@shoalrun/cli 0.1.0-alpha.18 → 0.1.0-alpha.19

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## 0.1.0-alpha.19 — 2026-11-05
+
+- Give your coding agent the `shoalrun-brand` skill to match a documentation
+  site to your brand. It guides the agent through choosing colors and fonts,
+  adding your logo, and applying theme settings and CSS. It also checks search
+  results, menus, buttons, keyboard focus, and mobile layouts for readability.
+  Read it with `shoalrun skills read shoalrun-brand`.
+- Make hosted chat verify where a visitor check came from. Turnstile responses
+  must match a trusted hostname and, when configured, the expected action.
+  A session pass from a different hostname/action policy no longer skips the
+  check, even when the deployments share a secret. Changing the policy
+  invalidates existing passes. Upgrade the CLI, then rebuild and
+  redeploy hosted chat to apply these protections.
+- Keep local and hosted test previews working with Turnstile's published test
+  keys. Local preview checks the actual dummy-token response; the documentation
+  site's hosted preview requires test credentials and a separate usage store.
+- Check development dependencies as well as production dependencies in both
+  repositories during a coordinated release. Update the documentation site's
+  browser tools and affected dependencies to remove the identified security
+  advisories without forcing incompatible package versions.
+- Add security headers to the documentation site that restrict framing to the
+  same origin and set an explicit referrer policy. Deployment checks now reject
+  responses missing the required headers. A broader Content Security Policy
+  starts in report-only mode so browser violations can be reviewed before
+  enforcement; it doesn't yet block scripts. These are site-owned settings,
+  not new defaults imposed on customer sites.
+- Refresh the repository and package READMEs with product versions, customer
+  editions, branding, application content delivery, and agent workflows. Update
+  the hosted-chat guide with hostname checks, optional actions, session passes,
+  and preview configuration.
+
 ## 0.1.0-alpha.18 — 2026-11-04
 
 - Add authored page availability ranges with `since` and `through` version

package/README.md

@@ -1,6 +1,6 @@
 # Shoalrun
 
-Shoalrun turns Markdown and MDX into a documentation website and Markdown pages from the same content. People can browse the site; agents can read the Markdown. Native components such as steps, tabs, and API references preserve their content in both formats.
+Shoalrun builds a documentation website, Markdown pages, and application content from the same Markdown and MDX source. People can browse the site; applications and agents can read stable documents, sections, and snippet instances. Native components keep essential instructions and API details readable in both HTML and Markdown.
 
 This package provides the `shoalrun` CLI, starter projects, agent skills, and offline documentation. It requires Node.js 22.12 or newer. This alpha is distributed through the public npm registry. Installation requires no npm account or package token.
 
@@ -9,17 +9,9 @@ This package provides the `shoalrun` CLI, starter projects, agent skills, and of
 From the project where you want to keep your documentation:
 
 ```sh
-npm install --save-dev --save-exact @shoalrun/cli@0.1.0-alpha.18
+npm install --save-dev --save-exact @shoalrun/cli@0.1.0-alpha.19
 ```
 
-If you previously used the private GitHub Packages alpha, check `npm config get @shoalrun:registry`. Remove or replace any `@shoalrun:registry=https://npm.pkg.github.com` entry in your project or user `.npmrc`. You can explicitly select the public registry for the upgrade:
-
-```sh
-npm install --save-dev --save-exact @shoalrun/cli@0.1.0-alpha.18 --@shoalrun:registry=https://registry.npmjs.org
-```
-
-Commit the updated package manifest and lockfile together. Check that the lockfile resolves `@shoalrun/cli` from `registry.npmjs.org`. Keep any credentials needed by other private dependencies; Shoalrun itself no longer needs a package token.
-
 ## Create and preview a site
 
 Run these commands from the directory where you installed the package:
@@ -38,11 +30,34 @@ npx --no-install shoalrun dev my-docs/docs.config.yaml my-docs/site-dist --port
 
 Stop the existing preview with Ctrl-C before starting the development server on the same port. Choose **Explore the starter**, the first item in the left navigation, to find component examples, diagrams, reader views, themes, and generated API references. The service and API hosts are fictional; replace them before sending requests. Choose `--starter minimal` for a smaller starting point or `--starter api-docs` for a focused OpenAPI example. All three starters build without provider credentials.
 
