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

package/agents/AGENTS.md

@@ -1,192 +1,192 @@
-# __NAME__ (`__SLUG__`): a Hawk App
-
-A Hawk App is a static web app that runs in an iframe inside the HawkSearch dashboard (and later Spark), for one
-client at a time. It gets its context and all of its data through the bridge,
-`@bridgeline-digital/hawk-app-bridge`. It's deployed with the CLI,
-`@bridgeline-digital/hawk-app-cli` (`npx hawk-app`).
-
-## Rules
-
-- **No secrets in the app.** Everything in the build is public. Never add API keys, AWS credentials, database
-  connection strings or HawkSearch keys. The platform adds credentials server-side, and it takes the client from the
-  signed app token, so the app can only reach the current client's data. A third-party key goes in a function secret
-  (`npx hawk-app secrets set NAME`) and is used in a function, never in the browser.
-- **Settings that change without a deploy go in `config`.** Non-secret values (notification recipients, thresholds,
-  switches) are declared in `config` in `hawk-app.json` (type, label, default) and read with `app.config.get(key)`
-  (`ctx.config` in a function). Their values are set with `npx hawk-app config set` or in the Hawk Analytics portal,
-  never hard-coded. They reach the browser, so never put a key or password there.
-- **All data goes through the bridge.** Don't call HawkSearch, the analytics API, Athena or AWS directly from the
-  app. Use `app.analytics`, `app.dashboard`, `app.data`, `app.functions` and the others below.
-- **Static files only.** The build is plain HTML, JS and CSS: no SSR, API routes or middleware. Server code goes in
-  `functions/`.
-- **Every asset URL is under the version's base path.** Each deploy is served from `/<slug>/v<n>/`. `hawk-app deploy`
-  builds with `HAWK_APP_BASE_PATH=/__SLUG__/v<n>`; the build must use it (or only relative URLs). An absolute
-  `/assets/...` URL loads nothing once deployed.
-- **No cookies, no `localStorage` for auth.** The app runs in a cross-site iframe where browsers block cookies. For a
-  backend of your own, send `await app.getToken()` as a Bearer header.
-- **Ask for the fewest scopes.** Each one is in `hawk-app.json` and reviewed; elevated scopes are never auto-approved.
-- **List outside origins.** `externalOrigins` in `hawk-app.json` should list every https origin the app loads from or
-  calls (`[]` when none). The default `["*"]` fails review. To show images from hosts you can't list (a client's
-  product images), use `"img:*"`: images only, from any https origin, and it passes review.
-- **Handle a client without analytics.** When `app.context.tenant.analyticsProvisioned === false`, show a message
-  instead of calling `app.analytics` or `app.data`.
-- Don't add a page heading: the host shows the app's name above the frame.
-- Don't edit `hawk-app.json`'s `slug` (it can't change) and don't add `status`, `clients` or `excludeClients` (set in
-  HawkSearch and with `npx hawk-app clients`).
-
-## The bridge
-
-```ts
-import { createApp } from '@bridgeline-digital/hawk-app-bridge/client';
-
-const app = await createApp({ autoResize: true }); // rejects with code 'not_embedded' when opened outside a host
-render(app.context);
-app.onContextChange(render); // the user switched client, engine or dates
-```
-
-`app.context`: `tenant.clientId`, `tenant.analyticsProvisioned`, `engine { id, name }`, `site`,
-`dateRange { from, to, timeZone }`, `user { id, email, roles }`, `locale`, `theme`, `app.slug`.
-
-| Call | Scope |
-| --- | --- |
-| `app.analytics.report('queries', { limit, startDate, endDate, filters })` | `reports:read` |
-| `app.dashboard.get('Synonym')`: HawkSearch dashboard API, no API version in the path | `hawksearch:read` |
-| `app.dashboard.post/put/delete(path, body)`: merchandising and relevancy resources only, never retried | `hawksearch:write` |
-| `app.hawksearch.search(...)`, `app.hawksearch.autocomplete(...)` on the user's engine | `hawksearch:search` |
-| `app.data.query('name', params)`: your SQL in `queries/<name>.sql` + `.json` | `data:read` |
-| `app.functions.call('name', input)`, `.start/.wait/.job` for jobs: `functions/<name>.ts` exporting `handler` | `functions:invoke` |
-| `app.email.send(...)` | `email:send` |
-| `app.storage.get/put/delete/list/batch/usage`: the app's own JSON data per client (350 KB a value, `ttlDays`, `ifVersion`); `app.storage.files.upload/url/download/list/delete`: its files (100 MB each) | `storage` |
-| `app.hawksearch.systemParameters.list/get/set`: names listed in `systemParameters` | `hawksearch:sysparams:write` |
-| `app.hawksearch.features.list/set/setFacet` | `hawksearch:features:write` |
-| `app.hawksearch.index.rebuild()`, `.status(id?)`, `.wait(id)`: rebuild the engine's index from its feed (needs the engine's `EnableRebuildIndex` on; one at a time); `.indexes()`, `.current()` | `hawksearch:index` |
-| `app.hawksearch.index.items.upsert/update/delete(...)`: items in the engine's indexes, live at once (125 a call) | `hawksearch:index:items` |
-| `app.hawksearch.index.create/setCurrent/deleteIndex/rebuildAll(...)`, `.call('hierarchy/upsert', …)` and other management | `hawksearch:index:manage` |
-| `app.hawksearch.recommendations({ widgetUids: [{ widgetGuid, uniqueId? }] })`: recommendation widgets, untracked | `hawksearch:recommendations` |
-| `app.ai.generate/stream/info` | `ai:invoke` |
-| `app.lambdas.invoke('name', input)`: names listed in `lambdas`, allowed by Engineering | `lambdas:invoke` |
-| `app.config.get('key')`, `app.config.all()`: keys declared in `config`, the client's value, else the global one, else the default (null when none); not secret | none |
-| `app.assistant.ask('question')`, `app.assistant.setContext({ ...what's on screen })` (null clears): the host's assistant (Hawk Assistant) answers in its chat, as the user; only from a click, and only while `context.features?.assistant` is true (it can load after the app: `app.onContextChange`) | `assistant` |
-
-Also: `app.reportError(error)` for errors the app catches and handles (uncaught ones are reported on their own; see
-them with `hawk-app errors`), `app.setTitle`, `app.toast(message, 'info'|'success'|'warning'|'error')`,
-`app.navigate({ intent: 'app'|'report'|'settings'|'external', ... })` (intents, never URLs), `app.getToken()`,
-`app.api.get('me')` (`internal: true` for Bridgeline staff, from the signed token: use it for staff-only screens).
-Failed data calls throw `HawkApiError` (`status`, `code`); host requests throw `HawkBridgeError` (`code`). A 403
-`scope_missing` means the scope is missing from `hawk-app.json` or the app wasn't deployed again after adding it
-(`validate` and `deploy` warn about bridge calls whose scope is missing).
-Look: every template uses the Hawk Apps UI kit (`@bridgeline-digital/hawk-app-ui`) for Spark's look in the
-host's colors and mode: React + MUI apps (next-mui) its provider and components, every other app its stylesheet
-(`/css`) and elements (`/elements`); see this app's section below. Don't restyle it or add another font. For your own
-styles use its `--hawk-ui-*` variables (or the host's `--hawk-*` ones with your own fallbacks).
-Accessibility: approvers see an axe-core check of the built pages (critical issues fail it): label form fields, give
-images `alt`, keep one `<main>` and headings in order. `validate --build` shows the issues.
-Dialogs: any `[role="dialog"]` (every MUI Dialog) covers the host's whole page on its own, even from a small frame;
-center dialogs in the visible part of the frame (`--hawk-visible-top`, `--hawk-visible-height`, as the templates'
-theme does), and use in-page dialogs, never `window.confirm`/`alert` (blocked in the sandbox).
-
-Before using a call, read its section in the bridge README for the exact options, limits and error codes: the
-`hawk-apps` MCP server's `docs` tool (below), or
-`node_modules/@bridgeline-digital/hawk-app-bridge/README.md` when the bridge is installed, otherwise
-https://www.npmjs.com/package/@bridgeline-digital/hawk-app-bridge. Its TypeScript types are in the same package.
-
-## MCP server
-
-`.mcp.json` (Claude Code) and `.vscode/mcp.json` (VS Code) start the CLI's MCP server, `hawk-apps`, from
-`node_modules` (`npm install` first). Its tools: `docs` (the bridge, UI kit, CLI, `hawk-app.json` schema and the
-showcase app, which has working code for every feature), `ui_components` (the UI kit's components for this app's
-template: use them before writing your own), `validate`, `status` (with the review checks approvers will see),
-`analytics_reports` (every report `app.analytics.report()` can call, with its columns and filters),
-`hawksearch_api` (HawkSearch's dashboard, search, recommendation and indexing operations: fields, the bridge call, its scope),
-`data_tables` and `data_describe` (names and columns, never data), `logs`, `init`, `upgrade`,
-`deploy` (with `alias`, and `dryRun` to only show what hawk-app.json would change), `versions`, `why` (what a client sees, and why), `doctor` (what's wrong with the setup), `errors`, `usage`, and `clients` and `clients_add`, which only ever use the dev platform. Prefer them to guessing. When the
-user names a client ("deploy to OTC"), call `clients_add` with their words: it shows them a form to pick the exact
-client. With `alias` (`hawk-app clients add <id> --alias review`) the client gets that alias's version: on a version that
-isn't approved, only Bridgeline staff in it see the app. Only approvers change what a client whose users see the app
-gets. `hawk-app deploy out --alias staging` deploys off the main line: the version carries this hawk-app.json, `staging`
-points at it, and the version under review isn't touched. A plain `hawk-app deploy` sends hawk-app.json first, so scope
-changes go with the deploy. Client names aren't shared with you; don't ask for them in the chat. Its prompts (`check-before-submit`, `add-feature`,
-`explain-app`, `deploy-to-client`; in Claude Code `/mcp__hawk-apps__<name>`) are ready-made tasks that use them.
-
-## Icon
-
-`icon` in `hawk-app.json` is the app's icon file, next to it: `icon.svg` by default, which `create` and `init` add.
-- **An .svg** is drawn in the host's own color (HawkSearch, Spark; light and dark): only its shape counts, so draw it in
-  one color, on a square `viewBox` (e.g. `0 0 24 24`), at most 32 KB.
-- **A .png** is shown as is, for a full-color logo: square, 64 to 1024 px (256 is a good size), at most 256 KB.
-- `hawk-app validate` and `deploy` check it; `deploy` uploads it with each version, so an icon change is reviewed like
-  other settings. Leave `icon` out for the hosts' default icon. Names from HawkSearch's icon set are no longer used.
-
-## Views
-
-`views` in `hawk-app.json` declares pages of the build that hosts show inside other pages:
-- **`preview`:** shown live on the Apps page's cards, under the description.
-- **`"embeddable": true`:** Bridgeline users can place the view in app slots of HawkSearch pages (per engine or for
-  every client), with values for its `params`.
-
-Each view is a route, e.g. `src/app/views/preview/page.tsx` for `"path": "views/preview"`. It reads
-`app.context.view` (`{ name, params, embedded, maxHeight }`). In a view:
-- Keep it small and fast: read stored results, not reports. Many views can share a page.
-- The page background is transparent (the host's shows through) and the height fits the content: never set
-  `html, body { height: 100% }`, or it can't shrink.
-- Toasts and title changes are ignored; `app.navigate({ intent: 'app', slug })` opens the full app.
-- `"cacheMinutes": n` (0–1440) on a view caches its reads (data queries, reports, `dashboard.get`, search,
-  recommendations) on the platform for n minutes, per client and engine. A `preview` caches 60 minutes by default
-  (`0` turns it off); other views don't unless they say so. Pass
-  `{ cache: 'no-store' }` on a call that writes (e.g. an analytics report that records something), or
-  `{ cache: 'reload' }` to refresh. The full app page is never cached.
-
-A slot can also hold the **entire app** (its own page, with no `view` in the context): it then runs inside another
-page, at the slot's height, so don't rely on the full window either.
-
-## Queries and functions
-
-- **Queries** (`queries/<name>.sql` + `<name>.json`, next to `hawk-app.json`): one `SELECT`/`WITH`, `?` for each
-  parameter in order, plain table names. Every query with a date range needs `{{partitions(from, to)}}`, names its
-  columns (no `SELECT *`) and has a `LIMIT` on lists; review flags any that don't. `npx hawk-app data tables` and
-  `npx hawk-app data describe <table>` show the tables and columns.
-- **Functions** (`functions/<name>.ts`, settings under `functions` in `hawk-app.json`): Node 22 Lambda,
-  `export const handler: HawkFunction<In, Out> = async (input, ctx) => ...` with `HawkFunction` from
-  `@bridgeline-digital/hawk-app-bridge/server`. Use `ctx.platform` (same APIs as `app`), `ctx.secrets.NAME`,
-  `ctx.client.id`, `ctx.user`. Stateless; 25 s, or 900 s for a job (`"job": true`). Engineering enables functions per
-  app.
-
-## Project
-
-__PROJECT__
-
-## Commands
-
-```bash
-npx hawk-app doctor              # check the setup (Node, login, hawk-app.json, scopes the code uses) and what to fix
-npm run app:dev                  # run the app locally in a stand-in for HawkSearch (asks which client the first time)
-npx hawk-app validate            # check hawk-app.json, queries/ and functions/ (--build also checks the build's URLs)
-npm run app:audit                # npm audit of the production dependencies: fix high and critical before deploying
-npm run app:deploy               # build and upload a new version, with hawk-app.json (dev unless --env prod)
-npx hawk-app deploy --dry-run    # what hawk-app.json would change, without a version
-npx hawk-app status              # released and newest versions, the request, the aliases
-npx hawk-app versions            # every version with its status and aliases
-npx hawk-app open                # the app's page in HawkSearch (review, submit for approval)
-npx hawk-app logs <function>     # a function's logs
-npx hawk-app config list         # config values (config set <key> <value> [--client <id>], config unset <key>)
-npx hawk-app errors              # errors in the app's pages (deployed versions), the most frequent first
-npx hawk-app usage               # opens, users and clients per day
-npx hawk-app upgrade             # bring the app (and this file) up to the CLI's current template
-npx hawk-app upgrade --channel latest  # a dev app (bridge/CLI on the `dev` tag) to the released versions
-```
-
-Deploy only when asked to. Never use `--env prod` unless asked to. If the bridge or CLI is on the
-`dev` tag (a dev app), its features may only exist on the dev platform: don't move it to `latest` or to prod unless
-asked to.
-
-## Review
-
-A new app is a draft that only Bridgeline staff see. Members of Hawk-App-Developers submit it (and each later version
-or settings change) for approval in HawkSearch; Hawk-App-Approvers approve it. The approve dialog runs automated
-checks, and a failed check forces the approver to override it:
-
-- **Bundle:** over 20 MB in total, any file over 5 MB, or 50% (and 1 MB) bigger than the released version.
-- **Dependencies:** high or critical `npm audit` findings in the production dependencies, or no audit.
-- **Outside origins:** `externalOrigins` is `["*"]`.
-- **Queries:** a query without `{{partitions(...)}}`; `SELECT *` and a missing `LIMIT` are flagged too.
-- Functions, external Lambdas and new outside origins are shown to the approver.
+# __NAME__ (`__SLUG__`): a Hawk App
+
+A Hawk App is a static web app that runs in an iframe inside the HawkSearch dashboard (and later Spark), for one
+client at a time. It gets its context and all of its data through the bridge,
+`@bridgeline-digital/hawk-app-bridge`. It's deployed with the CLI,
+`@bridgeline-digital/hawk-app-cli` (`npx hawk-app`).
+
+## Rules
+
+- **No secrets in the app.** Everything in the build is public. Never add API keys, AWS credentials, database
+  connection strings or HawkSearch keys. The platform adds credentials server-side, and it takes the client from the
+  signed app token, so the app can only reach the current client's data. A third-party key goes in a function secret
+  (`npx hawk-app secrets set NAME`) and is used in a function, never in the browser.
+- **Settings that change without a deploy go in `config`.** Non-secret values (notification recipients, thresholds,
+  switches) are declared in `config` in `hawk-app.json` (type, label, default) and read with `app.config.get(key)`
+  (`ctx.config` in a function). Their values are set with `npx hawk-app config set` or in the Hawk Analytics portal,
+  never hard-coded. They reach the browser, so never put a key or password there.
+- **All data goes through the bridge.** Don't call HawkSearch, the analytics API, Athena or AWS directly from the
+  app. Use `app.analytics`, `app.dashboard`, `app.data`, `app.functions` and the others below.
+- **Static files only.** The build is plain HTML, JS and CSS: no SSR, API routes or middleware. Server code goes in
+  `functions/`.
+- **Every asset URL is under the version's base path.** Each deploy is served from `/<slug>/v<n>/`. `hawk-app deploy`
+  builds with `HAWK_APP_BASE_PATH=/__SLUG__/v<n>`; the build must use it (or only relative URLs). An absolute
+  `/assets/...` URL loads nothing once deployed.
+- **No cookies, no `localStorage` for auth.** The app runs in a cross-site iframe where browsers block cookies. For a
+  backend of your own, send `await app.getToken()` as a Bearer header.
+- **Ask for the fewest scopes.** Each one is in `hawk-app.json` and reviewed; elevated scopes are never auto-approved.
+- **List outside origins.** `externalOrigins` in `hawk-app.json` should list every https origin the app loads from or
+  calls (`[]` when none). The default `["*"]` fails review. To show images from hosts you can't list (a client's
+  product images), use `"img:*"`: images only, from any https origin, and it passes review.
+- **Handle a client without analytics.** When `app.context.tenant.analyticsProvisioned === false`, show a message
+  instead of calling `app.analytics` or `app.data`.
+- Don't add a page heading: the host shows the app's name above the frame.
+- Don't edit `hawk-app.json`'s `slug` (it can't change) and don't add `status`, `clients` or `excludeClients` (set in
+  HawkSearch and with `npx hawk-app clients`).
+
+## The bridge
+
+```ts
+import { createApp } from '@bridgeline-digital/hawk-app-bridge/client';
+
+const app = await createApp({ autoResize: true }); // rejects with code 'not_embedded' when opened outside a host
+render(app.context);
+app.onContextChange(render); // the user switched client, engine or dates
+```
+
+`app.context`: `tenant.clientId`, `tenant.analyticsProvisioned`, `engine { id, name }`, `site`,
+`dateRange { from, to, timeZone }`, `user { id, email, roles }`, `locale`, `theme`, `app.slug`.
+
+| Call | Scope |
+| --- | --- |
+| `app.analytics.report('queries', { limit, startDate, endDate, filters })` | `reports:read` |
+| `app.dashboard.get('Synonym')`: HawkSearch dashboard API, no API version in the path | `hawksearch:read` |
+| `app.dashboard.post/put/delete(path, body)`: merchandising and relevancy resources only, never retried | `hawksearch:write` |
+| `app.hawksearch.search(...)`, `app.hawksearch.autocomplete(...)` on the user's engine | `hawksearch:search` |
+| `app.data.query('name', params)`: your SQL in `queries/<name>.sql` + `.json` | `data:read` |
+| `app.functions.call('name', input)`, `.start/.wait/.job` for jobs: `functions/<name>.ts` exporting `handler` | `functions:invoke` |
+| `app.email.send(...)` | `email:send` |
+| `app.storage.get/put/delete/list/batch/usage`: the app's own JSON data per client (350 KB a value, `ttlDays`, `ifVersion`); `app.storage.files.upload/url/download/list/delete`: its files (100 MB each) | `storage` |
+| `app.hawksearch.systemParameters.list/get/set`: names listed in `systemParameters` | `hawksearch:sysparams:write` |
+| `app.hawksearch.features.list/set/setFacet` | `hawksearch:features:write` |
+| `app.hawksearch.index.rebuild()`, `.status(id?)`, `.wait(id)`: rebuild the engine's index from its feed (needs the engine's `EnableRebuildIndex` on; one at a time); `.indexes()`, `.current()` | `hawksearch:index` |
+| `app.hawksearch.index.items.upsert/update/delete(...)`: items in the engine's indexes, live at once (125 a call) | `hawksearch:index:items` |
+| `app.hawksearch.index.create/setCurrent/deleteIndex/rebuildAll(...)`, `.call('hierarchy/upsert', …)` and other management | `hawksearch:index:manage` |
+| `app.hawksearch.recommendations({ widgetUids: [{ widgetGuid, uniqueId? }] })`: recommendation widgets, untracked | `hawksearch:recommendations` |
+| `app.ai.generate/stream/info` | `ai:invoke` |
+| `app.lambdas.invoke('name', input)`: names listed in `lambdas`, allowed by Engineering | `lambdas:invoke` |
+| `app.config.get('key')`, `app.config.all()`: keys declared in `config`, the client's value, else the global one, else the default (null when none); not secret | none |
+| `app.assistant.ask('question')`, `app.assistant.setContext({ ...what's on screen })` (null clears): the host's assistant (Hawk Assistant) answers in its chat, as the user; only from a click, and only while `context.features?.assistant` is true (it can load after the app: `app.onContextChange`) | `assistant` |
+
+Also: `app.reportError(error)` for errors the app catches and handles (uncaught ones are reported on their own; see
+them with `hawk-app errors`), `app.setTitle`, `app.toast(message, 'info'|'success'|'warning'|'error')`,
+`app.navigate({ intent: 'app'|'report'|'settings'|'external', ... })` (intents, never URLs), `app.getToken()`,
+`app.api.get('me')` (`internal: true` for Bridgeline staff, from the signed token: use it for staff-only screens).
+Failed data calls throw `HawkApiError` (`status`, `code`); host requests throw `HawkBridgeError` (`code`). A 403
+`scope_missing` means the scope is missing from `hawk-app.json` or the app wasn't deployed again after adding it
+(`validate` and `deploy` warn about bridge calls whose scope is missing).
+Look: every template uses the Hawk Apps UI kit (`@bridgeline-digital/hawk-app-ui`) for Spark's look in the
+host's colors and mode: React + MUI apps (next-mui) its provider and components, every other app its stylesheet
+(`/css`) and elements (`/elements`); see this app's section below. Don't restyle it or add another font. For your own
+styles use its `--hawk-ui-*` variables (or the host's `--hawk-*` ones with your own fallbacks).
+Accessibility: approvers see an axe-core check of the built pages (critical issues fail it): label form fields, give
+images `alt`, keep one `<main>` and headings in order. `validate --build` shows the issues.
+Dialogs: any `[role="dialog"]` (every MUI Dialog) covers the host's whole page on its own, even from a small frame;
+center dialogs in the visible part of the frame (`--hawk-visible-top`, `--hawk-visible-height`, as the templates'
+theme does), and use in-page dialogs, never `window.confirm`/`alert` (blocked in the sandbox).
+
+Before using a call, read its section in the bridge README for the exact options, limits and error codes: the
+`hawk-apps` MCP server's `docs` tool (below), or
+`node_modules/@bridgeline-digital/hawk-app-bridge/README.md` when the bridge is installed, otherwise
+https://www.npmjs.com/package/@bridgeline-digital/hawk-app-bridge. Its TypeScript types are in the same package.
+
+## MCP server
+
+`.mcp.json` (Claude Code) and `.vscode/mcp.json` (VS Code) start the CLI's MCP server, `hawk-apps`, from
+`node_modules` (`npm install` first). Its tools: `docs` (the bridge, UI kit, CLI, `hawk-app.json` schema and the
+showcase app, which has working code for every feature), `ui_components` (the UI kit's components for this app's
+template: use them before writing your own), `validate`, `status` (with the review checks approvers will see),
+`analytics_reports` (every report `app.analytics.report()` can call, with its columns and filters),
+`hawksearch_api` (HawkSearch's dashboard, search, recommendation and indexing operations: fields, the bridge call, its scope),
+`data_tables` and `data_describe` (names and columns, never data), `logs`, `init`, `upgrade`,
+`deploy` (with `alias`, and `dryRun` to only show what hawk-app.json would change), `versions`, `why` (what a client sees, and why), `doctor` (what's wrong with the setup), `errors`, `usage`, and `clients` and `clients_add`, which only ever use the dev platform. Prefer them to guessing. When the
+user names a client ("deploy to OTC"), call `clients_add` with their words: it shows them a form to pick the exact
+client. With `alias` (`hawk-app clients add <id> --alias review`) the client gets that alias's version: on a version that
+isn't approved, only Bridgeline staff in it see the app. Only approvers change what a client whose users see the app
+gets. `hawk-app deploy out --alias staging` deploys off the main line: the version carries this hawk-app.json, `staging`
+points at it, and the version under review isn't touched. A plain `hawk-app deploy` sends hawk-app.json first, so scope
+changes go with the deploy. Client names aren't shared with you; don't ask for them in the chat. Its prompts (`check-before-submit`, `add-feature`,
+`explain-app`, `deploy-to-client`; in Claude Code `/mcp__hawk-apps__<name>`) are ready-made tasks that use them.
+
+## Icon
+
+`icon` in `hawk-app.json` is the app's icon file, next to it: `icon.svg` by default, which `create` and `init` add.
+- **An .svg** is drawn in the host's own color (HawkSearch, Spark; light and dark): only its shape counts, so draw it in
+  one color, on a square `viewBox` (e.g. `0 0 24 24`), at most 32 KB.
+- **A .png** is shown as is, for a full-color logo: square, 64 to 1024 px (256 is a good size), at most 256 KB.
+- `hawk-app validate` and `deploy` check it; `deploy` uploads it with each version, so an icon change is reviewed like
+  other settings. Leave `icon` out for the hosts' default icon. Names from HawkSearch's icon set are no longer used.
+
+## Views
+
+`views` in `hawk-app.json` declares pages of the build that hosts show inside other pages:
+- **`preview`:** shown live on the Apps page's cards, under the description.
+- **`"embeddable": true`:** Bridgeline users can place the view in app slots of HawkSearch pages (per engine or for
+  every client), with values for its `params`.
+
+Each view is a route, e.g. `src/app/views/preview/page.tsx` for `"path": "views/preview"`. It reads
+`app.context.view` (`{ name, params, embedded, maxHeight }`). In a view:
+- Keep it small and fast: read stored results, not reports. Many views can share a page.
+- The page background is transparent (the host's shows through) and the height fits the content: never set
+  `html, body { height: 100% }`, or it can't shrink.
+- Toasts and title changes are ignored; `app.navigate({ intent: 'app', slug })` opens the full app.
+- `"cacheMinutes": n` (0–1440) on a view caches its reads (data queries, reports, `dashboard.get`, search,
+  recommendations) on the platform for n minutes, per client and engine. A `preview` caches 60 minutes by default
+  (`0` turns it off); other views don't unless they say so. Pass
+  `{ cache: 'no-store' }` on a call that writes (e.g. an analytics report that records something), or
+  `{ cache: 'reload' }` to refresh. The full app page is never cached.
+
+A slot can also hold the **entire app** (its own page, with no `view` in the context): it then runs inside another
+page, at the slot's height, so don't rely on the full window either.
+
+## Queries and functions
+
+- **Queries** (`queries/<name>.sql` + `<name>.json`, next to `hawk-app.json`): one `SELECT`/`WITH`, `?` for each
+  parameter in order, plain table names. Every query with a date range needs `{{partitions(from, to)}}`, names its
+  columns (no `SELECT *`) and has a `LIMIT` on lists; review flags any that don't. `npx hawk-app data tables` and
+  `npx hawk-app data describe <table>` show the tables and columns.
+- **Functions** (`functions/<name>.ts`, settings under `functions` in `hawk-app.json`): Node 22 Lambda,
+  `export const handler: HawkFunction<In, Out> = async (input, ctx) => ...` with `HawkFunction` from
+  `@bridgeline-digital/hawk-app-bridge/server`. Use `ctx.platform` (same APIs as `app`), `ctx.secrets.NAME`,
+  `ctx.client.id`, `ctx.user`. Stateless; 25 s, or 900 s for a job (`"job": true`). Engineering enables functions per
+  app.
+
+## Project
+
+__PROJECT__
+
+## Commands
+
+```bash
+npx hawk-app doctor              # check the setup (Node, login, hawk-app.json, scopes the code uses) and what to fix
+npm run app:dev                  # run the app locally in a stand-in for HawkSearch (asks which client the first time)
+npx hawk-app validate            # check hawk-app.json, queries/ and functions/ (--build also checks the build's URLs)
+npm run app:audit                # npm audit of the production dependencies: fix high and critical before deploying
+npm run app:deploy               # build and upload a new version, with hawk-app.json (dev unless --env prod)
+npx hawk-app deploy --dry-run    # what hawk-app.json would change, without a version
+npx hawk-app status              # released and newest versions, the request, the aliases
+npx hawk-app versions            # every version with its status and aliases
+npx hawk-app open                # the app's page in HawkSearch (review, submit for approval)
+npx hawk-app logs <function>     # a function's logs
+npx hawk-app config list         # config values (config set <key> <value> [--client <id>], config unset <key>)
+npx hawk-app errors              # errors in the app's pages (deployed versions), the most frequent first
+npx hawk-app usage               # opens, users and clients per day
+npx hawk-app upgrade             # bring the app (and this file) up to the CLI's current template
+npx hawk-app upgrade --channel latest  # a dev app (bridge/CLI on the `dev` tag) to the released versions
+```
+
+Deploy only when asked to. Never use `--env prod` unless asked to. If the bridge or CLI is on the
+`dev` tag (a dev app), its features may only exist on the dev platform: don't move it to `latest` or to prod unless
+asked to.
+
+## Review
+
+A new app is a draft that only Bridgeline staff see. Members of Hawk-App-Developers submit it (and each later version
+or settings change) for approval in HawkSearch; Hawk-App-Approvers approve it. The approve dialog runs automated
+checks, and a failed check forces the approver to override it:
+
+- **Bundle:** over 20 MB in total, any file over 5 MB, or 50% (and 1 MB) bigger than the released version.
+- **Dependencies:** high or critical `npm audit` findings in the production dependencies, or no audit.
+- **Outside origins:** `externalOrigins` is `["*"]`.
+- **Queries:** a query without `{{partitions(...)}}`; `SELECT *` and a missing `LIMIT` are flagged too.
+- Functions, external Lambdas and new outside origins are shown to the approver.

package/agents/project/custom.md

@@ -1,21 +1,21 @@
-This app doesn't use one of the CLI's templates (it was set up with `npx hawk-app init`), so the project itself has to
-do what a template would:
-
-- **Bridge.** Install `@bridgeline-digital/hawk-app-bridge` and import `createApp` from
-  `@bridgeline-digital/hawk-app-bridge/client`. Without a bundler, import it from the CDN pinned to a minor
-  version: `https://cdn.jsdelivr.net/npm/@bridgeline-digital/hawk-app-bridge@<major.minor>/dist/client/index.js`.
-  Connect once (`createApp`), keep the context in state, and show "Open this app from the Apps page in HawkSearch"
-  when it rejects with `not_embedded`.
-- **Base path.** `hawk-app deploy` runs `npm run build` with `HAWK_APP_BASE_PATH=/__SLUG__/v<n>`. Read it in the build
-  config, e.g. Vite `base: (process.env.HAWK_APP_BASE_PATH ?? '/__SLUG__') + '/'`, Next.js
-  `basePath: process.env.HAWK_APP_BASE_PATH ?? '/__SLUG__'` with `output: 'export'`, or emit only relative URLs. `npx hawk-app validate --build` checks the output.
-- **Static output.** The build writes plain files to one folder (e.g. `dist/`), deployed with
-  `npx hawk-app deploy <folder>` (it builds when package.json has a `build` script; without one it uploads the folder
-  as it is, so use relative URLs only).
-- **Dev server** on `http://localhost:3100` (the dev platform accepts calls from ports 3100-3103), opened in HawkSearch
-  with `<HawkSearch>/admin/apps/__SLUG__?devUrl=<the dev server's URL for the app>`.
-- **Look.** Use the Hawk Apps UI kit (`@bridgeline-digital/hawk-app-ui`) for Spark's look: React + MUI apps
-  its `<HawkAppProvider>` and components, any other app its stylesheet (`/css`, or from the CDN
-  `…/hawk-app-ui@<major.minor>/dist/css/hawk.css`) and elements (`/elements`). See the kit's README.
-- **Scripts.** Add `"app:dev": "hawk-app dev"`, `"app:deploy": "hawk-app deploy <folder>"` and
-  `"app:audit": "npm audit --omit=dev --audit-level=high"` to `package.json`, with the CLI as a dev dependency.
+This app doesn't use one of the CLI's templates (it was set up with `npx hawk-app init`), so the project itself has to
+do what a template would:
+
+- **Bridge.** Install `@bridgeline-digital/hawk-app-bridge` and import `createApp` from
+  `@bridgeline-digital/hawk-app-bridge/client`. Without a bundler, import it from the CDN pinned to a minor
+  version: `https://cdn.jsdelivr.net/npm/@bridgeline-digital/hawk-app-bridge@<major.minor>/dist/client/index.js`.
+  Connect once (`createApp`), keep the context in state, and show "Open this app from the Apps page in HawkSearch"
+  when it rejects with `not_embedded`.
+- **Base path.** `hawk-app deploy` runs `npm run build` with `HAWK_APP_BASE_PATH=/__SLUG__/v<n>`. Read it in the build
+  config, e.g. Vite `base: (process.env.HAWK_APP_BASE_PATH ?? '/__SLUG__') + '/'`, Next.js
+  `basePath: process.env.HAWK_APP_BASE_PATH ?? '/__SLUG__'` with `output: 'export'`, or emit only relative URLs. `npx hawk-app validate --build` checks the output.
+- **Static output.** The build writes plain files to one folder (e.g. `dist/`), deployed with
+  `npx hawk-app deploy <folder>` (it builds when package.json has a `build` script; without one it uploads the folder
+  as it is, so use relative URLs only).
+- **Dev server** on `http://localhost:3100` (the dev platform accepts calls from ports 3100-3103), opened in HawkSearch
+  with `<HawkSearch>/admin/apps/__SLUG__?devUrl=<the dev server's URL for the app>`.
+- **Look.** Use the Hawk Apps UI kit (`@bridgeline-digital/hawk-app-ui`) for Spark's look: React + MUI apps
+  its `<HawkAppProvider>` and components, any other app its stylesheet (`/css`, or from the CDN
+  `…/hawk-app-ui@<major.minor>/dist/css/hawk.css`) and elements (`/elements`). See the kit's README.
+- **Scripts.** Add `"app:dev": "hawk-app dev"`, `"app:deploy": "hawk-app deploy <folder>"` and
+  `"app:audit": "npm audit --omit=dev --audit-level=high"` to `package.json`, with the CLI as a dev dependency.

package/agents/project/next-mui.md

@@ -1,21 +1,21 @@
-Created from the CLI's `next-mui` template (Next.js static export + Material UI 9 + the Hawk Apps UI kit,
-`@bridgeline-digital/hawk-app-ui`). `npx hawk-app upgrade` keeps it in step.
-
-- `src/app/providers.tsx` renders `<HawkAppProvider>`: it connects to the host and shows the app in Spark's theme, in
-  the host's colors and mode. Read the app and its context with `useHawk()` (`{ app, context }`, always connected).
-  Components that use hooks are client components (`'use client'`). `src/app/layout.tsx` imports
-  `@bridgeline-digital/hawk-app-ui/fonts` (Montserrat): keep it.
-- Build screens from the kit before writing your own: `Section`, `KpiTile`/`KpiRow`, `DataTable` (sortable, totals,
-  CSV download), `EmptyState`, `LoadingSection`, `Notice` (with `onRetry`), `ConfirmDialog`, `SideDrawer`; charts from
-  `@bridgeline-digital/hawk-app-ui/charts` (`BarList`, `ColumnChart`, `StackedColumnChart`, `Sparkline`);
-  `DataGrid` from `/data-grid` (add `@mui/x-data-grid@^9`) for thousands of rows. Format with `useFormat()` (the
-  host's locale) and toast with `useToast()`, not hand-rolled helpers or a local Snackbar.
-- Don't restyle Spark's theme or add another font: the kit's theme is Spark's. App-specific additions go in
-  `<HawkAppProvider theme={{ … }}>`.
-- `next.config.ts` has `output: 'export'`, `basePath` from `HAWK_APP_BASE_PATH` (local dev: `/__SLUG__`) and
-  `trailingSlash`. Keep them. No server features: no `getServerSideProps`, route handlers, server actions,
-  middleware or `next/image` optimization.
-- Develop: `npm run dev` (port 3100), then open
-  `<HawkSearch>/admin/apps/__SLUG__?devUrl=http://localhost:3100/__SLUG__/` (dev mode
-  allows ports 3100-3103).
-- Build output: `out/` (`npm run app:deploy` builds and deploys it).
+Created from the CLI's `next-mui` template (Next.js static export + Material UI 9 + the Hawk Apps UI kit,
+`@bridgeline-digital/hawk-app-ui`). `npx hawk-app upgrade` keeps it in step.
+
+- `src/app/providers.tsx` renders `<HawkAppProvider>`: it connects to the host and shows the app in Spark's theme, in
+  the host's colors and mode. Read the app and its context with `useHawk()` (`{ app, context }`, always connected).
+  Components that use hooks are client components (`'use client'`). `src/app/layout.tsx` imports
+  `@bridgeline-digital/hawk-app-ui/fonts` (Montserrat): keep it.
+- Build screens from the kit before writing your own: `Section`, `KpiTile`/`KpiRow`, `DataTable` (sortable, totals,
+  CSV download), `EmptyState`, `LoadingSection`, `Notice` (with `onRetry`), `ConfirmDialog`, `SideDrawer`; charts from
+  `@bridgeline-digital/hawk-app-ui/charts` (`BarList`, `ColumnChart`, `StackedColumnChart`, `Sparkline`);
+  `DataGrid` from `/data-grid` (add `@mui/x-data-grid@^9`) for thousands of rows. Format with `useFormat()` (the
+  host's locale) and toast with `useToast()`, not hand-rolled helpers or a local Snackbar.
+- Don't restyle Spark's theme or add another font: the kit's theme is Spark's. App-specific additions go in
+  `<HawkAppProvider theme={{ … }}>`.
+- `next.config.ts` has `output: 'export'`, `basePath` from `HAWK_APP_BASE_PATH` (local dev: `/__SLUG__`) and
+  `trailingSlash`. Keep them. No server features: no `getServerSideProps`, route handlers, server actions,
+  middleware or `next/image` optimization.
+- Develop: `npm run dev` (port 3100), then open
+  `<HawkSearch>/admin/apps/__SLUG__?devUrl=http://localhost:3100/__SLUG__/` (dev mode
+  allows ports 3100-3103).
+- Build output: `out/` (`npm run app:deploy` builds and deploys it).

package/agents/project/next.md

@@ -1,24 +1,24 @@
-Created from the CLI's `__TEMPLATE__` template (Next.js static export + TypeScript). `npx hawk-app upgrade` keeps
-it in step.
-
-- `src/lib/useHawkApp.ts` connects to the host once and keeps the context current; build screens on it. Components
-  that use it are client components (`'use client'`).
-- Spark's look comes from the Hawk Apps UI kit (`@bridgeline-digital/hawk-app-ui`): its stylesheet (`/css`,
-  imported in `src/app/layout.tsx`: Montserrat, the host's colors and light or dark mode) and its elements
-  (`/elements`, imported in the client page; safe to import on the server). Build screens from them before writing
-  your own: classes `hawk-section` (with `hawk-section-header`, `hawk-section-title`, `hawk-section-subtitle`),
-  `hawk-kpi-row`, `hawk-stack`, `hawk-button` (`is-outlined`, `is-small`), `hawk-notice` (`is-error`, `is-warning`,
-  `is-success`), `hawk-input`, `hawk-select`, `hawk-chip`, `hawk-empty`, `hawk-spinner`, `hawk-muted`; elements
-  `<hawk-kpi label value hint change good-when highlight loading>`, `<hawk-data-table>` (properties `columns`, `rows`,
-  `totals`; attributes `download`, `max-height`, `clickable`; sortable, CSV download), `<hawk-bar-list>` (`items`,
-  `selectable`: `hawk-select` events) and `<hawk-column-chart>` (`columns`). Data goes in as properties, settings as
-  attributes; `src/hawk-elements.d.ts` types them in JSX. Format numbers and dates with `createFormat(context.locale)`
-  from `/elements`. Don't add another font or restyle the kit; your own styles go in `src/app/globals.css`, using the
-  `--hawk-ui-*` variables.
-- `next.config.ts` has `output: 'export'`, `basePath` from `HAWK_APP_BASE_PATH` (local dev: `/__SLUG__`) and
-  `trailingSlash`. Keep them. No server features: no `getServerSideProps`, route handlers, server actions,
-  middleware or `next/image` optimization.
-- Develop: `npm run dev` (port 3100), then open
-  `<HawkSearch>/admin/apps/__SLUG__?devUrl=http://localhost:3100/__SLUG__/` (dev mode
-  allows ports 3100-3103).
-- Build output: `out/` (`npm run app:deploy` builds and deploys it).
+Created from the CLI's `__TEMPLATE__` template (Next.js static export + TypeScript). `npx hawk-app upgrade` keeps
+it in step.
+
+- `src/lib/useHawkApp.ts` connects to the host once and keeps the context current; build screens on it. Components
+  that use it are client components (`'use client'`).
+- Spark's look comes from the Hawk Apps UI kit (`@bridgeline-digital/hawk-app-ui`): its stylesheet (`/css`,
+  imported in `src/app/layout.tsx`: Montserrat, the host's colors and light or dark mode) and its elements
+  (`/elements`, imported in the client page; safe to import on the server). Build screens from them before writing
+  your own: classes `hawk-section` (with `hawk-section-header`, `hawk-section-title`, `hawk-section-subtitle`),
+  `hawk-kpi-row`, `hawk-stack`, `hawk-button` (`is-outlined`, `is-small`), `hawk-notice` (`is-error`, `is-warning`,
+  `is-success`), `hawk-input`, `hawk-select`, `hawk-chip`, `hawk-empty`, `hawk-spinner`, `hawk-muted`; elements
+  `<hawk-kpi label value hint change good-when highlight loading>`, `<hawk-data-table>` (properties `columns`, `rows`,
+  `totals`; attributes `download`, `max-height`, `clickable`; sortable, CSV download), `<hawk-bar-list>` (`items`,
+  `selectable`: `hawk-select` events) and `<hawk-column-chart>` (`columns`). Data goes in as properties, settings as
+  attributes; `src/hawk-elements.d.ts` types them in JSX. Format numbers and dates with `createFormat(context.locale)`
+  from `/elements`. Don't add another font or restyle the kit; your own styles go in `src/app/globals.css`, using the
+  `--hawk-ui-*` variables.
+- `next.config.ts` has `output: 'export'`, `basePath` from `HAWK_APP_BASE_PATH` (local dev: `/__SLUG__`) and
+  `trailingSlash`. Keep them. No server features: no `getServerSideProps`, route handlers, server actions,
+  middleware or `next/image` optimization.
+- Develop: `npm run dev` (port 3100), then open
+  `<HawkSearch>/admin/apps/__SLUG__?devUrl=http://localhost:3100/__SLUG__/` (dev mode
+  allows ports 3100-3103).
+- Build output: `out/` (`npm run app:deploy` builds and deploys it).

package/agents/project/vanilla.md

@@ -1,22 +1,22 @@
-Created from the CLI's `vanilla` template (plain HTML and JavaScript, no build step). `npx hawk-app upgrade` keeps
-it in step.
-
-- Everything deployed is in `public/` (`npm run app:deploy` uploads it as it is: no build step).
-- `public/app.js` imports the bridge from the CDN, pinned to a minor version
-  (`https://cdn.jsdelivr.net/npm/@bridgeline-digital/hawk-app-bridge@<major.minor>/dist/client/index.js`), and
-  the Hawk Apps UI kit's elements at the same version (`…/hawk-app-ui@<major.minor>/dist/elements/index.js`);
-  `public/index.html` links the kit's stylesheet (`…/hawk-app-ui@<major.minor>/dist/css/hawk.css`: Spark's look,
-  Montserrat, the host's colors and light or dark mode). Keep all three on the same version: `npx hawk-app upgrade`
-  raises them together.
-- Build screens from the kit before writing your own: classes `hawk-section` (with `hawk-section-header`,
-  `hawk-section-title`, `hawk-section-subtitle`), `hawk-kpi-row`, `hawk-stack`, `hawk-button` (`is-outlined`,
-  `is-small`), `hawk-notice` (`is-error`, `is-warning`, `is-success`), `hawk-input`, `hawk-select`, `hawk-chip`,
-  `hawk-empty`, `hawk-spinner`, `hawk-muted`; elements `<hawk-kpi label value hint change good-when highlight loading>`,
-  `<hawk-data-table>` (properties `columns`, `rows`, `totals`; attributes `download`, `max-height`, `clickable`;
-  sortable, CSV download), `<hawk-bar-list>` (`items`, `selectable`: `hawk-select` events) and `<hawk-column-chart>`
-  (`columns`). Data goes in as properties (`el.rows = [...]`), settings as attributes. Format numbers and dates with
-  `createFormat(context.locale)` from the elements module. Your own styles go in `public/styles.css`, using the
-  `--hawk-ui-*` variables. `hawk-app.json` keeps `https://cdn.jsdelivr.net` in `externalOrigins` (the CDN).
-- Use only relative URLs (`app.js`, `styles.css`), never `/app.js`: the files are served from `/__SLUG__/v<n>/`.
-- Develop: `npm run app:dev` (serves `public/` on port 3100 inside a local stand-in for HawkSearch), or `npm run dev`
-  and open `<HawkSearch>/admin/apps/__SLUG__?devUrl=http://localhost:3100/` (the dev mode allows ports 3100-3103).
+Created from the CLI's `vanilla` template (plain HTML and JavaScript, no build step). `npx hawk-app upgrade` keeps
+it in step.
+
+- Everything deployed is in `public/` (`npm run app:deploy` uploads it as it is: no build step).
+- `public/app.js` imports the bridge from the CDN, pinned to a minor version
+  (`https://cdn.jsdelivr.net/npm/@bridgeline-digital/hawk-app-bridge@<major.minor>/dist/client/index.js`), and
+  the Hawk Apps UI kit's elements at the same version (`…/hawk-app-ui@<major.minor>/dist/elements/index.js`);
+  `public/index.html` links the kit's stylesheet (`…/hawk-app-ui@<major.minor>/dist/css/hawk.css`: Spark's look,
+  Montserrat, the host's colors and light or dark mode). Keep all three on the same version: `npx hawk-app upgrade`
+  raises them together.
+- Build screens from the kit before writing your own: classes `hawk-section` (with `hawk-section-header`,
+  `hawk-section-title`, `hawk-section-subtitle`), `hawk-kpi-row`, `hawk-stack`, `hawk-button` (`is-outlined`,
+  `is-small`), `hawk-notice` (`is-error`, `is-warning`, `is-success`), `hawk-input`, `hawk-select`, `hawk-chip`,
+  `hawk-empty`, `hawk-spinner`, `hawk-muted`; elements `<hawk-kpi label value hint change good-when highlight loading>`,
+  `<hawk-data-table>` (properties `columns`, `rows`, `totals`; attributes `download`, `max-height`, `clickable`;
+  sortable, CSV download), `<hawk-bar-list>` (`items`, `selectable`: `hawk-select` events) and `<hawk-column-chart>`
+  (`columns`). Data goes in as properties (`el.rows = [...]`), settings as attributes. Format numbers and dates with
+  `createFormat(context.locale)` from the elements module. Your own styles go in `public/styles.css`, using the
+  `--hawk-ui-*` variables. `hawk-app.json` keeps `https://cdn.jsdelivr.net` in `externalOrigins` (the CDN).
+- Use only relative URLs (`app.js`, `styles.css`), never `/app.js`: the files are served from `/__SLUG__/v<n>/`.
+- Develop: `npm run app:dev` (serves `public/` on port 3100 inside a local stand-in for HawkSearch), or `npm run dev`
+  and open `<HawkSearch>/admin/apps/__SLUG__?devUrl=http://localhost:3100/` (the dev mode allows ports 3100-3103).