How it works

Map mode is the product. Your site declares nothing in code. A site map on our server says what your filters are and how they land; the widget turns that map into the same six tools on every site, and the same one script tag works everywhere.

The request, in one picture

Visitor talks to the widget, the widget and our API run the conversation, a tool call becomes a command the page itself runs, and the answer travels back the same way. Visitorclicks, then speaks The widgetthe orb, in the browser Our APIsession + your site map Tool webhookapi/tool/[name] Your pageyour own filters, unchanged speaks opens a call calls a tool a command, waiting the page runs its own handler, the widget reads the result, and Gerry speaks the answer — the server never touches the page (SECURITY.md #1)

The site map

One document per tenant, validated before it is stored. It holds intent, not layout: which filters exist, what people call them out loud, how each one lands in the site's own address, how to read the results. It is drafted for you, edited in the panel, and fetched once by the widget at the start of a conversation — the site itself never asks for it. See the full site map reference.

Six tools, always the same, plus one built in

The engine builds these from the map, and the server derives the same six from the same map, so the model can never call a tool the page cannot run.

apply_filterSets one filter to one value. "Stainless", "under three hundred", "diesel".
clear_filterRemoves one filter, or all of them.
result_statusReads how many results are on screen and which filters are active.
summarize_listingReads the visible rows: title, price, link, the small print. "Open the third one" opens the third one on the screen.
open_listingOpens one result by its position or its title.
sort_resultsSorts by one of the site's own sort tokens. Offered only when the map has a sort block.
page_contextBuilt in, on every tenant. The page's title, its path, and any element you marked with data-katman-context. Nothing else — see Security & privacy, rule 5.

A tenant with no site map, on a page that declares no actions, still mounts the widget with page_context alone — Gerry can talk about the page even before a map exists.

How a filter lands in the address

Through the most stable layer the site has, in this order — the full mechanics, including what happens when the page can't be swapped in place, are in How a filter is applied:

  1. The address itself. A query parameter, a min/max pair, a dash-joined path slug, or an ordered path segment. Sites keep these for years, for search engines and shared links.
  2. The site's own filter panel, read live at session time. New options appear with no map change; a filter marked facet is resolved against the panel by its label and applied by following the link the site itself already wrote — Gerry never invents a URL for one of these.
  3. DOM selectors, last, and only for reading results — never for applying anything — behind structured data (schema.org JSON-LD) and text patterns.

What speech-to-text gets wrong

Choice filters carry a closed dictionary of values with spoken aliases. The model hands over "folksvagen"; only a closed list turns that into "Volkswagen", or into an honest "I didn't catch that". A tie between two close values asks instead of guessing. A filter that needs another one set first — a model with no brand — is dropped and reported, never guessed at.

When your site changes

You update nothing. Because filters land through the address and the live panel, a redesign usually changes nothing for Gerry. When something does stop working, a nightly check catches it (see Checks) and Gerry degrades to "I can't do that on this page" rather than failing outright.

Questions: hello@heygerry.io. These pages describe what is built today; nothing here is a promise about what is not.