DEV Community: Omar Bni

The Clanker Support WordPress plugin is approved — here's how it was built

Omar Bni — Wed, 02 Sep 2026 14:18:15 +0000

Good news for the roughly 40% of the web: Clanker Support is now an official WordPress plugin, approved for the WordPress.org plugin directory. Install it, paste your project key under Settings → Clanker Support, save — and every page on your site gets a streaming AI support agent that answers from your knowledge base and hands off to a human when it should.

This post is the whole story: why we built it, what it took to get through the WordPress.org review (spoiler: our zip file was secretly a tar), and how to use it.

Why a plugin at all

Adding a chat widget to WordPress has always meant one of two bad options: edit your theme and paste a script tag into header.php (which silently disappears the next time you switch or update themes), or install a generic "insert headers and footers" plugin and manage raw HTML in a settings box. Either way, you're maintaining code to use a product that was supposed to save you time.

The plugin is the third option. It's deliberately thin — under the hood it enqueues the same widget.js embed our dashboard generates — but moving it into a plugin changes what it's like to live with:

It survives your theme. The settings live in your database and the widget is injected on every front-end page, whatever theme is active.
No performance tax. The script loads asynchronously and renders after your page is interactive. The plugin ships no JavaScript or CSS of its own to your visitors — one script tag is its entire front-end footprint, and nothing loads in the admin area.
Always current. The widget ships from the API, not from the plugin, so new widget features appear on your site without a plugin update.
Reconfigure without touching HTML. Brand color, escalation threshold, turning the bubble off — all settings saves, not snippet edits.

What we built

Everything lives on one screen under Settings → Clanker Support:

Project key — the public key from your dashboard (Project → Embed). It's the same key the script embed exposes in your HTML, so it isn't a secret.
Floating widget — the site-wide launcher bubble, on by default.
Brand color — match the launcher and chat bubbles to your site.
Escalation threshold — how many visitor messages before "Talk to a human" appears. Leave it blank and the widget uses your project's server-side default.
API URL — for self-hosters (more on that below).

The settings page also does something a pasted script tag never will: it checks itself. On load, the plugin verifies your project key server-side against the API and shows a status pill — connected, invalid key, or unreachable — so a typo'd key is caught on the settings screen, not discovered days later when you wonder why nobody's chatting. The result is cached for five minutes, and saving the settings re-checks immediately.

And the floating bubble isn't the only placement. Drop the shortcode into any page or post — a contact page, a help center, a pricing FAQ — and the chat renders inline in a sandboxed iframe:

[clanker_support width="400" height="600"]

The shortcode works even when the site-wide bubble is toggled off, so you can offer chat only where it makes sense.

Your visitors get the same full support loop as every Clanker Support embed: streaming AI answers grounded in your docs, human escalation that notifies your team by email and Slack, operator replies from the dashboard inbox appearing in the widget within seconds, and per-message ratings with an end-of-conversation CSAT prompt.

The build: shipped in a day, rebuilt the next

The first version came together in an afternoon — a thin, pure-PHP injector, a settings page, the shortcode, a packaging script. We merged it, looked at it against what the WordPress.org directory actually expects, and pulled it back the same day.

Because a plugin that works and a plugin that belongs in the directory are different artifacts. The rebuild that landed the next morning added everything reviewers (and WordPress conventions) expect: a proper class-based structure instead of one long bootstrap file, a translation template so the plugin is translatable, silence-is-golden index.php files in every directory, an uninstaller that removes the plugin's two stored values (its settings option and the connection-status cache — conversations live in your Clanker Support project, never in your WordPress database), directory listing assets, and a full readme.txt in the WordPress.org format.

The readme deserves a special mention. Since the plugin is a connector to a hosted service, WordPress.org requires an explicit external services disclosure: what loads from where, what data is sent, and links to the terms and privacy policy. Ours spells out that the widget script comes from your configured API origin, that nothing about a visitor is sent until they interact with the widget — and that if you self-host, every one of those requests goes to your own deployment instead of ours.

The review: three rejections' worth of lessons

Before a human reviewer ever sees your plugin, automated checks run on the upload — and ours found things.

The zip that was secretly a tar. Our packaging script built the upload zip with the system archiver, and on Windows that quietly falls apart: there's no zip CLI, tar.exe accepts -a -cf plugin.zip but can't actually write zip format — so it silently emits a TAR with a .zip name — and the PowerShell alternatives store backslash entry paths that unzip into garbage on Linux. The WordPress.org uploader rejected the artifact with the marvelously unhelpful "the plugin has no name." The fix: we threw out every external archiver and wrote a minimal zip writer on Node's built-in zlib — one deterministic code path on every OS — and the build now verifies the magic bytes of its own output. If your zip doesn't start with PK, it isn't a zip.

Plugin URI ≠ Author URI. The submission checker requires the plugin's homepage and the author's homepage to be different URLs. Both of ours pointed at clankersupport.com. The Plugin URI now points at the plugin's home in our monorepo on GitHub.

Validate the readme where the validator can read it. The readme validator accepts a URL — but point it at a normal GitHub file link and it gets GitHub's HTML page, not your readme. We keep a byte-for-byte mirror of readme.txt at the package root and validate against the raw URL.

With those fixed, the submission went in — and a few days later, the approval came through. Approval on WordPress.org means the plugin gets its own SVN repository and a directory listing, which brings the two things a GitHub zip can't: one-click installs from Plugins → Add New, and automatic updates for everyone who installs it.

Using it

In your WordPress admin, go to Plugins → Add New and search for "Clanker Support" (or grab the zip from GitHub and upload it under Add New → Upload Plugin).
Install and activate.
In your Clanker Support dashboard, copy your project's public key (Project → Embed).
In WordPress, go to Settings → Clanker Support, paste the key, and save. Watch the status pill turn to connected.

That's the whole setup. The bubble is live on every page; add the [clanker_support] shortcode wherever you want inline chat.

And because Clanker Support is open source (theopenco/llmchat), the plugin treats self-hosters as first-class: point the API URL setting at your own deployment and everything — the widget script, the chat API, the inline embed, even the settings page's connection check — talks to your infrastructure instead of ours.

Next on the roadmap: automatically identifying logged-in WordPress users so escalations arrive with a name and email attached, and WooCommerce context so the agent knows about the visitor's order. If either of those matters to your store, come tell us in Discord — it directly shapes what we build first.

Add AI customer support to your Next.js app with one Server Component

Omar Bni — Wed, 26 Aug 2026 14:18:59 +0000

Support widgets have shipped the same way since 2015: paste a script tag before </body>, hope it doesn't fight your framework. In a Next.js app that means no types, no server rendering, a mystery global mutating your DOM, and a launcher that pops in after hydration.

We just shipped a better way. @clankersupport/widget-rsc is Clanker Support as a native React Server Components package: one component in your root layout puts a streaming AI support agent on every page, server-rendered into your HTML. And because the whole widget is built on headless primitives, you can restyle it with plain CSS or replace our UI entirely.

This tutorial takes you from npm install to a customized widget in about ten minutes.

What you'll need

