autotel-cli 0.8.7 → 0.8.9

package/dist/index.js

@@ -1,10 +1,11 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import { Command } from "commander";
+import { Command as Command11 } 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"
+// 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"
+    }
+  ];
+  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 };
+}
+function findPreset(slug) {
+  for (const type of ["backend", "subscriber", "plugin", "platform"]) {
+    const p = getPreset(type, slug);
+    if (p !== void 0) return p;
+  }
+  return null;
+}
+
+// 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 } : {}
+      }
+    };
+  }
+};
+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 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.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[]" }
+    });
+  }
+  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;
+}
+
+// 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));
+}
+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: "Where do you want to send telemetry?",
-    choices,
-    default: "local"
-  });
+  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 promptLogging() {
-  return await select({
-    message: "Which logging framework do you use?",
+async function confirmOrEditPlan(plan) {
+  console.log(renderPlanPreview(plan));
+  console.log("");
+  const choice = await select({
+    message: "Proceed?",
     choices: [
-      { value: null, name: "None / Not sure" },
-      { value: "pino", name: "Pino" },
-      { value: "winston", name: "Winston" }
+      { 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: null
+    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 };
 }
-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/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;
   }
-  return await checkbox({
-    message: "Which databases/ORMs do you use? (space to select, enter to continue)",
-    choices
-  });
+  if (typeof value === "string" && SECRET_VALUE_PATTERN.test(value)) {
+    return REDACTED;
+  }
+  return value;
 }
-async function promptSubscribers(subscribers2) {
-  const choices = [...subscribers2.entries()].map(([slug, preset]) => ({
-    value: slug,
-    name: `${preset.name} - ${preset.description}`
-  }));
-  if (choices.length === 0) {
-    return [];
+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;
   }
-  return await checkbox({
-    message: "Which event destinations? (space to select, enter to continue)",
-    choices
-  });
 }
-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"
-  });
-}
-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" }
-  ];
-  return await select({
-    message: "How do you start your app?",
-    choices,
-    default: "node-esm"
-  });
+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");
+  }
 }
-async function promptExistingConfigAction() {
-  return await select({
-    message: "Existing instrumentation detected. What would you like to do?",
-    choices: [
-      { value: "update", name: "Update existing file (recommended)" },
-      { value: "new", name: "Create new file (src/autotel-config.mts)" },
-      { value: "abort", name: "Abort" }
-    ],
-    default: "update"
+
+// 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.json) {
+    configureJsonOutput({
+      outputFile: options.outputFile,
+      noSecrets: options.noSecrets
+    });
   }
-  if (options.quiet) {
-    process.env["AUTOTEL_QUIET"] = "true";
-  }
-  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 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 }
+      });
+    }
+    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));
+    }
+  } else {
+    atomicWrite(instrumentationPath, newContent, {
+      root: project.packageRoot
+    });
+    result.wroteFiles.push(path9.relative(project.cwd, instrumentationPath));
+  }
   const envVars = [];
