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

package/README.md

@@ -306,14 +306,22 @@ HawkSearch). The full picture, with diagrams: docs/versions-and-aliases.md in th
 
 ## Errors and usage (`hawk-app errors`, `hawk-app usage`)
 
-The bridge reports the app's page errors and one open per page load (platform/docs/telemetry.md):
+The bridge reports the app's page errors, one open per page load, and the screens and actions used
+(platform/docs/telemetry.md):
 
 ```bash
 npx hawk-app errors              # the last 7 days (--days 1-30): grouped, the most frequent first, with versions, clients and an [id]
 npx hawk-app errors --explain 3fa1c2d9   # one error's brief, then Claude's likely cause and patch (--no-ai: the brief only)
 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`
+(the UI kit's `useScreen('Logs')`, for a tab); actions are clicks on `data-hawk-usage="Export CSV"` elements and
+`app.usage.action`. Compare versions to see whether a change is used, and the least used to see what to simplify.
+
 **Errors that come with a fix.** `--explain <id>` writes the error's **brief** and asks Claude for the cause:
 
 - **The stack, mapped to your source:** each of the app's frames as `src/app/page.tsx:42:17`, with the code around it
@@ -333,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
@@ -562,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.
 
@@ -739,7 +790,7 @@ attribute (`"data": "hawk-keyword"`), used as is when the page has it, with its
 (the bridge README's **Actions**, with every target setting). `hawk-app validate` checks the targets (paths and
 patterns are regular expressions, params the view declares); `hawk-app status` lists the actions. `hawk-app dev` has an
 **Action** menu: pick an action, type a value, and the view opens in a dialog as in HawkSearch. For complete recipes
-(actions, schedules, events, a client API endpoint and their tests), see [docs/examples.md](../../docs/examples.md).
+(actions, schedules, events, a client API endpoint and their tests), see the [Recipes](../../docs/examples.md).
 
 ### Testing functions (`hawk-app test`)
 

package/agents/AGENTS.md

@@ -146,10 +146,26 @@ With the UI kit: `usePageContext(rows ? { page: '<the page>', dateRange, totals,
 `app.assistant.setContext({ ... })` whenever the data or filters change. Plain names and numbers of what's on screen,
 at most 50 KB; summarize long tables. `hawk-app validate` warns when an app never sets one.
 
+**Comments** (scope `comments`): `<HawkComments target="keyword:…" label="…" />` from the UI kit on what people discuss
+(a row, a widget, `page:summary`); targets are stable ids, never personal data. Declare `config.commentEmails`
+(`{ "type": "emails" }`) so new comments are emailed (`hawk-app config set commentEmails …`, a person or a Slack
+channel's email).
+
 **Export as PDF** (only on pages worth keeping: a report, a summary): `usePdfExport({ fileName })` from the UI kit
 (`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).