A Next.js 15+ app using the App Router (any React 19 RSC framework works; we'll use Next.js here).
A Clanker Support project and its public widget key — grab it from the dashboard under Project → Embed. Self-hosting the open-source llmchat stack works too; you'll just pass your own apiUrl.

The key is public by design — it's the same key the script-tag embed exposes — so it's safe in client code and env files.

Step 1: Install the SDK

npm install @clankersupport/widget-rsc

React 19 and React DOM are the only peer dependencies. The package itself has zero runtime dependencies — the streaming protocol, API client, and storage layer are self-contained, so your bundle barely notices it.

Step 2: Add the widget to your root layout

Open app/layout.tsx and render ClankerSupport just before the closing body tag:

import { ClankerSupport } from "@clankersupport/widget-rsc";

export default function RootLayout({
    children,
}: {
    children: React.ReactNode;
}) {
    return (
        <html lang="en">
            <body>
                {children}
                <ClankerSupport apiKey={process.env.NEXT_PUBLIC_CLANKER_KEY!} />
            </body>
        </html>
    );
}

Add the key to .env.local:

NEXT_PUBLIC_CLANKER_KEY=pk_your_project_key

Run next dev and open any page. A launcher bubble sits bottom-right; click it and you're chatting with your support agent — streaming answers from your knowledge base, with "Talk to a human" escalation and everything else the hosted widget does.

Here's what makes this different from a script tag. ClankerSupport is an async Server Component: it fetches your widget config (branding, privacy URL) on the server, cached and revalidated every five minutes, so the client skips a round-trip and never flashes the wrong branding. The fetch is wrapped in Suspense with a null fallback and fails soft — if our API is slow or unreachable, your page renders normally and the widget simply appears with safe defaults. A support vendor should never be able to block your page. Now it can't.

Step 3: Make it yours

Everything visual is a typed prop:

<ClankerSupport
    apiKey={process.env.NEXT_PUBLIC_CLANKER_KEY!}
    brandColor="#16a34a"
    position="bottom-left"
    title="Acme Support"
    greeting="Hi! Ask us anything about Acme."
    escalationThreshold={2}
/>

brandColor drives the launcher, header, and user bubbles.
position docks the widget to either bottom corner.
greeting is the opening bubble (it personalizes automatically once a visitor gives their name; pass null to hide it).
escalationThreshold controls how many visitor messages appear before the "Talk to a human" option shows. Default is 3.

Step 4: Restyle with CSS

The default UI is plain, namespaced CSS — .clanker-* classes driven by custom properties, no shadow DOM — so your stylesheet always wins:

.clanker-root {
    --clanker-brand: #16a34a;
    --clanker-surface: #0b0f14;
    --clanker-text: #e5e7eb;
    --clanker-bubble: #1f2937;
    --clanker-border: #1f2937;
}
.clanker-panel {
    border-radius: 8px;
}

That's a dark-mode widget in eleven lines, no configuration UI required.

Step 5: Go headless when CSS isn't enough

The styled widget is a thin composition over primitives we export from @clankersupport/widget-rsc/headless — the same pattern as Radix: unstyled semantic elements, data-* state attributes, asChild support, and full prop passthrough.

"use client";

import * as SupportChat from "@clankersupport/widget-rsc/headless";

export function HelpButton() {
    return (
        <SupportChat.Root apiKey={process.env.NEXT_PUBLIC_CLANKER_KEY!}>
            <SupportChat.Trigger className="btn">Need help?</SupportChat.Trigger>
            <SupportChat.Panel className="panel">
                <SupportChat.Messages>
                    {(m) => <Bubble role={m.role}>{m.content}</Bubble>}
                </SupportChat.Messages>
                <SupportChat.EscalateButton>Talk to a human</SupportChat.EscalateButton>
                <SupportChat.Composer>
                    <SupportChat.Input placeholder="Ask anything…" />
                    <SupportChat.Submit>Send</SupportChat.Submit>
                </SupportChat.Composer>
                <SupportChat.Branding />
            </SupportChat.Panel>
        </SupportChat.Root>
    );
}

And when even components are too much structure, there's a single hook that exposes the whole state machine — messages, streaming status, sending, escalation, ratings, CSAT:

"use client";

import { useClankerSupport } from "@clankersupport/widget-rsc/headless";

export function SupportShortcut() {
    const { send, status, canEscalate, escalate } = useClankerSupport();

    return (
        <>
            <button onClick={() => send("Where is my order?")}>Track my order</button>
            {status === "streaming" && <TypingDots />}
            {canEscalate && <button onClick={escalate}>Talk to a human</button>}
        </>
    );
}

Build a ⌘K support palette, a docked sidebar, a help tab inside your settings page — the SDK handles the protocol (streaming, polling, escalation semantics, optimistic ratings) and you own every pixel.

What you get out of the box

Whichever layer you use, the behavior is the full Clanker Support loop:

Streaming AI answers grounded in your knowledge base (docs URLs, text snippets, Q&A pairs).
Human escalation that emails your team and posts to Slack, with the agent going quiet while a human owns the conversation.
Operator replies from the dashboard inbox appearing in the widget within seconds — no refresh.
Per-message thumbs ratings and an end-of-conversation CSAT prompt.
A privacy notice, identity capture, and conversations that survive reloads.

One detail worth knowing if you're already using our script tag: the SDK uses the same browser storage keys, so switching to the React package keeps every existing visitor conversation and identity. Migration is deleting one script tag and adding one import.

Self-hosting

Everything above works against your own deployment of the open-source stack — pass your API origin and you're done:

<ClankerSupport apiKey="pk_…" apiUrl="https://support-api.your-domain.com" />

The full API reference — every prop, primitive, and hook field — lives in the package README. If you build something with the headless layer, we'd genuinely like to see it — come show us in Discord.

I spent an hour trying to break my own product with 12 languages. It won.

Omar Bni — Tue, 11 Aug 2026 00:10:58 +0000

Last night I sat down with one goal: make my own product embarrass me.

The product is Clanker Support — an open-source support agent you drop on your site with one script tag. The plan: one continuous conversation, same question every time, and I switch languages mid-thread until something cracks.

Spanish. French. German. Portuguese. Japanese. Mandarin. Korean. Hindi. Russian. Turkish. Arabic.

It answered every single one in the language it was asked. Not "detected Spanish, please hold" — just… the answer, in Spanish.

The frame that sold me on my own product

My favorite moment isn't one answer — it's the seam between two.

The Spanish reply has fully landed: trial terms, pricing, a source citation. And in the input box below it, the next question is already half-typed. In French. Same thread, three seconds apart, and the agent doesn't blink — it answers the French question in French like that's a completely normal thing for a support conversation to do.

Then Arabic. The entire exchange flips right-to-left — question, answer, the pricing list — like the widget grew up writing it.

(I also fed it Moroccan Darija typed in Arabizi, my personal "no software knows this exists" test. It passed that too, code-switching and all.)

The kicker

There is no language setting in the product. No dropdown, no locale config, nothing to enable. There's no translation layer either — no detect-then-translate pipeline bolted on the side. The agent just answers in whatever it's spoken to. That's the whole trick, and it cost zero lines of code.

Your customer decides the language. Every message, fresh.

And now it does it out loud

We just added voice: there's a phone icon in the widget, and your customer can talk to the support agent on a live call. Same knowledge, same languages, spoken back in real time.

The one rule that survives all of this

When the agent can't answer — any language — it doesn't improvise. It hands the conversation to a human on your team with the whole thread attached. That rule is why the product exists. The polyglot part is just it being useful on the way there.

The chat bubble on clankersupport.com is the live agent, not a demo. Go ask it something in your language — I'd genuinely love to know if it holds up in yours. It's open source, and hosted plans have a 7-day free trial.

We Audited Our Marketing Site Against Our Codebase and Found 6 Lies

Omar Bni — Mon, 27 Jul 2026 14:47:33 +0000

Last week we put our marketing site in one tab and our codebase in the other and checked every falsifiable sentence on the site against the code that would have to make it true. Six claims failed the check, and the people most likely to notice were exactly the people we most need to convince.

We build Clanker Support, an open-source, MIT-licensed AI support agent you embed with one script tag. We're early: no wall of logos, no review-site score to lean on. The one trust asset available to a company like ours is honesty a stranger can verify, and claim drift burns it invisibly — usually midway through a technical evaluation, when a developer checks.

To be clear about how the drift accumulated: nobody sat down and decided to fabricate features. Copy got written against a roadmap, the code took a different route, and nobody ever diffs the homepage against the repo. Drift never feels like lying from the inside. The visitor reading the page can't tell the difference, so functionally it is.

Every fix below shipped as one public pull request. You can read each diff.

The six claims that failed the diff

1. "Run any model or provider."

The model picker is a curated catalog of web-search-capable models, filtered from a generated snapshot of our gateway's catalog. Higher tiers unlock more of the list. "Any model" was aspirational copy for a picker that refuses to even boot with an empty list:

// packages/shared/src/models.ts
// Loud failure, never a blank picker: if the generated snapshot is ever empty
// (a botched regen), fail at import rather than silently offer no models.
if (WEB_SEARCH_MODELS.length === 0) {
    throw new Error(
        "WEB_SEARCH_MODELS is empty — run `pnpm gen:web-search-models` to regenerate from @llmgateway/models",
    );
}

A curated catalog is a defensible design choice. We rewrote the copy to describe it, because it's what you get.

2. "How many exchanges before the bot hands off."

That's how the site described the escalation threshold: as if the agent decides, at some configured point, to hand the conversation over. The setting behind that copy is a per-project message threshold, and what it does is reveal a "Talk to a human" button after N messages. The visitor decides. A counter, not a judgment. The copy now describes the threshold.

3. "Answers when it can. Hands off when it can't."

Tidy copy, and it claims the AI monitors its own confidence and bails out the moment it's unsure. Great feature. We don't have it. What actually exists is visitor-initiated hand-off: the threshold button above, plus pattern detection for a visitor explicitly asking for a person. The detector's own doc comment is more honest than our homepage was:

// packages/widget/src/escalation-intent.ts
/**
 * Detects a visitor explicitly asking for a human, so the "Talk to a human"
 * CTA can surface immediately instead of waiting for the message-count
 * threshold.
 *
 * Matching leans toward recall over precision: a match only REVEALS the
 * escalate button (the visitor still has to click it), so a rare false
 * positive costs one extra affordance while a false negative traps a
 * frustrated visitor with the bot.
 * …
 */

Even the explicit-ask path only reveals a button. The visitor clicks it. Nothing anywhere in the codebase asks the model how confident it feels. This one stung the most, because the fake version sounds smarter and we'd absorbed it into how we described the product out loud.

4. Infrastructure attributed to the wrong vendor.

Our comparison pages said "Fully self-hostable on Cloudflare infrastructure — D1, KV, and workerd." We don't run on Cloudflare. We run on serverless workerd via a platform called Ploy, and the same copy now reads "serverless workerd via Ploy (D1-compatible SQLite + KV state)." Same runtime family, wrong vendor. Nobody sues over this one, but a reader who catches the infrastructure paragraph being wrong has no reason to trust the security paragraph.

5. "Self-host free, full feature set."

The worst one, because it bent the promise open-source people actually check. Self-hosting is free forever with your own LLM keys; that part was true. What the copy skipped: a fresh self-hosted install resolves to a locked plan unless an environment allowlist is set. The unlock is a few lines of config parsing:

// apps/api/src/lib/plan.ts
export function internalEmails(env: Env): string[] {
    const raw = env.vars.INTERNAL_ACCOUNT_EMAILS;
    if (!raw) return [];
    return raw
        .split(",")
        .map((s) => s.trim())
        .filter(Boolean);
}

Unset, no workspace is exempt, and software running on your own server greets you with a paywall you had no way to anticipate. The immediate fix was documentation: the docs now tell you the unlock exists and how to set it, instead of letting you discover the lock the hard way. Documenting an awkward mechanism beats hiding it, and it bought us time to decide what the mechanism should become.

6. SSO/SAML and audit logs listed on the enterprise tier.

Display copy with zero code behind it. We don't mean "beta" or "partially built" — grep the repo for SAML and the only hits are the copy itself. Both are now labeled as roadmap. Had an enterprise buyer asked for an audit-log demo, the demo would have been us typing very fast in another room.

A seventh came from an internal doc rather than the site: a per-plan member cap we claimed to enforce. The entitlement number exists in the billing config, but there's no invite endpoint, so there's nothing to gate. A limit with no enforcement path is a wish with a number on it. Claim dropped.

One page undersold us

The audit cut the other way exactly once. Our own Chatwoot comparison listed "fully open-source (MIT license) — read, fork, and contribute" as the competitor's advantage, implying we weren't. We are, and the LICENSE file has been in the repo the whole time. That fix went into the same pull request as the six above.

Finding it reframed the whole exercise. The target is agreement between the site and the repo, and undersell is the same defect as oversell: the two disagree. Treat both directions as bugs and the audit stops feeling like penance and starts feeling like ordinary QA, which is what got it finished.

The re-pass found 18 more, four written during the fix

After the first fix pass we felt pretty good about ourselves. Then we ran an adversarial review: a two-agent panel, LLMs given the repo, whose only job was to attack the corrected copy against the codebase.

They found 14 missed instances of the same six overclaims, spread across pages, docs, and meta descriptions the first pass never opened.

Worse, they found 4 brand-new overclaims in the replacement copy itself. Text written during a truth-telling exercise, by people actively trying to be accurate, still drifted optimistic within the same edit session. We'd swap a false claim for a true one and unconsciously round it up while typing.

Marketing language has gravity: every sentence wants to be slightly more impressive than the facts, and you don't feel the pull while writing. The only countermeasure we've found is a second pass by someone, or something, that doesn't share your incentives.

Diff your homepage against your repo

The repeatable version fits in an afternoon, and you don't have to read code to run it. Each step is an ask you can hand to your team as one sentence.

Extract every falsifiable claim. Scrape your homepage, pricing page, feature pages, and docs. Pull out every sentence that asserts something checkable: a feature exists, a limit is enforced, a platform is used, a license applies. Ignore vibes ("delightful"), keep facts ("supports SSO").
Assign each claim a code location. For every claim, ask: which file or endpoint makes this true? "Any model" should point at the model list. "Audit logs" should point at an audit-log table. A claim nobody can point anywhere is a finding, and whoever wrote the feature can answer the question in about a minute.
Classify: true / roadmap / false / understated. A roadmap item is fine as long as it's labeled as one. Anything shipped-but-unclaimed goes in the understated bucket, and it gets fixed in the same pass.
Fix everything in one public pull request. The public part is the point. A private cleanup earns nothing; a public one is evidence you can hand a skeptical visitor for years.
Re-audit the fix adversarially. This is the step everyone skips, and we nearly did. It produced 18 of our findings — four of which we authored during the fix itself. A colleague, an advisor, an LLM given the repo and told to attack: anyone whose job is to disagree with your copy.

Then put it on a calendar, because drift regrows and every new landing page restarts the clock. The cost of skipping the whole exercise never appears as a line item. It arrives as an evaluation that quietly churned when a developer caught claim number four, or an enterprise call where someone asks to see the audit log.

We've run a related exercise on our search presence before, in our AI SEO audit checklist. Don't blur the two: that one audits how your pages present claims to search and answer engines; this one audits the product claims themselves against code.

The cheapest credibility available

The product carries the same rule at a smaller scale. Where the dashboard has no real value for a metric, it renders an em dash rather than a guessed number, and the inbox stats' doc comment spells the policy out:

// apps/dashboard/src/app/inbox/_components/InboxStats.tsx
/**
 * …The avg rating is the mean CSAT across rated conversations only, shown
 * as "—" when none are rated (never NaN). While the aggregate is loading,
 * values render as "—".
 */

The usage meter in the sidebar goes further and renders nothing at all until the number resolves — its comment reads "(no fabricated zero)". That's the same rule our homepage broke six ways, applied at the level of a single stat card.

What a company at our stage can offer is verifiability: an MIT repo you can read, a public pull request where we corrected our own marketing, docs that explain the awkward parts like the self-host unlock instead of burying them. A skeptical developer can check every word of this post against the diffs in about ten minutes, and that checkability is worth more to us than any adjective we could have kept.

If you're early and your homepage promises things your repo can't cash, you're spending trust you haven't minted yet. Diff the site against the repo and fix in both directions, where people can watch. It's an afternoon of mildly humiliating work, and it's the cheapest credibility you'll ever buy.

FAQ

How do you audit marketing claims against a codebase?

Extract every falsifiable claim from your homepage, pricing page, and docs; assign each one the file or endpoint that would make it true; classify each as true, roadmap, false, or understated; fix everything in one public pull request; then have someone adversarial re-audit the fix. The last step matters most — our re-pass caught overclaims written during the fix itself.

What is claim drift?

Claim drift is the gap that grows between what a marketing site says and what the codebase does. It rarely starts as a lie: copy gets written against a roadmap, the product takes a different route, and nobody re-checks the copy. The visitor can't distinguish drift from fabrication, so it costs the same trust.

Should the fixes be public?

If the product is open source, yes. A private cleanup earns nothing, while a public pull request is standing evidence you can hand a skeptical evaluator years later. It also raises the cost of future drift, which is half the point.

Two messages, one sequence number: the concurrency bug that never threw

Omar Bni — Mon, 27 Jul 2026 14:45:32 +0000

One day, two messages in the same support conversation both had sequence = 2. Both inserts succeeded and nothing was logged; everything downstream simply picked an order. The colliding pair says it all: the "Visitor requested a human operator" marker and the AI answer the visitor was escalating away from, and depending on which order a client picked, the request for a human rendered before or after the answer that prompted it. That sequence integer is load-bearing in Clanker Support: the widget orders the thread by it, the dashboard inbox orders by it, unread tracking uses it as a high-water mark. For a support product, that is close to the worst available failure. The conversation thread is the artifact your customer trusts, and a garbled support thread fails the way a garbled bank statement does: the customer stops believing the record.

The expensive property of this bug class is who finds it. It never appears in tests, never appears in logs, and the corruption compounds quietly, so the first person positioned to notice is a customer reading a thread that makes no sense — long after the writes that caused it. We caught it in our own testing before it cost anyone anything; we're early, and that's the cheapest possible place to catch it. Nothing about the race changes at scale except how much data it quietly ruins first. The product is open source (theopenco/llmchat), so everything below links to real diffs.

Two sins, one write path

Every writer in the system did some version of this: read the conversation, do work, then write a message whose sequence was computed from the earlier read. Simplified:

// BEFORE: read early, write late
const convo = await db.query.conversation.findFirst({
    where: eq(conversation.id, conversationId),
});

// ... 5–20 seconds of LLM streaming happens here ...

await db.insert(message).values({
    conversationId,
    content,
    sequence: convo.messageCount + 1, // computed from a read made earlier
});
await db.update(conversation).set({ messageCount: convo.messageCount + 1 }); // absolute assignment

Sin one: sequence is computed from messageCount as it stood when this request read it. If any other writer inserts between the read and the insert, both writers saw messageCount = 3 and both write sequence = 4. SQLite takes both rows without complaint.

Sin two: the count update is an absolute assignment. Writer A sets messageCount = 4; writer B, working from the same stale read, also sets it to 4. Two messages arrived and the count moved by one. The damage compounds from there, because the next writer derives its sequence from a count that's already wrong, so one race seeds the next.

We had no shortage of concurrent writers, either. The chat handler persists the assistant's reply after the stream finishes, inside waitUntil, seconds after it read the conversation. An operator can reply from the dashboard inbox at any moment. Internal notes land. An escalation writes a system message. An inbound email reply arrives through a webhook. Five independent writers, all doing read-then-write against the same counter.

Why every test passed

Our tests exercised each writer in isolation: insert a user message, assert sequence 1; insert a reply, assert sequence 2. Green across the board.

The race needs two writers interleaved inside the same window, and the widest window in the whole system is the one no unit test reproduces: the assistant-persist that runs after an LLM stream completes. In tests the "stream" resolves instantly with nothing else running. In production it takes 5 to 20 seconds, and the true trigger is mundane: the visitor hits "Talk to a human" mid-stream (the exact collision we found), or an operator replies from the inbox while the agent is still streaming. Either one lands a write inside the gap every single time it happens.

So tests pass because they're sequential, and production fails because it isn't. No quantity of extra tests fixes that cleanly. The gap itself has to go.

The fix shipped in three steps, and the order is the point

You can't just add a unique index: the old writers are still running while you deploy, and the index build fails outright if duplicates exist. You can't just fix the writers either: existing duplicate rows stay corrupted, and any future regression goes back to being silent. So the fix went out as three deploys, strictly ordered.

Clean the data first

The backfill (the public pull request) finds every conversation with at least one duplicated (conversation_id, sequence) pair, renumbers all of that conversation's messages with ROW_NUMBER(), then trues up the drifted message_count. Lightly trimmed:

CREATE TABLE _seq_backfill AS
    SELECT id AS mid,
        ROW_NUMBER() OVER (PARTITION BY conversation_id
            ORDER BY sequence, created_at, id) AS new_seq
    FROM message
    WHERE conversation_id IN (
        SELECT conversation_id FROM message
        GROUP BY conversation_id, sequence HAVING COUNT(*) > 1);

UPDATE message
SET sequence = (SELECT new_seq FROM _seq_backfill WHERE mid = message.id)
WHERE id IN (SELECT mid FROM _seq_backfill);

DROP TABLE _seq_backfill;

UPDATE conversation
SET message_count = (SELECT COUNT(*) FROM message m WHERE m.conversation_id = conversation.id)
WHERE message_count <> (SELECT COUNT(*) FROM message m WHERE m.conversation_id = conversation.id);

Two details worth stealing. The ORDER BY sequence, created_at, id makes the renumbering deterministic: ties on the duplicated sequence break by creation time, and ties on creation time break by id. That last tiebreaker matters more than it looks — our timestamps are unix seconds, so same-second writes are common, which is the whole bug. Run the backfill twice and you get the same answer. And it stages through a temp table rather than a correlated self-update, because renumbering a partition while you're reading it is how you end up with a backfill you can't reason about.

One writer, and the database allocates the key

The writer refactor replaces every inline insert-and-bump in every route with one function: insertMessage() in apps/api/src/lib/messages.ts. Chat persist, operator reply, notes, escalation markers, inbound email replies: all of them now go through it.

The core move is that the sequence is allocated by a scalar subquery inside the INSERT itself:

db(env)
    .insert(message)
    .values({
        conversationId: input.conversationId,
        role: input.role,
        content: input.content,
        // ...
        sequence: sql`(SELECT COALESCE(MAX(${message.sequence}), 0) + 1 FROM ${message} WHERE ${message.conversationId} = ${input.conversationId})`,
    })
    .returning();

That's the entire trick. SQLite (and D1, which is SQLite at the edge) serialize writers per statement, so MAX(sequence) + 1 and the insert are atomic. There is no gap between reading the current max and writing the next value, because they're the same statement. The database allocates the ordering key, and the application never holds it in a variable where it can go stale.

The counter fix rides along:

const bumped = await db(env)
    .update(conversation)
    .set({
        messageCount: sql`${conversation.messageCount} + 1`,
        updatedAt: new Date(),
    })
    .where(eq(conversation.id, input.conversationId))
    .returning({ messageCount: conversation.messageCount });

message_count = message_count + 1 is commutative: two concurrent bumps produce +2 no matter how they interleave, where two absolute assignments produced +1. The RETURNING clause hands the post-bump count back to callers so nobody is tempted to re-derive it from a sequence number.

The unique index that makes any regression loud

The last deploy adds the unique index that makes any regression loud:

CREATE UNIQUE INDEX IF NOT EXISTS message_conv_seq_uidx
    ON message (conversation_id, sequence);

And the part we'd get wrong if we did this again without notes: that migration re-runs the exact same dedupe backfill, immediately before creating the index, in the same migration. Between the backfill deploy and the writer deploy, the old racy writers were still live in production. Any duplicate they minted in that window would make the index build fail and take the whole deploy down with it. The re-dedupe costs nothing when the data is already clean and saves the deploy when it isn't. (We're rigid about deploy ordering around risky schema changes in general — it's the same discipline that kept an "always safe" additive column from breaking every login.)

Once the new writer is live, the index should never fire. It exists so that if someone adds an inline insert with a precomputed sequence eight months from now, the result is a constraint error in the logs instead of six more weeks of silently shuffled threads. Downgrading a bug from silent corruption to loud error is most of the value of the whole exercise.

Drizzle buries the error your retry path needs on `.cause`

insertMessage() has a retry path: if an insert ever trips the unique index, it retries once, and the re-run subquery naturally picks the next free slot. To do that it has to detect a unique-constraint violation, and our first attempt was the obvious one:

// looks right, never matches in prod
if (err instanceof Error && /unique constraint failed/i.test(err.message)) {

It never matches. Drizzle 0.45 wraps every driver error in a DrizzleQueryError whose message reads "Failed query: insert into message ...". The actual UNIQUE constraint failed: message.conversation_id, message.sequence text lives on err.cause, one level down. A message-only check compiles, passes any test that fakes the error, and silently classifies every real violation as an unknown error to rethrow. The retry path becomes dead code, and you find out the day the tripwire fires and nothing retries.

The version that works walks the cause chain, with a cycle guard because cause can technically point anywhere:

function isUniqueViolation(err: unknown): boolean {
    const seen = new Set<unknown>();
    for (let e: unknown = err; e && !seen.has(e); ) {
        seen.add(e);
        const msg = e instanceof Error ? e.message : String(e);
        if (/unique constraint failed/i.test(msg)) {
            return true;
        }
        e = (e as { cause?: unknown }).cause;
    }
    return false;
}

If you classify database errors through any ORM, check whether the string you match lives on .message or on .cause.message. Error.cause chains have been standard since ES2022, and most error-classification code we've read predates them.

The five-second audit

The rule underneath all of this: never derive an ordering key from state you read earlier in the request. Not a sequence number, and not a version counter either. The moment the value leaves the database and sits in a variable it's a snapshot, and every millisecond between read and write is a window some other writer will eventually hit. Streams, webhooks, and background jobs stretch those windows to seconds.

You don't need to write code to check your own product for this today. Ask whoever owns the backend to search the codebase for count + 1 or position + 1 computed in application code and written back later. The search takes about five seconds, and each hit is this bug wearing different clothes. Then ask two follow-ups: is there one writer function for that key, and is there a database constraint that would make a violation loud? If either answer is no, you have this bug on a timer.

The repair, when you need it, is the same recipe in the same order:

Backfill first, deterministically and idempotently, so the data is clean.
Let the database allocate the key atomically, in the same statement as the write, through one writer function with no exceptions.
Add the constraint last, re-cleaning immediately before you build it, so the bug class becomes impossible rather than unlikely, and any regression is a loud error instead of quiet drift.

All three diffs are small enough to read in one sitting, and every one of them is public on our repo.

FAQ

How do you safely generate a per-group sequence number in SQLite or D1?

Allocate it inside the INSERT itself with a scalar subquery: sequence = (SELECT COALESCE(MAX(sequence), 0) + 1 FROM message WHERE conversation_id = ?). SQLite serializes writers per statement, so reading the current max and writing the next value happen atomically. Any pattern that reads a counter into application code first has a race window, and streaming or background work stretches that window to seconds.

Why isn't a unique index alone enough to fix a sequence race?

Deploys aren't instantaneous. While the index migration runs, older application code with the racy writer is still serving traffic, and any existing duplicates make the index build fail outright. Clean the data first, route every write through one atomic writer, then create the index, re-running the dedupe immediately before it to absorb duplicates minted between deploys.

Why doesn't err.message contain "UNIQUE constraint failed" with Drizzle?

Drizzle 0.45 wraps driver errors in a DrizzleQueryError whose message describes the failed query; the constraint text lives on err.cause. Walk the cause chain (with a cycle guard) when classifying database errors, or your retry and fallback paths will silently never run.

Every hosted plan now starts with a 7-day free trial

Omar Bni — Wed, 22 Jul 2026 15:21:23 +0000

Originally published on the Clanker Support blog.

As of last week, every new hosted Clanker Support subscription starts with a 7-day free trial. It applies automatically at checkout — no promo code, nothing to hunt for. Pick a plan, and for seven days you use it for free.

Here's the honest version of why. Our hosted product has never had a free tier — that's by design, because self-hosting is the free version and always will be. But it meant the first thing a new customer met was a paywall, before the product had said a word for itself. We didn't like that first impression, so we replaced it: now the first thing you meet is the full product, free for a week.

The trial is the whole plan, not a preview

The seven days are the plan you picked, from day one. Every feature, the full response allowance — 2,000 AI responses on Starter, 12,000 on Growth, 50,000 on Scale. There's no demo mode, no locked features, no "upgrade to unlock" halfway through.

That matters because of what a week is actually enough for. Install is one script tag, and most teams are live in about five minutes. Point the agent at your docs and knowledge sources, and it starts answering your real customers — escalating to your team instead of guessing when it can't. By day seven you're not evaluating our product anymore. You're deciding whether to switch off something that's already handling your support.

Why we ask for a card

We do ask for a card at checkout, and we'd rather explain that than hide it.

Nothing is charged during the trial. Usage during the trial is never billed — not on day seven, not ever. The first charge happens only when the trial ends and you've chosen to stay.

The card is there so the week ends cleanly either way. If Clanker Support has earned its place, your subscription continues without you re-entering anything or losing a day of coverage. If it hasn't, cancelling is self-serve from your billing settings — through the Stripe billing portal, before day seven, and you pay nothing.

When the seven days end

If you stay, your plan simply continues and your first charge goes through. And you're still covered: every hosted plan comes with a 14-day money-back guarantee, you can cancel anytime, and there are no contracts.

Stack that up and the arrangement is deliberately lopsided. Seven free days, no charge until the trial ends, self-serve cancellation from billing settings, money-back guarantee after that. We carry the risk of you trying Clanker Support. You don't.

Already a customer?

One thing we want to be straightforward about: switching between paid tiers doesn't restart a trial. The trial is for workspaces starting their first subscription — if you're already with us and move from Starter to Growth, the change applies right away, without a second free week.

We think that's the fair version. The trial exists so new customers can see the product work before paying, not as a loop to be replayed. Existing customers already know what they're paying for.

Self-hosting stays free

Nothing about this changes the open-source side. Clanker Support is open source, and self-hosting is free forever — bring your own LLM keys and run the whole thing on your own infrastructure. The hosted plans are for teams who'd rather we operate it; the trial just means trying that now costs nothing either.

How to start

See it working first, with no signup. The live demo is the real widget running in your browser — open it and ask it something.
Pick a plan on /pricing. We'd suggest starting on Starter — $19 a month, 2,000 AI responses, no per-seat fees — and switching tiers later if you outgrow it. Annual billing gets you two months free. Your 7-day trial starts at checkout, automatically.
Drop in the script tag. One script tag on your site; most teams are live in about five minutes. Then let it take your real conversations for a week.

Questions you might have

Why do you require a card for a free trial?

So the trial ends cleanly. Nothing is charged during the seven days — if you stay, your plan continues without interruption or re-entering details; if you don't, you cancel yourself from billing settings and pay nothing.

What happens when the 7 days end?

Your subscription begins and your first charge goes through. You're still protected by the 14-day money-back guarantee, and you can cancel anytime — there are no contracts.

Does usage during the trial cost anything?

No. Trial usage is never billed, no matter how much of your plan's allowance you use.

I already subscribe — do I get a trial if I switch plans?

No — tier changes apply immediately without a new trial. The trial is for workspaces starting their first hosted subscription.

Is self-hosting still free?

Yes, forever. Open source, your own infrastructure, your own LLM keys.

Start wherever you're comfortable

There's a ladder here, and you can stop on any rung. Try the live demo with no signup at all. When you're curious what it does with your docs and your customers, take the 7 free days. And if by day seven your support agent already feels like yours — that's the point at which staying is the easy decision.

Pick your plan at /pricing. The trial starts the moment you do.

Next.js merges metadata shallowly your og:image is probably missing (plus a 9-point AI SEO audit checklist)

Omar Bni — Mon, 20 Jul 2026 10:54:45 +0000

Originally published on the Clanker Support blog.

For about a month, every page on our marketing site that used our own metadata helper without an image of its own — /pricing, every /vs/* comparison, every /features/* page — shipped a summary_large_image Twitter card with no image. Not a broken image. No image at all, on pages whose metadata we thought a shared helper had made uniform. The cause is a Next.js behavior that hits any site combining a root Open Graph image with page-level metadata — which is most maturing Next.js sites — and we'll get to it first because it earned its place at the top of the checklist.

We found it while auditing our five web surfaces (marketing, docs, dashboard, showcase, admin). An AI-SEO audit checks the machine-facing surface of your site twice: once for search crawlers — robots rules, canonicals, sitemaps, Open Graph, structured data, index hygiene — and once for AI answer engines — crawler access for GPTBot, ClaudeBot and PerplexityBot, llms.txt and llms-full.txt files, and self-contained extractable answers. The output is a pass/fail list per domain you operate, including the domains your product mints pages on.

The audit landed in two waves: a first pass of fixes straight to main on July 6–8, then the cross-domain wave that merged as PR #148 on July 17 — that one touched marketing, docs, showcase, admin and the api. Everything is public in the repo, so every finding links to real code. Here is the checklist, then the four findings that were genuinely non-obvious.

The checklist

Run each question against every domain you operate — including subdomains you forgot you had.

#	Check	Ask yourself	Us, before the audit
1	Social card images	Does the rendered HTML of every page contain `og:image` — not just the homepage?	Fail — every helper-built page without its own cover had none
2	noindex reachability	Can crawlers fetch your noindex'd pages? A robots Disallow hides the tag	Fail — the dashboard got noindex + robots in wave one; admin's robots.txt came in wave two
3	Product-minted URLs	Does every per-customer URL your product serves send noindex?	Fail — `/embed/:key` was indexable
4	AI crawler access	Do any robots rules block GPTBot, ClaudeBot, PerplexityBot, or Google-Extended?	Pass — nothing blocked (now deliberate)
5	llms.txt files	Do you publish a link map (`/llms.txt`) and a full-content file (`/llms-full.txt`)?	Half — link map yes, full-content no
6	Secondary domains	Does every subdomain have robots, a sitemap, canonicals, OG tags, and structured data?	Fail — the docs subdomain had none of the five
7	Title lengths	Do your titles survive the ~60-character SERP cutoff?	Fail — a brand suffix pushed every post past it
8	Sitemap honesty	Is `lastModified` a real content date or a build timestamp?	Fail — build timestamp on every entry
9	Demo properties	Do showcase/demo sites have a `metadataBase`, a canonical, and a robots.txt that isn't a 404?	Fail — our showcase's robots.txt returned 404

Five domains, nine checks, and the only things that came through clean were the marketing site's JSON-LD, canonicals and llms.txt — the parts built deliberately. Even its sitemap was lying about dates, and the RSS feed it should have advertised didn't exist until the first wave added it. Everything that grew organically had a gap.

Why your Next.js pages have no og:image

The mechanism: Next.js merges route metadata shallowly. When a page exports its own openGraph object, it doesn't extend the layout's — it replaces it wholesale, and the same applies to twitter and alternates. Our root layout ships a site-wide OG cover via the opengraph-image.png file convention, and we assumed that cover reached every page. It reached exactly the pages that declared no openGraph of their own. Every page that called our pageMeta helper without an explicit image — /pricing, the comparisons, the feature pages, the tools — wiped the image out in the same stroke, and these were the pages we had put the most metadata care into. Blog posts survived only because they pass their own cover image to the same helper.

The failure is invisible in the browser and in most SEO tooling, because the pages still had titles, descriptions and canonicals. What they emitted was a twitter:card of summary_large_image with no image behind it, so every share of /pricing or a comparison page rendered as a bare text stub. We only caught it by grepping the prerendered HTML for og:image during the audit.

The fix is a constant and a default: put the image inside the helper, so no caller can forget it. The comment in apps/marketing/src/lib/seo.ts is the whole postmortem:

// apps/marketing/src/lib/seo.ts
/** The site-wide OG cover (the app/opengraph-image.png file convention route).
 * Explicit fallback because a page-level `openGraph` object replaces the
 * layout's resolved metadata wholesale (Next merges shallowly) — without this,
 * every pageMeta page shipped no og:image/twitter:image at all. */
const DEFAULT_OG_IMAGE = "/opengraph-image.png";

The same shallow merge had already bitten us once in the same file, back in the first wave — the alternates block re-declares the RSS <link> on every page, because a page-level canonical would otherwise delete the feed reference the layout set. Same behavior, different casualty.

Check number 1, generalized: if you use any metadata helper or page-level openGraph in a Next.js App Router site with a root OG image, view source on a non-homepage page and search for og:image. This combination — root image plus page-level metadata — is the default shape of a maturing Next.js site, which is why we're comfortable saying the bug is widespread. It costs you every social and chat-app share silently, and no console warns you.

robots.txt Disallow doesn't deindex — it does the opposite

The counterintuitive one. Our operator dashboard should never appear in search results, and the reflex is to write Disallow: / in its robots.txt. That reflex is wrong, and it's wrong in a way that leaves the pages in the index.

A robots Disallow controls crawling, not indexing. A noindex meta tag controls indexing — but Google can only read the tag on pages it's allowed to fetch. Disallow a URL that anyone links to externally, and Google indexes it anyway, as a bare URL with no snippet ("Indexed, though blocked by robots.txt" in Search Console). Our marketing site links to the dashboard sign-in page, so a Disallow would have pinned that URL in the index with no crawlable signal to ever remove it.

So the dashboard does the opposite. apps/dashboard/src/app/robots.ts, rationale included:

// apps/dashboard/src/app/robots.ts
// Deliberately allow crawling: the layout serves a noindex robots meta on every
// page, and Google can only see that tag on pages it's allowed to fetch. A
// Disallow here would leave externally-linked URLs (the marketing site links to
// sign-in) indexed as bare URLs with no way to discover the noindex.
export default function robots(): MetadataRoute.Robots {
    return {
        rules: { userAgent: "*", allow: "/" },
    };
}

This file is itself a first-wave audit fix (commit 90c3567) — before it, the operator console had neither the meta tag nor the robots file. The internal admin console had carried a noindex meta since its first commit but no robots.txt at all, so the second wave gave it the same explicit file (commit f8acf17), mirroring the rationale.

Check number 2: for every property you want out of search results, confirm the noindex is reachable. Disallow plus noindex is not belt-and-suspenders — the belt hides the suspenders.

Your product mints URLs on your domain — noindex them at the product level

This is the checklist item that only shows up when your product is itself a website. Clanker Support serves an iframe-able full-page chat shell at /embed/:key for hosts that can't run third-party script tags (the details are in everything that broke while shipping an embeddable widget). Every customer project gets one of these URLs — on our API domain.

Follow that to its bad ending: a customer embeds the iframe, their page links to our URL, a crawler finds it, and now a search for the customer's brand can surface api.clankersupport.com/embed/<their-key> — a bare chat shell wearing their brand color — next to, or instead of, the customer's own site. Nobody involved wants that, and the customer can't fix it, because the page isn't theirs.

Since the shell is served by a Hono route on workerd, not a Next.js page, the fix is a response header (commit d276077, in apps/api/src/routes/embed.ts):

// apps/api/src/routes/embed.ts
// Iframe chrome, not content: per-project embed URLs on the api host must
// never appear in search results next to the customer's own site.
c.header("x-robots-tag", "noindex");

Check number 3, and the framing we'd push hardest: for a SaaS, index hygiene is a product decision, not an SEO chore. Every URL pattern your product generates — embed shells, share links, preview pages, per-tenant subdomains — is a page you are publishing on your customers' behalf. Decide its index status when you design the feature, because by the time it ranks, it's an incident.

What we ship for AI crawlers, and what we deliberately don't block

The AI half of the audit had two parts: what we add, and what we refuse to subtract.

What we added: /llms-full.txt, the llmstxt.org companion to the /llms.txt link map we already served. Where llms.txt is a table of contents, llms-full.txt is the entire text of every blog post in one plain-markdown file, newest first, so an AI system can ingest the content without crawling each page. The builder (apps/marketing/src/lib/llms-full-txt.ts) is 55 lines, pure, and unit-tested; the only subtle line rewrites root-relative links, because a markdown link like /pricing means nothing once the text leaves our domain:

// apps/marketing/src/lib/llms-full-txt.ts
// Root-relative markdown links would be resolved against whatever
// domain serves this text, so make them absolute site URLs.
const absolute = p.content.replace(/\]\((\/[^)\s]*)\)/g, `](${siteUrl}$1)`);