-  for (const preset of selectedPresets) {
-    envVars.push(...preset.env.required, ...preset.env.optional);
+  for (const p of presets) {
+    envVars.push(...p.env.required, ...p.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}`);
-    }
-    if (devPkgs2.length > 0) {
-      const cmd = getInstallCommand(project.packageManager, devPkgs2, { dev: true });
-      info(`Would run: ${cmd}`);
-    }
-    process.exit(0);
-  }
-  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...");
+  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 fs9 = await import("fs");
+        fs9.writeFileSync(filePath, result.modified, "utf8");
       }
     }
     const showSummary = printFiles || dryRun || result.changed;
@@ -3368,25 +4098,1718 @@ 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
+  }
+];
+var INVESTIGATE_FLAGS = [
+  { name: "--backend", takesValue: true, description: "Backend kind (env: AUTOTEL_BACKEND)" },
+  { name: "--jaeger-base-url", takesValue: true, description: "Jaeger base URL" },
+  { name: "--tempo-base-url", takesValue: true, description: "Tempo base URL" },
+  { name: "--prometheus-base-url", takesValue: true, description: "Prometheus base URL" },
+  { name: "--loki-base-url", takesValue: true, description: "Loki base URL" },
+  { name: "--collector-port", takesValue: true, description: "OTLP receiver port" },
+  { name: "--fixture-path", takesValue: true, description: "Fixture JSON path" },
+  { name: "--output-file", takesValue: true, description: "Persist JSON output to this path" },
+  { name: "--no-secrets-in-output", description: "Redact secret-shaped values" }
+];
+var STATIC_FLAGS = [
+  { name: "--output-file", takesValue: true, description: "Persist JSON output to this path" },
+  { name: "--no-secrets-in-output", description: "Redact secret-shaped values" }
+];
+function investigateCmd(name, description, extras = {}) {
+  return {
+    name,
+    description,
+    ...extras.args ? { args: extras.args } : {},
+    flags: [...extras.static ? STATIC_FLAGS : INVESTIGATE_FLAGS, ...extras.flags ?? []],
+    mutating: false,
+    network: extras.network ?? !extras.static,
+    writesFiles: false,
+    supportsDryRun: false,
+    requiresPackageJson: false,
+    mayReadEnv: false,
+    supportsJson: true
+  };
+}
+var traceIdArg = [
+  { name: "traceId", required: true, description: "Trace ID" }
+];
+var serviceNameArg = [
+  { name: "serviceName", required: true, description: "Service name" }
+];
+var INVESTIGATE_COMMANDS = [
+  investigateCmd("health", "Backend health + signal coverage"),
+  investigateCmd("capabilities", "Which signals the active backend serves"),
+  investigateCmd("discover", "Discover services and field shapes (parent)"),
+  investigateCmd("discover services", "Services with cross-signal metadata"),
+  investigateCmd("discover trace-fields", "Trace/span field names from sampled traces", {
+    flags: [{ name: "--search", takesValue: true, description: "Substring filter" }]
+  }),
+  investigateCmd("discover log-fields", "Log field names from sampled logs", {
+    flags: [{ name: "--search", takesValue: true, description: "Substring filter" }]
+  }),
+  investigateCmd("query", "Query traces/spans/metrics/logs (parent)"),
+  investigateCmd("query traces", "Search traces by service/op/status/tags/time/error"),
+  investigateCmd("query spans", "Search individual spans (extra duration filters)"),
+  investigateCmd("query metrics", "List metric series"),
+  investigateCmd("query logs", "Search logs"),
+  investigateCmd("trace", "Trace lookup commands (parent)"),
+  investigateCmd("trace get", "Get a trace by ID", { args: traceIdArg }),
+  investigateCmd("trace summary", "Compact incident-friendly trace summary", { args: traceIdArg }),
+  investigateCmd("topology", "Service topology commands (parent)"),
+  investigateCmd("topology services", "List known services"),
+  investigateCmd("topology operations", "List operations for a service", { args: serviceNameArg }),
+  investigateCmd("topology map", "Service dependency map with node/edge health"),
+  investigateCmd("diagnose", "Anomaly / root-cause / errors / SLO diagnosis (parent)"),
+  investigateCmd("diagnose anomalies", "Latency / error-rate outliers"),
+  investigateCmd("diagnose root-cause", "Bottleneck span in a trace", { args: traceIdArg }),
+  investigateCmd("diagnose errors", "Error spans grouped by service/operation"),
+  investigateCmd("diagnose slos", "SLO violations for a service"),
+  investigateCmd("correlate", "Cross-signal correlation (parent)"),
+  investigateCmd("correlate trace", "Trace + metrics + logs for a trace ID", { args: traceIdArg }),
+  investigateCmd("correlate explain-slowdown", "Anomalies + root cause + correlated signals"),
+  investigateCmd("llm", "LLM analytics (parent)"),
+  investigateCmd("llm usage", "Token usage + USD by model and service"),
+  investigateCmd("llm models", "Discover LLM models in use"),
+  investigateCmd("llm model-stats", "Per-model latency/token/error stats"),
+  investigateCmd("llm expensive", "Top token-spend traces"),
+  investigateCmd("llm slow", "Slowest LLM traces"),
+  investigateCmd("llm tools", "Tool/function spans grouped by tool name"),
+  investigateCmd("semconv", "Semantic conventions lookup (parent)", { static: true }),
+  investigateCmd("semconv list", "List semconv namespaces", { static: true, network: true }),
+  investigateCmd("semconv get", "Groups for one namespace", {
+    static: true,
+    network: true,
+    args: [{ name: "namespace", required: true, description: "Namespace (e.g. http)" }]
+  }),
+  investigateCmd("semconv refresh", "Clear semconv cache", { static: true }),
+  investigateCmd("score", "Score a span for instrumentation quality (JSON on stdin)", {
+    static: true,
+    flags: [{ name: "--span-file", takesValue: true, description: "Read span JSON from file" }]
+  }),
+  investigateCmd("score explain", "Explain the instrumentation scoring rubric", { static: true }),
+  investigateCmd("collector", "OpenTelemetry Collector config + schema commands (parent)", {
+    static: true
+  }),
+  investigateCmd("collector validate", "Validate OTLP receiver config", {
+    static: true,
+    flags: [{ name: "--config-file", takesValue: true, description: "Read JSON config from file" }]
+  }),
+  investigateCmd("collector suggest", "Minimal OTLP receiver config", { static: true }),
+  investigateCmd("collector explain", "Receiver config shape + defaults", { static: true }),
+  investigateCmd("collector versions", "Supported collector schema versions", { static: true, network: true }),
+  investigateCmd("collector components", "Components for a version", {
+    static: true,
+    network: true,
+    flags: [
+      { name: "--version", takesValue: true, description: "Collector version" },
+      { name: "--kind", takesValue: true, description: "Component kind filter" }
+    ]
+  }),
+  investigateCmd("collector schema", "JSON schema for a component", {
+    static: true,
+    network: true,
+    flags: [
+      { name: "--kind", takesValue: true, description: "Component kind" },
+      { name: "--name", takesValue: true, description: "Component name" },
+      { name: "--version", takesValue: true, description: "Collector version" }
+    ]
+  }),
+  investigateCmd("collector readme", "README for a component", {
+    static: true,
+    network: true,
+    flags: [
+      { name: "--kind", takesValue: true, description: "Component kind" },
+      { name: "--name", takesValue: true, description: "Component name" },
+      { name: "--version", takesValue: true, description: "Collector version" }
+    ]
+  }),
+  investigateCmd("collector validate-component", "Validate component config against upstream schema", {
+    static: true,
+    network: true,
+    flags: [
+      { name: "--kind", takesValue: true, description: "Component kind" },
+      { name: "--name", takesValue: true, description: "Component name" },
+      { name: "--version", takesValue: true, description: "Collector version" },
+      { name: "--config-file", takesValue: true, description: "Read JSON config from file" }
+    ]
+  }),
+  investigateCmd("collector refresh", "Refresh in-memory collector metadata cache", { static: true, network: true })
+];
+COMMANDS.push(...INVESTIGATE_COMMANDS);
+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/commands/investigate/health.ts
+import { Command } from "commander";
+
+// src/commands/investigate/runtime.ts
+function applyFlagsToEnv(flags) {
+  if (flags.backend !== void 0) process.env.AUTOTEL_BACKEND = flags.backend;
+  if (flags.jaegerBaseUrl !== void 0)
+    process.env.JAEGER_BASE_URL = flags.jaegerBaseUrl;
+  if (flags.tempoBaseUrl !== void 0)
+    process.env.TEMPO_BASE_URL = flags.tempoBaseUrl;
+  if (flags.prometheusBaseUrl !== void 0)
+    process.env.PROMETHEUS_BASE_URL = flags.prometheusBaseUrl;
+  if (flags.lokiBaseUrl !== void 0)
+    process.env.LOKI_BASE_URL = flags.lokiBaseUrl;
+  if (flags.collectorPort !== void 0)
+    process.env.AUTOTEL_COLLECTOR_PORT = String(flags.collectorPort);
+  if (flags.fixturePath !== void 0)
+    process.env.AUTOTEL_FIXTURE_PATH = flags.fixturePath;
+}
+async function openBackend(flags) {
+  applyFlagsToEnv(flags);
+  const { loadConfig, createBackend } = await import("autotel-mcp");
+  const config = loadConfig();
+  return createBackend(config);
+}
+async function runStatic(command, flags, fn) {
+  configureJsonOutput({
+    outputFile: flags.outputFile,
+    noSecrets: flags.noSecrets
+  });
+  try {
+    const data = await fn();
+    printJson({ ok: true, command, data });
+  } catch (error2) {
+    throw toInvestigateError(command, error2);
+  }
+}
+async function runInvestigate(command, flags, fn) {
+  configureJsonOutput({
+    outputFile: flags.outputFile,
+    noSecrets: flags.noSecrets
+  });
+  let handle = null;
+  try {
+    handle = await openBackend(flags);
+    await handle.start();
+    const data = await fn(handle.backend);
+    printJson({ ok: true, command, data });
+  } catch (error2) {
+    throw toInvestigateError(command, error2);
+  } finally {
+    if (handle) {
+      try {
+        await handle.stop();
+      } catch {
+      }
+    }
+  }
+}
+function toInvestigateError(command, error2) {
+  if (error2 instanceof AutotelError) return error2;
+  if (error2 !== null && typeof error2 === "object" && "issues" in error2 && Array.isArray(error2.issues)) {
+    const issues = error2.issues;
+    const first = issues[0];
+    const path15 = first?.path?.join(".") ?? "";
+    return new AutotelError({
+      type: "validation",
+      code: "AUTOTEL_E_INVALID_INPUT",
+      message: `autotel ${command}: invalid input${path15 ? ` for "${path15}"` : ""} \u2014 ${first?.message ?? "validation failed"}`,
+      retryable: false,
+      expected: { issues }
+    });
+  }
+  const message = error2 instanceof Error ? error2.message : String(error2);
+  return new AutotelError({
+    type: "runtime",
+    code: "AUTOTEL_E_UNKNOWN",
+    message: `autotel ${command} failed: ${message}`,
+    retryable: false
+  });
+}
+
+// src/commands/investigate/cli-helpers.ts
+var intArg = (v) => Number.parseInt(v, 10);
+var floatArg = (v) => Number.parseFloat(v);
+function addBackendFlags(cmd) {
+  return cmd.option(
+    "--backend <kind>",
+    "Backend: collector|jaeger|tempo|prometheus|loki|stack|auto|fixture (env: AUTOTEL_BACKEND)"
+  ).option("--jaeger-base-url <url>", "Jaeger base URL (env: JAEGER_BASE_URL)").option("--tempo-base-url <url>", "Tempo base URL (env: TEMPO_BASE_URL)").option(
+    "--prometheus-base-url <url>",
+    "Prometheus base URL (env: PROMETHEUS_BASE_URL)"
+  ).option("--loki-base-url <url>", "Loki base URL (env: LOKI_BASE_URL)").option(
+    "--collector-port <n>",
+    "OTLP receiver port for the collector backend",
+    intArg
+  ).option("--fixture-path <path>", "Fixture JSON for the fixture backend").option("--output-file <path>", "Persist JSON output to this file").option("--no-secrets-in-output", "Redact secret-shaped values");
+}
+function addStaticFlags(cmd) {
+  return cmd.option("--output-file <path>", "Persist JSON output to this file").option("--no-secrets-in-output", "Redact secret-shaped values");
+}
+function backendFlagsFromOpts(opts) {
+  return {
+    backend: opts.backend,
+    jaegerBaseUrl: opts.jaegerBaseUrl,
+    tempoBaseUrl: opts.tempoBaseUrl,
+    prometheusBaseUrl: opts.prometheusBaseUrl,
+    lokiBaseUrl: opts.lokiBaseUrl,
+    collectorPort: opts.collectorPort,
+    fixturePath: opts.fixturePath,
+    outputFile: opts.outputFile,
+    noSecrets: opts.secretsInOutput === false
+  };
+}
+function staticFlagsFromOpts(opts) {
+  return {
+    outputFile: opts.outputFile,
+    noSecrets: opts.secretsInOutput === false
+  };
+}
+function addTimeWindowFlags(cmd) {
+  return cmd.option("--service-name <name>", "Filter by service name").option("--operation-name <name>", "Filter by operation name").option("--lookback-minutes <n>", "Lookback window in minutes", intArg).option("--from <iso>", "Start time (ISO 8601)").option("--to <iso>", "End time (ISO 8601)").option("--limit <n>", "Max results", intArg);
+}
+
+// src/commands/investigate/health.ts
+async function runHealth(flags) {
+  await runInvestigate("health", flags, async (backend) => {
+    const [health, capabilities] = await Promise.all([
+      backend.healthCheck(),
+      Promise.resolve(backend.capabilities())
+    ]);
+    return { ...health, signals: capabilities };
+  });
+}
+async function runCapabilities(flags) {
+  await runInvestigate(
+    "capabilities",
+    flags,
+    async (backend) => backend.capabilities()
+  );
+}
+function registerHealthCommands(program) {
+  const healthCmd = new Command("health").description("Backend health check + signal coverage (JSON)").action(async function() {
+    await runHealth(backendFlagsFromOpts(this.opts()));
+  });
+  addBackendFlags(healthCmd);
+  program.addCommand(healthCmd);
+  const capabilitiesCmd = new Command("capabilities").description("Which telemetry signals the active backend can serve (JSON)").action(async function() {
+    await runCapabilities(backendFlagsFromOpts(this.opts()));
+  });
+  addBackendFlags(capabilitiesCmd);
+  program.addCommand(capabilitiesCmd);
+}
+
+// src/commands/investigate/discovery.ts
+import { Command as Command2 } from "commander";
+import {
+  discoverServices,
+  discoverTraceFields,
+  discoverLogFields
+} from "autotel-mcp";
+async function runDiscoverServices(flags) {
+  await runInvestigate("discover services", flags, async (backend) => {
+    const limitServices = flags.limitServices ?? 100;
+    const traceSample = flags.traceSample ?? 200;
+    const logSample = flags.logSample ?? 200;
+    const metricSample = flags.metricSample ?? 200;
+    const caps = backend.capabilities();
+    const servicesResult = await backend.listServices({ limit: limitServices });
+    const services = servicesResult.services.slice(0, limitServices);
+    const [traces, logs, metrics] = await Promise.all([
+      caps.traces === "available" ? backend.searchTraces({ limit: traceSample }).then((r) => r.items) : Promise.resolve([]),
+      caps.logs === "available" ? backend.searchLogs({ limit: logSample }).then((r) => r.items) : Promise.resolve([]),
+      caps.metrics === "available" ? backend.listMetrics({ limit: metricSample }).then((r) => r.items) : Promise.resolve([])
+    ]);
+    const discovered = discoverServices({ services, traces, logs, metrics });
+    return { count: discovered.length, services: discovered };
+  });
+}
+async function runDiscoverTraceFields(flags) {
+  await runInvestigate("discover trace-fields", flags, async (backend) => {
+    return discoverFields(backend, flags, "traces");
+  });
+}
+async function runDiscoverLogFields(flags) {
+  await runInvestigate("discover log-fields", flags, async (backend) => {
+    return discoverFields(backend, flags, "logs");
+  });
+}
+async function discoverFields(backend, flags, signal) {
+  const sampleSize = flags.sampleSize ?? 200;
+  if (signal === "traces") {
+    const traces = await backend.searchTraces({ limit: sampleSize }).then((r) => r.items);
+    return {
+      search: flags.search ?? null,
+      sampleSize: traces.length,
+      ...discoverTraceFields(traces, flags.search)
+    };
+  }
+  const logs = await backend.searchLogs({ limit: sampleSize }).then((r) => r.items);
+  return {
+    search: flags.search ?? null,
+    sampleSize: logs.length,
+    ...discoverLogFields(logs, flags.search)
+  };
+}
+function registerDiscoveryCommands(program) {
+  const discoverCmd = new Command2("discover").description(
+    "Discover services and field shapes from the active backend (JSON)"
+  );
+  const servicesCmd = new Command2("services").description("Discover services with cross-signal metadata").option("--limit-services <n>", "Max services", intArg).option("--trace-sample <n>", "Trace sample size", intArg).option("--log-sample <n>", "Log sample size", intArg).option("--metric-sample <n>", "Metric sample size", intArg).action(async function() {
+    const o = this.optsWithGlobals();
+    await runDiscoverServices({
+      ...backendFlagsFromOpts(o),
+      limitServices: o.limitServices,
+      traceSample: o.traceSample,
+      logSample: o.logSample,
+      metricSample: o.metricSample
+    });
+  });
+  const traceFieldsCmd = new Command2("trace-fields").description("Discover trace/span field names from sampled traces").option("--search <text>", "Filter field names by substring").option("--sample-size <n>", "Trace sample size", intArg).action(async function() {
+    const o = this.optsWithGlobals();
+    await runDiscoverTraceFields({
+      ...backendFlagsFromOpts(o),
+      search: o.search,
+      sampleSize: o.sampleSize
+    });
+  });
+  const logFieldsCmd = new Command2("log-fields").description("Discover log field names from sampled logs").option("--search <text>", "Filter field names by substring").option("--sample-size <n>", "Log sample size", intArg).action(async function() {
+    const o = this.optsWithGlobals();
+    await runDiscoverLogFields({
+      ...backendFlagsFromOpts(o),
+      search: o.search,
+      sampleSize: o.sampleSize
+    });
+  });
+  addBackendFlags(discoverCmd);
+  discoverCmd.addCommand(servicesCmd);
+  discoverCmd.addCommand(traceFieldsCmd);
+  discoverCmd.addCommand(logFieldsCmd);
+  program.addCommand(discoverCmd);
+}
+
+// src/commands/investigate/investigation.ts
+import { Command as Command3 } from "commander";
+import {
+  toTraceSearchQuery,
+  toSpanSearchQuery
+} from "autotel-mcp";
+
+// src/commands/investigate/signals.ts
+import {
+  toMetricSearchQuery,
+  toLogSearchQuery
+} from "autotel-mcp";
+async function runQueryMetrics(flags) {
+  await runInvestigate(
+    "query metrics",
+    flags,
+    async (backend) => backend.listMetrics(toMetricSearchQuery(flags))
+  );
+}
+async function runQueryLogs(flags) {
+  await runInvestigate(
+    "query logs",
+    flags,
+    async (backend) => backend.searchLogs(toLogSearchQuery(flags))
+  );
+}
+
+// src/commands/investigate/investigation.ts
+async function runQueryTraces(flags) {
+  await runInvestigate(
+    "query traces",
+    flags,
+    async (backend) => backend.searchTraces(toTraceSearchQuery(flags))
+  );
+}
+async function runQuerySpans(flags) {
+  await runInvestigate(
+    "query spans",
+    flags,
+    async (backend) => backend.searchSpans(toSpanSearchQuery(flags))
+  );
+}
+async function runTraceGet(flags) {
+  await runInvestigate(
+    "trace get",
+    flags,
+    async (backend) => backend.getTrace(flags.traceId)
+  );
+}
+async function runTraceSummary(flags) {
+  await runInvestigate(
+    "trace summary",
+    flags,
+    async (backend) => backend.summarizeTrace(flags.traceId)
+  );
+}
+function registerQueryCommands(program) {
+  const queryCmd = new Command3("query").description(
+    "Query traces, spans, metrics, or logs (JSON)"
+  );
+  const tracesCmd = addTimeWindowFlags(new Command3("traces")).description("Search traces by service, op, status, tags, time, error").option("--error-only", "Only traces with errors").option("--status-code <code>", "OK | ERROR | UNSET").option("--min-duration-ms <n>", "Minimum duration", intArg).option("--max-duration-ms <n>", "Maximum duration", intArg).option("--gen-ai-system <name>", "gen_ai.system").option("--gen-ai-request-model <name>", "gen_ai.request.model").option("--gen-ai-response-model <name>", "gen_ai.response.model").action(async function() {
+    const o = this.optsWithGlobals();
+    await runQueryTraces({
+      ...backendFlagsFromOpts(o),
+      serviceName: o.serviceName,
+      operationName: o.operationName,
+      lookbackMinutes: o.lookbackMinutes,
+      from: o.from,
+      to: o.to,
+      limit: o.limit,
+      errorOnly: o.errorOnly,
+      statusCode: o.statusCode,
+      minDurationMs: o.minDurationMs,
+      maxDurationMs: o.maxDurationMs,
+      genAiSystem: o.genAiSystem,
+      genAiRequestModel: o.genAiRequestModel,
+      genAiResponseModel: o.genAiResponseModel
+    });
+  });
+  const spansCmd = addTimeWindowFlags(new Command3("spans")).description("Search individual spans by service/op/status/tags/duration").option("--error-only", "Only spans with errors").option("--status-code <code>", "OK | ERROR | UNSET").option("--min-duration-ms <n>", "Minimum span duration", intArg).option("--max-duration-ms <n>", "Maximum span duration", intArg).action(async function() {
+    const o = this.optsWithGlobals();
+    await runQuerySpans({
+      ...backendFlagsFromOpts(o),
+      serviceName: o.serviceName,
+      operationName: o.operationName,
+      lookbackMinutes: o.lookbackMinutes,
+      from: o.from,
+      to: o.to,
+      limit: o.limit,
+      errorOnly: o.errorOnly,
+      statusCode: o.statusCode,
+      minDurationMs: o.minDurationMs,
+      maxDurationMs: o.maxDurationMs
+    });
+  });
+  const metricsCmd = addTimeWindowFlags(new Command3("metrics")).description("List metric series").option("--metric-name <name>", "Filter by metric name").action(async function() {
+    const o = this.optsWithGlobals();
+    await runQueryMetrics({
+      ...backendFlagsFromOpts(o),
+      metricName: o.metricName,
+      serviceName: o.serviceName,
+      lookbackMinutes: o.lookbackMinutes,
+      from: o.from,
+      to: o.to,
+      limit: o.limit
+    });
+  });
+  const logsCmd = addTimeWindowFlags(new Command3("logs")).description("Search logs").option("--trace-id <id>", "Filter by trace id").option("--span-id <id>", "Filter by span id").option("--severity-text <text>", "Severity text").option("--text <text>", "Free-text search").action(async function() {
+    const o = this.optsWithGlobals();
+    await runQueryLogs({
+      ...backendFlagsFromOpts(o),
+      serviceName: o.serviceName,
+      traceId: o.traceId,
+      spanId: o.spanId,
+      severityText: o.severityText,
+      text: o.text,
+      lookbackMinutes: o.lookbackMinutes,
+      from: o.from,
+      to: o.to,
+      limit: o.limit
+    });
+  });
+  addBackendFlags(queryCmd);
+  queryCmd.addCommand(tracesCmd);
+  queryCmd.addCommand(spansCmd);
+  queryCmd.addCommand(metricsCmd);
+  queryCmd.addCommand(logsCmd);
+  program.addCommand(queryCmd);
+}
+function registerTraceCommands(program) {
+  const traceLookupCmd = new Command3("trace").description(
+    "Trace lookup commands (JSON)"
+  );
+  const getCmd = new Command3("get").description("Get a trace by ID").argument("<traceId>", "Trace ID").action(async function(traceId) {
+    await runTraceGet({
+      ...backendFlagsFromOpts(this.optsWithGlobals()),
+      traceId
+    });
+  });
+  const summaryCmd = new Command3("summary").description("Compact incident-friendly trace summary").argument("<traceId>", "Trace ID").action(async function(traceId) {
+    await runTraceSummary({
+      ...backendFlagsFromOpts(this.optsWithGlobals()),
+      traceId
+    });
+  });
+  addBackendFlags(traceLookupCmd);
+  traceLookupCmd.addCommand(getCmd);
+  traceLookupCmd.addCommand(summaryCmd);
+  program.addCommand(traceLookupCmd);
+}
+
+// src/commands/investigate/topology.ts
+import { Command as Command4 } from "commander";
+async function runListServices(flags) {
+  await runInvestigate(
+    "topology services",
+    flags,
+    async (backend) => backend.listServices()
+  );
+}
+async function runListOperations(flags) {
+  await runInvestigate(
+    "topology operations",
+    flags,
+    async (backend) => backend.listOperations(flags.serviceName)
+  );
+}
+async function runServiceMap(flags) {
+  await runInvestigate(
+    "topology map",
+    flags,
+    async (backend) => backend.serviceMap(flags.lookbackMinutes ?? 60, flags.limit ?? 20)
+  );
+}
+function registerTopologyCommands(program) {
+  const topologyCmd = new Command4("topology").description(
+    "Service topology commands (JSON)"
+  );
+  const servicesCmd = new Command4("services").description("List known services").action(async function() {
+    await runListServices(backendFlagsFromOpts(this.optsWithGlobals()));
+  });
+  const operationsCmd = new Command4("operations").description("List operations for a service").argument("<serviceName>", "Service name").action(async function(serviceName) {
+    await runListOperations({
+      ...backendFlagsFromOpts(this.optsWithGlobals()),
+      serviceName
+    });
+  });
+  const mapCmd = new Command4("map").description("Build a service dependency map").option("--lookback-minutes <n>", "Lookback in minutes", intArg).option("--limit <n>", "Max services", intArg).action(async function() {
+    const o = this.optsWithGlobals();
+    await runServiceMap({
+      ...backendFlagsFromOpts(o),
+      lookbackMinutes: o.lookbackMinutes,
+      limit: o.limit
+    });
+  });
+  addBackendFlags(topologyCmd);
+  topologyCmd.addCommand(servicesCmd);
+  topologyCmd.addCommand(operationsCmd);
+  topologyCmd.addCommand(mapCmd);
+  program.addCommand(topologyCmd);
+}
+
+// src/commands/investigate/diagnosis.ts
+import { Command as Command5 } from "commander";
+import {
+  detectAnomalies,
+  findRootCause,
+  pickErrorMessage
+} from "autotel-mcp";
+async function runDiagnoseAnomalies(flags) {
+  await runInvestigate("diagnose anomalies", flags, async (backend) => {
+    const lookback = flags.lookbackMinutes ?? 60;
+    const nowMs = Date.now();
+    const result = await backend.searchTraces({
+      service: flags.service,
+      startTimeUnixMs: nowMs - lookback * 60 * 1e3,
+      endTimeUnixMs: nowMs,
+      limit: 100
+    });
+    return detectAnomalies(result.items, {
+      service: flags.service,
+      operation: flags.operation
+    });
+  });
+}
+async function runDiagnoseRootCause(flags) {
+  await runInvestigate("diagnose root-cause", flags, async (backend) => {
+    const trace = await backend.getTrace(flags.traceId);
+    if (!trace) return { error: `Trace not found: ${flags.traceId}` };
+    return findRootCause(trace);
+  });
+}
+async function runDiagnoseErrors(flags) {
+  await runInvestigate("diagnose errors", flags, async (backend) => {
+    const lookback = flags.lookbackMinutes ?? 60;
+    const limit = flags.limit ?? 20;
+    const nowMs = Date.now();
+    const result = await backend.searchTraces({
+      service: flags.service,
+      hasError: true,
+      startTimeUnixMs: nowMs - lookback * 60 * 1e3,
+      endTimeUnixMs: nowMs,
+      limit
+    });
+    const groups = /* @__PURE__ */ new Map();
+    for (const trace of result.items) {
+      for (const span of trace.spans) {
+        if (!span.hasError) continue;
+        if (flags.service && span.serviceName !== flags.service) continue;
+        const key = `${span.serviceName}::${span.operationName}`;
+        if (!groups.has(key)) {
+          groups.set(key, {
+            service: span.serviceName,
+            operation: span.operationName,
+            count: 0,
+            errorMessages: [],
+            traceIds: []
+          });
+        }
+        const group = groups.get(key);
+        group.count++;
+        const msg = pickErrorMessage(span.tags);
+        if (msg && !group.errorMessages.includes(msg)) {
+          group.errorMessages.push(msg);
+        }
+        if (!group.traceIds.includes(trace.traceId)) {
+          group.traceIds.push(trace.traceId);
+        }
+      }
+    }
+    return {
+      totalTraces: result.totalCount,
+      groups: [...groups.values()].toSorted((a, b) => b.count - a.count)
+    };
+  });
+}
+async function runDiagnoseSlos(flags) {
+  await runInvestigate("diagnose slos", flags, async (backend) => {
+    const lookback = flags.lookbackMinutes ?? 60;
+    const nowMs = Date.now();
+    const result = await backend.searchTraces({
+      service: flags.service,
+      startTimeUnixMs: nowMs - lookback * 60 * 1e3,
+      endTimeUnixMs: nowMs,
+      limit: 100
+    });
+    const spans = result.items.flatMap(
+      (t) => t.spans.filter((s) => s.serviceName === flags.service)
+    );
+    const violations = [];
+    if (spans.length === 0) {
+      return {
+        service: flags.service,
+        totalSpans: 0,
+        violations,
+        message: "No spans found for the given service and time window."
+      };
+    }
+    const durations = spans.map((s) => s.durationMs).toSorted((a, b) => a - b);
+    const p99Index = Math.floor(durations.length * 0.99);
+    const actualP99 = durations[Math.min(p99Index, durations.length - 1)];
+    if (flags.p99LatencyMs !== void 0 && actualP99 > flags.p99LatencyMs) {
+      violations.push({
+        type: "p99_latency",
+        target: flags.p99LatencyMs,
+        actual: actualP99,
+        description: `p99 latency ${actualP99.toFixed(1)}ms exceeds target ${flags.p99LatencyMs}ms`
+      });
+    }
+    const errorCount = spans.filter((s) => s.hasError).length;
+    const actualErrorRate = errorCount / spans.length;
+    if (flags.maxErrorRate !== void 0 && actualErrorRate > flags.maxErrorRate) {
+      violations.push({
+        type: "error_rate",
+        target: flags.maxErrorRate,
+        actual: actualErrorRate,
+        description: `Error rate ${(actualErrorRate * 100).toFixed(2)}% exceeds target ${(flags.maxErrorRate * 100).toFixed(2)}%`
+      });
+    }
+    return {
+      service: flags.service,
+      totalSpans: spans.length,
+      p99LatencyMs: actualP99,
+      errorRate: actualErrorRate,
+      violations
+    };
+  });
+}
+function registerDiagnoseCommands(program) {
+  const diagnoseCmd = new Command5("diagnose").description(
+    "Anomaly / root-cause / errors / SLO diagnosis (JSON)"
+  );
+  const anomaliesCmd = new Command5("anomalies").description("Detect latency/error-rate outliers").option("--service <name>", "Service filter").option("--operation <name>", "Operation filter").option("--lookback-minutes <n>", "Lookback in minutes", intArg).action(async function() {
+    const o = this.optsWithGlobals();
+    await runDiagnoseAnomalies({
+      ...backendFlagsFromOpts(o),
+      service: o.service,
+      operation: o.operation,
+      lookbackMinutes: o.lookbackMinutes
+    });
+  });
+  const rootCauseCmd = new Command5("root-cause").description("Walk a trace tree to identify the bottleneck span").argument("<traceId>", "Trace ID").action(async function(traceId) {
+    await runDiagnoseRootCause({
+      ...backendFlagsFromOpts(this.optsWithGlobals()),
+      traceId
+    });
+  });
+  const errorsCmd = new Command5("errors").description("Aggregate error spans by service/operation").option("--service <name>", "Service filter").option("--lookback-minutes <n>", "Lookback in minutes", intArg).option("--limit <n>", "Max traces to scan", intArg).action(async function() {
+    const o = this.optsWithGlobals();
+    await runDiagnoseErrors({
+      ...backendFlagsFromOpts(o),
+      service: o.service,
+      lookbackMinutes: o.lookbackMinutes,
+      limit: o.limit
+    });
+  });
+  const slosCmd = new Command5("slos").description("Report SLO violations for a service").requiredOption("--service <name>", "Service to check").option("--p99-latency-ms <n>", "p99 latency target", floatArg).option("--max-error-rate <n>", "Error-rate target (0..1)", floatArg).option("--lookback-minutes <n>", "Lookback in minutes", intArg).action(async function() {
+    const o = this.optsWithGlobals();
+    await runDiagnoseSlos({
+      ...backendFlagsFromOpts(o),
+      service: o.service,
+      p99LatencyMs: o.p99LatencyMs,
+      maxErrorRate: o.maxErrorRate,
+      lookbackMinutes: o.lookbackMinutes
+    });
+  });
+  addBackendFlags(diagnoseCmd);
+  diagnoseCmd.addCommand(anomaliesCmd);
+  diagnoseCmd.addCommand(rootCauseCmd);
+  diagnoseCmd.addCommand(errorsCmd);
+  diagnoseCmd.addCommand(slosCmd);
+  program.addCommand(diagnoseCmd);
+}
+
+// src/commands/investigate/correlation.ts
+import { Command as Command6 } from "commander";
+import { detectAnomalies as detectAnomalies2, findRootCause as findRootCause2 } from "autotel-mcp";
+async function runCorrelate(flags) {
+  await runInvestigate(
+    "correlate trace",
+    flags,
+    async (backend) => backend.getCorrelatedSignals(flags.traceId)
+  );
+}
+async function runExplainSlowdown(flags) {
+  await runInvestigate("correlate explain-slowdown", flags, async (backend) => {
+    const lookback = flags.lookbackMinutes ?? 60;
+    const nowMs = Date.now();
+    const result = await backend.searchTraces({
+      service: flags.service,
+      startTimeUnixMs: nowMs - lookback * 60 * 1e3,
+      endTimeUnixMs: nowMs,
+      limit: 100
+    });
+    const anomalies = detectAnomalies2(result.items, { service: flags.service });
+    const findings = await Promise.all(
+      anomalies.map(async (anomaly) => {
+        const sampleTraceId = anomaly.affectedTraceIds[0];
+        if (!sampleTraceId) {
+          return { anomaly, rootCause: null, correlatedSignals: null };
+        }
+        const trace = await backend.getTrace(sampleTraceId);
+        const rootCause = trace ? findRootCause2(trace) : null;
+        const correlatedSignals = await backend.getCorrelatedSignals(sampleTraceId);
+        return { anomaly, rootCause, correlatedSignals };
+      })
+    );
+    return {
+      service: flags.service,
+      lookbackMinutes: lookback,
+      anomalyCount: anomalies.length,
+      findings
+    };
+  });
+}
+function registerCorrelateCommands(program) {
+  const correlateCmd = new Command6("correlate").description(
+    "Cross-signal correlation (JSON)"
+  );
+  const traceCmd = new Command6("trace").description("Trace + metrics + correlated logs for a trace ID").argument("<traceId>", "Trace ID").action(async function(traceId) {
+    await runCorrelate({
+      ...backendFlagsFromOpts(this.optsWithGlobals()),
+      traceId
+    });
+  });
+  const slowdownCmd = new Command6("explain-slowdown").description("Identify when/why a service degraded").requiredOption("--service <name>", "Service name").option("--lookback-minutes <n>", "Lookback in minutes", intArg).action(async function() {
+    const o = this.optsWithGlobals();
+    await runExplainSlowdown({
+      ...backendFlagsFromOpts(o),
+      service: o.service,
+      lookbackMinutes: o.lookbackMinutes
+    });
+  });
+  addBackendFlags(correlateCmd);
+  correlateCmd.addCommand(traceCmd);
+  correlateCmd.addCommand(slowdownCmd);
+  program.addCommand(correlateCmd);
+}
+
+// src/commands/investigate/llm.ts
+import {
+  collectUsage,
+  listModels,
+  getModelStats,
+  rankExpensiveTraces,
+  rankSlowTraces,
+  listToolUsage,
+  toTraceSearchQuery as toTraceSearchQuery2
+} from "autotel-mcp";
+import { Command as Command7 } from "commander";
+function parseDateToUnixMs(value) {
+  if (!value) return void 0;
+  const parsed = Date.parse(value);
+  return Number.isFinite(parsed) ? parsed : void 0;
+}
+async function collectTracesForAnalytics(backend, input2) {
+  const result = await backend.searchTraces(
+    toTraceSearchQuery2({
+      serviceName: input2.serviceName,
+      genAiSystem: input2.genAiSystem,
+      genAiRequestModel: input2.genAiRequestModel,
+      genAiResponseModel: input2.genAiResponseModel,
+      limit: input2.limit ?? 1e3
+    })
+  );
+  let filtered = result.items;
+  const startUnixMs = parseDateToUnixMs(input2.startTime);
+  const endUnixMs = parseDateToUnixMs(input2.endTime);
+  if (startUnixMs !== void 0) {
+    filtered = filtered.filter(
+      (trace) => trace.spans.some((span) => span.startTimeUnixMs >= startUnixMs)
+    );
+  }
+  if (endUnixMs !== void 0) {
+    filtered = filtered.filter(
+      (trace) => trace.spans.some((span) => span.startTimeUnixMs <= endUnixMs)
+    );
+  }
+  return filtered;
+}
+async function runLlmUsage(flags) {
+  await runInvestigate("llm usage", flags, async (backend) => {
+    const traces = await collectTracesForAnalytics(backend, flags);
+    const report = collectUsage(traces);
+    return {
+      period: {
+        startTime: flags.startTime ?? null,
+        endTime: flags.endTime ?? null
+      },
+      filters: {
+        serviceName: flags.serviceName ?? null,
+        genAiSystem: flags.genAiSystem ?? null,
+        genAiRequestModel: flags.genAiRequestModel ?? null,
+        genAiResponseModel: flags.genAiResponseModel ?? null
+      },
+      summary: {
+        totalRequests: report.totalRequests,
+        totalPromptTokens: report.totalPromptTokens,
+        totalCompletionTokens: report.totalCompletionTokens,
+        totalTokens: report.totalTokens,
+        totalCostUsd: report.totalCostUsd,
+        unpricedRequests: report.unpricedRequests
+      },
+      byModel: report.byModel,
+      byService: report.byService
+    };
+  });
+}
+async function runLlmModels(flags) {
+  await runInvestigate("llm models", flags, async (backend) => {
+    const traces = await collectTracesForAnalytics(backend, flags);
+    const models = listModels(traces).slice(0, flags.limit ?? 1e3);
+    return { count: models.length, models };
+  });
+}
+async function runLlmModelStats(flags) {
+  await runInvestigate("llm model-stats", flags, async (backend) => {
+    const traces = await collectTracesForAnalytics(backend, flags);
+    const stats = getModelStats(traces, flags.modelName);
+    if (!stats) {
+      return {
+        error: `No traces found for model '${flags.modelName}' in the specified time range`
+      };
+    }
+    return stats;
+  });
+}
+async function runLlmExpensive(flags) {
+  await runInvestigate("llm expensive", flags, async (backend) => {
+    const traces = await collectTracesForAnalytics(backend, flags);
+    let ranked = rankExpensiveTraces(traces);
+    if (flags.minTokens !== void 0) {
+      ranked = ranked.filter((t) => t.tokens.total >= flags.minTokens);
+    }
+    ranked = ranked.slice(0, flags.limit ?? 10);
+    return { count: ranked.length, traces: ranked };
+  });
+}
+async function runLlmSlow(flags) {
+  await runInvestigate("llm slow", flags, async (backend) => {
+    const traces = await collectTracesForAnalytics(backend, flags);
+    let ranked = rankSlowTraces(traces);
+    if (flags.minDurationMs !== void 0) {
+      ranked = ranked.filter((t) => t.durationMs >= flags.minDurationMs);
+    }
+    ranked = ranked.slice(0, flags.limit ?? 10);
+    return { count: ranked.length, traces: ranked };
+  });
+}
+async function runLlmTools(flags) {
+  await runInvestigate("llm tools", flags, async (backend) => {
+    const traces = await collectTracesForAnalytics(backend, flags);
+    const tools = listToolUsage(traces).slice(0, flags.limit ?? 1e3);
+    return {
+      count: tools.length,
+      totalCalls: tools.reduce((sum, t) => sum + t.usageCount, 0),
+      tools
+    };
+  });
+}
+function registerLlmCommands(program) {
+  const llmCmd = new Command7("llm").description(
+    "LLM analytics (cost, models, expensive/slow traces, tools)"
+  );
+  const commonOpts = (cmd) => cmd.option("--start-time <iso>", "Start of window (ISO 8601)").option("--end-time <iso>", "End of window (ISO 8601)").option("--service-name <name>", "Service filter").option("--gen-ai-system <name>", "gen_ai.system filter").option("--gen-ai-request-model <name>", "gen_ai.request.model filter").option("--gen-ai-response-model <name>", "gen_ai.response.model filter").option("--limit <n>", "Max results", intArg);
+  const usageCmd = commonOpts(new Command7("usage")).description("Aggregate token usage by model and service").action(async function() {
+    const o = this.optsWithGlobals();
+    await runLlmUsage({
+      ...backendFlagsFromOpts(o),
+      startTime: o.startTime,
+      endTime: o.endTime,
+      serviceName: o.serviceName,
+      genAiSystem: o.genAiSystem,
+      genAiRequestModel: o.genAiRequestModel,
+      genAiResponseModel: o.genAiResponseModel,
+      limit: o.limit
+    });
+  });
+  const modelsCmd = commonOpts(new Command7("models")).description("Discover LLM models in use").action(async function() {
+    const o = this.optsWithGlobals();
+    await runLlmModels({
+      ...backendFlagsFromOpts(o),
+      startTime: o.startTime,
+      endTime: o.endTime,
+      serviceName: o.serviceName,
+      genAiSystem: o.genAiSystem,
+      limit: o.limit
+    });
+  });
+  const modelStatsCmd = commonOpts(new Command7("model-stats")).description("Latency/token/error stats for one LLM model").requiredOption("--model-name <name>", "Model to inspect").action(async function() {
+    const o = this.optsWithGlobals();
+    await runLlmModelStats({
+      ...backendFlagsFromOpts(o),
+      modelName: o.modelName,
+      startTime: o.startTime,
+      endTime: o.endTime,
+      serviceName: o.serviceName
+    });
+  });
+  const expensiveCmd = commonOpts(new Command7("expensive")).description("Traces with highest total LLM token usage").option("--min-tokens <n>", "Minimum token threshold", intArg).action(async function() {
+    const o = this.optsWithGlobals();
+    await runLlmExpensive({
+      ...backendFlagsFromOpts(o),
+      startTime: o.startTime,
+      endTime: o.endTime,
+      serviceName: o.serviceName,
+      genAiRequestModel: o.genAiRequestModel,
+      genAiResponseModel: o.genAiResponseModel,
+      minTokens: o.minTokens,
+      limit: o.limit
+    });
+  });
+  const slowCmd = commonOpts(new Command7("slow")).description("Slowest traces that include LLM spans").option("--min-duration-ms <n>", "Minimum duration", intArg).action(async function() {
+    const o = this.optsWithGlobals();
+    await runLlmSlow({
+      ...backendFlagsFromOpts(o),
+      startTime: o.startTime,
+      endTime: o.endTime,
+      serviceName: o.serviceName,
+      genAiRequestModel: o.genAiRequestModel,
+      genAiResponseModel: o.genAiResponseModel,
+      minDurationMs: o.minDurationMs,
+      limit: o.limit
+    });
+  });
+  const toolsCmd = commonOpts(new Command7("tools")).description("Discover tool/function spans grouped by tool name").action(async function() {
+    const o = this.optsWithGlobals();
+    await runLlmTools({
+      ...backendFlagsFromOpts(o),
+      startTime: o.startTime,
+      endTime: o.endTime,
+      serviceName: o.serviceName,
+      genAiSystem: o.genAiSystem,
+      limit: o.limit
+    });
+  });
+  addBackendFlags(llmCmd);
+  llmCmd.addCommand(usageCmd);
+  llmCmd.addCommand(modelsCmd);
+  llmCmd.addCommand(modelStatsCmd);
+  llmCmd.addCommand(expensiveCmd);
+  llmCmd.addCommand(slowCmd);
+  llmCmd.addCommand(toolsCmd);
+  program.addCommand(llmCmd);
+}
+
+// src/commands/investigate/semconv.ts
+import {
+  clearSemanticConventionCache,
+  getSemanticConventionNamespace,
+  listSemanticConventionNamespaces
+} from "autotel-mcp";
+import { Command as Command8 } from "commander";
+async function runSemconvList(flags) {
+  await runStatic("semconv list", flags, async () => ({
+    namespaces: await listSemanticConventionNamespaces()
+  }));
+}
+async function runSemconvGet(flags) {
+  await runStatic(
+    "semconv get",
+    flags,
+    async () => getSemanticConventionNamespace(flags.namespace)
+  );
+}
+async function runSemconvRefresh(flags) {
+  await runStatic("semconv refresh", flags, async () => {
+    clearSemanticConventionCache();
+    return { cleared: true };
+  });
+}
+function registerSemconvCommands(program) {
+  const semconvCmd = new Command8("semconv").description(
+    "OpenTelemetry semantic conventions lookup (JSON)"
+  );
+  const listCmd = addStaticFlags(new Command8("list")).description("List semconv namespaces").action(async function() {
+    await runSemconvList(staticFlagsFromOpts(this.optsWithGlobals()));
+  });
+  const getCmd = addStaticFlags(new Command8("get")).description("Get groups for one namespace").argument("<namespace>", "Namespace (e.g. http, rpc, database)").action(async function(namespace) {
+    await runSemconvGet({
+      ...staticFlagsFromOpts(this.optsWithGlobals()),
+      namespace
+    });
+  });
+  const refreshCmd = addStaticFlags(new Command8("refresh")).description("Clear semconv cache").action(async function() {
+    await runSemconvRefresh(staticFlagsFromOpts(this.optsWithGlobals()));
+  });
+  semconvCmd.addCommand(listCmd);
+  semconvCmd.addCommand(getCmd);
+  semconvCmd.addCommand(refreshCmd);
+  program.addCommand(semconvCmd);
+}
+
+// src/commands/investigate/instrumentation.ts
+import {
+  scoreSpan,
+  suggestInstrumentationFixes,
+  buildInstrumentationGuide
+} from "autotel-mcp";
+import { Command as Command9 } from "commander";
+import * as fs7 from "fs";
+function readSpanFromStdinOrFile(spanFile) {
+  let raw;
+  if (spanFile) {
+    raw = fs7.readFileSync(spanFile, "utf8");
+  } else {
+    raw = fs7.readFileSync(0, "utf8");
+  }
+  const parsed = JSON.parse(raw);
+  if (typeof parsed.operationName !== "string" || typeof parsed.serviceName !== "string" || typeof parsed.tags !== "object" || typeof parsed.hasError !== "boolean") {
+    throw new AutotelError({
+      type: "validation",
+      code: "AUTOTEL_E_INVALID_INPUT",
+      message: "score expects JSON with operationName, serviceName, tags, hasError",
+      retryable: false,
+      expected: {
+        shape: {
+          operationName: "string",
+          serviceName: "string",
+          tags: "Record<string, string | number | boolean>",
+          hasError: "boolean"
+        }
+      }
+    });
+  }
+  return parsed;
+}
+async function runScoreSpan(flags) {
+  await runStatic("score", flags, async () => {
+    const span = readSpanFromStdinOrFile(flags.spanFile);
+    const result = scoreSpan(span);
+    const suggestions = suggestInstrumentationFixes(span);
+    return { ...result, suggestions };
+  });
+}
+async function runScoreExplain(flags) {
+  await runStatic("score explain", flags, async () => ({
+    guide: buildInstrumentationGuide()
+  }));
+}
+function registerScoreCommands(program) {
+  const scoreCmd = addStaticFlags(new Command9("score")).description("Score a span for instrumentation quality (JSON)").option("--span-file <path>", "Read span JSON from file (default: stdin)").action(async function() {
+    const o = this.optsWithGlobals();
+    await runScoreSpan({
+      ...staticFlagsFromOpts(o),
+      spanFile: o.spanFile
+    });
+  });
+  const explainCmd = addStaticFlags(new Command9("explain")).description("Explain the instrumentation scoring rubric").action(async function() {
+    await runScoreExplain(staticFlagsFromOpts(this.optsWithGlobals()));
+  });
+  scoreCmd.addCommand(explainCmd);
+  program.addCommand(scoreCmd);
+}
+
+// src/commands/investigate/collector.ts
+import {
+  validateOtlpReceiverConfig,
+  suggestCollectorConfig,
+  buildCollectorGuide,
+  listCollectorVersions,
+  listCollectorComponents,
+  getCollectorComponentSchema,
+  getCollectorComponentReadme,
+  validateCollectorComponentConfig,
+  refreshCollectorCatalog,
+  resolveCollectorVersion
+} from "autotel-mcp";
+import { Command as Command10 } from "commander";
+import * as fs8 from "fs";
+function readJsonFromStdinOrFile(file) {
+  const raw = file ? fs8.readFileSync(file, "utf8") : fs8.readFileSync(0, "utf8");
+  return JSON.parse(raw);
+}
+function assertVersion(version) {
+  if (version === void 0) return;
+  if (!/^\d+\.\d+\.\d+$/.test(version)) {
+    throw new AutotelError({
+      type: "validation",
+      code: "AUTOTEL_E_INVALID_INPUT",
+      message: `--version must be semver (got "${version}")`,
+      retryable: false
+    });
+  }
+}
+async function runCollectorValidate(flags) {
+  await runStatic("collector validate", flags, async () => {
+    const config = readJsonFromStdinOrFile(flags.configFile);
+    return validateOtlpReceiverConfig(config);
+  });
+}
+async function runCollectorSuggest(flags) {
+  await runStatic("collector suggest", flags, async () => ({
+    suggestion: suggestCollectorConfig()
+  }));
+}
+async function runCollectorExplain(flags) {
+  await runStatic("collector explain", flags, async () => ({
+    guide: buildCollectorGuide()
+  }));
+}
+async function runCollectorVersions(flags) {
+  await runStatic("collector versions", flags, async () => ({
+    versions: await listCollectorVersions()
+  }));
+}
+async function runCollectorComponents(flags) {
+  await runStatic("collector components", flags, async () => {
+    assertVersion(flags.version);
+    const resolvedVersion = await resolveCollectorVersion(flags.version);
+    const components = await listCollectorComponents(resolvedVersion);
+    if (flags.kind) {
+      return {
+        version: resolvedVersion,
+        kind: flags.kind,
+        components: components[flags.kind]
+      };
+    }
+    return { version: resolvedVersion, components };
+  });
+}
+async function runCollectorSchema(flags) {
+  await runStatic("collector schema", flags, async () => {
+    assertVersion(flags.version);
+    const resolvedVersion = await resolveCollectorVersion(flags.version);
+    const schema = await getCollectorComponentSchema(
+      flags.kind,
+      flags.name,
+      resolvedVersion
+    );
+    return { version: resolvedVersion, kind: flags.kind, name: flags.name, schema };
+  });
+}
+async function runCollectorReadme(flags) {
+  await runStatic("collector readme", flags, async () => {
+    assertVersion(flags.version);
+    const resolvedVersion = await resolveCollectorVersion(flags.version);
+    const readme = await getCollectorComponentReadme(
+      flags.kind,
+      flags.name,
+      resolvedVersion
+    );
+    return { version: resolvedVersion, kind: flags.kind, name: flags.name, readme };
+  });
+}
+async function runCollectorValidateComponent(flags) {
+  await runStatic("collector validate-component", flags, async () => {
+    assertVersion(flags.version);
+    const resolvedVersion = await resolveCollectorVersion(flags.version);
+    const config = readJsonFromStdinOrFile(flags.configFile);
+    const result = await validateCollectorComponentConfig({
+      kind: flags.kind,
+      name: flags.name,
+      version: resolvedVersion,
+      config
+    });
+    return { version: resolvedVersion, kind: flags.kind, name: flags.name, ...result };
+  });
+}
+async function runCollectorRefresh(flags) {
+  await runStatic(
+    "collector refresh",
+    flags,
+    async () => refreshCollectorCatalog()
+  );
+}
+function registerCollectorCommands(program) {
+  const collectorCmd = new Command10("collector").description(
+    "OpenTelemetry Collector config + schema commands (JSON)"
+  );
+  const validateCmd = addStaticFlags(new Command10("validate")).description("Validate an OTLP receiver config fragment").option("--config-file <path>", "Read JSON config (default: stdin)").action(async function() {
+    const o = this.optsWithGlobals();
+    await runCollectorValidate({
+      ...staticFlagsFromOpts(o),
+      configFile: o.configFile
+    });
+  });
+  const suggestCmd = addStaticFlags(new Command10("suggest")).description("Print a minimal OTLP receiver config").action(async function() {
+    await runCollectorSuggest(staticFlagsFromOpts(this.optsWithGlobals()));
+  });
+  const explainCmd = addStaticFlags(new Command10("explain")).description("Explain OTLP receiver config shape + defaults").action(async function() {
+    await runCollectorExplain(staticFlagsFromOpts(this.optsWithGlobals()));
+  });
+  const versionsCmd = addStaticFlags(new Command10("versions")).description("List supported collector schema versions").action(async function() {
+    await runCollectorVersions(staticFlagsFromOpts(this.optsWithGlobals()));
+  });
+  const componentsCmd = addStaticFlags(new Command10("components")).description("List components for a version (optionally filter by kind)").option("--version <semver>", "Collector version (e.g. 0.110.0)").option(
+    "--kind <kind>",
+    "receiver | processor | exporter | connector | extension"
+  ).action(async function() {
+    const o = this.optsWithGlobals();
+    await runCollectorComponents({
+      ...staticFlagsFromOpts(o),
+      version: o.version,
+      kind: o.kind
+    });
+  });
+  const schemaCmd = addStaticFlags(new Command10("schema")).description("Get JSON Schema for a collector component").requiredOption("--kind <kind>", "Component kind").requiredOption("--name <name>", "Component name").option("--version <semver>", "Collector version").action(async function() {
+    const o = this.optsWithGlobals();
+    await runCollectorSchema({
+      ...staticFlagsFromOpts(o),
+      kind: o.kind,
+      name: o.name,
+      version: o.version
+    });
+  });
+  const readmeCmd = addStaticFlags(new Command10("readme")).description("Get README for a collector component").requiredOption("--kind <kind>", "Component kind").requiredOption("--name <name>", "Component name").option("--version <semver>", "Collector version").action(async function() {
+    const o = this.optsWithGlobals();
+    await runCollectorReadme({
+      ...staticFlagsFromOpts(o),
+      kind: o.kind,
+      name: o.name,
+      version: o.version
+    });
+  });
+  const validateComponentCmd = addStaticFlags(
+    new Command10("validate-component")
+  ).description("Validate component config against upstream schema").requiredOption("--kind <kind>", "Component kind").requiredOption("--name <name>", "Component name").option("--version <semver>", "Collector version").option("--config-file <path>", "Read JSON config (default: stdin)").action(async function() {
+    const o = this.optsWithGlobals();
+    await runCollectorValidateComponent({
+      ...staticFlagsFromOpts(o),
+      kind: o.kind,
+      name: o.name,
+      version: o.version,
+      configFile: o.configFile
+    });
+  });
+  const refreshCmd = addStaticFlags(new Command10("refresh")).description("Refresh in-memory collector metadata cache").action(async function() {
+    await runCollectorRefresh(staticFlagsFromOpts(this.optsWithGlobals()));
+  });
+  collectorCmd.addCommand(validateCmd);
+  collectorCmd.addCommand(suggestCmd);
+  collectorCmd.addCommand(explainCmd);
+  collectorCmd.addCommand(versionsCmd);
+  collectorCmd.addCommand(componentsCmd);
+  collectorCmd.addCommand(schemaCmd);
+  collectorCmd.addCommand(readmeCmd);
+  collectorCmd.addCommand(validateComponentCmd);
+  collectorCmd.addCommand(refreshCmd);
+  program.addCommand(collectorCmd);
+}
+
 // src/cli.ts
 function createProgram() {
-  const program = new Command();
+  const program = new Command11();
   program.name("autotel").description("CLI for autotel - setup wizard, diagnostics, and incremental features").version("0.1.0");
   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 Command11("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;
@@ -3396,7 +5819,7 @@ function createProgram() {
   });
   addGlobalOptions(initCmd);
   program.addCommand(initCmd);
-  const doctorCmd = new Command("doctor").description("Run diagnostics on your autotel setup").option("--json", "Output machine-readable JSON").option("--fix", "Auto-fix resolvable issues").option("--list-checks", "List all available checks").option("--env-file <path>", "Specify env file to check").action(async (opts) => {
+  const doctorCmd = new Command11("doctor").description("Run diagnostics on your autotel setup").option("--json", "Output machine-readable JSON").option("--fix", "Auto-fix resolvable issues").option("--list-checks", "List all available checks").option("--env-file <path>", "Specify env file to check").action(async (opts) => {
     const options = {
       cwd: opts.cwd ?? process.cwd(),
       dryRun: false,
@@ -3414,7 +5837,7 @@ function createProgram() {
   });
   addGlobalOptions(doctorCmd);
   program.addCommand(doctorCmd);
-  const addCmd = new Command("add").description("Add a backend, subscriber, plugin, or platform").argument("[type]", "Preset type (backend, subscriber, plugin, platform)").argument("[name]", "Preset name (e.g., datadog, posthog, mongoose)").option("--list", "List available presets for the given type").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("--force", "Overwrite non-CLI-owned config (creates backup first)").option("--json", "Output machine-readable JSON (for --list)").option("--workspace-root", "Install at workspace root instead of package root").action(async (type, name, opts) => {
+  const addCmd = new Command11("add").description("Add a backend, subscriber, plugin, or platform").argument("[type]", "Preset type (backend, subscriber, plugin, platform)").argument("[name]", "Preset name (e.g., datadog, posthog, mongoose)").option("--list", "List available presets for the given type").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("--force", "Overwrite non-CLI-owned config (creates backup first)").option("--json", "Output machine-readable JSON (for --list)").option("--workspace-root", "Install at workspace root instead of package root").action(async (type, name, opts) => {
     const options = {
       cwd: opts.cwd ?? process.cwd(),
       dryRun: opts.dryRun ?? false,
@@ -3436,8 +5859,8 @@ function createProgram() {
   });
   addGlobalOptions(addCmd);
   program.addCommand(addCmd);
-  const codemodCmd = new Command("codemod").description("Codemod commands for adopting autotel");
-  const traceCmd = new Command("trace").description("Wrap functions in trace() with span name from function/variable/method name").argument("<path>", "File path or glob (e.g. src/index.ts, src/**/*.ts)").option("--dry-run", "Print changes without writing files").option("--name-pattern <pattern>", "Span name template: {name}, {file}, {path}").option("--skip <regex>...", "Skip functions whose name matches (repeatable)").option("--print-files", "Print per-file summary (wrapped count, skipped)").action(async (pathArg, opts) => {
+  const codemodCmd = new Command11("codemod").description("Codemod commands for adopting autotel");
+  const traceCmd = new Command11("trace").description("Wrap functions in trace() with span name from function/variable/method name").argument("<path>", "File path or glob (e.g. src/index.ts, src/**/*.ts)").option("--dry-run", "Print changes without writing files").option("--name-pattern <pattern>", "Span name template: {name}, {file}, {path}").option("--skip <regex>...", "Skip functions whose name matches (repeatable)").option("--print-files", "Print per-file summary (wrapped count, skipped)").action(async (pathArg, opts) => {
     const options = {
       cwd: opts.cwd ?? process.cwd(),
       dryRun: opts.dryRun ?? false,
@@ -3457,16 +5880,104 @@ function createProgram() {
   codemodCmd.addCommand(traceCmd);
   addGlobalOptions(codemodCmd);
   program.addCommand(codemodCmd);
+  const schemaCmd = new Command11("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 Command11("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 Command11("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 Command11("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 Command11("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 Command11("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);
+  registerHealthCommands(program);
+  registerDiscoveryCommands(program);
+  registerQueryCommands(program);
+  registerTraceCommands(program);
+  registerTopologyCommands(program);
+  registerDiagnoseCommands(program);
+  registerCorrelateCommands(program);
+  registerLlmCommands(program);
+  registerSemconvCommands(program);
+  registerScoreCommands(program);
+  registerCollectorCommands(program);
   return program;
 }
 async function run() {
   const program = createProgram();
+  program.exitOverride();
+  const argvJoined = process.argv.slice(2).join(" ");
+  const isJsonOnly = process.argv.includes("--json") || /^(schema|commands|examples|version|health|capabilities|discover|query|trace|diagnose|topology|correlate|llm|semconv|score|collector)\b/.test(
+    argvJoined
+  );
+  if (isJsonOnly) {
+    program.configureOutput({ writeErr: () => {
+    } });
+  }
+  const stack = [...program.commands];
+  while (stack.length > 0) {
+    const cmd = stack.pop();
+    cmd.exitOverride();
+    if (isJsonOnly) {
+      cmd.configureOutput({ writeErr: () => {
+      } });
+    }
+    stack.push(...cmd.commands);
+  }
   await program.parseAsync(process.argv);
 }
 
+// src/lib/commander-error.ts
+function commanderErrorToAutotel(error2) {
+  if (error2 === null || typeof error2 !== "object" || !("code" in error2) || typeof error2.code !== "string" || !error2.code.startsWith("commander.")) {
+    return null;
+  }
+  const ce = error2;
+  if (ce.code === "commander.help" || ce.code === "commander.helpDisplayed" || ce.code === "commander.version") {
+    process.exit(ce.exitCode ?? 0);
+  }
+  return new AutotelError({
+    type: "validation",
+    code: "AUTOTEL_E_INVALID_FLAG",
+    message: ce.message,
+    retryable: false,
+    expected: { commanderCode: ce.code }
+  });
+}
+
 // 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 = commanderErrorToAutotel(error2) ?? toAutotelError(error2);
+  const isJson = jsonModeRequested() || // schema/commands/examples/version + investigate commands are JSON-only
+  /^(schema|commands|examples|version|health|capabilities|discover|query|trace|diagnose|topology|correlate|llm|semconv|score|collector)\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