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

package/README.md

@@ -69,7 +69,8 @@ separately, see [Clients](#clients)):
                                        // client can request it from the store (needs "store", below) (clients: see "Clients")
   "icon": "icon.svg",                  // the app's icon: an .svg (drawn in the host's color) or a square .png, next to this file
   "scopes": ["reports:read"]           // reports:read = analytics; hawksearch:read = dashboard API (read) and preview tools;
-                                       // hawksearch:write = create/update/delete synonyms, redirects, banners, …
+                                       // hawksearch:write = create/update/delete synonyms, redirects, banners, …,
+                                       //   and pin items (hawksearch.pinning)
                                        // through the dashboard API (see the bridge's "Writing to HawkSearch");
                                        // data:read = your own SQL queries in queries/ (see "Custom data");
                                        // functions:invoke = server-side functions (see "Functions");
@@ -176,8 +177,8 @@ npx hawk-app dev --client e3141 --engine 3141
 
 The first time, it asks for part of a client's name and lets you pick the client, then saves it in `.env.local` as
 `HAWK_APPS_DEV_CLIENT` (`--client <id>` uses another). A new app is registered on the platform the first time (not
-released: only Bridgeline staff see it). Queries and functions always run from the **deployed** version, even here:
-deploy after changing them.
+released: only Bridgeline staff see it). Queries and functions called from the app run from the **deployed** version,
+even here: deploy after changing them (or test them locally with `hawk-app test`).
 
 Starts your app (`npm run dev`) and a local stand-in for HawkSearch at `http://localhost:3200`, which embeds the app
 the way HawkSearch does (the bridge's own `<hawk-app-frame>`). The app gets **real tokens and real data**: the CLI asks
@@ -195,7 +196,19 @@ CORS setup, on dev or prod; so does the AI stream (`app.ai.stream`), which the p
   `https://dev.hawksearch.net`; `HAWKSEARCH_GROUP_KEY=true` for a group key): the platform seals it into the token. It is
   never written anywhere else.
 - Queries and functions run against your **current deployed version** (deploy first after changing them); the UI is your
-  local code. Every dev token is audit-logged with your publisher key.
+  local code. Every dev token is audit-logged with your publisher key. To run functions from your local code, use
+  `hawk-app test` ([Testing functions](#testing-functions-hawk-app-test)).
+- **Actions:** when `hawk-app.json` has `actions`, the toolbar's **Action** menu opens an action's view in a dialog as
+  HawkSearch will (type the value its targets would read from the page); `app.action.done()` closes it.
+- **Export as PDF:** the toolbar has HawkSearch's PDF icon. It shows while the page allows it (`app.setPdfExport` /
+  `usePdfExport`; the events list logs it), and a click downloads the page as a PDF.
+- **Explain this page:** the toolbar has HawkSearch's **Explain this page** button. It shows once the page says what
+  it shows (`app.assistant.setContext` / `usePageContext`; the events list logs each one), and explains it with the
+  platform's AI for the client.
+- **Client API:** `http://localhost:3200/v1/clients/<id>/apps/<slug>/api/<name>` (with `X-HawkSearch-ApiKey`) runs the
+  endpoint's function from your **local** `functions/` (bundled on each call), with a real token for the client whose
+  HawkSearch connection is the key you send. The platform's own checks (the key's engine, API access, the limit) are
+  skipped; secrets and config are empty.
 
 ## Deploy
 
