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

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

@@ -0,0 +1,36 @@
+---
+name: prepare-review
+description: Get a Hawk App ready to submit for approval in HawkSearch - run the approvers' automated checks (bundle, dependencies, accessibility, outside origins, queries, functions, scopes), fix what fails and say what's left. Use before submitting, after a big change, or when the user asks whether the app will pass review.
+---
+
+# Prepare for review
+
+Approvers see automated checks in HawkSearch's approve dialog; a failed one forces them to override it. Get every check
+green, or explain to the user why one can't be.
+
+1. **Validate with the build.** Run the hawk-apps `validate` tool with `build: true`. Fix what it reports in the code;
+   ask the user before changing `scopes` or `externalOrigins` in `hawk-app.json`.
+2. **The review checklist** (fix or explain each):
+   - **Bundle:** under 20 MB in total, no file over 5 MB, not 50% (and 1 MB) bigger than the released version.
+   - **Dependencies:** no high or critical findings in `npm run app:audit` (production dependencies).
+   - **Accessibility:** no critical axe issues (`validate --build` lists them): labels, `alt`, one `<main>`, headings
+     in order.
+   - **Outside origins:** `externalOrigins` lists each https origin the app calls or loads from; `["*"]` fails
+     (`"img:*"` is fine for images).
+   - **Scopes:** each one is used by the code, and every bridge call's scope is there (`validate` warns about missing
+     ones). Fewer is better: elevated scopes (`data:read`, `functions:invoke`, `hawksearch:write`, `ai:invoke`, …) are
+     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. `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: `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.

package/docs/bridge/README.md

@@ -125,6 +125,82 @@ them in `hawk-app.json`:
   `data:read`): hide or disable what writes, sends, stores or asks the assistant, and say it's a trial.
   `navigate({ intent: 'app' })` opens the host's request dialog.
 
