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

package/README.md

@@ -68,8 +68,9 @@ separately, see [Clients](#clients)):
                                        // 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, …
+  "scopes": ["reports:read"]           // reports:read = analytics; hawksearch:read = dashboard API (read) and preview tools;
+                                       // hawksearch:write = create/update/delete synonyms, redirects, banners, …,
+                                       //   and pin items (hawksearch.pinning)
                                        // through the dashboard API (see the bridge's "Writing to HawkSearch");
                                        // data:read = your own SQL queries in queries/ (see "Custom data");
                                        // functions:invoke = server-side functions (see "Functions");
@@ -79,6 +80,8 @@ separately, see [Clients](#clients)):
                                        // (with "systemParameters", see "HawkSearch system parameters");
                                        // hawksearch:search = HawkSearch search and autocomplete, live or preview;
                                        // hawksearch:recommendations = the engine's recommendation widgets;
+                                       // hawkai:read = HawkAI agents and smart responses: list, run a smart
+                                       //   response, open an agent in HawkAI's assistant widget;
                                        // 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;
@@ -174,8 +177,8 @@ npx hawk-app dev --client e3141 --engine 3141
 
 The first time, it asks for part of a client's name and lets you pick the client, then saves it in `.env.local` as
 `HAWK_APPS_DEV_CLIENT` (`--client <id>` uses another). A new app is registered on the platform the first time (not
-released: only Bridgeline staff see it). Queries and functions always run from the **deployed** version, even here:
-deploy after changing them.
+released: only Bridgeline staff see it). Queries and functions called from the app run from the **deployed** version,
+even here: deploy after changing them (or test them locally with `hawk-app test`).
 
 Starts your app (`npm run dev`) and a local stand-in for HawkSearch at `http://localhost:3200`, which embeds the app
 the way HawkSearch does (the bridge's own `<hawk-app-frame>`). The app gets **real tokens and real data**: the CLI asks
@@ -193,7 +196,19 @@ CORS setup, on dev or prod; so does the AI stream (`app.ai.stream`), which the p
   `https://dev.hawksearch.net`; `HAWKSEARCH_GROUP_KEY=true` for a group key): the platform seals it into the token. It is
   never written anywhere else.
 - Queries and functions run against your **current deployed version** (deploy first after changing them); the UI is your
-  local code. Every dev token is audit-logged with your publisher key.
+  local code. Every dev token is audit-logged with your publisher key. To run functions from your local code, use
+  `hawk-app test` ([Testing functions](#testing-functions-hawk-app-test)).
+- **Actions:** when `hawk-app.json` has `actions`, the toolbar's **Action** menu opens an action's view in a dialog as
+  HawkSearch will (type the value its targets would read from the page); `app.action.done()` closes it.
+- **Export as PDF:** the toolbar has HawkSearch's PDF icon. It shows while the page allows it (`app.setPdfExport` /
+  `usePdfExport`; the events list logs it), and a click downloads the page as a PDF.
+- **Explain this page:** the toolbar has HawkSearch's **Explain this page** button. It shows once the page says what
+  it shows (`app.assistant.setContext` / `usePageContext`; the events list logs each one), and explains it with the
+  platform's AI for the client.
+- **Client API:** `http://localhost:3200/v1/clients/<id>/apps/<slug>/api/<name>` (with `X-HawkSearch-ApiKey`) runs the
+  endpoint's function from your **local** `functions/` (bundled on each call), with a real token for the client whose
+  HawkSearch connection is the key you send. The platform's own checks (the key's engine, API access, the limit) are
+  skipped; secrets and config are empty.
 
 ## Deploy
 
@@ -215,7 +230,7 @@ npx hawk-app deploy --dry-run     # what hawk-app.json would change, without a v
 | Command | What it does |
 |---|---|
 | `init` | Creates `hawk-app.json` (never overwrites an existing one) and adds [AGENTS.md](#ai-coding-assistants-agentsmd). |
-| `validate [--build [<folder>]]` | Checks `hawk-app.json` locally, `queries/` and `functions/` if the app has them, and the project: the bridge is used and current, and there's a build script (or `--no-build` deploys). `--build` also builds the app with a stand-in base path (`/<slug>/v0`) and fails on absolute URLs outside it; the folder comes from the `app:deploy` script unless given. |
+| `validate [--build [<folder>]]` | Checks `hawk-app.json` locally, `queries/` and `functions/` if the app has them, and the project: the bridge is used and current, the app says what its page shows ("Explain this page"), and there's a build script (or `--no-build` deploys). `--build` also builds the app with a stand-in base path (`/<slug>/v0`) and fails on absolute URLs outside it; the folder comes from the `app:deploy` script unless given. |
 | `deploy [<folder>] [--no-build] [--no-audit] [--alias <name>] [--dry-run]` | Sends hawk-app.json first (its scopes and settings go with every deploy), then reserves the next version number, runs `npm run build` with `HAWK_APP_BASE_PATH=/<slug>/v<n>` (when package.json has a `build` script, unless `--no-build`), then uploads every file in the build folder (the template's, `dist`, `out` or `public`, unless given) to `/<slug>/v<n>/` on the apps CDN, plus `queries/` and the bundled `functions` (if any) to the platform's private storage, and deploys the functions. Runs `npm audit` of the production dependencies first, asks before deploying with high or critical findings, and reports the counts to reviewers (see [Dependency check](#dependency-check); `--no-audit` skips it). Warns when the HTML loads absolute URLs outside `/<slug>/v<n>/`, which wouldn't load, and when the code calls a bridge feature whose scope `hawk-app.json` lacks (e.g. `app.ai.generate` without `ai:invoke`; `validate` and `doctor` check it too). Says whether the version is a draft (staff only until it's approved) or auto-approved, and when it cleared an approval request. `--alias staging` points the alias at the new version (see [Versions and aliases](#versions-and-aliases)). `--dry-run` only shows what hawk-app.json would change. |
 | `register` | Sends `hawk-app.json` without a new version (for scripts; `deploy` and `dev` already send it). It never releases anything and never changes the app's clients. On a released app, changes wait for review. |
 | `versions` | Every version with its status (draft, waiting, approved, rejected) and the aliases on it. |
@@ -294,10 +309,30 @@ HawkSearch). The full picture, with diagrams: docs/versions-and-aliases.md in th
 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 errors              # the last 7 days (--days 1-30): grouped, the most frequent first, with versions, clients and an [id]
+npx hawk-app errors --explain 3fa1c2d9   # one error's brief, then Claude's likely cause and patch (--no-ai: the brief only)
 npx hawk-app usage               # the last 30 days (--days 1-400): opens, view opens, users and clients; staff apart
 ```
 
+**Errors that come with a fix.** `--explain <id>` writes the error's **brief** and asks Claude for the cause:
+
+- **The stack, mapped to your source:** each of the app's frames as `src/app/page.tsx:42:17`, with the code around it
+  and the line that threw marked `>`. The maps are the version's own, so the code is what ran, not what's in your
+  checkout now. Library frames are listed on one line each.
+- **The platform calls that failed** in the same versions and days (route, status, code, detail), often the reason
+  (e.g. a report that answered 502 left `rows` undefined).
+- **What changed since the last version without it:** a diff of the files in the stack between that version and the
+  one that threw.
+- **Then Claude** (the platform's, on its account, no scope or key needed) answers with the likely cause, a patch as a
+  unified diff, and how to check it. Check the patch before you apply it; nothing is changed for you.
+- **In Claude Code,** the MCP server's `error_brief` tool gives it the same brief, so it can fix the code in your repo
+  directly (ask: "fix error 3fa1c2d9").
+
+It needs the version's **source maps**: the templates build them (`productionBrowserSourceMaps` in next.config.ts,
+`build.sourcemap: 'hidden'` in vite.config.ts), and `hawk-app deploy` sends every `.map` file of the build to the
+platform's private bucket instead of the CDN, so your source is never public. Without maps the stack stays minified and
+the brief says so. Errors of versions deployed before keep their minified stacks; the next deploy maps the new ones.
+
 ## Accessibility check
 
 `hawk-app deploy` runs axe-core (WCAG 2.1 A/AA and best practices) over up to 10 built pages and sends the result with
@@ -338,14 +373,40 @@ instead of guessing:
   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`.
+- **`.vscode/mcp.json`** (VS Code / Copilot), which starts 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).
+An existing AGENTS.md or CLAUDE.md is never replaced: the CLI's part (or the import) is added to it. An existing
+`.vscode/mcp.json` gets the `hawk-apps` server added (one with comments is left alone: add it yourself).
+
+### Claude Code plugin (`hawk-app claude`)
+
+Claude Code gets the MCP server, and skills for the common jobs, from the **Hawk Apps plugin**, installed once per
+machine (not per app):
+
+```bash
+npx @bridgeline-digital/hawk-app-cli@latest claude
+```
+
+It copies the plugin, which ships in this package, next to your login (`%APPDATA%\hawk-app\claude-plugin` on Windows,
+`~/.config/hawk-app/claude-plugin` elsewhere) and adds it to Claude Code as a local marketplace with `claude plugin`
+when that command is on the PATH. Otherwise it prints the two commands to type in the Claude Code panel:
+`/plugin marketplace add <folder>` and `/plugin install hawk-apps@hawk-apps`. No repository access is needed. Run it
+again to update: the plugin carries the CLI's version, so Claude Code takes the new one (`/reload-plugins` in an open
+session). Engineers can also add the repository itself as the marketplace (`.claude-plugin/marketplace.json` at its root).
+
+| Skill | What it does |
+| --- | --- |
+| `/hawk-apps:new-screen` | A new page, view or panel from the UI kit: its components, the data's bridge calls and scopes, the states every screen needs, then `validate`. |
+| `/hawk-apps:add-query` | A query in `queries/`: report first if one fits, tables and columns from `data_tables`/`data_describe`, the partitions rule, the params file, `validate`; client rows never come into the chat. |
+| `/hawk-apps:add-function` | A function, job or schedule: the declaration, the handler, secrets set by you in a terminal, errors, `validate`. |
+| `/hawk-apps:prepare-review` | The approvers' checks (bundle, dependencies, accessibility, outside origins, scopes, queries, functions): fixes them or says what's left. |
+
+Claude also picks a skill on its own when your request matches it. The plugin's MCP server starts in the open folder,
+from the app's own CLI (`node_modules`) when it has one, else the released CLI through `npx`. The CLI no longer writes
+`.mcp.json` for Claude Code; `upgrade` takes the old `hawk-apps` entry out of it (other servers are kept), so the tools
+aren't listed twice.
 
 ### MCP server (`hawk-app mcp`)
 
@@ -360,6 +421,7 @@ Protocol](https://modelcontextprotocol.io)), so they can look things up and chec
 | `doctor` | `hawk-app doctor`: what's wrong with the setup, and how to fix it. |
 | `versions`, `why` | Every version with its status and aliases; what a client sees of the app, and why. |
 | `errors`, `usage` | The app's page errors; its opens, users and clients per day. |
+| `error_brief` | One error's brief (`errors --explain <id> --no-ai`): the stack mapped to the source with the code, the failed platform calls, what changed since the last version without it. For fixing it in the repo. |
 | `ui_components` | The UI kit's components for the app's template (next-mui: the provider, components and theme; the others: the stylesheet classes and elements), or what's said about one, from the kit's README, with a link to the live [gallery](https://developers.hawksearchapps.com/reference/ui-kit-gallery/). |
 | `analytics_reports` | The analytics API's reports for `app.analytics.report()`, with one report's columns, filters and an example call, read from the developer portal's dev spec (public; no client data). |
 | `hawksearch_api` | HawkSearch's API reference (developerdocs.hawksearch.com): an operation's parameters, request and response fields, the bridge call (`app.dashboard.*`, `app.hawksearch.*`) and its scope, or why apps can't call it (public; no client data). |
@@ -369,17 +431,17 @@ Protocol](https://modelcontextprotocol.io)), so they can look things up and chec
 | `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`):
+It also has **prompts**, ready-made tasks that use the tools (in Claude Code, the plugin's skills cover the same
+jobs; its slash commands list the prompts too, under the plugin's server):
 
-| 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. |
+| Prompt | What it does |
+| --- | --- |
+| `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` | Finds the bridge calls, scopes and showcase examples it needs, says what the review will see, makes the change and validates it. |
+| `explain-app` | What the app does, its scopes (unused or missing ones too) and where it stands in review. |
+| `deploy-to-client` | 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.
+Each takes an optional `dir` for a workspace with several apps. In VS Code with Copilot they're under `/`.
 
 - **Dev only.** Every tool runs with `--env dev`; nothing reaches prod. Approvals, secrets, removing clients and logins
   aren't tools.
@@ -392,9 +454,10 @@ Each takes an optional `dir` for a workspace with several apps. In VS Code with
   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
+`create` and `init` add it to `.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`.
+`validate` warns when it isn't); Claude Code gets it from the plugin (above). For Cursor, add the same command to
+`.cursor/mcp.json` under `mcpServers`.
 
 ## Clients
 
@@ -614,6 +677,107 @@ with 6 fields (`minutes hours day-of-month month day-of-week year`, no `cron( )`
 scope. `schedules` is a setting sent with each deploy: on a released app a change waits for review like scopes,
 and `hawk-app status` lists the registered schedules.
 
+`events` run a job function when something happens for a client, so the app doesn't need a schedule to notice it.
+`client.added` runs when a client's users get the app (a store request approved, the client added to the app's list,
+or the app released to the clients on its list), `config.changed` when a config value changes for a client (its own,
+or a global one), `version.released` when another version reaches a client that had the app, and, read from HawkSearch
+once a minute, `hawksearch.changed` (a dashboard change; `"sections": ["synonym", …]` to follow only some) and
+`index.rebuilt` (a rebuild finished):
+
+```jsonc
+"functions": { "welcome": { "job": true }, "migrate": { "job": true } },
+"events": { "client.added": { "function": "welcome" }, "version.released": { "function": "migrate" } }
+```
+
+The run is a job for that client, without a site or HawkSearch connection, except the HawkSearch events, which get the
+engine and the client's connection (the bridge README's **Events** section has the details). `hawk-app validate` checks the event names, that each `function` is a job function of the same
+`hawk-app.json`, and the `functions:invoke` scope; `events` is reviewed like scopes, and `hawk-app status` lists them.
+
+`api` turns functions into endpoints the client's own systems call (a developer's script, a job on their side) with
+their engine's HawkSearch site API key, once Bridgeline turns API access on for the client in HawkSearch (the app's
+kebab menu › API access, which shows each endpoint's URL and a curl):
+
+```jsonc
+"functions": { "design-html": {} },
+"api": { "design-html": { "function": "design-html", "method": "GET", "description": "A saved design's email HTML" } }
+```
+
+The function isn't a job (the caller waits); its input is the query string (GET) or the JSON body (POST), and
+`apiResponse()` from the bridge's `/server` entry answers HTML or any other type (the bridge README's **Client API**
+section). `hawk-app validate` checks the names (at most 10), that each `function` is a function of the same
+`hawk-app.json` without `"job": true`, the method (GET or POST) and the `functions:invoke` scope; `api` is reviewed like
+scopes, and `hawk-app status` lists the endpoints.
+
+### Actions (start the app from HawkSearch's screens)
+
+`actions` put an app where the work is: a button in HawkSearch's own pages that opens one of the app's views in a
+dialog, with values read from the page as the view's params. The app says where with **targets**: the page (a regular
+expression on its path), a CSS selector for the things (one button per match), where the button goes, and how each
+param is read:
+
+```jsonc
+"views": { "fix": { "path": "views/fix", "title": "Fix a search", "params": ["keyword"] } },
+"actions": {
+  "fix-keyword": {
+    "label": "Fix with Zero Results Fixer",
+    "view": "fix",
+    "targets": { "hawksearch": [{
+      "path": "/admin/advanced-analytics/top-queries/?$",
+      "selector": "bl-table tbody.table__body > tr.table__row",
+      "anchor": "td.table__cell:first-child",
+      "params": { "keyword": { "selector": "td.table__cell:first-child" } }
+    }] }
+  }
+}
+```
+
+Deploy; once the version is approved, the buttons appear in HawkSearch with no change there. `actions` always needs an
+approver (never auto-approve): reviewers see each target and what it reads. Pick stable selectors (ids, `data-*`
+attributes, element names): if HawkSearch changes its markup, deploy new targets. A param can also name a `data-*`
+attribute (`"data": "hawk-keyword"`), used as is when the page has it, with its selector and pattern as the fallback. The view reads
+`app.context.view.params` and `app.context.view.action`, and calls `app.action.done({ changed })` to close the dialog
+(the bridge README's **Actions**, with every target setting). `hawk-app validate` checks the targets (paths and
+patterns are regular expressions, params the view declares); `hawk-app status` lists the actions. `hawk-app dev` has an
+**Action** menu: pick an action, type a value, and the view opens in a dialog as in HawkSearch. For complete recipes
+(actions, schedules, events, a client API endpoint and their tests), see [docs/examples.md](../../docs/examples.md).
+
+### Testing functions (`hawk-app test`)
+
+Functions can be tested without deploying. Put tests next to them as `functions/<name>.test.ts` (Node's own
+`node:test` and `node:assert`: nothing to install) and run `npx hawk-app test` (or `npm run app:test`):
+
+```ts
+// functions/design-html.test.ts
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { runFunction } from '@bridgeline-digital/hawk-app-cli/testing';
+
+test('answers the design as JSON', async () => {
+    const run = await runFunction('design-html', {
+        trigger: 'api',                                     // call (default), job, schedule, event or api
+        input: { designId: 'spring' },
+        storage: { 'design#spring': design },               // storage in memory
+        answers: [{ method: 'POST', path: 'hawksearch/recommendations', body: recommendations }],
+    });
+    assert.equal(run.error, null, run.logs);
+    assert.equal(run.result.subject, 'New for spring');
+});
+```
+
+- `runFunction(name, options)` bundles the function exactly as `hawk-app deploy` does and runs it in its own Node
+  process with the event the platform sends (`input`, `trigger`, `client`, `engine`, `user`, `secrets`,
+  `clientSecrets`, `config`), with its `timeoutSeconds`. It answers `{ result, error, calls, progress, storage, logs }`:
+  what it returned or threw, every platform call it made (with its body and what answered it), `ctx.job.progress`
+  reports, the storage afterwards, and its console output.
+- Its platform calls go to a fake platform: `answers` first, then storage and config in memory (when the test gives
+  `storage` or `config`), then a **recording** (`recording: 'spring'` reads `functions/__recordings__/spring.json`).
+  A call nothing answers fails with 501 `not_recorded`.
+- `hawk-app test --record` makes the recordings: calls nothing else answers go to the platform once, as the test's
+  `client` (and `engine`; `HAWKSEARCH_API_KEY` for HawkSearch), and are saved. Recordings hold real answers: review them
+  before committing. They are never deployed with the function's source.
+- `hawk-app test <filter>` runs only the test files whose path contains the filter. Tests aren't functions: they are
+  never deployed as one.
+
 ## Email
 
 Apps with the `email:send` scope can send email with `app.email.send(...)` or, from a function,
