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

package/README.md

@@ -1,770 +1,770 @@
-# @bridgeline-digital/hawk-app-cli
-
-Build, run and release **Hawk Apps**, that run inside HawkSearch. Sign in with your Bridgeline account (or a
-**publisher key** in CI): no AWS account, no bucket names, no platform repo.
-
-The full developer docs, with guides, the bridge API and every command, are at
-**[developers.hawksearchapps.com](https://developers.hawksearchapps.com)** (sign in with your Bridgeline account;
-`npx hawk-app docs` opens them).
-
-## Quickstart
-
-```bash
-npx @bridgeline-digital/hawk-app-cli@latest sso       # 1. once per machine: sign in with your Bridgeline account
-npx @bridgeline-digital/hawk-app-cli@latest create my-app && cd my-app && npm install   # 2. a new app
-npm run app:dev                                              # 3. run it locally inside a stand-in for HawkSearch
-npm run app:deploy                                           # 4. build and upload a new version (a draft)
-npx hawk-app open                                            # 5. review it in HawkSearch and submit it for approval
-```
-
-Then `npx hawk-app status` shows where the app stands, and `npx hawk-app doctor` checks everything (Node, login,
-`hawk-app.json`, the project, the scopes the code uses) and says what to fix. `npx hawk-app help` lists the commands by
-task; `npx hawk-app help <command>` gives one command's details.
-
-The templates add the CLI as a dev dependency; elsewhere: `npm i -D @bridgeline-digital/hawk-app-cli`.
-
-## Start a new app
-
-```bash
-npx @bridgeline-digital/hawk-app-cli@latest create keyword-explorer                     # React + Vite + TypeScript
-npx @bridgeline-digital/hawk-app-cli@latest create keyword-explorer --template preact   # Preact + Vite + TypeScript (small bundle)
-npx @bridgeline-digital/hawk-app-cli@latest create keyword-explorer --template next     # Next.js (static export)
-npx @bridgeline-digital/hawk-app-cli@latest create keyword-explorer --template next-mui # Next.js + Material UI (the UI kit's components)
-npx @bridgeline-digital/hawk-app-cli@latest create keyword-explorer --template vanilla  # plain HTML/JS, no build
-```
-
-The folder name becomes the app's slug. Every template comes ready to run:
-- the bridge set up, with the base path read from `HAWK_APP_BASE_PATH` (set by `hawk-app deploy`; `/<slug>/` in local dev)
-- Spark's look in the host's colors and mode, from the UI kit
-  ([`@bridgeline-digital/hawk-app-ui`](../ui/README.md)): `next-mui` its MUI theme, provider and components;
-  every other template its stylesheet and elements (`<hawk-kpi>`, `<hawk-data-table>`, `<hawk-column-chart>`, …;
-  `vanilla` loads them from the CDN)
-- a working analytics example (total searches for the selected engine and date range, per day)
-- a `hawk-app.json` (new apps start as drafts)
-- `app:dev` / `app:deploy` scripts and a README
-- `AGENTS.md`, `CLAUDE.md` and the MCP server's settings for AI coding assistants (see [AI coding assistants](#ai-coding-assistants-agentsmd))
-
-Add `--name "Keyword Explorer"` to set the display name, and `--install` to run `npm install` straight away.
-
-## Add to an existing app
-
-```bash
-npx hawk-app init        # creates hawk-app.json and AGENTS.md
-npx hawk-app validate    # checks hawk-app.json and the project (bridge, build script)
-```
-
-`init` also writes [AGENTS.md](#ai-coding-assistants-agentsmd) with what a template would have done for you: the bridge,
-the base path, the build folder and the dev server. `npx hawk-app validate --build` builds the app as deploy does and
-checks that its HTML only loads URLs under the version's base path.
-
-`hawk-app.json` decides the app's **visibility** and what data it can read (which clients have it is managed
-separately, see [Clients](#clients)):
-
-```jsonc
-{
-  "slug": "keyword-explorer",          // unique; each deploy is served at <apps CDN>/keyword-explorer/v<n>/
-  "name": "Keyword Explorer",
-  "visibility": "allowList",           // allowList: only the app's clients; all: every client except excluded ones;
-                                       // internal: Bridgeline users only; store: the app's clients, and every other
-                                       // client can request it from the store (needs "store", below) (clients: see "Clients")
-  "icon": "icon.svg",                  // the app's icon: an .svg (drawn in the host's color) or a square .png, next to this file
-  "scopes": ["reports:read"]           // reports:read = analytics; hawksearch:read = dashboard API (read);
-                                       // hawksearch:write = create/update/delete synonyms, redirects, banners, …
-                                       // through the dashboard API (see the bridge's "Writing to HawkSearch");
-                                       // data:read = your own SQL queries in queries/ (see "Custom data");
-                                       // functions:invoke = server-side functions (see "Functions");
-                                       // email:send = send email (see "Email");
-                                       // storage = the app's own data and files per client (see the bridge's "Storage");
-                                       // hawksearch:sysparams:write = set HawkSearch system parameters
-                                       // (with "systemParameters", see "HawkSearch system parameters");
-                                       // hawksearch:search = HawkSearch search and autocomplete, live or preview;
-                                       // hawksearch:recommendations = the engine's recommendation widgets;
-                                       // hawksearch:index = rebuild the engine's index (where HawkSearch allows it)
-                                       //   and read its indexes; hawksearch:index:items = add, update, delete items;
-                                       // hawksearch:index:manage = create, switch and delete indexes, hierarchy, mappings;
-                                       // hawksearch:features:write = HawkSearch features on and off;
-                                       // lambdas:invoke = Lambdas outside Hawk Apps (with "lambdas");
-                                       // ai:invoke = Claude through the platform (see "AI")
-  // "config": { "signupNotifyEmails": { "type": "emails", "default": ["a@example.com"] } }
-  //   = non-secret settings the app reads with app.config, values set without a deploy (see "App config")
-}
-```
-
-Optional `"listed": false` keeps the app off the host's Apps landing page (the host also hides its own title and back
-button for it), while it still opens by its direct URL. It only changes the listing, not who can open the app
-(`visibility` and the app's clients still apply); the default is `true`, and `hawk-app status` shows `listed no` when it's off.
-
-**Store apps.** `"visibility": "store"` offers the app to every client that doesn't have it, on the Store tab of the
-Apps page in HawkSearch: a client user requests it, and a Hawk-App-Manager approves (the client is added to its
-clients) or declines. It needs the listing:
-
-```jsonc
-"store": {
-  "tagline": "Find and fix searches that return nothing",   // one line, at most 120 characters
-  "highlights": ["Zero-result searches by volume"],          // optional, up to 5
-  "screenshots": ["store/overview.png", "store/fix.png"]     // 1-5 .png, .jpg or .webp next to hawk-app.json, at most 1 MB each
-}
-```
-
-A view with `"trial": true` (one at most, no params) is the live trial: the card runs it on the client's own data
-before they have the app, with a read-only token (only the app's `reports:read`, `hawksearch:read`,
-`hawksearch:search`, `hawksearch:recommendations` and `data:read`). There `app.context.trial` is true: hide what needs
-other scopes (`validate` lists them); `navigate({ intent: 'app' })` opens the request dialog. Without a trial view, or
-for a client without analytics data, the card shows the screenshots.
-
-`validate` and `deploy` check the screenshots, and `deploy` uploads them with each version (`_hawk/store/1.png`…). The
-listing is reviewed like the other settings; the price label is set by Bridgeline, not here. `hawk-app status` shows
-whether the app is in the store, its price label and how many requests are open, approved and declined.
-
-There is no `status` field any more: approvers release versions from the Apps page in HawkSearch (see [Review](#review-in-hawksearch)). An old `status` is ignored with a warning.
-
-Every deploy is a new version served at `/<slug>/v<n>/`, so the build needs that base path. `hawk-app deploy` runs `npm run build` with `HAWK_APP_BASE_PATH=/<slug>/v<n>`; read it in your build config with `/<slug>` as the local fallback:
-- Vite: ``base: `${process.env.HAWK_APP_BASE_PATH ?? '/keyword-explorer'}/` ``
-- Next.js (`output: 'export'`): `basePath: process.env.HAWK_APP_BASE_PATH ?? '/keyword-explorer'`
-- Other build tools: set the base href / public path from `HAWK_APP_BASE_PATH` the same way (plus a trailing `/` where the tool expects one)
-
-Apps that use only relative paths (plain HTML) can skip the build with `hawk-app deploy <folder> --no-build`.
-
-## Log in (once per machine)
-
-```bash
-npx hawk-app sso       # sign in with your Bridgeline account in the browser: the platform issues your own key
-                       #   (--publisher <id>: another team's apps, e.g. qa-team; one saved key per platform)
-npx hawk-app login     # or: paste a publisher key from Engineering (input hidden), checked and saved for every app
-npx hawk-app whoami    # are you logged in? which platform and key apply here?
-npx hawk-app logout    # remove the saved key from this machine
-```
-
-**`sso`** opens the browser on the HawkSearch sign-in, which goes straight to Bridgeline's AD sign-in (Microsoft). Only
-Bridgeline AD accounts get a key; HawkSearch client logins can't. The platform then issues a key for you on this
-machine (`sso-<name>-<computer>`, in the Services team's publisher, so you work on the team's apps; `--publisher qa-team`
-for another team the platform allows, e.g. QA's own test apps) and the CLI saves it
-like `login` does. You're also added to Hawk-App-Developers in HawkSearch, so you can submit apps for approval. It
-works for 90 days; then commands say it was refused, and you run `sso` again. Signing in again on
-the same computer replaces that computer's key. Works on dev and prod (`npx hawk-app sso --env prod`). Pipelines keep using keys from the portal with `HAWK_APPS_PUBLISHER_KEY`.
-
-**`login`** takes a publisher key made in the Hawk Analytics portal. Those keys don't expire.
-
-`login` saves the key in your user profile, so every app on the machine uses it and no project files hold it:
-- **Windows:** `%APPDATA%\hawk-app\credentials.json`
-- **macOS / Linux:** `~/.config/hawk-app/credentials.json`, readable only by you
-
-It works the same in PowerShell, cmd and bash. The key is never shown, never stored in shell history, and never passed as a command-line argument.
-
-Every command works on **dev** unless you say otherwise. `--env prod` (on any command) picks prod:
-`npx hawk-app sso --env prod` signs you in to prod, and `npx hawk-app deploy --env prod` deploys there. Logging in
-never changes which environment later commands use, so prod is always chosen on purpose; `deploy` says
-when they go to prod. Keys are stored per environment, so a dev key is never sent to prod. (`--platform <url>` targets
-any other platform, e.g. one running locally.)
-
-**Which environment**, first match wins: `--env` / `--platform`, then `HAWK_APPS_ENV` (`dev` or `prod`) or
-`HAWK_APPS_PLATFORM_URL` in the environment (CI) or the project's `.env.local` / `.env`, else dev.
-
-**Which key**, first match wins:
-1. The environment variable `HAWK_APPS_PUBLISHER_KEY`. CI pipelines set it as a secured variable.
-2. The project's `.env.local` (git-ignored), for a per-project override. `npx hawk-app login --local` writes it for you.
-3. The machine login from `hawk-app login` for that environment.
-
-## Run locally without HawkSearch (`hawk-app dev`)
-
-```bash
-npm run app:dev                        # = npx hawk-app dev; asks which client the first time
-npx hawk-app dev --client e3141 --engine 3141
-```
-
-The first time, it asks for part of a client's name and lets you pick the client, then saves it in `.env.local` as
-`HAWK_APPS_DEV_CLIENT` (`--client <id>` uses another). A new app is registered on the platform the first time (not
-released: only Bridgeline staff see it). Queries and functions always run from the **deployed** version, even here:
-deploy after changing them.
-
-Starts your app (`npm run dev`) and a local stand-in for HawkSearch at `http://localhost:3200`, which embeds the app
-the way HawkSearch does (the bridge's own `<hawk-app-frame>`). The app gets **real tokens and real data**: the CLI asks
-the platform for an app token with your publisher key, for any client you name, as a Bridgeline user previewing your
-newest version (with the scopes waiting for review). The app's platform calls go through the local page, so nothing needs
-CORS setup, on dev or prod; so does the AI stream (`app.ai.stream`), which the page pipes through as it arrives.
-
-- The toolbar changes the client, site (engine), user (Bridgeline or client user), date range and theme. Toasts,
-  titles and navigation requests from the app show in the page; a panel shows the token's claims and expiry.
-- `--url <dev server>`: use an app dev server that is already running (nothing is started). The default is where the
-  template serves the app: `http://localhost:3100/<slug>/` for Next.js, `http://localhost:3100/` otherwise. `--no-start`: don't run `npm run dev`. `--port`: the local page's port (default 3200). `--client-user`: start
-  as a client user. `HAWK_APPS_DEV_CLIENT` / `HAWK_APPS_DEV_ENGINE` in `.env.local` replace `--client` / `--engine`.
-- The HawkSearch dashboard API (`app.dashboard`, writes, and authenticated search) needs a HawkSearch key, which only a
-  host has. Put yours in `.env.local` as `HAWKSEARCH_API_KEY` (and `HAWKSEARCH_DOMAIN`, default
-  `https://dev.hawksearch.net`; `HAWKSEARCH_GROUP_KEY=true` for a group key): the platform seals it into the token. It is
-  never written anywhere else.
-- Queries and functions run against your **current deployed version** (deploy first after changing them); the UI is your
-  local code. Every dev token is audit-logged with your publisher key.
-
-## Deploy
-
-**One app, one codebase.** Every developer of a publisher (team) can deploy any of its apps, so the CLI
-guards against mixing two apps under one slug: `create` and `init` refuse a slug that's already an app (saying who last
-changed it; `--yes` to set up a folder for that existing app on purpose), and `deploy` asks before going on
-when someone else's key made the app's last change ("`showcase` was last deployed by Jane Doe on … Deploy a new version
-of it? (y/N)"). `--yes` skips the question; in a pipeline (no terminal) it's a warning and the command goes on. Another
-publisher's slug is always refused (`409 slug_owned`).
-
-```bash
-npx hawk-app deploy               # build and upload a new version, with hawk-app.json
-npx hawk-app status               # released or not, the newest version, the approval request, the aliases
-npx hawk-app open                 # the app in HawkSearch: review it and submit it for approval
-npx hawk-app clients add e3141    # give a client the app (see "Clients")
-npx hawk-app deploy --dry-run     # what hawk-app.json would change, without a version (use this on pull requests)
-```
-
-| Command | What it does |
-|---|---|
-| `init` | Creates `hawk-app.json` (never overwrites an existing one) and adds [AGENTS.md](#ai-coding-assistants-agentsmd). |
-| `validate [--build [<folder>]]` | Checks `hawk-app.json` locally, `queries/` and `functions/` if the app has them, and the project: the bridge is used and current, and there's a build script (or `--no-build` deploys). `--build` also builds the app with a stand-in base path (`/<slug>/v0`) and fails on absolute URLs outside it; the folder comes from the `app:deploy` script unless given. |
-| `deploy [<folder>] [--no-build] [--no-audit] [--alias <name>] [--dry-run]` | Sends hawk-app.json first (its scopes and settings go with every deploy), then reserves the next version number, runs `npm run build` with `HAWK_APP_BASE_PATH=/<slug>/v<n>` (when package.json has a `build` script, unless `--no-build`), then uploads every file in the build folder (the template's, `dist`, `out` or `public`, unless given) to `/<slug>/v<n>/` on the apps CDN, plus `queries/` and the bundled `functions` (if any) to the platform's private storage, and deploys the functions. Runs `npm audit` of the production dependencies first, asks before deploying with high or critical findings, and reports the counts to reviewers (see [Dependency check](#dependency-check); `--no-audit` skips it). Warns when the HTML loads absolute URLs outside `/<slug>/v<n>/`, which wouldn't load, and when the code calls a bridge feature whose scope `hawk-app.json` lacks (e.g. `app.ai.generate` without `ai:invoke`; `validate` and `doctor` check it too). Says whether the version is a draft (staff only until it's approved) or auto-approved, and when it cleared an approval request. `--alias staging` points the alias at the new version (see [Versions and aliases](#versions-and-aliases)). `--dry-run` only shows what hawk-app.json would change. |
-| `register` | Sends `hawk-app.json` without a new version (for scripts; `deploy` and `dev` already send it). It never releases anything and never changes the app's clients. On a released app, changes wait for review. |
-| `versions` | Every version with its status (draft, waiting, approved, rejected) and the aliases on it. |
-| `alias set <name> <version>` / `alias delete <name>` | Point an alias at a version that isn't approved (only Bridgeline staff in its clients see it), or delete one of yours with no clients on it. Approvers do the rest. |
-| `open [--alias <name>]` | Opens the app's page in HawkSearch (dev or prod, from `--env`) to review it and submit it for approval; `--alias` shows it as that alias's clients see it. Prints the link when there's no browser. |
-| `docs [<topic>]` | Opens the developer docs at developers.hawksearchapps.com, or a topic's page (`start`, `versions`, `bridge`, `api`, `cli`, `commands`, `functions`, …; `hawk-app help docs` lists them). Prints the link when there's no browser. |
-| `doctor` | Checks everything a developer needs: Node, the login and platform, `hawk-app.json`, the project (bridge, build script), the template, the scopes the code uses, the app on the platform and the MCP config. Each line says what to fix; exits 1 when something must be. |
-| `help [<command> \| all]` | The commands by task; one command's details; or every detail. |
-| `why <client id>` | What a client's users see of the app, and why (the client list, its alias, that version's status). |
-| `status` | Shows the automated review checks approvers will see (bundle, dependencies, origins, queries, …), the released version, the newest version and its status, settings waiting for review, the approval request (waiting for approval, or rejected and why), auto-approve, review emails (when an approver turned them off), the view cache (when Engineering shortened or stopped it), visibility, scopes, system parameters, config keys and clients. |
-| `clients` / `clients add <id> [<id> …] [--name "<name>"] [--alias <name>]` / `clients exclude <id> [--name "<name>"]` / `clients remove <id>` | Which clients have the app, and which version (alias) each gets (see [Clients](#clients)). |
-| `data tables` / `data describe <table>` / `data run <file.sql> --client <id> [--param name=value …]` | The tables app queries can use, and running a query on dev (see [Custom data](#custom-data-queries)). |
-| `secrets list` / `secrets set <NAME> [--value-from-env VAR]` / `secrets delete <NAME>` | The app's function secrets (see [Functions](#functions)). |
-| `logs <function> [--since 1h] [--follow]` | A function's logs (see [Functions](#functions)). |
-| `config list [--client <id>]` / `config set <key> <value> [--client <id>]` / `config unset <key> [--client <id>]` | The app's config values, global or for one client, without a deploy (see [App config](#app-config)). |
-| `sso [--publisher <id>]` | Sign in with your Bridgeline account; the platform issues your own key (see above). |
-| `login [--local]` / `whoami` / `logout` | Save a publisher key (CI, or without SSO), check which key and platform apply, or remove the saved key. |
-| `errors` / `usage` | The app's page errors, and its opens, users and clients per day (see [Errors and usage](#errors-and-usage-hawk-app-errors-hawk-app-usage)). |
-| `upgrade` / `templates` / `mcp` | Keep up with the template (see below); list the templates; the MCP server for AI assistants (see [MCP server](#mcp-server-hawk-app-mcp)). |
-
-Options: `--manifest <file>` to use a manifest other than `hawk-app.json`, `--env dev|prod` (default dev), and `--platform <url>` to target another platform. `deploy` never uploads hidden files such as `.env.local`.
-
-## Keep up with the template (`hawk-app upgrade`)
-
-Templates move on (a new Next.js, a security fix, a config change). `hawk-app upgrade` brings an app's template-owned
-parts up to the template this CLI ships:
-
-```bash
-npx hawk-app upgrade          # shows what would change; changes nothing
-npx hawk-app upgrade --yes    # applies it and runs npm install
-```
-
-- **Dependencies:** the packages the template pins (e.g. `next`, `react`, `@mui/material`, the bridge) are raised to the
-  template's version. Never lowered, and your own packages are never touched. A package the template gained since the
-  app was made is added: a `react`, `preact`, `next` or `next-mui` app gets the UI kit
-  (`@bridgeline-digital/hawk-app-ui`), and `upgrade` lists the code to change to start using it (next-mui: the
-  provider; the others: the stylesheet and elements imports). A major version (Material UI 7 → 9) is called out, with
-  what to check.
-- **Config files** (`next.config.ts`, `vite.config.ts`, `tsconfig.json`): replaced only if you never edited them (the
-  CLI knows every version the templates have shipped). An edited one is left alone, with a diff of what the template
-  changed so you can apply it yourself.
-- The vanilla template's CDN imports (the bridge and the UI kit, in `public/app.js` and `public/index.html`) are raised
-  together to the template's minor version. A vanilla app made before the kit adds its two lines itself: see a new
-  app's `public/index.html` and `public/app.js`.
-- **AGENTS.md:** the CLI's part is refreshed, and `CLAUDE.md` gets its `@AGENTS.md` import (see below).
-- **Never** your code (`src/`), `hawk-app.json` settings or any other file.
-
-It uses `"template"` in `hawk-app.json`, which `hawk-app create` writes; for older apps it guesses from the dependencies
-(and records it on `--yes`), or pass `--template <name>`. An app set up with `init` that follows no template gets only
-AGENTS.md refreshed. `hawk-app deploy` tells you when an app is behind its template. After upgrading: build, test
-(`npm run dev`) and deploy as usual. `--no-install` skips `npm install`.
-
-## Versions and aliases
-
-Every deploy is a version with a status from its review: draft, waiting (submitted), approved or rejected. An **alias**
-points at a version and takes its status: on an approved version its clients' users see the app; on any other only
-Bridgeline staff in them do. **`default`** is the version released to everyone, for every client without another alias.
-
-```bash
-npx hawk-app deploy --alias staging              # staging → the new version (staff only until it's approved)
-npx hawk-app clients add e4 e5 --alias staging   # new clients on staging: staff in them test it
-```
-
-When an approver approves that version, they choose: release to everyone (`default` moves), or only to the aliases on it
-(staging's clients see it, everyone else stays on `default`). You can point aliases only at versions that aren't approved,
-and put on them only clients whose users don't see the app yet; anything users see is for approvers (the portal or
-HawkSearch). The full picture, with diagrams: docs/versions-and-aliases.md in the hawk-apps repository. `hawk-app status` shows the aliases, `hawk-app versions` every version with its status:
-
-```
-  released    v7  (default: every client without another alias)
-  aliases     default v7 (all other clients) · pilot v8 (3 clients) · staging v9 (draft: Bridgeline staff only, 2 clients)
-```
-
-## Errors and usage (`hawk-app errors`, `hawk-app usage`)
-
-The bridge reports the app's page errors and one open per page load (platform/docs/telemetry.md):
-
-```bash
-npx hawk-app errors              # the last 7 days (--days 1-30): grouped, the most frequent first, with versions and clients
-npx hawk-app usage               # the last 30 days (--days 1-400): opens, view opens, users and clients; staff apart
-```
-
-## Accessibility check
-
-`hawk-app deploy` runs axe-core (WCAG 2.1 A/AA and best practices) over up to 10 built pages and sends the result with
-the version: approvers see it as the `accessibility` review check (critical issues fail it; a force approve still goes
-through). `hawk-app validate --build` prints critical and serious issues before you deploy. It sees each page's HTML as
-built, not what the app draws later in the browser, and no layout (so no color contrast).
-
-## Release channels: latest and dev
-
-The bridge, the UI kit and the CLI are published together, with the same version, on two npm tags:
-- **`latest`**, from `main`: stable releases, matched to the prod platform. What `npm install` and `npx hawk-app` get.
-- **`dev`**, from `dev`: pre-releases (`x.y.z-dev.<time>`) with features still in development, which may need the dev
-  platform.
-
-To start an app on dev features, create it with the dev CLI. It puts the bridge, the UI kit and the CLI on the `dev` tag (the vanilla
-template's CDN imports too), so the app gets the dev bridge and not the release its template pins:
-
-```bash
-npx @bridgeline-digital/hawk-app-cli@dev create my-app       # a dev app (or --channel dev with any CLI)
-npx hawk-app upgrade --channel latest           # once the features are released: ^ the latest versions (--yes applies)
-npx hawk-app upgrade --channel dev              # move an existing app onto the dev builds (again: onto the newest ones)
-```
-
-- `--channel` installs the packages it moves by name (`npm install <package>@dev`, or `@^<latest>`), so
-  `package-lock.json` moves with them; npm then writes the version it installed (`^0.1.0-dev.<time>`), which is
-  still the dev channel. Running `--channel dev` again moves to the newest dev builds.
-- A dev app's `npm update` follows the newest dev builds; its `package-lock.json` records the exact one, so commit it.
-- `hawk-app upgrade` keeps a dev app on `dev`; `--channel` is the only thing that moves it.
-- `hawk-app validate` warns when a dev app is set to use the prod platform (`--env prod`, `HAWK_APPS_ENV=prod`).
-
-## AI coding assistants (AGENTS.md)
-
-`create` and `init` write these files for AI coding assistants, so they build Hawk Apps the way the platform expects
-instead of guessing:
-
-- **`AGENTS.md`**, read by GitHub Copilot, Cursor, Codex and others: the rules (no secrets, data only through the
-  bridge, static files, the base path), the bridge's calls and their scopes, queries and functions, the commands, and
-  what fails review. Its project section matches the app's template, or, for an app set up with `init`, says what the
-  project has to do itself.
-- **`CLAUDE.md`** with `@AGENTS.md`, so Claude Code reads the same file.
-
-- **`.mcp.json`** (Claude Code) and **`.vscode/mcp.json`** (VS Code / Copilot), which start the CLI's MCP server (see
-  below) from `node_modules`.
-
-The CLI owns the part of AGENTS.md between its `<!-- hawk-app:start … -->` and `<!-- hawk-app:end -->` markers, and
-`npx hawk-app upgrade` refreshes it when a new CLI changes it. Write your own notes outside the markers; they're kept.
-An existing AGENTS.md or CLAUDE.md is never replaced: the CLI's part (or the import) is added to it. An existing MCP
-settings file gets the `hawk-apps` server added (one with comments is left alone: add it yourself).
-
-### MCP server (`hawk-app mcp`)
-
-`hawk-app mcp` serves the CLI's commands to AI coding assistants over stdio (the [Model Context
-Protocol](https://modelcontextprotocol.io)), so they can look things up and check their own work:
-
-| Tool | What it does |
-| --- | --- |
-| `docs` | Searches or reads the bridge and UI kit READMEs (the app's installed versions), this README, the `hawk-app.json` schema and the showcase app, whose code shows every feature working. |
-| `validate` | `hawk-app validate`, optionally with `--build`. |
-| `status` | `hawk-app status`, including the automated review checks approvers will see. |
-| `doctor` | `hawk-app doctor`: what's wrong with the setup, and how to fix it. |
-| `versions`, `why` | Every version with its status and aliases; what a client sees of the app, and why. |
-| `errors`, `usage` | The app's page errors; its opens, users and clients per day. |
-| `ui_components` | The UI kit's components for the app's template (next-mui: the provider, components and theme; the others: the stylesheet classes and elements), or what's said about one, from the kit's README, with a link to the live [gallery](https://developers.hawksearchapps.com/reference/ui-kit-gallery/). |
-| `analytics_reports` | The analytics API's reports for `app.analytics.report()`, with one report's columns, filters and an example call, read from the developer portal's dev spec (public; no client data). |
-| `hawksearch_api` | HawkSearch's API reference (developerdocs.hawksearch.com): an operation's parameters, request and response fields, the bridge call (`app.dashboard.*`, `app.hawksearch.*`) and its scope, or why apps can't call it (public; no client data). |
-| `data_tables`, `data_describe` | Table names and columns for queries. Never data: `data run` isn't a tool, because its rows would go to the assistant. |
-| `logs` | A function's logs. |
-| `init`, `upgrade` | `hawk-app init`; `hawk-app upgrade` (`apply` for `--yes`). |
-| `deploy` | `hawk-app deploy` (the folder is optional; `alias`, and `dryRun` to only show what hawk-app.json would change). Marked destructive, so the assistant asks you first. |
-| `clients`, `clients_add` | The app's clients, by id. Say "deploy to OTC": `clients_add` finds the matching clients and shows *you* a form to pick one; the assistant only hears whether a client was added. Marked destructive too. Removing clients isn't a tool. |
-
-It also has **prompts**, ready-made tasks that use the tools. Claude Code lists them as slash commands (type `/` and
-`hawk`):
-
-| Prompt | In Claude Code | What it does |
-| --- | --- | --- |
-| `check-before-submit` | `/mcp__hawk-apps__check-before-submit` | Validates (with the build check), reads the status and review checks, and explains how to fix what an approver would have to force approve. |
-| `add-feature` | `/mcp__hawk-apps__add-feature "<what to build>"` | Finds the bridge calls, scopes and showcase examples it needs, says what the review will see, makes the change and validates it. |
-| `explain-app` | `/mcp__hawk-apps__explain-app` | What the app does, its scopes (unused or missing ones too) and where it stands in review. |
-| `deploy-to-client` | `/mcp__hawk-apps__deploy-to-client "<client name>"` | Deploys to dev and gives a client the app; you pick the client from the matches for its name. |
-
-Each takes an optional `dir` for a workspace with several apps. In VS Code with Copilot they're under `/` too.
-
-- **Dev only.** Every tool runs with `--env dev`; nothing reaches prod. Approvals, secrets, removing clients and logins
-  aren't tools.
-- **Your key stays put.** The tools use your saved login (or `.env.local`) like the CLI does; the key never passes
-  through the assistant.
-- **No client names.** Tool output shows client ids only, and client names go to you, never to the assistant: the
-  client picker is a form your assistant shows you (MCP elicitation). An assistant without forms tells you to run
-  `npx hawk-app clients add --pick "<name>"` in a terminal instead.
-- **No silent go-aheads.** Where the CLI would ask (a teammate made the app's last change, or `npm audit` found high or
-  critical vulnerabilities) the tool stops and tells the assistant, which has to ask you and call again with `force`.
-- **Several apps in one workspace?** Each tool takes `dir`, the app's folder relative to the workspace.
-
-`create` and `init` add it to `.mcp.json` and `.vscode/mcp.json`, started as
-`node node_modules/@bridgeline-digital/hawk-app-cli/bin/hawk-app.mjs mcp` (the CLI must be a dev dependency;
-`validate` warns when it isn't). For Cursor, copy the `mcpServers` entry of `.mcp.json` to `.cursor/mcp.json`.
-
-## Clients
-
-Which clients have the app is not in `hawk-app.json`: the platform's registry holds it, and Engineering and approvers
-change it in the Hawk Analytics portal. Developers can change it with the CLI:
-
-```bash
-npx hawk-app clients                                  # the app's visibility and its clients
-npx hawk-app clients search outdoor                   # find a client's id by its name
-npx hawk-app clients add e3141 --name "Outdoor Demo"  # give a client the app (visibility allowList)
-npx hawk-app clients add --pick "outdoor"             # the same, picking the client from the matches
-npx hawk-app clients add e4 e5 --alias staging       # on an alias: the version they get
-npx hawk-app clients add e4 --alias default           # back to the default version
-npx hawk-app clients exclude e2002                    # opt a client out (visibility all)
-npx hawk-app clients remove e3141                     # take the client off the list
-```
-
-`add` and `exclude` take only ids from the environment's HawkSearch client list (the Hawk Analytics portal's client
-picker): an id the dashboard doesn't use, such as `3141` for `e3141`, is refused with the id you probably meant. The
-client's name comes from that list unless you pass `--name`. `remove` takes any id on the app's list.
-
-`hawk-app clients` lists `+ e3141 (Outdoor Demo)` for a client that has the app and `- e2002 (Acme Retail)` for one
-that is opted out; `[on pilot]` after a client on an alias (`[on staging · draft: Bridgeline staff only]` when its version
-isn't approved). What the list means depends on `visibility` in `hawk-app.json`:
-- `allowList`: only the clients marked `+` have the app.
-- `all`: every client has it, except the ones marked `-`.
-- `internal`: Bridgeline users only; the list is ignored.
-
-Changes apply at once, released or not, without a deploy or an approval, and are recorded in the app's history.
-`--name` is a label for people (up to 100 characters); the client id is what grants access. Register the app before
-adding clients.
-
-`--alias` sets the version a client gets (see [Versions and aliases](#versions-and-aliases)). You can change it only for
-clients whose users don't see the app yet; after that, approvers do.
-
-## Custom data (queries)
-
-Apps with the `data:read` scope can ship their own SQL, run by the platform against the current client's analytics
-tables. Put each query in `queries/` next to `hawk-app.json` (not in the build folder) as a pair of files:
-
-```text
-my-app/
-  hawk-app.json          "scopes": ["data:read"]
-  queries/
-    top-searches.sql
-    top-searches.json
-```
-
-```sql
--- queries/top-searches.sql
-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 }] }
-```
-
-The app calls it with `app.data.query('top-searches', { from, to })` (see the bridge README for types, the
-`{{partitions(from, to)}}` macro, the tables and the errors).
-
-**Step by step**
-1. Add `"data:read"` to `scopes` in `hawk-app.json`.
-2. Find your table and columns: `npx hawk-app data tables`, then `npx hawk-app data describe <table>`.
-3. Write `queries/<name>.sql` and `queries/<name>.json`. Filter by a date range and add
-   `{{partitions(from, to)}}`.
-4. Try it on dev: `npx hawk-app data run queries/<name>.sql --client <id> --param from=… --param to=…`.
-5. Call it from the app with `app.data.query('<name>', { … })`. Queries always run from a **deployed** version, even
-   in dev mode (`?devUrl=`): the platform never reads your local `queries/` folder. So after adding or editing a
-   query, deploy (step 6) before calling it from the app; use `data run` to iterate on the SQL itself.
-6. `npm run app:deploy` (checks the queries and uploads them with the new version, with `hawk-app.json`).
-7. Bridgeline staff review the version in HawkSearch: they see each added or changed query and its SQL diff.
-   Once approved (or right away on a draft or auto-approve app), the app's users get the new queries.
-
-`hawk-app validate` and `hawk-app deploy` check the queries before anything is uploaded, with the same rules as the
-platform:
-- names are lowercase letters, digits and single dashes (up to 64), and every `.sql` has a `.json` (and vice versa);
-  only `.sql` and `.json` files, no subfolders, at most 50 queries
-- each `.sql` is one `SELECT` or `WITH … SELECT` statement (no `;`), up to 64 KB
-- the `?` count equals the number of params (a `string[]` param is one `?`, written `IN ?`)
-- params have a `name` and a `type` (`string`, `int`, `decimal`, `date`, `timestamp`, `boolean`, `string[]`), and
-  optionally `required`, `default`, `min`/`max` (numbers) and `maxItems` (`string[]`, up to 100)
-- `{{partitions(from, to)}}` (optionally `{{partitions(from, to, alias)}}`) uses params declared as `date`
-- `queries/` needs `data:read` in `scopes`.
-
-`deploy` uploads them with the version (`… 3 files, 12 KB from dist, 2 queries`). They're part of the version: staff
-review them with it, and each version runs its own queries.
-
-Try a query on dev before deploying it:
-
-```bash
-npx hawk-app data tables                        # the tables queries can use (and which are partitioned)
-npx hawk-app data tables --app my-app           # also: may my-app use the sensitive tables?
-npx hawk-app data describe dailysearches        # a table's columns and types
-npx hawk-app data run queries/top-searches.sql --client e3141 --param from=2026-09-01 --param to=2026-09-30
-```
-
-`data run` sends the SQL and its `.json` from your disk (nothing needs to be deployed), waits for the result, and prints
-up to 50 rows plus the bytes scanned. `--client` is the HawkSearch client id (the one in the app's context,
-`context.tenant.clientId`); on dev, use a demo or test client. `string[]` values are comma-separated (`--param engines=a,b`). It only works
-against the dev platform. When too many queries are running (429 `too_many_queries`) it waits and tries again.
-
-The sensitive tables (visitor-level data such as `summary`) are listed apart: only apps Engineering has opted in can
-query them. Ask Engineering if your app needs one.
-
-
-## Functions
-
-Server-side code that ships with each version (AWS Lambda, Node 22), called from the app with
-`app.functions.call(name, input)`. The bridge README's **Functions** section covers `ctx`, errors and limits; this is
-the CLI side.
-
-**Before you start: Engineering must enable functions for your app** (they can reach the internet and hold secrets),
-and a version whose functions changed **always needs review**, even on an auto-approve app.
-
-1. Add `"functions:invoke"` to `scopes`, and declare each function in `hawk-app.json`:
-   ```jsonc
-   "functions": {
-       "sync-feed": { "timeoutSeconds": 20, "memoryMb": 512, "secrets": ["FEED_API_KEY"] },
-       "echo": {},                                 // defaults: 10 s, 256 MB, no secrets
-       "nightly-report": { "job": true, "timeoutSeconds": 600 }   // a background job (see below)
-   }
-   ```
-2. Write `functions/<name>.ts` (or `.mts`, `.js`, `.mjs`) exporting `handler`, with
-   `@bridgeline-digital/hawk-app-bridge` (0.4.0 or later) installed in the app:
-   ```ts
-   import type { HawkFunction } from '@bridgeline-digital/hawk-app-bridge/server';
-   export const handler: HawkFunction<{ name: string }, { greeting: string }> = async (input, ctx) => ({
-       greeting: `Hello ${input.name} from ${ctx.client.id}`,
-   });
-   ```
-   Shared code goes in subfolders (`functions/lib/…`) or anywhere else you import from (`src/`, npm packages).
-3. Set its secrets once: `npx hawk-app secrets set FEED_API_KEY`.
-4. `npx hawk-app validate`, then deploy as usual: `npm run app:deploy`.
-5. Call it from the app: `await app.functions.call('sync-feed', { since: '2026-09-01' })`. Like queries, functions
-   always run from a **deployed** version, also in dev mode (`?devUrl=`).
-
-`hawk-app validate` and `hawk-app deploy` check, with the platform's rules:
-- at most 10 functions; names are lowercase letters, digits and single dashes, up to 40 characters;
-- `job` true or false; `timeoutSeconds` 1–25 (1–900 for a job), `memoryMb` 128–1024, `secrets` up to 20 unique
-  `UPPER_SNAKE_CASE` names, no other keys;
-- every declared function has its `functions/<name>.*` file, and every entry file in `functions/` is declared;
-- the `functions:invoke` scope, and the bridge installed with its `/server` entry.
-
-**What deploy does with them.** Before reserving a version, each function is bundled with esbuild (Node 22, ESM,
-every dependency included, your `handler` wrapped for Lambda) into `index.mjs`, zipped as `bundle.zip` (10 MB at
-most). `source.zip` (every file under `functions/` except `node_modules`, 5 MB at most) and `deps.json` (the npm
-packages in the bundle, with versions) go along so reviewers can see the code and its dependencies. After the upload
-the platform deploys each function and the CLI prints one line per function:
-
-```
-Bundling 2 functions…
-  ƒ echo  4 KB zipped, 1 package
-  ƒ sync-feed  38 KB zipped, 2 packages
-Uploading v9 of my-app: 12 files, 210 KB from dist, 2 functions
-  ✔ function echo  (10 s, 256 MB)  Lambda version 3
-  ✔ function sync-feed  (20 s, 512 MB, secrets FEED_API_KEY)  Lambda version 5
-✔ Deployed v9 of my-app (12 files, 2 functions). A draft: clients stay on v8 until it's approved in HawkSearch …
-```
-
-Zips are built the same way every time, so a function whose code didn't change keeps the same code hash (and doesn't
-show as changed in review).
-
-**Secrets.** App-level, stored by the platform (encrypted, in AWS Systems Manager Parameter Store), never in the app or
-a version: a change applies to every version at once. A function receives only the secrets it declares, as
-`ctx.secrets.NAME`.
-
-```bash
-npx hawk-app secrets list                                    # names and when they were set; never values
-npx hawk-app secrets set FEED_API_KEY                        # type the value (hidden, never echoed)
-npx hawk-app secrets set FEED_API_KEY --value-from-env FEED  # CI: read it from an environment variable
-npx hawk-app secrets delete FEED_API_KEY
-```
-
-**Client secrets** are for values each client sets for itself, such as its email platform's API key. Declare them on
-the function (`"clientSecrets": ["MAILCHIMP_API_KEY"]`). The app sets them with `app.clientSecrets.set(...)` and the
-function reads `ctx.clientSecrets.MAILCHIMP_API_KEY`. The CLI never sees them.
-
-Values are never printed, logged or passed as command-line arguments, and are at most 4 KB each (UTF-8 bytes).
-
-**Logs.** `console.log` and `console.error` go to the function's log (kept 30 days):
-
-```bash
-npx hawk-app logs sync-feed                  # recent events
-npx hawk-app logs sync-feed --since 1d       # 15m, 1h, 1d or an ISO time
-npx hawk-app logs sync-feed --follow         # keep polling every 2 s (Ctrl+C to stop)
-```
-
-**When a call fails** the app gets a `HawkApiError`: `function_failed` (the handler threw: see the logs),
-`function_timeout`, `secret_missing` (run `secrets set`), `functions_not_enabled` (ask Engineering) or
-`function_not_found` (deploy the version with the function). The bridge README lists them all.
-
-### Background jobs and schedules
-
-A function with `"job": true` is a **background job**: the app starts it with `app.functions.start(name, input)`
-(it can't be called with `call`, and a normal function can't be started), it runs up to 900 s (default 300), and the
-app reads its result later with `app.functions.wait(jobId)`. The bridge README's **Background jobs** section has the
-code and limits.
-
-`schedules` run job functions on a timer, for the clients where a user turns them on from the app
-(`app.schedules.enable(name)`); nothing runs until someone does:
-
-```jsonc
-"functions": { "nightly-report": { "job": true, "timeoutSeconds": 600 } },
-"schedules": {
-    "nightly": { "function": "nightly-report", "cron": "0 7 ? * MON-FRI *", "timezone": "America/Chicago" }
-}
-```
-
-`hawk-app validate` checks: at most 5 schedules, named like functions; `function` is a job function of the same
-`hawk-app.json`; `cron` is an [EventBridge cron](https://docs.aws.amazon.com/scheduler/latest/UserGuide/schedule-types.html#cron-based)
-with 6 fields (`minutes hours day-of-month month day-of-week year`, no `cron( )` wrapper) that runs **at most hourly**
-(the minutes field is a single number, 0–59) with `?` for day-of-month or day-of-week (EventBridge needs one);
-`timezone` is an IANA name like `America/Chicago`, or `UTC` (the default); the `functions:invoke`
-scope. `schedules` is a setting sent with each deploy: on a released app a change waits for review like scopes,
-and `hawk-app status` lists the registered schedules.
-
-## Email
-
-Apps with the `email:send` scope can send email with `app.email.send(...)` or, from a function,
-`ctx.platform.email.send(...)` (the bridge README's **Email** section has the details). There are no CLI commands for
-it: add `"email:send"` to `scopes` and deploy (without the scope, sends fail with `scope_missing`). Mail goes out from `noreply@hawksearch.com` with the app's name, to up to 10 recipients per
-send and 200 recipients per app and client per day.
-
-## HawkSearch system parameters
-
-Apps with the `hawksearch:sysparams:write` scope can read and set the HawkSearch system parameters they list in
-`systemParameters`, for the user's current engine, with `app.hawksearch.systemParameters.list() / get(name) /
-set(name, value)` (or `ctx.platform.hawksearch.systemParameters` in a function; the bridge README's **HawkSearch
-system parameters** section has the details). There are no CLI commands for it:
-
-```json
-{
-  "scopes": ["hawksearch:sysparams:write"],
-  "systemParameters": ["Timezone", "SearchPreviewURL"]
-}
-```
-
-`hawk-app validate` checks the list: up to 50 names of 1-50 letters, digits, `_`, `.` or `-`, each listed once
-(names are not case-sensitive); the list needs the scope, and the scope needs a non-empty list. The list is a setting:
-on a released app a change waits for review like scopes. Any user of the app can set the listed parameters, including
-"AE only" ones; encrypted, global and read-only ones never can. Changes apply within about 3 minutes and only to the
-user's current engine (no group sync).
-
-## App config
-
-Settings someone changes without a deploy (who gets a notification email, a threshold, a switch) go in `config`:
-declare each key with its type and an optional default, and read it in the app with `app.config.get(key)` /
-`app.config.all()` (`ctx.config` in a function; the bridge README's **App config** section has the details).
-
-```json
-{
-  "config": {
-    "signupNotifyEmails": { "type": "emails", "label": "Sign-up notification recipients", "default": ["support@example.com"] },
-    "connectorsRequestEmails": { "type": "emails", "label": "API Connections request recipients" }
-  }
-}
-```
-
-The values are set outside hawk-app.json, from the Hawk Analytics portal or the CLI, for the whole app (global) or for
-one client, and apply within about 30 seconds, with no deploy or approval. A client's value wins over the global one,
-which wins over the default. **Values are not secret**: they reach the browser, so keep keys in `hawk-app secrets`.
-
-```bash
-npx hawk-app config list [--client e3141]                     # each key: type, default, global and client values
-npx hawk-app config set signupNotifyEmails a@example.com,b@example.com   # global
-npx hawk-app config set signupNotifyEmails csd@example.com --client e3141   # one client
-npx hawk-app config unset signupNotifyEmails --client e3141
-```
-
-`set` reads the value as the key's type in your hawk-app.json: `string` as is, `number`, `boolean` (`true`/`false`),
-`emails` comma-separated, `json` as JSON (quote it for your shell). `hawk-app validate` checks the declarations: at
-most 50 keys named `^[A-Za-z][A-Za-z0-9_]{0,63}$`, each with `type` (`string`, `number`, `boolean`, `emails`,
-`json`), optional `label` (up to 100 characters), `description` (up to 500) and `default` (a valid value of the type;
-`emails` up to 50 different plain addresses; every value at most 16 KB). The declarations are a setting: on a released
-app a change waits for review like scopes (values can already be set for a key waiting for review). `hawk-app status`
-lists the declared keys.
-
-## AI
-
-Apps with the `ai:invoke` scope can ask Claude with `app.ai.generate(...)` / `app.ai.stream(...)` or, from a function,
-`ctx.platform.ai` (the bridge README's **AI** section has the details). There are no CLI commands for it: add
-`"ai:invoke"` to `scopes` and deploy. Two tiers, `fast` and `smart`, each with a daily token budget
-per app and client, plus a per-minute request limit; `app.ai.info()` shows today's use. The scope is elevated: an app
-with it is never auto-approved. Prompts and answers are never logged or stored.
-
-## Review in HawkSearch
-
-- **Not released yet.** A new app's versions are drafts: only Bridgeline staff see it, only on the clients it's enabled
-  for, on the Apps page in HawkSearch, always at its newest version. Developers can't release it; an approver does, on
-  the Apps page (see [Versions and aliases](#versions-and-aliases)).
-- **Released apps.** Every deploy is a new version. Clients stay on the approved version until the new one is approved in
-  HawkSearch (staff can open it there first). Changes to settings in `hawk-app.json` (name, description,
-  icon, category, version, visibility, hosting, scopes, `systemParameters`, `schedules`, `config`, `externalOrigins`, `listed`, `minProtocolVersion`) wait for approval
-  the same way. For `config` only the declarations are reviewed: its values are set at any time without review.
-- **Functions.** Engineering enables functions per app. A version whose functions changed (added, removed, new code,
-  dependencies or settings) always waits for review, even with auto-approve; reviewers see each function's settings,
-  dependency changes and a diff of its sources.
-- **Clients any time.** Client changes (`hawk-app clients` or the Hawk Analytics portal) apply at once, released or
-  not, without review (see [Clients](#clients)).
-- **Auto-approve.** Approvers can set an app to auto-approve: new versions and setting changes are then released
-  straight away.
-- **Approval workflow.** Bridgeline users submit a version or settings change for approval on the Apps page in
-  HawkSearch (`npx hawk-app open`; with an optional note). Members of the **Approvers** group approve it (it's released), reject it with a
-  reason, or force approve without a request (for example to roll back). The approvers get an email about each request
-  (they can stop these with the link at the bottom), the submitter gets one when it's approved or rejected, and every
-  step is posted to the #hawk-app-approvers Slack channel. A new main-line deploy or settings change clears a waiting request (deploy says so: submit it again in
-  HawkSearch). `hawk-app status` shows `request     waiting for approval (submitted by Jane Doe, 2026-10-08: <note>)`
-  or `request     rejected by Jane Doe on 2026-10-09: <reason>`.
-- **Elevated apps.** Apps using queries, functions, system parameters, dashboard writes, AI, external Lambdas, HawkSearch
-  features or the index (rebuilds, items, management) are never auto-approved;
-  approvers review their queries, functions and scopes like any other change.
-- **Rollback and retention.** The released version, the newest version and the 5 newest others are kept, so staff can
-  roll back in HawkSearch; older versions are removed when you deploy.
-
-## How deploy works
-
-1. The CLI asks the platform for the next version number (`v<n>`) with your publisher key, and builds the app for
-   `/<slug>/v<n>` (unless `--no-build`).
-2. The CLI sends the list of files (paths and sizes). The platform checks them:
-   - the file types are static web content
-   - the sizes are within the limits
-   - the paths can't leave your app's folder
-   - you own the slug.
-
-   It then returns one **short-lived upload link per file**. Each link allows exactly one upload, to exactly that file in the version's folder, and expires after about 15 minutes.
-3. The CLI uploads each file straight to storage using its link.
-4. The CLI tells the platform it's done, with the result of `npm audit` of the production dependencies (run before the version was reserved, see below). The platform checks that every file arrived and marks the version ready: an app not released yet shows it to Bridgeline staff at once, a released app holds it for review (or releases it, with auto-approve). Versions never change once uploaded, so there's no CDN refresh to wait for.
-
-The platform also sets content types and caching: hashed bundles are cached for a year, HTML is never cached, and everything else is cached for 5 minutes.
-
-### Dependency check
-
-Before it reserves a version number, `deploy` runs `npm audit --json --omit=dev` in the app folder (next to
-`hawk-app.json`, 60 s at most), and it sends the vulnerability counts with the version. Reviewers see them with the other
-pre-approval checks in HawkSearch and the Hawk Analytics portal. High or critical vulnerabilities fail that check, so
-approvers can only force approve the version: when the audit finds any, `deploy` names the packages and asks before
-going on.
-
-```
-  dependencies 1 high, 1 moderate (npm audit)
-npm audit found 1 high, 1 moderate in the production dependencies (postcss). Approvers can only force approve this
-version. Deploy anyway? (Fix with npm audit fix or by updating the packages; npm run app:audit shows the details.) (y/N)
-```
-
-No cancels without reserving anything. `--yes` goes on with a warning, and so does a pipeline (no terminal to ask in).
-Moderate and low findings are only reported. Check before deploying with `npm run app:audit` (in apps created from the
-templates: `npm audit --omit=dev --audit-level=high`, which exits non-zero on high or critical findings, so it also works
-as a CI step). Other outcomes:
-
-```
-  dependencies no known vulnerabilities
-  dependencies not checked: no package-lock.json
-```
-
-An app in an npm workspace is audited with the lockfile at the repository root. Without a `package-lock.json` (in the
-app folder or above it), when npm audit fails (for example a registry without audit support) or times out, the
-version is marked "not checked" with a short reason. `--no-audit` skips it (`not checked: skipped (--no-audit)`).
-
-## In CI (example: Bitbucket Pipelines)
-
-```yaml
-- step:
-    name: Deploy Hawk App (dev)
-    deployment: development        # HAWK_APPS_ENV (dev or prod) and HAWK_APPS_PUBLISHER_KEY as secured variables
-    script:
-      - npm ci
-      - npx hawk-app deploy        # builds with the version's base path, then uploads (with hawk-app.json)
-```
-
-Requires Node 20 or later. Dependencies: `esbuild` (bundles functions) and `fflate` (zips them).
+# @bridgeline-digital/hawk-app-cli
+
+Build, run and release **Hawk Apps**, that run inside HawkSearch. Sign in with your Bridgeline account (or a
+**publisher key** in CI): no AWS account, no bucket names, no platform repo.
+
+The full developer docs, with guides, the bridge API and every command, are at
+**[developers.hawksearchapps.com](https://developers.hawksearchapps.com)** (sign in with your Bridgeline account;
+`npx hawk-app docs` opens them).
+
+## Quickstart
+
+```bash
+npx @bridgeline-digital/hawk-app-cli@latest sso       # 1. once per machine: sign in with your Bridgeline account
+npx @bridgeline-digital/hawk-app-cli@latest create my-app && cd my-app && npm install   # 2. a new app
+npm run app:dev                                              # 3. run it locally inside a stand-in for HawkSearch
+npm run app:deploy                                           # 4. build and upload a new version (a draft)
+npx hawk-app open                                            # 5. review it in HawkSearch and submit it for approval
+```
+
+Then `npx hawk-app status` shows where the app stands, and `npx hawk-app doctor` checks everything (Node, login,
+`hawk-app.json`, the project, the scopes the code uses) and says what to fix. `npx hawk-app help` lists the commands by
+task; `npx hawk-app help <command>` gives one command's details.
+
+The templates add the CLI as a dev dependency; elsewhere: `npm i -D @bridgeline-digital/hawk-app-cli`.
+
+## Start a new app
+
+```bash
+npx @bridgeline-digital/hawk-app-cli@latest create keyword-explorer                     # React + Vite + TypeScript
+npx @bridgeline-digital/hawk-app-cli@latest create keyword-explorer --template preact   # Preact + Vite + TypeScript (small bundle)
+npx @bridgeline-digital/hawk-app-cli@latest create keyword-explorer --template next     # Next.js (static export)
+npx @bridgeline-digital/hawk-app-cli@latest create keyword-explorer --template next-mui # Next.js + Material UI (the UI kit's components)
+npx @bridgeline-digital/hawk-app-cli@latest create keyword-explorer --template vanilla  # plain HTML/JS, no build
+```
+
+The folder name becomes the app's slug. Every template comes ready to run:
+- the bridge set up, with the base path read from `HAWK_APP_BASE_PATH` (set by `hawk-app deploy`; `/<slug>/` in local dev)
+- Spark's look in the host's colors and mode, from the UI kit
+  ([`@bridgeline-digital/hawk-app-ui`](../ui/README.md)): `next-mui` its MUI theme, provider and components;
+  every other template its stylesheet and elements (`<hawk-kpi>`, `<hawk-data-table>`, `<hawk-column-chart>`, …;
+  `vanilla` loads them from the CDN)
+- a working analytics example (total searches for the selected engine and date range, per day)
+- a `hawk-app.json` (new apps start as drafts)
+- `app:dev` / `app:deploy` scripts and a README
+- `AGENTS.md`, `CLAUDE.md` and the MCP server's settings for AI coding assistants (see [AI coding assistants](#ai-coding-assistants-agentsmd))
+
+Add `--name "Keyword Explorer"` to set the display name, and `--install` to run `npm install` straight away.
+
+## Add to an existing app
+
+```bash
+npx hawk-app init        # creates hawk-app.json and AGENTS.md
+npx hawk-app validate    # checks hawk-app.json and the project (bridge, build script)
+```
+
+`init` also writes [AGENTS.md](#ai-coding-assistants-agentsmd) with what a template would have done for you: the bridge,
+the base path, the build folder and the dev server. `npx hawk-app validate --build` builds the app as deploy does and
+checks that its HTML only loads URLs under the version's base path.
+
+`hawk-app.json` decides the app's **visibility** and what data it can read (which clients have it is managed
+separately, see [Clients](#clients)):
+
+```jsonc
+{
+  "slug": "keyword-explorer",          // unique; each deploy is served at <apps CDN>/keyword-explorer/v<n>/
+  "name": "Keyword Explorer",
+  "visibility": "allowList",           // allowList: only the app's clients; all: every client except excluded ones;
+                                       // internal: Bridgeline users only; store: the app's clients, and every other
+                                       // client can request it from the store (needs "store", below) (clients: see "Clients")
+  "icon": "icon.svg",                  // the app's icon: an .svg (drawn in the host's color) or a square .png, next to this file
+  "scopes": ["reports:read"]           // reports:read = analytics; hawksearch:read = dashboard API (read);
+                                       // hawksearch:write = create/update/delete synonyms, redirects, banners, …
+                                       // through the dashboard API (see the bridge's "Writing to HawkSearch");
+                                       // data:read = your own SQL queries in queries/ (see "Custom data");
+                                       // functions:invoke = server-side functions (see "Functions");
+                                       // email:send = send email (see "Email");
+                                       // storage = the app's own data and files per client (see the bridge's "Storage");
+                                       // hawksearch:sysparams:write = set HawkSearch system parameters
+                                       // (with "systemParameters", see "HawkSearch system parameters");
+                                       // hawksearch:search = HawkSearch search and autocomplete, live or preview;
+                                       // hawksearch:recommendations = the engine's recommendation widgets;
+                                       // hawksearch:index = rebuild the engine's index (where HawkSearch allows it)
+                                       //   and read its indexes; hawksearch:index:items = add, update, delete items;
+                                       // hawksearch:index:manage = create, switch and delete indexes, hierarchy, mappings;
+                                       // hawksearch:features:write = HawkSearch features on and off;
+                                       // lambdas:invoke = Lambdas outside Hawk Apps (with "lambdas");
+                                       // ai:invoke = Claude through the platform (see "AI")
+  // "config": { "signupNotifyEmails": { "type": "emails", "default": ["a@example.com"] } }
+  //   = non-secret settings the app reads with app.config, values set without a deploy (see "App config")
+}
+```
+
+Optional `"listed": false` keeps the app off the host's Apps landing page (the host also hides its own title and back
+button for it), while it still opens by its direct URL. It only changes the listing, not who can open the app
+(`visibility` and the app's clients still apply); the default is `true`, and `hawk-app status` shows `listed no` when it's off.
+
+**Store apps.** `"visibility": "store"` offers the app to every client that doesn't have it, on the Store tab of the
+Apps page in HawkSearch: a client user requests it, and a Hawk-App-Manager approves (the client is added to its
+clients) or declines. It needs the listing:
+
+```jsonc
+"store": {
+  "tagline": "Find and fix searches that return nothing",   // one line, at most 120 characters
+  "highlights": ["Zero-result searches by volume"],          // optional, up to 5
+  "screenshots": ["store/overview.png", "store/fix.png"]     // 1-5 .png, .jpg or .webp next to hawk-app.json, at most 1 MB each
+}
+```
+
+A view with `"trial": true` (one at most, no params) is the live trial: the card runs it on the client's own data
+before they have the app, with a read-only token (only the app's `reports:read`, `hawksearch:read`,
+`hawksearch:search`, `hawksearch:recommendations` and `data:read`). There `app.context.trial` is true: hide what needs
+other scopes (`validate` lists them); `navigate({ intent: 'app' })` opens the request dialog. Without a trial view, or
+for a client without analytics data, the card shows the screenshots.
+
+`validate` and `deploy` check the screenshots, and `deploy` uploads them with each version (`_hawk/store/1.png`…). The
+listing is reviewed like the other settings; the price label is set by Bridgeline, not here. `hawk-app status` shows
+whether the app is in the store, its price label and how many requests are open, approved and declined.
+
+There is no `status` field any more: approvers release versions from the Apps page in HawkSearch (see [Review](#review-in-hawksearch)). An old `status` is ignored with a warning.
+
+Every deploy is a new version served at `/<slug>/v<n>/`, so the build needs that base path. `hawk-app deploy` runs `npm run build` with `HAWK_APP_BASE_PATH=/<slug>/v<n>`; read it in your build config with `/<slug>` as the local fallback:
+- Vite: ``base: `${process.env.HAWK_APP_BASE_PATH ?? '/keyword-explorer'}/` ``
+- Next.js (`output: 'export'`): `basePath: process.env.HAWK_APP_BASE_PATH ?? '/keyword-explorer'`
+- Other build tools: set the base href / public path from `HAWK_APP_BASE_PATH` the same way (plus a trailing `/` where the tool expects one)
+
+Apps that use only relative paths (plain HTML) can skip the build with `hawk-app deploy <folder> --no-build`.
+
+## Log in (once per machine)
+
+```bash
+npx hawk-app sso       # sign in with your Bridgeline account in the browser: the platform issues your own key
+                       #   (--publisher <id>: another team's apps, e.g. qa-team; one saved key per platform)
+npx hawk-app login     # or: paste a publisher key from Engineering (input hidden), checked and saved for every app
+npx hawk-app whoami    # are you logged in? which platform and key apply here?
+npx hawk-app logout    # remove the saved key from this machine
+```
+
+**`sso`** opens the browser on the HawkSearch sign-in, which goes straight to Bridgeline's AD sign-in (Microsoft). Only
+Bridgeline AD accounts get a key; HawkSearch client logins can't. The platform then issues a key for you on this
+machine (`sso-<name>-<computer>`, in the Services team's publisher, so you work on the team's apps; `--publisher qa-team`
+for another team the platform allows, e.g. QA's own test apps) and the CLI saves it
+like `login` does. You're also added to Hawk-App-Developers in HawkSearch, so you can submit apps for approval. It
+works for 90 days; then commands say it was refused, and you run `sso` again. Signing in again on
+the same computer replaces that computer's key. Works on dev and prod (`npx hawk-app sso --env prod`). Pipelines keep using keys from the portal with `HAWK_APPS_PUBLISHER_KEY`.
+
+**`login`** takes a publisher key made in the Hawk Analytics portal. Those keys don't expire.
+
+`login` saves the key in your user profile, so every app on the machine uses it and no project files hold it:
+- **Windows:** `%APPDATA%\hawk-app\credentials.json`
+- **macOS / Linux:** `~/.config/hawk-app/credentials.json`, readable only by you
+
+It works the same in PowerShell, cmd and bash. The key is never shown, never stored in shell history, and never passed as a command-line argument.
+
+Every command works on **dev** unless you say otherwise. `--env prod` (on any command) picks prod:
+`npx hawk-app sso --env prod` signs you in to prod, and `npx hawk-app deploy --env prod` deploys there. Logging in
+never changes which environment later commands use, so prod is always chosen on purpose; `deploy` says
+when they go to prod. Keys are stored per environment, so a dev key is never sent to prod. (`--platform <url>` targets
+any other platform, e.g. one running locally.)
+
+**Which environment**, first match wins: `--env` / `--platform`, then `HAWK_APPS_ENV` (`dev` or `prod`) or
+`HAWK_APPS_PLATFORM_URL` in the environment (CI) or the project's `.env.local` / `.env`, else dev.
+
+**Which key**, first match wins:
+1. The environment variable `HAWK_APPS_PUBLISHER_KEY`. CI pipelines set it as a secured variable.
+2. The project's `.env.local` (git-ignored), for a per-project override. `npx hawk-app login --local` writes it for you.
+3. The machine login from `hawk-app login` for that environment.
+
+## Run locally without HawkSearch (`hawk-app dev`)
+
+```bash
+npm run app:dev                        # = npx hawk-app dev; asks which client the first time
+npx hawk-app dev --client e3141 --engine 3141
+```
+
+The first time, it asks for part of a client's name and lets you pick the client, then saves it in `.env.local` as
+`HAWK_APPS_DEV_CLIENT` (`--client <id>` uses another). A new app is registered on the platform the first time (not
+released: only Bridgeline staff see it). Queries and functions always run from the **deployed** version, even here:
+deploy after changing them.
+
+Starts your app (`npm run dev`) and a local stand-in for HawkSearch at `http://localhost:3200`, which embeds the app
+the way HawkSearch does (the bridge's own `<hawk-app-frame>`). The app gets **real tokens and real data**: the CLI asks
+the platform for an app token with your publisher key, for any client you name, as a Bridgeline user previewing your
+newest version (with the scopes waiting for review). The app's platform calls go through the local page, so nothing needs
+CORS setup, on dev or prod; so does the AI stream (`app.ai.stream`), which the page pipes through as it arrives.
+
+- The toolbar changes the client, site (engine), user (Bridgeline or client user), date range and theme. Toasts,
+  titles and navigation requests from the app show in the page; a panel shows the token's claims and expiry.
+- `--url <dev server>`: use an app dev server that is already running (nothing is started). The default is where the
+  template serves the app: `http://localhost:3100/<slug>/` for Next.js, `http://localhost:3100/` otherwise. `--no-start`: don't run `npm run dev`. `--port`: the local page's port (default 3200). `--client-user`: start
+  as a client user. `HAWK_APPS_DEV_CLIENT` / `HAWK_APPS_DEV_ENGINE` in `.env.local` replace `--client` / `--engine`.
+- The HawkSearch dashboard API (`app.dashboard`, writes, and authenticated search) needs a HawkSearch key, which only a
+  host has. Put yours in `.env.local` as `HAWKSEARCH_API_KEY` (and `HAWKSEARCH_DOMAIN`, default
+  `https://dev.hawksearch.net`; `HAWKSEARCH_GROUP_KEY=true` for a group key): the platform seals it into the token. It is
+  never written anywhere else.
+- Queries and functions run against your **current deployed version** (deploy first after changing them); the UI is your
+  local code. Every dev token is audit-logged with your publisher key.
+
+## Deploy
+
+**One app, one codebase.** Every developer of a publisher (team) can deploy any of its apps, so the CLI
+guards against mixing two apps under one slug: `create` and `init` refuse a slug that's already an app (saying who last
+changed it; `--yes` to set up a folder for that existing app on purpose), and `deploy` asks before going on
+when someone else's key made the app's last change ("`showcase` was last deployed by Jane Doe on … Deploy a new version
+of it? (y/N)"). `--yes` skips the question; in a pipeline (no terminal) it's a warning and the command goes on. Another
+publisher's slug is always refused (`409 slug_owned`).
+
+```bash
+npx hawk-app deploy               # build and upload a new version, with hawk-app.json
+npx hawk-app status               # released or not, the newest version, the approval request, the aliases
+npx hawk-app open                 # the app in HawkSearch: review it and submit it for approval
+npx hawk-app clients add e3141    # give a client the app (see "Clients")
+npx hawk-app deploy --dry-run     # what hawk-app.json would change, without a version (use this on pull requests)
+```
+
+| Command | What it does |
+|---|---|
+| `init` | Creates `hawk-app.json` (never overwrites an existing one) and adds [AGENTS.md](#ai-coding-assistants-agentsmd). |
+| `validate [--build [<folder>]]` | Checks `hawk-app.json` locally, `queries/` and `functions/` if the app has them, and the project: the bridge is used and current, and there's a build script (or `--no-build` deploys). `--build` also builds the app with a stand-in base path (`/<slug>/v0`) and fails on absolute URLs outside it; the folder comes from the `app:deploy` script unless given. |
+| `deploy [<folder>] [--no-build] [--no-audit] [--alias <name>] [--dry-run]` | Sends hawk-app.json first (its scopes and settings go with every deploy), then reserves the next version number, runs `npm run build` with `HAWK_APP_BASE_PATH=/<slug>/v<n>` (when package.json has a `build` script, unless `--no-build`), then uploads every file in the build folder (the template's, `dist`, `out` or `public`, unless given) to `/<slug>/v<n>/` on the apps CDN, plus `queries/` and the bundled `functions` (if any) to the platform's private storage, and deploys the functions. Runs `npm audit` of the production dependencies first, asks before deploying with high or critical findings, and reports the counts to reviewers (see [Dependency check](#dependency-check); `--no-audit` skips it). Warns when the HTML loads absolute URLs outside `/<slug>/v<n>/`, which wouldn't load, and when the code calls a bridge feature whose scope `hawk-app.json` lacks (e.g. `app.ai.generate` without `ai:invoke`; `validate` and `doctor` check it too). Says whether the version is a draft (staff only until it's approved) or auto-approved, and when it cleared an approval request. `--alias staging` points the alias at the new version (see [Versions and aliases](#versions-and-aliases)). `--dry-run` only shows what hawk-app.json would change. |
+| `register` | Sends `hawk-app.json` without a new version (for scripts; `deploy` and `dev` already send it). It never releases anything and never changes the app's clients. On a released app, changes wait for review. |
+| `versions` | Every version with its status (draft, waiting, approved, rejected) and the aliases on it. |
+| `alias set <name> <version>` / `alias delete <name>` | Point an alias at a version that isn't approved (only Bridgeline staff in its clients see it), or delete one of yours with no clients on it. Approvers do the rest. |
+| `open [--alias <name>]` | Opens the app's page in HawkSearch (dev or prod, from `--env`) to review it and submit it for approval; `--alias` shows it as that alias's clients see it. Prints the link when there's no browser. |
+| `docs [<topic>]` | Opens the developer docs at developers.hawksearchapps.com, or a topic's page (`start`, `versions`, `bridge`, `api`, `cli`, `commands`, `functions`, …; `hawk-app help docs` lists them). Prints the link when there's no browser. |
+| `doctor` | Checks everything a developer needs: Node, the login and platform, `hawk-app.json`, the project (bridge, build script), the template, the scopes the code uses, the app on the platform and the MCP config. Each line says what to fix; exits 1 when something must be. |
+| `help [<command> \| all]` | The commands by task; one command's details; or every detail. |
+| `why <client id>` | What a client's users see of the app, and why (the client list, its alias, that version's status). |
+| `status` | Shows the automated review checks approvers will see (bundle, dependencies, origins, queries, …), the released version, the newest version and its status, settings waiting for review, the approval request (waiting for approval, or rejected and why), auto-approve, review emails (when an approver turned them off), the view cache (when Engineering shortened or stopped it), visibility, scopes, system parameters, config keys and clients. |
+| `clients` / `clients add <id> [<id> …] [--name "<name>"] [--alias <name>]` / `clients exclude <id> [--name "<name>"]` / `clients remove <id>` | Which clients have the app, and which version (alias) each gets (see [Clients](#clients)). |
+| `data tables` / `data describe <table>` / `data run <file.sql> --client <id> [--param name=value …]` | The tables app queries can use, and running a query on dev (see [Custom data](#custom-data-queries)). |
+| `secrets list` / `secrets set <NAME> [--value-from-env VAR]` / `secrets delete <NAME>` | The app's function secrets (see [Functions](#functions)). |
+| `logs <function> [--since 1h] [--follow]` | A function's logs (see [Functions](#functions)). |
+| `config list [--client <id>]` / `config set <key> <value> [--client <id>]` / `config unset <key> [--client <id>]` | The app's config values, global or for one client, without a deploy (see [App config](#app-config)). |
+| `sso [--publisher <id>]` | Sign in with your Bridgeline account; the platform issues your own key (see above). |
+| `login [--local]` / `whoami` / `logout` | Save a publisher key (CI, or without SSO), check which key and platform apply, or remove the saved key. |
+| `errors` / `usage` | The app's page errors, and its opens, users and clients per day (see [Errors and usage](#errors-and-usage-hawk-app-errors-hawk-app-usage)). |
+| `upgrade` / `templates` / `mcp` | Keep up with the template (see below); list the templates; the MCP server for AI assistants (see [MCP server](#mcp-server-hawk-app-mcp)). |
+
+Options: `--manifest <file>` to use a manifest other than `hawk-app.json`, `--env dev|prod` (default dev), and `--platform <url>` to target another platform. `deploy` never uploads hidden files such as `.env.local`.
+
+## Keep up with the template (`hawk-app upgrade`)
+
+Templates move on (a new Next.js, a security fix, a config change). `hawk-app upgrade` brings an app's template-owned
+parts up to the template this CLI ships:
+
+```bash
+npx hawk-app upgrade          # shows what would change; changes nothing
+npx hawk-app upgrade --yes    # applies it and runs npm install
+```
+
+- **Dependencies:** the packages the template pins (e.g. `next`, `react`, `@mui/material`, the bridge) are raised to the
+  template's version. Never lowered, and your own packages are never touched. A package the template gained since the
+  app was made is added: a `react`, `preact`, `next` or `next-mui` app gets the UI kit
+  (`@bridgeline-digital/hawk-app-ui`), and `upgrade` lists the code to change to start using it (next-mui: the
+  provider; the others: the stylesheet and elements imports). A major version (Material UI 7 → 9) is called out, with
+  what to check.
+- **Config files** (`next.config.ts`, `vite.config.ts`, `tsconfig.json`): replaced only if you never edited them (the
+  CLI knows every version the templates have shipped). An edited one is left alone, with a diff of what the template
+  changed so you can apply it yourself.
+- The vanilla template's CDN imports (the bridge and the UI kit, in `public/app.js` and `public/index.html`) are raised
+  together to the template's minor version. A vanilla app made before the kit adds its two lines itself: see a new
+  app's `public/index.html` and `public/app.js`.
+- **AGENTS.md:** the CLI's part is refreshed, and `CLAUDE.md` gets its `@AGENTS.md` import (see below).
+- **Never** your code (`src/`), `hawk-app.json` settings or any other file.
+
+It uses `"template"` in `hawk-app.json`, which `hawk-app create` writes; for older apps it guesses from the dependencies
+(and records it on `--yes`), or pass `--template <name>`. An app set up with `init` that follows no template gets only
+AGENTS.md refreshed. `hawk-app deploy` tells you when an app is behind its template. After upgrading: build, test
+(`npm run dev`) and deploy as usual. `--no-install` skips `npm install`.
+
+## Versions and aliases
+
+Every deploy is a version with a status from its review: draft, waiting (submitted), approved or rejected. An **alias**
+points at a version and takes its status: on an approved version its clients' users see the app; on any other only
+Bridgeline staff in them do. **`default`** is the version released to everyone, for every client without another alias.
+
+```bash
+npx hawk-app deploy --alias staging              # staging → the new version (staff only until it's approved)
+npx hawk-app clients add e4 e5 --alias staging   # new clients on staging: staff in them test it
+```
+
+When an approver approves that version, they choose: release to everyone (`default` moves), or only to the aliases on it
+(staging's clients see it, everyone else stays on `default`). You can point aliases only at versions that aren't approved,
+and put on them only clients whose users don't see the app yet; anything users see is for approvers (the portal or
+HawkSearch). The full picture, with diagrams: docs/versions-and-aliases.md in the hawk-apps repository. `hawk-app status` shows the aliases, `hawk-app versions` every version with its status:
+
+```
+  released    v7  (default: every client without another alias)
+  aliases     default v7 (all other clients) · pilot v8 (3 clients) · staging v9 (draft: Bridgeline staff only, 2 clients)
+```
+
+## Errors and usage (`hawk-app errors`, `hawk-app usage`)
+
+The bridge reports the app's page errors and one open per page load (platform/docs/telemetry.md):
+
+```bash
+npx hawk-app errors              # the last 7 days (--days 1-30): grouped, the most frequent first, with versions and clients
+npx hawk-app usage               # the last 30 days (--days 1-400): opens, view opens, users and clients; staff apart
+```
+
+## Accessibility check
+
+`hawk-app deploy` runs axe-core (WCAG 2.1 A/AA and best practices) over up to 10 built pages and sends the result with
+the version: approvers see it as the `accessibility` review check (critical issues fail it; a force approve still goes
+through). `hawk-app validate --build` prints critical and serious issues before you deploy. It sees each page's HTML as
+built, not what the app draws later in the browser, and no layout (so no color contrast).
+
+## Release channels: latest and dev
+
+The bridge, the UI kit and the CLI are published together, with the same version, on two npm tags:
+- **`latest`**, from `main`: stable releases, matched to the prod platform. What `npm install` and `npx hawk-app` get.
+- **`dev`**, from `dev`: pre-releases (`x.y.z-dev.<time>`) with features still in development, which may need the dev
+  platform.
+
+To start an app on dev features, create it with the dev CLI. It puts the bridge, the UI kit and the CLI on the `dev` tag (the vanilla
+template's CDN imports too), so the app gets the dev bridge and not the release its template pins:
+
+```bash
+npx @bridgeline-digital/hawk-app-cli@dev create my-app       # a dev app (or --channel dev with any CLI)
+npx hawk-app upgrade --channel latest           # once the features are released: ^ the latest versions (--yes applies)
+npx hawk-app upgrade --channel dev              # move an existing app onto the dev builds (again: onto the newest ones)
+```
+
+- `--channel` installs the packages it moves by name (`npm install <package>@dev`, or `@^<latest>`), so
+  `package-lock.json` moves with them; npm then writes the version it installed (`^0.1.0-dev.<time>`), which is
+  still the dev channel. Running `--channel dev` again moves to the newest dev builds.
+- A dev app's `npm update` follows the newest dev builds; its `package-lock.json` records the exact one, so commit it.
+- `hawk-app upgrade` keeps a dev app on `dev`; `--channel` is the only thing that moves it.
+- `hawk-app validate` warns when a dev app is set to use the prod platform (`--env prod`, `HAWK_APPS_ENV=prod`).
+
+## AI coding assistants (AGENTS.md)
+
+`create` and `init` write these files for AI coding assistants, so they build Hawk Apps the way the platform expects
+instead of guessing:
+
+- **`AGENTS.md`**, read by GitHub Copilot, Cursor, Codex and others: the rules (no secrets, data only through the
+  bridge, static files, the base path), the bridge's calls and their scopes, queries and functions, the commands, and
+  what fails review. Its project section matches the app's template, or, for an app set up with `init`, says what the
+  project has to do itself.
+- **`CLAUDE.md`** with `@AGENTS.md`, so Claude Code reads the same file.
+
+- **`.mcp.json`** (Claude Code) and **`.vscode/mcp.json`** (VS Code / Copilot), which start the CLI's MCP server (see
+  below) from `node_modules`.
+
+The CLI owns the part of AGENTS.md between its `<!-- hawk-app:start … -->` and `<!-- hawk-app:end -->` markers, and
+`npx hawk-app upgrade` refreshes it when a new CLI changes it. Write your own notes outside the markers; they're kept.
+An existing AGENTS.md or CLAUDE.md is never replaced: the CLI's part (or the import) is added to it. An existing MCP
+settings file gets the `hawk-apps` server added (one with comments is left alone: add it yourself).
+
+### MCP server (`hawk-app mcp`)
+
+`hawk-app mcp` serves the CLI's commands to AI coding assistants over stdio (the [Model Context
+Protocol](https://modelcontextprotocol.io)), so they can look things up and check their own work:
+
+| Tool | What it does |
+| --- | --- |
+| `docs` | Searches or reads the bridge and UI kit READMEs (the app's installed versions), this README, the `hawk-app.json` schema and the showcase app, whose code shows every feature working. |
+| `validate` | `hawk-app validate`, optionally with `--build`. |
+| `status` | `hawk-app status`, including the automated review checks approvers will see. |
+| `doctor` | `hawk-app doctor`: what's wrong with the setup, and how to fix it. |
+| `versions`, `why` | Every version with its status and aliases; what a client sees of the app, and why. |
+| `errors`, `usage` | The app's page errors; its opens, users and clients per day. |
+| `ui_components` | The UI kit's components for the app's template (next-mui: the provider, components and theme; the others: the stylesheet classes and elements), or what's said about one, from the kit's README, with a link to the live [gallery](https://developers.hawksearchapps.com/reference/ui-kit-gallery/). |
+| `analytics_reports` | The analytics API's reports for `app.analytics.report()`, with one report's columns, filters and an example call, read from the developer portal's dev spec (public; no client data). |
+| `hawksearch_api` | HawkSearch's API reference (developerdocs.hawksearch.com): an operation's parameters, request and response fields, the bridge call (`app.dashboard.*`, `app.hawksearch.*`) and its scope, or why apps can't call it (public; no client data). |
+| `data_tables`, `data_describe` | Table names and columns for queries. Never data: `data run` isn't a tool, because its rows would go to the assistant. |
+| `logs` | A function's logs. |
+| `init`, `upgrade` | `hawk-app init`; `hawk-app upgrade` (`apply` for `--yes`). |
+| `deploy` | `hawk-app deploy` (the folder is optional; `alias`, and `dryRun` to only show what hawk-app.json would change). Marked destructive, so the assistant asks you first. |
+| `clients`, `clients_add` | The app's clients, by id. Say "deploy to OTC": `clients_add` finds the matching clients and shows *you* a form to pick one; the assistant only hears whether a client was added. Marked destructive too. Removing clients isn't a tool. |
+
+It also has **prompts**, ready-made tasks that use the tools. Claude Code lists them as slash commands (type `/` and
+`hawk`):
+
+| Prompt | In Claude Code | What it does |
+| --- | --- | --- |
+| `check-before-submit` | `/mcp__hawk-apps__check-before-submit` | Validates (with the build check), reads the status and review checks, and explains how to fix what an approver would have to force approve. |
+| `add-feature` | `/mcp__hawk-apps__add-feature "<what to build>"` | Finds the bridge calls, scopes and showcase examples it needs, says what the review will see, makes the change and validates it. |
+| `explain-app` | `/mcp__hawk-apps__explain-app` | What the app does, its scopes (unused or missing ones too) and where it stands in review. |
+| `deploy-to-client` | `/mcp__hawk-apps__deploy-to-client "<client name>"` | Deploys to dev and gives a client the app; you pick the client from the matches for its name. |
+
+Each takes an optional `dir` for a workspace with several apps. In VS Code with Copilot they're under `/` too.
+
+- **Dev only.** Every tool runs with `--env dev`; nothing reaches prod. Approvals, secrets, removing clients and logins
+  aren't tools.
+- **Your key stays put.** The tools use your saved login (or `.env.local`) like the CLI does; the key never passes
+  through the assistant.
+- **No client names.** Tool output shows client ids only, and client names go to you, never to the assistant: the
+  client picker is a form your assistant shows you (MCP elicitation). An assistant without forms tells you to run
+  `npx hawk-app clients add --pick "<name>"` in a terminal instead.
+- **No silent go-aheads.** Where the CLI would ask (a teammate made the app's last change, or `npm audit` found high or
+  critical vulnerabilities) the tool stops and tells the assistant, which has to ask you and call again with `force`.
+- **Several apps in one workspace?** Each tool takes `dir`, the app's folder relative to the workspace.
+
+`create` and `init` add it to `.mcp.json` and `.vscode/mcp.json`, started as
+`node node_modules/@bridgeline-digital/hawk-app-cli/bin/hawk-app.mjs mcp` (the CLI must be a dev dependency;
+`validate` warns when it isn't). For Cursor, copy the `mcpServers` entry of `.mcp.json` to `.cursor/mcp.json`.
+
+## Clients
+
+Which clients have the app is not in `hawk-app.json`: the platform's registry holds it, and Engineering and approvers
+change it in the Hawk Analytics portal. Developers can change it with the CLI:
+
+```bash
+npx hawk-app clients                                  # the app's visibility and its clients
+npx hawk-app clients search outdoor                   # find a client's id by its name
+npx hawk-app clients add e3141 --name "Outdoor Demo"  # give a client the app (visibility allowList)
+npx hawk-app clients add --pick "outdoor"             # the same, picking the client from the matches
+npx hawk-app clients add e4 e5 --alias staging       # on an alias: the version they get
+npx hawk-app clients add e4 --alias default           # back to the default version
+npx hawk-app clients exclude e2002                    # opt a client out (visibility all)
+npx hawk-app clients remove e3141                     # take the client off the list
+```
+
+`add` and `exclude` take only ids from the environment's HawkSearch client list (the Hawk Analytics portal's client
+picker): an id the dashboard doesn't use, such as `3141` for `e3141`, is refused with the id you probably meant. The
+client's name comes from that list unless you pass `--name`. `remove` takes any id on the app's list.
+
+`hawk-app clients` lists `+ e3141 (Outdoor Demo)` for a client that has the app and `- e2002 (Acme Retail)` for one
+that is opted out; `[on pilot]` after a client on an alias (`[on staging · draft: Bridgeline staff only]` when its version
+isn't approved). What the list means depends on `visibility` in `hawk-app.json`:
+- `allowList`: only the clients marked `+` have the app.
+- `all`: every client has it, except the ones marked `-`.
+- `internal`: Bridgeline users only; the list is ignored.
+
+Changes apply at once, released or not, without a deploy or an approval, and are recorded in the app's history.
+`--name` is a label for people (up to 100 characters); the client id is what grants access. Register the app before
+adding clients.
+
+`--alias` sets the version a client gets (see [Versions and aliases](#versions-and-aliases)). You can change it only for
+clients whose users don't see the app yet; after that, approvers do.
+
+## Custom data (queries)
+
+Apps with the `data:read` scope can ship their own SQL, run by the platform against the current client's analytics
+tables. Put each query in `queries/` next to `hawk-app.json` (not in the build folder) as a pair of files:
+
+```text
+my-app/
+  hawk-app.json          "scopes": ["data:read"]
+  queries/
+    top-searches.sql
+    top-searches.json
+```
+
+```sql
+-- queries/top-searches.sql
+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 }] }
+```
+
+The app calls it with `app.data.query('top-searches', { from, to })` (see the bridge README for types, the
+`{{partitions(from, to)}}` macro, the tables and the errors).
+
+**Step by step**
+1. Add `"data:read"` to `scopes` in `hawk-app.json`.
+2. Find your table and columns: `npx hawk-app data tables`, then `npx hawk-app data describe <table>`.
+3. Write `queries/<name>.sql` and `queries/<name>.json`. Filter by a date range and add
+   `{{partitions(from, to)}}`.
+4. Try it on dev: `npx hawk-app data run queries/<name>.sql --client <id> --param from=… --param to=…`.
+5. Call it from the app with `app.data.query('<name>', { … })`. Queries always run from a **deployed** version, even
+   in dev mode (`?devUrl=`): the platform never reads your local `queries/` folder. So after adding or editing a
+   query, deploy (step 6) before calling it from the app; use `data run` to iterate on the SQL itself.
+6. `npm run app:deploy` (checks the queries and uploads them with the new version, with `hawk-app.json`).
+7. Bridgeline staff review the version in HawkSearch: they see each added or changed query and its SQL diff.
+   Once approved (or right away on a draft or auto-approve app), the app's users get the new queries.
+
+`hawk-app validate` and `hawk-app deploy` check the queries before anything is uploaded, with the same rules as the
+platform:
+- names are lowercase letters, digits and single dashes (up to 64), and every `.sql` has a `.json` (and vice versa);
+  only `.sql` and `.json` files, no subfolders, at most 50 queries
+- each `.sql` is one `SELECT` or `WITH … SELECT` statement (no `;`), up to 64 KB
+- the `?` count equals the number of params (a `string[]` param is one `?`, written `IN ?`)
+- params have a `name` and a `type` (`string`, `int`, `decimal`, `date`, `timestamp`, `boolean`, `string[]`), and
+  optionally `required`, `default`, `min`/`max` (numbers) and `maxItems` (`string[]`, up to 100)
+- `{{partitions(from, to)}}` (optionally `{{partitions(from, to, alias)}}`) uses params declared as `date`
+- `queries/` needs `data:read` in `scopes`.
+
+`deploy` uploads them with the version (`… 3 files, 12 KB from dist, 2 queries`). They're part of the version: staff
+review them with it, and each version runs its own queries.
+
+Try a query on dev before deploying it:
+
+```bash
+npx hawk-app data tables                        # the tables queries can use (and which are partitioned)
+npx hawk-app data tables --app my-app           # also: may my-app use the sensitive tables?
+npx hawk-app data describe dailysearches        # a table's columns and types
+npx hawk-app data run queries/top-searches.sql --client e3141 --param from=2026-09-01 --param to=2026-09-30
+```
+
+`data run` sends the SQL and its `.json` from your disk (nothing needs to be deployed), waits for the result, and prints
+up to 50 rows plus the bytes scanned. `--client` is the HawkSearch client id (the one in the app's context,
+`context.tenant.clientId`); on dev, use a demo or test client. `string[]` values are comma-separated (`--param engines=a,b`). It only works
+against the dev platform. When too many queries are running (429 `too_many_queries`) it waits and tries again.
+
+The sensitive tables (visitor-level data such as `summary`) are listed apart: only apps Engineering has opted in can
+query them. Ask Engineering if your app needs one.
+
+
+## Functions
+
+Server-side code that ships with each version (AWS Lambda, Node 22), called from the app with
+`app.functions.call(name, input)`. The bridge README's **Functions** section covers `ctx`, errors and limits; this is
+the CLI side.
+
+**Before you start: Engineering must enable functions for your app** (they can reach the internet and hold secrets),
+and a version whose functions changed **always needs review**, even on an auto-approve app.
+
+1. Add `"functions:invoke"` to `scopes`, and declare each function in `hawk-app.json`:
+   ```jsonc
+   "functions": {
+       "sync-feed": { "timeoutSeconds": 20, "memoryMb": 512, "secrets": ["FEED_API_KEY"] },
+       "echo": {},                                 // defaults: 10 s, 256 MB, no secrets
+       "nightly-report": { "job": true, "timeoutSeconds": 600 }   // a background job (see below)
+   }
+   ```
+2. Write `functions/<name>.ts` (or `.mts`, `.js`, `.mjs`) exporting `handler`, with
+   `@bridgeline-digital/hawk-app-bridge` (0.4.0 or later) installed in the app:
+   ```ts
+   import type { HawkFunction } from '@bridgeline-digital/hawk-app-bridge/server';
+   export const handler: HawkFunction<{ name: string }, { greeting: string }> = async (input, ctx) => ({
+       greeting: `Hello ${input.name} from ${ctx.client.id}`,
+   });
+   ```
+   Shared code goes in subfolders (`functions/lib/…`) or anywhere else you import from (`src/`, npm packages).
+3. Set its secrets once: `npx hawk-app secrets set FEED_API_KEY`.
+4. `npx hawk-app validate`, then deploy as usual: `npm run app:deploy`.
+5. Call it from the app: `await app.functions.call('sync-feed', { since: '2026-09-01' })`. Like queries, functions
+   always run from a **deployed** version, also in dev mode (`?devUrl=`).
+
+`hawk-app validate` and `hawk-app deploy` check, with the platform's rules:
+- at most 10 functions; names are lowercase letters, digits and single dashes, up to 40 characters;
+- `job` true or false; `timeoutSeconds` 1–25 (1–900 for a job), `memoryMb` 128–1024, `secrets` up to 20 unique
+  `UPPER_SNAKE_CASE` names, no other keys;
+- every declared function has its `functions/<name>.*` file, and every entry file in `functions/` is declared;
+- the `functions:invoke` scope, and the bridge installed with its `/server` entry.
+
+**What deploy does with them.** Before reserving a version, each function is bundled with esbuild (Node 22, ESM,
+every dependency included, your `handler` wrapped for Lambda) into `index.mjs`, zipped as `bundle.zip` (10 MB at
+most). `source.zip` (every file under `functions/` except `node_modules`, 5 MB at most) and `deps.json` (the npm
+packages in the bundle, with versions) go along so reviewers can see the code and its dependencies. After the upload
+the platform deploys each function and the CLI prints one line per function:
+
+```
+Bundling 2 functions…
+  ƒ echo  4 KB zipped, 1 package
+  ƒ sync-feed  38 KB zipped, 2 packages
+Uploading v9 of my-app: 12 files, 210 KB from dist, 2 functions
+  ✔ function echo  (10 s, 256 MB)  Lambda version 3
+  ✔ function sync-feed  (20 s, 512 MB, secrets FEED_API_KEY)  Lambda version 5
+✔ Deployed v9 of my-app (12 files, 2 functions). A draft: clients stay on v8 until it's approved in HawkSearch …
+```
+
+Zips are built the same way every time, so a function whose code didn't change keeps the same code hash (and doesn't
+show as changed in review).
+
+**Secrets.** App-level, stored by the platform (encrypted, in AWS Systems Manager Parameter Store), never in the app or
+a version: a change applies to every version at once. A function receives only the secrets it declares, as
+`ctx.secrets.NAME`.
+
+```bash
+npx hawk-app secrets list                                    # names and when they were set; never values
+npx hawk-app secrets set FEED_API_KEY                        # type the value (hidden, never echoed)
+npx hawk-app secrets set FEED_API_KEY --value-from-env FEED  # CI: read it from an environment variable
+npx hawk-app secrets delete FEED_API_KEY
+```
+
+**Client secrets** are for values each client sets for itself, such as its email platform's API key. Declare them on
+the function (`"clientSecrets": ["MAILCHIMP_API_KEY"]`). The app sets them with `app.clientSecrets.set(...)` and the
+function reads `ctx.clientSecrets.MAILCHIMP_API_KEY`. The CLI never sees them.
+
+Values are never printed, logged or passed as command-line arguments, and are at most 4 KB each (UTF-8 bytes).
+
+**Logs.** `console.log` and `console.error` go to the function's log (kept 30 days):
+
+```bash
+npx hawk-app logs sync-feed                  # recent events
+npx hawk-app logs sync-feed --since 1d       # 15m, 1h, 1d or an ISO time
+npx hawk-app logs sync-feed --follow         # keep polling every 2 s (Ctrl+C to stop)
+```
+
+**When a call fails** the app gets a `HawkApiError`: `function_failed` (the handler threw: see the logs),
+`function_timeout`, `secret_missing` (run `secrets set`), `functions_not_enabled` (ask Engineering) or
+`function_not_found` (deploy the version with the function). The bridge README lists them all.
+
+### Background jobs and schedules
+
+A function with `"job": true` is a **background job**: the app starts it with `app.functions.start(name, input)`
+(it can't be called with `call`, and a normal function can't be started), it runs up to 900 s (default 300), and the
+app reads its result later with `app.functions.wait(jobId)`. The bridge README's **Background jobs** section has the
+code and limits.
+
+`schedules` run job functions on a timer, for the clients where a user turns them on from the app
+(`app.schedules.enable(name)`); nothing runs until someone does:
+
+```jsonc
+"functions": { "nightly-report": { "job": true, "timeoutSeconds": 600 } },
+"schedules": {
+    "nightly": { "function": "nightly-report", "cron": "0 7 ? * MON-FRI *", "timezone": "America/Chicago" }
+}
+```
+
+`hawk-app validate` checks: at most 5 schedules, named like functions; `function` is a job function of the same
+`hawk-app.json`; `cron` is an [EventBridge cron](https://docs.aws.amazon.com/scheduler/latest/UserGuide/schedule-types.html#cron-based)
+with 6 fields (`minutes hours day-of-month month day-of-week year`, no `cron( )` wrapper) that runs **at most hourly**
+(the minutes field is a single number, 0–59) with `?` for day-of-month or day-of-week (EventBridge needs one);
+`timezone` is an IANA name like `America/Chicago`, or `UTC` (the default); the `functions:invoke`
+scope. `schedules` is a setting sent with each deploy: on a released app a change waits for review like scopes,
+and `hawk-app status` lists the registered schedules.
+
+## Email
+
+Apps with the `email:send` scope can send email with `app.email.send(...)` or, from a function,
+`ctx.platform.email.send(...)` (the bridge README's **Email** section has the details). There are no CLI commands for
+it: add `"email:send"` to `scopes` and deploy (without the scope, sends fail with `scope_missing`). Mail goes out from `noreply@hawksearch.com` with the app's name, to up to 10 recipients per
+send and 200 recipients per app and client per day.
+
+## HawkSearch system parameters
+
+Apps with the `hawksearch:sysparams:write` scope can read and set the HawkSearch system parameters they list in
+`systemParameters`, for the user's current engine, with `app.hawksearch.systemParameters.list() / get(name) /
+set(name, value)` (or `ctx.platform.hawksearch.systemParameters` in a function; the bridge README's **HawkSearch
+system parameters** section has the details). There are no CLI commands for it:
+
+```json
+{
+  "scopes": ["hawksearch:sysparams:write"],
+  "systemParameters": ["Timezone", "SearchPreviewURL"]
+}
+```
+
+`hawk-app validate` checks the list: up to 50 names of 1-50 letters, digits, `_`, `.` or `-`, each listed once
+(names are not case-sensitive); the list needs the scope, and the scope needs a non-empty list. The list is a setting:
+on a released app a change waits for review like scopes. Any user of the app can set the listed parameters, including
+"AE only" ones; encrypted, global and read-only ones never can. Changes apply within about 3 minutes and only to the
+user's current engine (no group sync).
+
+## App config
+
+Settings someone changes without a deploy (who gets a notification email, a threshold, a switch) go in `config`:
+declare each key with its type and an optional default, and read it in the app with `app.config.get(key)` /
+`app.config.all()` (`ctx.config` in a function; the bridge README's **App config** section has the details).
+
+```json
+{
+  "config": {
+    "signupNotifyEmails": { "type": "emails", "label": "Sign-up notification recipients", "default": ["support@example.com"] },
+    "connectorsRequestEmails": { "type": "emails", "label": "API Connections request recipients" }
+  }
+}
+```
+
+The values are set outside hawk-app.json, from the Hawk Analytics portal or the CLI, for the whole app (global) or for
+one client, and apply within about 30 seconds, with no deploy or approval. A client's value wins over the global one,
+which wins over the default. **Values are not secret**: they reach the browser, so keep keys in `hawk-app secrets`.
+
+```bash
+npx hawk-app config list [--client e3141]                     # each key: type, default, global and client values
+npx hawk-app config set signupNotifyEmails a@example.com,b@example.com   # global
+npx hawk-app config set signupNotifyEmails csd@example.com --client e3141   # one client
+npx hawk-app config unset signupNotifyEmails --client e3141
+```
+
+`set` reads the value as the key's type in your hawk-app.json: `string` as is, `number`, `boolean` (`true`/`false`),
+`emails` comma-separated, `json` as JSON (quote it for your shell). `hawk-app validate` checks the declarations: at
+most 50 keys named `^[A-Za-z][A-Za-z0-9_]{0,63}$`, each with `type` (`string`, `number`, `boolean`, `emails`,
+`json`), optional `label` (up to 100 characters), `description` (up to 500) and `default` (a valid value of the type;
+`emails` up to 50 different plain addresses; every value at most 16 KB). The declarations are a setting: on a released
+app a change waits for review like scopes (values can already be set for a key waiting for review). `hawk-app status`
+lists the declared keys.
+
+## AI
+
+Apps with the `ai:invoke` scope can ask Claude with `app.ai.generate(...)` / `app.ai.stream(...)` or, from a function,
+`ctx.platform.ai` (the bridge README's **AI** section has the details). There are no CLI commands for it: add
+`"ai:invoke"` to `scopes` and deploy. Two tiers, `fast` and `smart`, each with a daily token budget
+per app and client, plus a per-minute request limit; `app.ai.info()` shows today's use. The scope is elevated: an app
+with it is never auto-approved. Prompts and answers are never logged or stored.
+
+## Review in HawkSearch
+
+- **Not released yet.** A new app's versions are drafts: only Bridgeline staff see it, only on the clients it's enabled
+  for, on the Apps page in HawkSearch, always at its newest version. Developers can't release it; an approver does, on
+  the Apps page (see [Versions and aliases](#versions-and-aliases)).
+- **Released apps.** Every deploy is a new version. Clients stay on the approved version until the new one is approved in
+  HawkSearch (staff can open it there first). Changes to settings in `hawk-app.json` (name, description,
+  icon, category, version, visibility, hosting, scopes, `systemParameters`, `schedules`, `config`, `externalOrigins`, `listed`, `minProtocolVersion`) wait for approval
+  the same way. For `config` only the declarations are reviewed: its values are set at any time without review.
+- **Functions.** Engineering enables functions per app. A version whose functions changed (added, removed, new code,
+  dependencies or settings) always waits for review, even with auto-approve; reviewers see each function's settings,
+  dependency changes and a diff of its sources.
+- **Clients any time.** Client changes (`hawk-app clients` or the Hawk Analytics portal) apply at once, released or
+  not, without review (see [Clients](#clients)).
+- **Auto-approve.** Approvers can set an app to auto-approve: new versions and setting changes are then released
+  straight away.
+- **Approval workflow.** Bridgeline users submit a version or settings change for approval on the Apps page in
+  HawkSearch (`npx hawk-app open`; with an optional note). Members of the **Approvers** group approve it (it's released), reject it with a
+  reason, or force approve without a request (for example to roll back). The approvers get an email about each request
+  (they can stop these with the link at the bottom), the submitter gets one when it's approved or rejected, and every
+  step is posted to the #hawk-app-approvers Slack channel. A new main-line deploy or settings change clears a waiting request (deploy says so: submit it again in
+  HawkSearch). `hawk-app status` shows `request     waiting for approval (submitted by Jane Doe, 2026-10-08: <note>)`
+  or `request     rejected by Jane Doe on 2026-10-09: <reason>`.
+- **Elevated apps.** Apps using queries, functions, system parameters, dashboard writes, AI, external Lambdas, HawkSearch
+  features or the index (rebuilds, items, management) are never auto-approved;
+  approvers review their queries, functions and scopes like any other change.
+- **Rollback and retention.** The released version, the newest version and the 5 newest others are kept, so staff can
+  roll back in HawkSearch; older versions are removed when you deploy.
+
+## How deploy works
+
+1. The CLI asks the platform for the next version number (`v<n>`) with your publisher key, and builds the app for
+   `/<slug>/v<n>` (unless `--no-build`).
+2. The CLI sends the list of files (paths and sizes). The platform checks them:
+   - the file types are static web content
+   - the sizes are within the limits
+   - the paths can't leave your app's folder
+   - you own the slug.
+
+   It then returns one **short-lived upload link per file**. Each link allows exactly one upload, to exactly that file in the version's folder, and expires after about 15 minutes.
+3. The CLI uploads each file straight to storage using its link.
+4. The CLI tells the platform it's done, with the result of `npm audit` of the production dependencies (run before the version was reserved, see below). The platform checks that every file arrived and marks the version ready: an app not released yet shows it to Bridgeline staff at once, a released app holds it for review (or releases it, with auto-approve). Versions never change once uploaded, so there's no CDN refresh to wait for.
+
+The platform also sets content types and caching: hashed bundles are cached for a year, HTML is never cached, and everything else is cached for 5 minutes.
+
+### Dependency check
+
+Before it reserves a version number, `deploy` runs `npm audit --json --omit=dev` in the app folder (next to
+`hawk-app.json`, 60 s at most), and it sends the vulnerability counts with the version. Reviewers see them with the other
+pre-approval checks in HawkSearch and the Hawk Analytics portal. High or critical vulnerabilities fail that check, so
+approvers can only force approve the version: when the audit finds any, `deploy` names the packages and asks before
+going on.
+
+```
+  dependencies 1 high, 1 moderate (npm audit)
+npm audit found 1 high, 1 moderate in the production dependencies (postcss). Approvers can only force approve this
+version. Deploy anyway? (Fix with npm audit fix or by updating the packages; npm run app:audit shows the details.) (y/N)
+```
+
+No cancels without reserving anything. `--yes` goes on with a warning, and so does a pipeline (no terminal to ask in).
+Moderate and low findings are only reported. Check before deploying with `npm run app:audit` (in apps created from the
+templates: `npm audit --omit=dev --audit-level=high`, which exits non-zero on high or critical findings, so it also works
+as a CI step). Other outcomes:
+
+```
+  dependencies no known vulnerabilities
+  dependencies not checked: no package-lock.json
+```
+
+An app in an npm workspace is audited with the lockfile at the repository root. Without a `package-lock.json` (in the
+app folder or above it), when npm audit fails (for example a registry without audit support) or times out, the
+version is marked "not checked" with a short reason. `--no-audit` skips it (`not checked: skipped (--no-audit)`).
+
+## In CI (example: Bitbucket Pipelines)
+
+```yaml
+- step:
+    name: Deploy Hawk App (dev)
+    deployment: development        # HAWK_APPS_ENV (dev or prod) and HAWK_APPS_PUBLISHER_KEY as secured variables
+    script:
+      - npm ci
+      - npx hawk-app deploy        # builds with the version's base path, then uploads (with hawk-app.json)
+```
+
+Requires Node 20 or later. Dependencies: `esbuild` (bundles functions) and `fflate` (zips them).