+## What you can build
+
+The [features overview](https://www.shoalrun.com/features) describes the complete authoring and delivery workflow. Start with the part you need:
+
+| Need | Capability |
+| --- | --- |
+| A documentation site | Pages, navigation, local preview, themes, palettes, fonts, and project CSS. |
+| Reusable procedures | Recipes, shared ingredients, and cookbooks that help readers choose a complete task. |
+| API reference | OpenAPI operation pages, code examples, focused contracts, and an explicit source-review gate. |
+| Several product releases | Independent product versions and defaults, publication routes, and a header publication selector. |
+| Customer editions | External profiles, SKU revisions, feature grants, and conditional pages or sections. |
+| Application help | HTML and Markdown exports, stable page/section/snippet references, static and REST clients, and instance-safe mounting. |
+| Agent discovery | Markdown twins, compact linked indexes, read-only MCP tools, bundled skills, and offline references. |
+| Search and answers | Browser keyword search, optional semantic retrieval, and hosted documentation chat with shared limits. |
+
+Local builds and keyword search need no provider credentials. Semantic retrieval and generated answers use separately configured services; credentials stay server-side. Reader filters are browsing controls, not authorization. Customer profiles select output during compilation; private-edition hosting remains your responsibility.
+
+## Match your brand
+
+Use `site.logo`, `site.favicon`, and header settings for site identity. Choose a theme preset and configure `theme.palette`, `theme.mode`, and `theme.fonts`. Use `site.customCss` for changes beyond those settings. Customer profiles can supply deployment-owned branding without storing customer records in the shared source.
+
+Check controls and interactive states as well as article text: a dark header can contain light inputs, menus, and search results. Palette validation doesn't check arbitrary project CSS. See [themes and fonts](https://www.shoalrun.com/styling/themes), the [CSS reference](https://www.shoalrun.com/author/css), and [deployment profiles](DEPLOYMENT-PROFILES.md).
+
 ## Independently versioned products
 
 Projects can give each product its own version catalog and default version. Product publications carry a product, channel, version, and language; routes, document links, navigation, search, and content exports retain that scope. Existing projects without product catalogs keep their publication identities and routes.
 
-Available since `0.1.0-alpha.18`.
+Product catalogs and profile-aware development preview are available since `0.1.0-alpha.18`. The product names and versions below are an example configuration.
 
 The header publication dropdown groups the published releases by product. It hides language labels when the edition has one language; set `site.publicationSelector.showLanguage: true` or `false` to override that display without changing publication identity.
 
@@ -87,7 +102,7 @@ publications:
 The shared configuration must declare `profiles.manifest`, which defines the known features and SKU revisions. Each selected publication must be enabled by that configuration. Preview the customer edition directly:
 
 ```sh
-npx --no-install shoalrun dev docs.config.yaml site-dist --profile customers/acme.yaml --port 8770
+npx --no-install shoalrun dev docs.config.yaml site-dist --profile customers/example.yaml --port 8770
 ```
 
 The development server compiles the selected edition and watches its profile, SKU manifest, and declared assets, including files outside the project. Editing the profile rebuilds the edition and removes output that is no longer selected. The preview identifies the last successful edition. If a rebuild fails, it keeps that output and displays the failure on existing and newly opened pages. Reader views remain browsing controls; customer profile selection applies during compilation to HTML, Markdown, navigation, and indexes.
@@ -96,7 +111,7 @@ Agents can discover product scopes through MCP `get_publications` before searchi
 
 ## Work with an agent
 
-Shoalrun works with your existing coding agent. Its packaged skills explain how to set up a site, edit pages, and develop components:
+Shoalrun works with your existing coding agent. Its packaged skills cover setup, page authoring, components, recipes, and walkthroughs. Use `skills list` to discover the skills included with your installed version:
 
 ```sh
 npx --no-install shoalrun skills list
@@ -105,7 +120,7 @@ npx --no-install shoalrun skills read shoalrun-setup
 
 Ask your agent to read the skill for the task. `skills list` returns names, descriptions, and local instruction-file paths. These commands read the skills; installing the npm package does not automatically install them into your agent.
 
-The usual editing workflow is to capture a baseline, edit source files, validate the changes, then review a local preview. From your documentation project directory:
+The editing workflow is to capture a baseline, edit source files, validate the changes, then review a local preview. From your documentation project directory:
 
 ```sh
 npx --no-install shoalrun docs baseline --out .shoalrun/task-baseline.json
@@ -113,7 +128,7 @@ npx --no-install shoalrun docs baseline --out .shoalrun/task-baseline.json
 npx --no-install shoalrun docs validate --baseline .shoalrun/task-baseline.json
 ```
 
-Validation returns a report path. Pass that path to `shoalrun docs review` and `shoalrun docs preview`. Snapshot validation can render affected draft pages while preserving their draft access; ordinary site builds exclude drafts. Supply your own project writing and review requirements—the starter does not define them for you.
+Validation returns a report path. Pass that path to `shoalrun docs review` and `shoalrun docs preview`. Snapshot validation can render affected draft pages while preserving their draft access; ordinary site builds exclude drafts. Supply your own project writing and review requirements. Configured checks and custom plugins execute trusted project code; a validation copy is not an operating-system sandbox.
 
 ## Find documentation
 
@@ -297,18 +312,6 @@ The limit applies to each index response, not an entire multi-step reading sessi
 An individual title or summary too large to fit an index produces an explicit
 build error rather than silently dropping content.
 
-## Status and development
-
-This alpha may change configuration and output formats between releases. No compatibility promise or maintained older release line is offered yet. Creating and previewing a basic site does not require a model provider or Chrome. Optional provider-backed features require their own configuration.
-
-Shoalrun is maintainer-led and does not accept unsolicited pull requests at this time. The [repository development instructions](https://github.com/shoalrun/shoalrun#develop-the-framework) explain how to build and test your own checkout or fork.
-
-Pin an exact package version and read the [changelog](CHANGELOG.md) before upgrading. Rebuild and check HTML, Markdown, links, and any application consuming exported content before deploying. See the [contribution policy](https://github.com/shoalrun/shoalrun/blob/main/CONTRIBUTING.md) and [security policy](https://github.com/shoalrun/shoalrun/blob/main/SECURITY.md) for reporting problems and project trust boundaries.
-
-## License
-
-Copyright 2026 Casey Smith. This package is licensed under [Apache-2.0](LICENSE). Your authored site content keeps its own license. Built sites contain runtime assets and may contain copied template text; retain applicable licenses and third-party notices when distributing them.
-
 ## Verification dates
 
 Set `verified` only after checking a page's technical claims. It is separate from
@@ -327,3 +330,25 @@ in HTML only; Markdown and manifest metadata retain it. Set
 `frontmatter.defaults.showVerified: false` in project configuration for a shared
 default, then override it with `showVerified: true` on individual pages. A layout
 with a Hero replaces the standard page header and does not display its dates.
+
+## Upgrade from the earlier private registry
+
+If you previously used the private GitHub Packages alpha, check `npm config get @shoalrun:registry`. Remove or replace any `@shoalrun:registry=https://npm.pkg.github.com` entry in your project or user `.npmrc`. You can explicitly select the public registry for the upgrade:
+
+```sh
+npm install --save-dev --save-exact @shoalrun/cli@0.1.0-alpha.19 --@shoalrun:registry=https://registry.npmjs.org
+```
+
+Commit the updated package manifest and lockfile together. Check that the lockfile resolves `@shoalrun/cli` from `registry.npmjs.org`. Keep any credentials needed by other private dependencies; Shoalrun itself no longer needs a package token.
+
+## Status and development
+
+This alpha may change configuration and output formats between releases. No compatibility promise or maintained older release line is offered yet. Creating and previewing a basic site does not require a model provider or Chrome. Optional provider-backed features require their own configuration.
+
+Shoalrun is maintainer-led and does not accept unsolicited pull requests at this time. The [repository development instructions](https://github.com/shoalrun/shoalrun#develop-the-framework) explain how to build and test your own checkout or fork.
+
+Pin an exact package version and read the [changelog](CHANGELOG.md) before upgrading. Rebuild and check HTML, Markdown, links, and any application consuming exported content before deploying. See the [contribution policy](https://github.com/shoalrun/shoalrun/blob/main/CONTRIBUTING.md) and [security policy](https://github.com/shoalrun/shoalrun/blob/main/SECURITY.md) for reporting problems and project trust boundaries.
+
+## License
+
+Copyright 2026 Casey Smith. This package is licensed under [Apache-2.0](LICENSE). Your authored site content keeps its own license. Built sites contain runtime assets and may contain copied template text; retain applicable licenses and third-party notices when distributing them.

package/agent-docs/.well-known/shoalrun/navigation/project-updates-50f26fe22670.txt

@@ -24,13 +24,15 @@ Full-page token counts use cl100k_base. Navigation section ID: project-updates.
 
 - [Smaller hosted search and Ask functions](https://www.shoalrun.com/changelog/2026-11-04-runtime-packaging.md) — ID: change.2026-11-04-runtime-packaging. changelog-entry; 647 tokens. Rebuild hosted docs with alpha.17 to reduce deployment files while keeping semantic search and Ask available.
 
+- [Branding guidance and safer hosted chat](https://www.shoalrun.com/changelog/branding-security.md) — ID: change.branding-security. changelog-entry; 936 tokens. Match your documentation to your brand with an agent skill, and bind hosted-chat visitor checks to the intended site.
+
 - [Authoring snapshot previews and review reports](https://www.shoalrun.com/changelog/authoring-preview.md) — ID: change.authoring-preview. changelog-entry; 554 tokens. Snapshot previews with coverage and freshness reports.
 
 - [Agent authoring, search, and documentation answers](https://www.shoalrun.com/changelog/authoring-search.md) — ID: change.authoring-search. changelog-entry; 468 tokens. Reviewed agent drafts, search improvements, and answer context.
 
 - [Working-tree authoring tools](https://www.shoalrun.com/changelog/authoring-tools.md) — ID: change.authoring-tools. changelog-entry; 384 tokens. Project discovery and captured working-tree validation.
 
-- [Changelog](https://www.shoalrun.com/changelog.md) — ID: reference.changelog. reference; 1337 tokens. Compiler, CLI, and reader changes.
+- [Changelog](https://www.shoalrun.com/changelog.md) — ID: reference.changelog. reference; 1407 tokens. Compiler, CLI, and reader changes.
 
 - [MCP hosting, analytics, and component improvements](https://www.shoalrun.com/changelog/2026-10-17-mcp-hosting.md) — ID: change.mcp-hosting. changelog-entry; 1147 tokens. MCP hosting, analytics, and shared component content.
 

package/agent-docs/SNAPSHOT.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": 1,
   "sourceRepository": "https://github.com/shoalrun/docs",
-  "sourceCommit": "201a4e562b70414e26ecba7c2488ba899550f06b",
-  "siteBuildId": "41390a172a8dbd578761e016a1c5890718f0b06c37f90b40769f585f75fd71ec",
-  "manifestDigest": "b0996def2c34eaafbb41b5ab5b3ca0e78a370a620ffb4b8bfe53bc6248300d05",
-  "indexDigest": "ed3b6ccce7e13cb3d038707a22430a76367522344d879a166d2764d445c16e06",
-  "packageIntegrity": "sha512-91enZzr2NCzCFo8OXfEZWjI7SQD+FVlFtEwRD30UKaMD3OBjgVY0wBgZyvVULXMUoZkdbyOj/OpdfDw/Tkk1ww=="
+  "sourceCommit": "27e393134027da5587c4102f6d4a4e9598f2bed5",
+  "siteBuildId": "3ca70f64a4b3562b2c51fd6a4a6beceb3578705d2fc545b7788589aebd0e6ff5",
+  "manifestDigest": "2fb2a205cf322384919c7546e0626c42de82c34cfcdc2f5e244c92968993fd03",
+  "indexDigest": "66cbcb506a60f1a1588e76135ab195c1491cb69337526f21979aed936d4478c5",
+  "packageIntegrity": "sha512-UMknmhUPoDv6tSOUlIjfeEuOHANy/+pEouq8wGEXlAxN9uRaVqcO/bSRcXQkLZvWLIolLcqkFDRjAUzVNimFDA=="
 }

package/agent-docs/changelog/branding-security.md

@@ -0,0 +1,66 @@
+---
+id: change.branding-security
+title: Branding guidance and safer hosted chat
+summary: Match your documentation to your brand with an agent skill, and bind
+  hosted-chat visitor checks to the intended site.
+type: changelog-entry
+area:
+  - appearance
+  - discovery
+  - project
+subarea:
+  - appearance-themes
+  - discovery-chat
+  - project-releases
+canonical: /changelog/branding-security
+date: 2026-11-05
+releaseVersion: 0.1.0-alpha.19
+---
+
+# Branding guidance and safer hosted chat
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Project](https://www.shoalrun.com/.well-known/shoalrun/navigation/project-updates-50f26fe22670.txt) (ID: project-updates). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Project](https://www.shoalrun.com/status.md) > Changelog > alpha.19: Branding and security
+
+**Published: 2026-11-05.**
+
+**Version: 0.1.0-alpha.19.**
+
+Give your coding agent the `shoalrun-brand` skill to match a documentation site to your brand. It guides the agent through colors, fonts, logos, theme settings, and CSS, then checks menus, search results, buttons, keyboard focus, and mobile layouts for readability.
+
+Upgrade to CLI `0.1.0-alpha.19`. Rebuild and redeploy hosted chat to apply its new visitor checks. You don't need provider credentials to read the skill or brand a local site.
+
+## Match a documentation site to your brand
+
+Ask your agent to read the skill:
+
+```sh
+npx --no-install shoalrun skills read shoalrun-brand
+```
+
+The skill works from a supplied website, brand guide, or assets. It uses supported configuration first and project CSS where needed. It keeps brand assets in your project and preserves the documentation, navigation, and routes. It checks both the page and interactive surfaces: a dark header can contain light inputs, dropdowns, and search results that need their own text colors.
+
+The agent builds and previews the result for review. See [themes and fonts](https://www.shoalrun.com/styling/themes.md) and the [CSS reference](https://www.shoalrun.com/author/css.md) for the configuration it uses.
+
+## Keep visitor checks tied to the intended site
+
+Hosted chat checks the hostname returned by Turnstile rather than accepting a successful response alone. By default, the accepted names come from the site's trusted deployment addresses. You can supply an exact `chat.challenge.hostnames` list and an optional `action` for this operation.
+
+A session pass is now tied to the hostname/action policy as well as the caller. A pass from a different policy can't skip the check, even when deployments share a secret. Changing the policy invalidates existing passes; the next required check gives the visitor a new one.
+
+Local public preview handles the published dummy-token response separately from production verification. Hosted test previews need matching test credentials and a separate usage store. See [Host and limit documentation chat](https://www.shoalrun.com/chat/host.md) for the settings and preview behavior.
+
+## Check dependencies and hosting policy
+
+Coordinated releases now check both the framework and documentation dependency graphs, including development tools. The documentation site's browser tools and affected dependencies are updated without forcing an incompatible package version.
+
+The documentation site also restricts framing to the same origin, sets an explicit referrer policy, and checks the required headers after deployment. Its broader Content Security Policy starts in report-only mode: browser violations can be reviewed before enforcement, and that policy doesn't yet block scripts. These settings belong to this site; they aren't compiler defaults for customer sites.
+
+The repository and package READMEs now cover product versions, customer editions, branding, application content delivery, and agent workflows.
+
+## HTML, Markdown, and agents
+
+Branding changes the HTML site's appearance and interaction states. Markdown retains the documentation and examples without fonts, colors, menus, or focus styles. Agents read the packaged skill and bundled references, edit project source, validate the result, and share a local preview. A successful build doesn't replace visual checks of the browser output.

package/agent-docs/changelog.md

@@ -22,6 +22,14 @@ Updates to Shoalrun and its documentation. Each entry identifies the affected ve
 
 ## Latest changes
 
+- 2026-11-05
+
+  Version 0.1.0-alpha.19
+
+  [Branding guidance and safer hosted chat](https://www.shoalrun.com/changelog/branding-security.md)
+
+  Match your documentation to your brand with an agent skill, and bind hosted-chat visitor checks to the intended site.
+
 - 2026-11-04
 
   Version 0.1.0-alpha.17

package/agent-docs/chat/host.md

@@ -116,6 +116,22 @@ chat:
 
 The site key is public and goes in the config. The secret goes in the environment variable. A check that fails, times out, or has no secret refuses the request, so an outage can't let scripts through. Without `chat.challenge`, the function logs a warning, because only the daily caps then stand in the way of a script.
 
+The function also checks the hostname returned by Cloudflare. By default, it accepts the trusted site and deployment hostnames described above, without their ports. Set `hostnames` to an explicit list to narrow that check. Names are exact: don't include a scheme, path, port, or wildcard. Keep the widget's allowed domains in Cloudflare consistent with the addresses you intend to use.
+
+Use `action` when the widget needs to identify this operation. The browser sends it when requesting a token, and the server requires the same value in Cloudflare's verification response:
+
+```yaml title="docs.config.yaml"
+chat:
+  challenge:
+    provider: turnstile
+    siteKey: 0x4AAAAAAAexample
+    secretEnv: TURNSTILE_SECRET_KEY
+    hostnames: [docs.example.com]
+    action: documentation_chat
+```
+
+A missing or mismatched hostname, or a missing or mismatched configured action, refuses the request before answering. Adding a hostname here doesn't authorize incoming requests from that host; the function's host checks still apply.
+
 The default `adaptive` mode requests a challenge when usage crosses a threshold:
 
 - A caller is asked once they have used `freeQuestions` model answers in a day. The default is 3.
@@ -124,15 +140,17 @@ The default `adaptive` mode requests a challenge when usage crosses a threshold:
 
 When challenged, the panel runs the check and resends the question. It shows `Checking that you are a person…` while waiting.
 
-A successful check creates a signed, browser-script-inaccessible cookie tied to the caller’s address. The signing key is derived from the Turnstile secret. The pass lasts 15 minutes, so follow-up questions need no new challenge during that time.
+A successful check creates a signed, browser-script-inaccessible cookie tied to the caller’s address and the hostname/action policy. The signing key is derived from the Turnstile secret and that policy. Changing the policy invalidates existing passes. The pass lasts 15 minutes, so follow-up questions need no new challenge during that time.
 
 | Setting         | What it does                                                                                                                                                            |
 | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `hostnames`     | Exact hostnames accepted from token verification. Defaults to the trusted runtime hostnames; an explicit list must be nonempty.                                         |
+| `action`        | Optional operation name sent by the widget and checked by the server. Use 1–32 letters, digits, underscores, or hyphens.                                                |
 | `when`          | `adaptive` (the default) asks only when needed. `always` checks every conversation. It runs in the background when the panel opens, so the first question doesn't wait. |
 | `freeQuestions` | Model answers a caller gets before being asked. The default is 3.                                                                                                       |
 | `busyShare`     | The share of the daily budget at which everyone is asked. A number above 0 and at most 1. The default is 0.5.                                                           |
 
-Cloudflare publishes test keys for development. They work on any address and accept only their own test token, so a test site key needs the matching test secret. Use them for preview deployments, so you never have to register preview addresses.
+Cloudflare publishes test keys for development. A test site key needs the matching test secret. Test responses use synthetic hostname metadata and don't prove a production domain or action. `serve --ask --public-preview` configures its local test expectations for you. For hosted previews with real verification, register the preview hostname in the widget and include it among the function's trusted hosts. Keep test keys and test grants out of production.
 
 ### Record questions
 

package/agent-docs/chat/settings.md

@@ -98,7 +98,7 @@ Add these fields to `chat` when the corresponding capability is needed. Scorer-d
 | `fallback`   | A list of one to five other models to try, in order, when the main one fails. See [Use more than one model](#use-more-than-one-model).                                                                                                                               |
 | `escalate`   | A second model to ask when the checks flag an answer, with an optional `when` list. See [Use more than one model](#use-more-than-one-model).                                                                                                                         |
 | `budget`     | Daily caps on questions that reach the model. See [Cap the daily spend](https://www.shoalrun.com/chat/host.md).                                                                                                                                                      |
-| `challenge`  | A Turnstile check for a hosted chat. See [Host the chat on Vercel](https://www.shoalrun.com/chat/host.md).                                                                                                                                                           |
+| `challenge`  | A Turnstile check for hosted chat, with verified hostnames and an optional action. See [Host the chat on Vercel](https://www.shoalrun.com/chat/host.md).                                                                                                             |
 | `log`        | Records questions on a hosted chat. See [Host the chat on Vercel](https://www.shoalrun.com/chat/host.md).                                                                                                                                                            |
 | `cache`      | Keeps clean answers so a repeated question costs nothing. `maxEntries` (default 500) and `ttlMinutes` (default 1,440) set the size and the age. See [Reuse answers](https://www.shoalrun.com/chat/checks.md).                                                        |
 | `cards`      | Needs `rerank: jev`. Serves answers written ahead of time. `threshold` (default 0.75) shortlists a card by similarity, and `confirm` (default 0.9) is the Jev score that must confirm it. See [Prepared answers](https://www.shoalrun.com/chat/prepared-answers.md). |

package/agent-docs/chat/settings.sections/configure-chat.md

@@ -66,7 +66,7 @@ Add these fields to `chat` when the corresponding capability is needed. Scorer-d
 | `fallback`   | A list of one to five other models to try, in order, when the main one fails. See [Use more than one model](https://www.shoalrun.com/chat/settings.md#use-more-than-one-model).                                                                                      |
 | `escalate`   | A second model to ask when the checks flag an answer, with an optional `when` list. See [Use more than one model](https://www.shoalrun.com/chat/settings.md#use-more-than-one-model).                                                                                |
 | `budget`     | Daily caps on questions that reach the model. See [Cap the daily spend](https://www.shoalrun.com/chat/host.md).                                                                                                                                                      |
-| `challenge`  | A Turnstile check for a hosted chat. See [Host the chat on Vercel](https://www.shoalrun.com/chat/host.md).                                                                                                                                                           |
+| `challenge`  | A Turnstile check for hosted chat, with verified hostnames and an optional action. See [Host the chat on Vercel](https://www.shoalrun.com/chat/host.md).                                                                                                             |
 | `log`        | Records questions on a hosted chat. See [Host the chat on Vercel](https://www.shoalrun.com/chat/host.md).                                                                                                                                                            |
 | `cache`      | Keeps clean answers so a repeated question costs nothing. `maxEntries` (default 500) and `ttlMinutes` (default 1,440) set the size and the age. See [Reuse answers](https://www.shoalrun.com/chat/checks.md).                                                        |
 | `cards`      | Needs `rerank: jev`. Serves answers written ahead of time. `threshold` (default 0.75) shortlists a card by similarity, and `confirm` (default 0.9) is the Jev score that must confirm it. See [Prepared answers](https://www.shoalrun.com/chat/prepared-answers.md). |

package/agent-docs/config/examples.md

@@ -27,7 +27,7 @@ Install Node.js 22.12 or newer and npm before running these commands.
 mkdir my-docs
 cd my-docs
 npm init -y
-npm install --save-exact @shoalrun/cli@0.1.0-alpha.18
+npm install --save-exact @shoalrun/cli@0.1.0-alpha.19
 npx --no-install shoalrun init . --starter minimal
 npx --no-install shoalrun build docs.config.yaml site-dist
 npx --no-install shoalrun serve site-dist
@@ -52,7 +52,7 @@ The `showcase` starter provides 18 connected pages. Its component examples cover
 mkdir my-handbook
 cd my-handbook
 npm init -y
-npm install --save-exact @shoalrun/cli@0.1.0-alpha.18
+npm install --save-exact @shoalrun/cli@0.1.0-alpha.19
 npx --no-install shoalrun init . --starter showcase
 npx --no-install shoalrun build docs.config.yaml site-dist
 npx --no-install shoalrun serve site-dist

package/agent-docs/config/examples.sections/feature-showcase.md

@@ -29,7 +29,7 @@ Install Node.js 22.12 or newer and npm before running these commands.
 mkdir my-docs
 cd my-docs
 npm init -y
-npm install --save-exact @shoalrun/cli@0.1.0-alpha.18
+npm install --save-exact @shoalrun/cli@0.1.0-alpha.19
 npx --no-install shoalrun init . --starter minimal
 npx --no-install shoalrun build docs.config.yaml site-dist
 npx --no-install shoalrun serve site-dist
@@ -54,7 +54,7 @@ The `showcase` starter provides 18 connected pages. Its component examples cover
 mkdir my-handbook
 cd my-handbook
 npm init -y
-npm install --save-exact @shoalrun/cli@0.1.0-alpha.18
+npm install --save-exact @shoalrun/cli@0.1.0-alpha.19
 npx --no-install shoalrun init . --starter showcase
 npx --no-install shoalrun build docs.config.yaml site-dist
 npx --no-install shoalrun serve site-dist

package/agent-docs/config/examples.sections/minimal-site.md

@@ -29,7 +29,7 @@ Install Node.js 22.12 or newer and npm before running these commands.
 mkdir my-docs
 cd my-docs
 npm init -y
-npm install --save-exact @shoalrun/cli@0.1.0-alpha.18
+npm install --save-exact @shoalrun/cli@0.1.0-alpha.19
 npx --no-install shoalrun init . --starter minimal
 npx --no-install shoalrun build docs.config.yaml site-dist
 npx --no-install shoalrun serve site-dist

package/agent-docs/config/examples.sections/multilingual-help-center.md

@@ -29,7 +29,7 @@ Install Node.js 22.12 or newer and npm before running these commands.
 mkdir my-docs
 cd my-docs
 npm init -y
-npm install --save-exact @shoalrun/cli@0.1.0-alpha.18
+npm install --save-exact @shoalrun/cli@0.1.0-alpha.19
 npx --no-install shoalrun init . --starter minimal
 npx --no-install shoalrun build docs.config.yaml site-dist
 npx --no-install shoalrun serve site-dist

package/agent-docs/config/examples.sections/parcel-api-documentation.md

@@ -29,7 +29,7 @@ Install Node.js 22.12 or newer and npm before running these commands.
 mkdir my-docs
 cd my-docs
 npm init -y
-npm install --save-exact @shoalrun/cli@0.1.0-alpha.18
+npm install --save-exact @shoalrun/cli@0.1.0-alpha.19
 npx --no-install shoalrun init . --starter minimal
 npx --no-install shoalrun build docs.config.yaml site-dist
 npx --no-install shoalrun serve site-dist

package/agent-docs/config/examples.sections/related-reading.md

@@ -29,7 +29,7 @@ Install Node.js 22.12 or newer and npm before running these commands.
 mkdir my-docs
 cd my-docs
 npm init -y
-npm install --save-exact @shoalrun/cli@0.1.0-alpha.18
+npm install --save-exact @shoalrun/cli@0.1.0-alpha.19
 npx --no-install shoalrun init . --starter minimal
 npx --no-install shoalrun build docs.config.yaml site-dist
 npx --no-install shoalrun serve site-dist

package/agent-docs/config/examples.sections/shared-company-preset.md

@@ -29,7 +29,7 @@ Install Node.js 22.12 or newer and npm before running these commands.
 mkdir my-docs
 cd my-docs
 npm init -y
-npm install --save-exact @shoalrun/cli@0.1.0-alpha.18
+npm install --save-exact @shoalrun/cli@0.1.0-alpha.19
 npx --no-install shoalrun init . --starter minimal
 npx --no-install shoalrun build docs.config.yaml site-dist
 npx --no-install shoalrun serve site-dist

package/agent-docs/configuration.md

@@ -59,7 +59,7 @@ CONFIG_DEMO="$(mktemp -d)"
 mkdir "$CONFIG_DEMO/site"
 cd "$CONFIG_DEMO/site"
 npm init -y
-npm install --save-exact @shoalrun/cli@0.1.0-alpha.18
+npm install --save-exact @shoalrun/cli@0.1.0-alpha.19
 npx --no-install shoalrun init . --starter minimal
 ```
 

package/agent-docs/configuration.sections/start-with-one-working-file.md

@@ -40,7 +40,7 @@ CONFIG_DEMO="$(mktemp -d)"
 mkdir "$CONFIG_DEMO/site"
 cd "$CONFIG_DEMO/site"
 npm init -y
-npm install --save-exact @shoalrun/cli@0.1.0-alpha.18
+npm install --save-exact @shoalrun/cli@0.1.0-alpha.19
 npx --no-install shoalrun init . --starter minimal
 ```