+
 **Actions** (`actions` in `hawk-app.json`) add a button to HawkSearch's own pages that opens a view in a dialog:
 `{ "<name>": { "label": "Fix with …", "view": "fix", "targets": { "hawksearch": [{ "path": "<regex on the page path>",
 "selector": "<CSS: each thing>", "anchor"?: "<CSS inside it>", "position"?: "after", "params": { "keyword": { "data"?,
@@ -195,6 +211,11 @@ npx hawk-app config list         # config values (config set <key> <value> [--cl
 npx hawk-app errors              # errors in the app's pages (deployed versions), the most frequent first, with [id]s
 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

@@ -150,13 +150,15 @@ buttons appear in HawkSearch: nothing changes in HawkSearch for it.
           "params": { "keyword": { "selector": "td.table__cell:first-child" } }            // its text
         },
         {
+          // AI Advisor: only the insights that suggest a synonym or a redirect (HawkSearch marks each insight with
+          // data-hawk-action, data-hawk-category, data-hawk-keyword and data-hawk-insight-id).
           "path": "/admin/recommendations/?$",
-          "selector": ".recommendations-list__item:not(.recommendations-list__item--empty)",
+          "selector": ".recommendations-list__item[data-hawk-action=\"Synonym\"], .recommendations-list__item[data-hawk-action=\"Redirect\"]",
           "anchor": ".recommendations-list__text",
           "position": "after",
           "params": {
-            "keyword": { "selector": ".recommendations-list__text", "pattern": "[\"“”]([^\"“”]{1,100})[\"“”]" },
-            "category": { "selector": ".recommendations-list__category-tag" }
+            "keyword": { "data": "hawk-keyword" },        // the insight's exact term
+            "category": { "data": "hawk-category" }
           }
         }
       ]
@@ -177,7 +179,8 @@ buttons appear in HawkSearch: nothing changes in HawkSearch for it.
 - **Pick stable selectors:** ids, `data-*` attributes and element names over styling classes. HawkSearch doesn't know
   about your selectors: when it changes its markup, your buttons stop appearing until you deploy new targets.
 - **Approval:** `actions` is a setting that always needs an approver (never auto-approve): reviewers see each target and
-  what it reads from the page. Read only what the view needs. Settings and the Apps pages never show actions.
+  what it reads from the page. Before approval, Bridgeline staff already get the new actions on a draft app (the version
+  they open), so they can try the buttons in HawkSearch first; clients only ever get approved ones. Read only what the view needs. Settings and the Apps pages never show actions.
 
 ```tsx
 // src/app/views/fix/page.tsx
@@ -1209,6 +1212,46 @@ await app.storage.files.delete('exports/prices.csv');
 
 See the platform's docs/storage.md.
 
