diff --git a/.gitignore b/.gitignore
index 60ef949c1e..1779ca803a 100644
--- a/.gitignore
+++ b/.gitignore
@@ -48,6 +48,8 @@ notebooks
 tmp/appmap
 packages/*/tmp/
 packages/cli/tests/unit/fixtures/malformedParentId/parent_id_49_does_not_exist/
+# Gradle test fixtures regenerate their build/ trees on every run.
+packages/cli/tests/unit/fixtures/java/**/build/
 *.appmap.json
 .navie
 .run-stats
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000000..ad1b28229a
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,39 @@
+# Verifying changes
+
+This is a Yarn 3 monorepo (`packages/*`). CI rejects pushes for both lint errors and tsc errors, with several-minute round-trip costs per CI run. Verify locally before committing.
+
+## When to run verify
+
+After any **substantial batch of changes** — multiple files touched, new functions added, tests added, refactors — run `yarn verify` from the repo root before reporting work complete or asking to commit. A one-line typo fix doesn't need it; a multi-file change does.
+
+## How to run verify
+
+```sh
+yarn verify           # check working-tree changes (staged + unstaged + untracked)
+yarn verify:staged    # check only staged changes
+```
+
+`scripts/verify.mjs`:
+
+1. Reads modified files from git.
+2. Groups them by `packages/<name>/`.
+3. For each affected package: runs ESLint (`--quiet`, errors only) on the changed lintable files, then `tsc --noEmit` on the whole package (since TS is project-wide, you can't typecheck a single file).
+
+Typical run on one package: ~5–7s. CI's full lint+typecheck takes ~30s; scoped is ~3× faster.
+
+## Adding verify to a package
+
+If you touch a package that doesn't yet participate, add a `typecheck` script (`tsc --noEmit`) to its `package.json` so `verify.mjs` includes it. The existing `lint` script is enough for ESLint coverage.
+
+## What verify catches
+
+- ESLint errors that CI rejects: `array-type` (use `T[]` not `Array<T>`), `no-unnecessary-type-assertion`, `prefer-function-type`, `prefer-optional-chain`, etc. Warnings (e.g. `no-unsafe-*`, `prefer-nullish-coalescing`) are suppressed by `--quiet`.
+- Type errors that `tsc --noEmit` finds, including yargs `CommandModule<T, any>` assignability issues that require widening exported handler argv types.
+
+# Driving the MCP after MCP-side changes
+
+The `appmap query mcp` server lives in `built/cli.js`. If you change anything under `packages/cli/src/cmds/query/queries/mcp.ts` (or anywhere it transitively imports), you must run `npx tsc` (or `yarn build`) inside `packages/cli` before launching `mcp` for ad-hoc testing. A stale binary will respond to `tools/list` with the old surface — symptom is usually `unknown tool: …` from a client driving a tool the source defines.
+
+# Recording with appmap-node from a monorepo
+
+`npx appmap-node@latest npx jest …` invoked from the repo root can fail to parse `.ts` test files with a babel SyntaxError, because the inner jest doesn't pick up `packages/<name>/jest.config.js`'s `ts-jest` preset. Run from the package directory whose preset matters — e.g. `cd packages/cli && npx appmap-node@latest npx jest …`.
diff --git a/package.json b/package.json
index 8b0e76759d..92d534e07b 100644
--- a/package.json
+++ b/package.json
@@ -6,6 +6,8 @@
   ],
   "scripts": {
     "lint": "yarn workspaces foreach --exclude root -v run lint",
+    "verify": "node scripts/verify.mjs",
+    "verify:staged": "node scripts/verify.mjs --staged",
     "test": "yarn workspaces foreach --exclude '{root}' -v run test",
     "build": "yarn workspaces foreach -t --exclude root -v run build",
     "build-native": "yarn workspaces foreach -t --exclude root -v run build-native",
diff --git a/packages/cli/.eslintrc.cjs b/packages/cli/.eslintrc.cjs
index cbaab0be01..1ee54c49e9 100644
--- a/packages/cli/.eslintrc.cjs
+++ b/packages/cli/.eslintrc.cjs
@@ -22,7 +22,13 @@ const FIXME = [
 module.exports = {
   root: true,
   ignorePatterns: [
-    'src/telemetry.ts', // symlink to a separate "package"
+    '.eslintrc.cjs',     // self — type-aware parser doesn't include this file in tsconfig.lint
+    'src/telemetry.ts',  // symlink to a separate "package"
+    // The query-ui React app has its own toolchain (esbuild + tailwind);
+    // the main cli ESLint/TS setup doesn't ship React types and treats
+    // src/html as build-only, matching how src/html/{appmap,navie}.js are
+    // already handled.
+    'src/html/query-ui/**',
   ],
   env: {
     browser: true,
diff --git a/packages/cli/esbuild.html.ts b/packages/cli/esbuild.html.ts
index 0dc15236c2..4aa981ba52 100644
--- a/packages/cli/esbuild.html.ts
+++ b/packages/cli/esbuild.html.ts
@@ -110,3 +110,123 @@ esbuild
     console.warn(err);
     process.exit(1);
   });
+
+// Query UI React SPA — main app shell.
+//
+// Output goes under `built/html/query-ui/` so the cli's `query ui` verb
+// can serve it (`packages/cli/src/cmds/query/lib/uiServer.ts` looks
+// there). Tailwind CSS is built separately by `build:ui:css` and lands
+// at `built/html/query-ui/tailwind.css`, referenced from the inline
+// HTML template below.
+esbuild
+  .build({
+    minify: true,
+    sourcemap: true,
+    target: 'es2021',
+    metafile: true,
+    outdir: 'built/html/query-ui',
+    bundle: true,
+    logLevel: 'info',
+    define: {
+      'process.env': '{}',
+      'process.env.NODE_ENV': '"production"',
+      global: 'window',
+    },
+    loader: { '.ts': 'tsx', '.tsx': 'tsx' },
+    entryPoints: ['src/html/query-ui/src/main.tsx'],
+    plugins: [
+      htmlPlugin({
+        files: [
+          {
+            entryPoints: ['src/html/query-ui/src/main.tsx'],
+            filename: 'index.html',
+            htmlTemplate: `<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>AppMap Query UI</title>
+    <link rel="stylesheet" href="./tailwind.css" />
+  </head>
+  <body class="bg-gray-950 text-gray-100">
+    <div id="root"></div>
+  </body>
+</html>`,
+          },
+        ],
+      }),
+    ],
+  })
+  .catch((err) => {
+    console.warn(err);
+    process.exit(1);
+  });
+
+// Query UI — embedded AppMap viewer.
+//
+// Vue 2 + @appland/components mount that the React detail page loads
+// via <iframe src="/viewer.html?appmap=…">. Same alias setup as the
+// other Vue-based viewers (appmap.html, sequenceDiagram.html).
+//
+// The banner installs a `process` shim before the bundle runs because
+// transitive deps (e.g. @appland/telemetry's deprecation logger) make
+// unguarded `process.stderr.write(...)` calls. The other Vue bundles
+// carry the same code but just don't hit that codepath in normal use;
+// loadData() in the dashboard's iframe path does.
+esbuild
+  .build({
+    minify: true,
+    sourcemap: true,
+    target: 'es2021',
+    metafile: true,
+    outdir: 'built/html/query-ui',
+    bundle: true,
+    logLevel: 'info',
+    define: {
+      'process.env': '{}',
+      'process.env.NODE_ENV': '"production"',
+      global: 'window',
+    },
+    banner: {
+      js: 'window.process=window.process||{env:{},stderr:{write:function(){}},stdout:{write:function(){}},platform:"browser",version:""};',
+    },
+    alias: {
+      http: require.resolve('stream-http'),
+      https: require.resolve('https-browserify'),
+    },
+    entryPoints: ['src/html/query-ui/src/viewer.ts'],
+    plugins: [
+      htmlPlugin({
+        files: [
+          {
+            entryPoints: ['src/html/query-ui/src/viewer.ts'],
+            filename: 'viewer.html',
+            htmlTemplate: `<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>AppMap Viewer</title>
+    <style>
+      * { margin: 0; padding: 0; box-sizing: border-box; }
+      html, body, #viewer { width: 100%; height: 100%; overflow: hidden; }
+      body { background: #0a0a0f; color: #e5e7eb; font-family: system-ui, sans-serif; }
+      #loading { display: flex; align-items: center; justify-content: center; height: 100%; color: #6b7280; }
+      #error { display: none; padding: 2rem; color: #ef4444; }
+    </style>
+  </head>
+  <body>
+    <div id="loading">Loading AppMap...</div>
+    <div id="error"></div>
+    <div id="viewer"></div>
+  </body>
+</html>`,
+          },
+        ],
+      }),
+    ],
+  })
+  .catch((err) => {
+    console.warn(err);
+    process.exit(1);
+  });
diff --git a/packages/cli/package.json b/packages/cli/package.json
index 62270c6a22..5a8f4f80e7 100644
--- a/packages/cli/package.json
+++ b/packages/cli/package.json
@@ -16,12 +16,15 @@
   "scripts": {
     "lint": "eslint src tests",
     "lint:fix": "eslint src tests --fix",
+    "typecheck": "tsc --noEmit",
+    "verify": "yarn lint && yarn typecheck",
     "pre-commit": "lint-staged",
     "test": "jest --filter=./tests/testFilter.js",
     "test:binary": "jest -c tests/binary/jest.config.js",
-    "build": "tsc && yarn build:html && yarn build:doc",
+    "build": "tsc && yarn build:html && yarn build:ui:css && yarn build:doc",
     "watch": "tsc --watch",
     "build:html": "ts-node esbuild.html.ts",
+    "build:ui:css": "tailwindcss -i src/html/query-ui/index.css -o built/html/query-ui/tailwind.css --config src/html/query-ui/tailwind.config.js --minify",
     "build:doc": "rsync -av --delete ../../docs built/ && rm -f built/docs/reference/appmap-agent-js.md",
     "start": "ts-node src/cli.ts",
     "build-native": "yarn build && ./bin/build-native"
@@ -51,6 +54,8 @@
     "@types/moo": "^0.5.5",
     "@types/node": "^16",
     "@types/proper-lockfile": "^4.1.4",
+    "@types/react": "^18.3.0",
+    "@types/react-dom": "^18.3.0",
     "@types/semver": "^7.3.10",
     "@types/sinon": "^10.0.2",
     "@types/tmp": "^0.2.3",
@@ -71,8 +76,12 @@
     "node-fetch": "2.6.7",
     "pkg": "5.8.1-patched",
     "prettier": "^2.7.1",
+    "react": "^18.3.0",
+    "react-dom": "^18.3.0",
+    "react-router-dom": "^6.26.0",
     "sinon": "^11.1.2",
     "stream-http": "^3.2.0",
+    "tailwindcss": "^3.4.0",
     "tmp": "^0.2.1",
     "tmp-promise": "^3.0.3",
     "ts-jest": "^29.0.5",
diff --git a/packages/cli/scripts/demo-query.sh b/packages/cli/scripts/demo-query.sh
new file mode 100755
index 0000000000..6c1d189631
--- /dev/null
+++ b/packages/cli/scripts/demo-query.sh
@@ -0,0 +1,103 @@
+#!/usr/bin/env bash
+#
+# Quick demo of the `appmap query` verbs against a fixture set.
+#
+# Usage:
+#   ./scripts/demo-query.sh                       # uses appmap-apm fixtures if present,
+#                                                 #   else bundled ruby fixtures
+#   ./scripts/demo-query.sh /path/to/your/appmaps # any directory of *.appmap.json files
+#
+# Side effects: copies the fixture set to a temp dir, builds and imports a
+# query.db there, leaves the originals untouched. Cleans up on exit.
+
+set -euo pipefail
+
+cd "$(dirname "$0")/.."   # → packages/cli
+
+# Pick the richest fixture set available.
+DEFAULT="$HOME/source/appland/appmap-apm/tests/fixtures/tmp/appmap"
+[ -d "$DEFAULT" ] || DEFAULT="$(pwd)/tests/unit/fixtures/ruby"
+SRC="${1:-$DEFAULT}"
+[ -d "$SRC" ] || { echo "fixture dir not found: $SRC" >&2; exit 2; }
+
+# Temp work area: copy the fixtures so `appmap index` can write fingerprint
+# sidecars without touching the originals.
+TMP="$(mktemp -d -t appmap-demo)"
+DATA="$TMP/data"
+DB="$TMP/query.db"
+mkdir -p "$DATA"
+cp -r "$SRC"/. "$DATA"/
+export NODE_NO_WARNINGS=1
+trap 'rm -rf "$TMP"' EXIT
+
+CLI=( node "$(pwd)/built/cli.js" )
+
+echo "Building CLI…" >&2
+npx tsc 2>&1 | grep -v 'navie-local' >&2 || true
+
+# Filter out diagnostic noise from @appland/models that the verbs themselves
+# don't emit (kept loose so we don't suppress real errors).
+NOISE='\[DEBUG '
+
+banner() {
+  echo
+  echo "── \$ appmap $*"
+}
+run() {
+  banner "$@"
+  "${CLI[@]}" "$@" 2>&1 | grep -vE "$NOISE" || true
+}
+run_quiet() {
+  banner "$@"
+  "${CLI[@]}" "$@" 2>&1 | grep -vE "$NOISE" | tail -5 || true
+}
+
+cat <<HEAD
+Source : $SRC
+Query DB : $DB
+HEAD
+
+# Build the query DB. The index command itself is noisy (one line per file
+# plus diagnostics from @appland/models) — the demo cares about the verbs,
+# not the indexer, so we silence index output and report a row count.
+echo
+echo "── \$ appmap index --appmap-dir <DATA> --query-db <QUERY_DB>"
+"${CLI[@]}" index --appmap-dir "$DATA" --query-db "$DB" >/dev/null 2>&1
+COUNT=$(node -e "
+  const db = require('better-sqlite3')('$DB', { readonly: true });
+  process.stdout.write(String(db.prepare('SELECT COUNT(*) AS n FROM appmaps').get().n));
+")
+echo "indexed $COUNT recordings"
+
+run query endpoints --query-db "$DB" --sort p95 --limit 5
+run query find queries --query-db "$DB" --table users --limit 3 || true
+run query find exceptions --query-db "$DB" --limit 5 || true
+run query hotspots --query-db "$DB" --limit 5
+run query hotspots --query-db "$DB" --type=sql --limit 3
+
+# related: find passing baselines for a recording (with whatever data exists)
+RELATED_SOURCE="$(node -e "
+  const db = require('better-sqlite3')('$DB', { readonly: true });
+  const r = db.prepare(\"SELECT name FROM appmaps WHERE name LIKE '%oups%' LIMIT 1\").get();
+  process.stdout.write(r ? r.name : '');
+")"
+if [ -n "$RELATED_SOURCE" ]; then
+  run query related "$RELATED_SOURCE" --query-db "$DB" --limit 5
+fi
+
+# Pick the recording with the most events for the tree demos.
+APPMAP="$(node -e "
+  const db = require('better-sqlite3')('$DB', { readonly: true });
+  const r = db.prepare(
+    'SELECT name FROM appmaps WHERE event_count > 0 ORDER BY event_count DESC LIMIT 1'
+  ).get();
+  process.stdout.write(r ? r.name : '');
+")"
+
+if [ -n "$APPMAP" ]; then
+  run query tree "$APPMAP" --query-db "$DB" --format=summary
+  run query tree "$APPMAP" --query-db "$DB" --filter=sql
+fi
+
+echo
+echo "Done."
diff --git a/packages/cli/src/cli.ts b/packages/cli/src/cli.ts
index 630ad5edb1..fe4a3b69fe 100755
--- a/packages/cli/src/cli.ts
+++ b/packages/cli/src/cli.ts
@@ -40,6 +40,7 @@ import * as RpcCommand from './cmds/index/rpc';
 import * as RpcClientCommand from './cmds/rpcClient';
 import * as NavieCommand from './cmds/navie';
 import * as ApplyCommand from './cmds/apply';
+import * as QueryCommand from './cmds/query/query';
 import * as RunTestCommand from './cmds/runTest';
 import TelemetryTestCommand from './cmds/testTelemetry';
 import { default as sqlErrorLog } from './lib/sqlErrorLog';
@@ -156,6 +157,7 @@ yargs(process.argv.slice(2))
   .command(RpcClientCommand)
   .command(NavieCommand)
   .command(ApplyCommand)
+  .command(QueryCommand)
   .command(RunTestCommand)
   .command(TelemetryTestCommand)
   .option('verbose', {
diff --git a/packages/cli/src/cmds/index/index.ts b/packages/cli/src/cmds/index/index.ts
index 4621bdf44a..77abf4e022 100644
--- a/packages/cli/src/cmds/index/index.ts
+++ b/packages/cli/src/cmds/index/index.ts
@@ -10,6 +10,8 @@ import { configureRpcDirectories, handleWorkingDirectory } from '../../lib/handl
 import { locateAppMapDir } from '../../lib/locateAppMapDir';
 import { verbose } from '../../utils';
 import { log, warn } from 'console';
+import { openQueryDb } from '../query/db';
+import { QueryDbIndexer } from '../query/db/import/QueryDbIndexer';
 import { numProcessed } from '../../rpc/index/numProcessed';
 import { search } from '../../rpc/search/search';
 import appmapFilter from '../../rpc/appmap/filter';
@@ -51,6 +53,10 @@ export const builder = (args: yargs.Argv) => {
     type: 'number',
     alias: 'p',
   });
+  args.option('query-db', {
+    describe: 'path to query.db (overrides default ~/.appmap/data/<sha>/query.db)',
+    type: 'string',
+  });
   args.option('navie-provider', {
     describe: 'navie provider to use',
     type: 'string',
@@ -78,11 +84,19 @@ export const handler = async (argv) => {
   const runServer = watch || port !== undefined;
   if (port && !watch) warn(`Note: --port option implies --watch`);
 
+  const queryDb = openQueryDb(appmapDir, argv.queryDb as string | undefined);
+  const indexer = new QueryDbIndexer(queryDb.db);
+  log(
+    `Query DB at ${queryDb.path} (schema v${queryDb.version}${
+      queryDb.rebuilt ? ', rebuilt' : ''
+    })`
+  );
+
   if (runServer) {
     void checkLicense(false);
 
     log(`Running indexer in watch mode`);
-    const cmd = new FingerprintWatchCommand(appmapDir);
+    const cmd = new FingerprintWatchCommand(appmapDir, indexer);
     await cmd.execute();
 
     if (port !== undefined) {
@@ -149,7 +163,8 @@ export const handler = async (argv) => {
       }
     }
   } else {
-    const cmd = new FingerprintDirectoryCommand(appmapDir);
+    const cmd = new FingerprintDirectoryCommand(appmapDir, indexer);
     await cmd.execute();
+    indexer.close();
   }
 };
diff --git a/packages/cli/src/cmds/query/db/import/QueryDbIndexer.ts b/packages/cli/src/cmds/query/db/import/QueryDbIndexer.ts
new file mode 100644
index 0000000000..8977ee1f23
--- /dev/null
+++ b/packages/cli/src/cmds/query/db/import/QueryDbIndexer.ts
@@ -0,0 +1,69 @@
+import { resolve } from 'path';
+
+import sqlite3 from 'better-sqlite3';
+
+import { findFiles } from '../../../../utils';
+import { deleteAppmap, importAppmap } from './importAppmap';
+
+// Subscribes to fingerprint pipeline events and routes per-file work into
+// the query DB. Owns no policy beyond "import on index, delete on unlink";
+// callers wire it up to whichever queue/watcher fits the command shape.
+//
+// Failure handling: per-file errors (bad JSON, missing fields) are logged
+// and skipped; the walk does not abort. DB-level errors still propagate —
+// those indicate a real bug, not bad data.
+
+interface IndexEmitter {
+  on(event: 'index', listener: (ev: { path: string }) => void): unknown;
+}
+
+export class QueryDbIndexer {
+  private imported = 0;
+  private failed = 0;
+
+  constructor(private readonly db: sqlite3.Database) {}
+
+  // Subscribe to a FingerprintQueue (or anything matching its 'index' event
+  // shape) so each successfully fingerprinted file is also imported.
+  attach(queue: IndexEmitter): void {
+    queue.on('index', (ev) => this.onIndexed(ev.path));
+  }
+
+  // Walk a directory and import any .appmap.json that doesn't already have
+  // a row in the appmaps table. Bridges the gap when query.db is fresh but
+  // fingerprints already exist (so the fingerprinter skips them and never
+  // emits an 'index' event for the importer to catch).
+  async syncDirectory(directory: string): Promise<void> {
+    const present = this.db.prepare('SELECT 1 FROM appmaps WHERE source_path = ?');
+    await findFiles(directory, '.appmap.json', (file) => {
+      const absolutePath = resolve(file);
+      if (!present.get(absolutePath)) this.onIndexed(absolutePath);
+    });
+  }
+
+  onIndexed(file: string): void {
+    try {
+      importAppmap(this.db, file);
+      this.imported += 1;
+    } catch (err) {
+      this.failed += 1;
+      console.warn(`query db: failed to import ${file}: ${(err as Error).message}`);
+    }
+  }
+
+  onRemoved(file: string): void {
+    try {
+      deleteAppmap(this.db, file);
+    } catch (err) {
+      console.warn(`query db: failed to delete ${file}: ${(err as Error).message}`);
+    }
+  }
+
+  stats(): { imported: number; failed: number } {
+    return { imported: this.imported, failed: this.failed };
+  }
+
+  close(): void {
+    this.db.close();
+  }
+}
diff --git a/packages/cli/src/cmds/query/db/import/appmapRecord.ts b/packages/cli/src/cmds/query/db/import/appmapRecord.ts
new file mode 100644
index 0000000000..77ad40de59
--- /dev/null
+++ b/packages/cli/src/cmds/query/db/import/appmapRecord.ts
@@ -0,0 +1,98 @@
+import { statSync } from 'fs';
+import { basename } from 'path';
+
+import sqlite3 from 'better-sqlite3';
+
+export interface AppmapMetadata {
+  name?: string;
+  language?: { name?: string };
+  frameworks?: { name?: string }[];
+  recorder?: { type?: string };
+  git?: { repository?: string; branch?: string; commit?: string };
+  timestamp?: number;
+  labels?: unknown;
+}
+
+export interface ParsedAppmap {
+  events?: Record<string, unknown>[];
+  metadata?: AppmapMetadata;
+  classMap?: unknown;
+}
+
+export interface AppmapRecordResult {
+  appmapId: number;
+  timestampIso: string;
+}
+
+// Insert the top-level appmaps row and return its id and resolved timestamp.
+//
+// Total elapsed is taken from the first return event carrying an
+// http_server_response. If metadata.timestamp is missing, falls back to the
+// file's mtime so time-range queries still work.
+export function insertAppmapRecord(
+  db: sqlite3.Database,
+  absolutePath: string,
+  appmap: ParsedAppmap
+): AppmapRecordResult {
+  const events = appmap.events ?? [];
+  const metadata = appmap.metadata ?? {};
+
+  let totalElapsedMs: number | null = null;
+  for (const ev of events) {
+    if (ev.event === 'return' && 'http_server_response' in ev) {
+      const elapsed = ev.elapsed;
+      if (typeof elapsed === 'number') totalElapsedMs = elapsed * 1000;
+      break;
+    }
+  }
+
+  let sqlQueryCount = 0;
+  let httpRequestCount = 0;
+  for (const ev of events) {
+    if ('sql_query' in ev) sqlQueryCount += 1;
+    if ('http_server_request' in ev) httpRequestCount += 1;
+  }
+
+  const language = metadata.language?.name ?? null;
+  const framework = metadata.frameworks?.[0]?.name ?? null;
+  const recorderType = metadata.recorder?.type ?? null;
+  const git = metadata.git ?? {};
+
+  let timestampIso: string;
+  if (typeof metadata.timestamp === 'number') {
+    timestampIso = new Date(metadata.timestamp * 1000).toISOString();
+  } else {
+    timestampIso = statSync(absolutePath).mtime.toISOString();
+  }
+
+  const labels = metadata.labels;
+  const metadataLabelsJson = labels ? JSON.stringify(labels) : null;
+  const name = metadata.name ?? basename(absolutePath);
+
+  const info = db
+    .prepare(
+      `INSERT INTO appmaps (name, source_path, language, framework, recorder_type,
+        git_repository, git_branch, git_commit, timestamp,
+        event_count, sql_query_count, http_request_count, elapsed_ms,
+        metadata_labels)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
+    )
+    .run(
+      name,
+      absolutePath,
+      language,
+      framework,
+      recorderType,
+      git.repository ?? null,
+      git.branch ?? null,
+      git.commit ?? null,
+      timestampIso,
+      events.length,
+      sqlQueryCount,
+      httpRequestCount,
+      totalElapsedMs,
+      metadataLabelsJson
+    );
+
+  return { appmapId: Number(info.lastInsertRowid), timestampIso };
+}
diff --git a/packages/cli/src/cmds/query/db/import/codeObjects.ts b/packages/cli/src/cmds/query/db/import/codeObjects.ts
new file mode 100644
index 0000000000..b93689e4c1
--- /dev/null
+++ b/packages/cli/src/cmds/query/db/import/codeObjects.ts
@@ -0,0 +1,123 @@
+import sqlite3 from 'better-sqlite3';
+
+import type { CodeObjectType, Label } from '@appland/models';
+
+// Minimal classMap node shape used by the walk. Stays loose to avoid
+// coupling to @appland/models per V3 ("no @appland/models for ingestion");
+// only leaf type names are imported (type-only).
+export interface ClassMapNode {
+  type?: CodeObjectType;
+  name?: string;
+  static?: boolean;
+  location?: string;
+  labels?: Label[];
+  children?: ClassMapNode[];
+}
+
+// Walk the classMap tree, insert one code_objects row per function node,
+// insert its labels, and return a map of "{location}|{method}" →
+// code_object_id. The method component disambiguates classMap entries
+// that share a path:lineno (e.g. Spring Data proxy methods), preventing
+// the function_calls linker from binding events to the wrong code_object.
+//
+// Each function is decomposed into:
+//   - package : slash-joined package path  (e.g. "app/services/idempotency")
+//   - class   : ::-joined class chain      (e.g. "Outer::Inner")
+//   - method  : leaf method name           (e.g. "generate")
+//   - is_static : 1 for static, 0 for instance
+//
+// fqid is derived from these and matches @appland/models' codeObjectId.js:
+//   - between package and class:           '/'
+//   - between class and child class:       '::'
+//   - between class and function method:   '.' (static) or '#' (instance)
+//
+// Behavior preserved from the Python prototype:
+//   - Function node names with an auxtype suffix like " (get)" are trimmed.
+//   - Functions without a location are skipped (e.g., C-extensions).
+//   - When descending from a package, the class chain resets (a class
+//     directly under a package starts a fresh chain).
+export function importCodeObjects(
+  db: sqlite3.Database,
+  classMap: readonly ClassMapNode[]
+): Map<string, number> {
+  const lookup = new Map<string, number>();
+
+  const insertCodeObject = db.prepare(
+    `INSERT OR IGNORE INTO code_objects (fqid, package, classes, leaf_class, method, is_static)
+     VALUES (?, ?, ?, ?, ?, ?)`
+  );
+  const selectCodeObjectId = db.prepare(`SELECT id FROM code_objects WHERE fqid = ?`);
+  const insertLabel = db.prepare(
+    `INSERT OR IGNORE INTO labels (code_object_id, label) VALUES (?, ?)`
+  );
+
+  function buildFqid(
+    packageTokens: readonly string[],
+    classTokens: readonly string[],
+    method: string,
+    isStatic: boolean
+  ): string {
+    const pkg = packageTokens.join('/');
+    const cls = classTokens.join('::');
+    const methodSep = isStatic ? '.' : '#';
+    if (pkg && cls) return `${pkg}/${cls}${methodSep}${method}`;
+    if (pkg) return `${pkg}${methodSep}${method}`;
+    if (cls) return `${cls}${methodSep}${method}`;
+    return `${methodSep}${method}`;
+  }
+
+  function walk(
+    node: ClassMapNode,
+    packageTokens: readonly string[],
+    classTokens: readonly string[]
+  ): void {
+    const nodeType = node.type;
+    const name = node.name ?? '';
+
+    if (nodeType === 'function') {
+      const location = node.location;
+      if (!location) return;
+
+      const parenIdx = name.indexOf(' (');
+      const methodName = parenIdx >= 0 ? name.slice(0, parenIdx) : name;
+      const isStatic = !!node.static;
+
+      const fqid = buildFqid(packageTokens, classTokens, methodName, isStatic);
+
+      const leafClass = classTokens.length > 0 ? classTokens[classTokens.length - 1] : '';
+      insertCodeObject.run(
+        fqid,
+        packageTokens.join('/'),
+        JSON.stringify([...classTokens]),
+        leafClass,
+        methodName,
+        isStatic ? 1 : 0
+      );
+      const row = selectCodeObjectId.get(fqid) as { id: number };
+      // Key includes the method name so multiple functions sharing a
+      // path:lineno (e.g. Spring Data proxy methods) each map to their
+      // own code_object instead of clobbering one another.
+      lookup.set(`${location}|${methodName}`, row.id);
+
+      const labels = node.labels ?? [];
+      for (const label of labels) insertLabel.run(row.id, label);
+      return;
+    }
+
+    let nextPackageTokens = packageTokens;
+    let nextClassTokens = classTokens;
+    if (nodeType === 'package') {
+      nextPackageTokens = [...packageTokens, name];
+      nextClassTokens = []; // package descent resets the class chain
+    } else if (nodeType === 'class') {
+      nextClassTokens = [...classTokens, name];
+    }
+
+    const children = node.children ?? [];
+    for (const child of children) walk(child, nextPackageTokens, nextClassTokens);
+  }
+
+  for (const root of classMap) walk(root, [], []);
+
+  return lookup;
+}
diff --git a/packages/cli/src/cmds/query/db/import/exceptions.ts b/packages/cli/src/cmds/query/db/import/exceptions.ts
new file mode 100644
index 0000000000..aeab5cf1c9
--- /dev/null
+++ b/packages/cli/src/cmds/query/db/import/exceptions.ts
@@ -0,0 +1,85 @@
+import sqlite3 from 'better-sqlite3';
+
+import type { ExceptionObject } from '@appland/models';
+
+// Import exceptions into the exceptions table.
+//
+// In the AppMap event stream, `exceptions` lives on **return** events: the
+// return event terminates a call, and any thrown exception that propagated
+// is attached there. The row's `event_id` and `parent_event_id` should
+// describe the **call** the exception belongs to, not the return event:
+//
+//   - event_id        = call event id     (= ev.parent_id on the return)
+//   - parent_event_id = parent of that call in the per-thread stack
+//                       (= parentEventMap.get(callEventId))
+//
+// Some recorders also place `exceptions` directly on the call event itself.
+// We accept that legacy shape but de-dup against the canonical return-event
+// source: if a call id was already covered via its return event, we skip
+// the call-event source for the same id.
+export function importExceptions(
+  db: sqlite3.Database,
+  appmapId: number,
+  events: readonly Record<string, any>[],
+  parentEventMap: Map<number, number>
+): void {
+  const stmt = db.prepare(
+    `INSERT INTO exceptions (appmap_id, event_id, return_event_id, thread_id,
+      parent_event_id, exception_class, message, path, lineno)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`
+  );
+
+  const seenCallIds = new Set<number>();
+
+  // Pass 1: return events carrying exceptions (canonical case).
+  for (const ev of events) {
+    if (ev.event !== 'return') continue;
+    const excs = ev.exceptions as ExceptionObject[] | undefined;
+    if (!Array.isArray(excs)) continue;
+    if (typeof ev.parent_id !== 'number') continue;
+
+    const callEventId = ev.parent_id;
+    const returnEventId = typeof ev.id === 'number' ? ev.id : null;
+    seenCallIds.add(callEventId);
+    const parentEventId = parentEventMap.get(callEventId) ?? null;
+
+    for (const exc of excs) {
+      stmt.run(
+        appmapId,
+        callEventId,
+        returnEventId,
+        ev.thread_id ?? null,
+        parentEventId,
+        exc.class,
+        exc.message ?? null,
+        exc.path ?? null,
+        exc.lineno ?? null
+      );
+    }
+  }
+
+  // Pass 2: legacy shape — exceptions on a call event we didn't already cover.
+  // No paired return event in this shape, so return_event_id stays null.
+  for (const ev of events) {
+    if (ev.event !== 'call') continue;
+    const excs = ev.exceptions as ExceptionObject[] | undefined;
+    if (!Array.isArray(excs)) continue;
+    if (typeof ev.id !== 'number' || seenCallIds.has(ev.id)) continue;
+
+    const parentEventId = parentEventMap.get(ev.id) ?? null;
+
+    for (const exc of excs) {
+      stmt.run(
+        appmapId,
+        ev.id,
+        null,
+        ev.thread_id ?? null,
+        parentEventId,
+        exc.class,
+        exc.message ?? null,
+        exc.path ?? null,
+        exc.lineno ?? null
+      );
+    }
+  }
+}
diff --git a/packages/cli/src/cmds/query/db/import/functionCalls.ts b/packages/cli/src/cmds/query/db/import/functionCalls.ts
new file mode 100644
index 0000000000..293a422cb1
--- /dev/null
+++ b/packages/cli/src/cmds/query/db/import/functionCalls.ts
@@ -0,0 +1,83 @@
+import sqlite3 from 'better-sqlite3';
+
+import type { ReturnEventLike } from './returnEventMap';
+
+// Import function call events. Each event is linked to a code_object via
+// (path, lineno) → classMap location, and captures parameters + return
+// value for every call.
+export function importFunctionCalls(
+  db: sqlite3.Database,
+  appmapId: number,
+  events: readonly Record<string, any>[],
+  returnEvents: Map<number, ReturnEventLike>,
+  parentEventMap: Map<number, number>,
+  codeObjectLookup: Map<string, number>
+): void {
+  const stmt = db.prepare(
+    `INSERT INTO function_calls (appmap_id, event_id, thread_id, parent_event_id,
+      code_object_id, defined_class, method_id, path, lineno, is_static,
+      elapsed_ms, parameters_json, return_value)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
+  );
+
+  for (const ev of events) {
+    if (ev.event !== 'call') continue;
+    if (!ev.defined_class || !ev.method_id) continue;
+    if ('http_server_request' in ev || 'sql_query' in ev) continue;
+
+    const ret = returnEvents.get(ev.id) ?? {};
+    const elapsed = ret.elapsed;
+
+    let coId: number | null = null;
+    const evPath = ev.path;
+    const evLineno = ev.lineno;
+    if (evPath != null && evLineno != null) {
+      // Lookup key matches the importer's: "<path>:<lineno>|<method_id>".
+      // The method component disambiguates classMap entries that share
+      // a path:lineno, so two events at the same source location bind to
+      // their own code_object rather than colliding.
+      coId = codeObjectLookup.get(`${evPath}:${evLineno}|${ev.method_id}`) ?? null;
+    }
+
+    let paramsJson: string | null = null;
+    let returnVal: string | null = null;
+    // Parameters are captured for every call, labeled or not — symmetric
+    // with return_value below. For void methods params are the *only*
+    // runtime signal, and distinguishing sibling calls (e.g. updateStatus
+    // invoked with different newStatus args) needs them on plain,
+    // unlabeled domain code too. Storage keeps the full JSON; renderers
+    // apply a per-field budget when surfacing it compactly.
+    const params = ev.parameters;
+    if (Array.isArray(params) && params.length > 0) {
+      paramsJson = JSON.stringify(
+        params.map((p: any) => ({ name: p?.name, class: p?.class, value: p?.value }))
+      );
+    }
+    // Return values are captured for every call, labeled or not: one
+    // bounded string per call, and the highest-signal field for
+    // root-cause work — distinguishing sibling calls (e.g. two builders
+    // stamping different timestamps) needs the return values of plain,
+    // unlabeled domain code too.
+    const rv = (ret as any).return_value;
+    if (rv && typeof rv === 'object') {
+      const value = rv.value;
+      returnVal = value == null ? null : String(value);
+    }
+
+    stmt.run(
+      appmapId,
+      ev.id,
+      ev.thread_id ?? null,
+      parentEventMap.get(ev.id) ?? null,
+      coId,
+      ev.defined_class,
+      ev.method_id,
+      evPath ?? null,
+      evLineno ?? null,
+      ev.static ? 1 : 0,
+      typeof elapsed === 'number' ? elapsed * 1000 : null,
+      paramsJson,
+      returnVal
+    );
+  }
+}
diff --git a/packages/cli/src/cmds/query/db/import/httpClientRequests.ts b/packages/cli/src/cmds/query/db/import/httpClientRequests.ts
new file mode 100644
index 0000000000..4f338f00b3
--- /dev/null
+++ b/packages/cli/src/cmds/query/db/import/httpClientRequests.ts
@@ -0,0 +1,42 @@
+import sqlite3 from 'better-sqlite3';
+
+import type { HttpClientRequest, HttpClientResponse } from '@appland/models';
+
+import type { ReturnEventLike } from './returnEventMap';
+
+// Mirror httpRequests.ts: recordings carry a status_code field alongside
+// what @appland/models declares, and an empty {} when no return was emitted.
+type RawHttpClientResponse = Partial<HttpClientResponse> & { status_code?: number };
+
+export function importHttpClientRequests(
+  db: sqlite3.Database,
+  appmapId: number,
+  events: readonly Record<string, any>[],
+  returnEvents: Map<number, ReturnEventLike>,
+  parentEventMap: Map<number, number>
+): void {
+  const stmt = db.prepare(
+    `INSERT INTO http_client_requests (appmap_id, event_id, thread_id, parent_event_id,
+      method, url, status_code, elapsed_ms)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?)`
+  );
+
+  for (const ev of events) {
+    const req = ev.http_client_request as HttpClientRequest | undefined;
+    if (!req) continue;
+    const ret = returnEvents.get(ev.id) ?? {};
+    const resp = (ret.http_client_response ?? {}) as RawHttpClientResponse;
+    const elapsed = ret.elapsed;
+
+    stmt.run(
+      appmapId,
+      ev.id,
+      ev.thread_id ?? null,
+      parentEventMap.get(ev.id) ?? null,
+      req.request_method ?? 'GET',
+      req.url ?? '',
+      resp.status_code ?? null,
+      typeof elapsed === 'number' ? elapsed * 1000 : null
+    );
+  }
+}
diff --git a/packages/cli/src/cmds/query/db/import/httpRequests.ts b/packages/cli/src/cmds/query/db/import/httpRequests.ts
new file mode 100644
index 0000000000..b54a293a61
--- /dev/null
+++ b/packages/cli/src/cmds/query/db/import/httpRequests.ts
@@ -0,0 +1,51 @@
+import sqlite3 from 'better-sqlite3';
+
+import type { HttpServerRequest, HttpServerResponse } from '@appland/models';
+
+import type { ReturnEventLike } from './returnEventMap';
+
+// Some recorders carry status_code/mime_type alongside the @appland/models
+// HttpServerResponse fields, and we may also see an empty object when no
+// return event was emitted. Capture the JSON-as-found here without changing
+// the upstream type definitions.
+type RawHttpServerResponse = Partial<HttpServerResponse> & {
+  status_code?: number;
+  mime_type?: string;
+};
+
+export function importHttpRequests(
+  db: sqlite3.Database,
+  appmapId: number,
+  events: readonly Record<string, any>[],
+  returnEvents: Map<number, ReturnEventLike>,
+  parentEventMap: Map<number, number>
+): void {
+  const stmt = db.prepare(
+    `INSERT INTO http_requests (appmap_id, event_id, thread_id, parent_event_id,
+      method, path, normalized_path, protocol, status_code, mime_type,
+      elapsed_ms)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
+  );
+
+  for (const ev of events) {
+    const req = ev.http_server_request as HttpServerRequest | undefined;
+    if (!req) continue;
+    const ret = returnEvents.get(ev.id) ?? {};
+    const resp = (ret.http_server_response ?? {}) as RawHttpServerResponse;
+    const elapsed = ret.elapsed;
+
+    stmt.run(
+      appmapId,
+      ev.id,
+      ev.thread_id ?? null,
+      parentEventMap.get(ev.id) ?? null,
+      req.request_method,
+      req.path_info,
+      req.normalized_path_info ?? null,
+      req.protocol ?? null,
+      resp.status_code ?? 0,
+      resp.mime_type ?? null,
+      typeof elapsed === 'number' ? elapsed * 1000 : null
+    );
+  }
+}
diff --git a/packages/cli/src/cmds/query/db/import/importAppmap.ts b/packages/cli/src/cmds/query/db/import/importAppmap.ts
new file mode 100644
index 0000000000..47443c910e
--- /dev/null
+++ b/packages/cli/src/cmds/query/db/import/importAppmap.ts
@@ -0,0 +1,67 @@
+import { readFileSync } from 'fs';
+import { resolve } from 'path';
+
+import sqlite3 from 'better-sqlite3';
+
+import { insertAppmapRecord, ParsedAppmap } from './appmapRecord';
+import { importCodeObjects, ClassMapNode } from './codeObjects';
+import { importHttpRequests } from './httpRequests';
+import { importHttpClientRequests } from './httpClientRequests';
+import { importSqlQueries } from './sqlQueries';
+import { importFunctionCalls } from './functionCalls';
+import { importExceptions } from './exceptions';
+import { buildParentEventMap } from './parentEventMap';
+import { buildReturnEventMap } from './returnEventMap';
+
+export interface ImportResult {
+  appmapId: number;
+  eventCount: number;
+  sqlCount: number;
+  httpCount: number;
+}
+
+// Idempotency: existing rows for this source_path are dropped (FK cascade
+// clears child rows) before re-inserting. The whole import runs in one
+// transaction — partial state is never visible to readers.
+export function importAppmap(db: sqlite3.Database, filePath: string): ImportResult {
+  const absolutePath = resolve(filePath);
+  const raw = readFileSync(absolutePath, 'utf8');
+  const parsed = JSON.parse(raw) as ParsedAppmap & { classMap?: ClassMapNode[] };
+  const events = parsed.events ?? [];
+  const classMap = parsed.classMap ?? [];
+
+  const tx = db.transaction((): ImportResult => {
+    db.prepare('DELETE FROM appmaps WHERE source_path = ?').run(absolutePath);
+
+    const { appmapId } = insertAppmapRecord(db, absolutePath, parsed);
+    const codeObjectLookup = importCodeObjects(db, classMap);
+
+    const returnEvents = buildReturnEventMap(events);
+    const parentEventMap = buildParentEventMap(events);
+
+    importHttpRequests(db, appmapId, events, returnEvents, parentEventMap);
+    importHttpClientRequests(db, appmapId, events, returnEvents, parentEventMap);
+    importSqlQueries(db, appmapId, events, returnEvents, parentEventMap);
+    importFunctionCalls(db, appmapId, events, returnEvents, parentEventMap, codeObjectLookup);
+    importExceptions(db, appmapId, events, parentEventMap);
+
+    let sqlCount = 0;
+    let httpCount = 0;
+    for (const ev of events) {
+      if ('sql_query' in ev) sqlCount += 1;
+      if ('http_server_request' in ev) httpCount += 1;
+    }
+
+    return { appmapId, eventCount: events.length, sqlCount, httpCount };
+  });
+
+  return tx();
+}
+
+// Drop all rows for the given recording. ON DELETE CASCADE removes child
+// rows from http_requests, sql_queries, function_calls, exceptions, etc.
+export function deleteAppmap(db: sqlite3.Database, filePath: string): boolean {
+  const absolutePath = resolve(filePath);
+  const info = db.prepare('DELETE FROM appmaps WHERE source_path = ?').run(absolutePath);
+  return info.changes > 0;
+}
diff --git a/packages/cli/src/cmds/query/db/import/parentEventMap.ts b/packages/cli/src/cmds/query/db/import/parentEventMap.ts
new file mode 100644
index 0000000000..07c81c6d94
--- /dev/null
+++ b/packages/cli/src/cmds/query/db/import/parentEventMap.ts
@@ -0,0 +1,40 @@
+// Minimal shape of an AppMap event used during parent-link reconstruction.
+// We only inspect a few fields, so we keep this loose rather than coupling
+// to @appland/models.
+export interface AppMapEventLike {
+  id?: number;
+  thread_id?: number;
+  event?: string;
+}
+
+// Walk the event stream once and return a map of event_id → parent_event_id
+// using per-thread call stacks. Each 'call' event's parent is the top of its
+// thread's stack at the moment of the call; each 'return' pops the stack.
+//
+// Events with no thread_id or no id are skipped. Threads are independent:
+// events on different threads never become each other's parents.
+export function buildParentEventMap(events: readonly AppMapEventLike[]): Map<number, number> {
+  const parentMap = new Map<number, number>();
+  const threadStacks = new Map<number, number[]>();
+
+  for (const ev of events) {
+    const tid = ev.thread_id;
+    const eid = ev.id;
+    if (tid === undefined || eid === undefined) continue;
+
+    if (ev.event === 'call') {
+      let stack = threadStacks.get(tid);
+      if (!stack) {
+        stack = [];
+        threadStacks.set(tid, stack);
+      }
+      if (stack.length > 0) parentMap.set(eid, stack[stack.length - 1]);
+      stack.push(eid);
+    } else if (ev.event === 'return') {
+      const stack = threadStacks.get(tid);
+      if (stack && stack.length > 0) stack.pop();
+    }
+  }
+
+  return parentMap;
+}
diff --git a/packages/cli/src/cmds/query/db/import/parseLocation.ts b/packages/cli/src/cmds/query/db/import/parseLocation.ts
new file mode 100644
index 0000000000..0348ea9130
--- /dev/null
+++ b/packages/cli/src/cmds/query/db/import/parseLocation.ts
@@ -0,0 +1,26 @@
+// Parse a classMap location string into [path, lineno].
+//
+// Handles:
+//   "app/views.py:10"         → ["app/views.py", 10]
+//   "/abs/path/file.rb:511"   → ["/abs/path/file.rb", 511]
+//   "File.java:-1"            → ["File.java", -1]
+//   "OpenSSL::Cipher#decrypt" → [null, null]   (C-extension; no file)
+//   ""                        → [null, null]
+//
+// Splits on the rightmost ':' so paths containing colons (Windows drive
+// letters, namespaced classes) are handled correctly.
+export function parseLocation(location: string | undefined | null): [string | null, number | null] {
+  if (!location) return [null, null];
+
+  const idx = location.lastIndexOf(':');
+  if (idx <= 0) return [null, null];
+
+  const pathPart = location.slice(0, idx);
+  const linenoPart = location.slice(idx + 1);
+
+  if (linenoPart.length === 0) return [null, null];
+  // Integer parse — accept leading minus, reject anything non-numeric.
+  if (!/^-?\d+$/.test(linenoPart)) return [null, null];
+
+  return [pathPart, Number.parseInt(linenoPart, 10)];
+}
diff --git a/packages/cli/src/cmds/query/db/import/returnEventMap.ts b/packages/cli/src/cmds/query/db/import/returnEventMap.ts
new file mode 100644
index 0000000000..fa9ca7c8db
--- /dev/null
+++ b/packages/cli/src/cmds/query/db/import/returnEventMap.ts
@@ -0,0 +1,26 @@
+// Index return events by their associated call event id, so call events can
+// look up their elapsed time + return-specific payload (http_server_response,
+// http_client_response, return_value).
+//
+// In the AppMap event stream, each return event carries `parent_id` pointing
+// at the id of the call event it terminates.
+export interface ReturnEventLike {
+  event?: string;
+  parent_id?: number;
+  elapsed?: number;
+  http_server_response?: Record<string, unknown>;
+  http_client_response?: Record<string, unknown>;
+  return_value?: Record<string, unknown>;
+}
+
+export function buildReturnEventMap(
+  events: readonly ReturnEventLike[]
+): Map<number, ReturnEventLike> {
+  const map = new Map<number, ReturnEventLike>();
+  for (const ev of events) {
+    if (ev.event === 'return' && typeof ev.parent_id === 'number') {
+      map.set(ev.parent_id, ev);
+    }
+  }
+  return map;
+}
diff --git a/packages/cli/src/cmds/query/db/import/sqlQueries.ts b/packages/cli/src/cmds/query/db/import/sqlQueries.ts
new file mode 100644
index 0000000000..22492012c9
--- /dev/null
+++ b/packages/cli/src/cmds/query/db/import/sqlQueries.ts
@@ -0,0 +1,62 @@
+import sqlite3 from 'better-sqlite3';
+
+import type { SqlQuery } from '@appland/models';
+
+import type { ReturnEventLike } from './returnEventMap';
+
+// Import sql_query events. The caller class/method is taken from the event
+// itself when present; otherwise it's derived from the parent call event in
+// the per-thread call stack (matches the Python prototype).
+export function importSqlQueries(
+  db: sqlite3.Database,
+  appmapId: number,
+  events: readonly Record<string, any>[],
+  returnEvents: Map<number, ReturnEventLike>,
+  parentEventMap: Map<number, number>
+): void {
+  // event_id → call event, for parent-callsite lookup.
+  const callEvents = new Map<number, Record<string, any>>();
+  for (const ev of events) {
+    if (ev.event === 'call' && typeof ev.id === 'number') callEvents.set(ev.id, ev);
+  }
+
+  const stmt = db.prepare(
+    `INSERT INTO sql_queries (appmap_id, event_id, thread_id, parent_event_id,
+      sql_text, database_type, server_version, caller_class, caller_method,
+      elapsed_ms)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
+  );
+
+  for (const ev of events) {
+    const sq = ev.sql_query as SqlQuery | undefined;
+    if (!sq) continue;
+    const ret = returnEvents.get(ev.id) ?? {};
+    const elapsed = ret.elapsed;
+
+    let callerClass: string | null = ev.defined_class ?? null;
+    let callerMethod: string | null = ev.method_id ?? null;
+    if (!callerClass) {
+      const parentEid = parentEventMap.get(ev.id);
+      if (parentEid !== undefined) {
+        const parent = callEvents.get(parentEid);
+        if (parent) {
+          callerClass = parent.defined_class ?? null;
+          callerMethod = parent.method_id ?? null;
+        }
+      }
+    }
+
+    stmt.run(
+      appmapId,
+      ev.id,
+      ev.thread_id ?? null,
+      parentEventMap.get(ev.id) ?? null,
+      sq.sql,
+      sq.database_type ?? null,
+      sq.server_version ?? null,
+      callerClass,
+      callerMethod,
+      typeof elapsed === 'number' ? elapsed * 1000 : null
+    );
+  }
+}
diff --git a/packages/cli/src/cmds/query/db/index.ts b/packages/cli/src/cmds/query/db/index.ts
new file mode 100644
index 0000000000..7a3acb61d0
--- /dev/null
+++ b/packages/cli/src/cmds/query/db/index.ts
@@ -0,0 +1,3 @@
+export { SCHEMA, SCHEMA_VERSION, SCHEMA_TABLES } from './schema';
+export { queryDbPath, QUERY_DB_FILENAME } from './path';
+export { openQueryDb, OpenQueryDbResult } from './openQueryDb';
diff --git a/packages/cli/src/cmds/query/db/openQueryDb.ts b/packages/cli/src/cmds/query/db/openQueryDb.ts
new file mode 100644
index 0000000000..f5c4117161
--- /dev/null
+++ b/packages/cli/src/cmds/query/db/openQueryDb.ts
@@ -0,0 +1,55 @@
+import { mkdirSync } from 'fs';
+import { dirname } from 'path';
+
+import sqlite3 from 'better-sqlite3';
+
+import { SCHEMA, SCHEMA_TABLES, SCHEMA_VERSION } from './schema';
+import { queryDbPath } from './path';
+
+export interface OpenQueryDbResult {
+  db: sqlite3.Database;
+  path: string;
+  version: number;
+  rebuilt: boolean;
+}
+
+// Open the query DB for the given appmap directory, ensuring its schema is
+// at SCHEMA_VERSION. Creates the parent directory and the file if missing.
+// Drops and rebuilds all schema tables if the on-disk version doesn't match.
+//
+// `dbPath` overrides path derivation (used by tests).
+export function openQueryDb(appmapDir: string, dbPath?: string): OpenQueryDbResult {
+  const path = dbPath ?? queryDbPath(appmapDir);
+  mkdirSync(dirname(path), { recursive: true });
+
+  const db = sqlite3(path);
+  db.pragma('journal_mode = WAL');
+  db.pragma('foreign_keys = ON');
+  db.pragma('busy_timeout = 5000');
+
+  const currentVersion = db.pragma('user_version', { simple: true }) as number;
+  let rebuilt = false;
+
+  if (currentVersion === 0) {
+    db.exec(SCHEMA);
+    db.pragma(`user_version = ${SCHEMA_VERSION}`);
+  } else if (currentVersion !== SCHEMA_VERSION) {
+    rebuildSchema(db);
+    rebuilt = true;
+  }
+
+  return { db, path, version: SCHEMA_VERSION, rebuilt };
+}
+
+function rebuildSchema(db: sqlite3.Database): void {
+  const tx = db.transaction(() => {
+    db.pragma('foreign_keys = OFF');
+    for (const table of SCHEMA_TABLES) {
+      db.exec(`DROP TABLE IF EXISTS ${table}`);
+    }
+    db.exec(SCHEMA);
+    db.pragma(`user_version = ${SCHEMA_VERSION}`);
+    db.pragma('foreign_keys = ON');
+  });
+  tx();
+}
diff --git a/packages/cli/src/cmds/query/db/path.ts b/packages/cli/src/cmds/query/db/path.ts
new file mode 100644
index 0000000000..2cae528308
--- /dev/null
+++ b/packages/cli/src/cmds/query/db/path.ts
@@ -0,0 +1,20 @@
+import { createHash } from 'crypto';
+import { homedir } from 'os';
+import { join, resolve } from 'path';
+
+export const QUERY_DB_FILENAME = 'query.db';
+
+// Derive the on-disk path for the query DB that corresponds to the given
+// appmap directory. The path is rooted at `~/.appmap/data/<sha12>/query.db`,
+// where `<sha12>` is the first 12 hex characters of the SHA-256 digest of
+// the resolved directory path.
+//
+// Pure: returns the path without creating any directories.
+//
+// To use a different path (tests, CI, demo scripts), call openQueryDb /
+// openReadOnly with an explicit `dbPath` argument; the corresponding CLI
+// flag is `--db`.
+export function queryDbPath(appmapDir: string): string {
+  const id = createHash('sha256').update(resolve(appmapDir)).digest('hex').slice(0, 12);
+  return join(homedir(), '.appmap', 'data', id, QUERY_DB_FILENAME);
+}
diff --git a/packages/cli/src/cmds/query/db/schema.ts b/packages/cli/src/cmds/query/db/schema.ts
new file mode 100644
index 0000000000..28d4a212f6
--- /dev/null
+++ b/packages/cli/src/cmds/query/db/schema.ts
@@ -0,0 +1,175 @@
+// SQLite schema for AppMap APM data.
+//
+// Denormalizes AppMap events into APM-oriented tables optimized for the
+// queries an APM dashboard or LLM agent needs. Ported from appmap-apm
+// (server/db/schema.py); shape preserved unchanged.
+
+export const SCHEMA_VERSION = 5;
+
+export const SCHEMA = `
+CREATE TABLE IF NOT EXISTS appmaps (
+    id              INTEGER PRIMARY KEY AUTOINCREMENT,
+    name            TEXT NOT NULL,
+    source_path     TEXT NOT NULL UNIQUE,
+    language        TEXT,
+    framework       TEXT,
+    recorder_type   TEXT,
+    git_repository  TEXT,
+    git_branch      TEXT,
+    git_commit      TEXT,
+    timestamp       TEXT,
+    event_count     INTEGER NOT NULL DEFAULT 0,
+    sql_query_count INTEGER NOT NULL DEFAULT 0,
+    http_request_count INTEGER NOT NULL DEFAULT 0,
+    elapsed_ms      REAL,
+    metadata_labels TEXT  -- JSON array of metadata-level labels
+);
+
+-- Code objects from classMap entries (one per unique instrumented function).
+-- A lookup table for stable fqids. Components are stored separately so
+-- filters can match exactly without parsing the fqid string:
+--   package     slash-joined package path  ('' for top-level fn)
+--   classes     JSON array of class names  ('[]' for package-level fn)
+--   leaf_class  last element of classes, denormalized for fast lookup
+--               on short-form filters like --class Cipher (matches both
+--               top-level Cipher and OpenSSL::Cipher).
+--   method      leaf method name
+--   is_static   1 for static / class methods, 0 for instance methods
+-- The fqid is always derivable from these (package + cls-chain + (#|.) +
+-- method); we keep it as a stored column for output ergonomics and
+-- uniqueness enforcement.
+--
+-- This table intentionally does NOT store path/lineno/location, because
+-- those vary across recordings of the same code (different branches or
+-- revisions). Per-recording location data lives on function_calls.
+CREATE TABLE IF NOT EXISTS code_objects (
+    id              INTEGER PRIMARY KEY AUTOINCREMENT,
+    fqid            TEXT NOT NULL UNIQUE,
+    package         TEXT NOT NULL,
+    classes         TEXT NOT NULL,
+    leaf_class      TEXT NOT NULL,
+    method          TEXT NOT NULL,
+    is_static       INTEGER NOT NULL DEFAULT 0
+);
+
+CREATE TABLE IF NOT EXISTS http_requests (
+    id              INTEGER PRIMARY KEY AUTOINCREMENT,
+    appmap_id       INTEGER NOT NULL REFERENCES appmaps(id) ON DELETE CASCADE,
+    event_id        INTEGER NOT NULL,
+    thread_id       INTEGER,
+    parent_event_id INTEGER,
+    method          TEXT NOT NULL,
+    path            TEXT NOT NULL,
+    normalized_path TEXT,
+    protocol        TEXT,
+    status_code     INTEGER NOT NULL,
+    mime_type       TEXT,
+    elapsed_ms      REAL
+    -- Note: no per-row timestamp. Time range queries JOIN to appmaps and
+    -- filter on appmaps.timestamp (the recording-level value).
+);
+
+CREATE TABLE IF NOT EXISTS http_client_requests (
+    id              INTEGER PRIMARY KEY AUTOINCREMENT,
+    appmap_id       INTEGER NOT NULL REFERENCES appmaps(id) ON DELETE CASCADE,
+    event_id        INTEGER NOT NULL,
+    thread_id       INTEGER,
+    parent_event_id INTEGER,
+    method          TEXT NOT NULL,
+    url             TEXT NOT NULL,
+    status_code     INTEGER,
+    elapsed_ms      REAL
+);
+
+CREATE TABLE IF NOT EXISTS sql_queries (
+    id              INTEGER PRIMARY KEY AUTOINCREMENT,
+    appmap_id       INTEGER NOT NULL REFERENCES appmaps(id) ON DELETE CASCADE,
+    event_id        INTEGER NOT NULL,
+    thread_id       INTEGER,
+    parent_event_id INTEGER,
+    sql_text        TEXT NOT NULL,
+    database_type   TEXT,
+    server_version  TEXT,
+    caller_class    TEXT,
+    caller_method   TEXT,
+    elapsed_ms      REAL
+);
+
+CREATE TABLE IF NOT EXISTS function_calls (
+    id              INTEGER PRIMARY KEY AUTOINCREMENT,
+    appmap_id       INTEGER NOT NULL REFERENCES appmaps(id) ON DELETE CASCADE,
+    event_id        INTEGER NOT NULL,
+    thread_id       INTEGER,
+    parent_event_id INTEGER,
+    code_object_id  INTEGER REFERENCES code_objects(id),
+    defined_class   TEXT NOT NULL,
+    method_id       TEXT NOT NULL,
+    path            TEXT,
+    lineno          INTEGER,
+    is_static       INTEGER NOT NULL DEFAULT 0,
+    elapsed_ms      REAL,
+    parameters_json TEXT,   -- JSON of parameter values (for labeled/log functions)
+    return_value    TEXT    -- string repr of return value (for labeled/log functions)
+);
+
+CREATE TABLE IF NOT EXISTS exceptions (
+    id              INTEGER PRIMARY KEY AUTOINCREMENT,
+    appmap_id       INTEGER NOT NULL REFERENCES appmaps(id) ON DELETE CASCADE,
+    -- event_id is the call event id (the call this exception belongs to);
+    -- return_event_id is the return event id (where the throw materialized in
+    -- the event stream). Use return_event_id for ordering — e.g. the
+    -- with_logs neighborhood query (what did the app log before the throw?)
+    -- needs to include logs that fired *inside* the throwing call, which all
+    -- have event_id greater than the call entry id but less than the return.
+    event_id        INTEGER,
+    return_event_id INTEGER,
+    thread_id       INTEGER,
+    parent_event_id INTEGER,
+    exception_class TEXT NOT NULL,
+    message         TEXT,
+    path            TEXT,
+    lineno          INTEGER
+);
+
+-- Labels from classMap function entries (log, security.*, etc.)
+CREATE TABLE IF NOT EXISTS labels (
+    id              INTEGER PRIMARY KEY AUTOINCREMENT,
+    code_object_id  INTEGER NOT NULL REFERENCES code_objects(id),
+    label           TEXT NOT NULL,
+    UNIQUE(code_object_id, label)
+);
+
+-- Indexes for common APM queries
+CREATE INDEX IF NOT EXISTS idx_http_requests_appmap ON http_requests(appmap_id);
+CREATE INDEX IF NOT EXISTS idx_http_requests_path ON http_requests(normalized_path, method);
+CREATE INDEX IF NOT EXISTS idx_http_requests_status ON http_requests(status_code);
+CREATE INDEX IF NOT EXISTS idx_http_client_requests_appmap ON http_client_requests(appmap_id);
+CREATE INDEX IF NOT EXISTS idx_sql_queries_appmap ON sql_queries(appmap_id);
+CREATE INDEX IF NOT EXISTS idx_sql_queries_elapsed ON sql_queries(elapsed_ms DESC);
+CREATE INDEX IF NOT EXISTS idx_function_calls_appmap ON function_calls(appmap_id);
+CREATE INDEX IF NOT EXISTS idx_function_calls_class_method ON function_calls(defined_class, method_id);
+CREATE INDEX IF NOT EXISTS idx_function_calls_code_object ON function_calls(code_object_id);
+CREATE INDEX IF NOT EXISTS idx_function_calls_parent ON function_calls(appmap_id, parent_event_id);
+CREATE INDEX IF NOT EXISTS idx_exceptions_appmap ON exceptions(appmap_id);
+CREATE INDEX IF NOT EXISTS idx_exceptions_class ON exceptions(exception_class);
+CREATE INDEX IF NOT EXISTS idx_code_objects_fqid ON code_objects(fqid);
+CREATE INDEX IF NOT EXISTS idx_code_objects_leaf_class ON code_objects(leaf_class);
+CREATE INDEX IF NOT EXISTS idx_code_objects_method ON code_objects(method);
+CREATE INDEX IF NOT EXISTS idx_code_objects_leaf_method ON code_objects(leaf_class, method);
+CREATE INDEX IF NOT EXISTS idx_labels_label ON labels(label);
+CREATE INDEX IF NOT EXISTS idx_labels_code_object ON labels(code_object_id);
+CREATE INDEX IF NOT EXISTS idx_appmaps_timestamp ON appmaps(timestamp);
+CREATE INDEX IF NOT EXISTS idx_appmaps_branch ON appmaps(git_branch);
+`;
+
+// Names of all schema tables (used by the version-mismatch teardown path).
+export const SCHEMA_TABLES = [
+  'appmaps',
+  'code_objects',
+  'http_requests',
+  'http_client_requests',
+  'sql_queries',
+  'function_calls',
+  'exceptions',
+  'labels',
+];
diff --git a/packages/cli/src/cmds/query/lib/appmapPath.ts b/packages/cli/src/cmds/query/lib/appmapPath.ts
new file mode 100644
index 0000000000..d1e45ce7bb
--- /dev/null
+++ b/packages/cli/src/cmds/query/lib/appmapPath.ts
@@ -0,0 +1,62 @@
+// Helpers that work with AppMap recording identifiers.
+//
+// The canonical id for a recording is its absolute file path on disk —
+// the same value the indexer stored as `appmaps.source_path`. The path
+// is self-documenting — "junit/" / "request_recording/" segments tell
+// the agent what kind of trace it is, the basename embeds the test
+// method or HTTP route — and an absolute path is unambiguous against
+// the index even when a sticky/widened scan accidentally cataloged two
+// recordings with the same basename. That orienting metadata is paid
+// back many times over by avoiding identifier-form retries (numeric id
+// → name → relative path → display label) when the agent re-queries
+// the same recording.
+//
+// Aliases (recording name, basename, numeric id) are not accepted —
+// see resolveAppmapPath in queries/mcp.ts. Only the canonical absolute
+// path resolves. Names are not unique and numeric ids aren't stable
+// across reindexing, so accepting them would be flexibility for
+// flexibility's sake — at the cost of agents getting silent-wrong or
+// "ambiguous" results when those collisions happen in the wild.
+
+import { sep } from 'path';
+
+const RECORDING_KINDS = {
+  junit: 'junit',
+  request: 'request',
+  other: 'other',
+} as const;
+
+export type RecordingKind = (typeof RECORDING_KINDS)[keyof typeof RECORDING_KINDS];
+
+function toForwardSlashes(p: string): string {
+  return sep === '\\' ? p.replace(/\\/g, '/') : p;
+}
+
+// Categorize the recording by its on-disk location. Junit recordings sit
+// in `…/junit/…appmap.json`; per-request slices sit in
+// `…/request_recording/…appmap.json`. Any other layout is reported as
+// "other" so the field stays present on every row.
+export function deriveKind(sourcePath: string): RecordingKind {
+  const norm = toForwardSlashes(sourcePath).toLowerCase();
+  if (norm.includes('/junit/')) return RECORDING_KINDS.junit;
+  if (norm.includes('/request_recording/') || norm.includes('/requests/')) {
+    return RECORDING_KINDS.request;
+  }
+  return RECORDING_KINDS.other;
+}
+
+// Display labels — strings of the form "GET /api/v1/payments (200) - 19:47:22.660"
+// — sometimes get pasted back as appmap arguments because they're what
+// an earlier `find_recordings` *displayed*. They aren't ids; they don't
+// match anything in the database. Detect the form here so the caller
+// can return a helpful error instead of a silent miss.
+const HTTP_METHOD_PREFIX = /^\s*(GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS)\s+\S/i;
+const TRAILING_TIMESTAMP = /\s-\s\d{1,2}:\d{2}:\d{2}/;
+const PARENS_STATUS = /\(\d{3}\)/;
+
+export function looksLikeDisplayLabel(s: string): boolean {
+  if (!s) return false;
+  if (TRAILING_TIMESTAMP.test(s)) return true;
+  if (HTTP_METHOD_PREFIX.test(s) && PARENS_STATUS.test(s)) return true;
+  return false;
+}
diff --git a/packages/cli/src/cmds/query/lib/format.ts b/packages/cli/src/cmds/query/lib/format.ts
new file mode 100644
index 0000000000..d8effde2ba
--- /dev/null
+++ b/packages/cli/src/cmds/query/lib/format.ts
@@ -0,0 +1,37 @@
+// Render a row of cells as a tab-aligned line. Per V3, tabular output never
+// wraps — long fqids extend past terminal width rather than break (so grep
+// over output stays usable). Pipe through `less -S` or use --json instead.
+//
+// `widths` is a per-column minimum width; cells longer than the minimum
+// extend the column.
+export function formatTable(
+  headers: readonly string[],
+  rows: readonly (readonly string[])[]
+): string {
+  const widths = headers.map((h, i) =>
+    Math.max(h.length, ...rows.map((r) => (r[i] ?? '').length))
+  );
+  const lines: string[] = [];
+  lines.push(headers.map((h, i) => h.padEnd(widths[i])).join('  '));
+  for (const row of rows) {
+    lines.push(row.map((c, i) => (c ?? '').padEnd(widths[i])).join('  '));
+  }
+  return lines.join('\n');
+}
+
+// Format a duration in ms as "12ms" / "480ms" / "3.4s" / "1.2s".
+export function formatMs(ms: number | null | undefined): string {
+  if (ms == null) return '—';
+  if (ms < 1000) return `${Math.round(ms)}ms`;
+  return `${(ms / 1000).toFixed(1)}s`;
+}
+
+// Format a non-negative integer with thousands separators ("1,891").
+export function formatCount(n: number): string {
+  return n.toLocaleString('en-US');
+}
+
+// Format a percentage like "4.6%".
+export function formatPct(pct: number): string {
+  return `${pct.toFixed(1)}%`;
+}
diff --git a/packages/cli/src/cmds/query/lib/logMessage.ts b/packages/cli/src/cmds/query/lib/logMessage.ts
new file mode 100644
index 0000000000..7bb6d79ae1
--- /dev/null
+++ b/packages/cli/src/cmds/query/lib/logMessage.ts
@@ -0,0 +1,53 @@
+// Pick a displayable message from a log row's captured fields.
+//   1. If return_value parses as JSON with a `message` field, use it
+//      (this is the structured-return contract).
+//   2. Otherwise, look in parameters_json for a parameter whose `name`
+//      is `message` or `msg`; fall back to the first string-typed value.
+//   3. Otherwise, return ''.
+// Display-only — does not affect filtering. The `--message` SQL LIKE
+// runs against the raw columns and may return rows whose projected
+// message doesn't contain the substring (e.g., matched a class name);
+// that's the documented FP-tolerant behavior.
+export function projectLogMessage(
+  parametersJson: string | null,
+  returnValue: string | null
+): string {
+  if (returnValue) {
+    try {
+      const parsed = JSON.parse(returnValue) as Record<string, unknown>;
+      if (parsed && typeof parsed === 'object' && typeof parsed.message === 'string') {
+        return parsed.message;
+      }
+    } catch {
+      // not structured — fall through
+    }
+  }
+  if (parametersJson) {
+    try {
+      const params = JSON.parse(parametersJson) as { name?: string; class?: string; value?: unknown }[];
+      const named = params.find((p) => p.name === 'message' || p.name === 'msg');
+      if (named?.value != null) return stripWrappingQuotes(String(named.value));
+      const firstString = params.find((p) => typeof p.value === 'string');
+      if (firstString) return stripWrappingQuotes(String(firstString.value));
+      if (params.length > 0) return JSON.stringify(params.map((p) => p.value));
+    } catch {
+      return parametersJson;
+    }
+  }
+  // No structured message available. Return blank rather than the raw
+  // `return_value` (which is often noise like "true" / "None").
+  return '';
+}
+
+// Some recorders stringify String parameter values with the source-code
+// quote characters preserved (e.g. `'hello'`). Strip a single matched
+// pair of leading+trailing single or double quotes so the display text
+// is the raw message.
+function stripWrappingQuotes(s: string): string {
+  if (s.length >= 2) {
+    const first = s[0];
+    const last = s[s.length - 1];
+    if ((first === "'" || first === '"') && first === last) return s.slice(1, -1);
+  }
+  return s;
+}
diff --git a/packages/cli/src/cmds/query/lib/openReadOnly.ts b/packages/cli/src/cmds/query/lib/openReadOnly.ts
new file mode 100644
index 0000000000..cb68998c36
--- /dev/null
+++ b/packages/cli/src/cmds/query/lib/openReadOnly.ts
@@ -0,0 +1,18 @@
+import { existsSync } from 'fs';
+
+import sqlite3 from 'better-sqlite3';
+
+import { queryDbPath } from '../db/path';
+
+// Open the query DB read-only for the given appmap directory.
+// Errors if the DB doesn't exist, prompting the user to run `appmap index`.
+// `dbPath` overrides path derivation (used by tests and the --query-db flag).
+export function openReadOnly(appmapDir: string, dbPath?: string): sqlite3.Database {
+  const path = dbPath ?? queryDbPath(appmapDir);
+  if (!existsSync(path)) {
+    throw new Error(
+      `query DB not found at ${path}\nRun \`appmap index\` first to build it.`
+    );
+  }
+  return sqlite3(path, { readonly: true });
+}
diff --git a/packages/cli/src/cmds/query/lib/page.ts b/packages/cli/src/cmds/query/lib/page.ts
new file mode 100644
index 0000000000..342213becd
--- /dev/null
+++ b/packages/cli/src/cmds/query/lib/page.ts
@@ -0,0 +1,56 @@
+import sqlite3 from 'better-sqlite3';
+
+// Standard wrapper for any list-returning query. `rows` is the slice
+// the caller asked for; `total` is the count of all matching rows
+// (ignoring limit/offset). JSON consumers get truncation info for free;
+// text renderers append a footer when total > offset + rows.length.
+export interface Page<T> {
+  rows: T[];
+  total: number;
+  limit: number;
+  offset: number;
+}
+
+// Default limit applied when filter.limit is undefined. Pass 0 or
+// negative to mean unbounded.
+export const DEFAULT_PAGE_LIMIT = 20;
+
+// Run a base query and return its paginated result + total count.
+// `baseSql` is the SELECT (with WHERE / ORDER BY) without LIMIT/OFFSET;
+// the function wraps it in a COUNT subquery for the total. Limit/offset
+// are inlined as numbers — they come from typed filter fields, not
+// arbitrary user input, so this is safe.
+export function paginate<T>(
+  db: sqlite3.Database,
+  baseSql: string,
+  params: readonly (string | number)[],
+  options: { limit?: number; offset?: number } = {}
+): Page<T> {
+  const limit = options.limit ?? DEFAULT_PAGE_LIMIT;
+  const offset = options.offset ?? 0;
+
+  const countSql = `SELECT COUNT(*) AS n FROM (${baseSql})`;
+  const total = (db.prepare(countSql).get(...params) as { n: number }).n;
+
+  let rowsSql = baseSql;
+  if (limit > 0) {
+    rowsSql += ` LIMIT ${limit | 0} OFFSET ${offset | 0}`;
+  } else if (offset > 0) {
+    rowsSql += ` LIMIT -1 OFFSET ${offset | 0}`;
+  }
+  const rows = db.prepare(rowsSql).all(...params) as T[];
+
+  return { rows, total, limit, offset };
+}
+
+// Format the truncation footer for text-mode renderers. Returns null
+// when nothing was clipped (so the caller can choose whether to print
+// it at all).
+export function truncationFooter(page: Page<unknown>): string | null {
+  const shown = page.rows.length;
+  if (shown === 0 && page.total === 0) return null;
+  const last = page.offset + shown;
+  if (last >= page.total) return null;
+  const first = page.offset + 1;
+  return `(showing ${first}–${last} of ${page.total}; use --limit / --offset to page)`;
+}
diff --git a/packages/cli/src/cmds/query/lib/parseFilter.ts b/packages/cli/src/cmds/query/lib/parseFilter.ts
new file mode 100644
index 0000000000..00ea5eb5d8
--- /dev/null
+++ b/packages/cli/src/cmds/query/lib/parseFilter.ts
@@ -0,0 +1,76 @@
+// Shared parsers for CLI filter flags.
+//
+// These convert user-typed strings into canonical structured forms that
+// query functions can apply uniformly. Verbs share these so a flag like
+// --since "7d ago" means the same thing everywhere.
+
+export type Comparator = '=' | '>=' | '<=' | '>' | '<';
+
+export interface NumberFilter {
+  op: Comparator;
+  value: number;
+}
+
+// Parse a status filter: "500", "=500", ">=500", ">500", "<400", "<=399".
+// Whitespace around the operator is tolerated.
+export function parseStatus(input: string): NumberFilter {
+  const m = input.trim().match(/^(>=|<=|>|<|=)?\s*(\d+)$/);
+  if (!m) throw new Error(`invalid --status filter: ${input}`);
+  const op = (m[1] ?? '=') as Comparator;
+  return { op, value: Number.parseInt(m[2], 10) };
+}
+
+// Parse a duration filter: ">1s", ">=500ms", "<2m". The numeric form is
+// returned in milliseconds for direct comparison against elapsed_ms.
+export function parseDuration(input: string): NumberFilter {
+  const m = input.trim().match(/^(>=|<=|>|<|=)?\s*(\d+(?:\.\d+)?)\s*(ms|s|m|h)?$/);
+  if (!m) throw new Error(`invalid --duration filter: ${input}`);
+  const op = (m[1] ?? '=') as Comparator;
+  const n = Number.parseFloat(m[2]);
+  const unit = m[3] ?? 'ms';
+  const ms =
+    unit === 'ms'
+      ? n
+      : unit === 's'
+      ? n * 1000
+      : unit === 'm'
+      ? n * 60_000
+      : n * 3_600_000;
+  return { op, value: ms };
+}
+
+// Parse a time spec: ISO date/timestamp ("2026-04-29", "2026-04-29T14:21:08Z")
+// or a relative offset ("7d ago", "30m ago", "2h ago", "45s ago"). Returns
+// an ISO 8601 string suitable for direct text comparison against the
+// timestamp column (which is also ISO 8601).
+export function parseTime(input: string, now: Date = new Date()): string {
+  const trimmed = input.trim();
+
+  const rel = trimmed.match(/^(\d+)\s*([smhd])\s+ago$/);
+  if (rel) {
+    const n = Number.parseInt(rel[1], 10);
+    const unit = rel[2];
+    const ms =
+      unit === 's'
+        ? n * 1_000
+        : unit === 'm'
+        ? n * 60_000
+        : unit === 'h'
+        ? n * 3_600_000
+        : n * 86_400_000;
+    return new Date(now.getTime() - ms).toISOString();
+  }
+
+  const ms = Date.parse(trimmed);
+  if (Number.isNaN(ms)) throw new Error(`invalid time filter: ${input}`);
+  return new Date(ms).toISOString();
+}
+
+// Apply a NumberFilter as a WHERE-clause fragment. Returns the SQL fragment
+// (with a `?` placeholder) and the value to bind. Throws on unknown op.
+export function numberFilterSql(
+  column: string,
+  filter: NumberFilter
+): { sql: string; value: number } {
+  return { sql: `${column} ${filter.op} ?`, value: filter.value };
+}
diff --git a/packages/cli/src/cmds/query/lib/recordingId.ts b/packages/cli/src/cmds/query/lib/recordingId.ts
new file mode 100644
index 0000000000..d8b86b5585
--- /dev/null
+++ b/packages/cli/src/cmds/query/lib/recordingId.ts
@@ -0,0 +1,92 @@
+// Recording-id helpers shared by the MCP server and the UI server.
+//
+// The canonical id for a recording is its absolute file path on disk —
+// the same value the indexer stored as `appmaps.source_path` (UNIQUE in
+// the schema). Names, basenames, numeric ids, and display labels are
+// rejected here so consumers get a clear error pointing at the right
+// input instead of a silent miss when one of the looser shapes collides.
+//
+// Extracted from queries/mcp.ts so a second consumer (the local UI HTTP
+// server) can resolve and decorate recordings without depending on the
+// MCP module.
+
+import sqlite3 from 'better-sqlite3';
+
+import { deriveKind, looksLikeDisplayLabel, RecordingKind } from './appmapPath';
+import type { FindAppmapRow } from '../queries/find';
+import type { AppmapInfo } from '../queries/tree';
+
+// Resolve an `appmap` argument against the indexed recordings.
+//
+// Primary form is the canonical id — the absolute source_path returned
+// by find_recordings's `path` field. `appmaps.source_path` is UNIQUE,
+// so an exact match is always unambiguous.
+//
+// Relative paths (anything containing a `/` but not starting with one)
+// are also accepted, matched against `source_path` by suffix. The
+// indexer already constrains the corpus to configured appmap dirs, so
+// a unique suffix match means a single recording — the caller doesn't
+// need to plumb absolute paths through. When multiple recordings share
+// the suffix, we surface the ambiguity with the candidate paths so
+// the caller can pick one.
+//
+// Bare names, numeric ids, and display labels remain rejected: those
+// shapes silently collide in real corpora (multiple recordings share
+// the same basename or name), and the resulting wrong-recording
+// resolution is harder to debug than an explicit error.
+export function resolveAppmapPath(db: sqlite3.Database, ref: unknown): AppmapInfo {
+  const s = String(ref);
+  if (looksLikeDisplayLabel(s)) {
+    throw new Error(
+      `appmap argument looks like a display label. ` +
+        `Use the 'path' field from find_recordings instead. Got: '${s}'.`
+    );
+  }
+  // Exact match on the canonical absolute path (fast path; UNIQUE index).
+  const exact = db
+    .prepare(`SELECT id, name, source_path FROM appmaps WHERE source_path = ?`)
+    .get(s) as AppmapInfo | undefined;
+  if (exact) return exact;
+
+  // Relative path: a leading slash is absent, but there's at least one
+  // `/` separator so this isn't a bare name. Suffix-match the indexed
+  // source_paths; require uniqueness.
+  if (!s.startsWith('/') && s.includes('/')) {
+    const candidates = db
+      .prepare(
+        `SELECT id, name, source_path FROM appmaps WHERE source_path LIKE ('%/' || ?)`
+      )
+      .all(s) as AppmapInfo[];
+    if (candidates.length === 1) return candidates[0];
+    if (candidates.length > 1) {
+      const paths = candidates.map((c) => `  ${c.source_path}`).join('\n');
+      throw new Error(
+        `appmap '${s}' is ambiguous; ${candidates.length} indexed recordings end with that path:\n${paths}\n` +
+          `Use the absolute 'path' field from find_recordings to disambiguate.`
+      );
+    }
+  }
+  throw new Error(
+    `appmap not found at path '${s}'. ` +
+      `The appmap argument must be a path that matches an indexed recording — ` +
+      `either the canonical absolute 'path' from find_recordings, or a project-` +
+      `relative path that uniquely resolves. Bare names and numeric ids are not accepted.`
+  );
+}
+
+// Decorate a FindAppmapRow with the canonical id surface (Spec 01):
+//   - path  : the absolute source_path — what get_call_tree, find_related,
+//             and the --appmap filter expect as input
+//   - label : the human-readable name from metadata
+//   - kind  : "junit" | "request" | "other" so the UI / agent can pick
+//             the right vantage point without guessing from the basename
+export function decorateRecording(
+  row: FindAppmapRow
+): FindAppmapRow & { path: string; label: string; kind: RecordingKind } {
+  return {
+    ...row,
+    path: row.source_path,
+    label: row.appmap_name,
+    kind: deriveKind(row.source_path),
+  };
+}
diff --git a/packages/cli/src/cmds/query/lib/scope.ts b/packages/cli/src/cmds/query/lib/scope.ts
new file mode 100644
index 0000000000..e5d35e74de
--- /dev/null
+++ b/packages/cli/src/cmds/query/lib/scope.ts
@@ -0,0 +1,444 @@
+import type { NumberFilter } from './parseFilter';
+
+// Shared recording-scope filter shape — the subset of CLI filter flags that
+// constrain *which recordings* a verb considers (as opposed to row-level
+// filters like --duration or --label that constrain rows within a recording).
+//
+// Verb-specific filter types should extend this; helpers in this file accept
+// any shape with the relevant fields.
+export interface RecordingScope {
+  branch?: string;
+  commit?: string;
+  since?: string;
+  until?: string;
+  appmap?: string;
+  // HTTP-level filters that scope to "the recording must contain ≥1
+  // matching server request":
+  route?: string;          // "POST /orders" or "/orders"
+  status?: NumberFilter;
+}
+
+export interface RouteSpec {
+  method?: string;
+  path: string;
+}
+
+const HTTP_METHODS = /^(GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS)\s+(.+)$/i;
+
+export function parseRoute(s: string): RouteSpec {
+  const m = s.match(HTTP_METHODS);
+  if (m) return { method: m[1].toUpperCase(), path: m[2] };
+  return { path: s };
+}
+
+// Returns SQL clauses (and params) that match an --appmap reference against
+// the appmaps table, accepting any of:
+//   - exact appmap.name
+//   - exact source_path                                (canonical absolute id)
+//   - source_path ending in `<sep><ref>.appmap.json`  (Unix or Windows sep)
+//   - source_path ending in `<sep><ref>`              (non-`.appmap.json` stores)
+// The "ends-with" branches let a relative path under the indexer's root
+// (`customer-portal-api/tmp/appmap/junit/foo.appmap.json`) match the
+// stored absolute source_path on either platform.
+// Used by `tree` and other single-resolve operations that want
+// exact-match-or-fail (with an ambiguity error). For find/list contexts
+// where lenient matching is the right UX, use appmapLikeClause.
+export function appmapRefClause(
+  ref: string,
+  alias: string
+): { sql: string; params: string[] } {
+  return {
+    sql: `(${alias}.name = ?
+        OR ${alias}.source_path = ?
+        OR ${alias}.source_path GLOB '*[/\\\\]' || ? || '.appmap.json'
+        OR ${alias}.source_path GLOB '*[/\\\\]' || ?)`,
+    params: [ref, ref, ref, ref],
+  };
+}
+
+// Lenient appmap match for find/list contexts: ref is a substring of
+// either the human-readable name or the source_path. SQLite LIKE is
+// case-insensitive for ASCII by default. Used by appmapWhere so all the
+// find_* tools surface a recording when any reasonable word from its
+// name or path is provided.
+export function appmapLikeClause(
+  ref: string,
+  alias: string
+): { sql: string; params: string[] } {
+  const like = `%${ref}%`;
+  return {
+    sql: `(${alias}.name LIKE ? OR ${alias}.source_path LIKE ?)`,
+    params: [like, like],
+  };
+}
+
+export interface Clauses {
+  where: string[];
+  params: (string | number)[];
+}
+
+// Recording-level filters that go on the appmaps row directly.
+export function appmapWhere(filter: RecordingScope, alias: string): Clauses {
+  const where: string[] = [];
+  const params: (string | number)[] = [];
+  if (filter.branch) {
+    where.push(`${alias}.git_branch = ?`);
+    params.push(filter.branch);
+  }
+  if (filter.commit) {
+    where.push(`${alias}.git_commit = ?`);
+    params.push(filter.commit);
+  }
+  if (filter.since) {
+    where.push(`${alias}.timestamp >= ?`);
+    params.push(filter.since);
+  }
+  if (filter.until) {
+    where.push(`${alias}.timestamp <= ?`);
+    params.push(filter.until);
+  }
+  if (filter.appmap) {
+    const ref = appmapLikeClause(filter.appmap, alias);
+    where.push(ref.sql);
+    params.push(...ref.params);
+  }
+  return { where, params };
+}
+
+// HTTP-level filters that scope to "the recording must contain ≥1 matching
+// server request." Used as a subquery for non-request finds. The alias
+// defaults to `h`; override when emitting clauses inside a nested subquery
+// where the outer alias is taken.
+export function httpScopeClauses(filter: RecordingScope, alias = 'h'): Clauses {
+  const where: string[] = [];
+  const params: (string | number)[] = [];
+  if (filter.route) {
+    const route = parseRoute(filter.route);
+    where.push(`COALESCE(${alias}.normalized_path, ${alias}.path) LIKE ?`);
+    params.push(`%${route.path}%`);
+    if (route.method) {
+      where.push(`${alias}.method = ?`);
+      params.push(route.method);
+    }
+  }
+  if (filter.status) {
+    where.push(`${alias}.status_code ${filter.status.op} ?`);
+    params.push(filter.status.value);
+  }
+  return { where, params };
+}
+
+// Parse a --class flag value into (package, class, method) components, per
+// V3's accepted forms:
+//   short        : "UserRepository" / "Cls1::Cls2"
+//   class+method : "UserRepository#findById" / "Cls1::Cls2#m"
+//   pkg+class    : "app/services/UserRepository"
+//   full fqid    : "app/services/UserRepository#findById"
+//                  "app/Outer::Inner.parse"   (static method)
+//
+// Class chains use `::` as the inner separator (canonical V3, also Ruby /
+// C++ idiomatic); we treat that as part of the class name, not a split
+// point. The method separator (`#` or `.`) only applies when the input is
+// in canonical form (contains `/`) or uses `#` explicitly. A short-form
+// dot like "org.example.Foo" is kept whole — Java/Python dot-form class
+// names match the defined_class fallback, not the normalized columns.
+export interface ClassMethodParts {
+  package?: string;
+  class?: string;
+  method?: string;
+}
+
+export function parseClassRef(input: string): ClassMethodParts {
+  const slashIdx = input.lastIndexOf('/');
+
+  if (slashIdx < 0) {
+    // Short form. `#` is the only unambiguous method separator here; `.`
+    // is left in place because it could be part of a Java/Python class name
+    // ("org.example.Foo") rather than a method separator.
+    const hashIdx = input.lastIndexOf('#');
+    if (hashIdx > 0) {
+      return {
+        class: input.slice(0, hashIdx) || undefined,
+        method: input.slice(hashIdx + 1),
+      };
+    }
+    return { class: input.length > 0 ? input : undefined };
+  }
+
+  // Canonical fqid (slash present). The method separator is the rightmost
+  // `#` or `.` AFTER the last `/`. (Inner `.` characters in the package
+  // path don't apply — packages are slash-separated.)
+  let methodSepIdx = -1;
+  for (let i = input.length - 1; i > slashIdx; i--) {
+    const ch = input[i];
+    if (ch === '#' || ch === '.') {
+      methodSepIdx = i;
+      break;
+    }
+  }
+
+  let classPart = input;
+  let methodPart: string | undefined;
+  if (methodSepIdx > 0) {
+    classPart = input.slice(0, methodSepIdx);
+    methodPart = input.slice(methodSepIdx + 1);
+  }
+
+  const classSlashIdx = classPart.lastIndexOf('/');
+  const pkg = classPart.slice(0, classSlashIdx);
+  const cls = classPart.slice(classSlashIdx + 1);
+  return {
+    package: pkg.length > 0 ? pkg : undefined,
+    class: cls.length > 0 ? cls : undefined,
+    method: methodPart,
+  };
+}
+
+// Match a --class input against function_calls via the normalized
+// code_objects columns. The `class` part of the user input is interpreted
+// as either:
+//   - A `::`-separated chain ("Outer::Inner") → match `classes` exactly
+//     (canonical JSON form).
+//   - A single-segment short form ("Cipher")  → match `leaf_class`
+//     exactly (hits any chain ending in that class — top-level Cipher
+//     and OpenSSL::Cipher both qualify).
+// Adding a package narrows further: `... AND package = ?`.
+//
+// Falls back to function_calls.defined_class for rows that aren't linked
+// to a code_object (sparse classMap recordings). The fallback recognizes
+// `.` (Java/Python), `::` (Ruby/C++) as suffix separators for short-form
+// matching against the raw event field.
+export function classFilterClauses(input: string, fcAlias: string): Clauses {
+  const parts = parseClassRef(input);
+  if (!parts.class) {
+    return { where: ['1 = 0'], params: [] };
+  }
+
+  const coWhere: string[] = [];
+  const coParams: (string | number)[] = [];
+  if (parts.class.includes('::')) {
+    // Full chain — match classes JSON exactly.
+    coWhere.push('classes = ?');
+    coParams.push(JSON.stringify(parts.class.split('::')));
+  } else {
+    // Single segment — match the leaf.
+    coWhere.push('leaf_class = ?');
+    coParams.push(parts.class);
+  }
+  if (parts.package) {
+    coWhere.push('package = ?');
+    coParams.push(parts.package);
+  }
+  if (parts.method) {
+    coWhere.push('method = ?');
+    coParams.push(parts.method);
+  }
+
+  // Fallback for unlinked function_calls. Includes a substring match on
+  // defined_class so a search like "Repo" matches "UserRepository" even
+  // when the row isn't linked to a code_object.
+  const fbWhere: string[] = [
+    `${fcAlias}.defined_class = ?`,
+    `${fcAlias}.defined_class LIKE '%.' || ?`,
+    `${fcAlias}.defined_class LIKE '%::' || ?`,
+    `${fcAlias}.defined_class LIKE ?`,
+  ];
+  const fbParams: (string | number)[] = [
+    parts.class,
+    parts.class,
+    parts.class,
+    `%${parts.class}%`,
+  ];
+
+  // Lenient leaf_class substring lookup against code_objects. Applied
+  // only when the user supplied a SHORT form (no package, no chain) —
+  // a canonical input like "org/example/UserRepository#findById" is
+  // explicit disambiguation and should match strictly. So short-form
+  // "Repo" finds "UserRepository", but full canonical doesn't broaden.
+  const isShortForm = !parts.package && !parts.class.includes('::');
+  if (!isShortForm) {
+    return {
+      where: [
+        `((${fcAlias}.code_object_id IN (
+            SELECT id FROM code_objects WHERE ${coWhere.join(' AND ')}
+          ))
+          OR (${fcAlias}.code_object_id IS NULL AND (${fbWhere.join(' OR ')})))`,
+      ],
+      params: [...coParams, ...fbParams],
+    };
+  }
+
+  return {
+    where: [
+      `((${fcAlias}.code_object_id IN (
+            SELECT id FROM code_objects WHERE ${coWhere.join(' AND ')}
+          ))
+        OR (${fcAlias}.code_object_id IN (
+            SELECT id FROM code_objects WHERE leaf_class LIKE ?
+          ))
+        OR (${fcAlias}.code_object_id IS NULL AND (${fbWhere.join(' OR ')})))`,
+    ],
+    params: [...coParams, `%${parts.class}%`, ...fbParams],
+  };
+}
+
+// Match a --method input against function_calls via the normalized
+// code_objects.method column, with a fallback to function_calls.method_id
+// for rows that aren't linked to a code_object.
+export function methodFilterClauses(input: string, fcAlias: string): Clauses {
+  const like = `%${input}%`;
+  return {
+    where: [
+      `(${fcAlias}.code_object_id IN (
+          SELECT id FROM code_objects WHERE method = ? OR method LIKE ?
+        )
+        OR (${fcAlias}.code_object_id IS NULL
+            AND (${fcAlias}.method_id = ? OR ${fcAlias}.method_id LIKE ?)))`,
+    ],
+    params: [input, like, input, like],
+  };
+}
+
+// Match a --class input against a sql_query by following its
+// parent_event_id back to the function_call that issued the query, then
+// looking up that call's code_object — same canonical path as
+// classFilterClauses uses for direct function_calls. Falls back to the
+// row's denormalized caller_class string when the parent function_call
+// has no code_object link.
+//
+// When the user supplies --package, only the code_object path is used
+// (the caller_class string has no package component to match against).
+export function sqlCallerClassClauses(input: string, qAlias: string): Clauses {
+  const parts = parseClassRef(input);
+  if (!parts.class) {
+    return { where: ['1 = 0'], params: [] };
+  }
+
+  const coWhere: string[] = [];
+  const coParams: (string | number)[] = [];
+  if (parts.class.includes('::')) {
+    coWhere.push('classes = ?');
+    coParams.push(JSON.stringify(parts.class.split('::')));
+  } else {
+    coWhere.push('leaf_class = ?');
+    coParams.push(parts.class);
+  }
+  if (parts.package) {
+    coWhere.push('package = ?');
+    coParams.push(parts.package);
+  }
+  if (parts.method) {
+    coWhere.push('method = ?');
+    coParams.push(parts.method);
+  }
+
+  const coClause = `${qAlias}.parent_event_id IN (
+    SELECT fc.event_id FROM function_calls fc
+    WHERE fc.appmap_id = ${qAlias}.appmap_id
+      AND fc.code_object_id IN (
+        SELECT id FROM code_objects WHERE ${coWhere.join(' AND ')}
+      )
+  )`;
+
+  // If the user gave an explicit package, only the code_object path can
+  // honor it (caller_class has no package column to match).
+  if (parts.package) {
+    return { where: [coClause], params: coParams };
+  }
+
+  // Fallback: match the row's raw caller_class with suffix-aware logic
+  // plus a generic substring fallback so "Repo" finds "UserRepository".
+  const fbConditions: string[] = [
+    `${qAlias}.caller_class = ?`,
+    `${qAlias}.caller_class LIKE '%.' || ?`,
+    `${qAlias}.caller_class LIKE '%::' || ?`,
+    `${qAlias}.caller_class LIKE ?`,
+  ];
+  const fbParams: (string | number)[] = [
+    parts.class,
+    parts.class,
+    parts.class,
+    `%${parts.class}%`,
+  ];
+  const fbParts: string[] = [`(${fbConditions.join(' OR ')})`];
+  if (parts.method) {
+    fbParts.push(`(${qAlias}.caller_method = ? OR ${qAlias}.caller_method LIKE ?)`);
+    fbParams.push(parts.method, `%${parts.method}%`);
+  }
+
+  // Substring leaf_class lookup against code_objects. As in
+  // classFilterClauses, only applied for short-form inputs ("Repo")
+  // so canonical fqids stay strict. (parts.package is filtered out
+  // earlier; the short-form check here is just on `::`.)
+  if (parts.class.includes('::')) {
+    return {
+      where: [`(${coClause} OR (${fbParts.join(' AND ')}))`],
+      params: [...coParams, ...fbParams],
+    };
+  }
+
+  const looseLeafClause = `${qAlias}.parent_event_id IN (
+    SELECT fc.event_id FROM function_calls fc
+    WHERE fc.appmap_id = ${qAlias}.appmap_id
+      AND fc.code_object_id IN (
+        SELECT id FROM code_objects WHERE leaf_class LIKE ?
+      )
+  )`;
+
+  return {
+    where: [`(${coClause} OR ${looseLeafClause} OR (${fbParts.join(' AND ')}))`],
+    params: [...coParams, `%${parts.class}%`, ...fbParams],
+  };
+}
+
+// Match a --method input against a sql_query via its parent function_call's
+// code_object.method, with a fallback to caller_method for unlinked
+// parents.
+export function sqlCallerMethodClauses(input: string, qAlias: string): Clauses {
+  const like = `%${input}%`;
+  return {
+    where: [
+      `(${qAlias}.parent_event_id IN (
+          SELECT fc.event_id FROM function_calls fc
+          WHERE fc.appmap_id = ${qAlias}.appmap_id
+            AND fc.code_object_id IN (
+              SELECT id FROM code_objects WHERE method = ? OR method LIKE ?
+            )
+        )
+        OR ${qAlias}.caller_method = ?
+        OR ${qAlias}.caller_method LIKE ?)`,
+    ],
+    params: [input, like, input, like],
+  };
+}
+
+// Build "<row>.appmap_id IN (SELECT a.id …)" for tables where filtering at
+// the appmap-id level is the right shape (sql_queries, function_calls,
+// exceptions, http_client_requests). Returns null if no recording-level
+// filtering is needed.
+export function appmapIdScope(
+  filter: RecordingScope,
+  rowAlias: string
+): { sql: string; params: (string | number)[] } | null {
+  const a = appmapWhere(filter, 'a');
+  const h = httpScopeClauses(filter);
+  if (a.where.length === 0 && h.where.length === 0) return null;
+
+  if (h.where.length > 0) {
+    const all = [...a.where, ...h.where].join(' AND ');
+    return {
+      sql: `${rowAlias}.appmap_id IN (
+        SELECT DISTINCT a.id FROM appmaps a
+        JOIN http_requests h ON h.appmap_id = a.id
+        WHERE ${all}
+      )`,
+      params: [...a.params, ...h.params],
+    };
+  }
+  return {
+    sql: `${rowAlias}.appmap_id IN (
+      SELECT a.id FROM appmaps a WHERE ${a.where.join(' AND ')}
+    )`,
+    params: a.params,
+  };
+}
diff --git a/packages/cli/src/cmds/query/lib/suggestSimilarFunctionIds.ts b/packages/cli/src/cmds/query/lib/suggestSimilarFunctionIds.ts
new file mode 100644
index 0000000000..9f03a52831
--- /dev/null
+++ b/packages/cli/src/cmds/query/lib/suggestSimilarFunctionIds.ts
@@ -0,0 +1,226 @@
+// Diagnostic helper for find_calls when matches = 0.
+//
+// The cost of an empty result isn't free — every retried call costs
+// cache-creation tokens for the request setup AND for adding the
+// (unhelpful) result to the conversation. Empty find_calls calls were
+// observed to make up ~30% of one fixture's tool usage, with the agent
+// guessing different identifier shapes (interface vs impl, missing `#`,
+// dot vs slash, trailing parens). This helper suggests up to 5 similar
+// function ids and explains the most likely cause so the next call lands.
+//
+// Only invoked when matches = 0 — the cost of scanning the function-id
+// index is paid only on miss. Scoring is a substring match boosted by
+// component overlap (leaf_class / method) plus a Levenshtein tiebreak;
+// no fancy ML, just enough to catch the common typos.
+
+import sqlite3 from 'better-sqlite3';
+
+import { parseClassRef } from './scope';
+
+export interface DidYouMean {
+  function_id: string;
+  calls: number;
+  // Set false when the function id appears in the classMap but never
+  // fired in any recording — distinguishes "wrong name" from
+  // "function not invoked in this trace."
+  in_index?: false;
+}
+
+export interface FindCallsDiagnostic {
+  did_you_mean: DidYouMean[];
+  hint: string;
+}
+
+const MAX_SUGGESTIONS = 5;
+// Levenshtein-only matches barely above zero produce noise (any short
+// fqid will match any short probe a little). Require some structural
+// signal — a leaf_class or method overlap, or a high Levenshtein
+// similarity — before we hand the agent a "did you mean."
+const MIN_SCORE = 30;
+
+interface CodeObjectRow {
+  fqid: string;
+  leaf_class: string;
+  method: string;
+  calls: number;
+}
+
+export function suggestSimilarFunctionIds(
+  db: sqlite3.Database,
+  className: string | undefined,
+  methodId: string | undefined
+): FindCallsDiagnostic {
+  // Probe = canonical "Class#method" reconstruction of what the agent
+  // asked for. We use it as the input to Levenshtein-style scoring.
+  const probe = composeProbe(className, methodId);
+
+  // Parse the class reference once — exposes the parts we use for both
+  // structural hints (interface-vs-impl, missing separator) and for
+  // boosting suggestions where leaf_class / method match.
+  const parts = className ? parseClassRef(className) : {};
+  const probeClass = parts.class ?? className;
+  // parseClassRef.method only fires for canonical fqid forms or `#`-form.
+  // Otherwise the explicit methodId argument carries the method.
+  const probeMethod = methodId ?? parts.method;
+
+  const rows = db
+    .prepare(
+      `SELECT co.fqid                                 AS fqid,
+              co.leaf_class                           AS leaf_class,
+              co.method                               AS method,
+              COUNT(fc.id)                            AS calls
+       FROM code_objects co
+       LEFT JOIN function_calls fc ON fc.code_object_id = co.id
+       GROUP BY co.id`
+    )
+    .all() as CodeObjectRow[];
+
+  const scored = rows
+    .map((r) => ({
+      row: r,
+      score: scoreCandidate(r, probe, probeClass, probeMethod),
+    }))
+    .filter((s) => s.score >= MIN_SCORE)
+    .sort((a, b) => b.score - a.score)
+    .slice(0, MAX_SUGGESTIONS);
+
+  const did_you_mean: DidYouMean[] = scored.map((s) => {
+    const entry: DidYouMean = { function_id: s.row.fqid, calls: s.row.calls };
+    if (s.row.calls === 0) entry.in_index = false;
+    return entry;
+  });
+
+  return {
+    did_you_mean,
+    hint: buildHint(probe, did_you_mean, scored.map((s) => s.row), probeClass, probeMethod),
+  };
+}
+
+function composeProbe(
+  className: string | undefined,
+  methodId: string | undefined
+): string {
+  if (className && methodId) {
+    // Avoid double-separators if the className already embeds a #.
+    return /[#.]/.test(className) ? className : `${className}#${methodId}`;
+  }
+  return className ?? methodId ?? '';
+}
+
+// Score a candidate higher when it shares structural fragments with
+// the probe (leaf_class substring, method exact) before falling back
+// to Levenshtein similarity. Pure scoring; no side effects.
+function scoreCandidate(
+  row: CodeObjectRow,
+  probe: string,
+  probeClass: string | undefined,
+  probeMethod: string | undefined
+): number {
+  let score = 0;
+
+  if (probeMethod && row.method === probeMethod) score += 60;
+  else if (probeMethod && row.method.toLowerCase() === probeMethod.toLowerCase()) score += 40;
+
+  if (probeClass) {
+    const lc = row.leaf_class.toLowerCase();
+    const pc = probeClass.toLowerCase();
+    if (lc === pc) score += 50;
+    else if (lc.includes(pc) || pc.includes(lc)) score += 30;
+  }
+
+  // Levenshtein-based component, capped so close-but-not-identical
+  // candidates don't overpower an exact-component match.
+  const dist = levenshtein(row.fqid.toLowerCase(), probe.toLowerCase());
+  const maxLen = Math.max(row.fqid.length, probe.length);
+  const lev = maxLen === 0 ? 0 : Math.max(0, 25 - Math.round((dist * 25) / maxLen));
+  score += lev;
+
+  return score;
+}
+
+// Detect common identifier-shape mistakes. A short hint is much cheaper
+// than another empty find_calls retry, so be specific when we can.
+function buildHint(
+  probe: string,
+  suggestions: DidYouMean[],
+  topRows: CodeObjectRow[],
+  probeClass: string | undefined,
+  probeMethod: string | undefined
+): string {
+  if (suggestions.length === 0) {
+    return (
+      `No functions matching '${probe}' fired in any recording. ` +
+      `Possible reasons: function not invoked in this trace; ` +
+      `class not in package coverage scope (check appmap.yml); typo in identifier.`
+    );
+  }
+
+  const top = suggestions[0];
+  const topRow = topRows[0];
+
+  // Interface vs Impl: top suggestion's leaf_class is the probe's class
+  // plus an "Impl" / "Default" / "Base" suffix (or the probe's class is
+  // a prefix of the top's leaf class).
+  if (probeClass && topRow.leaf_class !== probeClass) {
+    const lc = topRow.leaf_class;
+    const pc = probeClass;
+    if (
+      lc.length > pc.length &&
+      lc.toLowerCase().startsWith(pc.toLowerCase()) &&
+      /^(Impl|Default|Base|Spring|Mock)/i.test(lc.slice(pc.length))
+    ) {
+      return (
+        `Closest match: '${top.function_id}' (${top.calls} call${top.calls === 1 ? '' : 's'}). ` +
+        `'${probeClass}' looks like an interface; the runtime invokes '${lc}'.`
+      );
+    }
+  }
+
+  // FQCN with `.` instead of `/` — the canonical separator in the index
+  // is `/` between package segments.
+  if (probeClass && probeClass.includes('.') && !probeClass.includes('/')) {
+    return (
+      `Closest match: '${top.function_id}'. ` +
+      `Use slash-separated packages: 'app/services/Foo', not 'app.services.Foo'.`
+    );
+  }
+
+  // Trailing parens.
+  if (probeMethod && /\(\)?\s*$/.test(probeMethod)) {
+    return (
+      `Closest match: '${top.function_id}'. ` +
+      `Don't include parentheses; use 'Class#method' (no '()').`
+    );
+  }
+
+  // Missing # / . between class and method (probe has neither, but the
+  // top suggestion uses one).
+  if (probe && !/[#.]/.test(probe) && /[#.]/.test(top.function_id)) {
+    return (
+      `Closest match: '${top.function_id}'. ` +
+      `Use 'Class#method' for instance methods, 'Class.method' for static methods.`
+    );
+  }
+
+  return `Closest match: '${top.function_id}' (${top.calls} call${top.calls === 1 ? '' : 's'}).`;
+}
+
+// Plain DP Levenshtein. Strings here are short (<100 chars); a custom
+// implementation avoids pulling another dependency for ~30 lines of code.
+function levenshtein(a: string, b: string): number {
+  if (a === b) return 0;
+  if (a.length === 0) return b.length;
+  if (b.length === 0) return a.length;
+  let prev = new Array<number>(b.length + 1);
+  let curr = new Array<number>(b.length + 1);
+  for (let j = 0; j <= b.length; j++) prev[j] = j;
+  for (let i = 1; i <= a.length; i++) {
+    curr[0] = i;
+    for (let j = 1; j <= b.length; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      curr[j] = Math.min(curr[j - 1] + 1, prev[j] + 1, prev[j - 1] + cost);
+    }
+    [prev, curr] = [curr, prev];
+  }
+  return prev[b.length];
+}
diff --git a/packages/cli/src/cmds/query/lib/treeRender.ts b/packages/cli/src/cmds/query/lib/treeRender.ts
new file mode 100644
index 0000000000..d47b96b07e
--- /dev/null
+++ b/packages/cli/src/cmds/query/lib/treeRender.ts
@@ -0,0 +1,523 @@
+import {
+  ExceptionNode,
+  FunctionNode,
+  HttpClientNode,
+  HttpServerNode,
+  LogNode,
+  SqlNode,
+  TreeNode,
+  TreeSummary,
+} from '../queries/tree';
+import { formatCount, formatMs, formatTable } from './format';
+import { projectLogMessage } from './logMessage';
+
+const INDENT = '  ';
+
+// Render the full tree. Each event is one line; depth maps to indentation.
+// Format mirrors V3:
+//   HTTP→  POST /orders → HTTP 500 [520ms]
+//     CALL  app/.../OrdersController#create [519ms]
+//     SQL   INSERT INTO orders (...) [14ms]
+//     EXC   IntegrityError: duplicate key
+//     HTTP← GET https://api.example/v1 → 200 [40ms]
+export function renderTree(nodes: readonly TreeNode[]): string {
+  return nodes.map(renderTreeLine).join('\n');
+}
+
+function renderTreeLine(node: TreeNode): string {
+  const indent = INDENT.repeat(node.depth);
+  switch (node.kind) {
+    case 'http_server':
+      return `${indent}HTTP→  ${renderHttpServer(node)}`;
+    case 'http_client':
+      return `${indent}HTTP←  ${renderHttpClient(node)}`;
+    case 'function':
+      return `${indent}CALL   ${renderFunction(node)}`;
+    case 'sql':
+      return `${indent}SQL    ${renderSql(node)}`;
+    case 'exception':
+      return `${indent}EXC    ${renderException(node)}`;
+    case 'log':
+      return `${indent}LOG    ${renderLog(node)}`;
+  }
+}
+
+function renderException(n: ExceptionNode): string {
+  const where = n.path ? ` @ ${n.path}${n.lineno != null ? `:${n.lineno}` : ''}` : '';
+  return `${n.exception_class}${n.message ? `: ${n.message}` : ''}${where}`;
+}
+
+function renderHttpServer(n: HttpServerNode): string {
+  return `${n.method} ${n.route} → HTTP ${n.status_code} ${bracket(n.elapsed_ms)}`.trim();
+}
+
+function renderHttpClient(n: HttpClientNode): string {
+  const status = n.status_code != null ? ` → ${n.status_code}` : '';
+  return `${n.method} ${n.url}${status} ${bracket(n.elapsed_ms)}`.trim();
+}
+
+function renderFunction(n: FunctionNode): string {
+  const id = n.fqid ?? `${n.defined_class}${n.is_static ? '.' : '#'}${n.method_id}`;
+  const ret = n.return_value != null ? `  → ${n.return_value}` : '';
+  return `${id} ${bracket(n.elapsed_ms)}${ret}`.trim();
+}
+
+function renderSql(n: SqlNode): string {
+  return `${truncate(n.sql_text, 120)} ${bracket(n.elapsed_ms)}`.trim();
+}
+
+function renderLog(n: LogNode): string {
+  const message = projectLogMessage(n.parameters_json, n.return_value);
+  const prefix = `${n.logger}.${n.method_id}`;
+  return message ? `${prefix}: ${truncate(message, 120)}` : prefix;
+}
+
+function bracket(ms: number | null): string {
+  return ms == null ? '' : `[${formatMs(ms)}]`;
+}
+
+function truncate(s: string, n: number): string {
+  return s.length <= n ? s : s.slice(0, n - 1) + '…';
+}
+
+// Dense one-line-per-event rendering for MCP responses. Each line starts
+// with the event_id (so the agent can drill via find_calls/find_queries)
+// and includes file:line for source-reading without a follow-up call.
+// Carries a truncated return value inline — the cheapest evidence that
+// distinguishes sibling calls (e.g. two builders stamping different
+// timestamps) — but drops parameters; agents query specific event_ids
+// or `format=json` for full, untruncated detail.
+export function renderTreeForMcp(nodes: readonly TreeNode[]): string {
+  return nodes.map(renderTreeLineForMcp).join('\n');
+}
+
+function renderTreeLineForMcp(node: TreeNode): string {
+  const indent = INDENT.repeat(node.depth);
+  const id = `#${node.event_id}`;
+  switch (node.kind) {
+    case 'http_server':
+      return `${indent}${id} HTTP→ ${renderHttpServer(node)}`;
+    case 'http_client':
+      return `${indent}${id} HTTP← ${renderHttpClient(node)}`;
+    case 'function':
+      return `${indent}${id} CALL  ${renderFunctionForMcp(node)}`;
+    case 'sql':
+      return `${indent}${id} SQL   ${renderSql(node)}`;
+    case 'exception':
+      return `${indent}${id} EXC   ${renderException(node)}`;
+    case 'log':
+      return `${indent}${id} LOG   ${renderLog(node)}`;
+  }
+}
+
+// Return values in the dense MCP tree are truncated value-aware, not by a
+// flat prefix cut. A flat cut wastes the budget on identity fields — a
+// record like `ApprovalRequest[requestId=<uuid>, loanId=<uuid>,
+// status=APPROVED, …]` spends ~80 chars on two UUIDs before reaching the
+// state field that actually distinguishes the call. truncateStructValue
+// parses the struct shape and budgets *per field value*, clipping
+// id/hash-shaped values hard so semantic fields downstream survive.
+export interface StructBudget {
+  perValueCap: number; // max chars for an ordinary field value
+  idCap: number; // max chars for a uuid/hash-shaped value (identity, low signal)
+  maxFields: number; // fields rendered before the tail is elided
+  flatCap: number; // flat cap applied to non-struct strings
+}
+
+export const MCP_RETURN_VALUE_BUDGET: StructBudget = {
+  perValueCap: 48,
+  idCap: 12,
+  maxFields: 16,
+  flatCap: 120,
+};
+
+// A uuid, a hex object hash (`@1a2b3c4`, `0x00007f…`), or either prefixed
+// by a short tag (`LOAN-<uuid>`, `PID-<uuid>`). These are identity, not
+// state — low root-cause signal — so they get the tight idCap.
+const ID_VALUE_RE =
+  /(?:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}|(?:@|0x)[0-9a-f]{4,})/i;
+
+const CLOSE_FOR: Record<string, string> = { '[': ']', '{': '}', '(': ')' };
+
+interface Struct {
+  prefix: string; // leading type name (may be empty for a bare collection)
+  open: string; // opening delimiter
+  body: string; // comma-separated field list
+  close: string; // closing delimiter
+}
+
+// Recognize the toString()/repr shapes AppMap captures across the four
+// supported languages:
+//   Java record / Python repr   Type[…]  /  Type(…)
+//   Java bean / JS-ish object   Type{…}  /  {…}
+//   Ruby                        #<Type …>
+// Returns null for primitives, `[object Object]`-style opaque values, and
+// `Type@1a2b3c` hashes — those fall back to a flat truncation.
+function parseStruct(s: string): Struct | null {
+  const ruby = /^#<([^\s>]+)\s+(.+)>$/.exec(s);
+  if (ruby) return { prefix: `#<${ruby[1]} `, open: '', body: ruby[2], close: '>' };
+  const m = /^([A-Za-z_][\w.$]*)?([[{(])([\s\S]*)([\]})])$/.exec(s);
+  if (m && CLOSE_FOR[m[2]] === m[4]) {
+    return { prefix: m[1] ?? '', open: m[2], body: m[3], close: m[4] };
+  }
+  return null;
+}
+
+// Split a struct body on top-level ", ". Commas nested inside [], {}, (),
+// or <> belong to a field's own value and must not split it.
+function splitTopLevelFields(body: string): string[] {
+  if (body.length === 0) return [];
+  const out: string[] = [];
+  let depth = 0;
+  let start = 0;
+  for (let i = 0; i < body.length; i++) {
+    const c = body[i];
+    if (c === '[' || c === '{' || c === '(' || c === '<') depth++;
+    else if (c === ']' || c === '}' || c === ')' || c === '>') depth = Math.max(0, depth - 1);
+    else if (c === ',' && depth === 0 && body[i + 1] === ' ') {
+      out.push(body.slice(start, i));
+      start = i + 2;
+      i++;
+    }
+  }
+  out.push(body.slice(start));
+  return out;
+}
+
+// A field value that is itself a struct (a nested record, or an element
+// of a collection-of-records like `getParticipants`) recurses so its own
+// fields get the per-field budget too — flat-clipping it would collapse
+// `[ParticipantState[…status=PENDING], …]` down to an opaque stub. Depth
+// is bounded so a pathologically deep value can't recurse without end.
+const MAX_STRUCT_DEPTH = 4;
+
+// Truncate one field value: recurse if it is itself a struct, else
+// id/hash-shaped values get the tight idCap and all others the perValueCap.
+function truncateFieldValue(value: string, budget: StructBudget, depth: number): string {
+  if (depth < MAX_STRUCT_DEPTH) {
+    const nested = parseStruct(value);
+    if (nested) return renderStruct(nested, budget, depth + 1);
+  }
+  const cap = ID_VALUE_RE.test(value) ? budget.idCap : budget.perValueCap;
+  return truncate(value, cap);
+}
+
+// Truncate one `name=value` / `name: value` field, keeping the name whole
+// and budgeting only the value. A field with no recognizable name
+// separator (a bare collection element) is budgeted as a whole value.
+function truncateField(field: string, budget: StructBudget, depth: number): string {
+  const m = /^(\s*[\w$]+\s*)([:=])(\s*)([\s\S]*)$/.exec(field);
+  if (!m) return truncateFieldValue(field, budget, depth);
+  return `${m[1]}${m[2]}${m[3]}${truncateFieldValue(m[4], budget, depth)}`;
+}
+
+function renderStruct(st: Struct, budget: StructBudget, depth: number): string {
+  const fields = splitTopLevelFields(st.body);
+  const kept = fields.slice(0, budget.maxFields).map((f) => truncateField(f, budget, depth));
+  const elided = fields.length - kept.length;
+  const tail = elided > 0 ? `${kept.length > 0 ? ', ' : ''}…+${elided} more` : '';
+  return `${st.prefix}${st.open}${kept.join(', ')}${tail}${st.close}`;
+}
+
+// Value-aware truncation for a captured return value / parameter. Parses
+// the struct shape and budgets per field value, recursing into nested
+// structs; non-struct strings fall back to a flat cap. See StructBudget.
+export function truncateStructValue(
+  s: string,
+  budget: StructBudget = MCP_RETURN_VALUE_BUDGET
+): string {
+  const st = parseStruct(s);
+  if (!st) return truncate(s, budget.flatCap);
+  return renderStruct(st, budget, 1);
+}
+
+function renderFunctionForMcp(n: FunctionNode): string {
+  const id = n.fqid ?? `${n.defined_class}${n.is_static ? '.' : '#'}${n.method_id}`;
+  const where =
+    n.path != null ? ` (${n.path}${n.lineno != null ? `:${n.lineno}` : ''})` : '';
+  const ret = n.return_value != null ? `  → ${truncateStructValue(n.return_value)}` : '';
+  return `${id}${where} ${bracket(n.elapsed_ms)}${ret}`.trim();
+}
+
+export interface BudgetedRenderResult {
+  tree: string;
+  rendered_events: number;
+  clipped_events: number;
+  clipped_bytes: number;
+  cutoff_depth: number;       // last depth fully rendered (-1 if no depth fully fit)
+  partial_depth: number;      // depth at which partial fill happened (-1 if none)
+  bytes_used: number;
+}
+
+// Byte-budgeted breadth-first rendering. Fills the budget level-by-level
+// (all of depth 0, then all of depth 1, ...); when an entire layer
+// doesn't fit, partial-fills that layer in event_id order. Subtrees
+// whose descendants were clipped get an inline marker showing the
+// clipped count + bytes so the agent knows where to drill.
+export function renderTreeForMcpBudgeted(
+  nodes: readonly TreeNode[],
+  budget: number
+): BudgetedRenderResult {
+  if (nodes.length === 0) {
+    return {
+      tree: '',
+      rendered_events: 0,
+      clipped_events: 0,
+      clipped_bytes: 0,
+      cutoff_depth: -1,
+      partial_depth: -1,
+      bytes_used: 0,
+    };
+  }
+
+  // Dedupe by event_id: the upstream tree query emits separate rows for
+  // a function call and the exception it threw (same event_id). For
+  // breadth-first byte accounting we want one node per event_id, so
+  // collapse to a deterministic representative — first occurrence wins.
+  const seen = new Set<number>();
+  const dedupedNodes: TreeNode[] = [];
+  for (const n of nodes) {
+    if (seen.has(n.event_id)) continue;
+    seen.add(n.event_id);
+    dedupedNodes.push(n);
+  }
+
+  const byId = new Map<number, TreeNode>();
+  const childrenOf = new Map<number, number[]>();
+  const roots: number[] = [];
+  const lineFor = new Map<number, string>();
+  const lineBytes = new Map<number, number>();
+  const nodesAtDepth = new Map<number, number[]>();
+  let maxDepth = 0;
+
+  for (const n of dedupedNodes) {
+    byId.set(n.event_id, n);
+    const line = renderTreeLineForMcp(n);
+    lineFor.set(n.event_id, line);
+    lineBytes.set(n.event_id, line.length + 1);
+    if (n.depth > maxDepth) maxDepth = n.depth;
+    const dArr = nodesAtDepth.get(n.depth) ?? [];
+    dArr.push(n.event_id);
+    nodesAtDepth.set(n.depth, dArr);
+  }
+  for (const arr of nodesAtDepth.values()) arr.sort((a, b) => a - b);
+
+  for (const n of dedupedNodes) {
+    if (n.parent_event_id !== null && byId.has(n.parent_event_id)) {
+      const arr = childrenOf.get(n.parent_event_id) ?? [];
+      arr.push(n.event_id);
+      childrenOf.set(n.parent_event_id, arr);
+    } else {
+      roots.push(n.event_id);
+    }
+  }
+  for (const arr of childrenOf.values()) arr.sort((a, b) => a - b);
+  roots.sort((a, b) => a - b);
+
+  // Reserve roughly 80 bytes per potential clip marker. One marker per
+  // node at the cutoff depth that has children; we don't know which
+  // yet, so reserve based on node count at cutoff candidates.
+  const MARKER_RESERVE_PER = 80;
+
+  // Cumulative line bytes through each depth.
+  const bytesThroughDepth: number[] = [];
+  let cum = 0;
+  for (let d = 0; d <= maxDepth; d++) {
+    for (const id of nodesAtDepth.get(d) ?? []) cum += lineBytes.get(id) ?? 0;
+    bytesThroughDepth[d] = cum;
+  }
+
+  // Pick the deepest D such that depth-≤D fits, leaving room for clip
+  // markers under each depth-D node that still has children at D+1.
+  let cutoff = -1;
+  for (let d = 0; d <= maxDepth; d++) {
+    const parentsWithKids = (nodesAtDepth.get(d) ?? []).filter(
+      (id) => (childrenOf.get(id) ?? []).length > 0
+    ).length;
+    const projected = bytesThroughDepth[d] + parentsWithKids * MARKER_RESERVE_PER;
+    if (projected <= budget) cutoff = d;
+    else break;
+  }
+
+  const rendered = new Set<number>();
+  // All events through cutoff depth are rendered.
+  for (let d = 0; d <= cutoff; d++) {
+    for (const id of nodesAtDepth.get(d) ?? []) rendered.add(id);
+  }
+
+  // Partial fill at cutoff+1 in event_id order while residual budget
+  // permits. The cutoff projection already accounted for cutoff-layer
+  // marker reserve, but we don't subtract it here a second time — that
+  // would shut partial fill off in the squeezed zone where cutoff
+  // barely fits.  The trade-off is a small (≤ markers × ~80 bytes)
+  // over-budget slop in the final rendered size; agents see this in
+  // `bytes_used` and can re-request with a lower max_chars if needed.
+  let partialDepth = -1;
+  const bytesUsedThroughCutoff = cutoff >= 0 ? bytesThroughDepth[cutoff] : 0;
+  let residual = budget - bytesUsedThroughCutoff;
+  if (cutoff + 1 <= maxDepth) {
+    const partialCandidates = nodesAtDepth.get(cutoff + 1) ?? [];
+    for (const id of partialCandidates) {
+      const lb = lineBytes.get(id) ?? 0;
+      // Reserve marker cost for this event's potential subtree clip too.
+      const hasKids = (childrenOf.get(id) ?? []).length > 0;
+      const cost = lb + (hasKids ? MARKER_RESERVE_PER : 0);
+      if (cost <= residual) {
+        rendered.add(id);
+        residual -= cost;
+        if (partialDepth === -1) partialDepth = cutoff + 1;
+      } else {
+        break;
+      }
+    }
+  }
+
+  // If no depth-0 events fit, emit at least one as best-effort so the
+  // agent sees something. Mark the rest clipped.
+  if (cutoff === -1 && rendered.size === 0 && roots.length > 0) {
+    rendered.add(roots[0]);
+  }
+
+  // Pre-compute per-node "all-descendant" totals for fast clip math.
+  const allDescendantCount = new Map<number, number>();
+  const allDescendantBytes = new Map<number, number>();
+  function computeTotals(id: number): { count: number; bytes: number } {
+    let c = 0;
+    let b = 0;
+    for (const k of childrenOf.get(id) ?? []) {
+      const sub = computeTotals(k);
+      c += 1 + sub.count;
+      b += (lineBytes.get(k) ?? 0) + sub.bytes;
+    }
+    allDescendantCount.set(id, c);
+    allDescendantBytes.set(id, b);
+    return { count: c, bytes: b };
+  }
+  for (const r of roots) computeTotals(r);
+
+  // Walk DFS preorder, emit rendered lines, emit a clip marker beneath a
+  // node when any of its descendants is unrendered.
+  const out: string[] = [];
+  let clippedEvents = 0;
+  let clippedBytes = 0;
+
+  // For clip-marker totals, count only direct unrendered children (and
+  // their subtrees) — not transitive ones that already produced their
+  // own marker beneath an inner rendered node. This avoids the same
+  // clip being reported at every ancestor in a linear chain.
+  function directlyClippedSubtree(id: number): { count: number; bytes: number } {
+    let c = 0;
+    let b = 0;
+    for (const k of childrenOf.get(id) ?? []) {
+      if (!rendered.has(k)) {
+        c += 1 + (allDescendantCount.get(k) ?? 0);
+        b += (lineBytes.get(k) ?? 0) + (allDescendantBytes.get(k) ?? 0);
+      }
+    }
+    return { count: c, bytes: b };
+  }
+
+  function walk(id: number): void {
+    if (!rendered.has(id)) return;
+    out.push(lineFor.get(id) ?? '');
+    for (const k of childrenOf.get(id) ?? []) walk(k);
+    const clip = directlyClippedSubtree(id);
+    if (clip.count > 0) {
+      const node = byId.get(id);
+      const childDepth = (node?.depth ?? 0) + 1;
+      const indent = INDENT.repeat(childDepth);
+      out.push(
+        `${indent}... [clipped: ${clip.count} events, ${clip.bytes} bytes; drill via child_depth=${childDepth + 1} or focus on #${id}]`
+      );
+    }
+  }
+
+  for (const r of roots) walk(r);
+
+  // Top-level totals: total events - rendered = clipped.
+  let totalBytes = 0;
+  for (const lb of lineBytes.values()) totalBytes += lb;
+  let renderedBytes = 0;
+  for (const id of rendered) renderedBytes += lineBytes.get(id) ?? 0;
+  clippedEvents = dedupedNodes.length - rendered.size;
+  clippedBytes = totalBytes - renderedBytes;
+
+  const tree = out.join('\n');
+  return {
+    tree,
+    rendered_events: rendered.size,
+    clipped_events: clippedEvents,
+    clipped_bytes: clippedBytes,
+    cutoff_depth: cutoff,
+    partial_depth: partialDepth,
+    bytes_used: tree.length,
+  };
+}
+
+// Flat rendering — used by --filter=sql and --filter=http (no indentation,
+// just the matching events in order).
+export function renderFlat(nodes: readonly TreeNode[]): string {
+  return nodes
+    .map((n) => {
+      switch (n.kind) {
+        case 'http_server':
+          return `HTTP→  ${renderHttpServer(n)}`;
+        case 'http_client':
+          return `HTTP←  ${renderHttpClient(n)}`;
+        case 'sql':
+          return `SQL    ${renderSql(n)}`;
+        case 'function':
+          return `CALL   ${renderFunction(n)}`;
+        case 'exception':
+          return `EXC    ${renderException(n)}`;
+        case 'log':
+          return `LOG    ${renderLog(n)}`;
+      }
+    })
+    .join('\n');
+}
+
+// Summary format: per V3, a one-screen overview without the tree.
+//   ENTRY      POST /orders → 500 [520ms]
+//   SQL        3 queries, 19ms total
+//   EXCEPTION  IntegrityError
+//   LABELS     log×2, dao×3, security.idempotency×1
+export function renderSummary(s: TreeSummary): string {
+  const rows: [string, string][] = [];
+
+  if (s.entry) {
+    rows.push([
+      'ENTRY',
+      `${s.entry.method} ${s.entry.route} → ${s.entry.status_code} ${bracket(s.entry.elapsed_ms)}`,
+    ]);
+  }
+
+  if (s.sql.count > 0) {
+    rows.push([
+      'SQL',
+      `${formatCount(s.sql.count)} quer${s.sql.count === 1 ? 'y' : 'ies'}, ${formatMs(s.sql.total_ms)} total`,
+    ]);
+  }
+
+  if (s.http_client.count > 0) {
+    rows.push([
+      'HTTP→OUT',
+      `${formatCount(s.http_client.count)} request${s.http_client.count === 1 ? '' : 's'}, ${formatMs(s.http_client.total_ms)} total`,
+    ]);
+  }
+
+  for (const e of s.exceptions) {
+    const where = e.path ? ` @ ${e.path}${e.lineno != null ? `:${e.lineno}` : ''}` : '';
+    rows.push([
+      'EXCEPTION',
+      e.exception_class + (e.message ? `: ${e.message}` : '') + where,
+    ]);
+  }
+
+  if (s.labels.length > 0) {
+    const text = s.labels.map((l) => `${l.label}×${l.count}`).join(', ');
+    rows.push(['LABELS', text]);
+  }
+
+  return formatTable(['', ''], rows);
+}
diff --git a/packages/cli/src/cmds/query/lib/uiServer.ts b/packages/cli/src/cmds/query/lib/uiServer.ts
new file mode 100644
index 0000000000..6793ab0f88
--- /dev/null
+++ b/packages/cli/src/cmds/query/lib/uiServer.ts
@@ -0,0 +1,594 @@
+// HTTP server for `appmap query ui`.
+//
+// Express adapter that exposes the typed query functions (find_*,
+// endpoints, hotspots, tree, related, compare, dashboard) as a small
+// JSON REST surface on top of a read-only query.db. The `/api/*` routes
+// are thin pass-throughs over the existing query layer; the server also
+// serves the React SPA bundle from `staticDir` and falls through to
+// index.html for SPA routes.
+
+import express, { Request, Response, NextFunction } from 'express';
+import cors from 'cors';
+import { existsSync, statSync } from 'fs';
+import { Server } from 'http';
+import path from 'path';
+
+import sqlite3 from 'better-sqlite3';
+
+import { compare } from '../queries/compare';
+import { dashboardTotals } from '../queries/dashboard';
+import { endpoints, EndpointSort, EndpointsFilter } from '../queries/endpoints';
+import { find, FindAppmapRow, FindFilter } from '../queries/find';
+import { hotspots, HotspotsFilter } from '../queries/hotspots';
+import { related, RelatedFilter } from '../queries/related';
+import { treeWithMeta, TreeOptions } from '../queries/tree';
+import { Page } from './page';
+import { parseDuration, parseStatus, parseTime } from './parseFilter';
+import { decorateRecording, resolveAppmapPath } from './recordingId';
+
+export interface UIServerOptions {
+  db: sqlite3.Database;
+  // 0 (or undefined) means "let the OS pick a free port".
+  port?: number;
+  // Absolute path to the built SPA. If the directory or its index.html
+  // doesn't exist, the server still runs (the API works) and the root
+  // path returns a build-instruction message instead of 500-ing.
+  staticDir: string;
+}
+
+export interface UIServerHandle {
+  server: Server;
+  port: number;
+  url: string;
+  close: () => Promise<void>;
+}
+
+function maybeString(v: unknown): string | undefined {
+  return typeof v === 'string' && v.length > 0 ? v : undefined;
+}
+
+function maybeNumber(v: unknown): number | undefined {
+  if (typeof v === 'string' && /^-?\d+$/.test(v)) return Number.parseInt(v, 10);
+  return undefined;
+}
+
+function maybeTime(v: unknown): string | undefined {
+  return typeof v === 'string' && v.length > 0 ? parseTime(v) : undefined;
+}
+
+// Build a FindFilter from query-string params. Mirrors the parser in
+// queries/mcp.ts buildFindFilter, adapted for HTTP query strings (where
+// every value is a string before parse).
+function buildFindFilter(req: Request): FindFilter {
+  const q = req.query;
+  const f: FindFilter = {};
+  f.route = maybeString(q.route);
+  f.className = maybeString(q.class);
+  f.method = maybeString(q.method);
+  f.label = maybeString(q.label);
+  f.branch = maybeString(q.branch);
+  f.commit = maybeString(q.commit);
+  f.appmap = maybeString(q.appmap);
+  f.table = maybeString(q.table);
+  f.exception = maybeString(q.exception);
+  f.logger = maybeString(q.logger);
+  f.message = maybeString(q.message);
+  const status = maybeString(q.status);
+  if (status) f.status = parseStatus(status);
+  const duration = maybeString(q.duration);
+  if (duration) f.duration = parseDuration(duration);
+  f.since = maybeTime(q.since);
+  f.until = maybeTime(q.until);
+  f.limit = maybeNumber(q.limit);
+  f.offset = maybeNumber(q.offset);
+  const withLogs = maybeNumber(q.with_logs);
+  if (withLogs !== undefined) f.withLogs = withLogs;
+  return f;
+}
+
+// Wrap a sync handler so any thrown Error becomes a 400 JSON response.
+// Filter parsers (parseStatus, parseTime) throw on bad input — surface
+// the message so the client sees what's wrong without a 500.
+function wrap(handler: (req: Request, res: Response) => void) {
+  return (req: Request, res: Response, _next: NextFunction): void => {
+    try {
+      handler(req, res);
+    } catch (err) {
+      res.status(400).json({ error: (err as Error).message });
+    }
+  };
+}
+
+export function buildUIApp(opts: UIServerOptions): express.Express {
+  const { db, staticDir } = opts;
+  const app = express();
+  app.use(cors());
+
+  // ---- aggregations -----------------------------------------------------
+
+  app.get(
+    '/api/dashboard',
+    wrap((_req, res) => {
+      res.json(dashboardTotals(db));
+    })
+  );
+
+  app.get(
+    '/api/endpoints',
+    wrap((req, res) => {
+      const f: EndpointsFilter = {};
+      f.branch = maybeString(req.query.branch);
+      f.since = maybeTime(req.query.since);
+      f.until = maybeTime(req.query.until);
+      const status = maybeString(req.query.status);
+      if (status) f.status = parseStatus(status);
+      const sort = maybeString(req.query.sort);
+      if (sort) f.sort = sort as EndpointSort;
+      f.limit = maybeNumber(req.query.limit);
+      f.offset = maybeNumber(req.query.offset);
+      res.json(endpoints(db, f));
+    })
+  );
+
+  // /api/functions/hotspots and /api/sql/hotspots both back onto
+  // hotspots() with a different `type`. Splitting paths so the UI's
+  // routing maps cleanly to the page surface.
+  app.get(
+    '/api/functions/hotspots',
+    wrap((req, res) => {
+      const f: HotspotsFilter = { type: 'function' };
+      f.className = maybeString(req.query.class);
+      f.appmap = maybeString(req.query.appmap);
+      f.limit = maybeNumber(req.query.limit);
+      f.offset = maybeNumber(req.query.offset);
+      res.json(hotspots(db, f));
+    })
+  );
+
+  app.get(
+    '/api/sql/hotspots',
+    wrap((req, res) => {
+      const f: HotspotsFilter = { type: 'sql' };
+      f.appmap = maybeString(req.query.appmap);
+      f.limit = maybeNumber(req.query.limit);
+      f.offset = maybeNumber(req.query.offset);
+      res.json(hotspots(db, f));
+    })
+  );
+
+  app.get(
+    '/api/labels',
+    wrap((_req, res) => {
+      const rows = db
+        .prepare(
+          `SELECT l.label                  AS label,
+                  COUNT(DISTINCT co.id)    AS count,
+                  MIN(co.fqid)             AS sample_fqid
+           FROM labels l
+           JOIN code_objects co ON co.id = l.code_object_id
+           GROUP BY l.label
+           ORDER BY count DESC, l.label`
+        )
+        .all();
+      res.json(rows);
+    })
+  );
+
+  // ---- row-level finders ------------------------------------------------
+
+  app.get(
+    '/api/recordings',
+    wrap((req, res) => {
+      const filter = buildFindFilter(req);
+      const page = find(db, 'appmaps', filter) as Page<FindAppmapRow>;
+      res.json({ ...page, rows: page.rows.map((r) => decorateRecording(r)) });
+    })
+  );
+
+  app.get(
+    '/api/requests',
+    wrap((req, res) => {
+      res.json(find(db, 'requests', buildFindFilter(req)));
+    })
+  );
+
+  app.get(
+    '/api/queries',
+    wrap((req, res) => {
+      res.json(find(db, 'queries', buildFindFilter(req)));
+    })
+  );
+
+  app.get(
+    '/api/calls',
+    wrap((req, res) => {
+      res.json(find(db, 'calls', buildFindFilter(req)));
+    })
+  );
+
+  app.get(
+    '/api/logs',
+    wrap((req, res) => {
+      res.json(find(db, 'logs', buildFindFilter(req)));
+    })
+  );
+
+  app.get(
+    '/api/exceptions',
+    wrap((req, res) => {
+      const filter = buildFindFilter(req);
+      // Default to attaching 5 preceding logs per exception so the UI
+      // can show a "what did the app log before the throw?" panel
+      // without a follow-up call. Caller can override with
+      // ?with_logs=N (or 0 to disable).
+      if (filter.withLogs === undefined) filter.withLogs = 5;
+      res.json(find(db, 'exceptions', filter));
+    })
+  );
+
+  // ---- per-recording / cross-recording ---------------------------------
+
+  app.get(
+    '/api/recording',
+    wrap((req, res) => {
+      const ref = maybeString(req.query.appmap);
+      if (!ref) {
+        res.status(400).json({ error: 'appmap query parameter is required' });
+        return;
+      }
+      const am = resolveAppmapPath(db, ref);
+      // Single-recording metadata + per-table counts. The UI's detail
+      // page renders this header above the embedded viewer iframe.
+      const row = db
+        .prepare(
+          `SELECT id, name, source_path, language, framework, recorder_type,
+                  git_repository, git_branch, git_commit, timestamp,
+                  event_count, sql_query_count, http_request_count, elapsed_ms
+             FROM appmaps WHERE id = ?`
+        )
+        .get(am.id) as Record<string, unknown>;
+      const counts = db
+        .prepare(
+          `SELECT
+             (SELECT COUNT(*) FROM http_requests        WHERE appmap_id = ?) AS http_requests,
+             (SELECT COUNT(*) FROM http_client_requests WHERE appmap_id = ?) AS http_client_requests,
+             (SELECT COUNT(*) FROM sql_queries          WHERE appmap_id = ? AND sql_text NOT IN ('BEGIN','COMMIT')) AS sql_queries,
+             (SELECT COUNT(*) FROM function_calls       WHERE appmap_id = ?) AS function_calls,
+             (SELECT COUNT(*) FROM exceptions           WHERE appmap_id = ?) AS exceptions`
+        )
+        .get(am.id, am.id, am.id, am.id, am.id) as Record<string, number>;
+      res.json({ recording: { ...row, path: am.source_path, label: am.name }, counts });
+    })
+  );
+
+  app.get(
+    '/api/tree',
+    wrap((req, res) => {
+      const ref = maybeString(req.query.appmap);
+      if (!ref) {
+        res.status(400).json({ error: 'appmap query parameter is required' });
+        return;
+      }
+      const am = resolveAppmapPath(db, ref);
+      const opts: TreeOptions = {};
+      const focusType = maybeString(req.query.focus_type);
+      const focusValue = maybeString(req.query.focus_value);
+      if (focusType && focusValue) {
+        if (focusType === 'function') opts.focusFn = focusValue;
+        else if (focusType === 'sql_query') opts.focusSql = focusValue;
+        else if (focusType === 'http_server_request') opts.focusRoute = focusValue;
+        else if (focusType === 'http_client_request') opts.focusUrl = focusValue;
+      }
+      opts.ancestors = maybeNumber(req.query.parent_depth);
+      opts.descendants = maybeNumber(req.query.child_depth);
+      const minMs = maybeNumber(req.query.min_elapsed_ms);
+      if (minMs !== undefined) opts.minElapsedMs = minMs;
+      res.json(treeWithMeta(db, am.source_path, opts));
+    })
+  );
+
+  app.get(
+    '/api/related',
+    wrap((req, res) => {
+      const ref = maybeString(req.query.appmap);
+      if (!ref) {
+        res.status(400).json({ error: 'appmap query parameter is required' });
+        return;
+      }
+      const am = resolveAppmapPath(db, ref);
+      const filter: RelatedFilter = {};
+      const status = maybeString(req.query.status);
+      if (status) filter.status = parseStatus(status);
+      filter.route = maybeString(req.query.route);
+      filter.branch = maybeString(req.query.branch);
+      filter.since = maybeTime(req.query.since);
+      filter.until = maybeTime(req.query.until);
+      filter.limit = maybeNumber(req.query.limit);
+      filter.offset = maybeNumber(req.query.offset);
+      res.json(related(db, am.source_path, filter));
+    })
+  );
+
+  app.get(
+    '/api/compare',
+    wrap((req, res) => {
+      const a = maybeString(req.query.branch_a);
+      const b = maybeString(req.query.branch_b);
+      if (!a || !b) {
+        res.status(400).json({ error: 'branch_a and branch_b query parameters are required' });
+        return;
+      }
+      const sort = maybeString(req.query.sort);
+      res.json(
+        compare(db, {
+          branch_a: a,
+          branch_b: b,
+          since: maybeTime(req.query.since),
+          until: maybeTime(req.query.until),
+          sort: sort as 'delta' | 'p95-a' | 'p95-b' | undefined,
+          limit: maybeNumber(req.query.limit),
+          offset: maybeNumber(req.query.offset),
+        })
+      );
+    })
+  );
+
+  // ---- structured search (multi-entity fanout) -------------------------
+  //
+  // Lightweight parser for the apm-style query syntax. We feed each
+  // recognized filter into the relevant typed find_* function and return
+  // a single composite result.
+
+  app.get(
+    '/api/search',
+    wrap((req, res) => {
+      const q = maybeString(req.query.q) ?? '';
+      const limit = maybeNumber(req.query.limit) ?? 25;
+      const filters = parseSearchQuery(q);
+
+      const result: Record<string, unknown> = { query: q, filters };
+
+      const baseFilter = (): FindFilter => {
+        const f: FindFilter = { limit };
+        if (filters.branch) f.branch = filters.branch;
+        if (filters.commit) f.commit = filters.commit;
+        if (filters.since) f.since = filters.since;
+        if (filters.until) f.until = filters.until;
+        if (filters.appmap) f.appmap = filters.appmap;
+        if (filters.duration) f.duration = parseDuration(filters.duration);
+        if (filters.status) f.status = parseStatus(filters.status);
+        return f;
+      };
+
+      // HTTP requests
+      const reqFilter = baseFilter();
+      if (filters.path) reqFilter.route = filters.path;
+      if (filters.method && filters.path) reqFilter.route = `${filters.method} ${filters.path}`;
+      if (filters.text && !reqFilter.route) reqFilter.route = filters.text;
+      if (reqFilter.route || filters.status || filters.duration) {
+        result.requests = find(db, 'requests', reqFilter);
+      }
+
+      // SQL queries
+      const sqlFilter = baseFilter();
+      if (filters.table) sqlFilter.table = filters.table;
+      if (filters.sql) sqlFilter.table = filters.sql; // table acts as substring
+      if (filters.text && !sqlFilter.table) sqlFilter.table = filters.text;
+      if (sqlFilter.table || filters.duration) {
+        result.queries = find(db, 'queries', sqlFilter);
+      }
+
+      // Function calls
+      const callFilter = baseFilter();
+      if (filters.class) callFilter.className = filters.class;
+      if (filters.function) callFilter.method = filters.function;
+      if (filters.label) callFilter.label = filters.label;
+      if (filters.text && !callFilter.className && !callFilter.method && !callFilter.label) {
+        callFilter.className = filters.text;
+      }
+      if (callFilter.className || callFilter.method || callFilter.label) {
+        result.calls = find(db, 'calls', callFilter);
+      }
+
+      // Exceptions
+      const excFilter = baseFilter();
+      if (filters.exception) excFilter.exception = filters.exception;
+      if (filters.text && !excFilter.exception) excFilter.exception = filters.text;
+      if (excFilter.exception) {
+        result.exceptions = find(db, 'exceptions', excFilter);
+      }
+
+      // Recordings (always include if no other entity filter narrowed)
+      if (
+        !result.requests &&
+        !result.queries &&
+        !result.calls &&
+        !result.exceptions
+      ) {
+        const recFilter = baseFilter();
+        if (filters.text) recFilter.appmap = filters.text;
+        const page = find(db, 'appmaps', recFilter) as Page<FindAppmapRow>;
+        result.recordings = { ...page, rows: page.rows.map((r) => decorateRecording(r)) };
+      }
+
+      res.json(result);
+    })
+  );
+
+  // ---- file serve for the embedded viewer ------------------------------
+  //
+  // Streams the .appmap.json file *only* if its path is registered in
+  // appmaps.source_path, so the UI server can't be coerced into reading
+  // arbitrary disk paths.
+  app.get(
+    '/file',
+    wrap((req, res) => {
+      const ref = maybeString(req.query.appmap);
+      if (!ref) {
+        res.status(400).json({ error: 'appmap query parameter is required' });
+        return;
+      }
+      let am;
+      try {
+        am = resolveAppmapPath(db, ref);
+      } catch (err) {
+        res.status(404).json({ error: (err as Error).message });
+        return;
+      }
+      if (!existsSync(am.source_path)) {
+        res.status(404).json({ error: `appmap file missing on disk: ${am.source_path}` });
+        return;
+      }
+      // Refuse anything bigger than 50MB to avoid handing the browser
+      // a recording that won't render anyway. Indexed appmap.json files
+      // typically run from KB to a few MB.
+      const stat = statSync(am.source_path);
+      if (stat.size > 50 * 1024 * 1024) {
+        res.status(413).json({ error: `appmap file too large: ${stat.size} bytes` });
+        return;
+      }
+      res.type('application/json').sendFile(am.source_path);
+    })
+  );
+
+  // ---- static SPA -------------------------------------------------------
+  //
+  // Everything that isn't /api/* and isn't an asset under staticDir
+  // falls through to index.html so React Router can handle client-side
+  // routes. If the bundle isn't built, the API still works and the root
+  // path returns a friendly build-instruction message.
+  const indexHtml = path.join(staticDir, 'index.html');
+  const bundleExists = existsSync(indexHtml);
+
+  if (bundleExists) {
+    app.use(express.static(staticDir));
+  }
+
+  // Catch-all for non-API GETs. Express 5's path-to-regexp doesn't
+  // accept '*' as a route — use a middleware after the API routes
+  // instead.
+  app.use((req, res, next) => {
+    if (req.method !== 'GET' || req.path.startsWith('/api/') || req.path === '/file') {
+      next();
+      return;
+    }
+    if (bundleExists) {
+      res.sendFile(indexHtml);
+      return;
+    }
+    res
+      .status(503)
+      .type('text/plain')
+      .send(
+        `query-ui bundle not found at ${staticDir}\n` +
+          `Build it before launching: \`yarn build\` in packages/cli.\n` +
+          `(API routes under /api/* are still available.)\n`
+      );
+  });
+
+  return app;
+}
+
+export function startUIServer(opts: UIServerOptions): Promise<UIServerHandle> {
+  return new Promise((resolve, reject) => {
+    const app = buildUIApp(opts);
+    const requestedPort = opts.port ?? 0;
+    const server = app.listen(requestedPort, '127.0.0.1');
+    server.once('error', reject);
+    server.once('listening', () => {
+      const addr = server.address();
+      if (!addr || typeof addr === 'string') {
+        reject(new Error('failed to bind UI server'));
+        return;
+      }
+      const port = addr.port;
+      resolve({
+        server,
+        port,
+        url: `http://localhost:${port}/`,
+        close: () =>
+          new Promise<void>((rs, rj) => {
+            server.close((err) => (err ? rj(err) : rs()));
+          }),
+      });
+    });
+  });
+}
+
+// ---- search query parser ------------------------------------------------
+//
+// Recognizes the apm-style structured filter syntax:
+//   status:500  status:5xx
+//   method:GET
+//   path:/api
+//   duration:>1s
+//   class:UserController
+//   function:save
+//   label:log
+//   table:widgets
+//   sql:SELECT
+//   branch:main  commit:<sha>  exception:NotFound
+//   last:1h  since:<iso>  until:<iso>
+//
+// Everything not matching the `key:value` shape becomes free-text.
+
+const FILTER_KEYS = new Set([
+  'status', 'method', 'path', 'duration',
+  'class', 'function', 'label', 'table', 'sql',
+  'branch', 'commit', 'exception',
+  'last', 'since', 'until', 'appmap',
+]);
+
+interface SearchFilters {
+  text?: string;
+  status?: string;
+  method?: string;
+  path?: string;
+  duration?: string;
+  class?: string;
+  function?: string;
+  label?: string;
+  table?: string;
+  sql?: string;
+  branch?: string;
+  commit?: string;
+  exception?: string;
+  since?: string;
+  until?: string;
+  appmap?: string;
+}
+
+export function parseSearchQuery(q: string): SearchFilters {
+  const filters: SearchFilters = {};
+  const text: string[] = [];
+
+  for (const tok of q.split(/\s+/).filter(Boolean)) {
+    const m = /^([a-zA-Z]+):(.+)$/.exec(tok);
+    if (m && FILTER_KEYS.has(m[1].toLowerCase())) {
+      const key = m[1].toLowerCase();
+      let value = m[2];
+
+      // status:5xx → status:>=500
+      if (key === 'status' && /^[1-5]xx$/i.test(value)) {
+        const family = value.charAt(0);
+        filters.status = `>=${family}00`;
+        continue;
+      }
+      // last:1h → since:<now - 1h>
+      if (key === 'last') {
+        try {
+          filters.since = parseTime(`${value} ago`);
+        } catch {
+          // ignore unparseable values; agents/users often paste partials
+        }
+        continue;
+      }
+      (filters as Record<string, string>)[key] = value;
+    } else {
+      text.push(tok);
+    }
+  }
+
+  if (text.length > 0) filters.text = text.join(' ');
+  return filters;
+}
diff --git a/packages/cli/src/cmds/query/queries/compare.ts b/packages/cli/src/cmds/query/queries/compare.ts
new file mode 100644
index 0000000000..5ab2c45765
--- /dev/null
+++ b/packages/cli/src/cmds/query/queries/compare.ts
@@ -0,0 +1,121 @@
+import sqlite3 from 'better-sqlite3';
+
+import { DEFAULT_PAGE_LIMIT, Page } from '../lib/page';
+import { endpoints } from './endpoints';
+
+export interface CompareRow {
+  method: string;
+  route: string;
+  a_count: number;
+  a_p95_ms: number | null;
+  b_count: number;
+  b_p95_ms: number | null;
+  // b_p95 / a_p95 — undefined when either side has no measured durations.
+  delta: number | null;
+}
+
+export type CompareSort = 'delta' | 'p95-a' | 'p95-b';
+
+export interface CompareFilter {
+  branch_a: string;
+  branch_b: string;
+  since?: string;
+  until?: string;
+  sort?: CompareSort;
+  limit?: number;
+  offset?: number;
+}
+
+// Computes per-route p95 for two branches and merges the results, exposing
+// delta = b_p95 / a_p95 alongside both sides' counts and p95s. Implementation
+// reuses endpoints() (which already does the SQL window-function p95) so the
+// p95 semantics match the endpoints verb exactly.
+export function compare(
+  db: sqlite3.Database,
+  filter: CompareFilter
+): Page<CompareRow> {
+  // Pull all endpoint rows for each branch (limit: 0 = unbounded). The
+  // outer pagination is on the merged compare rows, not on either side
+  // individually.
+  const a = endpoints(db, {
+    branch: filter.branch_a,
+    since: filter.since,
+    until: filter.until,
+    limit: 0,
+  }).rows;
+  const b = endpoints(db, {
+    branch: filter.branch_b,
+    since: filter.since,
+    until: filter.until,
+    limit: 0,
+  }).rows;
+
+  const rows = new Map<string, CompareRow>();
+  const key = (method: string, route: string) => `${method}\t${route}`;
+
+  for (const r of a) {
+    rows.set(key(r.method, r.route), {
+      method: r.method,
+      route: r.route,
+      a_count: r.count,
+      a_p95_ms: r.p95_ms,
+      b_count: 0,
+      b_p95_ms: null,
+      delta: null,
+    });
+  }
+  for (const r of b) {
+    const k = key(r.method, r.route);
+    const existing = rows.get(k);
+    if (existing) {
+      existing.b_count = r.count;
+      existing.b_p95_ms = r.p95_ms;
+    } else {
+      rows.set(k, {
+        method: r.method,
+        route: r.route,
+        a_count: 0,
+        a_p95_ms: null,
+        b_count: r.count,
+        b_p95_ms: r.p95_ms,
+        delta: null,
+      });
+    }
+  }
+
+  for (const row of rows.values()) {
+    if (row.a_p95_ms != null && row.a_p95_ms > 0 && row.b_p95_ms != null) {
+      row.delta = row.b_p95_ms / row.a_p95_ms;
+    }
+  }
+
+  const result = [...rows.values()];
+  const sortKey: CompareSort = filter.sort ?? 'delta';
+  result.sort(comparators[sortKey]);
+
+  const limit = filter.limit ?? DEFAULT_PAGE_LIMIT;
+  const offset = filter.offset ?? 0;
+  const total = result.length;
+  const sliced = limit > 0 ? result.slice(offset, offset + limit) : result.slice(offset);
+  return { rows: sliced, total, limit, offset };
+}
+
+// "delta" sorts by absolute deviation from 1× — biggest changes (in
+// either direction) at the top. "p95-a" / "p95-b" sort by the named side
+// descending. All keys put nulls last.
+function descNullsLast(a: number | null, b: number | null): number {
+  if (a == null && b == null) return 0;
+  if (a == null) return 1;
+  if (b == null) return -1;
+  return b - a;
+}
+
+const comparators: Record<CompareSort, (a: CompareRow, b: CompareRow) => number> = {
+  delta: (x, y) => {
+    const xd = x.delta == null ? null : Math.abs(Math.log(x.delta));
+    const yd = y.delta == null ? null : Math.abs(Math.log(y.delta));
+    return descNullsLast(xd, yd);
+  },
+  'p95-a': (x, y) => descNullsLast(x.a_p95_ms, y.a_p95_ms),
+  'p95-b': (x, y) => descNullsLast(x.b_p95_ms, y.b_p95_ms),
+};
diff --git a/packages/cli/src/cmds/query/queries/dashboard.ts b/packages/cli/src/cmds/query/queries/dashboard.ts
new file mode 100644
index 0000000000..5b9c1b4b0d
--- /dev/null
+++ b/packages/cli/src/cmds/query/queries/dashboard.ts
@@ -0,0 +1,35 @@
+import sqlite3 from 'better-sqlite3';
+
+// Recording-set totals shown on the UI's dashboard. One round-trip query
+// — every value is a SELECT subquery so the cost is one statement.
+//
+// avg_request_ms is a coarse "average HTTP request latency across the
+// whole DB" measurement; the per-route breakdown lives in endpoints().
+// earliest/latest read appmaps.timestamp because http_requests has no
+// per-row timestamp in this schema.
+export interface DashboardTotals {
+  recordings: number;
+  requests: number;
+  queries: number;
+  exceptions: number;
+  calls: number;
+  avg_request_ms: number | null;
+  earliest: string | null;
+  latest: string | null;
+}
+
+export function dashboardTotals(db: sqlite3.Database): DashboardTotals {
+  return db
+    .prepare(
+      `SELECT
+         (SELECT COUNT(*) FROM appmaps)                                                AS recordings,
+         (SELECT COUNT(*) FROM http_requests)                                          AS requests,
+         (SELECT COUNT(*) FROM sql_queries WHERE sql_text NOT IN ('BEGIN', 'COMMIT'))  AS queries,
+         (SELECT COUNT(*) FROM exceptions)                                             AS exceptions,
+         (SELECT COUNT(*) FROM function_calls)                                         AS calls,
+         (SELECT AVG(elapsed_ms) FROM http_requests WHERE elapsed_ms IS NOT NULL)      AS avg_request_ms,
+         (SELECT MIN(timestamp) FROM appmaps WHERE timestamp IS NOT NULL)              AS earliest,
+         (SELECT MAX(timestamp) FROM appmaps WHERE timestamp IS NOT NULL)              AS latest`
+    )
+    .get() as DashboardTotals;
+}
diff --git a/packages/cli/src/cmds/query/queries/endpoints.ts b/packages/cli/src/cmds/query/queries/endpoints.ts
new file mode 100644
index 0000000000..5105e7ace2
--- /dev/null
+++ b/packages/cli/src/cmds/query/queries/endpoints.ts
@@ -0,0 +1,150 @@
+import sqlite3 from 'better-sqlite3';
+
+import { Page, paginate } from '../lib/page';
+import type { Comparator, NumberFilter } from '../lib/parseFilter';
+
+export interface EndpointRow {
+  method: string;
+  route: string;
+  count: number;
+  avg_ms: number | null;
+  p95_ms: number | null;
+  err_pct: number;
+}
+
+export type EndpointSort = 'count' | 'avg' | 'p95' | 'err';
+
+export interface EndpointsFilter {
+  // ISO timestamp (use parseTime to build).
+  since?: string;
+  until?: string;
+  branch?: string;
+  // --status N (or comparator). Acts as a HAVING-style filter on routes:
+  // a route is shown iff at least one of its requests matches. Counts /
+  // averages / p95 / err_pct remain over all of that route's requests.
+  status?: NumberFilter;
+  sort?: EndpointSort;
+  limit?: number;
+  offset?: number;
+}
+
+// err_pct is fixed at "% of requests with status >= 500" (server errors),
+// independent of any --status filter.
+const ERR_THRESHOLD = 500;
+
+const SORT_COLUMNS: Record<EndpointSort, string> = {
+  count: 'count',
+  avg: 'avg_ms',
+  p95: 'p95_ms',
+  err: 'err_pct',
+};
+
+const VALID_OPS = new Set<Comparator>(['=', '>=', '<=', '>', '<']);
+
+// Aggregation runs entirely in SQL. Per route:
+//   count         COUNT(*) over the partition
+//   avg_ms        AVG(elapsed_ms) over non-null values
+//   p95_ms        elapsed_ms at rank ceil(0.95 * measured_count) within
+//                 the partition (computed with a ROW_NUMBER() window).
+//   err_pct       100 * SUM(status >= 500) / COUNT(*)
+// --status acts as a HAVING filter: route is shown iff ≥1 of its rows
+// matches; aggregates remain over all rows.
+//
+// SQL injection surface: filter.sort and filter.status.op are validated
+// against fixed allow-lists before being interpolated.
+export function endpoints(
+  db: sqlite3.Database,
+  filter: EndpointsFilter = {}
+): Page<EndpointRow> {
+  const where: string[] = [];
+  const params: (string | number)[] = [];
+
+  if (filter.branch) {
+    where.push('a.git_branch = ?');
+    params.push(filter.branch);
+  }
+  // --since/--until filter on the recording's timestamp (a.timestamp) —
+  // the canonical recording-level attribute. find verbs use the same
+  // column.
+  if (filter.since) {
+    where.push('a.timestamp >= ?');
+    params.push(filter.since);
+  }
+  if (filter.until) {
+    where.push('a.timestamp <= ?');
+    params.push(filter.until);
+  }
+  const whereSql = where.length > 0 ? `WHERE ${where.join(' AND ')}` : '';
+
+  let havingSql = '';
+  if (filter.status) {
+    if (!VALID_OPS.has(filter.status.op)) {
+      throw new Error(`invalid status op: ${filter.status.op}`);
+    }
+    havingSql = `HAVING SUM(CASE WHEN status_code ${filter.status.op} ? THEN 1 ELSE 0 END) > 0`;
+    params.push(filter.status.value);
+  }
+
+  const sortKey = filter.sort ?? 'count';
+  if (!(sortKey in SORT_COLUMNS)) {
+    throw new Error(`invalid sort key: ${sortKey}`);
+  }
+  const sortColumn = SORT_COLUMNS[sortKey];
+
+  const sql = `
+    WITH ranked AS (
+      SELECT
+        h.method                              AS method,
+        COALESCE(h.normalized_path, h.path)   AS route,
+        h.elapsed_ms                          AS elapsed_ms,
+        h.status_code                         AS status_code,
+        ROW_NUMBER() OVER (
+          PARTITION BY h.method, COALESCE(h.normalized_path, h.path)
+          ORDER BY h.elapsed_ms NULLS LAST
+        ) AS rn,
+        SUM(CASE WHEN h.elapsed_ms IS NOT NULL THEN 1 ELSE 0 END) OVER (
+          PARTITION BY h.method, COALESCE(h.normalized_path, h.path)
+        ) AS measured_count
+      FROM http_requests h
+      JOIN appmaps a ON a.id = h.appmap_id
+      ${whereSql}
+    )
+    SELECT
+      method,
+      route,
+      COUNT(*)                                                    AS count,
+      AVG(CASE WHEN elapsed_ms IS NOT NULL THEN elapsed_ms END)   AS avg_ms,
+      MAX(CASE
+        WHEN measured_count > 0
+          AND rn = (measured_count * 19 + 19) / 20
+        THEN elapsed_ms
+      END)                                                        AS p95_ms,
+      CAST(SUM(CASE WHEN status_code >= ${ERR_THRESHOLD} THEN 1 ELSE 0 END) AS REAL)
+        * 100.0 / COUNT(*)                                        AS err_pct
+    FROM ranked
+    GROUP BY method, route
+    ${havingSql}
+    ORDER BY ${sortColumn} DESC NULLS LAST, method, route
+  `;
+
+  const page = paginate<{
+    method: string;
+    route: string;
+    count: number;
+    avg_ms: number | null;
+    p95_ms: number | null;
+    err_pct: number | null;
+  }>(db, sql, params, { limit: filter.limit, offset: filter.offset });
+
+  return {
+    ...page,
+    rows: page.rows.map((r) => ({
+      method: r.method,
+      route: r.route,
+      count: r.count,
+      avg_ms: r.avg_ms,
+      p95_ms: r.p95_ms,
+      err_pct: r.err_pct ?? 0,
+    })),
+  };
+}
diff --git a/packages/cli/src/cmds/query/queries/find.ts b/packages/cli/src/cmds/query/queries/find.ts
new file mode 100644
index 0000000000..95254d9bf9
--- /dev/null
+++ b/packages/cli/src/cmds/query/queries/find.ts
@@ -0,0 +1,491 @@
+import sqlite3 from 'better-sqlite3';
+
+import { projectLogMessage } from '../lib/logMessage';
+import { Page, paginate } from '../lib/page';
+import type { NumberFilter } from '../lib/parseFilter';
+import {
+  appmapIdScope,
+  appmapWhere,
+  classFilterClauses,
+  httpScopeClauses,
+  methodFilterClauses,
+  parseRoute,
+  sqlCallerClassClauses,
+  sqlCallerMethodClauses,
+} from '../lib/scope';
+
+export type FindType = 'appmaps' | 'requests' | 'queries' | 'calls' | 'exceptions' | 'logs';
+
+export interface FindFilter {
+  route?: string;          // "POST /orders" or "/orders"
+  className?: string;      // --class (TS reserved word workaround)
+  method?: string;         // --method (method_id, not HTTP method)
+  label?: string;          // --label
+  eventIds?: number[];     // --event-id; exact event_id match (find calls)
+  branch?: string;
+  commit?: string;
+  status?: NumberFilter;   // --status N / >=N
+  duration?: NumberFilter; // --duration ">1s" → ms
+  since?: string;
+  until?: string;
+  appmap?: string;         // appmap name (or basename of source_path)
+  table?: string;          // SQL table name (find queries)
+  exception?: string;      // exception class (find exceptions)
+  logger?: string;         // --logger (find logs); class of the logging fn
+  message?: string;        // --message (find logs); substring of the log line
+  withLogs?: number;       // --with-logs N (find exceptions); attach N preceding logs
+  limit?: number;
+  offset?: number;
+}
+
+export interface FindAppmapRow {
+  appmap_id: number;
+  appmap_name: string;
+  // Stored absolute path on disk. The MCP layer relativizes this to a
+  // canonical `path` field (see lib/appmapPath); CLI table output
+  // doesn't surface it, but JSON callers benefit from having it
+  // available so they don't have to round-trip through a separate query.
+  source_path: string;
+  route: string | null;
+  status_code: number | null;
+  elapsed_ms: number | null;
+  sql_count: number;
+  branch: string | null;
+  timestamp: string | null;
+}
+
+export interface FindRequestRow {
+  appmap_name: string;
+  event_id: number;
+  method: string;
+  route: string;
+  status_code: number;
+  elapsed_ms: number | null;
+  branch: string | null;
+}
+
+export interface FindQueryRow {
+  appmap_name: string;
+  event_id: number;
+  elapsed_ms: number | null;
+  caller_class: string | null;
+  caller_method: string | null;
+  sql_text: string;
+}
+
+export interface FindCallRow {
+  appmap_name: string;
+  event_id: number;
+  fqid: string | null;
+  defined_class: string;
+  method_id: string;
+  path: string | null;
+  lineno: number | null;
+  elapsed_ms: number | null;
+  parameters_json: string | null;
+  return_value: string | null;
+}
+
+export interface FindLogRow {
+  appmap_name: string;
+  event_id: number;
+  parent_event_id: number | null;
+  logger: string;          // defined_class of the logging fn
+  method_id: string;
+  path: string | null;
+  lineno: number | null;
+  // Display-projected message derived from parameters_json / return_value
+  // (see lib/logMessage.projectLogMessage). '' when nothing usable was
+  // captured; the raw JSON columns remain for callers who need them.
+  message: string;
+  parameters_json: string | null;
+  return_value: string | null;
+}
+
+export interface FindExceptionRow {
+  appmap_id: number;
+  appmap_name: string;
+  event_id: number;
+  // Return event id where the throw materialized. with_logs uses this as
+  // the upper bound so logs that fired *inside* the throwing call are
+  // included. Null only for the legacy "exceptions on a call event"
+  // recorder shape.
+  return_event_id: number | null;
+  exception_class: string;
+  message: string | null;
+  path: string | null;
+  lineno: number | null;
+  // Populated only when filter.withLogs > 0. Ordered chronologically
+  // (oldest first), capped at filter.withLogs entries. Each row has
+  // event_id < the exception's return_event_id (or event_id if
+  // return_event_id is null).
+  recent_logs?: FindLogRow[];
+}
+
+// --- internal helpers (find-specific) ---
+
+interface Clauses {
+  where: string[];
+  params: (string | number)[];
+}
+
+function durationClause(filter: FindFilter, column: string): Clauses {
+  const where: string[] = [];
+  const params: (string | number)[] = [];
+  if (filter.duration) {
+    where.push(`${column} ${filter.duration.op} ?`);
+    params.push(filter.duration.value);
+  }
+  return { where, params };
+}
+
+function pageOptions(filter: FindFilter): { limit?: number; offset?: number } {
+  return { limit: filter.limit, offset: filter.offset };
+}
+
+// --- per-type queries ---
+
+export function findAppmaps(db: sqlite3.Database, filter: FindFilter): Page<FindAppmapRow> {
+  const a = appmapWhere(filter, 'a');
+  const h = httpScopeClauses(filter, 'h2');
+  const requireHttpMatch = h.where.length > 0;
+
+  // Pick a deterministic "sample" request per appmap via a correlated
+  // subquery: the http_request with the smallest event_id among those
+  // matching --route / --status (or any request if no http filter). This
+  // avoids the non-determinism of GROUP BY a.id with non-aggregated h.*.
+  const innerHttpFilter = requireHttpMatch ? ` AND ${h.where.join(' AND ')}` : '';
+
+  const whereParts: string[] = [...a.where];
+  if (requireHttpMatch) whereParts.push('h.id IS NOT NULL');
+  if (filter.duration) {
+    whereParts.push(`a.elapsed_ms ${filter.duration.op} ?`);
+  }
+  const whereSql = whereParts.length > 0 ? `WHERE ${whereParts.join(' AND ')}` : '';
+
+  // Param order: inner subquery http filters → outer WHERE (appmap, then duration).
+  const params: (string | number)[] = [...h.params, ...a.params];
+  if (filter.duration) params.push(filter.duration.value);
+
+  const sql = `
+    SELECT a.id                                       AS appmap_id,
+           a.name                                     AS appmap_name,
+           a.source_path                              AS source_path,
+           COALESCE(h.normalized_path, h.path)        AS route,
+           h.status_code                              AS status_code,
+           COALESCE(h.elapsed_ms, a.elapsed_ms)       AS elapsed_ms,
+           a.sql_query_count                          AS sql_count,
+           a.git_branch                               AS branch,
+           a.timestamp                                AS timestamp
+    FROM appmaps a
+    LEFT JOIN http_requests h ON h.id = (
+      SELECT h2.id FROM http_requests h2
+      WHERE h2.appmap_id = a.id${innerHttpFilter}
+      ORDER BY h2.event_id LIMIT 1
+    )
+    ${whereSql}
+    ORDER BY a.timestamp, a.name
+  `;
+  return paginate<FindAppmapRow>(db, sql, params, pageOptions(filter));
+}
+
+export function findRequests(db: sqlite3.Database, filter: FindFilter): Page<FindRequestRow> {
+  const a = appmapWhere(filter, 'a');
+  const where: string[] = [...a.where];
+  const params: (string | number)[] = [...a.params];
+
+  if (filter.route) {
+    const route = parseRoute(filter.route);
+    where.push(`COALESCE(h.normalized_path, h.path) LIKE ?`);
+    params.push(`%${route.path}%`);
+    if (route.method) {
+      where.push(`h.method = ?`);
+      params.push(route.method);
+    }
+  }
+  if (filter.status) {
+    where.push(`h.status_code ${filter.status.op} ?`);
+    params.push(filter.status.value);
+  }
+  const dur = durationClause(filter, 'h.elapsed_ms');
+  where.push(...dur.where);
+  params.push(...dur.params);
+
+  const sql = `
+    SELECT a.name AS appmap_name,
+           h.event_id AS event_id,
+           h.method AS method,
+           COALESCE(h.normalized_path, h.path) AS route,
+           h.status_code AS status_code,
+           h.elapsed_ms AS elapsed_ms,
+           a.git_branch AS branch
+    FROM http_requests h
+    JOIN appmaps a ON a.id = h.appmap_id
+    ${where.length > 0 ? `WHERE ${where.join(' AND ')}` : ''}
+    ORDER BY a.source_path, h.event_id
+  `;
+  return paginate<FindRequestRow>(db, sql, params, pageOptions(filter));
+}
+
+export function findQueries(db: sqlite3.Database, filter: FindFilter): Page<FindQueryRow> {
+  const where: string[] = [];
+  const params: (string | number)[] = [];
+
+  const scope = appmapIdScope(filter, 'q');
+  if (scope) {
+    where.push(scope.sql);
+    params.push(...scope.params);
+  }
+
+  if (filter.table) {
+    where.push(`q.sql_text LIKE ?`);
+    params.push(`%${filter.table}%`);
+  }
+  if (filter.className) {
+    // The caller of a sql_query is the function_call referenced by
+    // q.parent_event_id, which has its own code_object link. Use that
+    // canonical path; fall back to the denormalized caller_class string
+    // when the parent function_call has no code_object link.
+    const c = sqlCallerClassClauses(filter.className, 'q');
+    where.push(...c.where);
+    params.push(...c.params);
+  }
+  if (filter.method) {
+    const m = sqlCallerMethodClauses(filter.method, 'q');
+    where.push(...m.where);
+    params.push(...m.params);
+  }
+  const dur = durationClause(filter, 'q.elapsed_ms');
+  where.push(...dur.where);
+  params.push(...dur.params);
+
+  const sql = `
+    SELECT a.name AS appmap_name,
+           q.event_id AS event_id,
+           q.elapsed_ms AS elapsed_ms,
+           q.caller_class AS caller_class,
+           q.caller_method AS caller_method,
+           q.sql_text AS sql_text
+    FROM sql_queries q
+    JOIN appmaps a ON a.id = q.appmap_id
+    ${where.length > 0 ? `WHERE ${where.join(' AND ')}` : ''}
+    ORDER BY a.source_path, q.event_id
+  `;
+  return paginate<FindQueryRow>(db, sql, params, pageOptions(filter));
+}
+
+export function findCalls(db: sqlite3.Database, filter: FindFilter): Page<FindCallRow> {
+  const where: string[] = [];
+  const params: (string | number)[] = [];
+
+  const scope = appmapIdScope(filter, 'fc');
+  if (scope) {
+    where.push(scope.sql);
+    params.push(...scope.params);
+  }
+
+  if (filter.className) {
+    const c = classFilterClauses(filter.className, 'fc');
+    where.push(...c.where);
+    params.push(...c.params);
+  }
+  if (filter.method) {
+    const m = methodFilterClauses(filter.method, 'fc');
+    where.push(...m.where);
+    params.push(...m.params);
+  }
+  if (filter.label) {
+    where.push(
+      `fc.code_object_id IN (SELECT l.code_object_id FROM labels l WHERE l.label LIKE ?)`
+    );
+    params.push(`%${filter.label}%`);
+  }
+  // Exact event_id drill: fetch specific calls (e.g. ids read off a
+  // get_call_tree) so their full, untruncated parameters_json /
+  // return_value can be inspected.
+  if (filter.eventIds && filter.eventIds.length > 0) {
+    where.push(`fc.event_id IN (${filter.eventIds.map(() => '?').join(', ')})`);
+    params.push(...filter.eventIds);
+  }
+  const dur = durationClause(filter, 'fc.elapsed_ms');
+  where.push(...dur.where);
+  params.push(...dur.params);
+
+  const sql = `
+    SELECT a.name AS appmap_name,
+           fc.event_id AS event_id,
+           co.fqid AS fqid,
+           fc.defined_class AS defined_class,
+           fc.method_id AS method_id,
+           fc.path AS path,
+           fc.lineno AS lineno,
+           fc.elapsed_ms AS elapsed_ms,
+           fc.parameters_json AS parameters_json,
+           fc.return_value AS return_value
+    FROM function_calls fc
+    JOIN appmaps a ON a.id = fc.appmap_id
+    LEFT JOIN code_objects co ON co.id = fc.code_object_id
+    ${where.length > 0 ? `WHERE ${where.join(' AND ')}` : ''}
+    ORDER BY a.source_path, fc.event_id
+  `;
+  return paginate<FindCallRow>(db, sql, params, pageOptions(filter));
+}
+
+// Log rows: function_calls whose linked code_object has the canonical
+// 'log' label. The label is the contract — it tells the importer to
+// capture parameters_json + return_value, and tells us which calls are
+// loggers. --message is a SQL LIKE substring against both columns;
+// false positives (matching a parameter name, a class name, or a JSON
+// punctuation byte) are accepted by design and can be tightened in
+// post-processing.
+export function findLogs(db: sqlite3.Database, filter: FindFilter): Page<FindLogRow> {
+  const where: string[] = [
+    `fc.code_object_id IN (SELECT l.code_object_id FROM labels l WHERE l.label = 'log')`,
+  ];
+  const params: (string | number)[] = [];
+
+  const scope = appmapIdScope(filter, 'fc');
+  if (scope) {
+    where.push(scope.sql);
+    params.push(...scope.params);
+  }
+
+  if (filter.logger) {
+    const c = classFilterClauses(filter.logger, 'fc');
+    where.push(...c.where);
+    params.push(...c.params);
+  }
+
+  if (filter.message) {
+    where.push(`(fc.parameters_json LIKE ? OR fc.return_value LIKE ?)`);
+    const like = `%${filter.message}%`;
+    params.push(like, like);
+  }
+
+  const sql = `
+    SELECT a.name AS appmap_name,
+           fc.event_id AS event_id,
+           fc.parent_event_id AS parent_event_id,
+           fc.defined_class AS logger,
+           fc.method_id AS method_id,
+           fc.path AS path,
+           fc.lineno AS lineno,
+           fc.parameters_json AS parameters_json,
+           fc.return_value AS return_value
+    FROM function_calls fc
+    JOIN appmaps a ON a.id = fc.appmap_id
+    WHERE ${where.join(' AND ')}
+    ORDER BY a.source_path, fc.event_id
+  `;
+  const page = paginate<Omit<FindLogRow, 'message'>>(db, sql, params, pageOptions(filter));
+  return {
+    ...page,
+    rows: page.rows.map((r) => ({
+      ...r,
+      message: projectLogMessage(r.parameters_json, r.return_value),
+    })),
+  };
+}
+
+export function findExceptions(
+  db: sqlite3.Database,
+  filter: FindFilter
+): Page<FindExceptionRow> {
+  const where: string[] = [];
+  const params: (string | number)[] = [];
+
+  const scope = appmapIdScope(filter, 'e');
+  if (scope) {
+    where.push(scope.sql);
+    params.push(...scope.params);
+  }
+
+  if (filter.exception) {
+    where.push(`e.exception_class LIKE ?`);
+    params.push(`%${filter.exception}%`);
+  }
+
+  const sql = `
+    SELECT e.appmap_id AS appmap_id,
+           a.name AS appmap_name,
+           e.event_id AS event_id,
+           e.return_event_id AS return_event_id,
+           e.exception_class AS exception_class,
+           e.message AS message,
+           e.path AS path,
+           e.lineno AS lineno
+    FROM exceptions e
+    JOIN appmaps a ON a.id = e.appmap_id
+    ${where.length > 0 ? `WHERE ${where.join(' AND ')}` : ''}
+    ORDER BY a.source_path, e.event_id, e.exception_class
+  `;
+  const page = paginate<FindExceptionRow>(db, sql, params, pageOptions(filter));
+  const rows = page.rows;
+
+  // Enrichment: for each exception, attach the last N log calls in the
+  // same recording with event_id strictly less than the exception's
+  // return_event_id (the throw point in the event stream). Falling back
+  // to event_id (the call entry) only handles the legacy recorder shape
+  // — which produces no preceding logs anyway, since logs inside the
+  // call have event_id > the call entry. We use event order rather than
+  // parent_event_id subtree walking to avoid recursive CTEs; this picks
+  // up logs that ran in the same thread before the throw, which is
+  // what "what did the app log before it crashed?" asks.
+  if (filter.withLogs && filter.withLogs > 0) {
+    const logStmt = db.prepare(`
+      SELECT a.name AS appmap_name,
+             fc.event_id AS event_id,
+             fc.parent_event_id AS parent_event_id,
+             fc.defined_class AS logger,
+             fc.method_id AS method_id,
+             fc.path AS path,
+             fc.lineno AS lineno,
+             fc.parameters_json AS parameters_json,
+             fc.return_value AS return_value
+        FROM function_calls fc
+        JOIN appmaps a ON a.id = fc.appmap_id
+       WHERE fc.appmap_id = ?
+         AND fc.event_id < ?
+         AND fc.code_object_id IN (
+               SELECT l.code_object_id FROM labels l WHERE l.label = 'log'
+             )
+       ORDER BY fc.event_id DESC
+       LIMIT ?
+    `);
+    for (const row of rows) {
+      const upperBound = row.return_event_id ?? row.event_id;
+      if (upperBound == null) {
+        row.recent_logs = [];
+        continue;
+      }
+      const logs = logStmt.all(row.appmap_id, upperBound, filter.withLogs) as Omit<FindLogRow, 'message'>[];
+      row.recent_logs = logs
+        .reverse() // chronological
+        .map((l) => ({ ...l, message: projectLogMessage(l.parameters_json, l.return_value) }));
+    }
+  }
+
+  return page;
+}
+
+// Dispatcher.
+export function find(
+  db: sqlite3.Database,
+  type: FindType,
+  filter: FindFilter
+): Page<unknown> {
+  switch (type) {
+    case 'appmaps':
+      return findAppmaps(db, filter);
+    case 'requests':
+      return findRequests(db, filter);
+    case 'queries':
+      return findQueries(db, filter);
+    case 'calls':
+      return findCalls(db, filter);
+    case 'exceptions':
+      return findExceptions(db, filter);
+    case 'logs':
+      return findLogs(db, filter);
+  }
+}
diff --git a/packages/cli/src/cmds/query/queries/hotspots.ts b/packages/cli/src/cmds/query/queries/hotspots.ts
new file mode 100644
index 0000000000..2d2bd92d7a
--- /dev/null
+++ b/packages/cli/src/cmds/query/queries/hotspots.ts
@@ -0,0 +1,137 @@
+import sqlite3 from 'better-sqlite3';
+
+import { Page, paginate } from '../lib/page';
+import { appmapIdScope, classFilterClauses, RecordingScope } from '../lib/scope';
+
+export type HotspotType = 'function' | 'sql';
+
+export interface HotspotsFilter extends RecordingScope {
+  type?: HotspotType;
+  className?: string;   // function mode only
+  limit?: number;
+  offset?: number;
+}
+
+export interface FunctionHotspotRow {
+  fqid: string | null;
+  defined_class: string;
+  method_id: string;
+  // Representative source location: one call's path/lineno from the
+  // aggregated set. Useful for "show me the source of this hotspot"
+  // without a follow-up lookup.
+  path: string | null;
+  lineno: number | null;
+  calls: number;
+  total_ms: number;
+  self_ms: number;
+}
+
+export interface SqlHotspotRow {
+  count: number;
+  avg_ms: number;
+  total_ms: number;
+  sql_text: string;
+}
+
+// SELF_MS = elapsed_ms - sum of immediate children's elapsed_ms, where a
+// child is any function_call / sql_query / http_client_request whose
+// parent_event_id points at this call. Computed via a one-pass CTE that
+// pre-aggregates per-event child time, so the join is O(rows) regardless of
+// nesting depth.
+const CHILD_TIME_CTE = `
+  WITH child_events AS (
+    SELECT appmap_id, parent_event_id, elapsed_ms FROM function_calls
+    UNION ALL
+    SELECT appmap_id, parent_event_id, elapsed_ms FROM sql_queries
+    UNION ALL
+    SELECT appmap_id, parent_event_id, elapsed_ms FROM http_client_requests
+  ),
+  child_time AS (
+    SELECT appmap_id, parent_event_id AS event_id,
+           SUM(COALESCE(elapsed_ms, 0)) AS sum_children
+    FROM child_events
+    WHERE parent_event_id IS NOT NULL
+    GROUP BY appmap_id, parent_event_id
+  )
+`;
+
+export function functionHotspots(
+  db: sqlite3.Database,
+  filter: HotspotsFilter
+): Page<FunctionHotspotRow> {
+  const where: string[] = [];
+  const params: (string | number)[] = [];
+
+  const scope = appmapIdScope(filter, 'fc');
+  if (scope) {
+    where.push(scope.sql);
+    params.push(...scope.params);
+  }
+  if (filter.className) {
+    const c = classFilterClauses(filter.className, 'fc');
+    where.push(...c.where);
+    params.push(...c.params);
+  }
+
+  const sql = `
+    ${CHILD_TIME_CTE}
+    SELECT
+      co.fqid                                        AS fqid,
+      fc.defined_class                               AS defined_class,
+      fc.method_id                                   AS method_id,
+      MIN(fc.path)                                   AS path,
+      MIN(fc.lineno)                                 AS lineno,
+      COUNT(*)                                       AS calls,
+      SUM(COALESCE(fc.elapsed_ms, 0))                AS total_ms,
+      SUM(COALESCE(fc.elapsed_ms, 0)
+          - COALESCE(ct.sum_children, 0))            AS self_ms
+    FROM function_calls fc
+    LEFT JOIN child_time ct
+      ON ct.appmap_id = fc.appmap_id AND ct.event_id = fc.event_id
+    LEFT JOIN code_objects co ON co.id = fc.code_object_id
+    ${where.length > 0 ? `WHERE ${where.join(' AND ')}` : ''}
+    GROUP BY fc.code_object_id, fc.defined_class, fc.method_id
+    ORDER BY total_ms DESC
+  `;
+  return paginate<FunctionHotspotRow>(db, sql, params, {
+    limit: filter.limit,
+    offset: filter.offset,
+  });
+}
+
+export function sqlHotspots(
+  db: sqlite3.Database,
+  filter: HotspotsFilter
+): Page<SqlHotspotRow> {
+  const where: string[] = [];
+  const params: (string | number)[] = [];
+
+  const scope = appmapIdScope(filter, 'q');
+  if (scope) {
+    where.push(scope.sql);
+    params.push(...scope.params);
+  }
+
+  const sql = `
+    SELECT
+      COUNT(*)                          AS count,
+      AVG(q.elapsed_ms)                 AS avg_ms,
+      SUM(COALESCE(q.elapsed_ms, 0))    AS total_ms,
+      q.sql_text                        AS sql_text
+    FROM sql_queries q
+    ${where.length > 0 ? `WHERE ${where.join(' AND ')}` : ''}
+    GROUP BY q.sql_text
+    ORDER BY total_ms DESC
+  `;
+  return paginate<SqlHotspotRow>(db, sql, params, {
+    limit: filter.limit,
+    offset: filter.offset,
+  });
+}
+
+export function hotspots(
+  db: sqlite3.Database,
+  filter: HotspotsFilter
+): Page<FunctionHotspotRow> | Page<SqlHotspotRow> {
+  return filter.type === 'sql' ? sqlHotspots(db, filter) : functionHotspots(db, filter);
+}
diff --git a/packages/cli/src/cmds/query/queries/mcp.ts b/packages/cli/src/cmds/query/queries/mcp.ts
new file mode 100644
index 0000000000..7e3a24a523
--- /dev/null
+++ b/packages/cli/src/cmds/query/queries/mcp.ts
@@ -0,0 +1,1105 @@
+// MCP (Model Context Protocol) handler. Exposes the V3 query surface as
+// MCP tools and resources.
+//
+// Tool names are LLM-readable and uniquely identify what each tool
+// returns: `find_*` returns row-level matches, `function_hotspots` /
+// `sql_hotspots` return rankings, `get_call_tree` returns one recording's
+// tree, etc. Mirrors V3's CLI verbs but with descriptive names rather
+// than the terse single-noun forms the CLI uses.
+//
+// Wire format: newline-delimited JSON-RPC 2.0 over stdio. This module
+// implements the message dispatch logic only; the stdio loop lives in
+// the verb so this file stays testable without process I/O.
+
+import sqlite3 from 'better-sqlite3';
+
+import { compare } from './compare';
+import { endpoints, EndpointSort, EndpointsFilter } from './endpoints';
+import {
+  FindAppmapRow,
+  FindCallRow,
+  FindExceptionRow,
+  FindFilter,
+  FindLogRow,
+  FindQueryRow,
+  FindRequestRow,
+  find,
+} from './find';
+import { hotspots } from './hotspots';
+import { related, RelatedFilter } from './related';
+import { FunctionNode, TreeNode, treeWithMeta, TreeOptions } from './tree';
+import { Page } from '../lib/page';
+import { parseDuration, parseStatus, parseTime } from '../lib/parseFilter';
+import { decorateRecording, resolveAppmapPath } from '../lib/recordingId';
+import { suggestSimilarFunctionIds } from '../lib/suggestSimilarFunctionIds';
+import { renderTreeForMcp, renderTreeForMcpBudgeted } from '../lib/treeRender';
+
+export interface JsonRpcRequest {
+  jsonrpc: '2.0';
+  id?: string | number | null;
+  method: string;
+  params?: Record<string, unknown>;
+}
+
+export interface JsonRpcResponse {
+  jsonrpc: '2.0';
+  id: string | number | null;
+  result?: unknown;
+  error?: { code: number; message: string; data?: unknown };
+}
+
+interface ToolSpec {
+  name: string;
+  description: string;
+  inputSchema: {
+    type: 'object';
+    properties: Record<string, unknown>;
+    required?: string[];
+  };
+}
+
+// Per-handler context. Only the DB handle for now; kept as an object
+// so future cross-cutting state (auth tokens, logger, etc.) can attach
+// without touching every tool signature.
+export interface McpContext {
+  db: sqlite3.Database;
+}
+
+interface ToolImpl {
+  spec: ToolSpec;
+  handler: (args: Record<string, unknown>, ctx: McpContext) => unknown;
+}
+
+interface ResourceSpec {
+  uri: string;
+  name: string;
+  description: string;
+  mimeType: string;
+}
+
+interface ResourceImpl {
+  spec: ResourceSpec;
+  read: (ctx: McpContext) => unknown;
+}
+
+// Template-based resources expose a parameterized URI. The agent
+// discovers them via resources/templates/list, then reads a concrete
+// instance with resources/read by substituting the placeholder.
+interface ResourceTemplateSpec {
+  uriTemplate: string;       // RFC 6570 template
+  name: string;
+  description: string;
+  mimeType: string;
+}
+
+interface ResourceTemplateImpl {
+  spec: ResourceTemplateSpec;
+  // Returns the args object if the URI matches the template, else null.
+  match: (uri: string) => Record<string, string> | null;
+  read: (args: Record<string, string>, ctx: McpContext) => unknown;
+}
+
+const SERVER_INFO = { name: 'appmap-query', version: '1.0.0' };
+const PROTOCOL_VERSION = '2024-11-05';
+
+// --- helpers ------------------------------------------------------------
+
+function maybeTime(s: unknown): string | undefined {
+  return typeof s === 'string' && s.length > 0 ? parseTime(s) : undefined;
+}
+
+function maybeNumber(n: unknown): number | undefined {
+  if (typeof n === 'number' && Number.isFinite(n)) return n;
+  if (typeof n === 'string' && /^-?\d+(\.\d+)?$/.test(n)) return Number(n);
+  return undefined;
+}
+
+function maybeString(s: unknown): string | undefined {
+  return typeof s === 'string' && s.length > 0 ? s : undefined;
+}
+
+// ---- get_call_tree default selection -----------------------------------
+//
+// Solver trajectories repeatedly burned 2–3 calls discovering tractable
+// `child_depth` values: a junit recording at depth 6 would blow the
+// token budget, the agent retried with focus_type=http_server_request
+// (which silently returned [] on a junit recording), and only on the
+// third call landed on a per-request recording where the original
+// depth worked. The fix lives at the tool-defaults layer: pick a
+// useful depth based on the recording's shape, fall back to a
+// summary if the result still doesn't fit, and tell the agent
+// explicitly what was chosen and why.
+
+// Recordings with more events than this default to a shallow tree. The
+// value is a heuristic, not a hard rule — agents can still pass
+// child_depth explicitly to override. 500 separates per-request
+// recordings (typically 50–300 events) from junit/process recordings
+// (typically 1k+ events) in the corpus we observed.
+const BROAD_EVENT_THRESHOLD = 500;
+
+// Default child_depth used in JSON mode when an explicit value isn't
+// supplied and the recording is classified as broad. Two levels keeps
+// the response small enough that even a 10k-event recording stays
+// within budget. Text mode uses byte-budgeted rendering instead — see
+// DEFAULT_MAX_CHARS — and skips this path.
+const BROAD_DEFAULT_CHILD_DEPTH = 2;
+
+// Default byte budget for text-mode get_call_tree responses. Sized at
+// roughly the p90 of historical response sizes on the omnibank corpus
+// so common calls pass through whole and outliers (junit-scope
+// recordings hitting deep filter/service chains) get a small clip at
+// the cut sites. Agents can override by passing max_chars explicitly;
+// can also force an unclipped response by passing a very large value.
+const DEFAULT_MAX_CHARS = 12_000;
+
+// When max_chars is in effect, fetch this many descendant levels from
+// the DB; the renderer trims by bytes. Picked deep enough that the
+// budgeted renderer has more material than it needs, but not unbounded
+// — at 8 levels even pathological recordings stay query-able.
+const DEEP_FETCH_DEPTH_FOR_BUDGET = 8;
+
+// Roughly 10K tokens at ~4 chars/token. Past this, fall back to summary
+// mode rather than serializing a tree the agent can't usefully process.
+const RESPONSE_BUDGET_CHARS = 40_000;
+
+// Number of expensive functions surfaced in the summary-mode drilldown
+// list. Picked to give the agent a handful of starting points without
+// re-blowing the budget.
+const SUMMARY_DRILLDOWN_LIMIT = 10;
+
+interface RecordingShape {
+  recorder_type: string | null;
+  event_count: number;
+  http_request_count: number;
+  sql_query_count: number;
+}
+
+function readRecordingShape(db: sqlite3.Database, appmapId: number): RecordingShape {
+  const row = db
+    .prepare(
+      `SELECT recorder_type, event_count, http_request_count, sql_query_count
+         FROM appmaps WHERE id = ?`
+    )
+    .get(appmapId) as RecordingShape | undefined;
+  if (!row) {
+    return { recorder_type: null, event_count: 0, http_request_count: 0, sql_query_count: 0 };
+  }
+  return row;
+}
+
+function isBroadRecording(shape: RecordingShape): boolean {
+  // Per-request recordings are always narrow regardless of event count
+  // (typically one entry-point, one full callstack). Anything else is
+  // broad if the event count crosses the threshold. The recorder_type
+  // values come from AppMap recording metadata; we recognize the common
+  // single-request markers and classify the rest by size.
+  const rt = (shape.recorder_type ?? '').toLowerCase();
+  if (rt === 'http_server_request' || rt === 'requests' || rt === 'request') return false;
+  return shape.event_count > BROAD_EVENT_THRESHOLD;
+}
+
+function buildEmptyFocusDiagnostic(focusType: string, shape: RecordingShape): string {
+  const have: string[] = [];
+  if (shape.http_request_count > 0) have.push(`${shape.http_request_count} http_server_request`);
+  if (shape.sql_query_count > 0) have.push(`${shape.sql_query_count} sql_query`);
+  if (shape.event_count > 0) have.push(`${shape.event_count} total events`);
+  const recordingType = shape.recorder_type ?? 'unknown';
+
+  // Map focus_type back to the table the user was filtering against and
+  // suggest the next step that's actually likely to land. Functions are
+  // the universal fallback because every recording has them.
+  let suggestion: string;
+  if (focusType === 'http_server_request' && shape.http_request_count === 0) {
+    suggestion =
+      "this recording has no HTTP server requests. Try omitting focus_type to get the full tree, " +
+      "or focus_type='function' with a specific fqid.";
+  } else if (focusType === 'sql_query' && shape.sql_query_count === 0) {
+    suggestion =
+      "this recording has no SQL queries. Try omitting focus_type to get the full tree, " +
+      "or focus_type='function' with a specific fqid.";
+  } else if (focusType === 'http_client_request') {
+    suggestion =
+      "no outbound HTTP calls matched. Try omitting focus_type, or list inbound traffic with focus_type='http_server_request'.";
+  } else if (focusType === 'function') {
+    suggestion =
+      "no function call with that fqid. Use find_calls to discover fqids in this recording, then re-call with the exact value.";
+  } else {
+    suggestion = "drop focus_type to get the full tree, then re-aim with a value found in those nodes.";
+  }
+
+  const haveLine = have.length > 0 ? ` Recording contents: ${have.join(', ')}.` : '';
+  return `no events of type '${focusType}' matched in this recording (recorder_type=${recordingType}).${haveLine} ${suggestion}`;
+}
+
+interface SummaryDrilldownItem {
+  fqid: string | null;
+  defined_class: string;
+  method_id: string;
+  event_id: number;
+  elapsed_ms: number | null;
+  child_count: number;
+  path: string | null;
+  lineno: number | null;
+}
+
+function buildSummaryResponse(
+  meta: { nodes: TreeNode[]; truncated: boolean; max_depth_reached: number },
+  chosenParams: Record<string, unknown>,
+  shape: RecordingShape,
+  projectedSize: number
+): Record<string, unknown> {
+  // Keep entry points + exceptions — the high-signal nodes the agent
+  // can pivot from. Drop SQL and intermediate function calls; their
+  // signal lives in the drilldown ranking instead.
+  const kept = meta.nodes.filter(
+    (n) => n.kind === 'http_server' || n.kind === 'http_client' || n.kind === 'exception'
+  );
+
+  // Top-N functions by elapsed_ms with a child_count so the agent can
+  // judge which one is worth drilling into.
+  const childCountById = new Map<number, number>();
+  for (const n of meta.nodes) {
+    if (n.parent_event_id !== null) {
+      childCountById.set(n.parent_event_id, (childCountById.get(n.parent_event_id) ?? 0) + 1);
+    }
+  }
+  const drilldown: SummaryDrilldownItem[] = meta.nodes
+    .filter((n): n is FunctionNode => n.kind === 'function')
+    .filter((n) => typeof n.elapsed_ms === 'number')
+    .sort((a, b) => (b.elapsed_ms ?? 0) - (a.elapsed_ms ?? 0))
+    .slice(0, SUMMARY_DRILLDOWN_LIMIT)
+    .map((n) => ({
+      fqid: n.fqid,
+      defined_class: n.defined_class,
+      method_id: n.method_id,
+      event_id: n.event_id,
+      elapsed_ms: n.elapsed_ms,
+      child_count: childCountById.get(n.event_id) ?? 0,
+      path: n.path,
+      lineno: n.lineno,
+    }));
+
+  return {
+    nodes: kept,
+    truncated: true,
+    max_depth_reached: meta.max_depth_reached,
+    chosen_params: chosenParams,
+    summary_mode: true,
+    reason:
+      `recording has ${shape.event_count} events; full tree at chosen depths would be ${projectedSize} chars ` +
+      `(over the ${RESPONSE_BUDGET_CHARS}-char budget). Returned entry-points and exceptions only; ` +
+      `use suggested_drilldown[].fqid with focus_type='function' to drill into specific calls.`,
+    suggested_drilldown: drilldown,
+  };
+}
+
+// Project the get_call_tree response according to the agent-requested
+// format. `text` (default) replaces the `nodes` array with a `tree`
+// string (indented one-line-per-event, prefixed with #event_id for
+// drilldown). `json` returns nodes unchanged. The metadata envelope
+// (chosen_params, truncated, diagnostic, etc.) is preserved in both.
+// When `maxChars` is given with text format, the renderer fills the
+// budget breadth-first and emits inline clip markers; the result's
+// clip stats surface to the agent so it can drill if it wants more.
+function projectTreeResponse(
+  result: Record<string, unknown>,
+  format: 'text' | 'json',
+  maxChars?: number
+): Record<string, unknown> {
+  if (format === 'json') return result;
+  const nodes = (result.nodes as TreeNode[] | undefined) ?? [];
+  const { nodes: _drop, ...rest } = result;
+  if (maxChars !== undefined) {
+    const r = renderTreeForMcpBudgeted(nodes, maxChars);
+    return {
+      tree: r.tree,
+      node_count: nodes.length,
+      rendered_events: r.rendered_events,
+      clipped_events: r.clipped_events,
+      clipped_bytes: r.clipped_bytes,
+      cutoff_depth: r.cutoff_depth,
+      partial_depth: r.partial_depth,
+      bytes_used: r.bytes_used,
+      max_chars: maxChars,
+      ...rest,
+    };
+  }
+  return {
+    tree: renderTreeForMcp(nodes),
+    node_count: nodes.length,
+    ...rest,
+  };
+}
+
+// Common filter shape shared by the find_* tools and the hotspots tools.
+const COMMON_FILTER_PROPERTIES: Record<string, unknown> = {
+  route: {
+    type: 'string',
+    description:
+      'Substring of the request path; optionally prefixed with an HTTP method ("POST /orders"). e.g. "orders" matches /orders, /api/orders/:id.',
+  },
+  status: { type: 'string', description: 'e.g. "500", ">=500", "<400".' },
+  duration: { type: 'string', description: 'e.g. ">1s", ">=500ms".' },
+  branch: { type: 'string', description: 'Exact branch name.' },
+  commit: { type: 'string', description: 'Exact commit SHA.' },
+  since: { type: 'string', description: 'ISO timestamp lower bound.' },
+  until: { type: 'string', description: 'ISO timestamp upper bound.' },
+  appmap: {
+    type: 'string',
+    description:
+      'Substring of the recording name OR source_path. Any reasonable word from the basename, test method, route, etc. matches. Case-insensitive. To target a single recording unambiguously, prefer the canonical `path` field returned by find_recordings — that\'s the absolute source_path on disk and is unique by construction.',
+  },
+  limit: {
+    type: 'integer',
+    description: 'Default 20. Pass 0 for unbounded. Response includes total count.',
+  },
+  offset: { type: 'integer', description: 'Skip this many rows for pagination.' },
+};
+
+// Build a FindFilter from MCP tool args, parsing structured fields.
+function buildFindFilter(args: Record<string, unknown>): FindFilter {
+  const f: FindFilter = {};
+  if (typeof args.route === 'string') f.route = args.route;
+  if (typeof args.class === 'string') f.className = args.class;
+  if (typeof args.method === 'string') f.method = args.method;
+  if (typeof args.label === 'string') f.label = args.label;
+  // event_id: an array of exact ids, or a lone scalar for convenience.
+  if (Array.isArray(args.event_id)) {
+    const ids = args.event_id.filter((n): n is number => typeof n === 'number');
+    if (ids.length > 0) f.eventIds = ids;
+  } else if (typeof args.event_id === 'number') {
+    f.eventIds = [args.event_id];
+  }
+  if (typeof args.branch === 'string') f.branch = args.branch;
+  if (typeof args.commit === 'string') f.commit = args.commit;
+  if (typeof args.status === 'string') f.status = parseStatus(args.status);
+  if (typeof args.duration === 'string') f.duration = parseDuration(args.duration);
+  if (typeof args.appmap === 'string') f.appmap = args.appmap;
+  if (typeof args.table === 'string') f.table = args.table;
+  if (typeof args.exception === 'string') f.exception = args.exception;
+  if (typeof args.logger === 'string') f.logger = args.logger;
+  if (typeof args.message === 'string') f.message = args.message;
+  const withLogs = maybeNumber(args.with_logs);
+  if (withLogs !== undefined) f.withLogs = withLogs;
+  f.since = maybeTime(args.since);
+  f.until = maybeTime(args.until);
+  f.limit = maybeNumber(args.limit);
+  f.offset = maybeNumber(args.offset);
+  return f;
+}
+
+// --- tools --------------------------------------------------------------
+
+const TOOLS: ToolImpl[] = [
+  // ----- aggregations ----------------------------------------------------
+
+  {
+    spec: {
+      name: 'list_endpoints',
+      description:
+        'Per-route summary table; the first call when orienting against an unfamiliar query database. Returns Page<{method, route, count, avg_ms, p95_ms, err_pct}> = {rows, total, limit, offset}.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          branch: { type: 'string' },
+          since: { type: 'string' },
+          until: { type: 'string' },
+          status: {
+            type: 'string',
+            description:
+              'Route filter — e.g. ">=500". A route is shown if any request matches; aggregates remain over all of that route\'s requests.',
+          },
+          sort: { type: 'string', enum: ['count', 'avg', 'p95', 'err'] },
+          limit: { type: 'integer' },
+        },
+      },
+    },
+    handler: (args, { db }) => {
+      const f: EndpointsFilter = {};
+      f.branch = maybeString(args.branch);
+      f.since = maybeTime(args.since);
+      f.until = maybeTime(args.until);
+      if (typeof args.status === 'string') f.status = parseStatus(args.status);
+      if (typeof args.sort === 'string') f.sort = args.sort as EndpointSort;
+      f.limit = maybeNumber(args.limit);
+      return endpoints(db, f);
+    },
+  },
+
+  {
+    spec: {
+      name: 'function_hotspots',
+      description:
+        'Functions ranked by total elapsed time across recordings. Filter by `route` (scope to one entry point) or `class` (substring). path/lineno are one representative call\'s source location — read directly. fqid forms: "app/Logger#error" (instance), "app/Util.parse" (static), "module.fn" (module-level), "Outer::Inner#method" (nested).',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          route: COMMON_FILTER_PROPERTIES.route,
+          class: { type: 'string', description: 'Substring of class identifier; canonical fqid forms also accepted.' },
+          branch: COMMON_FILTER_PROPERTIES.branch,
+          since: COMMON_FILTER_PROPERTIES.since,
+          until: COMMON_FILTER_PROPERTIES.until,
+          limit: COMMON_FILTER_PROPERTIES.limit,
+          offset: COMMON_FILTER_PROPERTIES.offset,
+        },
+      },
+    },
+    handler: (args, { db }) =>
+      hotspots(db, {
+        type: 'function',
+        route: maybeString(args.route),
+        className: maybeString(args.class),
+        branch: maybeString(args.branch),
+        since: maybeTime(args.since),
+        until: maybeTime(args.until),
+        limit: maybeNumber(args.limit),
+        offset: maybeNumber(args.offset),
+      }),
+  },
+
+  {
+    spec: {
+      name: 'sql_hotspots',
+      description:
+        'SQL queries ranked by total elapsed time, deduplicated by text. Returns Page<{count, avg_ms, total_ms, sql_text}> = {rows, total, limit, offset}.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          route: COMMON_FILTER_PROPERTIES.route,
+          branch: COMMON_FILTER_PROPERTIES.branch,
+          since: COMMON_FILTER_PROPERTIES.since,
+          until: COMMON_FILTER_PROPERTIES.until,
+          limit: COMMON_FILTER_PROPERTIES.limit,
+          offset: COMMON_FILTER_PROPERTIES.offset,
+        },
+      },
+    },
+    handler: (args, { db }) =>
+      hotspots(db, {
+        type: 'sql',
+        route: maybeString(args.route),
+        branch: maybeString(args.branch),
+        since: maybeTime(args.since),
+        until: maybeTime(args.until),
+        limit: maybeNumber(args.limit),
+        offset: maybeNumber(args.offset),
+      }),
+  },
+
+  {
+    spec: {
+      name: 'list_labels',
+      description:
+        'AppMap labels in the database, ranked by usage. Discovers what semantic anchors exist (canonical examples: "log", "security.authentication", "security.authorization", "deserialize", "system.exec") and project-specific labels (e.g. "bug.<id>"). Pass a returned label to `find_calls --label` to retrieve its calls.',
+      inputSchema: { type: 'object', properties: {} },
+    },
+    handler: (_args, { db }) =>
+      db
+        .prepare(
+          `SELECT l.label                  AS label,
+                  COUNT(DISTINCT co.id)    AS count,
+                  MIN(co.fqid)             AS sample_fqid
+           FROM labels l
+           JOIN code_objects co ON co.id = l.code_object_id
+           GROUP BY l.label
+           ORDER BY count DESC, l.label`
+        )
+        .all(),
+  },
+
+  // ----- row-level finders ----------------------------------------------
+
+  {
+    spec: {
+      name: 'find_recordings',
+      description:
+        'Recording-level rows: one row per .appmap.json file with its sample request, branch, status, and counts. `appmap` filter is substring match against name and source_path. `path` is the canonical recording identifier (absolute file path on disk) — pass it back to `get_call_tree`, `find_related`, and the `--appmap` filter on other queries. `kind` ∈ {"junit" (full test), "request" (per-HTTP slice), "other"}; prefer junit for full-flow context.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          route: COMMON_FILTER_PROPERTIES.route,
+          status: COMMON_FILTER_PROPERTIES.status,
+          branch: COMMON_FILTER_PROPERTIES.branch,
+          commit: COMMON_FILTER_PROPERTIES.commit,
+          since: COMMON_FILTER_PROPERTIES.since,
+          until: COMMON_FILTER_PROPERTIES.until,
+          duration: COMMON_FILTER_PROPERTIES.duration,
+          appmap: COMMON_FILTER_PROPERTIES.appmap,
+          limit: COMMON_FILTER_PROPERTIES.limit,
+          offset: COMMON_FILTER_PROPERTIES.offset,
+        },
+      },
+    },
+    handler: (args, { db }) => {
+      const page = find(db, 'appmaps', buildFindFilter(args)) as Page<FindAppmapRow>;
+      return {
+        ...page,
+        rows: page.rows.map((r) => decorateRecording(r)),
+      };
+    },
+  },
+
+  {
+    spec: {
+      name: 'find_requests',
+      description:
+        'Individual HTTP request rows with status, elapsed time, and the recording each came from. Filter by route (substring), status, duration, branch, time window. Returns Page<{appmap_name, event_id, method, route, status_code, elapsed_ms, branch}> = {rows, total, limit, offset}.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          route: COMMON_FILTER_PROPERTIES.route,
+          status: COMMON_FILTER_PROPERTIES.status,
+          duration: COMMON_FILTER_PROPERTIES.duration,
+          branch: COMMON_FILTER_PROPERTIES.branch,
+          commit: COMMON_FILTER_PROPERTIES.commit,
+          since: COMMON_FILTER_PROPERTIES.since,
+          until: COMMON_FILTER_PROPERTIES.until,
+          appmap: COMMON_FILTER_PROPERTIES.appmap,
+          limit: COMMON_FILTER_PROPERTIES.limit,
+          offset: COMMON_FILTER_PROPERTIES.offset,
+        },
+      },
+    },
+    handler: (args, { db }) => find(db, 'requests', buildFindFilter(args)),
+  },
+
+  {
+    spec: {
+      name: 'find_queries',
+      description:
+        'SQL query rows. Filter by table (substring), caller class/method (substring), duration, route, branch. Use duration:">100ms" to find slow queries; use route to scope to a specific request. Returns Page<{appmap_name, event_id, sql_text, elapsed_ms, caller_class, caller_method}> = {rows, total, limit, offset}.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          table: { type: 'string', description: 'SQL table name (matches sql_text substring).' },
+          class: { type: 'string', description: 'Caller class identifier.' },
+          method: { type: 'string', description: 'Caller method name.' },
+          duration: COMMON_FILTER_PROPERTIES.duration,
+          route: COMMON_FILTER_PROPERTIES.route,
+          status: COMMON_FILTER_PROPERTIES.status,
+          branch: COMMON_FILTER_PROPERTIES.branch,
+          commit: COMMON_FILTER_PROPERTIES.commit,
+          since: COMMON_FILTER_PROPERTIES.since,
+          until: COMMON_FILTER_PROPERTIES.until,
+          appmap: COMMON_FILTER_PROPERTIES.appmap,
+          limit: COMMON_FILTER_PROPERTIES.limit,
+          offset: COMMON_FILTER_PROPERTIES.offset,
+        },
+      },
+    },
+    handler: (args, { db }) => find(db, 'queries', buildFindFilter(args)),
+  },
+
+  {
+    spec: {
+      name: 'find_calls',
+      description:
+        'Function-call rows. Filter by `class` (substring), `method` (substring), `label` (e.g. "log", "security.authorization"), `duration`, `appmap`, or `event_id` (exact ids — e.g. drilled off a get_call_tree `#id` — returned with full, untruncated parameters_json / return_value). Class syntax: short ("Cipher") matches any leaf class; package-qualified ("app/services/Payment") strict-matches; "Class#method" for instance, "Class.method" for static; class+method may be combined. parameters_json and return_value are captured for every call. When the result is empty, response includes `diagnostic.did_you_mean` and a `hint` — read it before guessing another identifier shape.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          class: {
+            type: 'string',
+            description:
+              'Class name. Bare class ("UserRepository") matches any leaf class with that name; slash-separated package form ("app/services/UserRepository") scopes to one definition; substrings match ("Repo" finds "UserRepository"). Combine with `method` to filter by both. On empty results, `diagnostic.hint` reports the actual indexed form to retry with.',
+          },
+          method: {
+            type: 'string',
+            description:
+              'Method name. Bare identifier ("submit") or substring ("subm" finds "submit"). Combine with `class` to filter by both.',
+          },
+          label: { type: 'string', description: 'Substring of the label name.' },
+          event_id: {
+            type: 'array',
+            items: { type: 'integer' },
+            description:
+              'Exact event_id(s) to fetch — e.g. ids read off a get_call_tree `#id`. Returns those rows with full, untruncated parameters_json and return_value. Pass several ids in one call to drill a set of sibling calls at once.',
+          },
+          duration: COMMON_FILTER_PROPERTIES.duration,
+          route: COMMON_FILTER_PROPERTIES.route,
+          status: COMMON_FILTER_PROPERTIES.status,
+          branch: COMMON_FILTER_PROPERTIES.branch,
+          commit: COMMON_FILTER_PROPERTIES.commit,
+          since: COMMON_FILTER_PROPERTIES.since,
+          until: COMMON_FILTER_PROPERTIES.until,
+          appmap: COMMON_FILTER_PROPERTIES.appmap,
+          limit: COMMON_FILTER_PROPERTIES.limit,
+          offset: COMMON_FILTER_PROPERTIES.offset,
+        },
+      },
+    },
+    handler: (args, { db }) => {
+      const filter = buildFindFilter(args);
+      const page = find(db, 'calls', filter) as Page<FindCallRow>;
+      // Empty results from a class/method query are usually identifier
+      // typos, not "the function genuinely didn't fire." Attach a
+      // diagnostic so the next call lands instead of triggering yet
+      // another shot-in-the-dark retry.
+      if (page.rows.length === 0 && (filter.className || filter.method)) {
+        const diagnostic = suggestSimilarFunctionIds(db, filter.className, filter.method);
+        return { ...page, diagnostic };
+      }
+      return page;
+    },
+  },
+
+  {
+    spec: {
+      name: 'find_logs',
+      description:
+        'Application log lines captured from functions labeled `log`. Filter by `message` (substring), `class` (logger), recording, branch, or time. `message` is the display-projected log text — use it directly. Use path:lineno to read the call site.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          message: {
+            type: 'string',
+            description:
+              'Substring to look for inside the captured log call. Matches a SQL LIKE against parameters_json and return_value — false positives (e.g. matching a class or parameter name) are accepted; tighten in post-processing if needed.',
+          },
+          logger: {
+            type: 'string',
+            description:
+              'Class of the logging function (defined_class). Accepts short or canonical fqid form, same as find_calls --class.',
+          },
+          branch: COMMON_FILTER_PROPERTIES.branch,
+          commit: COMMON_FILTER_PROPERTIES.commit,
+          since: COMMON_FILTER_PROPERTIES.since,
+          until: COMMON_FILTER_PROPERTIES.until,
+          appmap: COMMON_FILTER_PROPERTIES.appmap,
+          limit: COMMON_FILTER_PROPERTIES.limit,
+          offset: COMMON_FILTER_PROPERTIES.offset,
+        },
+      },
+    },
+    handler: (args, { db }) => find(db, 'logs', buildFindFilter(args)),
+  },
+
+  {
+    spec: {
+      name: 'find_exceptions',
+      description:
+        'Exception rows with class, message, source location. Filter by exception class (substring), route, status, branch, or time. Pass `with_logs=N` to attach the last N log lines preceding the throw under `recent_logs` — usually the fastest way to see what the app reported before the failure (logs from inside the throwing call are included).',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          exception: { type: 'string', description: 'Substring of the exception class name.' },
+          with_logs: {
+            type: 'integer',
+            description: 'Attach up to N preceding log lines per exception under recent_logs (chronological). Each entry has the same shape as a find_logs row.',
+          },
+          route: COMMON_FILTER_PROPERTIES.route,
+          status: COMMON_FILTER_PROPERTIES.status,
+          branch: COMMON_FILTER_PROPERTIES.branch,
+          commit: COMMON_FILTER_PROPERTIES.commit,
+          since: COMMON_FILTER_PROPERTIES.since,
+          until: COMMON_FILTER_PROPERTIES.until,
+          appmap: COMMON_FILTER_PROPERTIES.appmap,
+          limit: COMMON_FILTER_PROPERTIES.limit,
+          offset: COMMON_FILTER_PROPERTIES.offset,
+        },
+      },
+    },
+    handler: (args, { db }) => find(db, 'exceptions', buildFindFilter(args)),
+  },
+
+  // ----- per-recording / cross-recording --------------------------------
+
+  {
+    spec: {
+      name: 'get_call_tree',
+      description:
+        'Call tree of one recording. **First call**: `get_call_tree(appmap=<path>)` — returns text-format tree, capped at 12,000 chars by default with inline `[clipped: N events, B bytes; drill via child_depth=K or focus on #event]` markers at cut sites. `appmap` must be the `path` field from `find_recordings` (absolute file path; names/ids rejected). Optional params: `max_chars=N` to widen or narrow the byte budget; `child_depth=N` to cap fetch depth (caps what the budget can render); `focus_type` ∈ {function, sql_query, http_server_request, http_client_request} + `focus_value` to narrow to a function/SQL/route; `min_elapsed_ms` to prune fast leaves; `format="json"` for nodes[] with full structured fields (args/return_value/etc.) — JSON ignores max_chars and uses the legacy depth auto-tune. Response signals: `clipped_events`/`clipped_bytes` + per-marker drill anchors; `summary_mode` + `suggested_drilldown` (JSON only — recording too big at fetched depth); `diagnostic` (focus matched nothing — re-aim).',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          appmap: {
+            type: 'string',
+            description:
+              'Canonical recording path — the `path` field returned by find_recordings (the absolute file path on disk).',
+          },
+          focus_type: {
+            type: 'string',
+            enum: ['function', 'sql_query', 'http_server_request', 'http_client_request'],
+          },
+          focus_value: { type: 'string' },
+          parent_depth: { type: 'integer', description: 'Ancestor levels (default 5).' },
+          child_depth: {
+            type: 'integer',
+            description:
+              'Descendant levels. When omitted, defaults to 4 for narrow per-request recordings and 2 for broad junit/process recordings (event_count > 500).',
+          },
+          min_elapsed_ms: { type: 'number' },
+          format: {
+            type: 'string',
+            enum: ['text', 'json'],
+            description:
+              'Tree-body format. `text` (default): indented one-line-per-event, prefixed with `#event_id` for drilldown. `json`: nodes[] array with full structured fields (args, return_value, etc.). Text is ~3-5× more compact; use json when you need structured fields the text form drops.',
+          },
+          max_chars: {
+            type: 'integer',
+            description:
+              'Byte budget for the rendered tree. Default 12000 in text mode. Breadth-first fill: each depth completes before the next, the final layer partial-fills in event_id order, clipped subtrees get inline `[clipped: N events, B bytes; drill via child_depth=K or focus on #event]` markers at the cut sites. Response surfaces `rendered_events`, `clipped_events`, `clipped_bytes`, `cutoff_depth`, `partial_depth`. When both `max_chars` and `child_depth` are set, both apply as upper bounds — the more restrictive wins on each axis (bytes can only shrink what depth provides; depth can only cap what bytes would have allowed). Ignored for `format=json`.',
+          },
+        },
+        required: ['appmap'],
+      },
+    },
+    handler: (args, { db }) => {
+      const am = resolveAppmapPath(db, args.appmap);
+      const shape = readRecordingShape(db, am.id);
+
+      const focusType = maybeString(args.focus_type);
+      const focusValue = maybeString(args.focus_value);
+      const parentDepthIn = maybeNumber(args.parent_depth);
+      const childDepthIn = maybeNumber(args.child_depth);
+      const format = maybeString(args.format) === 'json' ? 'json' : 'text';
+      // Text mode: max_chars governs the response by default. Caller
+      // can override by passing max_chars; json mode ignores max_chars
+      // (the auto-tune below + RESPONSE_BUDGET_CHARS summary fallback
+      // serve as the safety net there).
+      const maxCharsIn = maybeNumber(args.max_chars);
+      const maxChars =
+        format === 'text' ? (maxCharsIn ?? DEFAULT_MAX_CHARS) : maxCharsIn;
+
+      // Pick the DB-fetch depth. Text mode (the default) goes through
+      // the byte-budgeted renderer, so we fetch deep and let the
+      // renderer trim — depth-based pre-pruning would hide useful
+      // material from the budget fill. JSON mode keeps the legacy
+      // event-count auto-tune as a safety net since max_chars doesn't
+      // apply there.
+      const broadDefault = isBroadRecording(shape);
+      let chosenChildDepth = childDepthIn;
+      let autoReason: string | undefined;
+      if (chosenChildDepth === undefined && format === 'text') {
+        chosenChildDepth = DEEP_FETCH_DEPTH_FOR_BUDGET;
+        autoReason =
+          `text mode (max_chars=${maxChars}); fetching deep ` +
+          `(child_depth=${DEEP_FETCH_DEPTH_FOR_BUDGET}) and letting the renderer ` +
+          `trim by bytes. Pass child_depth explicitly to cap depth.`;
+      } else if (chosenChildDepth === undefined && broadDefault) {
+        chosenChildDepth = BROAD_DEFAULT_CHILD_DEPTH;
+        autoReason =
+          `${shape.recorder_type ?? 'process-wide'} recording has ${shape.event_count} events; ` +
+          `using child_depth=${BROAD_DEFAULT_CHILD_DEPTH} to fit the response budget. ` +
+          `Pass child_depth explicitly to override.`;
+      }
+
+      const opts: TreeOptions = {};
+      if (focusType && focusValue) {
+        if (focusType === 'function') opts.focusFn = focusValue;
+        else if (focusType === 'sql_query') opts.focusSql = focusValue;
+        else if (focusType === 'http_server_request') opts.focusRoute = focusValue;
+        else if (focusType === 'http_client_request') opts.focusUrl = focusValue;
+      }
+      opts.ancestors = parentDepthIn;
+      opts.descendants = chosenChildDepth;
+      opts.minElapsedMs = maybeNumber(args.min_elapsed_ms);
+
+      // Pass am.source_path so resolveAppmap inside tree() exact-matches
+      // (source_path is UNIQUE) instead of GLOB-matching, which can
+      // re-trigger ambiguity on duplicate-basename recordings.
+      const meta = treeWithMeta(db, am.source_path, opts);
+
+      const chosenParams = {
+        parent_depth: parentDepthIn ?? null,
+        child_depth: chosenChildDepth ?? null,
+        focus_type: focusType ?? null,
+        focus_value: focusValue ?? null,
+      };
+
+      // Empty-focus diagnostic: focus excluded everything. Without this
+      // signal the agent only sees nodes:[] and can't tell whether the
+      // filter was wrong or the recording genuinely lacked the kind.
+      if (focusType && focusValue && meta.nodes.length === 0) {
+        return projectTreeResponse(
+          {
+            ...meta,
+            chosen_params: chosenParams,
+            ...(autoReason ? { reason: autoReason } : {}),
+            diagnostic: buildEmptyFocusDiagnostic(focusType, shape),
+          },
+          format,
+          maxChars
+        );
+      }
+
+      // When the caller supplied max_chars with text format, the
+      // budgeted renderer handles clipping inline — skip summary-mode
+      // fallback entirely.
+      if (maxChars === undefined || format !== 'text') {
+        // Budget check: if the rendered response would still be huge, fall
+        // back to summary mode (entry-points + exceptions in `nodes`,
+        // top-N functions in `suggested_drilldown`). Avoids the LLM seeing
+        // a truncated-mid-traversal tree that gives no useful evidence.
+        // For budget projection use the format the agent actually asked
+        // for — text bodies are 3-5× smaller, so a tree that overflows
+        // in json may fit easily in text and shouldn't be summarized.
+        const projected =
+          format === 'text'
+            ? renderTreeForMcp(meta.nodes).length +
+              JSON.stringify({ chosen_params: chosenParams }).length
+            : JSON.stringify({ ...meta, chosen_params: chosenParams }).length;
+        if (projected > RESPONSE_BUDGET_CHARS) {
+          const summary = buildSummaryResponse(meta, chosenParams, shape, projected);
+          return projectTreeResponse(summary, format, maxChars);
+        }
+      }
+
+      return projectTreeResponse(
+        {
+          ...meta,
+          chosen_params: chosenParams,
+          ...(autoReason ? { reason: autoReason } : {}),
+        },
+        format,
+        maxChars
+      );
+    },
+  },
+
+  {
+    spec: {
+      name: 'find_related',
+      description:
+        'Recordings ranked by similarity to a source recording. Score combines: same HTTP route (×5), shared SQL tables (×3 each), shared classes (×2 each). Primary use: pass a failing recording with status:succeeded to find a passing baseline for side-by-side comparison. Returns Page<{appmap_name, score, method, route, status_code, elapsed_ms, shared}> = {rows, total, limit, offset}. shared is a string array of contributing signals.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          appmap: {
+            type: 'string',
+            description:
+              'Canonical source recording path — the `path` field returned by find_recordings (the absolute file path on disk).',
+          },
+          status: COMMON_FILTER_PROPERTIES.status,
+          route: COMMON_FILTER_PROPERTIES.route,
+          branch: COMMON_FILTER_PROPERTIES.branch,
+          since: COMMON_FILTER_PROPERTIES.since,
+          until: COMMON_FILTER_PROPERTIES.until,
+          limit: COMMON_FILTER_PROPERTIES.limit,
+          offset: COMMON_FILTER_PROPERTIES.offset,
+        },
+        required: ['appmap'],
+      },
+    },
+    handler: (args, { db }) => {
+      const am = resolveAppmapPath(db, args.appmap);
+      const filter: RelatedFilter = {};
+      if (typeof args.status === 'string') filter.status = parseStatus(args.status);
+      filter.route = maybeString(args.route);
+      filter.branch = maybeString(args.branch);
+      filter.since = maybeTime(args.since);
+      filter.until = maybeTime(args.until);
+      filter.limit = maybeNumber(args.limit);
+      filter.offset = maybeNumber(args.offset);
+      return related(db, am.source_path, filter);
+    },
+  },
+
+  {
+    spec: {
+      name: 'compare_branches',
+      description:
+        'Per-route p95 latency for two branches with a delta column. Use to surface regressions a feature branch introduces relative to a baseline. Returns Page<{method, route, a_count, a_p95_ms, b_count, b_p95_ms, delta}> = {rows, total, limit, offset}. delta is b_p95/a_p95; null when either side has no measured durations.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          branch_a: { type: 'string', description: 'Baseline branch.' },
+          branch_b: { type: 'string', description: 'Comparison branch.' },
+          since: COMMON_FILTER_PROPERTIES.since,
+          until: COMMON_FILTER_PROPERTIES.until,
+          sort: { type: 'string', enum: ['delta', 'p95-a', 'p95-b'] },
+          limit: COMMON_FILTER_PROPERTIES.limit,
+          offset: COMMON_FILTER_PROPERTIES.offset,
+        },
+        required: ['branch_a', 'branch_b'],
+      },
+    },
+    handler: (args, { db }) =>
+      compare(db, {
+        branch_a: String(args.branch_a),
+        branch_b: String(args.branch_b),
+        since: maybeTime(args.since),
+        until: maybeTime(args.until),
+        sort: maybeString(args.sort) as 'delta' | 'p95-a' | 'p95-b' | undefined,
+        limit: maybeNumber(args.limit),
+        offset: maybeNumber(args.offset),
+      }),
+  },
+];
+
+// --- resources -----------------------------------------------------------
+
+const RESOURCES: ResourceImpl[] = [
+  {
+    spec: {
+      uri: 'appmap://endpoints',
+      name: 'endpoints',
+      description:
+        'All HTTP endpoints with request count, average latency, p95, and error rate.',
+      mimeType: 'application/json',
+    },
+    read: ({ db }) => endpoints(db, { limit: 200 }),
+  },
+];
+
+const RESOURCE_TEMPLATES: ResourceTemplateImpl[] = [
+  {
+    spec: {
+      uriTemplate: 'appmap://recording/{ref}/logs',
+      name: 'recording_logs',
+      description:
+        'All log lines (functions labeled `log`) for one recording, ordered by event_id. {ref} is the canonical recording path (find_recordings\' `path` field — the absolute file path on disk; URL-encode it). Each entry has the find_logs row shape.',
+      mimeType: 'application/json',
+    },
+    match: (uri) => {
+      const m = /^appmap:\/\/recording\/([^/]+)\/logs$/.exec(uri);
+      if (!m) return null;
+      // The {ref} segment may be percent-encoded (recording names can
+      // contain spaces, em-dashes, etc.).
+      return { ref: decodeURIComponent(m[1]) };
+    },
+    read: (args, { db }) => {
+      const info = resolveAppmapPath(db, args.ref);
+      return find(db, 'logs', { appmap: info.source_path, limit: 0 });
+    },
+  },
+];
+
+// --- handler -------------------------------------------------------------
+
+export type McpHandler = (msg: JsonRpcRequest) => JsonRpcResponse | null;
+
+export function buildMcpHandler(db: sqlite3.Database): McpHandler {
+  const ctx: McpContext = { db };
+  return (msg: JsonRpcRequest): JsonRpcResponse | null => {
+    const id = msg.id ?? null;
+    const method = msg.method;
+
+    if (method.startsWith('notifications/')) return null;
+
+    if (method === 'initialize') {
+      return {
+        jsonrpc: '2.0',
+        id,
+        result: {
+          protocolVersion: PROTOCOL_VERSION,
+          serverInfo: SERVER_INFO,
+          capabilities: { tools: {}, resources: {} },
+        },
+      };
+    }
+
+    if (method === 'tools/list') {
+      return {
+        jsonrpc: '2.0',
+        id,
+        result: { tools: TOOLS.map((t) => t.spec) },
+      };
+    }
+
+    if (method === 'tools/call') {
+      const params = (msg.params ?? {}) as { name?: string; arguments?: Record<string, unknown> };
+      const name = params.name;
+      const args = params.arguments ?? {};
+      const tool = TOOLS.find((t) => t.spec.name === name);
+      if (!tool) return errorResponse(id, -32601, `unknown tool: ${name}`);
+      try {
+        const result = tool.handler(args, ctx);
+        return {
+          jsonrpc: '2.0',
+          id,
+          result: {
+            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+          },
+        };
+      } catch (e) {
+        return errorResponse(id, -32000, (e as Error).message);
+      }
+    }
+
+    if (method === 'resources/list') {
+      return {
+        jsonrpc: '2.0',
+        id,
+        result: { resources: RESOURCES.map((r) => r.spec) },
+      };
+    }
+
+    if (method === 'resources/templates/list') {
+      return {
+        jsonrpc: '2.0',
+        id,
+        result: { resourceTemplates: RESOURCE_TEMPLATES.map((t) => t.spec) },
+      };
+    }
+
+    if (method === 'resources/read') {
+      const params = (msg.params ?? {}) as { uri?: string };
+      const uri = params.uri ?? '';
+      const resource = RESOURCES.find((r) => r.spec.uri === uri);
+      if (resource) {
+        try {
+          const result = resource.read(ctx);
+          return readResponse(id, uri, resource.spec.mimeType, result);
+        } catch (e) {
+          return errorResponse(id, -32000, (e as Error).message);
+        }
+      }
+      for (const tmpl of RESOURCE_TEMPLATES) {
+        const matched = tmpl.match(uri);
+        if (matched) {
+          try {
+            const result = tmpl.read(matched, ctx);
+            return readResponse(id, uri, tmpl.spec.mimeType, result);
+          } catch (e) {
+            return errorResponse(id, -32000, (e as Error).message);
+          }
+        }
+      }
+      return errorResponse(id, -32602, `unknown resource: ${uri}`);
+    }
+
+    return errorResponse(id, -32601, `method not found: ${method}`);
+  };
+}
+
+function errorResponse(
+  id: string | number | null,
+  code: number,
+  message: string
+): JsonRpcResponse {
+  return { jsonrpc: '2.0', id, error: { code, message } };
+}
+
+function readResponse(
+  id: string | number | null,
+  uri: string,
+  mimeType: string,
+  result: unknown
+): JsonRpcResponse {
+  return {
+    jsonrpc: '2.0',
+    id,
+    result: {
+      contents: [
+        {
+          uri,
+          mimeType,
+          text: JSON.stringify(result, null, 2),
+        },
+      ],
+    },
+  };
+}
+
+export function listTools(): readonly ToolSpec[] {
+  return TOOLS.map((t) => t.spec);
+}
+
+export function listResources(): readonly ResourceSpec[] {
+  return RESOURCES.map((r) => r.spec);
+}
+
+export function listResourceTemplates(): readonly ResourceTemplateSpec[] {
+  return RESOURCE_TEMPLATES.map((t) => t.spec);
+}
diff --git a/packages/cli/src/cmds/query/queries/related.ts b/packages/cli/src/cmds/query/queries/related.ts
new file mode 100644
index 0000000000..1e36963acd
--- /dev/null
+++ b/packages/cli/src/cmds/query/queries/related.ts
@@ -0,0 +1,201 @@
+import sqlite3 from 'better-sqlite3';
+
+import { DEFAULT_PAGE_LIMIT, Page } from '../lib/page';
+import { appmapWhere, httpScopeClauses, RecordingScope } from '../lib/scope';
+import { resolveAppmap } from './tree';
+
+// Score weights, from V3:
+//   same HTTP route   ×5  (binary)
+//   same SQL tables   ×3  (per shared table)
+//   same classes      ×2  (per shared class)
+const ROUTE_WEIGHT = 5;
+const TABLE_WEIGHT = 3;
+const CLASS_WEIGHT = 2;
+
+// Heuristic table-name extraction. Matches identifiers following
+// FROM/JOIN/INTO/UPDATE; strips a single leading schema qualifier and
+// lowercases for case-insensitive matching. Imperfect (won't handle
+// nested subqueries / unusual quoting cleanly) but adequate for the
+// similarity score, which is itself a heuristic.
+const TABLE_PATTERN = /\b(?:FROM|JOIN|INTO|UPDATE)\s+["`]?(?:\w+\.)?(\w+)["`]?/gi;
+
+export function extractTables(sqlText: string): Set<string> {
+  const tables = new Set<string>();
+  TABLE_PATTERN.lastIndex = 0;
+  let m: RegExpExecArray | null;
+  while ((m = TABLE_PATTERN.exec(sqlText)) !== null) {
+    tables.add(m[1].toLowerCase());
+  }
+  return tables;
+}
+
+export interface RelatedRow {
+  appmap_name: string;
+  score: number;
+  method: string | null;
+  route: string | null;
+  status_code: number | null;
+  elapsed_ms: number | null;
+  shared: string[];
+}
+
+export interface RelatedFilter extends RecordingScope {
+  limit?: number;
+  offset?: number;
+}
+
+interface AppmapSig {
+  id: number;
+  name: string;
+  method: string | null;
+  route: string | null;
+  status_code: number | null;
+  elapsed_ms: number | null;
+  tables: Set<string>;
+  classes: Set<string>;
+}
+
+// Strip trailing class name from a defined_class string. Handles Java/Python
+// dot-form ("org.example.X" → "X") and Ruby/C++ chain ("Foo::Bar" → "Bar").
+function leafFromDefinedClass(s: string): string {
+  const ddIdx = s.lastIndexOf('::');
+  const dotIdx = s.lastIndexOf('.');
+  const idx = Math.max(ddIdx, dotIdx);
+  return idx >= 0 ? s.slice(idx + (s[idx] === ':' ? 2 : 1)) : s;
+}
+
+function loadSignature(db: sqlite3.Database, appmapId: number): AppmapSig {
+  const meta = db
+    .prepare(
+      `SELECT a.id, a.name, a.elapsed_ms,
+              (SELECT h.method FROM http_requests h WHERE h.appmap_id = a.id
+                 ORDER BY h.event_id LIMIT 1) AS method,
+              (SELECT COALESCE(h.normalized_path, h.path) FROM http_requests h
+                 WHERE h.appmap_id = a.id ORDER BY h.event_id LIMIT 1) AS route,
+              (SELECT h.status_code FROM http_requests h
+                 WHERE h.appmap_id = a.id ORDER BY h.event_id LIMIT 1) AS status_code
+       FROM appmaps a WHERE a.id = ?`
+    )
+    .get(appmapId) as {
+    id: number;
+    name: string;
+    elapsed_ms: number | null;
+    method: string | null;
+    route: string | null;
+    status_code: number | null;
+  };
+
+  const sqlRows = db
+    .prepare(`SELECT sql_text FROM sql_queries WHERE appmap_id = ?`)
+    .all(appmapId) as { sql_text: string }[];
+  const tables = new Set<string>();
+  for (const r of sqlRows) for (const t of extractTables(r.sql_text)) tables.add(t);
+
+  const classes = new Set<string>();
+  for (const r of db
+    .prepare(
+      `SELECT DISTINCT co.leaf_class AS name FROM code_objects co
+       JOIN function_calls fc ON fc.code_object_id = co.id
+       WHERE fc.appmap_id = ?`
+    )
+    .all(appmapId) as { name: string }[]) {
+    if (r.name) classes.add(r.name);
+  }
+  // Fall back to defined_class for unlinked rows so sparsely-linked
+  // recordings still contribute classes to the score.
+  for (const r of db
+    .prepare(
+      `SELECT DISTINCT fc.defined_class AS name FROM function_calls fc
+       WHERE fc.appmap_id = ? AND fc.code_object_id IS NULL`
+    )
+    .all(appmapId) as { name: string }[]) {
+    if (r.name) classes.add(leafFromDefinedClass(r.name));
+  }
+
+  return { ...meta, tables, classes };
+}
+
+export function related(
+  db: sqlite3.Database,
+  sourceRef: string,
+  filter: RelatedFilter = {}
+): Page<RelatedRow> {
+  const source = resolveAppmap(db, sourceRef);
+  const sourceSig = loadSignature(db, source.id);
+
+  // Candidate pool: appmaps matching recording-level / http filters,
+  // excluding the source itself.
+  const a = appmapWhere(filter, 'a');
+  const h = httpScopeClauses(filter);
+
+  const whereParts: string[] = ['a.id != ?'];
+  const params: (string | number)[] = [source.id];
+
+  whereParts.push(...a.where);
+  params.push(...a.params);
+
+  if (h.where.length > 0) {
+    whereParts.push(`EXISTS (
+      SELECT 1 FROM http_requests h WHERE h.appmap_id = a.id AND ${h.where.join(' AND ')}
+    )`);
+    params.push(...h.params);
+  }
+
+  const candidates = db
+    .prepare(`SELECT a.id FROM appmaps a WHERE ${whereParts.join(' AND ')} ORDER BY a.id`)
+    .all(...params) as { id: number }[];
+
+  const scored: RelatedRow[] = [];
+  for (const c of candidates) {
+    const sig = loadSignature(db, c.id);
+
+    let score = 0;
+    const shared: string[] = [];
+
+    // Route match (binary). Method is part of the comparison only if the
+    // source has one — recordings without an http_server_request are
+    // matched purely on path.
+    if (
+      sourceSig.route &&
+      sig.route === sourceSig.route &&
+      (!sourceSig.method || sig.method === sourceSig.method)
+    ) {
+      score += ROUTE_WEIGHT;
+      shared.push('route');
+    }
+
+    for (const t of sig.tables) {
+      if (sourceSig.tables.has(t)) {
+        score += TABLE_WEIGHT;
+        shared.push(t);
+      }
+    }
+
+    for (const cls of sig.classes) {
+      if (sourceSig.classes.has(cls)) {
+        score += CLASS_WEIGHT;
+        shared.push(cls);
+      }
+    }
+
+    if (score > 0) {
+      scored.push({
+        appmap_name: sig.name,
+        score,
+        method: sig.method,
+        route: sig.route,
+        status_code: sig.status_code,
+        elapsed_ms: sig.elapsed_ms,
+        shared,
+      });
+    }
+  }
+
+  scored.sort((a, b) => b.score - a.score);
+
+  const limit = filter.limit ?? DEFAULT_PAGE_LIMIT;
+  const offset = filter.offset ?? 0;
+  const total = scored.length;
+  const sliced = limit > 0 ? scored.slice(offset, offset + limit) : scored.slice(offset);
+  return { rows: sliced, total, limit, offset };
+}
diff --git a/packages/cli/src/cmds/query/queries/tree.ts b/packages/cli/src/cmds/query/queries/tree.ts
new file mode 100644
index 0000000000..d94b2d14b1
--- /dev/null
+++ b/packages/cli/src/cmds/query/queries/tree.ts
@@ -0,0 +1,657 @@
+import sqlite3 from 'better-sqlite3';
+
+import { looksLikeDisplayLabel } from '../lib/appmapPath';
+import { projectLogMessage } from '../lib/logMessage';
+import { appmapRefClause } from '../lib/scope';
+
+// Discriminated union of tree nodes. Each node corresponds to one row in
+// one of the per-event tables; `depth` is computed from parent_event_id
+// chains within the same recording.
+
+interface BaseNode {
+  event_id: number;
+  parent_event_id: number | null;
+  thread_id: number | null;
+  depth: number;
+}
+
+export interface HttpServerNode extends BaseNode {
+  kind: 'http_server';
+  method: string;
+  route: string;
+  status_code: number;
+  elapsed_ms: number | null;
+}
+
+export interface HttpClientNode extends BaseNode {
+  kind: 'http_client';
+  method: string;
+  url: string;
+  status_code: number | null;
+  elapsed_ms: number | null;
+}
+
+export interface SqlNode extends BaseNode {
+  kind: 'sql';
+  sql_text: string;
+  database_type: string | null;
+  elapsed_ms: number | null;
+}
+
+export interface FunctionNode extends BaseNode {
+  kind: 'function';
+  fqid: string | null;
+  defined_class: string;
+  method_id: string;
+  path: string | null;
+  lineno: number | null;
+  is_static: boolean;
+  elapsed_ms: number | null;
+  parameters_json: string | null;
+  return_value: string | null;
+}
+
+export interface ExceptionNode extends BaseNode {
+  kind: 'exception';
+  exception_class: string;
+  message: string | null;
+  path: string | null;
+  lineno: number | null;
+}
+
+// Logging calls are function calls whose linked code_object carries the
+// canonical `log` label. They share the function-call shape (same row in
+// `function_calls`) but get their own kind so renderers can format the
+// message inline rather than the bare call signature.
+export interface LogNode extends BaseNode {
+  kind: 'log';
+  fqid: string | null;
+  logger: string;          // defined_class
+  method_id: string;       // info / warn / error / etc. — best effort
+  path: string | null;
+  lineno: number | null;
+  elapsed_ms: number | null;
+  // Display-projected message derived from parameters_json / return_value
+  // (see lib/logMessage.projectLogMessage). '' when nothing usable was
+  // captured.
+  message: string;
+  parameters_json: string | null;
+  return_value: string | null;
+}
+
+export type TreeNode =
+  | HttpServerNode
+  | HttpClientNode
+  | SqlNode
+  | FunctionNode
+  | ExceptionNode
+  | LogNode;
+
+export interface AppmapInfo {
+  id: number;
+  name: string;
+  source_path: string;
+}
+
+// Resolve a user-supplied appmap reference to the row in `appmaps`.
+// Accepts the canonical relative path, an absolute path (== source_path),
+// the recording name, or a basename. Throws on miss or ambiguity (with
+// candidates in the message so the user can disambiguate). Display-label
+// strings (e.g. "GET /orders (200) - 19:47:22") are rejected up front
+// with a hint to use the `path` field from find_recordings instead —
+// those silently miss otherwise, and the resulting empty result drives
+// agents to retry with yet more identifier forms.
+export function resolveAppmap(db: sqlite3.Database, ref: string): AppmapInfo {
+  if (looksLikeDisplayLabel(ref)) {
+    throw new Error(
+      `appmap argument looks like a display label. ` +
+        `Use the 'path' field from find_recordings instead. Got: '${ref}'.`
+    );
+  }
+  const m = appmapRefClause(ref, 'a');
+  const rows = db
+    .prepare(
+      `SELECT a.id, a.name, a.source_path FROM appmaps a
+       WHERE ${m.sql}
+       ORDER BY a.source_path`
+    )
+    .all(...m.params) as AppmapInfo[];
+  if (rows.length === 0) throw new Error(`appmap not found: ${ref}`);
+  if (rows.length > 1) {
+    const list = rows.map((r) => `  - ${r.source_path}`).join('\n');
+    throw new Error(`appmap "${ref}" is ambiguous; matches:\n${list}`);
+  }
+  return rows[0];
+}
+
+export interface TreeOptions {
+  // Focus criteria — multiple may be supplied; results are the union of
+  // matches' neighborhoods. Without any focus, the full tree is returned.
+  focusFn?: string;       // exact code_object fqid
+  focusSql?: string;      // case-insensitive substring of sql_text
+  focusRoute?: string;    // normalized_path (or raw path) of a server request
+  focusUrl?: string;      // case-insensitive substring of an outbound URL
+
+  // Depth budgets, in effect only when focus is active.
+  ancestors?: number;     // ancestor levels to keep above each match (default 5)
+  descendants?: number;   // descendant levels below each match (default 4)
+
+  // Prune subtrees whose maximum elapsed time is below this threshold —
+  // useful for trimming traces dominated by fast leaf calls.
+  minElapsedMs?: number;
+}
+
+const DEFAULT_ANCESTORS = 5;
+// Bumped from 3 → 4 (Spec 05). Across the rca2 fixtures every first
+// call to get_call_tree overrode the previous default with child_depth
+// ∈ {4, 5}; the agent had learned 3 was too shallow. With this default
+// the modal first call no longer needs an override, and the truncation
+// signal (Spec 04) handles the minority of cases where 4 isn't enough.
+const DEFAULT_DESCENDANTS = 4;
+
+// Cap suggested next-step depth so we don't egg the agent into an
+// unbounded zoom. 10 is well past the practical depth of any real
+// Spring Boot or Rails callstack we've seen in the rca2 fixtures.
+const MAX_SUGGESTED_DEPTH = 10;
+
+// Outcome of a tree() call augmented with truncation metadata. Helps the
+// caller decide whether re-querying with deeper depth would yield more —
+// returns false in two distinct cases (no focus active so the full
+// recording is already present; or focus active and every leaf bottomed
+// out before the budget). When `truncated: true`, `next_step` is a
+// ready-to-use suggestion for the next call so the agent doesn't have
+// to invent a deeper depth itself.
+export interface TreeWithMeta {
+  nodes: TreeNode[];
+  truncated: boolean;
+  max_depth_reached: number;
+  next_step?: string;
+}
+
+// Build the flat-but-depth-annotated tree for a recording. Events are
+// returned in event_id order; consumers can render with indentation.
+//
+// For the metadata-aware variant — including truncation/depth signals
+// the MCP layer surfaces to agents — call `treeWithMeta`. This entry
+// point preserves the simple TreeNode[] shape historical CLI consumers
+// (and tree.spec.ts) depend on.
+export function tree(
+  db: sqlite3.Database,
+  appmapRef: string,
+  options: TreeOptions = {}
+): TreeNode[] {
+  return treeWithMeta(db, appmapRef, options).nodes;
+}
+
+// Tree + truncation metadata. Agents use the metadata to decide whether
+// re-querying with deeper depth would yield more (truncated=true), or
+// whether the current call was complete (truncated=false). See Spec 04.
+export function treeWithMeta(
+  db: sqlite3.Database,
+  appmapRef: string,
+  options: TreeOptions = {}
+): TreeWithMeta {
+  const am = resolveAppmap(db, appmapRef);
+  const events: TreeNode[] = [];
+
+  for (const r of db
+    .prepare(
+      `SELECT event_id, parent_event_id, thread_id, method,
+              COALESCE(normalized_path, path) AS route, status_code, elapsed_ms
+       FROM http_requests WHERE appmap_id = ?`
+    )
+    .all(am.id) as {
+    event_id: number;
+    parent_event_id: number | null;
+    thread_id: number | null;
+    method: string;
+    route: string;
+    status_code: number;
+    elapsed_ms: number | null;
+  }[]) {
+    events.push({
+      kind: 'http_server',
+      event_id: r.event_id,
+      parent_event_id: r.parent_event_id,
+      thread_id: r.thread_id,
+      depth: 0,
+      method: r.method,
+      route: r.route,
+      status_code: r.status_code,
+      elapsed_ms: r.elapsed_ms,
+    });
+  }
+
+  for (const r of db
+    .prepare(
+      `SELECT event_id, parent_event_id, thread_id, method, url, status_code, elapsed_ms
+       FROM http_client_requests WHERE appmap_id = ?`
+    )
+    .all(am.id) as {
+    event_id: number;
+    parent_event_id: number | null;
+    thread_id: number | null;
+    method: string;
+    url: string;
+    status_code: number | null;
+    elapsed_ms: number | null;
+  }[]) {
+    events.push({
+      kind: 'http_client',
+      event_id: r.event_id,
+      parent_event_id: r.parent_event_id,
+      thread_id: r.thread_id,
+      depth: 0,
+      method: r.method,
+      url: r.url,
+      status_code: r.status_code,
+      elapsed_ms: r.elapsed_ms,
+    });
+  }
+
+  for (const r of db
+    .prepare(
+      `SELECT event_id, parent_event_id, thread_id, sql_text, database_type, elapsed_ms
+       FROM sql_queries WHERE appmap_id = ?`
+    )
+    .all(am.id) as {
+    event_id: number;
+    parent_event_id: number | null;
+    thread_id: number | null;
+    sql_text: string;
+    database_type: string | null;
+    elapsed_ms: number | null;
+  }[]) {
+    events.push({
+      kind: 'sql',
+      event_id: r.event_id,
+      parent_event_id: r.parent_event_id,
+      thread_id: r.thread_id,
+      depth: 0,
+      sql_text: r.sql_text,
+      database_type: r.database_type,
+      elapsed_ms: r.elapsed_ms,
+    });
+  }
+
+  for (const r of db
+    .prepare(
+      `SELECT fc.event_id, fc.parent_event_id, fc.thread_id,
+              co.fqid AS fqid, fc.defined_class, fc.method_id,
+              fc.path, fc.lineno,
+              fc.is_static, fc.elapsed_ms, fc.parameters_json, fc.return_value,
+              EXISTS (
+                SELECT 1 FROM labels l
+                WHERE l.code_object_id = fc.code_object_id AND l.label = 'log'
+              ) AS is_log
+       FROM function_calls fc
+       LEFT JOIN code_objects co ON co.id = fc.code_object_id
+       WHERE fc.appmap_id = ?`
+    )
+    .all(am.id) as {
+    event_id: number;
+    parent_event_id: number | null;
+    thread_id: number | null;
+    fqid: string | null;
+    defined_class: string;
+    method_id: string;
+    path: string | null;
+    lineno: number | null;
+    is_static: number;
+    elapsed_ms: number | null;
+    parameters_json: string | null;
+    return_value: string | null;
+    is_log: number;
+  }[]) {
+    if (r.is_log === 1) {
+      events.push({
+        kind: 'log',
+        event_id: r.event_id,
+        parent_event_id: r.parent_event_id,
+        thread_id: r.thread_id,
+        depth: 0,
+        fqid: r.fqid,
+        logger: r.defined_class,
+        method_id: r.method_id,
+        path: r.path,
+        lineno: r.lineno,
+        elapsed_ms: r.elapsed_ms,
+        message: projectLogMessage(r.parameters_json, r.return_value),
+        parameters_json: r.parameters_json,
+        return_value: r.return_value,
+      });
+    } else {
+      events.push({
+        kind: 'function',
+        event_id: r.event_id,
+        parent_event_id: r.parent_event_id,
+        thread_id: r.thread_id,
+        depth: 0,
+        fqid: r.fqid,
+        defined_class: r.defined_class,
+        method_id: r.method_id,
+        path: r.path,
+        lineno: r.lineno,
+        is_static: r.is_static === 1,
+        elapsed_ms: r.elapsed_ms,
+        parameters_json: r.parameters_json,
+        return_value: r.return_value,
+      });
+    }
+  }
+
+  for (const r of db
+    .prepare(
+      `SELECT event_id, parent_event_id, thread_id, exception_class, message,
+              path, lineno
+       FROM exceptions WHERE appmap_id = ?`
+    )
+    .all(am.id) as {
+    event_id: number;
+    parent_event_id: number | null;
+    thread_id: number | null;
+    exception_class: string;
+    message: string | null;
+    path: string | null;
+    lineno: number | null;
+  }[]) {
+    events.push({
+      kind: 'exception',
+      event_id: r.event_id,
+      parent_event_id: r.parent_event_id,
+      thread_id: r.thread_id,
+      depth: 0,
+      exception_class: r.exception_class,
+      message: r.message,
+      path: r.path,
+      lineno: r.lineno,
+    });
+  }
+
+  events.sort((a, b) => a.event_id - b.event_id);
+  computeDepths(events);
+
+  let result = events;
+  let truncated = false;
+  if (hasFocus(options)) {
+    const focused = applyFocus(result, options);
+    result = focused.events;
+    truncated = focused.truncated;
+  }
+  if (options.minElapsedMs && options.minElapsedMs > 0) {
+    result = pruneByElapsed(result, options.minElapsedMs);
+  }
+  // Re-anchor depth to the highest included ancestor in the surviving
+  // set, so the rendered indentation starts at column 0 instead of
+  // floating wherever the original absolute depth happened to be.
+  if (result !== events) recomputeDepthsRelative(result);
+
+  let maxDepth = 0;
+  for (const e of result) if (e.depth > maxDepth) maxDepth = e.depth;
+
+  const meta: TreeWithMeta = { nodes: result, truncated, max_depth_reached: maxDepth };
+  if (truncated) {
+    const currentDescendants =
+      options.descendants ?? DEFAULT_DESCENDANTS;
+    const next = Math.min(currentDescendants + 2, MAX_SUGGESTED_DEPTH);
+    if (next > currentDescendants) {
+      meta.next_step = `To see deeper, call get_call_tree(appmap='${appmapRef}', child_depth=${next}).`;
+    }
+  }
+  return meta;
+}
+
+function computeDepths(events: TreeNode[]): void {
+  // Events are sorted by event_id; parents always precede children, so a
+  // single forward pass suffices.
+  const depthByEventId = new Map<number, number>();
+  for (const ev of events) {
+    let depth = 0;
+    if (ev.parent_event_id !== null) {
+      const p = depthByEventId.get(ev.parent_event_id);
+      if (p !== undefined) depth = p + 1;
+    }
+    ev.depth = depth;
+    depthByEventId.set(ev.event_id, depth);
+  }
+}
+
+function recomputeDepthsRelative(events: readonly TreeNode[]): void {
+  const includedIds = new Set(events.map((e) => e.event_id));
+  const eventsByEventId = new Map<number, TreeNode>();
+  for (const e of events) {
+    if (!eventsByEventId.has(e.event_id)) eventsByEventId.set(e.event_id, e);
+  }
+  for (const e of events) {
+    let d = 0;
+    let pid = e.parent_event_id;
+    while (pid !== null && includedIds.has(pid)) {
+      d += 1;
+      const parent = eventsByEventId.get(pid);
+      if (!parent) break;
+      pid = parent.parent_event_id;
+    }
+    e.depth = d;
+  }
+}
+
+function hasFocus(options: TreeOptions): boolean {
+  return !!(options.focusFn || options.focusSql || options.focusRoute || options.focusUrl);
+}
+
+function matchesFocus(node: TreeNode, options: TreeOptions): boolean {
+  if (options.focusFn && node.kind === 'function') {
+    return node.fqid === options.focusFn;
+  }
+  if (options.focusSql && node.kind === 'sql') {
+    return node.sql_text.toLowerCase().includes(options.focusSql.toLowerCase());
+  }
+  if (options.focusRoute && node.kind === 'http_server') {
+    // Accept "METHOD /path" (the natural concatenation when an agent reads
+    // back {method, route} pairs from other tools) or bare "/path".
+    const focus = options.focusRoute.trim();
+    const spaceIdx = focus.indexOf(' ');
+    if (spaceIdx > 0 && focus.slice(0, spaceIdx).toUpperCase() === focus.slice(0, spaceIdx)) {
+      const focusMethod = focus.slice(0, spaceIdx);
+      const focusPath = focus.slice(spaceIdx + 1).trim();
+      return node.method.toUpperCase() === focusMethod && node.route === focusPath;
+    }
+    return node.route === focus;
+  }
+  if (options.focusUrl && node.kind === 'http_client') {
+    return node.url.toLowerCase().includes(options.focusUrl.toLowerCase());
+  }
+  return false;
+}
+
+// Filter `events` to a neighborhood around the focus matches:
+//   - the matches themselves
+//   - up to `ancestors` parent levels above each match
+//   - the direct children of each ancestor (so siblings of the match are visible)
+//   - up to `descendants` levels below each match
+//
+// Also tracks whether the descendant budget actually cut off any kids —
+// agents use that signal (Spec 04) to decide whether re-querying with
+// deeper depth would yield more, instead of the "try 4, try 5, try 6"
+// hedge pattern we observed in rca2 sessions.
+function applyFocus(
+  events: readonly TreeNode[],
+  options: TreeOptions
+): { events: TreeNode[]; truncated: boolean } {
+  const ancestorBudget = options.ancestors ?? DEFAULT_ANCESTORS;
+  const descendantBudget = options.descendants ?? DEFAULT_DESCENDANTS;
+
+  // Build helpers. Multiple TreeNodes can share an event_id (e.g. a call
+  // event can also have an exception attached), so children are keyed
+  // by event_id and we dedupe.
+  const nodeByEventId = new Map<number, TreeNode>();
+  for (const e of events) {
+    if (!nodeByEventId.has(e.event_id)) nodeByEventId.set(e.event_id, e);
+  }
+  const childrenByParent = new Map<number, Set<number>>();
+  for (const e of events) {
+    if (e.parent_event_id !== null) {
+      let bucket = childrenByParent.get(e.parent_event_id);
+      if (!bucket) {
+        bucket = new Set();
+        childrenByParent.set(e.parent_event_id, bucket);
+      }
+      bucket.add(e.event_id);
+    }
+  }
+
+  const focusIds = new Set<number>();
+  for (const e of events) {
+    if (matchesFocus(e, options)) focusIds.add(e.event_id);
+  }
+  if (focusIds.size === 0) return { events: [], truncated: false };
+
+  const included = new Set<number>();
+  let truncated = false;
+  for (const fid of focusIds) {
+    included.add(fid);
+
+    // Walk up to `ancestorBudget` ancestors; record them and remember the
+    // path so we can include their direct children.
+    const ancestorIds: number[] = [];
+    let cur = fid;
+    for (let i = 0; i < ancestorBudget; i++) {
+      const node = nodeByEventId.get(cur);
+      if (node?.parent_event_id == null) break;
+      const parentId = node.parent_event_id;
+      if (!nodeByEventId.has(parentId)) break;
+      ancestorIds.push(parentId);
+      included.add(parentId);
+      cur = parentId;
+    }
+    // Direct children of every ancestor (so the focus's siblings — and
+    // siblings of every node on the path to root — are visible).
+    for (const aid of ancestorIds) {
+      const kids = childrenByParent.get(aid);
+      if (kids) for (const k of kids) included.add(k);
+    }
+
+    // Descendants up to `descendantBudget` levels (BFS).
+    const queue: { id: number; depth: number }[] = [{ id: fid, depth: 0 }];
+    while (queue.length > 0) {
+      const next = queue.shift();
+      if (!next) break;
+      if (next.depth >= descendantBudget) {
+        // We hit the budget. If this node has any kids we'd have walked
+        // into, the result is truncated.
+        const kids = childrenByParent.get(next.id);
+        if (kids && kids.size > 0) truncated = true;
+        continue;
+      }
+      const kids = childrenByParent.get(next.id);
+      if (!kids) continue;
+      for (const k of kids) {
+        if (!included.has(k)) {
+          included.add(k);
+          queue.push({ id: k, depth: next.depth + 1 });
+        }
+      }
+    }
+  }
+
+  return { events: events.filter((e) => included.has(e.event_id)), truncated };
+}
+
+// Prune subtrees whose entire branch's maximum elapsed_ms is below the
+// threshold. A node is kept iff it (or any of its descendants) has an
+// elapsed_ms ≥ threshold. Events without elapsed (exceptions, http
+// requests with no return) are kept iff their owning subtree qualifies.
+function pruneByElapsed(events: readonly TreeNode[], minMs: number): TreeNode[] {
+  const childrenByParent = new Map<number, Set<number>>();
+  for (const e of events) {
+    if (e.parent_event_id !== null) {
+      let bucket = childrenByParent.get(e.parent_event_id);
+      if (!bucket) {
+        bucket = new Set();
+        childrenByParent.set(e.parent_event_id, bucket);
+      }
+      bucket.add(e.event_id);
+    }
+  }
+  const elapsedById = new Map<number, number>();
+  for (const e of events) {
+    const cur = elapsedById.get(e.event_id) ?? 0;
+    const here = 'elapsed_ms' in e && typeof e.elapsed_ms === 'number' ? e.elapsed_ms : 0;
+    if (here > cur) elapsedById.set(e.event_id, here);
+  }
+  const maxByEventId = new Map<number, number>();
+  function maxFor(id: number): number {
+    const cached = maxByEventId.get(id);
+    if (cached !== undefined) return cached;
+    let m = elapsedById.get(id) ?? 0;
+    const kids = childrenByParent.get(id);
+    if (kids) for (const k of kids) m = Math.max(m, maxFor(k));
+    maxByEventId.set(id, m);
+    return m;
+  }
+  return events.filter((e) => maxFor(e.event_id) >= minMs);
+}
+
+export interface TreeSummary {
+  appmap_name: string;
+  source_path: string;
+  entry: { method: string; route: string; status_code: number; elapsed_ms: number | null } | null;
+  sql: { count: number; total_ms: number };
+  http_client: { count: number; total_ms: number };
+  exceptions: {
+    exception_class: string;
+    message: string | null;
+    path: string | null;
+    lineno: number | null;
+  }[];
+  labels: { label: string; count: number }[];
+}
+
+export function treeSummary(db: sqlite3.Database, appmapRef: string): TreeSummary {
+  const am = resolveAppmap(db, appmapRef);
+  const nodes = tree(db, appmapRef);
+
+  const httpServer = nodes.find((n): n is HttpServerNode => n.kind === 'http_server');
+  const sqls = nodes.filter((n): n is SqlNode => n.kind === 'sql');
+  const httpClients = nodes.filter((n): n is HttpClientNode => n.kind === 'http_client');
+  const excs = nodes.filter((n): n is ExceptionNode => n.kind === 'exception');
+
+  const labelRows = db
+    .prepare(
+      `SELECT l.label, COUNT(*) AS n
+       FROM function_calls fc
+       JOIN labels l ON l.code_object_id = fc.code_object_id
+       WHERE fc.appmap_id = ?
+       GROUP BY l.label
+       ORDER BY n DESC, l.label`
+    )
+    .all(am.id) as { label: string; n: number }[];
+
+  return {
+    appmap_name: am.name,
+    source_path: am.source_path,
+    entry: httpServer
+      ? {
+          method: httpServer.method,
+          route: httpServer.route,
+          status_code: httpServer.status_code,
+          elapsed_ms: httpServer.elapsed_ms,
+        }
+      : null,
+    sql: {
+      count: sqls.length,
+      total_ms: sqls.reduce((s, q) => s + (q.elapsed_ms ?? 0), 0),
+    },
+    http_client: {
+      count: httpClients.length,
+      total_ms: httpClients.reduce((s, c) => s + (c.elapsed_ms ?? 0), 0),
+    },
+    exceptions: excs.map((e) => ({
+      exception_class: e.exception_class,
+      message: e.message,
+      path: e.path,
+      lineno: e.lineno,
+    })),
+    labels: labelRows.map((r) => ({ label: r.label, count: r.n })),
+  };
+}
diff --git a/packages/cli/src/cmds/query/query.ts b/packages/cli/src/cmds/query/query.ts
new file mode 100644
index 0000000000..0109b00ae5
--- /dev/null
+++ b/packages/cli/src/cmds/query/query.ts
@@ -0,0 +1,31 @@
+import yargs from 'yargs';
+
+import * as CompareVerb from './verbs/compare';
+import * as EndpointsVerb from './verbs/endpoints';
+import * as FindVerb from './verbs/find';
+import * as HotspotsVerb from './verbs/hotspots';
+import * as McpVerb from './verbs/mcp';
+import * as RelatedVerb from './verbs/related';
+import * as TreeVerb from './verbs/tree';
+import * as UiVerb from './verbs/ui';
+
+export const command = 'query';
+export const describe =
+  'Query AppMap recordings (endpoints, find, tree, related, hotspots, compare, mcp, ui)';
+
+export const builder = <T>(args: yargs.Argv<T>) =>
+  args
+    .command(CompareVerb)
+    .command(EndpointsVerb)
+    .command(FindVerb)
+    .command(HotspotsVerb)
+    .command(McpVerb)
+    .command(RelatedVerb)
+    .command(TreeVerb)
+    .command(UiVerb)
+    .demandCommand(1, 'specify a query verb')
+    .strict();
+
+export const handler = (): void => {
+  // Dispatched by subcommand. Yargs will print help if no verb is given.
+};
diff --git a/packages/cli/src/cmds/query/verbs/compare.ts b/packages/cli/src/cmds/query/verbs/compare.ts
new file mode 100644
index 0000000000..cc01c96db3
--- /dev/null
+++ b/packages/cli/src/cmds/query/verbs/compare.ts
@@ -0,0 +1,120 @@
+import yargs from 'yargs';
+import { log } from 'console';
+
+import { handleWorkingDirectory } from '../../../lib/handleWorkingDirectory';
+import { locateAppMapDir } from '../../../lib/locateAppMapDir';
+import { verbose } from '../../../utils';
+import { openReadOnly } from '../lib/openReadOnly';
+import { truncationFooter } from '../lib/page';
+import { parseTime } from '../lib/parseFilter';
+import {
+  compare,
+  CompareFilter,
+  CompareRow,
+  CompareSort,
+} from '../queries/compare';
+import { formatCount, formatMs, formatTable } from '../lib/format';
+
+export const command = 'compare <branch-a> <branch-b>';
+export const describe = 'Per-route latency delta between two branches';
+
+export const builder = <T>(args: yargs.Argv<T>) => {
+  return args
+    .positional('branch-a', { type: 'string', describe: 'baseline branch' })
+    .positional('branch-b', { type: 'string', describe: 'comparison branch' })
+    .option('directory', { type: 'string', alias: 'd' })
+    .option('appmap-dir', { type: 'string' })
+    .option('query-db', { type: 'string', describe: 'path to query.db (overrides default)' })
+    .option('since', { type: 'string' })
+    .option('until', { type: 'string' })
+    .option('sort', {
+      type: 'string',
+      choices: ['delta', 'p95-a', 'p95-b'] as const,
+      default: 'delta',
+    })
+    .option('include-counts', { type: 'boolean', default: false })
+    .option('limit', { type: 'number', describe: 'default 20; pass 0 for unbounded' })
+    .option('offset', { type: 'number' })
+    .option('json', { type: 'boolean', default: false });
+};
+
+type Argv = ReturnType<typeof builder> extends yargs.Argv<infer T> ? T : never;
+
+export const handler = async (argvIn: yargs.ArgumentsCamelCase<unknown>): Promise<void> => {
+  const argv = argvIn as yargs.ArgumentsCamelCase<Argv>;
+  verbose(argv.verbose as boolean | undefined);
+  handleWorkingDirectory(argv.directory);
+  const appmapDir = argv.queryDb ? '' : await locateAppMapDir(argv.appmapDir);
+
+  const branchA = argv.branchA;
+  const branchB = argv.branchB;
+  if (!branchA || !branchB) throw new Error('<branch-a> and <branch-b> are required');
+
+  const filter: CompareFilter = {
+    branch_a: branchA,
+    branch_b: branchB,
+    sort: argv.sort as CompareSort,
+  };
+  if (argv.since) filter.since = parseTime(argv.since);
+  if (argv.until) filter.until = parseTime(argv.until);
+  if (argv.limit !== undefined) filter.limit = argv.limit;
+  if (argv.offset !== undefined) filter.offset = argv.offset;
+
+  const db = openReadOnly(appmapDir, argv.queryDb);
+  try {
+    const page = compare(db, filter);
+    if (argv.json) {
+      log(JSON.stringify(page, null, 2));
+      return;
+    }
+    log(renderCompare(page.rows, branchA, branchB, !!argv.includeCounts));
+    const footer = truncationFooter(page);
+    if (footer) log(footer);
+  } finally {
+    db.close();
+  }
+};
+
+// Format a delta ratio (b_p95 / a_p95) for display:
+//   ~                if 0.8 ≤ ratio ≤ 1.25 (no meaningful change)
+//   +Nx / -Nx        for ≥2× or ≤0.5
+//   +N% / -N%        otherwise
+//   ?                if delta is null
+function formatDelta(d: number | null): string {
+  if (d == null) return '?';
+  if (d >= 0.8 && d <= 1.25) return '~';
+  if (d >= 2) return `+${d.toFixed(1)}×`;
+  if (d <= 0.5) return `-${(1 / d).toFixed(1)}×`;
+  const pct = (d - 1) * 100;
+  return `${pct > 0 ? '+' : ''}${pct.toFixed(0)}%`;
+}
+
+function renderCompare(
+  rows: readonly CompareRow[],
+  branchA: string,
+  branchB: string,
+  includeCounts: boolean
+): string {
+  if (includeCounts) {
+    return formatTable(
+      ['ROUTE', `${branchA}_p95`, `${branchA}_n`, `${branchB}_p95`, `${branchB}_n`, 'Δ'],
+      rows.map((r) => [
+        `${r.method} ${r.route}`,
+        formatMs(r.a_p95_ms),
+        formatCount(r.a_count),
+        formatMs(r.b_p95_ms),
+        formatCount(r.b_count),
+        formatDelta(r.delta),
+      ])
+    );
+  }
+  return formatTable(
+    ['ROUTE', `${branchA}_p95`, `${branchB}_p95`, 'Δ'],
+    rows.map((r) => [
+      `${r.method} ${r.route}`,
+      formatMs(r.a_p95_ms),
+      formatMs(r.b_p95_ms),
+      formatDelta(r.delta),
+    ])
+  );
+}
diff --git a/packages/cli/src/cmds/query/verbs/endpoints.ts b/packages/cli/src/cmds/query/verbs/endpoints.ts
new file mode 100644
index 0000000000..d12bb9d258
--- /dev/null
+++ b/packages/cli/src/cmds/query/verbs/endpoints.ts
@@ -0,0 +1,87 @@
+import yargs from 'yargs';
+import { log } from 'console';
+
+import { handleWorkingDirectory } from '../../../lib/handleWorkingDirectory';
+import { locateAppMapDir } from '../../../lib/locateAppMapDir';
+import { verbose } from '../../../utils';
+import { openReadOnly } from '../lib/openReadOnly';
+import { truncationFooter } from '../lib/page';
+import { parseStatus, parseTime } from '../lib/parseFilter';
+import {
+  endpoints,
+  EndpointSort,
+  EndpointsFilter,
+} from '../queries/endpoints';
+import { formatCount, formatMs, formatPct, formatTable } from '../lib/format';
+
+export const command = 'endpoints';
+export const describe = 'Per-route summary table (orient verb)';
+
+export const builder = <T>(args: yargs.Argv<T>) => {
+  return args
+    .option('directory', { type: 'string', alias: 'd', describe: 'program working directory' })
+    .option('appmap-dir', { type: 'string', describe: 'directory of recordings' })
+    .option('query-db', { type: 'string', describe: 'path to query.db (overrides default)' })
+    .option('since', { type: 'string', describe: 'ISO timestamp or "Nd ago"' })
+    .option('until', { type: 'string', describe: 'ISO timestamp or "Nd ago"' })
+    .option('branch', { type: 'string' })
+    .option('status', {
+      type: 'string',
+      describe:
+        'route filter — e.g. 500, ">=500" (route is shown if any request matches; aggregates still cover all of that route\'s requests)',
+    })
+    .option('sort', {
+      type: 'string',
+      choices: ['count', 'avg', 'p95', 'err'] as const,
+      default: 'count',
+    })
+    .option('limit', { type: 'number', describe: 'default 20; pass 0 for unbounded' })
+    .option('offset', { type: 'number' })
+    .option('json', { type: 'boolean', default: false });
+};
+
+type Argv = ReturnType<typeof builder> extends yargs.Argv<infer T> ? T : never;
+
+// Widened at the export so this module is assignable to CommandModule<T, any>.
+export const handler = async (argvIn: yargs.ArgumentsCamelCase<unknown>): Promise<void> => {
+  const argv = argvIn as yargs.ArgumentsCamelCase<Argv>;
+  verbose(argv.verbose as boolean | undefined);
+  handleWorkingDirectory(argv.directory);
+  // When --query-db is supplied, the appmap dir is irrelevant — the user has
+  // already named a query.db. Otherwise, derive it from the appmap dir.
+  const appmapDir = argv.queryDb ? '' : await locateAppMapDir(argv.appmapDir);
+
+  const filter: EndpointsFilter = { sort: argv.sort as EndpointSort };
+  if (argv.since) filter.since = parseTime(argv.since);
+  if (argv.until) filter.until = parseTime(argv.until);
+  if (argv.branch) filter.branch = argv.branch;
+  if (argv.status) filter.status = parseStatus(argv.status);
+  if (argv.limit !== undefined) filter.limit = argv.limit;
+  if (argv.offset !== undefined) filter.offset = argv.offset;
+
+  const db = openReadOnly(appmapDir, argv.queryDb);
+  try {
+    const page = endpoints(db, filter);
+    if (argv.json) {
+      log(JSON.stringify(page, null, 2));
+      return;
+    }
+    log(
+      formatTable(
+        ['METHOD', 'ROUTE', 'COUNT', 'AVG', 'P95', 'ERR%'],
+        page.rows.map((r) => [
+          r.method,
+          r.route,
+          formatCount(r.count),
+          formatMs(r.avg_ms),
+          formatMs(r.p95_ms),
+          formatPct(r.err_pct),
+        ])
+      )
+    );
+    const footer = truncationFooter(page);
+    if (footer) log(footer);
+  } finally {
+    db.close();
+  }
+};
diff --git a/packages/cli/src/cmds/query/verbs/find.ts b/packages/cli/src/cmds/query/verbs/find.ts
new file mode 100644
index 0000000000..23e5576e20
--- /dev/null
+++ b/packages/cli/src/cmds/query/verbs/find.ts
@@ -0,0 +1,301 @@
+import yargs from 'yargs';
+import { log } from 'console';
+
+import { handleWorkingDirectory } from '../../../lib/handleWorkingDirectory';
+import { locateAppMapDir } from '../../../lib/locateAppMapDir';
+import { verbose } from '../../../utils';
+import { openReadOnly } from '../lib/openReadOnly';
+import { truncationFooter } from '../lib/page';
+import { parseDuration, parseStatus, parseTime } from '../lib/parseFilter';
+import { parseClassRef } from '../lib/scope';
+import {
+  find,
+  FindFilter,
+  FindType,
+  FindAppmapRow,
+  FindCallRow,
+  FindExceptionRow,
+  FindLogRow,
+  FindQueryRow,
+  FindRequestRow,
+} from '../queries/find';
+import { formatMs, formatTable } from '../lib/format';
+import { projectLogMessage } from '../lib/logMessage';
+
+export { projectLogMessage };
+
+const TYPES: readonly FindType[] = ['appmaps', 'requests', 'queries', 'calls', 'exceptions', 'logs'];
+// 'recordings' is accepted as an alias for 'appmaps' to match the MCP
+// naming (find_recordings) and the user-facing concept of a "recording".
+const TYPE_CHOICES: readonly string[] = ['appmaps', 'recordings', ...TYPES.filter((t) => t !== 'appmaps')];
+
+function normalizeType(input: string): FindType {
+  return (input === 'recordings' ? 'appmaps' : input) as FindType;
+}
+
+export const command = 'find <type>';
+export const describe = 'Row-level search across recordings';
+
+export const builder = <T>(args: yargs.Argv<T>) => {
+  return args
+    .positional('type', { type: 'string', choices: TYPE_CHOICES })
+    .option('directory', { type: 'string', alias: 'd' })
+    .option('appmap-dir', { type: 'string' })
+    .option('query-db', { type: 'string', describe: 'path to query.db (overrides default)' })
+    .option('route', {
+      type: 'string',
+      describe:
+        'e.g. "POST /orders" or "/orders" (path is exact match; method case-insensitive)',
+    })
+    .option('class', { type: 'string', describe: 'defined_class or fqid Class part' })
+    .option('method', { type: 'string', describe: 'method_id (not HTTP method)' })
+    .option('label', { type: 'string' })
+    .option('event-id', {
+      type: 'number',
+      array: true,
+      describe: 'exact event_id(s) to fetch (calls); repeatable',
+    })
+    .option('branch', { type: 'string' })
+    .option('commit', { type: 'string' })
+    .option('status', { type: 'string', describe: 'e.g. 500, ">=500"' })
+    .option('duration', { type: 'string', describe: 'e.g. ">1s", ">=500ms"' })
+    .option('since', { type: 'string' })
+    .option('until', { type: 'string' })
+    .option('appmap', { type: 'string', describe: 'appmap name' })
+    .option('table', { type: 'string', describe: 'SQL table name (queries)' })
+    .option('exception', { type: 'string', describe: 'exception class (exceptions)' })
+    .option('logger', { type: 'string', describe: 'logger class (logs)' })
+    .option('message', { type: 'string', describe: 'log message substring (logs)' })
+    .option('with-logs', {
+      type: 'number',
+      describe: 'attach the last N log lines preceding each row (exceptions)',
+    })
+    .option('limit', { type: 'number' })
+    .option('offset', { type: 'number' })
+    .option('json', { type: 'boolean', default: false });
+};
+
+type Argv = ReturnType<typeof builder> extends yargs.Argv<infer T> ? T : never;
+
+// Per-type flag rejection list. Universal flags (--branch, --commit,
+// --since, --until, --appmap) are accepted everywhere, as are output flags
+// (--limit, --offset, --json). Other filter flags are accepted only on
+// types where they make sense; flagging them on the wrong type is an
+// error rather than a silent no-op.
+const REJECTED_FLAGS: Record<FindType, readonly string[]> = {
+  appmaps: ['class', 'method', 'label', 'event-id', 'table', 'exception', 'logger', 'message', 'with-logs'],
+  requests: ['class', 'method', 'label', 'event-id', 'table', 'exception', 'logger', 'message', 'with-logs'],
+  queries: ['label', 'event-id', 'exception', 'logger', 'message', 'with-logs'],
+  calls: ['table', 'exception', 'logger', 'message', 'with-logs'],
+  exceptions: ['class', 'method', 'label', 'event-id', 'duration', 'table', 'logger', 'message'],
+  logs: ['class', 'method', 'label', 'event-id', 'route', 'status', 'duration', 'table', 'exception', 'with-logs'],
+};
+
+// Per-flag hints, attached to error messages when a rejected flag is used.
+// Useful for nudging users toward the right flag (e.g., HTTP method
+// belongs in --route, not --method, which is a function-method-name flag).
+const REJECTED_HINTS: Partial<Record<FindType, Partial<Record<string, string>>>> = {
+  requests: {
+    method: 'to filter by HTTP method, use --route "METHOD /path"',
+  },
+  logs: {
+    class: 'to filter logs by logger class, use --logger',
+    label: '--label is implied (logs always means label=log)',
+  },
+};
+
+// Exported for tests. Operates on a generic flag map so unit tests don't
+// need a full yargs argv.
+export function validateFlags(type: FindType, flags: Record<string, unknown>): void {
+  const used: string[] = [];
+  const hints: string[] = [];
+  for (const flag of REJECTED_FLAGS[type]) {
+    if (flags[flag] != null) {
+      used.push(`--${flag}`);
+      const hint = REJECTED_HINTS[type]?.[flag];
+      if (hint) hints.push(`  --${flag}: ${hint}`);
+    }
+  }
+  if (used.length === 0) return;
+  const verb = used.length === 1 ? 'is' : 'are';
+  let message = `find ${type}: ${used.join(', ')} ${verb} not supported for this type`;
+  if (hints.length > 0) message += `\n${hints.join('\n')}`;
+  throw new Error(message);
+}
+
+// Build a FindFilter from a yargs argv. Exported for testing — also makes
+// the verb-layer transformations (e.g. splitting Class#method off of
+// --class so the method composes via filter.method) directly assertable.
+export interface ParsedFind {
+  type: FindType;
+  filter: FindFilter;
+}
+
+export function buildFindFilter(argv: Record<string, unknown>): ParsedFind {
+  const type = normalizeType(argv.type as string);
+  validateFlags(type, argv);
+
+  const filter: FindFilter = {};
+  if (typeof argv.route === 'string') filter.route = argv.route;
+  if (typeof argv.label === 'string') filter.label = argv.label;
+  // yargs camelCases --event-id into argv.eventId; read the kebab key
+  // too so direct test invocations don't depend on yargs coercion. A
+  // single --event-id arrives as a scalar, repeated ones as an array.
+  const eventIdArg = argv.eventId ?? argv['event-id'];
+  if (Array.isArray(eventIdArg)) {
+    const ids = eventIdArg.filter((n): n is number => typeof n === 'number');
+    if (ids.length > 0) filter.eventIds = ids;
+  } else if (typeof eventIdArg === 'number') {
+    filter.eventIds = [eventIdArg];
+  }
+  if (typeof argv.branch === 'string') filter.branch = argv.branch;
+  if (typeof argv.commit === 'string') filter.commit = argv.commit;
+  if (typeof argv.status === 'string') filter.status = parseStatus(argv.status);
+  if (typeof argv.duration === 'string') filter.duration = parseDuration(argv.duration);
+  if (typeof argv.since === 'string') filter.since = parseTime(argv.since);
+  if (typeof argv.until === 'string') filter.until = parseTime(argv.until);
+  if (typeof argv.appmap === 'string') filter.appmap = argv.appmap;
+  if (typeof argv.table === 'string') filter.table = argv.table;
+  if (typeof argv.exception === 'string') filter.exception = argv.exception;
+  if (typeof argv.logger === 'string') filter.logger = argv.logger;
+  if (typeof argv.message === 'string') filter.message = argv.message;
+  // yargs camelCases --with-logs into argv.withLogs and also keeps the
+  // kebab-case key. Read both so direct test invocations don't have to
+  // depend on yargs's coercion.
+  const withLogs = argv.withLogs ?? argv['with-logs'];
+  if (typeof withLogs === 'number') filter.withLogs = withLogs;
+  if (typeof argv.limit === 'number') filter.limit = argv.limit;
+  if (typeof argv.offset === 'number') filter.offset = argv.offset;
+
+  // The documented --class form is "[pkg/]Class[#method]". Split the
+  // method off here so it composes through filter.method even when the
+  // user only supplied --class. Internal helpers (classFilterClauses /
+  // sqlCallerClassClauses) also re-parse, but doing it at the verb gives
+  // us a uniform contract: filter.className is "[pkg/]Class" only;
+  // method, if any, lives on filter.method (and an explicit --method
+  // wins over a method embedded in --class).
+  let methodFilter = typeof argv.method === 'string' ? argv.method : undefined;
+  if (typeof argv.class === 'string') {
+    const parsed = parseClassRef(argv.class);
+    if (parsed.method && !methodFilter) methodFilter = parsed.method;
+    filter.className = argv.class;
+  }
+  if (methodFilter) filter.method = methodFilter;
+
+  return { type, filter };
+}
+
+// Widened at the export so this module is assignable to CommandModule<T, any>.
+export const handler = async (argvIn: yargs.ArgumentsCamelCase<unknown>): Promise<void> => {
+  const argv = argvIn as yargs.ArgumentsCamelCase<Argv>;
+  verbose(argv.verbose as boolean | undefined);
+  handleWorkingDirectory(argv.directory);
+  const appmapDir = argv.queryDb ? '' : await locateAppMapDir(argv.appmapDir);
+
+  const { type, filter } = buildFindFilter(argv as Record<string, unknown>);
+
+  const db = openReadOnly(appmapDir, argv.queryDb);
+  try {
+    const page = find(db, type, filter);
+    if (argv.json) {
+      log(JSON.stringify(page, null, 2));
+      return;
+    }
+    log(renderTable(type, page.rows));
+    const footer = truncationFooter(page);
+    if (footer) log(footer);
+  } finally {
+    db.close();
+  }
+};
+
+function renderTable(type: FindType, rows: unknown[]): string {
+  switch (type) {
+    case 'appmaps':
+      return formatTable(
+        ['APPMAP', 'ROUTE', 'STATUS', 'ELAPSED', 'SQL', 'BRANCH', 'TIMESTAMP'],
+        (rows as FindAppmapRow[]).map((r) => [
+          r.appmap_name,
+          r.route ?? '',
+          r.status_code != null ? String(r.status_code) : '',
+          formatMs(r.elapsed_ms),
+          String(r.sql_count),
+          r.branch ?? '',
+          r.timestamp ?? '',
+        ])
+      );
+    case 'requests':
+      return formatTable(
+        ['APPMAP', 'METHOD', 'ROUTE', 'STATUS', 'ELAPSED', 'BRANCH'],
+        (rows as FindRequestRow[]).map((r) => [
+          r.appmap_name,
+          r.method,
+          r.route,
+          String(r.status_code),
+          formatMs(r.elapsed_ms),
+          r.branch ?? '',
+        ])
+      );
+    case 'queries':
+      return formatTable(
+        ['APPMAP', 'ELAPSED', 'CALLER', 'SQL'],
+        (rows as FindQueryRow[]).map((r) => [
+          r.appmap_name,
+          formatMs(r.elapsed_ms),
+          r.caller_class && r.caller_method ? `${r.caller_class}#${r.caller_method}` : '',
+          r.sql_text,
+        ])
+      );
+    case 'calls':
+      return formatTable(
+        ['APPMAP', 'FQID', 'LOCATION', 'ELAPSED', 'PARAMS', 'RETURN'],
+        (rows as FindCallRow[]).map((r) => [
+          r.appmap_name,
+          r.fqid ?? `${r.defined_class}#${r.method_id}`,
+          r.path != null ? `${r.path}${r.lineno != null ? `:${r.lineno}` : ''}` : '',
+          formatMs(r.elapsed_ms),
+          formatParams(r.parameters_json),
+          r.return_value ?? '',
+        ])
+      );
+    case 'exceptions': {
+      const exRows = rows as FindExceptionRow[];
+      const withLogs = exRows.some((r) => r.recent_logs !== undefined);
+      const headers = withLogs
+        ? ['APPMAP', 'CLASS', 'MESSAGE', 'EVENT', 'LOGS']
+        : ['APPMAP', 'CLASS', 'MESSAGE', 'EVENT'];
+      return formatTable(
+        headers,
+        exRows.map((r) => {
+          const base = [r.appmap_name, r.exception_class, r.message ?? '', String(r.event_id)];
+          if (withLogs) base.push(String(r.recent_logs?.length ?? 0));
+          return base;
+        })
+      );
+    }
+    case 'logs':
+      return formatTable(
+        ['APPMAP', 'LOGGER', 'METHOD', 'MESSAGE', 'EVENT'],
+        (rows as FindLogRow[]).map((r) => [
+          r.appmap_name,
+          r.logger,
+          r.method_id,
+          projectLogMessage(r.parameters_json, r.return_value),
+          String(r.event_id),
+        ])
+      );
+  }
+}
+
+
+function formatParams(json: string | null): string {
+  if (!json) return '';
+  try {
+    const parsed = JSON.parse(json) as { name?: string; value?: unknown }[];
+    return parsed
+      .map((p) => `${p.name ?? '?'}=${typeof p.value === 'string' ? p.value : JSON.stringify(p.value)}`)
+      .join(', ');
+  } catch {
+    return json;
+  }
+}
diff --git a/packages/cli/src/cmds/query/verbs/hotspots.ts b/packages/cli/src/cmds/query/verbs/hotspots.ts
new file mode 100644
index 0000000000..f7f00f7fd7
--- /dev/null
+++ b/packages/cli/src/cmds/query/verbs/hotspots.ts
@@ -0,0 +1,129 @@
+import yargs from 'yargs';
+import { log } from 'console';
+
+import { handleWorkingDirectory } from '../../../lib/handleWorkingDirectory';
+import { locateAppMapDir } from '../../../lib/locateAppMapDir';
+import { verbose } from '../../../utils';
+import { openReadOnly } from '../lib/openReadOnly';
+import { truncationFooter } from '../lib/page';
+import { parseTime } from '../lib/parseFilter';
+import {
+  FunctionHotspotRow,
+  HotspotsFilter,
+  HotspotType,
+  SqlHotspotRow,
+  hotspots,
+} from '../queries/hotspots';
+import { formatCount, formatMs, formatTable } from '../lib/format';
+
+export const command = 'hotspots';
+export const describe = 'Rank functions or SQL queries by cumulative elapsed';
+
+export const builder = <T>(args: yargs.Argv<T>) => {
+  return args
+    .option('directory', { type: 'string', alias: 'd' })
+    .option('appmap-dir', { type: 'string' })
+    .option('query-db', { type: 'string', describe: 'path to query.db (overrides default)' })
+    .option('type', {
+      type: 'string',
+      choices: ['function', 'sql'] as const,
+      default: 'function',
+    })
+    .option('route', {
+      type: 'string',
+      describe: 'e.g. "GET /reports" (path is exact match; method case-insensitive)',
+    })
+    .option('class', { type: 'string', describe: 'class filter (function mode only)' })
+    .option('branch', { type: 'string' })
+    .option('since', { type: 'string' })
+    .option('until', { type: 'string' })
+    .option('limit', { type: 'number', describe: 'default 20; pass 0 for unbounded' })
+    .option('offset', { type: 'number' })
+    .option('json', { type: 'boolean', default: false });
+};
+
+type Argv = ReturnType<typeof builder> extends yargs.Argv<infer T> ? T : never;
+
+// Per-type flag rejection list. Same shape as find's: a small allow-list
+// surfaces user mistakes (e.g. --class on --type=sql) instead of silently
+// dropping them, and pre-empts future filter additions that only one
+// type can honor.
+const REJECTED_FLAGS: Record<HotspotType, readonly string[]> = {
+  function: [],
+  sql: ['class'],
+};
+
+// Exported for tests.
+export function validateFlags(type: HotspotType, flags: Record<string, unknown>): void {
+  const used: string[] = [];
+  for (const flag of REJECTED_FLAGS[type]) {
+    if (flags[flag] != null) used.push(`--${flag}`);
+  }
+  if (used.length === 0) return;
+  const verb = used.length === 1 ? 'is' : 'are';
+  throw new Error(
+    `hotspots --type=${type}: ${used.join(', ')} ${verb} not supported for this type`
+  );
+}
+
+// Widened at the export so this module is assignable to CommandModule<T, any>.
+export const handler = async (argvIn: yargs.ArgumentsCamelCase<unknown>): Promise<void> => {
+  const argv = argvIn as yargs.ArgumentsCamelCase<Argv>;
+  verbose(argv.verbose as boolean | undefined);
+  handleWorkingDirectory(argv.directory);
+  const appmapDir = argv.queryDb ? '' : await locateAppMapDir(argv.appmapDir);
+
+  const type = argv.type as HotspotType;
+  validateFlags(type, argv as Record<string, unknown>);
+
+  const filter: HotspotsFilter = { type };
+  if (argv.route) filter.route = argv.route;
+  if (argv.class) filter.className = argv.class;
+  if (argv.branch) filter.branch = argv.branch;
+  if (argv.since) filter.since = parseTime(argv.since);
+  if (argv.until) filter.until = parseTime(argv.until);
+  if (argv.limit !== undefined) filter.limit = argv.limit;
+  if (argv.offset !== undefined) filter.offset = argv.offset;
+
+  const db = openReadOnly(appmapDir, argv.queryDb);
+  try {
+    const page = hotspots(db, filter);
+    if (argv.json) {
+      log(JSON.stringify(page, null, 2));
+      return;
+    }
+    log(
+      filter.type === 'sql'
+        ? renderSql(page.rows as readonly SqlHotspotRow[])
+        : renderFunctions(page.rows as readonly FunctionHotspotRow[])
+    );
+    const footer = truncationFooter(page);
+    if (footer) log(footer);
+  } finally {
+    db.close();
+  }
+};
+
+function renderFunctions(rows: readonly FunctionHotspotRow[]): string {
+  return formatTable(
+    ['FQID', 'CALLS', 'TOTAL_MS', 'SELF_MS'],
+    rows.map((r) => [
+      r.fqid ?? `${r.defined_class}#${r.method_id}`,
+      formatCount(r.calls),
+      formatMs(r.total_ms),
+      formatMs(r.self_ms),
+    ])
+  );
+}
+
+function renderSql(rows: readonly SqlHotspotRow[]): string {
+  return formatTable(
+    ['COUNT', 'AVG', 'TOTAL', 'SQL'],
+    rows.map((r) => [
+      formatCount(r.count),
+      formatMs(r.avg_ms),
+      formatMs(r.total_ms),
+      r.sql_text,
+    ])
+  );
+}
diff --git a/packages/cli/src/cmds/query/verbs/mcp.ts b/packages/cli/src/cmds/query/verbs/mcp.ts
new file mode 100644
index 0000000000..fcabfcd2b1
--- /dev/null
+++ b/packages/cli/src/cmds/query/verbs/mcp.ts
@@ -0,0 +1,81 @@
+import { createInterface } from 'readline';
+
+import yargs from 'yargs';
+
+import { handleWorkingDirectory } from '../../../lib/handleWorkingDirectory';
+import { locateAppMapDir } from '../../../lib/locateAppMapDir';
+import { verbose } from '../../../utils';
+import { openReadOnly } from '../lib/openReadOnly';
+import {
+  buildMcpHandler,
+  JsonRpcRequest,
+  JsonRpcResponse,
+} from '../queries/mcp';
+
+export const command = 'mcp';
+export const describe =
+  'Run an MCP (Model Context Protocol) server on stdio that exposes the query verbs as tools';
+
+export const builder = <T>(args: yargs.Argv<T>) => {
+  return args
+    .option('directory', { type: 'string', alias: 'd' })
+    .option('appmap-dir', { type: 'string' })
+    .option('query-db', {
+      type: 'string',
+      describe: 'path to query.db (overrides default)',
+    });
+};
+
+type Argv = ReturnType<typeof builder> extends yargs.Argv<infer T> ? T : never;
+
+// Widened at the export so this module is assignable to CommandModule<T, any>.
+export const handler = async (argvIn: yargs.ArgumentsCamelCase<unknown>): Promise<void> => {
+  const argv = argvIn as yargs.ArgumentsCamelCase<Argv>;
+  verbose(argv.verbose as boolean | undefined);
+  handleWorkingDirectory(argv.directory);
+  const appmapDir = argv.queryDb ? '' : await locateAppMapDir(argv.appmapDir);
+
+  const db = openReadOnly(appmapDir, argv.queryDb);
+  const handle = buildMcpHandler(db);
+
+  // MCP transport: newline-delimited JSON-RPC 2.0 over stdio. Logging
+  // goes to stderr only — anything on stdout corrupts the protocol stream.
+  process.stderr.write(`appmap mcp listening on stdio\n`);
+
+  const rl = createInterface({ input: process.stdin });
+  rl.on('line', (line) => {
+    const trimmed = line.trim();
+    if (trimmed.length === 0) return;
+    let msg: JsonRpcRequest;
+    try {
+      msg = JSON.parse(trimmed) as JsonRpcRequest;
+    } catch (err) {
+      writeResponse({
+        jsonrpc: '2.0',
+        id: null,
+        error: { code: -32700, message: `parse error: ${(err as Error).message}` },
+      });
+      return;
+    }
+    let response: JsonRpcResponse | null;
+    try {
+      response = handle(msg);
+    } catch (err) {
+      response = {
+        jsonrpc: '2.0',
+        id: msg.id ?? null,
+        error: { code: -32603, message: (err as Error).message },
+      };
+    }
+    if (response) writeResponse(response);
+  });
+
+  rl.on('close', () => {
+    db.close();
+    process.exit(0);
+  });
+};
+
+function writeResponse(response: JsonRpcResponse): void {
+  process.stdout.write(`${JSON.stringify(response)}\n`);
+}
diff --git a/packages/cli/src/cmds/query/verbs/related.ts b/packages/cli/src/cmds/query/verbs/related.ts
new file mode 100644
index 0000000000..49ae01ba38
--- /dev/null
+++ b/packages/cli/src/cmds/query/verbs/related.ts
@@ -0,0 +1,89 @@
+import yargs from 'yargs';
+import { log } from 'console';
+
+import { handleWorkingDirectory } from '../../../lib/handleWorkingDirectory';
+import { locateAppMapDir } from '../../../lib/locateAppMapDir';
+import { verbose } from '../../../utils';
+import { openReadOnly } from '../lib/openReadOnly';
+import { truncationFooter } from '../lib/page';
+import { parseStatus, parseTime } from '../lib/parseFilter';
+import { related, RelatedFilter, RelatedRow } from '../queries/related';
+import { formatCount, formatMs, formatTable } from '../lib/format';
+
+export const command = 'related <appmap>';
+export const describe = 'Rank recordings similar to <appmap>';
+
+export const builder = <T>(args: yargs.Argv<T>) => {
+  return args
+    .positional('appmap', { type: 'string', describe: 'source appmap (name or basename)' })
+    .option('directory', { type: 'string', alias: 'd' })
+    .option('appmap-dir', { type: 'string' })
+    .option('query-db', { type: 'string', describe: 'path to query.db (overrides default)' })
+    .option('branch', { type: 'string' })
+    .option('commit', { type: 'string' })
+    .option('since', { type: 'string' })
+    .option('until', { type: 'string' })
+    .option('status', {
+      type: 'string',
+      describe:
+        'route filter — e.g. 200, ">=500" (route is shown if any request matches)',
+    })
+    .option('route', {
+      type: 'string',
+      describe: 'e.g. "POST /orders" (path is exact match; method case-insensitive)',
+    })
+    .option('limit', { type: 'number', describe: 'default 20; pass 0 for unbounded' })
+    .option('offset', { type: 'number' })
+    .option('json', { type: 'boolean', default: false });
+};
+
+type Argv = ReturnType<typeof builder> extends yargs.Argv<infer T> ? T : never;
+
+// Widened at the export so this module is assignable to CommandModule<T, any>.
+export const handler = async (argvIn: yargs.ArgumentsCamelCase<unknown>): Promise<void> => {
+  const argv = argvIn as yargs.ArgumentsCamelCase<Argv>;
+  verbose(argv.verbose as boolean | undefined);
+  handleWorkingDirectory(argv.directory);
+  const appmapDir = argv.queryDb ? '' : await locateAppMapDir(argv.appmapDir);
+
+  const ref = argv.appmap;
+  if (!ref) throw new Error('<appmap> is required');
+
+  const filter: RelatedFilter = {};
+  if (argv.branch) filter.branch = argv.branch;
+  if (argv.commit) filter.commit = argv.commit;
+  if (argv.since) filter.since = parseTime(argv.since);
+  if (argv.until) filter.until = parseTime(argv.until);
+  if (argv.status) filter.status = parseStatus(argv.status);
+  if (argv.route) filter.route = argv.route;
+  if (argv.limit !== undefined) filter.limit = argv.limit;
+  if (argv.offset !== undefined) filter.offset = argv.offset;
+
+  const db = openReadOnly(appmapDir, argv.queryDb);
+  try {
+    const page = related(db, ref, filter);
+    if (argv.json) {
+      log(JSON.stringify(page, null, 2));
+      return;
+    }
+    log(renderRelated(page.rows));
+    const footer = truncationFooter(page);
+    if (footer) log(footer);
+  } finally {
+    db.close();
+  }
+};
+
+function renderRelated(rows: readonly RelatedRow[]): string {
+  return formatTable(
+    ['APPMAP', 'SCORE', 'ROUTE', 'STATUS', 'ELAPSED', 'SHARED'],
+    rows.map((r) => [
+      r.appmap_name,
+      formatCount(r.score),
+      r.method && r.route ? `${r.method} ${r.route}` : r.route ?? '',
+      r.status_code != null ? String(r.status_code) : '',
+      formatMs(r.elapsed_ms),
+      r.shared.join(', '),
+    ])
+  );
+}
diff --git a/packages/cli/src/cmds/query/verbs/tree.ts b/packages/cli/src/cmds/query/verbs/tree.ts
new file mode 100644
index 0000000000..eb94675e5d
--- /dev/null
+++ b/packages/cli/src/cmds/query/verbs/tree.ts
@@ -0,0 +1,125 @@
+import yargs from 'yargs';
+import { log } from 'console';
+
+import { handleWorkingDirectory } from '../../../lib/handleWorkingDirectory';
+import { locateAppMapDir } from '../../../lib/locateAppMapDir';
+import { verbose } from '../../../utils';
+import { openReadOnly } from '../lib/openReadOnly';
+import { tree, treeSummary, TreeNode, TreeOptions } from '../queries/tree';
+import { renderFlat, renderSummary, renderTree } from '../lib/treeRender';
+
+export const command = 'tree <appmap>';
+export const describe = 'Render the call tree of one recording';
+
+export const builder = <T>(args: yargs.Argv<T>) => {
+  return args
+    .positional('appmap', { type: 'string', describe: 'appmap name (or basename of source path)' })
+    .option('directory', { type: 'string', alias: 'd' })
+    .option('appmap-dir', { type: 'string' })
+    .option('query-db', { type: 'string', describe: 'path to query.db' })
+    .option('format', {
+      type: 'string',
+      choices: ['tree', 'summary'] as const,
+      default: 'tree',
+    })
+    .option('filter', {
+      type: 'string',
+      choices: ['all', 'http', 'sql', 'logs'] as const,
+      default: 'all',
+    })
+    .option('focus-fn', {
+      type: 'string',
+      describe: 'centre on function calls matching this fqid',
+    })
+    .option('focus-sql', {
+      type: 'string',
+      describe: 'centre on SQL queries containing this substring',
+    })
+    .option('focus-route', {
+      type: 'string',
+      describe: 'centre on a server request matching this normalized path',
+    })
+    .option('focus-url', {
+      type: 'string',
+      describe: 'centre on an outbound HTTP call whose URL contains this substring',
+    })
+    .option('ancestors', {
+      type: 'number',
+      describe: 'ancestor levels to keep above each focus match (default 5)',
+    })
+    .option('descendants', {
+      type: 'number',
+      describe: 'descendant levels below each focus match (default 4)',
+    })
+    .option('min-elapsed-ms', {
+      type: 'number',
+      describe: 'prune subtrees whose max elapsed is below this threshold',
+    })
+    .option('json', { type: 'boolean', default: false });
+};
+
+type Argv = ReturnType<typeof builder> extends yargs.Argv<infer T> ? T : never;
+
+// Widened at the export so this module is assignable to CommandModule<T, any>.
+export const handler = async (argvIn: yargs.ArgumentsCamelCase<unknown>): Promise<void> => {
+  const argv = argvIn as yargs.ArgumentsCamelCase<Argv>;
+  verbose(argv.verbose as boolean | undefined);
+  handleWorkingDirectory(argv.directory);
+  const appmapDir = argv.queryDb ? '' : await locateAppMapDir(argv.appmapDir);
+
+  const ref = argv.appmap;
+  if (!ref) throw new Error('<appmap> is required');
+
+  const db = openReadOnly(appmapDir, argv.queryDb);
+  try {
+    if (argv.format === 'summary') {
+      // The summary aggregates over all event types; combining with
+      // --filter would be ambiguous, so reject rather than silently drop.
+      const f = argv.filter as TreeFilter;
+      if (f !== 'all') {
+        throw new Error(
+          'tree --format=summary does not accept --filter; remove one of them'
+        );
+      }
+      const s = treeSummary(db, ref);
+      if (argv.json) log(JSON.stringify(s, null, 2));
+      else log(renderSummary(s));
+      return;
+    }
+
+    const treeOptions: TreeOptions = {};
+    if (argv.focusFn) treeOptions.focusFn = argv.focusFn;
+    if (argv.focusSql) treeOptions.focusSql = argv.focusSql;
+    if (argv.focusRoute) treeOptions.focusRoute = argv.focusRoute;
+    if (argv.focusUrl) treeOptions.focusUrl = argv.focusUrl;
+    if (argv.ancestors !== undefined) treeOptions.ancestors = argv.ancestors;
+    if (argv.descendants !== undefined) treeOptions.descendants = argv.descendants;
+    if (argv.minElapsedMs !== undefined) treeOptions.minElapsedMs = argv.minElapsedMs;
+
+    const nodes = tree(db, ref, treeOptions);
+    const filtered = applyFilter(nodes, argv.filter as TreeFilter);
+    if (argv.json) {
+      log(JSON.stringify(filtered, null, 2));
+    } else {
+      const f = argv.filter as TreeFilter;
+      log(f === 'all' ? renderTree(filtered) : renderFlat(filtered));
+    }
+  } finally {
+    db.close();
+  }
+};
+
+type TreeFilter = 'all' | 'http' | 'sql' | 'logs';
+
+export function applyFilter(nodes: readonly TreeNode[], filter: TreeFilter): TreeNode[] {
+  switch (filter) {
+    case 'all':
+      return [...nodes];
+    case 'sql':
+      return nodes.filter((n) => n.kind === 'sql');
+    case 'logs':
+      return nodes.filter((n) => n.kind === 'log');
+    case 'http':
+      return nodes.filter((n) => n.kind === 'http_server' || n.kind === 'http_client');
+  }
+}
diff --git a/packages/cli/src/cmds/query/verbs/ui.ts b/packages/cli/src/cmds/query/verbs/ui.ts
new file mode 100644
index 0000000000..f8db95bca9
--- /dev/null
+++ b/packages/cli/src/cmds/query/verbs/ui.ts
@@ -0,0 +1,80 @@
+import path from 'path';
+import { log } from 'console';
+
+import open from 'open';
+import yargs from 'yargs';
+
+import { handleWorkingDirectory } from '../../../lib/handleWorkingDirectory';
+import { locateAppMapDir } from '../../../lib/locateAppMapDir';
+import { verbose } from '../../../utils';
+import { openReadOnly } from '../lib/openReadOnly';
+import { startUIServer } from '../lib/uiServer';
+
+export const command = 'ui';
+export const describe =
+  'Launch a local web UI for browsing the query database (dashboard, endpoints, hotspots, traces)';
+
+export const builder = <T>(args: yargs.Argv<T>) => {
+  return args
+    .option('directory', { type: 'string', alias: 'd', describe: 'program working directory' })
+    .option('appmap-dir', { type: 'string', describe: 'directory of recordings' })
+    .option('query-db', { type: 'string', describe: 'path to query.db (overrides default)' })
+    .option('port', {
+      type: 'number',
+      describe: 'TCP port to listen on (default: random free port)',
+    })
+    .option('open', {
+      type: 'boolean',
+      default: true,
+      describe: 'open the UI in the system browser on start (use --no-open to disable)',
+    });
+};
+
+type Argv = ReturnType<typeof builder> extends yargs.Argv<infer T> ? T : never;
+
+// Resolve the bundled SPA dir relative to the compiled JS location.
+//   built/cmds/query/verbs/ui.js  →  built/html/query-ui
+function defaultStaticDir(): string {
+  return path.resolve(__dirname, '..', '..', '..', 'html', 'query-ui');
+}
+
+// Widened at the export so this module is assignable to CommandModule<T, any>.
+export const handler = async (argvIn: yargs.ArgumentsCamelCase<unknown>): Promise<void> => {
+  const argv = argvIn as yargs.ArgumentsCamelCase<Argv>;
+  verbose(argv.verbose as boolean | undefined);
+  handleWorkingDirectory(argv.directory);
+
+  // When --query-db is supplied, the appmap dir is irrelevant — the user
+  // has already named a query.db. Otherwise, derive it from the appmap dir.
+  const appmapDir = argv.queryDb ? '' : await locateAppMapDir(argv.appmapDir);
+  const db = openReadOnly(appmapDir, argv.queryDb);
+
+  const handle = await startUIServer({
+    db,
+    port: argv.port,
+    staticDir: defaultStaticDir(),
+  });
+
+  log(`appmap query ui listening on ${handle.url}`);
+  if (argv.open) {
+    // Best-effort. A failed browser launch shouldn't take down the server —
+    // the URL is already printed above for the user to copy.
+    void open(handle.url).catch(() => undefined);
+  }
+
+  // Keep the process alive until the user terminates it. The DB stays
+  // open for the lifetime of the server; closing both on signal so the
+  // file lock releases cleanly.
+  const shutdown = (signal: string) => {
+    log(`\nreceived ${signal}, shutting down`);
+    handle
+      .close()
+      .catch(() => undefined)
+      .finally(() => {
+        db.close();
+        process.exit(0);
+      });
+  };
+  process.on('SIGINT', () => shutdown('SIGINT'));
+  process.on('SIGTERM', () => shutdown('SIGTERM'));
+};
diff --git a/packages/cli/src/fingerprint/fingerprintDirectoryCommand.ts b/packages/cli/src/fingerprint/fingerprintDirectoryCommand.ts
index a7a172b0a6..46ea8fd113 100644
--- a/packages/cli/src/fingerprint/fingerprintDirectoryCommand.ts
+++ b/packages/cli/src/fingerprint/fingerprintDirectoryCommand.ts
@@ -2,13 +2,17 @@ import type { Metadata } from '@appland/models';
 import { findFiles, verbose } from '../utils';
 import FingerprintQueue from './fingerprintQueue';
 import writeUsage, { collectUsageData } from '../lib/emitUsage';
+import type { QueryDbIndexer } from '../cmds/query/db/import/QueryDbIndexer';
 
 class FingerprintDirectoryCommand {
   private appmaps = 0;
   private events = 0;
   private metadata?: Metadata;
 
-  constructor(private readonly directory: string) {}
+  constructor(
+    private readonly directory: string,
+    private readonly indexer?: QueryDbIndexer
+  ) {}
 
   async execute() {
     if (verbose()) {
@@ -21,6 +25,7 @@ class FingerprintDirectoryCommand {
       this.events += numEvents;
       this.metadata = metadata;
     });
+    if (this.indexer) this.indexer.attach(fpQueue);
 
     let count = 0;
     await this.files((file) => {
@@ -29,6 +34,8 @@ class FingerprintDirectoryCommand {
     });
     if (count > 0) await fpQueue.process();
 
+    if (this.indexer) await this.indexer.syncDirectory(this.directory);
+
     const usageData = await collectUsageData(
       this.directory,
       this.events,
diff --git a/packages/cli/src/fingerprint/fingerprintWatchCommand.ts b/packages/cli/src/fingerprint/fingerprintWatchCommand.ts
index 25b01d598b..a2868cfb15 100644
--- a/packages/cli/src/fingerprint/fingerprintWatchCommand.ts
+++ b/packages/cli/src/fingerprint/fingerprintWatchCommand.ts
@@ -11,6 +11,7 @@ import { FingerprintEvent } from './fingerprinter';
 import { Metadata } from '@appland/models';
 import { rm } from 'fs/promises';
 import AppMapIndex from './appmapIndex';
+import type { QueryDbIndexer } from '../cmds/query/db/import/QueryDbIndexer';
 
 export default class FingerprintWatchCommand {
   private pidfilePath: string | undefined;
@@ -31,7 +32,7 @@ export default class FingerprintWatchCommand {
     this._numProcessed = value;
   }
 
-  constructor(private directory: string) {
+  constructor(private directory: string, private readonly indexer?: QueryDbIndexer) {
     this.pidfilePath = process.env.APPMAP_WRITE_PIDFILE && join(this.directory, 'index.pid');
     this.fpQueue = new FingerprintQueue();
     this.eventAggregator = new EventAggregator(async (events) => {
@@ -39,6 +40,7 @@ export default class FingerprintWatchCommand {
       this.numProcessed += events.length;
     });
     this.eventAggregator.attach(this.fpQueue, 'index');
+    if (this.indexer) this.indexer.attach(this.fpQueue);
   }
 
   removePidfile() {
@@ -198,6 +200,8 @@ export default class FingerprintWatchCommand {
     this.poller.start();
     await pollReady;
 
+    if (this.indexer) await this.indexer.syncDirectory(this.directory);
+
     this.ready();
   }
 
@@ -229,6 +233,7 @@ export default class FingerprintWatchCommand {
 
     const { indexDir } = new AppMapIndex(file);
     rm(indexDir, { force: true, recursive: true });
+    if (this.indexer) this.indexer.onRemoved(file);
   }
 
   ready() {
diff --git a/packages/cli/src/html/query-ui/index.css b/packages/cli/src/html/query-ui/index.css
new file mode 100644
index 0000000000..b5c61c9567
--- /dev/null
+++ b/packages/cli/src/html/query-ui/index.css
@@ -0,0 +1,3 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
diff --git a/packages/cli/src/html/query-ui/index.html b/packages/cli/src/html/query-ui/index.html
new file mode 100644
index 0000000000..38da21042d
--- /dev/null
+++ b/packages/cli/src/html/query-ui/index.html
@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>AppMap Query UI</title>
+    <link rel="stylesheet" href="./tailwind.css" />
+  </head>
+  <body class="bg-gray-950 text-gray-100">
+    <div id="root"></div>
+  </body>
+</html>
diff --git a/packages/cli/src/html/query-ui/postcss.config.js b/packages/cli/src/html/query-ui/postcss.config.js
new file mode 100644
index 0000000000..12a703d900
--- /dev/null
+++ b/packages/cli/src/html/query-ui/postcss.config.js
@@ -0,0 +1,6 @@
+module.exports = {
+  plugins: {
+    tailwindcss: {},
+    autoprefixer: {},
+  },
+};
diff --git a/packages/cli/src/html/query-ui/src/components/ExpandableTable.tsx b/packages/cli/src/html/query-ui/src/components/ExpandableTable.tsx
new file mode 100644
index 0000000000..8d62e703fc
--- /dev/null
+++ b/packages/cli/src/html/query-ui/src/components/ExpandableTable.tsx
@@ -0,0 +1,84 @@
+import React, { useState } from 'react';
+import type { Column } from './Table';
+
+interface Props<T> {
+  columns: Column<T>[];
+  rows: T[];
+  rowKey: (row: T) => string;
+  isExpandable?: (row: T) => boolean;
+  renderExpanded: (row: T) => React.ReactNode;
+}
+
+export default function ExpandableTable<T extends Record<string, unknown>>({
+  columns,
+  rows,
+  rowKey,
+  isExpandable,
+  renderExpanded,
+}: Props<T>) {
+  const [expanded, setExpanded] = useState<Set<string>>(new Set());
+
+  if (rows.length === 0) {
+    return <div className="text-gray-500 text-sm py-2">No results.</div>;
+  }
+
+  const toggle = (key: string) => {
+    setExpanded((prev) => {
+      const next = new Set(prev);
+      if (next.has(key)) next.delete(key);
+      else next.add(key);
+      return next;
+    });
+  };
+
+  return (
+    <div className="overflow-x-auto">
+      <table className="w-full text-sm">
+        <thead>
+          <tr className="text-left text-gray-500 border-b border-gray-800">
+            <th className="w-6"></th>
+            {columns.map((c) => (
+              <th key={c.key} className={`py-2 px-2 font-normal ${c.className ?? ''}`}>
+                {c.label}
+              </th>
+            ))}
+          </tr>
+        </thead>
+        <tbody>
+          {rows.map((row) => {
+            const key = rowKey(row);
+            const isOpen = expanded.has(key);
+            const canExpand = isExpandable ? isExpandable(row) : true;
+            return (
+              <React.Fragment key={key}>
+                <tr
+                  className={`border-b border-gray-900 ${canExpand ? 'cursor-pointer hover:bg-gray-800/50' : ''}`}
+                  onClick={canExpand ? () => toggle(key) : undefined}
+                >
+                  <td className="py-2 px-2 align-top text-gray-600">
+                    {canExpand ? (isOpen ? '▼' : '▶') : ''}
+                  </td>
+                  {columns.map((c) => {
+                    const v = c.render ? c.render(row) : String(row[c.key] ?? '-');
+                    return (
+                      <td key={c.key} className={`py-2 px-2 align-top ${c.className ?? ''}`}>
+                        {v as React.ReactNode}
+                      </td>
+                    );
+                  })}
+                </tr>
+                {isOpen && canExpand && (
+                  <tr className="bg-gray-950 border-b border-gray-900">
+                    <td colSpan={columns.length + 1} className="px-4 py-3">
+                      {renderExpanded(row)}
+                    </td>
+                  </tr>
+                )}
+              </React.Fragment>
+            );
+          })}
+        </tbody>
+      </table>
+    </div>
+  );
+}
diff --git a/packages/cli/src/html/query-ui/src/components/HeatBar.tsx b/packages/cli/src/html/query-ui/src/components/HeatBar.tsx
new file mode 100644
index 0000000000..c80f4ea223
--- /dev/null
+++ b/packages/cli/src/html/query-ui/src/components/HeatBar.tsx
@@ -0,0 +1,16 @@
+import React from 'react';
+import { heatColor } from '../lib/format';
+
+export default function HeatBar({ value, max, width = 'w-20' }: { value: number | null; max: number; width?: string }) {
+  if (value == null || max === 0) return <div className={`${width} h-3 bg-gray-800 rounded`} />;
+  const ratio = value / max;
+  const widthPercent = Math.max(ratio * 100, 2);
+  return (
+    <div className={`${width} h-3 bg-gray-800 rounded overflow-hidden`}>
+      <div
+        className={`h-full rounded ${heatColor(ratio)}`}
+        style={{ width: `${widthPercent}%` }}
+      />
+    </div>
+  );
+}
diff --git a/packages/cli/src/html/query-ui/src/components/Layout.tsx b/packages/cli/src/html/query-ui/src/components/Layout.tsx
new file mode 100644
index 0000000000..b909004872
--- /dev/null
+++ b/packages/cli/src/html/query-ui/src/components/Layout.tsx
@@ -0,0 +1,45 @@
+import React from 'react';
+import { Link, useLocation } from 'react-router-dom';
+
+const NAV_ITEMS: { path: string; label: string }[] = [
+  { path: '/', label: 'Dashboard' },
+  { path: '/search', label: 'Search' },
+  { path: '/endpoints', label: 'Endpoints' },
+  { path: '/sql', label: 'SQL' },
+  { path: '/functions', label: 'Functions' },
+  { path: '/exceptions', label: 'Exceptions' },
+  { path: '/labels', label: 'Labels' },
+  { path: '/recordings', label: 'Recordings' },
+  { path: '/compare', label: 'Compare' },
+];
+
+export default function Layout({ children }: { children: React.ReactNode }) {
+  const location = useLocation();
+  const navItems = NAV_ITEMS;
+  return (
+    <div className="min-h-screen bg-gray-950 text-gray-100">
+      <nav className="bg-gray-900 border-b border-gray-800 px-6 py-3 flex items-center gap-8">
+        <span className="text-lg font-bold text-blue-400">AppMap Query</span>
+        <div className="flex flex-wrap gap-1">
+          {navItems.map(({ path, label }) => {
+            const active = path === '/' ? location.pathname === '/' : location.pathname.startsWith(path);
+            return (
+              <Link
+                key={path}
+                to={path}
+                className={`px-3 py-1.5 rounded text-sm ${
+                  active
+                    ? 'bg-blue-600 text-white'
+                    : 'text-gray-400 hover:text-gray-200 hover:bg-gray-800'
+                }`}
+              >
+                {label}
+              </Link>
+            );
+          })}
+        </div>
+      </nav>
+      <main className="p-6">{children}</main>
+    </div>
+  );
+}
diff --git a/packages/cli/src/html/query-ui/src/components/RequestTracePanel.tsx b/packages/cli/src/html/query-ui/src/components/RequestTracePanel.tsx
new file mode 100644
index 0000000000..0834f9595f
--- /dev/null
+++ b/packages/cli/src/html/query-ui/src/components/RequestTracePanel.tsx
@@ -0,0 +1,367 @@
+import React, { useEffect, useState, useCallback } from 'react';
+import { api, RecordingRow, TreeNode, TreeResult } from '../lib/api';
+import { formatMs, severityColor } from '../lib/format';
+
+// Trace panel that drives the appmap-js `tree` query. Two modes:
+//
+//   - Cross-recording: callers pass `focusType` + `focusValue` and the
+//     panel first asks /api/recordings to find recordings exercising that
+//     focus, then loads the tree for the first matching recording.
+//   - Single-recording: callers pass `appmap` (canonical path); the
+//     focus selector is optional.
+//
+// Click on a function node drills the focus to that node's fqid; a back
+// stack tracks history.
+
+interface FocusState {
+  focusType: 'function' | 'sql_query' | 'http_server_request' | 'http_client_request';
+  focusValue: string;
+}
+
+interface Props {
+  // Initial focus to seed the tree.
+  focusType?: FocusState['focusType'];
+  focusValue?: string;
+  // If supplied, the panel goes straight to that recording — no
+  // recording selector is shown.
+  appmap?: string;
+  // When the panel is mounted in cross-recording mode (no appmap), this
+  // route filter is used to find candidate recordings.
+  filterRoute?: string;
+}
+
+export default function RequestTracePanel({ focusType, focusValue, appmap, filterRoute }: Props) {
+  const [recordings, setRecordings] = useState<RecordingRow[] | null>(null);
+  const [selected, setSelected] = useState<string | null>(appmap ?? null);
+  const [tree, setTree] = useState<TreeResult | null>(null);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const [focusStack, setFocusStack] = useState<FocusState[]>([]);
+  const currentFocus: FocusState | null = focusStack.length > 0
+    ? focusStack[focusStack.length - 1]
+    : focusType && focusValue ? { focusType, focusValue } : null;
+
+  const [parentDepth, setParentDepth] = useState(2);
+  const [childDepth, setChildDepth] = useState(3);
+  const [minMs, setMinMs] = useState(0);
+
+  const loadTree = useCallback(
+    async (am: string, focus: FocusState | null, pd: number, cd: number, me: number) => {
+      setLoading(true);
+      setError(null);
+      try {
+        const params: Record<string, string | number> = {
+          appmap: am,
+          parent_depth: pd,
+          child_depth: cd,
+          min_elapsed_ms: me,
+        };
+        if (focus) {
+          params.focus_type = focus.focusType;
+          params.focus_value = focus.focusValue;
+        }
+        const result = await api.tree(params);
+        setTree(result);
+      } catch (e) {
+        setError((e as Error).message);
+      } finally {
+        setLoading(false);
+      }
+    },
+    []
+  );
+
+  // Initial load: either go directly to the supplied appmap, or look up
+  // matching recordings first.
+  useEffect(() => {
+    if (appmap) {
+      void loadTree(appmap, currentFocus, parentDepth, childDepth, minMs);
+      return;
+    }
+    let cancelled = false;
+    void (async () => {
+      try {
+        const params: Record<string, string | number> = { limit: 20 };
+        if (filterRoute) params.route = filterRoute;
+        const page = await api.recordings(params);
+        if (cancelled) return;
+        setRecordings(page.rows);
+        if (page.rows.length > 0) {
+          const first = page.rows[0].path;
+          setSelected(first);
+          void loadTree(first, currentFocus, parentDepth, childDepth, minMs);
+        }
+      } catch (e) {
+        if (!cancelled) setError((e as Error).message);
+      }
+    })();
+    return () => {
+      cancelled = true;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [appmap, filterRoute, focusType, focusValue]);
+
+  const handleParamChange = (key: 'parentDepth' | 'childDepth' | 'minMs', value: number) => {
+    if (key === 'parentDepth') setParentDepth(value);
+    if (key === 'childDepth') setChildDepth(value);
+    if (key === 'minMs') setMinMs(value);
+    if (selected) {
+      const pd = key === 'parentDepth' ? value : parentDepth;
+      const cd = key === 'childDepth' ? value : childDepth;
+      const me = key === 'minMs' ? value : minMs;
+      void loadTree(selected, currentFocus, pd, cd, me);
+    }
+  };
+
+  const handleNodeClick = (node: TreeNode) => {
+    if (node.kind !== 'function' || !node.fqid) return;
+    const newFocus: FocusState = {
+      focusType: 'function',
+      focusValue: String(node.fqid),
+    };
+    setFocusStack([...focusStack, newFocus]);
+    if (selected) void loadTree(selected, newFocus, parentDepth, childDepth, minMs);
+  };
+
+  const handleBack = () => {
+    if (focusStack.length === 0) return;
+    const next = focusStack.slice(0, -1);
+    setFocusStack(next);
+    const focus = next.length > 0 ? next[next.length - 1] : (focusType && focusValue ? { focusType, focusValue } : null);
+    if (selected) void loadTree(selected, focus, parentDepth, childDepth, minMs);
+  };
+
+  if (error && !recordings && !appmap) return <div className="text-red-400 text-xs py-2">{error}</div>;
+  if (!appmap && !recordings) return <div className="text-gray-500 text-xs py-2">Loading recordings...</div>;
+  if (!appmap && recordings && recordings.length === 0) {
+    return <div className="text-gray-500 text-xs py-2">No matching recordings.</div>;
+  }
+
+  return (
+    <div className="mt-2">
+      {recordings && recordings.length > 0 && (
+        <div className="flex gap-2 mb-3 flex-wrap">
+          {recordings.map((r) => (
+            <button
+              key={r.path}
+              onClick={() => {
+                setSelected(r.path);
+                void loadTree(r.path, currentFocus, parentDepth, childDepth, minMs);
+              }}
+              className={`text-xs px-2 py-1 rounded border ${
+                selected === r.path
+                  ? 'border-blue-500 bg-blue-900/40 text-blue-200'
+                  : 'border-gray-700 bg-gray-800/50 text-gray-400 hover:border-gray-600'
+              }`}
+            >
+              {r.label || r.appmap_name}
+              {r.status_code != null && (
+                <span className={`ml-1 ${r.status_code >= 400 ? 'text-red-400' : 'text-green-400'}`}>
+                  [{r.status_code}]
+                </span>
+              )}
+            </button>
+          ))}
+        </div>
+      )}
+
+      <div className="flex items-center gap-2 mb-2">
+        {focusStack.length > 0 && (
+          <button
+            onClick={handleBack}
+            className="text-xs px-2 py-0.5 rounded border border-gray-700 bg-gray-800/50 text-gray-300 hover:border-gray-500"
+          >
+            &larr; Back
+          </button>
+        )}
+        {currentFocus && (
+          <span className="text-xs text-gray-400">
+            Focus: <span className="text-gray-200 font-mono">{currentFocus.focusValue}</span>
+          </span>
+        )}
+      </div>
+
+      <div className="flex gap-4 items-center text-xs text-gray-400 mb-3">
+        <label className="flex items-center gap-1">
+          Parent depth
+          <input
+            type="number"
+            min={0}
+            max={20}
+            value={parentDepth}
+            onChange={(e) => handleParamChange('parentDepth', Number(e.target.value))}
+            className="w-14 bg-gray-800 border border-gray-700 rounded px-1.5 py-0.5 text-gray-200 text-xs"
+          />
+        </label>
+        <label className="flex items-center gap-1">
+          Child depth
+          <input
+            type="number"
+            min={0}
+            max={20}
+            value={childDepth}
+            onChange={(e) => handleParamChange('childDepth', Number(e.target.value))}
+            className="w-14 bg-gray-800 border border-gray-700 rounded px-1.5 py-0.5 text-gray-200 text-xs"
+          />
+        </label>
+        <label className="flex items-center gap-1">
+          Min elapsed
+          <input
+            type="number"
+            min={0}
+            step={1}
+            value={minMs}
+            onChange={(e) => handleParamChange('minMs', Number(e.target.value))}
+            className="w-20 bg-gray-800 border border-gray-700 rounded px-1.5 py-0.5 text-gray-200 text-xs"
+          />
+          <span>ms</span>
+        </label>
+      </div>
+
+      <div className="bg-gray-950 border border-gray-800 rounded p-3 max-h-96 overflow-y-auto">
+        {loading ? (
+          <div className="text-gray-500 text-xs">Loading trace...</div>
+        ) : error ? (
+          <div className="text-red-400 text-xs">{error}</div>
+        ) : !tree || tree.nodes.length === 0 ? (
+          <div className="text-gray-500 text-xs">No trace data.</div>
+        ) : (
+          <TraceTree nodes={tree.nodes} onNodeClick={handleNodeClick} />
+        )}
+        {tree?.truncated && (
+          <div className="mt-2 text-xs text-yellow-500/80 border-t border-gray-800 pt-2">
+            Tree truncated. Increase child depth to drill in further.
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
+
+function kindBadgeColor(k: TreeNode['kind']): string {
+  switch (k) {
+    case 'function':
+      return 'bg-blue-900/60 text-blue-300';
+    case 'sql':
+      return 'bg-purple-900/60 text-purple-300';
+    case 'http_server':
+      return 'bg-green-900/60 text-green-300';
+    case 'http_client':
+      return 'bg-orange-900/60 text-orange-300';
+    case 'exception':
+      return 'bg-red-900/60 text-red-300';
+    case 'log':
+      return 'bg-gray-800 text-gray-300';
+  }
+}
+
+function kindIcon(k: TreeNode['kind']): string {
+  switch (k) {
+    case 'function':
+      return 'fn';
+    case 'sql':
+      return 'SQL';
+    case 'http_server':
+      return 'HTTP';
+    case 'http_client':
+      return 'OUT';
+    case 'exception':
+      return 'EXC';
+    case 'log':
+      return 'log';
+  }
+}
+
+function nodeLabel(n: TreeNode): string {
+  switch (n.kind) {
+    case 'function':
+      return String(n.fqid ?? `${n.defined_class as string}.${n.method_id as string}`);
+    case 'sql': {
+      const text = String(n.sql_text ?? '');
+      return `SQL: ${text.length > 80 ? text.slice(0, 80) + '...' : text}`;
+    }
+    case 'http_server':
+      return `${n.method as string} ${n.route as string} [${n.status_code as number}]`;
+    case 'http_client':
+      return `HTTP ${n.method as string} ${n.url as string}${n.status_code ? ` [${n.status_code as number}]` : ''}`;
+    case 'exception':
+      return `${n.exception_class as string}${n.message ? `: ${String(n.message).slice(0, 60)}` : ''}`;
+    case 'log':
+      return String(n.message ?? n.method_id ?? 'log');
+  }
+}
+
+function TraceTree({
+  nodes,
+  onNodeClick,
+}: {
+  nodes: TreeNode[];
+  onNodeClick: (node: TreeNode) => void;
+}) {
+  const [expandedSql, setExpandedSql] = useState<Set<number>>(new Set());
+
+  return (
+    <div className="font-mono text-xs leading-relaxed overflow-x-auto">
+      {nodes.map((node) => {
+        const elapsed =
+          typeof node.elapsed_ms === 'number' ? (node.elapsed_ms as number) : null;
+        const isClickable = node.kind === 'function' && Boolean(node.fqid);
+        const sqlText = node.kind === 'sql' ? String(node.sql_text ?? '') : '';
+        const sqlExpandable = node.kind === 'sql' && sqlText.length > 80;
+        const sqlOpen = expandedSql.has(node.event_id);
+        return (
+          <div key={`${node.event_id}-${node.depth}`}>
+            <div
+              className={`flex items-baseline gap-2 py-0.5 rounded ${
+                isClickable ? 'cursor-pointer hover:bg-gray-800/60' : ''
+              }`}
+              style={{ paddingLeft: `${node.depth * 20 + 8}px` }}
+              onClick={() => isClickable && onNodeClick(node)}
+            >
+              <span
+                className={`inline-block w-8 text-center rounded text-[10px] font-bold ${kindBadgeColor(node.kind)}`}
+              >
+                {kindIcon(node.kind)}
+              </span>
+              <span
+                className={`flex-1 text-gray-300 ${
+                  isClickable ? 'underline decoration-dotted decoration-gray-600 hover:decoration-blue-400' : ''
+                }`}
+              >
+                {nodeLabel(node)}
+                {sqlExpandable && (
+                  <button
+                    onClick={(e) => {
+                      e.stopPropagation();
+                      setExpandedSql((prev) => {
+                        const next = new Set(prev);
+                        if (next.has(node.event_id)) next.delete(node.event_id);
+                        else next.add(node.event_id);
+                        return next;
+                      });
+                    }}
+                    className="ml-2 text-purple-400 hover:text-purple-300 text-[10px] no-underline"
+                  >
+                    {sqlOpen ? '[collapse]' : '[expand]'}
+                  </button>
+                )}
+              </span>
+              {elapsed != null && (
+                <span className={`whitespace-nowrap ${severityColor(elapsed)}`}>{formatMs(elapsed)}</span>
+              )}
+            </div>
+            {sqlExpandable && sqlOpen && (
+              <pre
+                className="text-purple-200 bg-purple-950/30 border border-purple-900/40 rounded p-2 mx-2 my-1 whitespace-pre-wrap break-all text-[11px]"
+                style={{ marginLeft: `${node.depth * 20 + 40}px` }}
+              >
+                {sqlText}
+              </pre>
+            )}
+          </div>
+        );
+      })}
+    </div>
+  );
+}
diff --git a/packages/cli/src/html/query-ui/src/components/StatCard.tsx b/packages/cli/src/html/query-ui/src/components/StatCard.tsx
new file mode 100644
index 0000000000..d8d8604f75
--- /dev/null
+++ b/packages/cli/src/html/query-ui/src/components/StatCard.tsx
@@ -0,0 +1,10 @@
+import React from 'react';
+
+export default function StatCard({ label, value }: { label: string; value: React.ReactNode }) {
+  return (
+    <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
+      <div className="text-xs uppercase tracking-wide text-gray-500 mb-1">{label}</div>
+      <div className="text-2xl font-bold text-gray-100">{value}</div>
+    </div>
+  );
+}
diff --git a/packages/cli/src/html/query-ui/src/components/Table.tsx b/packages/cli/src/html/query-ui/src/components/Table.tsx
new file mode 100644
index 0000000000..700302c59b
--- /dev/null
+++ b/packages/cli/src/html/query-ui/src/components/Table.tsx
@@ -0,0 +1,59 @@
+import React from 'react';
+
+export interface Column<T> {
+  key: string;
+  label: string;
+  render?: (row: T) => React.ReactNode;
+  className?: string;
+}
+
+interface Props<T> {
+  columns: Column<T>[];
+  rows: T[];
+  rowKey?: (row: T, index: number) => string;
+  onRowClick?: (row: T) => void;
+}
+
+export default function Table<T extends Record<string, unknown>>({
+  columns,
+  rows,
+  rowKey,
+  onRowClick,
+}: Props<T>) {
+  if (rows.length === 0) {
+    return <div className="text-gray-500 text-sm py-2">No results.</div>;
+  }
+  return (
+    <div className="overflow-x-auto">
+      <table className="w-full text-sm">
+        <thead>
+          <tr className="text-left text-gray-500 border-b border-gray-800">
+            {columns.map((c) => (
+              <th key={c.key} className={`py-2 px-2 font-normal ${c.className ?? ''}`}>
+                {c.label}
+              </th>
+            ))}
+          </tr>
+        </thead>
+        <tbody>
+          {rows.map((row, i) => (
+            <tr
+              key={rowKey ? rowKey(row, i) : i}
+              className={`border-b border-gray-900 ${onRowClick ? 'cursor-pointer hover:bg-gray-800/50' : ''}`}
+              onClick={onRowClick ? () => onRowClick(row) : undefined}
+            >
+              {columns.map((c) => {
+                const v = c.render ? c.render(row) : String(row[c.key] ?? '-');
+                return (
+                  <td key={c.key} className={`py-2 px-2 align-top ${c.className ?? ''}`}>
+                    {v as React.ReactNode}
+                  </td>
+                );
+              })}
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </div>
+  );
+}
diff --git a/packages/cli/src/html/query-ui/src/lib/api.ts b/packages/cli/src/html/query-ui/src/lib/api.ts
new file mode 100644
index 0000000000..1fcb69af67
--- /dev/null
+++ b/packages/cli/src/html/query-ui/src/lib/api.ts
@@ -0,0 +1,253 @@
+// Thin wrapper around the /api/* REST surface exposed by uiServer.ts.
+// All routes return either a Page<T> (rows + total + limit + offset) or
+// a small JSON object — the helper just deserializes and propagates
+// non-2xx as Error.
+
+export interface Page<T> {
+  rows: T[];
+  total: number;
+  limit: number;
+  offset: number;
+}
+
+async function getJson<T>(path: string, params?: Record<string, string | number | undefined>): Promise<T> {
+  const url = new URL(path, window.location.origin);
+  if (params) {
+    for (const [k, v] of Object.entries(params)) {
+      if (v === undefined || v === null || v === '') continue;
+      url.searchParams.set(k, String(v));
+    }
+  }
+  const res = await fetch(url.toString(), { headers: { Accept: 'application/json' } });
+  if (!res.ok) {
+    let msg: string;
+    try {
+      const body = (await res.json()) as { error?: string };
+      msg = body.error ?? `${res.status} ${res.statusText}`;
+    } catch {
+      msg = `${res.status} ${res.statusText}`;
+    }
+    throw new Error(msg);
+  }
+  return (await res.json()) as T;
+}
+
+export const api = {
+  dashboard: () => getJson<DashboardTotals>('/api/dashboard'),
+  endpoints: (params?: Record<string, string | number | undefined>) =>
+    getJson<Page<EndpointRow>>('/api/endpoints', params),
+  recordings: (params?: Record<string, string | number | undefined>) =>
+    getJson<Page<RecordingRow>>('/api/recordings', params),
+  recording: (appmap: string) =>
+    getJson<{ recording: RecordingDetail; counts: Record<string, number> }>(
+      '/api/recording',
+      { appmap }
+    ),
+  requests: (params?: Record<string, string | number | undefined>) =>
+    getJson<Page<RequestRow>>('/api/requests', params),
+  queries: (params?: Record<string, string | number | undefined>) =>
+    getJson<Page<QueryRow>>('/api/queries', params),
+  calls: (params?: Record<string, string | number | undefined>) =>
+    getJson<Page<CallRow>>('/api/calls', params),
+  logs: (params?: Record<string, string | number | undefined>) =>
+    getJson<Page<LogRow>>('/api/logs', params),
+  exceptions: (params?: Record<string, string | number | undefined>) =>
+    getJson<Page<ExceptionRow>>('/api/exceptions', params),
+  functionHotspots: (params?: Record<string, string | number | undefined>) =>
+    getJson<Page<FunctionHotspotRow>>('/api/functions/hotspots', params),
+  sqlHotspots: (params?: Record<string, string | number | undefined>) =>
+    getJson<Page<SqlHotspotRow>>('/api/sql/hotspots', params),
+  labels: () => getJson<LabelRow[]>('/api/labels'),
+  tree: (params: Record<string, string | number | undefined>) =>
+    getJson<TreeResult>('/api/tree', params),
+  related: (params: Record<string, string | number | undefined>) =>
+    getJson<Page<RelatedRow>>('/api/related', params),
+  compare: (params: Record<string, string | number | undefined>) =>
+    getJson<Page<CompareRow>>('/api/compare', params),
+  search: (q: string, limit = 25) => getJson<SearchResult>('/api/search', { q, limit }),
+};
+
+// ---- types -------------------------------------------------------------
+
+export interface DashboardTotals {
+  recordings: number;
+  requests: number;
+  queries: number;
+  exceptions: number;
+  calls: number;
+  avg_request_ms: number | null;
+  earliest: string | null;
+  latest: string | null;
+}
+
+export interface EndpointRow {
+  method: string;
+  route: string;
+  count: number;
+  avg_ms: number | null;
+  p95_ms: number | null;
+  err_pct: number;
+}
+
+export interface RecordingRow {
+  appmap_id: number;
+  appmap_name: string;
+  source_path: string;
+  path: string;
+  label: string;
+  kind: 'junit' | 'request' | 'other';
+  route: string | null;
+  status_code: number | null;
+  elapsed_ms: number | null;
+  sql_count: number;
+  branch: string | null;
+  timestamp: string | null;
+}
+
+export interface RecordingDetail {
+  id: number;
+  name: string;
+  source_path: string;
+  path: string;
+  label: string;
+  language: string | null;
+  framework: string | null;
+  recorder_type: string | null;
+  git_repository: string | null;
+  git_branch: string | null;
+  git_commit: string | null;
+  timestamp: string | null;
+  event_count: number;
+  sql_query_count: number;
+  http_request_count: number;
+  elapsed_ms: number | null;
+}
+
+export interface RequestRow {
+  appmap_name: string;
+  event_id: number;
+  method: string;
+  route: string;
+  status_code: number;
+  elapsed_ms: number | null;
+  branch: string | null;
+}
+
+export interface QueryRow {
+  appmap_name: string;
+  event_id: number;
+  elapsed_ms: number | null;
+  caller_class: string | null;
+  caller_method: string | null;
+  sql_text: string;
+}
+
+export interface CallRow {
+  appmap_name: string;
+  event_id: number;
+  fqid: string | null;
+  defined_class: string;
+  method_id: string;
+  path: string | null;
+  lineno: number | null;
+  elapsed_ms: number | null;
+  parameters_json: string | null;
+  return_value: string | null;
+}
+
+export interface LogRow {
+  appmap_name: string;
+  event_id: number;
+  parent_event_id: number | null;
+  logger: string;
+  method_id: string;
+  path: string | null;
+  lineno: number | null;
+  message: string;
+  parameters_json: string | null;
+  return_value: string | null;
+}
+
+export interface ExceptionRow {
+  appmap_id: number;
+  appmap_name: string;
+  event_id: number;
+  return_event_id: number | null;
+  exception_class: string;
+  message: string | null;
+  path: string | null;
+  lineno: number | null;
+  recent_logs?: LogRow[];
+}
+
+export interface FunctionHotspotRow {
+  fqid: string | null;
+  defined_class: string;
+  method_id: string;
+  path: string | null;
+  lineno: number | null;
+  calls: number;
+  total_ms: number;
+  self_ms: number;
+}
+
+export interface SqlHotspotRow {
+  count: number;
+  avg_ms: number;
+  total_ms: number;
+  sql_text: string;
+}
+
+export interface LabelRow {
+  label: string;
+  count: number;
+  sample_fqid: string;
+}
+
+export interface TreeNode {
+  event_id: number;
+  parent_event_id: number | null;
+  thread_id: number | null;
+  depth: number;
+  kind: 'function' | 'sql' | 'http_server' | 'http_client' | 'exception' | 'log';
+  // kind-specific fields are loose here; the renderer reads what it needs.
+  [key: string]: unknown;
+}
+
+export interface TreeResult {
+  nodes: TreeNode[];
+  truncated: boolean;
+  max_depth_reached?: boolean;
+  next_step?: { tool: string; args: Record<string, unknown> } | null;
+}
+
+export interface RelatedRow {
+  appmap_name: string;
+  source_path: string;
+  score: number;
+  method: string | null;
+  route: string | null;
+  status_code: number | null;
+  elapsed_ms: number | null;
+  shared: string[];
+}
+
+export interface CompareRow {
+  method: string;
+  route: string;
+  a_count: number;
+  a_p95_ms: number | null;
+  b_count: number;
+  b_p95_ms: number | null;
+  delta: number | null;
+}
+
+export interface SearchResult {
+  query: string;
+  filters: Record<string, string>;
+  recordings?: Page<RecordingRow>;
+  requests?: Page<RequestRow>;
+  queries?: Page<QueryRow>;
+  calls?: Page<CallRow>;
+  exceptions?: Page<ExceptionRow>;
+}
diff --git a/packages/cli/src/html/query-ui/src/lib/format.ts b/packages/cli/src/html/query-ui/src/lib/format.ts
new file mode 100644
index 0000000000..d73a052cab
--- /dev/null
+++ b/packages/cli/src/html/query-ui/src/lib/format.ts
@@ -0,0 +1,59 @@
+// Display helpers shared across pages.
+
+export function formatMs(ms: number | null | undefined): string {
+  if (ms == null) return '-';
+  return ms >= 1000 ? `${(ms / 1000).toFixed(2)}s` : `${ms.toFixed(1)}ms`;
+}
+
+export function formatPct(p: number | null | undefined): string {
+  if (p == null) return '-';
+  return `${p.toFixed(1)}%`;
+}
+
+export function formatTime(ts: string | null | undefined): string {
+  if (!ts) return '-';
+  return new Date(ts).toLocaleString();
+}
+
+// Threshold-banded color for elapsed-time values.
+export function severityColor(ms: number | null | undefined): string {
+  if (ms == null) return 'text-gray-400';
+  if (ms < 10) return 'text-green-400';
+  if (ms < 100) return 'text-yellow-400';
+  if (ms < 1000) return 'text-orange-400';
+  return 'text-red-400';
+}
+
+// HTTP status code → text color.
+export function statusColor(code: number): string {
+  if (code >= 500) return 'text-red-400';
+  if (code >= 400) return 'text-yellow-400';
+  return 'text-green-400';
+}
+
+// HTTP method badge colors.
+export function methodBadge(method: string): string {
+  const colors: Record<string, string> = {
+    GET: 'bg-green-900/50 text-green-400',
+    POST: 'bg-blue-900/50 text-blue-400',
+    PUT: 'bg-yellow-900/50 text-yellow-400',
+    DELETE: 'bg-red-900/50 text-red-400',
+    PATCH: 'bg-purple-900/50 text-purple-400',
+  };
+  return colors[method] ?? 'bg-gray-800 text-gray-400';
+}
+
+// Heat-bar fill color by ratio (0-1).
+export function heatColor(ratio: number): string {
+  if (ratio < 0.25) return 'bg-green-500';
+  if (ratio < 0.5) return 'bg-yellow-500';
+  if (ratio < 0.75) return 'bg-orange-500';
+  return 'bg-red-500';
+}
+
+// URL-safe encoding for an appmap path used as a query parameter.
+// Filesystem paths almost never contain characters that need escaping,
+// but we encode anyway so the URL is well-formed regardless.
+export function encodeAppmap(path: string): string {
+  return encodeURIComponent(path);
+}
diff --git a/packages/cli/src/html/query-ui/src/main.tsx b/packages/cli/src/html/query-ui/src/main.tsx
new file mode 100644
index 0000000000..449c82f497
--- /dev/null
+++ b/packages/cli/src/html/query-ui/src/main.tsx
@@ -0,0 +1,37 @@
+import React from 'react';
+import { createRoot } from 'react-dom/client';
+import { BrowserRouter, Routes, Route } from 'react-router-dom';
+
+import Layout from './components/Layout';
+import Dashboard from './pages/Dashboard';
+import Endpoints from './pages/Endpoints';
+import Sql from './pages/Sql';
+import Functions from './pages/Functions';
+import Exceptions from './pages/Exceptions';
+import Recordings from './pages/Recordings';
+import RecordingDetail from './pages/RecordingDetail';
+import Search from './pages/Search';
+import Labels from './pages/Labels';
+import Compare from './pages/Compare';
+
+const root = createRoot(document.getElementById('root')!);
+root.render(
+  <React.StrictMode>
+    <BrowserRouter>
+      <Layout>
+        <Routes>
+          <Route path="/" element={<Dashboard />} />
+          <Route path="/endpoints" element={<Endpoints />} />
+          <Route path="/sql" element={<Sql />} />
+          <Route path="/functions" element={<Functions />} />
+          <Route path="/exceptions" element={<Exceptions />} />
+          <Route path="/recordings" element={<Recordings />} />
+          <Route path="/recordings/detail" element={<RecordingDetail />} />
+          <Route path="/search" element={<Search />} />
+          <Route path="/labels" element={<Labels />} />
+          <Route path="/compare" element={<Compare />} />
+        </Routes>
+      </Layout>
+    </BrowserRouter>
+  </React.StrictMode>
+);
diff --git a/packages/cli/src/html/query-ui/src/pages/Compare.tsx b/packages/cli/src/html/query-ui/src/pages/Compare.tsx
new file mode 100644
index 0000000000..de995f0087
--- /dev/null
+++ b/packages/cli/src/html/query-ui/src/pages/Compare.tsx
@@ -0,0 +1,88 @@
+import React, { useState } from 'react';
+import { api, CompareRow } from '../lib/api';
+import { formatMs, severityColor } from '../lib/format';
+import Table, { Column } from '../components/Table';
+
+export default function Compare() {
+  const [a, setA] = useState('');
+  const [b, setB] = useState('');
+  const [rows, setRows] = useState<CompareRow[]>([]);
+  const [error, setError] = useState<string | null>(null);
+  const [loading, setLoading] = useState(false);
+
+  const run = async () => {
+    if (!a || !b) return;
+    setLoading(true);
+    setError(null);
+    try {
+      const p = await api.compare({ branch_a: a, branch_b: b, sort: 'delta', limit: 100 });
+      setRows(p.rows);
+    } catch (e) {
+      setError((e as Error).message);
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  const columns: Column<CompareRow>[] = [
+    { key: 'method', label: 'Method', className: 'font-mono w-20' },
+    { key: 'route', label: 'Route', render: (r) => <span className="font-mono text-gray-200">{r.route}</span> },
+    { key: 'a_count', label: 'A reqs', className: 'text-right' },
+    { key: 'a_p95_ms', label: 'A p95', render: (r) => <span className={severityColor(r.a_p95_ms)}>{formatMs(r.a_p95_ms)}</span>, className: 'text-right' },
+    { key: 'b_count', label: 'B reqs', className: 'text-right' },
+    { key: 'b_p95_ms', label: 'B p95', render: (r) => <span className={severityColor(r.b_p95_ms)}>{formatMs(r.b_p95_ms)}</span>, className: 'text-right' },
+    {
+      key: 'delta',
+      label: 'Δ (B/A)',
+      render: (r) => {
+        if (r.delta == null) return <span className="text-gray-500">-</span>;
+        const cls =
+          r.delta > 1.5 ? 'text-red-400' : r.delta > 1.1 ? 'text-orange-400' : r.delta < 0.9 ? 'text-green-400' : 'text-gray-300';
+        return <span className={cls}>{r.delta.toFixed(2)}×</span>;
+      },
+      className: 'text-right',
+    },
+  ];
+
+  return (
+    <div>
+      <h1 className="text-2xl font-bold mb-6">Compare branches</h1>
+
+      <div className="bg-gray-900 border border-gray-800 rounded-lg p-4 mb-6 flex gap-3 items-end">
+        <div className="flex-1">
+          <label className="block text-xs text-gray-500 mb-1">Branch A (baseline)</label>
+          <input
+            value={a}
+            onChange={(e) => setA(e.target.value)}
+            placeholder="main"
+            className="w-full bg-gray-800 border border-gray-700 rounded px-2 py-1.5 font-mono text-sm"
+          />
+        </div>
+        <div className="flex-1">
+          <label className="block text-xs text-gray-500 mb-1">Branch B</label>
+          <input
+            value={b}
+            onChange={(e) => setB(e.target.value)}
+            placeholder="feat/x"
+            className="w-full bg-gray-800 border border-gray-700 rounded px-2 py-1.5 font-mono text-sm"
+          />
+        </div>
+        <button
+          onClick={() => void run()}
+          disabled={!a || !b || loading}
+          className="bg-blue-600 hover:bg-blue-500 disabled:opacity-50 text-white px-4 py-1.5 rounded text-sm"
+        >
+          {loading ? 'Loading...' : 'Compare'}
+        </button>
+      </div>
+
+      {error && <div className="text-red-400 mb-4">{error}</div>}
+
+      {rows.length > 0 && (
+        <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
+          <Table columns={columns} rows={rows} rowKey={(r) => `${r.method}:${r.route}`} />
+        </div>
+      )}
+    </div>
+  );
+}
diff --git a/packages/cli/src/html/query-ui/src/pages/Dashboard.tsx b/packages/cli/src/html/query-ui/src/pages/Dashboard.tsx
new file mode 100644
index 0000000000..2f6e267e6b
--- /dev/null
+++ b/packages/cli/src/html/query-ui/src/pages/Dashboard.tsx
@@ -0,0 +1,141 @@
+import React, { useEffect, useState } from 'react';
+import { Link } from 'react-router-dom';
+import { api, DashboardTotals, EndpointRow, FunctionHotspotRow, SqlHotspotRow, ExceptionRow } from '../lib/api';
+import { formatMs, formatTime, severityColor } from '../lib/format';
+import StatCard from '../components/StatCard';
+
+interface State {
+  totals: DashboardTotals;
+  endpoints: EndpointRow[];
+  fnHotspots: FunctionHotspotRow[];
+  sqlHotspots: SqlHotspotRow[];
+  exceptions: ExceptionRow[];
+}
+
+export default function Dashboard() {
+  const [state, setState] = useState<State | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    let cancelled = false;
+    void (async () => {
+      try {
+        const [totals, endpoints, fnHs, sqlHs, exc] = await Promise.all([
+          api.dashboard(),
+          api.endpoints({ sort: 'avg', limit: 5 }),
+          api.functionHotspots({ limit: 5 }),
+          api.sqlHotspots({ limit: 5 }),
+          api.exceptions({ limit: 5 }),
+        ]);
+        if (cancelled) return;
+        setState({
+          totals,
+          endpoints: endpoints.rows,
+          fnHotspots: fnHs.rows,
+          sqlHotspots: sqlHs.rows,
+          exceptions: exc.rows,
+        });
+      } catch (e) {
+        if (!cancelled) setError((e as Error).message);
+      }
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
+  if (error) return <div className="text-red-400">Error: {error}</div>;
+  if (!state) return <div className="text-gray-400">Loading...</div>;
+  const { totals, endpoints, fnHotspots, sqlHotspots, exceptions } = state;
+
+  return (
+    <div>
+      <h1 className="text-2xl font-bold mb-6">Dashboard</h1>
+
+      <div className="grid grid-cols-2 md:grid-cols-5 gap-4 mb-8">
+        <StatCard label="Recordings" value={totals.recordings} />
+        <StatCard label="HTTP Requests" value={totals.requests} />
+        <StatCard label="SQL Queries" value={totals.queries} />
+        <StatCard label="Function Calls" value={totals.calls} />
+        <StatCard label="Exceptions" value={totals.exceptions} />
+      </div>
+
+      <div className="grid grid-cols-2 md:grid-cols-3 gap-4 mb-8 text-sm">
+        <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
+          <div className="text-xs text-gray-500 mb-1">Avg HTTP latency</div>
+          <div className={`text-xl font-bold ${severityColor(totals.avg_request_ms)}`}>{formatMs(totals.avg_request_ms)}</div>
+        </div>
+        <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
+          <div className="text-xs text-gray-500 mb-1">Earliest recording</div>
+          <div className="text-base font-mono text-gray-300">{formatTime(totals.earliest)}</div>
+        </div>
+        <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
+          <div className="text-xs text-gray-500 mb-1">Latest recording</div>
+          <div className="text-base font-mono text-gray-300">{formatTime(totals.latest)}</div>
+        </div>
+      </div>
+
+      <div className="grid grid-cols-1 lg:grid-cols-2 gap-6">
+        <Section title="Slowest Endpoints" link={{ to: '/endpoints', label: 'all' }}>
+          {endpoints.length === 0 ? <Empty /> : endpoints.map((e) => (
+            <Row key={`${e.method}:${e.route}`} left={<span className="font-mono text-xs">{e.method} {e.route}</span>}>
+              <span className={severityColor(e.avg_ms)}>{formatMs(e.avg_ms)}</span>
+              <span className="text-gray-500 ml-3 text-xs">{e.count} reqs</span>
+            </Row>
+          ))}
+        </Section>
+
+        <Section title="Hottest Functions" link={{ to: '/functions', label: 'all' }}>
+          {fnHotspots.length === 0 ? <Empty /> : fnHotspots.map((h, i) => (
+            <Row key={i} left={<span className="font-mono text-xs">{h.fqid ?? `${h.defined_class}.${h.method_id}`}</span>}>
+              <span className={severityColor(h.total_ms)}>{formatMs(h.total_ms)}</span>
+              <span className="text-gray-500 ml-3 text-xs">{h.calls} calls</span>
+            </Row>
+          ))}
+        </Section>
+
+        <Section title="Slowest SQL" link={{ to: '/sql', label: 'all' }}>
+          {sqlHotspots.length === 0 ? <Empty /> : sqlHotspots.map((s, i) => (
+            <Row key={i} left={<span className="font-mono text-xs text-gray-300" title={s.sql_text}>{s.sql_text.length > 80 ? s.sql_text.slice(0, 80) + '...' : s.sql_text}</span>}>
+              <span className={severityColor(s.total_ms)}>{formatMs(s.total_ms)}</span>
+              <span className="text-gray-500 ml-3 text-xs">{s.count}×</span>
+            </Row>
+          ))}
+        </Section>
+
+        <Section title="Recent Exceptions" link={{ to: '/exceptions', label: 'all' }}>
+          {exceptions.length === 0 ? <Empty /> : exceptions.map((e) => (
+            <Row key={e.event_id} left={<span className="font-mono text-red-400 text-xs">{e.exception_class}</span>}>
+              <span className="text-gray-400 text-xs">{(e.message ?? '').slice(0, 60)}</span>
+            </Row>
+          ))}
+        </Section>
+      </div>
+    </div>
+  );
+}
+
+function Section({ title, link, children }: { title: string; link?: { to: string; label: string }; children: React.ReactNode }) {
+  return (
+    <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
+      <div className="flex items-baseline justify-between mb-3">
+        <h2 className="text-sm font-medium text-gray-400">{title}</h2>
+        {link && <Link to={link.to} className="text-xs text-blue-400 hover:underline">{link.label}</Link>}
+      </div>
+      <div className="space-y-1">{children}</div>
+    </div>
+  );
+}
+
+function Row({ left, children }: { left: React.ReactNode; children: React.ReactNode }) {
+  return (
+    <div className="flex items-baseline justify-between gap-3 py-1 border-b border-gray-900 last:border-b-0">
+      <div className="flex-1 min-w-0 truncate">{left}</div>
+      <div className="flex-none whitespace-nowrap">{children}</div>
+    </div>
+  );
+}
+
+function Empty() {
+  return <div className="text-gray-600 text-sm">No data.</div>;
+}
diff --git a/packages/cli/src/html/query-ui/src/pages/Endpoints.tsx b/packages/cli/src/html/query-ui/src/pages/Endpoints.tsx
new file mode 100644
index 0000000000..44005ca865
--- /dev/null
+++ b/packages/cli/src/html/query-ui/src/pages/Endpoints.tsx
@@ -0,0 +1,69 @@
+import React, { useEffect, useState } from 'react';
+import { api, EndpointRow } from '../lib/api';
+import { formatMs, formatPct, methodBadge, severityColor } from '../lib/format';
+import ExpandableTable from '../components/ExpandableTable';
+import HeatBar from '../components/HeatBar';
+import RequestTracePanel from '../components/RequestTracePanel';
+import type { Column } from '../components/Table';
+
+export default function Endpoints() {
+  const [rows, setRows] = useState<EndpointRow[]>([]);
+  const [error, setError] = useState<string | null>(null);
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    let cancelled = false;
+    void (async () => {
+      try {
+        const page = await api.endpoints({ limit: 100, sort: 'count' });
+        if (!cancelled) setRows(page.rows);
+      } catch (e) {
+        if (!cancelled) setError((e as Error).message);
+      } finally {
+        if (!cancelled) setLoading(false);
+      }
+    })();
+    return () => { cancelled = true; };
+  }, []);
+
+  if (loading) return <div className="text-gray-400">Loading...</div>;
+  if (error) return <div className="text-red-400">Error: {error}</div>;
+
+  const maxAvg = Math.max(...rows.map((r) => r.avg_ms ?? 0), 1);
+
+  const columns: Column<EndpointRow>[] = [
+    { key: 'heat', label: '', render: (r) => <HeatBar value={r.avg_ms} max={maxAvg} />, className: 'w-24' },
+    {
+      key: 'method',
+      label: 'Method',
+      render: (r) => <span className={`px-2 py-0.5 rounded text-xs font-mono ${methodBadge(r.method)}`}>{r.method}</span>,
+      className: 'w-20',
+    },
+    { key: 'route', label: 'Route', render: (r) => <span className="font-mono text-gray-200">{r.route}</span> },
+    { key: 'count', label: 'Requests', className: 'text-right' },
+    { key: 'avg_ms', label: 'Avg', render: (r) => <span className={severityColor(r.avg_ms)}>{formatMs(r.avg_ms)}</span>, className: 'text-right' },
+    { key: 'p95_ms', label: 'p95', render: (r) => <span className={severityColor(r.p95_ms)}>{formatMs(r.p95_ms)}</span>, className: 'text-right' },
+    {
+      key: 'err_pct',
+      label: 'Err%',
+      render: (r) => <span className={r.err_pct > 0 ? 'text-red-400 font-semibold' : 'text-gray-500'}>{formatPct(r.err_pct)}</span>,
+      className: 'text-right',
+    },
+  ];
+
+  return (
+    <div>
+      <h1 className="text-2xl font-bold mb-6">Endpoints</h1>
+      <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
+        <ExpandableTable
+          columns={columns}
+          rows={rows}
+          rowKey={(r) => `${r.method}:${r.route}`}
+          renderExpanded={(r) => (
+            <RequestTracePanel focusType="http_server_request" focusValue={r.route} filterRoute={r.route} />
+          )}
+        />
+      </div>
+    </div>
+  );
+}
diff --git a/packages/cli/src/html/query-ui/src/pages/Exceptions.tsx b/packages/cli/src/html/query-ui/src/pages/Exceptions.tsx
new file mode 100644
index 0000000000..bd2605e318
--- /dev/null
+++ b/packages/cli/src/html/query-ui/src/pages/Exceptions.tsx
@@ -0,0 +1,71 @@
+import React, { useEffect, useState } from 'react';
+import { api, ExceptionRow } from '../lib/api';
+
+export default function Exceptions() {
+  const [rows, setRows] = useState<ExceptionRow[]>([]);
+  const [error, setError] = useState<string | null>(null);
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    let cancelled = false;
+    void (async () => {
+      try {
+        const page = await api.exceptions({ limit: 100, with_logs: 5 });
+        if (!cancelled) setRows(page.rows);
+      } catch (e) {
+        if (!cancelled) setError((e as Error).message);
+      } finally {
+        if (!cancelled) setLoading(false);
+      }
+    })();
+    return () => { cancelled = true; };
+  }, []);
+
+  if (loading) return <div className="text-gray-400">Loading...</div>;
+  if (error) return <div className="text-red-400">Error: {error}</div>;
+  if (rows.length === 0) return <div>
+    <h1 className="text-2xl font-bold mb-6">Exceptions</h1>
+    <div className="text-gray-500">No exceptions recorded.</div>
+  </div>;
+
+  return (
+    <div>
+      <h1 className="text-2xl font-bold mb-6">Exceptions</h1>
+      <div className="space-y-3">
+        {rows.map((r) => (
+          <div key={`${r.appmap_id}-${r.event_id}`} className="bg-gray-900 border border-gray-800 rounded-lg p-4">
+            <div className="flex items-baseline justify-between gap-3 mb-2">
+              <div className="flex-1 min-w-0">
+                <span className="font-mono text-red-400 text-sm">{r.exception_class}</span>
+                {r.message && (
+                  <span className="text-gray-300 text-sm ml-2">: {r.message}</span>
+                )}
+              </div>
+              <div className="text-xs text-gray-500 whitespace-nowrap">
+                {r.appmap_name}
+              </div>
+            </div>
+            {r.path && (
+              <div className="text-xs text-gray-500 font-mono mb-2">
+                {r.path}{r.lineno != null ? `:${r.lineno}` : ''}
+              </div>
+            )}
+            {r.recent_logs && r.recent_logs.length > 0 && (
+              <div className="mt-2 border-t border-gray-800 pt-2">
+                <div className="text-xs text-gray-500 mb-1">Recent log lines (preceding throw):</div>
+                <ul className="font-mono text-xs space-y-0.5">
+                  {r.recent_logs.map((l, i) => (
+                    <li key={i} className="text-gray-300">
+                      <span className="text-purple-400 mr-2">[{l.logger}]</span>
+                      {l.message}
+                    </li>
+                  ))}
+                </ul>
+              </div>
+            )}
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}
diff --git a/packages/cli/src/html/query-ui/src/pages/Functions.tsx b/packages/cli/src/html/query-ui/src/pages/Functions.tsx
new file mode 100644
index 0000000000..c8fe38fd3a
--- /dev/null
+++ b/packages/cli/src/html/query-ui/src/pages/Functions.tsx
@@ -0,0 +1,83 @@
+import React, { useEffect, useState } from 'react';
+import { api, FunctionHotspotRow } from '../lib/api';
+import { formatMs, severityColor } from '../lib/format';
+import ExpandableTable from '../components/ExpandableTable';
+import HeatBar from '../components/HeatBar';
+import RequestTracePanel from '../components/RequestTracePanel';
+import type { Column } from '../components/Table';
+
+export default function Functions() {
+  const [rows, setRows] = useState<FunctionHotspotRow[]>([]);
+  const [error, setError] = useState<string | null>(null);
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    let cancelled = false;
+    void (async () => {
+      try {
+        const page = await api.functionHotspots({ limit: 50 });
+        if (!cancelled) setRows(page.rows);
+      } catch (e) {
+        if (!cancelled) setError((e as Error).message);
+      } finally {
+        if (!cancelled) setLoading(false);
+      }
+    })();
+    return () => { cancelled = true; };
+  }, []);
+
+  if (loading) return <div className="text-gray-400">Loading...</div>;
+  if (error) return <div className="text-red-400">Error: {error}</div>;
+
+  const maxTotal = Math.max(...rows.map((r) => r.total_ms ?? 0), 1);
+
+  const columns: Column<FunctionHotspotRow>[] = [
+    {
+      key: 'fn',
+      label: 'Function',
+      render: (r) => (
+        <div className="flex items-center gap-2">
+          <HeatBar value={r.total_ms} max={maxTotal} width="w-24" />
+          <FunctionName r={r} />
+        </div>
+      ),
+    },
+    { key: 'calls', label: 'Calls', className: 'text-right' },
+    { key: 'total_ms', label: 'Total', render: (r) => <span className={severityColor(r.total_ms)}>{formatMs(r.total_ms)}</span>, className: 'text-right' },
+    { key: 'self_ms', label: 'Self', render: (r) => <span className={severityColor(r.self_ms)}>{formatMs(r.self_ms)}</span>, className: 'text-right' },
+  ];
+
+  return (
+    <div>
+      <h1 className="text-2xl font-bold mb-6">Function Hotspots</h1>
+      <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
+        <ExpandableTable
+          columns={columns}
+          rows={rows}
+          rowKey={(r) => r.fqid ?? `${r.defined_class}.${r.method_id}`}
+          isExpandable={(r) => Boolean(r.fqid)}
+          renderExpanded={(r) =>
+            r.fqid ? <RequestTracePanel focusType="function" focusValue={r.fqid} /> : null
+          }
+        />
+      </div>
+    </div>
+  );
+}
+
+function FunctionName({ r }: { r: FunctionHotspotRow }) {
+  const id = r.fqid ?? `${r.defined_class}.${r.method_id}`;
+  const sep = id.lastIndexOf('#') >= 0 ? '#' : '.';
+  const idx = id.lastIndexOf(sep);
+  const prefix = idx >= 0 ? id.slice(0, idx + 1) : '';
+  const method = idx >= 0 ? id.slice(idx + 1) : id;
+  return (
+    <div>
+      <span className="font-mono text-gray-200 text-xs">
+        {prefix}
+        <span className="text-blue-400">{method}</span>
+      </span>
+      {r.path && <div className="text-xs text-gray-500 mt-0.5">{r.path}{r.lineno != null ? `:${r.lineno}` : ''}</div>}
+    </div>
+  );
+}
diff --git a/packages/cli/src/html/query-ui/src/pages/Labels.tsx b/packages/cli/src/html/query-ui/src/pages/Labels.tsx
new file mode 100644
index 0000000000..51caa9f32c
--- /dev/null
+++ b/packages/cli/src/html/query-ui/src/pages/Labels.tsx
@@ -0,0 +1,87 @@
+import React, { useEffect, useState } from 'react';
+import { api, CallRow, LabelRow } from '../lib/api';
+
+export default function Labels() {
+  const [labels, setLabels] = useState<LabelRow[] | null>(null);
+  const [active, setActive] = useState<string | null>(null);
+  const [calls, setCalls] = useState<CallRow[]>([]);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    void api.labels().then(setLabels).catch((e: Error) => setError(e.message));
+  }, []);
+
+  useEffect(() => {
+    if (!active) return;
+    setCalls([]);
+    void api
+      .calls({ label: active, limit: 100 })
+      .then((p) => setCalls(p.rows))
+      .catch(() => setCalls([]));
+  }, [active]);
+
+  if (error) return <div className="text-red-400">Error: {error}</div>;
+  if (!labels) return <div className="text-gray-400">Loading...</div>;
+
+  return (
+    <div>
+      <h1 className="text-2xl font-bold mb-6">Labels</h1>
+
+      <div className="flex flex-wrap gap-2 mb-6">
+        {labels.map((l) => (
+          <button
+            key={l.label}
+            onClick={() => setActive(active === l.label ? null : l.label)}
+            className={`border rounded-full px-3 py-1 text-xs font-mono transition ${
+              active === l.label
+                ? 'border-blue-500 bg-blue-900/40 text-blue-200 ring-2 ring-blue-500'
+                : labelColor(l.label)
+            }`}
+          >
+            {l.label} <span className="text-gray-500 ml-1">{l.count}</span>
+          </button>
+        ))}
+      </div>
+
+      {active && (
+        <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
+          <h2 className="text-sm font-medium text-gray-400 mb-3">
+            Calls labeled <span className="text-blue-400 font-mono">{active}</span>
+          </h2>
+          {calls.length === 0 ? (
+            <div className="text-gray-500 text-sm">No calls.</div>
+          ) : (
+            <ul className="space-y-1 font-mono text-xs">
+              {calls.map((c) => (
+                <li key={`${c.appmap_name}-${c.event_id}`} className="text-gray-300">
+                  <span className="text-blue-400">{c.fqid ?? `${c.defined_class}.${c.method_id}`}</span>
+                  {c.path && (
+                    <span className="text-gray-600 ml-2">
+                      {c.path}{c.lineno != null ? `:${c.lineno}` : ''}
+                    </span>
+                  )}
+                </li>
+              ))}
+            </ul>
+          )}
+        </div>
+      )}
+    </div>
+  );
+}
+
+function labelColor(label: string): string {
+  const prefix = label.split('.')[0];
+  const map: Record<string, string> = {
+    security: 'border-red-700 bg-red-950 text-red-200',
+    log: 'border-purple-700 bg-purple-950 text-purple-200',
+    crypto: 'border-yellow-700 bg-yellow-950 text-yellow-200',
+    dao: 'border-blue-700 bg-blue-950 text-blue-200',
+    job: 'border-green-700 bg-green-950 text-green-200',
+    audit: 'border-orange-700 bg-orange-950 text-orange-200',
+    secret: 'border-red-700 bg-red-950 text-red-200',
+    deserialize: 'border-yellow-700 bg-yellow-950 text-yellow-200',
+    system: 'border-gray-600 bg-gray-900 text-gray-300',
+  };
+  return `${map[prefix] ?? 'border-gray-700 bg-gray-900 text-gray-300'} hover:ring-1 hover:ring-gray-500`;
+}
diff --git a/packages/cli/src/html/query-ui/src/pages/RecordingDetail.tsx b/packages/cli/src/html/query-ui/src/pages/RecordingDetail.tsx
new file mode 100644
index 0000000000..67d112d536
--- /dev/null
+++ b/packages/cli/src/html/query-ui/src/pages/RecordingDetail.tsx
@@ -0,0 +1,227 @@
+import React, { useEffect, useState } from 'react';
+import { Link, useSearchParams } from 'react-router-dom';
+import { api, ExceptionRow, LogRow, RecordingDetail as Detail, RelatedRow } from '../lib/api';
+import { formatMs, formatTime, statusColor, severityColor, encodeAppmap } from '../lib/format';
+import RequestTracePanel from '../components/RequestTracePanel';
+
+type TabKey = 'trace' | 'logs' | 'exceptions' | 'related';
+
+export default function RecordingDetail() {
+  const [params] = useSearchParams();
+  const path = params.get('appmap');
+  const [data, setData] = useState<{ recording: Detail; counts: Record<string, number> } | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const [tab, setTab] = useState<TabKey>('trace');
+
+  useEffect(() => {
+    if (!path) return;
+    let cancelled = false;
+    void api
+      .recording(path)
+      .then((d) => { if (!cancelled) setData(d); })
+      .catch((e: Error) => { if (!cancelled) setError(e.message); });
+    return () => { cancelled = true; };
+  }, [path]);
+
+  if (!path) {
+    return (
+      <div>
+        <Link to="/recordings" className="text-blue-400 hover:underline text-sm">&larr; Recordings</Link>
+        <div className="mt-4 text-gray-400">No recording specified.</div>
+      </div>
+    );
+  }
+  if (error) return <div className="text-red-400">Error: {error}</div>;
+  if (!data) return <div className="text-gray-400">Loading...</div>;
+
+  const { recording: r, counts } = data;
+
+  return (
+    <div className="flex flex-col" style={{ minHeight: 'calc(100vh - 64px)' }}>
+      <div className="flex-none mb-4">
+        <Link to="/recordings" className="text-blue-400 hover:underline text-sm">&larr; Recordings</Link>
+        <h1 className="text-xl font-bold mt-2 mb-2 font-mono">{r.label}</h1>
+        <div className="flex flex-wrap gap-4 text-sm text-gray-400">
+          {r.framework && <span>{r.framework}</span>}
+          {r.language && <span>{r.language}</span>}
+          {r.git_branch && (
+            <span className="bg-gray-800 px-2 py-0.5 rounded font-mono text-xs">{r.git_branch}</span>
+          )}
+          {r.git_commit && (
+            <span className="font-mono text-xs text-gray-500">{r.git_commit.slice(0, 8)}</span>
+          )}
+          <span>{r.event_count} events</span>
+          <span>{counts.sql_queries} SQL</span>
+          <span>{counts.function_calls} fn</span>
+          <span>{counts.exceptions} exc</span>
+          <span className={severityColor(r.elapsed_ms)}>{formatMs(r.elapsed_ms)}</span>
+          <span className="text-gray-500">{formatTime(r.timestamp)}</span>
+        </div>
+        <div className="text-xs text-gray-600 font-mono mt-1 truncate">{r.path}</div>
+      </div>
+
+      <div className="flex-none border-b border-gray-800 mb-4">
+        <Tabs tab={tab} onChange={setTab} />
+      </div>
+
+      <div className="flex-1">
+        {tab === 'trace' && <TraceTab path={path} />}
+        {tab === 'logs' && <LogsTab path={path} />}
+        {tab === 'exceptions' && <ExceptionsTab path={path} />}
+        {tab === 'related' && <RelatedTab path={path} />}
+      </div>
+    </div>
+  );
+}
+
+function Tabs({ tab, onChange }: { tab: TabKey; onChange: (t: TabKey) => void }) {
+  const tabs: { key: TabKey; label: string }[] = [
+    { key: 'trace', label: 'Trace' },
+    { key: 'logs', label: 'Logs' },
+    { key: 'exceptions', label: 'Exceptions' },
+    { key: 'related', label: 'Related' },
+  ];
+  return (
+    <div className="flex gap-2">
+      {tabs.map((t) => (
+        <button
+          key={t.key}
+          onClick={() => onChange(t.key)}
+          className={`px-4 py-2 text-sm border-b-2 -mb-px ${
+            tab === t.key ? 'border-blue-500 text-blue-300' : 'border-transparent text-gray-400 hover:text-gray-200'
+          }`}
+        >
+          {t.label}
+        </button>
+      ))}
+    </div>
+  );
+}
+
+function TraceTab({ path }: { path: string }) {
+  return (
+    <div className="grid grid-cols-1 xl:grid-cols-2 gap-4">
+      <div className="bg-gray-900 border border-gray-800 rounded-lg overflow-hidden" style={{ height: '70vh' }}>
+        <iframe
+          src={`/viewer.html?appmap=${encodeAppmap(path)}`}
+          className="w-full h-full border-0"
+          title="AppMap Viewer"
+        />
+      </div>
+      <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
+        <h2 className="text-sm font-medium text-gray-400 mb-3">Call tree</h2>
+        <RequestTracePanel appmap={path} />
+      </div>
+    </div>
+  );
+}
+
+function LogsTab({ path }: { path: string }) {
+  const [rows, setRows] = useState<LogRow[]>([]);
+  const [loading, setLoading] = useState(true);
+  useEffect(() => {
+    let cancelled = false;
+    void api.logs({ appmap: path, limit: 0 }).then((p) => {
+      if (!cancelled) setRows(p.rows);
+    }).finally(() => { if (!cancelled) setLoading(false); });
+    return () => { cancelled = true; };
+  }, [path]);
+  if (loading) return <div className="text-gray-400">Loading...</div>;
+  if (rows.length === 0) return <div className="text-gray-500">No log calls captured.</div>;
+  return (
+    <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
+      <ul className="space-y-1 font-mono text-xs">
+        {rows.map((r, i) => (
+          <li key={i} className="flex gap-3 border-b border-gray-900 pb-1 last:border-b-0">
+            <span className="text-purple-400 whitespace-nowrap">[{r.logger}]</span>
+            <span className="text-gray-300 flex-1 break-all">{r.message}</span>
+            {r.path && <span className="text-gray-600 whitespace-nowrap">{r.path}{r.lineno != null ? `:${r.lineno}` : ''}</span>}
+          </li>
+        ))}
+      </ul>
+    </div>
+  );
+}
+
+function ExceptionsTab({ path }: { path: string }) {
+  const [rows, setRows] = useState<ExceptionRow[]>([]);
+  const [loading, setLoading] = useState(true);
+  useEffect(() => {
+    let cancelled = false;
+    void api.exceptions({ appmap: path, limit: 0, with_logs: 5 }).then((p) => {
+      if (!cancelled) setRows(p.rows);
+    }).finally(() => { if (!cancelled) setLoading(false); });
+    return () => { cancelled = true; };
+  }, [path]);
+  if (loading) return <div className="text-gray-400">Loading...</div>;
+  if (rows.length === 0) return <div className="text-gray-500">No exceptions in this recording.</div>;
+  return (
+    <div className="space-y-3">
+      {rows.map((r) => (
+        <div key={r.event_id} className="bg-gray-900 border border-gray-800 rounded-lg p-4">
+          <div>
+            <span className="font-mono text-red-400 text-sm">{r.exception_class}</span>
+            {r.message && <span className="text-gray-300 text-sm ml-2">: {r.message}</span>}
+          </div>
+          {r.path && (
+            <div className="text-xs text-gray-500 font-mono mt-1">{r.path}{r.lineno != null ? `:${r.lineno}` : ''}</div>
+          )}
+          {r.recent_logs && r.recent_logs.length > 0 && (
+            <div className="mt-2 border-t border-gray-800 pt-2">
+              <div className="text-xs text-gray-500 mb-1">Preceding log lines:</div>
+              <ul className="font-mono text-xs space-y-0.5">
+                {r.recent_logs.map((l, i) => (
+                  <li key={i} className="text-gray-300">
+                    <span className="text-purple-400 mr-2">[{l.logger}]</span>
+                    {l.message}
+                  </li>
+                ))}
+              </ul>
+            </div>
+          )}
+        </div>
+      ))}
+    </div>
+  );
+}
+
+function RelatedTab({ path }: { path: string }) {
+  const [rows, setRows] = useState<RelatedRow[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+  useEffect(() => {
+    let cancelled = false;
+    void api.related({ appmap: path, limit: 20 }).then((p) => {
+      if (!cancelled) setRows(p.rows);
+    }).catch((e: Error) => {
+      if (!cancelled) setError(e.message);
+    }).finally(() => { if (!cancelled) setLoading(false); });
+    return () => { cancelled = true; };
+  }, [path]);
+  if (loading) return <div className="text-gray-400">Loading...</div>;
+  if (error) return <div className="text-red-400">Error: {error}</div>;
+  if (rows.length === 0) return <div className="text-gray-500">No related recordings.</div>;
+  return (
+    <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
+      <ul className="space-y-2">
+        {rows.map((r, i) => (
+          <li key={i} className="flex items-baseline gap-3 border-b border-gray-900 pb-2 last:border-b-0">
+            <span className="text-blue-400 font-mono text-xs w-12 flex-none">×{r.score}</span>
+            <Link
+              to={`/recordings/detail?appmap=${encodeAppmap(r.source_path)}`}
+              className="font-mono text-xs text-gray-200 hover:text-blue-300 flex-1 truncate"
+            >
+              {r.appmap_name}
+            </Link>
+            {r.status_code != null && (
+              <span className={`font-mono text-xs ${statusColor(r.status_code)}`}>{r.status_code}</span>
+            )}
+            {r.elapsed_ms != null && (
+              <span className={`text-xs ${severityColor(r.elapsed_ms)}`}>{formatMs(r.elapsed_ms)}</span>
+            )}
+          </li>
+        ))}
+      </ul>
+    </div>
+  );
+}
diff --git a/packages/cli/src/html/query-ui/src/pages/Recordings.tsx b/packages/cli/src/html/query-ui/src/pages/Recordings.tsx
new file mode 100644
index 0000000000..3a9cc66c25
--- /dev/null
+++ b/packages/cli/src/html/query-ui/src/pages/Recordings.tsx
@@ -0,0 +1,103 @@
+import React, { useEffect, useState } from 'react';
+import { useNavigate } from 'react-router-dom';
+import { api, RecordingRow } from '../lib/api';
+import { formatMs, formatTime, statusColor, encodeAppmap } from '../lib/format';
+import Table, { Column } from '../components/Table';
+
+export default function Recordings() {
+  const navigate = useNavigate();
+  const [rows, setRows] = useState<RecordingRow[]>([]);
+  const [total, setTotal] = useState(0);
+  const [error, setError] = useState<string | null>(null);
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    let cancelled = false;
+    void (async () => {
+      try {
+        const page = await api.recordings({ limit: 200 });
+        if (!cancelled) {
+          setRows(page.rows);
+          setTotal(page.total);
+        }
+      } catch (e) {
+        if (!cancelled) setError((e as Error).message);
+      } finally {
+        if (!cancelled) setLoading(false);
+      }
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
+  if (loading) return <div className="text-gray-400">Loading...</div>;
+  if (error) return <div className="text-red-400">Error: {error}</div>;
+
+  const columns: Column<RecordingRow>[] = [
+    {
+      key: 'kind',
+      label: 'Kind',
+      render: (r) => (
+        <span className={`px-2 py-0.5 rounded text-xs font-mono ${
+          r.kind === 'junit' ? 'bg-blue-900/40 text-blue-300'
+            : r.kind === 'request' ? 'bg-green-900/40 text-green-300'
+            : 'bg-gray-800 text-gray-400'
+        }`}>{r.kind}</span>
+      ),
+      className: 'w-20',
+    },
+    {
+      key: 'label',
+      label: 'Recording',
+      render: (r) => <span className="text-gray-200 text-xs font-mono">{r.label}</span>,
+    },
+    {
+      key: 'route',
+      label: 'Route',
+      render: (r) => r.route ? (
+        <span className="font-mono text-xs">
+          <span className={r.status_code != null ? statusColor(r.status_code) : 'text-gray-400'}>
+            {r.status_code ?? ''}
+          </span> {r.route}
+        </span>
+      ) : <span className="text-gray-600">-</span>,
+    },
+    {
+      key: 'branch',
+      label: 'Branch',
+      render: (r) => r.branch ? (
+        <span className="bg-gray-800 px-2 py-0.5 rounded text-xs font-mono">{r.branch}</span>
+      ) : <span className="text-gray-600">-</span>,
+    },
+    { key: 'sql_count', label: 'SQL', className: 'text-right' },
+    {
+      key: 'elapsed_ms',
+      label: 'Duration',
+      render: (r) => formatMs(r.elapsed_ms),
+      className: 'text-right',
+    },
+    {
+      key: 'timestamp',
+      label: 'Recorded',
+      render: (r) => <span className="text-gray-500 text-xs">{formatTime(r.timestamp)}</span>,
+    },
+  ];
+
+  return (
+    <div>
+      <div className="flex items-baseline gap-3 mb-6">
+        <h1 className="text-2xl font-bold">Recordings</h1>
+        <span className="text-gray-500 text-sm">{total} total</span>
+      </div>
+      <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
+        <Table
+          columns={columns}
+          rows={rows}
+          rowKey={(r) => r.path}
+          onRowClick={(r) => navigate(`/recordings/detail?appmap=${encodeAppmap(r.path)}`)}
+        />
+      </div>
+    </div>
+  );
+}
diff --git a/packages/cli/src/html/query-ui/src/pages/Search.tsx b/packages/cli/src/html/query-ui/src/pages/Search.tsx
new file mode 100644
index 0000000000..8eeae4d1a8
--- /dev/null
+++ b/packages/cli/src/html/query-ui/src/pages/Search.tsx
@@ -0,0 +1,203 @@
+import React, { useEffect, useRef, useState } from 'react';
+import { api, SearchResult } from '../lib/api';
+import { formatMs, methodBadge, severityColor, statusColor } from '../lib/format';
+import Table, { Column } from '../components/Table';
+
+const EXAMPLES: { label: string; query: string }[] = [
+  { label: 'Errors', query: 'status:5xx' },
+  { label: 'Slow requests', query: 'duration:>1s' },
+  { label: 'Log output', query: 'label:log' },
+  { label: 'Security', query: 'label:security' },
+  { label: 'SQL on table', query: 'table:users' },
+  { label: 'By exception', query: 'exception:NotFound' },
+  { label: 'Last hour', query: 'last:1h' },
+  { label: 'By branch', query: 'branch:main' },
+];
+
+export default function Search() {
+  const [input, setInput] = useState('');
+  const [debounced, setDebounced] = useState('');
+  const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  useEffect(() => {
+    if (timer.current) clearTimeout(timer.current);
+    if (input.length >= 2) {
+      timer.current = setTimeout(() => setDebounced(input), 300);
+    } else {
+      setDebounced('');
+    }
+    return () => { if (timer.current) clearTimeout(timer.current); };
+  }, [input]);
+
+  return (
+    <div>
+      <h1 className="text-2xl font-bold mb-4">Search</h1>
+      <div className="relative">
+        <input
+          type="text"
+          value={input}
+          onChange={(e) => setInput(e.target.value)}
+          placeholder="Search... or use filters: status:500 label:log duration:>1s last:1h"
+          className="w-full bg-gray-900 border border-gray-700 rounded-lg px-4 py-3 pr-20 text-gray-100 placeholder-gray-500 focus:outline-none focus:border-blue-500 focus:ring-1 focus:ring-blue-500 font-mono"
+          autoFocus
+        />
+        {input && (
+          <button
+            onClick={() => setInput('')}
+            className="absolute right-2 top-1/2 -translate-y-1/2 bg-gray-700 hover:bg-gray-600 text-gray-300 px-3 py-1 rounded text-xs"
+          >
+            Clear
+          </button>
+        )}
+      </div>
+
+      {!debounced && (
+        <div className="mt-3 flex flex-wrap gap-2">
+          {EXAMPLES.map(({ label, query }) => (
+            <button
+              key={query}
+              onClick={() => setInput(query)}
+              className="bg-gray-800 hover:bg-gray-700 text-gray-300 px-3 py-1 rounded-full text-xs"
+            >
+              {label} <span className="text-gray-500 ml-1">{query}</span>
+            </button>
+          ))}
+        </div>
+      )}
+
+      {input.length > 0 && input.length < 2 && (
+        <div className="text-gray-500 text-sm mt-2">Type at least 2 characters.</div>
+      )}
+
+      {debounced && <SearchResults query={debounced} />}
+    </div>
+  );
+}
+
+function SearchResults({ query }: { query: string }) {
+  const [data, setData] = useState<SearchResult | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    let cancelled = false;
+    setLoading(true);
+    setError(null);
+    void api
+      .search(query, 50)
+      .then((r) => {
+        if (!cancelled) {
+          setData(r);
+          setLoading(false);
+        }
+      })
+      .catch((e: Error) => {
+        if (!cancelled) {
+          setError(e.message);
+          setLoading(false);
+        }
+      });
+    return () => { cancelled = true; };
+  }, [query]);
+
+  if (loading) return <div className="text-gray-400 mt-4">Searching...</div>;
+  if (error) return <div className="text-red-400 mt-4">Error: {error}</div>;
+  if (!data) return null;
+
+  const filterEntries = Object.entries(data.filters).filter(([, v]) => v != null && v !== '');
+  const total =
+    (data.requests?.rows.length ?? 0) +
+    (data.queries?.rows.length ?? 0) +
+    (data.calls?.rows.length ?? 0) +
+    (data.exceptions?.rows.length ?? 0) +
+    (data.recordings?.rows.length ?? 0);
+
+  if (total === 0) return <div className="text-gray-500 mt-6">No results.</div>;
+
+  return (
+    <div className="mt-6 space-y-6">
+      {filterEntries.length > 0 && (
+        <div className="flex flex-wrap gap-2">
+          {filterEntries.map(([k, v]) => (
+            <span key={k} className="bg-blue-900/40 text-blue-300 px-2 py-1 rounded text-xs font-mono">
+              {k}: {v}
+            </span>
+          ))}
+        </div>
+      )}
+
+      {data.recordings && data.recordings.rows.length > 0 && (
+        <Section title={`Recordings (${data.recordings.total})`}>
+          <Table
+            columns={[
+              { key: 'label', label: 'Recording', render: (r: { label: string }) => <span className="text-gray-200 font-mono text-xs">{r.label}</span> },
+              { key: 'route', label: 'Route', render: (r: { route?: string | null }) => <span className="font-mono text-xs">{r.route ?? '-'}</span> },
+              { key: 'kind', label: 'Kind' },
+            ]}
+            rows={data.recordings.rows as Record<string, unknown>[]}
+            rowKey={(r) => String(r.path)}
+          />
+        </Section>
+      )}
+
+      {data.requests && data.requests.rows.length > 0 && (
+        <Section title={`Requests (${data.requests.total})`}>
+          <Table
+            columns={[
+              { key: 'method', label: 'Method', render: (r: { method: string }) => <span className={`font-mono px-2 py-0.5 rounded text-xs ${methodBadge(r.method)}`}>{r.method}</span> },
+              { key: 'route', label: 'Route', render: (r: { route: string }) => <span className="font-mono text-xs">{r.route}</span> },
+              { key: 'status_code', label: 'Status', render: (r: { status_code: number }) => <span className={`font-mono ${statusColor(r.status_code)}`}>{r.status_code}</span> },
+              { key: 'elapsed_ms', label: 'Time', render: (r: { elapsed_ms: number | null }) => <span className={severityColor(r.elapsed_ms)}>{formatMs(r.elapsed_ms)}</span>, className: 'text-right' },
+            ]}
+            rows={data.requests.rows as Record<string, unknown>[]}
+          />
+        </Section>
+      )}
+
+      {data.queries && data.queries.rows.length > 0 && (
+        <Section title={`SQL (${data.queries.total})`}>
+          <Table
+            columns={[
+              { key: 'sql_text', label: 'Query', render: (r: { sql_text: string }) => <span className="font-mono text-xs text-gray-300">{r.sql_text.slice(0, 120)}</span> },
+              { key: 'elapsed_ms', label: 'Time', render: (r: { elapsed_ms: number | null }) => <span className={severityColor(r.elapsed_ms)}>{formatMs(r.elapsed_ms)}</span>, className: 'text-right' },
+            ]}
+            rows={data.queries.rows as Record<string, unknown>[]}
+          />
+        </Section>
+      )}
+
+      {data.calls && data.calls.rows.length > 0 && (
+        <Section title={`Functions (${data.calls.total})`}>
+          <Table
+            columns={[
+              { key: 'fn', label: 'Function', render: (r: { fqid: string | null; defined_class: string; method_id: string }) => <span className="font-mono text-xs">{r.fqid ?? `${r.defined_class}.${r.method_id}`}</span> },
+              { key: 'elapsed_ms', label: 'Time', render: (r: { elapsed_ms: number | null }) => <span className={severityColor(r.elapsed_ms)}>{formatMs(r.elapsed_ms)}</span>, className: 'text-right' },
+            ] as Column<Record<string, unknown>>[]}
+            rows={data.calls.rows as Record<string, unknown>[]}
+          />
+        </Section>
+      )}
+
+      {data.exceptions && data.exceptions.rows.length > 0 && (
+        <Section title={`Exceptions (${data.exceptions.total})`}>
+          <Table
+            columns={[
+              { key: 'exception_class', label: 'Exception', render: (r: { exception_class: string }) => <span className="font-mono text-red-300 text-xs">{r.exception_class}</span> },
+              { key: 'message', label: 'Message', render: (r: { message: string | null }) => <span className="text-gray-400 text-xs">{r.message ?? '-'}</span> },
+            ]}
+            rows={data.exceptions.rows as Record<string, unknown>[]}
+          />
+        </Section>
+      )}
+    </div>
+  );
+}
+
+function Section({ title, children }: { title: string; children: React.ReactNode }) {
+  return (
+    <div>
+      <h2 className="text-lg font-bold mb-3">{title}</h2>
+      <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">{children}</div>
+    </div>
+  );
+}
diff --git a/packages/cli/src/html/query-ui/src/pages/Sql.tsx b/packages/cli/src/html/query-ui/src/pages/Sql.tsx
new file mode 100644
index 0000000000..c572eb17ed
--- /dev/null
+++ b/packages/cli/src/html/query-ui/src/pages/Sql.tsx
@@ -0,0 +1,63 @@
+import React, { useEffect, useState } from 'react';
+import { api, SqlHotspotRow } from '../lib/api';
+import { formatMs, severityColor } from '../lib/format';
+import ExpandableTable from '../components/ExpandableTable';
+import HeatBar from '../components/HeatBar';
+import RequestTracePanel from '../components/RequestTracePanel';
+import type { Column } from '../components/Table';
+
+export default function Sql() {
+  const [rows, setRows] = useState<SqlHotspotRow[]>([]);
+  const [error, setError] = useState<string | null>(null);
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    let cancelled = false;
+    void (async () => {
+      try {
+        const page = await api.sqlHotspots({ limit: 100 });
+        if (!cancelled) setRows(page.rows);
+      } catch (e) {
+        if (!cancelled) setError((e as Error).message);
+      } finally {
+        if (!cancelled) setLoading(false);
+      }
+    })();
+    return () => { cancelled = true; };
+  }, []);
+
+  if (loading) return <div className="text-gray-400">Loading...</div>;
+  if (error) return <div className="text-red-400">Error: {error}</div>;
+
+  const maxTotal = Math.max(...rows.map((r) => r.total_ms ?? 0), 1);
+
+  const columns: Column<SqlHotspotRow>[] = [
+    { key: 'heat', label: '', render: (r) => <HeatBar value={r.total_ms} max={maxTotal} width="w-20" />, className: 'w-20' },
+    {
+      key: 'sql_text',
+      label: 'Query',
+      render: (r) => (
+        <span className="font-mono text-xs text-gray-300" title={r.sql_text}>
+          {r.sql_text.length > 120 ? r.sql_text.slice(0, 120) + '...' : r.sql_text}
+        </span>
+      ),
+    },
+    { key: 'count', label: 'Calls', className: 'text-right' },
+    { key: 'avg_ms', label: 'Avg', render: (r) => <span className={severityColor(r.avg_ms)}>{formatMs(r.avg_ms)}</span>, className: 'text-right' },
+    { key: 'total_ms', label: 'Total', render: (r) => <span className={severityColor(r.total_ms)}>{formatMs(r.total_ms)}</span>, className: 'text-right' },
+  ];
+
+  return (
+    <div>
+      <h1 className="text-2xl font-bold mb-6">SQL Hotspots</h1>
+      <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
+        <ExpandableTable
+          columns={columns}
+          rows={rows}
+          rowKey={(r) => r.sql_text}
+          renderExpanded={(r) => <RequestTracePanel focusType="sql_query" focusValue={r.sql_text} />}
+        />
+      </div>
+    </div>
+  );
+}
diff --git a/packages/cli/src/html/query-ui/src/viewer.ts b/packages/cli/src/html/query-ui/src/viewer.ts
new file mode 100644
index 0000000000..b38e504f37
--- /dev/null
+++ b/packages/cli/src/html/query-ui/src/viewer.ts
@@ -0,0 +1,69 @@
+// Standalone AppMap viewer page.
+//
+// Loaded via /viewer.html?appmap=<path>. Fetches the raw .appmap.json
+// from the gated /file?appmap=<path> endpoint, then mounts the
+// @appland/components VVsCodeExtension Vue component to render the
+// interactive diagram. Adapted from appmap-apm/src/viewer/main.ts —
+// only the URL/API contract differs (path-based id; appmap-js gating).
+
+import Vue from 'vue';
+// @ts-ignore — no types for the Vue 2 component
+import { VVsCodeExtension } from '@appland/components';
+import '@appland/diagrams/dist/style.css';
+
+const params = new URLSearchParams(window.location.search);
+const appmapPath = params.get('appmap');
+
+const loadingEl = document.getElementById('loading') as HTMLElement;
+const errorEl = document.getElementById('error') as HTMLElement;
+const viewerEl = document.getElementById('viewer') as HTMLElement;
+
+function showError(msg: string): void {
+  loadingEl.style.display = 'none';
+  errorEl.style.display = 'block';
+  errorEl.textContent = msg;
+}
+
+async function init(): Promise<void> {
+  if (!appmapPath) {
+    showError('No AppMap path provided. Use ?appmap=<path>');
+    return;
+  }
+
+  try {
+    const res = await fetch(`/file?appmap=${encodeURIComponent(appmapPath)}`);
+    if (!res.ok) {
+      showError(`Failed to load AppMap: ${res.status} ${res.statusText}`);
+      return;
+    }
+    const data: unknown = await res.json();
+
+    loadingEl.style.display = 'none';
+
+    new Vue({
+      el: viewerEl,
+      render: (h) =>
+        h(VVsCodeExtension, {
+          ref: 'viewer',
+          props: {
+            defaultView: 'viewSequence',
+            allowFullscreen: true,
+            allowExport: false,
+          },
+        }),
+      async mounted() {
+        // Wait for the component ref to be available
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        while (!(this as any).$refs.viewer) {
+          await Vue.nextTick();
+        }
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        (this as any).$refs.viewer.loadData(data);
+      },
+    });
+  } catch (e) {
+    showError(`Error: ${(e as Error).message}`);
+  }
+}
+
+void init();
diff --git a/packages/cli/src/html/query-ui/tailwind.config.js b/packages/cli/src/html/query-ui/tailwind.config.js
new file mode 100644
index 0000000000..b88faf3d05
--- /dev/null
+++ b/packages/cli/src/html/query-ui/tailwind.config.js
@@ -0,0 +1,6 @@
+/** @type {import('tailwindcss').Config} */
+module.exports = {
+  content: ['./index.html', './src/**/*.{ts,tsx}'],
+  theme: { extend: {} },
+  plugins: [],
+};
diff --git a/packages/cli/src/html/query-ui/viewer.html b/packages/cli/src/html/query-ui/viewer.html
new file mode 100644
index 0000000000..afd2192046
--- /dev/null
+++ b/packages/cli/src/html/query-ui/viewer.html
@@ -0,0 +1,20 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>AppMap Viewer</title>
+    <style>
+      * { margin: 0; padding: 0; box-sizing: border-box; }
+      html, body, #viewer { width: 100%; height: 100%; overflow: hidden; }
+      body { background: #0a0a0f; color: #e5e7eb; font-family: system-ui, sans-serif; }
+      #loading { display: flex; align-items: center; justify-content: center; height: 100%; color: #6b7280; }
+      #error { display: none; padding: 2rem; color: #ef4444; }
+    </style>
+  </head>
+  <body>
+    <div id="loading">Loading AppMap...</div>
+    <div id="error"></div>
+    <div id="viewer"></div>
+  </body>
+</html>
diff --git a/packages/cli/tests/unit/cmds/query/db/import/QueryDbIndexer.spec.ts b/packages/cli/tests/unit/cmds/query/db/import/QueryDbIndexer.spec.ts
new file mode 100644
index 0000000000..6c381fe098
--- /dev/null
+++ b/packages/cli/tests/unit/cmds/query/db/import/QueryDbIndexer.spec.ts
@@ -0,0 +1,104 @@
+import { EventEmitter } from 'events';
+import { mkdtempSync, rmSync, writeFileSync } from 'fs';
+import { tmpdir } from 'os';
+import { join, resolve } from 'path';
+
+import { QueryDbIndexer } from '../../../../../../src/cmds/query/db/import/QueryDbIndexer';
+import { freshDb } from './helpers';
+
+function writeAppmap(dir: string, name: string, body: object): string {
+  const p = join(dir, name);
+  writeFileSync(p, JSON.stringify(body));
+  return p;
+}
+
+function minimalAppmap(): object {
+  return {
+    metadata: { timestamp: 1700000000 },
+    events: [
+      { id: 1, event: 'call', http_server_request: { request_method: 'GET', path_info: '/x' } },
+      { id: 2, event: 'return', parent_id: 1, http_server_response: { status_code: 200 } },
+    ],
+  };
+}
+
+describe('QueryDbIndexer', () => {
+  let tmp: string;
+
+  beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), 'qdb-indexer-'));
+  });
+
+  afterEach(() => {
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it('attach() routes index events into importAppmap', () => {
+    const db = freshDb();
+    const indexer = new QueryDbIndexer(db);
+    try {
+      const queue = new EventEmitter();
+      indexer.attach(queue as any);
+      const path = writeAppmap(tmp, 'a.appmap.json', minimalAppmap());
+      queue.emit('index', { path });
+      expect((db.prepare('SELECT COUNT(*) AS n FROM appmaps').get() as any).n).toBe(1);
+      expect(indexer.stats()).toEqual({ imported: 1, failed: 0 });
+    } finally {
+      // not closing db here — the indexer owns close
+      indexer.close();
+    }
+  });
+
+  it('logs and counts failures without throwing on per-file errors', () => {
+    const db = freshDb();
+    const indexer = new QueryDbIndexer(db);
+    const warn = jest.spyOn(console, 'warn').mockImplementation(() => undefined);
+    try {
+      const path = join(tmp, 'broken.appmap.json');
+      writeFileSync(path, '{not json');
+      indexer.onIndexed(path);
+      expect(indexer.stats()).toEqual({ imported: 0, failed: 1 });
+      expect(warn).toHaveBeenCalledWith(expect.stringContaining('failed to import'));
+    } finally {
+      indexer.close();
+      warn.mockRestore();
+    }
+  });
+
+  it('syncDirectory imports only files not yet in the DB', async () => {
+    const db = freshDb();
+    const indexer = new QueryDbIndexer(db);
+    try {
+      const a = writeAppmap(tmp, 'a.appmap.json', minimalAppmap());
+      const b = writeAppmap(tmp, 'b.appmap.json', minimalAppmap());
+      indexer.onIndexed(a); // pre-import a
+      const beforeFailed = indexer.stats().failed;
+      const beforeImported = indexer.stats().imported;
+      await indexer.syncDirectory(tmp);
+      // a was already in DB (skip); b was new (imported).
+      expect(indexer.stats().imported).toBe(beforeImported + 1);
+      expect(indexer.stats().failed).toBe(beforeFailed);
+      const rows = db
+        .prepare('SELECT source_path FROM appmaps ORDER BY source_path')
+        .all()
+        .map((r: any) => r.source_path);
+      expect(rows).toEqual([resolve(a), resolve(b)].sort());
+    } finally {
+      indexer.close();
+    }
+  });
+
+  it('onRemoved deletes by source_path', () => {
+    const db = freshDb();
+    const indexer = new QueryDbIndexer(db);
+    try {
+      const path = writeAppmap(tmp, 'a.appmap.json', minimalAppmap());
+      indexer.onIndexed(path);
+      expect((db.prepare('SELECT COUNT(*) AS n FROM appmaps').get() as any).n).toBe(1);
+      indexer.onRemoved(path);
+      expect((db.prepare('SELECT COUNT(*) AS n FROM appmaps').get() as any).n).toBe(0);
+    } finally {
+      indexer.close();
+    }
+  });
+});
diff --git a/packages/cli/tests/unit/cmds/query/db/import/appmapRecord.spec.ts b/packages/cli/tests/unit/cmds/query/db/import/appmapRecord.spec.ts
new file mode 100644
index 0000000000..d160ac163c
--- /dev/null
+++ b/packages/cli/tests/unit/cmds/query/db/import/appmapRecord.spec.ts
@@ -0,0 +1,106 @@
+import { mkdtempSync, rmSync, writeFileSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+
+import { insertAppmapRecord } from '../../../../../../src/cmds/query/db/import/appmapRecord';
+import { freshDb } from './helpers';
+
+describe('insertAppmapRecord', () => {
+  let tmp: string;
+
+  beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), 'appmap-record-'));
+  });
+
+  afterEach(() => {
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it('inserts a row with derived metadata, counts, and elapsed', () => {
+    const db = freshDb();
+    try {
+      const path = join(tmp, 'test.appmap.json');
+      writeFileSync(path, '{}');
+
+      const result = insertAppmapRecord(db, path, {
+        events: [
+          { id: 1, event: 'call', http_server_request: { request_method: 'GET' } },
+          { id: 2, event: 'return', parent_id: 1, http_server_response: { status_code: 200 }, elapsed: 0.42 },
+          { id: 3, event: 'call', sql_query: { sql: 'SELECT 1' } },
+          { id: 4, event: 'return', parent_id: 3 },
+        ],
+        metadata: {
+          name: 'demo',
+          language: { name: 'ruby' },
+          frameworks: [{ name: 'rails' }],
+          recorder: { type: 'rspec' },
+          git: { repository: 'r', branch: 'main', commit: 'abc' },
+          timestamp: 1700000000,
+          labels: ['lab1', 'lab2'],
+        },
+      });
+
+      expect(result.appmapId).toBe(1);
+      expect(result.timestampIso).toBe(new Date(1700000000 * 1000).toISOString());
+
+      const row = db.prepare('SELECT * FROM appmaps WHERE id = ?').get(result.appmapId) as any;
+      expect(row.name).toBe('demo');
+      expect(row.source_path).toBe(path);
+      expect(row.language).toBe('ruby');
+      expect(row.framework).toBe('rails');
+      expect(row.recorder_type).toBe('rspec');
+      expect(row.git_repository).toBe('r');
+      expect(row.git_branch).toBe('main');
+      expect(row.git_commit).toBe('abc');
+      expect(row.event_count).toBe(4);
+      expect(row.sql_query_count).toBe(1);
+      expect(row.http_request_count).toBe(1);
+      expect(row.elapsed_ms).toBeCloseTo(420);
+      expect(JSON.parse(row.metadata_labels)).toEqual(['lab1', 'lab2']);
+    } finally {
+      db.close();
+    }
+  });
+
+  it('falls back to file mtime when metadata has no timestamp', () => {
+    const db = freshDb();
+    try {
+      const path = join(tmp, 'no-ts.appmap.json');
+      writeFileSync(path, '{}');
+      const result = insertAppmapRecord(db, path, { events: [], metadata: {} });
+      // Just assert it parses as a valid date.
+      expect(Number.isNaN(Date.parse(result.timestampIso))).toBe(false);
+    } finally {
+      db.close();
+    }
+  });
+
+  it('uses the file basename as the name when metadata.name is missing', () => {
+    const db = freshDb();
+    try {
+      const path = join(tmp, 'unnamed.appmap.json');
+      writeFileSync(path, '{}');
+      insertAppmapRecord(db, path, { events: [], metadata: {} });
+      const row = db.prepare('SELECT name FROM appmaps').get() as any;
+      expect(row.name).toBe('unnamed.appmap.json');
+    } finally {
+      db.close();
+    }
+  });
+
+  it('leaves elapsed_ms null when there is no http_server_response return', () => {
+    const db = freshDb();
+    try {
+      const path = join(tmp, 'no-http.appmap.json');
+      writeFileSync(path, '{}');
+      insertAppmapRecord(db, path, {
+        events: [{ id: 1, event: 'call' }],
+        metadata: { timestamp: 1700000000 },
+      });
+      const row = db.prepare('SELECT elapsed_ms FROM appmaps').get() as any;
+      expect(row.elapsed_ms).toBeNull();
+    } finally {
+      db.close();
+    }
+  });
+});
diff --git a/packages/cli/tests/unit/cmds/query/db/import/codeObjects.spec.ts b/packages/cli/tests/unit/cmds/query/db/import/codeObjects.spec.ts
new file mode 100644
index 0000000000..8845f61423
--- /dev/null
+++ b/packages/cli/tests/unit/cmds/query/db/import/codeObjects.spec.ts
@@ -0,0 +1,361 @@
+import sqlite3 from 'better-sqlite3';
+
+import { openQueryDb } from '../../../../../../src/cmds/query/db/openQueryDb';
+import {
+  ClassMapNode,
+  importCodeObjects,
+} from '../../../../../../src/cmds/query/db/import/codeObjects';
+
+function freshDb(): sqlite3.Database {
+  return openQueryDb('/tmp/ignored', ':memory:').db;
+}
+
+describe('importCodeObjects', () => {
+  it('returns an empty map and writes nothing for an empty classMap', () => {
+    const db = freshDb();
+    try {
+      const lookup = importCodeObjects(db, []);
+      expect(lookup.size).toBe(0);
+      expect((db.prepare('SELECT COUNT(*) AS n FROM code_objects').get() as any).n).toBe(0);
+    } finally {
+      db.close();
+    }
+  });
+
+  it('inserts a single instance method with the canonical fqid', () => {
+    const db = freshDb();
+    try {
+      const tree: ClassMapNode[] = [
+        {
+          type: 'package',
+          name: 'app',
+          children: [
+            {
+              type: 'class',
+              name: 'User',
+              children: [
+                {
+                  type: 'function',
+                  name: 'save',
+                  static: false,
+                  location: 'app/models/user.rb:10',
+                },
+              ],
+            },
+          ],
+        },
+      ];
+      const lookup = importCodeObjects(db, tree);
+
+      const row = db
+        .prepare('SELECT fqid, package, classes, leaf_class, method, is_static FROM code_objects')
+        .get() as any;
+      expect(row.fqid).toBe('app/User#save');
+      expect(row.package).toBe('app');
+      expect(JSON.parse(row.classes)).toEqual(['User']);
+      expect(row.leaf_class).toBe('User');
+      expect(row.method).toBe('save');
+      expect(row.is_static).toBe(0);
+      expect(lookup.get('app/models/user.rb:10|save')).toBe(1);
+    } finally {
+      db.close();
+    }
+  });
+
+  it('uses "." for static methods', () => {
+    const db = freshDb();
+    try {
+      const tree: ClassMapNode[] = [
+        {
+          type: 'package',
+          name: 'core',
+          children: [
+            {
+              type: 'class',
+              name: 'Date',
+              children: [
+                {
+                  type: 'function',
+                  name: 'parse',
+                  static: true,
+                  location: 'core/date.rb:1',
+                },
+              ],
+            },
+          ],
+        },
+      ];
+      importCodeObjects(db, tree);
+      const fqid = (db.prepare('SELECT fqid FROM code_objects').get() as any).fqid;
+      expect(fqid).toBe('core/Date.parse');
+    } finally {
+      db.close();
+    }
+  });
+
+  it('strips an auxtype suffix from the method name', () => {
+    const db = freshDb();
+    try {
+      const tree: ClassMapNode[] = [
+        {
+          type: 'package',
+          name: 'app',
+          children: [
+            {
+              type: 'class',
+              name: 'User',
+              children: [
+                {
+                  type: 'function',
+                  name: 'is_authenticated (get)',
+                  location: 'app/models/user.rb:1',
+                },
+              ],
+            },
+          ],
+        },
+      ];
+      importCodeObjects(db, tree);
+      const row = db.prepare('SELECT fqid, method FROM code_objects').get() as any;
+      expect(row.method).toBe('is_authenticated');
+      expect(row.fqid).toBe('app/User#is_authenticated');
+    } finally {
+      db.close();
+    }
+  });
+
+  it('skips function nodes without a location', () => {
+    const db = freshDb();
+    try {
+      const tree: ClassMapNode[] = [
+        {
+          type: 'package',
+          name: 'lib',
+          children: [
+            {
+              type: 'class',
+              name: 'Cipher',
+              children: [{ type: 'function', name: 'decrypt' /* no location */ }],
+            },
+          ],
+        },
+      ];
+      const lookup = importCodeObjects(db, tree);
+      expect(lookup.size).toBe(0);
+      expect((db.prepare('SELECT COUNT(*) AS n FROM code_objects').get() as any).n).toBe(0);
+    } finally {
+      db.close();
+    }
+  });
+
+  it('inserts labels for the function and dedups them', () => {
+    const db = freshDb();
+    try {
+      const tree: ClassMapNode[] = [
+        {
+          type: 'package',
+          name: 'app',
+          children: [
+            {
+              type: 'class',
+              name: 'Logger',
+              children: [
+                {
+                  type: 'function',
+                  name: 'error',
+                  location: 'app/lib/logger.rb:5',
+                  labels: ['log', 'log'], // duplicate in source
+                },
+              ],
+            },
+          ],
+        },
+      ];
+      importCodeObjects(db, tree);
+      const labels = db
+        .prepare('SELECT label FROM labels ORDER BY label')
+        .all()
+        .map((r: any) => r.label);
+      expect(labels).toEqual(['log']);
+    } finally {
+      db.close();
+    }
+  });
+
+  it('builds nested-package fqids correctly', () => {
+    const db = freshDb();
+    try {
+      const tree: ClassMapNode[] = [
+        {
+          type: 'package',
+          name: 'app',
+          children: [
+            {
+              type: 'package',
+              name: 'controllers',
+              children: [
+                {
+                  type: 'package',
+                  name: 'orders',
+                  children: [
+                    {
+                      type: 'class',
+                      name: 'OrdersController',
+                      children: [
+                        {
+                          type: 'function',
+                          name: 'create',
+                          location: 'app/controllers/orders/orders_controller.rb:42',
+                        },
+                      ],
+                    },
+                  ],
+                },
+              ],
+            },
+          ],
+        },
+      ];
+      importCodeObjects(db, tree);
+      const fqid = (db.prepare('SELECT fqid FROM code_objects').get() as any).fqid;
+      expect(fqid).toBe('app/controllers/orders/OrdersController#create');
+    } finally {
+      db.close();
+    }
+  });
+
+  it('uses :: between nested class names (matches @appland/models codeObjectId)', () => {
+    const db = freshDb();
+    try {
+      const tree: ClassMapNode[] = [
+        {
+          type: 'package',
+          name: 'app',
+          children: [
+            {
+              type: 'class',
+              name: 'Outer',
+              children: [
+                {
+                  type: 'class',
+                  name: 'Inner',
+                  children: [
+                    { type: 'function', name: 'foo', location: 'app/outer.rb:1' },
+                  ],
+                },
+              ],
+            },
+          ],
+        },
+      ];
+      importCodeObjects(db, tree);
+      const fqid = (db.prepare('SELECT fqid FROM code_objects').get() as any).fqid;
+      expect(fqid).toBe('app/Outer::Inner#foo');
+    } finally {
+      db.close();
+    }
+  });
+
+  it('uses :: when a class is the immediate child of another class with a static method', () => {
+    const db = freshDb();
+    try {
+      const tree: ClassMapNode[] = [
+        {
+          type: 'package',
+          name: 'lib',
+          children: [
+            {
+              type: 'class',
+              name: 'Outer',
+              children: [
+                {
+                  type: 'class',
+                  name: 'Inner',
+                  children: [
+                    { type: 'function', name: 'parse', static: true, location: 'lib/x.rb:1' },
+                  ],
+                },
+              ],
+            },
+          ],
+        },
+      ];
+      importCodeObjects(db, tree);
+      const fqid = (db.prepare('SELECT fqid FROM code_objects').get() as any).fqid;
+      expect(fqid).toBe('lib/Outer::Inner.parse');
+    } finally {
+      db.close();
+    }
+  });
+
+  it('disambiguates two functions sharing the same path:lineno by method name', () => {
+    const db = freshDb();
+    try {
+      // Spring Data proxy-style: two distinct methods at the same
+      // synthetic source location.
+      const tree: ClassMapNode[] = [
+        {
+          type: 'package',
+          name: 'org/example',
+          children: [
+            {
+              type: 'class',
+              name: 'OwnerRepository',
+              children: [
+                { type: 'function', name: 'findById', location: 'Proxy.java:0' },
+                { type: 'function', name: 'findPetTypes', location: 'Proxy.java:0' },
+              ],
+            },
+          ],
+        },
+      ];
+      const lookup = importCodeObjects(db, tree);
+
+      // Both code_objects exist...
+      expect(
+        (db.prepare('SELECT COUNT(*) AS n FROM code_objects').get() as any).n
+      ).toBe(2);
+
+      // ...and the lookup keys disambiguate them by method.
+      const findByIdId = lookup.get('Proxy.java:0|findById');
+      const findPetTypesId = lookup.get('Proxy.java:0|findPetTypes');
+      expect(findByIdId).toBeDefined();
+      expect(findPetTypesId).toBeDefined();
+      expect(findByIdId).not.toBe(findPetTypesId);
+    } finally {
+      db.close();
+    }
+  });
+
+  it('is idempotent on re-import (INSERT OR IGNORE)', () => {
+    const db = freshDb();
+    try {
+      const tree: ClassMapNode[] = [
+        {
+          type: 'package',
+          name: 'app',
+          children: [
+            {
+              type: 'class',
+              name: 'User',
+              children: [
+                {
+                  type: 'function',
+                  name: 'save',
+                  location: 'app/models/user.rb:10',
+                  labels: ['dao'],
+                },
+              ],
+            },
+          ],
+        },
+      ];
+      importCodeObjects(db, tree);
+      importCodeObjects(db, tree);
+      expect((db.prepare('SELECT COUNT(*) AS n FROM code_objects').get() as any).n).toBe(1);
+      expect((db.prepare('SELECT COUNT(*) AS n FROM labels').get() as any).n).toBe(1);
+    } finally {
+      db.close();
+    }
+  });
+});
diff --git a/packages/cli/tests/unit/cmds/query/db/import/exceptions.spec.ts b/packages/cli/tests/unit/cmds/query/db/import/exceptions.spec.ts
new file mode 100644
index 0000000000..572119b80e
--- /dev/null
+++ b/packages/cli/tests/unit/cmds/query/db/import/exceptions.spec.ts
@@ -0,0 +1,180 @@
+import { importExceptions } from '../../../../../../src/cmds/query/db/import/exceptions';
+import { buildParentEventMap } from '../../../../../../src/cmds/query/db/import/parentEventMap';
+import { freshDb } from './helpers';
+
+function seedAppmap(db: any): number {
+  const info = db
+    .prepare("INSERT INTO appmaps (name, source_path) VALUES ('rec', '/tmp/rec.appmap.json')")
+    .run();
+  return Number(info.lastInsertRowid);
+}
+
+describe('importExceptions', () => {
+  it('inserts one row per exception entry, preserving class/message/path/lineno', () => {
+    const db = freshDb();
+    try {
+      const appmapId = seedAppmap(db);
+      const events = [
+        { id: 1, event: 'call', thread_id: 7 },
+        {
+          id: 2,
+          event: 'return',
+          parent_id: 1,
+          thread_id: 7,
+          exceptions: [
+            {
+              class: 'IntegrityError',
+              message: 'duplicate key',
+              path: 'app/models/order.rb',
+              lineno: 42,
+            },
+          ],
+        },
+      ];
+      importExceptions(db, appmapId, events, buildParentEventMap(events));
+      const row = db.prepare('SELECT * FROM exceptions').get() as any;
+      expect(row.exception_class).toBe('IntegrityError');
+      expect(row.message).toBe('duplicate key');
+      expect(row.path).toBe('app/models/order.rb');
+      expect(row.lineno).toBe(42);
+      expect(row.thread_id).toBe(7);
+    } finally {
+      db.close();
+    }
+  });
+
+  it('expands multiple exceptions on the same return event into multiple rows', () => {
+    const db = freshDb();
+    try {
+      const appmapId = seedAppmap(db);
+      const events = [
+        { id: 1, event: 'call', thread_id: 1 },
+        {
+          id: 2,
+          event: 'return',
+          parent_id: 1,
+          exceptions: [{ class: 'A' }, { class: 'B' }],
+        },
+      ];
+      importExceptions(db, appmapId, events, buildParentEventMap(events));
+      const rows = db
+        .prepare('SELECT exception_class FROM exceptions ORDER BY id')
+        .all()
+        .map((r: any) => r.exception_class);
+      expect(rows).toEqual(['A', 'B']);
+    } finally {
+      db.close();
+    }
+  });
+
+  it('skips events without an exceptions array', () => {
+    const db = freshDb();
+    try {
+      const appmapId = seedAppmap(db);
+      importExceptions(db, appmapId, [{ id: 1, event: 'call' }], new Map());
+      expect((db.prepare('SELECT COUNT(*) AS n FROM exceptions').get() as any).n).toBe(0);
+    } finally {
+      db.close();
+    }
+  });
+
+  it('uses the call event id (not the return event id) for event_id and derives parent_event_id from the call', () => {
+    const db = freshDb();
+    try {
+      const appmapId = seedAppmap(db);
+      const events = [
+        { id: 10, event: 'call', thread_id: 1 }, // outer
+        { id: 11, event: 'call', thread_id: 1 }, // inner — parent is 10
+        {
+          id: 12,
+          event: 'return',
+          parent_id: 11,
+          thread_id: 1,
+          exceptions: [{ class: 'BoomError' }],
+        },
+      ];
+      importExceptions(db, appmapId, events, buildParentEventMap(events));
+      const row = db.prepare('SELECT event_id, parent_event_id FROM exceptions').get() as any;
+      expect(row.event_id).toBe(11); // call id, not return id
+      expect(row.parent_event_id).toBe(10); // parent of the call
+    } finally {
+      db.close();
+    }
+  });
+
+  it('leaves parent_event_id NULL when the failing call is at the top of its thread', () => {
+    const db = freshDb();
+    try {
+      const appmapId = seedAppmap(db);
+      const events = [
+        { id: 1, event: 'call', thread_id: 1 }, // top-level call
+        {
+          id: 2,
+          event: 'return',
+          parent_id: 1,
+          thread_id: 1,
+          exceptions: [{ class: 'TopLevelError' }],
+        },
+      ];
+      importExceptions(db, appmapId, events, buildParentEventMap(events));
+      const row = db.prepare('SELECT event_id, parent_event_id FROM exceptions').get() as any;
+      expect(row.event_id).toBe(1);
+      expect(row.parent_event_id).toBeNull();
+    } finally {
+      db.close();
+    }
+  });
+
+  it('still imports legacy recordings that place exceptions on the call event', () => {
+    const db = freshDb();
+    try {
+      const appmapId = seedAppmap(db);
+      const events = [
+        { id: 1, event: 'call', thread_id: 1 }, // outer
+        {
+          id: 2,
+          event: 'call',
+          thread_id: 1, // inner — exceptions attached here directly
+          exceptions: [{ class: 'LegacyError' }],
+        },
+        { id: 3, event: 'return', parent_id: 2, thread_id: 1 },
+      ];
+      importExceptions(db, appmapId, events, buildParentEventMap(events));
+      const row = db.prepare('SELECT event_id, parent_event_id FROM exceptions').get() as any;
+      expect(row.event_id).toBe(2);
+      expect(row.parent_event_id).toBe(1);
+    } finally {
+      db.close();
+    }
+  });
+
+  it('de-dups when the same call has exceptions on both call and return events (return wins)', () => {
+    const db = freshDb();
+    try {
+      const appmapId = seedAppmap(db);
+      const events = [
+        {
+          id: 1,
+          event: 'call',
+          thread_id: 1,
+          exceptions: [{ class: 'OnCall' }],
+        },
+        {
+          id: 2,
+          event: 'return',
+          parent_id: 1,
+          thread_id: 1,
+          exceptions: [{ class: 'OnReturn' }],
+        },
+      ];
+      importExceptions(db, appmapId, events, buildParentEventMap(events));
+      const rows = db
+        .prepare('SELECT exception_class FROM exceptions ORDER BY id')
+        .all()
+        .map((r: any) => r.exception_class);
+      expect(rows).toEqual(['OnReturn']);
+    } finally {
+      db.close();
+    }
+  });
+});
diff --git a/packages/cli/tests/unit/cmds/query/db/import/functionCalls.spec.ts b/packages/cli/tests/unit/cmds/query/db/import/functionCalls.spec.ts
new file mode 100644
index 0000000000..fbe19f28ec
--- /dev/null
+++ b/packages/cli/tests/unit/cmds/query/db/import/functionCalls.spec.ts
@@ -0,0 +1,251 @@
+import {
+  importCodeObjects,
+  ClassMapNode,
+} from '../../../../../../src/cmds/query/db/import/codeObjects';
+import { importFunctionCalls } from '../../../../../../src/cmds/query/db/import/functionCalls';
+import { buildReturnEventMap } from '../../../../../../src/cmds/query/db/import/returnEventMap';
+import { buildParentEventMap } from '../../../../../../src/cmds/query/db/import/parentEventMap';
+import { freshDb } from './helpers';
+
+function seedAppmap(db: any): number {
+  const info = db
+    .prepare("INSERT INTO appmaps (name, source_path) VALUES ('rec', '/tmp/rec.appmap.json')")
+    .run();
+  return Number(info.lastInsertRowid);
+}
+
+describe('importFunctionCalls', () => {
+  it('inserts call events, links code_object via path:lineno, and records elapsed', () => {
+    const db = freshDb();
+    try {
+      const appmapId = seedAppmap(db);
+      const classMap: ClassMapNode[] = [
+        {
+          type: 'package',
+          name: 'app',
+          children: [
+            {
+              type: 'class',
+              name: 'User',
+              children: [
+                { type: 'function', name: 'save', location: 'app/models/user.rb:10' },
+              ],
+            },
+          ],
+        },
+      ];
+      const lookup = importCodeObjects(db, classMap);
+      const events = [
+        {
+          id: 1,
+          event: 'call',
+          thread_id: 1,
+          defined_class: 'User',
+          method_id: 'save',
+          path: 'app/models/user.rb',
+          lineno: 10,
+        },
+        { id: 2, event: 'return', parent_id: 1, elapsed: 0.001 },
+      ];
+      importFunctionCalls(
+        db,
+        appmapId,
+        events,
+        buildReturnEventMap(events),
+        buildParentEventMap(events),
+        lookup
+      );
+      const row = db.prepare('SELECT * FROM function_calls').get() as any;
+      expect(row.code_object_id).toBe(1);
+      expect(row.defined_class).toBe('User');
+      expect(row.method_id).toBe('save');
+      expect(row.path).toBe('app/models/user.rb');
+      expect(row.lineno).toBe(10);
+      expect(row.elapsed_ms).toBeCloseTo(1);
+      expect(row.parameters_json).toBeNull();
+      expect(row.return_value).toBeNull();
+    } finally {
+      db.close();
+    }
+  });
+
+  it('captures parameters and return value for a labeled function', () => {
+    const db = freshDb();
+    try {
+      const appmapId = seedAppmap(db);
+      const classMap: ClassMapNode[] = [
+        {
+          type: 'package',
+          name: 'app',
+          children: [
+            {
+              type: 'class',
+              name: 'IdempotencyKey',
+              children: [
+                {
+                  type: 'function',
+                  name: 'generate',
+                  static: true,
+                  location: 'app/services/idempotency.rb:12',
+                  labels: ['security.idempotency'],
+                },
+              ],
+            },
+          ],
+        },
+      ];
+      const lookup = importCodeObjects(db, classMap);
+      const events = [
+        {
+          id: 1,
+          event: 'call',
+          thread_id: 1,
+          defined_class: 'IdempotencyKey',
+          method_id: 'generate',
+          path: 'app/services/idempotency.rb',
+          lineno: 12,
+          static: true,
+          parameters: [{ name: 'request_id', class: 'String', value: "'req-9281'" }],
+        },
+        {
+          id: 2,
+          event: 'return',
+          parent_id: 1,
+          return_value: { class: 'String', value: "'k-9281'" },
+        },
+      ];
+      importFunctionCalls(
+        db,
+        appmapId,
+        events,
+        buildReturnEventMap(events),
+        buildParentEventMap(events),
+        lookup
+      );
+      const row = db.prepare('SELECT * FROM function_calls').get() as any;
+      expect(JSON.parse(row.parameters_json)).toEqual([
+        { name: 'request_id', class: 'String', value: "'req-9281'" },
+      ]);
+      expect(row.return_value).toBe("'k-9281'");
+      expect(row.is_static).toBe(1);
+    } finally {
+      db.close();
+    }
+  });
+
+  it('captures parameters for an unlabeled function (no label gating)', () => {
+    // Regression: parameter capture used to be gated on the code object
+    // carrying a label. A void domain method on an unlabeled class then
+    // had *both* parameters_json and return_value null — fully opaque.
+    const db = freshDb();
+    try {
+      const appmapId = seedAppmap(db);
+      // No classMap → coId stays null → the call is unlabeled.
+      const events = [
+        {
+          id: 1,
+          event: 'call',
+          thread_id: 1,
+          defined_class: 'SyndicationCloseStore',
+          method_id: 'updateStatus',
+          path: 'lending/SyndicationCloseStore.java',
+          lineno: 55,
+          parameters: [
+            { name: 'loanId', class: 'LoanId', value: 'LOAN-4c26df4c' },
+            { name: 'newStatus', class: 'Status', value: 'PREFLIGHT_OK' },
+          ],
+        },
+        // Void method: the return event carries no return_value.
+        { id: 2, event: 'return', parent_id: 1, elapsed: 0.001 },
+      ];
+      importFunctionCalls(
+        db,
+        appmapId,
+        events,
+        buildReturnEventMap(events),
+        buildParentEventMap(events),
+        new Map()
+      );
+      const row = db.prepare('SELECT * FROM function_calls').get() as any;
+      expect(row.code_object_id).toBeNull();
+      expect(JSON.parse(row.parameters_json)).toEqual([
+        { name: 'loanId', class: 'LoanId', value: 'LOAN-4c26df4c' },
+        { name: 'newStatus', class: 'Status', value: 'PREFLIGHT_OK' },
+      ]);
+      expect(row.return_value).toBeNull();
+    } finally {
+      db.close();
+    }
+  });
+
+  it('skips calls that are http_server_request or sql_query carriers', () => {
+    const db = freshDb();
+    try {
+      const appmapId = seedAppmap(db);
+      const events = [
+        {
+          id: 1,
+          event: 'call',
+          defined_class: 'Foo',
+          method_id: 'bar',
+          http_server_request: { request_method: 'GET', path_info: '/x' },
+        },
+        {
+          id: 2,
+          event: 'call',
+          defined_class: 'Foo',
+          method_id: 'bar',
+          sql_query: { sql: 'SELECT 1' },
+        },
+        {
+          id: 3,
+          event: 'call',
+          defined_class: 'Foo',
+          method_id: 'bar',
+        },
+      ];
+      importFunctionCalls(
+        db,
+        appmapId,
+        events,
+        buildReturnEventMap(events),
+        buildParentEventMap(events),
+        new Map()
+      );
+      expect((db.prepare('SELECT COUNT(*) AS n FROM function_calls').get() as any).n).toBe(1);
+      const row = db.prepare('SELECT event_id FROM function_calls').get() as any;
+      expect(row.event_id).toBe(3);
+    } finally {
+      db.close();
+    }
+  });
+
+  it('leaves code_object_id null when path:lineno does not match any classMap location', () => {
+    const db = freshDb();
+    try {
+      const appmapId = seedAppmap(db);
+      const events = [
+        {
+          id: 1,
+          event: 'call',
+          defined_class: 'Foo',
+          method_id: 'bar',
+          path: 'unknown.rb',
+          lineno: 1,
+        },
+      ];
+      importFunctionCalls(
+        db,
+        appmapId,
+        events,
+        buildReturnEventMap(events),
+        buildParentEventMap(events),
+        new Map()
+      );
+      const row = db.prepare('SELECT code_object_id FROM function_calls').get() as any;
+      expect(row.code_object_id).toBeNull();
+    } finally {
+      db.close();
+    }
+  });
+});
diff --git a/packages/cli/tests/unit/cmds/query/db/import/helpers.ts b/packages/cli/tests/unit/cmds/query/db/import/helpers.ts
new file mode 100644
index 0000000000..3617e9ae96
--- /dev/null
+++ b/packages/cli/tests/unit/cmds/query/db/import/helpers.ts
@@ -0,0 +1,8 @@
+import sqlite3 from 'better-sqlite3';
+
+import { openQueryDb } from '../../../../../../src/cmds/query/db/openQueryDb';
+
+// Open an in-memory query DB with the schema applied.
+export function freshDb(): sqlite3.Database {
+  return openQueryDb('/tmp/ignored', ':memory:').db;
+}
diff --git a/packages/cli/tests/unit/cmds/query/db/import/httpClientRequests.spec.ts b/packages/cli/tests/unit/cmds/query/db/import/httpClientRequests.spec.ts
new file mode 100644
index 0000000000..d2b05faaee
--- /dev/null
+++ b/packages/cli/tests/unit/cmds/query/db/import/httpClientRequests.spec.ts
@@ -0,0 +1,72 @@
+import { importHttpClientRequests } from '../../../../../../src/cmds/query/db/import/httpClientRequests';
+import { buildReturnEventMap } from '../../../../../../src/cmds/query/db/import/returnEventMap';
+import { buildParentEventMap } from '../../../../../../src/cmds/query/db/import/parentEventMap';
+import { freshDb } from './helpers';
+
+function seedAppmap(db: any): number {
+  const info = db
+    .prepare("INSERT INTO appmaps (name, source_path) VALUES ('rec', '/tmp/rec.appmap.json')")
+    .run();
+  return Number(info.lastInsertRowid);
+}
+
+describe('importHttpClientRequests', () => {
+  it('inserts one row per http_client_request', () => {
+    const db = freshDb();
+    try {
+      const appmapId = seedAppmap(db);
+      const events = [
+        {
+          id: 1,
+          event: 'call',
+          thread_id: 12,
+          http_client_request: { request_method: 'GET', url: 'https://api.example/v1' },
+        },
+        {
+          id: 2,
+          event: 'return',
+          parent_id: 1,
+          http_client_response: { status_code: 503 },
+          elapsed: 0.04,
+        },
+      ];
+      importHttpClientRequests(
+        db,
+        appmapId,
+        events,
+        buildReturnEventMap(events),
+        buildParentEventMap(events)
+      );
+      const row = db.prepare('SELECT * FROM http_client_requests').get() as any;
+      expect(row.method).toBe('GET');
+      expect(row.url).toBe('https://api.example/v1');
+      expect(row.status_code).toBe(503);
+      expect(row.elapsed_ms).toBeCloseTo(40);
+      expect(row.thread_id).toBe(12);
+    } finally {
+      db.close();
+    }
+  });
+
+  it('defaults missing method to GET and missing url to ""', () => {
+    const db = freshDb();
+    try {
+      const appmapId = seedAppmap(db);
+      const events = [
+        { id: 1, event: 'call', http_client_request: {} },
+      ];
+      importHttpClientRequests(
+        db,
+        appmapId,
+        events,
+        buildReturnEventMap(events),
+        buildParentEventMap(events)
+      );
+      const row = db.prepare('SELECT method, url FROM http_client_requests').get() as any;
+      expect(row.method).toBe('GET');
+      expect(row.url).toBe('');
+    } finally {
+      db.close();
+    }
+  });
+});
diff --git a/packages/cli/tests/unit/cmds/query/db/import/httpRequests.spec.ts b/packages/cli/tests/unit/cmds/query/db/import/httpRequests.spec.ts
new file mode 100644
index 0000000000..570c686582
--- /dev/null
+++ b/packages/cli/tests/unit/cmds/query/db/import/httpRequests.spec.ts
@@ -0,0 +1,97 @@
+import { importHttpRequests } from '../../../../../../src/cmds/query/db/import/httpRequests';
+import { buildReturnEventMap } from '../../../../../../src/cmds/query/db/import/returnEventMap';
+import { buildParentEventMap } from '../../../../../../src/cmds/query/db/import/parentEventMap';
+import { freshDb } from './helpers';
+
+function seedAppmap(db: any): number {
+  const info = db
+    .prepare("INSERT INTO appmaps (name, source_path) VALUES ('rec', '/tmp/rec.appmap.json')")
+    .run();
+  return Number(info.lastInsertRowid);
+}
+
+describe('importHttpRequests', () => {
+  it('inserts one row per http_server_request, joining the matching return for status + elapsed', () => {
+    const db = freshDb();
+    try {
+      const appmapId = seedAppmap(db);
+      const events = [
+        {
+          id: 1,
+          event: 'call',
+          thread_id: 99,
+          http_server_request: {
+            request_method: 'POST',
+            path_info: '/orders',
+            normalized_path_info: '/orders',
+            protocol: 'HTTP/1.1',
+          },
+        },
+        {
+          id: 2,
+          event: 'call',
+          thread_id: 99,
+        },
+        {
+          id: 3,
+          event: 'return',
+          parent_id: 2,
+        },
+        {
+          id: 4,
+          event: 'return',
+          parent_id: 1,
+          http_server_response: { status_code: 500, mime_type: 'application/json' },
+          elapsed: 0.52,
+        },
+      ];
+
+      importHttpRequests(
+        db,
+        appmapId,
+        events,
+        buildReturnEventMap(events),
+        buildParentEventMap(events)
+      );
+
+      const row = db.prepare('SELECT * FROM http_requests').get() as any;
+      expect(row.method).toBe('POST');
+      expect(row.path).toBe('/orders');
+      expect(row.normalized_path).toBe('/orders');
+      expect(row.protocol).toBe('HTTP/1.1');
+      expect(row.status_code).toBe(500);
+      expect(row.mime_type).toBe('application/json');
+      expect(row.elapsed_ms).toBeCloseTo(520);
+      expect(row.thread_id).toBe(99);
+      expect(row.parent_event_id).toBeNull();
+    } finally {
+      db.close();
+    }
+  });
+
+  it('records status_code 0 when no return event was emitted', () => {
+    const db = freshDb();
+    try {
+      const appmapId = seedAppmap(db);
+      const events = [
+        {
+          id: 1,
+          event: 'call',
+          http_server_request: { request_method: 'GET', path_info: '/x' },
+        },
+      ];
+      importHttpRequests(
+        db,
+        appmapId,
+        events,
+        buildReturnEventMap(events),
+        buildParentEventMap(events)
+      );
+      const row = db.prepare('SELECT status_code, elapsed_ms FROM http_requests').get() as any;
+      expect(row.status_code).toBe(0);
+      expect(row.elapsed_ms).toBeNull();
+    } finally {
+      db.close();
+    }
+  });
+});
diff --git a/packages/cli/tests/unit/cmds/query/db/import/importAppmap.spec.ts b/packages/cli/tests/unit/cmds/query/db/import/importAppmap.spec.ts
new file mode 100644
index 0000000000..4d25c85ece
--- /dev/null
+++ b/packages/cli/tests/unit/cmds/query/db/import/importAppmap.spec.ts
@@ -0,0 +1,196 @@
+import { mkdtempSync, rmSync, writeFileSync } from 'fs';
+import { tmpdir } from 'os';
+import { join, resolve } from 'path';
+
+import {
+  deleteAppmap,
+  importAppmap,
+} from '../../../../../../src/cmds/query/db/import/importAppmap';
+import { freshDb } from './helpers';
+
+function writeAppmap(dir: string, name: string, body: object): string {
+  const p = join(dir, name);
+  writeFileSync(p, JSON.stringify(body));
+  return p;
+}
+
+describe('importAppmap', () => {
+  let tmp: string;
+
+  beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), 'import-appmap-'));
+  });
+
+  afterEach(() => {
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it('imports an end-to-end recording into all tables', () => {
+    const db = freshDb();
+    try {
+      const path = writeAppmap(tmp, 'rec.appmap.json', {
+        metadata: {
+          name: 'orders_create_42',
+          language: { name: 'ruby' },
+          frameworks: [{ name: 'rails' }],
+          recorder: { type: 'rspec' },
+          git: { branch: 'feature/foo', commit: 'abc' },
+          timestamp: 1700000000,
+        },
+        classMap: [
+          {
+            type: 'package',
+            name: 'app',
+            children: [
+              {
+                type: 'class',
+                name: 'OrdersController',
+                children: [
+                  {
+                    type: 'function',
+                    name: 'create',
+                    location: 'app/controllers/orders_controller.rb:42',
+                  },
+                ],
+              },
+            ],
+          },
+        ],
+        events: [
+          {
+            id: 1,
+            event: 'call',
+            thread_id: 1,
+            http_server_request: { request_method: 'POST', path_info: '/orders' },
+          },
+          {
+            id: 2,
+            event: 'call',
+            thread_id: 1,
+            defined_class: 'OrdersController',
+            method_id: 'create',
+            path: 'app/controllers/orders_controller.rb',
+            lineno: 42,
+          },
+          {
+            id: 3,
+            event: 'call',
+            thread_id: 1,
+            sql_query: { sql: 'INSERT INTO orders (...)' },
+          },
+          { id: 4, event: 'return', parent_id: 3, elapsed: 0.014 },
+          {
+            id: 5,
+            event: 'return',
+            parent_id: 2,
+            exceptions: [{ class: 'IntegrityError', message: 'duplicate key' }],
+          },
+          {
+            id: 6,
+            event: 'return',
+            parent_id: 1,
+            http_server_response: { status_code: 500 },
+            elapsed: 0.52,
+          },
+        ],
+      });
+
+      const result = importAppmap(db, path);
+      expect(result.eventCount).toBe(6);
+      expect(result.sqlCount).toBe(1);
+      expect(result.httpCount).toBe(1);
+
+      const am = db.prepare('SELECT * FROM appmaps').get() as any;
+      expect(am.source_path).toBe(resolve(path));
+      expect(am.git_branch).toBe('feature/foo');
+      expect(am.elapsed_ms).toBeCloseTo(520);
+
+      expect((db.prepare('SELECT COUNT(*) AS n FROM http_requests').get() as any).n).toBe(1);
+      expect((db.prepare('SELECT COUNT(*) AS n FROM sql_queries').get() as any).n).toBe(1);
+      expect((db.prepare('SELECT COUNT(*) AS n FROM function_calls').get() as any).n).toBe(1);
+      expect((db.prepare('SELECT COUNT(*) AS n FROM exceptions').get() as any).n).toBe(1);
+      expect((db.prepare('SELECT COUNT(*) AS n FROM code_objects').get() as any).n).toBe(1);
+    } finally {
+      db.close();
+    }
+  });
+
+  it('is idempotent on re-import — rows are replaced, not duplicated', () => {
+    const db = freshDb();
+    try {
+      const path = writeAppmap(tmp, 'rec.appmap.json', {
+        metadata: { timestamp: 1700000000 },
+        events: [
+          {
+            id: 1,
+            event: 'call',
+            http_server_request: { request_method: 'GET', path_info: '/x' },
+          },
+          { id: 2, event: 'return', parent_id: 1, http_server_response: { status_code: 200 } },
+        ],
+      });
+      importAppmap(db, path);
+      importAppmap(db, path);
+      expect((db.prepare('SELECT COUNT(*) AS n FROM appmaps').get() as any).n).toBe(1);
+      expect((db.prepare('SELECT COUNT(*) AS n FROM http_requests').get() as any).n).toBe(1);
+    } finally {
+      db.close();
+    }
+  });
+
+  it('rolls back on a parse error, leaving no partial rows', () => {
+    const db = freshDb();
+    try {
+      const path = join(tmp, 'broken.appmap.json');
+      writeFileSync(path, '{not valid json');
+      expect(() => importAppmap(db, path)).toThrow();
+      expect((db.prepare('SELECT COUNT(*) AS n FROM appmaps').get() as any).n).toBe(0);
+    } finally {
+      db.close();
+    }
+  });
+});
+
+describe('deleteAppmap', () => {
+  let tmp: string;
+
+  beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), 'delete-appmap-'));
+  });
+
+  afterEach(() => {
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it('removes the recording and cascades to child rows', () => {
+    const db = freshDb();
+    try {
+      const path = writeAppmap(tmp, 'rec.appmap.json', {
+        metadata: { timestamp: 1700000000 },
+        events: [
+          {
+            id: 1,
+            event: 'call',
+            http_server_request: { request_method: 'GET', path_info: '/x' },
+          },
+          { id: 2, event: 'return', parent_id: 1, http_server_response: { status_code: 200 } },
+        ],
+      });
+      importAppmap(db, path);
+      expect(deleteAppmap(db, path)).toBe(true);
+      expect((db.prepare('SELECT COUNT(*) AS n FROM appmaps').get() as any).n).toBe(0);
+      expect((db.prepare('SELECT COUNT(*) AS n FROM http_requests').get() as any).n).toBe(0);
+    } finally {
+      db.close();
+    }
+  });
+
+  it('returns false when no matching row exists', () => {
+    const db = freshDb();
+    try {
+      expect(deleteAppmap(db, '/tmp/nonexistent.appmap.json')).toBe(false);
+    } finally {
+      db.close();
+    }
+  });
+});
diff --git a/packages/cli/tests/unit/cmds/query/db/import/parentEventMap.spec.ts b/packages/cli/tests/unit/cmds/query/db/import/parentEventMap.spec.ts
new file mode 100644
index 0000000000..f2b4a536f7
--- /dev/null
+++ b/packages/cli/tests/unit/cmds/query/db/import/parentEventMap.spec.ts
@@ -0,0 +1,74 @@
+import {
+  buildParentEventMap,
+  AppMapEventLike,
+} from '../../../../../../src/cmds/query/db/import/parentEventMap';
+
+describe('buildParentEventMap', () => {
+  it('returns an empty map for an empty event stream', () => {
+    expect(buildParentEventMap([])).toEqual(new Map());
+  });
+
+  it('assigns the call directly above as the parent on a single thread', () => {
+    const events: AppMapEventLike[] = [
+      { id: 1, thread_id: 1, event: 'call' }, // root
+      { id: 2, thread_id: 1, event: 'call' }, // child of 1
+      { id: 3, thread_id: 1, event: 'call' }, // child of 2
+      { id: 4, thread_id: 1, event: 'return' }, // returns from 3
+      { id: 5, thread_id: 1, event: 'call' }, // child of 2 again
+      { id: 6, thread_id: 1, event: 'return' }, // returns from 5
+      { id: 7, thread_id: 1, event: 'return' }, // returns from 2
+      { id: 8, thread_id: 1, event: 'return' }, // returns from 1
+    ];
+    const map = buildParentEventMap(events);
+    expect(map.get(1)).toBeUndefined();
+    expect(map.get(2)).toBe(1);
+    expect(map.get(3)).toBe(2);
+    expect(map.get(5)).toBe(2);
+  });
+
+  it('keeps threads independent', () => {
+    const events: AppMapEventLike[] = [
+      { id: 1, thread_id: 1, event: 'call' },
+      { id: 2, thread_id: 2, event: 'call' }, // different thread; no parent
+      { id: 3, thread_id: 1, event: 'call' }, // child of 1
+      { id: 4, thread_id: 2, event: 'call' }, // child of 2
+    ];
+    const map = buildParentEventMap(events);
+    expect(map.get(1)).toBeUndefined();
+    expect(map.get(2)).toBeUndefined();
+    expect(map.get(3)).toBe(1);
+    expect(map.get(4)).toBe(2);
+  });
+
+  it('skips events missing id or thread_id', () => {
+    const events: AppMapEventLike[] = [
+      { id: 1, thread_id: 1, event: 'call' },
+      { thread_id: 1, event: 'call' }, // missing id
+      { id: 3, event: 'call' }, // missing thread_id
+      { id: 4, thread_id: 1, event: 'call' }, // child of 1 (the malformed events were skipped)
+    ];
+    const map = buildParentEventMap(events);
+    expect(map.get(4)).toBe(1);
+  });
+
+  it('tolerates extra returns past an empty stack', () => {
+    const events: AppMapEventLike[] = [
+      { id: 1, thread_id: 1, event: 'return' }, // no matching call
+      { id: 2, thread_id: 1, event: 'call' }, // root after a stray return
+      { id: 3, thread_id: 1, event: 'call' }, // child of 2
+    ];
+    const map = buildParentEventMap(events);
+    expect(map.get(2)).toBeUndefined();
+    expect(map.get(3)).toBe(2);
+  });
+
+  it('ignores events with neither call nor return', () => {
+    const events: AppMapEventLike[] = [
+      { id: 1, thread_id: 1, event: 'call' },
+      { id: 2, thread_id: 1, event: 'log' }, // synthetic; not a call/return
+      { id: 3, thread_id: 1, event: 'call' }, // still child of 1
+    ];
+    const map = buildParentEventMap(events);
+    expect(map.get(3)).toBe(1);
+  });
+});
diff --git a/packages/cli/tests/unit/cmds/query/db/import/parseLocation.spec.ts b/packages/cli/tests/unit/cmds/query/db/import/parseLocation.spec.ts
new file mode 100644
index 0000000000..e2aa48242a
--- /dev/null
+++ b/packages/cli/tests/unit/cmds/query/db/import/parseLocation.spec.ts
@@ -0,0 +1,35 @@
+import { parseLocation } from '../../../../../../src/cmds/query/db/import/parseLocation';
+
+describe('parseLocation', () => {
+  it('parses a simple relative path with a line number', () => {
+    expect(parseLocation('app/views.py:10')).toEqual(['app/views.py', 10]);
+  });
+
+  it('parses an absolute path with a line number', () => {
+    expect(parseLocation('/abs/path/file.rb:511')).toEqual(['/abs/path/file.rb', 511]);
+  });
+
+  it('parses a negative line number (synthetic locations)', () => {
+    expect(parseLocation('File.java:-1')).toEqual(['File.java', -1]);
+  });
+
+  it('returns nulls for locations without a colon', () => {
+    expect(parseLocation('OpenSSL::Cipher#decrypt')).toEqual([null, null]);
+  });
+
+  it('returns nulls for empty input', () => {
+    expect(parseLocation('')).toEqual([null, null]);
+    expect(parseLocation(undefined)).toEqual([null, null]);
+    expect(parseLocation(null)).toEqual([null, null]);
+  });
+
+  it('returns nulls when the suffix after the last colon is not an integer', () => {
+    expect(parseLocation('file.rb:abc')).toEqual([null, null]);
+    expect(parseLocation('file.rb:')).toEqual([null, null]);
+    expect(parseLocation('file.rb:1a')).toEqual([null, null]);
+  });
+
+  it('uses the rightmost colon so namespaced paths are preserved', () => {
+    expect(parseLocation('OpenSSL::Cipher:42')).toEqual(['OpenSSL::Cipher', 42]);
+  });
+});
diff --git a/packages/cli/tests/unit/cmds/query/db/import/returnEventMap.spec.ts b/packages/cli/tests/unit/cmds/query/db/import/returnEventMap.spec.ts
new file mode 100644
index 0000000000..c8124c1f3d
--- /dev/null
+++ b/packages/cli/tests/unit/cmds/query/db/import/returnEventMap.spec.ts
@@ -0,0 +1,26 @@
+import { buildReturnEventMap } from '../../../../../../src/cmds/query/db/import/returnEventMap';
+
+describe('buildReturnEventMap', () => {
+  it('maps call event id → return event via parent_id', () => {
+    const events = [
+      { id: 1, event: 'call' },
+      { id: 2, event: 'return', parent_id: 1, elapsed: 0.5 },
+      { id: 3, event: 'call' },
+      { id: 4, event: 'return', parent_id: 3, http_server_response: { status_code: 200 } },
+    ];
+    const map = buildReturnEventMap(events);
+    expect(map.get(1)?.elapsed).toBe(0.5);
+    expect(map.get(3)?.http_server_response).toEqual({ status_code: 200 });
+    expect(map.size).toBe(2);
+  });
+
+  it('ignores returns without parent_id', () => {
+    const events = [{ id: 1, event: 'return' /* no parent_id */ }];
+    expect(buildReturnEventMap(events).size).toBe(0);
+  });
+
+  it('ignores non-return events', () => {
+    const events = [{ id: 1, event: 'call', parent_id: 999 }];
+    expect(buildReturnEventMap(events).size).toBe(0);
+  });
+});
diff --git a/packages/cli/tests/unit/cmds/query/db/import/sqlQueries.spec.ts b/packages/cli/tests/unit/cmds/query/db/import/sqlQueries.spec.ts
new file mode 100644
index 0000000000..f93ac8fdf7
--- /dev/null
+++ b/packages/cli/tests/unit/cmds/query/db/import/sqlQueries.spec.ts
@@ -0,0 +1,84 @@
+import { importSqlQueries } from '../../../../../../src/cmds/query/db/import/sqlQueries';
+import { buildReturnEventMap } from '../../../../../../src/cmds/query/db/import/returnEventMap';
+import { buildParentEventMap } from '../../../../../../src/cmds/query/db/import/parentEventMap';
+import { freshDb } from './helpers';
+
+function seedAppmap(db: any): number {
+  const info = db
+    .prepare("INSERT INTO appmaps (name, source_path) VALUES ('rec', '/tmp/rec.appmap.json')")
+    .run();
+  return Number(info.lastInsertRowid);
+}
+
+describe('importSqlQueries', () => {
+  it('inserts one row per sql_query event with caller from the event', () => {
+    const db = freshDb();
+    try {
+      const appmapId = seedAppmap(db);
+      const events = [
+        {
+          id: 1,
+          event: 'call',
+          thread_id: 1,
+          defined_class: 'OrdersController',
+          method_id: 'create',
+          sql_query: { sql: 'INSERT INTO orders (...)', database_type: 'postgres', server_version: '14.5' },
+        },
+        { id: 2, event: 'return', parent_id: 1, elapsed: 0.014 },
+      ];
+      importSqlQueries(
+        db,
+        appmapId,
+        events,
+        buildReturnEventMap(events),
+        buildParentEventMap(events)
+      );
+      const row = db.prepare('SELECT * FROM sql_queries').get() as any;
+      expect(row.sql_text).toBe('INSERT INTO orders (...)');
+      expect(row.database_type).toBe('postgres');
+      expect(row.server_version).toBe('14.5');
+      expect(row.caller_class).toBe('OrdersController');
+      expect(row.caller_method).toBe('create');
+      expect(row.elapsed_ms).toBeCloseTo(14);
+    } finally {
+      db.close();
+    }
+  });
+
+  it('derives caller from the parent call event when the sql event lacks defined_class', () => {
+    const db = freshDb();
+    try {
+      const appmapId = seedAppmap(db);
+      const events = [
+        {
+          id: 1,
+          event: 'call',
+          thread_id: 1,
+          defined_class: 'OrdersController',
+          method_id: 'create',
+        },
+        {
+          id: 2,
+          event: 'call',
+          thread_id: 1,
+          // no defined_class on the SQL event itself
+          sql_query: { sql: 'SELECT 1' },
+        },
+        { id: 3, event: 'return', parent_id: 2 },
+        { id: 4, event: 'return', parent_id: 1 },
+      ];
+      importSqlQueries(
+        db,
+        appmapId,
+        events,
+        buildReturnEventMap(events),
+        buildParentEventMap(events)
+      );
+      const row = db.prepare('SELECT caller_class, caller_method FROM sql_queries').get() as any;
+      expect(row.caller_class).toBe('OrdersController');
+      expect(row.caller_method).toBe('create');
+    } finally {
+      db.close();
+    }
+  });
+});
diff --git a/packages/cli/tests/unit/cmds/query/db/openQueryDb.spec.ts b/packages/cli/tests/unit/cmds/query/db/openQueryDb.spec.ts
new file mode 100644
index 0000000000..96ea05485f
--- /dev/null
+++ b/packages/cli/tests/unit/cmds/query/db/openQueryDb.spec.ts
@@ -0,0 +1,119 @@
+import { mkdtempSync, rmSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+
+import { openQueryDb } from '../../../../../src/cmds/query/db/openQueryDb';
+import { SCHEMA_TABLES, SCHEMA_VERSION } from '../../../../../src/cmds/query/db/schema';
+
+describe('openQueryDb', () => {
+  let tmpDir: string;
+  let dbPath: string;
+
+  beforeEach(() => {
+    tmpDir = mkdtempSync(join(tmpdir(), 'appmap-query-db-'));
+    dbPath = join(tmpDir, 'query.db');
+  });
+
+  afterEach(() => {
+    rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it('creates all schema tables on a fresh DB and stamps user_version', () => {
+    const { db, version, rebuilt, path } = openQueryDb('/tmp/ignored', dbPath);
+    try {
+      expect(path).toBe(dbPath);
+      expect(version).toBe(SCHEMA_VERSION);
+      expect(rebuilt).toBe(false);
+
+      const tables = db
+        .prepare("SELECT name FROM sqlite_master WHERE type='table' ORDER BY name")
+        .all()
+        .map((r: any) => r.name);
+      for (const t of SCHEMA_TABLES) expect(tables).toContain(t);
+
+      expect(db.pragma('user_version', { simple: true })).toBe(SCHEMA_VERSION);
+    } finally {
+      db.close();
+    }
+  });
+
+  it('reopens an existing DB at the same version without rebuilding', () => {
+    const first = openQueryDb('/tmp/ignored', dbPath);
+    first.db.exec("INSERT INTO appmaps (name, source_path) VALUES ('canary', '/tmp/canary')");
+    first.db.close();
+
+    const second = openQueryDb('/tmp/ignored', dbPath);
+    try {
+      expect(second.rebuilt).toBe(false);
+      const row = second.db
+        .prepare("SELECT name FROM appmaps WHERE source_path = '/tmp/canary'")
+        .get() as { name: string } | undefined;
+      expect(row?.name).toBe('canary');
+    } finally {
+      second.db.close();
+    }
+  });
+
+  it('drops and rebuilds tables when on-disk user_version does not match', () => {
+    const first = openQueryDb('/tmp/ignored', dbPath);
+    first.db.exec("INSERT INTO appmaps (name, source_path) VALUES ('canary', '/tmp/canary')");
+    first.db.pragma('user_version = 999');
+    first.db.close();
+
+    const second = openQueryDb('/tmp/ignored', dbPath);
+    try {
+      expect(second.rebuilt).toBe(true);
+      expect(second.version).toBe(SCHEMA_VERSION);
+      const count = second.db.prepare('SELECT COUNT(*) AS n FROM appmaps').get() as { n: number };
+      expect(count.n).toBe(0);
+      expect(second.db.pragma('user_version', { simple: true })).toBe(SCHEMA_VERSION);
+    } finally {
+      second.db.close();
+    }
+  });
+
+  it('enables WAL and foreign_keys pragmas', () => {
+    const { db } = openQueryDb('/tmp/ignored', dbPath);
+    try {
+      expect(String(db.pragma('journal_mode', { simple: true })).toLowerCase()).toBe('wal');
+      expect(db.pragma('foreign_keys', { simple: true })).toBe(1);
+    } finally {
+      db.close();
+    }
+  });
+
+  it('cascades deletes from appmaps to dependent rows', () => {
+    const { db } = openQueryDb('/tmp/ignored', dbPath);
+    try {
+      const info = db
+        .prepare("INSERT INTO appmaps (name, source_path) VALUES (?, ?)")
+        .run('rec', '/tmp/rec.appmap.json');
+      const appmapId = info.lastInsertRowid;
+
+      db.prepare(
+        `INSERT INTO http_requests
+         (appmap_id, event_id, method, path, status_code)
+         VALUES (?, 1, 'GET', '/x', 200)`
+      ).run(appmapId);
+
+      db.prepare('DELETE FROM appmaps WHERE id = ?').run(appmapId);
+
+      const remaining = db
+        .prepare('SELECT COUNT(*) AS n FROM http_requests WHERE appmap_id = ?')
+        .get(appmapId) as { n: number };
+      expect(remaining.n).toBe(0);
+    } finally {
+      db.close();
+    }
+  });
+
+  it('creates the parent directory when it does not exist', () => {
+    const nested = join(tmpDir, 'a', 'b', 'c', 'query.db');
+    const { db } = openQueryDb('/tmp/ignored', nested);
+    try {
+      expect(db.pragma('user_version', { simple: true })).toBe(SCHEMA_VERSION);
+    } finally {
+      db.close();
+    }
+  });
+});
diff --git a/packages/cli/tests/unit/cmds/query/db/path.spec.ts b/packages/cli/tests/unit/cmds/query/db/path.spec.ts
new file mode 100644
index 0000000000..6186768b59
--- /dev/null
+++ b/packages/cli/tests/unit/cmds/query/db/path.spec.ts
@@ -0,0 +1,28 @@
+import { existsSync } from 'fs';
+import { dirname } from 'path';
+
+import { queryDbPath } from '../../../../../src/cmds/query/db/path';
+
+describe('queryDbPath', () => {
+  it('returns the same path for equivalent directory inputs', () => {
+    expect(queryDbPath('/tmp/a')).toBe(queryDbPath('/tmp/a/'));
+    expect(queryDbPath('/tmp/a')).toBe(queryDbPath('/tmp/a/./'));
+  });
+
+  it('produces different paths for different directories', () => {
+    expect(queryDbPath('/tmp/a')).not.toBe(queryDbPath('/tmp/b'));
+  });
+
+  it('lands under ~/.appmap/data/<sha12>/query.db', () => {
+    const path = queryDbPath('/tmp/path-test-dir');
+    expect(path).toMatch(/[/\\]\.appmap[/\\]data[/\\][0-9a-f]{12}[/\\]query\.db$/);
+  });
+
+  it('does not create the parent directory', () => {
+    const path = queryDbPath('/tmp/never-created-dir-xyz');
+    // The parent may exist if a prior test created it, but queryDbPath
+    // itself must not create anything; assert it returns a path without I/O.
+    expect(typeof path).toBe('string');
+    void existsSync(dirname(path));
+  });
+});
diff --git a/packages/cli/tests/unit/cmds/query/lib/appmapPath.spec.ts b/packages/cli/tests/unit/cmds/query/lib/appmapPath.spec.ts
new file mode 100644
index 0000000000..8133ca061a
--- /dev/null
+++ b/packages/cli/tests/unit/cmds/query/lib/appmapPath.spec.ts
@@ -0,0 +1,47 @@
+import { deriveKind, looksLikeDisplayLabel } from '../../../../../src/cmds/query/lib/appmapPath';
+
+describe('deriveKind', () => {
+  it('detects junit recordings', () => {
+    expect(deriveKind('/abs/tmp/appmap/junit/foo.appmap.json')).toBe('junit');
+  });
+
+  it('detects request recordings', () => {
+    expect(
+      deriveKind('/abs/tmp/appmap/request_recording/1779_post_orders.appmap.json')
+    ).toBe('request');
+  });
+
+  it('falls back to "other" for unrecognized layouts', () => {
+    expect(deriveKind('/abs/tmp/appmap/cucumber/foo.appmap.json')).toBe('other');
+  });
+});
+
+describe('looksLikeDisplayLabel', () => {
+  it('rejects HTTP-method + paren-status display labels', () => {
+    expect(
+      looksLikeDisplayLabel('GET /api/v1/payments/idempotent (200) - 19:47:22.660')
+    ).toBe(true);
+  });
+
+  it('rejects strings that contain a trailing time-of-day component', () => {
+    expect(looksLikeDisplayLabel('something - 14:05:31')).toBe(true);
+  });
+
+  it('accepts canonical absolute paths', () => {
+    expect(
+      looksLikeDisplayLabel(
+        '/Users/me/proj/customer-portal-api/tmp/appmap/junit/foo.appmap.json'
+      )
+    ).toBe(false);
+  });
+
+  it('accepts recording names', () => {
+    expect(
+      looksLikeDisplayLabel('com_omnibank_DuplicatePaymentRaceIT_concurrent_submissions')
+    ).toBe(false);
+  });
+
+  it('accepts numeric ids', () => {
+    expect(looksLikeDisplayLabel('2')).toBe(false);
+  });
+});
diff --git a/packages/cli/tests/unit/cmds/query/lib/parseFilter.spec.ts b/packages/cli/tests/unit/cmds/query/lib/parseFilter.spec.ts
new file mode 100644
index 0000000000..b6a3de55fe
--- /dev/null
+++ b/packages/cli/tests/unit/cmds/query/lib/parseFilter.spec.ts
@@ -0,0 +1,77 @@
+import {
+  numberFilterSql,
+  parseDuration,
+  parseStatus,
+  parseTime,
+} from '../../../../../src/cmds/query/lib/parseFilter';
+
+describe('parseStatus', () => {
+  it('parses bare integer as equality', () => {
+    expect(parseStatus('500')).toEqual({ op: '=', value: 500 });
+  });
+
+  it('parses each comparator', () => {
+    expect(parseStatus('>=500')).toEqual({ op: '>=', value: 500 });
+    expect(parseStatus('<=399')).toEqual({ op: '<=', value: 399 });
+    expect(parseStatus('>200')).toEqual({ op: '>', value: 200 });
+    expect(parseStatus('<400')).toEqual({ op: '<', value: 400 });
+    expect(parseStatus('=500')).toEqual({ op: '=', value: 500 });
+  });
+
+  it('tolerates whitespace around the operator', () => {
+    expect(parseStatus('>= 500')).toEqual({ op: '>=', value: 500 });
+    expect(parseStatus(' >=500 ')).toEqual({ op: '>=', value: 500 });
+  });
+
+  it('throws on garbage input', () => {
+    expect(() => parseStatus('5xx')).toThrow(/invalid/);
+    expect(() => parseStatus('')).toThrow(/invalid/);
+  });
+});
+
+describe('parseDuration', () => {
+  it('defaults to ms when no unit is given', () => {
+    expect(parseDuration('>500')).toEqual({ op: '>', value: 500 });
+  });
+
+  it('converts s/m/h to ms', () => {
+    expect(parseDuration('>1s')).toEqual({ op: '>', value: 1000 });
+    expect(parseDuration('>=2m')).toEqual({ op: '>=', value: 120_000 });
+    expect(parseDuration('<1h')).toEqual({ op: '<', value: 3_600_000 });
+  });
+
+  it('accepts decimals', () => {
+    expect(parseDuration('>1.5s')).toEqual({ op: '>', value: 1500 });
+  });
+});
+
+describe('parseTime', () => {
+  it('parses ISO timestamps', () => {
+    expect(parseTime('2026-04-29T14:21:08Z')).toBe('2026-04-29T14:21:08.000Z');
+  });
+
+  it('parses ISO dates', () => {
+    expect(parseTime('2026-04-29')).toBe('2026-04-29T00:00:00.000Z');
+  });
+
+  it('parses relative offsets', () => {
+    const now = new Date('2026-05-01T12:00:00Z');
+    expect(parseTime('7d ago', now)).toBe('2026-04-24T12:00:00.000Z');
+    expect(parseTime('30m ago', now)).toBe('2026-05-01T11:30:00.000Z');
+    expect(parseTime('2h ago', now)).toBe('2026-05-01T10:00:00.000Z');
+    expect(parseTime('45s ago', now)).toBe('2026-05-01T11:59:15.000Z');
+  });
+
+  it('throws on garbage input', () => {
+    expect(() => parseTime('not a time')).toThrow(/invalid/);
+  });
+});
+
+describe('numberFilterSql', () => {
+  it('builds a sql fragment + value', () => {
+    expect(numberFilterSql('status_code', { op: '>=', value: 500 })).toEqual({
+      sql: 'status_code >= ?',
+      value: 500,
+    });
+  });
+});
diff --git a/packages/cli/tests/unit/cmds/query/lib/scope.spec.ts b/packages/cli/tests/unit/cmds/query/lib/scope.spec.ts
new file mode 100644
index 0000000000..9279662bc9
--- /dev/null
+++ b/packages/cli/tests/unit/cmds/query/lib/scope.spec.ts
@@ -0,0 +1,321 @@
+import sqlite3 from 'better-sqlite3';
+
+import { openQueryDb } from '../../../../../src/cmds/query/db/openQueryDb';
+import {
+  appmapRefClause,
+  classFilterClauses,
+  methodFilterClauses,
+  parseClassRef,
+  parseRoute,
+} from '../../../../../src/cmds/query/lib/scope';
+
+function freshDb(): sqlite3.Database {
+  return openQueryDb('/tmp/ignored', ':memory:').db;
+}
+
+describe('parseRoute', () => {
+  it('parses an HTTP method case-insensitively and uppercases it', () => {
+    expect(parseRoute('post /orders')).toEqual({ method: 'POST', path: '/orders' });
+    expect(parseRoute('Get /reports')).toEqual({ method: 'GET', path: '/reports' });
+    expect(parseRoute('DELETE /orders/:id')).toEqual({
+      method: 'DELETE',
+      path: '/orders/:id',
+    });
+  });
+
+  it('treats an unrecognised prefix as part of the path', () => {
+    expect(parseRoute('FOO /bar')).toEqual({ path: 'FOO /bar' });
+    expect(parseRoute('/orders')).toEqual({ path: '/orders' });
+  });
+});
+
+describe('appmapRefClause (basename matching)', () => {
+  it('matches Unix-style source_path with .appmap.json suffix', () => {
+    const db = freshDb();
+    try {
+      db.prepare(
+        `INSERT INTO appmaps (name, source_path) VALUES ('rec1', '/tmp/path/rec1.appmap.json')`
+      ).run();
+      const m = appmapRefClause('rec1', 'a');
+      const row = db
+        .prepare(`SELECT a.name FROM appmaps a WHERE ${m.sql}`)
+        .get(...m.params) as { name: string } | undefined;
+      expect(row?.name).toBe('rec1');
+    } finally {
+      db.close();
+    }
+  });
+
+  it('matches Windows-style source_path with backslash separator', () => {
+    const db = freshDb();
+    try {
+      db.prepare(
+        `INSERT INTO appmaps (name, source_path) VALUES ('rec1', 'C:\\Users\\me\\rec1.appmap.json')`
+      ).run();
+      const m = appmapRefClause('rec1', 'a');
+      const row = db
+        .prepare(`SELECT a.name FROM appmaps a WHERE ${m.sql}`)
+        .get(...m.params) as { name: string } | undefined;
+      expect(row?.name).toBe('rec1');
+    } finally {
+      db.close();
+    }
+  });
+
+  it('matches source_path without the .appmap.json suffix', () => {
+    const db = freshDb();
+    try {
+      db.prepare(
+        `INSERT INTO appmaps (name, source_path) VALUES ('odd', '/store/abc/odd')`
+      ).run();
+      const m = appmapRefClause('odd', 'a');
+      const row = db
+        .prepare(`SELECT a.name FROM appmaps a WHERE ${m.sql}`)
+        .get(...m.params) as { name: string } | undefined;
+      expect(row?.name).toBe('odd');
+    } finally {
+      db.close();
+    }
+  });
+
+  it('matches by appmap.name when source_path differs', () => {
+    const db = freshDb();
+    try {
+      db.prepare(
+        `INSERT INTO appmaps (name, source_path) VALUES ('Friendly Name', '/x/foo.appmap.json')`
+      ).run();
+      const m = appmapRefClause('Friendly Name', 'a');
+      const row = db
+        .prepare(`SELECT a.name FROM appmaps a WHERE ${m.sql}`)
+        .get(...m.params) as { name: string } | undefined;
+      expect(row?.name).toBe('Friendly Name');
+    } finally {
+      db.close();
+    }
+  });
+});
+
+describe('parseClassRef', () => {
+  it('short form is just a class', () => {
+    expect(parseClassRef('UserRepository')).toEqual({ class: 'UserRepository' });
+  });
+
+  it('short form with method via #', () => {
+    expect(parseClassRef('UserRepository#findById')).toEqual({
+      class: 'UserRepository',
+      method: 'findById',
+    });
+  });
+
+  it('Ruby/C++ "::" chain in short form is kept as one class name', () => {
+    expect(parseClassRef('Cls1::Cls2')).toEqual({ class: 'Cls1::Cls2' });
+    expect(parseClassRef('OpenSSL::Cipher')).toEqual({ class: 'OpenSSL::Cipher' });
+  });
+
+  it('Ruby/C++ "::" chain with method via #', () => {
+    expect(parseClassRef('Net::HTTP#get')).toEqual({ class: 'Net::HTTP', method: 'get' });
+  });
+
+  it('Java/Python dot-form in short form is kept whole (no method split)', () => {
+    // We can't unambiguously split "org.example.Foo" without context; treat
+    // the whole input as the class name and let the fallback match it via
+    // defined_class.
+    expect(parseClassRef('org.example.Foo')).toEqual({ class: 'org.example.Foo' });
+  });
+
+  it('canonical fqid: package + class', () => {
+    expect(parseClassRef('app/services/UserRepository')).toEqual({
+      package: 'app/services',
+      class: 'UserRepository',
+    });
+  });
+
+  it('canonical fqid: package + class + instance method', () => {
+    expect(parseClassRef('app/services/UserRepository#findById')).toEqual({
+      package: 'app/services',
+      class: 'UserRepository',
+      method: 'findById',
+    });
+  });
+
+  it('canonical fqid: package + class + static method', () => {
+    expect(parseClassRef('core/date/Date.parse')).toEqual({
+      package: 'core/date',
+      class: 'Date',
+      method: 'parse',
+    });
+  });
+
+  it('canonical fqid with nested classes via ::', () => {
+    expect(parseClassRef('app/Outer::Inner#foo')).toEqual({
+      package: 'app',
+      class: 'Outer::Inner',
+      method: 'foo',
+    });
+    expect(parseClassRef('lib/Outer::Inner.parse')).toEqual({
+      package: 'lib',
+      class: 'Outer::Inner',
+      method: 'parse',
+    });
+  });
+});
+
+function seedCodeObject(
+  db: sqlite3.Database,
+  fqid: string,
+  pkg: string,
+  classes: string[],
+  method: string,
+  isStatic = 0
+): number {
+  const leaf = classes.length > 0 ? classes[classes.length - 1] : '';
+  db.prepare(
+    `INSERT OR IGNORE INTO code_objects (fqid, package, classes, leaf_class, method, is_static)
+     VALUES (?, ?, ?, ?, ?, ?)`
+  ).run(fqid, pkg, JSON.stringify(classes), leaf, method, isStatic);
+  return (db.prepare(`SELECT id FROM code_objects WHERE fqid = ?`).get(fqid) as { id: number }).id;
+}
+
+function seedAppmap(db: sqlite3.Database): number {
+  return Number(
+    db
+      .prepare(`INSERT INTO appmaps (name, source_path) VALUES ('a', '/tmp/a.appmap.json')`)
+      .run().lastInsertRowid
+  );
+}
+
+function seedCall(
+  db: sqlite3.Database,
+  appmapId: number,
+  eventId: number,
+  defined_class: string,
+  method_id: string,
+  code_object_id: number | null
+): void {
+  db.prepare(
+    `INSERT INTO function_calls (appmap_id, event_id, defined_class, method_id, code_object_id)
+     VALUES (?, ?, ?, ?, ?)`
+  ).run(appmapId, eventId, defined_class, method_id, code_object_id);
+}
+
+describe('classFilterClauses', () => {
+  it('short class name matches a nested ::-chain via suffix', () => {
+    const db = freshDb();
+    try {
+      const aid = seedAppmap(db);
+      const co1 = seedCodeObject(db, 'app/OpenSSL::Cipher#decrypt', 'app', ['OpenSSL', 'Cipher'], 'decrypt');
+      const co2 = seedCodeObject(db, 'app/Cipher#decrypt', 'app', ['Cipher'], 'decrypt');
+      const co3 = seedCodeObject(db, 'app/Other#m', 'app', ['Other'], 'm');
+      seedCall(db, aid, 1, 'OpenSSL::Cipher', 'decrypt', co1);
+      seedCall(db, aid, 2, 'Cipher', 'decrypt', co2);
+      seedCall(db, aid, 3, 'Other', 'm', co3);
+
+      const c = classFilterClauses('Cipher', 'fc');
+      const sql = `SELECT fc.event_id FROM function_calls fc WHERE ${c.where.join(' AND ')} ORDER BY fc.event_id`;
+      const eids = (db.prepare(sql).all(...c.params) as { event_id: number }[]).map((r) => r.event_id);
+      // Both co1 (nested) and co2 (top-level) should match; co3 should not.
+      expect(eids).toEqual([1, 2]);
+    } finally {
+      db.close();
+    }
+  });
+
+  it('full canonical fqid matches strictly on all components', () => {
+    const db = freshDb();
+    try {
+      const aid = seedAppmap(db);
+      const co1 = seedCodeObject(
+        db,
+        'org/example/UserRepository#findById',
+        'org/example',
+        ['UserRepository'],
+        'findById'
+      );
+      const co2 = seedCodeObject(
+        db,
+        'org/other/UserRepository#findById',
+        'org/other',
+        ['UserRepository'],
+        'findById'
+      );
+      seedCall(db, aid, 1, 'org.example.UserRepository', 'findById', co1);
+      seedCall(db, aid, 2, 'org.other.UserRepository', 'findById', co2);
+
+      const c = classFilterClauses('org/example/UserRepository#findById', 'fc');
+      const sql = `SELECT fc.event_id FROM function_calls fc WHERE ${c.where.join(' AND ')}`;
+      const eids = (db.prepare(sql).all(...c.params) as { event_id: number }[]).map((r) => r.event_id);
+      expect(eids).toEqual([1]);
+    } finally {
+      db.close();
+    }
+  });
+
+  it('Ruby short-form matches via defined_class fallback when not linked to a code_object', () => {
+    const db = freshDb();
+    try {
+      const aid = seedAppmap(db);
+      // Unlinked call (code_object_id = NULL); defined_class is Ruby-form.
+      seedCall(db, aid, 1, 'OpenSSL::Cipher', 'decrypt', null);
+      seedCall(db, aid, 2, 'Some::Other::Class', 'm', null);
+
+      const c = classFilterClauses('Cipher', 'fc');
+      const sql = `SELECT fc.event_id FROM function_calls fc WHERE ${c.where.join(' AND ')}`;
+      const eids = (db.prepare(sql).all(...c.params) as { event_id: number }[]).map((r) => r.event_id);
+      expect(eids).toEqual([1]);
+    } finally {
+      db.close();
+    }
+  });
+
+  it('Java dot-form input matches the full defined_class on unlinked rows', () => {
+    const db = freshDb();
+    try {
+      const aid = seedAppmap(db);
+      seedCall(db, aid, 1, 'org.example.Foo', 'm', null);
+      seedCall(db, aid, 2, 'org.example.Bar', 'm', null);
+
+      const c = classFilterClauses('org.example.Foo', 'fc');
+      const sql = `SELECT fc.event_id FROM function_calls fc WHERE ${c.where.join(' AND ')}`;
+      const eids = (db.prepare(sql).all(...c.params) as { event_id: number }[]).map((r) => r.event_id);
+      expect(eids).toEqual([1]);
+    } finally {
+      db.close();
+    }
+  });
+});
+
+describe('methodFilterClauses', () => {
+  it('matches via normalized code_objects.method', () => {
+    const db = freshDb();
+    try {
+      const aid = seedAppmap(db);
+      const co1 = seedCodeObject(db, 'app/X#findById', 'app', ['X'], 'findById');
+      const co2 = seedCodeObject(db, 'app/Y#save', 'app', ['Y'], 'save');
+      seedCall(db, aid, 1, 'X', 'findById', co1);
+      seedCall(db, aid, 2, 'Y', 'save', co2);
+
+      const m = methodFilterClauses('findById', 'fc');
+      const sql = `SELECT fc.event_id FROM function_calls fc WHERE ${m.where.join(' AND ')}`;
+      const eids = (db.prepare(sql).all(...m.params) as { event_id: number }[]).map((r) => r.event_id);
+      expect(eids).toEqual([1]);
+    } finally {
+      db.close();
+    }
+  });
+
+  it('falls back to function_calls.method_id for unlinked rows', () => {
+    const db = freshDb();
+    try {
+      const aid = seedAppmap(db);
+      seedCall(db, aid, 1, 'X', 'findById', null);
+      seedCall(db, aid, 2, 'Y', 'save', null);
+
+      const m = methodFilterClauses('findById', 'fc');
+      const sql = `SELECT fc.event_id FROM function_calls fc WHERE ${m.where.join(' AND ')}`;
+      const eids = (db.prepare(sql).all(...m.params) as { event_id: number }[]).map((r) => r.event_id);
+      expect(eids).toEqual([1]);
+    } finally {
+      db.close();
+    }
+  });
+});
diff --git a/packages/cli/tests/unit/cmds/query/lib/suggestSimilarFunctionIds.spec.ts b/packages/cli/tests/unit/cmds/query/lib/suggestSimilarFunctionIds.spec.ts
new file mode 100644
index 0000000000..b7e7625969
--- /dev/null
+++ b/packages/cli/tests/unit/cmds/query/lib/suggestSimilarFunctionIds.spec.ts
@@ -0,0 +1,163 @@
+import sqlite3 from 'better-sqlite3';
+
+import { openQueryDb } from '../../../../../src/cmds/query/db/openQueryDb';
+import { suggestSimilarFunctionIds } from '../../../../../src/cmds/query/lib/suggestSimilarFunctionIds';
+
+function freshDb(): sqlite3.Database {
+  return openQueryDb('/tmp/ignored', ':memory:').db;
+}
+
+interface SeededFn {
+  fqid: string;
+  package: string;
+  classes: string;
+  leaf_class: string;
+  method: string;
+  calls: number;
+}
+
+function seed(db: sqlite3.Database, fns: SeededFn[]): void {
+  // One appmap so function_calls have an FK target.
+  const am = db
+    .prepare(
+      `INSERT INTO appmaps (name, source_path) VALUES ('rec', '/tmp/rec.appmap.json')`
+    )
+    .run();
+  const amid = am.lastInsertRowid;
+  const insCo = db.prepare(
+    `INSERT INTO code_objects (fqid, package, classes, leaf_class, method, is_static)
+     VALUES (?, ?, ?, ?, ?, 0)`
+  );
+  const insFc = db.prepare(
+    `INSERT INTO function_calls (appmap_id, event_id, code_object_id, defined_class, method_id)
+     VALUES (?, ?, ?, ?, ?)`
+  );
+  let nextEventId = 1;
+  for (const fn of fns) {
+    const co = insCo.run(fn.fqid, fn.package, fn.classes, fn.leaf_class, fn.method);
+    const coId = co.lastInsertRowid;
+    for (let i = 0; i < fn.calls; i++) {
+      insFc.run(amid, nextEventId++, coId, fn.leaf_class, fn.method);
+    }
+  }
+}
+
+describe('suggestSimilarFunctionIds', () => {
+  it('detects interface vs Impl when only the Impl fired', () => {
+    const db = freshDb();
+    try {
+      seed(db, [
+        {
+          fqid: 'app/PaymentServiceImpl#submit',
+          package: 'app',
+          classes: '["PaymentServiceImpl"]',
+          leaf_class: 'PaymentServiceImpl',
+          method: 'submit',
+          calls: 12,
+        },
+        {
+          fqid: 'app/UserRepository#findById',
+          package: 'app',
+          classes: '["UserRepository"]',
+          leaf_class: 'UserRepository',
+          method: 'findById',
+          calls: 4,
+        },
+      ]);
+      const result = suggestSimilarFunctionIds(db, 'PaymentService', 'submit');
+      expect(result.did_you_mean[0].function_id).toBe('app/PaymentServiceImpl#submit');
+      expect(result.did_you_mean[0].calls).toBe(12);
+      expect(result.hint).toMatch(/interface/i);
+      expect(result.hint).toMatch(/PaymentServiceImpl/);
+    } finally {
+      db.close();
+    }
+  });
+
+  it('returns "no possible reasons" hint when nothing is close', () => {
+    const db = freshDb();
+    try {
+      seed(db, [
+        {
+          fqid: 'app/UserRepository#findById',
+          package: 'app',
+          classes: '["UserRepository"]',
+          leaf_class: 'UserRepository',
+          method: 'findById',
+          calls: 1,
+        },
+      ]);
+      const result = suggestSimilarFunctionIds(db, 'TotallyUnrelated', 'thing');
+      expect(result.hint).toMatch(/Possible reasons/i);
+      expect(result.hint).toMatch(/coverage/);
+    } finally {
+      db.close();
+    }
+  });
+
+  it('marks in_index=false for code_objects that never fired', () => {
+    const db = freshDb();
+    try {
+      seed(db, [
+        {
+          fqid: 'app/Foo#bar',
+          package: 'app',
+          classes: '["Foo"]',
+          leaf_class: 'Foo',
+          method: 'bar',
+          calls: 0,
+        },
+      ]);
+      const result = suggestSimilarFunctionIds(db, 'Foo', 'bar');
+      expect(result.did_you_mean[0]).toEqual({
+        function_id: 'app/Foo#bar',
+        calls: 0,
+        in_index: false,
+      });
+    } finally {
+      db.close();
+    }
+  });
+
+  it('hints about dot-vs-slash when probe uses Java-style dots', () => {
+    const db = freshDb();
+    try {
+      seed(db, [
+        {
+          fqid: 'app/services/Payment#submit',
+          package: 'app/services',
+          classes: '["Payment"]',
+          leaf_class: 'Payment',
+          method: 'submit',
+          calls: 3,
+        },
+      ]);
+      const result = suggestSimilarFunctionIds(db, 'app.services.Payment', 'submit');
+      expect(result.hint).toMatch(/slash/i);
+    } finally {
+      db.close();
+    }
+  });
+
+  it('caps suggestions at 5', () => {
+    const db = freshDb();
+    try {
+      const fns: SeededFn[] = [];
+      for (let i = 0; i < 12; i++) {
+        fns.push({
+          fqid: `app/Payment${i}#submit`,
+          package: 'app',
+          classes: `["Payment${i}"]`,
+          leaf_class: `Payment${i}`,
+          method: 'submit',
+          calls: 1,
+        });
+      }
+      seed(db, fns);
+      const result = suggestSimilarFunctionIds(db, 'Payment', 'submit');
+      expect(result.did_you_mean.length).toBeLessThanOrEqual(5);
+    } finally {
+      db.close();
+    }
+  });
+});
diff --git a/packages/cli/tests/unit/cmds/query/lib/treeRender.spec.ts b/packages/cli/tests/unit/cmds/query/lib/treeRender.spec.ts
new file mode 100644
index 0000000000..e1593600af
--- /dev/null
+++ b/packages/cli/tests/unit/cmds/query/lib/treeRender.spec.ts
@@ -0,0 +1,365 @@
+import {
+  renderFlat,
+  renderTree,
+  renderTreeForMcp,
+  renderTreeForMcpBudgeted,
+  StructBudget,
+  truncateStructValue,
+} from '../../../../../src/cmds/query/lib/treeRender';
+import { FunctionNode, LogNode, TreeNode } from '../../../../../src/cmds/query/queries/tree';
+
+function logNode(overrides: Partial<LogNode> = {}): LogNode {
+  return {
+    kind: 'log',
+    event_id: 5,
+    parent_event_id: 1,
+    thread_id: null,
+    depth: 1,
+    fqid: 'app/AppLogger#error',
+    logger: 'AppLogger',
+    method_id: 'error',
+    path: 'app/log.rb',
+    lineno: 12,
+    elapsed_ms: 0.1,
+    message: 'connection refused',
+    parameters_json: JSON.stringify([
+      { name: 'message', class: 'String', value: 'connection refused' },
+    ]),
+    return_value: null,
+    ...overrides,
+  };
+}
+
+describe('renderTree (log lines)', () => {
+  it('renders a log node with its projected message inline', () => {
+    const out = renderTree([logNode()] as TreeNode[]);
+    expect(out).toContain('LOG');
+    expect(out).toContain('AppLogger.error');
+    expect(out).toContain('connection refused');
+  });
+
+  it('respects the indentation of the log node depth', () => {
+    const out = renderTree([logNode({ depth: 3 })] as TreeNode[]);
+    // 3 levels of two-space indent = 6 leading spaces.
+    expect(out.startsWith('      LOG')).toBe(true);
+  });
+
+  it('falls back to logger.method when no message can be projected', () => {
+    const out = renderTree([
+      logNode({ parameters_json: null, return_value: null }),
+    ] as TreeNode[]);
+    // No trailing colon when message is empty.
+    expect(out).toMatch(/LOG\s+AppLogger\.error\s*$/);
+  });
+
+  it('uses a structured return_value when present', () => {
+    const out = renderTree([
+      logNode({
+        parameters_json: null,
+        return_value: JSON.stringify({ level: 'error', message: 'from return' }),
+      }),
+    ] as TreeNode[]);
+    expect(out).toContain('AppLogger.error: from return');
+  });
+});
+
+describe('renderFlat (log lines)', () => {
+  it('emits a LOG row when filtering down to log nodes', () => {
+    const out = renderFlat([logNode()] as TreeNode[]);
+    expect(out).toMatch(/^LOG\s+AppLogger\.error: connection refused$/);
+  });
+});
+
+// Helper to build a synthetic function-node tree.  Each node is a CALL
+// with predictable depth + parent linkage so byte budgets are easy to
+// reason about.
+function fn(
+  event_id: number,
+  depth: number,
+  parent_event_id: number | null,
+  fqid = `app/Foo#m${event_id}`
+): FunctionNode {
+  return {
+    kind: 'function',
+    event_id,
+    parent_event_id,
+    thread_id: 1,
+    depth,
+    fqid,
+    defined_class: 'app/Foo',
+    method_id: `m${event_id}`,
+    path: 'app/foo.rb',
+    lineno: 10,
+    is_static: false,
+    elapsed_ms: 0.1,
+    parameters_json: null,
+    return_value: null,
+  };
+}
+
+describe('renderTreeForMcp (dense per-event lines)', () => {
+  it('prefixes each line with #event_id and includes file:line', () => {
+    const out = renderTreeForMcp([fn(42, 0, null)] as TreeNode[]);
+    expect(out).toMatch(/^#42 CALL {2}app\/Foo#m42 \(app\/foo\.rb:10\) \[/);
+  });
+});
+
+describe('renderTreeForMcpBudgeted', () => {
+  it('returns an empty result on empty input', () => {
+    const r = renderTreeForMcpBudgeted([], 1000);
+    expect(r).toEqual({
+      tree: '',
+      rendered_events: 0,
+      clipped_events: 0,
+      clipped_bytes: 0,
+      cutoff_depth: -1,
+      partial_depth: -1,
+      bytes_used: 0,
+    });
+  });
+
+  it('renders the full tree when the budget is generous', () => {
+    // root → child → grandchild
+    const nodes: TreeNode[] = [fn(1, 0, null), fn(2, 1, 1), fn(3, 2, 2)];
+    const r = renderTreeForMcpBudgeted(nodes, 10_000);
+    expect(r.rendered_events).toBe(3);
+    expect(r.clipped_events).toBe(0);
+    expect(r.tree.split('\n')).toHaveLength(3);
+    expect(r.tree).not.toMatch(/\[clipped:/);
+    expect(r.bytes_used).toBeLessThanOrEqual(10_000);
+  });
+
+  // Budget enforcement is approximate: clip-marker bytes emitted at
+  // cut sites can push `bytes_used` over `budget` by O(markers ×
+  // ~80B).  Tests assert <= budget + slop rather than exact equality.
+  const BUDGET_SLOP = 300;
+
+  it('fills breadth-first: completes a depth before descending', () => {
+    // Two roots, each with two children.  A budget tight enough to
+    // exclude depth 1 should keep both depth-0 roots and clip both
+    // subtrees at depth 1.
+    const nodes: TreeNode[] = [
+      fn(1, 0, null),
+      fn(2, 0, null),
+      fn(3, 1, 1),
+      fn(4, 1, 1),
+      fn(5, 1, 2),
+      fn(6, 1, 2),
+    ];
+    // Budget covers depth 0 (2 events × ~43B + 2 markers × 80B ≈ 246B)
+    // but won't fit all of depth 1 — so cutoff=0 and depth 1 partial-fills.
+    const r = renderTreeForMcpBudgeted(nodes, 250);
+    expect(r.cutoff_depth).toBe(0);
+    // Both depth-0 roots are rendered (breadth-first guarantee).
+    expect(r.tree).toMatch(/#1 CALL/);
+    expect(r.tree).toMatch(/#2 CALL/);
+    // At least some depth-1 events get clipped (the budget can't fit
+    // them all even after partial fill).
+    expect(r.clipped_events).toBeGreaterThan(0);
+    expect(r.clipped_events).toBeLessThanOrEqual(4);
+    const clipMarkers = r.tree.match(/\[clipped:/g) ?? [];
+    expect(clipMarkers.length).toBeGreaterThan(0);
+    expect(r.bytes_used).toBeLessThanOrEqual(250 + BUDGET_SLOP);
+  });
+
+  it('partial-fills cutoff+1 in event_id order until the budget is used', () => {
+    // Single root with 4 grandchildren spread across two children.  A
+    // budget that fits all of depth ≤ 1 plus a few — but not all — of
+    // depth 2 should produce a non-empty partial_depth.
+    const nodes: TreeNode[] = [
+      fn(1, 0, null),
+      fn(2, 1, 1),
+      fn(3, 1, 1),
+      fn(4, 2, 2),
+      fn(5, 2, 2),
+      fn(6, 2, 3),
+      fn(7, 2, 3),
+    ];
+    // Budget covers depth ≤ 1 lines (~133B) + 2-marker reserve (~160B)
+    // → cutoff fits at d=1.  Residual after rendering depth-≤1 = ~167B,
+    // enough for some depth-2 events (~47B each) but not all.
+    const r = renderTreeForMcpBudgeted(nodes, 300);
+    expect(r.cutoff_depth).toBe(1);
+    expect(r.partial_depth).toBe(2);
+    // Rendered count is between the depth-≤1 events (3) and full (7).
+    expect(r.rendered_events).toBeGreaterThan(3);
+    expect(r.rendered_events).toBeLessThan(7);
+    expect(r.clipped_events).toBe(7 - r.rendered_events);
+    expect(r.bytes_used).toBeLessThanOrEqual(300 + BUDGET_SLOP);
+  });
+
+  it('emits clip markers only at direct cut sites, not at every ancestor', () => {
+    // Linear chain: 1 → 2 → 3 → 4 → 5 with a budget that admits 1..3
+    // and clips 4 (and transitively 5).  We expect exactly one marker
+    // (under #3) rather than one at every rendered ancestor.
+    const nodes: TreeNode[] = [
+      fn(1, 0, null),
+      fn(2, 1, 1),
+      fn(3, 2, 2),
+      fn(4, 3, 3),
+      fn(5, 4, 4),
+    ];
+    const r = renderTreeForMcpBudgeted(nodes, 220);
+    expect(r.cutoff_depth).toBe(2);
+    const clipMarkers = r.tree.match(/\[clipped:/g) ?? [];
+    expect(clipMarkers).toHaveLength(1);
+    expect(r.tree).toMatch(/focus on #3/);
+  });
+
+  it('renders at least one root even when the budget is too small for depth 0', () => {
+    const nodes: TreeNode[] = [fn(1, 0, null), fn(2, 0, null), fn(3, 1, 1)];
+    const r = renderTreeForMcpBudgeted(nodes, 10);
+    // Best-effort first root, everything else clipped.
+    expect(r.rendered_events).toBe(1);
+    expect(r.clipped_events).toBe(2);
+  });
+
+  it('dedupes nodes that share an event_id (function + exception)', () => {
+    // The tree query emits one row per kind, so a function that threw
+    // an exception appears twice with the same event_id.  The budgeted
+    // renderer should treat them as one logical node.
+    const dupe: TreeNode[] = [
+      fn(1, 0, null),
+      fn(2, 1, 1),
+      {
+        kind: 'exception',
+        event_id: 2,
+        parent_event_id: 1,
+        thread_id: 1,
+        depth: 1,
+        exception_class: 'BoomError',
+        message: 'kaboom',
+        path: 'app/foo.rb',
+        lineno: 10,
+      },
+    ];
+    const r = renderTreeForMcpBudgeted(dupe, 10_000);
+    // 2 logical nodes; only one #2 mention; no clipping.
+    expect(r.rendered_events).toBe(2);
+    expect(r.clipped_events).toBe(0);
+    const mentions = r.tree.match(/#2 /g) ?? [];
+    expect(mentions).toHaveLength(1);
+  });
+
+  it('records cumulative clipped_bytes from unrendered events', () => {
+    const nodes: TreeNode[] = [fn(1, 0, null), fn(2, 1, 1), fn(3, 1, 1)];
+    const r = renderTreeForMcpBudgeted(nodes, 100);
+    expect(r.clipped_events).toBeGreaterThan(0);
+    expect(r.clipped_bytes).toBeGreaterThan(0);
+  });
+});
+
+describe('truncateStructValue', () => {
+  // A real Java-record toString() where the budget-eating fields (two
+  // UUIDs) precede the state fields an RCA actually needs.
+  const APPROVAL_REQUEST =
+    'ApprovalRequest[requestId=d179dbbd-cc67-4384-a97f-36fd9eeedeb2, ' +
+    'loanId=LOAN-05dae83b-cc16-4bbe-b693-debf65e49556, ' +
+    'borrowerId=b1ffffff-aaaa-bbbb-cccc-123456789012, ' +
+    'status=APPROVED, requiredAuthority=RELATIONSHIP_MANAGER]';
+
+  it('clips id-shaped values hard so trailing state fields survive', () => {
+    const out = truncateStructValue(APPROVAL_REQUEST);
+    // The downstream state fields — the whole point — are intact.
+    expect(out).toContain('status=APPROVED');
+    expect(out).toContain('requiredAuthority=RELATIONSHIP_MANAGER');
+    // UUID values are clipped to the tight idCap, not shown in full.
+    expect(out).not.toContain('36fd9eeedeb2');
+    expect(out).toContain('requestId=d179dbbd-cc…');
+    // Field names are always kept whole.
+    expect(out).toContain('borrowerId=');
+  });
+
+  it('keeps short non-id values whole within perValueCap', () => {
+    const out = truncateStructValue('ConsumeResult[allowed=true, remaining=149, limit=150]');
+    expect(out).toBe('ConsumeResult[allowed=true, remaining=149, limit=150]');
+  });
+
+  it('parses Java bean { } shape', () => {
+    const out = truncateStructValue('Account{id=42, balance=100.00}');
+    expect(out).toBe('Account{id=42, balance=100.00}');
+  });
+
+  it('parses Python dataclass repr ( ) shape', () => {
+    const out = truncateStructValue('Order(id=7, total=10, status=OPEN)');
+    expect(out).toContain('Order(');
+    expect(out).toContain('status=OPEN');
+  });
+
+  it('parses Ruby #<...> shape with colon-separated fields', () => {
+    const out = truncateStructValue('#<Order id: 5, total: 10, paid: true>');
+    expect(out).toContain('#<Order ');
+    expect(out).toContain('paid: true');
+    expect(out).toMatch(/>$/);
+  });
+
+  it('does not split on commas nested inside a field value', () => {
+    // `lines` value carries inner commas; they must not produce extra fields.
+    const out = truncateStructValue('Order[id=1, lines=[Line[a, b], Line[c, d]], note=ok]');
+    // `note=ok` only survives if the inner commas were treated as nested.
+    expect(out).toContain('note=ok');
+    expect(out).toContain('lines=[Line[a, b]');
+  });
+
+  it('recurses into a collection of structs so each element keeps its fields', () => {
+    // A getParticipants-style return: a bare list of records. Flat-clipping
+    // each element (it contains a UUID) would collapse it to a stub; the
+    // per-element status must survive.
+    const out = truncateStructValue(
+      '[ParticipantState[partyId=PID-ced84ce5-2001-4994-b50d-8ee47724edf4, share=0.20, status=PENDING], ' +
+        'ParticipantState[partyId=PID-5bfa9c9d-2ca6-4dcc-be60-93b86a3cf0ad, share=0.10, status=COMMITTED]]'
+    );
+    expect(out).toContain('status=PENDING');
+    expect(out).toContain('status=COMMITTED');
+    expect(out).not.toContain('8ee47724edf4'); // UUID tail clipped
+  });
+
+  it('recurses into a struct-valued field', () => {
+    const out = truncateStructValue(
+      'Result[ok=true, detail=Detail[code=E_PREFLIGHT, retriable=false]]'
+    );
+    expect(out).toContain('detail=Detail[code=E_PREFLIGHT');
+    expect(out).toContain('retriable=false');
+  });
+
+  it('elides the field tail past maxFields', () => {
+    const budget: StructBudget = { perValueCap: 48, idCap: 12, maxFields: 2, flatCap: 120 };
+    const out = truncateStructValue('T[a=1, b=2, c=3, d=4]', budget);
+    expect(out).toContain('a=1');
+    expect(out).toContain('b=2');
+    expect(out).not.toContain('c=3');
+    expect(out).toContain('…+2 more');
+    expect(out).toMatch(/]$/);
+  });
+
+  it('falls back to a flat cap for non-struct values', () => {
+    expect(truncateStructValue('USD 7000000.00')).toBe('USD 7000000.00');
+    expect(truncateStructValue('true')).toBe('true');
+    // `[object Object]` and `Type@1a2b3c` are opaque — no fields to budget.
+    expect(truncateStructValue('java.lang.Object@1a2b3c4')).toBe('java.lang.Object@1a2b3c4');
+    const long = 'x'.repeat(400);
+    const out = truncateStructValue(long);
+    expect(out.length).toBe(120);
+    expect(out.endsWith('…')).toBe(true);
+  });
+
+  it('handles an empty struct body', () => {
+    expect(truncateStructValue('EmptyRecord[]')).toBe('EmptyRecord[]');
+  });
+});
+
+describe('renderTreeForMcp (return values)', () => {
+  it('renders a struct return value through the per-field budget', () => {
+    const node: FunctionNode = {
+      ...fn(1, 0, null),
+      return_value:
+        'ApprovalRequest[requestId=d179dbbd-cc67-4384-a97f-36fd9eeedeb2, ' +
+        'status=APPROVED, requiredAuthority=RELATIONSHIP_MANAGER]',
+    };
+    const out = renderTreeForMcp([node] as TreeNode[]);
+    expect(out).toContain('→ ApprovalRequest[');
+    expect(out).toContain('status=APPROVED');
+    expect(out).toContain('requiredAuthority=RELATIONSHIP_MANAGER');
+    expect(out).not.toContain('36fd9eeedeb2');
+  });
+});
diff --git a/packages/cli/tests/unit/cmds/query/queries/compare.spec.ts b/packages/cli/tests/unit/cmds/query/queries/compare.spec.ts
new file mode 100644
index 0000000000..b9a1800be2
--- /dev/null
+++ b/packages/cli/tests/unit/cmds/query/queries/compare.spec.ts
@@ -0,0 +1,133 @@
+import sqlite3 from 'better-sqlite3';
+
+import { openQueryDb } from '../../../../../src/cmds/query/db/openQueryDb';
+import { compare } from '../../../../../src/cmds/query/queries/compare';
+
+function freshDb(): sqlite3.Database {
+  return openQueryDb('/tmp/ignored', ':memory:').db;
+}
+
+interface SeedReq {
+  branch: string;
+  method: string;
+  path: string;
+  status: number;
+  elapsed_ms?: number;
+}
+
+let nextEvent = 1;
+function seed(db: sqlite3.Database, reqs: SeedReq[]): void {
+  const insAm = db.prepare(
+    `INSERT INTO appmaps (name, source_path, git_branch, timestamp) VALUES (?, ?, ?, ?)`
+  );
+  const insReq = db.prepare(
+    `INSERT INTO http_requests (appmap_id, event_id, method, path, status_code, elapsed_ms)
+     VALUES (?, ?, ?, ?, ?, ?)`
+  );
+  for (let i = 0; i < reqs.length; i++) {
+    const r = reqs[i];
+    const am = insAm.run(
+      `rec-${i}`,
+      `/tmp/rec-${i}.appmap.json`,
+      r.branch,
+      '2026-04-29T12:00:00.000Z'
+    );
+    insReq.run(
+      am.lastInsertRowid,
+      nextEvent++,
+      r.method,
+      r.path,
+      r.status,
+      r.elapsed_ms ?? null
+    );
+  }
+}
+
+describe('compare', () => {
+  beforeEach(() => {
+    nextEvent = 1;
+  });
+
+  it('reports a per-route delta = b_p95 / a_p95', () => {
+    const db = freshDb();
+    try {
+      // Same route on both branches: main is fast, feature is slow.
+      seed(db, [
+        { branch: 'main', method: 'GET', path: '/reports', status: 200, elapsed_ms: 200 },
+        { branch: 'main', method: 'GET', path: '/reports', status: 200, elapsed_ms: 210 },
+        { branch: 'feat', method: 'GET', path: '/reports', status: 200, elapsed_ms: 6000 },
+        { branch: 'feat', method: 'GET', path: '/reports', status: 200, elapsed_ms: 6100 },
+      ]);
+      const rows = compare(db, { branch_a: 'main', branch_b: 'feat' }).rows;
+      expect(rows).toHaveLength(1);
+      const r = rows[0];
+      expect(r.method).toBe('GET');
+      expect(r.route).toBe('/reports');
+      expect(r.delta).not.toBeNull();
+      // ~30× slowdown
+      expect(r.delta!).toBeGreaterThan(20);
+    } finally {
+      db.close();
+    }
+  });
+
+  it('preserves routes that exist on only one side', () => {
+    const db = freshDb();
+    try {
+      seed(db, [
+        { branch: 'main', method: 'GET', path: '/old', status: 200, elapsed_ms: 100 },
+        { branch: 'feat', method: 'GET', path: '/new', status: 200, elapsed_ms: 50 },
+      ]);
+      const rows = compare(db, { branch_a: 'main', branch_b: 'feat' }).rows;
+      const old = rows.find((r) => r.route === '/old')!;
+      const fresh = rows.find((r) => r.route === '/new')!;
+      expect(old.a_p95_ms).toBe(100);
+      expect(old.b_p95_ms).toBeNull();
+      expect(old.delta).toBeNull();
+      expect(fresh.a_p95_ms).toBeNull();
+      expect(fresh.b_p95_ms).toBe(50);
+      expect(fresh.delta).toBeNull();
+    } finally {
+      db.close();
+    }
+  });
+
+  it('--sort=delta puts the biggest absolute change first (in either direction)', () => {
+    const db = freshDb();
+    try {
+      seed(db, [
+        // /a: 10× slowdown
+        { branch: 'main', method: 'GET', path: '/a', status: 200, elapsed_ms: 100 },
+        { branch: 'feat', method: 'GET', path: '/a', status: 200, elapsed_ms: 1000 },
+        // /b: 5× speedup
+        { branch: 'main', method: 'GET', path: '/b', status: 200, elapsed_ms: 500 },
+        { branch: 'feat', method: 'GET', path: '/b', status: 200, elapsed_ms: 100 },
+        // /c: ~unchanged
+        { branch: 'main', method: 'GET', path: '/c', status: 200, elapsed_ms: 100 },
+        { branch: 'feat', method: 'GET', path: '/c', status: 200, elapsed_ms: 105 },
+      ]);
+      const rows = compare(db, { branch_a: 'main', branch_b: 'feat', sort: 'delta' }).rows;
+      // /a (10×) and /b (1/5×) have the largest log-delta; /c last.
+      expect(rows[rows.length - 1].route).toBe('/c');
+    } finally {
+      db.close();
+    }
+  });
+
+  it('--limit caps the result set', () => {
+    const db = freshDb();
+    try {
+      seed(db, [
+        { branch: 'main', method: 'GET', path: '/a', status: 200, elapsed_ms: 100 },
+        { branch: 'main', method: 'GET', path: '/b', status: 200, elapsed_ms: 100 },
+        { branch: 'feat', method: 'GET', path: '/a', status: 200, elapsed_ms: 100 },
+        { branch: 'feat', method: 'GET', path: '/b', status: 200, elapsed_ms: 100 },
+      ]);
+      expect(
+        compare(db, { branch_a: 'main', branch_b: 'feat', limit: 1 }).rows
+      ).toHaveLength(1);
+    } finally {
+      db.close();
+    }
+  });
+});
diff --git a/packages/cli/tests/unit/cmds/query/queries/endpoints.spec.ts b/packages/cli/tests/unit/cmds/query/queries/endpoints.spec.ts
new file mode 100644
index 0000000000..f166e69850
--- /dev/null
+++ b/packages/cli/tests/unit/cmds/query/queries/endpoints.spec.ts
@@ -0,0 +1,245 @@
+import sqlite3 from 'better-sqlite3';
+
+import { openQueryDb } from '../../../../../src/cmds/query/db/openQueryDb';
+import { endpoints } from '../../../../../src/cmds/query/queries/endpoints';
+
+function freshDb(): sqlite3.Database {
+  return openQueryDb('/tmp/ignored', ':memory:').db;
+}
+
+interface SeedReq {
+  method: string;
+  path: string;
+  normalized_path?: string;
+  status: number;
+  elapsed_ms: number | null;
+  timestamp?: string;
+  branch?: string;
+}
+
+let nextEvent = 1;
+function seed(db: sqlite3.Database, reqs: SeedReq[]): void {
+  const insertAppmap = db.prepare(
+    `INSERT INTO appmaps (name, source_path, git_branch, timestamp) VALUES (?, ?, ?, ?)`
+  );
+  const insertReq = db.prepare(
+    `INSERT INTO http_requests (appmap_id, event_id, method, path, normalized_path,
+       status_code, elapsed_ms)
+     VALUES (?, ?, ?, ?, ?, ?, ?)`
+  );
+  for (let i = 0; i < reqs.length; i++) {
+    const r = reqs[i];
+    const ts = r.timestamp ?? '2026-04-29T12:00:00.000Z';
+    const am = insertAppmap.run(
+      `rec-${i}`,
+      `/tmp/rec-${i}.appmap.json`,
+      r.branch ?? null,
+      ts
+    );
+    insertReq.run(
+      am.lastInsertRowid,
+      nextEvent++,
+      r.method,
+      r.path,
+      r.normalized_path ?? null,
+      r.status,
+      r.elapsed_ms
+    );
+  }
+}
+
+describe('endpoints', () => {
+  beforeEach(() => {
+    nextEvent = 1;
+  });
+
+  it('returns an empty array when there are no requests', () => {
+    const db = freshDb();
+    try {
+      expect(endpoints(db).rows).toEqual([]);
+    } finally {
+      db.close();
+    }
+  });
+
+  it('groups by (method, route) and counts', () => {
+    const db = freshDb();
+    try {
+      seed(db, [
+        { method: 'GET', path: '/x', status: 200, elapsed_ms: 100 },
+        { method: 'GET', path: '/x', status: 200, elapsed_ms: 200 },
+        { method: 'POST', path: '/x', status: 201, elapsed_ms: 150 },
+      ]);
+      const out = endpoints(db).rows;
+      const get = out.find((r) => r.method === 'GET');
+      const post = out.find((r) => r.method === 'POST');
+      expect(get?.count).toBe(2);
+      expect(post?.count).toBe(1);
+      expect(out).toHaveLength(2);
+    } finally {
+      db.close();
+    }
+  });
+
+  it('uses normalized_path when present, otherwise raw path', () => {
+    const db = freshDb();
+    try {
+      seed(db, [
+        { method: 'GET', path: '/orders/42', normalized_path: '/orders/:id', status: 200, elapsed_ms: 100 },
+        { method: 'GET', path: '/orders/99', normalized_path: '/orders/:id', status: 200, elapsed_ms: 200 },
+        { method: 'GET', path: '/raw-only', status: 200, elapsed_ms: 50 },
+      ]);
+      const out = endpoints(db).rows;
+      expect(out.find((r) => r.route === '/orders/:id')?.count).toBe(2);
+      expect(out.find((r) => r.route === '/raw-only')?.count).toBe(1);
+    } finally {
+      db.close();
+    }
+  });
+
+  it('computes avg, p95, and err_pct', () => {
+    const db = freshDb();
+    try {
+      // 10 requests on /x: 9 with status 200 / elapsed [10,20,...,90], 1 with status 500 / elapsed 1000.
+      const reqs: SeedReq[] = [];
+      for (let i = 1; i <= 9; i++) {
+        reqs.push({ method: 'GET', path: '/x', status: 200, elapsed_ms: i * 10 });
+      }
+      reqs.push({ method: 'GET', path: '/x', status: 500, elapsed_ms: 1000 });
+      seed(db, reqs);
+
+      const row = endpoints(db).rows.find((r) => r.route === '/x')!;
+      expect(row.count).toBe(10);
+      expect(row.err_pct).toBeCloseTo(10);
+      expect(row.avg_ms).toBeCloseTo((10 + 20 + 30 + 40 + 50 + 60 + 70 + 80 + 90 + 1000) / 10);
+      // sorted [10,20,...,90,1000]; p95 = ceil(0.95 * 10) - 1 = 9 → idx 9 → 1000
+      expect(row.p95_ms).toBe(1000);
+    } finally {
+      db.close();
+    }
+  });
+
+  it('--status filter shows only routes with at least one matching response, but counts remain over all', () => {
+    const db = freshDb();
+    try {
+      seed(db, [
+        { method: 'GET', path: '/quiet', status: 200, elapsed_ms: 50 },
+        { method: 'GET', path: '/quiet', status: 200, elapsed_ms: 60 },
+        { method: 'POST', path: '/orders', status: 201, elapsed_ms: 100 },
+        { method: 'POST', path: '/orders', status: 201, elapsed_ms: 110 },
+        { method: 'POST', path: '/orders', status: 500, elapsed_ms: 520 },
+      ]);
+      const out = endpoints(db, { status: { op: '>=', value: 500 } }).rows;
+      // /quiet has no 5xx → excluded.
+      // /orders has one 5xx → included; count=3, err_pct=33%.
+      expect(out).toHaveLength(1);
+      const row = out[0];
+      expect(row.route).toBe('/orders');
+      expect(row.count).toBe(3);
+      expect(row.err_pct).toBeCloseTo((1 / 3) * 100);
+    } finally {
+      db.close();
+    }
+  });
+
+  it('filters by branch', () => {
+    const db = freshDb();
+    try {
+      seed(db, [
+        { method: 'GET', path: '/x', status: 200, elapsed_ms: 100, branch: 'main' },
+        { method: 'GET', path: '/y', status: 200, elapsed_ms: 100, branch: 'feature' },
+      ]);
+      expect(endpoints(db, { branch: 'main' }).rows).toHaveLength(1);
+      expect(endpoints(db, { branch: 'main' }).rows[0].route).toBe('/x');
+    } finally {
+      db.close();
+    }
+  });
+
+  it('filters by since/until', () => {
+    const db = freshDb();
+    try {
+      seed(db, [
+        { method: 'GET', path: '/x', status: 200, elapsed_ms: 100, timestamp: '2026-04-01T00:00:00.000Z' },
+        { method: 'GET', path: '/x', status: 200, elapsed_ms: 100, timestamp: '2026-04-15T00:00:00.000Z' },
+        { method: 'GET', path: '/x', status: 200, elapsed_ms: 100, timestamp: '2026-04-30T00:00:00.000Z' },
+      ]);
+      expect(endpoints(db, { since: '2026-04-10T00:00:00.000Z' }).rows[0].count).toBe(2);
+      expect(
+        endpoints(db, {
+          since: '2026-04-10T00:00:00.000Z',
+          until: '2026-04-20T00:00:00.000Z',
+        }).rows[0].count
+      ).toBe(1);
+    } finally {
+      db.close();
+    }
+  });
+
+  it('sorts by the requested key', () => {
+    const db = freshDb();
+    try {
+      seed(db, [
+        { method: 'GET', path: '/a', status: 200, elapsed_ms: 100 },
+        { method: 'GET', path: '/b', status: 200, elapsed_ms: 50 },
+        { method: 'GET', path: '/b', status: 200, elapsed_ms: 50 },
+        { method: 'GET', path: '/c', status: 500, elapsed_ms: 20 },
+        { method: 'GET', path: '/d', status: 200, elapsed_ms: 200 },
+      ]);
+      const byCount = endpoints(db, { sort: 'count' }).rows.map((r) => r.route);
+      expect(byCount[0]).toBe('/b'); // count 2
+      const byErr = endpoints(db, { sort: 'err' }).rows.map((r) => r.route);
+      expect(byErr[0]).toBe('/c'); // 100% err
+      const byAvg = endpoints(db, { sort: 'avg' }).rows.map((r) => r.route);
+      expect(byAvg[0]).toBe('/d'); // 200ms avg
+      const byP95 = endpoints(db, { sort: 'p95' }).rows.map((r) => r.route);
+      expect(byP95[0]).toBe('/d'); // 200ms p95
+    } finally {
+      db.close();
+    }
+  });
+
+  it('sorts nulls last (a route with no measured duration ranks below a real 0)', () => {
+    const db = freshDb();
+    try {
+      seed(db, [
+        { method: 'GET', path: '/measured', status: 200, elapsed_ms: 0 },
+        { method: 'GET', path: '/unmeasured', status: 200, elapsed_ms: null },
+      ]);
+      const byP95 = endpoints(db, { sort: 'p95' }).rows.map((r) => r.route);
+      expect(byP95).toEqual(['/measured', '/unmeasured']);
+    } finally {
+      db.close();
+    }
+  });
+
+  it('limits the result set', () => {
+    const db = freshDb();
+    try {
+      seed(db, [
+        { method: 'GET', path: '/a', status: 200, elapsed_ms: 100 },
+        { method: 'GET', path: '/b', status: 200, elapsed_ms: 100 },
+        { method: 'GET', path: '/c', status: 200, elapsed_ms: 100 },
+      ]);
+      expect(endpoints(db, { limit: 2 }).rows).toHaveLength(2);
+    } finally {
+      db.close();
+    }
+  });
+
+  it('handles null elapsed_ms (avg and p95 derived from non-null values only)', () => {
+    const db = freshDb();
+    try {
+      seed(db, [
+        { method: 'GET', path: '/x', status: 200, elapsed_ms: 100 },
+        { method: 'GET', path: '/x', status: 200, elapsed_ms: null },
+      ]);
+      const row = endpoints(db).rows[0];
+      expect(row.count).toBe(2);
+      expect(row.avg_ms).toBe(100);
+      expect(row.p95_ms).toBe(100);
+    } finally {
+      db.close();
+    }
+  });
+});
diff --git a/packages/cli/tests/unit/cmds/query/queries/find.spec.ts b/packages/cli/tests/unit/cmds/query/queries/find.spec.ts
new file mode 100644
index 0000000000..ff6fb9a2d2
--- /dev/null
+++ b/packages/cli/tests/unit/cmds/query/queries/find.spec.ts
@@ -0,0 +1,1114 @@
+import sqlite3 from 'better-sqlite3';
+
+import { openQueryDb } from '../../../../../src/cmds/query/db/openQueryDb';
+import {
+  findAppmaps,
+  findCalls,
+  findExceptions,
+  findLogs,
+  findQueries,
+  findRequests,
+} from '../../../../../src/cmds/query/queries/find';
+
+function freshDb(): sqlite3.Database {
+  return openQueryDb('/tmp/ignored', ':memory:').db;
+}
+
+interface Recording {
+  name: string;
+  branch?: string;
+  commit?: string;
+  timestamp?: string;
+  requests?: {
+    event_id: number;
+    method: string;
+    path: string;
+    normalized_path?: string;
+    status: number;
+    elapsed_ms?: number;
+  }[];
+  queries?: {
+    event_id: number;
+    parent_event_id?: number;
+    sql: string;
+    caller_class?: string;
+    caller_method?: string;
+    elapsed_ms?: number;
+  }[];
+  calls?: {
+    event_id: number;
+    parent_event_id?: number;
+    defined_class: string;
+    method_id: string;
+    elapsed_ms?: number;
+    fqid?: string;
+    labels?: string[];
+    parameters?: { name: string; class?: string; value: unknown }[];
+    return_value?: unknown;
+  }[];
+  exceptions?: {
+    event_id: number;
+    exception_class: string;
+    message?: string;
+  }[];
+}
+
+function seed(db: sqlite3.Database, recs: Recording[]): void {
+  const insAm = db.prepare(
+    `INSERT INTO appmaps (name, source_path, git_branch, git_commit, timestamp, sql_query_count, elapsed_ms)
+     VALUES (?, ?, ?, ?, ?, ?, ?)`
+  );
+  const insReq = db.prepare(
+    `INSERT INTO http_requests (appmap_id, event_id, method, path, normalized_path, status_code, elapsed_ms)
+     VALUES (?, ?, ?, ?, ?, ?, ?)`
+  );
+  const insQ = db.prepare(
+    `INSERT INTO sql_queries (appmap_id, event_id, parent_event_id, sql_text,
+       caller_class, caller_method, elapsed_ms)
+     VALUES (?, ?, ?, ?, ?, ?, ?)`
+  );
+  // Test seed: derive package + class chain from defined_class so call
+  // sites don't have to specify them. defined_class may be Java dot-form
+  // ("org.example.Foo"), in which case we treat the trailing segment as
+  // the leaf class and the rest as a slash-form package.
+  const insCo = db.prepare(
+    `INSERT OR IGNORE INTO code_objects (fqid, package, classes, leaf_class, method, is_static)
+     VALUES (?, ?, ?, ?, ?, ?)`
+  );
+  const selCoId = db.prepare(`SELECT id FROM code_objects WHERE fqid = ?`);
+  const insLabel = db.prepare(
+    `INSERT OR IGNORE INTO labels (code_object_id, label) VALUES (?, ?)`
+  );
+  const insCall = db.prepare(
+    `INSERT INTO function_calls (appmap_id, event_id, parent_event_id, defined_class, method_id,
+       code_object_id, elapsed_ms, parameters_json, return_value)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`
+  );
+  const insExc = db.prepare(
+    `INSERT INTO exceptions (appmap_id, event_id, exception_class, message)
+     VALUES (?, ?, ?, ?)`
+  );
+
+  for (const r of recs) {
+    const sqlCount = r.queries?.length ?? 0;
+    const am = insAm.run(
+      r.name,
+      `/tmp/${r.name}.appmap.json`,
+      r.branch ?? null,
+      r.commit ?? null,
+      r.timestamp ?? '2026-04-29T12:00:00.000Z',
+      sqlCount,
+      r.requests?.[0]?.elapsed_ms ?? null
+    );
+    const aid = am.lastInsertRowid;
+    for (const req of r.requests ?? []) {
+      insReq.run(
+        aid,
+        req.event_id,
+        req.method,
+        req.path,
+        req.normalized_path ?? null,
+        req.status,
+        req.elapsed_ms ?? null
+      );
+    }
+    for (const q of r.queries ?? []) {
+      insQ.run(
+        aid,
+        q.event_id,
+        q.parent_event_id ?? null,
+        q.sql,
+        q.caller_class ?? null,
+        q.caller_method ?? null,
+        q.elapsed_ms ?? null
+      );
+    }
+    for (const c of r.calls ?? []) {
+      const fqid = c.fqid ?? `${c.defined_class}#${c.method_id}`;
+      const dotIdx = c.defined_class.lastIndexOf('.');
+      const pkg = dotIdx >= 0 ? c.defined_class.slice(0, dotIdx).replace(/\./g, '/') : '';
+      const leaf = dotIdx >= 0 ? c.defined_class.slice(dotIdx + 1) : c.defined_class;
+      insCo.run(fqid, pkg, JSON.stringify([leaf]), leaf, c.method_id, 0);
+      const coId = (selCoId.get(fqid) as { id: number }).id;
+      for (const label of c.labels ?? []) insLabel.run(coId, label);
+      const paramsJson = c.parameters ? JSON.stringify(c.parameters) : null;
+      const returnVal =
+        c.return_value === undefined
+          ? null
+          : typeof c.return_value === 'string'
+            ? c.return_value
+            : JSON.stringify(c.return_value);
+      insCall.run(
+        aid,
+        c.event_id,
+        c.parent_event_id ?? null,
+        c.defined_class,
+        c.method_id,
+        coId,
+        c.elapsed_ms ?? null,
+        paramsJson,
+        returnVal
+      );
+    }
+    for (const e of r.exceptions ?? []) {
+      insExc.run(aid, e.event_id, e.exception_class, e.message ?? null);
+    }
+  }
+}
+
+describe('findRequests', () => {
+  it('filters by route, method, status, duration, branch', () => {
+    const db = freshDb();
+    try {
+      seed(db, [
+        {
+          name: 'a',
+          branch: 'main',
+          requests: [
+            { event_id: 1, method: 'GET', path: '/orders/42', normalized_path: '/orders/:id', status: 200, elapsed_ms: 50 },
+            { event_id: 2, method: 'POST', path: '/orders', status: 500, elapsed_ms: 520 },
+          ],
+        },
+        {
+          name: 'b',
+          branch: 'feature',
+          requests: [{ event_id: 1, method: 'POST', path: '/orders', status: 500, elapsed_ms: 600 }],
+        },
+      ]);
+
+      // Method-prefixed route
+      const r1 = findRequests(db, { route: 'POST /orders' }).rows;
+      expect(r1).toHaveLength(2);
+      expect(r1.every((r) => r.method === 'POST' && r.route === '/orders')).toBe(true);
+
+      // Status filter
+      const r2 = findRequests(db, { status: { op: '>=', value: 500 } }).rows;
+      expect(r2).toHaveLength(2);
+
+      // Duration filter
+      const r3 = findRequests(db, { duration: { op: '>', value: 550 } }).rows;
+      expect(r3).toHaveLength(1);
+      expect(r3[0].appmap_name).toBe('b');
+
+      // Branch filter
+      const r4 = findRequests(db, { branch: 'feature' }).rows;
+      expect(r4).toHaveLength(1);
+      expect(r4[0].appmap_name).toBe('b');
+    } finally {
+      db.close();
+    }
+  });
+
+  it('--limit/--offset trims results', () => {
+    const db = freshDb();
+    try {
+      seed(db, [
+        {
+          name: 'a',
+          requests: [
+            { event_id: 1, method: 'GET', path: '/x', status: 200 },
+            { event_id: 2, method: 'GET', path: '/x', status: 200 },
+            { event_id: 3, method: 'GET', path: '/x', status: 200 },
+          ],
+        },
+      ]);
+      expect(findRequests(db, { limit: 2 }).rows).toHaveLength(2);
+      expect(findRequests(db, { limit: 2, offset: 1 }).rows[0].event_id).toBe(2);
+    } finally {
+      db.close();
+    }
+  });
+});
+
+describe('findAppmaps', () => {
+  it('returns one row per recording, sample request fields populated', () => {
+    const db = freshDb();
+    try {
+      seed(db, [
+        {
+          name: 'a',
+          branch: 'main',
+          requests: [
+            { event_id: 1, method: 'GET', path: '/x', status: 200, elapsed_ms: 100 },
+            { event_id: 2, method: 'POST', path: '/y', status: 500, elapsed_ms: 200 },
+          ],
+        },
+        { name: 'b', branch: 'feature' },
+      ]);
+      const rows = findAppmaps(db, {}).rows;
+      expect(rows).toHaveLength(2);
+      const a = rows.find((r) => r.appmap_name === 'a')!;
+      expect(a.route).toBe('/x'); // first request by event_id
+      expect(a.branch).toBe('main');
+      expect(rows.find((r) => r.appmap_name === 'b')?.route).toBeNull();
+    } finally {
+      db.close();
+    }
+  });
+
+  it('is deterministic when route filtering — picks the lowest event_id matching request', () => {
+    const db = freshDb();
+    try {
+      // Two POST /orders requests in one recording with different elapsed.
+      // The query must consistently pick event_id=1 (the smaller).
+      seed(db, [
+        {
+          name: 'a',
+          requests: [
+            { event_id: 1, method: 'POST', path: '/orders', status: 500, elapsed_ms: 100 },
+            { event_id: 2, method: 'POST', path: '/orders', status: 500, elapsed_ms: 999 },
+          ],
+        },
+      ]);
+      const rows = findAppmaps(db, { route: 'POST /orders' }).rows;
+      expect(rows).toHaveLength(1);
+      expect(rows[0].elapsed_ms).toBe(100); // event_id=1 wins, not 2
+    } finally {
+      db.close();
+    }
+  });
+
+  it('--duration filters on the appmap row (a.elapsed_ms)', () => {
+    const db = freshDb();
+    try {
+      seed(db, [
+        {
+          name: 'fast',
+          requests: [{ event_id: 1, method: 'GET', path: '/x', status: 200, elapsed_ms: 50 }],
+        },
+        {
+          name: 'slow',
+          requests: [{ event_id: 1, method: 'GET', path: '/x', status: 200, elapsed_ms: 5000 }],
+        },
+      ]);
+      const rows = findAppmaps(db, { duration: { op: '>', value: 1000 } }).rows;
+      expect(rows).toHaveLength(1);
+      expect(rows[0].appmap_name).toBe('slow');
+    } finally {
+      db.close();
+    }
+  });
+
+  it('--route narrows to recordings with a matching request and reports that request', () => {
+    const db = freshDb();
+    try {
+      seed(db, [
+        {
+          name: 'a',
+          requests: [
+            { event_id: 1, method: 'GET', path: '/x', status: 200 },
+            { event_id: 2, method: 'POST', path: '/orders', status: 500, elapsed_ms: 520 },
+          ],
+        },
+        { name: 'b', requests: [{ event_id: 1, method: 'GET', path: '/x', status: 200 }] },
+      ]);
+      const rows = findAppmaps(db, { route: 'POST /orders', status: { op: '>=', value: 500 } }).rows;
+      expect(rows).toHaveLength(1);
+      expect(rows[0].appmap_name).toBe('a');
+      expect(rows[0].route).toBe('/orders');
+      expect(rows[0].status_code).toBe(500);
+      expect(rows[0].elapsed_ms).toBe(520);
+    } finally {
+      db.close();
+    }
+  });
+});
+
+describe('findQueries', () => {
+  it('--table filters via SQL text LIKE; --status scopes via owning request', () => {
+    const db = freshDb();
+    try {
+      seed(db, [
+        {
+          name: 'a',
+          requests: [{ event_id: 1, method: 'POST', path: '/orders', status: 500 }],
+          queries: [
+            { event_id: 2, sql: 'INSERT INTO orders (...) VALUES (...)', elapsed_ms: 14 },
+            { event_id: 3, sql: 'SELECT * FROM users WHERE id = ?' },
+          ],
+        },
+        {
+          name: 'b',
+          requests: [{ event_id: 1, method: 'GET', path: '/x', status: 200 }],
+          queries: [{ event_id: 2, sql: 'INSERT INTO orders (...) VALUES (...)' }],
+        },
+      ]);
+      const rows = findQueries(db, { table: 'orders', status: { op: '>=', value: 500 } }).rows;
+      expect(rows).toHaveLength(1);
+      expect(rows[0].appmap_name).toBe('a');
+      expect(rows[0].sql_text).toContain('INSERT INTO orders');
+    } finally {
+      db.close();
+    }
+  });
+});
+
+describe('find filters: --commit, --since/--until, --duration', () => {
+  it('--commit on findRequests', () => {
+    const db = freshDb();
+    try {
+      seed(db, [
+        {
+          name: 'a',
+          commit: 'abc123',
+          requests: [{ event_id: 1, method: 'GET', path: '/x', status: 200 }],
+        },
+        {
+          name: 'b',
+          commit: 'def456',
+          requests: [{ event_id: 1, method: 'GET', path: '/y', status: 200 }],
+        },
+      ]);
+      const rows = findRequests(db, { commit: 'abc123' }).rows;
+      expect(rows).toHaveLength(1);
+      expect(rows[0].appmap_name).toBe('a');
+    } finally {
+      db.close();
+    }
+  });
+
+  it('--commit on findAppmaps', () => {
+    const db = freshDb();
+    try {
+      seed(db, [
+        { name: 'a', commit: 'abc' },
+        { name: 'b', commit: 'def' },
+      ]);
+      expect(findAppmaps(db, { commit: 'abc' }).rows).toHaveLength(1);
+    } finally {
+      db.close();
+    }
+  });
+
+  it('--since / --until on findRequests filter via the appmap timestamp', () => {
+    const db = freshDb();
+    try {
+      seed(db, [
+        {
+          name: 'a',
+          timestamp: '2026-04-01T00:00:00.000Z',
+          requests: [{ event_id: 1, method: 'GET', path: '/x', status: 200 }],
+        },
+        {
+          name: 'b',
+          timestamp: '2026-04-15T00:00:00.000Z',
+          requests: [{ event_id: 1, method: 'GET', path: '/x', status: 200 }],
+        },
+        {
+          name: 'c',
+          timestamp: '2026-04-30T00:00:00.000Z',
+          requests: [{ event_id: 1, method: 'GET', path: '/x', status: 200 }],
+        },
+      ]);
+      const rows = findRequests(db, {
+        since: '2026-04-10T00:00:00.000Z',
+        until: '2026-04-20T00:00:00.000Z',
+      }).rows;
+      expect(rows).toHaveLength(1);
+      expect(rows[0].appmap_name).toBe('b');
+    } finally {
+      db.close();
+    }
+  });
+
+  it('--since on findCalls scopes via the recording', () => {
+    const db = freshDb();
+    try {
+      seed(db, [
+        {
+          name: 'old',
+          timestamp: '2026-04-01T00:00:00.000Z',
+          calls: [{ event_id: 1, defined_class: 'X', method_id: 'm' }],
+        },
+        {
+          name: 'new',
+          timestamp: '2026-04-30T00:00:00.000Z',
+          calls: [{ event_id: 1, defined_class: 'X', method_id: 'm' }],
+        },
+      ]);
+      const rows = findCalls(db, { since: '2026-04-15T00:00:00.000Z' }).rows;
+      expect(rows).toHaveLength(1);
+      expect(rows[0].appmap_name).toBe('new');
+    } finally {
+      db.close();
+    }
+  });
+
+  it('--duration on findCalls filters per-row elapsed_ms', () => {
+    const db = freshDb();
+    try {
+      seed(db, [
+        {
+          name: 'a',
+          calls: [
+            { event_id: 1, defined_class: 'X', method_id: 'fast', elapsed_ms: 5 },
+            { event_id: 2, defined_class: 'X', method_id: 'slow', elapsed_ms: 500 },
+          ],
+        },
+      ]);
+      const rows = findCalls(db, { duration: { op: '>', value: 100 } }).rows;
+      expect(rows).toHaveLength(1);
+      expect(rows[0].method_id).toBe('slow');
+    } finally {
+      db.close();
+    }
+  });
+
+  it('--duration on findQueries filters per-row elapsed_ms', () => {
+    const db = freshDb();
+    try {
+      seed(db, [
+        {
+          name: 'a',
+          queries: [
+            { event_id: 1, sql: 'SELECT 1', elapsed_ms: 1 },
+            { event_id: 2, sql: 'SELECT 2', elapsed_ms: 50 },
+          ],
+        },
+      ]);
+      const rows = findQueries(db, { duration: { op: '>=', value: 10 } }).rows;
+      expect(rows).toHaveLength(1);
+      expect(rows[0].sql_text).toBe('SELECT 2');
+    } finally {
+      db.close();
+    }
+  });
+
+  it('findQueries --class matches via the parent function_call code_object when the linked parent has the right class', () => {
+    const db = freshDb();
+    try {
+      // Seed a function_call with a code_object link, then a sql_query
+      // whose parent_event_id references that call. caller_class is set
+      // to a deliberately mismatching raw string so we can prove the
+      // code_object path (not the fallback) is matching.
+      seed(db, [
+        {
+          name: 'a',
+          calls: [
+            {
+              event_id: 10,
+              defined_class: 'org.example.UserRepository',
+              method_id: 'findById',
+              fqid: 'org/example/UserRepository#findById',
+            },
+          ],
+          queries: [
+            {
+              event_id: 11,
+              parent_event_id: 10,
+              sql: 'SELECT 1',
+              caller_class: 'WrongClassName',
+              caller_method: 'wrong',
+            },
+          ],
+        },
+      ]);
+      // Class part is read from code_objects (UserRepository), not from
+      // the WrongClassName caller_class string.
+      expect(findQueries(db, { className: 'UserRepository' }).rows).toHaveLength(1);
+      // Full chain match also works.
+      expect(findQueries(db, { className: 'org/example/UserRepository' }).rows).toHaveLength(
+        1
+      );
+      // Misspelled — no match.
+      expect(findQueries(db, { className: 'OtherRepository' }).rows).toHaveLength(0);
+    } finally {
+      db.close();
+    }
+  });
+
+  it('findQueries --class matches caller_class via the suffix-aware helper', () => {
+    const db = freshDb();
+    try {
+      seed(db, [
+        {
+          name: 'a',
+          queries: [
+            {
+              event_id: 1,
+              sql: 'SELECT 1',
+              caller_class: 'org.example.UserRepository',
+              caller_method: 'findById',
+            },
+            {
+              event_id: 2,
+              sql: 'SELECT 2',
+              caller_class: 'OpenSSL::Cipher',
+              caller_method: 'decrypt',
+            },
+            {
+              event_id: 3,
+              sql: 'SELECT 3',
+              caller_class: 'Other',
+              caller_method: 'm',
+            },
+          ],
+        },
+      ]);
+      // Java dot-suffix
+      expect(findQueries(db, { className: 'UserRepository' }).rows).toHaveLength(1);
+      // Ruby ::-suffix
+      expect(findQueries(db, { className: 'Cipher' }).rows).toHaveLength(1);
+      // Exact match also works
+      expect(findQueries(db, { className: 'OpenSSL::Cipher' }).rows).toHaveLength(1);
+      // Top-level
+      expect(findQueries(db, { className: 'Other' }).rows).toHaveLength(1);
+    } finally {
+      db.close();
+    }
+  });
+});
+
+describe('findCalls', () => {
+  it('--class and --method filter directly; --route scopes by recording', () => {
+    const db = freshDb();
+    try {
+      seed(db, [
+        {
+          name: 'a',
+          requests: [{ event_id: 1, method: 'POST', path: '/orders', status: 500 }],
+          calls: [
+            { event_id: 2, defined_class: 'IdempotencyKey', method_id: 'generate', fqid: 'app/IdempotencyKey.generate' },
+            { event_id: 3, defined_class: 'OrdersController', method_id: 'create' },
+          ],
+        },
+        {
+          name: 'b',
+          requests: [{ event_id: 1, method: 'GET', path: '/x', status: 200 }],
+          calls: [{ event_id: 2, defined_class: 'IdempotencyKey', method_id: 'generate' }],
+        },
+      ]);
+      const rows = findCalls(db, {
+        className: 'IdempotencyKey',
+        route: 'POST /orders',
+        status: { op: '>=', value: 500 },
+      }).rows;
+      expect(rows).toHaveLength(1);
+      expect(rows[0].appmap_name).toBe('a');
+      expect(rows[0].fqid).toBe('app/IdempotencyKey.generate');
+    } finally {
+      db.close();
+    }
+  });
+
+  it('--label filters via the labels table', () => {
+    const db = freshDb();
+    try {
+      seed(db, [
+        {
+          name: 'a',
+          calls: [
+            { event_id: 1, defined_class: 'Logger', method_id: 'error', labels: ['log'] },
+            { event_id: 2, defined_class: 'OrdersController', method_id: 'create' },
+          ],
+        },
+      ]);
+      const rows = findCalls(db, { label: 'log' }).rows;
+      expect(rows).toHaveLength(1);
+      expect(rows[0].defined_class).toBe('Logger');
+    } finally {
+      db.close();
+    }
+  });
+
+  it('--event-id fetches exact calls by id', () => {
+    const db = freshDb();
+    try {
+      seed(db, [
+        {
+          name: 'a',
+          calls: [
+            { event_id: 10, defined_class: 'Store', method_id: 'register' },
+            { event_id: 20, defined_class: 'Store', method_id: 'updateStatus' },
+            { event_id: 30, defined_class: 'Store', method_id: 'close' },
+          ],
+        },
+      ]);
+      const rows = findCalls(db, { eventIds: [10, 30] }).rows;
+      expect(rows.map((r) => r.event_id).sort((a, b) => a - b)).toEqual([10, 30]);
+    } finally {
+      db.close();
+    }
+  });
+
+  it('--event-id combines with --class to narrow within the id set', () => {
+    const db = freshDb();
+    try {
+      seed(db, [
+        {
+          name: 'a',
+          calls: [
+            { event_id: 10, defined_class: 'Store', method_id: 'register' },
+            { event_id: 20, defined_class: 'Service', method_id: 'close' },
+          ],
+        },
+      ]);
+      const rows = findCalls(db, { eventIds: [10, 20], className: 'Store' }).rows;
+      expect(rows).toHaveLength(1);
+      expect(rows[0].event_id).toBe(10);
+    } finally {
+      db.close();
+    }
+  });
+});
+
+describe('findLogs', () => {
+  it('returns only label=log calls; non-log calls are excluded', () => {
+    const db = freshDb();
+    try {
+      seed(db, [
+        {
+          name: 'a',
+          calls: [
+            {
+              event_id: 1,
+              defined_class: 'Logger',
+              method_id: 'info',
+              labels: ['log'],
+              parameters: [{ name: 'message', class: 'String', value: 'starting up' }],
+            },
+            { event_id: 2, defined_class: 'OrdersController', method_id: 'create' },
+          ],
+        },
+      ]);
+      const rows = findLogs(db, {}).rows;
+      expect(rows).toHaveLength(1);
+      expect(rows[0].logger).toBe('Logger');
+      expect(rows[0].method_id).toBe('info');
+    } finally {
+      db.close();
+    }
+  });
+
+  it('--message matches a substring inside parameters_json', () => {
+    const db = freshDb();
+    try {
+      seed(db, [
+        {
+          name: 'a',
+          calls: [
+            {
+              event_id: 1,
+              defined_class: 'Logger',
+              method_id: 'error',
+              labels: ['log'],
+              parameters: [{ name: 'message', class: 'String', value: 'connection refused' }],
+            },
+            {
+              event_id: 2,
+              defined_class: 'Logger',
+              method_id: 'info',
+              labels: ['log'],
+              parameters: [{ name: 'message', class: 'String', value: 'started worker' }],
+            },
+          ],
+        },
+      ]);
+      const rows = findLogs(db, { message: 'refused' }).rows;
+      expect(rows).toHaveLength(1);
+      expect(rows[0].event_id).toBe(1);
+    } finally {
+      db.close();
+    }
+  });
+
+  it('--message also matches against return_value (structured-return contract)', () => {
+    const db = freshDb();
+    try {
+      seed(db, [
+        {
+          name: 'a',
+          calls: [
+            {
+              event_id: 1,
+              defined_class: 'Logger',
+              method_id: 'info',
+              labels: ['log'],
+              // No params; the message lives in a structured return_value.
+              return_value: { level: 'info', message: 'connection refused at host:5432' },
+            },
+            {
+              event_id: 2,
+              defined_class: 'Logger',
+              method_id: 'info',
+              labels: ['log'],
+              return_value: { level: 'info', message: 'all systems nominal' },
+            },
+          ],
+        },
+      ]);
+      const rows = findLogs(db, { message: 'refused' }).rows;
+      expect(rows).toHaveLength(1);
+      expect(rows[0].event_id).toBe(1);
+    } finally {
+      db.close();
+    }
+  });
+
+  it('--logger filters by the logging class (uses classFilterClauses)', () => {
+    const db = freshDb();
+    try {
+      seed(db, [
+        {
+          name: 'a',
+          calls: [
+            {
+              event_id: 1,
+              defined_class: 'app.AppLogger',
+              method_id: 'info',
+              labels: ['log'],
+              parameters: [{ name: 'msg', class: 'String', value: 'hello' }],
+            },
+            {
+              event_id: 2,
+              defined_class: 'lib.AuditLogger',
+              method_id: 'info',
+              labels: ['log'],
+              parameters: [{ name: 'msg', class: 'String', value: 'audited' }],
+            },
+          ],
+        },
+      ]);
+      // Suffix-aware short-form match: "AppLogger" hits "app.AppLogger".
+      const rows = findLogs(db, { logger: 'AppLogger' }).rows;
+      expect(rows).toHaveLength(1);
+      expect(rows[0].event_id).toBe(1);
+    } finally {
+      db.close();
+    }
+  });
+
+  it('combines --message with appmap-scope filters (--branch)', () => {
+    const db = freshDb();
+    try {
+      seed(db, [
+        {
+          name: 'a',
+          branch: 'main',
+          calls: [
+            {
+              event_id: 1,
+              defined_class: 'Logger',
+              method_id: 'info',
+              labels: ['log'],
+              parameters: [{ name: 'message', class: 'String', value: 'connection refused' }],
+            },
+          ],
+        },
+        {
+          name: 'b',
+          branch: 'feature',
+          calls: [
+            {
+              event_id: 1,
+              defined_class: 'Logger',
+              method_id: 'info',
+              labels: ['log'],
+              parameters: [{ name: 'message', class: 'String', value: 'connection refused' }],
+            },
+          ],
+        },
+      ]);
+      const rows = findLogs(db, { message: 'refused', branch: 'feature' }).rows;
+      expect(rows).toHaveLength(1);
+      expect(rows[0].appmap_name).toBe('b');
+    } finally {
+      db.close();
+    }
+  });
+
+  it('false positives are accepted: --message matches a parameter name', () => {
+    // Documents the design choice — broad LIKE over the JSON blob means
+    // a search for "message" matches the parameter name, not just the
+    // value. Display-time projection can tighten this if needed.
+    const db = freshDb();
+    try {
+      seed(db, [
+        {
+          name: 'a',
+          calls: [
+            {
+              event_id: 1,
+              defined_class: 'Logger',
+              method_id: 'info',
+              labels: ['log'],
+              parameters: [{ name: 'message', class: 'String', value: 'hi' }],
+            },
+          ],
+        },
+      ]);
+      const rows = findLogs(db, { message: 'message' }).rows;
+      expect(rows).toHaveLength(1);
+    } finally {
+      db.close();
+    }
+  });
+});
+
+describe('findCalls --class / --method (fqid-aware)', () => {
+  it('matches the canonical fqid prefix', () => {
+    const db = freshDb();
+    try {
+      seed(db, [
+        {
+          name: 'a',
+          calls: [
+            {
+              event_id: 1,
+              defined_class: 'org.example.UserRepository',
+              method_id: 'findById',
+              fqid: 'org/example/UserRepository#findById',
+            },
+          ],
+        },
+      ]);
+      // Canonical V3 fqid prefix (slash form, sans method)
+      const rows = findCalls(db, { className: 'org/example/UserRepository' }).rows;
+      expect(rows).toHaveLength(1);
+    } finally {
+      db.close();
+    }
+  });
+
+  it('matches a short class name as the trailing fqid segment', () => {
+    const db = freshDb();
+    try {
+      seed(db, [
+        {
+          name: 'a',
+          calls: [
+            {
+              event_id: 1,
+              defined_class: 'org.example.UserRepository',
+              method_id: 'findById',
+              fqid: 'org/example/UserRepository#findById',
+            },
+            {
+              event_id: 2,
+              defined_class: 'org.other.OrdersController',
+              method_id: 'create',
+              fqid: 'org/other/OrdersController#create',
+            },
+          ],
+        },
+      ]);
+      const rows = findCalls(db, { className: 'UserRepository' }).rows;
+      expect(rows).toHaveLength(1);
+      expect(rows[0].method_id).toBe('findById');
+    } finally {
+      db.close();
+    }
+  });
+
+  it('matches the trailing dot-segment of a Java-style defined_class even without code_object', () => {
+    const db = freshDb();
+    try {
+      // Insert a function_call that has NO code_object (code_object_id NULL)
+      // but has a Java dot-form defined_class.
+      const am = db
+        .prepare(`INSERT INTO appmaps (name, source_path) VALUES ('a', '/tmp/a.appmap.json')`)
+        .run();
+      db.prepare(
+        `INSERT INTO function_calls (appmap_id, event_id, defined_class, method_id)
+         VALUES (?, 1, 'org.example.UserRepository', 'findById')`
+      ).run(am.lastInsertRowid);
+
+      const rows = findCalls(db, { className: 'UserRepository' }).rows;
+      expect(rows).toHaveLength(1);
+    } finally {
+      db.close();
+    }
+  });
+
+  it('--method matches via fqid suffix', () => {
+    const db = freshDb();
+    try {
+      seed(db, [
+        {
+          name: 'a',
+          calls: [
+            {
+              event_id: 1,
+              defined_class: 'org.example.UserRepository',
+              method_id: 'findById',
+              fqid: 'org/example/UserRepository#findById',
+            },
+            {
+              event_id: 2,
+              defined_class: 'org.example.OrderRepository',
+              method_id: 'findById',
+              fqid: 'org/example/OrderRepository#findById',
+            },
+            {
+              event_id: 3,
+              defined_class: 'org.example.UserRepository',
+              method_id: 'save',
+              fqid: 'org/example/UserRepository#save',
+            },
+          ],
+        },
+      ]);
+      const rows = findCalls(db, { method: 'findById' }).rows;
+      expect(rows).toHaveLength(2);
+      expect(rows.every((r) => r.method_id === 'findById')).toBe(true);
+    } finally {
+      db.close();
+    }
+  });
+});
+
+describe('findExceptions', () => {
+  it('--exception filters by class; --route scopes by recording', () => {
+    const db = freshDb();
+    try {
+      seed(db, [
+        {
+          name: 'a',
+          requests: [{ event_id: 1, method: 'POST', path: '/orders', status: 500 }],
+          exceptions: [{ event_id: 2, exception_class: 'IntegrityError', message: 'duplicate key' }],
+        },
+        {
+          name: 'b',
+          requests: [{ event_id: 1, method: 'GET', path: '/x', status: 404 }],
+          exceptions: [{ event_id: 2, exception_class: 'RecordNotFound' }],
+        },
+      ]);
+      expect(findExceptions(db, { exception: 'IntegrityError' }).rows).toHaveLength(1);
+      expect(findExceptions(db, { route: 'POST /orders' }).rows).toHaveLength(1);
+      expect(findExceptions(db, { route: 'POST /orders' }).rows[0].appmap_name).toBe('a');
+    } finally {
+      db.close();
+    }
+  });
+
+  it('--with-logs attaches the last N preceding logs in chronological order', () => {
+    const db = freshDb();
+    try {
+      seed(db, [
+        {
+          name: 'a',
+          calls: [
+            {
+              event_id: 1,
+              defined_class: 'Logger',
+              method_id: 'info',
+              labels: ['log'],
+              parameters: [{ name: 'message', class: 'String', value: 'starting up' }],
+            },
+            {
+              event_id: 2,
+              defined_class: 'Logger',
+              method_id: 'warn',
+              labels: ['log'],
+              parameters: [{ name: 'message', class: 'String', value: 'connection slow' }],
+            },
+            {
+              event_id: 3,
+              defined_class: 'Logger',
+              method_id: 'error',
+              labels: ['log'],
+              parameters: [{ name: 'message', class: 'String', value: 'connection refused' }],
+            },
+          ],
+          // Exception lands at event 4, after the three logs.
+          exceptions: [{ event_id: 4, exception_class: 'IOError', message: 'broken pipe' }],
+        },
+      ]);
+      const rows = findExceptions(db, { withLogs: 2 }).rows;
+      expect(rows).toHaveLength(1);
+      expect(rows[0].recent_logs).toBeDefined();
+      // Last 2 in chronological order: the warn at event 2, then error at event 3.
+      const logs = rows[0].recent_logs!;
+      expect(logs).toHaveLength(2);
+      expect(logs[0].event_id).toBe(2);
+      expect(logs[1].event_id).toBe(3);
+    } finally {
+      db.close();
+    }
+  });
+
+  it('--with-logs is omitted when not requested (recent_logs undefined)', () => {
+    const db = freshDb();
+    try {
+      seed(db, [
+        {
+          name: 'a',
+          calls: [
+            {
+              event_id: 1,
+              defined_class: 'Logger',
+              method_id: 'info',
+              labels: ['log'],
+              parameters: [{ name: 'message', class: 'String', value: 'hi' }],
+            },
+          ],
+          exceptions: [{ event_id: 2, exception_class: 'IOError' }],
+        },
+      ]);
+      const rows = findExceptions(db, {}).rows;
+      expect(rows[0].recent_logs).toBeUndefined();
+    } finally {
+      db.close();
+    }
+  });
+
+  it('--with-logs with no preceding logs returns an empty array', () => {
+    const db = freshDb();
+    try {
+      seed(db, [
+        {
+          name: 'a',
+          // Exception at event 1; no logs at all.
+          exceptions: [{ event_id: 1, exception_class: 'IOError' }],
+        },
+      ]);
+      const rows = findExceptions(db, { withLogs: 5 }).rows;
+      expect(rows[0].recent_logs).toEqual([]);
+    } finally {
+      db.close();
+    }
+  });
+
+  it('--with-logs only includes logs from the same recording', () => {
+    const db = freshDb();
+    try {
+      seed(db, [
+        {
+          name: 'a',
+          calls: [
+            {
+              event_id: 1,
+              defined_class: 'Logger',
+              method_id: 'info',
+              labels: ['log'],
+              parameters: [{ name: 'message', class: 'String', value: 'recording-a log' }],
+            },
+          ],
+          exceptions: [{ event_id: 2, exception_class: 'IOError' }],
+        },
+        {
+          name: 'b',
+          calls: [
+            {
+              event_id: 1,
+              defined_class: 'Logger',
+              method_id: 'info',
+              labels: ['log'],
+              parameters: [{ name: 'message', class: 'String', value: 'recording-b log' }],
+            },
+          ],
+          exceptions: [{ event_id: 2, exception_class: 'IOError' }],
+        },
+      ]);
+      const rows = findExceptions(db, { withLogs: 5 }).rows;
+      expect(rows).toHaveLength(2);
+      // Each exception's recent_logs is scoped to its own recording.
+      for (const row of rows) {
+        expect(row.recent_logs).toHaveLength(1);
+        expect(row.recent_logs![0].appmap_name).toBe(row.appmap_name);
+      }
+    } finally {
+      db.close();
+    }
+  });
+});
diff --git a/packages/cli/tests/unit/cmds/query/queries/hotspots.spec.ts b/packages/cli/tests/unit/cmds/query/queries/hotspots.spec.ts
new file mode 100644
index 0000000000..ad91e0b7bd
--- /dev/null
+++ b/packages/cli/tests/unit/cmds/query/queries/hotspots.spec.ts
@@ -0,0 +1,306 @@
+import sqlite3 from 'better-sqlite3';
+
+import { openQueryDb } from '../../../../../src/cmds/query/db/openQueryDb';
+import {
+  functionHotspots,
+  sqlHotspots,
+} from '../../../../../src/cmds/query/queries/hotspots';
+
+function freshDb(): sqlite3.Database {
+  return openQueryDb('/tmp/ignored', ':memory:').db;
+}
+
+interface CallSeed {
+  event_id: number;
+  parent_event_id?: number;
+  defined_class: string;
+  method_id: string;
+  fqid?: string;
+  elapsed_ms: number;
+}
+
+function seedRecording(
+  db: sqlite3.Database,
+  opts: {
+    name: string;
+    branch?: string;
+    request?: { event_id: number; method: string; path: string; status: number };
+    calls?: CallSeed[];
+    queries?: { event_id: number; parent_event_id?: number; sql: string; elapsed_ms: number }[];
+  }
+): number {
+  const am = db
+    .prepare(
+      `INSERT INTO appmaps (name, source_path, git_branch) VALUES (?, ?, ?)`
+    )
+    .run(opts.name, `/tmp/${opts.name}.appmap.json`, opts.branch ?? null);
+  const aid = Number(am.lastInsertRowid);
+
+  if (opts.request) {
+    db.prepare(
+      `INSERT INTO http_requests (appmap_id, event_id, method, path, status_code)
+       VALUES (?, ?, ?, ?, ?)`
+    ).run(aid, opts.request.event_id, opts.request.method, opts.request.path, opts.request.status);
+  }
+
+  for (const c of opts.calls ?? []) {
+    const fqid = c.fqid ?? `${c.defined_class}#${c.method_id}`;
+    const dotIdx = c.defined_class.lastIndexOf('.');
+    const pkg = dotIdx >= 0 ? c.defined_class.slice(0, dotIdx).replace(/\./g, '/') : '';
+    const leaf = dotIdx >= 0 ? c.defined_class.slice(dotIdx + 1) : c.defined_class;
+    db.prepare(
+      `INSERT OR IGNORE INTO code_objects (fqid, package, classes, leaf_class, method, is_static)
+       VALUES (?, ?, ?, ?, ?, ?)`
+    ).run(fqid, pkg, JSON.stringify([leaf]), leaf, c.method_id, 0);
+    const coId = (db
+      .prepare(`SELECT id FROM code_objects WHERE fqid = ?`)
+      .get(fqid) as { id: number }).id;
+    db.prepare(
+      `INSERT INTO function_calls (appmap_id, event_id, parent_event_id,
+         code_object_id, defined_class, method_id, elapsed_ms)
+       VALUES (?, ?, ?, ?, ?, ?, ?)`
+    ).run(aid, c.event_id, c.parent_event_id ?? null, coId, c.defined_class, c.method_id, c.elapsed_ms);
+  }
+
+  for (const q of opts.queries ?? []) {
+    db.prepare(
+      `INSERT INTO sql_queries (appmap_id, event_id, parent_event_id, sql_text, elapsed_ms)
+       VALUES (?, ?, ?, ?, ?)`
+    ).run(aid, q.event_id, q.parent_event_id ?? null, q.sql, q.elapsed_ms);
+  }
+
+  return aid;
+}
+
+describe('functionHotspots', () => {
+  it('groups by code_object_id and ranks by total_ms desc', () => {
+    const db = freshDb();
+    try {
+      seedRecording(db, {
+        name: 'a',
+        calls: [
+          { event_id: 1, defined_class: 'X', method_id: 'fast', fqid: 'app/X#fast', elapsed_ms: 5 },
+          { event_id: 2, defined_class: 'X', method_id: 'fast', fqid: 'app/X#fast', elapsed_ms: 5 },
+          { event_id: 3, defined_class: 'Y', method_id: 'slow', fqid: 'app/Y#slow', elapsed_ms: 100 },
+        ],
+      });
+      const rows = functionHotspots(db, {}).rows;
+      expect(rows[0].fqid).toBe('app/Y#slow');
+      expect(rows[0].calls).toBe(1);
+      expect(rows[0].total_ms).toBe(100);
+      expect(rows[1].fqid).toBe('app/X#fast');
+      expect(rows[1].calls).toBe(2);
+      expect(rows[1].total_ms).toBe(10);
+    } finally {
+      db.close();
+    }
+  });
+
+  it('computes self_ms as elapsed minus the sum of immediate children', () => {
+    const db = freshDb();
+    try {
+      // outer call (10) calls inner1 (3) and inner2 (4) and an SQL (1).
+      // self_ms(outer) should be 10 - (3 + 4 + 1) = 2.
+      seedRecording(db, {
+        name: 'a',
+        calls: [
+          { event_id: 1, defined_class: 'X', method_id: 'outer', fqid: 'app/X#outer', elapsed_ms: 10 },
+          { event_id: 2, parent_event_id: 1, defined_class: 'X', method_id: 'inner1', fqid: 'app/X#inner1', elapsed_ms: 3 },
+          { event_id: 3, parent_event_id: 1, defined_class: 'X', method_id: 'inner2', fqid: 'app/X#inner2', elapsed_ms: 4 },
+        ],
+        queries: [{ event_id: 4, parent_event_id: 1, sql: 'SELECT 1', elapsed_ms: 1 }],
+      });
+      const outer = functionHotspots(db, {}).rows.find((r) => r.fqid === 'app/X#outer')!;
+      expect(outer.total_ms).toBe(10);
+      expect(outer.self_ms).toBe(2);
+      const inner1 = functionHotspots(db, {}).rows.find((r) => r.fqid === 'app/X#inner1')!;
+      expect(inner1.self_ms).toBe(3); // leaf — self equals total
+    } finally {
+      db.close();
+    }
+  });
+
+  it('aggregates across recordings', () => {
+    const db = freshDb();
+    try {
+      seedRecording(db, {
+        name: 'a',
+        calls: [{ event_id: 1, defined_class: 'X', method_id: 'm', fqid: 'app/X#m', elapsed_ms: 10 }],
+      });
+      seedRecording(db, {
+        name: 'b',
+        calls: [{ event_id: 1, defined_class: 'X', method_id: 'm', fqid: 'app/X#m', elapsed_ms: 20 }],
+      });
+      const rows = functionHotspots(db, {}).rows;
+      expect(rows).toHaveLength(1);
+      expect(rows[0].calls).toBe(2);
+      expect(rows[0].total_ms).toBe(30);
+    } finally {
+      db.close();
+    }
+  });
+
+  it('--route scopes to recordings with a matching server request', () => {
+    const db = freshDb();
+    try {
+      seedRecording(db, {
+        name: 'reports',
+        request: { event_id: 0, method: 'GET', path: '/reports', status: 200 },
+        calls: [{ event_id: 1, defined_class: 'R', method_id: 'calc', fqid: 'app/R#calc', elapsed_ms: 100 }],
+      });
+      seedRecording(db, {
+        name: 'orders',
+        request: { event_id: 0, method: 'POST', path: '/orders', status: 200 },
+        calls: [{ event_id: 1, defined_class: 'O', method_id: 'create', fqid: 'app/O#create', elapsed_ms: 50 }],
+      });
+      const rows = functionHotspots(db, { route: 'GET /reports' }).rows;
+      expect(rows).toHaveLength(1);
+      expect(rows[0].fqid).toBe('app/R#calc');
+    } finally {
+      db.close();
+    }
+  });
+
+  it('--class filters by defined_class', () => {
+    const db = freshDb();
+    try {
+      seedRecording(db, {
+        name: 'a',
+        calls: [
+          { event_id: 1, defined_class: 'OrdersController', method_id: 'create', elapsed_ms: 100 },
+          { event_id: 2, defined_class: 'OrdersController', method_id: 'index', elapsed_ms: 50 },
+          { event_id: 3, defined_class: 'UsersController', method_id: 'show', elapsed_ms: 200 },
+        ],
+      });
+      const rows = functionHotspots(db, { className: 'OrdersController' }).rows;
+      expect(rows.map((r) => r.method_id).sort()).toEqual(['create', 'index']);
+    } finally {
+      db.close();
+    }
+  });
+
+  it('--class also matches via the canonical fqid (not just defined_class)', () => {
+    const db = freshDb();
+    try {
+      seedRecording(db, {
+        name: 'a',
+        calls: [
+          {
+            event_id: 1,
+            defined_class: 'org.example.UserRepository',
+            method_id: 'findById',
+            fqid: 'org/example/UserRepository#findById',
+            elapsed_ms: 100,
+          },
+          {
+            event_id: 2,
+            defined_class: 'org.example.OrderRepository',
+            method_id: 'findById',
+            fqid: 'org/example/OrderRepository#findById',
+            elapsed_ms: 50,
+          },
+        ],
+      });
+      const rows = functionHotspots(db, { className: 'UserRepository' }).rows;
+      expect(rows).toHaveLength(1);
+      expect(rows[0].fqid).toBe('org/example/UserRepository#findById');
+    } finally {
+      db.close();
+    }
+  });
+
+  it('--limit truncates the result set', () => {
+    const db = freshDb();
+    try {
+      seedRecording(db, {
+        name: 'a',
+        calls: [
+          { event_id: 1, defined_class: 'X', method_id: 'a', elapsed_ms: 100 },
+          { event_id: 2, defined_class: 'X', method_id: 'b', elapsed_ms: 50 },
+          { event_id: 3, defined_class: 'X', method_id: 'c', elapsed_ms: 25 },
+        ],
+      });
+      expect(functionHotspots(db, { limit: 2 }).rows).toHaveLength(2);
+    } finally {
+      db.close();
+    }
+  });
+});
+
+describe('sqlHotspots', () => {
+  it('groups by sql_text, ranks by total_ms desc', () => {
+    const db = freshDb();
+    try {
+      seedRecording(db, {
+        name: 'a',
+        queries: [
+          { event_id: 1, sql: 'SELECT * FROM users WHERE id = ?', elapsed_ms: 2 },
+          { event_id: 2, sql: 'SELECT * FROM users WHERE id = ?', elapsed_ms: 2 },
+          { event_id: 3, sql: 'SELECT * FROM tenants WHERE slug = ?', elapsed_ms: 80 },
+        ],
+      });
+      const rows = sqlHotspots(db, {}).rows;
+      expect(rows[0].sql_text).toBe('SELECT * FROM tenants WHERE slug = ?');
+      expect(rows[0].count).toBe(1);
+      expect(rows[0].avg_ms).toBeCloseTo(80);
+      expect(rows[1].count).toBe(2);
+      expect(rows[1].avg_ms).toBeCloseTo(2);
+      expect(rows[1].total_ms).toBe(4);
+    } finally {
+      db.close();
+    }
+  });
+
+  it('--since / --until scope to recordings within the time range', () => {
+    const db = freshDb();
+    try {
+      const oldId = (db
+        .prepare(
+          `INSERT INTO appmaps (name, source_path, timestamp) VALUES ('old', '/o', '2026-04-01T00:00:00.000Z')`
+        )
+        .run().lastInsertRowid as number);
+      const newId = (db
+        .prepare(
+          `INSERT INTO appmaps (name, source_path, timestamp) VALUES ('new', '/n', '2026-04-30T00:00:00.000Z')`
+        )
+        .run().lastInsertRowid as number);
+      db.prepare(
+        `INSERT INTO sql_queries (appmap_id, event_id, sql_text, elapsed_ms) VALUES (?, 1, 'SELECT a', 1)`
+      ).run(oldId);
+      db.prepare(
+        `INSERT INTO sql_queries (appmap_id, event_id, sql_text, elapsed_ms) VALUES (?, 1, 'SELECT b', 2)`
+      ).run(newId);
+
+      const since = sqlHotspots(db, { since: '2026-04-15T00:00:00.000Z' }).rows;
+      expect(since).toHaveLength(1);
+      expect(since[0].sql_text).toBe('SELECT b');
+
+      const until = sqlHotspots(db, { until: '2026-04-15T00:00:00.000Z' }).rows;
+      expect(until).toHaveLength(1);
+      expect(until[0].sql_text).toBe('SELECT a');
+    } finally {
+      db.close();
+    }
+  });
+
+  it('--branch filter applies', () => {
+    const db = freshDb();
+    try {
+      seedRecording(db, {
+        name: 'a',
+        branch: 'main',
+        queries: [{ event_id: 1, sql: 'SELECT 1', elapsed_ms: 1 }],
+      });
+      seedRecording(db, {
+        name: 'b',
+        branch: 'feature',
+        queries: [{ event_id: 1, sql: 'SELECT 2', elapsed_ms: 2 }],
+      });
+      const main = sqlHotspots(db, { branch: 'main' }).rows;
+      expect(main).toHaveLength(1);
+      expect(main[0].sql_text).toBe('SELECT 1');
+    } finally {
+      db.close();
+    }
+  });
+});
diff --git a/packages/cli/tests/unit/cmds/query/queries/mcp.spec.ts b/packages/cli/tests/unit/cmds/query/queries/mcp.spec.ts
new file mode 100644
index 0000000000..1c05308678
--- /dev/null
+++ b/packages/cli/tests/unit/cmds/query/queries/mcp.spec.ts
@@ -0,0 +1,1134 @@
+import sqlite3 from 'better-sqlite3';
+
+import { openQueryDb } from '../../../../../src/cmds/query/db/openQueryDb';
+import {
+  buildMcpHandler,
+  JsonRpcRequest,
+  listResources,
+  listResourceTemplates,
+  listTools,
+} from '../../../../../src/cmds/query/queries/mcp';
+
+function freshDb(): sqlite3.Database {
+  return openQueryDb('/tmp/ignored', ':memory:').db;
+}
+
+function seedMinimal(db: sqlite3.Database): void {
+  // One recording with a request, a SQL query, an exception, and a labelled
+  // function call — enough to exercise most tools.
+  const am = db
+    .prepare(
+      `INSERT INTO appmaps (name, source_path, git_branch, sql_query_count, elapsed_ms, timestamp)
+       VALUES ('rec', '/tmp/rec.appmap.json', 'main', 1, 100, '2026-04-29T12:00:00.000Z')`
+    )
+    .run();
+  const id = am.lastInsertRowid;
+  db.prepare(
+    `INSERT INTO http_requests (appmap_id, event_id, parent_event_id, method, path, status_code, elapsed_ms)
+     VALUES (?, 1, NULL, 'POST', '/orders', 500, 100)`
+  ).run(id);
+  db.prepare(
+    `INSERT OR IGNORE INTO code_objects (fqid, package, classes, leaf_class, method, is_static)
+     VALUES ('app/Logger#error', 'app', '["Logger"]', 'Logger', 'error', 0)`
+  ).run();
+  const co = (db
+    .prepare(`SELECT id FROM code_objects WHERE fqid = 'app/Logger#error'`)
+    .get() as { id: number }).id;
+  db.prepare(`INSERT OR IGNORE INTO labels (code_object_id, label) VALUES (?, 'log')`).run(co);
+  db.prepare(
+    `INSERT INTO function_calls (appmap_id, event_id, parent_event_id, code_object_id,
+       defined_class, method_id, elapsed_ms, parameters_json, return_value)
+     VALUES (?, 2, 1, ?, 'Logger', 'error', 0.1,
+       '[{"name":"message","class":"String","value":"connection refused"}]', NULL)`
+  ).run(id, co);
+  db.prepare(
+    `INSERT INTO sql_queries (appmap_id, event_id, parent_event_id, sql_text, elapsed_ms)
+     VALUES (?, 3, 2, 'INSERT INTO orders (id) VALUES (?)', 14)`
+  ).run(id);
+  // Exception's call entry is event_id=2 (the Logger.error call), and the
+  // throw materialised at the return event id=4. with_logs uses event_id=2
+  // as the call boundary and event_id=4 as the throw boundary.
+  db.prepare(
+    `INSERT INTO exceptions (appmap_id, event_id, return_event_id, parent_event_id,
+      exception_class, message)
+     VALUES (?, 2, 4, 1, 'IntegrityError', 'duplicate key')`
+  ).run(id);
+}
+
+function call(handler: ReturnType<typeof buildMcpHandler>, msg: JsonRpcRequest) {
+  const r = handler(msg);
+  return r;
+}
+
+describe('MCP handler', () => {
+  it('initialize returns server info and capabilities', () => {
+    const db = freshDb();
+    try {
+      const r = call(buildMcpHandler(db), { jsonrpc: '2.0', id: 1, method: 'initialize' });
+      expect(r).not.toBeNull();
+      expect((r!.result as any).serverInfo.name).toBe('appmap-query');
+      expect((r!.result as any).protocolVersion).toBeDefined();
+      expect((r!.result as any).capabilities.tools).toBeDefined();
+      expect((r!.result as any).capabilities.resources).toBeDefined();
+    } finally {
+      db.close();
+    }
+  });
+
+  it('notifications/initialized returns null (notification, no response)', () => {
+    const db = freshDb();
+    try {
+      const r = call(buildMcpHandler(db), {
+        jsonrpc: '2.0',
+        method: 'notifications/initialized',
+      });
+      expect(r).toBeNull();
+    } finally {
+      db.close();
+    }
+  });
+
+  it('tools/list returns the V3 tool surface', () => {
+    const db = freshDb();
+    try {
+      const r = call(buildMcpHandler(db), { jsonrpc: '2.0', id: 2, method: 'tools/list' });
+      const names = ((r!.result as any).tools as { name: string }[]).map((t) => t.name);
+      expect(names).toEqual(
+        expect.arrayContaining([
+          'list_endpoints',
+          'function_hotspots',
+          'sql_hotspots',
+          'list_labels',
+          'find_recordings',
+          'find_requests',
+          'find_queries',
+          'find_calls',
+          'find_logs',
+          'find_exceptions',
+          'get_call_tree',
+          'find_related',
+          'compare_branches',
+        ])
+      );
+    } finally {
+      db.close();
+    }
+  });
+
+  it('resources/list returns the appmap://endpoints resource', () => {
+    const db = freshDb();
+    try {
+      const r = call(buildMcpHandler(db), { jsonrpc: '2.0', id: 3, method: 'resources/list' });
+      const uris = ((r!.result as any).resources as { uri: string }[]).map((x) => x.uri);
+      expect(uris).toContain('appmap://endpoints');
+    } finally {
+      db.close();
+    }
+  });
+
+  it('unknown method → -32601 method-not-found', () => {
+    const db = freshDb();
+    try {
+      const r = call(buildMcpHandler(db), { jsonrpc: '2.0', id: 4, method: 'no/such/method' });
+      expect(r!.error?.code).toBe(-32601);
+    } finally {
+      db.close();
+    }
+  });
+
+  it('tools/call to an unknown tool → -32601', () => {
+    const db = freshDb();
+    try {
+      const r = call(buildMcpHandler(db), {
+        jsonrpc: '2.0',
+        id: 5,
+        method: 'tools/call',
+        params: { name: 'no_such_tool', arguments: {} },
+      });
+      expect(r!.error?.code).toBe(-32601);
+    } finally {
+      db.close();
+    }
+  });
+
+  it('tools/call wraps the result as a content block of type=text', () => {
+    const db = freshDb();
+    try {
+      seedMinimal(db);
+      const r = call(buildMcpHandler(db), {
+        jsonrpc: '2.0',
+        id: 6,
+        method: 'tools/call',
+        params: { name: 'find_exceptions', arguments: { limit: 10 } },
+      });
+      const content = (r!.result as any).content;
+      expect(Array.isArray(content)).toBe(true);
+      expect(content[0].type).toBe('text');
+      const parsed = JSON.parse(content[0].text);
+      expect(parsed.rows).toHaveLength(1);
+      expect(parsed.total).toBe(1);
+      expect(parsed.rows[0].exception_class).toBe('IntegrityError');
+    } finally {
+      db.close();
+    }
+  });
+
+  it('get_call_tree resolves the canonical appmap path and applies focus_type', () => {
+    const db = freshDb();
+    try {
+      seedMinimal(db);
+      const handler = buildMcpHandler(db);
+
+      // Look up the canonical path via find_recordings, then call
+      // get_call_tree with that exact value. This is the round-trip
+      // the API contract documents.
+      const list = call(handler, {
+        jsonrpc: '2.0',
+        id: 7,
+        method: 'tools/call',
+        params: { name: 'find_recordings', arguments: {} },
+      });
+      const path = JSON.parse((list!.result as any).content[0].text).rows[0].path;
+
+      const r = call(handler, {
+        jsonrpc: '2.0',
+        id: 8,
+        method: 'tools/call',
+        params: {
+          name: 'get_call_tree',
+          arguments: {
+            appmap: path,
+            focus_type: 'sql_query',
+            focus_value: 'INSERT INTO orders',
+            format: 'json',
+          },
+        },
+      });
+      const result = JSON.parse((r!.result as any).content[0].text);
+      expect(Array.isArray(result.nodes)).toBe(true);
+      expect(result.nodes.some((n: any) => n.kind === 'sql')).toBe(true);
+      expect(typeof result.truncated).toBe('boolean');
+      expect(typeof result.max_depth_reached).toBe('number');
+    } finally {
+      db.close();
+    }
+  });
+
+  it('list_labels returns labels with counts and a sample fqid', () => {
+    const db = freshDb();
+    try {
+      seedMinimal(db);
+      const r = call(buildMcpHandler(db), {
+        jsonrpc: '2.0',
+        id: 90,
+        method: 'tools/call',
+        params: { name: 'list_labels', arguments: {} },
+      });
+      const rows = JSON.parse((r!.result as any).content[0].text);
+      expect(rows).toEqual([{ label: 'log', count: 1, sample_fqid: 'app/Logger#error' }]);
+    } finally {
+      db.close();
+    }
+  });
+
+  it('find_logs returns label=log calls and filters by --message', () => {
+    const db = freshDb();
+    try {
+      seedMinimal(db);
+      // Add a parameters_json + return_value to the seeded log call so
+      // --message has something to LIKE against.
+      db.prepare(
+        `UPDATE function_calls
+            SET parameters_json = ?, return_value = ?
+            WHERE method_id = 'error'`
+      ).run(
+        JSON.stringify([{ name: 'message', class: 'String', value: 'connection refused' }]),
+        null
+      );
+      const handler = buildMcpHandler(db);
+
+      // No filter: returns the log row.
+      const all = call(handler, {
+        jsonrpc: '2.0',
+        id: 100,
+        method: 'tools/call',
+        params: { name: 'find_logs', arguments: {} },
+      });
+      const allRows = JSON.parse((all!.result as any).content[0].text);
+      expect(allRows.rows).toHaveLength(1);
+      expect(allRows.rows[0].logger).toBe('Logger');
+      expect(allRows.rows[0].method_id).toBe('error');
+      expect(allRows.rows[0].parameters_json).toContain('connection refused');
+
+      // Substring filter against parameters_json.
+      const matched = call(handler, {
+        jsonrpc: '2.0',
+        id: 101,
+        method: 'tools/call',
+        params: { name: 'find_logs', arguments: { message: 'refused' } },
+      });
+      expect(JSON.parse((matched!.result as any).content[0].text).rows).toHaveLength(1);
+
+      // Substring that doesn't appear: zero rows.
+      const empty = call(handler, {
+        jsonrpc: '2.0',
+        id: 102,
+        method: 'tools/call',
+        params: { name: 'find_logs', arguments: { message: 'this never appears' } },
+      });
+      expect(JSON.parse((empty!.result as any).content[0].text).rows).toHaveLength(0);
+    } finally {
+      db.close();
+    }
+  });
+
+  it('find_exceptions with_logs attaches recent_logs', () => {
+    const db = freshDb();
+    try {
+      seedMinimal(db);
+      // Give the seeded log call a message so recent_logs has content.
+      db.prepare(
+        `UPDATE function_calls
+            SET parameters_json = ?
+            WHERE method_id = 'error'`
+      ).run(
+        JSON.stringify([{ name: 'message', class: 'String', value: 'connection refused' }])
+      );
+      const handler = buildMcpHandler(db);
+
+      // No with_logs: recent_logs is absent.
+      const noLogs = call(handler, {
+        jsonrpc: '2.0',
+        id: 200,
+        method: 'tools/call',
+        params: { name: 'find_exceptions', arguments: {} },
+      });
+      const noLogsRows = JSON.parse((noLogs!.result as any).content[0].text);
+      expect(noLogsRows.rows[0].recent_logs).toBeUndefined();
+      // appmap_id is now exposed.
+      expect(typeof noLogsRows.rows[0].appmap_id).toBe('number');
+
+      // with_logs=5: recent_logs is present and non-empty (the seed has
+      // a log call at event 2, exception at event 2 — the log shares the
+      // event_id with the exception so it doesn't qualify; verify the
+      // shape regardless).
+      const withLogsRes = call(handler, {
+        jsonrpc: '2.0',
+        id: 201,
+        method: 'tools/call',
+        params: { name: 'find_exceptions', arguments: { with_logs: 5 } },
+      });
+      const withLogsRows = JSON.parse((withLogsRes!.result as any).content[0].text);
+      expect(Array.isArray(withLogsRows.rows[0].recent_logs)).toBe(true);
+    } finally {
+      db.close();
+    }
+  });
+
+  it('find_logs row carries a derived message field', () => {
+    const db = freshDb();
+    try {
+      seedMinimal(db);
+      const r = call(buildMcpHandler(db), {
+        jsonrpc: '2.0',
+        id: 91,
+        method: 'tools/call',
+        params: { name: 'find_logs', arguments: {} },
+      });
+      const page = JSON.parse((r!.result as any).content[0].text);
+      expect(page.rows).toHaveLength(1);
+      expect(page.rows[0].message).toBe('connection refused');
+      expect(page.rows[0].logger).toBe('Logger');
+      expect(page.rows[0].parameters_json).toContain('connection refused');
+    } finally {
+      db.close();
+    }
+  });
+
+  it('find_exceptions with_logs uses return_event_id for ordering (regression)', () => {
+    const db = freshDb();
+    try {
+      seedMinimal(db);
+      const r = call(buildMcpHandler(db), {
+        jsonrpc: '2.0',
+        id: 92,
+        method: 'tools/call',
+        params: { name: 'find_exceptions', arguments: { with_logs: 5 } },
+      });
+      const page = JSON.parse((r!.result as any).content[0].text);
+      expect(page.rows).toHaveLength(1);
+      expect(page.rows[0].return_event_id).toBe(4);
+      // Pre-fix the with_logs SQL filtered by `event_id < exception.event_id`
+      // (=2), which excluded the Logger.error log call at event_id=2 entirely.
+      // With return_event_id (=4) as the upper bound, the log call (event 2)
+      // is included — that's the regression we're guarding against.
+      expect(page.rows[0].recent_logs).toHaveLength(1);
+      expect(page.rows[0].recent_logs[0].event_id).toBe(2);
+      expect(page.rows[0].recent_logs[0].message).toBe('connection refused');
+    } finally {
+      db.close();
+    }
+  });
+
+  it('find_calls --label filters by the AppMap label', () => {
+    const db = freshDb();
+    try {
+      seedMinimal(db);
+      const r = call(buildMcpHandler(db), {
+        jsonrpc: '2.0',
+        id: 9,
+        method: 'tools/call',
+        params: { name: 'find_calls', arguments: { label: 'log' } },
+      });
+      const page = JSON.parse((r!.result as any).content[0].text);
+      expect(page.rows).toHaveLength(1);
+      expect(page.rows[0].method_id).toBe('error');
+    } finally {
+      db.close();
+    }
+  });
+
+  it('list_endpoints / function_hotspots / sql_hotspots produce expected rows', () => {
+    const db = freshDb();
+    try {
+      seedMinimal(db);
+      const handler = buildMcpHandler(db);
+
+      const ep = call(handler, {
+        jsonrpc: '2.0',
+        id: 11,
+        method: 'tools/call',
+        params: { name: 'list_endpoints', arguments: {} },
+      });
+      const epPage = JSON.parse((ep!.result as any).content[0].text);
+      expect(epPage.rows[0].route).toBe('/orders');
+
+      const fh = call(handler, {
+        jsonrpc: '2.0',
+        id: 12,
+        method: 'tools/call',
+        params: { name: 'function_hotspots', arguments: { limit: 5 } },
+      });
+      expect(JSON.parse((fh!.result as any).content[0].text).rows.length).toBeGreaterThan(0);
+
+      const sh = call(handler, {
+        jsonrpc: '2.0',
+        id: 13,
+        method: 'tools/call',
+        params: { name: 'sql_hotspots', arguments: { limit: 5 } },
+      });
+      expect(JSON.parse((sh!.result as any).content[0].text).rows.length).toBeGreaterThan(0);
+    } finally {
+      db.close();
+    }
+  });
+
+  it('resources/read returns the endpoints summary as JSON', () => {
+    const db = freshDb();
+    try {
+      seedMinimal(db);
+      const r = call(buildMcpHandler(db), {
+        jsonrpc: '2.0',
+        id: 10,
+        method: 'resources/read',
+        params: { uri: 'appmap://endpoints' },
+      });
+      const contents = (r!.result as any).contents;
+      expect(contents[0].uri).toBe('appmap://endpoints');
+      const parsed = JSON.parse(contents[0].text);
+      expect(parsed.rows[0].route).toBe('/orders');
+    } finally {
+      db.close();
+    }
+  });
+
+  it('listTools / listResources / listResourceTemplates are stable for documentation use', () => {
+    expect(listTools().length).toBeGreaterThan(0);
+    expect(listResources().length).toBeGreaterThan(0);
+    expect(listResourceTemplates().length).toBeGreaterThan(0);
+  });
+
+  it('resources/templates/list advertises the per-recording logs template', () => {
+    const db = freshDb();
+    try {
+      const r = call(buildMcpHandler(db), {
+        jsonrpc: '2.0',
+        id: 300,
+        method: 'resources/templates/list',
+      });
+      const templates = (r!.result as any).resourceTemplates as { uriTemplate: string }[];
+      expect(templates.some((t) => t.uriTemplate === 'appmap://recording/{ref}/logs')).toBe(
+        true
+      );
+    } finally {
+      db.close();
+    }
+  });
+
+  it('resources/read on appmap://recording/<encoded-path>/logs returns the recording\'s log rows', () => {
+    const db = freshDb();
+    try {
+      seedMinimal(db);
+      // Give the seeded log call a captured message.
+      db.prepare(
+        `UPDATE function_calls
+            SET parameters_json = ?
+            WHERE method_id = 'error'`
+      ).run(
+        JSON.stringify([{ name: 'message', class: 'String', value: 'connection refused' }])
+      );
+
+      // {ref} is the canonical path (the absolute source_path). Since
+      // it contains slashes, the URI segment is URL-encoded.
+      const sourcePath = '/tmp/rec.appmap.json';
+      const uri = `appmap://recording/${encodeURIComponent(sourcePath)}/logs`;
+      const r = call(buildMcpHandler(db), {
+        jsonrpc: '2.0',
+        id: 301,
+        method: 'resources/read',
+        params: { uri },
+      });
+      const contents = (r!.result as any).contents;
+      expect(contents[0].uri).toBe(uri);
+      const page = JSON.parse(contents[0].text);
+      expect(page.rows).toHaveLength(1);
+      expect(page.rows[0].logger).toBe('Logger');
+      expect(page.rows[0].method_id).toBe('error');
+    } finally {
+      db.close();
+    }
+  });
+
+  it('resources/read on a recording-logs URI with an unknown path returns an error', () => {
+    const db = freshDb();
+    try {
+      const uri = `appmap://recording/${encodeURIComponent('/no/such/recording.appmap.json')}/logs`;
+      const r = call(buildMcpHandler(db), {
+        jsonrpc: '2.0',
+        id: 302,
+        method: 'resources/read',
+        params: { uri },
+      });
+      expect(r!.error).toBeDefined();
+      expect(r!.error!.message).toMatch(/not found at path/);
+    } finally {
+      db.close();
+    }
+  });
+
+  it('resources/read on a URI that matches no resource or template returns an error', () => {
+    const db = freshDb();
+    try {
+      const r = call(buildMcpHandler(db), {
+        jsonrpc: '2.0',
+        id: 303,
+        method: 'resources/read',
+        params: { uri: 'appmap://nope' },
+      });
+      expect(r!.error).toBeDefined();
+      expect(r!.error!.message).toMatch(/unknown resource/);
+    } finally {
+      db.close();
+    }
+  });
+
+  // --- Spec 01: canonical path identifier ---------------------------------
+
+  describe('Spec 01: canonical path identifier', () => {
+    function seedTwo(db: sqlite3.Database): void {
+      // Two recordings rooted at /tmp/proj — one junit, one request — so
+      // we can verify path/kind derivation and alias equivalence.
+      db.prepare(
+        `INSERT INTO appmaps (name, source_path, git_branch, sql_query_count, elapsed_ms, timestamp)
+         VALUES ('JunitTest_method_x', '/tmp/proj/tmp/appmap/junit/JunitTest_method_x.appmap.json',
+                 'main', 0, 100, '2026-04-29T12:00:00.000Z')`
+      ).run();
+      db.prepare(
+        `INSERT INTO appmaps (name, source_path, git_branch, sql_query_count, elapsed_ms, timestamp)
+         VALUES ('1779_post_orders', '/tmp/proj/tmp/appmap/request_recording/1779_post_orders.appmap.json',
+                 'main', 0, 50,  '2026-04-29T12:00:01.000Z')`
+      ).run();
+    }
+
+    it('find_recordings rows expose path = absolute source_path, plus label and kind', () => {
+      const db = freshDb();
+      try {
+        seedTwo(db);
+        const r = call(buildMcpHandler(db), {
+          jsonrpc: '2.0',
+          id: 400,
+          method: 'tools/call',
+          params: { name: 'find_recordings', arguments: {} },
+        });
+        const page = JSON.parse((r!.result as any).content[0].text);
+        expect(page.rows).toHaveLength(2);
+        const byKind = Object.fromEntries(page.rows.map((row: any) => [row.kind, row]));
+        expect(byKind.junit.path).toBe(
+          '/tmp/proj/tmp/appmap/junit/JunitTest_method_x.appmap.json'
+        );
+        expect(byKind.junit.path).toBe(byKind.junit.source_path);
+        expect(byKind.junit.label).toBe('JunitTest_method_x');
+        expect(byKind.request.path).toBe(
+          '/tmp/proj/tmp/appmap/request_recording/1779_post_orders.appmap.json'
+        );
+        expect(byKind.request.kind).toBe('request');
+      } finally {
+        db.close();
+      }
+    });
+
+    it('get_call_tree only accepts the canonical path; name / numeric id return a "not found" hint', () => {
+      const db = freshDb();
+      try {
+        seedTwo(db);
+        const handler = buildMcpHandler(db);
+        const list = call(handler, {
+          jsonrpc: '2.0',
+          id: 401,
+          method: 'tools/call',
+          params: { name: 'find_recordings', arguments: {} },
+        });
+        const junit = JSON.parse((list!.result as any).content[0].text).rows.find(
+          (row: any) => row.kind === 'junit'
+        );
+
+        // Canonical path: succeeds.
+        const ok = call(handler, {
+          jsonrpc: '2.0',
+          id: 402,
+          method: 'tools/call',
+          params: { name: 'get_call_tree', arguments: { appmap: junit.path } },
+        });
+        expect(ok!.error).toBeUndefined();
+        // Text mode is default; response surface is `tree` (string).
+        expect(typeof JSON.parse((ok!.result as any).content[0].text).tree).toBe('string');
+
+        // Recording name: rejected.
+        const byName = call(handler, {
+          jsonrpc: '2.0',
+          id: 403,
+          method: 'tools/call',
+          params: { name: 'get_call_tree', arguments: { appmap: junit.appmap_name } },
+        });
+        expect(byName!.error).toBeDefined();
+        expect(byName!.error!.message).toMatch(/not found at path/);
+
+        // Numeric id: rejected.
+        const byId = call(handler, {
+          jsonrpc: '2.0',
+          id: 404,
+          method: 'tools/call',
+          params: { name: 'get_call_tree', arguments: { appmap: String(junit.appmap_id) } },
+        });
+        expect(byId!.error).toBeDefined();
+        expect(byId!.error!.message).toMatch(/not found at path/);
+      } finally {
+        db.close();
+      }
+    });
+
+    it('find_calls attaches did_you_mean diagnostic on empty results', () => {
+      const db = freshDb();
+      try {
+        seedMinimal(db);
+        // Seed an Impl whose class is *not* a substring of the user's
+        // probe — only Levenshtein/component scoring should connect them.
+        db.prepare(
+          `INSERT INTO code_objects (fqid, package, classes, leaf_class, method, is_static)
+           VALUES ('app/PaymentServiceImpl#submit', 'app',
+                   '["PaymentServiceImpl"]', 'PaymentServiceImpl', 'submit', 0)`
+        ).run();
+        const co = (db
+          .prepare(`SELECT id FROM code_objects WHERE fqid = 'app/PaymentServiceImpl#submit'`)
+          .get() as { id: number }).id;
+        db.prepare(
+          `INSERT INTO function_calls (appmap_id, event_id, code_object_id, defined_class, method_id)
+           VALUES (1, 99, ?, 'PaymentServiceImpl', 'submit')`
+        ).run(co);
+
+        // Use a class that won't substring-match any leaf_class — substring
+        // is the existing behavior for find_calls, so the diagnostic only
+        // fires when no class match is found at all.
+        const r = call(buildMcpHandler(db), {
+          jsonrpc: '2.0',
+          id: 410,
+          method: 'tools/call',
+          params: { name: 'find_calls', arguments: { class: 'PmtSvc', method: 'submit' } },
+        });
+        const page = JSON.parse((r!.result as any).content[0].text);
+        expect(page.rows).toHaveLength(0);
+        expect(page.diagnostic).toBeDefined();
+        expect(
+          page.diagnostic.did_you_mean.some(
+            (d: any) => d.function_id === 'app/PaymentServiceImpl#submit'
+          )
+        ).toBe(true);
+      } finally {
+        db.close();
+      }
+    });
+
+    it('find_calls omits diagnostic when matches are non-empty', () => {
+      const db = freshDb();
+      try {
+        seedMinimal(db);
+        const r = call(buildMcpHandler(db), {
+          jsonrpc: '2.0',
+          id: 411,
+          method: 'tools/call',
+          params: { name: 'find_calls', arguments: { class: 'Logger' } },
+        });
+        const page = JSON.parse((r!.result as any).content[0].text);
+        expect(page.rows.length).toBeGreaterThan(0);
+        expect(page.diagnostic).toBeUndefined();
+      } finally {
+        db.close();
+      }
+    });
+
+    it('get_call_tree resolves cleanly when duplicate-basename recordings share a name (path is unambiguous)', () => {
+      // Regression: when a sticky/widened indexer scan leaves two
+      // recordings with the same basename and name in the DB — one at
+      // /tmp/proj, the other at /var/elsewhere — passing the absolute
+      // `path` field returned by find_recordings must resolve to that
+      // exact row (source_path is UNIQUE in the schema). Bare names
+      // are rejected outright by the strict resolver, with a hint
+      // pointing the caller back at the path field.
+      const db = freshDb();
+      try {
+        db.prepare(
+          `INSERT INTO appmaps (name, source_path, git_branch, sql_query_count, elapsed_ms, timestamp)
+           VALUES ('foo', '/tmp/proj/tmp/appmap/junit/foo.appmap.json',
+                   'main', 0, 100, '2026-04-29T12:00:00.000Z')`
+        ).run();
+        db.prepare(
+          `INSERT INTO appmaps (name, source_path, git_branch, sql_query_count, elapsed_ms, timestamp)
+           VALUES ('foo', '/var/elsewhere/tmp/appmap/junit/foo.appmap.json',
+                   'main', 0, 100, '2026-04-29T12:00:00.000Z')`
+        ).run();
+        db.prepare(
+          `INSERT INTO http_requests (appmap_id, event_id, parent_event_id, method, path, status_code, elapsed_ms)
+           VALUES (1, 1, NULL, 'GET', '/x', 200, 1)`
+        ).run();
+
+        const handler = buildMcpHandler(db);
+        // Absolute path: resolves cleanly.
+        const ok = call(handler, {
+          jsonrpc: '2.0',
+          id: 420,
+          method: 'tools/call',
+          params: {
+            name: 'get_call_tree',
+            arguments: { appmap: '/tmp/proj/tmp/appmap/junit/foo.appmap.json' },
+          },
+        });
+        expect(ok!.error).toBeUndefined();
+
+        // Bare name: rejected with a hint to use the path field.
+        const reject = call(handler, {
+          jsonrpc: '2.0',
+          id: 421,
+          method: 'tools/call',
+          params: { name: 'get_call_tree', arguments: { appmap: 'foo' } },
+        });
+        expect(reject!.error).toBeDefined();
+        expect(reject!.error!.message).toMatch(/not found at path/);
+        expect(reject!.error!.message).toMatch(/find_recordings/);
+      } finally {
+        db.close();
+      }
+    });
+
+    it('get_call_tree resolves a unique project-relative path', () => {
+      // Callers (especially LLM clients) often quote a recording by the
+      // project-relative path they see in junit reports — e.g. the path
+      // logged by appmap-node. Accept the suffix match when it's
+      // unambiguous so the agent's first call works without an extra
+      // find_recordings round-trip.
+      const db = freshDb();
+      try {
+        db.prepare(
+          `INSERT INTO appmaps (name, source_path, git_branch, sql_query_count, elapsed_ms, timestamp)
+           VALUES ('foo', '/tmp/proj/customer-portal-api/tmp/appmap/junit/foo.appmap.json',
+                   'main', 0, 100, '2026-04-29T12:00:00.000Z')`
+        ).run();
+        db.prepare(
+          `INSERT INTO http_requests (appmap_id, event_id, parent_event_id, method, path, status_code, elapsed_ms)
+           VALUES (1, 1, NULL, 'GET', '/x', 200, 1)`
+        ).run();
+        const handler = buildMcpHandler(db);
+        const ok = call(handler, {
+          jsonrpc: '2.0',
+          id: 430,
+          method: 'tools/call',
+          params: {
+            name: 'get_call_tree',
+            arguments: {
+              appmap: 'customer-portal-api/tmp/appmap/junit/foo.appmap.json',
+            },
+          },
+        });
+        expect(ok!.error).toBeUndefined();
+        expect(typeof JSON.parse((ok!.result as any).content[0].text).tree).toBe('string');
+      } finally {
+        db.close();
+      }
+    });
+
+    it('get_call_tree errors with candidate paths when a relative path is ambiguous', () => {
+      const db = freshDb();
+      try {
+        db.prepare(
+          `INSERT INTO appmaps (name, source_path, git_branch, sql_query_count, elapsed_ms, timestamp)
+           VALUES ('foo', '/tmp/proj-a/tmp/appmap/junit/foo.appmap.json',
+                   'main', 0, 100, '2026-04-29T12:00:00.000Z')`
+        ).run();
+        db.prepare(
+          `INSERT INTO appmaps (name, source_path, git_branch, sql_query_count, elapsed_ms, timestamp)
+           VALUES ('foo', '/tmp/proj-b/tmp/appmap/junit/foo.appmap.json',
+                   'main', 0, 100, '2026-04-29T12:00:00.000Z')`
+        ).run();
+        const handler = buildMcpHandler(db);
+        const r = call(handler, {
+          jsonrpc: '2.0',
+          id: 431,
+          method: 'tools/call',
+          params: {
+            name: 'get_call_tree',
+            arguments: { appmap: 'tmp/appmap/junit/foo.appmap.json' },
+          },
+        });
+        expect(r!.error).toBeDefined();
+        expect(r!.error!.message).toMatch(/ambiguous/);
+        expect(r!.error!.message).toContain('/tmp/proj-a/tmp/appmap/junit/foo.appmap.json');
+        expect(r!.error!.message).toContain('/tmp/proj-b/tmp/appmap/junit/foo.appmap.json');
+      } finally {
+        db.close();
+      }
+    });
+
+    it('get_call_tree rejects display-label refs with a hint', () => {
+      const db = freshDb();
+      try {
+        seedTwo(db);
+        const r = call(buildMcpHandler(db), {
+          jsonrpc: '2.0',
+          id: 403,
+          method: 'tools/call',
+          params: {
+            name: 'get_call_tree',
+            arguments: { appmap: 'POST /orders (200) - 19:47:22.660' },
+          },
+        });
+        expect(r!.error).toBeDefined();
+        expect(r!.error!.message).toMatch(/display label/);
+        expect(r!.error!.message).toMatch(/find_recordings/);
+      } finally {
+        db.close();
+      }
+    });
+  });
+
+  describe('get_call_tree default selection', () => {
+    function seedRecording(
+      db: sqlite3.Database,
+      opts: { recorderType: string; eventCount: number; httpRequestCount?: number; sourcePath?: string }
+    ): { id: number; path: string } {
+      const path = opts.sourcePath ?? '/tmp/auto.appmap.json';
+      const am = db
+        .prepare(
+          `INSERT INTO appmaps (name, source_path, recorder_type, event_count, http_request_count, sql_query_count, elapsed_ms, timestamp)
+           VALUES ('auto', ?, ?, ?, ?, 0, 50, '2026-04-29T12:00:00.000Z')`
+        )
+        .run(path, opts.recorderType, opts.eventCount, opts.httpRequestCount ?? 0);
+      // Add at least one event so tree() returns something. The
+      // recorded event_count above is what the heuristic reads — the
+      // actual rows can be sparse for tests that don't care about depth.
+      db.prepare(
+        `INSERT INTO function_calls (appmap_id, event_id, parent_event_id, defined_class, method_id, path, lineno, elapsed_ms)
+         VALUES (?, 1, NULL, 'App', 'main', '/src/App.java', 1, 5)`
+      ).run(am.lastInsertRowid);
+      return { id: Number(am.lastInsertRowid), path };
+    }
+
+    it('auto-selects child_depth=2 on broad recordings in JSON mode (event_count > 500)', () => {
+      const db = freshDb();
+      try {
+        const { path } = seedRecording(db, { recorderType: 'tests', eventCount: 1500 });
+        const r = call(buildMcpHandler(db), {
+          jsonrpc: '2.0',
+          id: 500,
+          method: 'tools/call',
+          params: { name: 'get_call_tree', arguments: { appmap: path, format: 'json' } },
+        });
+        const out = JSON.parse((r!.result as any).content[0].text);
+        expect(out.chosen_params).toEqual({
+          parent_depth: null,
+          child_depth: 2,
+          focus_type: null,
+          focus_value: null,
+        });
+        expect(out.reason).toMatch(/1500 events/);
+        expect(out.reason).toMatch(/child_depth=2/);
+      } finally {
+        db.close();
+      }
+    });
+
+    it('JSON mode keeps default child_depth on narrow per-request recordings', () => {
+      const db = freshDb();
+      try {
+        const { path } = seedRecording(db, {
+          recorderType: 'http_server_request',
+          eventCount: 5000,
+          httpRequestCount: 1,
+        });
+        const r = call(buildMcpHandler(db), {
+          jsonrpc: '2.0',
+          id: 501,
+          method: 'tools/call',
+          params: { name: 'get_call_tree', arguments: { appmap: path, format: 'json' } },
+        });
+        const out = JSON.parse((r!.result as any).content[0].text);
+        // Narrow recordings keep the existing default — chosen child_depth
+        // is undefined here because the user didn't supply one and the
+        // heuristic didn't pre-select one. tree() applies its own default
+        // (DEFAULT_DESCENDANTS=4) internally.
+        expect(out.chosen_params.child_depth).toBeNull();
+        expect(out.chosen_params.focus_type).toBeNull();
+        expect(out.reason).toBeUndefined();
+      } finally {
+        db.close();
+      }
+    });
+
+    it('JSON mode keeps default child_depth on small recordings regardless of recorder_type', () => {
+      const db = freshDb();
+      try {
+        const { path } = seedRecording(db, { recorderType: 'tests', eventCount: 100 });
+        const r = call(buildMcpHandler(db), {
+          jsonrpc: '2.0',
+          id: 502,
+          method: 'tools/call',
+          params: { name: 'get_call_tree', arguments: { appmap: path, format: 'json' } },
+        });
+        const out = JSON.parse((r!.result as any).content[0].text);
+        expect(out.chosen_params.child_depth).toBeNull();
+        expect(out.reason).toBeUndefined();
+      } finally {
+        db.close();
+      }
+    });
+
+    it('JSON mode respects explicit child_depth even on broad recordings', () => {
+      const db = freshDb();
+      try {
+        const { path } = seedRecording(db, { recorderType: 'tests', eventCount: 1500 });
+        const r = call(buildMcpHandler(db), {
+          jsonrpc: '2.0',
+          id: 503,
+          method: 'tools/call',
+          params: {
+            name: 'get_call_tree',
+            arguments: { appmap: path, child_depth: 6, format: 'json' },
+          },
+        });
+        const out = JSON.parse((r!.result as any).content[0].text);
+        expect(out.chosen_params.child_depth).toBe(6);
+        // The auto-reason is suppressed when the user specified the value.
+        expect(out.reason).toBeUndefined();
+      } finally {
+        db.close();
+      }
+    });
+
+    it('text mode (default) replaces JSON nodes[] with a budgeted tree string', () => {
+      const db = freshDb();
+      try {
+        const { path } = seedRecording(db, { recorderType: 'tests', eventCount: 1500 });
+        const r = call(buildMcpHandler(db), {
+          jsonrpc: '2.0',
+          id: 510,
+          method: 'tools/call',
+          params: { name: 'get_call_tree', arguments: { appmap: path } },
+        });
+        const out = JSON.parse((r!.result as any).content[0].text);
+        // Text mode replaces nodes[] with `tree` + clip stats and applies
+        // the default 12K byte budget.  child_depth is the deep-fetch
+        // value (DEEP_FETCH_DEPTH_FOR_BUDGET), not the legacy broad
+        // auto-tune value, so the renderer has material to trim from.
+        expect(typeof out.tree).toBe('string');
+        expect(out.nodes).toBeUndefined();
+        expect(out.max_chars).toBe(12_000);
+        expect(out.chosen_params.child_depth).toBe(8);
+        expect(out.reason).toMatch(/text mode/);
+        expect(out.reason).toMatch(/child_depth=8/);
+      } finally {
+        db.close();
+      }
+    });
+
+    it('text mode honors an explicit max_chars override', () => {
+      const db = freshDb();
+      try {
+        const { path } = seedRecording(db, { recorderType: 'tests', eventCount: 1500 });
+        const r = call(buildMcpHandler(db), {
+          jsonrpc: '2.0',
+          id: 511,
+          method: 'tools/call',
+          params: {
+            name: 'get_call_tree',
+            arguments: { appmap: path, max_chars: 4_000 },
+          },
+        });
+        const out = JSON.parse((r!.result as any).content[0].text);
+        expect(out.max_chars).toBe(4_000);
+        expect(out.bytes_used).toBeLessThanOrEqual(4_000);
+      } finally {
+        db.close();
+      }
+    });
+
+    it('text mode honors explicit child_depth as a depth ceiling alongside max_chars', () => {
+      // Both ceilings apply.  child_depth caps the DB fetch (the renderer
+      // never sees deeper nodes); max_chars caps the rendered bytes.
+      const db = freshDb();
+      try {
+        const { path } = seedRecording(db, { recorderType: 'tests', eventCount: 1500 });
+        const r = call(buildMcpHandler(db), {
+          jsonrpc: '2.0',
+          id: 512,
+          method: 'tools/call',
+          params: {
+            name: 'get_call_tree',
+            arguments: { appmap: path, child_depth: 2, max_chars: 20_000 },
+          },
+        });
+        const out = JSON.parse((r!.result as any).content[0].text);
+        expect(out.chosen_params.child_depth).toBe(2);
+        expect(out.max_chars).toBe(20_000);
+        // No auto-reason — caller picked child_depth explicitly.
+        expect(out.reason).toBeUndefined();
+      } finally {
+        db.close();
+      }
+    });
+
+    it('json mode ignores max_chars', () => {
+      const db = freshDb();
+      try {
+        const { path } = seedRecording(db, { recorderType: 'tests', eventCount: 1500 });
+        const r = call(buildMcpHandler(db), {
+          jsonrpc: '2.0',
+          id: 513,
+          method: 'tools/call',
+          params: {
+            name: 'get_call_tree',
+            arguments: { appmap: path, max_chars: 1_000, format: 'json' },
+          },
+        });
+        const out = JSON.parse((r!.result as any).content[0].text);
+        // JSON mode keeps the legacy nodes[] surface; max_chars isn't
+        // surfaced in the response.
+        expect(out.max_chars).toBeUndefined();
+        expect(out.tree).toBeUndefined();
+        expect(Array.isArray(out.nodes)).toBe(true);
+      } finally {
+        db.close();
+      }
+    });
+
+    it('returns a diagnostic when focus excludes everything', () => {
+      const db = freshDb();
+      try {
+        // junit recording with no http server requests; agent tries to
+        // focus on http_server_request and gets nothing back.
+        const { path } = seedRecording(db, {
+          recorderType: 'tests',
+          eventCount: 100,
+          httpRequestCount: 0,
+        });
+        const r = call(buildMcpHandler(db), {
+          jsonrpc: '2.0',
+          id: 504,
+          method: 'tools/call',
+          params: {
+            name: 'get_call_tree',
+            arguments: {
+              appmap: path,
+              focus_type: 'http_server_request',
+              focus_value: '/anything',
+              format: 'json',
+            },
+          },
+        });
+        const out = JSON.parse((r!.result as any).content[0].text);
+        expect(out.nodes).toEqual([]);
+        expect(out.diagnostic).toMatch(/no events of type 'http_server_request'/);
+        expect(out.diagnostic).toMatch(/recorder_type=tests/);
+        expect(out.diagnostic).toMatch(/no HTTP server requests/);
+        expect(out.chosen_params.focus_type).toBe('http_server_request');
+      } finally {
+        db.close();
+      }
+    });
+
+    it('json mode falls back to summary_mode when the response would exceed the budget', () => {
+      const db = freshDb();
+      try {
+        // Insert one entry-point HTTP request + many fat function calls
+        // so the JSON serialization easily clears RESPONSE_BUDGET_CHARS
+        // (40_000). Each row carries a kilobyte of parameters_json so we
+        // hit the budget without seeding tens of thousands of rows.
+        const am = db
+          .prepare(
+            `INSERT INTO appmaps (name, source_path, recorder_type, event_count, http_request_count, sql_query_count, elapsed_ms, timestamp)
+             VALUES ('big', '/tmp/big.appmap.json', 'tests', 5000, 1, 0, 5000, '2026-04-29T12:00:00.000Z')`
+          )
+          .run();
+        const id = am.lastInsertRowid;
+        db.prepare(
+          `INSERT INTO http_requests (appmap_id, event_id, parent_event_id, method, path, status_code, elapsed_ms)
+           VALUES (?, 1, NULL, 'GET', '/api/big', 200, 5000)`
+        ).run(id);
+        const big = 'x'.repeat(1024);
+        for (let i = 2; i < 100; i += 1) {
+          db.prepare(
+            `INSERT INTO function_calls (appmap_id, event_id, parent_event_id, defined_class, method_id, path, lineno, elapsed_ms, parameters_json)
+             VALUES (?, ?, 1, 'C', 'm', '/src/C.java', ?, ?, ?)`
+          ).run(id, i, i, i, JSON.stringify([{ value: big }]));
+        }
+        const r = call(buildMcpHandler(db), {
+          jsonrpc: '2.0',
+          id: 505,
+          method: 'tools/call',
+          params: {
+            name: 'get_call_tree',
+            arguments: { appmap: '/tmp/big.appmap.json', format: 'json' },
+          },
+        });
+        const out = JSON.parse((r!.result as any).content[0].text);
+        expect(out.summary_mode).toBe(true);
+        expect(out.nodes.some((n: any) => n.kind === 'http_server')).toBe(true);
+        expect(out.nodes.some((n: any) => n.kind === 'function')).toBe(false);
+        expect(Array.isArray(out.suggested_drilldown)).toBe(true);
+        expect(out.suggested_drilldown.length).toBeGreaterThan(0);
+        expect(out.suggested_drilldown[0]).toEqual(
+          expect.objectContaining({
+            event_id: expect.any(Number),
+            elapsed_ms: expect.any(Number),
+            child_count: expect.any(Number),
+          })
+        );
+        // Drilldown is sorted by elapsed_ms desc.
+        const elapsed: number[] = out.suggested_drilldown.map((d: any) => d.elapsed_ms);
+        for (let i = 1; i < elapsed.length; i += 1) {
+          expect(elapsed[i - 1]).toBeGreaterThanOrEqual(elapsed[i]);
+        }
+        expect(out.reason).toMatch(/over the .*-char budget/);
+      } finally {
+        db.close();
+      }
+    });
+  });
+});
diff --git a/packages/cli/tests/unit/cmds/query/queries/related.spec.ts b/packages/cli/tests/unit/cmds/query/queries/related.spec.ts
new file mode 100644
index 0000000000..19e330de1b
--- /dev/null
+++ b/packages/cli/tests/unit/cmds/query/queries/related.spec.ts
@@ -0,0 +1,205 @@
+import sqlite3 from 'better-sqlite3';
+
+import { openQueryDb } from '../../../../../src/cmds/query/db/openQueryDb';
+import {
+  extractTables,
+  related,
+} from '../../../../../src/cmds/query/queries/related';
+
+function freshDb(): sqlite3.Database {
+  return openQueryDb('/tmp/ignored', ':memory:').db;
+}
+
+interface SeedRecording {
+  name: string;
+  branch?: string;
+  request?: { method: string; path: string; status: number; elapsed_ms?: number };
+  sqls?: string[];
+  classes?: string[]; // leaf names; we register code_objects for each
+}
+
+function seed(db: sqlite3.Database, recs: SeedRecording[]): void {
+  const insAm = db.prepare(
+    `INSERT INTO appmaps (name, source_path, git_branch, elapsed_ms) VALUES (?, ?, ?, ?)`
+  );
+  const insReq = db.prepare(
+    `INSERT INTO http_requests (appmap_id, event_id, method, path, status_code, elapsed_ms)
+     VALUES (?, 1, ?, ?, ?, ?)`
+  );
+  const insQ = db.prepare(
+    `INSERT INTO sql_queries (appmap_id, event_id, sql_text) VALUES (?, ?, ?)`
+  );
+  const insCo = db.prepare(
+    `INSERT OR IGNORE INTO code_objects (fqid, package, classes, leaf_class, method, is_static)
+     VALUES (?, ?, ?, ?, ?, ?)`
+  );
+  const selCo = db.prepare(`SELECT id FROM code_objects WHERE fqid = ?`);
+  const insCall = db.prepare(
+    `INSERT INTO function_calls (appmap_id, event_id, defined_class, method_id, code_object_id)
+     VALUES (?, ?, ?, ?, ?)`
+  );
+
+  let nextEvent = 100;
+  for (const r of recs) {
+    const am = insAm.run(
+      r.name,
+      `/tmp/${r.name}.appmap.json`,
+      r.branch ?? null,
+      r.request?.elapsed_ms ?? null
+    );
+    const aid = Number(am.lastInsertRowid);
+    if (r.request) {
+      insReq.run(
+        aid,
+        r.request.method,
+        r.request.path,
+        r.request.status,
+        r.request.elapsed_ms ?? null
+      );
+    }
+    for (const sql of r.sqls ?? []) {
+      insQ.run(aid, nextEvent++, sql);
+    }
+    for (const cls of r.classes ?? []) {
+      const fqid = `app/${cls}#m`;
+      insCo.run(fqid, 'app', JSON.stringify([cls]), cls, 'm', 0);
+      const co = selCo.get(fqid) as { id: number };
+      insCall.run(aid, nextEvent++, cls, 'm', co.id);
+    }
+  }
+}
+
+describe('extractTables', () => {
+  it('extracts FROM/JOIN/INTO/UPDATE table names case-insensitively', () => {
+    const sql =
+      "SELECT * FROM users u JOIN orders o ON u.id = o.user_id WHERE u.id = 1; INSERT INTO logs VALUES (1); UPDATE Sessions SET x=1";
+    expect([...extractTables(sql)].sort()).toEqual(['logs', 'orders', 'sessions', 'users']);
+  });
+
+  it('strips a single leading schema qualifier', () => {
+    expect(extractTables('SELECT * FROM public.orders')).toEqual(new Set(['orders']));
+  });
+});
+
+describe('related', () => {
+  it('scores by route + tables + classes; excludes the source', () => {
+    const db = freshDb();
+    try {
+      seed(db, [
+        {
+          name: 'source',
+          request: { method: 'POST', path: '/orders', status: 500 },
+          sqls: ['INSERT INTO orders VALUES (1)', 'SELECT * FROM users WHERE id = 1'],
+          classes: ['OrdersController', 'IdempotencyKey'],
+        },
+        {
+          name: 'best',
+          request: { method: 'POST', path: '/orders', status: 201, elapsed_ms: 140 },
+          sqls: ['INSERT INTO orders VALUES (1)', 'SELECT * FROM users WHERE id = 1'],
+          classes: ['OrdersController', 'IdempotencyKey'],
+        },
+        {
+          name: 'partial',
+          request: { method: 'POST', path: '/orders', status: 201 },
+          sqls: ['INSERT INTO orders VALUES (1)'],
+          classes: ['OrdersController'],
+        },
+        {
+          name: 'unrelated',
+          request: { method: 'GET', path: '/healthz', status: 200 },
+          sqls: [],
+          classes: ['HealthController'],
+        },
+      ]);
+      const rows = related(db, 'source').rows;
+      expect(rows.find((r) => r.appmap_name === 'source')).toBeUndefined();
+      expect(rows.find((r) => r.appmap_name === 'unrelated')).toBeUndefined();
+      const best = rows.find((r) => r.appmap_name === 'best')!;
+      const partial = rows.find((r) => r.appmap_name === 'partial')!;
+      // best: route(5) + 2 tables*3 + 2 classes*2 = 15
+      expect(best.score).toBe(15);
+      expect(best.shared).toContain('route');
+      expect(best.shared).toContain('orders');
+      expect(best.shared).toContain('users');
+      expect(best.shared).toContain('OrdersController');
+      // partial: route(5) + 1 table*3 + 1 class*2 = 10
+      expect(partial.score).toBe(10);
+      // best ranks first
+      expect(rows[0].appmap_name).toBe('best');
+    } finally {
+      db.close();
+    }
+  });
+
+  it('--branch scopes the candidate pool', () => {
+    const db = freshDb();
+    try {
+      seed(db, [
+        {
+          name: 'src',
+          branch: 'main',
+          request: { method: 'GET', path: '/x', status: 200 },
+          classes: ['Foo'],
+        },
+        {
+          name: 'main_match',
+          branch: 'main',
+          request: { method: 'GET', path: '/x', status: 200 },
+          classes: ['Foo'],
+        },
+        {
+          name: 'feature_match',
+          branch: 'feature',
+          request: { method: 'GET', path: '/x', status: 200 },
+          classes: ['Foo'],
+        },
+      ]);
+      const rows = related(db, 'src', { branch: 'main' }).rows;
+      expect(rows.map((r) => r.appmap_name)).toEqual(['main_match']);
+    } finally {
+      db.close();
+    }
+  });
+
+  it('--status filters candidates to recordings with a matching response', () => {
+    const db = freshDb();
+    try {
+      seed(db, [
+        {
+          name: 'src',
+          request: { method: 'POST', path: '/orders', status: 500 },
+          classes: ['Foo'],
+        },
+        {
+          name: 'succeeded',
+          request: { method: 'POST', path: '/orders', status: 201 },
+          classes: ['Foo'],
+        },
+        {
+          name: 'also_failed',
+          request: { method: 'POST', path: '/orders', status: 500 },
+          classes: ['Foo'],
+        },
+      ]);
+      const rows = related(db, 'src', { status: { op: '<', value: 400 } }).rows;
+      expect(rows.map((r) => r.appmap_name)).toEqual(['succeeded']);
+    } finally {
+      db.close();
+    }
+  });
+
+  it('--limit caps the result set', () => {
+    const db = freshDb();
+    try {
+      seed(db, [
+        { name: 'src', request: { method: 'GET', path: '/x', status: 200 }, classes: ['A', 'B'] },
+        { name: 'a', request: { method: 'GET', path: '/x', status: 200 }, classes: ['A', 'B'] },
+        { name: 'b', request: { method: 'GET', path: '/x', status: 200 }, classes: ['A'] },
+        { name: 'c', request: { method: 'GET', path: '/x', status: 200 }, classes: ['B'] },
+      ]);
+      expect(related(db, 'src', { limit: 2 }).rows).toHaveLength(2);
+    } finally {
+      db.close();
+    }
+  });
+});
diff --git a/packages/cli/tests/unit/cmds/query/queries/tree.spec.ts b/packages/cli/tests/unit/cmds/query/queries/tree.spec.ts
new file mode 100644
index 0000000000..e9497eb5af
--- /dev/null
+++ b/packages/cli/tests/unit/cmds/query/queries/tree.spec.ts
@@ -0,0 +1,550 @@
+import sqlite3 from 'better-sqlite3';
+
+import { openQueryDb } from '../../../../../src/cmds/query/db/openQueryDb';
+import {
+  resolveAppmap,
+  tree,
+  treeSummary,
+  treeWithMeta,
+} from '../../../../../src/cmds/query/queries/tree';
+
+function freshDb(): sqlite3.Database {
+  return openQueryDb('/tmp/ignored', ':memory:').db;
+}
+
+// Seed a recording shaped like the V3 worked-session example: an HTTP request
+// at depth 0, a controller call beneath it, an SQL query beneath the
+// controller, and an exception on the same call.
+function seed(
+  db: sqlite3.Database,
+  opts: {
+    name?: string;
+    branch?: string;
+    addLabel?: boolean;
+    addOutbound?: boolean;
+  } = {}
+): number {
+  const am = db
+    .prepare(
+      `INSERT INTO appmaps (name, source_path, git_branch, sql_query_count)
+       VALUES (?, ?, ?, ?)`
+    )
+    .run(
+      opts.name ?? 'orders_create_42',
+      `/tmp/${opts.name ?? 'orders_create_42'}.appmap.json`,
+      opts.branch ?? 'main',
+      1
+    );
+  const id = am.lastInsertRowid;
+
+  // event_id 1: HTTP server request, parent_event_id null (root)
+  db.prepare(
+    `INSERT INTO http_requests (appmap_id, event_id, parent_event_id, thread_id,
+       method, path, status_code, elapsed_ms)
+     VALUES (?, 1, NULL, 1, 'POST', '/orders', 500, 520.0)`
+  ).run(id);
+
+  // event_id 2: controller call, parent = 1
+  let coId = 1;
+  db.prepare(
+    `INSERT OR IGNORE INTO code_objects (fqid, package, classes, leaf_class, method, is_static)
+     VALUES ('app/OrdersController#create', 'app', '["OrdersController"]', 'OrdersController', 'create', 0)`
+  ).run();
+  coId = (db
+    .prepare(`SELECT id FROM code_objects WHERE fqid = 'app/OrdersController#create'`)
+    .get() as { id: number }).id;
+
+  if (opts.addLabel) {
+    db.prepare(`INSERT OR IGNORE INTO labels (code_object_id, label) VALUES (?, 'log')`).run(coId);
+  }
+
+  db.prepare(
+    `INSERT INTO function_calls (appmap_id, event_id, parent_event_id, thread_id,
+       code_object_id, defined_class, method_id, elapsed_ms)
+     VALUES (?, 2, 1, 1, ?, 'OrdersController', 'create', 519.0)`
+  ).run(id, coId);
+
+  // event_id 3: sql_query, parent = 2
+  db.prepare(
+    `INSERT INTO sql_queries (appmap_id, event_id, parent_event_id, thread_id,
+       sql_text, database_type, elapsed_ms)
+     VALUES (?, 3, 2, 1, 'INSERT INTO orders (...)', 'postgres', 14.0)`
+  ).run(id);
+
+  // event_id 4: exception, owned by call 2 (carried by its return event)
+  db.prepare(
+    `INSERT INTO exceptions (appmap_id, event_id, parent_event_id, thread_id,
+       exception_class, message, path, lineno)
+     VALUES (?, 2, 1, 1, 'IntegrityError', 'duplicate key',
+             'app/models/order.rb', 42)`
+  ).run(id);
+
+  if (opts.addOutbound) {
+    db.prepare(
+      `INSERT INTO http_client_requests (appmap_id, event_id, parent_event_id, thread_id,
+         method, url, status_code, elapsed_ms)
+       VALUES (?, 5, 2, 1, 'GET', 'https://api.example/v1', 200, 40.0)`
+    ).run(id);
+  }
+
+  return Number(id);
+}
+
+describe('resolveAppmap', () => {
+  it('resolves by exact name match', () => {
+    const db = freshDb();
+    try {
+      seed(db);
+      expect(resolveAppmap(db, 'orders_create_42').name).toBe('orders_create_42');
+    } finally {
+      db.close();
+    }
+  });
+
+  it('resolves by source-path basename', () => {
+    const db = freshDb();
+    try {
+      // Insert an appmap whose name doesn't match the basename.
+      db.prepare(
+        `INSERT INTO appmaps (name, source_path) VALUES ('Friendly Name', '/x/foo.appmap.json')`
+      ).run();
+      expect(resolveAppmap(db, 'foo').source_path).toBe('/x/foo.appmap.json');
+    } finally {
+      db.close();
+    }
+  });
+
+  it('throws on miss', () => {
+    const db = freshDb();
+    try {
+      expect(() => resolveAppmap(db, 'nope')).toThrow(/not found/);
+    } finally {
+      db.close();
+    }
+  });
+
+  it('throws on ambiguous match', () => {
+    const db = freshDb();
+    try {
+      seed(db, { name: 'a' });
+      db.prepare(
+        `INSERT INTO appmaps (name, source_path) VALUES ('a', '/y/a.appmap.json')`
+      ).run();
+      expect(() => resolveAppmap(db, 'a')).toThrow(/ambiguous/);
+    } finally {
+      db.close();
+    }
+  });
+});
+
+describe('tree', () => {
+  it('returns nodes in event_id order with computed depths', () => {
+    const db = freshDb();
+    try {
+      seed(db);
+      const nodes = tree(db, 'orders_create_42');
+
+      expect(nodes.map((n) => n.event_id)).toEqual([1, 2, 2, 3]);
+      // event 1: HTTP server (root).
+      expect(nodes[0].kind).toBe('http_server');
+      expect(nodes[0].depth).toBe(0);
+      // event 2: function call (under request).
+      const fn = nodes.find((n) => n.kind === 'function')!;
+      expect(fn.depth).toBe(1);
+      // event 2 also has an exception attached (same event_id, separate row).
+      const exc = nodes.find((n) => n.kind === 'exception')!;
+      expect(exc.depth).toBe(1);
+      // event 3: SQL under the function call.
+      const sql = nodes.find((n) => n.kind === 'sql')!;
+      expect(sql.depth).toBe(2);
+    } finally {
+      db.close();
+    }
+  });
+
+  it('exception nodes carry path and lineno', () => {
+    const db = freshDb();
+    try {
+      seed(db);
+      const exc = tree(db, 'orders_create_42').find((n) => n.kind === 'exception');
+      expect(exc).toBeDefined();
+      if (exc?.kind === 'exception') {
+        expect(exc.path).toBe('app/models/order.rb');
+        expect(exc.lineno).toBe(42);
+      }
+    } finally {
+      db.close();
+    }
+  });
+
+  it('joins fqid into function nodes', () => {
+    const db = freshDb();
+    try {
+      seed(db);
+      const nodes = tree(db, 'orders_create_42');
+      const fn = nodes.find((n) => n.kind === 'function')!;
+      // @ts-expect-error narrowing not visible here without further check
+      expect(fn.fqid).toBe('app/OrdersController#create');
+    } finally {
+      db.close();
+    }
+  });
+});
+
+describe('tree focus', () => {
+  // Build a richer recording: HTTP root → controller → 3 sibling calls
+  // (one of which calls a deeper helper) → SQL + EXC under controller.
+  function seedRich(db: sqlite3.Database): void {
+    const am = db
+      .prepare(
+        `INSERT INTO appmaps (name, source_path, sql_query_count) VALUES ('rich', '/tmp/rich.appmap.json', 1)`
+      )
+      .run();
+    const id = am.lastInsertRowid;
+    db.prepare(
+      `INSERT INTO http_requests (appmap_id, event_id, parent_event_id, method, path, status_code, elapsed_ms)
+       VALUES (?, 1, NULL, 'POST', '/orders', 500, 520.0)`
+    ).run(id);
+    db.prepare(
+      `INSERT INTO function_calls (appmap_id, event_id, parent_event_id, defined_class, method_id, elapsed_ms)
+       VALUES (?, 2, 1, 'OrdersController', 'create', 519.0)`
+    ).run(id);
+    db.prepare(
+      `INSERT OR IGNORE INTO code_objects (fqid, package, classes, leaf_class, method, is_static)
+       VALUES ('app/IdempotencyKey.generate', 'app', '["IdempotencyKey"]', 'IdempotencyKey', 'generate', 1)`
+    ).run();
+    const co = (db
+      .prepare(`SELECT id FROM code_objects WHERE fqid = 'app/IdempotencyKey.generate'`)
+      .get() as { id: number }).id;
+    db.prepare(
+      `INSERT INTO function_calls (appmap_id, event_id, parent_event_id, code_object_id, defined_class, method_id, elapsed_ms)
+       VALUES (?, 3, 2, ?, 'IdempotencyKey', 'generate', 0.2)`
+    ).run(id, co);
+    db.prepare(
+      `INSERT INTO function_calls (appmap_id, event_id, parent_event_id, defined_class, method_id, elapsed_ms)
+       VALUES (?, 4, 2, 'Order', 'new', 0.4)`
+    ).run(id);
+    db.prepare(
+      `INSERT INTO sql_queries (appmap_id, event_id, parent_event_id, sql_text, elapsed_ms)
+       VALUES (?, 5, 2, 'INSERT INTO orders (id, name) VALUES (?, ?)', 14.0)`
+    ).run(id);
+    db.prepare(
+      `INSERT INTO exceptions (appmap_id, event_id, parent_event_id, exception_class, message)
+       VALUES (?, 2, 1, 'IntegrityError', 'duplicate key')`
+    ).run(id);
+    // Add an outbound HTTP call as a separate child of controller
+    db.prepare(
+      `INSERT INTO http_client_requests (appmap_id, event_id, parent_event_id, method, url, status_code, elapsed_ms)
+       VALUES (?, 6, 2, 'GET', 'https://api.example/v1', 200, 40.0)`
+    ).run(id);
+    // A deeper descendant under IdempotencyKey.generate (event_id 3)
+    db.prepare(
+      `INSERT INTO function_calls (appmap_id, event_id, parent_event_id, defined_class, method_id, elapsed_ms)
+       VALUES (?, 7, 3, 'Digest', 'sha256', 0.05)`
+    ).run(id);
+  }
+
+  it('--focus-sql narrows to the matching SQL plus its ancestors and their children', () => {
+    const db = freshDb();
+    try {
+      seedRich(db);
+      const nodes = tree(db, 'rich', { focusSql: 'INSERT INTO orders' });
+      const ids = new Set(nodes.map((n) => n.event_id));
+      // Includes: HTTP (1), controller (2), SQL (5), and the controller's
+      // direct children (3, 4, 5, 6, 7? No — children of controller are
+      // 3, 4, 5, 6 only; 7 is a descendant of 3, not a sibling of focus).
+      expect(ids.has(1)).toBe(true);
+      expect(ids.has(2)).toBe(true);
+      expect(ids.has(5)).toBe(true);
+      expect(ids.has(3)).toBe(true); // sibling
+      expect(ids.has(4)).toBe(true); // sibling
+      expect(ids.has(6)).toBe(true); // sibling
+      // 7 is a child of 3, not of an ancestor of the focus.
+      expect(ids.has(7)).toBe(false);
+    } finally {
+      db.close();
+    }
+  });
+
+  it('--focus-fn matches by canonical fqid', () => {
+    const db = freshDb();
+    try {
+      seedRich(db);
+      const nodes = tree(db, 'rich', { focusFn: 'app/IdempotencyKey.generate' });
+      const ids = new Set(nodes.map((n) => n.event_id));
+      // Focus event_id 3; ancestors 2, 1; children of ancestors include
+      // siblings 4, 5, 6 (children of 2). Descendants of 3: 7.
+      expect(ids.has(1)).toBe(true);
+      expect(ids.has(2)).toBe(true);
+      expect(ids.has(3)).toBe(true);
+      expect(ids.has(4)).toBe(true);
+      expect(ids.has(5)).toBe(true);
+      expect(ids.has(6)).toBe(true);
+      expect(ids.has(7)).toBe(true); // descendant
+    } finally {
+      db.close();
+    }
+  });
+
+  it('--focus-route matches a server request', () => {
+    const db = freshDb();
+    try {
+      seedRich(db);
+      const nodes = tree(db, 'rich', { focusRoute: '/orders' });
+      // The HTTP request matches; ancestors of HTTP = none; descendants
+      // of the focus drill down. With descendants=3 we get the full tree
+      // up to depth 3 from the request.
+      expect(nodes.find((n) => n.kind === 'http_server')).toBeDefined();
+      expect(nodes.find((n) => n.kind === 'function' && n.method_id === 'create')).toBeDefined();
+    } finally {
+      db.close();
+    }
+  });
+
+  it('--focus-url matches an outbound call', () => {
+    const db = freshDb();
+    try {
+      seedRich(db);
+      const nodes = tree(db, 'rich', { focusUrl: 'api.example' });
+      const ids = new Set(nodes.map((n) => n.event_id));
+      expect(ids.has(6)).toBe(true);
+    } finally {
+      db.close();
+    }
+  });
+
+  it('--ancestors=1 trims the path to root', () => {
+    const db = freshDb();
+    try {
+      seedRich(db);
+      const nodes = tree(db, 'rich', { focusFn: 'app/IdempotencyKey.generate', ancestors: 1 });
+      const ids = new Set(nodes.map((n) => n.event_id));
+      // Only controller (1 ancestor) — not HTTP.
+      expect(ids.has(2)).toBe(true);
+      expect(ids.has(1)).toBe(false);
+    } finally {
+      db.close();
+    }
+  });
+
+  it('--descendants=0 drops the subtree below focus', () => {
+    const db = freshDb();
+    try {
+      seedRich(db);
+      const nodes = tree(db, 'rich', {
+        focusFn: 'app/IdempotencyKey.generate',
+        descendants: 0,
+      });
+      const ids = new Set(nodes.map((n) => n.event_id));
+      // 7 (descendant of focus) excluded.
+      expect(ids.has(3)).toBe(true);
+      expect(ids.has(7)).toBe(false);
+    } finally {
+      db.close();
+    }
+  });
+
+  it('--min-elapsed-ms prunes fast subtrees', () => {
+    const db = freshDb();
+    try {
+      seedRich(db);
+      const nodes = tree(db, 'rich', { minElapsedMs: 10 });
+      const ids = new Set(nodes.map((n) => n.event_id));
+      // SQL (14ms) and outbound HTTP (40ms) survive; IdempotencyKey
+      // (0.2ms with no fast descendant) and Order.new (0.4ms) are pruned.
+      expect(ids.has(5)).toBe(true);
+      expect(ids.has(6)).toBe(true);
+      expect(ids.has(3)).toBe(false);
+      expect(ids.has(4)).toBe(false);
+    } finally {
+      db.close();
+    }
+  });
+
+  it('focus with no matches returns no events', () => {
+    const db = freshDb();
+    try {
+      seedRich(db);
+      const nodes = tree(db, 'rich', { focusFn: 'app/Nope.nothing' });
+      expect(nodes).toEqual([]);
+    } finally {
+      db.close();
+    }
+  });
+
+  it('depths are recomputed relative to the highest included ancestor', () => {
+    const db = freshDb();
+    try {
+      seedRich(db);
+      // Without focus, HTTP is depth 0, controller 1, IdempotencyKey 2.
+      const focused = tree(db, 'rich', { focusFn: 'app/IdempotencyKey.generate', ancestors: 1 });
+      // Highest included is controller (event_id=2). It should now be
+      // depth 0; its child IdempotencyKey (focus) should be depth 1.
+      const controller = focused.find((n) => n.kind === 'function' && n.method_id === 'create');
+      const idem = focused.find((n) => n.kind === 'function' && n.method_id === 'generate');
+      expect(controller?.depth).toBe(0);
+      expect(idem?.depth).toBe(1);
+    } finally {
+      db.close();
+    }
+  });
+
+  // --- Spec 04: truncation signal ---------------------------------------
+
+  describe('treeWithMeta truncation', () => {
+    it('reports truncated=true and a next_step when descendants budget cuts off children', () => {
+      const db = freshDb();
+      try {
+        seedRich(db);
+        // Focus at HTTP root (depth 0). The tree under the focus is
+        // controller (1) → idempotencyKey (2) → digest (3). With
+        // descendants=1, only the controller is reachable; idem and
+        // digest are cut off.
+        const result = treeWithMeta(db, 'rich', {
+          focusRoute: '/orders',
+          descendants: 1,
+        });
+        expect(result.truncated).toBe(true);
+        expect(result.next_step).toMatch(/child_depth=3/);
+        expect(result.next_step).toContain("appmap='rich'");
+      } finally {
+        db.close();
+      }
+    });
+
+    it('reports truncated=false when every leaf reaches its natural end', () => {
+      const db = freshDb();
+      try {
+        seedRich(db);
+        // descendants=10 is well past the deepest leaf (sha256 at 3
+        // levels under the focus). Nothing gets cut off.
+        const result = treeWithMeta(db, 'rich', {
+          focusRoute: '/orders',
+          descendants: 10,
+        });
+        expect(result.truncated).toBe(false);
+        expect(result.next_step).toBeUndefined();
+        expect(result.max_depth_reached).toBeGreaterThan(0);
+      } finally {
+        db.close();
+      }
+    });
+
+    it('reports truncated=false when no focus is active (full recording is returned)', () => {
+      const db = freshDb();
+      try {
+        seedRich(db);
+        const result = treeWithMeta(db, 'rich');
+        expect(result.truncated).toBe(false);
+        expect(result.nodes.length).toBeGreaterThan(0);
+      } finally {
+        db.close();
+      }
+    });
+  });
+});
+
+describe('tree --filter', () => {
+  it('returns only http events when filter=http', () => {
+    const db = freshDb();
+    try {
+      seed(db, { addOutbound: true });
+      const nodes = tree(db, 'orders_create_42').filter(
+        (n) => n.kind === 'http_server' || n.kind === 'http_client'
+      );
+      expect(nodes.map((n) => n.kind).sort()).toEqual(['http_client', 'http_server']);
+    } finally {
+      db.close();
+    }
+  });
+
+  it('returns only sql events when filter=sql', () => {
+    const db = freshDb();
+    try {
+      seed(db);
+      const nodes = tree(db, 'orders_create_42').filter((n) => n.kind === 'sql');
+      expect(nodes).toHaveLength(1);
+      expect(nodes[0].kind).toBe('sql');
+    } finally {
+      db.close();
+    }
+  });
+});
+
+describe('log nodes in tree', () => {
+  function seedWithLogger(db: sqlite3.Database): number {
+    const am = db
+      .prepare(
+        `INSERT INTO appmaps (name, source_path) VALUES ('with_logger', '/tmp/with_logger.appmap.json')`
+      )
+      .run();
+    const id = am.lastInsertRowid;
+    db.prepare(
+      `INSERT INTO http_requests (appmap_id, event_id, parent_event_id, method, path, status_code, elapsed_ms)
+       VALUES (?, 1, NULL, 'POST', '/orders', 500, 100)`
+    ).run(id);
+    db.prepare(
+      `INSERT INTO function_calls (appmap_id, event_id, parent_event_id, defined_class, method_id, elapsed_ms)
+       VALUES (?, 2, 1, 'OrdersController', 'create', 90)`
+    ).run(id);
+    db.prepare(
+      `INSERT OR IGNORE INTO code_objects (fqid, package, classes, leaf_class, method, is_static)
+       VALUES ('app/AppLogger#error', 'app', '["AppLogger"]', 'AppLogger', 'error', 0)`
+    ).run();
+    const logCo = (db
+      .prepare(`SELECT id FROM code_objects WHERE fqid = 'app/AppLogger#error'`)
+      .get() as { id: number }).id;
+    db.prepare(`INSERT OR IGNORE INTO labels (code_object_id, label) VALUES (?, 'log')`).run(logCo);
+    db.prepare(
+      `INSERT INTO function_calls (appmap_id, event_id, parent_event_id, code_object_id,
+         defined_class, method_id, elapsed_ms, parameters_json)
+       VALUES (?, 3, 2, ?, 'AppLogger', 'error', 0.05, ?)`
+    ).run(
+      id,
+      logCo,
+      JSON.stringify([{ name: 'message', class: 'String', value: 'connection refused' }])
+    );
+    return Number(id);
+  }
+
+  it('promotes function calls with the `log` label to a log node kind', () => {
+    const db = freshDb();
+    try {
+      seedWithLogger(db);
+      const nodes = tree(db, 'with_logger');
+      const log = nodes.find((n) => n.kind === 'log');
+      expect(log).toBeDefined();
+      if (log?.kind !== 'log') throw new Error('expected log');
+      expect(log.logger).toBe('AppLogger');
+      expect(log.method_id).toBe('error');
+      expect(log.event_id).toBe(3);
+      // The same function_call should NOT also appear as a function node.
+      expect(nodes.filter((n) => n.event_id === 3 && n.kind === 'function')).toEqual([]);
+      // Other function_calls remain function nodes.
+      expect(nodes.find((n) => n.kind === 'function' && n.method_id === 'create')).toBeDefined();
+    } finally {
+      db.close();
+    }
+  });
+});
+
+describe('treeSummary', () => {
+  it('counts SQL, surfaces entry/exception, and tallies labels', () => {
+    const db = freshDb();
+    try {
+      seed(db, { addLabel: true, addOutbound: true });
+      const s = treeSummary(db, 'orders_create_42');
+      expect(s.entry?.method).toBe('POST');
+      expect(s.entry?.route).toBe('/orders');
+      expect(s.entry?.status_code).toBe(500);
+      expect(s.sql.count).toBe(1);
+      expect(s.sql.total_ms).toBeCloseTo(14);
+      expect(s.http_client.count).toBe(1);
+      expect(s.http_client.total_ms).toBeCloseTo(40);
+      expect(s.exceptions[0].exception_class).toBe('IntegrityError');
+      expect(s.labels).toEqual([{ label: 'log', count: 1 }]);
+    } finally {
+      db.close();
+    }
+  });
+});
diff --git a/packages/cli/tests/unit/cmds/query/verbs/find.spec.ts b/packages/cli/tests/unit/cmds/query/verbs/find.spec.ts
new file mode 100644
index 0000000000..ae6a2a97d7
--- /dev/null
+++ b/packages/cli/tests/unit/cmds/query/verbs/find.spec.ts
@@ -0,0 +1,221 @@
+import {
+  buildFindFilter,
+  projectLogMessage,
+  validateFlags,
+} from '../../../../../src/cmds/query/verbs/find';
+
+describe('find verb flag validation', () => {
+  it('accepts the universal flags on every type', () => {
+    const universal = {
+      branch: 'main',
+      commit: 'abc',
+      since: '2026-01-01',
+      until: '2026-12-31',
+      appmap: 'demo',
+      // output flags are also always allowed
+      limit: 5,
+      offset: 0,
+      json: true,
+    };
+    for (const type of ['appmaps', 'requests', 'queries', 'calls', 'exceptions', 'logs'] as const) {
+      expect(() => validateFlags(type, universal)).not.toThrow();
+    }
+  });
+
+  it('rejects --class on find appmaps', () => {
+    expect(() => validateFlags('appmaps', { class: 'Foo' })).toThrow(/--class/);
+    expect(() => validateFlags('appmaps', { class: 'Foo' })).toThrow(/find appmaps/);
+  });
+
+  it('accepts --route and --status on find appmaps', () => {
+    expect(() => validateFlags('appmaps', { route: '/x', status: '500' })).not.toThrow();
+  });
+
+  it('rejects --table on find calls and find exceptions', () => {
+    expect(() => validateFlags('calls', { table: 'orders' })).toThrow(/--table/);
+    expect(() => validateFlags('exceptions', { table: 'orders' })).toThrow(/--table/);
+  });
+
+  it('rejects --exception except on find exceptions', () => {
+    expect(() => validateFlags('exceptions', { exception: 'IntegrityError' })).not.toThrow();
+    expect(() => validateFlags('calls', { exception: 'IntegrityError' })).toThrow(/--exception/);
+    expect(() => validateFlags('queries', { exception: 'IntegrityError' })).toThrow(/--exception/);
+  });
+
+  it('rejects --label everywhere except find calls', () => {
+    expect(() => validateFlags('calls', { label: 'log' })).not.toThrow();
+    expect(() => validateFlags('appmaps', { label: 'log' })).toThrow(/--label/);
+    expect(() => validateFlags('requests', { label: 'log' })).toThrow(/--label/);
+    expect(() => validateFlags('queries', { label: 'log' })).toThrow(/--label/);
+    expect(() => validateFlags('exceptions', { label: 'log' })).toThrow(/--label/);
+  });
+
+  it('rejects --duration on exceptions; accepts elsewhere', () => {
+    expect(() => validateFlags('exceptions', { duration: '>1s' })).toThrow(/--duration/);
+    // appmaps (recording-level), calls, queries, requests all accept duration
+    expect(() => validateFlags('appmaps', { duration: '>1s' })).not.toThrow();
+    expect(() => validateFlags('calls', { duration: '>1s' })).not.toThrow();
+    expect(() => validateFlags('queries', { duration: '>1s' })).not.toThrow();
+    expect(() => validateFlags('requests', { duration: '>1s' })).not.toThrow();
+  });
+
+  it('hint message guides --method users on find requests', () => {
+    expect(() => validateFlags('requests', { method: 'findById' })).toThrow(
+      /--route/
+    );
+  });
+
+  it('lists multiple incompatible flags in a single error', () => {
+    expect(() =>
+      validateFlags('appmaps', { class: 'Foo', table: 'orders' })
+    ).toThrow(/--class.*--table|--table.*--class/);
+  });
+
+  it('ignores undefined / null flag values', () => {
+    expect(() =>
+      validateFlags('appmaps', { class: undefined, table: null })
+    ).not.toThrow();
+  });
+
+  it('logs accepts --logger and --message; rejects --class with a hint', () => {
+    expect(() => validateFlags('logs', { logger: 'AppLogger' })).not.toThrow();
+    expect(() => validateFlags('logs', { message: 'connection refused' })).not.toThrow();
+    expect(() => validateFlags('logs', { class: 'AppLogger' })).toThrow(/--logger/);
+    expect(() => validateFlags('logs', { label: 'log' })).toThrow(/implied/);
+  });
+
+  it('logs rejects row-level filters that don\'t apply', () => {
+    expect(() => validateFlags('logs', { route: '/x' })).toThrow(/--route/);
+    expect(() => validateFlags('logs', { status: '500' })).toThrow(/--status/);
+    expect(() => validateFlags('logs', { duration: '>1s' })).toThrow(/--duration/);
+    expect(() => validateFlags('logs', { table: 'users' })).toThrow(/--table/);
+    expect(() => validateFlags('logs', { exception: 'X' })).toThrow(/--exception/);
+  });
+
+  it('--logger and --message are rejected on non-logs types', () => {
+    for (const type of ['appmaps', 'requests', 'queries', 'calls', 'exceptions'] as const) {
+      expect(() => validateFlags(type, { logger: 'X' })).toThrow(/--logger/);
+      expect(() => validateFlags(type, { message: 'x' })).toThrow(/--message/);
+    }
+  });
+
+  it('--with-logs is accepted only on find exceptions', () => {
+    expect(() => validateFlags('exceptions', { 'with-logs': 5 })).not.toThrow();
+    for (const type of ['appmaps', 'requests', 'queries', 'calls', 'logs'] as const) {
+      expect(() => validateFlags(type, { 'with-logs': 5 })).toThrow(/--with-logs/);
+    }
+  });
+
+  it('--event-id is accepted only on find calls', () => {
+    expect(() => validateFlags('calls', { 'event-id': [42] })).not.toThrow();
+    for (const type of ['appmaps', 'requests', 'queries', 'exceptions', 'logs'] as const) {
+      expect(() => validateFlags(type, { 'event-id': [42] })).toThrow(/--event-id/);
+    }
+  });
+});
+
+describe('buildFindFilter', () => {
+  it('splits Class#method off of --class so the method composes via filter.method', () => {
+    const { filter } = buildFindFilter({
+      type: 'queries',
+      class: 'org.example.UserRepo#findById',
+    });
+    expect(filter.className).toBe('org.example.UserRepo#findById');
+    expect(filter.method).toBe('findById');
+  });
+
+  it('explicit --method wins over a method embedded in --class', () => {
+    const { filter } = buildFindFilter({
+      type: 'calls',
+      class: 'X#fromClass',
+      method: 'fromMethod',
+    });
+    expect(filter.method).toBe('fromMethod');
+  });
+
+  it('--class without # leaves filter.method undefined', () => {
+    const { filter } = buildFindFilter({
+      type: 'calls',
+      class: 'OpenSSL::Cipher',
+    });
+    expect(filter.className).toBe('OpenSSL::Cipher');
+    expect(filter.method).toBeUndefined();
+  });
+
+  it('returns the parsed type', () => {
+    expect(buildFindFilter({ type: 'appmaps' }).type).toBe('appmaps');
+  });
+
+  it('plumbs --with-logs into filter.withLogs from either kebab or camel keys', () => {
+    expect(buildFindFilter({ type: 'exceptions', withLogs: 5 }).filter.withLogs).toBe(5);
+    expect(buildFindFilter({ type: 'exceptions', 'with-logs': 7 }).filter.withLogs).toBe(7);
+    expect(buildFindFilter({ type: 'exceptions' }).filter.withLogs).toBeUndefined();
+  });
+
+  it('plumbs --logger and --message into the filter for logs', () => {
+    const { type, filter } = buildFindFilter({
+      type: 'logs',
+      logger: 'AppLogger',
+      message: 'connection refused',
+    });
+    expect(type).toBe('logs');
+    expect(filter.logger).toBe('AppLogger');
+    expect(filter.message).toBe('connection refused');
+  });
+
+  it('plumbs repeated --event-id into filter.eventIds (array)', () => {
+    const { filter } = buildFindFilter({ type: 'calls', eventId: [10, 30] });
+    expect(filter.eventIds).toEqual([10, 30]);
+  });
+
+  it('accepts a single --event-id scalar and the kebab key', () => {
+    expect(buildFindFilter({ type: 'calls', eventId: 42 }).filter.eventIds).toEqual([42]);
+    expect(buildFindFilter({ type: 'calls', 'event-id': [7] }).filter.eventIds).toEqual([7]);
+  });
+
+  it('leaves filter.eventIds undefined when --event-id is absent', () => {
+    expect(buildFindFilter({ type: 'calls' }).filter.eventIds).toBeUndefined();
+  });
+});
+
+describe('projectLogMessage', () => {
+  it('prefers a structured-return message field when return_value is JSON', () => {
+    const r = JSON.stringify({ level: 'info', message: 'hello world' });
+    expect(projectLogMessage(null, r)).toBe('hello world');
+  });
+
+  it('uses a parameter named message when return_value lacks a structured message', () => {
+    const params = JSON.stringify([
+      { name: 'tag', class: 'String', value: 'auth' },
+      { name: 'message', class: 'String', value: 'login ok' },
+    ]);
+    expect(projectLogMessage(params, null)).toBe('login ok');
+  });
+
+  it('accepts msg as an alias for message', () => {
+    const params = JSON.stringify([{ name: 'msg', class: 'String', value: 'queued' }]);
+    expect(projectLogMessage(params, null)).toBe('queued');
+  });
+
+  it('falls back to the first string-typed parameter value', () => {
+    const params = JSON.stringify([
+      { name: 'count', class: 'Integer', value: 5 },
+      { name: 'note', class: 'String', value: 'first text' },
+    ]);
+    expect(projectLogMessage(params, null)).toBe('first text');
+  });
+
+  it('returns a non-empty repr even when nothing matches', () => {
+    const params = JSON.stringify([{ name: 'count', class: 'Integer', value: 5 }]);
+    expect(projectLogMessage(params, null)).toBe('[5]');
+  });
+
+  it('returns an empty string when both inputs are null', () => {
+    expect(projectLogMessage(null, null)).toBe('');
+  });
+
+  it('return_value that is not JSON is treated as opaque (not the message)', () => {
+    // Falls through to parameters_json; if that's null, returns ''.
+    expect(projectLogMessage(null, 'true')).toBe('');
+  });
+});
diff --git a/packages/cli/tests/unit/cmds/query/verbs/hotspots.spec.ts b/packages/cli/tests/unit/cmds/query/verbs/hotspots.spec.ts
new file mode 100644
index 0000000000..7c119dd997
--- /dev/null
+++ b/packages/cli/tests/unit/cmds/query/verbs/hotspots.spec.ts
@@ -0,0 +1,29 @@
+import { validateFlags } from '../../../../../src/cmds/query/verbs/hotspots';
+
+describe('hotspots verb flag validation', () => {
+  it('function-mode accepts --class', () => {
+    expect(() => validateFlags('function', { class: 'UserRepository' })).not.toThrow();
+  });
+
+  it('sql-mode rejects --class', () => {
+    expect(() => validateFlags('sql', { class: 'UserRepository' })).toThrow(
+      /--type=sql:.*--class.*not supported/
+    );
+  });
+
+  it('sql-mode accepts --route, --branch, --since, --until, --limit', () => {
+    expect(() =>
+      validateFlags('sql', {
+        route: '/x',
+        branch: 'main',
+        since: '2026-01-01',
+        until: '2026-12-31',
+        limit: 5,
+      })
+    ).not.toThrow();
+  });
+
+  it('ignores undefined / null flag values', () => {
+    expect(() => validateFlags('sql', { class: undefined })).not.toThrow();
+  });
+});
diff --git a/packages/cli/tests/unit/cmds/query/verbs/tree.spec.ts b/packages/cli/tests/unit/cmds/query/verbs/tree.spec.ts
new file mode 100644
index 0000000000..33a730a23d
--- /dev/null
+++ b/packages/cli/tests/unit/cmds/query/verbs/tree.spec.ts
@@ -0,0 +1,63 @@
+import { applyFilter } from '../../../../../src/cmds/query/verbs/tree';
+import {
+  ExceptionNode,
+  FunctionNode,
+  HttpClientNode,
+  HttpServerNode,
+  LogNode,
+  SqlNode,
+  TreeNode,
+} from '../../../../../src/cmds/query/queries/tree';
+
+const baseFields = {
+  parent_event_id: null,
+  thread_id: null,
+  depth: 0,
+};
+
+const http: HttpServerNode = {
+  kind: 'http_server', event_id: 1, ...baseFields,
+  method: 'GET', route: '/x', status_code: 200, elapsed_ms: 1,
+};
+const httpOut: HttpClientNode = {
+  kind: 'http_client', event_id: 2, ...baseFields,
+  method: 'GET', url: 'https://x', status_code: 200, elapsed_ms: 1,
+};
+const sql: SqlNode = {
+  kind: 'sql', event_id: 3, ...baseFields,
+  sql_text: 'SELECT 1', database_type: null, elapsed_ms: 1,
+};
+const fn: FunctionNode = {
+  kind: 'function', event_id: 4, ...baseFields,
+  fqid: 'app/X#m', defined_class: 'X', method_id: 'm',
+  path: null, lineno: null, is_static: false,
+  elapsed_ms: 1, parameters_json: null, return_value: null,
+};
+const exc: ExceptionNode = {
+  kind: 'exception', event_id: 5, ...baseFields,
+  exception_class: 'IOError', message: null, path: null, lineno: null,
+};
+const lg: LogNode = {
+  kind: 'log', event_id: 6, ...baseFields,
+  fqid: 'app/Logger#info', logger: 'Logger', method_id: 'info',
+  path: null, lineno: null, elapsed_ms: 0.1,
+  message: 'hi',
+  parameters_json: '[{"name":"message","value":"hi"}]', return_value: null,
+};
+
+const all: TreeNode[] = [http, httpOut, sql, fn, exc, lg];
+
+describe('tree --filter', () => {
+  it('all returns every node', () => {
+    expect(applyFilter(all, 'all')).toHaveLength(6);
+  });
+  it('http includes server and client requests', () => {
+    expect(applyFilter(all, 'http')).toEqual([http, httpOut]);
+  });
+  it('sql returns only sql nodes', () => {
+    expect(applyFilter(all, 'sql')).toEqual([sql]);
+  });
+  it('logs returns only log nodes', () => {
+    expect(applyFilter(all, 'logs')).toEqual([lg]);
+  });
+});
diff --git a/scripts/verify.mjs b/scripts/verify.mjs
new file mode 100755
index 0000000000..d96bd61912
--- /dev/null
+++ b/scripts/verify.mjs
@@ -0,0 +1,162 @@
+#!/usr/bin/env node
+// Run lint + typecheck on packages with modified files.
+//
+// Usage:
+//   node scripts/verify.mjs           # check working-tree changes (staged + unstaged + untracked)
+//   node scripts/verify.mjs --staged  # check only staged changes (intended for pre-commit hook use)
+//
+// Per affected package:
+//   1. eslint on the package's changed *.ts / *.tsx / *.js / *.mjs files
+//   2. tsc --noEmit on the whole package, if it has tsconfig.json + a typecheck script
+//
+// Exits non-zero if any check fails. Skips files outside packages/.
+
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const STAGED = process.argv.includes('--staged');
+
+const LINT_EXTS = new Set(['.ts', '.tsx', '.js', '.mjs', '.cjs']);
+
+function git(...args) {
+  const r = spawnSync('git', args, { cwd: ROOT, encoding: 'utf8' });
+  if (r.status !== 0) {
+    console.error(`git ${args.join(' ')} failed:\n${r.stderr}`);
+    process.exit(1);
+  }
+  return r.stdout;
+}
+
+function modifiedFiles() {
+  if (STAGED) {
+    // Staged adds/copies/modifies/renames.
+    return git('diff', '--cached', '--name-only', '--diff-filter=ACMR')
+      .split('\n')
+      .filter(Boolean);
+  }
+  // Working tree: tracked changes + untracked (excluding ignored).
+  // --porcelain output is `XY filename`; strip the 3-char status prefix.
+  // Renames appear as `R  old -> new`; --no-renames keeps both columns simple.
+  return git('status', '--porcelain', '--no-renames')
+    .split('\n')
+    .filter(Boolean)
+    .map((line) => line.slice(3));
+}
+
+function groupByPackage(files) {
+  const byPkg = new Map();
+  const skipped = [];
+  for (const file of files) {
+    const m = /^packages\/([^/]+)\//.exec(file);
+    if (!m) {
+      skipped.push(file);
+      continue;
+    }
+    const pkg = m[1];
+    if (!byPkg.has(pkg)) byPkg.set(pkg, []);
+    byPkg.get(pkg).push(file);
+  }
+  return { byPkg, skipped };
+}
+
+function hasScript(pkgDir, name) {
+  const pj = path.join(pkgDir, 'package.json');
+  if (!existsSync(pj)) return false;
+  try {
+    const json = JSON.parse(readFileSync(pj, 'utf8'));
+    return Boolean(json.scripts && json.scripts[name]);
+  } catch {
+    return false;
+  }
+}
+
+function resolveBin(pkgDir, name) {
+  const pkgBin = path.join(pkgDir, 'node_modules', '.bin', name);
+  if (existsSync(pkgBin)) return pkgBin;
+  const rootBin = path.join(ROOT, 'node_modules', '.bin', name);
+  if (existsSync(rootBin)) return rootBin;
+  return null;
+}
+
+function run(label, command, args, opts) {
+  console.log(`\n→ ${label}: ${command} ${args.join(' ')}  (cwd: ${opts.cwd})`);
+  const r = spawnSync(command, args, { stdio: 'inherit', ...opts });
+  return r.status === 0;
+}
+
+function verifyPackage(pkg, files) {
+  const pkgDir = path.join(ROOT, 'packages', pkg);
+  const pkgJsonPath = path.join(pkgDir, 'package.json');
+  if (!existsSync(pkgJsonPath)) {
+    console.warn(`Skipping ${pkg}: no packages/${pkg}/package.json`);
+    return true;
+  }
+
+  let ok = true;
+
+  // Lint changed lintable files.
+  const lintable = files
+    .filter((f) => LINT_EXTS.has(path.extname(f)))
+    .filter((f) => existsSync(path.join(ROOT, f))) // skip deleted files
+    .map((f) => path.relative(pkgDir, path.join(ROOT, f)));
+
+  if (lintable.length > 0 && hasScript(pkgDir, 'lint')) {
+    // Prefer the package-local eslint binary — root and packages can carry
+    // different major versions (e.g. ESLint 7 at root vs 8 in cli), and
+    // @typescript-eslint plugins are pinned to one major.
+    const eslintBin = resolveBin(pkgDir, 'eslint');
+    if (!eslintBin) {
+      console.warn(`Skipping lint for ${pkg}: eslint not found in node_modules/.bin`);
+    } else {
+      ok =
+        run(
+          `${pkg}: eslint (${lintable.length} file${lintable.length === 1 ? '' : 's'})`,
+          eslintBin,
+          // --quiet hides warnings; CI rules that only warn are not blockers.
+          ['--quiet', ...lintable],
+          { cwd: pkgDir }
+        ) && ok;
+    }
+  }
+
+  // Typecheck the whole package.
+  if (hasScript(pkgDir, 'typecheck') && existsSync(path.join(pkgDir, 'tsconfig.json'))) {
+    const tscBin = resolveBin(pkgDir, 'tsc');
+    if (!tscBin) {
+      console.warn(`Skipping typecheck for ${pkg}: tsc not found in node_modules/.bin`);
+    } else {
+      ok = run(`${pkg}: tsc --noEmit`, tscBin, ['--noEmit'], { cwd: pkgDir }) && ok;
+    }
+  }
+
+  return ok;
+}
+
+const files = modifiedFiles();
+if (files.length === 0) {
+  console.log('No modified files. Nothing to verify.');
+  process.exit(0);
+}
+
+const { byPkg, skipped } = groupByPackage(files);
+console.log(`Verifying ${byPkg.size} package(s) with modified files:`);
+for (const [pkg, pkgFiles] of byPkg) {
+  console.log(`  packages/${pkg} (${pkgFiles.length} file${pkgFiles.length === 1 ? '' : 's'})`);
+}
+if (skipped.length > 0) {
+  console.log(`  skipped ${skipped.length} non-package file(s)`);
+}
+
+let allOk = true;
+for (const [pkg, pkgFiles] of byPkg) {
+  allOk = verifyPackage(pkg, pkgFiles) && allOk;
+}
+
+if (!allOk) {
+  console.error('\nverify: FAILED');
+  process.exit(1);
+}
+console.log('\nverify: OK');
diff --git a/yarn.lock b/yarn.lock
index cb88dc4b21..eac6570399 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -12,6 +12,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@alloc/quick-lru@npm:^5.2.0":
+  version: 5.2.0
+  resolution: "@alloc/quick-lru@npm:5.2.0"
+  checksum: bdc35758b552bcf045733ac047fb7f9a07c4678b944c641adfbd41f798b4b91fffd0fdc0df2578d9b0afc7b4d636aa6e110ead5d6281a2adc1ab90efd7f057f8
+  languageName: node
+  linkType: hard
+
 "@ampproject/remapping@npm:^2.2.0":
   version: 2.2.0
   resolution: "@ampproject/remapping@npm:2.2.0"
@@ -130,6 +137,8 @@ __metadata:
     "@types/moo": ^0.5.5
     "@types/node": ^16
     "@types/proper-lockfile": ^4.1.4
+    "@types/react": ^18.3.0
+    "@types/react-dom": ^18.3.0
     "@types/semver": ^7.3.10
     "@types/sinon": ^10.0.2
     "@types/tmp": ^0.2.3
@@ -193,6 +202,9 @@ __metadata:
     proper-lockfile: ^4.1.2
     ps-node: ^0.1.6
     puppeteer: ^19.7.5
+    react: ^18.3.0
+    react-dom: ^18.3.0
+    react-router-dom: ^6.26.0
     read-pkg-up: ^7.0.1
     reflect-metadata: ^0.2.2
     semver: ^7.3.5
@@ -200,6 +212,7 @@ __metadata:
     sql-formatter: ^4.0.2
     stream-http: ^3.2.0
     strip-ansi: ^6.0.0
+    tailwindcss: ^3.4.0
     tmp: ^0.2.1
     tmp-promise: ^3.0.3
     ts-jest: ^29.0.5
@@ -5368,6 +5381,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@remix-run/router@npm:1.23.2":
+  version: 1.23.2
+  resolution: "@remix-run/router@npm:1.23.2"
+  checksum: 0f046e480372be17d14f88684435cd6af4c05ce842bd6094a549605dd5b8f0ab1e9a1e9d9e2faec9e4d5cd370d02179b456189192f06415e461bce44c28295d8
+  languageName: node
+  linkType: hard
+
 "@rollup/plugin-alias@npm:^4.0.3":
   version: 4.0.3
   resolution: "@rollup/plugin-alias@npm:4.0.3"
@@ -7688,6 +7708,15 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@types/react-dom@npm:^18.3.0":
+  version: 18.3.7
+  resolution: "@types/react-dom@npm:18.3.7"
+  peerDependencies:
+    "@types/react": ^18.0.0
+  checksum: c8b63ec944d2a68992b4dba474003fe55ee1d949c4b9c8fe97eecb2290de23f76acfb670b2f7ceb46a5fc8e46808d1745369b03edda48a7a0cf730eff4c5d315
+  languageName: node
+  linkType: hard
+
 "@types/react@npm:>=16":
   version: 18.2.45
   resolution: "@types/react@npm:18.2.45"
@@ -7699,6 +7728,16 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@types/react@npm:^18.3.0":
+  version: 18.3.28
+  resolution: "@types/react@npm:18.3.28"
+  dependencies:
+    "@types/prop-types": "*"
+    csstype: ^3.2.2
+  checksum: 9d59fb3def4e712d4f8fa15998791a07f9799462f8d581d17039a9503017bfce3463d57fc737ce1d28d6aa3f482f4a3a5bae5a662d97560a9359aab111556c97
+  languageName: node
+  linkType: hard
+
 "@types/resolve@npm:1.17.1":
   version: 1.17.1
   resolution: "@types/resolve@npm:1.17.1"
@@ -10149,6 +10188,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"arg@npm:^5.0.2":
+  version: 5.0.2
+  resolution: "arg@npm:5.0.2"
+  checksum: 6c69ada1a9943d332d9e5382393e897c500908d91d5cb735a01120d5f71daf1b339b7b8980cbeaba8fd1afc68e658a739746179e4315a26e8a28951ff9930078
+  languageName: node
+  linkType: hard
+
 "argparse@npm:^1.0.7":
   version: 1.0.10
   resolution: "argparse@npm:1.0.10"
@@ -11377,6 +11423,15 @@ __metadata:
   languageName: node
   linkType: hard
 
+"braces@npm:^3.0.3":
+  version: 3.0.3
+  resolution: "braces@npm:3.0.3"
+  dependencies:
+    fill-range: ^7.1.1
+  checksum: b95aa0b3bd909f6cd1720ffcf031aeaf46154dd88b4da01f9a1d3f7ea866a79eba76a6d01cbc3c422b2ee5cdc39a4f02491058d5df0d7bf6e6a162a832df1f69
+  languageName: node
+  linkType: hard
+
 "brorand@npm:^1.0.1, brorand@npm:^1.1.0":
   version: 1.1.0
   resolution: "brorand@npm:1.1.0"
@@ -11905,6 +11960,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"camelcase-css@npm:^2.0.1":
+  version: 2.0.1
+  resolution: "camelcase-css@npm:2.0.1"
+  checksum: 1cec2b3b3dcb5026688a470b00299a8db7d904c4802845c353dbd12d9d248d3346949a814d83bfd988d4d2e5b9904c07efe76fecd195a1d4f05b543e7c0b56b1
+  languageName: node
+  linkType: hard
+
 "camelcase-keys@npm:^6.2.2":
   version: 6.2.2
   resolution: "camelcase-keys@npm:6.2.2"
@@ -12128,6 +12190,25 @@ __metadata:
   languageName: node
   linkType: hard
 
+"chokidar@npm:^3.6.0":
+  version: 3.6.0
+  resolution: "chokidar@npm:3.6.0"
+  dependencies:
+    anymatch: ~3.1.2
+    braces: ~3.0.2
+    fsevents: ~2.3.2
+    glob-parent: ~5.1.2
+    is-binary-path: ~2.1.0
+    is-glob: ~4.0.1
+    normalize-path: ~3.0.0
+    readdirp: ~3.6.0
+  dependenciesMeta:
+    fsevents:
+      optional: true
+  checksum: d2f29f499705dcd4f6f3bbed79a9ce2388cf530460122eed3b9c48efeab7a4e28739c6551fd15bec9245c6b9eeca7a32baa64694d64d9b6faeb74ddb8c4a413d
+  languageName: node
+  linkType: hard
+
 "chokidar@npm:^4.0.3":
   version: 4.0.3
   resolution: "chokidar@npm:4.0.3"
@@ -13631,6 +13712,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"csstype@npm:^3.2.2":
+  version: 3.2.3
+  resolution: "csstype@npm:3.2.3"
+  checksum: cb882521b3398958a1ce6ca98c011aec0bde1c77ecaf8a1dd4db3b112a189939beae3b1308243b2fe50fc27eb3edeb0f73a5a4d91d928765dc6d5ecc7bda92ee
+  languageName: node
+  linkType: hard
+
 "cyclist@npm:^1.0.1":
   version: 1.0.1
   resolution: "cyclist@npm:1.0.1"
@@ -14745,6 +14833,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"didyoumean@npm:^1.2.2":
+  version: 1.2.2
+  resolution: "didyoumean@npm:1.2.2"
+  checksum: d5d98719d58b3c2fa59663c4c42ba9716f1fd01245c31d5fce31915bd3aa26e6aac149788e007358f778ebbd68a2256eb5973e8ca6f221df221ba060115acf2e
+  languageName: node
+  linkType: hard
+
 "diff-sequences@npm:^24.9.0":
   version: 24.9.0
   resolution: "diff-sequences@npm:24.9.0"
@@ -14816,6 +14911,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"dlv@npm:^1.1.3":
+  version: 1.1.3
+  resolution: "dlv@npm:1.1.3"
+  checksum: d7381bca22ed11933a1ccf376db7a94bee2c57aa61e490f680124fa2d1cd27e94eba641d9f45be57caab4f9a6579de0983466f620a2cd6230d7ec93312105ae7
+  languageName: node
+  linkType: hard
+
 "dns-equal@npm:^1.0.0":
   version: 1.0.0
   resolution: "dns-equal@npm:1.0.0"
@@ -17181,6 +17283,19 @@ __metadata:
   languageName: node
   linkType: hard
 
+"fast-glob@npm:^3.3.2":
+  version: 3.3.3
+  resolution: "fast-glob@npm:3.3.3"
+  dependencies:
+    "@nodelib/fs.stat": ^2.0.2
+    "@nodelib/fs.walk": ^1.2.3
+    glob-parent: ^5.1.2
+    merge2: ^1.3.0
+    micromatch: ^4.0.8
+  checksum: 0704d7b85c0305fd2cef37777337dfa26230fdd072dce9fb5c82a4b03156f3ffb8ed3e636033e65d45d2a5805a4e475825369a27404c0307f2db0c8eb3366fbd
+  languageName: node
+  linkType: hard
+
 "fast-json-stable-stringify@npm:2.x, fast-json-stable-stringify@npm:^2.0.0, fast-json-stable-stringify@npm:^2.1.0":
   version: 2.1.0
   resolution: "fast-json-stable-stringify@npm:2.1.0"
@@ -17384,6 +17499,15 @@ __metadata:
   languageName: node
   linkType: hard
 
+"fill-range@npm:^7.1.1":
+  version: 7.1.1
+  resolution: "fill-range@npm:7.1.1"
+  dependencies:
+    to-regex-range: ^5.0.1
+  checksum: b4abfbca3839a3d55e4ae5ec62e131e2e356bf4859ce8480c64c4876100f4df292a63e5bb1618e1d7460282ca2b305653064f01654474aa35c68000980f17798
+  languageName: node
+  linkType: hard
+
 "finalhandler@npm:1.1.2":
   version: 1.1.2
   resolution: "finalhandler@npm:1.1.2"
@@ -18692,6 +18816,15 @@ fsevents@^1.2.7:
   languageName: node
   linkType: hard
 
+"hasown@npm:^2.0.3":
+  version: 2.0.3
+  resolution: "hasown@npm:2.0.3"
+  dependencies:
+    function-bind: ^1.1.2
+  checksum: bb06756a13dc4e6d1f45993c86c23f12d167c6c30a7dcc907aec5042300b4eb255615a0e5ed2c65014b93bf8bfcff111d991032c5c01ddefb340aa64b329bd55
+  languageName: node
+  linkType: hard
+
 "he@npm:1.2.x, he@npm:^1.2.0":
   version: 1.2.0
   resolution: "he@npm:1.2.0"
@@ -19759,6 +19892,15 @@ fsevents@^1.2.7:
   languageName: node
   linkType: hard
 
+"is-core-module@npm:^2.16.1":
+  version: 2.16.2
+  resolution: "is-core-module@npm:2.16.2"
+  dependencies:
+    hasown: ^2.0.3
+  checksum: 9317844b4959f8fb268bfc1b4e24033d60058235c2e7273499c2abfd8e4510e7059b1339bd9109766293747daa3e0b5a89095fb2825a866a4093563fe8fdf16f
+  languageName: node
+  linkType: hard
+
 "is-data-descriptor@npm:^0.1.4":
   version: 0.1.4
   resolution: "is-data-descriptor@npm:0.1.4"
@@ -21998,6 +22140,15 @@ fsevents@^1.2.7:
   languageName: node
   linkType: hard
 
+"jiti@npm:^1.21.7":
+  version: 1.21.7
+  resolution: "jiti@npm:1.21.7"
+  bin:
+    jiti: bin/jiti.js
+  checksum: 9cd20dabf82e3a4cceecb746a69381da7acda93d34eed0cdb9c9bdff3bce07e4f2f4a016ca89924392c935297d9aedc58ff9f7d3281bc5293319ad244926e0b7
+  languageName: node
+  linkType: hard
+
 "joi@npm:^17.4.0":
   version: 17.6.0
   resolution: "joi@npm:17.6.0"
@@ -23226,7 +23377,7 @@ fsevents@^1.2.7:
   languageName: node
   linkType: hard
 
-"lilconfig@npm:^3.1.1":
+"lilconfig@npm:^3.1.1, lilconfig@npm:^3.1.3":
   version: 3.1.3
   resolution: "lilconfig@npm:3.1.3"
   checksum: 644eb10830350f9cdc88610f71a921f510574ed02424b57b0b3abb66ea725d7a082559552524a842f4e0272c196b88dfe1ff7d35ffcc6f45736777185cd67c9a
@@ -24432,6 +24583,16 @@ fsevents@^1.2.7:
   languageName: node
   linkType: hard
 
+"micromatch@npm:^4.0.8":
+  version: 4.0.8
+  resolution: "micromatch@npm:4.0.8"
+  dependencies:
+    braces: ^3.0.3
+    picomatch: ^2.3.1
+  checksum: 79920eb634e6f400b464a954fcfa589c4e7c7143209488e44baf627f9affc8b1e306f41f4f0deedde97e69cb725920879462d3e750ab3bd3c1aed675bb3a8966
+  languageName: node
+  linkType: hard
+
 "miller-rabin@npm:^4.0.0":
   version: 4.0.1
   resolution: "miller-rabin@npm:4.0.1"
@@ -24993,6 +25154,15 @@ fsevents@^1.2.7:
   languageName: node
   linkType: hard
 
+"nanoid@npm:^3.3.11":
+  version: 3.3.12
+  resolution: "nanoid@npm:3.3.12"
+  bin:
+    nanoid: bin/nanoid.cjs
+  checksum: 38699257447dc59e21e73e0510d0dfb16b7a610d9ca80633d5c3a68f9b4298c990513d30404ca8f163c2d03225ee01695ff8898bea6179183f38f0477b7635ac
+  languageName: node
+  linkType: hard
+
 "nanoid@npm:^3.3.7":
   version: 3.3.7
   resolution: "nanoid@npm:3.3.7"
@@ -25812,6 +25982,13 @@ fsevents@^1.2.7:
   languageName: node
   linkType: hard
 
+"object-hash@npm:^3.0.0":
+  version: 3.0.0
+  resolution: "object-hash@npm:3.0.0"
+  checksum: 80b4904bb3857c52cc1bfd0b52c0352532ca12ed3b8a6ff06a90cd209dfda1b95cee059a7625eb9da29537027f68ac4619363491eedb2f5d3dddbba97494fd6c
+  languageName: node
+  linkType: hard
+
 "object-inspect@npm:^1.13.1, object-inspect@npm:^1.13.3":
   version: 1.13.4
   resolution: "object-inspect@npm:1.13.4"
@@ -26827,6 +27004,13 @@ fsevents@^1.2.7:
   languageName: node
   linkType: hard
 
+"picomatch@npm:^2.3.1":
+  version: 2.3.2
+  resolution: "picomatch@npm:2.3.2"
+  checksum: 0a3f5b9ff28faf022e1429b66e47c122e19e7b31cbd098095d29e949684e7ff1d9b83a2133d931326a53ec6ec11c7c59b1850c27fde2f26ca1d5f35861e9701a
+  languageName: node
+  linkType: hard
+
 "picomatch@npm:^4.0.3":
   version: 4.0.3
   resolution: "picomatch@npm:4.0.3"
@@ -26834,7 +27018,7 @@ fsevents@^1.2.7:
   languageName: node
   linkType: hard
 
-"pify@npm:^2.0.0, pify@npm:^2.2.0":
+"pify@npm:^2.0.0, pify@npm:^2.2.0, pify@npm:^2.3.0":
   version: 2.3.0
   resolution: "pify@npm:2.3.0"
   checksum: 9503aaeaf4577acc58642ad1d25c45c6d90288596238fb68f82811c08104c800e5a7870398e9f015d82b44ecbcbef3dc3d4251a1cbb582f6e5959fe09884b2ba
@@ -27184,6 +27368,30 @@ fsevents@^1.2.7:
   languageName: node
   linkType: hard
 
+"postcss-import@npm:^15.1.0":
+  version: 15.1.0
+  resolution: "postcss-import@npm:15.1.0"
+  dependencies:
+    postcss-value-parser: ^4.0.0
+    read-cache: ^1.0.0
+    resolve: ^1.1.7
+  peerDependencies:
+    postcss: ^8.0.0
+  checksum: 7bd04bd8f0235429009d0022cbf00faebc885de1d017f6d12ccb1b021265882efc9302006ba700af6cab24c46bfa2f3bc590be3f9aee89d064944f171b04e2a3
+  languageName: node
+  linkType: hard
+
+"postcss-js@npm:^4.0.1":
+  version: 4.1.0
+  resolution: "postcss-js@npm:4.1.0"
+  dependencies:
+    camelcase-css: ^2.0.1
+  peerDependencies:
+    postcss: ^8.4.21
+  checksum: 1fe3d51770f66d301e63103c15830d26875b1ae9bbe3ba6bf61256860edde3d9c0de5aa0c3e34d34b80c099f5d95b589cfcc92dac718253c8351aa8e05a8d80a
+  languageName: node
+  linkType: hard
+
 "postcss-load-config@npm:^2.0.0":
   version: 2.1.2
   resolution: "postcss-load-config@npm:2.1.2"
@@ -27194,7 +27402,7 @@ fsevents@^1.2.7:
   languageName: node
   linkType: hard
 
-"postcss-load-config@npm:^6.0.1":
+"postcss-load-config@npm:^4.0.2 || ^5.0 || ^6.0, postcss-load-config@npm:^6.0.1":
   version: 6.0.1
   resolution: "postcss-load-config@npm:6.0.1"
   dependencies:
@@ -27422,6 +27630,17 @@ fsevents@^1.2.7:
   languageName: node
   linkType: hard
 
+"postcss-nested@npm:^6.2.0":
+  version: 6.2.0
+  resolution: "postcss-nested@npm:6.2.0"
+  dependencies:
+    postcss-selector-parser: ^6.1.1
+  peerDependencies:
+    postcss: ^8.2.14
+  checksum: 2c86ecf2d0ce68f27c87c7e24ae22dc6dd5515a89fcaf372b2627906e11f5c1f36e4a09e4c15c20fd4a23d628b3d945c35839f44496fbee9a25866258006671b
+  languageName: node
+  linkType: hard
+
 "postcss-normalize-charset@npm:^4.0.1":
   version: 4.0.1
   resolution: "postcss-normalize-charset@npm:4.0.1"
@@ -27577,6 +27796,16 @@ fsevents@^1.2.7:
   languageName: node
   linkType: hard
 
+"postcss-selector-parser@npm:^6.1.1, postcss-selector-parser@npm:^6.1.2":
+  version: 6.1.2
+  resolution: "postcss-selector-parser@npm:6.1.2"
+  dependencies:
+    cssesc: ^3.0.0
+    util-deprecate: ^1.0.2
+  checksum: ce9440fc42a5419d103f4c7c1847cb75488f3ac9cbe81093b408ee9701193a509f664b4d10a2b4d82c694ee7495e022f8f482d254f92b7ffd9ed9dea696c6f84
+  languageName: node
+  linkType: hard
+
 "postcss-svgo@npm:^4.0.3":
   version: 4.0.3
   resolution: "postcss-svgo@npm:4.0.3"
@@ -27606,7 +27835,7 @@ fsevents@^1.2.7:
   languageName: node
   linkType: hard
 
-"postcss-value-parser@npm:^4.0.2, postcss-value-parser@npm:^4.1.0, postcss-value-parser@npm:^4.2.0":
+"postcss-value-parser@npm:^4.0.0, postcss-value-parser@npm:^4.0.2, postcss-value-parser@npm:^4.1.0, postcss-value-parser@npm:^4.2.0":
   version: 4.2.0
   resolution: "postcss-value-parser@npm:4.2.0"
   checksum: 819ffab0c9d51cf0acbabf8996dffbfafbafa57afc0e4c98db88b67f2094cb44488758f06e5da95d7036f19556a4a732525e84289a425f4f6fd8e412a9d7442f
@@ -27657,6 +27886,17 @@ fsevents@^1.2.7:
   languageName: node
   linkType: hard
 
+"postcss@npm:^8.4.47":
+  version: 8.5.14
+  resolution: "postcss@npm:8.5.14"
+  dependencies:
+    nanoid: ^3.3.11
+    picocolors: ^1.1.1
+    source-map-js: ^1.2.1
+  checksum: ec17d1519cd997b43aceb82bfa959f380085591269e286c53d5ba76eb1989525e7cde106a44f1565516fcbb50f206eb1858cc2cd5e5aaea3a8ee793886c8232c
+  languageName: node
+  linkType: hard
+
 "prebuild-install@npm:7.1.1":
   version: 7.1.1
   resolution: "prebuild-install@npm:7.1.1"
@@ -28497,6 +28737,18 @@ fsevents@^1.2.7:
   languageName: node
   linkType: hard
 
+"react-dom@npm:^18.3.0":
+  version: 18.3.1
+  resolution: "react-dom@npm:18.3.1"
+  dependencies:
+    loose-envify: ^1.1.0
+    scheduler: ^0.23.2
+  peerDependencies:
+    react: ^18.3.1
+  checksum: 298954ecd8f78288dcaece05e88b570014d8f6dce5db6f66e6ee91448debeb59dcd31561dddb354eee47e6c1bb234669459060deb238ed0213497146e555a0b9
+  languageName: node
+  linkType: hard
+
 "react-is@npm:^16.13.1, react-is@npm:^16.8.4":
   version: 16.13.1
   resolution: "react-is@npm:16.13.1"
@@ -28553,6 +28805,30 @@ fsevents@^1.2.7:
   languageName: node
   linkType: hard
 
+"react-router-dom@npm:^6.26.0":
+  version: 6.30.3
+  resolution: "react-router-dom@npm:6.30.3"
+  dependencies:
+    "@remix-run/router": 1.23.2
+    react-router: 6.30.3
+  peerDependencies:
+    react: ">=16.8"
+    react-dom: ">=16.8"
+  checksum: 1f43ce47dd8cfc1bc728ea7b0cf10136416416491136726cda500aaea74da3c5dbcfcec24781bc390f6e8a4383ff72b8331b53887485e79dcb75387ffe5508c3
+  languageName: node
+  linkType: hard
+
+"react-router@npm:6.30.3":
+  version: 6.30.3
+  resolution: "react-router@npm:6.30.3"
+  dependencies:
+    "@remix-run/router": 1.23.2
+  peerDependencies:
+    react: ">=16.8"
+  checksum: b61e1a456b72ed35907dadc261d8572a65dd4caae008f7a85a6b09b437b1a4b90034fc7df0e418f1f01b73c2b8a8f6755d7fc0108b1ec3f2ed37f03a1e248513
+  languageName: node
+  linkType: hard
+
 "react-style-singleton@npm:^2.2.1":
   version: 2.2.1
   resolution: "react-style-singleton@npm:2.2.1"
@@ -28579,6 +28855,24 @@ fsevents@^1.2.7:
   languageName: node
   linkType: hard
 
+"react@npm:^18.3.0":
+  version: 18.3.1
+  resolution: "react@npm:18.3.1"
+  dependencies:
+    loose-envify: ^1.1.0
+  checksum: a27bcfa8ff7c15a1e50244ad0d0c1cb2ad4375eeffefd266a64889beea6f6b64c4966c9b37d14ee32d6c9fcd5aa6ba183b6988167ab4d127d13e7cb5b386a376
+  languageName: node
+  linkType: hard
+
+"read-cache@npm:^1.0.0":
+  version: 1.0.0
+  resolution: "read-cache@npm:1.0.0"
+  dependencies:
+    pify: ^2.3.0
+  checksum: cffc728b9ede1e0667399903f9ecaf3789888b041c46ca53382fa3a06303e5132774dc0a96d0c16aa702dbac1ea0833d5a868d414f5ab2af1e1438e19e6657c6
+  languageName: node
+  linkType: hard
+
 "read-cmd-shim@npm:^3.0.0":
   version: 3.0.1
   resolution: "read-cmd-shim@npm:3.0.1"
@@ -29192,6 +29486,20 @@ resolve@1.1.7:
   languageName: node
   linkType: hard
 
+"resolve@npm:^1.1.7, resolve@npm:^1.22.8":
+  version: 1.22.12
+  resolution: "resolve@npm:1.22.12"
+  dependencies:
+    es-errors: ^1.3.0
+    is-core-module: ^2.16.1
+    path-parse: ^1.0.7
+    supports-preserve-symlinks-flag: ^1.0.0
+  bin:
+    resolve: bin/resolve
+  checksum: 4dc5a614b32142ef9ab455b242ed33c472c4ea50df17dbe1e9dac5fe0eebd7d5fdb7cb9cc8ad2165e5e0f07694498a74e7fbd6cc1599e20d84682cce1b80a4dc
+  languageName: node
+  linkType: hard
+
 "resolve@npm:^2.0.0-next.4":
   version: 2.0.0-next.4
   resolution: "resolve@npm:2.0.0-next.4"
@@ -29225,6 +29533,20 @@ resolve@1.1.7:
   languageName: node
   linkType: hard
 
+"resolve@patch:resolve@^1.1.7#~builtin<compat/resolve>, resolve@patch:resolve@^1.22.8#~builtin<compat/resolve>":
+  version: 1.22.12
+  resolution: "resolve@patch:resolve@npm%3A1.22.12#~builtin<compat/resolve>::version=1.22.12&hash=07638b"
+  dependencies:
+    es-errors: ^1.3.0
+    is-core-module: ^2.16.1
+    path-parse: ^1.0.7
+    supports-preserve-symlinks-flag: ^1.0.0
+  bin:
+    resolve: bin/resolve
+  checksum: 0cc5b060cbe081c85c331ac2eb08e8a54f0a195b899d5001822e5d3e2b335da651b1eed3d259fea904c22a0da9324a061e0e7ceab5dbeb5bcab5250b625754e1
+  languageName: node
+  linkType: hard
+
 "resolve@patch:resolve@^2.0.0-next.4#~builtin<compat/resolve>":
   version: 2.0.0-next.4
   resolution: "resolve@patch:resolve@npm%3A2.0.0-next.4#~builtin<compat/resolve>::version=2.0.0-next.4&hash=07638b"
@@ -29827,6 +30149,15 @@ resolve@1.1.7:
   languageName: node
   linkType: hard
 
+"scheduler@npm:^0.23.2":
+  version: 0.23.2
+  resolution: "scheduler@npm:0.23.2"
+  dependencies:
+    loose-envify: ^1.1.0
+  checksum: 3e82d1f419e240ef6219d794ff29c7ee415fbdc19e038f680a10c067108e06284f1847450a210b29bbaf97b9d8a97ced5f624c31c681248ac84c80d56ad5a2c4
+  languageName: node
+  linkType: hard
+
 "schema-utils@npm:^1.0.0":
   version: 1.0.0
   resolution: "schema-utils@npm:1.0.0"
@@ -30627,6 +30958,13 @@ resolve@1.1.7:
   languageName: node
   linkType: hard
 
+"source-map-js@npm:^1.2.1":
+  version: 1.2.1
+  resolution: "source-map-js@npm:1.2.1"
+  checksum: 4eb0cd997cdf228bc253bcaff9340afeb706176e64868ecd20efbe6efea931465f43955612346d6b7318789e5265bdc419bc7669c1cebe3db0eb255f57efa76b
+  languageName: node
+  linkType: hard
+
 "source-map-resolve@npm:^0.5.0, source-map-resolve@npm:^0.5.2":
   version: 0.5.3
   resolution: "source-map-resolve@npm:0.5.3"
@@ -31598,6 +31936,39 @@ resolve@1.1.7:
   languageName: node
   linkType: hard
 
+"tailwindcss@npm:^3.4.0":
+  version: 3.4.19
+  resolution: "tailwindcss@npm:3.4.19"
+  dependencies:
+    "@alloc/quick-lru": ^5.2.0
+    arg: ^5.0.2
+    chokidar: ^3.6.0
+    didyoumean: ^1.2.2
+    dlv: ^1.1.3
+    fast-glob: ^3.3.2
+    glob-parent: ^6.0.2
+    is-glob: ^4.0.3
+    jiti: ^1.21.7
+    lilconfig: ^3.1.3
+    micromatch: ^4.0.8
+    normalize-path: ^3.0.0
+    object-hash: ^3.0.0
+    picocolors: ^1.1.1
+    postcss: ^8.4.47
+    postcss-import: ^15.1.0
+    postcss-js: ^4.0.1
+    postcss-load-config: ^4.0.2 || ^5.0 || ^6.0
+    postcss-nested: ^6.2.0
+    postcss-selector-parser: ^6.1.2
+    resolve: ^1.22.8
+    sucrase: ^3.35.0
+  bin:
+    tailwind: lib/cli.js
+    tailwindcss: lib/cli.js
+  checksum: 10cd7872288fe0db85d3af402f16b0703ee74a3dd9d438a5c4838268a3ee194b60f1a8291e7abfedb878308664ddbfbc9de59e6be4b51c9c32319c7bafc287d4
+  languageName: node
+  linkType: hard
+
 "tapable@npm:^1.0.0, tapable@npm:^1.1.3":
   version: 1.1.3
   resolution: "tapable@npm:1.1.3"