@@ -690,7 +854,7 @@ with it is never auto-approved. Prompts and answers are never logged or stored.
   the Apps page (see [Versions and aliases](#versions-and-aliases)).
 - **Released apps.** Every deploy is a new version. Clients stay on the approved version until the new one is approved in
   HawkSearch (staff can open it there first). Changes to settings in `hawk-app.json` (name, description,
-  icon, category, version, visibility, hosting, scopes, `systemParameters`, `schedules`, `config`, `externalOrigins`, `listed`, `minProtocolVersion`) wait for approval
+  icon, category, version, visibility, hosting, scopes, `systemParameters`, `schedules`, `events`, `api`, `actions`, `config`, `externalOrigins`, `listed`, `minProtocolVersion`) wait for approval
   the same way. For `config` only the declarations are reviewed: its values are set at any time without review.
 - **Functions.** Engineering enables functions per app. A version whose functions changed (added, removed, new code,
   dependencies or settings) always waits for review, even with auto-approve; reviewers see each function's settings,

package/agents/AGENTS.md

@@ -50,11 +50,14 @@ app.onContextChange(render); // the user switched client, engine or dates
 | Call | Scope |
 | --- | --- |
 | `app.analytics.report('queries', { limit, startDate, endDate, filters })` | `reports:read` |
-| `app.dashboard.get('Synonym')`: HawkSearch dashboard API, no API version in the path | `hawksearch:read` |
+| `app.dashboard.get('Synonym')`: HawkSearch dashboard API, no API version in the path. Typed routes: `app.dashboard.resource('Synonym').list()/get(id)` (reads) and `.create/update/delete` (`hawksearch:write`), models as `HawkSearchModel<'Synonym'>` | `hawksearch:read` |
 | `app.dashboard.post/put/delete(path, body)`: merchandising and relevancy resources only, never retried | `hawksearch:write` |
-| `app.hawksearch.search(...)`, `app.hawksearch.autocomplete(...)` on the user's engine | `hawksearch:search` |
+| `app.hawksearch.pinning.set(itemPinId, docId, isPinned)`, `.order(itemPinId, docIds)`: the Item Pin rule a search applied (its `ItemPinId`), saved as the user | `hawksearch:write` |
+| `app.hawksearch.search(...)`, `app.hawksearch.autocomplete(...)` on the user's engine; preview: `IsInPreview`, `SmartBar`, `ClientData.PreviewBuckets`, `IndexName`, `ExplainDocId` | `hawksearch:search` |
+| `app.hawksearch.preview.settings/indexes/item/explain`: the preview page's visitor targets, indexes, item details, keyword explain | `hawksearch:read` |
+| `app.hawkai.agents/agent/smartResponses/smartResponse`: the client's HawkAI agents and smart responses (names and settings); `runSmartResponse(id, { query, search })`: its answer for a (preview) search; `assistant(agentId)`: the values for HawkAI's assistant widget | `hawkai:read` |
 | `app.data.query('name', params)`: your SQL in `queries/<name>.sql` + `.json` | `data:read` |
-| `app.functions.call('name', input)`, `.start/.wait/.job` for jobs: `functions/<name>.ts` exporting `handler` | `functions:invoke` |
+| `app.functions.call('name', input)`, `.start/.wait/.job` for jobs: `functions/<name>.ts` exporting `handler`. `schedules` and `events` in hawk-app.json run job functions on a cron, or when something happens for a client (`client.added`, `config.changed`, `version.released`, `hawksearch.changed` with optional `sections`, `index.rebuilt`; input types `HawkAppEvent` from the bridge's `/server`). `api` in hawk-app.json makes a function (not a job) an endpoint the client's own systems call with their HawkSearch site API key (`{ "<name>": { "function", "method": "GET" \| "POST" } }`; `apiResponse(body, { contentType })` for HTML). Test functions without deploying: `functions/<name>.test.ts` with `node:test` and `runFunction` from `@bridgeline-digital/hawk-app-cli/testing` (storage, answers, recordings), run by `npx hawk-app test` | `functions:invoke` |
 | `app.email.send(...)` | `email:send` |
 | `app.storage.get/put/delete/list/batch/usage`: the app's own JSON data per client (350 KB a value, `ttlDays`, `ifVersion`); `app.storage.files.upload/url/download/list/delete`: its files (100 MB each) | `storage` |
 | `app.hawksearch.systemParameters.list/get/set`: names listed in `systemParameters` | `hawksearch:sysparams:write` |
@@ -92,21 +95,23 @@ https://www.npmjs.com/package/@bridgeline-digital/hawk-app-bridge. Its TypeScrip
 
 ## MCP server
 
-`.mcp.json` (Claude Code) and `.vscode/mcp.json` (VS Code) start the CLI's MCP server, `hawk-apps`, from
-`node_modules` (`npm install` first). Its tools: `docs` (the bridge, UI kit, CLI, `hawk-app.json` schema and the
+The CLI's MCP server, `hawk-apps`: Claude Code gets it from the Hawk Apps plugin (`npx @bridgeline-digital/hawk-app-cli@latest
+claude`, once per machine; it also adds the skills `/hawk-apps:new-screen`, `/hawk-apps:add-query`,
+`/hawk-apps:add-function` and `/hawk-apps:prepare-review`), and VS Code from `.vscode/mcp.json`; both start this app's
+copy in `node_modules` (`npm install` first). Its tools: `docs` (the bridge, UI kit, CLI, `hawk-app.json` schema and the
 showcase app, which has working code for every feature), `ui_components` (the UI kit's components for this app's
 template: use them before writing your own), `validate`, `status` (with the review checks approvers will see),
 `analytics_reports` (every report `app.analytics.report()` can call, with its columns and filters),
 `hawksearch_api` (HawkSearch's dashboard, search, recommendation and indexing operations: fields, the bridge call, its scope),
 `data_tables` and `data_describe` (names and columns, never data), `logs`, `init`, `upgrade`,
-`deploy` (with `alias`, and `dryRun` to only show what hawk-app.json would change), `versions`, `why` (what a client sees, and why), `doctor` (what's wrong with the setup), `errors`, `usage`, and `clients` and `clients_add`, which only ever use the dev platform. Prefer them to guessing. When the
+`deploy` (with `alias`, and `dryRun` to only show what hawk-app.json would change), `versions`, `why` (what a client sees, and why), `doctor` (what's wrong with the setup), `errors`, `error_brief` (one error mapped to the source, with the failed calls and what changed since the last version without it: use it to fix production errors here), `usage`, and `clients` and `clients_add`, which only ever use the dev platform. Prefer them to guessing. When the
 user names a client ("deploy to OTC"), call `clients_add` with their words: it shows them a form to pick the exact
 client. With `alias` (`hawk-app clients add <id> --alias review`) the client gets that alias's version: on a version that
 isn't approved, only Bridgeline staff in it see the app. Only approvers change what a client whose users see the app
 gets. `hawk-app deploy out --alias staging` deploys off the main line: the version carries this hawk-app.json, `staging`
 points at it, and the version under review isn't touched. A plain `hawk-app deploy` sends hawk-app.json first, so scope
 changes go with the deploy. Client names aren't shared with you; don't ask for them in the chat. Its prompts (`check-before-submit`, `add-feature`,
-`explain-app`, `deploy-to-client`; in Claude Code `/mcp__hawk-apps__<name>`) are ready-made tasks that use them.
+`explain-app`, `deploy-to-client`) are ready-made tasks that use them; in Claude Code prefer the plugin's skills.
 
 ## Icon
 
@@ -136,6 +141,24 @@ Each view is a route, e.g. `src/app/views/preview/page.tsx` for `"path": "views/
   `{ cache: 'no-store' }` on a call that writes (e.g. an analytics report that records something), or
   `{ cache: 'reload' }` to refresh. The full app page is never cached.
 
+**Say what each page shows**: HawkSearch's "Explain this page" button explains the app's page from it (no scope).
+With the UI kit: `usePageContext(rows ? { page: '<the page>', dateRange, totals, top10 } : null)`; otherwise
+`app.assistant.setContext({ ... })` whenever the data or filters change. Plain names and numbers of what's on screen,
+at most 50 KB; summarize long tables. `hawk-app validate` warns when an app never sets one.
+
+**Export as PDF** (only on pages worth keeping: a report, a summary): `usePdfExport({ fileName })` from the UI kit
+(`false` while loading), or `app.setPdfExport({ fileName })` and `app.setPdfExport(null)` when the page leaves. The
+host shows a PDF icon and downloads the whole page; mark buttons and filters `data-hawk-pdf-ignore`.
+
+**Actions** (`actions` in `hawk-app.json`) add a button to HawkSearch's own pages that opens a view in a dialog:
+`{ "<name>": { "label": "Fix with …", "view": "fix", "targets": { "hawksearch": [{ "path": "<regex on the page path>",
+"selector": "<CSS: each thing>", "anchor"?: "<CSS inside it>", "position"?: "after", "params": { "keyword": { "data"?,
+"selector"?, "attribute"?, "pattern"? } } }] } } }`. `"data": "keyword"` reads `data-keyword` as is when the page has it,
+else the rest of the reader applies. Prefer stable selectors (ids, `data-*`, element names); the view must list the
+params in its `params` and handle them missing. The view reads `app.context.view.params` (and `context.view.action`:
+`{ name }`), its toasts show, and `app.action.done({ changed: true })` closes the dialog once the work is saved. Actions
+always need an approver. Try it with `hawk-app dev`'s Action menu.
+
 A slot can also hold the **entire app** (its own page, with no `view` in the context): it then runs inside another
 page, at the slot's height, so don't rely on the full window either.
 
@@ -169,7 +192,8 @@ npx hawk-app versions            # every version with its status and aliases
 npx hawk-app open                # the app's page in HawkSearch (review, submit for approval)
 npx hawk-app logs <function>     # a function's logs
 npx hawk-app config list         # config values (config set <key> <value> [--client <id>], config unset <key>)
-npx hawk-app errors              # errors in the app's pages (deployed versions), the most frequent first
+npx hawk-app errors              # errors in the app's pages (deployed versions), the most frequent first, with [id]s
+npx hawk-app errors --explain <id>  # one error mapped to the source, the failed calls, what changed; then a likely fix
 npx hawk-app usage               # opens, users and clients per day
 npx hawk-app upgrade             # bring the app (and this file) up to the CLI's current template
 npx hawk-app upgrade --channel latest  # a dev app (bridge/CLI on the `dev` tag) to the released versions

package/claude-plugin/.claude-plugin/marketplace.json

@@ -0,0 +1,14 @@
+{
+  "name": "hawk-apps",
+  "owner": { "name": "Bridgeline Digital" },
+  "metadata": {
+    "description": "Hawk Apps for Claude Code: the hawk-apps MCP server and skills for building, checking and shipping Hawk Apps."
+  },
+  "plugins": [
+    {
+      "name": "hawk-apps",
+      "source": "./hawk-apps",
+      "description": "Build Hawk Apps with Claude Code: the hawk-apps MCP server (docs, UI kit, validate, deploy to dev) and skills for new screens, queries, functions and review."
+    }
+  ]
+}

package/claude-plugin/hawk-apps/.claude-plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+  "name": "hawk-apps",
+  "version": "0.1.0",
+  "description": "Build Hawk Apps with Claude Code: the hawk-apps MCP server (docs, UI kit, validate, deploy to dev) and skills for new screens, queries, functions and review.",
+  "author": { "name": "Bridgeline Digital" },
+  "homepage": "https://developers.hawksearchapps.com/start/with-claude/",
+  "keywords": ["hawk-apps", "hawksearch"]
+}

package/claude-plugin/hawk-apps/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "hawk-apps": {
+      "command": "node",
+      "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/mcp.mjs"]
+    }
+  }
+}

