@bridgeline-digital/hawk-app-cli 0.1.2-dev.20261027234716 → 0.1.2-dev.20261028113950

package/README.md

@@ -648,6 +648,25 @@ and a version whose functions changed **always needs review**, even on an auto-a
 5. Call it from the app: `await app.functions.call('sync-feed', { since: '2026-09-01' })`. Like queries, functions
    always run from a **deployed** version, also in dev mode (`?devUrl=`).
 
+**Contracts.** Declare what a function takes and returns with zod (`npm install zod`), and deploy sends them with the
+function: the platform then refuses a call whose input doesn't match (400 `invalid_function_input`) before it runs.
+
+```ts
+import { z } from 'zod';
+import { defineFunction } from '@bridgeline-digital/hawk-app-bridge/server';
+export const handler = defineFunction({
+    input: z.object({ name: z.string() }),
+    output: z.object({ greeting: z.string() }),
+    async handler(input, ctx) { return { greeting: `Hello ${input.name} from ${ctx.client.id}` }; },
+});
+```
+
+`npx hawk-app types` writes `hawk-functions.d.ts` (in `src/`, else next to `hawk-app.json`) from the contracts, so
+pages get `app.functions.call('echo', { name })` typed without a type argument; `hawk-app dev` refreshes it when it
+starts, and deploy warns when it's out of date. Deploy prints `contracts: <names>` and stops when a contract can't be
+read (a schema that isn't zod, or larger than 6 KB as JSON Schema). Client API endpoints get an OpenAPI document from
+them, and approvers see contract changes that may break callers.
+
 `hawk-app validate` and `hawk-app deploy` check, with the platform's rules:
 - at most 10 functions; names are lowercase letters, digits and single dashes, up to 40 characters;
 - `job` true or false; `timeoutSeconds` 1–25 (1–900 for a job), `memoryMb` 128–1024, `secrets` up to 20 unique
@@ -785,7 +804,9 @@ param is read:
 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
+attribute (`"data": "hawk-keyword"`), used as is when the page has it, with its selector and pattern as the fallback.
+A target's `when` shows the button only where the values read meet conditions (`equals`, `in` or `pattern`, ignoring
+case), e.g. `"when": { "category": { "in": ["Synonym", "Redirect"] } }`. 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

package/agents/AGENTS.md

@@ -148,6 +148,11 @@ With the UI kit: `usePageContext(rows ? { page: '<the page>', dateRange, totals,
 `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.
 