+## Comments: `comments`
+
+Let the people using the app talk about what it shows, right where it is: a comment thread on a search term, a report
+row, a widget or the whole page. Everyone at the client who uses the app sees the comments, and so do Bridgeline staff.
+They're kept until deleted, and each new one is emailed to whoever you set.
+
+```json
+{
+    "scopes": ["comments"],
+    "config": { "commentEmails": { "type": "emails", "label": "Who gets new comments" } }
+}
+```
+
+```tsx
+// 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" />
+```
+
+```ts
+// Or the bridge itself:
+const thread = await app.comments.list('keyword:rain-boots');   // [{ id, text, author, createdAt, mine, canDelete, … }], oldest first
+await app.comments.add('keyword:rain-boots', 'Catalog gap or synonym?', { label: 'rain boots' });
+await app.comments.edit('keyword:rain-boots', id, 'Synonym: we sell rain boots.');   // the author only
+await app.comments.delete('keyword:rain-boots', id);                                 // the author, or Bridgeline staff
+const counts = await app.comments.counts(['keyword:rain-boots', 'keyword:wellies']); // { 'keyword:rain-boots': 2 }
+```
+
+- **Targets** are yours: stable ids of 1-200 characters (letters, digits, `. _ - : / # @`), never personal data. The
+  same target on two pages is the same thread. `label` names it in words for the drawer and the email.
+- **Email:** set `commentEmails` (declared as `emails` in `config`) to a person, a team list or a Slack channel's
+  email address (Slack: the channel's Integrations › Send emails to this channel), for every client or one:
+  `npx hawk-app config set commentEmails merch@agency.example [--client e3141]`. No deploy needed. Each new comment is
+  sent there from the platform, with the app's name, the target and the client; replies go to the author. Without the
+  key, nothing is sent. `hawk-app validate` warns about it.
+- **Authors** are shown by the email the host sends; Bridgeline staff are marked. Text only, up to 4,000 characters;
+  30 new or edited comments a minute per app and client (429 `too_many_requests`).
+- Errors (`HawkApiError`): 400 `invalid_target` / `invalid_comment`, 403 `scope_missing` / `not_author`, 404
+  `comment_not_found`. See the platform's docs/comments.md.
+
 ## External Lambdas: `lambdas:invoke`
 
 Call a Lambda written outside Hawk Apps (for example HawkAnalytics' client setup) from the app or a function. Declare
@@ -1409,11 +1452,31 @@ 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) and the page's uncaught
-errors and unhandled rejections: at most 10 per page load, each once, without query strings. The app's team sees them
-with `hawk-app errors` and `hawk-app usage`, and Bridgeline in the portal (platform/docs/telemetry.md).
+`createApp` reports, on its own, one open per page load (the full app or the view showing), the screens and actions
+used, and the page's uncaught errors and unhandled rejections: at most 10 per page load, each once, without query
+strings. The app's team sees them with `hawk-app errors` and `hawk-app usage`, and Bridgeline in the portal
+(platform/docs/telemetry.md).
 
 ```ts
 try {
@@ -1424,7 +1487,26 @@ try {
 }
 ```
 
-`createApp({ reportErrors: false, reportOpens: false })` turns either off.
+**What people use.** The bridge also counts the **screens** people open (each route of the full app, as `/orders/:id`
+with ids left out, or the view showing) and the **actions** they take: clicks on elements marked `data-hawk-usage`. Only
+these names are sent, batched every 15 s, never what users type or see. Count what the routes don't show yourself:
+
+```tsx
+<Button data-hawk-usage="Export CSV" onClick={exportCsv}>Export</Button>   // counted on each click
+
+app.usage.screen('Logs');       // a tab or step within one route (the UI kit: useScreen('Logs') in the tab)
+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.
+
+**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
 
@@ -1522,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,9 +42,19 @@ 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 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".
 - **`usePageContext(object | null)`** says what the page shows, for the host's **Explain this page** button (and its
   assistant): `usePageContext(rows ? { page: 'Zero-result searches', dateRange, top10 } : null)`. Plain names and
   numbers, at most 50 KB; sent shortly after it changes, cleared when the component unmounts. See the bridge guide's
@@ -85,9 +95,8 @@ const f = useFormat(); // in the host's locale
 
 The host shows the frame over the whole page while a dialog or drawer is open, so they're always fully visible.
 
-Every component, in light and dark, is in the [UI kit gallery](GALLERY.md) on the developer site (the gallery app,
-[examples/ui-kit](../../examples/ui-kit), as a preview; run it with `npm run dev` there and open it through a host to
-see it in a real one). `<HawkAppProvider preview={{ mode: 'dark' }}>` renders without a host, with sample context
+Every component, in light and dark, is in the [UI kit gallery](GALLERY.md) on the developer site (the repository's
+gallery app, `examples/ui-kit`, rendered as a preview). `<HawkAppProvider preview={{ mode: 'dark' }}>` renders without a host, with sample context
 (`previewContext()`), for galleries, docs and screenshots. New apps get the kit from the CLI's `next-mui` template
 (`hawk-app create my-app --template next-mui`); an existing next-mui app gets it with `hawk-app upgrade`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bridgeline-digital/hawk-app-cli",
-  "version": "0.1.1-dev.20261026155507",
+  "version": "0.1.1-dev.20261026224639",
   "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/schema/hawk-app.schema.json

@@ -120,7 +120,8 @@
           "hawksearch:recommendations",
           "storage",
           "assistant",
-          "hawkai:read"
+          "hawkai:read",
+          "comments"
         ]
       },
       "uniqueItems": true

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
@@ -65,7 +67,9 @@ Data and functions
   secrets, logs           Function secrets and logs
 
 Monitor
-  errors, usage           The app's page errors, and its opens, users and clients per day
+  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
@@ -196,6 +214,11 @@ Monitor:
                                                     cause and patch (--no-ai: the brief only)
   hawk-app usage [--days 30]                        Opens of the app and its views, users and clients per day (up to
                                                     400 days; Bridgeline staff counted apart)
+  hawk-app usage --screens [--days 30] [--version <n>]
+                                                    The screens (routes, views, app.usage.screen) and actions
+                                                    ([data-hawk-usage], app.usage.action) people use: the most used
+                                                    first, the least used last, the newest versions side by side
+                                                    (--version: one version's counts)
 
 Custom data (app queries, scope data:read):
   hawk-app data tables [--app <slug>]               List the tables queries can use (--app: is the app
@@ -204,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)
@@ -600,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);
@@ -624,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);
@@ -660,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();
@@ -852,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'].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) {