package/claude-plugin/hawk-apps/scripts/mcp.mjs

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+// Starts the Hawk Apps MCP server (`hawk-app mcp`) for Claude Code, in the open project: the project's own CLI when it
+// has one (a dev dependency, so the tools match the app's CLI version and channel), else the released CLI through npx.
+// stdio is passed straight through: it is the MCP protocol.
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const CLI_BIN = join('node_modules', '@bridgeline-digital', 'hawk-app-cli', 'bin', 'hawk-app.mjs');
+
+/** The CLI installed in the project or a folder above it (a workspace of apps), or null. */
+export function findProjectCli(start) {
+    for (let dir = resolve(start); ; dir = dirname(dir)) {
+        const bin = join(dir, CLI_BIN);
+        if (existsSync(bin)) return bin;
+        if (dirname(dir) === dir) return null;
+    }
+}
+
+function run() {
+    const project = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+    const local = findProjectCli(project);
+    const child = local
+        ? spawn(process.execPath, [local, 'mcp'], { cwd: project, stdio: 'inherit' })
+        : spawn('npx', ['--yes', '@bridgeline-digital/hawk-app-cli@latest', 'mcp'], { cwd: project, stdio: 'inherit', shell: process.platform === 'win32' });
+    child.on('error', (error) => {
+        process.stderr.write(`hawk-apps: could not start the MCP server (${error.message}). Is Node.js installed?\n`);
+        process.exit(1);
+    });
+    child.on('exit', (code, signal) => process.exit(signal ? 1 : (code ?? 0)));
+    for (const signal of ['SIGINT', 'SIGTERM']) process.on(signal, () => child.kill(signal));
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) run();

