akm-cli 0.9.27 → 0.9.28-alpha.2

package/dist/scripts/akm-migrate.js

@@ -27777,6 +27777,243 @@ registerMdRenderer("health", (result) => {
   return null;
 });
 
+// src/commands/metrics/report-view.ts
+var BRIEF_LIST_LIMIT = 5;
+function isMetricsResult(value) {
+  if (value === null || typeof value !== "object")
+    return false;
+  const r = value;
+  return r.schemaVersion === 1 && !!r.window && !!r.usage && !!r.feedback && !!r.llm;
+}
+var int = (n) => String(n);
+var dash = (v) => v === undefined || v === "" ? "-" : v;
+var pct = (n) => n === null ? "n/a" : `${(n * 100).toFixed(1)}%`;
+var ms = (n) => n === null ? "n/a" : `${Math.round(n)} ms`;
+var fixed = (n, digits) => n === null ? "n/a" : n.toFixed(digits);
+function sourceFacts(counts) {
+  const entries = Object.entries(counts);
+  return entries.length === 0 ? "-" : entries.map(([k, v]) => `${k}=${v}`).join(" ");
+}
+function llmRows(group) {
+  return Object.entries(group).map(([name, a]) => [
+    name,
+    int(a.calls),
+    int(a.failures),
+    int(a.promptTokens),
+    int(a.completionTokens),
+    int(a.totalTokens),
+    ms(a.totalDurationMs)
+  ]);
+}
+var LLM_HEADERS = ["name", "calls", "failed", "prompt", "completion", "total", "time"];
+function buildMetricsView(r, detail) {
+  const brief = detail === "brief";
+  const cut = (items) => brief ? items.slice(0, BRIEF_LIST_LIMIT) : items;
+  const { usage, feedback, utility, llm } = r;
+  const searches = usage.totals.searches;
+  const sections = [
+    {
+      title: "Usage",
+      facts: [
+        ["searches", int(searches)],
+        ["shows", int(usage.totals.shows)],
+        ["curates", int(usage.totals.curates)],
+        ["selects", int(usage.totals.selects)],
+        ["select rate", pct(usage.selectRate)],
+        [
+          "zero-result searches",
+          `${usage.totals.zeroResultSearches} (${pct(searches === 0 ? null : usage.totals.zeroResultSearches / searches)})`
+        ],
+        ["search median", ms(usage.searchMedianMs)],
+        ["distinct assets", int(usage.totals.distinctAssets)],
+        ["distinct queries", int(usage.totals.distinctQueries)],
+        ["by source", sourceFacts(usage.bySource)]
+      ],
+      tables: [
+        {
+          title: "Top assets",
+          headers: ["ref", "shows", "search hits", "selects", "+", "-", "last used"],
+          rows: cut(usage.topAssets).map((a) => [
+            a.ref,
+            int(a.shows),
+            int(a.searchHits),
+            int(a.selects),
+            int(a.positive),
+            int(a.negative),
+            dash(a.lastUsedAt)
+          ])
+        },
+        {
+          title: "Top queries",
+          headers: ["query", "count", "avg results", "last"],
+          rows: cut(usage.topQueries).map((q) => [q.query, int(q.count), fixed(q.avgResults, 1), q.lastAt])
+        },
+        {
+          title: "Zero-result queries",
+          headers: ["query", "count", "last"],
+          rows: cut(usage.zeroResultQueries).map((q) => [q.query, int(q.count), q.lastAt])
+        },
+        {
+          title: "Daily",
+          headers: ["day", "search", "show", "curate", "feedback"],
+          rows: brief ? [] : usage.daily.map((d) => [d.day, int(d.search), int(d.show), int(d.curate), int(d.feedback)]),
+          hideWhenEmpty: true
+        }
+      ]
+    },
+    {
+      title: "Feedback",
+      facts: [
+        ["positive", int(feedback.totals.positive)],
+        ["negative", int(feedback.totals.negative)]
+      ],
+      tables: [
+        {
+          title: "By asset",
+          headers: ["ref", "+", "-", "valence", "last"],
+          rows: cut(feedback.byAsset).map((a) => [
+            a.ref,
+            int(a.positive),
+            int(a.negative),
+            fixed(a.valence, 2),
+            a.lastAt
+          ])
+        },
+        {
+          title: "By tag",
+          headers: ["tag", "+", "-"],
+          rows: cut(Object.entries(feedback.byTag)).map(([tag, c]) => [tag, int(c.positive), int(c.negative)]),
+          hideWhenEmpty: true
+        },
+        {
+          title: "Recent negative",
+          headers: ["ref", "at", "reason", "tags"],
+          rows: cut(feedback.recentNegative).map((n) => [n.ref, n.at, dash(n.reason), dash(n.tags?.join(", "))])
+        }
+      ]
+    },
+    {
+      title: "Utility",
+      facts: [
+        ["scored assets", int(utility.count)],
+        ["never used", int(utility.neverUsed)]
+      ],
+      tables: [
+        {
+          title: "Histogram",
+          headers: ["bucket", "count"],
+          rows: utility.histogram.map((h) => [h.bucket, int(h.count)]),
+          hideWhenEmpty: true
+        },
+        { title: "Lowest", headers: utilityHeaders(), rows: cut(utility.lowest).map(utilityRow) },
+        { title: "Highest", headers: utilityHeaders(), rows: cut(utility.highest).map(utilityRow) },
+        {
+          title: "Lowest outcome",
+          headers: ["ref", "outcome", "retrievals", "negative", "accepted changes"],
+          rows: cut(r.outcomes.lowestOutcome).map((o) => [
+            o.ref,
+            fixed(o.outcomeScore, 2),
+            int(o.retrievalCount),
+            int(o.negativeFeedbackCount),
+            int(o.acceptedChangeCount)
+          ]),
+          hideWhenEmpty: true
+        }
+      ]
+    },
+    {
+      title: "LLM",
+      facts: [
+        ["calls", int(llm.calls)],
+        ["failed", int(llm.failures)],
+        ["prompt tokens", int(llm.promptTokens)],
+        ["completion tokens", int(llm.completionTokens)],
+        ["reasoning tokens", int(llm.reasoningTokens)],
+        ["total tokens", int(llm.totalTokens)],
+        ["time", ms(llm.totalDurationMs)]
+      ],
+      tables: [
+        { title: "By engine", headers: LLM_HEADERS, rows: cut(llmRows(llm.byEngine)), hideWhenEmpty: true },
+        { title: "By process", headers: LLM_HEADERS, rows: cut(llmRows(llm.byProcess)), hideWhenEmpty: true },
+        { title: "By stage", headers: LLM_HEADERS, rows: cut(llmRows(llm.byStage)), hideWhenEmpty: true }
+      ]
+    },
+    {
+      title: "Index",
+      facts: [
+        ["runs", int(r.index.runs)],
+        ["median time", ms(r.index.medianMs)]
+      ],
+      tables: [
+        {
+          title: "Recent runs",
+          headers: ["at", "mode", "time"],
+          rows: brief ? [] : r.index.recent.map((i) => [i.at, i.mode, ms(i.totalMs)]),
+          hideWhenEmpty: true
+        }
+      ]
+    },
+    {
+      title: "Tasks",
+      facts: [
+        ["runs", int(r.tasks.runs)],
+        ["failed", int(r.tasks.failed)],
+        ["fail rate", pct(r.tasks.failRate)]
+      ],
+      tables: [
+        {
+          title: "By task",
+          headers: ["task", "runs", "failed", "median"],
+          rows: cut(r.tasks.byTask).map((t) => [t.taskId, int(t.runs), int(t.failed), ms(t.medianMs)]),
+          hideWhenEmpty: true
+        }
+      ]
+    },
+    {
+      title: "Proposals",
+      facts: [["by status", sourceFacts(r.proposals.byStatus)]],
+      tables: [
+        {
+          title: "Accept rate by source",
+          headers: ["source", "total", "accepted", "rejected", "pending", "accept rate"],
+          rows: r.proposals.acceptRateBySource.map((p) => [
+            p.source,
+            int(p.total),
+            int(p.accepted),
+            int(p.rejected),
+            int(p.pending),
+            pct(p.acceptRate)
+          ]),
+          hideWhenEmpty: true
+        }
+      ]
+    },
+    {
+      title: "Workflows",
+      facts: [
+        ["runs", int(r.workflows.runs)],
+        ["by status", sourceFacts(r.workflows.byStatus)],
+        ["tokens", int(r.workflows.tokens)],
+        ["tokens by model", sourceFacts(r.workflows.byModel)]
+      ],
+      tables: []
+    }
+  ];
+  const f = r.filters;
+  return {
+    window: `${r.window.since} to ${r.window.until}`,
+    filters: `source=${f.source}`,
+    sections,
+    notes: r.notes
+  };
+}
+function utilityHeaders() {
+  return ["ref", "utility", "shows", "searches", "select rate", "last used"];
+}
+function utilityRow(u) {
+  return [u.ref, fixed(u.utility, 2), int(u.showCount), int(u.searchCount), pct(u.selectRate), dash(u.lastUsedAt)];
+}
+
 // src/output/generic-render.ts
 var ENVELOPE_META_KEYS = new Set(["shape", "schemaVersion"]);
 function flattenForText(value, path11, lines) {
@@ -28377,6 +28614,7 @@ var PASSTHROUGH_COMMANDS = [
   "info",
   "lint",
   "list",
+  "metrics",
   "models",
   "proposal-accept-batch",
   "proposal-drain",
@@ -29651,10 +29889,10 @@ function formatHealthPlain(r, detail) {
 `).trim();
 }
 // src/output/text/lint-format.ts
-function glyphFor(fixed) {
-  if (fixed === "failed")
+function glyphFor(fixed2) {
+  if (fixed2 === "failed")
     return { glyph: "\u2717", severityRank: 0 };
-  if (fixed === true)
+  if (fixed2 === true)
     return { glyph: "\u2713", severityRank: 2 };
   return { glyph: "\u26A0", severityRank: 1 };
 }
@@ -29673,17 +29911,17 @@ function renderIssueSection(title, issues) {
 function formatLintPlain(r) {
   if (r === null || typeof r !== "object")
     return null;
-  const fixed = Array.isArray(r.fixed) ? r.fixed : [];
+  const fixed2 = Array.isArray(r.fixed) ? r.fixed : [];
   const flagged = Array.isArray(r.flagged) ? r.flagged : [];
   const warnings = Array.isArray(r.warnings) ? r.warnings : [];
   const summary = r.summary;
   const lines = [];
   if (typeof r.ok === "boolean")
     lines.push(`ok: ${r.ok}`);
-  lines.push(`summary: fixed=${summary?.fixed ?? fixed.length} flagged=${summary?.flagged ?? flagged.length}` + ` warnings=${summary?.warnings ?? warnings.length}`);
+  lines.push(`summary: fixed=${summary?.fixed ?? fixed2.length} flagged=${summary?.flagged ?? flagged.length}` + ` warnings=${summary?.warnings ?? warnings.length}`);
   lines.push("", ...renderIssueSection("flagged", flagged));
   lines.push("", ...renderIssueSection("warnings", warnings));
-  lines.push("", ...renderIssueSection("fixed", fixed));
+  lines.push("", ...renderIssueSection("fixed", fixed2));
   return lines.join(`
 `).trim();
 }
@@ -36144,8 +36382,8 @@ function getConfigLockPath() {
 }
 var CONFIG_LOCK_MAX_RETRIES = 40;
 var CONFIG_LOCK_RETRY_DELAY_MS = 50;
-function sleepSyncMs(ms) {
-  sleepSync(ms);
+function sleepSyncMs(ms2) {
+  sleepSync(ms2);
 }
 function acquireConfigLock() {
   const lockPath = getConfigLockPath();
@@ -53170,6 +53408,40 @@ var lintFormatters = [{ command: "lint", handler: (r) => formatLintPlain(r) }];
 // src/output/text/list.ts
 var listFormatters = [{ command: "list", handler: (r) => formatListPlain(r) }];
 
+// src/output/text/metrics.ts
+var flat = (s) => s.replace(/\s*\r?\n\s*/g, " ");
+function renderTable2(table) {
+  const all = [table.headers, ...table.rows].map((r) => r.map(flat));
+  const widths = table.headers.map((_, i) => Math.max(...all.map((r) => (r[i] ?? "").length)));
+  const line = (r) => `  ${r.map((c, i) => c.padEnd(widths[i] ?? 0)).join("  ")}`.trimEnd();
+  return [`${table.title}:`, ...all.map(line)];
+}
+function formatMetricsPlain(result, detail) {
+  if (!isMetricsResult(result))
+    return null;
+  const view = buildMetricsView(result, detail);
+  const lines = [`akm metrics  ${view.window}`, `filters: ${view.filters}`];
+  for (const section of view.sections) {
+    lines.push("", section.title.toUpperCase());
+    const labelWidth = Math.max(0, ...section.facts.map(([label]) => label.length));
+    for (const [label, value] of section.facts)
+      lines.push(`  ${label.padEnd(labelWidth)}  ${value}`);
+    for (const table of section.tables) {
+      if (table.rows.length > 0)
+        lines.push("", ...renderTable2(table));
+      else if (!table.hideWhenEmpty)
+        lines.push("", `${table.title}: (none)`);
+    }
+  }
+  if (view.notes.length > 0)
+    lines.push("", "NOTES", ...view.notes.map((n) => `  - ${flat(n)}`));
+  return lines.join(`
+`);
+}
+var metricsFormatters = [
+  { command: "metrics", handler: (r, detail) => formatMetricsPlain(r, detail) }
+];
+
 // src/output/text/migrate.ts
 function planGlyph(status) {
   switch (status) {
@@ -53304,6 +53576,7 @@ var BUILT_IN_TEXT_FORMATTERS = [
   ...proposalProducerFormatters,
   ...infoFormatters,
   ...healthFormatters,
+  ...metricsFormatters,
   ...improveReportFormatters,
   ...lintFormatters,
   ...configFormatters,

package/dist/storage/repositories/index-utility-repository.js

@@ -271,3 +271,27 @@ export function applyFeedbackToUtilityScore(db, entryId, positiveCount, negative
   `).run(entryId, result.nextUtility, now, now, result.nextUtility, now);
     return result;
 }
+/**
+ * Every indexed entry with its `utility_scores` row (when it has one), for
+ * `akm metrics`. `utility_scores` is keyed by the unstable `entry_id`, so the
+ * join to `entries` is what yields a durable ref.
+ */
+export function listUtilityWithRefs(db) {
+    const rows = db
+        .prepare(`SELECT e.item_ref AS ref, u.utility, u.show_count, u.search_count, u.select_rate, u.last_used_at
+       FROM entries e LEFT JOIN utility_scores u ON u.entry_id = e.id
+       ORDER BY e.item_ref`)
+        .all();
+    return rows.map((row) => row.utility === null
+        ? { ref: row.ref }
+        : {
+            ref: row.ref,
+            score: {
+                utility: row.utility,
+                showCount: row.show_count ?? 0,
+                searchCount: row.search_count ?? 0,
+                selectRate: row.select_rate ?? 0,
+                lastUsedAt: row.last_used_at ?? undefined,
+            },
+        });
+}

package/dist/storage/repositories/metrics-repository.js

@@ -0,0 +1,80 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/** Usage rows (search / show / curate / feedback) in the window, oldest first. */
+export function listUsageEventRows(db, filter) {
+    const sourceSql = filter.source === undefined ? "" : " AND source = ?";
+    const sourceParams = filter.source === undefined ? [] : [filter.source];
+    // `created_at` has whole-second resolution, so a row written during the
+    // bound's own second (e.g. `--until` defaulting to now) is still inside the
+    // half-open window: round a fractional bound up to the next second.
+    const untilMs = Date.parse(filter.untilIso);
+    const untilBound = new Date(Math.ceil(untilMs / 1000) * 1000).toISOString();
+    return db
+        .prepare(`SELECT id, event_type, query, entry_id, entry_ref, signal, metadata, source, created_at
+       FROM usage_events
+       WHERE datetime(created_at) >= datetime(?) AND datetime(created_at) < datetime(?)${sourceSql}
+       ORDER BY datetime(created_at), id`)
+        .all(filter.sinceIso, untilBound, ...sourceParams);
+}
+/**
+ * `select` events (a show within 60 s of a search that returned the ref) in the
+ * window. The events stream stores the ref as the user typed it (often
+ * bundle-less), so the caller resolves it to the durable ref.
+ */
+export function listSelectEvents(db, sinceIso, untilIso) {
+    return db
+        .prepare(`SELECT ts, ref FROM events
+       WHERE event_type = 'select' AND ref IS NOT NULL AND ts >= ? AND ts < ?
+       ORDER BY id`)
+        .all(sinceIso, untilIso);
+}
+/** `index_completed` events (one per `akm index` run) in the window, oldest first. */
+export function listIndexCompletedEvents(db, sinceIso, untilIso) {
+    return db
+        .prepare(`SELECT ts, metadata_json FROM events
+       WHERE event_type = 'index_completed' AND ts >= ? AND ts < ?
+       ORDER BY id`)
+        .all(sinceIso, untilIso);
+}
+/** The `limit` assets with the lowest `outcome_score`, ties broken by ref. */
+export function listLowestOutcomeAssets(db, limit) {
+    return db
+        .prepare(`SELECT asset_ref, last_retrieved_at, retrieval_count, expected_retrieval_rate,
+              negative_feedback_count, accepted_change_count, outcome_score, updated_at
+       FROM asset_outcome
+       ORDER BY outcome_score ASC, asset_ref ASC LIMIT ?`)
+        .all(limit);
+}
+/** Proposal counts by status, for proposals last updated in the window. */
+export function countProposalsByStatus(db, sinceIso, untilIso) {
+    const rows = db
+        .prepare(`SELECT status, COUNT(*) AS n FROM proposals
+       WHERE updated_at >= ? AND updated_at < ?
+       GROUP BY status ORDER BY status`)
+        .all(sinceIso, untilIso);
+    return Object.fromEntries(rows.map((row) => [row.status, row.n]));
+}
+/**
+ * Workflow runs created in the window by status, and the tokens their unit
+ * attempts spent by model. Attempts, not the unit projection, so a retried
+ * unit keeps the tokens of every attempt.
+ */
+export function summarizeWorkflowRuns(db, sinceIso, untilIso) {
+    const statusRows = db
+        .prepare(`SELECT status, COUNT(*) AS n FROM workflow_runs
+       WHERE created_at >= ? AND created_at < ? GROUP BY status ORDER BY status`)
+        .all(sinceIso, untilIso);
+    const modelRows = db
+        .prepare(`SELECT COALESCE(model, 'unattributed') AS model, SUM(tokens) AS tokens
+       FROM workflow_run_unit_attempts
+       WHERE tokens IS NOT NULL AND started_at >= ? AND started_at < ?
+       GROUP BY COALESCE(model, 'unattributed') ORDER BY model`)
+        .all(sinceIso, untilIso);
+    return {
+        runs: statusRows.reduce((sum, row) => sum + row.n, 0),
+        byStatus: Object.fromEntries(statusRows.map((row) => [row.status, row.n])),
+        tokens: modelRows.reduce((sum, row) => sum + row.tokens, 0),
+        byModel: Object.fromEntries(modelRows.map((row) => [row.model, row.tokens])),
+    };
+}

package/docs/reference/cli.md

@@ -42,7 +42,8 @@ Useful for streaming consumption by scripts or agents.
 A command may register a renderer for a document format when it has something
 better to say than the generic one: `akm health --group-by run --format md`
 emits its per-run table, and `akm health --report --format html` renders the
-full report with KPI cards, charts, and advisories. The renderers are
+full report with KPI cards, charts, and advisories. `akm metrics` always carries
+its window rows under `--format html`. The renderers are
 data-driven — they fire when the result carries the report dataset, never on
 the format alone, so the same dataset is available as JSON too. Every other command falls back to a
 generic rendering derived from its own envelope — headings for the top-level
@@ -439,6 +440,64 @@ for an infrastructure reason (`llm_unavailable`, `read_failed`, `exception`,
 `locked_concurrent`) — naming the reason and, when recorded, the engine — and
 `pass` otherwise, with per-outcome counts.
 
+### metrics
+
+**Experimental** (see [STABILITY.md](../../STABILITY.md)): the report, its JSON shape and the
+dashboard may change in any release.
+
+Report what akm has recorded locally: asset usage (search, show, curate),
+feedback, derived utility, LLM tokens, task runs, proposal
+flow, workflow token spend, and index runs. Read-only, and every number comes
+from `state.db` or `index.db`; nothing is collected that was not already
+recorded.
+
+```sh
+akm metrics
+akm metrics --since 7d
+akm metrics --since 2026-05-01 --format yaml
+akm metrics --format html --output metrics.html
+```
+
+| Flag | Description |
+| --- | --- |
+| `--since` | Window start. Accepts ISO 8601, `YYYY-MM-DD`, epoch milliseconds, or shorthand like `24h` / `7d`. Default: `30d`. |
+
+The window always ends now. Only `user`-source usage rows are counted (matching
+utility and retrieval counts), and every ranked list holds its top 20. For a
+narrower view, open the HTML dashboard and filter by date, bundle, source and
+event type in the browser.
+
+Result sections (`schemaVersion: 1`):
+
+| Field | Description |
+| --- | --- |
+| `window`, `filters` | The resolved window and the usage source counted |
+| `usage` | Search, show, curate and select totals, `selectRate` (selects over searches that returned a hit), `searchMedianMs`, a daily series, top assets, top and zero-result queries, and rows by source |
+| `feedback` | Positive and negative totals, per-asset valence, per-tag counts, and the most recent negatives with their reasons |
+| `utility` | A ten-bucket histogram of `utility_scores`, the lowest and highest assets, and how many indexed entries were never used |
+| `outcomes` | The assets with the lowest `outcome_score` |
+| `llm` | `akm health`'s LLM usage aggregate (by stage, process and engine) |
+| `index`, `tasks`, `proposals`, `workflows` | Index runs and median time, task runs and fail rate, proposals by status and accept rate by source, workflow runs and tokens by model |
+| `rows` | The raw usage and LLM rows of the window; see below |
+| `notes` | Anything that limits what the numbers mean |
+
+A rate whose denominator is 0 is `null`, never `NaN`. A missing `state.db`
+gives an empty report and a missing `index.db` an empty `utility` section, each
+with a `notes` entry, and the exit code stays 0.
+
+`rows` is present with `--format html` (the dashboard re-aggregates from it in
+the browser) and with `--detail full` in any other format; it is absent
+otherwise.
+
+Notes you may see:
+
+- A `--since` older than what a store keeps names the store, its retention
+  (`usage_events` keeps 90 days; `events`, which holds selects, LLM calls and
+  index runs, keeps `improve.eventRetentionDays`, default 90) and where its data
+  effectively starts, so a long window is never silently shorter than asked.
+- Selects are read from the events stream, which records no source, so they are
+  counted whatever the usage source is.
+
 ### search
 
 Search bundle assets, registries, or both.
@@ -2655,8 +2714,8 @@ precedent as the retired `canary` scope).
 Every real (non-dry-run) `akm improve` invocation persists a `usageReport`
 field on the result (`result_json` in `improve_runs`, and in the
 `--json-to-stdout` / dry-run JSON): `{ byProcessEngineModel, noCalls }`.
