البحث في المعرفة

The knowledge widget searches the same index your chat uses. It does not crawl or embed your site a second time. Configure it in Console → Knowledge search. Changes save automatically; Undo writes the previous settings back. A revision conflict asks you to reload instead of overwriting another editor's changes. No chat publish is needed.

Before enabling

Review the Page index and the coverage note in Knowledge search. Select all indexed knowledge, published knowledge, or connected sources. Enabling this product makes those sources searchable by visitors. Excluded pages remain excluded by the existing retrieval reader.

Add your site's exact origin to the workspace's allowed embed origins. The knowledge widget uses that same origin list, with its own enable switch. An unknown origin cannot frame it. There is no wildcard framing policy.

Install

Copy the snippet shown by your Console. Its hostname belongs to your workspace:

<script defer src="https://YOUR-WORKSPACE.busymate.ai/kb/v1.js"
  data-hotkey="mod+k" data-slash="false" data-trigger="keyboard"></script>

The loader installs listeners only. It does not fetch configuration, create an iframe, read storage, or download the palette until the first trigger. An optional floating button is created locally. Recopy the snippet after changing trigger settings: fetching them before opening would violate the zero-eager-network contract.

Triggers and JavaScript

mod+k means Command+K on Apple platforms and Control+K elsewhere. Custom chords use mod, ctrl, meta, alt, and shift, followed by one letter or digit; for example alt+shift+p. / is optional. Keyboard shortcuts are ignored while composing text or editing an input, textarea, select, contenteditable element, or textbox.

<button type="button" data-busymate-kb-trigger>Search documentation</button>
<input data-busymate-kb-trigger aria-label="Search documentation">

window.BusymateKB.open("billing");
window.BusymateKB.close();
window.BusymateKB.configure({ hotkey: "alt+k", slash: true, trigger: "floating", label: "Search" });

open() takes an optional string, the query to start with (up to 500 characters). Any other value, such as the event an inline handler passes, opens the palette empty.

The palette opens centred over the page, which is dimmed and blurred behind it; at 640 px and below it is a full-height sheet. The modal and its stylesheet live in a shadow root on a <busymate-kb> element the loader appends to your page, so your site's CSS resets and dialog rules never reach it and its rules never reach your page. With nothing typed it offers Actions (Search the docs, Ask your mate), Go to (your site's top indexed pages, shallowest first) and Recent searches, whose last row is Clear recent searches. Typing shows results grouped by page with snippets, the cited answer as a row of its own group when enabled (Enter opens its source), and Ask your mate about this as the last row; until the first results arrive, Enter keeps searching rather than handing off. Use ↑/↓ to move, Tab and Shift+Tab to jump between groups, Enter to run the highlighted row (a result opens in a new tab, a Go to destination opens in the page), and Escape to close. Every row, the answer and Clear included, is an option of one listbox, so screen readers reach all of them from the search field. The native modal keeps focus inside the palette and returns it to the opener on close. Recent searches are stored locally; a browser that blocks storage still supports search.

Results and answers

Hybrid retrieval combines lexical and semantic ranking over the existing index. Results are grouped by page: a page whose title, top heading or address names the query ranks first, a page shows at most two sections, and a copy of a page in another language gives way to the copy in the language the search names (lang), else to the unprefixed copy. Each row is titled by its section and shows the sentence that matched. A match by meaning alone, with none of the query's words, needs strong similarity to appear. Results without a safe HTTP(S) page URL are omitted. The optional short answer quotes an excerpt and links its source; it needs both the query's words and a close match in meaning, so weak, lexical-only or meaning-only evidence produces a refusal, not an invented answer. Search failures are distinct from zero matches.

Ask your mate about this opens the workspace chat with the query prefilled for review. It does not automatically send a message.

API and MCP

The browser palette calls the tenant host:

POST /api/v1/kb/search
Content-Type: application/json
Accept: text/event-stream

{"query":"billing"}

Anonymous scope comes from the serving host, never tenant_id in the body. Admission is shared across server replicas: 30 requests per visitor IP bucket per minute, and 600 per tenant per minute. No IP address or query text is stored in the events trail. A refused budget returns 429 with Retry-After; retrieval or configuration outages return 503.

With Accept: application/json, search returns {query, results, answer, refused, searchId}. Each result has id, title (the section), url (the page, with a text fragment to the matched words where there is one), snippet, group (the page title), score, pageUrl (the page itself; group by this, since two pages can share a title), section (null for a page's introduction) and highlights ([start, end] offsets of the query's words in snippet). The score is relevance relative to the first result, which scores 1; it never increases down the list. An answer is {text, citation} or null. SSE sends results, optional answer chunks, then done. An optional lang in the request body (the page's language, which the loader sends for you) picks the matching copy of a page.

Workspace API keys use the existing REST/MCP facade and its {ok, data} response envelope. search_knowledge, get_kb_widget_config, and set_kb_widget_config are the corresponding MCP tools. Management calls are tenant-authorized; writes require confirmation and an expected revision. REST configuration is GET /api/v1/kb/config and POST /api/v1/kb/config. Never expose an API key in the install tag.

The public palette exposes search_knowledge as a WebMCP page tool when the platform's WebMCP provider is enabled and the browser supports it. It uses the same HTTP endpoint and limits.

Appearance, language and measurement

The palette follows the page it opens on. Its theme is, in order: the page's own explicit choice (data-theme="light|dark" on <html>, or a dark / light class on it, the way most site toggles pin it), then the Appearance setting in Console (Light or Dark; System means "follow the page"), then the operating system. The Console setting is read by the palette itself every time it opens, so a change in Console applies at once; nothing about appearance is written into the snippet, and there is nothing to recopy. Its language is the page's <html lang>, then the data-lang on the install tag, then the visitor's browser preference. Both are read when the palette opens, so the first paint already matches, and both are re-applied without a reload if the page changes them while the palette is open: the loader watches the <html> attributes and the storage event, so a theme toggle or a language switch on the page reaches the open palette at once. A page that sets its language in JavaScript without touching <html> can pass it directly:

window.BusymateKB.configure({ lang: "de" });

The palette uses the app's semantic theme tokens and tenant branding. The host page's CSS does not cross the iframe boundary.

The closed events are kb.search.performed, kb.result.clicked, kb.zero_results, and kb.handoff_to_chat. Each may carry a surface attribute, marketing or docs, naming which of this site's own pages opened the palette; a palette on your site never sends it. Authenticated Console previews and management MCP/API searches are excluded.

On this site

This site runs the same widget, bound to the platform workspace and driven by its own Console settings: the Search field in the header (an icon on phones) and the configured shortcut open the palette on every page, including this documentation. Its Go to group lists this site's own navigation. Nothing beyond the loader is downloaded until you open it. Ask your mate about this hands the query to the chat launcher in the corner of the page, prefilled for review; Ask your mate with nothing typed simply opens the launcher. The metric catalogue reserves kb_searches, kb_zero_result_rate, kb_click_through, and kb_handoffs; their aggregate readers and Insights pages are phase 2, so unavailable totals are never displayed as zero.

This guide has the standard Markdown twin at /docs/guides/knowledge-widget.md.