How the Guide works — the whole story

1. The one idea: it chooses, it never generates

Most "AI chat" products work by generating text: a large language model writes a new answer, word by word, every time. That's powerful — and it's why those products can say things nobody approved, invent pages that don't exist, and cost money on every message.

The Guide works the other way around. It never writes a sentence. It chooses — from two things you control completely:

• A script — every line it can say, written with you and approved by you.
• Your pages — an index of your real site; the only things it can ever point to.

The intelligence is in the choosing: understanding a vague, human question well enough to pick the right line and the right page. We call this authored voice, computed understanding.

2. A walkthrough: one real question

Say a visitor at Maplewood types:

What actually happened, in order:

• The message is checked against safety and social patterns first (more on this below — it always runs first).
• It isn't a greeting, a question about the guide, or a scripted small-talk topic — so it goes to routing.
• Every page in the site index is scored against the words: "family" and "tickets" match the Family pass page's title and keywords strongly; "five" matches nothing and is ignored.
• The best match clears a confidence floor — weak, coincidental word overlaps are rejected rather than guessed at — so the Guide answers with an approved lead-in line plus the page card.
• If nothing clears the floor, it says so honestly and offers directions — it never bluffs.

3. The layers, in the order they run

Routing is actually the fifth thing that happens to a message. The pipeline is a fixed sequence of layers, and the order is deliberate: the most important things claim the message first.

Why safety runs first: if a visitor — often a young one, on a family site — types something that signals real distress, the Guide drops the tour-guide act entirely and offers real help lines. That check happens before anything else can claim the message, it's tested by an automated suite of regression cases we run before every release, and it never depends on any AI model. This is the part that makes the Guide shippable on a children's brand.

4. What it knows: the pack

Everything the Guide knows about a site lives in one reviewable bundle we call the pack. For Maplewood it contains three kinds of things:

{
  "index": [   // one entry per page — the ONLY destinations it can offer
    { "t": "Family pass",
      "u": "/tickets/family-pass",
      "s": "Tickets",
      "k": ["family", "children", "price", "pass"] },
    …
  ],
  "guide": {  // the hand-curated tour: categories + featured pages
    "cats": ["Tours", "Tickets", "Animals", …], "featured": [ … ] },
  "lines":   { /* every sentence it can say — written with you */ },
  "bank":    { /* your authored answers: "what are your hours?" → your line + your page */ }
}

The pack is compiled together with the Guide's engine into one static file — the single <script> tag you add to your site. There is no database, no content server, no account system. Your web page is the deployment.

5. How we learn your site (and what we don't take)

We build the index by reading your public pages once, the way a search engine does, but far more politely: we identify ourselves, fetch slowly, respect your robots rules, and read only titles, addresses, headings and description lines — facts about your pages, never copies of them. Nothing of your site is rehosted; every card the Guide shows opens your real page.

Then comes the human pass — the part that's craft, not crawling: we fix titles, choose the tour categories, pick the featured pages, and write the voice with you. When your site changes, we re-read it on a schedule and refresh the pack.

6. You write the script — that's the point

Clients sometimes ask, carefully, whether they can be involved in what the Guide says. The answer is that it doesn't work any other way: the script is yours. In onboarding we draft the greetings, the small talk, and answers to the questions your visitors actually ask — in your brand's voice — and nothing ships until your team has approved every line. You can read the entire script; that's precisely the property your legal and brand teams will like most.

After launch, the Guide's misses become a monthly list of what visitors asked for and didn't find — which tells you which lines (or which pages) to add next. The script grows with you.

7. English and French: two brains, one engine

The French Guide is not a translation layer bolted on top. The engine is shared, but every language-dependent part exists separately per language: the script, the question patterns, and — most importantly — the safety layer. French grammar negates differently, French distress has its own idioms, and French visitors deserve the same care as English ones. So the French safety patterns are built and tested in French, with their own automated regression suite, and the French help lines are the right ones for francophone visitors.

8. The optional "understanding" upgrade

Everything above uses word matching — fast, predictable, and surprisingly capable once the keywords are curated. There is an optional module that adds understanding by meaning: "we're bored and it's raining" finding the indoor activities page even though no words overlap.

Why meaning-matching is only ever allowed to route pages — the negation problem. Embedding models are famously blind to negation: they encode what a sentence is about far more strongly than which way it points. We measured this on the exact model we'd ship:

For page routing this hardly matters — "I don't want a family pass" still belongs in the tickets neighbourhood, and a slightly-wrong card costs one click. But look at the last row: for anything involving how a person feels, this blindness would be catastrophic. That is why, by architectural rule, the safety layer never touches embeddings: distress, and every emotional turn, is handled by the deterministic first layer with hand-built, per-language negation guards ("I do not want to…" structurally cannot trip it), each protected by its own automated test suite. The geometry is allowed to answer what is this about — never how does this person feel about it.

9. What it deliberately can't do

• It can't answer open questions ("what year was the museum founded?") — it routes to the page that answers, or says honestly that it doesn't have it. If you need ticket-deflection Q&A, we'll say so and point you to that category of product instead.
• It can't improvise, roleplay, or be talked out of its script — there's no generator to jailbreak.
• It can't send anything to SpecEnvoy — we operate no servers it could talk to. What it remembers (a name, a preference, at the visitor's request) lives in that visitor's own browser. If you enable measurement, usage events go to your analytics only — see the pilot page for exactly what and where.

See it live in the demos → · Frequently asked questions →