Honesty about what this buys: llms.txt is an emerging convention, and consumption by the major engines is unproven. Google has said plainly that AI Overviews need no special AI files — ordinary indexable HTML is the input — while other engines are less explicit, and some tooling does fetch these files today. We treat the pair as cheap insurance: one static route, a pure function, six unit tests, and content we'd publish anyway in a format that costs a crawler one request instead of twenty.

What we refused to subtract: the audit checked every robots surface on all five domains for AI-crawler blocks — GPTBot, ClaudeBot, PerplexityBot, Google-Extended — found none, and ratified that as policy rather than leaving it as an accident of defaults. Blocking AI crawlers is a defensible choice for a publisher whose content is the product. Ours isn't; it's an open-source support agent, and the people who might use it increasingly ask an AI assistant what to use. An engine that has read our engineering posts can cite them; one that's blocked at robots.txt recommends whoever wasn't. The honest cost is that AI answers built on your content can substitute for visits to it. For a vendor blog, we'll take citation over control — being the source the answer names is the point of writing.

Check numbers 4 and 5: know your AI-crawler stance instead of inheriting it from a robots.txt someone wrote in 2019, and if you publish llms.txt files, hold them to the same testing standard as any route.

The smaller line items

Four more findings, one paragraph each, because they'll each cost someone a quiet month.

