@bridgeline-digital/hawk-app-cli 0.1.0-dev.20261020202308 → 0.1.0

package/docs/bridge/README.md

@@ -1,1315 +1,1315 @@
-# @bridgeline-digital/hawk-app-bridge
-
-Build **Hawk Apps**: small tools that run inside the HawkSearch dashboard. Your app gets the
-signed-in user's context (client, engine) and the client's data through this package, with **no API
-keys in your code**.
-
-Guides, the full API reference and the CLI are at **[developers.hawksearchapps.com](https://developers.hawksearchapps.com)**
-(sign in with your Bridgeline account).
-
-- Any static front end works: React, Next.js (static export), Vue, plain HTML. Apps are static files on the apps CDN;
-  there is no server of your own.
-- Pair it with the CLI, [`@bridgeline-digital/hawk-app-cli`](https://www.npmjs.com/package/@bridgeline-digital/hawk-app-cli),
-  to create, run locally and deploy apps.
-
-## Quick start
-
-```bash
-npx @bridgeline-digital/hawk-app-cli@latest create my-tool --template react --install
-cd my-tool
-npx hawk-app sso   # once per machine: sign in with your Bridgeline account
-npm run app:dev    # the app in a local stand-in for HawkSearch, with a client's data
-```
-
-The first time, `app:dev` asks for part of a client's name and saves your pick in `.env.local`
-(`npm run app:dev -- --client <id>` picks another).
-
-The template is already wired to this package. You can also open it inside HawkSearch in
-[dev mode](#local-development). When it's ready:
-
-```bash
-npm run app:deploy   # build and upload a new version, with hawk-app.json (no folder needed)
-npx hawk-app open    # the app in HawkSearch: review it and submit it for approval
-```
-
-New versions are drafts that only Bridgeline staff see; an approver releases them from the Apps page in HawkSearch (see
-[`hawk-app.json`](#hawk-appjson)).
-
-## Connect to the host
-
-```ts
-import { createApp } from '@bridgeline-digital/hawk-app-bridge/client';
-
-const app = await createApp({ autoResize: true });
-
-render(app.context);
-app.onContextChange((context) => render(context)); // the user switched client, engine or dates
-```
-
-**Where the app is visible.** A frame that grows with its content (auto-resize) can be much taller than the screen, so
-a dialog centered in the frame may open off screen. The host reports the visible part of the frame: `app.viewport`
-(`{ top, height }` in px from the frame's top), `app.onViewportChange(listener)`, and the CSS variables
-`--hawk-visible-top` and `--hawk-visible-height`. The UI kit's theme (`@bridgeline-digital/hawk-app-ui`, in the next-mui template) uses them to place MUI dialogs and
-snackbars; other apps can do the same in CSS, e.g.
-`.modal { position: absolute; top: calc(var(--hawk-visible-top, 0px) + 40px); }`.
-
-`createApp` resolves once the host has answered with the context. It rejects with code `not_embedded` when the page
-is opened directly instead of inside a host: show a friendly message (the templates do).
-
-You don't configure which hosts may embed your app: the platform does. The apps CDN only lets the HawkSearch dashboard and Spark frame
-an app, and the bridge only talks to the window that embedded it.
-
-| Option | Default | |
-|---|---|---|
-| `autoResize` | `false` | Keep the frame as tall as your content. Leave it off for full-height layouts. |
-| `applyTheme` | `true` | Apply the host theme as `--hawk-*` CSS variables. |
-| `timeoutMs` | `10000` | How long to wait for the host to answer a request. |
-
-## Context
-
-`app.context` is always current; `onContextChange` tells you when it changes.
-
-| Field | Example | |
-|---|---|---|
-| `tenant.clientId` | `"e3141"` | The client the user is working in. All data calls are scoped to it automatically. |
-| `tenant.analyticsProvisioned` | `false` | `false` when the client has no analytics data set up: show a message instead of calling `app.data` or `app.analytics` (they'd fail with `data_not_available` / `analytics_not_available`). Missing when the host doesn't say. |
-| `engine` | `{ id: "3141", name: "Outdoor Demo" }` | The engine selected in the host, if any. |
-| `site` | `{ id, name }` | The site, if the host has one selected. |
-| `dateRange` | `{ from: "2026-09-01", to: "2026-09-30", timeZone: "UTC" }` | The host's date picker. Analytics calls use it by default. |
-| `user` | `{ id, email, roles }` | The signed-in user. |
-| `locale` | `"en-US"` | Format numbers and dates with it. |
-| `theme` | `{ mode: "light", tokens }` | Also applied as CSS variables (see [Look and feel](#look-and-feel)). |
-| `features` | `{ assistant: true }` | What the host offers the app, e.g. `features.assistant`: the host's Hawk Assistant can be opened (see [Ask the host's assistant](#ask-the-hosts-assistant-assistant)). |
-| `view` | `{ name: "preview", params, embedded: true, maxHeight }` | The view showing, or null for the full app (see [Views](#views-an-app-inside-other-pages)). |
-| `app.slug` | `"my-tool"` | Your app. |
-
-## Views: an app inside other pages
-
-Besides its own page, an app can show **views**: pages of the same build that hosts show inside other pages. Declare
-them in `hawk-app.json`:
-
-```json
-"views": {
-  "preview": { "path": "views/preview", "title": "Price position", "height": 220, "cacheMinutes": 60 },
-  "product": { "path": "views/product", "title": "This product", "embeddable": true, "params": ["sku"] }
-}
-```
-
-- **`preview`** is shown on the Apps page under the app's description.
-- **Embeddable views** can be placed by Bridgeline users in other pages (the report builder, later Spark pages).
-- **Each view is a page at `<entry>/<path>/`,** e.g. a Next.js route `src/app/views/preview/page.tsx`, with the same
-  version, scopes and token as the app.
-- **`app.context.view`** says which view is showing and what the page passed in:
-  `{ name, params: { sku: 'A-1' }, embedded: true, maxHeight }`. It's null for the full app.
-- **Keep views small and fast.** A `preview` shares the Apps page with every other app, so read the app's stored
-  results rather than run reports or queries.
-- **`cacheMinutes` caches a view's reads** (0–1440; a `preview` caches 60 minutes unless it says otherwise, other views not at all): the platform keeps the answers to the view's data
-  queries, analytics reports, `dashboard.get`, search and recommendations for that long, per client and engine, and
-  answers the same call again from them. Set `"cacheMinutes": 0` on a preview that must always be fresh. The full app page is never cached,
-  and a new version starts fresh. A cached `data.query` result has `cachedAt` (when it was stored). Pass
-  `{ cache: 'reload' }` to ask the source again (and store the new answer), or `{ cache: 'no-store' }` for a call
-  that must not be cached, e.g. an analytics report that records something. Engineering can shorten or stop it per
-  app in the Hawk Analytics portal.
-- **`views` is a setting:** on a released app, changes wait for approval.
-- **A view's page is transparent:** the bridge marks it `data-hawk-view="<name>"` on `<html>` and clears the page
-  background, so the host's shows through. To paint one, set it on the view's content, or with
-  `html[data-hawk-view] body { … }`.
-- **A view fits its content:** it starts at its declared `height`, then auto-resize (on by default in a view) sizes it
-  to the content, within the container's `min-height` and `max-height`. Don't set `html, body { height: 100% }` in a
-  view, or it can't shrink.
-- **In a view**, toasts and title changes are ignored (the page isn't the app's), the height grows with
-  `app.resize()` up to `maxHeight`, and `app.navigate({ intent: 'app', slug })` opens the full app.
-- **The trial view** of a store app (`"trial": true`, one at most, no params) runs on its store card for clients that
-  don't have the app, on their own data. There `app.context.trial` is `true` and the token has only the app's
-  read-only scopes (`reports:read`, `hawksearch:read`, `hawksearch:search`, `hawksearch:recommendations`,
-  `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.
-
-### Hosts: `<hawk-app-container>`
-
-Configure once per page, then place containers anywhere:
-
-```ts
-import { configureHawkAppContainers, defineHawkAppContainer } from '@bridgeline-digital/hawk-app-bridge/host';
-
-defineHawkAppContainer();
-configureHawkAppContainers({
-    // From the registry: the app's entry URL plus the view's path; null hides the view. { trial }: the store listing's trial view.
-    resolveView: async (app, view, options) => ({ src, title, height, appName, description, params }),
-    // The app's context now and on every change; return a function that stops the updates.
-    watchContext: (app, listener) => subscribe(app, listener),
-    // { trial }: a trial token (POST /token/exchange with trial: true).
-    getToken: (app, { forceRefresh, trial }) => exchangeToken(app, forceRefresh, trial),
-    // { trial }: the client doesn't have the app: offer a request instead.
-    openApp: (app, params, options) => (options?.trial ? offerRequest(app) : router.open(app, params)),
-});
-```
-
-```html
-<hawk-app-container app="price-watch" view="preview" max-height="320" fallback="Compare your prices."></hawk-app-container>
-```
-
-- **Attributes:** `app`, `view` (default `preview`), `params` (a JSON object; only names the view declares are passed),
-  `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`).
-- **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
-  placeholder uses `--hawk-app-container-radius` and `--hawk-app-container-placeholder`.
-
-### Hosts: `<hawk-app-slot>`
-
-A place in a host page where Bridgeline users put an app view, saved on the platform per engine or for every client:
-
-```ts
-import { configureHawkAppSlots, defineHawkAppSlot } from '@bridgeline-digital/hawk-app-bridge/host';
-
-defineHawkAppSlot(); // also defines <hawk-app-container>: configure it as above
-configureHawkAppSlots({
-    canEdit: isBridgelineUser,
-    getSlots: (ids) => backend.get(`/slots?ids=${ids}`), // the platform's GET /slots, through the host backend
-    listChoices: async () => appsWithPlaceableViews, // [{ app, name, views: [{ name, title, params }] }]
-    saveSlot: (slot, change) => backend.put(`/slots/${slot}`, change), // { scope, app, view, params, minHeight, maxHeight }
-    removeSlot: (slot, scope) => backend.delete(`/slots/${slot}?scope=${scope}`),
-    appHref: (app) => `/apps/${app}`, // the app's page: the icon link's href
-    openApp: (app) => router.open(app), // a plain click on the icon link
-});
-```
-
-```html
-<hawk-app-slot slot-id="dashboard.top"></hawk-app-slot>
-```
-
-- **Clients** see the placement in a `<hawk-app-container>` (light DOM: style it with `hawk-app-slot > hawk-app-container`);
-  an empty slot is `hidden`.
-- **Editors** (`canEdit`) get a pencil button (a "Place an app" placeholder when empty) opening a form: app, view (or
-  *Entire app*: the app's own page, `<hawk-app-container full-app>`), the view's params, min and max height, *Show a
-  link to open the app* (an icon in the slot's corner; not for the entire app), and *This engine only* or *All
-  clients*. It fires `hawk-slot-change` after a save
-  or remove.
-- **Slots on a page load in one call** (`getSlots` gets every id requested in the same task).
-- **Texts:** `labels` (defaults `DEFAULT_SLOT_LABELS`). Theme: `--hawk-slot-accent`, `--hawk-slot-text`,
-  `--hawk-slot-muted`, `--hawk-slot-border`, `--hawk-slot-surface`, `--hawk-slot-font`, `--hawk-slot-radius`.
-- **The host backend adds the client, engine and editor** from its session: never from the browser.
-
-### Hosts: `<hawk-app-icon>`
-
-An app's icon, from the registry's `iconUrl` and `iconKind` (registered by `defineHawkAppIcon()`, and by
-`defineHawkAppFrame()`, `defineHawkAppContainer()` and `defineHawkAppSlot()`):
-
-```html
-<hawk-app-icon src="https://apps.example.com/price-watch/v3/icon.svg" kind="svg"></hawk-app-icon>
-```
-
-- **Attributes:** `src`, `kind` (`svg` or `png`), `label` (the accessible name; without it the icon is decorative).
-- **`svg` is drawn in the host's color:** only its shape counts, filled with `currentColor` (a CSS mask), like the
-  host's own icons in light and dark themes. **`png` is shown as is.**
-- **No `src`, or one that fails to load:** a built-in default app icon, in `currentColor`.
-- **Size and color:** it fills its own box, 24 × 24 px by default: set `width`, `height` and `color` on it. The
-  `state` attribute (`svg`, `png`, `default`) says what it shows.
-
-## Data
-
-Every call goes through the Hawk Apps Platform with a short-lived app token. The platform adds the credentials
-server-side and takes the client from the signed token, so an app can only ever read the current client's data. Ask
-for the scopes you need in `hawk-app.json`.
-
-### Analytics reports: `reports:read`
-
-```ts
-const top = await app.analytics.report('queries', { limit: 20 });
-// { columns: [{ name, type }], data: [...rows], totalRecords, page, hasMore }
-
-const lastWeek = await app.analytics.report('searches', { startDate: '2026-09-24', endDate: '2026-09-30' });
-```
-
-Dates default to the host's date range. Request options: `startDate`, `endDate`, `limit` (default 100), `page`,
-`filters` and `having` (`{ member, operator, values }`), as in the
-[HawkSearch Analytics API](https://developers.analytics.hawksearch.com/), which documents each report's columns.
-Data refreshes nightly. A third argument takes `{ signal?, cache? }`; in a caching view, pass `{ cache: 'no-store' }`
-for a report that records something (see [Views](#views-an-app-inside-other-pages)).
-
-**Typed reports.** The bridge knows every report in the analytics API's spec: `report('searches')` returns typed rows,
-with numbers and booleans converted from the strings the API sends (`row.search_count` is a number), and `filters`
-and `having` take only that report's fields. A renamed or removed column fails your build once you update the bridge,
-instead of showing blanks. `AnalyticsReportRow<'searches'>` is a row's type. The writes are typed too:
-`report('ai-advisor-feedback', { recommendationId, engineId, feedback })` returns `{ feedback }`.
-
-```ts
-const { data } = await app.analytics.report('assistant-activity', {
-    filters: [{ member: 'model_id', operator: 'equals', values: ['…'] }], // only this report's fields
-});
-const tokens = data.reduce((sum, row) => sum + row.total_tokens, 0); // numbers, not "123"
-```
-
-Every report the analytics API has can be called, by its path without the slash (`assistant-prompts`); new ones need
-no bridge or platform change: a report newer than your bridge returns untyped rows (`report<MyRow>('new-report')`),
-with values as the API sends them. Passing your own row type to a known report (`report<MyRow>('searches')`) opts out
-of its types, though its values are still converted. `report('', { query: '…' })` is the API's ad-hoc / natural-language query. For the list,
-each report's columns and its `filters`/`having` fields, see the
-[developer portal](https://developers.analytics.hawksearch.com/) (the dev platform uses the dev analytics API:
-[its spec](https://developers.analytics.hawksearch.com/dev/openapi.yaml)), or ask your assistant: the `hawk-apps` MCP
-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');
-// Query parameters: app.dashboard.get('LandingPage', { query: { ... } })
-```
-
-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
-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.
-
-### Writing to HawkSearch: `hawksearch:write`
-
-```ts
-// Create a synonym
-const synonym = await app.dashboard.post('Synonym', {
-  SearchTerm: 'sneakers',
-  SynonymGroup: 'trainers,running shoes',
-  MultiWay: true,
-});
-
-// Update a redirect
-await app.dashboard.put('Redirect/42', { ...redirect, NewUrl: '/sale' });
-
-// Delete a banner
-await app.dashboard.delete('Banner/7');
-```
-
-`app.dashboard.post(path, body?)`, `put(path, body?)` and `delete(path)` (also on `ctx.platform.dashboard` in
-[functions](#functions-functionsinvoke)) send the body as JSON to the
-[HawkSearch Dashboard API](https://developerdocs.hawksearch.com/reference/getting-started-with-your-api) and resolve
-to HawkSearch's response body (`undefined` when it's empty). Paths work as for `get`: no API version (`Synonym`,
-`Synonym/123`, `LandingPage/bulk`); each segment is URL-encoded for you.
-
-- **Scope**: add `"hawksearch:write"` to `scopes` in `hawk-app.json` (reviewed like any scope). Reading stays under
-  `hawksearch:read`; ask for both if you read what you write.
-- **Allowed resources**: `Banner`, `BoostBury`, `Campaign`, `Visibility`, `VisitorTarget`, `Redirect`, `Synonym`,
-  `SpellCheck`, `PaginationSet`, `SortingSet`, `RecommendationVisibility`, `LandingPageLayout`, `Facet` and
-  `LandingPage` (and their sub-paths). Anything else, e.g. `Field`, fails with 403 `path_not_allowed`; so do bulk
-  landing-page deletes.
-- **Limits**: bodies up to 5 MB, bulk requests up to 1000 items, and 120 writes per minute per app and client.
-- **Site keys only**: writes go through a site's own HawkSearch API key. When the client is connected with a group
-  key, writes fail with 403 `hawksearch_write_needs_site_key` (reads still work).
-- **Audited**: every write is audit-logged by the platform (which app, for which client, by which user).
-- **Not retried**: writes aren't idempotent, so the bridge sends each one once. A 429 `too_many_requests` is thrown
-  with `error.retryAfterMs`; wait at least that long before you try again, and only if repeating the write is safe.
-
-| Code | Status | Meaning |
-|---|---|---|
-| `scope_missing` | 403 | The app doesn't have the `hawksearch:write` scope. |
-| `path_not_allowed` | 403 | The resource isn't one of the allowed ones above (or it's a bulk landing-page delete). |
-| `hawksearch_write_needs_site_key` | 403 | The client is connected with a group key; writes need a site key. |
-| `request_too_large` | 413 | The body is over 5 MB. |
-| `too_many_items` | 400 | A bulk request has more than 1000 items. |
-| `too_many_requests` | 429 | Over 120 writes a minute for this app and client; `retryAfterMs` says when to try again. Not retried. |
-| `invalid_path` | 400 | The path is malformed (the bridge also rejects empty paths and `.`/`..` segments with a `TypeError`). |
-| `version_not_allowed` | 400 | You put an API version in the path: use `Synonym`, not `v11/Synonym`. |
-| `hawksearch_unavailable` | 502 | HawkSearch couldn't be reached: the write may or may not have happened, so check before you repeat it. |
-| `hawksearch_credentials_rejected` | 502 | HawkSearch rejected the client's API key: tell Engineering. |
-
-HawkSearch's own validation errors (e.g. 400 for a missing required field, 404 for an unknown id) come back as
-`HawkApiError` with HawkSearch's status and its response in `error.body`.
-
-### Custom data (queries): `data:read`
-
-When the reports don't have what you need, ship your own SQL with the app. Each query is two files in `queries/`,
-next to `hawk-app.json` (not in the build folder); `hawk-app deploy` checks them and deploys them with the version,
-and Bridgeline staff see them when they review it. The platform runs them (Amazon Athena) against the **current
-client's** analytics tables only: the client comes from the app token, never from the app.
-
-```sql
--- queries/top-searches.sql: one SELECT (or WITH … SELECT), plain table names, ? for each parameter in order
-SELECT search_date, sum(search_count) AS searches
-FROM dailysearches
-WHERE search_date BETWEEN ? AND ?
-  AND {{partitions(from, to)}}
-GROUP BY 1
-ORDER BY 1
-```
-
-```json
-{
-    "params": [
-        { "name": "from", "type": "date", "required": true },
-        { "name": "to", "type": "date", "required": true }
-    ]
-}
-```
-
-(`queries/top-searches.json`. `from` and `to` bind the two `?`s, in order.)
-
-```ts
-// `date` params are "YYYY-MM-DD"; the host's date range is full ISO timestamps, so cut them to the day.
-const day = (iso: string) => iso.slice(0, 10);
-const { from, to } = app.context.dateRange!;
-
-const { columns, rows, bytesScanned, cached } = await app.data.query<{ search_date: string; searches: number }>('top-searches', {
-    from: day(from),
-    to: day(to),
-});
-// rows: [{ search_date: '2026-09-01', searches: 1204 }, ...]
-```
-
-`app.data.query(name, params?, { signal?, timeoutMs?, cache? })` resolves to `{ columns: [{ name, type }], rows, rowCount,
-bytesScanned, cached, cachedAt }` (`cachedAt`: when the platform's view cache stored the rows, else null; `cache`:
-`'reload'` or `'no-store'`, see [Views](#views-an-app-inside-other-pages)). Rows are objects keyed by column name, typed: numbers for integer/decimal/double columns,
-booleans, ISO strings for dates and timestamps, `null` for nulls. Long queries are polled for you (1 s, 2 s, 4 s, then
-every 5 s) until they finish or `timeoutMs` (default 120 s) passes; pass an `AbortSignal` to stop waiting (the
-promise rejects with an `AbortError`). When too many queries are running (429 `too_many_queries`) the call waits and
-tries again (1 s, 2 s, 4 s, then every 5 s, never sooner than the platform's `Retry-After`), until `timeoutMs`; only
-then does it reject with the 429. `cached` is `true` when the result wasn't computed for this call: Athena reused a
-recent result of the same query and parameters, or an identical request made moments earlier was already running it.
-
-**Parameters** are declared in `<name>.json`, in the order of the `?`s in the SQL, and are always sent as query
-parameters (never pasted into the SQL):
-
-| Type | Value |
-|---|---|
-| `string` | up to 1000 characters |
-| `int`, `decimal` | a number; `min` / `max` optional |
-| `date` | `"YYYY-MM-DD"` |
-| `timestamp` | ISO 8601, e.g. `"2026-09-01T00:00:00Z"` |
-| `boolean` | `true` / `false` |
-| `string[]` | up to 100 strings (`maxItems` to lower it); counts as **one** `?`, written `IN ?` (it becomes `IN (?, ?, …)`) |
-
-Each param has a `name` and `type`, and optionally `required`, `default`, `min`/`max` (numbers) and `maxItems`
-(`string[]`). The number of `?`s must equal the number of params.
-
-**`{{partitions(from, to)}}`** limits the scan to the months between two `date` params (both must be declared
-`date`; they still bind their own `?`s). Use it on every query with a date range: most tables are partitioned by
-year/month, so without it a query reads the client's whole history. Add the table alias as a third argument when the
-query joins tables: `{{partitions(from, to, d)}}`. On a table that isn't partitioned it becomes `TRUE`.
-
-**Tables:** `apiusage`, `dailysearches`, `dailyusers`, `dailyrequests`, `geodistribution`, `redirecttracking`,
-`productimpressions`, `searchfunnel`, `pageloads`, `analyticsapilogs`, `queries`, `clickpositions`, `facets`,
-`sortingtracking`, `paginationtracking`, `poorresults`, `dailyspelling`, `salesbydate`, `salesbykeyword`,
-`salesbyproduct`, `recommendations`, `campaigns`, `banners`, `autocompleteclicks`, `autocompletetrendingcategories`,
-`autocompletetrendingitems`, `productratings`, `devicebrowser`, `landingpages`, `gacore`, `catalog`. Any other table
-fails with `TABLE_NOT_FOUND`.
-
-**Sensitive tables** hold visitor-level data or conversations: `summary`, `agentprompts`, `agentexchanges`,
-`agenttoolcalls`, `aisummary`, `facetselections`, `visitortargetselections`. An app can query them only after
-Engineering turns on **Allow sensitive data** for it (in the analytics portal; it applies to every client the app runs
-for). Until then they also fail with `TABLE_NOT_FOUND`. Ask Engineering when your app needs one, and select only the
-columns you need (counts rather than raw text where you can). `npx hawk-app data tables` and `npx hawk-app data describe <table>` show the columns, and
-`npx hawk-app data run queries/top-searches.sql --client <id> --param from=2026-09-01 --param to=2026-09-30` tries a
-query on dev before you deploy it.
-
-**Limits:** one statement per file, `SELECT`/`WITH` only, 64 KB per query, 50 queries per app, 10,000 rows / 5 MB per
-result, and a per-query scan limit (10 GB by default). Results of the same query with the same parameters are reused
-for up to 15 minutes (`cached: true`). Data refreshes nightly.
-
-**Errors** (`HawkApiError.code`):
-
-| Code | Status | Meaning |
-|---|---|---|
-| `query_not_found` | 404 | No `queries/<name>.sql` in the version the user has open. |
-| `invalid_params` | 400 | A parameter is missing or has the wrong type; `JSON.parse(error.body).errors` lists them. |
-| `query_failed` | 400 | Athena rejected or failed the query (the message says why, e.g. an unknown column). |
-| `scan_limit_exceeded` | 400 | The query reads too much data: narrow the date range or use `{{partitions(…)}}`. |
-| `result_too_large` | 413 | More than 10,000 rows or 5 MB: aggregate, filter or add `LIMIT`. |
-| `too_many_queries` | 429 | Too many queries running (at most 2 per app and client at a time): `app.data.query` already retried until `timeoutMs`. |
-| `query_timeout` | 408 | Still running after `timeoutMs` (raised by the bridge). |
-| `data_not_available` | 404 | Analytics data isn't set up for this client (when `context.tenant.analyticsProvisioned` is `false` it answers at once, without running the query). |
-| `data_unavailable` | 502 | Something is wrong on our side: retry later. |
-
-**Writing good queries**
-- Filter by date and add `{{partitions(from, to)}}`: it's what keeps queries fast and cheap.
-- Aggregate in SQL (`GROUP BY`, `sum`, `count`) and return only what the screen shows; add `LIMIT` to lists.
-- Name the columns you need instead of `SELECT *`: Athena reads only those columns.
-- Column names come back exactly as written; give computed columns an alias (`sum(x) AS searches`).
-- Run independent queries in parallel (`Promise.all`), but no more than two at a time per client: more just wait
-  their turn.
-- Show something while waiting: a first run can take a few seconds; repeats within 15 minutes are instant.
-
-### Who am I
-
-```ts
-const me = await app.api.get('me'); // { app, clientId, accountId, userId, scopes, internal }
-// internal: true for Bridgeline staff (from the signed token), e.g. to show a staff-only tab
-```
-
-## Functions: `functions:invoke`
-
-Server-side code that ships with your app: call a third-party API with a key the browser must never see, combine
-several platform calls, or reshape data before it reaches the app. Each function is a file in `functions/`, deployed
-with every version as an AWS Lambda function (Node 22) and called from the app with `app.functions.call`.
-
-**Engineering must enable functions for your app** (they reach the internet and can hold secrets). Until then calls
-fail with `functions_not_enabled`. A version whose functions changed (added, removed, new code or settings) **always
-needs review**, even on an auto-approve app.
-
-```
-my-app/
-  hawk-app.json        "scopes": ["functions:invoke", …],
-                       "functions": { "sync-feed": { "timeoutSeconds": 20, "memoryMb": 512, "secrets": ["FEED_API_KEY"] } }
-  functions/
-    sync-feed.ts       one entry file per function (.ts, .mts, .js or .mjs), named after it, exporting `handler`
-    lib/feed.ts        shared code goes in subfolders (or import from src/ and node_modules)
-```
-
-```ts
-// functions/sync-feed.ts
-import type { HawkFunction } from '@bridgeline-digital/hawk-app-bridge/server';
-
-export const handler: HawkFunction<{ since: string }, { items: unknown[] }> = async (input, ctx) => {
-    const response = await fetch(`https://feeds.example.com/items?since=${input.since}`, {
-        headers: { Authorization: `Bearer ${ctx.secrets.FEED_API_KEY}` },
-    });
-    if (!response.ok) throw new Error(`Feed answered ${response.status}`);
-    const top = await ctx.platform.analytics.report('searches', { startDate: input.since, limit: 10 });
-    return { items: [...(await response.json()), ...top.data] };
-};
-```
-
-```ts
-// In the app
-const { items } = await app.functions.call<{ items: unknown[] }>('sync-feed', { since: '2026-09-01' });
-```
-
-`app.functions.call(name, input?, { signal?, timeoutMs? })` posts `input` (any JSON, up to 256 KB) and resolves to
-what `handler` returned (up to 6 MB). It waits up to `timeoutMs` (default 30 s) and retries while the platform answers
-429 (too many calls running), like data queries.
-
-**`ctx`** (`HawkFunctionContext`)
-
-| | |
-|---|---|
-| `ctx.client.id` | The HawkSearch client the app is running for. |
-| `ctx.user` | `{ id, email, roles }` of the caller; `ctx.internal` is true for Bridgeline staff. |
-| `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.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
-bundles it with every dependency, so the app needs this package installed (0.4.0 or later). The `/server` entry has
-no DOM; `createPlatformClient({ apiBaseUrl, token })` gives you the same `ctx.platform` in tests or scripts.
-
-**Settings** (per function in `hawk-app.json`; all optional): `job` (a [background job](#background-jobs), default
-false), `timeoutSeconds` 1–25 (default 10; 1–900 for a job, default 300), `memoryMb` 128–1024
-(default 256; more memory also means more CPU), `secrets` up to 20 names. At most 10 functions per app; names are
-lowercase letters, digits and dashes, up to 40 characters. Bundles are limited to 10 MB zipped, the `functions/`
-sources to 5 MB.
-
-**Secrets** are set with the CLI, never in code or in the app: `npx hawk-app secrets set FEED_API_KEY` (input hidden;
-`--value-from-env VAR` in CI), at most 4 KB each; the platform stores them encrypted. They belong to the app, not a
-version: a change applies to every version at once. A function receives only the secrets it declares; a declared secret
-that isn't set fails the call with `secret_missing`.
-
-**Client secrets** hold values that belong to each client, such as their own email platform's API key. Declare the
-names on the function (`"clientSecrets": ["MAILCHIMP_API_KEY"]`, up to 10). The client's users set them in the app,
-the function reads the calling client's value, and nobody can read a value back:
-
-```ts
-const list = await app.clientSecrets.list();            // [{ name, set, updatedAt }]
-await app.clientSecrets.set('MAILCHIMP_API_KEY', key);  // write-only, at most 4 KB
-await app.clientSecrets.delete('MAILCHIMP_API_KEY');
-// In the function: ctx.clientSecrets.MAILCHIMP_API_KEY (missing when the client hasn't set it).
-```
-
-**Logs**: `console.log` / `console.error` in a function go to its log, kept 30 days:
-`npx hawk-app logs sync-feed --since 1h --follow`. Never log secrets, tokens or personal data.
-
-**Errors** come back to the app as `HawkApiError`:
-
-| Code | Status | Meaning |
-|---|---|---|
-| `function_failed` | 502 | `handler` threw. The response has only the error's name (`errorType`); the message and stack are in the logs. |
-| `function_timeout` | 504 / 408 | The function ran past its `timeoutSeconds` (504), or the call past `timeoutMs` (408, raised by the bridge). |
-| `result_too_large` | 502 | The result is over 6 MB. |
-| `request_too_large` | 413 | The input is over 256 KB. |
-| `too_many_requests` | 429 | Too many calls running at once: `app.functions.call` already retried until `timeoutMs`. |
-| `function_not_found` | 404 | The version the caller has open has no such function (deploy it first). |
-| `function_is_job` / `function_not_job` | 409 | `call` on a job function (use `start`), or `start` on a normal one. |
-| `functions_not_enabled` | 403 | Engineering hasn't enabled functions for the app. |
-| `secret_missing` | 500 | A declared secret isn't set: `npx hawk-app secrets set <NAME>`. |
-
-Good to know: a function runs **as the caller**, for the caller's client, so scope anything you store by
-`ctx.client.id`. Functions are stateless and short (25 s at most, or 900 s for a job); keep nothing between calls
-that you can't lose.
-
-### Background jobs
-
-Work that takes longer than a call (a full export, a batch of dashboard writes, a nightly report) goes in a **job
-function**: `"job": true` in `hawk-app.json`. The app starts it, gets a job id at once, and reads the result later.
-
-```jsonc
-"functions": {
-    "export-report": { "job": true, "timeoutSeconds": 600 }
-}
-```
-
-```ts
-// functions/export-report.ts
-export const handler: HawkFunction<{ month: string }, { rows: number }> = async (input, ctx) => {
-    const pages = await loadPages(input.month);
-    for (const [i, page] of pages.entries()) {
-        await writePage(page);
-        await ctx.job?.progress(Math.round(((i + 1) / pages.length) * 100), `Page ${i + 1} of ${pages.length}`);
-    }
-    return { rows: pages.length };
-};
-```
-
-```ts
-// In the app
-const { jobId } = await app.functions.start('export-report', { month: '2026-09' });
-try {
-    const job = await app.functions.wait<{ rows: number }>(jobId, {
-        onProgress: (j) => setStatus(j.progress?.message ?? j.status),
-    });
-    console.log(job.result!.rows);
-} catch (error) {
-    if (error instanceof FunctionJobError) console.log(error.job.status, error.job.error?.type); // failed / timed_out
-}
-```
-
-- `app.functions.start(name, input?, { signal? })` resolves to `{ jobId }` once the job is queued (202). A job
-  function can only be started and a normal function only called (409 `function_is_job` / `function_not_job`).
-- `app.functions.wait(jobId, { timeoutMs?, intervalMs?, onProgress?, signal? })` checks the job every `intervalMs`
-  (default 2 s) and resolves with the `succeeded` job; it throws `FunctionJobError` (with `.job`) when the job
-  `failed` or `timed_out`, and HawkApiError 408 `job_wait_timeout` after `timeoutMs` (default 15 min; the job keeps
-  running). `onProgress` gets the job whenever its status or progress changes.
-- `app.functions.job(jobId)` reads it once: `{ jobId, function, status, progress, result, error, createdAt,
-  finishedAt, trigger }`, `status` one of `queued`, `running`, `succeeded`, `failed`, `timed_out`. Store the id to
-  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 }`.
-- `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
-`too_many_jobs`, not retried); results up to 256 KB; jobs are kept 7 days (then 404 `job_not_found`, also for
-another app's or client's job). A job isn't retried when it fails.
-
-### Schedules
-
-`schedules` in `hawk-app.json` run a job function on a timer. A schedule does nothing until a user turns it on from
-the app, for their client: `app.schedules.enable(name)`.
-
-```jsonc
-"functions": { "nightly-report": { "job": true, "timeoutSeconds": 600 } },
-"schedules": {
-    "nightly": { "function": "nightly-report", "cron": "0 7 ? * MON-FRI *", "timezone": "America/Chicago" }
-}
-```
-
-```ts
-const schedules = await app.schedules.list();
-// [{ name: 'nightly', function: 'nightly-report', cron: '0 7 ? * MON-FRI *', timezone: 'America/Chicago',
-//    enabled: false, enabledBy: null, enabledAt: null, lastRun: null }]
-await app.schedules.enable('nightly');   // or disable('nightly'); both resolve to the schedule
-```
-
-- `cron` is an EventBridge cron with 6 fields (`minutes hours day-of-month month day-of-week year`, with `?` in
-  day-of-month or day-of-week) and runs **at most hourly** (the minutes field is a single number); `timezone` is an
-  IANA name, default `UTC`. At most 5 schedules per app, each running a job function of the same manifest.
-- A scheduled run is a job (`ctx.trigger.type === 'schedule'`) for the client and site where the user turned the
-  schedule on, as the user `schedule:<name>` (no roles, not internal), with that client's HawkSearch connection. Its
-  `lastRun` shows the job it started, or `skipped` with a `reason`.
-- 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.
-
-## Email: `email:send`
-
-Send an email from the app or from a [function](#functions-functionsinvoke): a report to the user, an alert, a
-digest. The platform sends it; your app never gets mail credentials.
-
-Add `"email:send"` to `scopes` in `hawk-app.json` and deploy (`hawk-app deploy` sends hawk-app.json with the version): any app with the scope can send. Without it, sends fail
-with `scope_missing`.
-
-```ts
-// functions/weekly-digest.ts: from a function, as the caller
-import type { HawkFunction } from '@bridgeline-digital/hawk-app-bridge/server';
-
-export const handler: HawkFunction<void, { messageId: string }> = async (_input, ctx) => {
-    if (!ctx.user.email) throw new Error('The caller has no email address.');
-    const top = await ctx.platform.analytics.report('searches', { startDate: '2026-09-01', endDate: '2026-09-30', limit: 5 });
-    const { messageId } = await ctx.platform.email.send({
-        to: ctx.user.email,
-        subject: 'Your top searches',
-        text: top.data.map((row) => JSON.stringify(row)).join('
-'),
-        html: `<p>${top.data.length} rows</p>`,
-    });
-    return { messageId };
-};
-```
-
-```ts
-// Or straight from the app
-const { messageId, recipients } = await app.email.send({ to: ['a@example.com', 'b@example.com'], subject: 'Export ready', text: 'Your export is ready.' });
-```
-
-`app.email.send({ to, subject, text?, html?, replyTo? }, { signal? })` (and `ctx.platform.email.send`, the same)
-resolves to `{ messageId, recipients }`.
-
-- **Sender**: `"<App name> (HawkSearch)" <noreply@hawksearch.com>`, with your app's name. Nobody reads replies to it:
-  set `replyTo` (one address) if recipients should be able to answer.
-- **Recipients**: `to` is one address or up to 10 unique ones, plain addresses only (no display names, no cc/bcc).
-  Apps can email anyone, so only send what the recipient should see, and never secrets.
-- **Content**: `subject` 1–200 characters on one line; at least one of `text` / `html`, together at most 256 KB.
-- **Limit**: 200 recipients per app and client per UTC day (a 10-recipient send counts 10), for every version of the
-  app together. Over it, sends fail with `email_limit_reached` until UTC midnight (`error.retryAfterMs`). Sends are
-  never retried for you.
-- **Audit**: every send is logged with the app, version, client, user, recipient count and domains and the message
-  id. The subject and body are never stored.
-
-**Errors** come back as `HawkApiError`:
-
-| Code | Status | Meaning |
-|---|---|---|
-| `scope_missing` | 403 | The app doesn't have the `email:send` scope. |
-| `invalid_email` | 400 | A field is missing or wrong; the response's `errors` (in `error.body`) lists each one. |
-| `request_too_large` | 413 | The body is over 256 KB. |
-| `email_limit_reached` | 429 | The app's daily limit for this client is used up; `retryAfterMs` is the time until it resets. |
-| `email_rejected` | 400 | The mail service refused the message (e.g. an address it can't deliver to). |
-| `email_unavailable` | 502 | The mail service failed: try again later. |
-
-## HawkSearch search: `hawksearch:search`
-
-Run real HawkSearch searches and autocompletes for the engine the user is working on, live or in **preview**
-(unpublished rules, a future date): before/after checks of a rule change, "do our top queries return results?",
-zero-result hunts. From the app or from a [function](#functions-functionsinvoke) (`ctx.platform.hawksearch`).
-
-```ts
-const results = await app.hawksearch.search({ Keyword: 'boots', MaxPerPage: 24 });
-results.Pagination?.NofResults; // HawkSearch's own v2 response
-
-// Preview: unpublished rules as of a date (the engine's time zone)
-await app.hawksearch.search({ Keyword: 'boots', IsInPreview: true, SmartBar: { PreviewDate: '2026-11-27T00:00:00' } });
-
-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.
-- `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.
-- Read-only, so the scope doesn't stop an app from being auto-approved.
-
-| `error.code` | Status | Meaning |
-|---|---|---|
-| `scope_missing` | 403 | Add `hawksearch:search` to `scopes`. |
-| `engine_required` | 400 | The host session has no engine. |
-| `search_not_available` | 404 / 503 | The engine isn't active, or has no search API set up in HawkSearch. |
-| `search_needs_site_key` | 403 | The engine requires authenticated searches and the session only has a group API key. |
-| `too_many_requests` | 429 | Over the per-minute limit; wait `retryAfterMs`. |
-| `hawksearch_unavailable` | 502 | HawkSearch didn't answer: try again. |
-
-Other HawkSearch errors (e.g. `400` for an unknown `IndexName`) come back as HawkSearch sent them.
-
-## HawkSearch system parameters: `hawksearch:sysparams:write`
-
-Let users change a few HawkSearch **system parameters** of the engine they are working on (Sites → System Parameters
-in HawkSearch) from the app or from a [function](#functions-functionsinvoke), e.g. a setup wizard that sets the time
-zone and the preview URL.
-
-Add the scope and list the parameters the app may touch in `hawk-app.json`:
-
-```json
-{
-    "scopes": ["hawksearch:sysparams:write"],
-    "systemParameters": ["Timezone", "SearchPreviewURL"]
-}
-```
-
-The list is reviewed like scopes: it goes with the version, which waits for approval in HawkSearch (`hawk-app status`:
-`settings    waiting for review: systemParameters`), and only the approved list counts. Up to 50 names (letters, digits, `_`, `.`, `-`; up to 50
-characters each), matched case-insensitively. The scope needs a non-empty list, and the list needs the scope.
-
-```ts
-const { engineId, parameters } = await app.hawksearch.systemParameters.list();
-// parameters: [{ name: 'Timezone', label: 'Time zone', group: 'General', type: 'TIMEZONE',
-//                value: 'Eastern Standard Time', encrypted: false, readOnly: false }, ...]
-
-const timezone = await app.hawksearch.systemParameters.get('Timezone');
-
-const { value, previous, appliesWithinSeconds } = await app.hawksearch.systemParameters.set('Timezone', 'UTC');
-await app.hawksearch.systemParameters.set('SearchPreviewURL', null); // null or "" clears it
-// A declared parameter the engine doesn't have yet: create it (AE only, label/type optional), then set it.
-await app.hawksearch.systemParameters.set('packageTier', 'Premium', { create: { group: 'HawkAI Configuration', label: 'Package Tier' } });
-```
-
-`ctx.platform.hawksearch.systemParameters` in a function is the same, as the caller.
-
-- **Which engine**: always the user's current engine in the host (`context.engine`), sent by the host when it issues
-  the app token, never chosen by the app. After the user switches engines, the host issues tokens for the new engine.
-  Only that engine changes: it is not synchronized to the other engines of a group.
-- **Who can set**: any user who can open the app. Every change is logged in HawkSearch (the parameter's history and
-  the activity log, as `<user> via Hawk Apps (<slug>)`) and in the platform's audit log.
-- **Which parameters**: only the declared ones that exist for the engine, including "AE only" ones (shown in red in
-  HawkSearch). Encrypted, global and read-only parameters are never settable; `list` leaves out global ones and
-  returns encrypted ones with `value: null`.
-- **Values** are strings, checked against the parameter's type: `STRING` (up to 1000 characters), `EMAIL`,
-  `INTEGER`, `FLOAT`, `YESNO` (`"0"` / `"1"`; `"true"` / `"false"` are accepted), `TIMEZONE` (a Windows time zone id,
-  e.g. `"Eastern Standard Time"`), `DIMENSION` (`"width;height"`). Other types can't be set yet. Setting the current
-  value again changes nothing.
-- **When it applies**: HawkSearch caches system parameters, so a change applies within about **3 minutes**
-  (`appliesWithinSeconds`: 180). Calls are never retried for you.
-
-**Errors** come back as `HawkApiError`:
-
-| Code | Status | Meaning |
-|---|---|---|
-| `scope_missing` | 403 | The app doesn't have the `hawksearch:sysparams:write` scope. |
-| `engine_required` | 400 | The host didn't send an engine with the token (no engine selected). |
-| `engine_not_allowed` | 403 | The engine doesn't belong to the token's client. |
-| `parameter_not_found` | 404 | Not declared in `systemParameters`, or the engine has no such parameter (also for global ones; AE-only parameters work when declared). |
-| `parameter_read_only` | 403 | The parameter is read-only. |
-| `parameter_encrypted` | 400 | Encrypted parameters can't be set. |
-| `parameter_type_unsupported` | 400 | Parameters of this type can't be set yet. |
-| `invalid_value` | 400 | The value doesn't fit the parameter's type (the message says why). |
-| `hawksearch_db_unavailable` | 502 | HawkSearch couldn't be reached: try again later. |
-| `sysparams_not_configured` | 503 | System parameters aren't enabled on this platform yet. |
-
-## HawkSearch features: `hawksearch:features:write`
-
-Turn HawkSearch features on and off for the user's current engine: the Feature Configuration's additional features
-(`aiassistant`, `didYouMean`, `sortingSets`, …) and facet features (`tooltip`, `swatch`, `collapsible`, …). Add
-`"hawksearch:features:write"` to `scopes`; it's elevated (never auto-approved) and reaches every feature, paid add-ons
-included.
-
-```ts
-const { features, facetFeatures } = await app.hawksearch.features.list();   // [{ code, enabled, known }]
-await app.hawksearch.features.set('aiassistant', true);
-await app.hawksearch.features.setFacet('tooltip', false);                   // { code, enabled, known, changed, appliesWithinSeconds }
-```
-
-Each call changes one code and keeps the others. Codes HawkSearch knows are stored in its spelling; any other code of
-letters and digits is accepted (a feature HawkSearch adds later works at once) and answered with `known: false`.
-Changes apply within about 3 minutes. Errors are those of system parameters, plus `invalid_feature` (400) for a code
-that isn't 1-50 letters and digits.
-
-## HawkSearch index rebuilds: `hawksearch:index`
-
-Rebuild the user's current engine's index from its feed, as HawkSearch's Rebuild Index button does, and follow it. Add
-`"hawksearch:index"` to `scopes`; it's elevated (never auto-approved), since a rebuild reloads the client's live search.
-
-```ts
-const run = await app.hawksearch.index.rebuild();             // { notificationId, status: 'new', done: false, … }
-const final = await app.hawksearch.index.wait(run.notificationId!, {
-    onProgress: (r) => setStatus(`${r.status} (${r.count ?? 0} items)`),
-});                                                           // { status: 'success' | 'error' | …, done: true, count, durationSeconds }
-const latest = await app.hawksearch.index.status();           // the engine's latest rebuild, by anyone
-```
-
-- **Only where the engine allows it**: HawkSearch's `EnableRebuildIndex` system parameter must be on for the engine
-  (it's the switch for HawkSearch's own button). Otherwise 403 `index_rebuild_disabled`.
-- **One at a time per engine**: while a rebuild is `new`, `pending`, `processing` or `queue` (from this app or anyone),
-  `rebuild()` answers 409 `index_in_progress` with the running one in `current`. A rebuild is done when its status is
-  `success`, `error`, `duplicated` or `suspended`.
-- **Full rebuilds only**, from the engine's configured feed. There's no cancel, and progress is the status and item
-  count, not a percentage. Rebuilds take minutes: `wait` checks every 15 s by default, for up to an hour.
-- **Site keys only**: with a group key, 403 `hawksearch_index_needs_site_key` (HawkSearch would rebuild the group's
-  parent site). At most 2 rebuild requests per app and client per minute (429 `too_many_requests`). Every rebuild is
-  audit-logged (app, client, engine, user).
-- Other errors: `index_never_rebuilt` / `index_run_not_found` (404), `index_wait_timeout` (408, from `wait`),
-  `hawksearch_failed` / `hawksearch_unavailable` / `hawksearch_credentials_rejected` (502).
-
-### The Indexing API: `hawksearch:index`, `:index:items`, `:index:manage`
-
-For engines with their own indexes (HawkSearch's Indexing API), apps can read, change and manage the indexes
-themselves. Three scopes, all elevated, so an approver sees exactly what an app can do:
-
-| Scope | Calls |
-| --- | --- |
-| `hawksearch:index` | `indexes()`, `current()`, and reads with `call`: `'inactive'`, `'hierarchy'`, `'mappings'`, `'embedding/progress'`, `` `embedding/status/${id}` `` |
-| `hawksearch:index:items` | `items.upsert(items)`, `items.update(items)`, `items.delete(ids)`, and with `call`: `'add-attributes-to-items'`, `'update-attributes-of-items'`, `'remove-attributes-from-items'`, `'update-nested'`, `'remove-nested'`, `'bulk-update-nested'`, `'bulk-remove-nested'`, `'bulk-item-operations'` |
-| `hawksearch:index:manage` | `create({ suffix })`, `setCurrent(name)`, `deleteIndex(name)`, `rebuildAll(name)`, and with `call`: `'swap'`, `'rebuild-autocomplete'`, `'rebuild-percolator'`, `'rebuild-learning'`, `'rebuild-related'`, `'rebuild-embedding'`, `'hierarchy/upsert'`, `'hierarchy/rebuild'`, `'hierarchy/delete-items'`, `'hierarchy/delete-all'`, `'mappings/upsert'`, `'mappings/invalidate-cache'` |
-
-```ts
-// Update prices on the live index: each field is an array of values, with the engine's primary key.
-const result = await app.hawksearch.index.items.update([{ id: ['sku-1'], price: [79.99] }]);   // { Status, Summary, Items }
-
-// Build a new index, fill it, then switch live search to it.
-const name = await app.hawksearch.index.create({ suffix: 'spring' });
-await app.hawksearch.index.items.upsert(batch, { indexName: name });   // up to 125 items a call
-await app.hawksearch.index.rebuildAll(name);
-await app.hawksearch.index.setCurrent(name);
-```
-
-- **Live at once.** Item writes default to the engine's current index, and HawkSearch applies them immediately. Pass
-  `indexName` to change another one. HawkSearch checks each item against the engine's fields and primary key: a write
-  with any failed item is a 400 with HawkSearch's per-item `Status`.
-- **Limits:** 125 items (or 1000 ids) per call, 5 MB; 120 item writes and 10 management calls per app and client per
-  minute (429 `too_many_requests`). Site keys only. Writes are audit-logged (operation, index, count), never retried.
-- **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.
-
-## HawkSearch recommendations: `hawksearch:recommendations`
-
-HawkSearch's recommendation widgets for the user's current engine, as its storefront gets them. Add
-`"hawksearch:recommendations"` to `scopes` (not elevated: read-only storefront results).
-
-```ts
-const { widgetItems } = await app.hawksearch.recommendations({
-    widgetUids: [{ widgetGuid: '8a6d…', uniqueId: 'sku-1' }],      // the widget, and the product being viewed (if its model needs one)
-    contextProperties: { uniqueidlist: 'sku-1,sku-2' },            // e.g. a cart
-});
-for (const item of widgetItems?.[0]?.recommendationItems ?? []) console.log(item.itemName, item.price);
-```
-
-The request is HawkSearch's own ([Recommendation API](https://developerdocs.hawksearch.com/docs/recommendation-api)):
-`widgetUids` for one context, or `widgets` (up to 10, each with its own `contextProperties`) for the bulk endpoint;
-`renderHTML: true` for the widget's HTML; `enablePreview` for preview rules. The platform sets the engine's
-`clientGuid`, adds a random `visitorId` and `visitId` when you send none (send the shopper's to personalize), and never
-lets the request count in the client's recommendation reports. Widget guids are on HawkSearch's Recommendations page (or
-`app.dashboard.get(...)` with `hawksearch:read`). Limited to 600 requests per app and client per minute (429
-`too_many_requests`). Errors: `invalid_request` (400), `recommendations_not_configured` (503), `hawksearch_unavailable`
-(502).
-
-## Storage: `storage`
-
-Keep the app's own data on the platform: settings, state, history. Each item is a JSON value (at most 350 KB) under a
-key, kept for the current client and shared by everyone at that client using the app, and by its functions and
-schedules (`ctx.platform.storage`). Add `"storage"` to `scopes` (not elevated).
-
-```ts
-const config = await app.storage.get<WatchConfig>('config');                  // { key, value, version, ... } or null
-await app.storage.put('config', { competitors }, { ifVersion: config?.version ?? 0 });  // 409 if someone changed it
-await app.storage.put(`hist#${sku}#2026-10`, points, { ttlDays: 400 });      // expires in 400 days
-const { items, cursor } = await app.storage.list({ prefix: 'match#', values: true });
-await app.storage.delete('draft');
-await app.storage.batch({ get: ['a', 'b'], put: [{ key: 'c', value: 1 }], delete: ['d'] });   // up to 25, each answered on its own
-const { items: count, bytes, maxBytes } = await app.storage.usage();
-```
-
-- **Keys:** 1–256 characters from `A–Z a–z 0–9 . _ - : / #`, not starting with `#`, and without empty, `.` or `..`
-  segments between slashes. Listing by prefix is the only query, so put what you look things up by first.
-- **Limits:**
-  - 100 MB and 100,000 items per app and client: 507 `storage_quota_exceeded` beyond.
-  - 600 reads and 300 writes per app and client per minute: 429 `too_many_requests` with `retryAfterMs`.
-- **Other errors:** 409 `version_conflict`, 413 `value_too_large`.
-- **Reviewers' previews** use the client's real data, so version your keys (`v2#config`) when you change their shape.
-
-**Files** (up to 100 MB each; 5 GB and 50,000 per app and client) go straight between the app and the platform's
-bucket through short-lived signed requests:
-
-```ts
-await app.storage.files.upload('exports/prices.csv', csv, { contentType: 'text/csv', ttlDays: 30 });  // Blob, bytes or text
-const { url } = await app.storage.files.url('logos/acme.png');      // a 5-minute link: <img src={url}>, or { download: 'name' }
-const blob = await app.storage.files.download('exports/prices.csv');
-const { files, cursor } = await app.storage.files.list({ prefix: 'exports/' });
-await app.storage.files.delete('exports/prices.csv');
-```
-
-- **Paths:** segments of `A–Z a–z 0–9 . _ -` between slashes.
-- **Expiry:** `ttlDays` is 1 to 365 (rounded up to 1, 7, 30, 90 or 365).
-- **Errors:** 413 `file_too_large`, 507 `storage_quota_exceeded`, `upload_failed` when the bucket refuses the upload.
-- **Usage:** `usage()` counts files a few seconds after they land.
-
-See the platform's docs/storage.md.
-
-## External Lambdas: `lambdas:invoke`
-
-Call a Lambda written outside Hawk Apps (for example HawkAnalytics' client setup) from the app or a function. Declare
-it by name and add the scope; on a released app the change waits for approval, and Bridgeline Engineering allows each Lambda
-on the platform.
-
-```json
-{ "scopes": ["lambdas:invoke"], "lambdas": ["analytics-client-setup"] }
-```
-
-```ts
-const status = await app.lambdas.invoke('analytics-client-setup', { action: 'status' });   // or ctx.platform.lambdas
-```
-
-The Lambda receives `{ caller, input }`: `caller` (client, user, engine, roles) comes from the app token, so it can't be
-faked from the browser; `input` is what you pass. Calls are never retried. Errors: `lambda_not_allowed` (404),
-`too_many_calls` (429, 30 a minute per app and client), `lambda_failed` / `lambda_unavailable` (502), `lambda_timeout`
-(408, after `timeoutMs`, default 35 s). See the platform's docs/external-lambdas.md.
-
-## App config
-
-Settings the app reads at runtime that someone changes without a deploy: who gets a notification email, a threshold, a
-feature switch. Declare each key, its type and an optional default in `config` in hawk-app.json (the declarations are
-reviewed like any setting); the values are set from the Hawk Analytics portal or with `npx hawk-app config set`, for the
-whole app (global) or for one client, and apply within about 30 seconds, with no deploy or approval.
-
-```json
-{
-    "config": {
-        "signupNotifyEmails": {
-            "type": "emails",
-            "label": "Sign-up notification recipients",
-            "description": "Who is emailed when a client signs up.",
-            "default": ["support@example.com"]
-        },
-        "connectorsRequestEmails": { "type": "emails", "label": "API Connections request recipients" }
-    }
-}
-```
-
-```ts
-const all = await app.config.all();                               // { signupNotifyEmails: [...], connectorsRequestEmails: null }
-const to = await app.config.get<string[]>('signupNotifyEmails');  // the value, or null
-// In a function: ctx.config.signupNotifyEmails (already resolved), or ctx.platform.config.get(...)
-```
-
-- **Not secret:** values reach the browser, so anyone using the app can see them. Keep API keys and passwords in
-  [secrets](#functions-functionsinvoke) (`hawk-app secrets`, or `app.clientSecrets` for each client's own).
-- **Resolution:** the caller's client value, else the global value, else the declared `default`, else `null`. A stored
-  value that no longer matches the key's type is skipped. Every declared key is in `all()`; `get` returns `null` for a
-  key the app doesn't declare and throws a `TypeError` for an empty key.
-- **Declarations:** at most 50 keys, names `^[A-Za-z][A-Za-z0-9_]{0,63}$`. Each has a `type` (`string`, `number`,
-  `boolean`, `emails`, `json`), an optional `label` (up to 100 characters), `description` (up to 500) and `default`.
-- **Values by type:** `string` up to 4000 characters; `number` finite; `boolean`; `emails` a list of up to 50 distinct
-  plain addresses (`a@example.com`, no display names); `json` any JSON but `null`. At most 16 KB each.
-- **No scope** is needed. Functions get the values for their own version, the app the ones for the version it has open.
-- **Set values** with `npx hawk-app config set signupNotifyEmails a@example.com,b@example.com [--client e3141]`,
-  `config unset`, and `config list`, or in the Hawk Analytics portal.
-
-| Code | Status | Meaning |
-|---|---|---|
-| `config_key_not_declared` | 404 | Setting a key that isn't in `config` in hawk-app.json. |
-| `invalid_config_value` | 400 | The value doesn't match the key's type. |
-| `invalid_client` | 400 | The client id isn't a valid client id. |
-| `value_too_large` | 413 | The value is over 16 KB. |
-
-## AI: `ai:invoke`
-
-Ask Claude from the app or from a [function](#functions-functionsinvoke) (`ctx.platform.ai`): summarize a report,
-draft synonyms, explain a zero-result query. The platform calls the model; your app never holds a model key.
-
-Add `"ai:invoke"` to `scopes` in `hawk-app.json` and deploy. It is an **elevated** scope: an app with
-it is never auto-approved, and approvers review it like dashboard writes.
-
-```ts
-// The whole answer at once
-const { text, usage } = await app.ai.generate({ prompt: 'Suggest 5 synonyms for "sneakers", one per line.' });
-
-// Or as it is written
-const stream = app.ai.stream({
-    model: 'smart',
-    system: 'You are a HawkSearch merchandising assistant. Answer in short bullet points.',
-    messages: [{ role: 'user', content: `Explain these zero-result queries: ${queries.join(', ')}` }],
-    maxTokens: 800,
-});
-for await (const text of stream) {
-    output.textContent += text;
-}
-const { stopReason, usage: { inputTokens, outputTokens } } = await stream.result;
-```
-
-- **Tiers**: `model: 'fast'` (the default; Claude Haiku: quick, cheap answers) or `'smart'` (Claude Sonnet: harder
-  reasoning, longer answers).
-- **Request**: `prompt` (one user message) or `messages` (1–50 `{ role: 'user' | 'assistant', content }`, alternating,
-  first and last from the user), plus optional `system` (up to 32 KB), `maxTokens` (default 1024, up to the tier's
-  `maxOutputTokens`), `temperature` (0–1) and `stopSequences` (up to 4). At most 256 KB in all.
-- **Result**: `{ text, stopReason, usage: { inputTokens, outputTokens }, id, model }`. `stopReason` is `end_turn`,
-  `max_tokens` (raise `maxTokens`), `stop_sequence` or `content_filtered`.
-- **Streaming**: `stream(request)` yields the text as it arrives; iterate it once, then `await stream.result`. Errors
-  are thrown by the loop and by `result`. `stream.abort()`, the `signal` option or leaving the loop early (`break`)
-  stops the request: both then reject with an `AbortError` (tokens generated so far still count).
-- **Usage**: `app.ai.info()` resolves to `{ tiers: [{ name, maxOutputTokens, dailyTokens, usedTokens }],
-  maxInputBytes, requestsPerMinute }`, with today's use for the current client.
-- **Limits**: a daily token budget (input + output) per app, client and tier, reset at UTC midnight, and a per-minute
-  request limit per app and client (all tiers). A request is checked against the budget before it runs and counted
-  after, so the last one of the day can go over by its own size. Calls are **never retried** for you: each one costs
-  tokens.
-- **Privacy**: prompts and answers are never logged or stored by the platform; it logs only the app, version, client,
-  user, tier, token counts, duration and outcome. Don't send secrets or personal data you don't need to.
-
-**Errors** come back as `HawkApiError`:
-
-| Code | Status | Meaning |
-|---|---|---|
-| `scope_missing` | 403 | The app doesn't have the `ai:invoke` scope. |
-| `invalid_ai_request` | 400 | A field is missing or wrong; the response's `errors` (in `error.body`) lists each one. |
-| `request_too_large` | 413 | The request is over 256 KB. |
-| `too_many_requests` | 429 | Over the per-minute limit; wait `retryAfterMs`. |
-| `ai_budget_exhausted` | 429 | The tier's daily tokens for this client are used up; `retryAfterMs` is the time until UTC midnight. Try the other tier, or wait. |
-| `ai_not_configured` | 503 | AI isn't enabled on this platform. |
-| `ai_unavailable`, `ai_throttled`, `ai_failed` | 502 | The model failed while answering (the stream's `error`): try again later. Text already streamed is incomplete. |
-
-## Your own backend
-
-If your app has a server of its own (an API, a database, a job), it can trust who is calling and act for them with
-the **app token**, without any login of its own.
-
-```ts
-// In the app: send the token as a Bearer header on every call to your backend.
-const response = await fetch('https://my-tool-api.example.com/reports', {
-    headers: { Authorization: `Bearer ${await app.getToken()}` },
-});
-```
-
-```ts
-// On your server (Node, with `jose`): verify it against the platform's public keys.
-import { createRemoteJWKSet, jwtVerify } from 'jose';
-
-const keys = createRemoteJWKSet(new URL('https://<platform>/.well-known/jwks.json'));
-
-const { payload } = await jwtVerify(token, keys, {
-    issuer: 'urn:hawk-apps:prod', // urn:hawk-apps:dev on dev
-    audience: 'hawk-app:my-tool', // your slug
-    algorithms: ['RS256'],
-});
-// payload.client_id, payload.sub, payload.email, payload.roles, payload.scope ...
-```
-
-**Auth is a Bearer token, never a cookie.** Your app runs in a cross-site iframe, where browsers block or partition
-cookies (Safari always, Chrome increasingly), so a session cookie that works when you open the app directly fails
-inside the HawkSearch dashboard or Spark. Ask for a fresh token per request: `app.getToken()` caches it and refreshes it before it expires.
-
-The token contract is stable, and any JWT library that reads a JWKS can check it:
-
-| Claim | Value |
-|---|---|
-| header `alg` / `kid` | `RS256`, and the id of the key in the JWKS (keys rotate; let your library pick by `kid`) |
-| `iss` | `urn:hawk-apps:dev` or `urn:hawk-apps:prod` |
-| `aud` | `["hawk-apps-api", "hawk-app:<slug>"]`: check for your own `hawk-app:<slug>` |
-| `exp`, `iat`, `nbf` | about 10 minutes of validity |
-| `sub`, `email` | the user (id, and email when the host has one) |
-| `client_id`, `account_id` | the tenant (`account_id` when the host has one): scope everything you store by `client_id` |
-| `analytics` | `"none"` when the client has no analytics data set up (missing otherwise) |
-| `roles`, `internal` | the user's roles, and whether they are Bridgeline staff |
-| `app`, `host`, `scope` | your slug, the host (e.g. `spark`), the granted scopes |
-| `jti` | a unique id for the token |
-
-Your server can also call the platform with the same token (`Authorization: Bearer <token>`, e.g.
-`POST https://<platform>/v1/analytics/searches`), so data can be fetched server-side for the current user and client.
-Treat the token like a password: don't log it or store it.
-
-Server-rendered apps (SSR, where the server needs the user on the very first page load) are planned: the manifest
-already has `"hosting": "static"`, and `"server"` is reserved for them.
-
-## Errors
-
-Failed data calls throw `HawkApiError` with `status` and `code`; failed host requests throw `HawkBridgeError` with
-`code`.
-
-| Code | Meaning |
-|---|---|
-| `not_embedded` | The page was opened directly, not inside a host. |
-| `host_not_allowed` | The host isn't in `allowedHostOrigins`. |
-| `timeout` | The host didn't answer in time. |
-| `report_not_allowed` | The report name isn't a plain kebab-case name, or the platform blocks that report. Any other name is passed to the analytics API (`report('')` is its ad-hoc / natural-language root); a name it doesn't know comes back as its own `400`. |
-| `analytics_not_available` | Analytics isn't set up for this client (at once when `context.tenant.analyticsProvisioned` is `false`). |
-| `hawksearch_not_available` | No HawkSearch access: add `hawksearch:read` to your scopes and deploy again. |
-| `version_not_allowed` | You put an API version in a dashboard path: use `Synonym`, not `v11/Synonym`. |
-| `path_not_allowed` | The dashboard path isn't allowed (writes: see [Writing to HawkSearch](#writing-to-hawksearch-hawksearchwrite)). |
-| `hawksearch_write_needs_site_key`, `too_many_items`, `too_many_requests`, `invalid_path` | Dashboard writes: see [Writing to HawkSearch](#writing-to-hawksearch-hawksearchwrite). |
-| `query_*`, `invalid_params`, … | Custom queries: see [Custom data (queries)](#custom-data-queries-dataread). |
-| `function_*`, `functions_not_enabled`, `secret_missing`, … | Functions: see [Functions](#functions-functionsinvoke). |
-| `email_*`, `invalid_email` | Email: see [Email](#email-emailsend). |
-| `config_key_not_declared`, `invalid_config_value` | Config values: see [App config](#app-config). |
-| `engine_*`, `parameter_*`, `invalid_value`, … | System parameters: see [HawkSearch system parameters](#hawksearch-system-parameters-hawksearchsysparamswrite). |
-| `ai_*`, `invalid_ai_request` | AI: see [AI](#ai-aiinvoke). |
-| `*_unavailable`, `*_credentials_rejected` | Something is wrong on our side: retry later, and tell Engineering if it persists. |
-
-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).
-
-```ts
-try {
-    await app.functions.call('refresh', {});
-} catch (error) {
-    app.reportError(error); // reported like an uncaught one, and the app shows its own message
-    showMessage('Couldn’t refresh: try again.');
-}
-```
-
-`createApp({ reportErrors: false, reportOpens: false })` turns either off.
-
-## Talk to the host
-
-```ts
-await app.setTitle('Synonyms review');                    // the host's page title
-await app.toast('Export ready', 'success');               // info | success | warning | error
-await app.navigate({ intent: 'app', slug: 'other-tool' }); // also: 'report', 'settings', 'external' (https only)
-await app.resize();                                       // when autoResize is off
-```
-
-### 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
-user sees the question and the answer in the assistant's chat, so call it only from a click:
-
-```ts
-// Show the button only while the host has an assistant: it may load after the app (HawkSearch loads it through GTM).
-const [ready, setReady] = useState(!!app.context.features?.assistant);
-useEffect(() => app.onContextChange((c) => setReady(!!c.features?.assistant)), [app]);
-
-<Button disabled={!ready} onClick={() => app.assistant.ask('Which recommendation widgets earn the most this quarter?')}>
-    Ask Hawk 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:
-
-```ts
-useEffect(() => void app.assistant.setContext({ page: 'Recommendation Dashboard', range, totals, widgets }), [range, totals, widgets]);
-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
-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.
-
-| Intent | Goes to |
-| --- | --- |
-| `{ intent: 'app', slug, params? }` | Another app |
-| `{ intent: 'report', id? }` | The report list (HawkSearch: Report Library); with an `id`, that report where the host supports it |
-| `{ intent: 'settings', section? }` | The host's settings |
-| `{ intent: 'external', url }` | An https page in a new tab |
-
-Navigation takes *intents*, not URLs, so the same app works in every host.
-
-## Look and feel
-
-Every template gets this from the UI kit ([`@bridgeline-digital/hawk-app-ui`](../ui/README.md)), Spark's look in
-the host's colors and mode: a React + MUI app its theme, provider and components; any other app (vanilla, Preact,
-React, Next) its stylesheet and custom elements. The rest of this section is for apps that style themselves.
-
-With `applyTheme` on, the host's design tokens are set as CSS variables on `<html>`, and
-`<html data-hawk-theme="light|dark">` matches the host. Use them with your own fallbacks so the app also renders on
-its own:
-
-```css
-body {
-    background: var(--hawk-color-background, #f6f7f9);
-    color: var(--hawk-color-text-default, #1f2933);
-    font-family: var(--hawk-font-default, system-ui, sans-serif);
-}
-button {
-    background: var(--hawk-color-button-accent-background, #ff6a13);
-    color: var(--hawk-color-button-accent-text, #fff);
-    border-radius: var(--hawk-border-radius, 6px);
-}
-```
-
-Available: `--hawk-color-background`, `--hawk-color-background-container`, `--hawk-color-background-primary`,
-`--hawk-color-background-accent`, `--hawk-color-text-default`, `--hawk-color-text-heading`,
-`--hawk-color-text-secondary`, `--hawk-color-text-accent`, `--hawk-color-border-default`, `--hawk-color-border-accent`,
-`--hawk-color-button-accent-background`, `--hawk-color-button-accent-text`, `--hawk-font-default`,
-`--hawk-border-radius`.
-
-The host already shows your app's name above the frame, so you don't need a page heading.
-
-### Dialogs cover the whole page
-
-An open dialog (any `[role="dialog"]`, e.g. every MUI Dialog or Drawer) covers the host's whole page, not just the
-frame, with nothing to call:
-- **A frame that's fully on screen and big enough**: the host dims the page around the frame to match your dialog's
-  backdrop (`modalBackdrop` on the host, default MUI's `rgba(0, 0, 0, 0.5)`). A click there sends Escape to the dialog.
-- **Any other frame** (a preview, a slot, a short or narrow frame, or a tall page scrolled partly out of view, where a
-  dialog fixed to the frame could open off screen): the host lifts the frame over the whole window while the dialog is
-  open. The bridge keeps your page exactly where the frame was (same width, same scroll, clipped to the frame's box)
-  on an otherwise transparent page, so the dialog shows full size over the dimmed host page with your content still
-  behind it; the frame goes back when the dialog closes.
-- The host page doesn't scroll meanwhile and keeps its scroll position, and auto-resize waits for the dialog to close.
-- Center dialogs in the visible part of the frame (`--hawk-visible-top` and `--hawk-visible-height`, see the templates'
-  theme). `createApp({ hostModals: false })` turns this off.
-
-## Local development
-
-Run your dev server on port 3100 (the templates do), then open the app in HawkSearch with `?devUrl=` pointing at it:
-
-```
-<HawkSearch>/admin/apps/my-tool?devUrl=http://localhost:3100/my-tool/
-```
-
-The HawkSearch dashboard loads your local copy instead of the deployed one, with the real context and real data, and hot reload works as
-usual. Dev mode is for Bridgeline users only and accepts only `http://localhost` addresses. The app must be registered
-for the client you're on (a draft is enough), and the dev platform accepts data calls from ports 3100 to 3103.
-
-## `hawk-app.json`
-
-The CLI sends this file to the platform with every `hawk-app deploy` (and `hawk-app dev`). It sets your app's visibility and what data it can read.
-Which clients have the app is not in this file: manage them in the Hawk Analytics portal or with `npx hawk-app clients`.
-
-```json
-{
-    "slug": "my-tool",
-    "name": "My Tool",
-    "description": "What it does, in one line.",
-    "visibility": "allowList",
-    "scopes": ["reports:read"]
-}
-```
-
-| Field | |
-|---|---|
-| `slug` | Unique id and the app's folder on the CDN (`/<slug>/`, one `v<n>/` folder per deploy). Can't change later. |
-| `icon` | An `.svg` (drawn in the host's color) or `.png` (shown as is) file next to `hawk-app.json`, e.g. `icon.svg`. New apps get a default `icon.svg`; without one, hosts show a default icon. |
-| `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). |
-| `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. |
-| `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"`. |
-
-Run `npx hawk-app deploy --dry-run` to see what would change without making a version (use it on pull requests), and
-`npx hawk-app clients` to see which clients have the app.
-
-**Who releases it.** There's no `status` field (an old one is ignored with a warning): every `hawk-app deploy` is a
-new version, with the hawk-app.json it was deployed with, and Bridgeline staff review apps on the Apps page in
-HawkSearch. See [versions, statuses and aliases](../../docs/versions-and-aliases.md).
-- Each version has a status: **draft** (deployed), **waiting** (submitted for approval), **approved** or **rejected**.
-  Only Bridgeline staff see versions that aren't approved, on the app's clients (or every client with
-  `"visibility": "all"`).
-- An approver **releases** a version: released to everyone, the built-in `default` alias moves to it, and every
-  client without another alias gets it. Other aliases (e.g. `pilot`) let some clients get a different version.
-- Once released, each new version and each settings change (name, scopes, `externalOrigins`, …) waits for approval,
-  and clients keep the released version until then. `npx hawk-app status` shows what's waiting.
-- 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.
-
-**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
-waiting request, so it has to be submitted again. `npx hawk-app status` shows whether it's waiting for approval or was
-rejected, and why.
-
-## Good to know
-
-- **No secrets in the app.** Everything in it is public. Credentials stay on the platform; API keys of your own go in
-  function secrets (see [Functions](#functions-functionsinvoke)).
-- **Outside origins are up to you.** An app can load scripts, styles, fonts and images from, embed, and call
-  (`fetch`, WebSockets) only the origins in `externalOrigins` (`"*"` allows any https origin, and fails the review
-  check). List the origins it really uses: the apps CDN blocks everything else (a Content-Security-Policy), so a compromised npm dependency can't send
-  data anywhere new. The platform API is always allowed. To show images from any site (for example a client's
-  product images) without opening anything else, use `"img:*"`. Dev mode on localhost has no such policy, so check a
-  deployed version in HawkSearch before it's released.
-- **Static files only.** Build to plain HTML, JS and CSS (`next build` with `output: 'export'`, `vite build`, …), with
-  the base path read from `HAWK_APP_BASE_PATH` (`/<slug>/v<n>`, set by `hawk-app deploy`; the templates do this).
-- **Tokens are handled for you.** `app.getToken()` exists for apps with a backend of their own; the token can be
-  verified against the platform's JWKS.
-- **Changes to client data are reviewed.** Apps change client data only through scopes that allow it:
-  `hawksearch:write`, `hawksearch:sysparams:write`, `hawksearch:features:write`, the `hawksearch:index` scopes and
-  `storage` (the app's own data). An approver reviews each one.
-
+# @bridgeline-digital/hawk-app-bridge
+
+Build **Hawk Apps**: small tools that run inside the HawkSearch dashboard. Your app gets the
+signed-in user's context (client, engine) and the client's data through this package, with **no API
+keys in your code**.
+
+Guides, the full API reference and the CLI are at **[developers.hawksearchapps.com](https://developers.hawksearchapps.com)**
+(sign in with your Bridgeline account).
+
+- Any static front end works: React, Next.js (static export), Vue, plain HTML. Apps are static files on the apps CDN;
+  there is no server of your own.
+- Pair it with the CLI, [`@bridgeline-digital/hawk-app-cli`](https://www.npmjs.com/package/@bridgeline-digital/hawk-app-cli),
+  to create, run locally and deploy apps.
+
+## Quick start
+
+```bash
+npx @bridgeline-digital/hawk-app-cli@latest create my-tool --template react --install
+cd my-tool
+npx hawk-app sso   # once per machine: sign in with your Bridgeline account
+npm run app:dev    # the app in a local stand-in for HawkSearch, with a client's data
+```
+
+The first time, `app:dev` asks for part of a client's name and saves your pick in `.env.local`
+(`npm run app:dev -- --client <id>` picks another).
+
+The template is already wired to this package. You can also open it inside HawkSearch in
+[dev mode](#local-development). When it's ready:
+
+```bash
+npm run app:deploy   # build and upload a new version, with hawk-app.json (no folder needed)
+npx hawk-app open    # the app in HawkSearch: review it and submit it for approval
+```
+
+New versions are drafts that only Bridgeline staff see; an approver releases them from the Apps page in HawkSearch (see
+[`hawk-app.json`](#hawk-appjson)).
+
+## Connect to the host
+
+```ts
+import { createApp } from '@bridgeline-digital/hawk-app-bridge/client';
+
+const app = await createApp({ autoResize: true });
+
+render(app.context);
+app.onContextChange((context) => render(context)); // the user switched client, engine or dates
+```
+
+**Where the app is visible.** A frame that grows with its content (auto-resize) can be much taller than the screen, so
+a dialog centered in the frame may open off screen. The host reports the visible part of the frame: `app.viewport`
+(`{ top, height }` in px from the frame's top), `app.onViewportChange(listener)`, and the CSS variables
+`--hawk-visible-top` and `--hawk-visible-height`. The UI kit's theme (`@bridgeline-digital/hawk-app-ui`, in the next-mui template) uses them to place MUI dialogs and
+snackbars; other apps can do the same in CSS, e.g.
+`.modal { position: absolute; top: calc(var(--hawk-visible-top, 0px) + 40px); }`.
+
+`createApp` resolves once the host has answered with the context. It rejects with code `not_embedded` when the page
+is opened directly instead of inside a host: show a friendly message (the templates do).
+
+You don't configure which hosts may embed your app: the platform does. The apps CDN only lets the HawkSearch dashboard and Spark frame
+an app, and the bridge only talks to the window that embedded it.
+
+| Option | Default | |
+|---|---|---|
+| `autoResize` | `false` | Keep the frame as tall as your content. Leave it off for full-height layouts. |
+| `applyTheme` | `true` | Apply the host theme as `--hawk-*` CSS variables. |
+| `timeoutMs` | `10000` | How long to wait for the host to answer a request. |
+
+## Context
+
+`app.context` is always current; `onContextChange` tells you when it changes.
+
+| Field | Example | |
+|---|---|---|
+| `tenant.clientId` | `"e3141"` | The client the user is working in. All data calls are scoped to it automatically. |
+| `tenant.analyticsProvisioned` | `false` | `false` when the client has no analytics data set up: show a message instead of calling `app.data` or `app.analytics` (they'd fail with `data_not_available` / `analytics_not_available`). Missing when the host doesn't say. |
+| `engine` | `{ id: "3141", name: "Outdoor Demo" }` | The engine selected in the host, if any. |
+| `site` | `{ id, name }` | The site, if the host has one selected. |
+| `dateRange` | `{ from: "2026-09-01", to: "2026-09-30", timeZone: "UTC" }` | The host's date picker. Analytics calls use it by default. |
+| `user` | `{ id, email, roles }` | The signed-in user. |
+| `locale` | `"en-US"` | Format numbers and dates with it. |
+| `theme` | `{ mode: "light", tokens }` | Also applied as CSS variables (see [Look and feel](#look-and-feel)). |
+| `features` | `{ assistant: true }` | What the host offers the app, e.g. `features.assistant`: the host's Hawk Assistant can be opened (see [Ask the host's assistant](#ask-the-hosts-assistant-assistant)). |
+| `view` | `{ name: "preview", params, embedded: true, maxHeight }` | The view showing, or null for the full app (see [Views](#views-an-app-inside-other-pages)). |
+| `app.slug` | `"my-tool"` | Your app. |
+
+## Views: an app inside other pages
+
+Besides its own page, an app can show **views**: pages of the same build that hosts show inside other pages. Declare
+them in `hawk-app.json`:
+
+```json
+"views": {
+  "preview": { "path": "views/preview", "title": "Price position", "height": 220, "cacheMinutes": 60 },
+  "product": { "path": "views/product", "title": "This product", "embeddable": true, "params": ["sku"] }
+}
+```
+
+- **`preview`** is shown on the Apps page under the app's description.
+- **Embeddable views** can be placed by Bridgeline users in other pages (the report builder, later Spark pages).
+- **Each view is a page at `<entry>/<path>/`,** e.g. a Next.js route `src/app/views/preview/page.tsx`, with the same
+  version, scopes and token as the app.
+- **`app.context.view`** says which view is showing and what the page passed in:
+  `{ name, params: { sku: 'A-1' }, embedded: true, maxHeight }`. It's null for the full app.
+- **Keep views small and fast.** A `preview` shares the Apps page with every other app, so read the app's stored
+  results rather than run reports or queries.
+- **`cacheMinutes` caches a view's reads** (0–1440; a `preview` caches 60 minutes unless it says otherwise, other views not at all): the platform keeps the answers to the view's data
+  queries, analytics reports, `dashboard.get`, search and recommendations for that long, per client and engine, and
+  answers the same call again from them. Set `"cacheMinutes": 0` on a preview that must always be fresh. The full app page is never cached,
+  and a new version starts fresh. A cached `data.query` result has `cachedAt` (when it was stored). Pass
+  `{ cache: 'reload' }` to ask the source again (and store the new answer), or `{ cache: 'no-store' }` for a call
+  that must not be cached, e.g. an analytics report that records something. Engineering can shorten or stop it per
+  app in the Hawk Analytics portal.
+- **`views` is a setting:** on a released app, changes wait for approval.
+- **A view's page is transparent:** the bridge marks it `data-hawk-view="<name>"` on `<html>` and clears the page
+  background, so the host's shows through. To paint one, set it on the view's content, or with
+  `html[data-hawk-view] body { … }`.
+- **A view fits its content:** it starts at its declared `height`, then auto-resize (on by default in a view) sizes it
+  to the content, within the container's `min-height` and `max-height`. Don't set `html, body { height: 100% }` in a
+  view, or it can't shrink.
+- **In a view**, toasts and title changes are ignored (the page isn't the app's), the height grows with
+  `app.resize()` up to `maxHeight`, and `app.navigate({ intent: 'app', slug })` opens the full app.
+- **The trial view** of a store app (`"trial": true`, one at most, no params) runs on its store card for clients that
+  don't have the app, on their own data. There `app.context.trial` is `true` and the token has only the app's
+  read-only scopes (`reports:read`, `hawksearch:read`, `hawksearch:search`, `hawksearch:recommendations`,
+  `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.
+
+### Hosts: `<hawk-app-container>`
+
+Configure once per page, then place containers anywhere:
+
+```ts
+import { configureHawkAppContainers, defineHawkAppContainer } from '@bridgeline-digital/hawk-app-bridge/host';
+
+defineHawkAppContainer();
+configureHawkAppContainers({
+    // From the registry: the app's entry URL plus the view's path; null hides the view. { trial }: the store listing's trial view.
+    resolveView: async (app, view, options) => ({ src, title, height, appName, description, params }),
+    // The app's context now and on every change; return a function that stops the updates.
+    watchContext: (app, listener) => subscribe(app, listener),
+    // { trial }: a trial token (POST /token/exchange with trial: true).
+    getToken: (app, { forceRefresh, trial }) => exchangeToken(app, forceRefresh, trial),
+    // { trial }: the client doesn't have the app: offer a request instead.
+    openApp: (app, params, options) => (options?.trial ? offerRequest(app) : router.open(app, params)),
+});
+```
+
+```html
+<hawk-app-container app="price-watch" view="preview" max-height="320" fallback="Compare your prices."></hawk-app-container>
+```
+
+- **Attributes:** `app`, `view` (default `preview`), `params` (a JSON object; only names the view declares are passed),
+  `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`).
+- **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
+  placeholder uses `--hawk-app-container-radius` and `--hawk-app-container-placeholder`.
+
+### Hosts: `<hawk-app-slot>`
+
+A place in a host page where Bridgeline users put an app view, saved on the platform per engine or for every client:
+
+```ts
+import { configureHawkAppSlots, defineHawkAppSlot } from '@bridgeline-digital/hawk-app-bridge/host';
+
+defineHawkAppSlot(); // also defines <hawk-app-container>: configure it as above
+configureHawkAppSlots({
+    canEdit: isBridgelineUser,
+    getSlots: (ids) => backend.get(`/slots?ids=${ids}`), // the platform's GET /slots, through the host backend
+    listChoices: async () => appsWithPlaceableViews, // [{ app, name, views: [{ name, title, params }] }]
+    saveSlot: (slot, change) => backend.put(`/slots/${slot}`, change), // { scope, app, view, params, minHeight, maxHeight }
+    removeSlot: (slot, scope) => backend.delete(`/slots/${slot}?scope=${scope}`),
+    appHref: (app) => `/apps/${app}`, // the app's page: the icon link's href
+    openApp: (app) => router.open(app), // a plain click on the icon link
+});
+```
+
+```html
+<hawk-app-slot slot-id="dashboard.top"></hawk-app-slot>
+```
+
+- **Clients** see the placement in a `<hawk-app-container>` (light DOM: style it with `hawk-app-slot > hawk-app-container`);
+  an empty slot is `hidden`.
+- **Editors** (`canEdit`) get a pencil button (a "Place an app" placeholder when empty) opening a form: app, view (or
+  *Entire app*: the app's own page, `<hawk-app-container full-app>`), the view's params, min and max height, *Show a
+  link to open the app* (an icon in the slot's corner; not for the entire app), and *This engine only* or *All
+  clients*. It fires `hawk-slot-change` after a save
+  or remove.
+- **Slots on a page load in one call** (`getSlots` gets every id requested in the same task).
+- **Texts:** `labels` (defaults `DEFAULT_SLOT_LABELS`). Theme: `--hawk-slot-accent`, `--hawk-slot-text`,
+  `--hawk-slot-muted`, `--hawk-slot-border`, `--hawk-slot-surface`, `--hawk-slot-font`, `--hawk-slot-radius`.
+- **The host backend adds the client, engine and editor** from its session: never from the browser.
+
+### Hosts: `<hawk-app-icon>`
+
+An app's icon, from the registry's `iconUrl` and `iconKind` (registered by `defineHawkAppIcon()`, and by
+`defineHawkAppFrame()`, `defineHawkAppContainer()` and `defineHawkAppSlot()`):
+
+```html
+<hawk-app-icon src="https://apps.example.com/price-watch/v3/icon.svg" kind="svg"></hawk-app-icon>
+```
+
+- **Attributes:** `src`, `kind` (`svg` or `png`), `label` (the accessible name; without it the icon is decorative).
+- **`svg` is drawn in the host's color:** only its shape counts, filled with `currentColor` (a CSS mask), like the
+  host's own icons in light and dark themes. **`png` is shown as is.**
+- **No `src`, or one that fails to load:** a built-in default app icon, in `currentColor`.
+- **Size and color:** it fills its own box, 24 × 24 px by default: set `width`, `height` and `color` on it. The
+  `state` attribute (`svg`, `png`, `default`) says what it shows.
+
+## Data
+
+Every call goes through the Hawk Apps Platform with a short-lived app token. The platform adds the credentials
+server-side and takes the client from the signed token, so an app can only ever read the current client's data. Ask
+for the scopes you need in `hawk-app.json`.
+
+### Analytics reports: `reports:read`
+
+```ts
+const top = await app.analytics.report('queries', { limit: 20 });
+// { columns: [{ name, type }], data: [...rows], totalRecords, page, hasMore }
+
+const lastWeek = await app.analytics.report('searches', { startDate: '2026-09-24', endDate: '2026-09-30' });
+```
+
+Dates default to the host's date range. Request options: `startDate`, `endDate`, `limit` (default 100), `page`,
+`filters` and `having` (`{ member, operator, values }`), as in the
+[HawkSearch Analytics API](https://developers.analytics.hawksearch.com/), which documents each report's columns.
+Data refreshes nightly. A third argument takes `{ signal?, cache? }`; in a caching view, pass `{ cache: 'no-store' }`
+for a report that records something (see [Views](#views-an-app-inside-other-pages)).
+
+**Typed reports.** The bridge knows every report in the analytics API's spec: `report('searches')` returns typed rows,
+with numbers and booleans converted from the strings the API sends (`row.search_count` is a number), and `filters`
+and `having` take only that report's fields. A renamed or removed column fails your build once you update the bridge,
+instead of showing blanks. `AnalyticsReportRow<'searches'>` is a row's type. The writes are typed too:
+`report('ai-advisor-feedback', { recommendationId, engineId, feedback })` returns `{ feedback }`.
+
+```ts
+const { data } = await app.analytics.report('assistant-activity', {
+    filters: [{ member: 'model_id', operator: 'equals', values: ['…'] }], // only this report's fields
+});
+const tokens = data.reduce((sum, row) => sum + row.total_tokens, 0); // numbers, not "123"
+```
+
+Every report the analytics API has can be called, by its path without the slash (`assistant-prompts`); new ones need
+no bridge or platform change: a report newer than your bridge returns untyped rows (`report<MyRow>('new-report')`),
+with values as the API sends them. Passing your own row type to a known report (`report<MyRow>('searches')`) opts out
+of its types, though its values are still converted. `report('', { query: '…' })` is the API's ad-hoc / natural-language query. For the list,
+each report's columns and its `filters`/`having` fields, see the
+[developer portal](https://developers.analytics.hawksearch.com/) (the dev platform uses the dev analytics API:
+[its spec](https://developers.analytics.hawksearch.com/dev/openapi.yaml)), or ask your assistant: the `hawk-apps` MCP
+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');
+// Query parameters: app.dashboard.get('LandingPage', { query: { ... } })
+```
+
+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
+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.
+
+### Writing to HawkSearch: `hawksearch:write`
+
+```ts
+// Create a synonym
+const synonym = await app.dashboard.post('Synonym', {
+  SearchTerm: 'sneakers',
+  SynonymGroup: 'trainers,running shoes',
+  MultiWay: true,
+});
+
+// Update a redirect
+await app.dashboard.put('Redirect/42', { ...redirect, NewUrl: '/sale' });
+
+// Delete a banner
+await app.dashboard.delete('Banner/7');
+```
+
+`app.dashboard.post(path, body?)`, `put(path, body?)` and `delete(path)` (also on `ctx.platform.dashboard` in
+[functions](#functions-functionsinvoke)) send the body as JSON to the
+[HawkSearch Dashboard API](https://developerdocs.hawksearch.com/reference/getting-started-with-your-api) and resolve
+to HawkSearch's response body (`undefined` when it's empty). Paths work as for `get`: no API version (`Synonym`,
+`Synonym/123`, `LandingPage/bulk`); each segment is URL-encoded for you.
+
+- **Scope**: add `"hawksearch:write"` to `scopes` in `hawk-app.json` (reviewed like any scope). Reading stays under
+  `hawksearch:read`; ask for both if you read what you write.
+- **Allowed resources**: `Banner`, `BoostBury`, `Campaign`, `Visibility`, `VisitorTarget`, `Redirect`, `Synonym`,
+  `SpellCheck`, `PaginationSet`, `SortingSet`, `RecommendationVisibility`, `LandingPageLayout`, `Facet` and
+  `LandingPage` (and their sub-paths). Anything else, e.g. `Field`, fails with 403 `path_not_allowed`; so do bulk
+  landing-page deletes.
+- **Limits**: bodies up to 5 MB, bulk requests up to 1000 items, and 120 writes per minute per app and client.
+- **Site keys only**: writes go through a site's own HawkSearch API key. When the client is connected with a group
+  key, writes fail with 403 `hawksearch_write_needs_site_key` (reads still work).
+- **Audited**: every write is audit-logged by the platform (which app, for which client, by which user).
+- **Not retried**: writes aren't idempotent, so the bridge sends each one once. A 429 `too_many_requests` is thrown
+  with `error.retryAfterMs`; wait at least that long before you try again, and only if repeating the write is safe.
+
+| Code | Status | Meaning |
+|---|---|---|
+| `scope_missing` | 403 | The app doesn't have the `hawksearch:write` scope. |
+| `path_not_allowed` | 403 | The resource isn't one of the allowed ones above (or it's a bulk landing-page delete). |
+| `hawksearch_write_needs_site_key` | 403 | The client is connected with a group key; writes need a site key. |
+| `request_too_large` | 413 | The body is over 5 MB. |
+| `too_many_items` | 400 | A bulk request has more than 1000 items. |
+| `too_many_requests` | 429 | Over 120 writes a minute for this app and client; `retryAfterMs` says when to try again. Not retried. |
+| `invalid_path` | 400 | The path is malformed (the bridge also rejects empty paths and `.`/`..` segments with a `TypeError`). |
+| `version_not_allowed` | 400 | You put an API version in the path: use `Synonym`, not `v11/Synonym`. |
+| `hawksearch_unavailable` | 502 | HawkSearch couldn't be reached: the write may or may not have happened, so check before you repeat it. |
+| `hawksearch_credentials_rejected` | 502 | HawkSearch rejected the client's API key: tell Engineering. |
+
+HawkSearch's own validation errors (e.g. 400 for a missing required field, 404 for an unknown id) come back as
+`HawkApiError` with HawkSearch's status and its response in `error.body`.
+
+### Custom data (queries): `data:read`
+
+When the reports don't have what you need, ship your own SQL with the app. Each query is two files in `queries/`,
+next to `hawk-app.json` (not in the build folder); `hawk-app deploy` checks them and deploys them with the version,
+and Bridgeline staff see them when they review it. The platform runs them (Amazon Athena) against the **current
+client's** analytics tables only: the client comes from the app token, never from the app.
+
+```sql
+-- queries/top-searches.sql: one SELECT (or WITH … SELECT), plain table names, ? for each parameter in order
+SELECT search_date, sum(search_count) AS searches
+FROM dailysearches
+WHERE search_date BETWEEN ? AND ?
+  AND {{partitions(from, to)}}
+GROUP BY 1
+ORDER BY 1
+```
+
+```json
+{
+    "params": [
+        { "name": "from", "type": "date", "required": true },
+        { "name": "to", "type": "date", "required": true }
+    ]
+}
+```
+
+(`queries/top-searches.json`. `from` and `to` bind the two `?`s, in order.)
+
+```ts
+// `date` params are "YYYY-MM-DD"; the host's date range is full ISO timestamps, so cut them to the day.
+const day = (iso: string) => iso.slice(0, 10);
+const { from, to } = app.context.dateRange!;
+
+const { columns, rows, bytesScanned, cached } = await app.data.query<{ search_date: string; searches: number }>('top-searches', {
+    from: day(from),
+    to: day(to),
+});
+// rows: [{ search_date: '2026-09-01', searches: 1204 }, ...]
+```
+
+`app.data.query(name, params?, { signal?, timeoutMs?, cache? })` resolves to `{ columns: [{ name, type }], rows, rowCount,
+bytesScanned, cached, cachedAt }` (`cachedAt`: when the platform's view cache stored the rows, else null; `cache`:
+`'reload'` or `'no-store'`, see [Views](#views-an-app-inside-other-pages)). Rows are objects keyed by column name, typed: numbers for integer/decimal/double columns,
+booleans, ISO strings for dates and timestamps, `null` for nulls. Long queries are polled for you (1 s, 2 s, 4 s, then
+every 5 s) until they finish or `timeoutMs` (default 120 s) passes; pass an `AbortSignal` to stop waiting (the
+promise rejects with an `AbortError`). When too many queries are running (429 `too_many_queries`) the call waits and
+tries again (1 s, 2 s, 4 s, then every 5 s, never sooner than the platform's `Retry-After`), until `timeoutMs`; only
+then does it reject with the 429. `cached` is `true` when the result wasn't computed for this call: Athena reused a
+recent result of the same query and parameters, or an identical request made moments earlier was already running it.
+
+**Parameters** are declared in `<name>.json`, in the order of the `?`s in the SQL, and are always sent as query
+parameters (never pasted into the SQL):
+
+| Type | Value |
+|---|---|
+| `string` | up to 1000 characters |
+| `int`, `decimal` | a number; `min` / `max` optional |
+| `date` | `"YYYY-MM-DD"` |
+| `timestamp` | ISO 8601, e.g. `"2026-09-01T00:00:00Z"` |
+| `boolean` | `true` / `false` |
+| `string[]` | up to 100 strings (`maxItems` to lower it); counts as **one** `?`, written `IN ?` (it becomes `IN (?, ?, …)`) |
+
+Each param has a `name` and `type`, and optionally `required`, `default`, `min`/`max` (numbers) and `maxItems`
+(`string[]`). The number of `?`s must equal the number of params.
+
+**`{{partitions(from, to)}}`** limits the scan to the months between two `date` params (both must be declared
+`date`; they still bind their own `?`s). Use it on every query with a date range: most tables are partitioned by
+year/month, so without it a query reads the client's whole history. Add the table alias as a third argument when the
+query joins tables: `{{partitions(from, to, d)}}`. On a table that isn't partitioned it becomes `TRUE`.
+
+**Tables:** `apiusage`, `dailysearches`, `dailyusers`, `dailyrequests`, `geodistribution`, `redirecttracking`,
+`productimpressions`, `searchfunnel`, `pageloads`, `analyticsapilogs`, `queries`, `clickpositions`, `facets`,
+`sortingtracking`, `paginationtracking`, `poorresults`, `dailyspelling`, `salesbydate`, `salesbykeyword`,
+`salesbyproduct`, `recommendations`, `campaigns`, `banners`, `autocompleteclicks`, `autocompletetrendingcategories`,
+`autocompletetrendingitems`, `productratings`, `devicebrowser`, `landingpages`, `gacore`, `catalog`. Any other table
+fails with `TABLE_NOT_FOUND`.
+
+**Sensitive tables** hold visitor-level data or conversations: `summary`, `agentprompts`, `agentexchanges`,
+`agenttoolcalls`, `aisummary`, `facetselections`, `visitortargetselections`. An app can query them only after
+Engineering turns on **Allow sensitive data** for it (in the analytics portal; it applies to every client the app runs
+for). Until then they also fail with `TABLE_NOT_FOUND`. Ask Engineering when your app needs one, and select only the
+columns you need (counts rather than raw text where you can). `npx hawk-app data tables` and `npx hawk-app data describe <table>` show the columns, and
+`npx hawk-app data run queries/top-searches.sql --client <id> --param from=2026-09-01 --param to=2026-09-30` tries a
+query on dev before you deploy it.
+
+**Limits:** one statement per file, `SELECT`/`WITH` only, 64 KB per query, 50 queries per app, 10,000 rows / 5 MB per
+result, and a per-query scan limit (10 GB by default). Results of the same query with the same parameters are reused
+for up to 15 minutes (`cached: true`). Data refreshes nightly.
+
+**Errors** (`HawkApiError.code`):
+
+| Code | Status | Meaning |
+|---|---|---|
+| `query_not_found` | 404 | No `queries/<name>.sql` in the version the user has open. |
+| `invalid_params` | 400 | A parameter is missing or has the wrong type; `JSON.parse(error.body).errors` lists them. |
+| `query_failed` | 400 | Athena rejected or failed the query (the message says why, e.g. an unknown column). |
+| `scan_limit_exceeded` | 400 | The query reads too much data: narrow the date range or use `{{partitions(…)}}`. |
+| `result_too_large` | 413 | More than 10,000 rows or 5 MB: aggregate, filter or add `LIMIT`. |
+| `too_many_queries` | 429 | Too many queries running (at most 2 per app and client at a time): `app.data.query` already retried until `timeoutMs`. |
+| `query_timeout` | 408 | Still running after `timeoutMs` (raised by the bridge). |
+| `data_not_available` | 404 | Analytics data isn't set up for this client (when `context.tenant.analyticsProvisioned` is `false` it answers at once, without running the query). |
+| `data_unavailable` | 502 | Something is wrong on our side: retry later. |
+
+**Writing good queries**
+- Filter by date and add `{{partitions(from, to)}}`: it's what keeps queries fast and cheap.
+- Aggregate in SQL (`GROUP BY`, `sum`, `count`) and return only what the screen shows; add `LIMIT` to lists.
+- Name the columns you need instead of `SELECT *`: Athena reads only those columns.
+- Column names come back exactly as written; give computed columns an alias (`sum(x) AS searches`).
+- Run independent queries in parallel (`Promise.all`), but no more than two at a time per client: more just wait
+  their turn.
+- Show something while waiting: a first run can take a few seconds; repeats within 15 minutes are instant.
+
+### Who am I
+
+```ts
+const me = await app.api.get('me'); // { app, clientId, accountId, userId, scopes, internal }
+// internal: true for Bridgeline staff (from the signed token), e.g. to show a staff-only tab
+```
+
+## Functions: `functions:invoke`
+
+Server-side code that ships with your app: call a third-party API with a key the browser must never see, combine
+several platform calls, or reshape data before it reaches the app. Each function is a file in `functions/`, deployed
+with every version as an AWS Lambda function (Node 22) and called from the app with `app.functions.call`.
+
+**Engineering must enable functions for your app** (they reach the internet and can hold secrets). Until then calls
+fail with `functions_not_enabled`. A version whose functions changed (added, removed, new code or settings) **always
+needs review**, even on an auto-approve app.
+
+```
+my-app/
+  hawk-app.json        "scopes": ["functions:invoke", …],
+                       "functions": { "sync-feed": { "timeoutSeconds": 20, "memoryMb": 512, "secrets": ["FEED_API_KEY"] } }
+  functions/
+    sync-feed.ts       one entry file per function (.ts, .mts, .js or .mjs), named after it, exporting `handler`
+    lib/feed.ts        shared code goes in subfolders (or import from src/ and node_modules)
+```
+
+```ts
+// functions/sync-feed.ts
+import type { HawkFunction } from '@bridgeline-digital/hawk-app-bridge/server';
+
+export const handler: HawkFunction<{ since: string }, { items: unknown[] }> = async (input, ctx) => {
+    const response = await fetch(`https://feeds.example.com/items?since=${input.since}`, {
+        headers: { Authorization: `Bearer ${ctx.secrets.FEED_API_KEY}` },
+    });
+    if (!response.ok) throw new Error(`Feed answered ${response.status}`);
+    const top = await ctx.platform.analytics.report('searches', { startDate: input.since, limit: 10 });
+    return { items: [...(await response.json()), ...top.data] };
+};
+```
+
+```ts
+// In the app
+const { items } = await app.functions.call<{ items: unknown[] }>('sync-feed', { since: '2026-09-01' });
+```
+
+`app.functions.call(name, input?, { signal?, timeoutMs? })` posts `input` (any JSON, up to 256 KB) and resolves to
+what `handler` returned (up to 6 MB). It waits up to `timeoutMs` (default 30 s) and retries while the platform answers
+429 (too many calls running), like data queries.
+
+**`ctx`** (`HawkFunctionContext`)
+
+| | |
+|---|---|
+| `ctx.client.id` | The HawkSearch client the app is running for. |
+| `ctx.user` | `{ id, email, roles }` of the caller; `ctx.internal` is true for Bridgeline staff. |
+| `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.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
+bundles it with every dependency, so the app needs this package installed (0.4.0 or later). The `/server` entry has
+no DOM; `createPlatformClient({ apiBaseUrl, token })` gives you the same `ctx.platform` in tests or scripts.
+
+**Settings** (per function in `hawk-app.json`; all optional): `job` (a [background job](#background-jobs), default
+false), `timeoutSeconds` 1–25 (default 10; 1–900 for a job, default 300), `memoryMb` 128–1024
+(default 256; more memory also means more CPU), `secrets` up to 20 names. At most 10 functions per app; names are
+lowercase letters, digits and dashes, up to 40 characters. Bundles are limited to 10 MB zipped, the `functions/`
+sources to 5 MB.
+
+**Secrets** are set with the CLI, never in code or in the app: `npx hawk-app secrets set FEED_API_KEY` (input hidden;
+`--value-from-env VAR` in CI), at most 4 KB each; the platform stores them encrypted. They belong to the app, not a
+version: a change applies to every version at once. A function receives only the secrets it declares; a declared secret
+that isn't set fails the call with `secret_missing`.
+
+**Client secrets** hold values that belong to each client, such as their own email platform's API key. Declare the
+names on the function (`"clientSecrets": ["MAILCHIMP_API_KEY"]`, up to 10). The client's users set them in the app,
+the function reads the calling client's value, and nobody can read a value back:
+
+```ts
+const list = await app.clientSecrets.list();            // [{ name, set, updatedAt }]
+await app.clientSecrets.set('MAILCHIMP_API_KEY', key);  // write-only, at most 4 KB
+await app.clientSecrets.delete('MAILCHIMP_API_KEY');
+// In the function: ctx.clientSecrets.MAILCHIMP_API_KEY (missing when the client hasn't set it).
+```
+
+**Logs**: `console.log` / `console.error` in a function go to its log, kept 30 days:
+`npx hawk-app logs sync-feed --since 1h --follow`. Never log secrets, tokens or personal data.
+
+**Errors** come back to the app as `HawkApiError`:
+
+| Code | Status | Meaning |
+|---|---|---|
+| `function_failed` | 502 | `handler` threw. The response has only the error's name (`errorType`); the message and stack are in the logs. |
+| `function_timeout` | 504 / 408 | The function ran past its `timeoutSeconds` (504), or the call past `timeoutMs` (408, raised by the bridge). |
+| `result_too_large` | 502 | The result is over 6 MB. |
+| `request_too_large` | 413 | The input is over 256 KB. |
+| `too_many_requests` | 429 | Too many calls running at once: `app.functions.call` already retried until `timeoutMs`. |
+| `function_not_found` | 404 | The version the caller has open has no such function (deploy it first). |
+| `function_is_job` / `function_not_job` | 409 | `call` on a job function (use `start`), or `start` on a normal one. |
+| `functions_not_enabled` | 403 | Engineering hasn't enabled functions for the app. |
+| `secret_missing` | 500 | A declared secret isn't set: `npx hawk-app secrets set <NAME>`. |
+
+Good to know: a function runs **as the caller**, for the caller's client, so scope anything you store by
+`ctx.client.id`. Functions are stateless and short (25 s at most, or 900 s for a job); keep nothing between calls
+that you can't lose.
+
+### Background jobs
+
+Work that takes longer than a call (a full export, a batch of dashboard writes, a nightly report) goes in a **job
+function**: `"job": true` in `hawk-app.json`. The app starts it, gets a job id at once, and reads the result later.
+
+```jsonc
+"functions": {
+    "export-report": { "job": true, "timeoutSeconds": 600 }
+}
+```
+
+```ts
+// functions/export-report.ts
+export const handler: HawkFunction<{ month: string }, { rows: number }> = async (input, ctx) => {
+    const pages = await loadPages(input.month);
+    for (const [i, page] of pages.entries()) {
+        await writePage(page);
+        await ctx.job?.progress(Math.round(((i + 1) / pages.length) * 100), `Page ${i + 1} of ${pages.length}`);
+    }
+    return { rows: pages.length };
+};
+```
+
+```ts
+// In the app
+const { jobId } = await app.functions.start('export-report', { month: '2026-09' });
+try {
+    const job = await app.functions.wait<{ rows: number }>(jobId, {
+        onProgress: (j) => setStatus(j.progress?.message ?? j.status),
+    });
+    console.log(job.result!.rows);
+} catch (error) {
+    if (error instanceof FunctionJobError) console.log(error.job.status, error.job.error?.type); // failed / timed_out
+}
+```
+
+- `app.functions.start(name, input?, { signal? })` resolves to `{ jobId }` once the job is queued (202). A job
+  function can only be started and a normal function only called (409 `function_is_job` / `function_not_job`).
+- `app.functions.wait(jobId, { timeoutMs?, intervalMs?, onProgress?, signal? })` checks the job every `intervalMs`
+  (default 2 s) and resolves with the `succeeded` job; it throws `FunctionJobError` (with `.job`) when the job
+  `failed` or `timed_out`, and HawkApiError 408 `job_wait_timeout` after `timeoutMs` (default 15 min; the job keeps
+  running). `onProgress` gets the job whenever its status or progress changes.
+- `app.functions.job(jobId)` reads it once: `{ jobId, function, status, progress, result, error, createdAt,
+  finishedAt, trigger }`, `status` one of `queued`, `running`, `succeeded`, `failed`, `timed_out`. Store the id to
+  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 }`.
+- `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
+`too_many_jobs`, not retried); results up to 256 KB; jobs are kept 7 days (then 404 `job_not_found`, also for
+another app's or client's job). A job isn't retried when it fails.
+
+### Schedules
+
+`schedules` in `hawk-app.json` run a job function on a timer. A schedule does nothing until a user turns it on from
+the app, for their client: `app.schedules.enable(name)`.
+
+```jsonc
+"functions": { "nightly-report": { "job": true, "timeoutSeconds": 600 } },
+"schedules": {
+    "nightly": { "function": "nightly-report", "cron": "0 7 ? * MON-FRI *", "timezone": "America/Chicago" }
+}
+```
+
+```ts
+const schedules = await app.schedules.list();
+// [{ name: 'nightly', function: 'nightly-report', cron: '0 7 ? * MON-FRI *', timezone: 'America/Chicago',
+//    enabled: false, enabledBy: null, enabledAt: null, lastRun: null }]
+await app.schedules.enable('nightly');   // or disable('nightly'); both resolve to the schedule
+```
+
+- `cron` is an EventBridge cron with 6 fields (`minutes hours day-of-month month day-of-week year`, with `?` in
+  day-of-month or day-of-week) and runs **at most hourly** (the minutes field is a single number); `timezone` is an
+  IANA name, default `UTC`. At most 5 schedules per app, each running a job function of the same manifest.
+- A scheduled run is a job (`ctx.trigger.type === 'schedule'`) for the client and site where the user turned the
+  schedule on, as the user `schedule:<name>` (no roles, not internal), with that client's HawkSearch connection. Its
+  `lastRun` shows the job it started, or `skipped` with a `reason`.
+- 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.
+
+## Email: `email:send`
+
+Send an email from the app or from a [function](#functions-functionsinvoke): a report to the user, an alert, a
+digest. The platform sends it; your app never gets mail credentials.
+
+Add `"email:send"` to `scopes` in `hawk-app.json` and deploy (`hawk-app deploy` sends hawk-app.json with the version): any app with the scope can send. Without it, sends fail
+with `scope_missing`.
+
+```ts
+// functions/weekly-digest.ts: from a function, as the caller
+import type { HawkFunction } from '@bridgeline-digital/hawk-app-bridge/server';
+
+export const handler: HawkFunction<void, { messageId: string }> = async (_input, ctx) => {
+    if (!ctx.user.email) throw new Error('The caller has no email address.');
+    const top = await ctx.platform.analytics.report('searches', { startDate: '2026-09-01', endDate: '2026-09-30', limit: 5 });
+    const { messageId } = await ctx.platform.email.send({
+        to: ctx.user.email,
+        subject: 'Your top searches',
+        text: top.data.map((row) => JSON.stringify(row)).join('
+'),
+        html: `<p>${top.data.length} rows</p>`,
+    });
+    return { messageId };
+};
+```
+
+```ts
+// Or straight from the app
+const { messageId, recipients } = await app.email.send({ to: ['a@example.com', 'b@example.com'], subject: 'Export ready', text: 'Your export is ready.' });
+```
+
+`app.email.send({ to, subject, text?, html?, replyTo? }, { signal? })` (and `ctx.platform.email.send`, the same)
+resolves to `{ messageId, recipients }`.
+
+- **Sender**: `"<App name> (HawkSearch)" <noreply@hawksearch.com>`, with your app's name. Nobody reads replies to it:
+  set `replyTo` (one address) if recipients should be able to answer.
+- **Recipients**: `to` is one address or up to 10 unique ones, plain addresses only (no display names, no cc/bcc).
+  Apps can email anyone, so only send what the recipient should see, and never secrets.
+- **Content**: `subject` 1–200 characters on one line; at least one of `text` / `html`, together at most 256 KB.
+- **Limit**: 200 recipients per app and client per UTC day (a 10-recipient send counts 10), for every version of the
+  app together. Over it, sends fail with `email_limit_reached` until UTC midnight (`error.retryAfterMs`). Sends are
+  never retried for you.
+- **Audit**: every send is logged with the app, version, client, user, recipient count and domains and the message
+  id. The subject and body are never stored.
+
+**Errors** come back as `HawkApiError`:
+
+| Code | Status | Meaning |
+|---|---|---|
+| `scope_missing` | 403 | The app doesn't have the `email:send` scope. |
+| `invalid_email` | 400 | A field is missing or wrong; the response's `errors` (in `error.body`) lists each one. |
+| `request_too_large` | 413 | The body is over 256 KB. |
+| `email_limit_reached` | 429 | The app's daily limit for this client is used up; `retryAfterMs` is the time until it resets. |
+| `email_rejected` | 400 | The mail service refused the message (e.g. an address it can't deliver to). |
+| `email_unavailable` | 502 | The mail service failed: try again later. |
+
+## HawkSearch search: `hawksearch:search`
+
+Run real HawkSearch searches and autocompletes for the engine the user is working on, live or in **preview**
+(unpublished rules, a future date): before/after checks of a rule change, "do our top queries return results?",
+zero-result hunts. From the app or from a [function](#functions-functionsinvoke) (`ctx.platform.hawksearch`).
+
+```ts
+const results = await app.hawksearch.search({ Keyword: 'boots', MaxPerPage: 24 });
+results.Pagination?.NofResults; // HawkSearch's own v2 response
+
+// Preview: unpublished rules as of a date (the engine's time zone)
+await app.hawksearch.search({ Keyword: 'boots', IsInPreview: true, SmartBar: { PreviewDate: '2026-11-27T00:00:00' } });
+
+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.
+- `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.
+- Read-only, so the scope doesn't stop an app from being auto-approved.
+
+| `error.code` | Status | Meaning |
+|---|---|---|
+| `scope_missing` | 403 | Add `hawksearch:search` to `scopes`. |
+| `engine_required` | 400 | The host session has no engine. |
+| `search_not_available` | 404 / 503 | The engine isn't active, or has no search API set up in HawkSearch. |
+| `search_needs_site_key` | 403 | The engine requires authenticated searches and the session only has a group API key. |
+| `too_many_requests` | 429 | Over the per-minute limit; wait `retryAfterMs`. |
+| `hawksearch_unavailable` | 502 | HawkSearch didn't answer: try again. |
+
+Other HawkSearch errors (e.g. `400` for an unknown `IndexName`) come back as HawkSearch sent them.
+
+## HawkSearch system parameters: `hawksearch:sysparams:write`
+
+Let users change a few HawkSearch **system parameters** of the engine they are working on (Sites → System Parameters
+in HawkSearch) from the app or from a [function](#functions-functionsinvoke), e.g. a setup wizard that sets the time
+zone and the preview URL.
+
+Add the scope and list the parameters the app may touch in `hawk-app.json`:
+
+```json
+{
+    "scopes": ["hawksearch:sysparams:write"],
+    "systemParameters": ["Timezone", "SearchPreviewURL"]
+}
+```
+
+The list is reviewed like scopes: it goes with the version, which waits for approval in HawkSearch (`hawk-app status`:
+`settings    waiting for review: systemParameters`), and only the approved list counts. Up to 50 names (letters, digits, `_`, `.`, `-`; up to 50
+characters each), matched case-insensitively. The scope needs a non-empty list, and the list needs the scope.
+
+```ts
+const { engineId, parameters } = await app.hawksearch.systemParameters.list();
+// parameters: [{ name: 'Timezone', label: 'Time zone', group: 'General', type: 'TIMEZONE',
+//                value: 'Eastern Standard Time', encrypted: false, readOnly: false }, ...]
+
+const timezone = await app.hawksearch.systemParameters.get('Timezone');
+
+const { value, previous, appliesWithinSeconds } = await app.hawksearch.systemParameters.set('Timezone', 'UTC');
+await app.hawksearch.systemParameters.set('SearchPreviewURL', null); // null or "" clears it
+// A declared parameter the engine doesn't have yet: create it (AE only, label/type optional), then set it.
+await app.hawksearch.systemParameters.set('packageTier', 'Premium', { create: { group: 'HawkAI Configuration', label: 'Package Tier' } });
+```
+
+`ctx.platform.hawksearch.systemParameters` in a function is the same, as the caller.
+
+- **Which engine**: always the user's current engine in the host (`context.engine`), sent by the host when it issues
+  the app token, never chosen by the app. After the user switches engines, the host issues tokens for the new engine.
+  Only that engine changes: it is not synchronized to the other engines of a group.
+- **Who can set**: any user who can open the app. Every change is logged in HawkSearch (the parameter's history and
+  the activity log, as `<user> via Hawk Apps (<slug>)`) and in the platform's audit log.
+- **Which parameters**: only the declared ones that exist for the engine, including "AE only" ones (shown in red in
+  HawkSearch). Encrypted, global and read-only parameters are never settable; `list` leaves out global ones and
+  returns encrypted ones with `value: null`.
+- **Values** are strings, checked against the parameter's type: `STRING` (up to 1000 characters), `EMAIL`,
+  `INTEGER`, `FLOAT`, `YESNO` (`"0"` / `"1"`; `"true"` / `"false"` are accepted), `TIMEZONE` (a Windows time zone id,
+  e.g. `"Eastern Standard Time"`), `DIMENSION` (`"width;height"`). Other types can't be set yet. Setting the current
+  value again changes nothing.
+- **When it applies**: HawkSearch caches system parameters, so a change applies within about **3 minutes**
+  (`appliesWithinSeconds`: 180). Calls are never retried for you.
+
+**Errors** come back as `HawkApiError`:
+
+| Code | Status | Meaning |
+|---|---|---|
+| `scope_missing` | 403 | The app doesn't have the `hawksearch:sysparams:write` scope. |
+| `engine_required` | 400 | The host didn't send an engine with the token (no engine selected). |
+| `engine_not_allowed` | 403 | The engine doesn't belong to the token's client. |
+| `parameter_not_found` | 404 | Not declared in `systemParameters`, or the engine has no such parameter (also for global ones; AE-only parameters work when declared). |
+| `parameter_read_only` | 403 | The parameter is read-only. |
+| `parameter_encrypted` | 400 | Encrypted parameters can't be set. |
+| `parameter_type_unsupported` | 400 | Parameters of this type can't be set yet. |
+| `invalid_value` | 400 | The value doesn't fit the parameter's type (the message says why). |
+| `hawksearch_db_unavailable` | 502 | HawkSearch couldn't be reached: try again later. |
+| `sysparams_not_configured` | 503 | System parameters aren't enabled on this platform yet. |
+
+## HawkSearch features: `hawksearch:features:write`
+
+Turn HawkSearch features on and off for the user's current engine: the Feature Configuration's additional features
+(`aiassistant`, `didYouMean`, `sortingSets`, …) and facet features (`tooltip`, `swatch`, `collapsible`, …). Add
+`"hawksearch:features:write"` to `scopes`; it's elevated (never auto-approved) and reaches every feature, paid add-ons
+included.
+
+```ts
+const { features, facetFeatures } = await app.hawksearch.features.list();   // [{ code, enabled, known }]
+await app.hawksearch.features.set('aiassistant', true);
+await app.hawksearch.features.setFacet('tooltip', false);                   // { code, enabled, known, changed, appliesWithinSeconds }
+```
+
+Each call changes one code and keeps the others. Codes HawkSearch knows are stored in its spelling; any other code of
+letters and digits is accepted (a feature HawkSearch adds later works at once) and answered with `known: false`.
+Changes apply within about 3 minutes. Errors are those of system parameters, plus `invalid_feature` (400) for a code
+that isn't 1-50 letters and digits.
+
+## HawkSearch index rebuilds: `hawksearch:index`
+
+Rebuild the user's current engine's index from its feed, as HawkSearch's Rebuild Index button does, and follow it. Add
+`"hawksearch:index"` to `scopes`; it's elevated (never auto-approved), since a rebuild reloads the client's live search.
+
+```ts
+const run = await app.hawksearch.index.rebuild();             // { notificationId, status: 'new', done: false, … }
+const final = await app.hawksearch.index.wait(run.notificationId!, {
+    onProgress: (r) => setStatus(`${r.status} (${r.count ?? 0} items)`),
+});                                                           // { status: 'success' | 'error' | …, done: true, count, durationSeconds }
+const latest = await app.hawksearch.index.status();           // the engine's latest rebuild, by anyone
+```
+
+- **Only where the engine allows it**: HawkSearch's `EnableRebuildIndex` system parameter must be on for the engine
+  (it's the switch for HawkSearch's own button). Otherwise 403 `index_rebuild_disabled`.
+- **One at a time per engine**: while a rebuild is `new`, `pending`, `processing` or `queue` (from this app or anyone),
+  `rebuild()` answers 409 `index_in_progress` with the running one in `current`. A rebuild is done when its status is
+  `success`, `error`, `duplicated` or `suspended`.
+- **Full rebuilds only**, from the engine's configured feed. There's no cancel, and progress is the status and item
+  count, not a percentage. Rebuilds take minutes: `wait` checks every 15 s by default, for up to an hour.
+- **Site keys only**: with a group key, 403 `hawksearch_index_needs_site_key` (HawkSearch would rebuild the group's
+  parent site). At most 2 rebuild requests per app and client per minute (429 `too_many_requests`). Every rebuild is
+  audit-logged (app, client, engine, user).
+- Other errors: `index_never_rebuilt` / `index_run_not_found` (404), `index_wait_timeout` (408, from `wait`),
+  `hawksearch_failed` / `hawksearch_unavailable` / `hawksearch_credentials_rejected` (502).
+
+### The Indexing API: `hawksearch:index`, `:index:items`, `:index:manage`
+
+For engines with their own indexes (HawkSearch's Indexing API), apps can read, change and manage the indexes
+themselves. Three scopes, all elevated, so an approver sees exactly what an app can do:
+
+| Scope | Calls |
+| --- | --- |
+| `hawksearch:index` | `indexes()`, `current()`, and reads with `call`: `'inactive'`, `'hierarchy'`, `'mappings'`, `'embedding/progress'`, `` `embedding/status/${id}` `` |
+| `hawksearch:index:items` | `items.upsert(items)`, `items.update(items)`, `items.delete(ids)`, and with `call`: `'add-attributes-to-items'`, `'update-attributes-of-items'`, `'remove-attributes-from-items'`, `'update-nested'`, `'remove-nested'`, `'bulk-update-nested'`, `'bulk-remove-nested'`, `'bulk-item-operations'` |
+| `hawksearch:index:manage` | `create({ suffix })`, `setCurrent(name)`, `deleteIndex(name)`, `rebuildAll(name)`, and with `call`: `'swap'`, `'rebuild-autocomplete'`, `'rebuild-percolator'`, `'rebuild-learning'`, `'rebuild-related'`, `'rebuild-embedding'`, `'hierarchy/upsert'`, `'hierarchy/rebuild'`, `'hierarchy/delete-items'`, `'hierarchy/delete-all'`, `'mappings/upsert'`, `'mappings/invalidate-cache'` |
+
+```ts
+// Update prices on the live index: each field is an array of values, with the engine's primary key.
+const result = await app.hawksearch.index.items.update([{ id: ['sku-1'], price: [79.99] }]);   // { Status, Summary, Items }
+
+// Build a new index, fill it, then switch live search to it.
+const name = await app.hawksearch.index.create({ suffix: 'spring' });
+await app.hawksearch.index.items.upsert(batch, { indexName: name });   // up to 125 items a call
+await app.hawksearch.index.rebuildAll(name);
+await app.hawksearch.index.setCurrent(name);
+```
+
+- **Live at once.** Item writes default to the engine's current index, and HawkSearch applies them immediately. Pass
+  `indexName` to change another one. HawkSearch checks each item against the engine's fields and primary key: a write
+  with any failed item is a 400 with HawkSearch's per-item `Status`.
+- **Limits:** 125 items (or 1000 ids) per call, 5 MB; 120 item writes and 10 management calls per app and client per
+  minute (429 `too_many_requests`). Site keys only. Writes are audit-logged (operation, index, count), never retried.
+- **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.
+
+## HawkSearch recommendations: `hawksearch:recommendations`
+
+HawkSearch's recommendation widgets for the user's current engine, as its storefront gets them. Add
+`"hawksearch:recommendations"` to `scopes` (not elevated: read-only storefront results).
+
+```ts
+const { widgetItems } = await app.hawksearch.recommendations({
+    widgetUids: [{ widgetGuid: '8a6d…', uniqueId: 'sku-1' }],      // the widget, and the product being viewed (if its model needs one)
+    contextProperties: { uniqueidlist: 'sku-1,sku-2' },            // e.g. a cart
+});
+for (const item of widgetItems?.[0]?.recommendationItems ?? []) console.log(item.itemName, item.price);
+```
+
+The request is HawkSearch's own ([Recommendation API](https://developerdocs.hawksearch.com/docs/recommendation-api)):
+`widgetUids` for one context, or `widgets` (up to 10, each with its own `contextProperties`) for the bulk endpoint;
+`renderHTML: true` for the widget's HTML; `enablePreview` for preview rules. The platform sets the engine's
+`clientGuid`, adds a random `visitorId` and `visitId` when you send none (send the shopper's to personalize), and never
+lets the request count in the client's recommendation reports. Widget guids are on HawkSearch's Recommendations page (or
+`app.dashboard.get(...)` with `hawksearch:read`). Limited to 600 requests per app and client per minute (429
+`too_many_requests`). Errors: `invalid_request` (400), `recommendations_not_configured` (503), `hawksearch_unavailable`
+(502).
+
+## Storage: `storage`
+
+Keep the app's own data on the platform: settings, state, history. Each item is a JSON value (at most 350 KB) under a
+key, kept for the current client and shared by everyone at that client using the app, and by its functions and
+schedules (`ctx.platform.storage`). Add `"storage"` to `scopes` (not elevated).
+
+```ts
+const config = await app.storage.get<WatchConfig>('config');                  // { key, value, version, ... } or null
+await app.storage.put('config', { competitors }, { ifVersion: config?.version ?? 0 });  // 409 if someone changed it
+await app.storage.put(`hist#${sku}#2026-10`, points, { ttlDays: 400 });      // expires in 400 days
+const { items, cursor } = await app.storage.list({ prefix: 'match#', values: true });
+await app.storage.delete('draft');
+await app.storage.batch({ get: ['a', 'b'], put: [{ key: 'c', value: 1 }], delete: ['d'] });   // up to 25, each answered on its own
+const { items: count, bytes, maxBytes } = await app.storage.usage();
+```
+
+- **Keys:** 1–256 characters from `A–Z a–z 0–9 . _ - : / #`, not starting with `#`, and without empty, `.` or `..`
+  segments between slashes. Listing by prefix is the only query, so put what you look things up by first.
+- **Limits:**
+  - 100 MB and 100,000 items per app and client: 507 `storage_quota_exceeded` beyond.
+  - 600 reads and 300 writes per app and client per minute: 429 `too_many_requests` with `retryAfterMs`.
+- **Other errors:** 409 `version_conflict`, 413 `value_too_large`.
+- **Reviewers' previews** use the client's real data, so version your keys (`v2#config`) when you change their shape.
+
+**Files** (up to 100 MB each; 5 GB and 50,000 per app and client) go straight between the app and the platform's
+bucket through short-lived signed requests:
+
+```ts
+await app.storage.files.upload('exports/prices.csv', csv, { contentType: 'text/csv', ttlDays: 30 });  // Blob, bytes or text
+const { url } = await app.storage.files.url('logos/acme.png');      // a 5-minute link: <img src={url}>, or { download: 'name' }
+const blob = await app.storage.files.download('exports/prices.csv');
+const { files, cursor } = await app.storage.files.list({ prefix: 'exports/' });
+await app.storage.files.delete('exports/prices.csv');
+```
+
+- **Paths:** segments of `A–Z a–z 0–9 . _ -` between slashes.
+- **Expiry:** `ttlDays` is 1 to 365 (rounded up to 1, 7, 30, 90 or 365).
+- **Errors:** 413 `file_too_large`, 507 `storage_quota_exceeded`, `upload_failed` when the bucket refuses the upload.
+- **Usage:** `usage()` counts files a few seconds after they land.
+
+See the platform's docs/storage.md.
+
+## External Lambdas: `lambdas:invoke`
+
+Call a Lambda written outside Hawk Apps (for example HawkAnalytics' client setup) from the app or a function. Declare
+it by name and add the scope; on a released app the change waits for approval, and Bridgeline Engineering allows each Lambda
+on the platform.
+
+```json
+{ "scopes": ["lambdas:invoke"], "lambdas": ["analytics-client-setup"] }
+```
+
+```ts
+const status = await app.lambdas.invoke('analytics-client-setup', { action: 'status' });   // or ctx.platform.lambdas
+```
+
+The Lambda receives `{ caller, input }`: `caller` (client, user, engine, roles) comes from the app token, so it can't be
+faked from the browser; `input` is what you pass. Calls are never retried. Errors: `lambda_not_allowed` (404),
+`too_many_calls` (429, 30 a minute per app and client), `lambda_failed` / `lambda_unavailable` (502), `lambda_timeout`
+(408, after `timeoutMs`, default 35 s). See the platform's docs/external-lambdas.md.
+
+## App config
+
+Settings the app reads at runtime that someone changes without a deploy: who gets a notification email, a threshold, a
+feature switch. Declare each key, its type and an optional default in `config` in hawk-app.json (the declarations are
+reviewed like any setting); the values are set from the Hawk Analytics portal or with `npx hawk-app config set`, for the
+whole app (global) or for one client, and apply within about 30 seconds, with no deploy or approval.
+
+```json
+{
+    "config": {
+        "signupNotifyEmails": {
+            "type": "emails",
+            "label": "Sign-up notification recipients",
+            "description": "Who is emailed when a client signs up.",
+            "default": ["support@example.com"]
+        },
+        "connectorsRequestEmails": { "type": "emails", "label": "API Connections request recipients" }
+    }
+}
+```
+
+```ts
+const all = await app.config.all();                               // { signupNotifyEmails: [...], connectorsRequestEmails: null }
+const to = await app.config.get<string[]>('signupNotifyEmails');  // the value, or null
+// In a function: ctx.config.signupNotifyEmails (already resolved), or ctx.platform.config.get(...)
+```
+
+- **Not secret:** values reach the browser, so anyone using the app can see them. Keep API keys and passwords in
+  [secrets](#functions-functionsinvoke) (`hawk-app secrets`, or `app.clientSecrets` for each client's own).
+- **Resolution:** the caller's client value, else the global value, else the declared `default`, else `null`. A stored
+  value that no longer matches the key's type is skipped. Every declared key is in `all()`; `get` returns `null` for a
+  key the app doesn't declare and throws a `TypeError` for an empty key.
+- **Declarations:** at most 50 keys, names `^[A-Za-z][A-Za-z0-9_]{0,63}$`. Each has a `type` (`string`, `number`,
+  `boolean`, `emails`, `json`), an optional `label` (up to 100 characters), `description` (up to 500) and `default`.
+- **Values by type:** `string` up to 4000 characters; `number` finite; `boolean`; `emails` a list of up to 50 distinct
+  plain addresses (`a@example.com`, no display names); `json` any JSON but `null`. At most 16 KB each.
+- **No scope** is needed. Functions get the values for their own version, the app the ones for the version it has open.
+- **Set values** with `npx hawk-app config set signupNotifyEmails a@example.com,b@example.com [--client e3141]`,
+  `config unset`, and `config list`, or in the Hawk Analytics portal.
+
+| Code | Status | Meaning |
+|---|---|---|
+| `config_key_not_declared` | 404 | Setting a key that isn't in `config` in hawk-app.json. |
+| `invalid_config_value` | 400 | The value doesn't match the key's type. |
+| `invalid_client` | 400 | The client id isn't a valid client id. |
+| `value_too_large` | 413 | The value is over 16 KB. |
+
+## AI: `ai:invoke`
+
+Ask Claude from the app or from a [function](#functions-functionsinvoke) (`ctx.platform.ai`): summarize a report,
+draft synonyms, explain a zero-result query. The platform calls the model; your app never holds a model key.
+
+Add `"ai:invoke"` to `scopes` in `hawk-app.json` and deploy. It is an **elevated** scope: an app with
+it is never auto-approved, and approvers review it like dashboard writes.
+
+```ts
+// The whole answer at once
+const { text, usage } = await app.ai.generate({ prompt: 'Suggest 5 synonyms for "sneakers", one per line.' });
+
+// Or as it is written
+const stream = app.ai.stream({
+    model: 'smart',
+    system: 'You are a HawkSearch merchandising assistant. Answer in short bullet points.',
+    messages: [{ role: 'user', content: `Explain these zero-result queries: ${queries.join(', ')}` }],
+    maxTokens: 800,
+});
+for await (const text of stream) {
+    output.textContent += text;
+}
+const { stopReason, usage: { inputTokens, outputTokens } } = await stream.result;
+```
+
+- **Tiers**: `model: 'fast'` (the default; Claude Haiku: quick, cheap answers) or `'smart'` (Claude Sonnet: harder
+  reasoning, longer answers).
+- **Request**: `prompt` (one user message) or `messages` (1–50 `{ role: 'user' | 'assistant', content }`, alternating,
+  first and last from the user), plus optional `system` (up to 32 KB), `maxTokens` (default 1024, up to the tier's
+  `maxOutputTokens`), `temperature` (0–1) and `stopSequences` (up to 4). At most 256 KB in all.
+- **Result**: `{ text, stopReason, usage: { inputTokens, outputTokens }, id, model }`. `stopReason` is `end_turn`,
+  `max_tokens` (raise `maxTokens`), `stop_sequence` or `content_filtered`.
+- **Streaming**: `stream(request)` yields the text as it arrives; iterate it once, then `await stream.result`. Errors
+  are thrown by the loop and by `result`. `stream.abort()`, the `signal` option or leaving the loop early (`break`)
+  stops the request: both then reject with an `AbortError` (tokens generated so far still count).
+- **Usage**: `app.ai.info()` resolves to `{ tiers: [{ name, maxOutputTokens, dailyTokens, usedTokens }],
+  maxInputBytes, requestsPerMinute }`, with today's use for the current client.
+- **Limits**: a daily token budget (input + output) per app, client and tier, reset at UTC midnight, and a per-minute
+  request limit per app and client (all tiers). A request is checked against the budget before it runs and counted
+  after, so the last one of the day can go over by its own size. Calls are **never retried** for you: each one costs
+  tokens.
+- **Privacy**: prompts and answers are never logged or stored by the platform; it logs only the app, version, client,
+  user, tier, token counts, duration and outcome. Don't send secrets or personal data you don't need to.
+
+**Errors** come back as `HawkApiError`:
+
+| Code | Status | Meaning |
+|---|---|---|
+| `scope_missing` | 403 | The app doesn't have the `ai:invoke` scope. |
+| `invalid_ai_request` | 400 | A field is missing or wrong; the response's `errors` (in `error.body`) lists each one. |
+| `request_too_large` | 413 | The request is over 256 KB. |
+| `too_many_requests` | 429 | Over the per-minute limit; wait `retryAfterMs`. |
+| `ai_budget_exhausted` | 429 | The tier's daily tokens for this client are used up; `retryAfterMs` is the time until UTC midnight. Try the other tier, or wait. |
+| `ai_not_configured` | 503 | AI isn't enabled on this platform. |
+| `ai_unavailable`, `ai_throttled`, `ai_failed` | 502 | The model failed while answering (the stream's `error`): try again later. Text already streamed is incomplete. |
+
+## Your own backend
+
+If your app has a server of its own (an API, a database, a job), it can trust who is calling and act for them with
+the **app token**, without any login of its own.
+
+```ts
+// In the app: send the token as a Bearer header on every call to your backend.
+const response = await fetch('https://my-tool-api.example.com/reports', {
+    headers: { Authorization: `Bearer ${await app.getToken()}` },
+});
+```
+
+```ts
+// On your server (Node, with `jose`): verify it against the platform's public keys.
+import { createRemoteJWKSet, jwtVerify } from 'jose';
+
+const keys = createRemoteJWKSet(new URL('https://<platform>/.well-known/jwks.json'));
+
+const { payload } = await jwtVerify(token, keys, {
+    issuer: 'urn:hawk-apps:prod', // urn:hawk-apps:dev on dev
+    audience: 'hawk-app:my-tool', // your slug
+    algorithms: ['RS256'],
+});
+// payload.client_id, payload.sub, payload.email, payload.roles, payload.scope ...
+```
+
+**Auth is a Bearer token, never a cookie.** Your app runs in a cross-site iframe, where browsers block or partition
+cookies (Safari always, Chrome increasingly), so a session cookie that works when you open the app directly fails
+inside the HawkSearch dashboard or Spark. Ask for a fresh token per request: `app.getToken()` caches it and refreshes it before it expires.
+
+The token contract is stable, and any JWT library that reads a JWKS can check it:
+
+| Claim | Value |
+|---|---|
+| header `alg` / `kid` | `RS256`, and the id of the key in the JWKS (keys rotate; let your library pick by `kid`) |
+| `iss` | `urn:hawk-apps:dev` or `urn:hawk-apps:prod` |
+| `aud` | `["hawk-apps-api", "hawk-app:<slug>"]`: check for your own `hawk-app:<slug>` |
+| `exp`, `iat`, `nbf` | about 10 minutes of validity |
+| `sub`, `email` | the user (id, and email when the host has one) |
+| `client_id`, `account_id` | the tenant (`account_id` when the host has one): scope everything you store by `client_id` |
+| `analytics` | `"none"` when the client has no analytics data set up (missing otherwise) |
+| `roles`, `internal` | the user's roles, and whether they are Bridgeline staff |
+| `app`, `host`, `scope` | your slug, the host (e.g. `spark`), the granted scopes |
+| `jti` | a unique id for the token |
+
+Your server can also call the platform with the same token (`Authorization: Bearer <token>`, e.g.
+`POST https://<platform>/v1/analytics/searches`), so data can be fetched server-side for the current user and client.
+Treat the token like a password: don't log it or store it.
+
+Server-rendered apps (SSR, where the server needs the user on the very first page load) are planned: the manifest
+already has `"hosting": "static"`, and `"server"` is reserved for them.
+
+## Errors
+
+Failed data calls throw `HawkApiError` with `status` and `code`; failed host requests throw `HawkBridgeError` with
+`code`.
+
+| Code | Meaning |
+|---|---|
+| `not_embedded` | The page was opened directly, not inside a host. |
+| `host_not_allowed` | The host isn't in `allowedHostOrigins`. |
+| `timeout` | The host didn't answer in time. |
+| `report_not_allowed` | The report name isn't a plain kebab-case name, or the platform blocks that report. Any other name is passed to the analytics API (`report('')` is its ad-hoc / natural-language root); a name it doesn't know comes back as its own `400`. |
+| `analytics_not_available` | Analytics isn't set up for this client (at once when `context.tenant.analyticsProvisioned` is `false`). |
+| `hawksearch_not_available` | No HawkSearch access: add `hawksearch:read` to your scopes and deploy again. |
+| `version_not_allowed` | You put an API version in a dashboard path: use `Synonym`, not `v11/Synonym`. |
+| `path_not_allowed` | The dashboard path isn't allowed (writes: see [Writing to HawkSearch](#writing-to-hawksearch-hawksearchwrite)). |
+| `hawksearch_write_needs_site_key`, `too_many_items`, `too_many_requests`, `invalid_path` | Dashboard writes: see [Writing to HawkSearch](#writing-to-hawksearch-hawksearchwrite). |
+| `query_*`, `invalid_params`, … | Custom queries: see [Custom data (queries)](#custom-data-queries-dataread). |
+| `function_*`, `functions_not_enabled`, `secret_missing`, … | Functions: see [Functions](#functions-functionsinvoke). |
+| `email_*`, `invalid_email` | Email: see [Email](#email-emailsend). |
+| `config_key_not_declared`, `invalid_config_value` | Config values: see [App config](#app-config). |
+| `engine_*`, `parameter_*`, `invalid_value`, … | System parameters: see [HawkSearch system parameters](#hawksearch-system-parameters-hawksearchsysparamswrite). |
+| `ai_*`, `invalid_ai_request` | AI: see [AI](#ai-aiinvoke). |
+| `*_unavailable`, `*_credentials_rejected` | Something is wrong on our side: retry later, and tell Engineering if it persists. |
+
+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).
+
+```ts
+try {
+    await app.functions.call('refresh', {});
+} catch (error) {
+    app.reportError(error); // reported like an uncaught one, and the app shows its own message
+    showMessage('Couldn’t refresh: try again.');
+}
+```
+
+`createApp({ reportErrors: false, reportOpens: false })` turns either off.
+
+## Talk to the host
+
+```ts
+await app.setTitle('Synonyms review');                    // the host's page title
+await app.toast('Export ready', 'success');               // info | success | warning | error
+await app.navigate({ intent: 'app', slug: 'other-tool' }); // also: 'report', 'settings', 'external' (https only)
+await app.resize();                                       // when autoResize is off
+```
+
+### 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
+user sees the question and the answer in the assistant's chat, so call it only from a click:
+
+```ts
+// Show the button only while the host has an assistant: it may load after the app (HawkSearch loads it through GTM).
+const [ready, setReady] = useState(!!app.context.features?.assistant);
+useEffect(() => app.onContextChange((c) => setReady(!!c.features?.assistant)), [app]);
+
+<Button disabled={!ready} onClick={() => app.assistant.ask('Which recommendation widgets earn the most this quarter?')}>
+    Ask Hawk 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:
+
+```ts
+useEffect(() => void app.assistant.setContext({ page: 'Recommendation Dashboard', range, totals, widgets }), [range, totals, widgets]);
+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
+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.
+
+| Intent | Goes to |
+| --- | --- |
+| `{ intent: 'app', slug, params? }` | Another app |
+| `{ intent: 'report', id? }` | The report list (HawkSearch: Report Library); with an `id`, that report where the host supports it |
+| `{ intent: 'settings', section? }` | The host's settings |
+| `{ intent: 'external', url }` | An https page in a new tab |
+
+Navigation takes *intents*, not URLs, so the same app works in every host.
+
+## Look and feel
+
+Every template gets this from the UI kit ([`@bridgeline-digital/hawk-app-ui`](../ui/README.md)), Spark's look in
+the host's colors and mode: a React + MUI app its theme, provider and components; any other app (vanilla, Preact,
+React, Next) its stylesheet and custom elements. The rest of this section is for apps that style themselves.
+
+With `applyTheme` on, the host's design tokens are set as CSS variables on `<html>`, and
+`<html data-hawk-theme="light|dark">` matches the host. Use them with your own fallbacks so the app also renders on
+its own:
+
+```css
+body {
+    background: var(--hawk-color-background, #f6f7f9);
+    color: var(--hawk-color-text-default, #1f2933);
+    font-family: var(--hawk-font-default, system-ui, sans-serif);
+}
+button {
+    background: var(--hawk-color-button-accent-background, #ff6a13);
+    color: var(--hawk-color-button-accent-text, #fff);
+    border-radius: var(--hawk-border-radius, 6px);
+}
+```
+
+Available: `--hawk-color-background`, `--hawk-color-background-container`, `--hawk-color-background-primary`,
+`--hawk-color-background-accent`, `--hawk-color-text-default`, `--hawk-color-text-heading`,
+`--hawk-color-text-secondary`, `--hawk-color-text-accent`, `--hawk-color-border-default`, `--hawk-color-border-accent`,
+`--hawk-color-button-accent-background`, `--hawk-color-button-accent-text`, `--hawk-font-default`,
+`--hawk-border-radius`.
+
+The host already shows your app's name above the frame, so you don't need a page heading.
+
+### Dialogs cover the whole page
+
+An open dialog (any `[role="dialog"]`, e.g. every MUI Dialog or Drawer) covers the host's whole page, not just the
+frame, with nothing to call:
+- **A frame that's fully on screen and big enough**: the host dims the page around the frame to match your dialog's
+  backdrop (`modalBackdrop` on the host, default MUI's `rgba(0, 0, 0, 0.5)`). A click there sends Escape to the dialog.
+- **Any other frame** (a preview, a slot, a short or narrow frame, or a tall page scrolled partly out of view, where a
+  dialog fixed to the frame could open off screen): the host lifts the frame over the whole window while the dialog is
+  open. The bridge keeps your page exactly where the frame was (same width, same scroll, clipped to the frame's box)
+  on an otherwise transparent page, so the dialog shows full size over the dimmed host page with your content still
+  behind it; the frame goes back when the dialog closes.
+- The host page doesn't scroll meanwhile and keeps its scroll position, and auto-resize waits for the dialog to close.
+- Center dialogs in the visible part of the frame (`--hawk-visible-top` and `--hawk-visible-height`, see the templates'
+  theme). `createApp({ hostModals: false })` turns this off.
+
+## Local development
+
+Run your dev server on port 3100 (the templates do), then open the app in HawkSearch with `?devUrl=` pointing at it:
+
+```
+<HawkSearch>/admin/apps/my-tool?devUrl=http://localhost:3100/my-tool/
+```
+
+The HawkSearch dashboard loads your local copy instead of the deployed one, with the real context and real data, and hot reload works as
+usual. Dev mode is for Bridgeline users only and accepts only `http://localhost` addresses. The app must be registered
+for the client you're on (a draft is enough), and the dev platform accepts data calls from ports 3100 to 3103.
+
+## `hawk-app.json`
+
+The CLI sends this file to the platform with every `hawk-app deploy` (and `hawk-app dev`). It sets your app's visibility and what data it can read.
+Which clients have the app is not in this file: manage them in the Hawk Analytics portal or with `npx hawk-app clients`.
+
+```json
+{
+    "slug": "my-tool",
+    "name": "My Tool",
+    "description": "What it does, in one line.",
+    "visibility": "allowList",
+    "scopes": ["reports:read"]
+}
+```
+
+| Field | |
+|---|---|
+| `slug` | Unique id and the app's folder on the CDN (`/<slug>/`, one `v<n>/` folder per deploy). Can't change later. |
+| `icon` | An `.svg` (drawn in the host's color) or `.png` (shown as is) file next to `hawk-app.json`, e.g. `icon.svg`. New apps get a default `icon.svg`; without one, hosts show a default icon. |
+| `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). |
+| `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. |
+| `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"`. |
+
+Run `npx hawk-app deploy --dry-run` to see what would change without making a version (use it on pull requests), and
+`npx hawk-app clients` to see which clients have the app.
+
+**Who releases it.** There's no `status` field (an old one is ignored with a warning): every `hawk-app deploy` is a
+new version, with the hawk-app.json it was deployed with, and Bridgeline staff review apps on the Apps page in
+HawkSearch. See [versions, statuses and aliases](../../docs/versions-and-aliases.md).
+- Each version has a status: **draft** (deployed), **waiting** (submitted for approval), **approved** or **rejected**.
+  Only Bridgeline staff see versions that aren't approved, on the app's clients (or every client with
+  `"visibility": "all"`).
+- An approver **releases** a version: released to everyone, the built-in `default` alias moves to it, and every
+  client without another alias gets it. Other aliases (e.g. `pilot`) let some clients get a different version.
+- Once released, each new version and each settings change (name, scopes, `externalOrigins`, …) waits for approval,
+  and clients keep the released version until then. `npx hawk-app status` shows what's waiting.
+- 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.
+
+**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
+waiting request, so it has to be submitted again. `npx hawk-app status` shows whether it's waiting for approval or was
+rejected, and why.
+
+## Good to know
+
+- **No secrets in the app.** Everything in it is public. Credentials stay on the platform; API keys of your own go in
+  function secrets (see [Functions](#functions-functionsinvoke)).
+- **Outside origins are up to you.** An app can load scripts, styles, fonts and images from, embed, and call
+  (`fetch`, WebSockets) only the origins in `externalOrigins` (`"*"` allows any https origin, and fails the review
+  check). List the origins it really uses: the apps CDN blocks everything else (a Content-Security-Policy), so a compromised npm dependency can't send
+  data anywhere new. The platform API is always allowed. To show images from any site (for example a client's
+  product images) without opening anything else, use `"img:*"`. Dev mode on localhost has no such policy, so check a
+  deployed version in HawkSearch before it's released.
+- **Static files only.** Build to plain HTML, JS and CSS (`next build` with `output: 'export'`, `vite build`, …), with
+  the base path read from `HAWK_APP_BASE_PATH` (`/<slug>/v<n>`, set by `hawk-app deploy`; the templates do this).
+- **Tokens are handled for you.** `app.getToken()` exists for apps with a backend of their own; the token can be
+  verified against the platform's JWKS.
+- **Changes to client data are reviewed.** Apps change client data only through scopes that allow it:
+  `hawksearch:write`, `hawksearch:sysparams:write`, `hawksearch:features:write`, the `hawksearch:index` scopes and
+  `storage` (the app's own data). An approver reviews each one.
+