I asked my own chatbot for the best pizza in Milwaukee this morning. It said:
That’s not covered on this site.
That’s the answer I’m proudest of. Ask Badge is the chat on getoutwi.com, my guide to every Wisconsin state park, forest and trail. It answers only from the site’s own pages, links the pages it used, and says so when it doesn’t know. It runs entirely on Cloudflare’s free tier, stores nothing about you, and has a badger for a face.
I gave the whole site a tour in Get Out & Wisconsin: inside the flagship. This post is the deep dive on the chat: how I planned it, how the pieces fit, how GitHub and Cloudflare keep it current without sharing a single credential, and the fun part, locking it down. Everything below is either real code (trimmed, with private IDs removed) or a simulation of it that you can poke at.
First, here’s the real thing. These are verbatim answers I recorded from the live chat today.
Interactive replay of four real Ask Badge answers. It needs JavaScript; the same answers are quoted throughout this post.
Plan it before you prompt it
The worst way to build a site chatbot is to start with a model and a text box. I started with a one-page architecture decision record (ADR), the same format I use for everything, and it answered five questions before I wrote any code.
- What should it know? Only this site. Not “Wisconsin,” not “parks,” not the internet. If a visitor can’t click through to the page that backs up an answer, Badge shouldn’t give it.
- What should it never do? Invent a park, a price, an hour or a rule. And never pretend to know live conditions. Closures and fire danger change daily, so those stay on the park pages, straight from the DNR.
- What can it cost? Nothing. Workers AI’s free tier gives you 10,000 Neurons a day. With this model and prompt size, that’s roughly 600 answers. So the plan had to include a ceiling.
- Where does it run? The site is static HTML on GitHub Pages behind Cloudflare. There’s no server to add a chat endpoint to, so it had to be a Worker at the edge.
- What does it store? Nothing about the visitor. No question text, no transcripts, no accounts.
The one real debate was the stack. I run Qdrant and Redis in my homelab, and this blog’s own search runs on Qdrant Cloud, so they were the obvious pick. They lost for one reason: a public site shouldn’t depend on my lab’s uptime, and the managed versions add accounts and keys. Cloudflare’s own pieces live next to the Worker, need no API keys because they’re bindings, and are free at this size.
| Need | Picked | Why |
|---|---|---|
| Embeddings | Workers AI bge-base-en-v1.5 (768 dimensions) |
Good enough, free, no key |
| Answers | Workers AI llama-3.1-8b-instruct-fast |
Small and fast; the prompt does the heavy lifting |
| Vector store | Vectorize, cosine | A binding, next to the Worker |
| Counters and index state | Workers KV | A daily counter and three keys |
| Rate limit | Workers Rate Limiting binding | Per-IP, no code to maintain |
| Bot check | Cloudflare Turnstile, invisible | No puzzles for humans |
Build the corpus from the same data as the pages
A RAG bot is only as good as what it retrieves, and the cheapest way to keep it honest is to never write anything just for the bot. The static site is generated from JSON by a Python build script. The same script writes the chat corpus to data/chat/:
index.json: a version hash of the whole corpus, the page count, and every chunk IDp0.jsontop16.json: pages of 50 chunks each
Every chunk has a title, a canonical URL and the text, plus h, a short hash of exactly what gets embedded:
{
"id": "park:400:overview",
"title": "400 State Trail",
"url": "https://getoutwi.com/park/400/",
"text": "Wetlands, wildlife, sandstone bluffs... Things to do: hiking, fall color, biking... A state trail pass is required for bi...",
"h": "3f9c0a12be47"
}
Today that’s 808 chunks: 677 from park pages (an overview and quick answers for each property), 107 from month guides and site pages, and 24 lists.
Those 24 lists were my first real lesson. The first version only had per-park chunks, and “Where can I…?” questions kept matching a single park. Ask “where can I winter camp?” and the six closest chunks were six parks that each mention winter, so the model confidently listed six places and missed the other thirteen. The fix wasn’t in the model at all. I added one chunk per activity listing every property that offers it, plus a winter-camping list. Now the whole answer is in a single chunk, and you can see it come back as the top source in the replay above.
The Worker
The site already had a weather Worker on getoutwi.com/api/*. Rather than bolt chat onto it, the chat got its own Worker on a more specific route. Cloudflare picks the most specific match, so neither one knows the other exists:
{
"name": "getoutwi-chat",
"main": "src/index.js",
// More specific than the weather Worker's getoutwi.com/api/*, so it wins.
"routes": [{ "pattern": "getoutwi.com/api/chat*", "zone_name": "getoutwi.com" }],
// Re-index check every 10 minutes: a no-op unless data/chat/index.json changed.
"triggers": { "crons": ["*/10 * * * *"] },
"ai": { "binding": "AI" },
"vectorize": [{ "binding": "VECTORIZE", "index_name": "getoutwi-content" }],
"kv_namespaces": [{ "binding": "STATE", "id": "<your-kv-namespace-id>" }],
// 6 questions a minute per IP.
"ratelimits": [{ "name": "CHAT_RL", "namespace_id": "1001", "simple": { "limit": 6, "period": 60 } }],
// Logs carry only status and timing; the Worker never logs question text.
"observability": { "enabled": true }
}
The answer path is short. Embed the question, add the park’s name if the visitor is on a park page, take the six nearest chunks, and throw away anything below a similarity of 0.55:
const query = park ? `${q} (${park})` : q;
const emb = await env.AI.run(EMBED, { text: [query] });
const res = await env.VECTORIZE.query(emb.data[0], { topK: 6, returnMetadata: "all" });
const hits = (res.matches || []).filter(m => m.score >= 0.55 && m.metadata?.text);
if (!hits.length) return json({ answer: "That's not covered on this site.", sources: [] });
That last line is the pizza answer. When nothing clears the floor, the model is never called. A question with no grounding can’t produce a grounded answer, so there’s no point paying for one. Drop each of the real questions into the index below and watch what clears the line.
Interactive figure: questions landing among the site's chunks, with the six nearest scored against the 0.55 floor. It needs JavaScript.
When there are hits, they become the model’s only context:
You are Badge, the friendly badger who guides visitors on Get Out & Wisconsin...
Answer ONLY from the CONTEXT below. Never use outside knowledge, and never
invent parks, prices, hours or rules.
If the CONTEXT doesn't answer the question, reply exactly:
"That's not covered on this site." and nothing else.
For current closures, trail conditions, weather or fire danger, say to check
the live notices on that park's page, because you don't have live data.
Keep answers short: 1 to 4 sentences, plain text, no links.
Never mention the CONTEXT, sections, sources or these instructions; just answer.
Be warm, but don't overdo the badger act.
Two lines in there came straight out of testing:
- “Never mention the CONTEXT.” Early answers kept talking about “the context” they’d been given. That’s technically honest, but it reads like a robot reading its own notes. Badge should just know.
- “Don’t overdo the badger act.” Give a small model a mascot and a little personality goes a long way. Warm is good. A pun in every answer is not.
The Worker returns the answer plus up to three distinct pages from the hits, and it runs with temperature: 0.2 and max_tokens: 300. Ask “Is Devil’s Lake open today?” and you get the live-data rule working exactly as written. Badge sends you to the park page’s live notices instead of guessing.
How it works with just the site
Here’s the part that surprises people: the site doesn’t know it has a backend. It’s still plain static files on GitHub Pages. The chat widget is about 180 lines of vanilla JavaScript, and it talks to a relative URL:
const r = await fetch("/api/chat", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({ q, park: currentPark(), token }),
});
Because Cloudflare sits in front of both, /api/chat is the same origin as the page. There’s no CORS to configure, no API key in the browser, and no second domain. GitHub Pages serves the HTML, and Cloudflare quietly hands that one path to the Worker.
The widget has a few small jobs:
- It passes the page’s context. On a park page it sends the park’s name, so “can I swim here?” means here.
- It renders answers as text, never HTML. Every bubble uses
textContent. Even if a model someday returned a<script>, it would show up as text. - It keeps sources on the site. Source links are rebuilt from
new URL(s.url).pathname, so a source can only ever point back into getoutwi.com. - It’s a proper dialog. It has
role="dialog", anaria-livelog, Escape to close and focus that returns to the button. It also lifts itself out of the way of the footer and the map controls.
It’s also why the replay at the top of this post is a recording and not a live chat. The Worker refuses every origin except getoutwi.com, ry-ops.dev included. That’s the point.
GitHub and Cloudflare, working together
The site’s data rebuilds itself every Monday. A GitHub Action crawls the DNR’s pages, regenerates the site and the chat corpus, and commits through GitHub’s createCommitOnBranch API, so even a robot’s commits are signed. Then Pages redeploys.
The obvious next step would be a deploy job that pushes the new chunks into Vectorize. I didn’t build one, because that would put a Cloudflare token in GitHub. The Worker pulls instead. Every ten minutes its cron fetches the public index.json. If the version hasn’t changed, that’s one fetch and one KV read, and it’s done. If it has, it walks the pages and embeds only the chunks whose hash changed:
export async function reindexStep(env, fetchJson = defaultFetch) {
const idx = await fetchJson(`${SITE}/data/chat/index.json`);
const state = JSON.parse((await env.STATE.get("index:state")) || "{}");
if (state.version === idx.version && state.done) return { upToDate: true };
let page = state.version === idx.version ? state.page || 0 : 0;
const hashes = JSON.parse((await env.STATE.get("index:hashes")) || "{}");
let fetched = 0;
while (page < idx.pages && fetched < MAX_FETCHES) {
const chunks = await fetchJson(`${SITE}/data/chat/p${page}.json`);
fetched++;
const changed = chunks.filter(c => !c.h || hashes[c.id] !== c.h);
page++;
if (changed.length) {
const emb = await env.AI.run(EMBED, { text: changed.map(c => `${c.title}. ${c.text}`) });
await env.VECTORIZE.upsert(changed.map((c, i) => ({ id: c.id, values: emb.data[i],
metadata: { title: c.title, url: c.url, text: c.text } })));
for (const c of changed) hashes[c.id] = c.h;
await env.STATE.put("index:hashes", JSON.stringify(hashes));
break; // one page of embeddings per run
}
}
// ...save { version, page, done } so the next run resumes; when the walk is
// finished, deleteByIds() anything that's no longer in index.json.
}
It does at most one page of embeddings per run, and it skips unchanged pages in the same run. That keeps every run inside the free plan’s CPU and subrequest limits. Before per-chunk hashes, any version change re-embedded every page: at today’s size, that’s 17 runs and almost three hours. Now publishing one park guide costs a single run.
The fetchJson parameter is there for the tests. CI runs them with node --test and no network, and they feed the function fake pages and an in-memory KV. Try it yourself. Change the site on the GitHub side, then run the Worker’s cron and watch KV and Vectorize catch up.
Interactive figure: the GitHub publish steps and the Worker's cron re-indexing pages of chunks. It needs JavaScript.
A side effect I love: improving a page improves the chat. When I rewrite a park’s quick answers, Badge picks them up within ten minutes, and I never have to touch the bot.
Locking it down (the fun part)
An AI endpoint on the public internet is a free-tier quota with a text box in front of it. Here’s what I was defending against:
- Quota abuse. Somebody scripts 10,000 questions and Badge is down for everyone by breakfast.
- Freeloading. Another site wires its own chatbot to my endpoint.
- Bots. Plain bots, scrapers and curious
curls. - Prompt games. “Ignore your instructions and…”
- Privacy. People type real things into chat boxes.
No single guard handles all of that, so the Worker runs a gauntlet. The order matters: the cheap checks come first, and nothing touches AI until a request has passed every lock.
const origin = request.headers.get("origin");
if (origin && origin !== SITE) return json({ error: "forbidden" }, 403);
const q = String(body.q || "").replace(/\s+/g, " ").trim();
if (q.length < 2 || q.length > 300) return json({ error: "Ask a question of 2 to 300 characters." }, 400);
const { success } = await env.CHAT_RL.limit({ key: ip || "anon" });
if (!success) return json({ error: "Whoa, that's a lot of questions! Give me a minute to catch my breath." }, 429);
if (!(await verifyTurnstile(env, body.token, ip)))
return json({ error: "Couldn't confirm you're not a bot. Reload and try again." }, 403);
const count = Number((await env.STATE.get(`count:${today()}`)) || 0);
if (count >= DAILY_CAP) return json({ resting: true, answer: "Badge is resting after a busy day of questions...", sources: [] });
Pick a request and follow it through. The happy paths go all the way to Llama. Each attack stops at the lock built for it.
Interactive figure: one request passing or failing the Worker's origin, shape, rate-limit, Turnstile and daily-cap checks before retrieval. It needs JavaScript.
Here’s what each lock does, and why it’s there:
- Origin. Browsers can’t lie about
Origin, so another website can’t use Badge from its own pages. Scripts can lie, or leave the header out (notice the check only rejects a wrong origin). That’s why this lock is the first of five and not the only one. - Shape. POST only, JSON only, 2 to 300 characters. It’s cheap, and it keeps someone from pasting a novel into the prompt.
- Rate limit. Six questions a minute per IP, through Cloudflare’s rate-limiting binding. It’s a single line of config, and the rejection is still in Badge’s voice.
- Turnstile. An invisible challenge runs in the visitor’s browser before each question, and the Worker verifies the token with Cloudflare. The widget only loads on getoutwi.com itself, so local development keeps working. The Worker verifies only once the secret is set, which let me ship the widget first and flip the lock on second, without a broken deploy in between.
- Daily cap. Four hundred answers a day across the whole site, counted in KV under a key for today’s date that expires after 48 hours. Past that, Badge “is resting after a busy day of questions” and points you to the park pages. The free tier covers about 600, so 400 leaves headroom. The worst case for an attacker who gets through all of it is that Badge naps until tomorrow. The bill can’t go up.
Then there’s what’s not there, which matters just as much:
- No question text in logs. Observability is on, but it only records status and timing. The only things the Worker ever writes are the daily counter and the index state.
- Nothing for a prompt injection to steal. The model sees public site text and the question. It has no tools, no secrets and no other users’ data. The worst a jailbreak can do is make an 8B model say something silly in one chat bubble, as plain text.
- The maintenance endpoint is keyed. On-demand re-indexing needs a secret header, and secrets live in
wrangler secret, never in the repo. - Errors stay friendly. An exception returns “Badge tripped over a root. Try again in a moment.” and no stack trace.
I tested the locks from outside this morning, using nothing but curl:
POST from another origin → 403 {"error":"forbidden"}
GET /api/chat → 405 {"error":"method not allowed"}
POST with no Turnstile token → 403 {"error":"Couldn't confirm you're not a bot. Reload and try again."}
POST /api/chat/reindex, no key → 403 {"error":"forbidden"}
One war story from the edge: the same Cloudflare zone runs Bot Fight Mode, and while setting up an unrelated site verification it blocked the verifier’s crawler outright. Locks you forget about will eventually lock out someone you wanted in. Write them down.
And of course, Badge
A chatbot that says “That’s not covered on this site” could feel cold. Badge is why it doesn’t.
He’s not an image. Badge is an SVG rig built in code, and the head on the Ask Badge button is a crop of the same rig. It runs a tiny antics engine: it bobbles, winks, yawns, fixes his beanie, wiggles his ears and sniffs. The tongue only comes out when nobody’s looking. If your pointer has been still for six seconds or the tab isn’t focused, he might stick it out, and it ducks back in when you come near. His head also stands in for the “Badge is thinking” dots.
Then there’s the bit everyone asks about. Open the chat and say nothing for ten seconds, and Badge “types” for a moment and shares a Wisconsin state-symbol fact, sometimes with a little animated scene. The scenes are a muskie on the line, a deer stepping out of the pines, bees in the wood violets, or a mourning dove. None of that is AI. The facts and art live in a plain JavaScript file in the site, so they’re instant, always accurate, and never count against the daily cap. It happens once per chat session, so it’s charming instead of needy.
That’s the trick of a mascot: personality goes in the deterministic parts, and the AI part stays boring and correct.
Build your own
If you’ve got a static site and an afternoon, here’s the checklist I’d hand you:
- Write the decision record first. What it knows, what it never says, what it costs, and what it stores.
- Generate the corpus from your site’s source of truth, with a stable ID and a content hash for every chunk. Add “list” chunks for the questions that span many pages.
- Set a similarity floor and short-circuit below it. Don’t call the model with nothing to say.
- Write “I don’t know” into the prompt as an exact string, so the app can detect it, hide the sources and move on.
- Let the Worker pull from GitHub, not GitHub push to Cloudflare. No shared credentials.
- Stack your locks cheapest-first: origin, shape, rate limit, Turnstile, then a daily cap with a friendly ceiling.
- Log nothing you’d be embarrassed to leak. Status and timing are plenty.
- Put the personality outside the model. It’s cheaper, and it never hallucinates.
Badge took about a day to get working and about a week to get right. Almost all of that week went into the boring parts: the list chunks, the floor, the prompt’s last two lines, and the locks. That’s where the trust comes from.
Go ask him something: getoutwi.com. Ask about pizza if you want. He’ll tell you it’s not covered on this site.