autotel-cli 0.8.8 → 0.8.9

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import { Command } from "commander";
+import { Command as Command11 } from "commander";
 
 // src/commands/init.ts
 import * as fs4 from "fs";
@@ -4078,8 +4078,8 @@ async function runCodemodTrace(options) {
       totalWrapped += result.wrappedCount;
       totalChanged += 1;
       if (!dryRun) {
-        const fs7 = await import("fs");
-        fs7.writeFileSync(filePath, result.modified, "utf8");
+        const fs9 = await import("fs");
+        fs9.writeFileSync(filePath, result.modified, "utf8");
       }
     }
     const showSummary = printFiles || dryRun || result.changed;
@@ -4307,6 +4307,142 @@ var COMMANDS = [
     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);
 }
@@ -4461,14 +4597,1199 @@ function runVersion(opts) {
   });
 }
 
+// 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").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 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,
@@ -4498,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,
@@ -4516,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,
@@ -4538,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,
@@ -4559,45 +5880,93 @@ function createProgram() {
   codemodCmd.addCommand(traceCmd);
   addGlobalOptions(codemodCmd);
   program.addCommand(codemodCmd);
-  const schemaCmd = new Command("schema").description("Print the CLI manifest as JSON (agent discovery)").option("--output-file <path>", "Persist JSON to a file").option("--no-secrets-in-output", "Redact secret-shaped values").action((opts) => {
+  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 Command("errors").description("Print error envelope shape + AUTOTEL_E_* codes").option("--output-file <path>", "Persist JSON to a file").action((opts) => {
+  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 Command("outputs").description("Print JSON output shapes per command").option("--output-file <path>", "Persist JSON to a file").action((opts) => {
+  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 Command("commands").description("Print compact tool-style listing of commands").option("--output-file <path>", "Persist JSON to a file").action((opts) => {
+  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 Command("examples").description("Print copy-pasteable examples for a command").argument("[command]", "Command name (omit for all)").option("--output-file <path>", "Persist JSON to a file").action((name, opts) => {
+  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 Command("version").description("Print version info as JSON").option("--output-file <path>", "Persist JSON to a file").action((opts) => {
+  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) => {
-  const err = toAutotelError(error2);
-  const isJson = jsonModeRequested() || // schema/commands/examples/version are JSON-only
-  /^(schema|commands|examples|version)\b/.test(
+  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) {