+### Actions: start the app from HawkSearch's screens
+
+**Actions** put the app where the work is: a button in HawkSearch's own pages (by a search term in a report, on an AI
+Advisor insight…) that opens one of the app's views in a dialog, already on that thing. The app says where, with
+**targets**: the page (a regular expression on its path), the things (a CSS selector: one button per match), where the
+button goes, and how each of the view's params is read from the thing. Deploy, and once the version is approved the
+buttons appear in HawkSearch: nothing changes in HawkSearch for it.
+
+```jsonc
+"views": {
+  "fix": { "path": "views/fix", "title": "Fix a search", "height": 420, "params": ["keyword", "category"] }
+},
+"actions": {
+  "fix-keyword": {
+    "label": "Fix with Zero Results Fixer",
+    "view": "fix",
+    "targets": {
+      "hawksearch": [
+        {
+          "path": "/admin/advanced-analytics/(top-queries|query-with-poor-results)/?$",   // the page
+          "selector": "bl-table tbody.table__body > tr.table__row",                        // each thing: a table row
+          "anchor": "td.table__cell:first-child",                                          // the button goes in it
+          "params": { "keyword": { "selector": "td.table__cell:first-child" } }            // its text
+        },
+        {
+          "path": "/admin/recommendations/?$",
+          "selector": ".recommendations-list__item:not(.recommendations-list__item--empty)",
+          "anchor": ".recommendations-list__text",
+          "position": "after",
+          "params": {
+            "keyword": { "selector": ".recommendations-list__text", "pattern": "[\"“”]([^\"“”]{1,100})[\"“”]" },
+            "category": { "selector": ".recommendations-list__category-tag" }
+          }
+        }
+      ]
+    }
+  }
+}
+```
+
+- **A target:** `path` (a regular expression on the page's path), `selector` (each thing), `anchor` (a selector inside
+  the thing; default the thing) and `position` (`append`, the default, `prepend`, `before` or `after` it), and `params`:
+  for each of the view's params, `selector` (an element inside the thing; default the thing), `attribute` (default its
+  text) and `pattern` (a regular expression; its first group is the value). Values are text, at most 200 characters.
+- **Data attributes (optional):** a param's `data` names a `data-*` attribute without its `data-` (`"keyword"` reads
+  `data-keyword`), on the thing or the first element inside it that has one. When it has a value, that value is used
+  as is (no pattern); when it's missing or empty, the param's `selector`, `attribute` and `pattern` read it as above.
+  So a target can be ready for an attribute HawkSearch adds later, e.g. `"keyword": { "data": "hawk-keyword",
+  "selector": "td.table__cell:first-child" }`. With `data` alone, nothing is read until the attribute is there.
+- **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.
+
+```tsx
+// src/app/views/fix/page.tsx
+const { app, context } = useHawk();
+const keyword = context.view?.params.keyword?.trim();          // only the params the view declares arrive
+// context.view.action: { name: 'fix-keyword' } (null when the view isn't opened by an action)
+
+async function saved() {
+    await app.toast(`Synonym created for "${keyword}"`, 'success');  // shown by the host for an action's view
+    await app.action.done({ changed: true });                         // the host closes the dialog (and may refresh)
+}
+```
+
+- Each target's params must be ones the view declares (`hawk-app validate` checks it).
+- `app.action.done({ changed })` closes the host's dialog. It does nothing outside an action, and on a host from
+  before actions.
+- Params are read from the page, like a URL's query: check them, and handle them missing (the page may not show the
+  value). The platform's checks (scopes, client, engine) still apply to every call the view makes.
+- At most 10 actions, 5 targets per host each. `hawk-app dev` has an **Action** menu that opens a view as HawkSearch
+  will (type the value in).
+- A complete example, from `hawk-app.json` to release:
+  [Fix a search term from HawkSearch's reports](../../docs/examples.md#fix-a-search-term-from-hawksearchs-reports).
+
 ### Hosts: `<hawk-app-container>`
 
 Configure once per page, then place containers anywhere:
@@ -153,7 +229,9 @@ configureHawkAppContainers({
   `full-app` (the entire app instead of a view: `resolveView(app, null)`; its context has no `view`),
   `min-height` (default 0), `max-height` (default 1200), `fallback` (text when the view can't load and the app has no description),
   `trial` (a store app's trial view: the host's `resolveView`, `getToken` and `openApp` get `{ trial: true }`, and
-  the context `trial: true`).
+  the context `trial: true`), `action` (`{"name":"fix-keyword"}`: the view was opened from one of the app's
+  [actions](#actions-start-the-app-from-hawksearchs-screens); its toasts reach the page and `app.action.done()` fires
+  `hawk-action-done`).
 - **Loading:** when scrolled near, at most `maxConcurrent` (default 3) at a time; a placeholder of the view's height
   until it connects; the fallback after `loadTimeoutMs` (default 20 s).
 - **Styling:** the `state` attribute (`idle`, `loading`, `ready`, `fallback`) and a `hawk-view-state` event; the
@@ -256,32 +334,48 @@ server's `analytics_reports` tool reads that spec.
 ### HawkSearch dashboard API: `hawksearch:read`
 
 ```ts
-const synonyms = await app.dashboard.get('Synonym');
-const fields = await app.dashboard.get('Field');
+const synonyms = await app.dashboard.get('Synonym');          // HawkSearchModel<'Synonym'>[]
+const fields = await app.dashboard.get('Field');              // HawkSearchModel<'FieldModel'>[]
 // Query parameters: app.dashboard.get('LandingPage', { query: { ... } })
+
+// Typed routes of a resource
+const redirects = app.dashboard.resource('redirect');
+const all = await redirects.list();
+const one = await redirects.get(42);
 ```
 
 Any resource of the [HawkSearch Dashboard API](https://developerdocs.hawksearch.com/reference/getting-started-with-your-api):
 `Synonym`, `LandingPage`, `Field`, …. Leave the API version out; the platform picks it. Responses are HawkSearch's
-body as is. To change data, see [Writing to HawkSearch](#writing-to-hawksearch-hawksearchwrite). For reporting, use
+body as is.
+
+**Typed from HawkSearch's API definition.** `app.dashboard.resource(name)` gives a resource's routes: `list()`,
+`get(id)`, `create(body)`, `update(id, body)` and `delete(id)`, only those HawkSearch has for it (`bannerzone` is list
+only, `LandingPage` has no list), with HawkSearch's models: a misspelled field or resource is a compile error.
+`get(name)` of such a resource is typed too, and `HawkSearchModel<'Synonym'>` (or `'RedirectModel'`, `'LandingPage'`,
+…) names a model in your own code. The resources, as HawkSearch spells them: `banner`, `bannerzone`, `boostbury`,
+`campaign`, `Facet`, `Field`, `FieldInfo`, `LandingPage`, `landingPageLayout`, `paginationset`,
+`recommendationvisibility`, `redirect`, `sortingset`, `spellcheck`, `Synonym`, `visibility`, `visitortarget` (paths
+ignore case). Other paths (`LandingPage/urls`, `reports/…`) stay on `get<T>(path)`. The types come from HawkSearch's dev
+API and are refreshed with each bridge release. To change data, see [Writing to HawkSearch](#writing-to-hawksearch-hawksearchwrite). For reporting, use
 analytics. Your assistant can look up any operation's fields, its bridge call and scope with the `hawk-apps` MCP
-server's `hawksearch_api` tool.
+server's `hawksearch_api` tool. The same scope gives the preview page's tools (`app.hawksearch.preview`: visitor targets,
+indexes, item details, keyword explain): see [Preview like HawkSearch's preview page](#preview-like-hawksearchs-preview-page).
 
 ### Writing to HawkSearch: `hawksearch:write`
 
 ```ts
 // Create a synonym
-const synonym = await app.dashboard.post('Synonym', {
+const synonym = await app.dashboard.resource('Synonym').create({
   SearchTerm: 'sneakers',
   SynonymGroup: 'trainers,running shoes',
   MultiWay: true,
 });
 
 // Update a redirect
-await app.dashboard.put('Redirect/42', { ...redirect, NewUrl: '/sale' });
+await app.dashboard.resource('redirect').update(42, { ...redirect, RedirectUrl: '/sale' });
 
-// Delete a banner
-await app.dashboard.delete('Banner/7');
+// Delete a banner (or any path: app.dashboard.delete('Banner/7'))
+await app.dashboard.resource('banner').delete(7);
 ```
 
 `app.dashboard.post(path, body?)`, `put(path, body?)` and `delete(path)` (also on `ctx.platform.dashboard` in
@@ -489,8 +583,8 @@ what `handler` returned (up to 6 MB). It waits up to `timeoutMs` (default 30 s)
 | `ctx.app.slug`, `ctx.version` | Your app and the version the caller has open (the function code is that version's). |
 | `ctx.secrets.NAME` | The secrets the function declares in `hawk-app.json` (see below). Nothing else. |
 | `ctx.config` | The app's [config](#app-config) for the caller's client and this version, already resolved: `{ key: value }` for every declared key (null when nothing is set and there's no default). Frozen. |
-| `ctx.platform` | The platform API **as the caller**: `analytics.report`, `dashboard.get/post/put/delete`, `data.query` (polled for you), [`email.send`](#email-emailsend), [`hawksearch.search/autocomplete`](#hawksearch-search-hawksearchsearch), [`hawksearch.systemParameters`](#hawksearch-system-parameters-hawksearchsysparamswrite), [`functions.start/job/wait`](#background-jobs), [`ai.generate/stream/info`](#ai-aiinvoke) and `api.get/post`, with your app's scopes. Analytics dates don't default on the server: pass them. |
-| `ctx.job`, `ctx.trigger` | For a [background job](#background-jobs): `{ id, progress(percent?, message?) }` (null for a call), and what started the run (`call` or `schedule`). |
+| `ctx.platform` | The platform API **as the caller**: `analytics.report`, `dashboard.get/post/put/delete`, `data.query` (polled for you), [`email.send`](#email-emailsend), [`hawksearch.search/autocomplete`](#hawksearch-search-hawksearchsearch), [`hawksearch.preview`](#preview-like-hawksearchs-preview-page), [`hawkai`](#hawkai-agents-and-smart-responses-hawkairead), [`hawksearch.systemParameters`](#hawksearch-system-parameters-hawksearchsysparamswrite), [`functions.start/job/wait`](#background-jobs), [`ai.generate/stream/info`](#ai-aiinvoke) and `api.get/post`, with your app's scopes. Analytics dates don't default on the server: pass them. |
+| `ctx.job`, `ctx.trigger` | For a [background job](#background-jobs): `{ id, progress(percent?, message?) }` (null for a call), and what started the run (`call`, `schedule`, [`event`](#events) or [`api`](#client-api)). |
 | `ctx.aws` | Only with `data:read`: short-lived credentials scoped to this client's analytics data, plus `region`, `database`, `workGroup`, `outputLocation`, for the AWS SDK's Athena client. Prefer `ctx.platform.data.query` when an app query does the job. |
 
 The deploy wraps your `handler` with `toLambdaHandler` from `@bridgeline-digital/hawk-app-bridge/server` and
@@ -587,7 +681,8 @@ try {
   pick the job up again after a reload.
 - In the function, `ctx.job` is `{ id, progress(percent?, message?) }` (null for a call). `progress` sends at most
   once a second (calls in between are merged) and never throws. `ctx.trigger` says what started the run:
-  `{ type: 'call' }` or `{ type: 'schedule', schedule, enabledBy }`.
+  `{ type: 'call' }`, `{ type: 'schedule', schedule, enabledBy }`, `{ type: 'event', event, enabledBy? }` or
+  `{ type: 'api', endpoint }` (a [client API](#client-api) call).
 - `ctx.platform.functions.start/job/wait` start other jobs from a function, e.g. to fan work out.
 
 Limits: a job runs up to 900 s (`timeoutSeconds`, default 300); 3 jobs per app and client run at once (429
@@ -622,6 +717,118 @@ await app.schedules.enable('nightly');   // or disable('nightly'); both resolve
 - Schedules are a setting reviewed like scopes. They stop when the app's release is withdrawn, functions are turned off for
   it, or a version without the schedule is approved.
 
+### Events
+
+`events` in `hawk-app.json` name a job function the platform starts when something happens for a client, so the app
+doesn't poll for it.
+
+```jsonc
+"functions": { "on-event": { "job": true } },
+"events": {
+    "client.added": { "function": "on-event" },
+    "config.changed": { "function": "on-event" },
+    "version.released": { "function": "on-event" }
+}
+```
+
+```ts
+// functions/on-event.ts
+import type { HawkAppEvent, HawkFunction } from '@bridgeline-digital/hawk-app-bridge/server';
+
+export const handler: HawkFunction<HawkAppEvent> = async (input, ctx) => {
+    switch (input.event) {
+        case 'client.added':      // { clientId, at }
+            await ctx.platform.storage.put('settings', { digest: 'weekly' });
+            break;
+        case 'config.changed':    // { clientId, at, key, scope: 'client' | 'global' }; new values in ctx.config
+            break;
+        case 'version.released':  // { clientId, at, version, previousVersion }; runs on the new version
+            break;
+    }
+};
+```
+
+| Event | When |
+|---|---|
+| `client.added` | The client's users see the app now and didn't before: a store request approved, the client added to the app's list, the app released (for every client already on its list), or an alias approved for the client. Only for listed clients: an app with visibility `all` has no list of who got it. |
+| `config.changed` | A config value was set or cleared for the client, or globally (then for every client without its own value for the key). |
+| `version.released` | Another version reached a client that had the app: a release or rollback, or its alias moved. |
+
+- For an app every client has (visibility `all`), `config.changed` (global) and `version.released` go to the clients
+  whose users opened it in the last 90 days.
+- The run is a job (`ctx.trigger` `{ type: 'event', event }`) for that client, as the user `event:<name>` (no roles,
+  not internal), **without a site or HawkSearch connection**: no user's session is behind it, so HawkSearch calls
+  answer 403 `hawksearch_not_available`. Storage, data, email, config and secrets work.
+- Delivered once; not retried when it can't start (3 jobs already running for the client). Events are a setting
+  reviewed like scopes; only approved handlers run, and only while functions are on for the app.
+
+#### HawkSearch events
+
+`hawksearch.changed` (something changed in HawkSearch's dashboard) and `index.rebuilt` (an index rebuild finished) come
+from HawkSearch itself, read once a minute for the engines where the client's users opened the app. They run **with
+that engine and the client's HawkSearch connection**, so the handler can read what changed:
+
+```jsonc
+"events": {
+    "hawksearch.changed": { "function": "sync-synonyms", "sections": ["synonym"] },
+    "index.rebuilt": { "function": "after-rebuild" }
+}
+```
+
+```ts
+import type { HawkFunction, HawkSearchChangedEvent } from '@bridgeline-digital/hawk-app-bridge/server';
+
+export const handler: HawkFunction<HawkSearchChangedEvent> = async (input, ctx) => {
+    // { engineId: '3141', section: 'synonym', changes: [{ action: 'update', recordId: 12, apiAction: false, at }], count: 1, truncated: false }
+    const synonyms = await ctx.platform.dashboard.get('Synonym');
+    // …push them to the other system
+};
+```
+
+- `sections` (optional) are HawkSearch's section codes: `synonym`, `redirect`, `landingpage`, `field`, `facet`,
+  `visibilityrule`, `boostburyrule`, `pinneditem`, `contentitem`, `bannergroup`, `systemparameters` and the rest of the
+  search settings (the JSON schema lists them all). One event per section per minute, with up to 100 changes.
+- `index.rebuilt`: `{ engineId, notificationId, status: 'success' | 'error', finishedAt }`, however the rebuild started.
+- Expect them 1–2 minutes after the change. Changes your app makes itself through the platform (dashboard writes,
+  pinning, system parameters) aren't sent back to it. Who made a change is never sent. A handler can see an event twice
+  after a platform hiccup: make it idempotent.
+
+### Client API
+
+`api` in `hawk-app.json` 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. No keys to manage: Bridgeline turns API access on per client
+in HawkSearch (the app's kebab menu › API access), which also 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: ?designId=<id>" }
+}
+```
+
+```ts
+// functions/design-html.ts
+import { apiResponse, type HawkApiResponse, type HawkFunction } from '@bridgeline-digital/hawk-app-bridge/server';
+
+export const handler: HawkFunction<{ designId?: string }, HawkApiResponse> = async (input, ctx) => {
+    const saved = await ctx.platform.storage.get<Design>(`design#${input.designId}`);
+    if (!saved) return apiResponse('No design with this id.', { status: 404 });
+    return apiResponse(await renderDesign(saved.value, ctx), { contentType: 'text/html; charset=utf-8' });
+};
+```
+
+```
+curl -H "X-HawkSearch-ApiKey: <site API key>" "https://<platform>/v1/clients/<clientId>/apps/<slug>/api/design-html?designId=abc"
+```
+
+- The input is the query string (GET, the default; values are strings) or the JSON body (POST).
+- A function's answer is sent as JSON; `apiResponse(body, { contentType?, status? })` sends a body as is (HTML, CSV, …).
+- The function isn't a job (the caller waits). `ctx.trigger` is `{ type: 'api', endpoint }`; it runs as the user
+  `api:<name>` (no roles, not internal) for the client, on the key's engine, with the key as its HawkSearch connection.
+- At most 10 endpoints; 120 calls a minute per client (429). Endpoints are a setting reviewed like functions. Anyone
+  holding the client's site key can call them once access is on: answer only what the client's users could see in
+  the app.
+
 ## Email: `email:send`
 
 Send an email from the app or from a [function](#functions-functionsinvoke): a report to the user, an alert, a
@@ -695,8 +902,9 @@ await app.hawksearch.autocomplete({ Keyword: 'boo', ProductCount: 5 });
 ```
 
 - The request is HawkSearch's v2 search / autocomplete body, sent as is: any field works (`Keyword`, `PageNo`,
-  `MaxPerPage`, `SortBy`, `FacetSelections`, `CustomUrl`, `IndexName`, `SmartBar`, …). The platform sets `ClientGuid`
-  to the current engine's; you never need it.
+  `MaxPerPage`, `SortBy`, `FacetSelections`, `CustomUrl`, `IndexName`, `SmartBar`, …). Every field of HawkSearch's search
+  API definition is typed (`SortingSetCode`, `PageId`, `RequestType`, `BoostQueries`, …). The platform sets `ClientGuid`
+  to the current engine's; you never need it. The response has the common fields typed; the rest is HawkSearch's as is.
 - `IsInPreview: true` runs on the engine's preview search API.
 - At most 600 calls per app and client per minute: a `429 too_many_requests` carries `retryAfterMs` (not retried
   for you). For bulk checks, run a few at a time.
@@ -713,6 +921,87 @@ await app.hawksearch.autocomplete({ Keyword: 'boo', ProductCount: 5 });
 
 Other HawkSearch errors (e.g. `400` for an unknown `IndexName`) come back as HawkSearch sent them.
 
+### Preview like HawkSearch's preview page
+
+A preview search takes everything the preview page sets: `IsInPreview: true`, `SmartBar` (`PreviewDate` and switches
+such as `BoostAndBury: false`, `ItemPin: false`), `ClientData: { PreviewBuckets: [ids] }` for visitor targets,
+`IndexName`, `Is100CoverageTurnedOn`, and `ExplainDocId` to explain one result's score (`DocExplain` in the answer). The page's own pickers and explain panel are `app.hawksearch.preview` (scope **`hawksearch:read`**,
+within the same per-minute limit):
+
+```ts
+const settings = await app.hawksearch.preview.settings();        // visitor targets, fields, layouts
+const { ClientIndexes, CurrentIndex } = await app.hawksearch.preview.indexes();
+const item = await app.hawksearch.preview.item('SKU-123');       // one item as indexed ({ indexName } optional)
+const why = await app.hawksearch.preview.explain({ Keyword: 'jackets', IsInPreview: true });
+why.AdjustedKeyword; why.AppliedKeywordReplacementRules; why.ElasticQuery;
+```
+
+`explain` needs the session's site API key (`403 preview_needs_site_key` with a group key).
+
+**Pin items** (scope **`hawksearch:write`**): a search's response has `ItemPinId`, the Item Pin rule it applied (null
+when none), and `IsPin` on the results that rule pins. Pin, unpin and reorder its items; HawkSearch saves the change as
+the user, and it applies to live search too:
+
+```ts
+const results = await app.hawksearch.search({ Keyword: 'jacket', IsInPreview: true });
+if (results.ItemPinId) {
+    await app.hawksearch.pinning.set(results.ItemPinId, 'SKU-123', true);       // false unpins
+    await app.hawksearch.pinning.order(results.ItemPinId, ['SKU-9', 'SKU-123']); // the pinned order
+}
+```
+
+Pass `{ previewDate }` (the search's `SmartBar.PreviewDate`) so the next preview search shows the change at once.
+Site keys only, within the write limit, never retried. Errors: `pinning_needs_user` (403: the host didn't send the
+user's HawkSearch admin), `hawksearch_write_needs_site_key` (403), `pinning_refused` (502: HawkSearch refused the
+user), `pinning_not_configured` (503). A search without a rule has nothing to pin into: rules are created in HawkSearch.
+
+## HawkAI agents and smart responses: `hawkai:read`
+
+The client's HawkAI agents and smart responses for the user's current engine, as Spark lists them: names and settings,
+never prompts. From the app or a function (`ctx.platform.hawkai`).
+
+```ts
+const agents = await app.hawkai.agents();            // by name
+const responses = await app.hawkai.smartResponses(); // with maxItems and allowRequestOverride
+const one = await app.hawkai.smartResponse(responses[0].id);
+```
+
+Each is `{ id, name, description, model, allEngines, maxItems, allowRequestOverride }` (`allEngines`: set up for every
+engine of the client).
+
+**Run a smart response** for a query and a search, live or in preview, as the storefront does. The platform adds the
+client, the engine's ClientGuid and its search API; HawkAI runs the search and picks the items:
+
+```ts
+const answer = await app.hawkai.runSmartResponse(id, {
+    query: 'waterproof jacket',
+    search: { Keyword: 'jacket', IsInPreview: true, SmartBar: { PreviewDate: '2026-11-27T00:00:00' } },
+});
+answer.recommendation; // Markdown
+answer.Results;        // [{ DocId, Document, reason }]
+```
+
+Answered whole (not streamed), within the search limit. **An assistant** runs in HawkAI's widget
+([`@bridgeline-digital/hawkai-assistant`](https://www.npmjs.com/package/@bridgeline-digital/hawkai-assistant)), which
+talks to HawkAI from the browser: `app.hawkai.assistant(agentId)` gives it `{ apiUrl, accountId, agentId }`.
+
+```ts
+HawkAI.Assistant.initialize({ ...(await app.hawkai.assistant(agentId)), ui: { display: 'embedded', embedHostSelector: '#assistant' } });
+```
+
+List HawkAI's origin in `externalOrigins` (`https://assistant-dev.hawksearch.net` on dev, `https://assistant.hawksearch.net`
+on prod). The widget initializes once per page: reload to switch agents.
+
+| `error.code` | Status | Meaning |
+|---|---|---|
+| `scope_missing` | 403 | Add `hawkai:read` to `scopes`. |
+| `engine_required` | 400 | The host session has no engine. |
+| `hawkai_not_found` | 404 | No agent / smart response with that id for this client and engine. |
+| `hawkai_unavailable` | 502 | HawkAI's configuration couldn't be read, or HawkAI didn't answer in time: try again. |
+| `hawkai_error` | 502 | HawkAI answered without a smart response (its reason is in the message). |
+| `hawkai_limit_reached` | 429 | HawkAI's own limit for the client (tokens or rate). |
+| `too_many_requests` | 429 | Over the search limit (smart responses count as searches); wait `retryAfterMs`. |
+
 ## HawkSearch system parameters: `hawksearch:sysparams:write`
 
 Let users change a few HawkSearch **system parameters** of the engine they are working on (Sites → System Parameters
@@ -851,8 +1140,10 @@ await app.hawksearch.index.setCurrent(name);
 - **Never the live index:** `deleteIndex` of the current index is 409 `index_is_current`. Engines may have only two
   indexes: delete the old one before `create`. `unset-current`, index templates and group indexing aren't available.
 - `call(operation, body?)` sends HawkSearch's own body
-  ([Indexing API](https://developerdocs.hawksearch.com/reference/indexv2_get)) and resolves to its answer. Engines
-  without an Indexing API answer 503 `indexing_api_not_available`; anything outside the list is 404.
+  ([Indexing API](https://developerdocs.hawksearch.com/reference/indexv2_get)) and resolves to its answer. The body is
+  typed from HawkSearch's Indexing API definition (`IndexingRequests`, fields in PascalCase: `IndexName`, `Items`,
+  `Hierarchies`, …; HawkSearch reads any case). Engines without an Indexing API answer 503 `indexing_api_not_available`;
+  anything outside the list is 404.
 
 ## HawkSearch recommendations: `hawksearch:recommendations`
 
@@ -1144,6 +1435,69 @@ await app.navigate({ intent: 'app', slug: 'other-tool' }); // also: 'report', 's
 await app.resize();                                       // when autoResize is off
 ```
 
+### Say what the page shows: "Explain this page"
+
+Hosts show an **Explain this page** button by the app: a short plain-language summary of what the page shows, what
+stands out and what to do, written by the platform's AI from what the app says is on screen. Every app gets it, with no
+scope and no AI budget of its own; the button shows only while the app has said what its page shows:
+
+```tsx
+// With the UI kit: sent shortly after it changes, cleared when the page unmounts; null while loading.
+usePageContext(rows ? { page: 'Zero-result searches', dateRange: context.dateRange, total, top10: rows.slice(0, 10) } : null);
+
+// Without it:
+await app.assistant.setContext({ page: 'Zero-result searches', dateRange, total, top10 }); // null clears it
+```
+
+- **What to put in it:** the figures on screen, in plain names and numbers, with what they mean (`{ keyword, searches,
+  results }`, not `{ k, s, r }`), and the page's name. A JSON object of at most 50 KB: summarize long tables (the top
+  rows and the totals).
+- **Keep it current:** set it again when the user changes a filter or a tab; the answer is about what you last set. The
+  host clears it when the app closes.
+- **The same context** goes to the host's assistant for apps with the `assistant` scope (below).
+- **The explanation** is written by the platform (Claude, the fast tier) from the context, the app's name and
+  description, the page's title (`app.setTitle`) and the user's language. It's told to use only what the page says;
+  users can copy it and rate it. Explanations come from one daily budget per client, for all its apps.
+- `hawk-app validate` warns when the app never sets a context, and `hawk-app dev` has the button in its bar.
+
+Hosts: `<hawk-app-explain for="<frame id>">` (registered with `<hawk-app-frame>`) is the button and its side panel;
+the frame's `pageContext`, `hawk-page-context` event and `explainPage()` are there for hosts that build their own. See
+[HOSTS.md](HOSTS.md).
+
+### Export a page as a PDF
+
+Pages worth keeping (a report, a summary for a meeting) can offer **Export as PDF**: while the page allows it, the
+host shows a PDF icon by the app, and a click downloads the app's whole page (its full height, not just what's on
+screen) as a PDF. Only the app's frame is in it, never the host's page. You choose the pages; no scope is needed.
+
+```tsx
+// With the UI kit: on while the page is mounted (false while it loads), off when it unmounts.
+usePdfExport(rows ? { fileName: `Zero results ${dateRange.from}`, title: 'Zero-result searches' } : false);
+
+// Without it:
+await app.setPdfExport({ fileName: 'Zero results' });   // the icon shows
+await app.setPdfExport(null);                          // and hides
+```
+
+```tsx
+<Stack direction="row" data-hawk-pdf-ignore>   {/* left out of the PDF: filters, buttons */}
+```
+
+- **What's in it:** the page as the user sees it, rendered to images in the app (the bridge loads `html-to-image`
+  only when someone exports) and cut into A4 pages, landscape for pages wider than 900 px. Text in the PDF is an
+  image: it can't be selected or searched.
+- **Options:** `fileName` (without `.pdf`; default `<slug>-<yyyy-mm-dd>`), `title` (the PDF's properties; default the
+  page's title).
+- **Leave out** what doesn't belong on paper with `data-hawk-pdf-ignore` (buttons, filters, the pager). Content inside
+  a scrolling box (a table with its own scrollbar) is exported as far as it's scrolled into view: let it grow on pages
+  you export.
+- Images from other sites that don't allow it (CORS) come out blank. A failed export shows the host's error toast and
+  is reported like the page's other errors (`hawk-app errors`).
+- `hawk-app dev` has the icon in its toolbar. Errors (`HawkBridgeError`): `unsupported` (a host without PDF export).
+
+Hosts: `<hawk-app-pdf for="<frame id>">` (registered with `<hawk-app-frame>`) is the icon; the frame's `pdfExport`,
+`hawk-pdf-export` event and `exportPdf()` are there for hosts that build their own. See [HOSTS.md](HOSTS.md).
+
 ### Ask the host's assistant: `assistant`
 
 With the `assistant` scope, an app asks the host's assistant (HawkSearch: Hawk Assistant) a question as the user. The
@@ -1159,10 +1513,9 @@ useEffect(() => app.onContextChange((c) => setReady(!!c.features?.assistant)), [
 </Button>
 ```
 
-Give the assistant what's on screen with `app.assistant.setContext({ ... })` (a JSON object, at most 50 KB; `null`
-clears it): it goes with every question, the app's and the ones the user types, until the app replaces or clears it, and
-the host clears it when the app closes. Keep it to the figures on screen, in plain names and numbers, and keep the
-questions themselves plain:
+The page context ([above](#say-what-the-page-shows-explain-this-page): `app.assistant.setContext`, or the UI kit's
+`usePageContext`) goes to the assistant too, for apps with the scope: with every question, the app's and the ones the
+user types, until the app replaces or clears it. Keep the questions themselves plain:
 
 ```ts
 useEffect(() => void app.assistant.setContext({ page: 'Recommendation Dashboard', range, totals, widgets }), [range, totals, widgets]);
@@ -1170,7 +1523,7 @@ await app.assistant.ask('Which widgets are taking up space?');
 ```
 
 A message is at most 2,000 characters. Errors (`HawkBridgeError`): `unsupported` (no assistant on the page), `scope_missing`,
-`invalid_request`. Hosts: `<hawk-app-frame>` fires a cancelable `hawk-assistant` event (`detail.message`; `hawk-assistant-context` with `detail.context` for the context); a host that
+`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
 message to `window.HawkAI.Assistant.sendMessage` (the context to `setContext`, kept until the assistant loads) when the page has it, and tells the app (a `contextChanged` with
 `features.assistant`) when it loads.
@@ -1264,9 +1617,12 @@ Which clients have the app is not in this file: manage them in the Hawk Analytic
 | `hosting` | `static` (the default): built files on the apps CDN. `server` is reserved for server-rendered apps and not accepted yet. |
 | `visibility` | `allowList` (only the clients given the app), `all` (every client except excluded ones), or `internal` (Bridgeline staff). The clients themselves are managed in the Hawk Analytics portal or with `npx hawk-app clients add`/`exclude`/`remove`; a `hawk-app.json` with `clients` or `excludeClients` is refused. |
 | `listed` | `true` (the default) shows the app on the host's Apps page. `false` leaves it off that list, and the host hides its own title and back button for it, but it still opens by its direct URL (e.g. linked from another app or page). It doesn't change who can open it: `visibility` and the app's clients still apply. |
-| `scopes` | `reports:read` for analytics, `hawksearch:read` for the dashboard API, `hawksearch:write` to [write to it](#writing-to-hawksearch-hawksearchwrite), `data:read` for [custom queries](#custom-data-queries-dataread), `functions:invoke` for [functions](#functions-functionsinvoke), `email:send` for [email](#email-emailsend), `hawksearch:sysparams:write` for [system parameters](#hawksearch-system-parameters-hawksearchsysparamswrite), `hawksearch:search` for [search](#hawksearch-search-hawksearchsearch), `hawksearch:features:write` for [features](#hawksearch-features-hawksearchfeatureswrite), `hawksearch:index` for [index rebuilds](#hawksearch-index-rebuilds-hawksearchindex), `hawksearch:index:items` and `hawksearch:index:manage` for [the Indexing API](#the-indexing-api-hawksearchindex-indexitems-indexmanage), `hawksearch:recommendations` for [recommendations](#hawksearch-recommendations-hawksearchrecommendations), `storage` for [storage](#storage-storage), `lambdas:invoke` for [external Lambdas](#external-lambdas-lambdasinvoke), `ai:invoke` for [AI](#ai-aiinvoke), `assistant` to [ask the host's assistant](#ask-the-hosts-assistant-assistant). |
+| `scopes` | `reports:read` for analytics, `hawksearch:read` for the dashboard API, `hawksearch:write` to [write to it](#writing-to-hawksearch-hawksearchwrite), `data:read` for [custom queries](#custom-data-queries-dataread), `functions:invoke` for [functions](#functions-functionsinvoke), `email:send` for [email](#email-emailsend), `hawksearch:sysparams:write` for [system parameters](#hawksearch-system-parameters-hawksearchsysparamswrite), `hawksearch:search` for [search](#hawksearch-search-hawksearchsearch), `hawksearch:features:write` for [features](#hawksearch-features-hawksearchfeatureswrite), `hawksearch:index` for [index rebuilds](#hawksearch-index-rebuilds-hawksearchindex), `hawksearch:index:items` and `hawksearch:index:manage` for [the Indexing API](#the-indexing-api-hawksearchindex-indexitems-indexmanage), `hawksearch:recommendations` for [recommendations](#hawksearch-recommendations-hawksearchrecommendations), `hawkai:read` for [HawkAI](#hawkai-agents-and-smart-responses-hawkairead), `storage` for [storage](#storage-storage), `lambdas:invoke` for [external Lambdas](#external-lambdas-lambdasinvoke), `ai:invoke` for [AI](#ai-aiinvoke), `assistant` to [ask the host's assistant](#ask-the-hosts-assistant-assistant). |
 | `functions` | Your [functions](#functions-functionsinvoke) and their settings: `{ "<name>": { "job", "timeoutSeconds", "memoryMb", "secrets" } }`. Recorded with each version. |
 | `schedules` | [Schedules](#schedules) for job functions: `{ "<name>": { "function", "cron", "timezone" } }`, at most 5, at most hourly. Needs `functions:invoke`. Reviewed like scopes. |
+| `events` | [Events](#events): a job function per event (`client.added`, `config.changed`, `version.released`, `hawksearch.changed`, `index.rebuilt`), `{ "<event>": { "function" } }` (`hawksearch.changed` also takes `sections`). Needs `functions:invoke`. Reviewed like scopes. |
+| `actions` | [Actions](#actions-start-the-app-from-hawksearchs-screens): buttons in HawkSearch's pages that open a view in a dialog, `{ "<name>": { "label", "view", "targets": { "hawksearch": [{ "path", "selector", "anchor"?, "position"?, "params" }] } } }` (at most 10). Always reviewed by an approver. |
+| `api` | [Client API](#client-api): endpoints the client's systems call with their HawkSearch site API key, `{ "<name>": { "function", "method"?: "GET" \| "POST", "description"? } }`, each a function that isn't a job (at most 10). Needs `functions:invoke`. Reviewed like scopes. |
 | `systemParameters` | The HawkSearch [system parameters](#hawksearch-system-parameters-hawksearchsysparamswrite) the app may read and set, e.g. `["Timezone"]`. Needs `hawksearch:sysparams:write`. Reviewed like scopes. |
 | `config` | [App config](#app-config) keys: `{ "<key>": { "type", "label", "description", "default" } }`, at most 50. The values are set outside the file (portal or `npx hawk-app config`) and aren't secret. Reviewed like scopes. |
 | `externalOrigins` | Outside origins for scripts, styles, fonts, images, frames and API calls. New apps start with `[]` (none; the vanilla template: `["https://cdn.jsdelivr.net"]`). `["https://api.example.com", "https://*.cdn.example.com"]` allows only those. `["*"]` (also what a missing field means) allows any https origin and fails the review check. https or wss, no paths. Entries starting with `img:` are for images only: `"img:*"` (any https origin, e.g. a client's product images) or `"img:https://cdn.example.com"`. |
@@ -1287,8 +1643,8 @@ HawkSearch. See [versions, statuses and aliases](../../docs/versions-and-aliases
 - Client changes (Hawk Analytics portal or `npx hawk-app clients`) apply at once, without a deploy or approval, and
   are recorded in the app's history.
 - Approvers can set an app to **auto-approve**, so new versions and changes are released straight away.
-- Apps using queries, functions, system parameters, dashboard writes, AI, external Lambdas, HawkSearch features or index
-  rebuilds are never auto-approved.
+- Apps using queries, functions, system parameters, dashboard writes, AI, external Lambdas, HawkSearch features, index
+  rebuilds or [actions](#actions-start-the-app-from-hawksearchs-screens) are never auto-approved.
 
 **Approval.** Members of the Hawk-App-Developers group submit a draft, new version or settings change for approval in HawkSearch; members of
 the Hawk-App-Approvers group approve, reject (with a reason) or force approve it. A new deploy or settings change clears a

package/docs/showcase/hawk-app.json

@@ -3,7 +3,7 @@
   "slug": "showcase",
   "name": "Hawk Apps Showcase",
   "icon": "icon.svg",
-  "description": "Every Hawk Apps feature in one app: context, analytics, dashboard API, search, queries, functions, jobs, system parameters, storage, app config, AI and host messages.",
+  "description": "Every Hawk Apps feature in one app: context, analytics, dashboard API, search, preview tools, HawkAI, queries, functions, jobs, system parameters, storage, app config, AI and host messages.",
   "category": "Showcase",
   "version": "0.1.0",
   "visibility": "internal",
@@ -21,7 +21,8 @@
     "hawksearch:index",
     "hawksearch:index:items",
     "ai:invoke",
-    "storage"
+    "storage",
+    "hawkai:read"
   ],
   "systemParameters": [
     "Timezone",
@@ -41,7 +42,11 @@
       "label": "Notification recipients"
     }
   },
-  "externalOrigins": [],
+  "externalOrigins": [
+    "https://cdn.jsdelivr.net",
+    "https://assistant-dev.hawksearch.net",
+    "https://assistant.hawksearch.net"
+  ],
   "functions": {
     "echo": {
       "timeoutSeconds": 10,