package/claude-plugin/hawk-apps/skills/add-function/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: add-function
+description: Add or change a server-side function (functions/<name>.ts, AWS Lambda), a background job, a schedule, an event handler or a client API endpoint in a Hawk App, with tests. Use when the app needs server code, a third-party API with a secret key, work longer than a page should wait, something on a timer, setup when a client gets the app, or data the client's own systems fetch.
+---
+
+# Add a function
+
+Functions are the app's own server code (Node 22 Lambda), shipped with each version. **Engineering must enable
+functions for the app**, and a version whose functions changed always waits for review. Before writing one, check
+whether the bridge already does it from the page (`docs`): no function is simpler.
+
+1. **Scope and declaration.** Tell the user, then add `functions:invoke` to `scopes` and declare the function in
+   `hawk-app.json`:
+   ```jsonc
+   "functions": { "sync-feed": { "timeoutSeconds": 20, "memoryMb": 512, "secrets": ["FEED_API_KEY"] } }
+   ```
+   Names: lowercase letters, digits, single dashes, up to 40. `timeoutSeconds` 1–25 (1–900 with `"job": true`),
+   `memoryMb` 128–1024, at most 10 functions.
+2. **Write `functions/<name>.ts`** exporting `handler`:
+   ```ts
+   import type { HawkFunction } from '@bridgeline-digital/hawk-app-bridge/server';
+   export const handler: HawkFunction<In, Out> = async (input, ctx) => { … };
+   ```
+   Use `ctx.platform` (the same APIs as `app`), `ctx.client.id`, `ctx.user`, `ctx.config`, `ctx.secrets.NAME`. Stateless:
+   keep state in `ctx.platform.storage`. Look up `ctx` and the errors with `docs` ("Functions").
+3. **Secrets** are never in code, `hawk-app.json` or the chat. Tell the user to run `npx hawk-app secrets set NAME`
+   themselves (hidden input). A value each client sets for itself is a `clientSecrets` entry instead.
+4. **Long work** is a job (`"job": true`, up to 900 s): the app calls `app.functions.start(name, input)` and
+   `app.functions.wait(jobId)`. **On a timer** it's a `schedules` entry (a job function, a 6-field EventBridge cron at
+   most hourly, an IANA `timezone`) that users turn on per client with `app.schedules.enable(name)`. **When something
+   happens for a client** it's an `events` entry (`"<event>": { "function": "<job>" }`): `client.added` (it got the
+   app), `config.changed` (its config changed), `version.released` (a new version reached it): these run without a site
+   or HawkSearch connection, so they can't call HawkSearch. `hawksearch.changed` (a dashboard change, `sections` to
+   narrow it) and `index.rebuilt` come from HawkSearch within 1–2 minutes and run with the engine and connection; keep
+   them idempotent.
+5. **Call it** from the app with `app.functions.call('<name>', input)` and handle `function_failed`,
+   `function_timeout`, `secret_missing` and `functions_not_enabled`. **For the client's own systems** (a script, a job
+   on their side) make it an endpoint instead: `"api": { "<name>": { "function": "<function>", "method": "GET" } }`
+   (not a job; input from the query or JSON body; `apiResponse(body, { contentType })` from `/server` for HTML).
+   Bridgeline turns API access on per client; the client calls it with its HawkSearch site API key.
+6. **Test it** without deploying: `functions/<name>.test.ts` with `node:test` and `runFunction` from
+   `@bridgeline-digital/hawk-app-cli/testing` (input, trigger, `storage` in memory, `answers` for platform calls,
+   recordings), then `npx hawk-app test`. A client API endpoint also runs locally under `hawk-app dev` at
+   `http://localhost:3200/v1/clients/<id>/apps/<slug>/api/<name>`.
+7. **Check it.** Run `validate`. Called from the app, functions run from the **deployed** version; deploy only when the
+   user asks. After a deploy, `logs` shows the function's output.