The docs subdomain had no baseline at all. docs.clankersupport.com served no robots.txt, no sitemap, no canonicals, no OG or Twitter cards, and no structured data — the app was two weeks old and every one of those defaults to "missing" (commit ac538e0 adds all five, plus TechArticle and BreadcrumbList JSON-LD on every page). Subdomains grow faster than their metadata; audit every host you answer on.

A brand suffix ate every title. Appending "— Clanker Support Journal" pushed every blog post title past the ~60-character SERP cutoff, so Google truncates or rewrites them (commit b433b72 drops it, and adds a dedicated seoDescription field because our comparison tldrs and migration intros ran 260–380 characters against a 160-character meta limit). Measure the title as rendered, suffix included.

Sitemap lastModified was a lie. We stamped build time on every entry, which claims every page changed on every deploy. The comment in seo.ts now enforces the rule: only blog entries carry the field, from real publish/update dates, because a timestamp on everything "teaches crawlers to distrust the field."

The showcase's robots.txt was a 404 page. Our live-demo site returned HTML for /robots.txt, had no metadataBase (so its OG image resolved against nothing), and — a Next.js footnote worth knowing — an opengraph-image file alone emits only og:image; without explicit openGraph/twitter blocks there's no og:title or card type around it (commits 7ad1f32 and 5ad2bf7, one from each wave).

What we can't tell you yet

The cross-domain wave merged three days ago, and even the oldest first-wave fixes have had two weeks in production — not enough for Search Console to say anything. So we have zero results data: no ranking movement, no AI citations to report, no before/after chart. Anyone who ships SEO changes on Thursday and reports wins on Sunday is selling something. What we can vouch for today is the mechanism behind each fix: the shallow merge is documented Next.js behavior we verified in prerendered HTML, the Disallow-hides-noindex trap is how Google has worked for years, and the embed-shell noindex closes a real path to ranking against our own customers. We'll report back when Search Console has something worth quoting, including if the answer is "nothing moved."

If the llms.txt items made your own list, the free llms.txt generator we host will build the link-map file from your page list — no sign-up attached. And if you run the nine checks and find your equivalent of the imageless Twitter card, we'd genuinely like to hear what it was: the whole audit started because we grepped our own HTML for a tag we were certain was there.

Additive column can 500 every login (Drizzle + Better Auth + preview deploys)

Omar Bni — Mon, 20 Jul 2026 10:45:12 +0000

Originally published on the Clanker Support blog.

Migration 0017_user_role.sql in our repo is one line of SQL under eighteen lines of comment, and the comment is the interesting part: it explains why the column it adds must never appear in our ORM schema. Declared the way every tutorial shows, that one additive column would have 500'd every authenticated request on any database that hadn't run the migration yet. "Additive nullable columns are always safe" is received wisdom, and on a modern stack it is false: ORMs like Drizzle and Prisma enumerate every mapped column on every SELECT, preview deploys run new code against old schemas, and auth libraries query your user table on every request — so one unmigrated column can fail every query that touches its table.