-`byProcessEngineModel` is a cross-tab of this run's own `llm_usage` events
-(#576) — one row per distinct `(process, engine, model)` triple, each with
+`byProcessEngineModel` is a cross-tab of the LLM call records this run's own
+usage sink collects (#576) — one row per distinct `(process, engine, model)` triple, each with
 `calls`, `failures`, `promptTokens`, `completionTokens`, `totalTokens`,
 `reasoningTokens`, and `totalDurationMs`. `noCalls` lists every model-calling
 process (`reflect`, `distill`, `consolidate`, `memoryInference`,
@@ -2678,7 +2737,7 @@ every real run in the window (`byProcessEngineModel` rows merged by
 `(process, engine, model)`; `noCalls` lists a process only if it made zero
 calls across every included run). A run recorded before 0.9.15 has no
 persisted `usageReport` — the command recomputes `byProcessEngineModel` from
-that run's own `llm_usage` events instead of erroring, sets `noCalls` to `[]`
+that run's stored `llm_usage` events (`summarizeLlmUsageCrossTab`) instead of erroring, sets `noCalls` to `[]`
 (eligibility reasons are not reconstructable after the fact), and adds a
 `notes` entry saying so rather than fabricating precision the old row can't
 support.

package/docs/reference/data-and-telemetry.md

@@ -162,6 +162,7 @@ the set of types the code actually emits at HEAD (verified against every
 | `feedback` | `akm feedback <ref>` | `signal` (positive/negative), `reason`, `tags`, `fix` (`source`, the number of replacements and, for `--superseded-by` or `--outdated`, the `beliefState` the proposal leaves and the `supersededBy` ref, when a fix was attached), `contentHash` (sha256 of the asset's body, without its frontmatter, as it stood when the feedback was given: it lets reflect mark feedback given on an earlier version of the text, and the loop's distill pass tell that a memory flagged wrong still has it; left out for an env or secret file and when the file cannot be read) |
 | `sync` | `akm sync` | `name`, `message`, `ok` |
 | `index_db_vacuumed` | `akm index` VACUUMed index.db, after an index layout migration or because more than half its pages were free | `pagesBefore`, `pagesAfter`, `freelistRatioBefore` |
+| `index_completed` | `akm index`, once when a run finishes | `mode`, `totalMs`, `walkMs`, `llmMs`, `embedMs`, `ftsMs`, `finalizeMs` (phase timings in milliseconds) |
 | `stash_synced` | `akm improve`'s internal auto-sync pass (the `sync.push` feature), **distinct from** the `akm sync` command above | `committed`, `pushed`, `skipped`, `reason`, `attributed` (paths the run wrote and staged), `unattributed` (in-scope paths that went dirty during the run without the run writing them — left for their author) |
 | `env_access` | `akm env run <name> -- <command>` (audit trail: key **names** only, values never recorded) | `ref`, `keys` |
 | `secret_access` | `akm secret run <ref> <VAR> -- <command>` (audit trail: var **name** only, value never recorded) | `ref`, `var` |
@@ -188,7 +189,7 @@ the set of types the code actually emits at HEAD (verified against every
 | `improve_invoked` | Start of an `akm improve` run | `ref` (scope); `strategy`, `scope`, `dryRun`, `eligibleCount` |
 | `improve_completed` | `akm improve` run finished | run stats |
 | `improve_failed` | `akm improve` run errored | error |
-| `improve_skipped` | `akm improve` left a ref, a lane, or a group of refs out | `reason` (`no_new_signal`, `not_retrieved`, `distill_no_new_signal`, `budget_exhausted`, `budget_exhausted_batch`, `asset_missing_on_disk`, `strategy_filtered_all_passes`, `autonomy_gated`, `engine_unavailable`, `pool_below_min_size`, `consolidation_no_memory_updates`, `below_min_new_sessions`, `derived_memory_reflect_skipped`, `memory_distill_requires_feedback`, `distill_flagged_wrong`, `distill_positive_without_reason`); `count`, `remaining`, `strategy`, `lane` or `configKey` where they apply |
+| `improve_skipped` | `akm improve` left a ref, a lane, or a group of refs out | `reason` (`no_new_signal`, `not_retrieved`, `distill_no_new_signal`, `budget_exhausted`, `budget_exhausted_batch`, `asset_missing_on_disk`, `strategy_filtered_all_passes`, `autonomy_gated`, `engine_unavailable`, `pool_below_min_size`, `consolidation_no_memory_updates`, `below_min_new_sessions`, `derived_memory_reflect_skipped`, `memory_distill_requires_feedback`, `distill_flagged_wrong`, `distill_positive_without_reason`, `distill_deprecated_or_superseded`); `count`, `remaining`, `strategy`, `lane` or `configKey` where they apply |
 | `improve_lock_recovered` | Stale improve lock cleared at startup | |
 | `improve_review_needed` | `akm feedback` pushed a high-utility asset's utility below the review threshold — a review-needed escalation is recorded (not a proposal, so it can't accidentally overwrite the asset) | `ref`, `previousUtility`, `nextUtility` |
 | `reflect_invoked` | Start of reflect phase in `akm improve` | `ref`, engine |
@@ -222,17 +223,20 @@ the set of types the code actually emits at HEAD (verified against every
 
 | Event type | When emitted | Key metadata fields |
 |---|---|---|
-| `llm_usage` | Per-attempt LLM call usage telemetry (#576) | model provenance, terminal outcome, duration, optional token usage |
-| `llm_usage_summary` | The owning LLM telemetry sink's terminal-record count marker | `expectedTerminalRecords` |
+| `llm_usage` | Per-attempt LLM call usage telemetry (#576), written by every akm command that makes an LLM call (`index`, `curate`, workflows, agent dispatch, `command run`, `improve`, `proposal drain`) | model provenance, terminal outcome, duration, optional token usage |
+| `llm_usage_summary` | The owning LLM telemetry sink's terminal-record count marker. The process-wide sink that covers commands other than `improve` writes none when it saw no call | `expectedTerminalRecords` |
 | `health_probe` | `akm health`'s state.db round-trip write/read probe. **Not durably retained**: the row is inserted then deleted within the same connection once the round trip is confirmed, so the net effect on the `events` table is always zero rows | n/a (ephemeral) |
 
 `llm_usage` rows also carry `process`/`engine`/`stage` (each optional; a call
 made outside any attributed scope carries none of them). `akm improve`
-(#944) aggregates a run's own `llm_usage` events into a process x engine x
-model cross-tab — `summarizeLlmUsageCrossTab` in `src/commands/health/llm-usage.ts`
-— persisted on the run result as `usageReport.byProcessEngineModel` and
-queryable per-run or aggregated with `akm improve report`; see
-`docs/reference/cli.md`'s `#### improve report` section.
+(#944) builds a process x engine x model cross-tab from the LLM call records
+the run's own usage sink collects — `summarizeLlmUsageRecordsCrossTab` in
+`src/commands/health/llm-usage.ts` — persisted on the run result as
+`usageReport.byProcessEngineModel` and queryable per-run or aggregated with
+`akm improve report`; see `docs/reference/cli.md`'s `#### improve report`
+section. `summarizeLlmUsageCrossTab` is the events form of the same
+aggregation, used by `improve report` to recompute the cross-tab from stored
+`llm_usage` events when a run has no persisted `usageReport`.
 
 ### 2. Usage Events Table
 
@@ -248,6 +252,12 @@ configured endpoint.
 Successful `search`, `curate`, and `show` commands always record usage. Machine
 reads are stamped by source (below), so they never skew ranking or eval.
 
+The `search` summary row (the one with no `entry_ref`) carries `resultCount`,
+`stashHitCount`, `registryHitCount`, `resolvedCount` and `mode` in its metadata,
+plus latency for `akm metrics`: `totalMs` for the whole search, and `rankMs` and
+`embedMs` for the ranking and query-embedding phases when the local search
+reported them (a registry-only search has `totalMs` alone).
+
 Every runtime writer stamps provenance as `user`, `improve`, `task`, `audit`, or
 `unknown`. Direct interactive CLI traffic defaults to `user`; internal improve,
 scheduled-task, and eval subprocesses preserve their stamp across nested
@@ -279,6 +289,19 @@ higher-priority-wins `(type, entry.name)` dedup across sources: attribution
 source-qualifies every indexed row but does not invent a lower-priority row for
 an identity that production indexing omitted.
 
+**Retention:** usage events older than 90 days are purged on every `akm index`.
+`created_at` is `YYYY-MM-DD HH:MM:SS` in UTC (SQLite `datetime('now')`), not
+ISO 8601, so time bounds compare `datetime(created_at)` with the bound rather
+than the raw text.
+
+`akm metrics` is the read surface for this table: it aggregates the rows of a
+window into per-asset usage, queries (including searches that returned nothing),
+feedback, and daily series, and `--format html` carries the window's rows in the
+page so they can be filtered and exported in the browser. It reads
+`usage_events`, the `select` events, `utility_scores`, `asset_outcome`,
+`proposals`, the workflow tables, and `llm_usage` events, and writes nothing.
+A window longer than a store's retention is reported in the result's `notes`.
+
 ### 3. Proposals Table
 
 The proposal queue: pending, accepted, rejected, and reverted improvement proposals for your bundle assets. Generated by `akm improve`, `akm proposal new`, and related proposal-producing flows.
@@ -311,6 +334,16 @@ A record of scheduled task runs (from `akm task`):
 
 ## How to Inspect and Clear Local Data
 
+### Report on usage
+
+```sh
+# What was searched, shown and rated in the last 30 days
+akm metrics
+
+# A dashboard you can open from disk
+akm metrics --format html --output metrics.html
+```
+
 ### Inspect events
 
 ```sh

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.9.27",
+  "version": "0.9.28-alpha.2",
   "type": "module",
   "description": "akm (Agent Knowledge Manager) — a portable, local-first capability library for AI agents. Discover, load, share, and improve reusable skills, scripts, workflows, and knowledge across any shell-capable coding agent, including Claude Code, OpenCode, and Cursor.",
   "keywords": [