package/claude-plugin/hawk-apps/skills/add-query/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: add-query
+description: Add or change a SQL query (queries/<name>.sql + .json) that a Hawk App runs on the client's analytics data with app.data.query. Use when the user wants data no analytics report gives, a custom aggregate, or to fix a query in a Hawk App.
+---
+
+# Add a query
+
+Queries are the app's own SQL, run by the platform (Athena) on the current client's analytics tables. They ship with
+each version and approvers review them. Check first whether an analytics report already gives the data (the hawk-apps
+`analytics_reports` tool): a report needs no SQL and no review.
+
+1. **Scope.** `data:read` in `hawk-app.json` `scopes` (elevated: the app is never auto-approved). Tell the user before
+   adding it.
+2. **Tables and columns.** `data_tables` (which tables exist, which are partitioned, which are sensitive) and
+   `data_describe <table>`. Never guess a column. Sensitive tables (visitor-level data) need Engineering's opt-in:
+   say so instead of using one.
+3. **Write `queries/<name>.sql`** next to `hawk-app.json` (not in the build folder). Name: lowercase letters, digits,
+   single dashes.
+   - one `SELECT` or `WITH … SELECT`, no `;`;
+   - a `?` for each parameter, in order (`IN ?` for a `string[]`);
+   - every query over dated data filters by a date range **and** has `{{partitions(from, to)}}` (params of type `date`);
+   - name every column (no `SELECT *`), and `LIMIT` every list.
+4. **Write `queries/<name>.json`**: `{ "params": [{ "name": "from", "type": "date", "required": true }, …] }`. Types:
+   `string`, `int`, `decimal`, `date`, `timestamp`, `boolean`, `string[]`; optional `required`, `default`,
+   `min`/`max`, `maxItems`.
+5. **Call it** with `app.data.query('<name>', { from, to })` (or `ctx.platform.data.query` in a function). Look up the
+   result shape and errors with `docs` ("data.query"). Handle a client without analytics.
+6. **Check it.** Run `validate`. To try the SQL, tell the user to run
+   `npx hawk-app data run queries/<name>.sql --client <test client id> --param from=… --param to=…` in a terminal: its rows
+   are client data and must not come into the chat. Queries run only from a **deployed** version, so the app sees a
+   new or changed query after a deploy (only when the user asks).

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

