@bridgeline-digital/hawk-app-cli 0.1.1-dev.20261026194933 → 0.1.1

package/README.md

@@ -315,6 +315,7 @@ npx hawk-app errors --explain 3fa1c2d9   # one error's brief, then Claude's like
 npx hawk-app usage               # the last 30 days (--days 1-400): opens, view opens, users and clients; staff apart
 npx hawk-app usage --screens     # screens and actions: the most used, then the least used, with the 3 newest versions
 npx hawk-app usage --screens --version 4   # one version's counts
+npx hawk-app usage --speed       # each screen's data time (median, 90%) beside the version before, slower ones flagged; the slowest calls
 ```
 
 **What people use.** Screens are the app's routes (ids as `:id`), its views, and what it names with `app.usage.screen`
@@ -340,6 +341,38 @@ It needs the version's **source maps**: the templates build them (`productionBro
 platform's private bucket instead of the CDN, so your source is never public. Without maps the stack stays minified and
 the brief says so. Errors of versions deployed before keep their minified stacks; the next deploy maps the new ones.
 
+## Problems users report (`hawk-app problems`)
+
+Users report what went wrong with the flag icon in the app's bar in HawkSearch: their words, a picture of the page,
+what the page showed, the version, and a recording if they agreed to one (platform/docs/problems.md).
+
+```bash
+npx hawk-app problems                  # the newest first: id, when, client, version, page, what came with it
+npx hawk-app problems show pk7m2n9x4q  # the words, a 5-minute link to the picture, the page context, the recording
+```
+
+The client's data: Bridgeline users only (`hawk-app sso`), kept 30 days, nothing written to disk. Declare and set
+`reportEmails` (`{ "type": "emails" }`) to get each report by email.
+
+## Replay a client's problem (`hawk-app dev --replay`)
+
+"It shows nothing for client X": a Bridgeline user opens the app as X in HawkSearch and turns on **Record this
+session** (the review bar's ⋮ menu). For up to 30 minutes the platform keeps every call the app makes in their session,
+with its answer (platform/docs/recordings.md). Then:
+
+```bash
+npx hawk-app recordings                  # the app's recorded sessions (kept 7 days): id, who, client, calls, failed calls
+npx hawk-app dev --replay r7k2m9xq4p     # your local code, answered as it was for that client
+```
+
+- `dev --replay` runs as the recorded client and site. Each call gets the recorded answer (the same method, path and
+  body; else the same path; else the same route with other query values), so the page behaves as it did, and you fix
+  it against the real case. A call the session never made answers 501 `not_recorded` (the terminal lists them); the
+  AI stream isn't recorded. The errors the page reported then are listed at start.
+- Nothing reaches the platform, and the session's date range is used.
+- **The client's data:** Bridgeline users only (`hawk-app sso` keys; others get 403). The recording stays in memory
+  (never on disk), is gone when you stop, and is never given to an AI assistant. Don't share screenshots of it.
+
 ## Accessibility check
 
 `hawk-app deploy` runs axe-core (WCAG 2.1 A/AA and best practices) over up to 10 built pages and sends the result with
@@ -569,6 +602,17 @@ up to 50 rows plus the bytes scanned. `--client` is the HawkSearch client id (th
 `context.tenant.clientId`); on dev, use a demo or test client. `string[]` values are comma-separated (`--param engines=a,b`). It only works
 against the dev platform. When too many queries are running (429 `too_many_queries`) it waits and tries again.
 
+```bash
+npx hawk-app data shape queries/top-searches.sql --param from=2026-09-01 --param to=2026-09-30
+npx hawk-app data shape report:top-searches --param engine=12
+```
+
+`data shape` runs a query or an analytics report for your dev client (`HAWK_APPS_DEV_CLIENT`, or `--client`) and
+prints only its **shape**: each column's type, what its values look like (number text, dates, uuids, urls), how often
+it's empty, how many distinct values and its size, all bucketed. Never a value. It's what the MCP server's `data_shape`
+tool gives Claude Code, so the code it writes handles the real answer (numbers sent as text, empty columns) without
+client data entering the chat.
+
 The sensitive tables (visitor-level data such as `summary`) are listed apart: only apps Engineering has opted in can
 query them. Ask Engineering if your app needs one.
 

package/agents/AGENTS.md

@@ -155,6 +155,13 @@ channel's email).
 (`false` while loading), or `app.setPdfExport({ fileName })` and `app.setPdfExport(null)` when the page leaves. The
 host shows a PDF icon and downloads the whole page; mark buttons and filters `data-hawk-pdf-ignore`.
 
+**Saved views:** keep what makes a page's state (filters, range, tab, sort) in the UI kit's `useSavedState(initial)`
+(or `app.state.set` and `app.state.onApply`), so users can save, share and link views from HawkSearch's Views menu. One
+small JSON object, never the data.
+
+**Ratings and reviews** need no code: users rate the app from HawkSearch's app header. To get each new review by email,
+declare `config.reviewEmails` (`{ "type": "emails" }`) and set it (`hawk-app config set reviewEmails …`).
+
 **Usage** is counted by the bridge: routes and views as screens. Name what they don't show: `useScreen('Logs')` from the
 UI kit in each tab (or `app.usage.screen`), and mark the main buttons `data-hawk-usage="Export CSV"` (or
 `app.usage.action`). Name the thing, never data (a keyword, a client).
@@ -205,6 +212,10 @@ npx hawk-app errors              # errors in the app's pages (deployed versions)
 npx hawk-app errors --explain <id>  # one error mapped to the source, the failed calls, what changed; then a likely fix
 npx hawk-app usage               # opens, users and clients per day
 npx hawk-app usage --screens     # the screens and actions used, most and least, per version (--version <n>)
+npx hawk-app usage --speed       # how fast each screen gets its data, per version; the slowest platform calls
+npx hawk-app data shape report:<name>   # what a report (or queries/<name>.sql) really answers: types, empties, sizes; no values
+npx hawk-app problems            # what users reported ("Report a problem"); hawk-app problems show <id> in a terminal (client data)
+npx hawk-app recordings          # recorded sessions of a client's problem; the developer replays one: hawk-app dev --replay <id>
 npx hawk-app upgrade             # bring the app (and this file) up to the CLI's current template
 npx hawk-app upgrade --channel latest  # a dev app (bridge/CLI on the `dev` tag) to the released versions
 ```

package/claude-plugin/hawk-apps/skills/add-query/SKILL.md

@@ -25,7 +25,9 @@ each version and approvers review them. Check first whether an analytics report
    `min`/`max`, `maxItems`.
 5. **Call it** with `app.data.query('<name>', { from, to })` (or `ctx.platform.data.query` in a function). Look up the
    result shape and errors with `docs` ("data.query"). Handle a client without analytics.
-6. **Check it.** Run `validate`. To try the SQL, tell the user to run
+6. **Check it.** Run `validate`, then `data_shape` with `queries/<name>.sql` and its params: it runs the query for the
+   developer's dev client and gives you its shape (types, empty rates, sizes), never rows. Adjust the SQL (casts,
+   `COALESCE`) and the code reading it to that shape. To see the rows themselves, tell the user to run
    `npx hawk-app data run queries/<name>.sql --client <test client id> --param from=… --param to=…` in a terminal: its rows
    are client data and must not come into the chat. Queries run only from a **deployed** version, so the app sees a
    new or changed query after a deploy (only when the user asks).

package/claude-plugin/hawk-apps/skills/new-screen/SKILL.md

@@ -19,6 +19,9 @@ colors and light/dark mode. Never restyle the kit or add another font.
    - the client's HawkSearch setup or searches: `hawksearch_api`;
    - your own SQL: the **add-query** skill;
    - server work or secrets: the **add-function** skill.
+   Then call `data_shape` for each report or query the screen reads (`report:<name>` with its fields, or
+   `queries/<name>.sql`): it shows what really comes back for the developer's client (number-as-text, empty columns,
+   nulls, sizes), never the values. Write the parsing, empty states and formatting for that shape.
    Tell the user which scopes the screen needs before adding them to `hawk-app.json`.
 4. **Build it** in the app's style:
    - read the client, engine and dates from `app.context` and re-load on `app.onContextChange`;

package/docs/bridge/README.md

@@ -1226,7 +1226,7 @@ They're kept until deleted, and each new one is emailed to whoever you set.
 ```
 
 ```tsx
-// The UI kit: a badge with the count (one request for all the page's badges); a click opens the thread.
+// The UI kit: a comment icon with a "!" when there are comments (one count request for all the page's icons); a click opens the thread.
 <HawkComments target={`keyword:${row.keyword}`} label={row.keyword} />
 <HawkComments target="page:summary" label="This month's summary" />
 ```
@@ -1452,6 +1452,25 @@ Failed data calls throw `HawkApiError` with `status` and `code`; failed host req
 
 A `403` without one of these codes means the app lacks the scope for that call.
 
+## Saved views
+
+Users save the page's state under a name and open it again later or share it with their company, from the host's
+Views menu (a bookmark icon) or a link. Say what makes the page's state, and restore it:
+
+```ts
+app.state.set({ range, target, sort });                  // as it changes; null while there's nothing to save
+const stop = app.state.onApply((state, view) => {        // a saved view (or its link) was opened
+    setRange(state.range);
+    setTarget(state.target);
+    setSort(state.sort);
+});
+```
+
+One small JSON object (at most 16 KB), never the page's data. The menu shows only while the app has set a state; a view
+opened by a link reaches `onApply` even if the app registers it later. The UI kit's `useSavedState(initial)` does both
+(`const [filters, setFilters] = useSavedState({ range: 'l13', target: null })`). Errors: `invalid_request` (not a JSON
+object, too large). See the platform's docs/saved-views.md.
+
 ## Errors and usage
 
 `createApp` reports, on its own, one open per page load (the full app or the view showing), the screens and actions
@@ -1482,7 +1501,12 @@ app.usage.action('Bulk fix');   // an action that isn't a click on one element
 Names are letters, digits and simple punctuation, up to 80 characters: name the thing (`Export CSV`), not the data
 (never a keyword or a client). `hawk-app usage --screens` lists the most and least used, per version.
 
-`createApp({ reportErrors: false, reportOpens: false, reportUsage: false })` turns any of them off.
+**How fast it is.** The bridge also times each screen: how long the page took to load, how long a screen took to get
+its data (until its platform calls are done), slow clicks (40 ms or more to the next paint) and each platform call by
+route. Only times and names. `hawk-app usage --speed` shows each screen's median and 90th percentile, the version
+beside the one before it, and the slowest calls.
+
+`createApp({ reportErrors: false, reportOpens: false, reportUsage: false, reportSpeed: false })` turns any of them off.
 
 ## Talk to the host
 
@@ -1580,6 +1604,9 @@ useEffect(() => void app.assistant.setContext({ page: 'Recommendation Dashboard'
 await app.assistant.ask('Which widgets are taking up space?');
 ```
 
+Asking from a dialog or drawer is fine: the host's assistant is part of the page the dialog covers, so the host closes
+the dialog first (as a click on its backdrop would) and the answer is in view.
+
 A message is at most 2,000 characters. Errors (`HawkBridgeError`): `unsupported` (no assistant on the page), `scope_missing`,
 `invalid_request`; `setContext` needs no scope (without it, only "Explain this page" gets the context). Hosts: `<hawk-app-frame>` fires a cancelable `hawk-assistant` event (`detail.message`; `hawk-assistant-context` with `detail.context` for the context); a host that
 answers it itself calls `preventDefault()` and sets the element's `assistant` attribute. Otherwise the element sends the

package/docs/ui/README.md

@@ -42,12 +42,16 @@ export function Page() {
   then renders its children in the theme. It follows the host when its theme changes.
 - **`useHawk()`** returns `{ app, context }`, always connected (the provider renders children only then).
   `useHawkAppState()` is the hook underneath, for an app that wants to render the states itself.
-- **`<HawkComments target label?>`** (the `comments` scope) is a comment badge with its count; a click opens the
+- **`<HawkComments target label?>`** (the `comments` scope) is a comment icon with a "!" when there are comments (the count in its tooltip); a click opens the
   thread in a drawer, where everyone at the client reads and adds comments (authors edit and delete their own). The
   page's badges share one count request. See the bridge guide's "Comments".
 - **`usePdfExport(options | false)`** lets the user export the page as a PDF while it's mounted: the host shows a PDF
   icon, and a click downloads the whole page. `usePdfExport({ fileName: 'Zero results' })`, or `false` while loading.
   Leave out buttons and filters with `data-hawk-pdf-ignore`. See the bridge guide's "Export a page as a PDF".
+- **`useSavedState(initial)`** is `useState` for what makes a saved view (filters, range, tab, sort): the value is the
+  page's state for the host's Views menu, and opening a saved view or its link sets it back.
+  `const [filters, setFilters] = useSavedState({ range: 'l13', target: null })`. One small JSON object, once per page.
+  See the bridge guide's "Saved views".
 - **`useScreen(name | null)`** counts a screen the routes don't show, such as a tab, each time it's shown:
   `useScreen('Logs')` in the tab's component. Routes and views are counted by the bridge, and so are clicks on
   `data-hawk-usage="Export CSV"` elements. See `hawk-app usage --screens` and the bridge guide's "Errors and usage".

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bridgeline-digital/hawk-app-cli",
-  "version": "0.1.1-dev.20261026194933",
+  "version": "0.1.1",
   "description": "For Bridgeline developers: create, deploy and register Hawk Apps (Services-built tools embedded in HawkSearch). Requires a Hawk Apps publisher key.",
   "author": "Bridgeline Digital",
   "license": "UNLICENSED",

package/src/cli.mjs

@@ -30,6 +30,8 @@ import { testCommand } from './test-command.mjs';
 import { appChannel } from './channel.mjs';
 import { accessibilityWarnings, checkAccessibility } from './accessibility.mjs';
 import { errorsCommand, usageCommand } from './telemetry.mjs';
+import { recordingsCommand } from './replay.mjs';
+import { problemsCommand } from './problems.mjs';
 
 /** The short help: what each command is for, by task. `hawk-app help <command>` shows a command's details. */
 const HELP = `hawk-app: build, run and release Hawk Apps
@@ -66,6 +68,8 @@ Data and functions
 
 Monitor
   errors, usage           The app's page errors; its opens, users, clients, screens and actions
+  recordings              Recorded sessions to replay with hawk-app dev --replay <id> (Bridgeline users)
+  problems                What users reported with "Report a problem" (Bridgeline users)
 
 Account
   login, whoami, logout   A publisher key (for CI), and which key and platform apply here
@@ -164,6 +168,20 @@ Usage:
                                                     from the deployed version: deploy after changing them. The
                                                     client API ("api") runs the local functions/ instead:
                                                     /v1/clients/<id>/apps/<slug>/api/<name> on this port
+  hawk-app dev --replay <id> [--url <app dev URL>] [--port 3200] [--no-start]
+                                                    Run your local code against a recorded session (a Bridgeline
+                                                    user's "Record this session" in HawkSearch): the app's calls are
+                                                    answered as they were for that client, nothing reaches the
+                                                    platform. Bridgeline users only (hawk-app sso); kept in memory
+  hawk-app usage --speed [--days 14] [--version <n>]
+                                                    How fast each screen gets its data (median and 90th percentile),
+                                                    the version beside the one before it (slower ones flagged), the
+                                                    page's load, slow clicks and the slowest platform calls
+  hawk-app recordings                               The app's recorded sessions (kept 7 days), with their ids
+  hawk-app problems [show <id>]                     What users reported with "Report a problem" (the flag in the
+                                                    app's bar): their words, a picture of the page (a 5-minute link),
+                                                    what the page showed, the version, a recording if they agreed.
+                                                    Bridgeline users only; kept 30 days
 
 Clients (who has the app; also managed in the Hawk Analytics portal, not in hawk-app.json):
   hawk-app clients                                  Show the app's visibility and its clients
@@ -209,6 +227,11 @@ Custom data (app queries, scope data:read):
   hawk-app data run <queries/name.sql> --client <id> [--param name=value …]
                                                     Run a query against a client's data (dev platform only);
                                                     string[] values are comma-separated
+  hawk-app data shape <queries/name.sql | report:<name>> [--client <id>] [--param name=value …]
+                                                    What a query or analytics report answers, as its shape only
+                                                    (columns, types, how often empty, what values look like,
+                                                    bucketed sizes): never the values. Default client: your dev
+                                                    client (HAWK_APPS_DEV_CLIENT). For the AI that writes the code
 
 Functions (server-side code, scope functions:invoke):
   hawk-app secrets list                             List the app's secrets (names only, never values)
@@ -605,7 +628,8 @@ export async function main(argv, { fetchImpl = fetch, log = console.log, runBuil
         case 'dev': {
             const manifest = await loadManifest(manifestFile);
             const projectDir = dirname(resolve(manifestFile));
-            if (!flags.client && !(env ?? process.env).HAWK_APPS_DEV_CLIENT) {
+            // A replay runs as the recorded client.
+            if (!flags.replay && !flags.client && !(env ?? process.env).HAWK_APPS_DEV_CLIENT) {
                 // No client yet: ask which one (by name), and remember it in .env.local for next time.
                 const id = await pickDevClient({ client, slug: manifest.slug, ...(choose ? { choose } : {}), ...(ask ? { ask } : {}), log });
                 await rememberDevClient(projectDir, id);
@@ -629,7 +653,10 @@ export async function main(argv, { fetchImpl = fetch, log = console.log, runBuil
         }
 
         case 'data':
-            return dataCommand({ client, sub: positional[0], args: positional.slice(1), flags, ...(sleep ? { sleep } : {}), log });
+            return dataCommand({
+                client, sub: positional[0], args: positional.slice(1), flags, ...(sleep ? { sleep } : {}), log,
+                ...(env ? { env } : {}), manifest: () => loadManifest(manifestFile),
+            });
 
         case 'secrets': {
             const manifest = await loadManifest(manifestFile);
@@ -665,6 +692,14 @@ export async function main(argv, { fetchImpl = fetch, log = console.log, runBuil
             return usageCommand({ client: client(), manifest: await loadManifest(manifestFile), flags, log });
         }
 
+        case 'recordings': {
+            return recordingsCommand({ client: client(), manifest: await loadManifest(manifestFile), log });
+        }
+
+        case 'problems': {
+            return problemsCommand({ client: client(), manifest: await loadManifest(manifestFile), sub: positional[0], args: positional.slice(1), log });
+        }
+
         case 'logs': {
             const manifest = await loadManifest(manifestFile);
             const controller = new AbortController();
@@ -857,7 +892,7 @@ export function parse(argv) {
                 flags.param = [...(flags.param ?? []), inline ?? argv[++i]];
                 continue;
             }
-            const takesValue = ['manifest', 'platform', 'slug', 'name', 'template', 'client', 'app', 'since', 'value-from-env', 'engine', 'url', 'port', 'env', 'publisher', 'pick', 'channel', 'days', 'alias', 'explain', 'version'].includes(name);
+            const takesValue = ['manifest', 'platform', 'slug', 'name', 'template', 'client', 'app', 'since', 'value-from-env', 'engine', 'url', 'port', 'env', 'publisher', 'pick', 'channel', 'days', 'alias', 'explain', 'version', 'replay'].includes(name);
             flags[name] = takesValue ? inline ?? argv[++i] : true;
         } else if (command === undefined) {
             command = arg;

package/src/data.mjs

@@ -1,6 +1,7 @@
 import { readFile } from 'node:fs/promises';
 import { basename } from 'node:path';
 import { checkValue, parseParamValue, validateQuery } from './queries.mjs';
+import { formatShape, shapeOf } from './shape.mjs';
 
 const MAX_ROWS_SHOWN = 50;
 const MAX_CELL_WIDTH = 40;
@@ -11,7 +12,8 @@ const CLIENT_ID = /^[A-Za-z0-9]+$/;
 const USAGE = `Usage:
   hawk-app data tables [--app <slug>]
   hawk-app data describe <table>
-  hawk-app data run <queries/name.sql> --client <id> [--param name=value …]`;
+  hawk-app data run <queries/name.sql> --client <id> [--param name=value …]
+  hawk-app data shape <queries/name.sql | report:<name>> [--client <id>] [--param name=value …]`;
 
 const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 
@@ -19,7 +21,7 @@ const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
  * `hawk-app data …`: the tables app queries can use, and running a query against a client's data before deploying it.
  * `client` is a factory, so a usage mistake shows before any login check.
  */
-export async function dataCommand({ client, sub, args = [], flags = {}, sleep = wait, log = console.log }) {
+export async function dataCommand({ client, sub, args = [], flags = {}, sleep = wait, log = console.log, env = process.env, manifest = null, fetchImpl = fetch, today = () => new Date() }) {
     switch (sub) {
         case 'tables': {
             const app = typeof flags.app === 'string' ? flags.app : undefined;
@@ -53,17 +55,69 @@ export async function dataCommand({ client, sub, args = [], flags = {}, sleep =
             return 0;
         }
 
-        case 'run':
-            return run({ client, file: args[0], flags, sleep, log });
+        case 'run': {
+            const data = await execute({ client, file: args[0], clientId: flags.client, flags, sleep, log });
+            printTable(data.columns ?? [], data.rows ?? [], log);
+            const rowCount = data.rowCount ?? data.rows?.length ?? 0;
+            const shown = Math.min(rowCount, MAX_ROWS_SHOWN, data.rows?.length ?? 0);
+            log(`${rowCount} row${rowCount === 1 ? '' : 's'}${rowCount > shown ? ` (showing the first ${shown})` : ''}, ${formatBytes(data.bytesScanned ?? 0)} scanned${data.cached ? ' (cached result)' : ''}.`);
+            return 0;
+        }
+
+        case 'shape':
+            return shape({ client, source: args[0], flags, sleep, log, env, manifest, fetchImpl, today });
 
         default:
             throw new Error(sub ? `Unknown data command "${sub}".\n${USAGE}` : USAGE);
     }
 }
 
-async function run({ client, file, flags, sleep, log }) {
+/**
+ * `hawk-app data shape <queries/name.sql | report:<name>>`: what a query or an analytics report answers for a client
+ * (default the app's dev client, HAWK_APPS_DEV_CLIENT), as its shape only: columns, types, how often empty, what values
+ * look like, bucketed sizes. Never the values: it's for the AI that writes the code (the MCP `data_shape` tool).
+ */
+async function shape({ client, source, flags, sleep, log, env, manifest, fetchImpl, today }) {
+    if (!source || !(source.endsWith('.sql') || source.startsWith('report:'))) throw new Error(USAGE);
+    const clientId = typeof flags.client === 'string' ? flags.client : env.HAWK_APPS_DEV_CLIENT;
+    if (!clientId || !CLIENT_ID.test(clientId)) {
+        throw new Error('Pass the client: --client <id> (or set HAWK_APPS_DEV_CLIENT in .env.local: `hawk-app dev` asks once and saves it).');
+    }
+    let result;
+    if (source.endsWith('.sql')) {
+        const data = await execute({ client, file: source, clientId, flags, sleep, log: () => undefined });
+        result = shapeOf(data.rows ?? [], data.columns ?? []);
+    } else {
+        const app = manifest ? await manifest() : null;
+        if (!app?.slug) throw new Error('Run it in the app\'s folder (next to hawk-app.json): reports are called as the app.');
+        const name = source.slice('report:'.length).replace(/^\/+|\/+$/g, '');
+        if (!/^[A-Za-z0-9/_-]+$/.test(name)) throw new Error(`"${name}" isn't a report name (analytics_reports lists them).`);
+        const end = today();
+        const from = new Date(end.getTime() - 29 * 86_400_000).toISOString().slice(0, 10);
+        const body = { from, to: end.toISOString().slice(0, 10) };
+        for (const entry of flags.param ?? []) {
+            const eq = typeof entry === 'string' ? entry.indexOf('=') : -1;
+            if (eq <= 0) throw new Error(`--param needs name=value, not "${entry}".`);
+            const raw = entry.slice(eq + 1);
+            body[entry.slice(0, eq)] = /^-?\d+(\.\d+)?$/.test(raw) ? Number(raw) : /^(true|false)$/.test(raw) ? raw === 'true' : raw;
+        }
+        const issued = await client().devToken(app.slug, { clientId, engineId: env.HAWK_APPS_DEV_ENGINE || null, internal: true });
+        const url = new URL(`analytics/${name}`, issued.apiBaseUrl.endsWith('/') ? issued.apiBaseUrl : `${issued.apiBaseUrl}/`);
+        const response = await fetchImpl(url, { method: 'POST', headers: { Authorization: `Bearer ${issued.token}`, 'Content-Type': 'application/json', Accept: 'application/json' }, body: JSON.stringify(body) });
+        const payload = await response.json().catch(() => null);
+        if (!response.ok) {
+            throw new Error(`The report answered ${response.status}${payload?.code ? ` ${payload.code}` : ''}${payload?.detail ? `: ${payload.detail}` : ''}.`);
+        }
+        const rows = Array.isArray(payload?.data) ? payload.data : Array.isArray(payload) ? payload : [];
+        result = shapeOf(rows);
+    }
+    for (const line of formatShape(`${source} for client ${clientId}`, result)) log(line);
+    return 0;
+}
+
+/** Checks and runs a query file against a client; resolves with the platform's answer (columns, rows, …). */
+async function execute({ client, file, clientId, flags, sleep, log }) {
     if (!file || !file.endsWith('.sql')) throw new Error(USAGE);
-    const clientId = flags.client;
     if (typeof clientId !== 'string' || !CLIENT_ID.test(clientId)) throw new Error('Pass the client to run against: --client <id> (letters and digits, e.g. e3141).');
 
     const jsonFile = file.replace(/\.sql$/, '.json');
@@ -128,13 +182,7 @@ async function run({ client, file, flags, sleep, log }) {
         await sleep(Math.min(Math.max(1000 * 2 ** attempt, data.retryAfterMs ?? 0), MAX_POLL_DELAY_MS));
         ({ status, data } = await retrying(() => platform.dataExecution(data.executionId)));
     }
-
-
-    printTable(data.columns ?? [], data.rows ?? [], log);
-    const rowCount = data.rowCount ?? data.rows?.length ?? 0;
-    const shown = Math.min(rowCount, MAX_ROWS_SHOWN, data.rows?.length ?? 0);
-    log(`${rowCount} row${rowCount === 1 ? '' : 's'}${rowCount > shown ? ` (showing the first ${shown})` : ''}, ${formatBytes(data.bytesScanned ?? 0)} scanned${data.cached ? ' (cached result)' : ''}.`);
-    return 0;
+    return data;
 }
 
 async function readText(file) {

package/src/dev.mjs

@@ -7,6 +7,7 @@ import { join } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { TEMPLATES } from './create.mjs';
 import { bundleFunction, loadFunctions } from './functions.mjs';
+import { loadRecording, recordedErrors, replayContext, replayer, replayToken } from './replay.mjs';
 
 const BRIDGE_PACKAGE = '@bridgeline-digital/hawk-app-bridge';
 export const DEFAULT_APP_URL = 'http://localhost:3100/';
@@ -22,13 +23,22 @@ const MAX_PROXY_BODY = 10 * 1024 * 1024;
  * (`POST /publish/apps/{slug}/dev-token`, any client), and proxies the app's platform calls (so no CORS setup is needed,
  * on dev or prod). Nothing is written to disk; the HawkSearch API key, if any, comes from the environment.
  */
-export async function devCommand({ client, manifest, flags = {}, projectDir = process.cwd(), env = process.env, log = console.log, signal, startDev = npmRunDev, waitForApp = waitForUrl }) {
-    const clientId = flags.client ?? env.HAWK_APPS_DEV_CLIENT;
+export async function devCommand({ client, manifest, flags = {}, projectDir = process.cwd(), env = process.env, log = console.log, signal, startDev = npmRunDev, waitForApp = waitForUrl, fetchImpl = fetch }) {
+    // --replay <id>: a recorded session's answers instead of the platform, as its client and site.
+    let replay = null;
+    if (flags.replay !== undefined) {
+        if (typeof flags.replay !== 'string') throw new Error('--replay needs a recording id, e.g. --replay r7k2m9xq4p (hawk-app recordings lists them).');
+        log(`› Downloading recording ${flags.replay} …`);
+        const loaded = await loadRecording({ client, slug: manifest.slug, id: flags.replay, fetchImpl, log });
+        replay = { ...loaded, answer: replayer(loaded.calls), context: replayContext(loaded.calls) };
+    }
+    const clientId = replay ? replay.recording.clientId : flags.client ?? env.HAWK_APPS_DEV_CLIENT;
     if (!clientId || clientId === true) {
         throw new Error('Usage: hawk-app dev --client <client id> [--engine <id>] [--url http://localhost:3100] [--port 3200] [--client-user] [--no-start]\n'
+            + '       hawk-app dev --replay <recording id>\n'
             + '  (or set HAWK_APPS_DEV_CLIENT in .env.local)');
     }
-    const engineId = flags.engine ?? env.HAWK_APPS_DEV_ENGINE ?? null;
+    const engineId = replay ? replay.recording.engineId ?? null : flags.engine ?? env.HAWK_APPS_DEV_ENGINE ?? null;
     const appUrl = normalizeAppUrl(typeof flags.url === 'string' ? flags.url : defaultAppUrl(projectDir, manifest));
     const port = Number(flags.port ?? DEFAULT_PORT);
     if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error('--port must be a port number.');
@@ -37,11 +47,15 @@ export async function devCommand({ client, manifest, flags = {}, projectDir = pr
         : null;
 
     const hostScript = await bundleHost(projectDir);
-    const tokens = tokenBroker({ client, slug: manifest.slug, hawkSearch });
+    const tokens = replay
+        ? async () => replayToken({ slug: manifest.slug, recording: replay.recording, scopes: Array.isArray(manifest.scopes) ? manifest.scopes : [] })
+        : tokenBroker({ client, slug: manifest.slug, hawkSearch });
     const settings = {
-        slug: manifest.slug, name: manifest.name ?? manifest.slug, appUrl, clientId: String(clientId), engineId: engineId ? String(engineId) : null, internal: !flags['client-user'],
+        slug: manifest.slug, name: manifest.name ?? manifest.slug, appUrl, clientId: String(clientId), engineId: engineId ? String(engineId) : null, internal: replay ? true : !flags['client-user'],
         // The page's Action menu opens these views in a dialog, as HawkSearch does from its screens.
         actions: actionsFor(manifest),
+        ...(replay ? { replay: replaySettings(manifest, replay) } : {}),
+        ...(replay?.context.from && replay.context.to ? { from: replay.context.from, to: replay.context.to } : {}),
     };
 
     // The app's dev server, unless it runs already (--url) or --no-start.
@@ -51,10 +65,10 @@ export async function devCommand({ client, manifest, flags = {}, projectDir = pr
         child = startDev({ cwd: projectDir });
     }
 
-    const clientApi = manifest.api && Object.keys(manifest.api).length
+    const clientApi = !replay && manifest.api && Object.keys(manifest.api).length
         ? localClientApi({ projectDir, manifest, client, engineId: settings.engineId, hawkSearchDomain: (env.HAWKSEARCH_DOMAIN || DEFAULT_HAWKSEARCH_DOMAIN).replace(/\/+$/, ''), log })
         : null;
-    const server = createHostServer({ settings, hostScript, tokens, platformBase: client.base, clientApi, log });
+    const server = createHostServer({ settings, hostScript, tokens, platformBase: client.base, clientApi, replay, log });
     await new Promise((resolve, reject) => {
         server.once('error', (error) => reject(error.code === 'EADDRINUSE' ? new Error(`Port ${port} is in use: pick another with --port.`) : error));
         server.listen(port, '127.0.0.1', resolve);
@@ -66,7 +80,11 @@ export async function devCommand({ client, manifest, flags = {}, projectDir = pr
     log('');
     log(`✔ Local host: http://localhost:${port}/`);
     log(`  app ${settings.slug} from ${appUrl}, client ${settings.clientId}${settings.engineId ? `, site ${settings.engineId}` : ''}, as a ${settings.internal ? 'Bridgeline' : 'client'} user`);
-    log(`  platform ${client.base} (real data)${hawkSearch ? `; HawkSearch ${hawkSearch.domain} with HAWKSEARCH_API_KEY` : '; no HawkSearch key (set HAWKSEARCH_API_KEY for the dashboard API)'}`);
+    if (replay) {
+        for (const line of replayIntro(replay)) log(`  ${line}`);
+    } else {
+        log(`  platform ${client.base} (real data)${hawkSearch ? `; HawkSearch ${hawkSearch.domain} with HAWKSEARCH_API_KEY` : '; no HawkSearch key (set HAWKSEARCH_API_KEY for the dashboard API)'}`);
+    }
     if (clientApi) {
         const [name, endpoint] = Object.entries(manifest.api)[0];
         log(`  client API: your local functions/, e.g. curl -H "X-HawkSearch-ApiKey: <site API key>" ${(endpoint.method ?? 'GET').toUpperCase() === 'POST' ? '-X POST -d "{}" ' : ''}http://localhost:${port}/v1/clients/${settings.clientId}/apps/${settings.slug}/api/${name}`);
@@ -84,6 +102,34 @@ export async function devCommand({ client, manifest, flags = {}, projectDir = pr
     return 0;
 }
 
+/** What the page shows of a replay: the recording, and the view to open when the session was in one. */
+function replaySettings(manifest, replay) {
+    const r = replay.recording;
+    const view = replay.context.view;
+    const path = view ? manifest.views?.[view]?.path : null;
+    return {
+        id: r.id, by: r.startedBy?.name || r.startedBy?.email || null, startedAt: r.startedAt, calls: replay.calls.length, version: r.version ?? null,
+        ...(view && typeof path === 'string' ? { view, viewPath: path.replace(/^\/+|\/+$/g, '') } : {}),
+    };
+}
+
+/** The terminal's summary of a replay: what was recorded, and the errors the page reported then. */
+export function replayIntro(replay) {
+    const r = replay.recording;
+    const lines = [
+        `replaying recording ${r.id}: ${replay.calls.length} calls by ${r.startedBy?.name || r.startedBy?.email || 'a Bridgeline user'}, ${new Date(r.startedAt).toISOString().slice(0, 16).replace('T', ' ')} UTC${r.version ? `, v${r.version}` : ''}`,
+        'nothing reaches the platform: the app\'s calls are answered from the recording (501 not_recorded when the session never made them)',
+        'the recording is the client\'s data: it stays in memory and is gone when you stop',
+    ];
+    if (replay.context.view) lines.push(`the session ran the view "${replay.context.view}" (opened here without its params: use the Action menu for an action's)`);
+    const errors = recordedErrors(replay.calls);
+    if (errors.length) {
+        lines.push(`the page reported ${errors.length === 1 ? 'this error' : `${errors.length} errors`} then:`);
+        for (const e of errors.slice(0, 5)) lines.push(`  ${e}`);
+    }
+    return lines;
+}
+
 /** Each action of hawk-app.json with its view's path and height and the params its targets read, for the page's Action menu. */
 export function actionsFor(manifest) {
     const views = manifest.views && typeof manifest.views === 'object' ? manifest.views : {};
@@ -165,7 +211,7 @@ export async function bundleHost(projectDir) {
  * The local host: `/` (the page), `/host.js` (the bridge's host side), `POST /token` (from the page only), `/api/*`
  * (the platform, for the app; CORS for the app's origin only) and `POST /ai-stream` (the AI stream, see `proxyAiStream`).
  */
-export function createHostServer({ settings, hostScript, tokens, platformBase, clientApi = null, log = console.log, fetchImpl = fetch }) {
+export function createHostServer({ settings, hostScript, tokens, platformBase, clientApi = null, replay = null, log = console.log, fetchImpl = fetch }) {
     const appOrigin = new URL(settings.appUrl).origin;
     // The real AI stream URL from the platform's last `GET ai` answer, which the app is told is `/ai-stream` here.
     const ai = { streamUrl: null };
@@ -189,9 +235,15 @@ export function createHostServer({ settings, hostScript, tokens, platformBase, c
                 const issued = await tokens({ clientId: String(body.clientId ?? ''), engineId: body.engineId ? String(body.engineId) : null, internal: body.internal !== false, forceRefresh: !!body.forceRefresh });
                 return send(res, 200, 'application/json', JSON.stringify(issued));
             }
+            if (replay && url.pathname.startsWith('/api/')) {
+                return replayAnswer(req, res, url, { appOrigin, hostOrigin, replay, log });
+            }
             if (url.pathname.startsWith('/api/')) {
                 return proxy(req, res, url, { platformBase, appOrigin, hostOrigin, ai, fetchImpl });
             }
+            if (replay && url.pathname === '/ai-stream') {
+                return notRecorded(res, corsHeaders(appOrigin, 'POST'), req.method, 'The AI stream isn\'t recorded: Claude\'s answers can\'t be replayed.');
+            }
             if (url.pathname === '/ai-stream') {
                 return proxyAiStream(req, res, { appOrigin, ai, fetchImpl });
             }
@@ -345,6 +397,70 @@ async function proxy(req, res, url, { platformBase, appOrigin, hostOrigin, ai, f
     res.end(payload);
 }
 
+/**
+ * A replayed call: the recorded answer (status, content type, body), or 501 `not_recorded` when the session never made
+ * it (logged once each). Telemetry is answered here and not reported (a replay isn't anyone using the app). `GET ai`
+ * points the app at this host's `/ai-stream`, which isn't recorded either.
+ */
+async function replayAnswer(req, res, url, { appOrigin, hostOrigin, replay, log }) {
+    const cors = corsHeaders(appOrigin, 'GET, POST, PUT, DELETE');
+    if (req.method === 'OPTIONS') {
+        res.writeHead(204, cors);
+        return res.end();
+    }
+    const body = ['GET', 'HEAD'].includes(req.method) ? '' : (await readBody(req, MAX_PROXY_BODY)).toString('utf8');
+    let pathname;
+    try {
+        pathname = decodeURIComponent(url.pathname);
+    } catch {
+        pathname = url.pathname;
+    }
+    if (!pathname.startsWith('/api/v1/')) return send(res, 404, 'text/plain', 'Not found');
+    const path = pathname.slice('/api/v1/'.length) + url.search;
+    if (path.startsWith('telemetry/')) {
+        res.writeHead(204, { ...cors, 'Cache-Control': 'no-store' });
+        return res.end();
+    }
+    const hit = replay.answer(req.method, path, body);
+    if (!hit) {
+        replay.missed ??= new Set();
+        if (!replay.missed.has(`${req.method} ${path}`)) {
+            replay.missed.add(`${req.method} ${path}`);
+            log(`! not recorded: ${req.method} ${path} (answered 501)`);
+        }
+        return notRecorded(res, cors, req.method, `The recorded session never made ${req.method} ${path.split('?')[0]}.`);
+    }
+    const { call } = hit;
+    if (call.truncated) {
+        return send(res, 502, 'application/problem+json', JSON.stringify({ status: 502, code: 'too_large_to_record', detail: `The answer to ${req.method} ${path.split('?')[0]} was over 2 MB and wasn't recorded.` }), cors);
+    }
+    let payload = call.body == null ? Buffer.alloc(0) : call.base64 ? Buffer.from(call.body, 'base64') : Buffer.from(call.body, 'utf8');
+    if (req.method === 'GET' && path === 'ai' && call.status < 300) payload = pointAiAt(payload, `${hostOrigin}/ai-stream`);
+    if (call.status === 204 || payload.length === 0) {
+        res.writeHead(call.status, { ...cors, 'Cache-Control': 'no-store' });
+        return res.end();
+    }
+    send(res, call.status, call.contentType ?? 'application/json', payload, cors);
+}
+
+function notRecorded(res, cors, method, detail) {
+    if (method === 'OPTIONS') {
+        res.writeHead(204, cors);
+        return res.end();
+    }
+    send(res, 501, 'application/problem+json', JSON.stringify({ status: 501, code: 'not_recorded', detail }), cors);
+}
+
+/** The recorded `GET ai` answer with its stream URL pointed at this host (whose replay says the stream isn't recorded). */
+function pointAiAt(payload, localStream) {
+    try {
+        const body = JSON.parse(payload.toString('utf8'));
+        return body && typeof body === 'object' && 'streamUrl' in body ? Buffer.from(JSON.stringify({ ...body, streamUrl: localStream })) : payload;
+    } catch {
+        return payload;
+    }
+}
+
 /** A real AI stream URL: https on a Lambda function URL host (`*.on.aws`), path `/v1/ai/messages`, nothing else. */
 export function isAiStreamUrl(value) {
     try {
@@ -428,8 +544,8 @@ function readBody(req, limit) {
     });
 }
 
-function send(res, status, type, body) {
-    res.writeHead(status, { 'Content-Type': type, 'Cache-Control': 'no-store' });
+function send(res, status, type, body, headers = {}) {
+    res.writeHead(status, { ...headers, 'Content-Type': type, 'Cache-Control': 'no-store' });
     res.end(body);
 }
 
@@ -458,7 +574,7 @@ const escapeHtml = (value) => String(value).replace(/[&<>"']/g, (c) => ({ '&': '
 export function hostPage(settings) {
     const today = new Date();
     const from = new Date(today.getTime() - 29 * 86_400_000);
-    const initial = { ...settings, from: from.toISOString().slice(0, 10), to: today.toISOString().slice(0, 10), theme: 'light' };
+    const initial = { ...settings, from: settings.from ?? from.toISOString().slice(0, 10), to: settings.to ?? today.toISOString().slice(0, 10), theme: 'light' };
     return `<!doctype html>
 <html lang="en">
 <head>
@@ -491,6 +607,7 @@ export function hostPage(settings) {
   dialog::backdrop { background: rgba(0,0,0,.45); }
   #actionTitle { margin: 0 0 8px; font-weight: 600; }
   #actionFrame { min-height: 200px; margin-bottom: 8px; }
+  #replay { padding: 6px 16px; background: #fef0c7; color: #7a2e0e; border-bottom: 1px solid #fedf89; font-size: 13px; }
 </style>
 </head>
 <body>
@@ -506,12 +623,16 @@ export function hostPage(settings) {
   <button id="reload">Reload app</button>
   <hawk-app-explain for="frame"></hawk-app-explain>
   <hawk-app-pdf for="frame"></hawk-app-pdf>
+  <hawk-app-reviews for="frame"></hawk-app-reviews>
+  <hawk-app-report for="frame"></hawk-app-report>
+  <hawk-app-views for="frame"></hawk-app-views>
   <span id="actions" hidden>
     <label>Action <select id="action"></select></label>
     <label>Value <input id="actionValue" size="14" placeholder="e.g. rain boots"></label>
     <button id="runAction">Run</button>
   </span>
 </header>
+<div id="replay" hidden></div>
 <dialog id="actionDialog"><p id="actionTitle"></p><hawk-app-frame id="actionFrame"></hawk-app-frame><button id="closeAction">Close</button></dialog>
 <main>
   <div>
@@ -533,6 +654,15 @@ export function hostPage(settings) {
   let state = { ...initial };
   for (const key of ['clientId', 'engineId', 'from', 'to', 'theme']) $(key).value = state[key] ?? '';
   $('internal').value = String(state.internal);
+  // A replay: the recorded client, site and user only (its answers are theirs).
+  const replay = initial.replay;
+  if (replay) {
+    for (const key of ['clientId', 'engineId', 'internal']) $(key).disabled = true;
+    $('replay').hidden = false;
+    $('replay').textContent = 'Replaying recording ' + replay.id + (replay.by ? ' by ' + replay.by : '') + ' · ' + new Date(replay.startedAt).toLocaleString()
+      + ' · ' + replay.calls + ' calls' + (replay.version ? ' · recorded on v' + replay.version : '') + (replay.view ? ' · view ' + replay.view : '')
+      + ' · answers come from the recording (the client\\'s data: don\\'t share screenshots)';
+  }
 
   const event = (text) => { const row = document.createElement('div'); row.textContent = new Date().toLocaleTimeString() + '  ' + text; $('events').prepend(row); };
   const claims = (token) => JSON.parse(atob(token.split('.')[1].replace(/-/g, '+').replace(/_/g, '/')));
@@ -581,8 +711,10 @@ export function hostPage(settings) {
     document.body.classList.toggle('dark', state.theme === 'dark');
     const t = await token(false).catch(() => null);
     if (!t) return;
-    frame.context = context(t.token);
-    if (reloadApp) { frame.removeAttribute('src'); frame.setAttribute('src', initial.appUrl); }
+    // A replayed session that ran in a view opens that view (its params aren't recorded).
+    const view = replay && replay.view ? { name: replay.view, params: {}, embedded: true } : null;
+    frame.context = view ? { ...context(t.token), view } : context(t.token);
+    if (reloadApp) { frame.removeAttribute('src'); frame.setAttribute('src', view ? new URL(replay.viewPath + '/', initial.appUrl).href : initial.appUrl); }
   }
 
   $('apply').addEventListener('click', () => {

package/src/mcp.mjs

@@ -5,7 +5,8 @@
 //   - No client names: outputs show client ids only. clients_add asks the person to pick the client in a form their
 //     assistant shows (MCP elicitation); the answer comes back to this server, and the assistant hears only that a
 //     client was added. Without forms, it sends the person to `hawk-app clients add --pick` in a terminal.
-//   - No query results: `data run` would put client rows in the assistant's context. Table and column names only.
+//   - No query results: `data run` would put client rows in the assistant's context. Table and column names only, and
+//     `data_shape`: what an answer looks like (types, empty rates, bucketed sizes), never its values.
 //   - The publisher key never passes through a tool: the commands use the saved login, as the CLI does.
 //   - deploy asks nothing: the assistant's client asks the user before calling it (destructive hint),
 //     and a question the CLI would ask (a teammate's app, serious vulnerabilities) cancels unless `force` is set.
@@ -31,7 +32,7 @@ const TAIL_LINES = 40;
 const INSTRUCTIONS = `Tools for building Hawk Apps: static web apps that run inside the HawkSearch dashboard and get their context and data through the bridge (@bridgeline-digital/hawk-app-bridge).
 - Read the app's AGENTS.md first. Before using a bridge call, look it up with \`docs\` (options, limits, error codes); the showcase sections are working examples of every feature.
 - Before building a screen, \`ui_components\` lists the UI kit's components for this app's template (Spark's look): use them instead of writing your own.
-- For analytics data, \`analytics_reports\` lists the reports app.analytics.report() can call, and gives one report's columns and filters: check it before writing a query.
+- For analytics data, \`analytics_reports\` lists the reports app.analytics.report() can call, and gives one report's columns and filters: check it before writing a query. \`data_shape\` then shows what a report or query really answers for the developer's client (types, empty columns, number-as-text; never values): check it before writing code that reads the data.
 - For HawkSearch's own APIs (dashboard, search, recommendations, indexing), \`hawksearch_api\` gives an operation's fields, the bridge call and its scope, and says what apps can't call: check it before writing one.
 - \`validate\` after changing hawk-app.json, queries/ or functions/, and \`validate\` with build=true after changing the build setup.
 - \`deploy\` changes the app on the dev platform: only when the user asks (dryRun: true only shows what hawk-app.json would change). It never touches prod.
@@ -295,6 +296,23 @@ export function createMcpServer({
         async ({ table, dir }) => result(await run(['data', 'describe', table], { dir })),
     );
 
+    server.registerTool(
+        'data_shape',
+        {
+            title: 'Real data shape',
+            description:
+                'What a query (queries/<name>.sql) or an analytics report (report:<name>) really answers for the developer\'s dev client, as its shape only: each column\'s type, what its values look like (number text, dates, ids, urls), how often it is empty, bucketed sizes and counts. Never the values (client data). Use it before writing code or tests that read the data: handle the empty columns, number-as-text and nulls it shows.',
+            inputSchema: {
+                source: z.string().regex(/^(queries\/[A-Za-z0-9_-]+\.sql|report:[A-Za-z0-9/_-]+)$/).describe('queries/<name>.sql, or report:<name> (a name from analytics_reports).'),
+                params: z.record(z.string(), z.string()).optional().describe('Parameters: the query\'s, or the report\'s request fields (from and to default to the last 30 days).'),
+                dir: dirParam,
+            },
+            annotations: { ...readOnly, openWorldHint: true },
+        },
+        async ({ source, params, dir }) =>
+            result(await run(['data', 'shape', source, ...Object.entries(params ?? {}).flatMap(([k, v]) => ['--param', `${k}=${v}`])], { dir })),
+    );
+
     server.registerTool(
         'logs',
         {
@@ -346,13 +364,38 @@ export function createMcpServer({
             inputSchema: {
                 days: z.number().int().min(1).max(400).optional().describe('Days back; default 30.'),
                 screens: z.boolean().optional().describe('The screens (routes, views, named tabs) and actions (marked clicks) used, instead of opens.'),
+                speed: z.boolean().optional().describe('How fast each screen gets its data, per version (slower ones flagged), and the slowest platform calls, instead of opens.'),
                 version: z.number().int().min(1).optional().describe('With screens: one version\'s counts only.'),
                 dir: dirParam,
             },
             annotations: { ...readOnly, openWorldHint: true },
         },
-        async ({ days, screens, version, dir }) =>
-            result(await run(['usage', ...(screens ? ['--screens'] : []), ...(screens && version ? ['--version', String(version)] : []), ...(days ? ['--days', String(days)] : [])], { dir })),
+        async ({ days, screens, speed, version, dir }) =>
+            result(await run(['usage', ...(speed ? ['--speed'] : screens ? ['--screens'] : []), ...((screens || speed) && version ? ['--version', String(version)] : []), ...(days ? ['--days', String(days)] : [])], { dir })),
+    );
+
+    server.registerTool(
+        'recordings',
+        {
+            title: 'Recorded sessions',
+            description:
+                'The app\'s recorded sessions on the dev platform (a Bridgeline user\'s "Record this session" in HawkSearch, kept 7 days): id, who, client, calls, failed calls. The developer replays one in a terminal with `hawk-app dev --replay <id>`; the recording itself (the client\'s data) is never given to the assistant. Bridgeline users only (hawk-app sso).',
+            inputSchema: { dir: dirParam },
+            annotations: { ...readOnly, openWorldHint: true },
+        },
+        async ({ dir }) => result(await run(['recordings'], { dir })),
+    );
+
+    server.registerTool(
+        'problems',
+        {
+            title: 'Reported problems',
+            description:
+                'The problems users reported in the app ("Report a problem" in HawkSearch, kept 30 days): id, when, client, version, page, and whether a picture, the page context or a recording came with it. Not what the user wrote, the picture or the context (client data): the developer reads one in a terminal with `hawk-app problems show <id>` and replays a recording with `hawk-app dev --replay <id>`. Bridgeline users only (hawk-app sso).',
+            inputSchema: { dir: dirParam },
+            annotations: { ...readOnly, openWorldHint: true },
+        },
+        async ({ dir }) => result(await run(['problems'], { dir })),
     );
 
     server.registerTool(

package/src/platform.mjs

@@ -144,6 +144,16 @@ export function platformClient({ url = process.env.HAWK_APPS_PLATFORM_URL, key =
         appUsage: (slug, days) => call('GET', `/publish/apps/${encodeURIComponent(slug)}/usage?days=${days}`),
         /** Screens and actions used: { days, versions, screens: [{ name, count, staffCount, clients, versions: [{ version, count }] }], actions }. */
         appScreens: (slug, days) => call('GET', `/publish/apps/${encodeURIComponent(slug)}/usage/screens?days=${days}`),
+        /** How fast screens are: { days, versions, metrics: [{ screen, metric, route, version, count, p50, p90, avgMs }] }. */
+        appSpeed: (slug, days) => call('GET', `/publish/apps/${encodeURIComponent(slug)}/usage/speed?days=${days}`),
+        /** Problem reports (Bridgeline users only): { problems: [{ id, clientId, email, version, title, createdAt, hasPicture, recordingId, … }] }. */
+        problems: (slug) => call('GET', `/publish/apps/${encodeURIComponent(slug)}/problems`),
+        /** One report: { problem, text, pictureUrl (5 minutes), context, replay }. */
+        problem: (slug, id) => call('GET', `/publish/apps/${encodeURIComponent(slug)}/problems/${encodeURIComponent(id)}`),
+        /** Recorded sessions (Bridgeline users only: keys from `hawk-app sso`): { recordings: [{ id, clientId, startedBy, startedAt, calls, … }] }. */
+        recordings: (slug) => call('GET', `/publish/apps/${encodeURIComponent(slug)}/recordings`),
+        /** One recording to replay: { recording, calls } locally, { recording, callUrls } (5-minute links) in AWS. */
+        recording: (slug, id) => call('GET', `/publish/apps/${encodeURIComponent(slug)}/recordings/${encodeURIComponent(id)}`),
         /** One page of a function's logs: { events: [{ timestamp, message }], nextToken }. */
         functionLogs: (slug, name, { since, nextToken } = {}) => {
             const query = new URLSearchParams();

package/src/problems.mjs

@@ -0,0 +1,48 @@
+// `hawk-app problems`: what users reported with "Report a problem" in the host's app bar (platform/docs/problems.md):
+// their words, a picture of the page, what the page showed, the version, and a recording when they agreed to one. It's
+// the client's data: Bridgeline users only (keys from `hawk-app sso`), kept 30 days. Nothing is written to disk.
+
+const when = (iso) => new Date(iso).toISOString().slice(0, 16).replace('T', ' ');
+
+/** `hawk-app problems` (the newest first) or `hawk-app problems show <id>`. */
+export async function problemsCommand({ client, manifest, sub, args = [], log = console.log }) {
+    if (sub === 'show') return show({ client, manifest, id: args[0], log });
+    if (sub) throw new Error(`Unknown problems command "${sub}". Usage: hawk-app problems [show <id>]`);
+    const { problems } = await client.problems(manifest.slug);
+    if (!problems.length) {
+        log(`No problems reported in ${manifest.slug} (reports are kept 30 days).`);
+        log('Users report them with the flag icon in the app\'s bar in HawkSearch.');
+        return 0;
+    }
+    log(`Problems reported in ${manifest.slug} (the client's data: don't share them):`);
+    log('');
+    log('  Id          Reported (UTC)    Client       Version  Page                      With');
+    for (const p of problems) {
+        const page = (p.title ?? '—').slice(0, 24);
+        const extras = [p.hasPicture ? 'picture' : null, p.hasContext ? 'context' : null, p.recordingId ? 'recording' : null].filter(Boolean).join(', ') || '—';
+        log(`  ${p.id.padEnd(10)}  ${when(p.createdAt)}  ${p.clientId.slice(0, 11).padEnd(11)}  ${(p.version ? `v${p.version}` : '—').padEnd(7)}  ${page.padEnd(24)}  ${extras}`);
+    }
+    log('');
+    log(`Read one: hawk-app problems show ${problems[0].id}`);
+    return 0;
+}
+
+async function show({ client, manifest, id, log }) {
+    if (!/^p[a-z0-9]{9}$/.test(String(id ?? ''))) throw new Error('Usage: hawk-app problems show <id> (e.g. pk7m2n9x4q; `hawk-app problems` lists them).');
+    const { problem: p, text, pictureUrl, context, replay } = await client.problem(manifest.slug, id);
+    log(`${p.id}: reported ${when(p.createdAt)} UTC by ${p.email ?? 'a user'}${p.internal ? ' (Bridgeline)' : ''}, client ${p.clientId}${p.version ? `, v${p.version}` : ''}${p.title ? `, on "${p.title}"` : ''}`);
+    log('');
+    for (const line of text.split(/\r?\n/)) log(`  ${line}`);
+    log('');
+    if (pictureUrl?.startsWith('https://')) log(`Picture (the link works for 5 minutes): ${pictureUrl}`);
+    else if (pictureUrl) log('Picture: kept (a local platform: open it from the platform\'s answer).');
+    else log('Picture: none.');
+    if (context) {
+        log('What the page showed (its page context):');
+        for (const line of JSON.stringify(context, null, 2).split('\n')) log(`  ${line}`);
+    }
+    if (replay) log(`Recording: ${replay}`);
+    log('');
+    log('The client\'s data: don\'t share it. Deleted 30 days after it was sent.');
+    return 0;
+}

package/src/replay.mjs

@@ -0,0 +1,176 @@
+// Recorded sessions (platform/docs/recordings.md): a Bridgeline user turned on "Record this session" for the app in
+// HawkSearch, and the platform kept their session's calls with the answers. `hawk-app recordings` lists them;
+// `hawk-app dev --replay <id>` (dev.mjs) serves the app from one, so the page behaves as it did for that client. A
+// recording holds the client's data: it's downloaded into memory only (never written to disk), and only Bridgeline
+// users (keys from `hawk-app sso`) can download it.
+
+const DOWNLOADS_AT_ONCE = 8;
+
+const plural = (n, one, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
+
+const when = (iso) => new Date(iso).toISOString().slice(0, 16).replace('T', ' ');
+
+function size(bytes) {
+    if (bytes < 1024) return `${bytes} B`;
+    if (bytes < 1024 * 1024) return `${Math.round(bytes / 1024)} KB`;
+    return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
+}
+
+function state(r) {
+    if (r.recording) return 'recording';
+    if (r.full) return 'full';
+    return 'done';
+}
+
+/** `hawk-app recordings`: the app's recorded sessions (kept 7 days), the newest first. */
+export async function recordingsCommand({ client, manifest, log = console.log }) {
+    const { recordings } = await client.recordings(manifest.slug);
+    if (!recordings.length) {
+        log(`No recorded sessions of ${manifest.slug} (they're kept 7 days).`);
+        log('A Bridgeline user records one in HawkSearch: open the app as the client, then ⋮ → Record this session.');
+        return 0;
+    }
+    log(`Recorded sessions of ${manifest.slug} (kept 7 days, the client's data: don't share them):`);
+    log('');
+    log('  Id          Started (UTC)     By                    Client       Calls  Failed  Size      State');
+    for (const r of recordings) {
+        const by = r.startedBy?.name || r.startedBy?.email || '—';
+        log(`  ${r.id.padEnd(10)}  ${when(r.startedAt)}  ${by.slice(0, 20).padEnd(20)}  ${r.clientId.slice(0, 11).padEnd(11)}  ${String(r.calls).padStart(5)}  ${String(r.failed).padStart(6)}  ${size(r.bytes).padStart(8)}  ${state(r)}`);
+    }
+    log('');
+    log(`Replay one locally: hawk-app dev --replay ${recordings[0].id}`);
+    return 0;
+}
+
+/**
+ * The recording and its calls, in order. In AWS each call is a 5-minute download link (fetched here, a few at a time);
+ * locally the platform sends the calls themselves. A call that can't be fetched is left out (and said).
+ */
+export async function loadRecording({ client, slug, id, fetchImpl = fetch, log = console.log }) {
+    if (!/^[a-z0-9]{10}$/.test(String(id))) throw new Error('--replay needs a recording id, e.g. --replay r7k2m9xq4p (hawk-app recordings lists them).');
+    const download = await client.recording(slug, id);
+    let calls = download.calls ?? [];
+    if (!download.calls && download.callUrls?.length) {
+        const urls = download.callUrls;
+        const fetched = new Array(urls.length);
+        let next = 0;
+        let missing = 0;
+        const worker = async () => {
+            while (next < urls.length) {
+                const i = next++;
+                try {
+                    const response = await fetchImpl(urls[i]);
+                    if (!response.ok) throw new Error(String(response.status));
+                    fetched[i] = await response.json();
+                } catch {
+                    missing++;
+                }
+            }
+        };
+        await Promise.all(Array.from({ length: Math.min(DOWNLOADS_AT_ONCE, urls.length) }, worker));
+        calls = fetched.filter(Boolean);
+        if (missing) log(`! ${plural(missing, 'call')} of the recording couldn't be downloaded: the replay answers them 501 not_recorded.`);
+    }
+    return { recording: download.recording, calls: calls.sort((a, b) => a.seq - b.seq) };
+}
+
+const TELEMETRY = /^telemetry\//;
+
+/**
+ * Answers a call from the recording: the same method, path (with its query) and body, in the order they were made (the
+ * last answer repeats); else the same method and path; else the same method and route without the query (e.g. other
+ * dates). Null when the session never made it. Telemetry isn't served from here (the replay answers it itself).
+ */
+export function replayer(calls) {
+    const exact = new Map();
+    const byPath = new Map();
+    const byRoute = new Map();
+    const used = new Map();
+    const add = (map, key, call) => {
+        if (!map.has(key)) map.set(key, []);
+        map.get(key).push(call);
+    };
+    for (const call of calls) {
+        if (TELEMETRY.test(call.path)) continue;
+        add(exact, `${call.method} ${call.path} ${normalizeBody(call.requestBody)}`, call);
+        add(byPath, `${call.method} ${call.path}`, call);
+        add(byRoute, `${call.method} ${call.path.split('?')[0]}`, call);
+    }
+    return (method, path, body) => {
+        for (const [map, key, match] of [
+            [exact, `${method} ${path} ${normalizeBody(body)}`, 'exact'],
+            [byPath, `${method} ${path}`, 'path'],
+            [byRoute, `${method} ${path.split('?')[0]}`, 'route'],
+        ]) {
+            const queue = map.get(key);
+            if (!queue) continue;
+            const n = used.get(key) ?? 0;
+            used.set(key, n + 1);
+            return { call: queue[Math.min(n, queue.length - 1)], match };
+        }
+        return null;
+    };
+}
+
+/** JSON bodies compared without their formatting; anything else as it is. */
+function normalizeBody(body) {
+    if (body === undefined || body === null || body === '') return '';
+    try {
+        return JSON.stringify(JSON.parse(body));
+    } catch {
+        return String(body);
+    }
+}
+
+/** The session's context, as far as the calls show it: the view (when every call came from one) and the dates. */
+export function replayContext(calls) {
+    const own = calls.filter((c) => !TELEMETRY.test(c.path));
+    const views = new Set(own.map((c) => c.view ?? null));
+    const view = views.size === 1 ? [...views][0] : null;
+    let from = null;
+    let to = null;
+    for (const c of own) {
+        const text = `${c.path} ${c.requestBody ?? ''}`;
+        from ??= /\bfrom["=:\s]+"?(\d{4}-\d{2}-\d{2})/.exec(text)?.[1] ?? null;
+        to ??= /\bto["=:\s]+"?(\d{4}-\d{2}-\d{2})/.exec(text)?.[1] ?? null;
+    }
+    return { view, from, to };
+}
+
+/** What the page reported while it was recorded (`telemetry/errors`): the errors, once each. */
+export function recordedErrors(calls) {
+    const seen = new Set();
+    const errors = [];
+    for (const c of calls) {
+        if (c.path !== 'telemetry/errors' || !c.requestBody) continue;
+        let body;
+        try {
+            body = JSON.parse(c.requestBody);
+        } catch {
+            continue;
+        }
+        for (const e of Array.isArray(body?.errors) ? body.errors : []) {
+            const line = `${e.kind === 'rejection' ? 'unhandled rejection' : 'error'}: ${String(e.message ?? '').slice(0, 200)}`;
+            if (!seen.has(line)) {
+                seen.add(line);
+                errors.push(line);
+            }
+        }
+    }
+    return errors;
+}
+
+/**
+ * A stand-in app token for the replay (the replay doesn't check it, and nothing reaches the platform): the recorded
+ * client, site and a Bridgeline user, with the app's scopes, so the bridge and the page work as they did.
+ */
+export function replayToken({ slug, recording, scopes = [], now = Date.now() }) {
+    const encode = (value) => Buffer.from(JSON.stringify(value)).toString('base64url');
+    const exp = Math.floor(now / 1000) + 3600;
+    const payload = {
+        sub: recording.startedBy?.email ? `replay:${recording.startedBy.email}` : 'replay', app: slug, client_id: recording.clientId,
+        ...(recording.engineId ? { engine: recording.engineId } : {}), internal: true, scope: scopes.join(' '), ...(recording.version ? { ver: recording.version } : {}),
+        exp, replay: recording.id,
+    };
+    return { token: `${encode({ alg: 'none', typ: 'JWT' })}.${encode(payload)}.replay`, expiresAt: new Date(exp * 1000).toISOString(), version: recording.version ?? null };
+}

package/src/shape.mjs

@@ -0,0 +1,111 @@
+// The shape of real data, for the AI that writes the app's code: what a query or an analytics report answers for a
+// client, as column names, types, how often each is empty and what its values look like, never the values themselves
+// (they're the client's data and stay out of the assistant's context). Magnitudes and counts come in coarse buckets.
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const DATE = /^\d{4}-\d{2}-\d{2}$/;
+const DATETIME = /^\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}/;
+const NUMBER_TEXT = /^-?\d+(\.\d+)?$/;
+const BOOL_TEXT = /^(true|false)$/i;
+const URL_TEXT = /^https?:\/\//i;
+const EMAIL = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
+/** "none", "1", "2-9", "10-99", "100-999", "1,000+": how many, without the number. */
+export function countBucket(n) {
+    if (n <= 0) return 'none';
+    if (n === 1) return '1';
+    if (n < 10) return '2-9';
+    if (n < 100) return '10-99';
+    if (n < 1000) return '100-999';
+    return '1,000+';
+}
+
+/** "0", "under 1", "1-9", "10-99", ..., "1M+": a number's size, not the number. */
+export function magnitude(n) {
+    const a = Math.abs(n);
+    if (a === 0) return '0';
+    if (a < 1) return 'under 1';
+    if (a >= 1_000_000) return '1M+';
+    const digits = Math.floor(Math.log10(a)) + 1;
+    const low = 10 ** (digits - 1);
+    return `${low === 1 ? 1 : low.toLocaleString('en-US')}-${(10 ** digits - 1).toLocaleString('en-US')}`;
+}
+
+function kindOf(value) {
+    if (value === null || value === undefined || value === '') return 'empty';
+    if (typeof value === 'boolean') return 'boolean';
+    if (typeof value === 'number') return Number.isInteger(value) ? 'integer' : 'decimal';
+    if (Array.isArray(value)) return 'array';
+    if (typeof value === 'object') return 'object';
+    const text = String(value);
+    if (DATE.test(text)) return 'date text';
+    if (DATETIME.test(text)) return 'date-time text';
+    if (NUMBER_TEXT.test(text)) return 'number text';
+    if (BOOL_TEXT.test(text)) return 'boolean text';
+    if (UUID.test(text)) return 'uuid text';
+    if (URL_TEXT.test(text)) return 'url text';
+    if (EMAIL.test(text)) return 'email text';
+    return 'text';
+}
+
+/**
+ * The shape of rows (objects, or arrays with `columns`): per column its declared type (when given), the kinds its values
+ * have, how many are empty, numbers' sizes and signs, texts' lengths, and how many distinct values (bucketed).
+ */
+export function shapeOf(rows, columns = null) {
+    const objects = columns
+        ? rows.map((row) => Object.fromEntries(columns.map((c, i) => [c.name, row[i]])))
+        : rows.filter((row) => row && typeof row === 'object' && !Array.isArray(row));
+    const names = columns ? columns.map((c) => c.name) : [...new Set(objects.flatMap((row) => Object.keys(row)))];
+    const declared = Object.fromEntries((columns ?? []).map((c) => [c.name, c.type]));
+    return {
+        rows: countBucket(objects.length),
+        columns: names.map((name) => {
+            const values = objects.map((row) => row[name]);
+            const kinds = new Map();
+            for (const v of values) kinds.set(kindOf(v), (kinds.get(kindOf(v)) ?? 0) + 1);
+            const empty = kinds.get('empty') ?? 0;
+            kinds.delete('empty');
+            const numbers = values.map((v) => (typeof v === 'number' ? v : typeof v === 'string' && NUMBER_TEXT.test(v) ? Number(v) : null)).filter((v) => v !== null);
+            const texts = values.filter((v) => typeof v === 'string' && v !== '');
+            const shape = {
+                name,
+                ...(declared[name] ? { type: declared[name] } : {}),
+                kinds: [...kinds.entries()].sort((a, b) => b[1] - a[1]).map(([kind]) => kind),
+                empty: objects.length ? `${Math.round((empty / objects.length) * 100)}%` : '—',
+                distinct: countBucket(new Set(values.filter((v) => v !== null && v !== undefined && v !== '').map((v) => JSON.stringify(v))).size),
+            };
+            if (numbers.length) {
+                shape.size = `${magnitude(Math.min(...numbers.map(Math.abs)))} to ${magnitude(Math.max(...numbers.map(Math.abs)))}`;
+                if (numbers.some((n) => n < 0)) shape.negative = true;
+            }
+            if (texts.length && !numbers.length) {
+                const lengths = texts.map((t) => t.length);
+                const [shortest, longest] = [Math.min(...lengths), Math.max(...lengths)];
+                shape.length = `${shortest === longest ? shortest : `${shortest}-${longest}`} characters`;
+            }
+            return shape;
+        }),
+    };
+}
+
+/** The shape as lines for the terminal and the assistant. */
+export function formatShape(source, shape) {
+    const lines = [`${source}: ${shape.rows} row${shape.rows === '1' ? '' : 's'} (counts and sizes are bucketed; no values are shown)`];
+    if (!shape.columns.length) {
+        lines.push('  no columns (an empty answer: try another client, dates or parameters)');
+        return lines;
+    }
+    for (const c of shape.columns) {
+        const parts = [
+            c.type ? `type ${c.type}` : null,
+            c.kinds.length ? c.kinds.join(' | ') : 'always empty',
+            `empty ${c.empty}`,
+            `distinct ${c.distinct}`,
+            c.size ? `size ${c.size}${c.negative ? ', some negative' : ''}` : null,
+            c.length ? c.length : null,
+        ].filter(Boolean);
+        lines.push(`  ${c.name}: ${parts.join(' · ')}`);
+    }
+    return lines;
+}

package/src/telemetry.mjs

@@ -72,6 +72,7 @@ async function explainCommand({ client, manifest, flags, log, write }) {
  */
 export async function usageCommand({ client, manifest, flags = {}, log = console.log }) {
     if (flags.screens) return screensCommand({ client, manifest, flags, log });
+    if (flags.speed) return speedCommand({ client, manifest, flags, log });
     const days = parseDays(flags.days, 30, 400);
     const usage = await client.appUsage(manifest.slug, days);
     log(`${manifest.slug}, the last ${plural(days, 'day')}:`);
@@ -90,6 +91,61 @@ export async function usageCommand({ client, manifest, flags = {}, log = console
     return 0;
 }
 
+const seconds = (ms) => (ms >= 1000 ? `${(ms / 1000).toFixed(1)}s` : `${ms}ms`);
+const SLOWER = 1.2;
+const SLOWER_MS = 200;
+
+/**
+ * `hawk-app usage --speed [--days 14] [--version <n>]`: per screen, the median and 90th percentile of its data time
+ * (and the page's load, slow clicks) in a version (default the newest) beside the version before it, the screens that
+ * got slower flagged; then the slowest platform calls.
+ */
+async function speedCommand({ client, manifest, flags, log }) {
+    const days = parseDays(flags.days, 14, 90);
+    const speed = await client.appSpeed(manifest.slug, days);
+    let version = speed.versions[0];
+    if (flags.version !== undefined) {
+        version = Number(String(flags.version).replace(/^v/i, ''));
+        if (!Number.isInteger(version) || version < 1) throw new Error('--version must be a version number, e.g. --version 4.');
+    }
+    log(`${manifest.slug}, the last ${plural(days, 'day')}:`);
+    if (!speed.metrics.length || !speed.versions.includes(version)) {
+        log(speed.metrics.length ? `  Nothing measured in v${version} (versions measured: ${speed.versions.map((v) => `v${v}`).join(', ')}).` : '  Nothing measured yet.');
+        log('  The bridge measures each screen when clients use the app (not in hawk-app dev).');
+        return 0;
+    }
+    const before = speed.versions.find((v) => v < version);
+    const find = (screen, metric, v, route = null) => speed.metrics.find((m) => m.screen === screen && m.metric === metric && m.version === v && (m.route ?? null) === route);
+    const pair = (m) => (m ? `${seconds(m.p50)} / ${seconds(m.p90)}` : '—');
+    const screens = [...new Set(speed.metrics.filter((m) => m.version === version && m.metric !== 'call').map((m) => m.screen))];
+    // The slowest screens first (by their data's 90th percentile).
+    screens.sort((a, b) => (find(b, 'data', version)?.p90 ?? 0) - (find(a, 'data', version)?.p90 ?? 0));
+    const width = Math.min(36, Math.max(6, ...screens.map((s) => s.length)));
+    log('');
+    log(`  ${'Screen'.padEnd(width)}  ${`Data v${version}`.padEnd(15)} ${before ? `Data v${before}`.padEnd(15) : ''} ${'Load'.padEnd(15)} Slow clicks`);
+    log(`  ${''.padEnd(width)}  ${'median / 90%'.padEnd(15)} ${before ? 'median / 90%'.padEnd(15) : ''} ${'median / 90%'.padEnd(15)}`);
+    let slower = 0;
+    for (const screen of screens) {
+        const data = find(screen, 'data', version);
+        const old = before ? find(screen, 'data', before) : null;
+        const worse = data && old && data.p90 > old.p90 * SLOWER && data.p90 - old.p90 >= SLOWER_MS;
+        if (worse) slower++;
+        const clicks = find(screen, 'interaction', version);
+        const name = screen.length > width ? `${screen.slice(0, width - 1)}…` : screen;
+        log(`  ${name.padEnd(width)}  ${pair(data).padEnd(15)} ${before ? pair(old).padEnd(15) : ''} ${pair(find(screen, 'load', version)).padEnd(15)} ${clicks ? clicks.count : 0}${worse ? '   ! slower' : ''}`);
+    }
+    const calls = speed.metrics.filter((m) => m.version === version && m.metric === 'call').sort((a, b) => b.p90 - a.p90).slice(0, 8);
+    if (calls.length) {
+        log('');
+        log(`  Slowest platform calls in v${version} (90th percentile):`);
+        for (const c of calls) log(`  ${seconds(c.p90).padStart(7)}  ${c.route}  (${c.screen}, ${plural(c.count, 'call')}, median ${seconds(c.p50)})`);
+    }
+    log('');
+    if (slower) log(`${plural(slower, 'screen')} got slower than v${before} (90th percentile up more than 20%).`);
+    log('Data: from a screen showing until its platform calls are done. Times are approximate (bucketed); hawk-app dev isn\'t counted.');
+    return 0;
+}
+
 const MOST = 15;
 const LEAST = 5;
 const VERSION_COLUMNS = 3;

package/templates/next/package.json

@@ -10,8 +10,8 @@
     "app:audit": "npm audit --omit=dev --audit-level=high"
   },
   "dependencies": {
-    "@bridgeline-digital/hawk-app-bridge": "^0.1.0",
-    "@bridgeline-digital/hawk-app-ui": "^0.1.0",
+    "@bridgeline-digital/hawk-app-bridge": "^0.1.1",
+    "@bridgeline-digital/hawk-app-ui": "^0.1.1",
     "next": "^16.4.0",
     "react": "^19.1.0",
     "react-dom": "^19.1.0"

package/templates/next-mui/package.json

@@ -10,8 +10,8 @@
     "app:audit": "npm audit --omit=dev --audit-level=high"
   },
   "dependencies": {
-    "@bridgeline-digital/hawk-app-bridge": "^0.1.0",
-    "@bridgeline-digital/hawk-app-ui": "^0.1.0",
+    "@bridgeline-digital/hawk-app-bridge": "^0.1.1",
+    "@bridgeline-digital/hawk-app-ui": "^0.1.1",
     "@emotion/react": "^11.14.0",
     "@emotion/styled": "^11.14.1",
     "@mui/icons-material": "^9.5.0",

package/templates/preact/package.json

@@ -12,8 +12,8 @@
     "app:audit": "npm audit --omit=dev --audit-level=high"
   },
   "dependencies": {
-    "@bridgeline-digital/hawk-app-bridge": "^0.1.0",
-    "@bridgeline-digital/hawk-app-ui": "^0.1.0",
+    "@bridgeline-digital/hawk-app-bridge": "^0.1.1",
+    "@bridgeline-digital/hawk-app-ui": "^0.1.1",
     "preact": "^11.0.0"
   },
   "devDependencies": {

package/templates/react/package.json

@@ -12,8 +12,8 @@
     "app:audit": "npm audit --omit=dev --audit-level=high"
   },
   "dependencies": {
-    "@bridgeline-digital/hawk-app-bridge": "^0.1.0",
-    "@bridgeline-digital/hawk-app-ui": "^0.1.0",
+    "@bridgeline-digital/hawk-app-bridge": "^0.1.1",
+    "@bridgeline-digital/hawk-app-ui": "^0.1.1",
     "react": "^19.1.0",
     "react-dom": "^19.1.0"
   },