@@ -217,7 +230,7 @@ npx hawk-app deploy --dry-run     # what hawk-app.json would change, without a v
 | Command | What it does |
 |---|---|
 | `init` | Creates `hawk-app.json` (never overwrites an existing one) and adds [AGENTS.md](#ai-coding-assistants-agentsmd). |
-| `validate [--build [<folder>]]` | Checks `hawk-app.json` locally, `queries/` and `functions/` if the app has them, and the project: the bridge is used and current, and there's a build script (or `--no-build` deploys). `--build` also builds the app with a stand-in base path (`/<slug>/v0`) and fails on absolute URLs outside it; the folder comes from the `app:deploy` script unless given. |
+| `validate [--build [<folder>]]` | Checks `hawk-app.json` locally, `queries/` and `functions/` if the app has them, and the project: the bridge is used and current, the app says what its page shows ("Explain this page"), and there's a build script (or `--no-build` deploys). `--build` also builds the app with a stand-in base path (`/<slug>/v0`) and fails on absolute URLs outside it; the folder comes from the `app:deploy` script unless given. |
 | `deploy [<folder>] [--no-build] [--no-audit] [--alias <name>] [--dry-run]` | Sends hawk-app.json first (its scopes and settings go with every deploy), then reserves the next version number, runs `npm run build` with `HAWK_APP_BASE_PATH=/<slug>/v<n>` (when package.json has a `build` script, unless `--no-build`), then uploads every file in the build folder (the template's, `dist`, `out` or `public`, unless given) to `/<slug>/v<n>/` on the apps CDN, plus `queries/` and the bundled `functions` (if any) to the platform's private storage, and deploys the functions. Runs `npm audit` of the production dependencies first, asks before deploying with high or critical findings, and reports the counts to reviewers (see [Dependency check](#dependency-check); `--no-audit` skips it). Warns when the HTML loads absolute URLs outside `/<slug>/v<n>/`, which wouldn't load, and when the code calls a bridge feature whose scope `hawk-app.json` lacks (e.g. `app.ai.generate` without `ai:invoke`; `validate` and `doctor` check it too). Says whether the version is a draft (staff only until it's approved) or auto-approved, and when it cleared an approval request. `--alias staging` points the alias at the new version (see [Versions and aliases](#versions-and-aliases)). `--dry-run` only shows what hawk-app.json would change. |
 | `register` | Sends `hawk-app.json` without a new version (for scripts; `deploy` and `dev` already send it). It never releases anything and never changes the app's clients. On a released app, changes wait for review. |
 | `versions` | Every version with its status (draft, waiting, approved, rejected) and the aliases on it. |
@@ -293,13 +306,40 @@ 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 and clients
+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
+  and the line that threw marked `>`. The maps are the version's own, so the code is what ran, not what's in your
+  checkout now. Library frames are listed on one line each.
+- **The platform calls that failed** in the same versions and days (route, status, code, detail), often the reason
+  (e.g. a report that answered 502 left `rows` undefined).
+- **What changed since the last version without it:** a diff of the files in the stack between that version and the
+  one that threw.
+- **Then Claude** (the platform's, on its account, no scope or key needed) answers with the likely cause, a patch as a
+  unified diff, and how to check it. Check the patch before you apply it; nothing is changed for you.
+- **In Claude Code,** the MCP server's `error_brief` tool gives it the same brief, so it can fix the code in your repo
+  directly (ask: "fix error 3fa1c2d9").
+
+It needs the version's **source maps**: the templates build them (`productionBrowserSourceMaps` in next.config.ts,
+`build.sourcemap: 'hidden'` in vite.config.ts), and `hawk-app deploy` sends every `.map` file of the build to the
+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.
+
 ## 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
@@ -388,6 +428,7 @@ Protocol](https://modelcontextprotocol.io)), so they can look things up and chec
 | `doctor` | `hawk-app doctor`: what's wrong with the setup, and how to fix it. |
 | `versions`, `why` | Every version with its status and aliases; what a client sees of the app, and why. |
 | `errors`, `usage` | The app's page errors; its opens, users and clients per day. |
+| `error_brief` | One error's brief (`errors --explain <id> --no-ai`): the stack mapped to the source with the code, the failed platform calls, what changed since the last version without it. For fixing it in the repo. |
 | `ui_components` | The UI kit's components for the app's template (next-mui: the provider, components and theme; the others: the stylesheet classes and elements), or what's said about one, from the kit's README, with a link to the live [gallery](https://developers.hawksearchapps.com/reference/ui-kit-gallery/). |
 | `analytics_reports` | The analytics API's reports for `app.analytics.report()`, with one report's columns, filters and an example call, read from the developer portal's dev spec (public; no client data). |
 | `hawksearch_api` | HawkSearch's API reference (developerdocs.hawksearch.com): an operation's parameters, request and response fields, the bridge call (`app.dashboard.*`, `app.hawksearch.*`) and its scope, or why apps can't call it (public; no client data). |
@@ -643,6 +684,107 @@ with 6 fields (`minutes hours day-of-month month day-of-week year`, no `cron( )`
 scope. `schedules` is a setting sent with each deploy: on a released app a change waits for review like scopes,
 and `hawk-app status` lists the registered schedules.
 
+`events` run a job function when something happens for a client, so the app doesn't need a schedule to notice it.
+`client.added` runs when a client's users get the app (a store request approved, the client added to the app's list,
+or the app released to the clients on its list), `config.changed` when a config value changes for a client (its own,
+or a global one), `version.released` when another version reaches a client that had the app, and, read from HawkSearch
+once a minute, `hawksearch.changed` (a dashboard change; `"sections": ["synonym", …]` to follow only some) and
+`index.rebuilt` (a rebuild finished):
+
+```jsonc
+"functions": { "welcome": { "job": true }, "migrate": { "job": true } },
+"events": { "client.added": { "function": "welcome" }, "version.released": { "function": "migrate" } }
+```
+
+The run is a job for that client, without a site or HawkSearch connection, except the HawkSearch events, which get the
+engine and the client's connection (the bridge README's **Events** section has the details). `hawk-app validate` checks the event names, that each `function` is a job function of the same
+`hawk-app.json`, and the `functions:invoke` scope; `events` is reviewed like scopes, and `hawk-app status` lists them.
+
+`api` turns functions into endpoints the client's own systems call (a developer's script, a job on their side) with
+their engine's HawkSearch site API key, once Bridgeline turns API access on for the client in HawkSearch (the app's
+kebab menu › API access, which shows each endpoint's URL and a curl):
+
+```jsonc
+"functions": { "design-html": {} },
+"api": { "design-html": { "function": "design-html", "method": "GET", "description": "A saved design's email HTML" } }
+```
+
+The function isn't a job (the caller waits); its input is the query string (GET) or the JSON body (POST), and
+`apiResponse()` from the bridge's `/server` entry answers HTML or any other type (the bridge README's **Client API**
+section). `hawk-app validate` checks the names (at most 10), that each `function` is a function of the same
+`hawk-app.json` without `"job": true`, the method (GET or POST) and the `functions:invoke` scope; `api` is reviewed like
+scopes, and `hawk-app status` lists the endpoints.
+
+### Actions (start the app from HawkSearch's screens)
+
+`actions` put an app where the work is: a button in HawkSearch's own pages that opens one of the app's views in a
+dialog, with values read from the page as the view's params. The app says where with **targets**: the page (a regular
+expression on its path), a CSS selector for the things (one button per match), where the button goes, and how each
+param is read:
+
+```jsonc
+"views": { "fix": { "path": "views/fix", "title": "Fix a search", "params": ["keyword"] } },
+"actions": {
+  "fix-keyword": {
+    "label": "Fix with Zero Results Fixer",
+    "view": "fix",
+    "targets": { "hawksearch": [{
+      "path": "/admin/advanced-analytics/top-queries/?$",
+      "selector": "bl-table tbody.table__body > tr.table__row",
+      "anchor": "td.table__cell:first-child",
+      "params": { "keyword": { "selector": "td.table__cell:first-child" } }
+    }] }
+  }
+}
+```
+
+Deploy; once the version is approved, the buttons appear in HawkSearch with no change there. `actions` always needs an
+approver (never auto-approve): reviewers see each target and what it reads. Pick stable selectors (ids, `data-*`
+attributes, element names): if HawkSearch changes its markup, deploy new targets. A param can also name a `data-*`
+attribute (`"data": "hawk-keyword"`), used as is when the page has it, with its selector and pattern as the fallback. The view reads
+`app.context.view.params` and `app.context.view.action`, and calls `app.action.done({ changed })` to close the dialog
+(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 the [Recipes](../../docs/examples.md).
+
+### Testing functions (`hawk-app test`)
+
+Functions can be tested without deploying. Put tests next to them as `functions/<name>.test.ts` (Node's own
+`node:test` and `node:assert`: nothing to install) and run `npx hawk-app test` (or `npm run app:test`):
+
+```ts
+// functions/design-html.test.ts
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { runFunction } from '@bridgeline-digital/hawk-app-cli/testing';
+
+test('answers the design as JSON', async () => {
+    const run = await runFunction('design-html', {
+        trigger: 'api',                                     // call (default), job, schedule, event or api
+        input: { designId: 'spring' },
+        storage: { 'design#spring': design },               // storage in memory
+        answers: [{ method: 'POST', path: 'hawksearch/recommendations', body: recommendations }],
+    });
+    assert.equal(run.error, null, run.logs);
+    assert.equal(run.result.subject, 'New for spring');
+});
+```
+
+- `runFunction(name, options)` bundles the function exactly as `hawk-app deploy` does and runs it in its own Node
+  process with the event the platform sends (`input`, `trigger`, `client`, `engine`, `user`, `secrets`,
+  `clientSecrets`, `config`), with its `timeoutSeconds`. It answers `{ result, error, calls, progress, storage, logs }`:
+  what it returned or threw, every platform call it made (with its body and what answered it), `ctx.job.progress`
+  reports, the storage afterwards, and its console output.
+- Its platform calls go to a fake platform: `answers` first, then storage and config in memory (when the test gives
+  `storage` or `config`), then a **recording** (`recording: 'spring'` reads `functions/__recordings__/spring.json`).
+  A call nothing answers fails with 501 `not_recorded`.
+- `hawk-app test --record` makes the recordings: calls nothing else answers go to the platform once, as the test's
+  `client` (and `engine`; `HAWKSEARCH_API_KEY` for HawkSearch), and are saved. Recordings hold real answers: review them
+  before committing. They are never deployed with the function's source.
+- `hawk-app test <filter>` runs only the test files whose path contains the filter. Tests aren't functions: they are
+  never deployed as one.
+
 ## Email
 
 Apps with the `email:send` scope can send email with `app.email.send(...)` or, from a function,
@@ -719,7 +861,7 @@ with it is never auto-approved. Prompts and answers are never logged or stored.
   the Apps page (see [Versions and aliases](#versions-and-aliases)).
 - **Released apps.** Every deploy is a new version. Clients stay on the approved version until the new one is approved in
   HawkSearch (staff can open it there first). Changes to settings in `hawk-app.json` (name, description,
-  icon, category, version, visibility, hosting, scopes, `systemParameters`, `schedules`, `config`, `externalOrigins`, `listed`, `minProtocolVersion`) wait for approval
+  icon, category, version, visibility, hosting, scopes, `systemParameters`, `schedules`, `events`, `api`, `actions`, `config`, `externalOrigins`, `listed`, `minProtocolVersion`) wait for approval
   the same way. For `config` only the declarations are reviewed: its values are set at any time without review.
 - **Functions.** Engineering enables functions per app. A version whose functions changed (added, removed, new code,
   dependencies or settings) always waits for review, even with auto-approve; reviewers see each function's settings,

package/agents/AGENTS.md

@@ -50,13 +50,14 @@ app.onContextChange(render); // the user switched client, engine or dates
 | Call | Scope |
 | --- | --- |
 | `app.analytics.report('queries', { limit, startDate, endDate, filters })` | `reports:read` |
-| `app.dashboard.get('Synonym')`: HawkSearch dashboard API, no API version in the path | `hawksearch:read` |
+| `app.dashboard.get('Synonym')`: HawkSearch dashboard API, no API version in the path. Typed routes: `app.dashboard.resource('Synonym').list()/get(id)` (reads) and `.create/update/delete` (`hawksearch:write`), models as `HawkSearchModel<'Synonym'>` | `hawksearch:read` |
 | `app.dashboard.post/put/delete(path, body)`: merchandising and relevancy resources only, never retried | `hawksearch:write` |
+| `app.hawksearch.pinning.set(itemPinId, docId, isPinned)`, `.order(itemPinId, docIds)`: the Item Pin rule a search applied (its `ItemPinId`), saved as the user | `hawksearch:write` |
 | `app.hawksearch.search(...)`, `app.hawksearch.autocomplete(...)` on the user's engine; preview: `IsInPreview`, `SmartBar`, `ClientData.PreviewBuckets`, `IndexName`, `ExplainDocId` | `hawksearch:search` |
 | `app.hawksearch.preview.settings/indexes/item/explain`: the preview page's visitor targets, indexes, item details, keyword explain | `hawksearch:read` |
 | `app.hawkai.agents/agent/smartResponses/smartResponse`: the client's HawkAI agents and smart responses (names and settings); `runSmartResponse(id, { query, search })`: its answer for a (preview) search; `assistant(agentId)`: the values for HawkAI's assistant widget | `hawkai:read` |
 | `app.data.query('name', params)`: your SQL in `queries/<name>.sql` + `.json` | `data:read` |
-| `app.functions.call('name', input)`, `.start/.wait/.job` for jobs: `functions/<name>.ts` exporting `handler` | `functions:invoke` |
+| `app.functions.call('name', input)`, `.start/.wait/.job` for jobs: `functions/<name>.ts` exporting `handler`. `schedules` and `events` in hawk-app.json run job functions on a cron, or when something happens for a client (`client.added`, `config.changed`, `version.released`, `hawksearch.changed` with optional `sections`, `index.rebuilt`; input types `HawkAppEvent` from the bridge's `/server`). `api` in hawk-app.json makes a function (not a job) an endpoint the client's own systems call with their HawkSearch site API key (`{ "<name>": { "function", "method": "GET" \| "POST" } }`; `apiResponse(body, { contentType })` for HTML). Test functions without deploying: `functions/<name>.test.ts` with `node:test` and `runFunction` from `@bridgeline-digital/hawk-app-cli/testing` (storage, answers, recordings), run by `npx hawk-app test` | `functions:invoke` |
 | `app.email.send(...)` | `email:send` |
 | `app.storage.get/put/delete/list/batch/usage`: the app's own JSON data per client (350 KB a value, `ttlDays`, `ifVersion`); `app.storage.files.upload/url/download/list/delete`: its files (100 MB each) | `storage` |
 | `app.hawksearch.systemParameters.list/get/set`: names listed in `systemParameters` | `hawksearch:sysparams:write` |
@@ -103,7 +104,7 @@ template: use them before writing your own), `validate`, `status` (with the revi
 `analytics_reports` (every report `app.analytics.report()` can call, with its columns and filters),
 `hawksearch_api` (HawkSearch's dashboard, search, recommendation and indexing operations: fields, the bridge call, its scope),
 `data_tables` and `data_describe` (names and columns, never data), `logs`, `init`, `upgrade`,
-`deploy` (with `alias`, and `dryRun` to only show what hawk-app.json would change), `versions`, `why` (what a client sees, and why), `doctor` (what's wrong with the setup), `errors`, `usage`, and `clients` and `clients_add`, which only ever use the dev platform. Prefer them to guessing. When the
+`deploy` (with `alias`, and `dryRun` to only show what hawk-app.json would change), `versions`, `why` (what a client sees, and why), `doctor` (what's wrong with the setup), `errors`, `error_brief` (one error mapped to the source, with the failed calls and what changed since the last version without it: use it to fix production errors here), `usage`, and `clients` and `clients_add`, which only ever use the dev platform. Prefer them to guessing. When the
 user names a client ("deploy to OTC"), call `clients_add` with their words: it shows them a form to pick the exact
 client. With `alias` (`hawk-app clients add <id> --alias review`) the client gets that alias's version: on a version that
 isn't approved, only Bridgeline staff in it see the app. Only approvers change what a client whose users see the app
@@ -140,6 +141,33 @@ Each view is a route, e.g. `src/app/views/preview/page.tsx` for `"path": "views/
   `{ cache: 'no-store' }` on a call that writes (e.g. an analytics report that records something), or
   `{ cache: 'reload' }` to refresh. The full app page is never cached.
 
+**Say what each page shows**: HawkSearch's "Explain this page" button explains the app's page from it (no scope).
+With the UI kit: `usePageContext(rows ? { page: '<the page>', dateRange, totals, top10 } : null)`; otherwise
+`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"?,
+"selector"?, "attribute"?, "pattern"? } } }] } } }`. `"data": "keyword"` reads `data-keyword` as is when the page has it,
+else the rest of the reader applies. Prefer stable selectors (ids, `data-*`, element names); the view must list the
+params in its `params` and handle them missing. The view reads `app.context.view.params` (and `context.view.action`:
+`{ name }`), its toasts show, and `app.action.done({ changed: true })` closes the dialog once the work is saved. Actions
+always need an approver. Try it with `hawk-app dev`'s Action menu.
+
 A slot can also hold the **entire app** (its own page, with no `view` in the context): it then runs inside another
 page, at the slot's height, so don't rely on the full window either.
 
@@ -173,8 +201,10 @@ npx hawk-app versions            # every version with its status and aliases
 npx hawk-app open                # the app's page in HawkSearch (review, submit for approval)
 npx hawk-app logs <function>     # a function's logs
 npx hawk-app config list         # config values (config set <key> <value> [--client <id>], config unset <key>)
-npx hawk-app errors              # errors in the app's pages (deployed versions), the most frequent first
+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/claude-plugin/hawk-apps/skills/add-function/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: add-function
-description: Add or change a server-side function (functions/<name>.ts, AWS Lambda), a background job or a schedule in a Hawk App. Use when the app needs server code, a third-party API with a secret key, work longer than a page should wait, or something on a timer.
+description: Add or change a server-side function (functions/<name>.ts, AWS Lambda), a background job, a schedule, an event handler or a client API endpoint in a Hawk App, with tests. Use when the app needs server code, a third-party API with a secret key, work longer than a page should wait, something on a timer, setup when a client gets the app, or data the client's own systems fetch.
 ---
 
 # Add a function
@@ -27,8 +27,20 @@ whether the bridge already does it from the page (`docs`): no function is simple
    themselves (hidden input). A value each client sets for itself is a `clientSecrets` entry instead.
 4. **Long work** is a job (`"job": true`, up to 900 s): the app calls `app.functions.start(name, input)` and
    `app.functions.wait(jobId)`. **On a timer** it's a `schedules` entry (a job function, a 6-field EventBridge cron at
-   most hourly, an IANA `timezone`) that users turn on per client with `app.schedules.enable(name)`.
+   most hourly, an IANA `timezone`) that users turn on per client with `app.schedules.enable(name)`. **When something
+   happens for a client** it's an `events` entry (`"<event>": { "function": "<job>" }`): `client.added` (it got the
+   app), `config.changed` (its config changed), `version.released` (a new version reached it): these run without a site
+   or HawkSearch connection, so they can't call HawkSearch. `hawksearch.changed` (a dashboard change, `sections` to
+   narrow it) and `index.rebuilt` come from HawkSearch within 1–2 minutes and run with the engine and connection; keep
+   them idempotent.
 5. **Call it** from the app with `app.functions.call('<name>', input)` and handle `function_failed`,
-   `function_timeout`, `secret_missing` and `functions_not_enabled`.
-6. **Check it.** Run `validate`. Functions run only from a **deployed** version; deploy only when the user asks. After
-   a deploy, `logs` shows the function's output.
+   `function_timeout`, `secret_missing` and `functions_not_enabled`. **For the client's own systems** (a script, a job
+   on their side) make it an endpoint instead: `"api": { "<name>": { "function": "<function>", "method": "GET" } }`
+   (not a job; input from the query or JSON body; `apiResponse(body, { contentType })` from `/server` for HTML).
+   Bridgeline turns API access on per client; the client calls it with its HawkSearch site API key.
+6. **Test it** without deploying: `functions/<name>.test.ts` with `node:test` and `runFunction` from
+   `@bridgeline-digital/hawk-app-cli/testing` (input, trigger, `storage` in memory, `answers` for platform calls,
+   recordings), then `npx hawk-app test`. A client API endpoint also runs locally under `hawk-app dev` at
+   `http://localhost:3200/v1/clients/<id>/apps/<slug>/api/<name>`.
+7. **Check it.** Run `validate`. Called from the app, functions run from the **deployed** version; deploy only when the
+   user asks. After a deploy, `logs` shows the function's output.

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