To be precise about what actually happened, because this is easy to overclaim: no production outage. What we had was a string of preview deploys 500ing on columns that existed only in code, and one near-miss — that role column — where the same mechanism pointed straight at the auth hot path. This is the failure mode we kept almost shipping, and the discipline that stopped it. Clanker Support is open source (theopenco/llmchat), so every file, commit, and PR below is public.

Why "additive columns are always safe" became folklore

The belief was earned, and it predates ORMs. Adding a nullable column — or a NOT NULL column with a default, the other blessed shape — rewrites nothing. In SQLite it's a metadata change; Postgres has done the same for defaulted columns since version 11. No lock, no backfill, no data risk. And the load-bearing clause: old code ignores columns it doesn't know about. SELECT id, email FROM user does not care what else the table grew this week.

That clause was true when column lists were handwritten. Then they started being generated from schema files that ship with the application code, and the clause quietly inverted: now the code can know about a column before the database does. Additive migrations are safe when the schema definition trails the database. They are dangerous when it leads — and on a modern deploy pipeline, it leads all the time.

Your ORM selects every column you map

Drizzle does not emit SELECT *. An unprojected select().from(user) expands to an explicit list of every column mapped on the table object in packages/db/src/schema.ts — for our user table, all seven of them, by name. Map an eighth column that the database doesn't have yet and every one of those queries throws no such column, including queries whose calling code never reads the new field. The migration isn't what breaks. Reads that predate the feature are what break.

This is not a Drizzle quirk. Prisma's generated client selects every scalar field by default unless you pass select. Rails people know the mirror image of this rule from column removal — you set ignored_columns before dropping, because the schema cache still names the column — but explicit-projection ORMs make column addition just as directional. Any ORM that generates its column lists from a checked-in schema has the same property: the table's every reader is coupled to the schema file's most recent line.

Preview deploys run new code against old schemas

For the mismatch to bite, some environment has to serve new code against an old database. Our platform hands us that environment on every branch: production deploys apply the migrations in apps/api/migrations/, preview deploys don't. A branch that adds a column and maps it in schema.ts gets a preview whose code names a column its database will never have. We watched exactly this — previews returning 500s for a column only prod would ever get — which is the cheap version of the lesson, paid in red preview checks instead of pages.

Previews are the guaranteed case, not the only one. A Vercel preview pointed at a shared staging database has the same gap, and so does a Neon branch-per-preview setup where the branch was snapshotted before your migration existed. So does every self-hosted install that pulls your code before running your migrations — and, potentially, production itself during the deploy window: our platform's docs don't specify whether migrations apply before the new worker starts serving traffic, so we defend against both orders rather than betting on one. The environments differ; the shape is identical: the schema file leads, the database trails, and the ORM faults on the gap.

The auth library that reads your user table on every request

Here is the multiplier that turns a red preview into a near-catastrophe. We were adding a platform-admin role to user for our internal admin console — a column that gates three admin routes only our own team calls. Its natural blast radius is approximately zero. Its actual blast radius, had we mapped it in Drizzle, is documented in a comment we now keep on the table itself:

// packages/db/src/schema.ts
// NOTE: the PLATFORM-admin role column (migration 0017_user_role.sql) is
// deliberately NOT modeled on this Drizzle table. Better Auth's Drizzle
// adapter loads the session user with an UNPROJECTED `select().from(user)`
// (every column of this table object) on every getSession, so declaring
// `role` here would make that auth hot-path query reference a column a preview
// DB — which skips migrations — does not have, 500-ing ALL authenticated
// requests.

Better Auth's adapter hydrates the full user object on every session check. That is not a bug, and we want to be fair about it: the adapter can't know which subset of columns your application needs, so returning the whole row is a reasonable contract, and Better Auth core has otherwise been solid for us. But it means the user table's column list is load-bearing for 100% of authenticated traffic, and any column you add to the mapping joins the hottest path in the system the moment you commit it. A column nobody reads would have taken down the inbox, the settings pages, sign-in — everything behind a session — on any lagging database.

The transferable lesson is not "audit your auth library". It's that your dependencies' query shapes are production behavior you own. You can read every line of your own code and still not know which of your tables gets an unprojected read per request.

Two PRs per schema change: migrate before you serve

The fix is old — the expand/contract pattern, in miniature. Every schema change on the tables our hottest paths read — message, conversation, user — ships as two pull requests. Phase 1 is the ALTER TABLE, its comment, and a seed-contract test; schema.ts is deliberately untouched, so no deployable code can name the column under any deploy ordering, in any environment. Phase 2 — the Drizzle mapping, the endpoints, the UI — merges only after phase 1 is live in production. We should admit the discipline is risk-scoped, not universal: lower-stakes columns on project — settings fields read by a handful of routes — still went out as single PRs (0016, 0020, 0021), which is a bet that nobody needs that table's preview to work that week. The hot tables don't get the bet. The migration files carry the reasoning in full, and they've become the best documentation in the repo:

-- apps/api/migrations/0022_message_reply_to.sql
-- PHASE 1 of 2 (deliberate migrate-before-serve split, mirroring 0014/0015).
-- Ploy's deploy ordering between "apply migrations" and "new Worker serves
-- traffic" is undocumented, so this PR ships ONLY the column — schema.ts is
-- intentionally NOT changed, so the live Worker never SELECTs a column that might
-- not exist yet (drizzle projects every column of `message`, and /v1/chat +
-- /v1/messages read it on the hottest paths; no read can 500 under any ordering).
ALTER TABLE `message` ADD COLUMN `reply_to_message_id` text;

We've run the split three times so far:

0014 conversation summaries — migration in PR #76, feature in PR #77, merged 24 minutes apart on June 22.
0015 resolve attribution — migration in PR #91, feature in PR #92, 41 minutes apart on June 29.
0022 quote-reply — migration in PR #142 on July 12, feature in PR #143 two hours later that night, once the column was confirmed live (the phase-2 commit message records that "migration 0022 is already live in prod").

That's the honest cost accounting: two PRs instead of one, and between 24 minutes and a couple of hours of waiting. Against that, for the changes we split, there is no deployable commit where code names the column before its migration is live in prod — the class of 500 becomes unrepresentable. The long comments are part of the discipline, not decoration: a one-line ALTER TABLE in its own PR looks like pointless ceremony six months later, and the comment is what stops the next person from helpfully collapsing it back into one.

The column we keep out of the ORM entirely

user.role is the extreme case: phase 2 never came, on purpose. Because the user table's mapping is read unprojected on every request, the column stays out of schema.ts indefinitely, and the admin gate reads it with a raw SQL projection wrapped in a fallback (the /admin/users listing uses the same guarded shape):

// apps/api/src/middleware/admin.ts
try {
    const rows = await db(c.env)
        .select({ role: sql<string>`role` })
        .from(user)
        .where(eq(user.id, userId))
        .limit(1);
    role = rows[0]?.role ?? null;
} catch {
    role = null;
}

On a database without the 0017 migration, the read throws, role degrades to null, and the requester is a non-admin — a 403, never a 500. Failing toward least privilege is the correct direction for an admin gate anyway, so the defensive shape costs nothing.

One loose end remained: Drizzle's query.user.findFirst without a columns option is also a select-everything of the row. Commit e287d58 swept the last two of those — billing checkout and project creation, each of which only ever read .email — down to explicit projections:

// apps/api/src/routes/billing.ts
const owner = await db(c.env).query.user.findFirst({
    where: (u, { eq: e }) => e(u.id, userId),
    columns: { email: true },
});

The invariant that fell out is easy to state and easy to check in review: exactly two queries in the codebase name role — the admin gate and the /admin/users listing — and both are wrapped in a try/catch that degrades to least privilege. Everything else touching user says which columns it wants. Once production and every preview convention has settled, the column can be folded into the schema like any other — the comment on the table says as much — but there is no hurry, because the current shape cannot break.

When a schema change needs the two-PR split

Change	Blast radius if code ships first	What to do
New table	None — no deployed code queries it	One PR is fine
New column, mapped in the ORM	Every ORM read of that table, via the generated column list	Two PRs: migration alone, then mapping + feature
New column on a table a dependency reads unprojected (auth, sessions)	Every authenticated request	Two PRs — or keep the column out of the ORM behind a guarded raw projection
Dropping a column	Deployed code still projects it during the rollout window	Two PRs in reverse: remove the mapping first, drop later
Self-hosted installs exist	You never control when they migrate	Treat every schema change as two-phase, always

The first question to ask about any table is the one we didn't know to ask: who reads it that you didn't write? For message it was our own hot paths, which we could see. For user it was our auth library, which we couldn't — until we looked at the queries it actually emits.

This is the second time that habit has paid for itself. When we moved the backend to workerd, the lesson was to audit transitive dependencies, not imports — the package that broke your deploy wasn't the one you installed. This one is the same lesson at the database layer: audit your dependencies' query shapes, not just your own reads. The code you didn't write is still your production behavior. The migration comments in apps/api/migrations/ are all public if you want the long-form version; they're better reading than most of our docs.

FAQ

Is adding a nullable column a safe migration?

Only if no deployed code selects it before it exists. The database operation is safe; the hazard is your ORM. Drizzle and Prisma generate explicit column lists from the schema definition, so a mapped-but-unmigrated column fails every read of that table — in previews that skip migrations, in self-hosted installs, and during the deploy window itself.

Why does my preview deploy fail with "no such column"?

Your branch maps a new column in the ORM schema, but the preview database never ran the branch's migration. The ORM names the column on every SELECT of that table, and the database rejects it. Ship the migration in its own PR first, and add the ORM mapping only after the column is live everywhere that serves traffic.

What is the expand/contract migration pattern?

Splitting a schema change so that every deployed version of the code works against both the old and new schema: add the column first (expand), deploy, then ship the code that uses it; for removals, delete the code references first, then drop the column (contract). Our two-PR split is the smallest useful version of it.

Changelog: July 2026, so far — the platform month

Omar Bni — Fri, 17 Jul 2026 23:40:54 +0000

We usually write these when the month closes. July's first two weeks shipped more than most full months, so here's everything so far — with more to come before August.

Clanker Support is an approved WordPress plugin. The plugin went through WordPress.org review and is now live in the plugin directory: install it, paste your project key under Settings → Clanker Support, and the widget is on every page — no code, and it survives theme changes. The launch post tells the whole story, including the zip file that was secretly a tar. A 1.0.1 followed within the week.

A Shopify app, running end to end. The Shopify app is built and deployed: a zero-permission theme app embed that puts the agent on your storefront without touching your orders, customers, or products. The App Store listing is in Shopify's hands; until it lands, the one-line script tag works on any store today — the Shopify guide has both paths.

The agent can now do things, not just say things. Agent integrations shipped: the agent can look up a customer's order on Shopify or book a meeting through Cal.com, right inside the conversation, with a "Working on it…" indicator while an action runs. We hardened this layer before shipping it — SSRF guards, per-conversation action limits, and an audit log of every action the agent takes — and scoped the agent to support-only via a base system prompt, so it stays your support agent even when a visitor tries to make it something else.

Dark mode, everywhere. The widget now supports data-theme="light" | "dark" | "auto" | "host" — auto follows the visitor's OS, and host mirrors your site's own theme toggle live, so the widget flips the instant your page does. The dashboard got dark mode too, and inline embeds accept a theme parameter so a dark page never frames a white chat.

The widget leads with chat. Conversations now start in the chat itself — the contact form is opt-in per project, for teams that want a name and email up front. Alongside it: an expandable large panel, admin-defined starter question chips (with a live chat preview in the dashboard while you edit them), an end-of-conversation rating prompt, and a proper "start a new conversation" flow.

Say "human" and it listens. If a visitor explicitly asks for a person — "can I talk to a human", "agent please", "I don't want to talk to a bot" — the escalation button appears immediately, before the usual message threshold. The matcher errs toward showing the option: a false positive costs one extra button; a false negative traps a frustrated customer with a bot.

Quote-reply in the chat. Visitors can reply to a specific earlier message, so "what about this one?" stays unambiguous in long conversations — for the visitor, the agent, and your team reading the thread later.

A notification bell in the dashboard. New conversations, escalations, and new visitor messages across the whole workspace, in one feed — and clicking a notification opens that exact conversation, even if you're already in the inbox.

An official React / Next.js package. @clankersupport/widget-rsc is on npm: one server component in your layout instead of a script tag. There's a tutorial if you're on Next.js or any React 19 app.

A real docs site. Product docs now live at docs.clankersupport.com — a getting-started path, a page per dashboard surface with real screenshots (light and dark), and integration guides for WordPress, Shopify, and the React SDK.

Free tools. An AI support savings calculator, CSAT calculator, canned response generator, and llms.txt generator — free, no signup, built because we kept needing them ourselves.

Email that behaves. Mail sent to your team address now forwards into the inbox reliably (and stops bouncing retries), and escalation replies keep threading straight back into the conversation.

That's two weeks. The Shopify listing decision, Slack notifications, and the public usage API are still in flight — see you at the end of the month.