@@ -0,0 +1,36 @@
+---
+name: new-screen
+description: Build a new screen, page, view or panel in a Hawk App with the Hawk Apps UI kit (Spark's look in the host's colors). Use when the user asks for a new page, tab, dashboard, table, chart, form or preview card in a Hawk App (a folder with hawk-app.json).
+---
+
+# New screen from the UI kit
+
+A Hawk App's screens use the Hawk Apps UI kit (`@bridgeline-digital/hawk-app-ui`), so they look like Spark in the host's
+colors and light/dark mode. Never restyle the kit or add another font.
+
+1. **Read the app.** `hawk-app.json` (its `template`: `next-mui` uses the kit's React + MUI provider and components;
+   `next`, `react`, `preact` and `vanilla` use its stylesheet and custom elements) and the CLI's part of `AGENTS.md`.
+2. **Find the components.** Call the hawk-apps `ui_components` tool for this app's template, then for each component
+   you plan to use. Use what the kit has (tables, cards, filters, empty states, dialogs) before writing your own. For
+   your own styles use the kit's `--hawk-ui-*` variables.
+3. **Find the data.** For each number or list on the screen, pick the bridge call and look it up with `docs` (options,
+   limits, error codes; the showcase sections have working code):
+   - analytics reports: `analytics_reports` gives the report's columns and filters;
+   - the client's HawkSearch setup or searches: `hawksearch_api`;
+   - your own SQL: the **add-query** skill;
+   - server work or secrets: the **add-function** skill.
+   Tell the user which scopes the screen needs before adding them to `hawk-app.json`.
+4. **Build it** in the app's style:
+   - read the client, engine and dates from `app.context` and re-load on `app.onContextChange`;
+   - when `app.context.tenant.analyticsProvisioned === false`, show a message instead of calling analytics or queries;
+   - loading, empty and error states (`HawkApiError.code`), no page heading (the host shows the app's name);
+   - dialogs in the page (never `window.confirm`/`alert`), placed in the visible part of the frame;
+   - accessible: labelled fields, `alt` on images, one `<main>`, headings in order.
+5. **A view** (a preview card or an embeddable slot) is a route declared in `views` in `hawk-app.json`: keep it small,
+   read stored results, transparent background, height from the content. See the Views section of `AGENTS.md`.
+   **Opened from HawkSearch's own pages** (a button by a search term in a report, on an AI Advisor insight…), it's an
+   `actions` entry: the view, and `targets` per host (a regex on the page path, CSS selectors, how each param is read;
+   the bridge README's **Actions**). The view reads `app.context.view.params`, handles them missing, and calls
+   `app.action.done({ changed: true })` when the work is saved. Try it with `npm run app:dev`'s Action menu.
+6. **Check it.** Run the hawk-apps `validate` tool (with `build: true` when the build setup changed) and fix what it
+   says. Offer `npm run app:dev` to see it locally. Deploy only when the user asks.