@cesarus777/opencode-cgp 0.3.0 → 0.4.0

package/dist/cli.js

@@ -44,6 +44,12 @@ function isHistoryRead(value) {
 function isHistoryResult(value) {
   return valid(value, historyResultSchema);
 }
+function isAnalyticsRead(value) {
+  return valid(value, analyticsReadSchema) && record(value) && typeof value.from === "number" && typeof value.to === "number" && value.from < value.to && value.to - value.from <= 604800000 && !(value.model !== undefined && value.unknownModel === true) && (!(value.modelCursor || value.requestCursor) || typeof value.snapshotId === "string");
+}
+function isAnalyticsResult(value) {
+  return valid(value, analyticsResultSchema);
+}
 function record(x) {
   return typeof x === "object" && x !== null && !Array.isArray(x);
 }
@@ -101,7 +107,7 @@ var count, text, enumeration = (...values) => ({ type: "string", enum: values })
   type: "array",
   items,
   maxItems
-}), measurement, row, batchFields, readSchema, batchSchema, resultSchema, monitorRpc, nonnegative, performanceSchema, performanceRow, performanceBatchSchema, performanceResultSchema, performanceRpc, chartPointSchema, chartRequestSchema, historyReadSchema, historyResultSchema, historyRpc;
+}), measurement, row, batchFields, readSchema, batchSchema, resultSchema, monitorRpc, nonnegative, performanceSchema, performanceRow, performanceBatchSchema, performanceResultSchema, performanceRpc, chartPointSchema, chartRequestSchema, historyReadSchema, historyResultSchema, historyRpc, modelSummarySchema, analyticsReadSchema, analyticsResultSchema, analyticsRpc;
 var init_rpc = __esm(() => {
   count = {
     type: "integer",
@@ -337,6 +343,123 @@ var init_rpc = __esm(() => {
     methods: { read: { input: historyReadSchema, output: historyResultSchema } },
     events: {}
   });
+  modelSummarySchema = object({
+    model: text,
+    sessions: count,
+    completedRequests: count,
+    partialRequests: count,
+    legacyAttributionRequests: count,
+    tpsRequests: count,
+    ttftRequests: count,
+    excludedTpsRequests: count,
+    excludedTtftRequests: count,
+    outputTokens: nonnegative,
+    durationMs: nonnegative,
+    averageTps: nonnegative,
+    meanTtftMs: nonnegative,
+    medianTtftMs: nonnegative,
+    p95TtftMs: nonnegative
+  }, [
+    "sessions",
+    "completedRequests",
+    "partialRequests",
+    "legacyAttributionRequests",
+    "tpsRequests",
+    "ttftRequests",
+    "excludedTpsRequests",
+    "excludedTtftRequests",
+    "outputTokens",
+    "durationMs"
+  ]);
+  analyticsReadSchema = object({
+    schemaVersion: { const: 1 },
+    from: count,
+    to: count,
+    buckets: { type: "integer", minimum: 1, maximum: 240 },
+    agent: text,
+    model: text,
+    unknownModel: { type: "boolean" },
+    sort: enumeration("requests", "tps", "ttft", "identity"),
+    snapshotId: text,
+    modelCursor: text,
+    requestCursor: text
+  }, ["schemaVersion", "from", "to", "buckets"]);
+  analyticsResultSchema = object({
+    schemaVersion: { const: 1 },
+    generatedAt: count,
+    expiresAt: count,
+    snapshotId: text,
+    enabled: { type: "boolean" },
+    from: count,
+    to: count,
+    agent: text,
+    models: array(modelSummarySchema, 50),
+    totalModels: count,
+    nextModelsCursor: text,
+    selected: modelSummarySchema,
+    buckets: array(object({ from: nonnegative, to: nonnegative, summary: modelSummarySchema }, ["from", "to"]), 240),
+    requests: array(object({
+      location: text,
+      sessionId: text,
+      requestId: text,
+      startedAt: count,
+      completedAt: count,
+      model: text,
+      agent: text,
+      attribution: enumeration("request", "legacy-record", "unknown"),
+      partial: { type: "boolean" },
+      outputTokens: nonnegative,
+      ttftMs: nonnegative
+    }, [
+      "location",
+      "sessionId",
+      "requestId",
+      "startedAt",
+      "completedAt",
+      "attribution",
+      "partial"
+    ]), 50),
+    nextRequestsCursor: text,
+    coverage: object({
+      source: enumeration("retained-request-records"),
+      scannedRecords: count,
+      unscannedRecords: count,
+      duplicateRecords: count,
+      conflictingRequests: count,
+      missingIdentityRecords: count,
+      incompleteRequests: count,
+      invalidTimingRequests: count,
+      gapRecords: count,
+      maxRequests: count,
+      partial: { type: "boolean" }
+    }),
+    metadata: historyResultSchema.properties.metadata ?? {},
+    gaps: array(count, 128),
+    omittedGaps: count
+  }, [
+    "schemaVersion",
+    "generatedAt",
+    "expiresAt",
+    "snapshotId",
+    "enabled",
+    "from",
+    "to",
+    "models",
+    "totalModels",
+    "buckets",
+    "requests",
+    "coverage",
+    "metadata",
+    "gaps",
+    "omittedGaps"
+  ]);
+  analyticsRpc = Rpc.define({
+    id: "context-guard.analytics.v1",
+    methods: {
+      read: { input: analyticsReadSchema, output: analyticsResultSchema }
+    },
+    events: {}
+  });
 });
 
 // src/history.ts
@@ -529,6 +652,7 @@ function scalarPerformance(p) {
 async function readPerformanceHistory(directory, filter = {}) {
   const records = [];
   const files = await segments(directory);
+  filter.signal?.throwIfAborted();
   const maxBytes = filter.maxBytes ?? 64 * 1024 * 1024;
   let bytes = 0, skippedBytes = 0, malformedRecords = 0;
   const selected = [];
@@ -541,6 +665,7 @@ async function readPerformanceHistory(directory, filter = {}) {
     selected.unshift(file);
   }
   for (const file of selected) {
+    filter.signal?.throwIfAborted();
     const handle = await open(join(directory, file.name), "r");
     let source;
     try {
@@ -550,7 +675,12 @@ async function readPerformanceHistory(directory, filter = {}) {
     } finally {
       await handle.close();
     }
+    let scannedLines = 0;
     for (const line of source.split("\n")) {
+      if (filter.signal && ++scannedLines % 256 === 0) {
+        await new Promise((done) => setTimeout(done, 0));
+        filter.signal.throwIfAborted();
+      }
       if (!line)
         continue;
       try {
@@ -663,19 +793,43 @@ async function loadTerminalRenderer() {
   try {
     return await import("@opentui/core");
   } catch {
-    throw new Error("Terminal renderer unavailable; install @opentui/core@0.5.17 beside @cesarus777/opencode-cgp using Bun >=1.3.0");
-  }
-}
-var dashboardHelp = `Usage: context-guard dashboard tui [--server URL] [--directory PATH]
-Read-only standalone terminal dashboard; never starts an OpenCode server.
-Requires an interactive terminal, Bun >=1.3.0 and @opentui/core@0.5.17.
-Install the renderer beside this package: npm install @opentui/core@0.5.17
-Local discovery defaults to the current directory.
-An explicit server requires --directory with an owning absolute server path.
-Remote authentication: CONTEXT_GUARD_PASSWORD and optional CONTEXT_GUARD_USERNAME
-(default opencode). Credentials must never be supplied in the URL.
-Keys: 1 overview, 2 detail, 3 history, arrows/j/k move, / search, f filters,
-l location, w history window, r refresh, ? help, Escape back, q/Ctrl+C quit.`;
+    throw new Error("Terminal renderer unavailable; reinstall @cesarus777/opencode-cgp with optional dependencies enabled for its platform renderer, using Bun >=1.3.0");
+  }
+}
+var dashboardHelp = `Usage: context-guard dashboard tui [options]
+Open a read-only live terminal dashboard for an existing OpenCode server.
+
+Start here
+  1. Keep an OpenCode server running with Context Guard registered.
+  2. Open a separate terminal tab, window or pane for the dashboard.
+  3. In the same project directory, run: context-guard dashboard tui
+  Keep working in OpenCode; the dashboard reads live updates from its server.
+
+Options
+  --directory PATH   Owning project directory (local default: current directory)
+  --server URL       Connect to an explicit server; requires --directory with
+                     an absolute server-side project path. Use HTTPS except
+                     on loopback. Credentials in URLs are rejected.
+  -h, --help         Show this help
+
+Examples
+  context-guard dashboard tui
+  context-guard dashboard tui --directory /absolute/project
+  context-guard dashboard tui --server https://server.example --directory /server/project
+
+Requirements
+  Interactive terminal and Bun >=1.3.0. The OpenTUI renderer is installed
+  automatically with CGP. This command never starts a server.
+
+Authentication (explicit servers)
+  CONTEXT_GUARD_PASSWORD   Server password
+  CONTEXT_GUARD_USERNAME   Server username (default: opencode)
+
+Keys
+  1/2/3/4 overview/detail/history/models; arrows or j/k move; Enter detail/chart;
+  Models: Left/Right metric, [/] bucket, d requests, n/p pages, s sort;
+  / session search; f filters (Models: agent); l location; w time window;
+  r refresh; ? help; q or Ctrl+C quit.`;
 var init_command = () => {
 };
 
@@ -1143,6 +1297,249 @@ var init_inventory = __esm(() => {
   });
 });
 
+// src/dashboard/port.ts
+var AnalyticsUnavailable;
+var init_port = __esm(() => {
+  AnalyticsUnavailable = class AnalyticsUnavailable extends Error {
+    reason;
+    constructor(reason) {
+      super(`Model analytics ${reason}`);
+      this.reason = reason;
+    }
+  };
+});
+
+// src/dashboard/models.ts
+class ModelsController {
+  changed;
+  port;
+  active = false;
+  key = "";
+  agent = "";
+  seedModel = "";
+  selection;
+  resolution = 120;
+  from = 0;
+  to = 1;
+  generation = 0;
+  abort;
+  pending;
+  modelPages = [undefined];
+  requestPages = [undefined];
+  state = {
+    status: "idle",
+    stale: false,
+    sort: "requests",
+    windowMs: 300000,
+    modelPage: 0,
+    requestPage: 0
+  };
+  constructor(changed) {
+    this.changed = changed;
+  }
+  getView() {
+    return this.state;
+  }
+  configure(port, active, windowMs, agent, seedModel, now) {
+    const key = JSON.stringify([
+      port.location.directory,
+      windowMs,
+      agent,
+      seedModel
+    ]);
+    const different = key !== this.key;
+    const preserveSelection = this.port?.location.directory === port.location.directory && this.agent === agent && this.seedModel === seedModel;
+    const entering = active && !this.active;
+    if (different || !active)
+      this.cancel();
+    this.port = port;
+    this.active = active;
+    if (different) {
+      this.key = key;
+      this.agent = agent;
+      this.seedModel = seedModel;
+      if (!preserveSelection)
+        this.selection = seedModel || undefined;
+      this.modelPages = [undefined];
+      this.requestPages = [undefined];
+      this.state = {
+        status: "idle",
+        stale: false,
+        sort: this.state.sort,
+        windowMs,
+        modelPage: 0,
+        requestPage: 0
+      };
+    }
+    if (active && (different || entering))
+      this.refresh(now);
+  }
+  cancel() {
+    this.generation++;
+    this.abort?.abort();
+    this.abort = undefined;
+    this.pending = undefined;
+  }
+  stop() {
+    this.cancel();
+    this.active = false;
+    this.state = { ...this.state, stale: Boolean(this.state.result) };
+  }
+  async refresh(now) {
+    if (!this.active || !this.port)
+      return;
+    if (this.pending)
+      return this.pending;
+    this.to = Math.max(1, Math.floor(now));
+    this.from = Math.max(0, this.to - this.state.windowMs);
+    this.modelPages = [undefined];
+    this.requestPages = [undefined];
+    this.state = { ...this.state, modelPage: 0, requestPage: 0 };
+    return this.query(false);
+  }
+  setWidth(width) {
+    const next = Math.max(1, Math.min(120, Math.floor(width) - 10));
+    if (next === this.resolution)
+      return;
+    this.resolution = next;
+    if (this.active && this.state.result)
+      this.query(true);
+  }
+  select(model) {
+    if (!this.active || model === this.selection)
+      return;
+    this.selection = model;
+    this.requestPages = [undefined];
+    this.state = { ...this.state, requestPage: 0 };
+    this.query(true);
+  }
+  sort() {
+    const sorts = ["requests", "tps", "ttft", "identity"];
+    this.modelPages = [undefined];
+    this.state = {
+      ...this.state,
+      sort: sorts[(sorts.indexOf(this.state.sort) + 1) % sorts.length] ?? "requests",
+      modelPage: 0
+    };
+    this.query(true);
+  }
+  page(kind, direction) {
+    if (this.state.status !== "ready")
+      return;
+    const pages = kind === "models" ? this.modelPages : this.requestPages;
+    const index = kind === "models" ? this.state.modelPage : this.state.requestPage;
+    const next = kind === "models" ? this.state.result?.nextModelsCursor : this.state.result?.nextRequestsCursor;
+    if (direction < 0 && index === 0 || direction > 0 && !next)
+      return;
+    if (direction > 0)
+      pages[index + 1] = next;
+    this.state = {
+      ...this.state,
+      ...kind === "models" ? { modelPage: index + direction, requestPage: 0 } : { requestPage: index + direction }
+    };
+    if (kind === "models") {
+      this.selection = undefined;
+      this.requestPages = [undefined];
+    }
+    this.query(true);
+  }
+  query(reuse) {
+    this.cancel();
+    const port = this.port;
+    if (!this.active || !port)
+      return Promise.resolve();
+    if (!port.analytics) {
+      this.state = { ...this.state, status: "unsupported", stale: false };
+      this.changed();
+      return Promise.resolve();
+    }
+    const read = port.analytics.bind(port);
+    const controller = new AbortController;
+    this.abort = controller;
+    const generation = this.generation;
+    const signal = AbortSignal.any([
+      controller.signal,
+      AbortSignal.timeout(15000)
+    ]);
+    const modelCursor = this.modelPages[this.state.modelPage];
+    const requestCursor = this.requestPages[this.state.requestPage];
+    const input = {
+      schemaVersion: 1,
+      from: this.from,
+      to: this.to,
+      buckets: this.resolution,
+      sort: this.state.sort,
+      ...this.agent ? { agent: this.agent } : {},
+      ...this.selection === "" ? { unknownModel: true } : this.selection ? { model: this.selection } : {},
+      ...reuse && this.state.result ? { snapshotId: this.state.result.snapshotId } : {},
+      ...reuse && modelCursor ? { modelCursor } : {},
+      ...reuse && requestCursor ? { requestCursor } : {}
+    };
+    this.state = {
+      ...this.state,
+      status: "loading",
+      stale: Boolean(this.state.result)
+    };
+    this.changed();
+    const task = Promise.resolve().then(async () => {
+      try {
+        let result;
+        try {
+          result = await read(input, signal);
+        } catch (error) {
+          if (!input.snapshotId || signal.aborted || error instanceof AnalyticsUnavailable && error.reason === "unsupported")
+            throw error;
+          const {
+            snapshotId: _id,
+            modelCursor: _m,
+            requestCursor: _r,
+            ...fresh
+          } = input;
+          result = await read(fresh, signal);
+          if (generation !== this.generation)
+            return;
+          signal.throwIfAborted();
+          this.modelPages = [undefined];
+          this.requestPages = [undefined];
+          this.state = { ...this.state, modelPage: 0, requestPage: 0 };
+        }
+        if (generation !== this.generation)
+          return;
+        signal.throwIfAborted();
+        if (!isAnalyticsResult(result) || result.from !== input.from || result.to !== input.to || result.agent !== input.agent || result.requests.some((r) => r.location !== port.location.directory))
+          throw new Error("Invalid analytics response");
+        if (result.selected)
+          this.selection = result.selected.model ?? "";
+        this.state = {
+          ...this.state,
+          result: structuredClone(result),
+          status: result.enabled ? "ready" : "disabled",
+          stale: false
+        };
+      } catch (error) {
+        if (generation !== this.generation || controller.signal.aborted)
+          return;
+        this.state = {
+          ...this.state,
+          status: error instanceof AnalyticsUnavailable && error.reason === "unsupported" && !this.state.result ? "unsupported" : "unavailable",
+          stale: Boolean(this.state.result)
+        };
+      } finally {
+        if (generation === this.generation) {
+          this.pending = undefined;
+          this.changed();
+        }
+      }
+    });
+    this.pending = task;
+    return task;
+  }
+}
+var init_models = __esm(() => {
+  init_rpc();
+  init_port();
+});
+
 // src/dashboard/view.ts
 function immutableView(value) {
   const copy = structuredClone(value);
@@ -1235,6 +1632,7 @@ class DashboardController {
   refreshTimer;
   ageTimer;
   view;
+  models;
   constructor(port, options = {}) {
     this.limits = { ...options.limits ?? inventoryLimits };
     validateInventoryLimits(this.limits);
@@ -1245,6 +1643,7 @@ class DashboardController {
       throw new Error("Invalid dashboard refresh interval");
     this.state = this.createLocation(port);
     this.locations.set(port.location.directory, this.state);
+    this.models = new ModelsController(() => this.publish());
     this.view = this.buildView();
   }
   createLocation(port) {
@@ -1294,6 +1693,7 @@ class DashboardController {
     await this.refresh();
   }
   stop() {
+    this.models.stop();
     this.running = false;
     this.generation++;
     this.scope?.abort();
@@ -1328,6 +1728,7 @@ class DashboardController {
     this.locations.delete(directory);
     this.locations.set(directory, next);
     this.state = next;
+    this.configureModels();
     if (this.locations.size > 4) {
       const oldest = this.locations.keys().next().value;
       if (oldest !== undefined)
@@ -1349,11 +1750,12 @@ class DashboardController {
     this.publish();
   }
   setScreen(screen) {
-    if (!["overview", "detail", "history"].includes(screen))
+    if (!["overview", "detail", "history", "models"].includes(screen))
       throw new Error("Invalid dashboard screen");
     if (screen === this.screen)
       return;
     this.screen = screen;
+    this.configureModels();
     this.queueHistory();
     this.publish();
   }
@@ -1363,6 +1765,7 @@ class DashboardController {
     if (windowMs === this.windowMs)
       return;
     this.windowMs = windowMs;
+    this.configureModels();
     this.queueHistory();
     this.publish();
   }
@@ -1375,11 +1778,18 @@ class DashboardController {
       agent: filters.agent ?? this.filters.agent,
       model: filters.model ?? this.filters.model
     };
+    this.configureModels();
     this.publish();
   }
+  configureModels() {
+    this.models.configure(this.state.port, this.running && this.screen === "models", this.windowMs, this.filters.agent, this.filters.model, this.serverNow());
+  }
   async refresh() {
     if (!this.running || !this.scope)
       return;
+    this.configureModels();
+    if (this.screen === "models")
+      this.models.refresh(this.serverNow());
     for (const cached of this.cache.values())
       if (cached.directory === this.state.port.location.directory)
         cached.valid = false;
@@ -1680,6 +2090,7 @@ class DashboardController {
           "maximum-500-points-and-requests"
         ]
       },
+      models: this.models.getView(),
       notices: [
         ...!state.complete ? ["partial-inventory"] : [],
         ...state.connection !== "live" ? ["live-data-stale"] : [],
@@ -1692,6 +2103,7 @@ var init_controller = __esm(() => {
   init_rpc();
   init_transport();
   init_inventory();
+  init_models();
   init_view();
 });
 
@@ -1844,6 +2256,19 @@ async function connectDashboard(options, discovery = Service) {
           }
         };
       },
+      async analytics(input, signal) {
+        if (!isAnalyticsRead(input))
+          throw new Error("Invalid analytics request");
+        try {
+          const result = await client.rpc(analyticsRpc).read(input, { location, signal: deadline(signal) });
+          if (!isAnalyticsResult(result))
+            throw new Error("Invalid analytics response");
+          return result;
+        } catch (error) {
+          const missing = typeof error === "object" && error !== null && "type" in error && (error.type === "rpc.unavailable" || error.type === "rpc.method_not_found");
+          throw new AnalyticsUnavailable(missing ? "unsupported" : "unavailable");
+        }
+      },
       async history(input, signal) {
         if (!isHistoryRead(input))
           throw new Error("History requires one session, at most seven days and 16\u2013500 points");
@@ -1871,6 +2296,7 @@ async function connectDashboard(options, discovery = Service) {
 }
 var init_connection = __esm(() => {
   init_rpc();
+  init_port();
 });
 
 // src/tui/format.ts
@@ -1991,9 +2417,9 @@ var init_format = __esm(() => {
 });
 
 // src/tui/chartformat.ts
-function columns(points, from, to, width, gaps = []) {
+function columns(points, from, to, width, gaps = [], halfOpen = false) {
   const size = Math.max(1, Math.min(120, Math.floor(width))), values = Array.from({ length: size });
-  const column = (time) => Math.max(0, Math.min(size - 1, Math.floor((time - from) / Math.max(1, to - from) * (size - 1))));
+  const column = (time) => Math.max(0, Math.min(size - 1, Math.floor((time - from) / Math.max(1, to - from) * (halfOpen ? size : size - 1))));
   let min = Infinity, max = -Infinity;
   for (const point of points) {
     if (point.time < from || point.time > to || point.value === undefined || !Number.isFinite(point.value) || point.value < 0)
@@ -2017,12 +2443,12 @@ function sparkline(points, from, to, width, gaps = []) {
       chars[column(time)] = "\u2506";
   return { line: chars.join(""), ...min === Infinity ? {} : { min, max } };
 }
-function metricPlot(points, from, to, width, gaps = []) {
+function metricPlot(points, from, to, width, gaps = [], halfOpen = false) {
   const label = (value) => value >= 1e6 ? `${(value / 1e6).toFixed(1)}M` : value >= 1000 ? `${(value / 1000).toFixed(1)}k` : value.toFixed(1);
   const peak = Math.max(0, ...points.filter((p) => p.time >= from && p.time <= to && Number.isFinite(p.value)).map((p) => p.value ?? 0));
   const scale = Math.max(1, peak);
   const gutter = width >= 20 ? Math.max(label(scale).length, 3) : 0;
-  const { values, column } = columns(points, from, to, Math.max(1, width - gutter - 2), gaps);
+  const { values, column } = columns(points, from, to, Math.max(1, halfOpen ? Math.min(points.length, width - gutter - 2) : width - gutter - 2), gaps, halfOpen);
   const gapColumns = new Set(gaps.filter((time) => time >= from && time <= to).map(column));
   const height = 6;
   const blocks = " \u2581\u2582\u2583\u2584\u2585\u2586\u2587\u2588";
@@ -2099,6 +2525,108 @@ var init_chartformat = __esm(() => {
   ];
 });
 
+// src/dashboard/modelview.ts
+function metricValue(summary, metric2) {
+  if (metric2.key === "outputTokens" && !summary?.tpsRequests)
+    return;
+  const value = summary?.[metric2.key];
+  return value === undefined ? undefined : value / metric2.divisor;
+}
+function terminalModelRow(model, focused) {
+  return [
+    `${focused ? "> " : "  "}${model.model ?? "unknown model attribution"}`,
+    `  ${stats(model)}`,
+    `  TPS eligible ${model.tpsRequests}; TTFT eligible ${model.ttftRequests}; partial ${model.partialRequests}; legacy attribution ${model.legacyAttributionRequests}`
+  ];
+}
+function terminalModels(view, width, detail, metricIndex, sample, focus, requests) {
+  const state = view.models;
+  const result = state.result;
+  const lines = [
+    `Models \xB7 ${state.status}${state.stale ? " \xB7 STALE cached results" : ""} \xB7 ${state.windowMs / 60000} minutes \xB7 retained history`,
+    `Agent: ${(result?.agent ?? view.filters.agent) || "all"} \xB7 sort ${state.sort} \xB7 location ${view.location}`,
+    "4 Models \xB7 Enter chart \xB7 Esc model list/overview \xB7 w window \xB7 f agent \xB7 r refresh"
+  ];
+  if (state.status === "unsupported")
+    return [
+      ...lines,
+      "Models requires a server with context-guard.analytics.v1; update the server plugin. Overview and session history remain available."
+    ];
+  if (state.status === "disabled")
+    return [
+      ...lines,
+      "Retained performance recording is disabled on this server."
+    ];
+  if (!result)
+    return [
+      ...lines,
+      state.status === "loading" ? "Loading model aggregates\u2026" : "Model analytics unavailable; press r to retry."
+    ];
+  lines.push(`${new Date(result.from).toISOString()} \u2192 ${new Date(result.to).toISOString()} (UTC; completion time)`);
+  const partial = result.coverage.partial || result.metadata.skippedBytes > 0 || result.metadata.malformedRecords > 0 || result.gaps.length > 0 || result.omittedGaps > 0;
+  lines.push(`Coverage: ${partial ? "PARTIAL" : "bounded observations"}; 64 MiB scan limit; ${result.coverage.maxRequests} request identities maximum; no pre-observation reconstruction.`);
+  lines.push(`Archive retained since ${result.metadata.retainedFrom === undefined ? "unknown" : new Date(result.metadata.retainedFrom).toISOString()}; snapshot observed at ${new Date(result.generatedAt).toISOString()}.`);
+  lines.push(`Scan: ${result.coverage.scannedRecords} records; ${result.metadata.skippedBytes} bytes skipped; ${result.metadata.malformedRecords} malformed; ${result.coverage.conflictingRequests} conflicting; ${result.coverage.incompleteRequests} incomplete; ${result.coverage.invalidTimingRequests} invalid timing; gaps ${result.gaps.length}${result.omittedGaps ? ` (+${result.omittedGaps} omitted)` : ""}.`);
+  if (!detail) {
+    lines.push(`Model page ${state.modelPage + 1} \xB7 ${result.totalModels} models \xB7 Up/Down scroll/select \xB7 n/p pages \xB7 s sort`);
+    if (!result.models.length)
+      lines.push("No completed requests match this range and agent filter.");
+    result.models.forEach((model, index) => {
+      lines.push(...terminalModelRow(model, index === focus));
+    });
+    return lines;
+  }
+  const selected = result.selected;
+  if (!selected)
+    return [
+      ...lines,
+      "No completed requests for this model in the selected range."
+    ];
+  lines.push(`Model: ${selected.model ?? "unknown model attribution"}`, stats(selected));
+  lines.push(`Reported output ${number(selected.tpsRequests ? selected.outputTokens : undefined)} tokens; matched duration ${number(selected.tpsRequests ? selected.durationMs / 1000 : undefined)}s; TPS eligible/excluded ${selected.tpsRequests}/${selected.excludedTpsRequests}; TTFT eligible/excluded ${selected.ttftRequests}/${selected.excludedTtftRequests}; partial ${selected.partialRequests}; legacy attribution ${selected.legacyAttributionRequests}`);
+  if (requests) {
+    lines.push(`Request page ${state.requestPage + 1} \xB7 n/p pages \xB7 d chart \xB7 completed stream \u2260 task success`);
+    result.requests.forEach((r) => lines.push(`Request ${r.requestId} \xB7 session ${r.sessionId}`, `Completed ${new Date(r.completedAt).toISOString()} \xB7 ${r.agent ?? "unknown agent"} \xB7 output ${number(r.outputTokens)} \xB7 duration ${number((r.completedAt - r.startedAt) / 1000)}s \xB7 TTFT ${number(r.ttftMs === undefined ? undefined : r.ttftMs / 1000)}s ~ \xB7 ${r.attribution}${r.partial ? " \xB7 partial" : ""}`));
+    return lines;
+  }
+  const metric2 = modelMetrics[metricIndex] ?? modelMetrics[0];
+  lines.push(`\u2039 ${metric2.label} (${metric2.unit}) \u203A \xB7 Left/Right metric \xB7 [/] bucket \xB7 d requests`);
+  lines.push(...metricPlot(result.buckets.map((bucket2) => {
+    const value = metricValue(bucket2.summary, metric2);
+    return {
+      time: (bucket2.from + bucket2.to) / 2,
+      ...value === undefined ? {} : { value }
+    };
+  }), result.from, result.to, width, result.gaps, true));
+  lines.push("UTC buckets \xB7 blank = no eligible observations \xB7 \u2506 = retained gap; partial coverage may hide other gaps.");
+  lines.push("TPS = reported output / summed matched request durations (includes TTFT); concurrent durations add. In-flight requests enter after stream completion.");
+  const bucket = result.buckets[Math.min(sample, Math.max(0, result.buckets.length - 1))];
+  if (bucket) {
+    lines.push(`Bucket ${Math.min(sample + 1, result.buckets.length)}/${result.buckets.length}: ${new Date(bucket.from).toISOString()} \u2192 ${new Date(bucket.to).toISOString()}`);
+    lines.push(bucket.summary ? stats(bucket.summary) : "No eligible observations; measurements unknown.");
+    lines.push(`Selected ${metric2.label}: ${number(metricValue(bucket.summary, metric2))} ${metric2.unit}`);
+    if (bucket.summary)
+      lines.push(`Bucket eligibility: TPS ${bucket.summary.tpsRequests}/${bucket.summary.completedRequests}; TTFT ${bucket.summary.ttftRequests}/${bucket.summary.completedRequests}; partial ${bucket.summary.partialRequests}`);
+  }
+  return lines;
+}
+var modelMetrics, number = (n) => n === undefined ? "?" : Number.isInteger(n) ? String(n) : n.toFixed(2), stats = (m) => `${m.sessions} sessions \xB7 ${m.completedRequests} completed \xB7 weighted TPS ${number(m.averageTps)} \xB7 TTFT median/p95 ${number(m.medianTtftMs === undefined ? undefined : m.medianTtftMs / 1000)}/${number(m.p95TtftMs === undefined ? undefined : m.p95TtftMs / 1000)}s ~`;
+var init_modelview = __esm(() => {
+  init_chartformat();
+  modelMetrics = [
+    { key: "averageTps", label: "Weighted request TPS", unit: "t/s", divisor: 1 },
+    { key: "medianTtftMs", label: "TTFT median ~", unit: "s", divisor: 1000 },
+    { key: "p95TtftMs", label: "TTFT p95 ~", unit: "s", divisor: 1000 },
+    {
+      key: "completedRequests",
+      label: "Completed requests",
+      unit: "requests",
+      divisor: 1
+    },
+    { key: "outputTokens", label: "Reported output", unit: "tokens", divisor: 1 }
+  ];
+});
+
 // src/dashboard/terminalview.ts
 function overviewRow(row2) {
   const s = row2.snapshot;
@@ -2181,7 +2709,11 @@ function terminalHistory(view, width, metricIndex, sample) {
   ];
 }
 function wrapped(lines, width) {
-  return lines.flatMap((line) => line ? wrap(line, Math.max(1, width)) : [""]);
+  const available = Math.max(1, width);
+  return lines.flatMap((line) => {
+    const clean = clip(line, Math.max(available, cells(line)));
+    return cells(clean) <= available ? [clean] : wrap(clean, available);
+  });
 }
 function headerLines(view, width) {
   return [
@@ -2261,7 +2793,10 @@ var init_terminalview = __esm(() => {
   ];
   terminalHelp = [
     "Context Guard standalone dashboard \u2014 keyboard help",
-    "1 overview \xB7 2 detail \xB7 3 history \xB7 Enter detail",
+    "1 overview \xB7 2 detail \xB7 3 history \xB7 4 models \xB7 Enter detail/chart",
+    "Models: Up/Down scroll tall rows, then select \xB7 Enter aggregate chart \xB7 Esc model list \xB7 s sort",
+    "Models charts: Left/Right metric \xB7 w window \xB7 [/] bucket \xB7 d request details",
+    "Models list/request details: n/p pages \xB7 f exact agent filter \xB7 r refresh",
     "Up/Down or j/k: select session in overview; scroll other screens",
     "PageUp/PageDown: move by a page \xB7 Home/End: first/last",
     "Left/Right: history metric (six metrics) \xB7 w: cycle 5m/1h/24h/7d",
@@ -2291,6 +2826,11 @@ class TerminalShell {
   scroll = 0;
   metric = 0;
   sample = 0;
+  modelDetail = false;
+  modelRequests = false;
+  modelFocus = 0;
+  modelFocusId;
+  modelViewport;
   help = false;
   editor;
   input = "";
@@ -2336,7 +2876,7 @@ class TerminalShell {
           this.task(this.controller.selectLocation(this.input));
         } else
           this.controller.setFilters({ [editor]: this.input });
-        this.editor = editor === "agent" ? "model" : undefined;
+        this.editor = editor === "agent" && view.screen !== "models" ? "model" : undefined;
         this.input = this.editor === "model" ? view.filters.model : "";
         this.scroll = 0;
         this.notice = "";
@@ -2356,6 +2896,11 @@ class TerminalShell {
     if (name === "escape") {
       this.help = false;
       this.scroll = 0;
+      if (view.screen === "models" && this.modelDetail) {
+        this.modelDetail = false;
+        this.modelRequests = false;
+        return;
+      }
       this.controller.setScreen("overview");
       return;
     }
@@ -2378,6 +2923,81 @@ class TerminalShell {
       this.task(this.controller.refresh());
       return;
     }
+    if (name === "4") {
+      this.help = false;
+      this.scroll = 0;
+      this.modelDetail = false;
+      this.modelRequests = false;
+      this.controller.setScreen("models");
+      return;
+    }
+    if (view.screen === "models" && !this.help) {
+      if (name === "enter" || name === "return") {
+        const model = view.models.result?.models[this.modelFocus];
+        if (model) {
+          this.controller.models.select(model.model ?? "");
+          this.modelDetail = true;
+          this.modelRequests = false;
+          this.sample = 0;
+          this.scroll = 0;
+        }
+        return;
+      }
+      if (name === "w") {
+        this.controller.setWindow(historyWindows[(historyWindows.indexOf(view.models.windowMs) + 1) % historyWindows.length] ?? historyWindows[0]);
+        this.sample = 0;
+        this.scroll = 0;
+        return;
+      }
+      if (name === "s" && !this.modelDetail) {
+        this.controller.models.sort();
+        this.scroll = 0;
+        return;
+      }
+      if (name === "n" || name === "p") {
+        if (!this.modelDetail || this.modelRequests) {
+          this.controller.models.page(this.modelDetail ? "requests" : "models", name === "n" ? 1 : -1);
+          if (!this.modelDetail) {
+            this.modelFocus = 0;
+            this.modelFocusId = undefined;
+          }
+          this.scroll = 0;
+        }
+        return;
+      }
+      if (this.modelDetail) {
+        if (name === "d") {
+          this.modelRequests = !this.modelRequests;
+          this.scroll = 0;
+          return;
+        }
+        if (name === "left" || name === "right") {
+          this.metric = (this.metric + modelMetrics.length + (name === "left" ? -1 : 1)) % modelMetrics.length;
+          this.sample = 0;
+          this.scroll = 0;
+          return;
+        }
+        if (name === "[" || name === "]") {
+          this.sample = Math.max(0, Math.min((view.models.result?.buckets.length ?? 1) - 1, this.sample + (name === "[" ? -1 : 1)));
+          return;
+        }
+      } else if (["up", "down", "j", "k", "home", "end", "pageup", "pagedown"].includes(name)) {
+        const models = view.models.result?.models ?? [];
+        const delta2 = name === "down" || name === "j" ? 1 : name === "up" || name === "k" ? -1 : name === "pagedown" ? page : -page;
+        const viewport = this.modelViewport;
+        if (viewport?.focus === this.modelFocus && viewport.end - viewport.start > viewport.height && name !== "home" && name !== "end" && (delta2 > 0 ? this.scroll + viewport.height < viewport.end : this.scroll > viewport.start)) {
+          this.scroll = Math.max(viewport.start, Math.min(viewport.end - viewport.height, this.scroll + delta2));
+          return;
+        }
+        if (name === "home")
+          this.scroll = 0;
+        if (name === "end")
+          this.scroll = Number.MAX_SAFE_INTEGER;
+        this.modelFocus = Math.max(0, Math.min(models.length - 1, name === "home" ? 0 : name === "end" ? models.length - 1 : this.modelFocus + delta2));
+        this.modelFocusId = models[this.modelFocus]?.model ?? "";
+        return;
+      }
+    }
     if (["1", "2", "3", "return", "enter"].includes(name)) {
       this.help = false;
       this.scroll = 0;
@@ -2414,14 +3034,28 @@ class TerminalShell {
   frame(width, height) {
     width = Math.max(1, width);
     height = Math.max(1, height);
+    this.controller.models.setWidth(width);
     const view = this.controller.getView();
-    const identity = `${view.location}\0${view.selectedSessionId}\0${view.history.windowMs}`;
+    if (view.screen === "models") {
+      const models = view.models.result?.models ?? [];
+      const identity2 = this.modelFocusId ?? view.models.result?.selected?.model ?? "";
+      const focused = models.findIndex((m) => (m.model ?? "") === identity2);
+      this.modelFocus = Math.max(0, focused < 0 ? Math.min(this.modelFocus, models.length - 1) : focused);
+      if (view.models.status === "ready" && models.length)
+        this.modelFocusId = models[this.modelFocus]?.model ?? "";
+    }
+    const identity = view.screen === "models" ? JSON.stringify([
+      view.location,
+      view.models.windowMs,
+      view.filters.agent,
+      view.models.result?.selected?.model
+    ]) : `${view.location}\0${view.selectedSessionId}\0${view.history.windowMs}`;
     if (identity !== this.historyIdentity) {
       this.sample = 0;
       this.scroll = 0;
       this.historyIdentity = identity;
     }
-    const footer = this.editor ? `${this.editor}> ${this.input} [Enter apply; Esc cancel${this.editor === "location" ? "; Tab remembered" : ""}]` : "? help q quit \xB7 1 overview 2 detail 3 history \xB7 / search f filters l location r refresh";
+    const footer = this.editor ? `${this.editor}> ${this.input} [Enter apply; Esc cancel${this.editor === "location" ? "; Tab remembered" : ""}]` : "? help q quit \xB7 1 overview 2 detail 3 history 4 models \xB7 / search f filters l location r refresh";
     if (height < 5)
       return [
         clip("Context Guard \xB7 ? help \xB7 q quit", width),
@@ -2434,7 +3068,7 @@ class TerminalShell {
       ...view.inventory.notices,
       ...view.health?.reasons ?? [],
       ...this.notice ? [this.notice] : [],
-      ...Object.values(view.filters).some(Boolean) ? [
+      ...view.screen !== "models" && Object.values(view.filters).some(Boolean) ? [
         `Filters: search=${view.filters.search} agent=${view.filters.agent} model=${view.filters.model}`
       ] : []
     ];
@@ -2469,8 +3103,28 @@ class TerminalShell {
     } else
       body = wrapped([
         ...notices,
-        ...view.screen === "detail" ? terminalDetail(view.selected) : terminalHistory(view, width, this.metric, this.sample)
+        ...view.screen === "detail" ? terminalDetail(view.selected) : view.screen === "models" ? terminalModels(view, width, this.modelDetail, this.metric, this.sample, this.modelFocus, this.modelRequests) : terminalHistory(view, width, this.metric, this.sample)
       ], width);
+    this.modelViewport = undefined;
+    if (view.screen === "models" && !this.modelDetail && !this.help && view.models.result?.models.length) {
+      const heights = (view.models.result?.models ?? []).map((model, index) => wrapped(terminalModelRow(model, index === this.modelFocus), width).length);
+      const start = body.length - heights.slice(this.modelFocus).reduce((a, b) => a + b, 0);
+      const end = start + (heights[this.modelFocus] ?? 0);
+      this.modelViewport = {
+        focus: this.modelFocus,
+        start,
+        end,
+        height: available
+      };
+      if (end - start > available) {
+        this.scroll = Math.max(start, Math.min(this.scroll, end - available));
+      } else {
+        if (start < this.scroll)
+          this.scroll = start;
+        if (end > this.scroll + available)
+          this.scroll = end - available;
+      }
+    }
     this.scroll = Math.max(0, Math.min(this.scroll, Math.max(0, body.length - available)));
     return [
       ...header,
@@ -2600,6 +3254,7 @@ var init_terminal = __esm(() => {
   init_connection();
   init_command();
   init_view();
+  init_modelview();
   init_format();
   init_terminalview();
 });
@@ -2647,7 +3302,7 @@ function reconcile(a, b) {
     partial: a.partial || b.partial
   };
 }
-function aggregateModels(records, options) {
+function analyzeModelRequests(records, options) {
   const maxRequests = options.maxRequests ?? 1e5;
   if (!Number.isSafeInteger(maxRequests) || maxRequests < 1 || maxRequests > 1e6)
     throw new Error("maxRequests must be an integer from 1 to 1000000");
@@ -2708,7 +3363,7 @@ function aggregateModels(records, options) {
       requests.set(key, { fact, conflict: false });
     }
   }
-  const groups = new Map;
+  const accepted = [];
   for (const { fact: r, conflict } of requests.values()) {
     if (conflict) {
       coverage.conflictingRequests++;
@@ -2725,6 +3380,22 @@ function aggregateModels(records, options) {
     }
     if (options.from !== undefined && r.completedAt < options.from || options.to !== undefined && r.completedAt >= options.to || options.model !== undefined && r.model !== options.model || options.agent !== undefined && r.agent !== options.agent)
       continue;
+    accepted.push({ ...r, completedAt: r.completedAt });
+  }
+  const models = summarizeModelRequests(accepted);
+  coverage.partial = coverage.unscannedRecords > 0 || coverage.conflictingRequests > 0 || coverage.missingIdentityRecords > 0 || coverage.incompleteRequests > 0 || coverage.invalidTimingRequests > 0 || coverage.gapRecords > 0 || models.some((s) => s.partialRequests > 0 || s.legacyAttributionRequests > 0 || s.excludedTpsRequests > 0 || s.excludedTtftRequests > 0 || !s.model);
+  return {
+    schemaVersion: 1,
+    location: options.location,
+    models,
+    coverage,
+    requests: accepted
+  };
+}
+function summarizeModelRequests(requests) {
+  const groups = new Map;
+  for (const r of requests) {
+    const duration = r.completedAt - r.startedAt;
     let group = groups.get(r.model);
     if (!group) {
       group = {
@@ -2779,8 +3450,11 @@ function aggregateModels(records, options) {
     }
     return s;
   }).sort((a, b) => (a.model ?? "").localeCompare(b.model ?? ""));
-  coverage.partial = coverage.unscannedRecords > 0 || coverage.conflictingRequests > 0 || coverage.missingIdentityRecords > 0 || coverage.incompleteRequests > 0 || coverage.invalidTimingRequests > 0 || coverage.gapRecords > 0 || models.some((s) => s.partialRequests > 0 || s.legacyAttributionRequests > 0 || s.excludedTpsRequests > 0 || s.excludedTtftRequests > 0 || !s.model);
-  return { schemaVersion: 1, location: options.location, models, coverage };
+  return models;
+}
+function aggregateModels(records, options) {
+  const { requests: _requests, ...result } = analyzeModelRequests(records, options);
+  return result;
 }
 var nonnegative2 = (n) => n !== undefined && Number.isFinite(n) && n >= 0;
 
@@ -2793,7 +3467,7 @@ import { isAbsolute as isAbsolute4, resolve as resolve2 } from "path";
 async function inspectModels(args) {
   const directory = args[0];
   if (!directory || !isAbsolute4(directory))
-    throw new Error("Usage: inspect models /absolute/history-directory [--model ID] [--agent NAME] [--from ISO-or-ms] [--to ISO-or-ms] [--csv | --json]");
+    throw new Error("Use context-guard models --help for usage and examples; the history directory must be an absolute path");
   const values = new Map;
   let csv = false, json = false;
   for (let i = 1;i < args.length; i++) {
@@ -3592,9 +4266,124 @@ async function readJournal(path, maxBytes = 16 * 1024 * 1024) {
   return records;
 }
 
+// src/clihelp.ts
+var mainHelp = `Context Guard \u2014 context monitoring for OpenCode V2
+
+Start here
+  In your project, run: opencode
+  Inside OpenCode, enter: /context-guard
+  The plugin loads with OpenCode; observe mode is the default.
+
+Usage: context-guard <command> [options]
+       context-guard <journal.jsonl> [--history | --json]
+
+Commands
+  dashboard tui   Open the standalone live terminal dashboard
+  models          Compare models across retained history
+  metrics         Export retained performance records as JSON or CSV
+  charts          Generate an interactive HTML report
+  <journal.jsonl> Inspect diagnostic session records
+
+Examples
+  context-guard dashboard tui
+  context-guard models /absolute/history-directory
+  context-guard charts /absolute/history-directory --output report.html
+  context-guard /absolute/events.jsonl --history
+
+Help
+  context-guard <command> --help   Show options and examples
+  context-guard help journal      Explain diagnostic inspection
+  -h, --help                     Show help
+
+Requires Bun >=1.1.34; the standalone dashboard requires Bun >=1.3.0.
+From a source checkout, replace context-guard with bun run inspect.`;
+var filterOptions = `  --agent NAME       Filter by exact agent name
+  --model PROVIDER/MODEL
+                     Filter by exact model ID
+  --from ISO-or-ms    Start time: ISO timestamp or Unix milliseconds
+  --to ISO-or-ms      End time: ISO timestamp or Unix milliseconds`;
+var historyOptions = `  --session ID       Filter by session
+${filterOptions}`;
+var historyPath = `Use the owning location's history.path directory, not its diagnostic JSONL
+file. By default it is a location-hashed directory under
+\$XDG_STATE_HOME/opencode-context-guard (or ~/.local/state/opencode-context-guard).
+A custom telemetry.path does not change the history directory.`;
+var commandHelp = {
+  models: `Usage: context-guard models <history-directory> [options]
+Compare model throughput and time to first token across retained sessions.
+The history directory must be an absolute path. Output defaults to JSON.
+
+Options
+${filterOptions}
+  --csv              Export CSV; coverage metadata goes to stderr
+  --json             Export JSON (default); cannot combine with --csv
+  -h, --help         Show this help
+
+Example
+  context-guard models /absolute/history-directory --agent build --csv
+
+${historyPath}`,
+  metrics: `Usage: context-guard metrics <history-directory> [options]
+Read retained performance records. Output defaults to JSON.
+
+Options
+${historyOptions}
+  --csv              Export CSV; coverage metadata goes to stderr
+  --chart FILE.html  Generate an HTML report instead (see charts --help)
+  -h, --help         Show this help
+
+Example
+  context-guard metrics /absolute/history-directory --csv > metrics.csv
+
+${historyPath}`,
+  charts: `Usage: context-guard charts <history-directory> [options]
+Generate a self-contained interactive HTML report, then open it in a browser.
+
+Options
+${historyOptions}
+  --output FILE.html Write the report (default: context-guard-charts.html)
+  --max-points N     Points per series: 16\u20135000 (default: 1000)
+  --max-sessions N   Session instances: 1\u20131024 (default: 128)
+  --force            Overwrite an existing report
+  -h, --help         Show this help
+
+Example
+  context-guard charts /absolute/history-directory --output report.html
+
+${historyPath}`,
+  journal: `Usage: context-guard <journal.jsonl> [options]
+Inspect the diagnostic journal reported in OpenCode's Context Guard startup log.
+By default, print the latest retained record for each session, one JSON per line.
+
+Options
+  --json             Print latest session records as a JSON array
+  --history          Print all retained journal records as a JSON array
+  -h, --help         Show this help
+
+Example
+  context-guard /absolute/path/from/startup.jsonl --history
+
+This reads a diagnostic file, not a performance history directory.`
+};
+
 // src/cli.ts
 var args = process.argv.slice(2);
-if (args[0] === "dashboard") {
+var helpRequested = args.some((arg) => arg === "--help" || arg === "-h");
+var helpTopic = args[0] === "help" ? args[1] : args[0];
+if (!args[0] || args[0] === "help" || helpRequested || args.length === 1 && (args[0] === "dashboard" || Object.hasOwn(commandHelp, args[0]))) {
+  if (helpTopic === "dashboard") {
+    const { dashboardHelp: dashboardHelp2 } = await Promise.resolve().then(() => (init_command(), exports_command));
+    console.log(dashboardHelp2);
+  } else if (helpTopic && Object.hasOwn(commandHelp, helpTopic)) {
+    console.log(commandHelp[helpTopic]);
+  } else if (args[0] === "help" && helpTopic) {
+    console.error(`Unknown help topic. Use context-guard --help for commands.`);
+    process.exitCode = 1;
+  } else if (helpRequested && helpTopic && !helpTopic.startsWith("-")) {
+    console.log(commandHelp.journal);
+  } else
+    console.log(mainHelp);
+} else if (args[0] === "dashboard") {
   const { parseDashboardArgs: parseDashboardArgs2, dashboardHelp: dashboardHelp2, checkTerminalRuntime: checkTerminalRuntime2 } = await Promise.resolve().then(() => (init_command(), exports_command));
   try {
     const options = parseDashboardArgs2(args.slice(1), process.cwd(), process.env);
@@ -3611,15 +4400,13 @@ if (args[0] === "dashboard") {
     console.error(safe ? message : "Dashboard startup failed; check server, owning directory, authentication and renderer installation");
     process.exitCode = 1;
   }
-} else if (!args[0] || args.includes("--help")) {
-  console.log("Usage: bun run inspect /absolute/path/to/journal.jsonl [--history] [--json]\nThe ready log reports the location-specific journal path.\nMetrics: inspect metrics /absolute/history-directory [--session ID] [--from ISO-or-ms] [--to ISO-or-ms] [--csv]\nModels: inspect models /absolute/history-directory [--model provider/model] [--agent NAME] [--from ISO-or-ms] [--to ISO-or-ms] [--csv | --json]\nCharts: inspect charts /absolute/history-directory --output report.html [--session ID] [--agent NAME] [--model provider/model] [--from ISO-or-ms] [--to ISO-or-ms] [--max-points 1000] [--force]");
 } else if (args[0] === "models") {
   const { inspectModels: inspectModels2 } = await Promise.resolve().then(() => (init_modelcli(), exports_modelcli));
   await inspectModels2(args.slice(1));
 } else if (args[0] === "metrics" || args[0] === "charts") {
   const directory = args[1];
   if (!directory || directory.startsWith("--"))
-    throw new Error("Usage: inspect metrics /absolute/history-directory [--session ID] [--from ISO-or-ms] [--to ISO-or-ms] [--csv]");
+    throw new Error(`Use context-guard ${args[0]} --help for usage and examples`);
   const option = (name) => {
     const index = args.indexOf(name);
     if (index < 0)