Add an AI support agent to Next.js, WordPress, Shopify, or any site

Omar Bni — Wed, 15 Jul 2026 20:36:08 +0000

You can add an AI support agent to any website by pasting one <script> tag before </body>. On Next.js there's a Server Components SDK on npm, WordPress gets a plugin, Shopify gets an app embed, and an iframe covers builders that allow none of the above. This guide shows all five installs with working code.

Full disclosure up front: this is our product tutorial. We build Clanker Support, an open-source (MIT), self-hostable support agent that answers from your docs and escalates to a human when it should. Every snippet below is the real, current install path — including the two channels where we'll tell you plainly what's live and what's still on its way.

The script tag: works on every stack

This is the install we designed first, and it's the one everything else wraps. Paste this just before the closing </body> tag of your site:

<script
    src="https://api.clankersupport.com/widget.js"
    data-project="pk_your_project_key"
    async
></script>

That's the whole install. widget.js is a single self-contained file — React, the chat UI, markdown rendering, streaming, all inlined — served with a five-minute cache. The script mounts the widget into a shadow DOM appended to document.body, so your site's CSS can't break the widget and the widget's styles can't leak into your page. It loads async, so it never blocks your page render.

Your project key is safe to expose in HTML. It only identifies which project answers the chat — clankersupport.com itself runs the widget with its real key committed in the repo. The dashboard generates this snippet pre-filled for you under Projects → your project → Widget → Install.

Configuration lives in exactly five data-* attributes:

data-project (required) — your project's public key. Without it the script throws instead of silently doing nothing.
data-api (optional) — the API origin. Defaults to whatever origin served widget.js.
data-brand (optional) — accent color; defaults to #111827. Most people set this in the dashboard instead.
data-mode (optional) — bubble (default, the floating launcher) or inline.
data-escalation-threshold (optional) — how many visitor messages before the widget offers a human. The agent default is 3.

There is no sixth attribute. Position, welcome message, starter questions — those are project settings in the dashboard, fetched at runtime, so you can change them without touching your site's HTML.

The data-api default is the detail we're most pleased with. Here's the actual resolution logic from the widget source:

const apiUrl =
    script?.dataset.api ??
    (script?.src ? new URL(script.src).origin : window.location.origin);

The widget derives its API origin from the URL that served the script. So if you self-host — the whole product is MIT-licensed, bring your own model keys — you serve widget.js from your own domain and the exact same snippet points at your own API. Zero config divergence between hosted and self-hosted.

If you're on Rails, Django, Laravel, plain HTML, Astro, Vue, Hugo — anything that renders a </body> — this is your install, and you're done. Full reference: docs.clankersupport.com/integrations/widget.

Next.js: the React Server Components SDK

The script tag works fine in Next.js. But if you're on Next.js 15 / React 19, we ship a first-class package, @clankersupport/widget-rsc, that plays properly with the App Router. Three steps.

Install it — React 19 and React DOM are the only peer dependencies, and there are zero runtime dependencies:

npm install @clankersupport/widget-rsc

Render it once in your root layout, before </body>:

import { ClankerSupport } from "@clankersupport/widget-rsc";

export default function RootLayout({ children }) {
    return (
        <html lang="en">
            <body>
                {children}
                <ClankerSupport apiKey={process.env.NEXT_PUBLIC_CLANKER_KEY!} />
            </body>
        </html>
    );
}

And put the key in .env.local:

NEXT_PUBLIC_CLANKER_KEY=pk_your_project_key

What you get over the script tag: ClankerSupport is an async Server Component. It fetches your widget config (branding, privacy URL) on the server, cached and revalidated every five minutes, so the client never flashes the wrong branding. The fetch is wrapped in Suspense with a null fallback and returns null on any failure — if our API is slow or down, your page streams normally and the widget mounts with safe defaults. It fails soft; it never blocks your app.

There's also a headless entry, @clankersupport/widget-rsc/headless, with Radix-style unstyled primitives — data-* state attributes, asChild composition, and a useClankerSupport hook — for teams that want the agent behind their own UI entirely.

We wrote a full tutorial on how (and why) this package works: an AI support widget as a React Server Component. Reference docs live at docs.clankersupport.com/integrations/react-sdk.

WordPress: plugin via zip upload (today)

Honest status first: the plugin has been approved for the WordPress.org plugin directory, but as we publish this (July 2026) the listing isn't live yet. Until it is, you install it the classic way — a zip upload. No FTP, no code edits, but also not yet a one-click search-and-install from wp-admin.

The install today:

Build the zip from the plugin package in the GitHub repo: pnpm package inside packages/wordpress-plugin emits dist/clanker-support-<version>.zip.
In wp-admin: Plugins → Add New → Upload Plugin, pick the zip, activate.
Under Settings → Clanker Support, paste your project's public key and save.

The plugin (v1.0.1, GPLv2 or later, requires WordPress 5.8+ and PHP 7.4+) enqueues widget.js asynchronously with the same data-* attributes the dashboard snippet uses, on every public page and nowhere in wp-admin. Settings cover the floating-bubble toggle, the project key, the API URL (default https://api.clankersupport.com, changeable if you self-host), brand color, and escalation threshold. The settings page runs a live connection check against the API and shows you a status pill, so a typo'd key fails loudly at save time instead of silently on your live site.

If you want the chat in a page instead of (or as well as) the floating bubble, there's a shortcode that renders the full-page chat in an iframe:

[clanker_support]
[clanker_support width="500" height="700"]

Default size is 400×600, and it works independently of the bubble toggle. The plugin stores exactly one option and one transient in your WordPress database — conversations live in Clanker Support, not in WP — and uninstalling removes both.

The launch post has the longer story: our WordPress AI support plugin. Reference: docs.clankersupport.com/integrations/wordpress.

Shopify: app embed now, App Store listing on the way

Same candor here: the Clanker Support Shopify app exists, is deployed, and works — it's a theme app extension we've tested on a live storefront. The public Shopify App Store listing is on its way but not live yet as we publish (July 2026). Until it lands, any Shopify store can run the agent today with the script tag.

The manual path today: Online Store → Themes → Edit code → layout/theme.liquid, paste the script tag from the first section just before </body>, save. Done — same widget, same dashboard.

Once you have the app installed, the flow is nicer: paste your project key on the app's settings page in Shopify admin, then in the theme editor open App embeds, toggle Clanker Support on, and hit Save. One thing Shopify makes per-theme: app embeds don't follow you when you publish a different theme, so re-enable the toggle after a theme switch.

Two design decisions worth knowing before you install anything on a store:

Zero permission scopes. The app requests no access to your orders, customers, or products. It stores only its own settings. If a support app asks for read access to your entire order history just to render a chat bubble, ask why.
A double-bubble guard. If the manual script tag is already in your theme when you enable the app embed, the embed detects it and stands down. One widget, never two — we verified this in testing because we knew people would migrate from the manual install.

The widget loads after page load, so it doesn't drag on storefront performance scores. Uninstalling the app removes the embed and clears its stored data. Reference: docs.clankersupport.com/integrations/shopify.

Everything else: the iframe embed

Some platforms won't let you add a script tag at all — locked-down site builders, sandboxed help-center pages, internal tools. For those, the API serves a CSP-hardened full-page chat at /embed/<key> that you can iframe from anywhere:

<iframe
    src="https://api.clankersupport.com/embed/pk_your_project_key"
    width="400"
    height="600"
    title="Support chat"
    style="border: 0; border-radius: 12px;"
    loading="lazy"
></iframe>

The embed page mounts the widget in inline mode with your project's brand color and escalation threshold baked in server-side — it reads them from your project settings, so there are no attributes to pass and nothing to update when you rebrand. Its Content-Security-Policy locks down everything except the one thing an embed must allow:

default-src 'none'; script-src 'self'; style-src 'unsafe-inline'; connect-src 'self'; img-src 'self' data:; base-uri 'none'; form-action 'none'; frame-ancestors *

frame-ancestors * because being iframed by any site is the point; everything else is shut. It also ships noindex, a no-referrer policy, and denies camera/microphone/geolocation/payment outright.

One more use for it: open the embed URL directly in a browser tab and you're talking to your agent — the fastest way to test your knowledge base before installing anything anywhere.

Which install should you pick?

Our honest decision guide, shortest answer first:

Any server-rendered or static site (Rails, Django, Laravel, Astro, plain HTML, Hugo, ...): the script tag. It's the product's native install; everything else is a wrapper around it.
Next.js 15 / React 19: the @clankersupport/widget-rsc SDK if you want server-fetched config, Suspense fail-soft behavior, or the headless primitives. The plain script tag in your layout is also completely fine — don't add a dependency you don't need.
WordPress: the plugin, because the settings page, connection check, and shortcode earn their keep — but know it's a zip upload today, not a directory search result.
Shopify: script tag in theme.liquid today; switch to the app embed when the listing is live (the double-bubble guard makes the migration safe).
Site builders with no script access: the iframe embed. It's the fallback that works when nothing else is allowed.

And when not to use us at all: if your support runs primarily over WhatsApp, SMS, or phone, we don't do those channels — we're web widget plus email threading. And there's no free hosted tier; if you want free, the answer is self-hosting with your own model keys, which is a genuine first-class path, not a demo.

After install: two things before you close the tab

Whichever channel you installed through, the same product is behind it, and an agent with nothing to read is just an apology generator. Two setup steps make the difference:

Add knowledge sources. In the dashboard, a project's knowledge base takes three source kinds: URLs (we crawl the page into a snapshot — there's a re-crawl button when your docs change), free-text snippets, and hand-written Q&A pairs for the questions you already answer weekly. There's no vector database in the pipeline — sources are byte-budgeted directly into the system prompt — and the models can search the live web when a question goes beyond your docs. Later, when an operator writes a particularly good reply in the inbox, you can promote it into the knowledge base straight from the thread, so the agent learns your best answers.

