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

package/README.md

@@ -306,14 +306,21 @@ 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
 ```
 
+**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
@@ -739,7 +746,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,19 @@ 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`.
 
+**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 +204,7 @@ 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 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/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 badge with the count (one request for all the page's badges); 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
@@ -1411,9 +1454,10 @@ A `403` without one of these codes means the app lacks the scope for that call.
 
 ## 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 +1468,21 @@ 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.
+
+`createApp({ reportErrors: false, reportOpens: false, reportUsage: false })` turns any of them off.
 
 ## Talk to the host
 

package/docs/ui/README.md

@@ -42,9 +42,15 @@ 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
+  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".
+- **`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 +91,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.20261026194933",
   "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

@@ -65,7 +65,7 @@ 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
 
 Account
   login, whoami, logout   A publisher key (for CI), and which key and platform apply here
@@ -196,6 +196,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
@@ -852,7 +857,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'].includes(name);
             flags[name] = takesValue ? inline ?? argv[++i] : true;
         } else if (command === undefined) {
             command = arg;

package/src/manifest.mjs

@@ -6,7 +6,7 @@ import { validateStore } from './store-listing.mjs';
 export const MANIFEST_FILE = 'hawk-app.json';
 const SLUG = /^[a-z0-9]+(-[a-z0-9]+)*$/;
 const VISIBILITIES = ['allowList', 'all', 'internal', 'store'];
-const SCOPES = ['reports:read', 'hawksearch:read', 'hawksearch:write', 'data:read', 'functions:invoke', 'email:send', 'hawksearch:sysparams:write', 'hawksearch:search', 'ai:invoke', 'lambdas:invoke', 'hawksearch:features:write', 'hawksearch:index', 'hawksearch:index:items', 'hawksearch:index:manage', 'hawksearch:recommendations', 'storage', 'assistant', 'hawkai:read'];
+const SCOPES = ['reports:read', 'hawksearch:read', 'hawksearch:write', 'data:read', 'functions:invoke', 'email:send', 'hawksearch:sysparams:write', 'hawksearch:search', 'ai:invoke', 'lambdas:invoke', 'hawksearch:features:write', 'hawksearch:index', 'hawksearch:index:items', 'hawksearch:index:manage', 'hawksearch:recommendations', 'storage', 'assistant', 'hawkai:read', 'comments'];
 export const SYSPARAMS_SCOPE = 'hawksearch:sysparams:write';
 /** The templates `hawk-app create` offers (the keys of create.mjs's TEMPLATES): `"template"` in hawk-app.json. */
 export const TEMPLATE_NAMES = ['react', 'preact', 'next', 'next-mui', 'vanilla'];
@@ -400,6 +400,7 @@ export function validateManifest(manifest) {
     errors.push(...store.errors);
     warnings.push(...store.warnings);
     warnings.push(...trialWarnings(m));
+    warnings.push(...commentWarnings(m));
 
     const unknownScopes = (m.scopes ?? []).filter((s) => !SCOPES.includes(s));
     if (unknownScopes.length) warnings.push(`These scopes are not available and will not be granted: ${unknownScopes.join(', ')}.`);
@@ -409,6 +410,21 @@ export function validateManifest(manifest) {
     return { errors, warnings };
 }
 
+/** The config key the platform emails new comments to (comments scope): it must be an `emails` key. */
+export const COMMENT_EMAILS_KEY = 'commentEmails';
+
+/** Comments' email: `commentEmails` declared as another type gets nothing; the comments scope without it emails no one. */
+function commentWarnings(m) {
+    const declared = m.config && typeof m.config === 'object' ? m.config[COMMENT_EMAILS_KEY] : undefined;
+    if (declared && declared.type !== 'emails') {
+        return [`config.${COMMENT_EMAILS_KEY} must be of type "emails" for new comments to be emailed to it.`];
+    }
+    if ((m.scopes ?? []).includes('comments') && !declared) {
+        return [`The app has comments but no config.${COMMENT_EMAILS_KEY} ({ "type": "emails" }): new comments are emailed to no one. Declare it, then \`hawk-app config set ${COMMENT_EMAILS_KEY} team@example.com\`.`];
+    }
+    return [];
+}
+
 /**
  * "lambdas": Lambdas outside Hawk Apps the app calls (scope lambdas:invoke). A list of up to 10 unique Lambda function
  * names; the list needs the scope and the scope needs a non-empty list. Whether a platform allows a name is only known

package/src/mcp.mjs

@@ -341,11 +341,18 @@ export function createMcpServer({
         'usage',
         {
             title: 'App usage on dev',
-            description: 'Opens of the app and of its views, distinct users and clients per day on the dev platform (Bridgeline staff counted apart).',
-            inputSchema: { days: z.number().int().min(1).max(400).optional().describe('Days back; default 30.'), dir: dirParam },
+            description:
+                'Opens of the app and of its views, distinct users and clients per day on the dev platform (Bridgeline staff counted apart). With screens: true, the screens and actions people use instead, the most and least used, per version: what to improve or remove.',
+            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.'),
+                version: z.number().int().min(1).optional().describe('With screens: one version\'s counts only.'),
+                dir: dirParam,
+            },
             annotations: { ...readOnly, openWorldHint: true },
         },
-        async ({ days, dir }) => result(await run(['usage', ...(days ? ['--days', String(days)] : [])], { dir })),
+        async ({ days, screens, version, dir }) =>
+            result(await run(['usage', ...(screens ? ['--screens'] : []), ...(screens && version ? ['--version', String(version)] : []), ...(days ? ['--days', String(days)] : [])], { dir })),
     );
 
     server.registerTool(

package/src/platform.mjs

@@ -142,6 +142,8 @@ export function platformClient({ url = process.env.HAWK_APPS_PLATFORM_URL, key =
         },
         /** The app's opens over `days`: { opens, viewOpens, staffOpens, users, clients, perDay, perClient }. */
         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}`),
         /** One page of a function's logs: { events: [{ timestamp, message }], nextToken }. */
         functionLogs: (slug, name, { since, nextToken } = {}) => {
             const query = new URLSearchParams();

package/src/scope-check.mjs

@@ -28,6 +28,7 @@ const RULES = [
     { scope: 'hawksearch:index:manage', pattern: /\.hawksearch\.index\.(create|setCurrent|deleteIndex|rebuildAll)\s*\(/ },
     { scope: 'hawksearch:recommendations', pattern: /\.hawksearch\.recommendations\s*\(/ },
     { scope: 'storage', pattern: /\.storage\.(get|put|delete|list|batch|usage)\s*\(|\.storage\.files\.\w+\s*\(/ },
+    { scope: 'comments', pattern: /\.comments\.(list|add|edit|delete|counts)\s*\(|<HawkComments\b/ },
     { scope: 'lambdas:invoke', pattern: /\.lambdas\.invoke\s*\(/ },
     { scope: 'ai:invoke', pattern: /\.ai\.(generate|stream|info)\s*\(/ },
     { scope: 'assistant', pattern: /\.assistant\.(ask|setContext)\s*\(/ },

package/src/telemetry.mjs

@@ -1,5 +1,5 @@
 // `hawk-app errors` and `hawk-app usage`: what the bridge reports from the app's pages (uncaught errors and rejections,
-// and one open per page load), as the platform groups them. Read-only. `hawk-app errors --explain <id>` adds the
+// one open per page load, the screens and actions used), as the platform groups them. Read-only. `hawk-app errors --explain <id>` adds the
 // error's brief (error-brief.mjs) and Claude's likely cause and patch.
 import { errorBrief, errorId, findGroup } from './error-brief.mjs';
 
@@ -65,8 +65,13 @@ async function explainCommand({ client, manifest, flags, log, write }) {
     return 0;
 }
 
-/** `hawk-app usage [--days 30]`: opens and users per day and client. */
+/**
+ * `hawk-app usage [--days 30]`: opens and users per day and client.
+ * `hawk-app usage --screens [--days 30] [--version <n>]`: the screens and actions people use, the most used first and
+ * the least used last, with the newest versions side by side (or only one version's).
+ */
 export async function usageCommand({ client, manifest, flags = {}, log = console.log }) {
+    if (flags.screens) return screensCommand({ 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')}:`);
@@ -80,5 +85,64 @@ export async function usageCommand({ client, manifest, flags = {}, log = console
         }
         if (usage.perClient.length > 20) log(`  … and ${usage.perClient.length - 20} more`);
     }