@@ -28,5 +28,9 @@ colors and light/dark mode. Never restyle the kit or add another font.
    - accessible: labelled fields, `alt` on images, one `<main>`, headings in order.
 5. **A view** (a preview card or an embeddable slot) is a route declared in `views` in `hawk-app.json`: keep it small,
    read stored results, transparent background, height from the content. See the Views section of `AGENTS.md`.
+   **Opened from HawkSearch's own pages** (a button by a search term in a report, on an AI Advisor insight…), it's an
+   `actions` entry: the view, and `targets` per host (a regex on the page path, CSS selectors, how each param is read;
+   the bridge README's **Actions**). The view reads `app.context.view.params`, handles them missing, and calls
+   `app.action.done({ changed: true })` when the work is saved. Try it with `npm run app:dev`'s Action menu.
 6. **Check it.** Run the hawk-apps `validate` tool (with `build: true` when the build setup changed) and fix what it
    says. Offer `npm run app:dev` to see it locally. Deploy only when the user asks.

package/claude-plugin/hawk-apps/skills/prepare-review/SKILL.md

@@ -22,11 +22,15 @@ green, or explain to the user why one can't be.
      never auto-approved.
    - **Queries:** each has `{{partitions(...)}}`, names its columns and has a `LIMIT` on lists.
    - **Functions and external Lambdas:** shown to the approver with their code and settings; Engineering must have
-     enabled functions.
+     enabled functions. `npx hawk-app test` passes, if the app has function tests.
+   - **Client API endpoints (`api`):** each answers only what the client's own users could see in the app.
+   - **Actions (`actions`):** each target reads only what its view needs, with stable selectors (ids, `data-*`
+     attributes, element names); approvers see every target, and an app with actions is never auto-approved.
    - **No secrets** anywhere in the app or the build.
 3. **What approvers will see.** Run `status`: the review checks on the newest version, and `deploy` with
    `dryRun: true`: what `hawk-app.json` would change. If the newest version is older than the code, say so: the user
    decides when to deploy.
-4. **Errors.** Run `errors` and fix what the deployed versions threw, the most frequent first.
+4. **Errors.** Run `errors` and fix what the deployed versions threw, the most frequent first: `error_brief` with an
+   error's id gives its stack mapped to the source, the failed platform calls and what changed since it last worked.
 5. **Finish** with a short list: ready to submit (open the app with `npx hawk-app open` and click **Submit for
    approval**), or what's left. Never deploy to prod or submit for the user.