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

package/README.md

@@ -68,7 +68,7 @@ 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);
+  "scopes": ["reports:read"]           // reports:read = analytics; hawksearch:read = dashboard API (read) and preview tools;
                                        // 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");
@@ -79,6 +79,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;
@@ -338,14 +340,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`)
 
@@ -369,17 +397,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 +420,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
 

package/agents/AGENTS.md

@@ -52,7 +52,9 @@ app.onContextChange(render); // the user switched client, engine or dates
 | `app.analytics.report('queries', { limit, startDate, endDate, filters })` | `reports:read` |
 | `app.dashboard.get('Synonym')`: HawkSearch dashboard API, no API version in the path | `hawksearch:read` |
 | `app.dashboard.post/put/delete(path, body)`: merchandising and relevancy resources only, never retried | `hawksearch:write` |
-| `app.hawksearch.search(...)`, `app.hawksearch.autocomplete(...)` on the user's engine | `hawksearch:search` |
+| `app.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.email.send(...)` | `email:send` |
@@ -92,8 +94,10 @@ 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),
@@ -106,7 +110,7 @@ isn't approved, only Bridgeline staff in it see the app. Only approvers change w
 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
 

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,34 @@
+---
+name: add-function
+description: Add or change a server-side function (functions/<name>.ts, AWS Lambda), a background job or a schedule in a Hawk App. Use when the app needs server code, a third-party API with a secret key, work longer than a page should wait, or something on a timer.
+---
+
+# 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)`.
+5. **Call it** from the app with `app.functions.call('<name>', input)` and handle `function_failed`,
+   `function_timeout`, `secret_missing` and `functions_not_enabled`.
+6. **Check it.** Run `validate`. Functions run only from a **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,32 @@
+---
+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`.
+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.

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

@@ -0,0 +1,32 @@
+---
+name: prepare-review
+description: Get a Hawk App ready to submit for approval in HawkSearch - run the approvers' automated checks (bundle, dependencies, accessibility, outside origins, queries, functions, scopes), fix what fails and say what's left. Use before submitting, after a big change, or when the user asks whether the app will pass review.
+---
+
+# Prepare for review
+
+Approvers see automated checks in HawkSearch's approve dialog; a failed one forces them to override it. Get every check
+green, or explain to the user why one can't be.
+
+1. **Validate with the build.** Run the hawk-apps `validate` tool with `build: true`. Fix what it reports in the code;
+   ask the user before changing `scopes` or `externalOrigins` in `hawk-app.json`.
+2. **The review checklist** (fix or explain each):
+   - **Bundle:** under 20 MB in total, no file over 5 MB, not 50% (and 1 MB) bigger than the released version.
+   - **Dependencies:** no high or critical findings in `npm run app:audit` (production dependencies).
+   - **Accessibility:** no critical axe issues (`validate --build` lists them): labels, `alt`, one `<main>`, headings
+     in order.
+   - **Outside origins:** `externalOrigins` lists each https origin the app calls or loads from; `["*"]` fails
+     (`"img:*"` is fine for images).
+   - **Scopes:** each one is used by the code, and every bridge call's scope is there (`validate` warns about missing
+     ones). Fewer is better: elevated scopes (`data:read`, `functions:invoke`, `hawksearch:write`, `ai:invoke`, …) are
+     never auto-approved.
+   - **Queries:** each has `{{partitions(...)}}`, names its columns and has a `LIMIT` on lists.
+   - **Functions and external Lambdas:** shown to the approver with their code and settings; Engineering must have
+     enabled functions.
+   - **No secrets** anywhere in the app or the build.
+3. **What approvers will see.** Run `status`: the review checks on the newest version, and `deploy` with
+   `dryRun: true`: what `hawk-app.json` would change. If the newest version is older than the code, say so: the user
+   decides when to deploy.
+4. **Errors.** Run `errors` and fix what the deployed versions threw, the most frequent first.
+5. **Finish** with a short list: ready to submit (open the app with `npx hawk-app open` and click **Submit for
+   approval**), or what's left. Never deploy to prod or submit for the user.

package/docs/bridge/README.md

@@ -265,7 +265,8 @@ Any resource of the [HawkSearch Dashboard API](https://developerdocs.hawksearch.
 `Synonym`, `LandingPage`, `Field`, …. Leave the API version out; the platform picks it. Responses are HawkSearch's
 body as is. To change data, see [Writing to HawkSearch](#writing-to-hawksearch-hawksearchwrite). For reporting, use
 analytics. Your assistant can look up any operation's fields, its bridge call and scope with the `hawk-apps` MCP
-server's `hawksearch_api` tool.
+server's `hawksearch_api` tool. The same scope gives the preview page's tools (`app.hawksearch.preview`: visitor targets,
+indexes, item details, keyword explain): see [Preview like HawkSearch's preview page](#preview-like-hawksearchs-preview-page).
 
 ### Writing to HawkSearch: `hawksearch:write`
 
@@ -489,7 +490,7 @@ what `handler` returned (up to 6 MB). It waits up to `timeoutMs` (default 30 s)
 | `ctx.app.slug`, `ctx.version` | Your app and the version the caller has open (the function code is that version's). |
 | `ctx.secrets.NAME` | The secrets the function declares in `hawk-app.json` (see below). Nothing else. |
 | `ctx.config` | The app's [config](#app-config) for the caller's client and this version, already resolved: `{ key: value }` for every declared key (null when nothing is set and there's no default). Frozen. |
-| `ctx.platform` | The platform API **as the caller**: `analytics.report`, `dashboard.get/post/put/delete`, `data.query` (polled for you), [`email.send`](#email-emailsend), [`hawksearch.search/autocomplete`](#hawksearch-search-hawksearchsearch), [`hawksearch.systemParameters`](#hawksearch-system-parameters-hawksearchsysparamswrite), [`functions.start/job/wait`](#background-jobs), [`ai.generate/stream/info`](#ai-aiinvoke) and `api.get/post`, with your app's scopes. Analytics dates don't default on the server: pass them. |
+| `ctx.platform` | The platform API **as the caller**: `analytics.report`, `dashboard.get/post/put/delete`, `data.query` (polled for you), [`email.send`](#email-emailsend), [`hawksearch.search/autocomplete`](#hawksearch-search-hawksearchsearch), [`hawksearch.preview`](#preview-like-hawksearchs-preview-page), [`hawkai`](#hawkai-agents-and-smart-responses-hawkairead), [`hawksearch.systemParameters`](#hawksearch-system-parameters-hawksearchsysparamswrite), [`functions.start/job/wait`](#background-jobs), [`ai.generate/stream/info`](#ai-aiinvoke) and `api.get/post`, with your app's scopes. Analytics dates don't default on the server: pass them. |
 | `ctx.job`, `ctx.trigger` | For a [background job](#background-jobs): `{ id, progress(percent?, message?) }` (null for a call), and what started the run (`call` or `schedule`). |
 | `ctx.aws` | Only with `data:read`: short-lived credentials scoped to this client's analytics data, plus `region`, `database`, `workGroup`, `outputLocation`, for the AWS SDK's Athena client. Prefer `ctx.platform.data.query` when an app query does the job. |
 
@@ -713,6 +714,71 @@ await app.hawksearch.autocomplete({ Keyword: 'boo', ProductCount: 5 });
 
 Other HawkSearch errors (e.g. `400` for an unknown `IndexName`) come back as HawkSearch sent them.
 
+### Preview like HawkSearch's preview page
+
+A preview search takes everything the preview page sets: `IsInPreview: true`, `SmartBar` (`PreviewDate` and switches
+such as `BoostAndBury: false`, `ItemPin: false`), `ClientData: { PreviewBuckets: [ids] }` for visitor targets,
+`IndexName`, `Is100CoverageTurnedOn`, and `ExplainDocId` to explain one result's score (`DocExplain` in the answer). The page's own pickers and explain panel are `app.hawksearch.preview` (scope **`hawksearch:read`**,
+within the same per-minute limit):
+
+```ts
+const settings = await app.hawksearch.preview.settings();        // visitor targets, fields, layouts
+const { ClientIndexes, CurrentIndex } = await app.hawksearch.preview.indexes();
+const item = await app.hawksearch.preview.item('SKU-123');       // one item as indexed ({ indexName } optional)
+const why = await app.hawksearch.preview.explain({ Keyword: 'jackets', IsInPreview: true });
+why.AdjustedKeyword; why.AppliedKeywordReplacementRules; why.ElasticQuery;
+```
+
+`explain` needs the session's site API key (`403 preview_needs_site_key` with a group key). Pinning from an app isn't
+available yet.
+
+## HawkAI agents and smart responses: `hawkai:read`
+
+The client's HawkAI agents and smart responses for the user's current engine, as Spark lists them: names and settings,
+never prompts. From the app or a function (`ctx.platform.hawkai`).
+
+```ts
+const agents = await app.hawkai.agents();            // by name
+const responses = await app.hawkai.smartResponses(); // with maxItems and allowRequestOverride
+const one = await app.hawkai.smartResponse(responses[0].id);
+```
+
+Each is `{ id, name, description, model, allEngines, maxItems, allowRequestOverride }` (`allEngines`: set up for every
+engine of the client).
+
+**Run a smart response** for a query and a search, live or in preview, as the storefront does. The platform adds the
+client, the engine's ClientGuid and its search API; HawkAI runs the search and picks the items:
+
+```ts
+const answer = await app.hawkai.runSmartResponse(id, {
+    query: 'waterproof jacket',
+    search: { Keyword: 'jacket', IsInPreview: true, SmartBar: { PreviewDate: '2026-11-27T00:00:00' } },
+});
+answer.recommendation; // Markdown
+answer.Results;        // [{ DocId, Document, reason }]
+```
+
+Answered whole (not streamed), within the search limit. **An assistant** runs in HawkAI's widget
+([`@bridgeline-digital/hawkai-assistant`](https://www.npmjs.com/package/@bridgeline-digital/hawkai-assistant)), which
+talks to HawkAI from the browser: `app.hawkai.assistant(agentId)` gives it `{ apiUrl, accountId, agentId }`.
+
+```ts
+HawkAI.Assistant.initialize({ ...(await app.hawkai.assistant(agentId)), ui: { display: 'embedded', embedHostSelector: '#assistant' } });
+```
+
+List HawkAI's origin in `externalOrigins` (`https://assistant-dev.hawksearch.net` on dev, `https://assistant.hawksearch.net`
+on prod). The widget initializes once per page: reload to switch agents.
+
+| `error.code` | Status | Meaning |
+|---|---|---|
+| `scope_missing` | 403 | Add `hawkai:read` to `scopes`. |
+| `engine_required` | 400 | The host session has no engine. |
+| `hawkai_not_found` | 404 | No agent / smart response with that id for this client and engine. |
+| `hawkai_unavailable` | 502 | HawkAI's configuration couldn't be read, or HawkAI didn't answer in time: try again. |
+| `hawkai_error` | 502 | HawkAI answered without a smart response (its reason is in the message). |
+| `hawkai_limit_reached` | 429 | HawkAI's own limit for the client (tokens or rate). |
+| `too_many_requests` | 429 | Over the search limit (smart responses count as searches); wait `retryAfterMs`. |
+
 ## HawkSearch system parameters: `hawksearch:sysparams:write`
 
 Let users change a few HawkSearch **system parameters** of the engine they are working on (Sites → System Parameters
@@ -1264,7 +1330,7 @@ Which clients have the app is not in this file: manage them in the Hawk Analytic
 | `hosting` | `static` (the default): built files on the apps CDN. `server` is reserved for server-rendered apps and not accepted yet. |
 | `visibility` | `allowList` (only the clients given the app), `all` (every client except excluded ones), or `internal` (Bridgeline staff). The clients themselves are managed in the Hawk Analytics portal or with `npx hawk-app clients add`/`exclude`/`remove`; a `hawk-app.json` with `clients` or `excludeClients` is refused. |
 | `listed` | `true` (the default) shows the app on the host's Apps page. `false` leaves it off that list, and the host hides its own title and back button for it, but it still opens by its direct URL (e.g. linked from another app or page). It doesn't change who can open it: `visibility` and the app's clients still apply. |
-| `scopes` | `reports:read` for analytics, `hawksearch:read` for the dashboard API, `hawksearch:write` to [write to it](#writing-to-hawksearch-hawksearchwrite), `data:read` for [custom queries](#custom-data-queries-dataread), `functions:invoke` for [functions](#functions-functionsinvoke), `email:send` for [email](#email-emailsend), `hawksearch:sysparams:write` for [system parameters](#hawksearch-system-parameters-hawksearchsysparamswrite), `hawksearch:search` for [search](#hawksearch-search-hawksearchsearch), `hawksearch:features:write` for [features](#hawksearch-features-hawksearchfeatureswrite), `hawksearch:index` for [index rebuilds](#hawksearch-index-rebuilds-hawksearchindex), `hawksearch:index:items` and `hawksearch:index:manage` for [the Indexing API](#the-indexing-api-hawksearchindex-indexitems-indexmanage), `hawksearch:recommendations` for [recommendations](#hawksearch-recommendations-hawksearchrecommendations), `storage` for [storage](#storage-storage), `lambdas:invoke` for [external Lambdas](#external-lambdas-lambdasinvoke), `ai:invoke` for [AI](#ai-aiinvoke), `assistant` to [ask the host's assistant](#ask-the-hosts-assistant-assistant). |
+| `scopes` | `reports:read` for analytics, `hawksearch:read` for the dashboard API, `hawksearch:write` to [write to it](#writing-to-hawksearch-hawksearchwrite), `data:read` for [custom queries](#custom-data-queries-dataread), `functions:invoke` for [functions](#functions-functionsinvoke), `email:send` for [email](#email-emailsend), `hawksearch:sysparams:write` for [system parameters](#hawksearch-system-parameters-hawksearchsysparamswrite), `hawksearch:search` for [search](#hawksearch-search-hawksearchsearch), `hawksearch:features:write` for [features](#hawksearch-features-hawksearchfeatureswrite), `hawksearch:index` for [index rebuilds](#hawksearch-index-rebuilds-hawksearchindex), `hawksearch:index:items` and `hawksearch:index:manage` for [the Indexing API](#the-indexing-api-hawksearchindex-indexitems-indexmanage), `hawksearch:recommendations` for [recommendations](#hawksearch-recommendations-hawksearchrecommendations), `hawkai:read` for [HawkAI](#hawkai-agents-and-smart-responses-hawkairead), `storage` for [storage](#storage-storage), `lambdas:invoke` for [external Lambdas](#external-lambdas-lambdasinvoke), `ai:invoke` for [AI](#ai-aiinvoke), `assistant` to [ask the host's assistant](#ask-the-hosts-assistant-assistant). |
 | `functions` | Your [functions](#functions-functionsinvoke) and their settings: `{ "<name>": { "job", "timeoutSeconds", "memoryMb", "secrets" } }`. Recorded with each version. |
 | `schedules` | [Schedules](#schedules) for job functions: `{ "<name>": { "function", "cron", "timezone" } }`, at most 5, at most hourly. Needs `functions:invoke`. Reviewed like scopes. |
 | `systemParameters` | The HawkSearch [system parameters](#hawksearch-system-parameters-hawksearchsysparamswrite) the app may read and set, e.g. `["Timezone"]`. Needs `hawksearch:sysparams:write`. Reviewed like scopes. |

package/docs/showcase/hawk-app.json

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

package/docs/showcase/src/App.tsx

@@ -6,6 +6,7 @@ import {
     type AiResult,
     type AppSchedule,
     type FunctionJob,
+    type HawkAiConfig,
     type HawkApp,
     type HawkAppContext,
     type IndexItemsResult,
@@ -24,7 +25,7 @@ import { useHawkApp } from './useHawkApp';
  * Internal test app for the Hawk Apps platform. One tab per feature; every call shows its outcome, timing and error
  * code, so a failing platform change is easy to spot. Not a product: keep it small and keep it working.
  */
-const TABS = ['Context', 'Analytics', 'Dashboard', 'Search', 'Recommendations', 'Index', 'Storage', 'Config', 'Queries', 'Functions', 'Jobs', 'System parameters', 'AI', 'Host'] as const;
+const TABS = ['Context', 'Analytics', 'Dashboard', 'Search', 'Preview', 'HawkAI', 'Recommendations', 'Index', 'Storage', 'Config', 'Queries', 'Functions', 'Jobs', 'System parameters', 'AI', 'Host'] as const;
 type Tab = (typeof TABS)[number];
 
 export function App() {
@@ -48,6 +49,8 @@ export function App() {
             {tab === 'Analytics' && <AnalyticsTab app={hawk.app} context={hawk.context} />}
             {tab === 'Dashboard' && <DashboardTab app={hawk.app} />}
             {tab === 'Search' && <SearchTab app={hawk.app} context={hawk.context} />}
+            {tab === 'Preview' && <PreviewTab app={hawk.app} />}
+            {tab === 'HawkAI' && <HawkAiTab app={hawk.app} />}
             {tab === 'Recommendations' && <RecommendationsTab app={hawk.app} />}
             {tab === 'Index' && <IndexTab app={hawk.app} />}
             {tab === 'Storage' && <StorageTab app={hawk.app} />}
@@ -1408,6 +1411,237 @@ function RecommendationsTab({ app }: { app: HawkApp }) {
     );
 }
 
+/** The preview page's tools (hawksearch:read) and a preview search with what they return (hawksearch:search). */
+function PreviewTab({ app }: { app: HawkApp }) {
+    const [outcomes, setOutcomes] = useState<Outcome[]>([]);
+    const [busy, setBusy] = useState(false);
+    const [keyword, setKeyword] = useState('jacket');
+    const [itemId, setItemId] = useState('');
+    const [buckets, setBuckets] = useState('');
+    const [indexName, setIndexName] = useState('');
+
+    const go = async (runs: () => Promise<Outcome[]>) => {
+        setBusy(true);
+        setOutcomes(await runs());
+        setBusy(false);
+    };
+
+    const tools = async () => [
+        await measure('hawksearch.preview.settings()', async () => {
+            const settings = await app.hawksearch.preview.settings();
+            return { summary: `fields: ${Object.keys(settings).join(', ') || 'none'}`, detail: settings };
+        }),
+        await measure('hawksearch.preview.indexes()', async () => {
+            const indexes = await app.hawksearch.preview.indexes();
+            if (typeof indexes.CurrentIndex === 'string' && !indexName) setIndexName(indexes.CurrentIndex);
+            return { summary: `current: ${String(indexes.CurrentIndex ?? 'none')}`, detail: indexes };
+        }),
+        await measure(`hawksearch.preview.explain({ Keyword: ${JSON.stringify(keyword)}, IsInPreview: true })`, async () => {
+            const why = await app.hawksearch.preview.explain({ Keyword: keyword, IsInPreview: true });
+            return { summary: `adjusted keyword: ${why.AdjustedKeyword ?? keyword}`, detail: why };
+        }),
+    ];
+
+    // As the preview page searches: preview rules, the chosen visitor targets and index, and one result explained.
+    const previewSearch = () => {
+        const previewBuckets = buckets.split(',').map((b) => Number(b.trim())).filter((b) => Number.isInteger(b) && b > 0);
+        const request: SearchRequest = {
+            Keyword: keyword,
+            IsInPreview: true,
+            ...(indexName ? { IndexName: indexName } : {}),
+            ...(previewBuckets.length ? { ClientData: { PreviewBuckets: previewBuckets } } : {}),
+            ...(itemId.trim() ? { ExplainDocId: itemId.trim() } : {}),
+        };
+        return measure(`hawksearch.search(${JSON.stringify(request)})`, async () => searchSummary(await app.hawksearch.search(request)));
+    };
+
+    return (
+        <Card title="Preview (hawksearch:read, hawksearch:search)">
+            <p className="muted">
+                The preview page's tools for this engine, and a preview search with what they give: visitor targets (ids from the settings),
+                the index, and one result's explain.
+            </p>
+            <div className="buttons">
+                <label>
+                    Keyword <input value={keyword} onChange={(e) => setKeyword(e.target.value)} />
+                </label>
+                <label>
+                    Visitor target ids <input value={buckets} onChange={(e) => setBuckets(e.target.value)} placeholder="e.g. 12, 14" />
+                </label>
+                <label>
+                    Index <input value={indexName} onChange={(e) => setIndexName(e.target.value)} placeholder="blank: current" />
+                </label>
+                <label>
+                    Item id <input value={itemId} onChange={(e) => setItemId(e.target.value)} placeholder="item details, explain" />
+                </label>
+            </div>
+            <div className="buttons">
+                <button disabled={busy} onClick={() => go(tools)}>
+                    Settings, indexes, keyword explain
+                </button>
+                <button
+                    disabled={busy || !itemId.trim()}
+                    onClick={() =>
+                        go(async () => [
+                            await measure(`hawksearch.preview.item(${JSON.stringify(itemId.trim())})`, async () => {
+                                const item = await app.hawksearch.preview.item(itemId.trim(), indexName ? { indexName } : {});
+                                return { summary: 'found', detail: item };
+                            }),
+                        ])
+                    }
+                >
+                    Item details
+                </button>
+                <button disabled={busy} onClick={() => go(async () => [await previewSearch()])}>
+                    Preview search
+                </button>
+            </div>
+            <Results outcomes={outcomes} />
+        </Card>
+    );
+}
+
+/** Where HawkAI's assistant widget (@bridgeline-digital/hawkai-assistant) comes from: its one-file build, pinned. */
+const HAWKAI_ASSISTANT_SCRIPT = 'https://cdn.jsdelivr.net/npm/@bridgeline-digital/hawkai-assistant@1.1.0/dist/hawkai-assistant.js';
+
+declare global {
+    interface Window {
+        HawkAI?: { Assistant?: { initialize(config: Record<string, unknown>): Promise<void> } };
+    }
+}
+
+/** Loads the widget's script once. */
+function loadAssistantScript(): Promise<void> {
+    if (window.HawkAI?.Assistant) return Promise.resolve();
+    return new Promise((resolve, reject) => {
+        const script = document.createElement('script');
+        script.src = HAWKAI_ASSISTANT_SCRIPT;
+        script.onload = () => resolve();
+        script.onerror = () => reject(new Error(`could not load ${HAWKAI_ASSISTANT_SCRIPT} (is it in externalOrigins?)`));
+        document.head.appendChild(script);
+    });
+}
+
+/** HawkAI (hawkai:read): pick a smart response and run it on a preview search; pick an agent and open it in HawkAI's widget. */
+function HawkAiTab({ app }: { app: HawkApp }) {
+    const [outcomes, setOutcomes] = useState<Outcome[]>([]);
+    const [busy, setBusy] = useState(false);
+    const [smartResponses, setSmartResponses] = useState<HawkAiConfig[]>([]);
+    const [agents, setAgents] = useState<HawkAiConfig[]>([]);
+    const [smartResponseId, setSmartResponseId] = useState('');
+    const [agentId, setAgentId] = useState('');
+    const [query, setQuery] = useState('a warm waterproof jacket');
+    const [preview, setPreview] = useState(true);
+    const [answer, setAnswer] = useState('');
+    // The widget initializes once per page: the agent it was opened with.
+    const [openedAgent, setOpenedAgent] = useState('');
+
+    const go = async (runs: () => Promise<Outcome[]>) => {
+        setBusy(true);
+        setOutcomes(await runs());
+        setBusy(false);
+    };
+
+    const load = async () => [
+        await measure('hawkai.smartResponses()', async () => {
+            const list = await app.hawkai.smartResponses();
+            setSmartResponses(list);
+            setSmartResponseId((current) => current || list[0]?.id || '');
+            return { summary: `${list.length} smart responses`, detail: list };
+        }),
+        await measure('hawkai.agents()', async () => {
+            const list = await app.hawkai.agents();
+            setAgents(list);
+            setAgentId((current) => current || list[0]?.id || '');
+            return { summary: `${list.length} agents`, detail: list };
+        }),
+    ];
+
+    const run = async () => [
+        await measure(`hawkai.runSmartResponse(${JSON.stringify(smartResponseId)}, { query, search${preview ? ': IsInPreview' : ''} })`, async () => {
+            setAnswer('');
+            const result = await app.hawkai.runSmartResponse(smartResponseId, { query, search: { Keyword: query, IsInPreview: preview } });
+            setAnswer(result.recommendation ?? '');
+            return { summary: `${result.Results?.length ?? 0} items, ${result.usage?.totalTokens ?? '?'} tokens`, detail: result };
+        }),
+    ];
+
+    const openAssistant = async () => [
+        await measure(`hawkai.assistant(${JSON.stringify(agentId)}) + HawkAI.Assistant.initialize`, async () => {
+            const config = await app.hawkai.assistant(agentId);
+            await loadAssistantScript();
+            await window.HawkAI!.Assistant!.initialize({ ...config, ui: { display: 'embedded', embedHostSelector: '#showcase-assistant', open: true } });
+            setOpenedAgent(agentId);
+            return { summary: `${config.apiUrl}, account ${config.accountId}`, detail: config };
+        }),
+    ];
+
+    const name = (list: HawkAiConfig[], id: string) => list.find((c) => c.id === id)?.name ?? id;
+
+    return (
+        <>
+            <Card title="Smart response (hawkai:read)">
+                <p className="muted">
+                    Pick one of the client's smart responses for this engine and run it: HawkAI runs the search itself (the preview search API with
+                    IsInPreview); the platform adds the client, ClientGuid and search API.
+                </p>
+                <div className="buttons">
+                    <button disabled={busy} onClick={() => go(load)}>
+                        Load smart responses and agents
+                    </button>
+                </div>
+                <div className="buttons">
+                    <label>
+                        Smart response{' '}
+                        <select value={smartResponseId} onChange={(e) => setSmartResponseId(e.target.value)}>
+                            {smartResponses.map((c) => (
+                                <option key={c.id} value={c.id}>
+                                    {c.name}
+                                    {c.allEngines ? ' (all engines)' : ''}
+                                </option>
+                            ))}
+                        </select>
+                    </label>
+                    <label>
+                        Query <input value={query} onChange={(e) => setQuery(e.target.value)} />
+                    </label>
+                    <label>
+                        <input type="checkbox" checked={preview} onChange={(e) => setPreview(e.target.checked)} /> Preview
+                    </label>
+                    <button disabled={busy || !smartResponseId || !query.trim()} onClick={() => go(run)}>
+                        Run
+                    </button>
+                </div>
+                {answer && <pre>{answer}</pre>}
+            </Card>
+            <Card title="Assistant (hawkai:read + HawkAI's widget)">
+                <p className="muted">
+                    Opens an agent in HawkAI's assistant widget, which talks to HawkAI from the browser (its origin is in externalOrigins). The widget
+                    starts once per page: reload the app to switch agents.
+                </p>
+                <div className="buttons">
+                    <label>
+                        Agent{' '}
+                        <select value={agentId} onChange={(e) => setAgentId(e.target.value)} disabled={!!openedAgent}>
+                            {agents.map((c) => (
+                                <option key={c.id} value={c.id}>
+                                    {c.name}
+                                </option>
+                            ))}
+                        </select>
+                    </label>
+                    <button disabled={busy || !agentId || !!openedAgent} onClick={() => go(openAssistant)}>
+                        Open assistant
+                    </button>
+                    {openedAgent && <span className="muted">Open: {name(agents, openedAgent)}. Reload to switch.</span>}
+                </div>
+                <div id="showcase-assistant" style={{ height: openedAgent ? 520 : 0 }} />
+            </Card>
+            <Results outcomes={outcomes} />
+        </>
+    );
+}
+
 function HostTab({ app }: { app: HawkApp }) {
     const [outcomes, setOutcomes] = useState<Outcome[]>([]);
     const [tall, setTall] = useState(false);

package/docs/ui/README.md

@@ -91,9 +91,9 @@ see it in a real one). `<HawkAppProvider preview={{ mode: 'dark' }}>` renders wi
 | Part | From |
 |---|---|
 | Typography (Montserrat, 14 px base, h1–h3, `featuredValue`), breakpoints (`sm` 640 … `2xl` 1536), spacing, card and list overrides | Spark's theme (`sparkThemeOptions`) |
-| Primary color and its text, backgrounds, text colors, dividers, border radius, light or dark | The host's theme tokens (`color-button-accent-background`, `color-background`, `color-background-container`, `color-text-default`, `color-text-secondary`, `color-border-default`, `border-radius`, `mode`), else Spark's |
+| Primary color and its text, backgrounds, text colors, dividers, border radius, light or dark | The host's theme tokens (`color-button-accent-background`, `color-background`, `color-background-container`, `color-text-default`, `color-text-secondary`, `color-border-default`, `border-radius`, `mode`), else Spark's. A `color-border-default` too faint to see on the host's surface (contrast under 1.2, such as HawkSearch's `#f5f7fa` on white) is left out, so dividers, table rows and outlined cards keep MUI's divider |
 | Dialogs and snackbars in the part of the frame the user can see | The kit (`frameThemeOptions`, from the bridge's `--hawk-visible-*` variables) |
-| Table rows and header (borders in the divider color, a header row on the page background) | The kit (`tableThemeOptions`) |
+| Table rows and header (borders in the divider color, a header row on the page background, rows 10px above and below, every other body row tinted; the stylesheet's `.hawk-table` alike) | The kit (`tableThemeOptions`) |
 
 The font is always Spark's, whatever the host uses, so apps look the same in HawkSearch and Spark.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bridgeline-digital/hawk-app-cli",
-  "version": "0.1.0",
+  "version": "0.1.1-dev.20261021204606",
   "description": "For Bridgeline developers: create, deploy and register Hawk Apps (Services-built tools embedded in HawkSearch). Requires a Hawk Apps publisher key.",
   "author": "Bridgeline Digital",
   "license": "UNLICENSED",
@@ -17,6 +17,7 @@
   "files": [
     "agents",
     "bin",
+    "claude-plugin",
     "docs",
     "src",
     "schema",

package/schema/hawk-app.schema.json

@@ -99,7 +99,7 @@
       "default": "static"
     },
     "scopes": {
-      "description": "Data the app needs. reports:read (HawkSearch Analytics reports), hawksearch:read (read the HawkSearch dashboard API), hawksearch:write (create, update and delete in the HawkSearch dashboard API: banners, boost/bury, campaigns, visibility, visitor targets, redirects, synonyms, spellcheck, pagination and sorting sets, recommendation visibility, landing page layouts, facets and landing pages; site API keys only, limited per app and client per minute, every write audit-logged), data:read (the app's own SQL queries in queries/, run against the current client's analytics data), functions:invoke (the app's own server-side functions in functions/, see \"functions\"), email:send (send email from noreply@hawksearch.com with the app's name, from the app or its functions; sends are limited per app and client per day), hawksearch:sysparams:write (read and set the HawkSearch system parameters listed in \"systemParameters\" for the user's current engine), hawksearch:search (HawkSearch search and autocomplete for the user's current engine, live or in preview; limited per app and client per minute), ai:invoke (Claude through the platform, tiers fast and smart, from the app or its functions; a daily token budget per tier and requests per minute per app and client; an app with it is never auto-approved), lambdas:invoke (call the Lambdas outside Hawk Apps listed in \"lambdas\" that the platform allows, with app.lambdas.invoke; an app with it is never auto-approved) and hawksearch:features:write (turn HawkSearch features on and off for the user's current engine, additional and facet features, one code at a time with app.hawksearch.features; any feature, including paid add-ons, so an app with it is never auto-approved), hawksearch:index (rebuild the user's engine's index from its feed and follow the rebuild with app.hawksearch.index, only where the engine's EnableRebuildIndex system parameter is on, one rebuild at a time per engine, and read the engine's indexes, current index, hierarchy and mappings through HawkSearch's Indexing API; never auto-approved), hawksearch:index:items (add, update and delete items and their attributes in the engine's indexes through the Indexing API, live at once on the current index; at most 125 items a call; never auto-approved), hawksearch:index:manage (create indexes, set the current one, delete others, rebuild autocomplete and the rest, hierarchy and facet mappings through the Indexing API; never auto-approved), hawksearch:recommendations (HawkSearch's recommendation widgets for the user's current engine with app.hawksearch.recommendations, never tracked in the client's recommendation reports; limited per app and client per minute), storage (the app's own key-value data and files kept by the platform with app.storage and app.storage.files, per app and client, within quotas; shared by everyone at the client and the app's functions and schedules) and assistant (ask the host's assistant, Hawk Assistant in HawkSearch, as the user with app.assistant.ask, from a click; the user sees the question and the answer in the assistant's chat; show the buttons only while context.features.assistant is true).",
+      "description": "Data the app needs. reports:read (HawkSearch Analytics reports), hawksearch:read (read the HawkSearch dashboard API), hawksearch:write (create, update and delete in the HawkSearch dashboard API: banners, boost/bury, campaigns, visibility, visitor targets, redirects, synonyms, spellcheck, pagination and sorting sets, recommendation visibility, landing page layouts, facets and landing pages; site API keys only, limited per app and client per minute, every write audit-logged), data:read (the app's own SQL queries in queries/, run against the current client's analytics data), functions:invoke (the app's own server-side functions in functions/, see \"functions\"), email:send (send email from noreply@hawksearch.com with the app's name, from the app or its functions; sends are limited per app and client per day), hawksearch:sysparams:write (read and set the HawkSearch system parameters listed in \"systemParameters\" for the user's current engine), hawksearch:search (HawkSearch search and autocomplete for the user's current engine, live or in preview; limited per app and client per minute), ai:invoke (Claude through the platform, tiers fast and smart, from the app or its functions; a daily token budget per tier and requests per minute per app and client; an app with it is never auto-approved), lambdas:invoke (call the Lambdas outside Hawk Apps listed in \"lambdas\" that the platform allows, with app.lambdas.invoke; an app with it is never auto-approved) and hawksearch:features:write (turn HawkSearch features on and off for the user's current engine, additional and facet features, one code at a time with app.hawksearch.features; any feature, including paid add-ons, so an app with it is never auto-approved), hawksearch:index (rebuild the user's engine's index from its feed and follow the rebuild with app.hawksearch.index, only where the engine's EnableRebuildIndex system parameter is on, one rebuild at a time per engine, and read the engine's indexes, current index, hierarchy and mappings through HawkSearch's Indexing API; never auto-approved), hawksearch:index:items (add, update and delete items and their attributes in the engine's indexes through the Indexing API, live at once on the current index; at most 125 items a call; never auto-approved), hawksearch:index:manage (create indexes, set the current one, delete others, rebuild autocomplete and the rest, hierarchy and facet mappings through the Indexing API; never auto-approved), hawksearch:recommendations (HawkSearch's recommendation widgets for the user's current engine with app.hawksearch.recommendations, never tracked in the client's recommendation reports; limited per app and client per minute), storage (the app's own key-value data and files kept by the platform with app.storage and app.storage.files, per app and client, within quotas; shared by everyone at the client and the app's functions and schedules) and assistant (ask the host's assistant, Hawk Assistant in HawkSearch, as the user with app.assistant.ask, from a click; the user sees the question and the answer in the assistant's chat; show the buttons only while context.features.assistant is true) and hawkai:read (list the client's HawkAI agents and smart responses for the user's current engine with app.hawkai: names and settings, never prompts).",
       "type": "array",
       "items": {
         "enum": [
@@ -119,7 +119,8 @@
           "hawksearch:index:manage",
           "hawksearch:recommendations",
           "storage",
-          "assistant"
+          "assistant",
+          "hawkai:read"
         ]
       },
       "uniqueItems": true

package/src/agents.mjs

@@ -1,10 +1,12 @@
 // Instructions for AI coding assistants, written into each app: AGENTS.md (read by Copilot, Cursor, Codex and others),
-// a CLAUDE.md that imports it (Claude Code), and the CLI's MCP server (`hawk-app mcp`) in .mcp.json (Claude Code) and
-// .vscode/mcp.json (VS Code / Copilot). The CLI owns the part of AGENTS.md between its markers and refreshes
-// it with `hawk-app upgrade`; anything outside the markers is the developer's. Sources: ../agents/AGENTS.md plus one
-// project section per template (../agents/project/), or custom.md for an app set up with `hawk-app init`.
+// a CLAUDE.md that imports it (Claude Code), and the CLI's MCP server (`hawk-app mcp`) in .vscode/mcp.json (VS Code /
+// Copilot). Claude Code gets the server from the Hawk Apps plugin (plugins/hawk-apps), installed once per machine, so
+// the CLI no longer writes .mcp.json and takes its old `hawk-apps` entry out (the plugin's would show every tool twice).
+// The CLI owns the part of AGENTS.md between its markers and refreshes it with `hawk-app upgrade`; anything outside
+// the markers is the developer's. Sources: ../agents/AGENTS.md plus one project section per template
+// (../agents/project/), or custom.md for an app set up with `hawk-app init`.
 import { existsSync, readFileSync } from 'node:fs';
-import { mkdir, writeFile } from 'node:fs/promises';
+import { mkdir, rm, writeFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -20,7 +22,6 @@ const CLAUDE_IMPORT = '@AGENTS.md';
  */
 const CLI_BIN = 'node_modules/@bridgeline-digital/hawk-app-cli/bin/hawk-app.mjs';
 const MCP_CONFIGS = [
-    { file: '.mcp.json', key: 'mcpServers', entry: { command: 'node', args: [CLI_BIN, 'mcp'] } },
     {
         file: '.vscode/mcp.json',
         key: 'servers',
@@ -28,6 +29,27 @@ const MCP_CONFIGS = [
     },
 ];
 const MCP_SERVER = 'hawk-apps';
+/** Claude Code's project MCP settings: the plugin starts the server now, so the CLI's old entry comes out. */
+const CLAUDE_MCP = '.mcp.json';
+
+/** .mcp.json without the CLI's old `hawk-apps` server: 'remove' (other settings kept), 'delete' (nothing else), or 'current'. */
+function planClaudeMcpCleanup(dir) {
+    const full = join(dir, CLAUDE_MCP);
+    if (!existsSync(full)) return null;
+    const text = readFileSync(full, 'utf8');
+    let config;
+    try {
+        config = JSON.parse(text);
+    } catch {
+        return { file: CLAUDE_MCP, state: 'current', content: text };
+    }
+    if (!config?.mcpServers?.[MCP_SERVER]) return { file: CLAUDE_MCP, state: 'current', content: text };
+    const { [MCP_SERVER]: _ours, ...servers } = config.mcpServers;
+    const updated = { ...config, mcpServers: servers };
+    if (Object.keys(servers).length === 0) delete updated.mcpServers;
+    if (Object.keys(updated).length === 0) return { file: CLAUDE_MCP, state: 'delete', content: '' };
+    return { file: CLAUDE_MCP, state: 'remove', content: JSON.stringify(updated, null, 2) + (text.includes('\r\n') ? '\r\n' : '\n') };
+}
 
 /** An assistant's MCP settings with the hawk-apps server: created, added to the developer's own, or left as is. */
 function planMcpConfig(dir, { file, key, entry }) {
@@ -85,6 +107,8 @@ export function planAgentFiles(dir, app) {
     }
 
     for (const config of MCP_CONFIGS) files.push(planMcpConfig(dir, config));
+    const cleanup = planClaudeMcpCleanup(dir);
+    if (cleanup) files.push(cleanup);
 
     const claudeFile = join(dir, 'CLAUDE.md');
     if (!existsSync(claudeFile)) {
@@ -108,6 +132,10 @@ export const isAgentChange = (f) => f.state !== 'current' && f.state !== 'skippe
 export async function writeAgentFiles(dir, plan) {
     const changed = plan.filter(isAgentChange);
     for (const f of changed) {
+        if (f.state === 'delete') {
+            await rm(join(dir, f.file), { force: true });
+            continue;
+        }
         await mkdir(dirname(join(dir, f.file)), { recursive: true });
         await writeFile(join(dir, f.file), f.content);
     }
@@ -118,8 +146,11 @@ export async function writeAgentFiles(dir, plan) {
 export function describeAgentFile({ file, state }) {
     const mcp = file.endsWith('mcp.json');
     switch (state) {
+        case 'remove':
+        case 'delete':
+            return `${file}: the hawk-apps MCP server is ${state === 'delete' ? 'removed (the file had nothing else)' : 'taken out (your other servers are kept)'}: Claude Code gets it from the Hawk Apps plugin now (see the CLI README).`;
         case 'create':
-            if (mcp) return `${file}: added (the hawk-app MCP server for ${file === '.mcp.json' ? 'Claude Code' : 'VS Code'}).`;
+            if (mcp) return `${file}: added (the hawk-app MCP server for VS Code).`;
             return file === 'AGENTS.md' ? 'AGENTS.md: added (instructions for AI coding assistants).' : `${file}: added (points Claude Code at AGENTS.md).`;
         case 'update':
             return `${file}: the CLI's part is refreshed (your notes outside its markers are kept).`;

package/src/claude-plugin.mjs

@@ -0,0 +1,67 @@
+// `hawk-app claude`: installs the Hawk Apps plugin for Claude Code (the hawk-apps MCP server and skills), once per
+// machine. The plugin ships in this package (../claude-plugin: a marketplace with one plugin) so nobody needs access to
+// the repository: it is copied next to the CLI's credentials, stamped with this CLI's version (Claude Code updates a
+// plugin when its version changes), and added to Claude Code as a local marketplace. With the `claude` command on the
+// PATH that happens here; otherwise the two /plugin commands are printed for the Claude Code panel. Run it again to
+// update.
+import { spawnSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { cp, mkdir, rm, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { cliVersion } from './channel.mjs';
+import { credentialsPath } from './credentials.mjs';
+
+export const MARKETPLACE = 'hawk-apps';
+export const PLUGIN = 'hawk-apps';
+export const PLUGIN_ID = `${PLUGIN}@${MARKETPLACE}`;
+const SOURCE = fileURLToPath(new URL('../claude-plugin', import.meta.url));
+
+/** Where the plugin is kept on this machine: next to the CLI's credentials (%APPDATA%\hawk-app\claude-plugin on Windows). */
+export const pluginHome = (env = process.env) => join(dirname(credentialsPath(env)), 'claude-plugin');
+
+/** Copies the packaged marketplace to `target` (replacing an older copy), with the plugin's version set to `version`. */
+export async function writePlugin(target, version = cliVersion()) {
+    await rm(target, { recursive: true, force: true });
+    await mkdir(target, { recursive: true });
+    await cp(SOURCE, target, { recursive: true });
+    const manifest = join(target, PLUGIN, '.claude-plugin', 'plugin.json');
+    const plugin = JSON.parse(readFileSync(manifest, 'utf8'));
+    await writeFile(manifest, JSON.stringify({ ...plugin, version }, null, 2) + '\n');
+}
+
+/** Runs `claude plugin …`; null when there's no `claude` command. */
+function defaultRunClaude(args) {
+    const result = spawnSync('claude', ['plugin', ...args], { encoding: 'utf8', shell: process.platform === 'win32' });
+    if (result.error || (result.status !== 0 && /not recognized|not found|ENOENT/i.test(`${result.stderr}${result.error?.message ?? ''}`))) return null;
+    return { ok: result.status === 0, output: `${result.stdout ?? ''}${result.stderr ?? ''}`.trim() };
+}
+
+/**
+ * Installs (or updates) the plugin. The marketplace is added, or refreshed when it already is; the plugin installed, or
+ * updated when it already is. Returns 0; the steps Claude Code still needs are printed when `claude` isn't available.
+ */
+export async function claudeCommand({ log = console.log, env = process.env, runClaude = defaultRunClaude, version = cliVersion() } = {}) {
+    const target = pluginHome(env);
+    await writePlugin(target, version);
+    log(`✔ Hawk Apps plugin ${version} saved to ${target}`);
+
+    const added = runClaude(['marketplace', 'add', target]);
+    if (added === null) {
+        log('');
+        log('Now, in the Claude Code panel (or a `claude` session), type these two commands:');
+        log(`  /plugin marketplace add ${target}`);
+        log(`  /plugin install ${PLUGIN_ID}`);
+        log('Already installed? Update it instead: /plugin marketplace update hawk-apps, then /reload-plugins.');
+        return 0;
+    }
+    const marketplace = added.ok ? added : runClaude(['marketplace', 'update', MARKETPLACE]);
+    if (!marketplace?.ok) throw new Error(`Claude Code didn't add the plugin's marketplace:\n${added.output}`);
+    const installed = runClaude(['install', PLUGIN_ID, '--scope', 'user']);
+    const plugin = installed?.ok ? installed : runClaude(['update', PLUGIN_ID]);
+    if (!plugin?.ok) throw new Error(`Claude Code didn't install the plugin:\n${installed?.output ?? ''}`);
+    log(`✔ Claude Code has the ${PLUGIN_ID} plugin. In a session that's already open, run /reload-plugins.`);
+    log('  Its skills: /hawk-apps:new-screen, /hawk-apps:add-query, /hawk-apps:add-function, /hawk-apps:prepare-review;');
+    log('  its MCP server starts in the open folder (/mcp lists it). Run `npx @bridgeline-digital/hawk-app-cli@latest claude` again to update.');
+    return 0;
+}

package/src/cli.mjs

@@ -37,6 +37,7 @@ Start
   create <folder>         Start a new app from a template (react, preact, next, next-mui, vanilla)
   init                    Make an existing project a Hawk App
   sso                     Sign in with your Bridgeline account (once per machine; CI: login with a publisher key)
+  claude                  Install the Hawk Apps plugin for Claude Code: MCP server and skills (once per machine)
   doctor                  Check everything: Node, login, hawk-app.json, project, scopes, template, MCP
   docs [topic]            The developer docs: guides, the bridge API, every command (Bridgeline sign-in)
 
@@ -146,7 +147,12 @@ Usage:
                                                     deletes one of yours (no clients on it)
   hawk-app why <client id>                          What a client's users see of the app, and why
   hawk-app mcp                                      Run the MCP server for AI coding assistants (stdio; dev platform
-                                                    only). create and init add it to .mcp.json and .vscode/mcp.json
+                                                    only). create and init add it to .vscode/mcp.json; Claude Code
+                                                    gets it from the Hawk Apps plugin (hawk-app claude)
+  hawk-app claude                                   Install or update the Hawk Apps plugin for Claude Code (the MCP
+                                                    server and skills), once per machine: copied next to your
+                                                    login, then added with \`claude plugin\` when it's on the PATH,
+                                                    else the two /plugin commands to type in Claude Code
   hawk-app dev [--client <id>] [--engine <id>] [--url <app dev URL>] [--port 3200] [--client-user] [--no-start]
                                                     Run the app locally in a stand-in for HawkSearch, with real
                                                     tokens and data for any client (runs \`npm run dev\` unless
@@ -213,6 +219,8 @@ HawkSearch index (scope hawksearch:index, no commands): app.hawksearch.index.reb
   Creating, switching and deleting indexes, hierarchy and mappings: scope hawksearch:index:manage.
 HawkSearch recommendations (scope hawksearch:recommendations, no commands): app.hawksearch.recommendations from the
   bridge, the engine's recommendation widgets, never tracked in the client's recommendation reports.
+HawkAI (scope hawkai:read, no commands): app.hawkai.agents/agent/smartResponses/smartResponse from the bridge, the
+  client's HawkAI agents and smart responses for the user's engine (names and settings, never prompts).
 Storage (scope storage, no commands): app.storage / ctx.platform.storage get, put, delete, list, batch and usage from
   the bridge, the app's own key-value data per client (JSON values up to 350 KB, optional expiry, version checks), and
   storage.files upload, url, download, list and delete for its files (up to 100 MB each).
@@ -353,6 +361,11 @@ export async function main(argv, { fetchImpl = fetch, log = console.log, runBuil
         case 'logout':
             return logout({ platform: flags.platform, env: flags.env, log });
 
+        case 'claude': {
+            const { claudeCommand } = await import('./claude-plugin.mjs');
+            return claudeCommand({ log });
+        }
+
         case 'mcp': {
             // Loaded only here: the MCP SDK isn't needed by any other command.
             const { serveMcp } = await import('./mcp.mjs');

package/src/doctor.mjs

@@ -26,6 +26,9 @@ export function appUrl(platformUrl, slug, alias) {
 /** The developer docs (built from the hawk-apps repo's markdown; sign in with a Bridgeline account). */
 export const DOCS_URL = 'https://developers.hawksearchapps.com';
 
+/** How to install (or update) the Hawk Apps plugin for Claude Code: see claude-plugin.mjs. */
+export const PLUGIN_INSTALL = 'npx @bridgeline-digital/hawk-app-cli@latest claude';
+
 /**
  * `hawk-app docs <topic>`: the page for each topic. Developers' topics open the developer docs (a feature's section of
  * the bridge reference); `platform` opens the engineering docs, which the site keeps out of its navigation and search.
@@ -166,9 +169,14 @@ export async function doctorCommand({ manifestFile, flags = {}, fetchImpl = fetc
     }
 
     // AI assistants.
-    const mcp = join(projectDir, '.mcp.json');
-    if (existsSync(mcp) && readFileSync(mcp, 'utf8').includes('hawk-apps')) ok('MCP server set up for AI assistants (.mcp.json)');
-    else warn('No MCP config for AI assistants: `npx hawk-app upgrade --yes` adds .mcp.json and .vscode/mcp.json.');
+    const vscodeMcp = join(projectDir, '.vscode', 'mcp.json');
+    if (existsSync(vscodeMcp) && readFileSync(vscodeMcp, 'utf8').includes('hawk-apps')) ok('MCP server set up for VS Code (.vscode/mcp.json)');
+    else warn('No MCP config for VS Code: `npx hawk-app upgrade --yes` adds .vscode/mcp.json.');
+    const claudeMcp = join(projectDir, '.mcp.json');
+    if (existsSync(claudeMcp) && readFileSync(claudeMcp, 'utf8').includes('"hawk-apps"')) {
+        warn('.mcp.json still starts the hawk-apps MCP server: `npx hawk-app upgrade --yes` takes it out (the Hawk Apps plugin starts it for Claude Code).');
+    }
+    log(`  Claude Code: the Hawk Apps plugin gives it the MCP server and skills (${PLUGIN_INSTALL}).`);
 
     log(failed ? `\n${failed} thing${failed === 1 ? '' : 's'} to fix above.` : '\nAll set.');
     log(`Docs: ${DOCS_URL} (npx hawk-app docs)`);

package/src/manifest.mjs

@@ -6,7 +6,7 @@ import { validateStore } from './store-listing.mjs';
 export const MANIFEST_FILE = 'hawk-app.json';
 const SLUG = /^[a-z0-9]+(-[a-z0-9]+)*$/;
 const VISIBILITIES = ['allowList', 'all', 'internal', 'store'];
-const SCOPES = ['reports:read', 'hawksearch:read', 'hawksearch:write', 'data:read', 'functions:invoke', 'email:send', 'hawksearch:sysparams:write', 'hawksearch:search', 'ai:invoke', 'lambdas:invoke', 'hawksearch:features:write', 'hawksearch:index', 'hawksearch:index:items', 'hawksearch:index:manage', 'hawksearch:recommendations', 'storage', 'assistant'];
+const SCOPES = ['reports:read', 'hawksearch:read', 'hawksearch:write', 'data:read', 'functions:invoke', 'email:send', 'hawksearch:sysparams:write', 'hawksearch:search', 'ai:invoke', 'lambdas:invoke', 'hawksearch:features:write', 'hawksearch:index', 'hawksearch:index:items', 'hawksearch:index:manage', 'hawksearch:recommendations', 'storage', 'assistant', 'hawkai:read'];
 export const SYSPARAMS_SCOPE = 'hawksearch:sysparams:write';
 /** The templates `hawk-app create` offers (the keys of create.mjs's TEMPLATES): `"template"` in hawk-app.json. */
 export const TEMPLATE_NAMES = ['react', 'preact', 'next', 'next-mui', 'vanilla'];

package/src/mcp-hawksearch.mjs

@@ -156,9 +156,18 @@ export function bridgeCall(api, method, path, rules = FALLBACK) {
     }
     if (api === 'search') {
         const limit = `${rules.search.perMinute} calls a minute.`;
-        if (rel === 'api/v2/search') return { call: "await app.hawksearch.search({ Keyword: 'boots' })", scope: 'hawksearch:search', note: `The platform sets ClientGuid to the engine's; IsInPreview: true runs on the preview search API. ${limit}` };
+        if (rel === 'api/v2/search') {
+            return {
+                call: "await app.hawksearch.search({ Keyword: 'boots' })",
+                scope: 'hawksearch:search',
+                note: `The platform sets ClientGuid to the engine's; IsInPreview: true runs on the preview search API (with SmartBar switches and PreviewDate, ClientData.PreviewBuckets for visitor targets). ${limit}`,
+            };
+        }
         if (rel === 'api/v2/autocomplete') return { call: "await app.hawksearch.autocomplete({ Keyword: 'boo' })", scope: 'hawksearch:search', note: `The platform sets ClientGuid to the engine's. ${limit}` };
-        return { unavailable: 'Apps can call only search and autocomplete of the Search API.' };
+        return {
+            unavailable:
+                "Apps can call only search and autocomplete of the Search API, plus the preview page's tools: app.hawksearch.preview.settings(), indexes(), item(id) and explain(request) (hawksearch:read).",
+        };
     }
     if (api === 'recommendations') {
         const { available, perMinute, maxBulkWidgets } = rules.recommendations;

package/src/project-checks.mjs

@@ -73,8 +73,8 @@ export async function checkProject(dir) {
         }
     }
 
-    if (pkg && !pkg.devDependencies?.[CLI] && !pkg.dependencies?.[CLI] && (existsSync(join(dir, '.mcp.json')) || existsSync(join(dir, '.vscode', 'mcp.json')))) {
-        warnings.push(`${CLI} isn't a dev dependency, but the MCP settings start it from node_modules: npm install -D ${CLI}.`);
+    if (pkg && !pkg.devDependencies?.[CLI] && !pkg.dependencies?.[CLI] && existsSync(join(dir, '.vscode', 'mcp.json'))) {
+        warnings.push(`${CLI} isn't a dev dependency, but VS Code's MCP settings start it from node_modules: npm install -D ${CLI}.`);
     }
     if (!pkg) {
         warnings.push('No package.json: deploy uploads the folder as it is, and npm audit cannot run, so the review\'s dependencies check fails.');

package/src/scope-check.mjs

@@ -9,7 +9,7 @@ import { extname, join, relative } from 'node:path';
  */
 const RULES = [
     { scope: 'reports:read', pattern: /\.analytics\.report\s*\(/ },
-    { scope: 'hawksearch:read', pattern: /\.dashboard\.get\s*\(/ },
+    { scope: 'hawksearch:read', pattern: /\.dashboard\.get\s*\(|\.hawksearch\.preview\.(settings|indexes|item|explain)\s*\(/ },
     { scope: 'hawksearch:write', pattern: /\.dashboard\.(post|put|delete)\s*\(/ },
     { scope: 'data:read', pattern: /\.data\.query\s*\(/ },
     { scope: 'functions:invoke', pattern: /\.functions\.(call|start|job|wait)\s*\(/ },
@@ -25,6 +25,7 @@ const RULES = [
     { scope: 'lambdas:invoke', pattern: /\.lambdas\.invoke\s*\(/ },
     { scope: 'ai:invoke', pattern: /\.ai\.(generate|stream|info)\s*\(/ },
     { scope: 'assistant', pattern: /\.assistant\.(ask|setContext)\s*\(/ },
+    { scope: 'hawkai:read', pattern: /\.hawkai\.(agents|agent|smartResponses|smartResponse|runSmartResponse|assistant)\s*\(/ },
 ];
 
 const SOURCE = new Set(['.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs', '.vue', '.svelte', '.html']);