+**Help** (`HELP.md` next to hawk-app.json): the app's guide for its users, which HawkSearch's Help tab answers "How do
+I…?" from. Keep it in step with the app: when you add or change a screen, a button or a workflow, update the steps in
+HELP.md too, naming buttons and fields exactly as the UI shows them. Plain Markdown for merchandisers (not developers),
+at most 32 KB; it ships with each deploy. HTML comments are notes for the team and are left out.
+
 **Comments** (scope `comments`): `<HawkComments target="keyword:…" label="…" />` from the UI kit on what people discuss
 (a row, a widget, `page:summary`); targets are stable ids, never personal data. Declare `config.commentEmails`
 (`{ "type": "emails" }`) so new comments are emailed (`hawk-app config set commentEmails …`, a person or a Slack
@@ -175,8 +180,9 @@ UI kit in each tab (or `app.usage.screen`), and mark the main buttons `data-hawk
 **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
+"selector"?, "attribute"?, "pattern"? } }, "when"?: { "<param>": { "equals" | "in" | "pattern": … } } }] } } }`.
+`"data": "keyword"` reads `data-keyword` as is when the page has it, else the rest of the reader applies. Use `when` so
+the button shows only where the action applies (conditions on the values read, ignoring case), not on every match. 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.
@@ -195,6 +201,11 @@ page, at the slot's height, so don't rely on the full window either.
   `@bridgeline-digital/hawk-app-bridge/server`. Use `ctx.platform` (same APIs as `app`), `ctx.secrets.NAME`,
   `ctx.client.id`, `ctx.user`. Stateless; 25 s, or 900 s for a job (`"job": true`). Engineering enables functions per
   app.
+- **Contracts** (prefer for every function): `export const handler = defineFunction({ input: z.object({…}), output:
+  z.object({…}), async handler(input, ctx) {…} })` with zod (add it to the app). The platform refuses a call whose
+  input doesn't match (400 `invalid_function_input`) before the function runs. Run `npx hawk-app types` after changing
+  a contract: it writes `hawk-functions.d.ts`, so pages call `app.functions.call('<name>', input)` without a type
+  argument and get the result typed. Client API endpoints get an OpenAPI document from them.
 
 ## Project
 

package/docs/bridge/README.md

@@ -176,6 +176,11 @@ buttons appear in HawkSearch: nothing changes in HawkSearch for it.
   as is (no pattern); when it's missing or empty, the param's `selector`, `attribute` and `pattern` read it as above.
   So a target can be ready for an attribute HawkSearch adds later, e.g. `"keyword": { "data": "hawk-keyword",
   "selector": "td.table__cell:first-child" }`. With `data` alone, nothing is read until the attribute is there.
+- **Only where it applies (optional):** `when` shows the button only on the things whose values meet every condition,
+  by param (one of the target's `params`): `{ "equals": "…" }`, `{ "in": ["…", …] }` (at most 20) or
+  `{ "pattern": "<regex>" }`, all ignoring case. A param that couldn't be read fails its condition, so no button goes
+  where a value is missing. Use it for what a CSS selector can't say: a cell's text, a value a pattern pulls out, e.g.
+  `"when": { "category": { "in": ["Zero results", "Poor results"] }, "keyword": { "pattern": "\\S" } }`.
 - **Pick stable selectors:** ids, `data-*` attributes and element names over styling classes. HawkSearch doesn't know
   about your selectors: when it changes its markup, your buttons stop appearing until you deploy new targets.
 - **Approval:** `actions` is a setting that always needs an approver (never auto-approve): reviewers see each target and
@@ -577,6 +582,42 @@ const { items } = await app.functions.call<{ items: unknown[] }>('sync-feed', {
 what `handler` returned (up to 6 MB). It waits up to `timeoutMs` (default 30 s) and retries while the platform answers
 429 (too many calls running), like data queries.
 
+### Contracts: `defineFunction`
+
+Say what a function takes and returns with zod schemas (add `zod` to the app), and every caller agrees on one shape:
+
+```ts
+// functions/price-check.ts
+import { z } from 'zod';
+import { defineFunction } from '@bridgeline-digital/hawk-app-bridge/server';
+
+export const handler = defineFunction({
+    input: z.object({ sku: z.string().min(1), limit: z.number().int().default(5) }),
+    output: z.object({ ours: z.number(), lowest: z.number().nullable() }),
+    async handler({ sku, limit }, ctx) {          // typed from input: limit is a number (its default applied)
+        return { ours: 10, lowest: null };
+    },
+});
+```
+
+```ts
+// In the app, after `npx hawk-app types` (hawk-app dev runs it when it starts)
+const price = await app.functions.call('price-check', { sku: 'abc' });   // input checked, result typed
+```
+
+- **The platform checks every call's input** against the contract before the function runs: a mismatch is
+  `HawkApiError` 400 `invalid_function_input`, with `errors` saying what's wrong (`"/sku: …"`); nothing runs or is
+  billed. Jobs (`start`) and the app's client API endpoints are checked the same way.
+- **Typed calls:** `hawk-app types` writes `hawk-functions.d.ts` from the contracts; `call` and `start` are then typed
+  for those functions, and a function without a contract stays `call<T>(name, input)`. Deploy warns when the file is
+  behind the contracts.
+- **Client API:** an endpoint's function contract types a GET's query (`?limit=5` is a number) and describes the
+  endpoint in the OpenAPI document the API access screen offers.
+- **Review:** a contract change that may break callers (a newly required input field, a removed output field, a
+  changed type) is flagged for the approver.
+- Any Standard Schema works for the input check in the function, but deploy describes only zod schemas (zod 4's
+  `toJSONSchema`). Keep each schema to the fields callers send and read (at most 6 KB as JSON Schema).
+
 **`ctx`** (`HawkFunctionContext`)
 
 | | |
@@ -1566,6 +1607,20 @@ Hosts: `<hawk-app-explain for="<frame id>">` (registered with `<hawk-app-frame>`
 the frame's `pageContext`, `hawk-page-context` event and `explainPage()` are there for hosts that build their own. See
 [HOSTS.md](HOSTS.md).
 
+### Help: the app's guide, `HELP.md`
+
+The same panel has a **Help** tab where users ask "How do I…?" and the platform's AI answers from your app's guide:
+`HELP.md`, next to hawk-app.json. No code and no scope; the button shows for Help alone on pages that set no context.
+
+- **Write it for the people who use the app:** what it's for in two or three sentences, each task as numbered steps that
+  name the buttons and fields as the app shows them, what its numbers and statuses mean, and common questions with their
+  answers. Plain Markdown, at most 32 KB. HTML comments are notes for your team: Help leaves them out.
+- **It ships with each deploy** (privately, not on the CDN), so every version answers from its own guide; deploy after
+  changing it. `hawk-app create` starts one with only comments, and Help stays off until you write it.
+- **Answers** use the guide and the page context (above), so "what does this column mean?" gets an answer about the
+  page the user is on. They never invent features; a question the guide doesn't cover is pointed to "Report a problem".
+  Help and Explain share one daily budget per client.
+
 ### Export a page as a PDF
 
 Pages worth keeping (a report, a summary for a meeting) can offer **Export as PDF**: while the page allows it, the
@@ -1726,7 +1781,7 @@ Which clients have the app is not in this file: manage them in the Hawk Analytic
 | `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. |
 | `events` | [Events](#events): a job function per event (`client.added`, `config.changed`, `version.released`, `hawksearch.changed`, `index.rebuilt`), `{ "<event>": { "function" } }` (`hawksearch.changed` also takes `sections`). Needs `functions:invoke`. Reviewed like scopes. |
-| `actions` | [Actions](#actions-start-the-app-from-hawksearchs-screens): buttons in HawkSearch's pages that open a view in a dialog, `{ "<name>": { "label", "view", "targets": { "hawksearch": [{ "path", "selector", "anchor"?, "position"?, "params" }] } } }` (at most 10). Always reviewed by an approver. |
+| `actions` | [Actions](#actions-start-the-app-from-hawksearchs-screens): buttons in HawkSearch's pages that open a view in a dialog, `{ "<name>": { "label", "view", "targets": { "hawksearch": [{ "path", "selector", "anchor"?, "position"?, "params", "when"? }] } } }` (at most 10). Always reviewed by an approver. |
 | `api` | [Client API](#client-api): endpoints the client's systems call with their HawkSearch site API key, `{ "<name>": { "function", "method"?: "GET" \| "POST", "description"? } }`, each a function that isn't a job (at most 10). Needs `functions:invoke`. Reviewed like scopes. |
 | `systemParameters` | The HawkSearch [system parameters](#hawksearch-system-parameters-hawksearchsysparamswrite) the app may read and set, e.g. `["Timezone"]`. Needs `hawksearch:sysparams:write`. Reviewed like scopes. |
 | `config` | [App config](#app-config) keys: `{ "<key>": { "type", "label", "description", "default" } }`, at most 50. The values are set outside the file (portal or `npx hawk-app config`) and aren't secret. Reviewed like scopes. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bridgeline-digital/hawk-app-cli",
-  "version": "0.1.2-dev.20261027234716",
+  "version": "0.1.2-dev.20261028113950",
   "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",

package/schema/hawk-app.schema.json

@@ -236,6 +236,23 @@
                           "pattern": { "type": "string", "minLength": 1, "maxLength": 300 }
                         }
                       }
+                    },
+                    "when": {
+                      "description": "Shows the button only on the things whose values meet every condition, by param (one of this target's params), ignoring case. A param that couldn't be read fails. E.g. { \"category\": { \"in\": [\"Synonym\", \"Redirect\"] } }.",
+                      "type": "object",
+                      "minProperties": 1,
+                      "maxProperties": 10,
+                      "additionalProperties": {
+                        "type": "object",
+                        "minProperties": 1,
+                        "maxProperties": 1,
+                        "additionalProperties": false,
+                        "properties": {
+                          "equals": { "description": "The value is this.", "type": "string", "minLength": 1, "maxLength": 100 },
+                          "in": { "description": "The value is one of these.", "type": "array", "minItems": 1, "maxItems": 20, "items": { "type": "string", "minLength": 1, "maxLength": 100 } },
+                          "pattern": { "description": "The value matches this regular expression.", "type": "string", "minLength": 1, "maxLength": 300 }
+                        }
+                      }
                     }
                   }
                 }

package/src/cli.mjs

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { writeFile } from 'node:fs/promises';
-import { basename, dirname, join, resolve } from 'node:path';
+import { basename, dirname, join, relative, resolve, sep } from 'node:path';
 import { TEMPLATES, createProject, titleCase, toSlug } from './create.mjs';
 import { addAgentFiles } from './agents.mjs';
 import { confirmVulnerabilities, deploy, npmRunBuild, submissionClearedMessage } from './deploy.mjs';
@@ -16,8 +16,10 @@ import { DEFAULT_ICON_SVG, checkIcon } from './app-icon.mjs';
 import { checkScreenshots } from './store-listing.mjs';
 import { platformClient } from './platform.mjs';
 import { dataCommand } from './data.mjs';
+import { hasZod, readContracts, TYPES_FILE, writeTypes } from './contracts.mjs';
+import { HELP_FILE, loadHelp } from './help.mjs';
 import { DATA_SCOPE, QUERIES_DIR, loadQueries } from './queries.mjs';
-import { FUNCTIONS_DIR, checkBridge, describeFunctions, loadFunctions } from './functions.mjs';
+import { BRIDGE_PACKAGE, FUNCTIONS_DIR, checkBridge, describeFunctions, loadFunctions } from './functions.mjs';
 import { secretsCommand } from './secrets.mjs';
 import { configCommand } from './config.mjs';
 import { clientsCommand, pickDevClient, rememberDevClient } from './clients.mjs';
@@ -249,6 +251,12 @@ Functions (server-side code, scope functions:invoke):
                                                     functions/__recordings__/). --record calls the platform once
                                                     (as the test's client, HAWKSEARCH_API_KEY for HawkSearch) and
                                                     saves its answers
+  hawk-app types                                    Write hawk-functions.d.ts from the functions' contracts
+                                                    (defineFunction's zod input and output), so pages get typed
+                                                    app.functions.call. hawk-app dev refreshes it when it starts
+  Contracts: export const handler = defineFunction({ input, output, handler }) with zod schemas. Deploy sends them;
+  the platform refuses a call whose input doesn't match (400 invalid_function_input) before the function runs, and
+  the API access screen offers the client API's OpenAPI document.
   Background jobs: "job": true on a function (up to 900 s), started with app.functions.start. "schedules" in
   hawk-app.json run job functions on an EventBridge cron (at most hourly) for clients where a user turns them on.
   "events" in hawk-app.json run a job function when something happens for a client: client.added (a client got the
@@ -455,6 +463,7 @@ export async function main(argv, { fetchImpl = fetch, log = console.log, runBuil
             const queries = await checkQueries(manifest, manifestFile);
             const functions = await checkFunctions(manifest, manifestFile);
             const projectDir = dirname(resolve(manifestFile));
+            const help = await loadHelp(projectDir);
             const project = await checkProject(projectDir);
             const { url } = resolveSettings({ flagPlatform: flags.platform, flagEnv: flags.env });
             const channelWarning = devAppOnProd(projectDir, url);
@@ -468,9 +477,9 @@ export async function main(argv, { fetchImpl = fetch, log = console.log, runBuil
             const { errors: buildErrors, warnings: buildWarnings } = flags.build
                 ? await checkBuild({ projectDir, manifest, folder: positional[0], runBuild, log })
                 : { errors: [], warnings: [] };
-            const ok = `✔ ${manifestFile} looks good.${queries ? ` ${QUERIES_DIR}/: ${describeQueryCount(queries.queries.length)}.` : ''}${functions ? ` ${FUNCTIONS_DIR}/: ${describeFunctions(functions.functions.length)}.` : ''}${flags.build ? ' The build\'s URLs are under its base path.' : ''}`;
+            const ok = `✔ ${manifestFile} looks good.${queries ? ` ${QUERIES_DIR}/: ${describeQueryCount(queries.queries.length)}.` : ''}${functions ? ` ${FUNCTIONS_DIR}/: ${describeFunctions(functions.functions.length)}.` : ''}${help?.file ? ` ${HELP_FILE}: the Help tab answers from it.` : ''}${flags.build ? ' The build\'s URLs are under its base path.' : ''}`;
             return report(
-                { errors: [...result.errors, ...icon.errors, ...screenshots.errors, ...(queries?.errors ?? []), ...(functions?.errors ?? []), ...buildErrors], warnings: [...result.warnings, ...project.warnings, ...buildWarnings] },
+                { errors: [...result.errors, ...icon.errors, ...screenshots.errors, ...(queries?.errors ?? []), ...(functions?.errors ?? []), ...(help?.errors ?? []), ...buildErrors], warnings: [...result.warnings, ...project.warnings, ...buildWarnings] },
                 ok,
                 log,
             );
@@ -513,6 +522,11 @@ export async function main(argv, { fetchImpl = fetch, log = console.log, runBuil
                 for (const error of functions.errors) log(`✖ ${error}`);
                 throw new Error(`Fix the functions first.`);
             }
+            const help = await loadHelp(projectDir);
+            if (help?.errors.length) {
+                for (const error of help.errors) log(`✖ ${error}`);
+                throw new Error(`Fix ${HELP_FILE} first.`);
+            }
             const alias = flags.alias === undefined ? undefined : checkAlias(flags.alias);
             // hawk-app.json as the platform takes it ($schema and template are for local tools).
             const { $schema: _schema, template: _template, ...settings } = manifest;
@@ -536,7 +550,7 @@ export async function main(argv, { fetchImpl = fetch, log = console.log, runBuil
                 storeFiles: screenshots.files,
                 dir: positional[0] ?? resolve(projectDir, target.folder),
                 build: target.build && !flags['no-build'],
-                serverFiles: queries?.files ?? [],
+                serverFiles: [...(queries?.files ?? []), ...(help?.file ? [help.file] : [])],
                 functions: functions?.functions ?? [],
                 projectDir,
                 audit: !flags['no-audit'],
@@ -647,9 +661,36 @@ export async function main(argv, { fetchImpl = fetch, log = console.log, runBuil
                 await client().register(manifest.slug, settings, false);
                 log(`✔ Registered ${manifest.slug} on the platform (not released: only Bridgeline staff see it).`);
             }
+            // Typed function calls follow the contracts as they are now (never stops dev).
+            await refreshTypes(projectDir, manifest, log).catch(() => undefined);
             return devCommand({ client: client(), manifest, flags, projectDir, ...(env ? { env } : {}), signal, log });
         }
 
+        case 'types': {
+            const manifest = await loadManifest(manifestFile);
+            const projectDir = dirname(resolve(manifestFile));
+            const loaded = await loadFunctions(projectDir, manifest);
+            if (loaded?.errors.length) {
+                for (const error of loaded.errors) log(`✖ ${error}`);
+                return 1;
+            }
+            const { contracts, errors } = await readContracts({ projectDir, functions: loaded?.functions ?? [] });
+            if (errors.length) {
+                for (const error of errors) log(`✖ ${error}`);
+                return 1;
+            }
+            const { file, changed } = await writeTypes(projectDir, contracts);
+            const typed = [...contracts].filter(([, c]) => c).map(([name]) => name);
+            if (!file) {
+                log(hasZod(projectDir) || !loaded?.functions.length
+                    ? `No function has a contract yet${changed ? ` (removed the old ${TYPES_FILE})` : ''}. Declare one with defineFunction({ input, output, handler }) from ${BRIDGE_PACKAGE}/server.`
+                    : `No contracts: the app has no zod. Add it (\`npm install zod\`) and declare them with defineFunction({ input, output, handler }).`);
+                return 0;
+            }
+            log(`✔ ${relative(projectDir, file).split(sep).join('/')} ${changed ? 'written' : 'up to date'}: typed app.functions.call for ${typed.join(', ')}.`);
+            return 0;
+        }
+
         case 'test': {
             const projectDir = dirname(resolve(manifestFile));
             const settings = flags.record ? resolveSettings({ flagPlatform: flags.platform, flagEnv: flags.env }) : null;
@@ -838,6 +879,19 @@ async function checkFunctions(manifest, manifestFile) {
     return result;
 }
 
+/** `hawk-app dev`'s start: hawk-functions.d.ts from the contracts as they are now (a line only when it changed). */
+async function refreshTypes(projectDir, manifest, log) {
+    const loaded = await loadFunctions(projectDir, manifest);
+    if (!loaded?.functions.length || loaded.errors.length) return;
+    const { contracts, errors } = await readContracts({ projectDir, functions: loaded.functions });
+    if (errors.length) {
+        log(`! ${errors[0]}`);
+        return;
+    }
+    const { file, changed } = await writeTypes(projectDir, contracts);
+    if (changed && file) log(`✔ ${relative(projectDir, file).split(sep).join('/')} updated from the functions' contracts.`);
+}
+
 /**
  * `validate --build [<folder>]`: builds the app as deploy would (with a stand-in base path, /<slug>/v0) and checks
  * that its HTML only loads URLs under it. The folder comes from the argument or the app:deploy script.

package/src/contracts.mjs

@@ -0,0 +1,212 @@
+import { existsSync } from 'node:fs';
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { tmpdir } from 'node:os';
+import { join, relative, sep } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+// Function contracts: zod schemas of what a function takes and returns (`defineFunction({ input, output, handler })`
+// from the bridge's /server). The CLI reads them with the app's own zod, as JSON Schema: deploy sends them with each
+// function (the platform checks calls' input against them), and `hawk-app types` writes hawk-functions.d.ts so pages
+// get typed `app.functions.call`. Same size limit as the platform.
+export const MAX_SCHEMA_BYTES = 6 * 1024;
+export const TYPES_FILE = 'hawk-functions.d.ts';
+
+/** The generated entry: the function's contract as JSON Schema, converted by the app's zod (the one its schemas come from). */
+function contractSource(entry) {
+    const userModule = entry.split(sep).join('/');
+    return [
+        `import * as fn from ${JSON.stringify(userModule)};`,
+        "import { toJSONSchema } from 'zod';",
+        'const contract = fn.handler && fn.handler.contract;',
+        "const convert = (schema, io) => (schema ? toJSONSchema(schema, { io, unrepresentable: 'any' }) : null);",
+        "export default contract ? { input: convert(contract.input, 'input'), output: convert(contract.output, 'output') } : null;",
+        '',
+    ].join('\n');
+}
+
+/** Whether the app has zod (its contracts' schemas): without it, its functions have no contracts. */
+export function hasZod(projectDir) {
+    try {
+        createRequire(join(projectDir, 'package.json')).resolve('zod');
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * Each function's contract, `{ input, output }` JSON Schemas (each null when not declared), or null for a function
+ * without one. Loads each function once in this process (its module's top-level code runs, as in `hawk-app dev`).
+ * @param {{ projectDir: string, functions: { name: string, entry: string }[] }} options
+ * @returns {Promise<{ contracts: Map<string, { input: object | null, output: object | null } | null>, errors: string[] }>}
+ */
+export async function readContracts({ projectDir, functions }) {
+    const contracts = new Map();
+    const errors = [];
+    if (!functions.length || !hasZod(projectDir)) {
+        for (const fn of functions) contracts.set(fn.name, null);
+        return { contracts, errors };
+    }
+    const esbuild = await import('esbuild');
+    const dir = await mkdtemp(join(tmpdir(), 'hawk-contracts-'));
+    try {
+        for (const fn of functions) {
+            const where = `functions/${fn.name}`;
+            const file = join(dir, `${fn.name}.mjs`);
+            try {
+                await esbuild.build({
+                    stdin: { contents: contractSource(fn.entry), resolveDir: projectDir, sourcefile: `hawk-contract-${fn.name}.mjs`, loader: 'js' },
+                    absWorkingDir: projectDir,
+                    bundle: true,
+                    platform: 'node',
+                    target: 'node22',
+                    format: 'esm',
+                    outfile: file,
+                    logLevel: 'silent',
+                    banner: { js: "import { createRequire as __hawkCreateRequire } from 'node:module';\nconst require = __hawkCreateRequire(import.meta.url);" },
+                });
+                const contract = (await import(`${pathToFileURL(file).href}?t=${Date.now()}`)).default ?? null;
+                if (contract) {
+                    for (const side of ['input', 'output']) {
+                        const bytes = contract[side] ? Buffer.byteLength(JSON.stringify(contract[side])) : 0;
+                        if (bytes > MAX_SCHEMA_BYTES) {
+                            errors.push(`${where}: the contract's ${side} schema is ${Math.ceil(bytes / 1024)} KB as JSON Schema; at most ${MAX_SCHEMA_BYTES / 1024} KB. Describe the fields callers send and read, not every nested detail.`);
+                        }
+                    }
+                }
+                contracts.set(fn.name, contract && (contract.input || contract.output) ? contract : null);
+            } catch (error) {
+                const text = error?.errors?.map((e) => e.text).join('; ') || error?.message || String(error);
+                errors.push(`${where}: couldn't read its contract (defineFunction's input and output must be zod schemas): ${text}`);
+            }
+        }
+    } finally {
+        await rm(dir, { recursive: true, force: true });
+    }
+    return { contracts, errors };
+}
+
+/** Where hawk-functions.d.ts goes: src/ when the app has one (the templates' TypeScript includes it), else next to hawk-app.json. */
+export function typesPath(projectDir) {
+    return existsSync(join(projectDir, 'src')) ? join(projectDir, 'src', TYPES_FILE) : join(projectDir, TYPES_FILE);
+}
+
+/**
+ * hawk-functions.d.ts: the functions with a contract, by name, as `HawkFunctions` of the bridge's client (typed
+ * `app.functions.call` and `start`). Null when no function has one.
+ */
+export function typesSource(contracts) {
+    const typed = [...contracts].filter(([, c]) => c).sort(([a], [b]) => a.localeCompare(b));
+    if (!typed.length) return null;
+    const lines = [
+        '// Generated by `hawk-app types` from the functions\' contracts (defineFunction in functions/). Don\'t edit it:',
+        '// run `npx hawk-app types` again after changing a contract (`hawk-app dev` does it when it starts).',
+        "import '@bridgeline-digital/hawk-app-bridge/client';",
+        '',
+        "declare module '@bridgeline-digital/hawk-app-bridge/client' {",
+        '    interface HawkFunctions {',
+    ];
+    for (const [name, contract] of typed) {
+        lines.push(`        ${JSON.stringify(name)}: {`);
+        lines.push(`            input: ${contract.input ? toTypeScript(contract.input, contract.input, 3) : 'unknown'};`);
+        lines.push(`            output: ${contract.output ? toTypeScript(contract.output, contract.output, 3) : 'unknown'};`);
+        lines.push('        };');
+    }
+    lines.push('    }', '}', '');
+    return lines.join('\n');
+}
+
+/**
+ * Writes hawk-functions.d.ts when the contracts give one (or removes a stale one when none do).
+ * @returns {Promise<{ file: string | null, changed: boolean }>}
+ */
+export async function writeTypes(projectDir, contracts) {
+    const file = typesPath(projectDir);
+    const source = typesSource(contracts);
+    const current = existsSync(file) ? await readFile(file, 'utf8') : null;
+    if (source === null) {
+        if (current !== null && current.startsWith('// Generated by `hawk-app types`')) {
+            await rm(file);
+            return { file: null, changed: true };
+        }
+        return { file: null, changed: false };
+    }
+    if (current === source) return { file, changed: false };
+    await writeFile(file, source);
+    return { file, changed: true };
+}
+
+/** "src/hawk-functions.d.ts" when it's out of date with the contracts (or missing while some function has one), else null. */
+export async function staleTypes(projectDir, contracts) {
+    const source = typesSource(contracts);
+    if (source === null) return null;
+    const file = typesPath(projectDir);
+    const current = existsSync(file) ? await readFile(file, 'utf8') : null;
+    return current === source ? null : relative(projectDir, file).split(sep).join('/');
+}
+
+const IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+
+/**
+ * A JSON Schema (as zod writes it) as a TypeScript type: objects, arrays, tuples, unions (anyOf, oneOf, type lists),
+ * intersections (allOf), enums and consts, records (additionalProperties), $refs into $defs; anything else is unknown.
+ * Descriptions become doc comments.
+ */
+export function toTypeScript(schema, root = schema, depth = 0, seen = new Set()) {
+    if (schema === true || schema === undefined || schema === null || typeof schema !== 'object') return schema === false ? 'never' : 'unknown';
+    const pad = '    '.repeat(depth + 1);
+    const end = '    '.repeat(depth);
+    if (typeof schema.$ref === 'string') {
+        const match = /^#\/(\$defs|definitions)\/(.+)$/.exec(schema.$ref);
+        const target = match ? root?.[match[1]]?.[decodeURIComponent(match[2])] : undefined;
+        // A recursive reference stays unknown rather than looping.
+        if (!target || seen.has(schema.$ref) || depth > 12) return 'unknown';
+        return toTypeScript(target, root, depth, new Set([...seen, schema.$ref]));
+    }
+    if ('const' in schema) return JSON.stringify(schema.const);
+    if (Array.isArray(schema.enum)) return schema.enum.map((v) => JSON.stringify(v)).join(' | ') || 'never';
+    const union = schema.anyOf ?? schema.oneOf;
+    if (Array.isArray(union)) return group(union.map((s) => toTypeScript(s, root, depth, seen)), ' | ');
+    if (Array.isArray(schema.allOf)) return group(schema.allOf.map((s) => toTypeScript(s, root, depth, seen)), ' & ');
+    if (Array.isArray(schema.type)) return group(schema.type.map((type) => toTypeScript({ ...schema, type }, root, depth, seen)), ' | ');
+    switch (schema.type) {
+        case 'string':
+            return 'string';
+        case 'number':
+        case 'integer':
+            return 'number';
+        case 'boolean':
+            return 'boolean';
+        case 'null':
+            return 'null';
+        case 'array': {
+            if (Array.isArray(schema.prefixItems)) {
+                const items = schema.prefixItems.map((s) => toTypeScript(s, root, depth, seen));
+                return `[${items.join(', ')}]`;
+            }
+            const item = toTypeScript(schema.items, root, depth, seen);
+            return /[|&]/.test(item) ? `Array<${item}>` : `${item}[]`;
+        }
+        case 'object':
+        case undefined: {
+            if (schema.type === undefined && !schema.properties && schema.additionalProperties === undefined) return 'unknown';
+            const required = new Set(Array.isArray(schema.required) ? schema.required : []);
+            const members = Object.entries(schema.properties ?? {}).map(([key, value]) => {
+                const name = IDENTIFIER.test(key) ? key : JSON.stringify(key);
+                const doc = typeof value?.description === 'string' ? `${pad}/** ${value.description.replace(/\*\//g, '* /')} */\n` : '';
+                return `${doc}${pad}${name}${required.has(key) ? '' : '?'}: ${toTypeScript(value, root, depth + 1, seen)};`;
+            });
+            const extra = schema.additionalProperties;
+            if (extra && extra !== false) members.push(`${pad}[key: string]: ${extra === true ? 'unknown' : toTypeScript(extra, root, depth + 1, seen)};`);
+            return members.length ? `{\n${members.join('\n')}\n${end}}` : extra === false ? 'Record<string, never>' : 'Record<string, unknown>';
+        }
+        default:
+            return 'unknown';
+    }
+}
+
+function group(types, separator) {
+    const unique = [...new Set(types)];
+    return unique.length === 1 ? unique[0] : unique.map((t) => (/[|&]/.test(t) && !t.startsWith('{') ? `(${t})` : t)).join(separator);
+}

package/src/create.mjs

@@ -6,6 +6,7 @@ import { fileURLToPath } from 'node:url';
 import { planAgentFiles, writeAgentFiles } from './agents.mjs';
 import { credentialsPath } from './credentials.mjs';
 import { ENV_EXAMPLE, resolveSettings } from './env.mjs';
+import { HELP_FILE, starterGuide } from './help.mjs';
 import { newManifest } from './manifest.mjs';
 import { DEFAULT_ICON_SVG } from './app-icon.mjs';
 import { applyChannel, CHANNELS, cliChannel, DEV_CHANNEL_NOTE, planChannel, writeCdnFiles } from './channel.mjs';
@@ -88,6 +89,7 @@ export async function createProject({ target, template = 'react', name, install
     await writeOut(join(dir, '.gitignore'), ['node_modules/', 'dist/', 'out/', '.next/', 'next-env.d.ts', '.env', '.env.local', '.env.*.local', '*.log', ''].join('\n'));
     await writeOut(join(dir, '.env.example'), ENV_EXAMPLE);
     await writeOut(join(dir, 'README.md'), readme({ slug, displayName, template, spec }));
+    await writeOut(join(dir, HELP_FILE), starterGuide(displayName));
     const agentFiles = await writeAgentFiles(dir, planAgentFiles(dir, { slug, name: displayName, template }));
 
     log(`✔ Created ${displayName} (${spec.description}) in ${relative(process.cwd(), dir) || '.'}`);
@@ -112,7 +114,7 @@ export async function createProject({ target, template = 'react', name, install
     log('  It isn\'t released yet: only Bridgeline staff see it, from the Apps page in HawkSearch (`npx hawk-app open`). Submit it');
     log('  for approval there; an approver releases it. `npx hawk-app --help` lists everything else.');
     log('  Docs: https://developers.hawksearchapps.com (npx hawk-app docs), with your Bridgeline account.');
-    return { dir, slug, files: [...written, 'hawk-app.json', 'icon.svg', '.gitignore', '.env.example', 'README.md', ...agentFiles] };
+    return { dir, slug, files: [...written, 'hawk-app.json', 'icon.svg', '.gitignore', '.env.example', 'README.md', HELP_FILE, ...agentFiles] };
 }
 
 async function listTemplateFiles(root) {
@@ -182,5 +184,10 @@ with the settings in \`hawk-app.json\` (scopes, origins, views, functions…).
 - **Clients any time.** \`npx hawk-app clients add|exclude|remove <id>\` (or the Hawk Analytics portal) applies at once,
   without a deploy or approval, and is recorded in the app's history.
 - **Something off?** \`npx hawk-app doctor\` checks your login, the platform, the project and the bridge.
+
+## Help
+\`HELP.md\` is the app's guide for its users: they ask "How do I…?" from the app's header in HawkSearch and the
+platform's AI answers from it and the page they're on. It ships with every deploy; Help is off while it holds only
+comments, as it starts.
 `;
 }

package/src/deploy.mjs

@@ -7,6 +7,8 @@ import { checkAccessibility, describeAccessibility } from './accessibility.mjs';
 import { checkBuildUrls, describeBuildUrls } from './project-checks.mjs';
 import { askYesNo } from './slug-guard.mjs';
 import { describeSource } from './source.mjs';
+import { readContracts, staleTypes } from './contracts.mjs';
+import { HELP_FILE, HELP_SERVER_PATH } from './help.mjs';
 import { sourceMapIndex, splitSourceMaps } from './sourcemaps.mjs';
 
 const CONCURRENCY = 8;
@@ -34,8 +36,8 @@ export async function listFiles(dir) {
  * folder on the CDN), the files go straight to storage, then the platform verifies them and decides who sees the
  * version: an app not released yet shows it to Bridgeline staff at once; a released app keeps clients on their version until
  * it's approved in HawkSearch (unless the app is set to auto-approve).
- * `serverFiles` (the app's checked queries/ files, from the project root) go to the platform's private server bucket
- * with their own upload URLs, never to the CDN.
+ * `serverFiles` (the app's checked queries/ files and its HELP.md as help.md, from the project root) go to the
+ * platform's private server bucket with their own upload URLs, never to the CDN.
  * `functions` (checked `{ name, entry, config }` from loadFunctions) are bundled with esbuild, uploaded to the server
  * bucket (bundle.zip, source.zip, deps.json), deployed one by one as Lambda versions, and listed on complete.
  * `audit` runs `npm audit` of the production dependencies before a version is reserved and sends the result with
@@ -60,6 +62,14 @@ export async function deploy({ client, slug, dir, alias, manifest, source = null
             built.push({ ...result, config: fn.config });
             log(`  ƒ ${fn.name}  ${formatBytes(result.bundleBytes)} zipped, ${result.deps.length} package${result.deps.length === 1 ? '' : 's'}`);
         }
+        // Contracts (defineFunction's zod schemas) go with each function: the platform checks calls' input against them.
+        const { contracts, errors } = await readContracts({ projectDir, functions });
+        if (errors.length) throw new Error(`Fix the functions' contracts first:\n${errors.map((e) => `  ${e}`).join('\n')}`);
+        for (const fn of built) fn.contract = contracts.get(fn.name) ?? null;
+        const typed = built.filter((fn) => fn.contract).map((fn) => fn.name);
+        if (typed.length) log(`  contracts: ${typed.join(', ')}`);
+        const stale = await staleTypes(projectDir, contracts);
+        if (stale) log(`! ${stale} doesn't match the functions' contracts: run \`npx hawk-app types\` so pages call them with the right types.`);
     }
     const functionFiles = built.flatMap((fn) => fn.files);
 
@@ -98,8 +108,10 @@ export async function deploy({ client, slug, dir, alias, manifest, source = null
     const accessibility = await runAccessibility(dir);
     log(`  accessibility ${describeAccessibility(accessibility)}`);
     const totalBytes = files.reduce((sum, f) => sum + f.size, 0);
-    const queryCount = new Set(serverFiles.map((f) => f.path.replace(/.(sql|json)$/, ''))).size;
-    const queriesNote = `${queryCount ? `, ${describeQueries(queryCount)}` : ''}${built.length ? `, ${describeFunctions(built.length)}` : ''}`;
+    const queryFiles = serverFiles.filter((f) => f.path.startsWith('queries/'));
+    const queryCount = new Set(queryFiles.map((f) => f.path.replace(/.(sql|json)$/, ''))).size;
+    const helpNote = serverFiles.some((f) => f.path === HELP_SERVER_PATH) ? `, ${HELP_FILE}` : '';
+    const queriesNote = `${queryCount ? `, ${describeQueries(queryCount)}` : ''}${built.length ? `, ${describeFunctions(built.length)}` : ''}${helpNote}`;
     const mapsNote = maps.length ? `, ${maps.length} source map${maps.length === 1 ? '' : 's'} (private)` : '';
     log(`Uploading v${version} of ${slug}: ${files.length} files, ${formatBytes(totalBytes)} from ${dir}${queriesNote}${mapsNote}`);
 
@@ -115,9 +127,11 @@ export async function deploy({ client, slug, dir, alias, manifest, source = null
     const serverByPath = new Map(privateFiles.map((f) => [f.path, f]));
     const functionByPath = new Map(functionFiles.map((f) => [f.path, f]));
     if (privateFiles.length && (started.serverUploads?.length ?? 0) !== privateFiles.length) {
-        throw new Error(serverFiles.length
+        throw new Error(queryFiles.length
             ? 'The platform did not accept the queries/ files. It may not support app queries yet; update it or remove queries/.'
-            : 'The platform did not accept the source maps. It may not support them yet; update it, or build without source maps.');
+            : serverFiles.length
+              ? `The platform did not accept ${HELP_FILE}. It may not support Help yet; update it, or move ${HELP_FILE} aside for this deploy.`
+              : 'The platform did not accept the source maps. It may not support them yet; update it, or build without source maps.');
     }
     if (functionFiles.length && (started.functionUploads?.length ?? 0) !== functionFiles.length) {
         throw new Error('The platform did not accept the functions. It may not support app functions yet; update it or remove "functions".');
@@ -142,7 +156,7 @@ export async function deploy({ client, slug, dir, alias, manifest, source = null
 
     // Each function becomes a Lambda version; the platform waits until it's ready.
     for (const fn of built) {
-        const deployed = await client.deployFunction(slug, version, fn.name, fn.config);
+        const deployed = await client.deployFunction(slug, version, fn.name, fn.contract ? { ...fn.config, contract: fn.contract } : fn.config);
         log(`  ✔ function ${fn.name}  (${describeConfig(fn.config)})${deployed?.lambdaVersion ? `  Lambda version ${deployed.lambdaVersion}` : ''}`);
     }
 

package/src/help.mjs

@@ -0,0 +1,56 @@
+import { existsSync } from 'node:fs';
+import { readFile, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+
+/** The app's guide, next to hawk-app.json: Help inside the app answers "How do I…?" from it. */
+export const HELP_FILE = 'HELP.md';
+/** Where it goes among the version's private server files (the platform reads it there). */
+export const HELP_SERVER_PATH = 'help.md';
+export const MAX_HELP_BYTES = 32 * 1024;
+
+/** The guide as Help reads it: HTML comments (notes for the app's team, like the template's) are left out. */
+export function guideText(text) {
+    return text.replace(/^/, '').replace(/<!--[\s\S]*?-->/g, '').trim();
+}
+
+/**
+ * The project's HELP.md as a server file of the version, checked: at most 32 KB. `file` is null without a guide yet (no
+ * file, or only comments, as `hawk-app create` writes it): the app then has no Help tab.
+ * @returns {Promise<{ file: { path: string, size: number, full: string } | null, errors: string[] } | null>}
+ */
+export async function loadHelp(projectDir) {
+    const full = join(projectDir, HELP_FILE);
+    if (!existsSync(full)) return null;
+    const { size } = await stat(full);
+    if (size > MAX_HELP_BYTES) {
+        return { file: null, errors: [`${HELP_FILE} is ${Math.ceil(size / 1024)} KB: at most ${MAX_HELP_BYTES / 1024} KB. Keep it to what users ask about.`] };
+    }
+    if (!guideText(await readFile(full, 'utf8'))) return { file: null, errors: [] };
+    return { file: { path: HELP_SERVER_PATH, size, full }, errors: [] };
+}
+
+/** The guide `hawk-app create` starts: only comments, so Help stays off until the team writes it. */
+export function starterGuide(displayName) {
+    return `<!--
+${HELP_FILE}: ${displayName}'s guide. Users ask "How do I…?" from the app's header in HawkSearch (the sparkles icon,
+"Help"), and the platform's AI answers from this file and the page they're on. It ships with every deploy (privately,
+not on the CDN), so each version answers from its own guide. Help is off while this file holds only comments.
+
+Write for the people who use the app (merchandisers, not developers):
+- what the app is for, in two or three sentences;
+- each task, as numbered steps that name the buttons and fields as the app shows them;
+- what the numbers and statuses mean, and common questions with their answers.
+Plain Markdown, at most 32 KB. Comments like this one are left out of what the AI reads.
+-->
+
+<!--
+# ${displayName}
+
+What it's for.
+
+## Getting started
+
+1. …
+-->
+`;
+}

package/src/manifest.mjs

@@ -110,8 +110,11 @@ function validateViews(m) {
 
 // Same rules as the platform (AppActionRules).
 const ACTION_KEYS = ['label', 'view', 'targets'];
-const ACTION_TARGET_KEYS = ['path', 'selector', 'anchor', 'position', 'params'];
+const ACTION_TARGET_KEYS = ['path', 'selector', 'anchor', 'position', 'params', 'when'];
 const ACTION_READER_KEYS = ['data', 'selector', 'attribute', 'pattern'];
+const ACTION_CONDITIONS = ['equals', 'in', 'pattern'];
+const MAX_CONDITION_VALUE = 100;
+const MAX_CONDITION_VALUES = 20;
 export const ACTION_HOSTS = ['hawksearch'];
 const ACTION_POSITIONS = ['append', 'prepend', 'before', 'after'];
 const ACTION_ATTRIBUTE = /^[A-Za-z_:][A-Za-z0-9_:.-]{0,63}$/;
@@ -131,8 +134,9 @@ const isRegex = (value) => {
 /**
  * "actions": buttons HawkSearch's action injector adds to its own pages, where the app's targets say (a page path and a
  * CSS selector), that open one of the app's views in a dialog with values read from the page:
- * { "<name>": { "label", "view", "targets": { "hawksearch": [{ "path", "selector", "anchor"?, "position"?, "params": { "<param>": { "data"?, "selector"?, "attribute"?, "pattern"? } } }] } } }.
- * A reader's "data" names a data-<data> attribute that wins when it has a value; the rest is the fallback.
+ * { "<name>": { "label", "view", "targets": { "hawksearch": [{ "path", "selector", "anchor"?, "position"?, "params": { "<param>": { "data"?, "selector"?, "attribute"?, "pattern"? } }, "when"? }] } } }.
+ * A reader's "data" names a data-<data> attribute that wins when it has a value; the rest is the fallback. "when" shows
+ * the button only where the values read meet conditions: { "<param>": { "equals" | "in" | "pattern": … } }.
  */
 export function validateActions(m) {
     const errors = [];
@@ -222,6 +226,35 @@ function validateActionTarget(target, at, view, viewName) {
         if (reader.attribute !== undefined && !(typeof reader.attribute === 'string' && ACTION_ATTRIBUTE.test(reader.attribute))) errors.push(`${where}.attribute is an attribute name, e.g. "data-keyword".`);
         if (reader.pattern !== undefined && !isRegex(reader.pattern)) errors.push(`${where}.pattern is a regular expression (at most ${MAX_ACTION_EXPRESSION} characters); its first group is the value.`);
     }
+    if (target.when !== undefined) errors.push(...validateActionWhen(target.when, `${at}.when`, params));
+    return errors;
+}
+
+/**
+ * "when": the button shows only where the values the target reads meet every condition, by param (one of the target's
+ * params): { "equals": "…" }, { "in": ["…", …] } or { "pattern": "…" }, ignoring case. Same rules as the platform.
+ */
+function validateActionWhen(when, at, params) {
+    if (!when || typeof when !== 'object' || Array.isArray(when) || !Object.keys(when).length) {
+        return [`${at} is { "<param>": { "equals": "…" } | { "in": ["…"] } | { "pattern": "…" } }: the button shows only where the values read meet them.`];
+    }
+    const errors = [];
+    for (const [param, condition] of Object.entries(when)) {
+        const where = `${at}.${param}`;
+        if (!Object.hasOwn(params, param)) errors.push(`${where}: "${param}" isn't one of this target's params, so it has no value to check.`);
+        const keys = condition && typeof condition === 'object' && !Array.isArray(condition) ? Object.keys(condition) : [];
+        if (keys.length !== 1 || !ACTION_CONDITIONS.includes(keys[0])) {
+            errors.push(`${where} is one condition: { "equals": "…" }, { "in": ["…", …] } or { "pattern": "…" }.`);
+            continue;
+        }
+        const value = condition[keys[0]];
+        const text = (v) => typeof v === 'string' && v.trim() && v.length <= MAX_CONDITION_VALUE;
+        if (keys[0] === 'equals' && !text(value)) errors.push(`${where}.equals is a value, at most ${MAX_CONDITION_VALUE} characters.`);
+        if (keys[0] === 'in' && !(Array.isArray(value) && value.length >= 1 && value.length <= MAX_CONDITION_VALUES && value.every(text))) {
+            errors.push(`${where}.in lists 1 to ${MAX_CONDITION_VALUES} values, each at most ${MAX_CONDITION_VALUE} characters.`);
+        }
+        if (keys[0] === 'pattern' && !isRegex(value)) errors.push(`${where}.pattern is a regular expression (at most ${MAX_ACTION_EXPRESSION} characters) the value must match.`);
+    }
     return errors;
 }