+    log('');
+    log('Which screens and actions: hawk-app usage --screens');
+    return 0;
+}
+
+const MOST = 15;
+const LEAST = 5;
+const VERSION_COLUMNS = 3;
+
+async function screensCommand({ client, manifest, flags, log }) {
+    const days = parseDays(flags.days, 30, 400);
+    let only = null;
+    if (flags.version !== undefined) {
+        only = Number(String(flags.version).replace(/^v/i, ''));
+        if (!Number.isInteger(only) || only < 1) throw new Error('--version must be a version number, e.g. --version 4.');
+    }
+    const usage = await client.appScreens(manifest.slug, days);
+    const countIn = (item, version) => item.versions.find((v) => v.version === version)?.count ?? 0;
+    // One version: its counts only (staff and clients are over all versions, so they're left out).
+    const pick = (items) =>
+        only === null
+            ? items
+            : items
+                  .map((item) => ({ ...item, count: countIn(item, only) }))
+                  .filter((item) => item.count > 0)
+                  .sort((a, b) => b.count - a.count || a.name.localeCompare(b.name));
+    const screens = pick(usage.screens);
+    const actions = pick(usage.actions);
+    const columns = only === null ? usage.versions.slice(0, VERSION_COLUMNS) : [];
+
+    log(`${manifest.slug}, the last ${plural(days, 'day')}${only === null ? '' : `, v${only}`}:`);
+    if (!screens.length && !actions.length) {
+        log(only !== null && usage.versions.length ? `  Nothing counted in v${only} (versions used: ${usage.versions.map((v) => `v${v}`).join(', ')}).` : '  Nothing counted yet.');
+        log('  Screens are counted by the bridge (routes, views, app.usage.screen); actions are clicks on [data-hawk-usage] or app.usage.action.');
+        return 0;
+    }
+    const table = (title, items) => {
+        if (!items.length) return;
+        const width = Math.min(40, Math.max(title.length, ...items.map((i) => i.name.length)));
+        const header = only === null ? ['Uses', 'Staff', 'Clients', ...columns.map((v) => `v${v}`)] : ['Uses'];
+        log('');
+        log(`  ${title.padEnd(width)}  ${header.map((h) => h.padStart(7)).join(' ')}`);
+        const row = (i) => {
+            const name = i.name.length > width ? `${i.name.slice(0, width - 1)}…` : i.name;
+            const cells = only === null ? [i.count, i.staffCount, i.clients, ...columns.map((v) => countIn(i, v))] : [i.count];
+            log(`  ${name.padEnd(width)}  ${cells.map((c) => String(c).padStart(7)).join(' ')}`);
+        };
+        if (items.length <= MOST + LEAST) {
+            items.forEach(row);
+            return;
+        }
+        items.slice(0, MOST).forEach(row);
+        log(`  ${'…'.padEnd(width)}  ${items.length - MOST - LEAST} more, then the least used:`);
+        items.slice(-LEAST).forEach(row);
+    };
+    table('Screens', screens);
+    table('Actions', actions);
+    log('');
+    log(`Uses are by your clients' users; Bridgeline staff are counted apart.${columns.length < usage.versions.length && only === null ? ' Older versions: --version <n>.' : ''}`);
     return 0;
 }