@shoalrun/cli 0.0.0-stage → 0.1.0-alpha.11

package/agent-docs/author/search.sections/html-markdown-and-agents.md

@@ -0,0 +1,37 @@
+---
+id: guide.search
+title: Site search
+summary: Search settings, keyboard behavior, provider interfaces, and index fields.
+type: reference
+area: discovery
+subarea: discovery-search
+canonical: /author/search
+---
+
+# Site search
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Search and chat > Site search
+
+**Updated: 2026-10-26.**
+
+**Verified: 2026-10-01.**
+
+Parent page: [Full Markdown page](/author/search.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Next steps**
+
+- [Preview semantic search in this checkout](https://www.shoalrun.com/recipes/preview-hybrid-search.md) — Build the passage index and verify hybrid search and lexical fallback in this checkout.
+
+Site search returns links to pages and sections. It is enabled by default and matches words in the browser, with no provider account or server required.
+
+Shoalrun supplies the search box and keyboard controls. A **search provider** supplies results; you can replace the built-in provider with your own module. [Search and chat](https://www.shoalrun.com/search-and-chat.md) explains when to add semantic search or cited answers.
+
+## HTML, Markdown, and agents
+
+The dropdown is an HTML interaction. It links to published pages and sections; it is not written into a page's Markdown twin. An agent can read the same published Markdown pages through their `.md` routes and discovery files. The local semantic endpoint returns links and short text, not an answer or a new agent-only representation. [Publishing and agent representations](https://www.shoalrun.com/publish/output.md) describes the Markdown routes and discovery files.

package/agent-docs/author/search.sections/lexical-search.md

@@ -0,0 +1,78 @@
+---
+id: guide.search
+title: Site search
+summary: Search settings, keyboard behavior, provider interfaces, and index fields.
+type: reference
+area: discovery
+subarea: discovery-search
+canonical: /author/search
+---
+
+# Site search
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Search and chat > Site search
+
+**Updated: 2026-10-26.**
+
+**Verified: 2026-10-01.**
+
+Parent page: [Full Markdown page](/author/search.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Next steps**
+
+- [Preview semantic search in this checkout](https://www.shoalrun.com/recipes/preview-hybrid-search.md) — Build the passage index and verify hybrid search and lexical fallback in this checkout.
+
+Site search returns links to pages and sections. It is enabled by default and matches words in the browser, with no provider account or server required.
+
+Shoalrun supplies the search box and keyboard controls. A **search provider** supplies results; you can replace the built-in provider with your own module. [Search and chat](https://www.shoalrun.com/search-and-chat.md) explains when to add semantic search or cited answers.
+
+## Lexical search
+
+The built-in provider matches words rather than meaning. It lowercases the query and recognizes phrases declared in `search.synonyms`.
+
+The browser provider ranks matches in this order:
+
+1. Pages containing every query term or its mapped synonym.
+2. If none match completely, partial results ordered by matched term count, then field score.
+
+Common filler words such as “how,” “do,” and “the” do not count toward partial-match coverage. A partial result must match at least one remaining term. This helps sentence-shaped queries but does not infer meaning or handle typos and general stemming.
+
+The [local search command](https://www.shoalrun.com/cli.md) shares the base index and weights, with additional CLI/MCP ranking rules described below.
+
+### Synonyms
+
+Projects can define their own synonym groups of words and phrases. Put them in a YAML file and include it from the site config:
+
+```yaml title="docs.config.yaml"
+search:
+  synonyms: { $include: ./config/search-synonyms.yaml }
+```
+
+The included file lists equivalent words or phrases:
+
+```yaml title="config/search-synonyms.yaml"
+- [walkthrough, "walk through", "code tutorial", tutorial]
+```
+
+Each group works in both directions. Exact word or phrase matches rank above synonym matches. A term can belong to only one group; groups need at least two distinct terms. Phrase matching respects word boundaries, so `walk through` is treated as one term. Shoalrun validates the file during config loading and includes its mapping in `/search-index.json` and `ai/chunks.json`. Browser search, `shoalrun search`, and lexical passage retrieval for chat share that vocabulary. Rebuild the site and passage index after editing the file. Custom search providers must read the mapping from `/search-index.json` if they want to apply it to their own results.
+
+### Result ordering and limits
+
+Pages rank by where the terms appear:
+
+1. Title, highest when the title starts with the term.
+2. Summary.
+3. Section headings.
+4. Body text.
+
+The built-in lexical provider returns at most one result per page. It adds a section link when every query term matches one section heading and the query is not already a title match. With a reader view selected, it returns page links because the unfiltered heading list may include hidden sections. Custom providers can return multiple section results from the same page.
+
+The list shows the top eight results. The provider downloads the index once, on first focus, and searches only pages in the reader's channel, version, and language. When [reader views](https://www.shoalrun.com/author/reader-views.md) are configured, it also excludes pages and marked section text outside the selected view. The local CLI search command reads the full index and does not apply a browser's saved view.
+
+The navigation sidebar has a separate filter. Its optional node-level `search` terms help readers find menu items; they do not change `/search-index.json` or masthead results. See [Organize site navigation](https://www.shoalrun.com/author/navigation.md).

package/agent-docs/author/search.sections/local-semantic-preview.md

@@ -0,0 +1,43 @@
+---
+id: guide.search
+title: Site search
+summary: Search settings, keyboard behavior, provider interfaces, and index fields.
+type: reference
+area: discovery
+subarea: discovery-search
+canonical: /author/search
+---
+
+# Site search
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Search and chat > Site search
+
+**Updated: 2026-10-26.**
+
+**Verified: 2026-10-01.**
+
+Parent page: [Full Markdown page](/author/search.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Next steps**
+
+- [Preview semantic search in this checkout](https://www.shoalrun.com/recipes/preview-hybrid-search.md) — Build the passage index and verify hybrid search and lexical fallback in this checkout.
+
+Site search returns links to pages and sections. It is enabled by default and matches words in the browser, with no provider account or server required.
+
+Shoalrun supplies the search box and keyboard controls. A **search provider** supplies results; you can replace the built-in provider with your own module. [Search and chat](https://www.shoalrun.com/search-and-chat.md) explains when to add semantic search or cited answers.
+
+## Local semantic preview
+
+The optional search endpoint uses vector similarity when current query and passage embeddings are available. It falls back to keyword passage search if vectors are unavailable, the provider fails, the budget is exhausted, or the deadline expires.
+
+For dotted configuration keys or command flags, the endpoint can add an exact-identifier explanation as the third result. It must contain every requested identifier in prose; tables, code listings, and identifier prefixes do not qualify. The first two semantic results stay in place. File-name queries and requests for fewer than three results keep semantic ranking.
+
+Result snippets prefer prose matching the substantive words in your question, omit generated discovery text, and keep a matching term visible in a long paragraph. Code-only and table-only passages use the page summary.
+
+[Preview semantic search in this checkout](https://www.shoalrun.com/recipes/preview-hybrid-search.md) covers the embedding provider key, passage index, local endpoint, lexical fallback, and Network inspector checks.

package/agent-docs/author/search.sections/read-a-search-result-with-an-agent.md

@@ -0,0 +1,41 @@
+---
+id: guide.search
+title: Site search
+summary: Search settings, keyboard behavior, provider interfaces, and index fields.
+type: reference
+area: discovery
+subarea: discovery-search
+canonical: /author/search
+---
+
+# Site search
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Search and chat > Site search
+
+**Updated: 2026-10-26.**
+
+**Verified: 2026-10-01.**
+
+Parent page: [Full Markdown page](/author/search.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Next steps**
+
+- [Preview semantic search in this checkout](https://www.shoalrun.com/recipes/preview-hybrid-search.md) — Build the passage index and verify hybrid search and lexical fallback in this checkout.
+
+Site search returns links to pages and sections. It is enabled by default and matches words in the browser, with no provider account or server required.
+
+Shoalrun supplies the search box and keyboard controls. A **search provider** supplies results; you can replace the built-in provider with your own module. [Search and chat](https://www.shoalrun.com/search-and-chat.md) explains when to add semantic search or cited answers.
+
+## Read a search result with an agent
+
+CLI and MCP search results include a ready-to-use `read` instruction: call `read.tool` with `read.arguments`. This selects `get_section` only when one eligible, author-declared standalone section heading matches the query after common English request wording and page-title context are removed. CLI/MCP ranking favors complete multiword matches to eligible section headings over incidental page-title words. Broad, ambiguous, cross-section, or undeclared-section queries select `get_page`. No outline request is needed first.
+
+The result's `markdownUrl` points to the recommended section or page, with its byte/token size when available. `pageMarkdownUrl` always points to the full page. Use that fallback when more context is needed. This is a lexical recommendation, not proof that the selected content answers the question. Page reads can still truncate at the maximum budget; inspect their budget metadata.
+
+Section resources exist only for pages of at least 2,000 `cl100k_base` tokens and only when they halve both bytes and tokens, including repeated context. Both search indexes include eligible section titles, URLs, sizes, and any `standalone: true` declaration without duplicating section bodies. Fetch-only agents should start with `/llms.min.txt`, which links to full pages and declared standalone sections, directly or through topic indexes. Each compact index is limited to 2,000 `cl100k_base` tokens; growing topics split automatically. Standalone links retain sizes and full-page fallbacks. The larger compact JSON index is optional when more headings are needed. The human search box continues to open HTML page or heading links. See [Markdown section resources](https://www.shoalrun.com/author/markdown-metadata.md).

package/agent-docs/author/search.sections/related-reading.md

@@ -0,0 +1,45 @@
+---
+id: guide.search
+title: Site search
+summary: Search settings, keyboard behavior, provider interfaces, and index fields.
+type: reference
+area: discovery
+subarea: discovery-search
+canonical: /author/search
+---
+
+# Site search
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Search and chat > Site search
+
+**Updated: 2026-10-26.**
+
+**Verified: 2026-10-01.**
+
+Parent page: [Full Markdown page](/author/search.md)
+
+Site search returns links to pages and sections. It is enabled by default and matches words in the browser, with no provider account or server required.
+
+Shoalrun supplies the search box and keyboard controls. A **search provider** supplies results; you can replace the built-in provider with your own module. [Search and chat](https://www.shoalrun.com/search-and-chat.md) explains when to add semantic search or cited answers.
+
+## Related reading
+
+### Next steps
+
+- [Preview semantic search in this checkout](https://www.shoalrun.com/recipes/preview-hybrid-search.md) — Build the passage index and verify hybrid search and lexical fallback in this checkout.
+
+### Reference while working
+
+- [CLI reference](https://www.shoalrun.com/cli.md) — Query a built site's search index without a server.
+
+### Related topics
+
+- [Header links](https://www.shoalrun.com/styling/header.md) — The search box sits in the site header, before your header links.
+
+- [How documentation answers work](https://www.shoalrun.com/chat.md) — Use retrieved passages to produce cited answers instead of page links. (Status: experimental.)
+
+- [Agent authoring, search, and documentation answers](https://www.shoalrun.com/changelog/authoring-search.md) — Configure semantic search and lexical fallback.

package/agent-docs/author/search.sections/reuse-the-lexical-index.md

@@ -0,0 +1,81 @@
+---
+id: guide.search
+title: Site search
+summary: Search settings, keyboard behavior, provider interfaces, and index fields.
+type: reference
+area: discovery
+subarea: discovery-search
+canonical: /author/search
+---
+
+# Site search
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Search and chat > Site search
+
+**Updated: 2026-10-26.**
+
+**Verified: 2026-10-01.**
+
+Parent page: [Full Markdown page](/author/search.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Next steps**
+
+- [Preview semantic search in this checkout](https://www.shoalrun.com/recipes/preview-hybrid-search.md) — Build the passage index and verify hybrid search and lexical fallback in this checkout.
+
+Site search returns links to pages and sections. It is enabled by default and matches words in the browser, with no provider account or server required.
+
+Shoalrun supplies the search box and keyboard controls. A **search provider** supplies results; you can replace the built-in provider with your own module. [Search and chat](https://www.shoalrun.com/search-and-chat.md) explains when to add semantic search or cited answers.
+
+## Reuse the lexical index
+
+Set `index: true` to build `/search-index.json` for a custom provider. Use it to load the pages into a client-side library such as MiniSearch or FlexSearch:
+
+```yaml title="docs.config.yaml"
+outputs:
+  html:
+    search:
+      provider: custom
+      module: ./search/minisearch.js
+      index: true
+```
+
+The generated index contains one record for each published page:
+
+```json title="search-index.json"
+{
+  "schemaVersion": 1,
+  "documents": [
+    {
+      "id": "guide.snippets",
+      "url": "/author/snippets",
+      "markdownUrl": "/author/snippets.md",
+      "title": "Reuse prose across pages",
+      "summary": "Share validated prose across pages with typed variables.",
+      "type": "how-to",
+      "variant": "production|current|en",
+      "headings": [{ "id": "register-a-snippet", "title": "Register a snippet" }],
+      "text": "A snippet is a shared Markdown or MDX fragment…"
+    }
+  ]
+}
+```
+
+The index fields have these limits:
+
+- `headings` covers levels 2 through 4, including headings later in the article.
+- `text` holds the first 5,000 characters of the HTML article as plain text. Body words beyond that limit are not searchable through this field.
+- Titles and the selected summary are indexed separately from body text.
+- A section result links to a heading; it does not mean the section's full body was indexed.
+- `id` and `markdownUrl` let local tools cite the matching page.
+
+When reader views are enabled, `readerFilters` holds page marks and `readerSegments` holds shared and marked text. A custom provider must apply those marks to respect the selected view. The full text remains in the index; reader views do not restrict access to published files.
+
+The browser index comes from the HTML article, including HTML-only blocks and excluding Markdown-only blocks written with [Only](https://www.shoalrun.com/author/components/only.md). It excludes the surrounding header, navigation, and search UI. Marked sections stay in the stored index; the built-in browser provider filters their text when a view is active. Each `readerSegments` text value is capped at 5,000 characters.
+
+The `summary` field uses `outputs.text.search`, or a page’s `displayText.search` override. Without a configured selection, it uses the frontmatter summary. This site selects description before summary. The lexical provider uses the selected text for ranking and result snippets.

package/agent-docs/author/search.sections/turn-search-off.md

@@ -0,0 +1,46 @@
+---
+id: guide.search
+title: Site search
+summary: Search settings, keyboard behavior, provider interfaces, and index fields.
+type: reference
+area: discovery
+subarea: discovery-search
+canonical: /author/search
+---
+
+# Site search
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Search and chat > Site search
+
+**Updated: 2026-10-26.**
+
+**Verified: 2026-10-01.**
+
+Parent page: [Full Markdown page](/author/search.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Next steps**
+
+- [Preview semantic search in this checkout](https://www.shoalrun.com/recipes/preview-hybrid-search.md) — Build the passage index and verify hybrid search and lexical fallback in this checkout.
+
+Site search returns links to pages and sections. It is enabled by default and matches words in the browser, with no provider account or server required.
+
+Shoalrun supplies the search box and keyboard controls. A **search provider** supplies results; you can replace the built-in provider with your own module. [Search and chat](https://www.shoalrun.com/search-and-chat.md) explains when to add semantic search or cited answers.
+
+## Turn search off
+
+Set the provider to `none` to remove the browser search box and its page index:
+
+```yaml title="docs.config.yaml"
+outputs:
+  html:
+    search:
+      provider: none
+```
+
+This removes both the reader search box and its index, so the local search command has nothing to query. Markdown twins, `/llms.txt`, and `/documents.json` do not change with the provider. Agents can still discover and fetch pages, but `shoalrun search` cannot query a missing `search-index.json`. The passage index and semantic endpoint are independent of this browser setting. Changing it does not remove those artifacts or disable a deployed endpoint.

package/agent-docs/author/search.sections/use-the-search-box.md

@@ -0,0 +1,39 @@
+---
+id: guide.search
+title: Site search
+summary: Search settings, keyboard behavior, provider interfaces, and index fields.
+type: reference
+area: discovery
+subarea: discovery-search
+canonical: /author/search
+---
+
+# Site search
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Search and chat > Site search
+
+**Updated: 2026-10-26.**
+
+**Verified: 2026-10-01.**
+
+Parent page: [Full Markdown page](/author/search.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Next steps**
+
+- [Preview semantic search in this checkout](https://www.shoalrun.com/recipes/preview-hybrid-search.md) — Build the passage index and verify hybrid search and lexical fallback in this checkout.
+
+Site search returns links to pages and sections. It is enabled by default and matches words in the browser, with no provider account or server required.
+
+Shoalrun supplies the search box and keyboard controls. A **search provider** supplies results; you can replace the built-in provider with your own module. [Search and chat](https://www.shoalrun.com/search-and-chat.md) explains when to add semantic search or cited answers.
+
+## Use the search box
+
+Press `/` or `Ctrl`+`K` (`⌘`+`K` on macOS) to focus the box. Use the arrow keys to move through results, Enter to open one, and Escape to close the list. When a match falls inside a section, the result names the section and links to its heading.
+
+The box needs JavaScript. Without it, both the search box and sidebar filter stay hidden; the published navigation links still work.

package/agent-docs/author/search.sections/write-a-custom-provider.md

@@ -0,0 +1,98 @@
+---
+id: guide.search
+title: Site search
+summary: Search settings, keyboard behavior, provider interfaces, and index fields.
+type: reference
+area: discovery
+subarea: discovery-search
+canonical: /author/search
+---
+
+# Site search
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Search and chat > Site search
+
+**Updated: 2026-10-26.**
+
+**Verified: 2026-10-01.**
+
+Parent page: [Full Markdown page](/author/search.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Next steps**
+
+- [Preview semantic search in this checkout](https://www.shoalrun.com/recipes/preview-hybrid-search.md) — Build the passage index and verify hybrid search and lexical fallback in this checkout.
+
+Site search returns links to pages and sections. It is enabled by default and matches words in the browser, with no provider account or server required.
+
+Shoalrun supplies the search box and keyboard controls. A **search provider** supplies results; you can replace the built-in provider with your own module. [Search and chat](https://www.shoalrun.com/search-and-chat.md) explains when to add semantic search or cited answers.
+
+## Write a custom provider
+
+A provider is one ES module. It must export `search`, and it can export `prepare`:
+
+```js title="search/hosted.js"
+const endpoint = 'https://search.example.com/query';
+
+// Optional. Runs when the reader first focuses the box.
+export async function prepare({ language }) {
+  await fetch(`${endpoint}/warm?language=${language}`);
+}
+
+export async function search(query, { language, limit, signal }) {
+  const params = new URLSearchParams({ q: query, language, limit: String(limit) });
+  const response = await fetch(`${endpoint}?${params}`, { signal });
+  if (!response.ok) throw new Error(`Search failed: ${response.status}`);
+  const { hits } = await response.json();
+  return hits.map(hit => ({ url: hit.path, title: hit.title, summary: hit.snippet }));
+}
+```
+
+Register the module in the config:
+
+```yaml title="docs.config.yaml"
+outputs:
+  html:
+    search:
+      provider: custom
+      module: ./search/hosted.js
+```
+
+The `module` path resolves from the config file that declares it. The module is a build dependency, so a rebuild picks up changes.
+
+### Search context
+
+The search box passes a context object to both functions.
+
+| Field             | Value                                                                                                                                                     |
+| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `variant`         | The page's channel, version, and language, joined by `\|`, such as `production\|current\|en`.                                                             |
+| `language`        | The page's `lang` value.                                                                                                                                  |
+| `indexUrl`        | The base-path-prefixed `/search-index.json` URL. The file exists only when the build writes an index.                                                     |
+| `limit`           | The maximum number of results the box shows.                                                                                                              |
+| `signal`          | An `AbortSignal`, passed to `search` only. It aborts when the reader types again.                                                                         |
+| `readerSelection` | The active reader view as facet IDs mapped to arrays of choice IDs. An empty object means show all. Custom providers must use it to filter their results. |
+
+Pass `signal` to `fetch` so stale requests stop. The box ignores results from an aborted search.
+
+### Search results
+
+`search` returns an array, or a promise of one. Each result is an object:
+
+| Field     | Required | Value                                                                      |
+| --------- | -------- | -------------------------------------------------------------------------- |
+| `url`     | Yes      | A site-root path or `http(s)` URL. Add `#heading-id` to link to a section. |
+| `title`   | Yes      | The page title.                                                            |
+| `summary` | No       | One line of supporting text.                                               |
+| `section` | No       | A section title, shown after the page title.                               |
+
+The box drops results without a valid `url` and `title`, and it keeps the first `limit` results. It escapes all text and highlights query terms itself. If `search` throws, the box shows "Search is unavailable right now."
+
+### Module limits
+
+The build copies one file. It does not copy files that the module imports with relative paths. Bundle the provider into one file, or import dependencies from absolute URLs.

package/agent-docs/author/snippets.md

@@ -0,0 +1,118 @@
+---
+id: guide.snippets
+title: Reuse prose across pages
+summary: Share validated prose across pages with typed variables.
+type: how-to
+area: authoring
+subarea: authoring-composition
+canonical: /author/snippets
+---
+
+# Reuse prose across pages
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Reusable snippets
+
+**Updated: 2026-10-26.**
+
+A snippet is a shared Markdown or MDX fragment that the build expands into each page that includes it. Use one when the wording must stay in sync across pages. A [template](https://www.shoalrun.com/author/templates.md) creates a draft once; editing a template does not change existing pages.
+
+## Register a snippet
+
+Import a `snippets` mapping in project config. Snippet IDs are dot-separated names, such as `authoring.build-check`. Each entry points to a plain `.md` or `.mdx` file and declares its variables:
+
+```yaml filename="docs/config/snippets.yaml"
+authoring.build-check:
+  file: ../snippets/build-check.mdx
+  variables:
+    command: { type: string, required: true }
+```
+
+The snippet file uses `<Var name="command" />` in prose:
+
+```mdx filename="docs/snippets/build-check.mdx"
+<Callout label="Check the result">Run <Var name="command" /> after editing. Confirm the HTML page and Markdown twin contain the same resolved snippet text.</Callout>
+```
+
+A page includes it with literal values:
+
+```mdx filename="docs/content/snippets.mdx"
+<Snippet id="authoring.build-check" values={{ command: "npm test" }} />
+```
+
+## See a variable resolve
+
+The example project has a second snippet with two variables:
+
+```yaml filename="example/config/snippets.yaml"
+payment.request-prep:
+  file: ../snippets/request-prep.mdx
+  variables:
+    product: { type: string, required: true }
+    header: { type: string, default: Idempotency-Key }
+```
+
+Its source file contains ordinary MDX prose:
+
+```mdx filename="example/snippets/request-prep.mdx"
+For <Var name="product" /> requests, choose a unique
+<Var name="header" /> and provide the amount in minor currency units.
+```
+
+The guide supplies `product` and leaves `header` at its declared default:
+
+```mdx filename="example/content/create-payment-guide.mdx"
+<Snippet id="payment.request-prep" values={{ product: "Payments" }} />
+```
+
+Readers and agents get resolved text in their respective page formats:
+
+> For Payments requests, choose a unique Idempotency-Key and provide the amount in minor currency units.
+
+The real snippet also includes a nested retry note. It inherits `product` from the outer snippet. See `example/snippets/request-prep.mdx` and `example/content/create-payment-guide.mdx` in the repository.
+
+This page uses that snippet below, so the published HTML and Markdown exercise the same expansion.
+
+> **Check the result:** Run npm test after editing. Confirm the HTML page and Markdown twin contain the same resolved snippet text.
+
+Values can be strings, numbers, or booleans. A variable can also list allowed values with `enum`, such as `tier: { type: string, enum: [free, pro] }`; its `default` must be one of them.
+
+Snippet defaults, project variables, page variables, and invocation values apply in that order. Set project variables in the top-level `variables` mapping of `docs.config.yaml`, and page variables in a page's `variables` frontmatter:
+
+```yaml title="docs.config.yaml"
+variables:
+  product: Payments
+```
+
+Unknown names, missing required values, wrong types, and recursive includes stop the build. The document manifest lists snippet IDs used by each page.
+
+For this slice, snippets use inline `<Var />` in prose. Code blocks are never changed by string replacement. Put headings in the page, and use absolute or `doc:` links inside snippets. These limits avoid ambiguous anchors and broken relative links until their adapters are built.
+
+## Component attributes
+
+`<Snippet>` is a standalone empty element in a page or registered snippet. `<Var>` is an inline empty element inside a snippet file; using it directly in a page fails the build.
+
+| Element     | Attribute | Required | Meaning                               |
+| ----------- | --------- | -------- | ------------------------------------- |
+| `<Snippet>` | `id`      | Yes      | Registered snippet ID.                |
+| `<Snippet>` | `values`  | No       | Literal mapping of invocation values. |
+| `<Var>`     | `name`    | Yes      | Variable declared for that snippet.   |
+
+The included Markdown and supported MDX components render in both HTML and Markdown. Nested snippets work, but recursive includes fail. API embeds need page-level headings and cannot be placed inside snippets. Keep headings in the page, and use absolute or `doc:` links in snippets.
+
+## Check the shared text
+
+Build your project and open each page that includes the snippet. Confirm that HTML and Markdown both contain the resolved text and that no variable tags remain. Change the snippet source and rebuild; every including page should receive that change. If validation fails, correct the named variable, include, or type before publishing.
+
+## Related reading
+
+### Reference while working
+
+- [Configuration reference](https://www.shoalrun.com/config.md) — Look up the snippets and variables settings.
+
+### Often confused with
+
+- [Templates](https://www.shoalrun.com/author/templates.md) — A template is copied into a new page once; a snippet is shared prose that stays in sync on every page that includes it.