Set your escalation email. When a visitor asks for a human (or the agent decides it's out of its depth), the conversation escalates: an email goes to your project's notify address and, optionally, a message to a Slack webhook. The email's Reply-To is wired so that just replying from your inbox threads your answer straight back into the visitor's chat — no dashboard login required, though the dashboard inbox (tags, search, AI triage summaries, unread counts) is there when you want it. We wrote up how the email threading works in setting up email threading.

Visitors can rate individual answers thumbs up/down and leave a 1–5 CSAT when the conversation closes, so you'll know quickly whether the sources you added are pulling their weight.

FAQ

How do I add an AI support agent to my website without a developer?

If you can paste one line of HTML before </body>, you can install it yourself — the dashboard generates the exact snippet with your key pre-filled. On WordPress it's a plugin upload with a settings page and no code at all. The only genuinely no-code-access path is the iframe embed, which needs just an embed block.

Does a support widget slow down my site?

Ours is designed not to: the script loads async so it never blocks rendering, it's a single self-contained file cached for five minutes, and it mounts into a shadow DOM after the page is up. On Shopify specifically, the embed loads after page load so storefront performance scores aren't affected.

Can I use the same widget if I self-host?

Yes — that's a deliberate design decision. The widget resolves its API origin from wherever widget.js was served, so a self-hosted install uses the identical snippet pointed at your own domain. The whole product is MIT-licensed on GitHub; self-hosting is free with your own model keys.

How much does a hosted AI support agent cost?

As of July 2026, our hosted plans are Starter at $19/month (2,000 AI responses, hard stop), Growth at $89/month (12,000), and Scale at $299/month (50,000), with annual billing giving two months free. Pricing is per workspace — no per-seat fees and no per-resolution fees — and there's no free hosted tier. Details on /pricing.

How does the agent know what to answer?

It answers from your project's knowledge base — crawled URL snapshots, text snippets, and hand-written Q&A pairs — combined with your system prompt, on web-search-capable models via LLM Gateway. When it can't answer, it escalates to your email and Slack instead of improvising.

Our AI support agent doesn't use RAG - here's the math

Omar Bni — Mon, 13 Jul 2026 11:34:44 +0000

Clanker Support's AI support agent has no vector database, no embeddings, and no retrieval pipeline. On every chat request we load every active knowledge source for the project and place it, budgeted to 80,000 characters, directly into the system prompt. For a support knowledge base measured in kilobytes, this beats RAG on simplicity, freshness, and recall — and we can show you exactly where it stops being true.

This is not a "RAG is dead" post. RAG is the correct architecture for corpora that don't fit in a context window. Our argument is narrower and, we think, more useful: most per-project support knowledge bases are tiny, context windows are large, and building an embedding pipeline before you've hit the ceiling is complexity you pay for every day and benefit from never. Here's the code, the arithmetic, and the honest failure mode.

The entire retrieval pipeline is a WHERE clause

Clanker Support is an open-source support widget (github.com/theopenco/llmchat). When a visitor sends a message, the API needs to decide which knowledge to show the model. Here is the entirety of that decision, from apps/api/src/routes/chat.ts:

const activeSources = await db(c.env).query.source.findMany({
    where: (s, { and: a, eq: e }) =>
        a(e(s.projectId, project.id), e(s.active, true)),
});

No query embedding. No similarity search. No reranker. Every active source for the project, every time. The sources come in three kinds — url (a one-shot snapshot of a single web page), text (a pasted snippet), and qa (a question/answer pair, either hand-written or promoted from a real operator reply in the inbox).

Those sources then flow into a prompt builder that assembles one string: a hardcoded support-only guardrail, the operator's own system prompt, a free-text knowledge field, a # Reference sources block, and finally an identity block for the visitor. The reference block is where the only "retrieval" decision in the codebase lives:

// Cap aggregate source content to keep system prompts bounded. ~80k chars
// ≈ 20k tokens — well below typical 128k context windows but leaves room
// for knowledge base + conversation history.
const MAX_SOURCES_CHARS = 80_000;

And the "chunking strategy" is an even split and a slice:

// Distribute the budget across sources so a single huge page can't
// crowd out the rest.
const perSource = Math.floor(MAX_SOURCES_CHARS / usable.length);
const rendered = usable
    .map((s, i) => {
        const body =
            s.content.length > perSource
                ? `${s.content.slice(0, perSource)}…`
                : s.content;

That's it. floor(80000 / N) characters per source, an ellipsis if it overflowed, a ## Source N: <title> header on each, and an instruction to the model to cite the source title or URL when it uses one. A dozen lines of arithmetic where a RAG system would have an ingestion worker, a chunker, an embedding model, a vector store, and a retriever — each one a place for bugs to live and data to go stale.

How much knowledge fits in an 80k-character budget

Let's do the honest math, using the same rough heuristic the code comment uses (~4 characters per token — real tokenization varies, so treat all token figures here as approximate).

The aggregate budget is 80,000 characters, roughly 20,000 tokens of reference material per request.
A URL source maxes out at 20,000 characters of extracted text. The snapshot fetcher reads at most 200 KB of raw body, strips markup with regexes, and slices the result to 20k chars (all three limits sit at the top of apps/api/src/lib/fetch-url.ts: MAX_BYTES = 200_000, MAX_CHARS = 20_000, TIMEOUT_MS = 10_000).
So the budget holds at most 4 full-size page snapshots. At 5 or more, floor(80k/N) drops below 20k and full pages start truncating each other.
10 sources → 8,000 chars (~2,000 tokens) each. 20 sources → 4,000 chars each. 40 sources → 2,000 chars — roughly 300 words — each.

For context on what real support KBs look like: a text snippet source caps at 50,000 characters at creation, and a promoted Q&A pair caps at 2,000 characters of question plus 8,000 of answer. A typical per-product support KB is a handful of doc pages, a pricing page, and a growing pile of Q&A pairs promoted from the inbox. That's tens of kilobytes. The budget swallows it whole, and the model sees everything on every question.

That last part is the underrated win. RAG doesn't just add infrastructure — it adds a new failure mode: the retrieval miss, where the answer existed in your corpus but the top-k didn't surface it, and the model confidently answers without it. When the whole KB is in the prompt, recall is 100% by construction. There is nothing to miss.

What it actually costs per message

No free lunch. The whole knowledge base rides in the system prompt of every request — the prompt is rebuilt and re-sent on every turn of the conversation. A visitor typing "hi" to a project with a full source budget costs roughly 20,000 input tokens of reference material before the operator prompt, the conversation history, or the message itself.

We can see this directly because metering records the real prompt and completion token counts per response into a usageEvent row. Prompt token counts grow linearly with KB size times message volume. That's the structural cost of prompt stuffing, and it's worth being clear-eyed about: RAG exists partly to not pay this.

Two things keep it bounded for us:

Input is the cheap direction. Model pricing is heavily skewed toward output tokens — on the major providers' price lists as of mid-2026, output tokens run several times the per-token price of input — and our output is hard-capped:

// Hard ceiling on a single support reply's completion — bounds per-response cost
// on the shared operator key. A support answer fits comfortably; the summary
// path caps far tighter (60).
const MAX_CHAT_OUTPUT_TOKENS = 2_000;

That cap is pinned by a unit test — it also bounds the blast radius of a prompt injection along the lines of "write 5000 words…" (the code comment's own example).

The budget is a ceiling, not a typical case. A KB of the shape above sits far below 80k characters of active sources, so the per-message overhead is a fraction of the worst case.

There's a second cost people forget to weigh: the cost of the RAG pipeline you didn't build. An embedding pipeline is not a one-time expense. It's re-embedding on every source edit, keeping the vector store in sync with the source-of-truth rows, versioning the embedding model, debugging why a chunk boundary split a refund policy mid-sentence, and explaining to an operator why the agent ignored the doc they just uploaded. Every one of those is a moving part that can silently drift. Our KB has exactly one representation — the text in the database — and what the model sees is a pure function of it. When something goes wrong, we read one assembled string.

That single-string property compounds in a direction we didn't fully appreciate at first: security review. Because the prompt is one deterministic assembly, injection defenses are string-level and unit-testable — visitor-supplied identity is sanitized (control characters and fence glyphs stripped, length-capped) and fenced between markers explicitly labeled as unverified data, and the tests pin that the support-only guardrail is prepended on every assembly. Auditing "what can an attacker put in front of the model" is a code read, not a data-pipeline archaeology dig.

Where this breaks, and how it fails

Honesty section. The failure mode is real and it's silent.

The ceiling is about 4 full-size pages. Past that, the even split truncates every source, and the tail of each long page becomes invisible to the agent. There's no error, no warning — the model just doesn't know things that are technically "in" the knowledge base. Because the split is arithmetic rather than relevance-ranked, a question answered in the truncated tail of source 3 fails even though a smarter system holding the same budget would have surfaced that passage. This is precisely the problem retrieval solves, and we don't pretend otherwise.

URL snapshots go stale. The fetcher grabs one URL, once, at creation. Refresh is a manual re-crawl button in the dashboard — deploying new docs does not update the agent until someone clicks it. There's no scheduled re-fetch today. We've tripped over this ourselves: we dogfood the widget on our own site, and shipping a docs change is not the same as re-snapshotting it for the agent.

Long-tail docs sites don't fit. If your product has 300 documentation pages, an even 266-character sliver of each is worse than useless. That's not a "tune the budget" problem; it's a "you need retrieval" problem.

We mitigate the ceiling in two ways that are cheaper than embeddings, and we think both are interesting design points on their own.

How web-search models change the calculus

Every model our agent can serve is web-search-capable, by construction. The allowed model list is generated from LLM Gateway's model catalog filtered to providers that advertise web search, and a guard in the chat route coerces any saved non-web-search model back to the default (gpt-5.4-mini). So the agent can reach the live web when answering.

This matters for the RAG question because a support KB is unusual among corpora: most of it is already on the public web. Your docs site, your pricing page, your changelog — the things a support agent needs are the things you publish. When the snapshot in the prompt is stale or truncated, the model can go look at the actual page. The prompt-stuffed KB becomes the fast path and the grounding; live search is the backstop for freshness and depth.

Two honest caveats. First, whether and when a model actually searches is up to the model and provider — "web-search-capable" is a capability flag, not a guarantee, so this is a mitigation rather than automatic RAG-over-the-web. Second, search only backstops public knowledge; internal policies and unpublished answers still have to live in the KB proper. (Being self-hostable makes that second category more comfortable to store at all — the argument in the case for self-hostable AI support.)

Curation beats ingestion: promoting real answers into the KB

The second mitigation is about what goes into the budget. The highest-value knowledge a support agent can hold isn't a crawled page — it's the answer a human already gave to this exact question. Our inbox has a "promote to knowledge base" action on any operator reply: it takes the reply, pairs it with the nearest preceding visitor message as the question, and stores it as a qa source. The stored content is literally:

const content = `Q: ${finalQuestion}\nA: ${finalAnswer}`;

Two lines. Deduped by source message, so promoting the same reply twice returns the existing source. A promoted Q&A is small (10k characters max), dense, and pre-validated by an actual human answering an actual customer — the opposite of a 20k-character page snapshot that's mostly navigation boilerplate. A KB grown this way stays comfortably inside the budget far longer than a KB grown by snapshotting every page of your docs site, and it improves exactly where your visitors demonstrated the gaps. It's the same instinct behind using AI as the first response and humans as the curriculum: the escalations teach the agent.

What we'll build when a customer blows past the budget

Our position is "you might not need RAG yet," not "you don't need RAG." The trigger is concrete: when a real customer's KB meaningfully exceeds ~4 full pages of unique, non-promotable content — a genuine long-tail docs corpus — even splitting stops being defensible, and we'll build retrieval. When we do, it'll be the boring, proven shape: chunk sources at ingestion, embed chunks, embed the visitor's question at query time, put the top-k chunks into the same # Reference sources block the prompt builder already renders. The prompt assembly, citation instruction, and injection fencing all stay; only the WHERE clause grows a brain.

What we won't do is build it speculatively. Every week the pipeline doesn't exist is a week we don't debug sync drift, don't re-embed on edits, and don't explain retrieval misses. The constants in llm.ts are doing the job a vector database would do, in twelve lines, with unit tests pinning the behavior. When the ceiling stops being theoretical for our users, the code knows exactly where retrieval slots in.

If you want to poke at the real thing, the agent answering questions on our live demo is running exactly the code quoted above, and the whole repo is MIT-licensed if you'd rather read the source than take our word for it.

FAQ

Do I need a vector database for an AI support agent?

Not if your knowledge base fits in the model's context window with room to spare. A typical per-product support KB — some doc pages, a pricing page, curated Q&A — is tens of kilobytes. We budget 80,000 characters (roughly 20k tokens) of sources per request and stuff them all in. You need a vector DB when your corpus is large enough that this either truncates badly or costs too much per message.

Is prompt stuffing cheaper than RAG?

Per message, no — you re-send the whole KB on every turn, so input tokens scale with KB size times message volume, where RAG sends only the retrieved chunks. In total cost of ownership, often yes for small KBs: you skip the embedding pipeline, vector store, sync logic, and the engineering time to keep them honest. Input tokens are also the cheap direction on most model pricing.

What happens when the knowledge base is too big for the prompt?

In our implementation, each source gets an even share of the 80k-character budget — floor(80000 / N) characters — and anything past its share is silently cut. Past about 4 full-size page snapshots, sources start truncating each other and the model can't see the tails. That silent truncation is the honest failure mode of this design, and it's the point where real retrieval earns its complexity.

Can web search replace RAG for customer support?

Partially. Support is unusual in that most of the corpus (docs, pricing, changelogs) is already public, so a web-search-capable model can fetch the live page when the in-prompt snapshot is stale or truncated. But search is model-discretionary — a capability, not a guarantee — and it can't reach internal or unpublished knowledge, so it's a backstop for a prompt-based KB rather than a substitute for retrieval at scale.

When should I add RAG to an LLM application?

When you can name the failing query. If you can point at real questions that fail because the relevant passage didn't fit in the prompt — not hypothetically, but in your logs — retrieval will pay for itself. If you can't, you're building infrastructure to solve a problem you haven't got, and every part of it (chunking, embeddings, sync) is a maintenance surface that starts costing the day it ships.

Everything that broke while shipping an embeddable AI widget

Omar Bni — Sun, 12 Jul 2026 16:28:47 +0000

Here is what broke while shipping the Clanker Support widget as a one-script-tag embed: Shopify's Dawn theme hid it entirely with div:empty { display: none }; a 62.5% root font-size shrank it to 10/16 scale straight through the shadow DOM; document.currentScript was null when we read it too late; and our server had no filesystem to serve the bundle from. Each breakage became a rule; this post walks through all of them.

An embedded widget is a strange artifact. It's a React app, but it runs inside a page built by someone else, styled by someone else, bundled by someone else, and served from infrastructure you'll never see. Every assumption a normal web app gets for free — sane resets, a 16px root, a predictable script lifecycle — is up for grabs. Shadow DOM helps less than you'd hope, and we'll get precise about exactly where it stops helping.

Why the widget is one file

The widget is a Vite lib build, IIFE format only, one entry (src/mount.tsx), one output (widget.js). Two config lines do most of the work:

inlineDynamicImports: true — no lazy chunks, ever. A second chunk means a second network fetch from a URL the bundle has to compute at runtime, on a page whose base URL, CSP, and bundler you don't control. One file has one failure mode.
cssCodeSplit: false — the CSS ships inside the JS (more on how below).

Single-file IIFE has a sharp edge, though: every transitive dynamic import in your dependency tree gets inlined whether you wanted it or not. Our markdown renderer, Streamdown, lazy-loads mermaid to render diagram blocks. In an app that's a nice deferred chunk; in an inlined IIFE it's the whole mermaid library riding along in widget.js for a feature support replies will never use. The fix is an alias to a stub:

    resolve: {
        alias: {
            // Streamdown lazy-loads mermaid for ```mermaid blocks. The widget is a
            // single inlined IIFE, so that lazy chunk gets inlined and would pull in
            // the whole (~MB) mermaid library. Support replies never contain
            // diagrams, so alias it to a no-op stub to keep widget.js small.
            mermaid: fileURLToPath(new URL("./src/mermaid-stub.ts", import.meta.url)),
        },
    },

The stub is a no-op object: initialize() does nothing, render() returns { svg: "" }. If a diagram block ever appears, it renders nothing instead of costing every visitor the download.

One more lib-mode gotcha: Vite keeps React's process.env.NODE_ENV references in a lib build, and there is no process in a browser. Without define: { "process.env.NODE_ENV": JSON.stringify("production") }, the widget throws a ReferenceError on the very first page it's embedded in.

Rule: ship a single-file IIFE, and audit what inlining drags in. Every dynamic import in your dependency tree is a hidden passenger.

Shadow DOM isolates selectors, not the cascade

We mount into a shadow root: append a host <div> to document.body, attachShadow({ mode: "open" }), inject a <style> element, render React into it. Host-page selectors can't reach inside; our selectors can't leak out. That's the sales pitch, and the part about selectors is true.

But two things pass straight through the shadow boundary: inherited properties and unit resolution. The host page's font-family, line-height, text-align, and letter-spacing all inherit into your shadow tree unless you pin them. So the top of our stylesheet is a wall of explicit values — font-size: 16px, line-height: 1.5, letter-spacing: normal, text-align: left on :host — plus a box-sizing: border-box reset on every element, because host pages love universal selectors and you don't get to assume content-box never leaked in from a parent frame's expectations.

We thought that wall made us safe. Then we tested the Shopify theme-app extension on a Dawn dev store, and the host page got us twice in one afternoon — once by reaching around the shadow DOM, once by reaching through it.

The day the widget vanished on Shopify Dawn: div:empty

First bug: on a stock Dawn store, the widget didn't render. Not broken — absent. No bubble, no errors, nothing.

The diagnosis is the kind you only get by staring at computed styles. All of the widget's content lives in the shadow root. From the light DOM's point of view, the host <div> we append to document.body has no children — it is, structurally, empty. And Shopify's Dawn theme ships this in base.css:

div:empty {
    display: none;
}

A perfectly reasonable rule for a theme to ship, and it hides your entire embed. The host page's stylesheet never touched a single element inside our shadow root — it didn't need to. It matched the one element we own in the light DOM and removed it from layout, shadow tree and all. Dawn is Shopify's default theme, so this was every Dawn-based store, which is a lot of stores.

The fix is one small function (commit e18586e, shipped as PR #111):

export function createWidgetHost(doc: Document): HTMLDivElement {
    const host = doc.createElement("div");
    host.id = "llmchat-widget-root";
    host.style.setProperty("display", "block", "important");
    return host;
}

Why an inline important declaration and not a rule in our stylesheet? Because our stylesheet lives in the shadow root, and the div:empty rule matches a light-DOM element — a shadow style can't win that fight. In the cascade, an important inline declaration outranks any stylesheet rule, important or not. It's the one place we can plant a flag the host page cannot override short of JavaScript.

Rule: your shadow host is :empty in the light DOM — plan for it. Either your host element has light-DOM content, or you defend its display with an inline important declaration like we did. Hiding empty divs is a common theme pattern; assume it's out there.

38 minutes later: rem resolves through shadow DOM

With the bubble finally visible on Dawn, the second bug was immediately obvious: the widget was tiny. The 56×56px launcher bubble measured 35×35. Panel text rendered around 10px. Everything was scaled by exactly 10/16.

That fraction is the tell. Dawn — like a lot of themes and older CSS codebases — sets html { font-size: 62.5% } so that 1rem = 10px for convenient arithmetic. And here's the part that surprises people: rem resolves against the host page's root font-size even inside shadow DOM. The shadow boundary doesn't intervene. rem means "root em," and the root is <html> — the host's <html>. There's no shadow-local root to resolve against.

Our stylesheet had 160 rem values in it. Every one of them was silently multiplied by 10/16 on any 62.5%-root page. Note what didn't break: text that inherited from our pinned font-size: 16px was fine, which is exactly why the widget had looked correct everywhere else — the font-size pin protected inherited text while every rem-denominated dimension (padding, radii, the bubble itself) quietly depended on a root we don't own.

The fix (commit 445af84, PR #113, 38 minutes after the Dawn fix) was mechanical: multiply all 160 values by 16 and write them as px. A 273-line diff of pure unit conversion, and a comment in the stylesheet so nobody "modernizes" it back:

/* Pin inherited properties so the host page's typography can't leak across
       the shadow boundary and distort the widget. Dimensions are px throughout
       (never rem): rem resolves against the HOST page's root font-size even
       inside shadow DOM — Shopify's Dawn sets html to 62.5%, which shrank the
       whole widget to 10/16 scale. */
line-height: 1.5;
font-size: 16px;

Inside an app you control, rem is good practice — it respects user font-size preferences. Inside an embed, rem is an unversioned runtime dependency on a value the host page sets. Those are different products with different rules.

Rule: in an embed, ship px, not rem. The two Dawn bugs make a matched pair, and together they're the thesis of this post: shadow DOM isolates selectors. It does not isolate inheritance, and it does not isolate unit resolution. The host page reached around our shadow root (the :empty match on the light-DOM host) and through it (rem resolving against the host root) on the same day, two PRs apart.

Things nobody tells you about script-tag embeds

Two smaller breakages, both about the <script> tag itself rather than CSS.

document.currentScript is a now-or-never API. The widget reads its config from data attributes on its own script tag — data-project, data-api, data-brand, data-mode. To find "its own script tag" it uses document.currentScript, which is only set during synchronous evaluation of the script. Defer your config read into a DOMContentLoaded callback — the natural place, since you can't mount before the body exists — and currentScript is null. So the config capture and the mount are split:

// document.currentScript is only set during synchronous script evaluation —
// it is null inside the DOMContentLoaded callback — so capture config now.
const config = resolveConfig(
    document.currentScript as HTMLScriptElement | null,
);

Config is resolved at top level, synchronously, the moment the script evaluates; only the DOM mount waits for readyState.

Derive your API origin from the script's own src. Where should the widget send chat requests? The obvious answer — hardcode the production API host — is a trap: every local dev embed, staging embed, and self-hosted install would silently talk to prod. The correct default was sitting in the script tag all along:

const apiUrl =
    script?.dataset.api ??
    (script?.src ? new URL(script.src).origin : window.location.origin);

Whatever origin served widget.js is, by construction, an origin running our API — the API is what serves the widget bundle. Local dev loads the widget from localhost and talks to localhost; a self-hosted install (the whole thing is open source and self-hostable) talks to itself; data-api remains as an explicit override. No environment detection, no build-time host baking.

Rule: capture currentScript synchronously, and make the script's own origin your API default.

Serving widget.js from a server with no filesystem

Our API runs on workerd — the Cloudflare-workers-compatible runtime — where there is no filesystem to read a built asset from. But /widget.js has to come from somewhere, ideally the same origin as the API (see the previous rule).

The answer is unglamorous: after vite build, a script reads dist/widget.js and writes it into a generated TypeScript module as one JSON-stringified constant. The API imports that module and serves the string from memory with content-type: application/javascript, x-content-type-options: nosniff, and cache-control: public, max-age=300. The generated file is gitignored; the API's deploy pipeline builds the widget first, so the constant is always fresh.

The five-minute cache is a deliberate embed-specific choice. Host pages pin your URL in their HTML forever — you can't cache-bust an asset whose URL is copy-pasted into <script> tags in HTML you don't control. Short max-age means a shipped fix (like either Dawn fix) reaches every embed within minutes, at the cost of more origin hits. For a support widget, that trade is easy.

Rule: an embed URL is immutable to you, so keep its cache lifetime short.

The iframe fallback and its upside-down CSP

Some environments can't or won't run third-party script tags — strict CSPs, locked-down site builders, "no external JS" policies. For those we serve /embed/<key>: a full-page chat shell designed to be iframed. (For hosts that do give you a real integration surface, we've written up the React Server Components install and the WordPress plugin separately.)

Writing the CSP for that page was a small lesson in itself, because it's a normal CSP turned inside out:

c.header(
    "content-security-policy",
    "default-src 'none'; script-src 'self'; style-src 'unsafe-inline'; connect-src 'self'; img-src 'self' data:; base-uri 'none'; form-action 'none'; frame-ancestors *",
);

Every app-hardening guide tells you to lock down frame-ancestors. Here frame-ancestors * is the entire point — being framed by arbitrary sites is the product — so everything else gets locked to nothing: no forms, no base-URI tricks, scripts and connections from self only. style-src 'unsafe-inline' looks alarming until you remember the widget's whole stylesheet is one <style> element in a shadow root; that's the mechanism, not a compromise.

One subtle line in that page: the widget script src is relative, not an absolute URL built from the request. Behind a TLS-terminating proxy the worker sees http://, and an absolute http:// script URL on an https:// page is mixed content — blocked before your code ever runs. A relative src inherits the page's real scheme and sidesteps the whole class of bug.

The rules, collected

Ship a single-file IIFE. Inline dynamic imports; stub out heavyweight transitive lazy-loads (our mermaid alias) instead of shipping them.
Define process.env.NODE_ENV at build time. Vite lib mode won't do it for you, and browsers have no process.
Pin every inherited property at your shadow root. Font, line-height, letter-spacing, text-align, plus a box-sizing reset. Shadow DOM only isolates selectors.
Your shadow host is :empty in the light DOM. Give it light-DOM content or defend display with an inline important declaration; theme CSS that hides empty divs is real and widespread.
Ship px, not rem. Inside an embed, rem is a dependency on the host page's root font-size — even through shadow DOM.
Capture document.currentScript synchronously. It's null by the time DOMContentLoaded fires.
Default your API origin to new URL(script.src).origin. Never a hardcoded host; keep an explicit override attribute.
Serve the bundle from your API's origin with a short max-age. Embed URLs are pinned in HTML you don't control; five minutes is our propagation ceiling for fixes.
If you offer an iframe mode, invert the CSP. frame-ancestors * on purpose, everything else 'none' or 'self', and a relative script src so TLS-terminating proxies can't hand you mixed content.

All of this code is public — the widget, the stub, both Dawn fixes with their commit messages — in the repo, and you can poke the live widget at showcase.clankersupport.com. If you're building your own embed, steal the rules; we already paid for them, one Dawn dev store at a time.

DEV Community: Omar Bni

The Clanker Support WordPress plugin is approved — here's how it was built

Why a plugin at all

What we built

The build: shipped in a day, rebuilt the next

The review: three rejections' worth of lessons

Using it

Add AI customer support to your Next.js app with one Server Component

What you'll need

Step 1: Install the SDK

Step 2: Add the widget to your root layout

Step 3: Make it yours

Step 4: Restyle with CSS

Step 5: Go headless when CSS isn't enough

What you get out of the box

Self-hosting

I spent an hour trying to break my own product with 12 languages. It won.

The frame that sold me on my own product

The kicker

And now it does it out loud

The one rule that survives all of this

We Audited Our Marketing Site Against Our Codebase and Found 6 Lies

The six claims that failed the diff

One page undersold us

The re-pass found 18 more, four written during the fix

Diff your homepage against your repo

The cheapest credibility available

FAQ

How do you audit marketing claims against a codebase?

What is claim drift?

Should the fixes be public?

Two messages, one sequence number: the concurrency bug that never threw

Two sins, one write path

Why every test passed

The fix shipped in three steps, and the order is the point

Clean the data first

One writer, and the database allocates the key

The unique index that makes any regression loud

Drizzle buries the error your retry path needs on .cause

The five-second audit

FAQ

How do you safely generate a per-group sequence number in SQLite or D1?

Why isn't a unique index alone enough to fix a sequence race?

Why doesn't err.message contain "UNIQUE constraint failed" with Drizzle?

Every hosted plan now starts with a 7-day free trial

The trial is the whole plan, not a preview

Why we ask for a card

When the seven days end

Already a customer?

Self-hosting stays free

How to start

Questions you might have

Why do you require a card for a free trial?

What happens when the 7 days end?

Does usage during the trial cost anything?

I already subscribe — do I get a trial if I switch plans?

Is self-hosting still free?

Start wherever you're comfortable

Next.js merges metadata shallowly your og:image is probably missing (plus a 9-point AI SEO audit checklist)

The checklist

Why your Next.js pages have no og:image

robots.txt Disallow doesn't deindex — it does the opposite

Your product mints URLs on your domain — noindex them at the product level

What we ship for AI crawlers, and what we deliberately don't block

The smaller line items

What we can't tell you yet

Additive column can 500 every login (Drizzle + Better Auth + preview deploys)

Why "additive columns are always safe" became folklore

Your ORM selects every column you map

Preview deploys run new code against old schemas

The auth library that reads your user table on every request

Two PRs per schema change: migrate before you serve

The column we keep out of the ORM entirely

When a schema change needs the two-PR split

FAQ

Is adding a nullable column a safe migration?

Why does my preview deploy fail with "no such column"?

What is the expand/contract migration pattern?

Changelog: July 2026, so far — the platform month

Add an AI support agent to Next.js, WordPress, Shopify, or any site

Drizzle buries the error your retry path needs on `.cause`