From e28fc6c8dd153e9a4cc8b2638dc397ee5fa2a5d9 Mon Sep 17 00:00:00 2001
From: Anthony Ettinger <anthony@chovy.com>
Date: Thu, 30 Jul 2026 09:27:01 +0000
Subject: [PATCH] feat(ads): terminal (ASCII) ad format served as plain text
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Terminals can't run /ad.js and can't render HTML, so the ad network had
nothing to sell to shells, SSH banners, BBS screens, or CLIs. This adds a
terminal_ascii format that is fetched, not embedded:

  curl -s "https://crawlproof.com/api/ads/motd?slot=<id>"

- lib/ads/terminal.ts renders a fixed-width, pure-ASCII box. Advertiser
  copy is untrusted text going straight into a TTY, so escapes/control
  chars are stripped and non-ASCII is folded (accents) or dropped (CJK,
  emoji) — both to keep terminals safe and to keep column maths honest.
- /api/ads/motd returns text/plain, with ?cols=44..120, ?color=1 for ANSI,
  and ?src=<tag> to tell surfaces apart. Impressions meter server-side via
  serveAd exactly like the HTML paths; an unknown slot falls back to the
  house ad so a login banner is never blank.
- Terminal clients identify as curl/wget/etc., which the tracker buckets
  as "bot". On this endpoint that's the actual audience, so a dedicated
  classifier lets shell clients through while still excluding crawlers.
  The click path deliberately keeps the strict rule: scripted hits on
  /a/<id> stay unbilled.
- Clicks use a short /a/<impression_id> URL (the long query-string form is
  unusable as printed text) and carry utm_source/medium/content through to
  the advertiser, since a shell sends no referrer.
- lib/ads/template.ts parses {{ads}} / {{ads:64}} / {{ads:terminal:64}} so
  a publisher's server can place the fill in its own template.
- Migration widens the format CHECK, adds terminal_ascii to slot inventory,
  and backfills a terminal creative for every existing campaign from the
  copy it already has (no LLM call, no advertiser action).

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 app/a/[id]/route.ts                           |  85 ++++++
 app/api/ads/motd/route.ts                     | 110 ++++++++
 components/ads/ad-preview.tsx                 |  32 ++-
 components/ads/slot-manager.tsx               |  46 +++-
 lib/ads/creative.ts                           |   8 +
 lib/ads/formats.ts                            |  21 ++
 lib/ads/house.ts                              |  19 +-
 lib/ads/serve.ts                              |  14 +-
 lib/ads/template.ts                           | 112 ++++++++
 lib/ads/terminal.ts                           | 254 ++++++++++++++++++
 .../20260730120000_ad_terminal_ascii.sql      |  74 +++++
 tests/contract/ads-template.test.ts           |  93 +++++++
 tests/contract/ads-terminal.test.ts           | 201 ++++++++++++++
 13 files changed, 1059 insertions(+), 10 deletions(-)
 create mode 100644 app/a/[id]/route.ts
 create mode 100644 app/api/ads/motd/route.ts
 create mode 100644 lib/ads/template.ts
 create mode 100644 lib/ads/terminal.ts
 create mode 100644 supabase/migrations/20260730120000_ad_terminal_ascii.sql
 create mode 100644 tests/contract/ads-template.test.ts
 create mode 100644 tests/contract/ads-terminal.test.ts

diff --git a/app/a/[id]/route.ts b/app/a/[id]/route.ts
new file mode 100644
index 00000000..0d6195e6
--- /dev/null
+++ b/app/a/[id]/route.ts
@@ -0,0 +1,85 @@
+// Short ad click redirector: https://crawlproof.com/a/<impression_id>
+//
+// Terminal ads print their click URL as literal text into someone's shell, so
+// the long /api/ads/click?i=…&s=…&c=…&cr=… form doesn't work — it wraps, it
+// looks like spam, and it's unusable when hand-typed. This path carries only
+// the impression id and re-reads slot/campaign/creative from the impression
+// row, then hands off to the same resolveClick() metering as the web path.
+//
+// Unknown/expired ids (including unmetered house-ad fills, which never get an
+// impression row) redirect to the site rather than dead-ending.
+
+import { NextRequest, NextResponse } from "next/server";
+import { resolveClick } from "@/lib/ads/serve";
+import { serviceClient } from "@/lib/supabase/service";
+import { clientIpFromHeaders, lookupGeo } from "@/lib/tracker/geo";
+import { parseDevice } from "@/lib/tracker/device";
+import { env } from "@/lib/env";
+
+export const runtime = "nodejs";
+export const dynamic = "force-dynamic";
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+export async function GET(request: NextRequest, ctx: { params: Promise<{ id: string }> }) {
+  const fallback = env.siteUrl || "https://crawlproof.com";
+  try {
+    const { id } = await ctx.params;
+    if (!UUID.test(id)) return NextResponse.redirect(fallback, { status: 302 });
+
+    const sb = serviceClient();
+    const { data: imp } = await sb
+      .from("ad_impressions")
+      .select("id, slot_id, campaign_id, creative_id, visitor_id")
+      .eq("id", id)
+      .maybeSingle();
+    if (!imp) return NextResponse.redirect(fallback, { status: 302 });
+
+    const ip = clientIpFromHeaders(request.headers);
+    const geo = await lookupGeo(ip).catch(() => null);
+    // Deliberately the STRICT classification here, unlike /api/ads/motd: a
+    // terminal ad is served to curl, but it's clicked from a browser when the
+    // reader follows the link. Anyone can curl this URL in a loop, so scripted
+    // hits stay unbilled (recorded with valid=false) rather than paying out.
+    const device = parseDevice(request.headers.get("user-agent")).deviceType;
+
+    const dest = await resolveClick({
+      impressionId: imp.id,
+      slotId: imp.slot_id,
+      campaignId: imp.campaign_id,
+      creativeId: imp.creative_id,
+      ctx: {
+        visitorId: imp.visitor_id,
+        ip,
+        country: geo?.countryCode ?? null,
+        device,
+      },
+    });
+
+    if (!dest) return NextResponse.redirect(fallback, { status: 302 });
+
+    // Terminal traffic is invisible in an advertiser's analytics without a tag
+    // — there's no referrer from a shell. resolveClick already appended
+    // ?ref=<campaign slug>; add utm on top, plus the publisher's own ?src=
+    // surface tag when the ad carried one. Never overwrite utm params the
+    // advertiser put on their own destination URL.
+    const q = new URL(request.url).searchParams;
+    const src = q.get("s") ?? q.get("src");
+    return NextResponse.redirect(withTerminalUtm(dest, src), { status: 302 });
+  } catch {
+    return NextResponse.redirect(fallback, { status: 302 });
+  }
+}
+
+function withTerminalUtm(dest: string, src: string | null): string {
+  try {
+    const u = new URL(dest);
+    if (!u.searchParams.has("utm_source")) u.searchParams.set("utm_source", "crawlproof");
+    if (!u.searchParams.has("utm_medium")) u.searchParams.set("utm_medium", "terminal");
+    const tag = (src ?? "").trim().replace(/[^\w.-]/g, "").slice(0, 32);
+    if (tag && !u.searchParams.has("utm_content")) u.searchParams.set("utm_content", tag);
+    return u.toString();
+  } catch {
+    return dest;
+  }
+}
diff --git a/app/api/ads/motd/route.ts b/app/api/ads/motd/route.ts
new file mode 100644
index 00000000..a55db6b8
--- /dev/null
+++ b/app/api/ads/motd/route.ts
@@ -0,0 +1,110 @@
+// Plain-text ad fill for terminals — the MOTD endpoint.
+//
+//   curl -s "https://crawlproof.com/api/ads/motd?slot=<slot_id>"
+//   curl -s "https://crawlproof.com/api/ads/motd?slot=<slot_id>&cols=64&color=1"
+//
+// Returns an ASCII box (text/plain), sized to `cols`, with optional ANSI
+// colour. Meant for shell MOTDs, SSH login banners, BBS screens, and CLI tools
+// — anywhere an <iframe> can't go. Impressions are metered server-side by
+// serveAd, exactly like the HTML paths; an unknown or inactive slot falls back
+// to the (unmetered) CrawlProof house ad so a login banner is never blank.
+
+import { NextRequest, NextResponse } from "next/server";
+import { serveAd } from "@/lib/ads/serve";
+import { houseFill } from "@/lib/ads/house";
+import { TERMINAL_FORMAT_ID } from "@/lib/ads/formats";
+import { clampCols, renderCreativeText, terminalDeviceType } from "@/lib/ads/terminal";
+import { clientIpFromHeaders, lookupGeo } from "@/lib/tracker/geo";
+import { parseDevice } from "@/lib/tracker/device";
+
+export const runtime = "nodejs";
+export const dynamic = "force-dynamic";
+
+function headers(request: Request): Record<string, string> {
+  const origin = request.headers.get("origin");
+  return {
+    "content-type": "text/plain; charset=utf-8",
+    // Every request is a fresh fill + impression, so never cache at the edge.
+    "cache-control": "no-store",
+    "access-control-allow-origin": origin ?? "*",
+    "access-control-allow-methods": "GET, OPTIONS",
+    vary: "Origin",
+    "x-robots-tag": "noindex",
+  };
+}
+
+export function OPTIONS(request: NextRequest) {
+  return new NextResponse(null, { status: 204, headers: headers(request) });
+}
+
+// color=1 / true / yes / ansi all opt into ANSI escapes. Default is plain text:
+// a consumer piping us into a file or a web page must not get escape codes.
+function wantsColor(v: string | null): boolean {
+  return v !== null && /^(1|true|yes|ansi|on)$/i.test(v);
+}
+
+// Optional publisher-supplied surface tag (?src=bbs, ?src=ssh-banner, …). It
+// rides along on the click URL so one slot can tell its surfaces apart in the
+// advertiser's own analytics. Sanitised hard: it ends up in a printed URL.
+function cleanSrc(v: string | null): string {
+  return (v ?? "").trim().replace(/[^\w.-]/g, "").slice(0, 32);
+}
+
+function withParam(rawUrl: string, key: string, value: string): string {
+  try {
+    const u = new URL(rawUrl);
+    u.searchParams.set(key, value);
+    return u.toString();
+  } catch {
+    return rawUrl;
+  }
+}
+
+export async function GET(request: NextRequest) {
+  const h = headers(request);
+  try {
+    const url = new URL(request.url);
+    const slotId = url.searchParams.get("slot");
+    const visitorId = url.searchParams.get("v");
+    const cols = clampCols(url.searchParams.get("cols") ?? url.searchParams.get("width"));
+    const color = wantsColor(url.searchParams.get("color"));
+    const src = cleanSrc(url.searchParams.get("src"));
+
+    let fill = null;
+    if (slotId) {
+      const ip = clientIpFromHeaders(request.headers);
+      const geo = await lookupGeo(ip).catch(() => null);
+      // Terminal clients identify as curl/wget/etc., which the generic tracker
+      // buckets as "bot" — correct for a web page, wrong here, where that's the
+      // actual audience. terminalDeviceType keeps real crawlers out and lets
+      // shell clients through; anything else falls back to normal parsing.
+      const ua = request.headers.get("user-agent");
+      const device = terminalDeviceType(ua) ?? parseDevice(ua).deviceType;
+      fill = await serveAd(slotId, TERMINAL_FORMAT_ID, {
+        visitorId,
+        ip,
+        country: geo?.countryCode ?? null,
+        device,
+      });
+    }
+    // No slot given, or the slot is inactive / has no terminal inventory.
+    if (!fill) fill = houseFill(TERMINAL_FORMAT_ID);
+
+    // Re-render at the caller's width/colour from the same creative + click URL
+    // the fill was metered with. House fills keep their own border label so an
+    // unsold slot doesn't read as a paid placement.
+    // Short key: the click URL is printed as literal text, so every character
+    // spent here is a character of box width.
+    const clickUrl = src ? withParam(fill.clickUrl, "s", src) : fill.clickUrl;
+    const body = renderCreativeText(fill.creative, clickUrl, {
+      cols,
+      color,
+      label: fill.campaignId === "house" ? "CRAWLPROOF ADS" : undefined,
+    });
+    return new NextResponse(`${body}\n`, { status: 200, headers: h });
+  } catch {
+    // Never fail a login banner: fall back to the house ad at defaults.
+    const fallback = houseFill(TERMINAL_FORMAT_ID);
+    return new NextResponse(`${fallback.text}\n`, { status: 200, headers: h });
+  }
+}
diff --git a/components/ads/ad-preview.tsx b/components/ads/ad-preview.tsx
index abf9db9c..3d90249c 100644
--- a/components/ads/ad-preview.tsx
+++ b/components/ads/ad-preview.tsx
@@ -2,13 +2,43 @@
 
 import type { CSSProperties } from "react";
 import type { AdCreative } from "@/lib/ads/formats";
-import { brandInitial, formatSpec, hexToRgba } from "@/lib/ads/formats";
+import { brandInitial, formatSpec, hexToRgba, TERMINAL_FORMAT_ID } from "@/lib/ads/formats";
+import { renderCreativeText } from "@/lib/ads/terminal";
+
+// Stand-in for the real /a/<impression_id> click URL, so the preview box is the
+// width the served ad will actually be.
+const PREVIEW_CLICK_URL = "https://crawlproof.com/a/00000000-0000-0000-0000-000000000000";
 
 // Live React mirror of renderCreativeHtml (lib/ads/creative.ts). Kept visually
 // in sync with the served HTML so the editor preview matches production.
 export function AdPreview({ creative, scale = 1 }: { creative: AdCreative; scale?: number }) {
   const { w, h } = formatSpec(creative.format);
 
+  // Terminal ad — render the exact ASCII the MOTD endpoint serves, monospaced.
+  if (creative.format === TERMINAL_FORMAT_ID) {
+    return (
+      <div style={{ width: w * scale, maxWidth: "100%", flex: "0 0 auto" }}>
+        <pre
+          style={{
+            margin: 0,
+            background: creative.bgColor,
+            color: creative.fgColor,
+            border: "1px solid rgba(255,255,255,.08)",
+            borderRadius: 8,
+            padding: "10px 12px",
+            fontFamily: "ui-monospace, SFMono-Regular, Menlo, Consolas, monospace",
+            fontSize: 11,
+            lineHeight: 1.35,
+            whiteSpace: "pre",
+            overflowX: "auto",
+          }}
+        >
+          {renderCreativeText(creative, PREVIEW_CLICK_URL)}
+        </pre>
+      </div>
+    );
+  }
+
   // Native text link — a borderless, full-width single line.
   if (creative.format === "text_link") {
     return (
diff --git a/components/ads/slot-manager.tsx b/components/ads/slot-manager.tsx
index 7ddaf38c..564114cd 100644
--- a/components/ads/slot-manager.tsx
+++ b/components/ads/slot-manager.tsx
@@ -3,14 +3,51 @@
 import { useState, useTransition } from "react";
 import { useRouter } from "next/navigation";
 import { createSlot, setSlotStatus, saveSlotPayout, requestPayout } from "@/app/actions/ads";
-import { PUBLISHER_FORMAT_IDS, formatSpec, type AdFormatId } from "@/lib/ads/formats";
+import {
+  PUBLISHER_FORMAT_IDS,
+  PUBLISHER_TEXT_FORMAT_IDS,
+  TERMINAL_COLS_LABEL,
+  TERMINAL_FORMAT_ID,
+  formatSpec,
+  type AdFormatId,
+} from "@/lib/ads/formats";
+
+// Every unit a publisher can install: HTML embeds first, then the fetch-based
+// text formats (terminal/MOTD).
+const INSTALLABLE_FORMAT_IDS: AdFormatId[] = [
+  ...PUBLISHER_FORMAT_IDS,
+  ...PUBLISHER_TEXT_FORMAT_IDS,
+];
 
 // The paste-once embed for a given size. data-format tells /ad.js which creative
 // to request; the medium rectangle stays the default the auto-installer uses.
+// The terminal format isn't embedded at all — it's curled, so it gets a shell
+// snippet instead of markup.
 function embedFor(slotId: string, format: AdFormatId, origin: string): string {
+  if (format === TERMINAL_FORMAT_ID) {
+    return [
+      "# Terminal ad — plain ASCII over HTTP. No JavaScript, no HTML, no iframe.",
+      "# Drop in ~/.zshrc, /etc/profile.d/, /etc/update-motd.d, or any CLI banner.",
+      `curl -fsS --max-time 3 "${origin}/api/ads/motd?slot=${slotId}&cols=72"`,
+      "",
+      "# Options: &color=1 for ANSI colour, &cols=44..120 for width,",
+      "# &src=<tag> to tell surfaces apart (rides through to the click URL).",
+      "",
+      "# Rendering a template server-side? Leave a token where the ad goes —",
+      "#   {{ads}}  {{ads:64}}  {{ads:terminal:64}}",
+      "# — and swap it for the fetched text before you send the response.",
+    ].join("\n");
+  }
   return `<div data-cp-ad data-slot="${slotId}" data-format="${format}"></div>\n<script src="${origin}/ad.js" async></script>`;
 }
 
+// Button caption: pixel sizes for banners, columns for the terminal box.
+function formatButtonLabel(id: AdFormatId): string {
+  const spec = formatSpec(id);
+  if (id === TERMINAL_FORMAT_ID) return `${spec.label} · ${TERMINAL_COLS_LABEL}`;
+  return `${spec.label} · ${spec.w}×${spec.h}`;
+}
+
 type Project = { id: string; name: string; url: string };
 type Slot = {
   id: string;
@@ -237,13 +274,12 @@ export function SlotManager({
           )}
           <div>
             <div className="text-xs uppercase tracking-wider text-[var(--color-muted)]">
-              Embed — pick a size, paste on your page
+              Embed — pick a unit, paste on your page (or in your shell)
             </div>
             {/* One button per available size. Clicking reveals that size's code;
                 clicking the open size again collapses it. */}
             <div className="mt-2 flex flex-wrap gap-2">
-              {PUBLISHER_FORMAT_IDS.map((id) => {
-                const spec = formatSpec(id);
+              {INSTALLABLE_FORMAT_IDS.map((id) => {
                 const open = id === fmt && showCode;
                 return (
                   <button
@@ -259,7 +295,7 @@ export function SlotManager({
                       }
                     }}
                   >
-                    {spec.label} · {spec.w}×{spec.h}
+                    {formatButtonLabel(id)}
                   </button>
                 );
               })}
diff --git a/lib/ads/creative.ts b/lib/ads/creative.ts
index e1a0b3ad..1270f43b 100644
--- a/lib/ads/creative.ts
+++ b/lib/ads/creative.ts
@@ -7,6 +7,7 @@ import { env } from "@/lib/env";
 import { generateStructuredOutput } from "@/lib/lx/backendAi";
 import { extractSiteBrand, type SiteBrand } from "./brand";
 import { resolveAdHeroImage } from "./heroImage";
+import { renderCreativeText, renderTerminalHtml } from "./terminal";
 import {
   AD_FORMATS,
   AD_FORMAT_IDS,
@@ -20,6 +21,7 @@ import {
 // Re-export the client-safe format primitives so existing server importers of
 // this module keep working; client components should import from ./formats.
 export { AD_FORMATS, AD_FORMAT_IDS, formatSpec };
+export { renderCreativeText, renderTerminalHtml };
 export type { AdCreative, AdFormatId };
 
 // Copy is generated once per URL by a frontier-ish model; sizes are rendered
@@ -186,6 +188,12 @@ function markHtml(creative: AdCreative, size: number): string {
 export function renderCreativeHtml(creative: AdCreative, clickUrl: string): string {
   const { w, h } = formatSpec(creative.format);
 
+  // Terminal ad — the ASCII artwork in a <pre>, so the same creative can also
+  // fill a web slot. The canonical delivery is /api/ads/motd (text/plain).
+  if (creative.format === "terminal_ascii") {
+    return renderTerminalHtml(creative, clickUrl);
+  }
+
   // Native text link — a borderless, full-width single line. No image/box.
   if (creative.format === "text_link") {
     const body = creative.body
diff --git a/lib/ads/formats.ts b/lib/ads/formats.ts
index 16f92491..51f306a6 100644
--- a/lib/ads/formats.ts
+++ b/lib/ads/formats.ts
@@ -10,6 +10,11 @@ export const AD_FORMATS = [
   // Native, borderless single-line text ad. Renders full-width (the w/h below
   // is the nominal iframe box; the unit itself fills its container).
   { id: "text_link", label: "Text Link", w: 600, h: 40 },
+  // ASCII box for terminals — SSH banners, shell MOTDs, BBS screens, CLI tools.
+  // There is no pixel box: w/h below is only the nominal size used by the web
+  // preview when the same creative is rendered in a <pre>. The real dimension
+  // is TERMINAL_COLS (see ./terminal).
+  { id: "terminal_ascii", label: "Terminal (ASCII)", w: 600, h: 148 },
 ] as const;
 
 export type AdFormatId = (typeof AD_FORMATS)[number]["id"];
@@ -19,6 +24,10 @@ export const AD_FORMAT_IDS = AD_FORMATS.map((f) => f.id) as AdFormatId[];
 // embed for and install. A subset of AD_FORMATS that grows as each size is
 // surfaced (one PR per size). Keep the medium rectangle first: it's the safe
 // default the auto-installer falls back to.
+//
+// WEB ONLY: these are the formats rendered as an <iframe> by /ad.js and dropped
+// into HTML by the GitHub auto-installer. Text/terminal formats must not be in
+// this list — they're fetched, not embedded.
 export const PUBLISHER_FORMAT_IDS: AdFormatId[] = [
   "banner_300x250",
   "banner_728x90",
@@ -26,6 +35,18 @@ export const PUBLISHER_FORMAT_IDS: AdFormatId[] = [
   "text_link",
 ];
 
+// The terminal format id, kept as a named constant since several call sites
+// (serving, the MOTD endpoint, the publisher snippet) branch on it.
+export const TERMINAL_FORMAT_ID = "terminal_ascii" as const;
+
+// Caption for the terminal unit's real dimension — it has columns, not pixels.
+export const TERMINAL_COLS_LABEL = "76 cols";
+
+// Formats a publisher consumes over plain HTTP as text rather than embedding —
+// `curl https://crawlproof.com/api/ads/motd?slot=<id>` in a login banner, MOTD,
+// or CLI. Shown as their own group on the Monetize page.
+export const PUBLISHER_TEXT_FORMAT_IDS: AdFormatId[] = [TERMINAL_FORMAT_ID];
+
 export function formatSpec(id: AdFormatId) {
   return AD_FORMATS.find((f) => f.id === id) ?? AD_FORMATS[0];
 }
diff --git a/lib/ads/house.ts b/lib/ads/house.ts
index 9a70b754..b652553c 100644
--- a/lib/ads/house.ts
+++ b/lib/ads/house.ts
@@ -1,6 +1,8 @@
 import crypto from "node:crypto";
 import { env } from "@/lib/env";
 import { formatSpec, type AdCreative, type AdFormatId } from "./creative";
+import { TERMINAL_FORMAT_ID } from "./formats";
+import { renderCreativeText, renderTerminalHtml } from "./terminal";
 import type { Fill } from "./serve";
 
 // Default "house" ad for the CrawlProof Ad Network. Shown when a slot has no
@@ -30,6 +32,12 @@ function esc(s: string): string {
 export function renderHouseAdHtml(format: AdFormatId, clickUrl: string): string {
   const { w, h } = formatSpec(format);
 
+  // Terminal ad — same ASCII artwork the /api/ads/motd endpoint serves, in a
+  // <pre> for the web/iframe paths.
+  if (format === TERMINAL_FORMAT_ID) {
+    return renderTerminalHtml(houseCreative(format), clickUrl);
+  }
+
   // Native text link — no artwork, single full-width line.
   if (format === "text_link") {
     return `<!doctype html><html><head><meta charset="utf-8"><style>
@@ -106,14 +114,21 @@ function houseCreative(format: AdFormatId): AdCreative {
 
 /** A default house-ad fill promoting the CrawlProof Ad Network. Not metered. */
 export function houseFill(format: AdFormatId): Fill {
-  const clickUrl = `${env.siteUrl}/?utm_source=house-ad&utm_medium=ad&utm_campaign=crawlproof-ads`;
+  // Terminals print the raw URL, so the terminal house ad uses a short one that
+  // fits the ASCII box instead of the full utm_campaign query.
+  const clickUrl =
+    format === TERMINAL_FORMAT_ID
+      ? `${env.siteUrl}/?utm_source=house-ad&utm_medium=motd`
+      : `${env.siteUrl}/?utm_source=house-ad&utm_medium=ad&utm_campaign=crawlproof-ads`;
+  const creative = houseCreative(format);
   return {
     impressionId: crypto.randomUUID(),
     campaignId: "house",
     creativeId: "house",
     refSlug: "house",
-    creative: houseCreative(format),
+    creative,
     clickUrl,
     html: renderHouseAdHtml(format, clickUrl),
+    text: renderCreativeText(creative, clickUrl, { label: "CRAWLPROOF ADS" }),
   };
 }
diff --git a/lib/ads/serve.ts b/lib/ads/serve.ts
index 32289b16..17bc5109 100644
--- a/lib/ads/serve.ts
+++ b/lib/ads/serve.ts
@@ -5,9 +5,11 @@ import {
   AD_FORMAT_IDS,
   appendRef,
   renderCreativeHtml,
+  renderCreativeText,
   type AdCreative,
   type AdFormatId,
 } from "./creative";
+import { TERMINAL_FORMAT_ID } from "./formats";
 import { houseFill, HOUSE_AD_ROTATION_RATE } from "./house";
 import { CREDIT_CENTS, DEFAULT_BID_CREDITS, PLATFORM_RATE } from "./pricing";
 import { assessClickValidity, isBotDevice } from "./fraud";
@@ -27,6 +29,8 @@ export type Fill = {
   creative: AdCreative;
   clickUrl: string;
   html: string;
+  /** ASCII rendering of the same creative, for terminal/MOTD consumers. */
+  text: string;
 };
 
 export function isAdFormat(v: string | null | undefined): v is AdFormatId {
@@ -175,8 +179,13 @@ export async function serveAd(
   const creative = rowToCreative(pick);
 
   // Click goes through our redirector so we can meter it, then lands on the
-  // destination with ?ref= applied.
-  const clickUrl = `${env.siteUrl}/api/ads/click?i=${impressionId}&s=${slotId}&c=${campaign.id}&cr=${pick.id}`;
+  // destination with ?ref= applied. Terminals print the URL as literal text, so
+  // the terminal format gets the short /a/<impression> form — it resolves the
+  // slot/campaign/creative from the impression row instead of the query string.
+  const clickUrl =
+    format === TERMINAL_FORMAT_ID
+      ? `${env.siteUrl}/a/${impressionId}`
+      : `${env.siteUrl}/api/ads/click?i=${impressionId}&s=${slotId}&c=${campaign.id}&cr=${pick.id}`;
 
   return {
     impressionId,
@@ -186,6 +195,7 @@ export async function serveAd(
     creative,
     clickUrl,
     html: renderCreativeHtml(creative, clickUrl),
+    text: renderCreativeText(creative, clickUrl),
   };
 }
 
diff --git a/lib/ads/template.ts b/lib/ads/template.ts
new file mode 100644
index 00000000..37729809
--- /dev/null
+++ b/lib/ads/template.ts
@@ -0,0 +1,112 @@
+// Server-side ad template tokens.
+//
+// A text/HTML template marks where ads go with a token, and the server swaps in
+// a fill before sending the response. This is the only workable model for
+// terminal surfaces (MOTDs, SSH banners, BBS screens) — there's no /ad.js to
+// run and no <iframe> to place, so the publisher's own server does the
+// substitution:
+//
+//   {{ads}}                  one terminal ad at the default width
+//   {{ads:64}}               terminal ad, 64 columns
+//   {{ads:terminal}}         explicit format
+//   {{ads:terminal:64}}      explicit format + width
+//   {{ads:text_link}}        a different format (HTML surfaces)
+//   {{ad}}                   singular alias for any of the above
+//
+// Unknown formats resolve to the terminal box rather than leaving a raw token
+// in someone's login banner. Pure module — no I/O — so the caller decides how
+// a token is filled (HTTP fetch, direct serveAd call, cache).
+
+import { AD_FORMAT_IDS, TERMINAL_FORMAT_ID, type AdFormatId } from "./formats";
+import { TERMINAL_COLS, clampCols } from "./terminal";
+
+/** Matches {{ads}} / {{ad}} with optional :args, tolerant of inner spaces. */
+const TOKEN_RE = /\{\{\s*ads?\s*(?::\s*([^}]*?)\s*)?\}\}/gi;
+
+export type AdToken = {
+  /** The exact token text, for a literal replace. */
+  raw: string;
+  format: AdFormatId;
+  /** Only meaningful for the terminal format. */
+  cols: number;
+};
+
+// Friendly aliases so a publisher doesn't have to remember the db format ids.
+const FORMAT_ALIASES: Record<string, AdFormatId> = {
+  terminal: TERMINAL_FORMAT_ID,
+  ascii: TERMINAL_FORMAT_ID,
+  motd: TERMINAL_FORMAT_ID,
+  text: "text_link",
+  textlink: "text_link",
+  link: "text_link",
+  rect: "banner_300x250",
+  rectangle: "banner_300x250",
+  leaderboard: "banner_728x90",
+  mobile: "banner_320x50",
+};
+
+function resolveFormat(arg: string): AdFormatId | null {
+  const key = arg.toLowerCase().replace(/[\s-]+/g, "_");
+  if ((AD_FORMAT_IDS as string[]).includes(key)) return key as AdFormatId;
+  return FORMAT_ALIASES[key.replace(/_/g, "")] ?? FORMAT_ALIASES[key] ?? null;
+}
+
+function parseArgs(args: string | undefined): { format: AdFormatId; cols: number } {
+  let format: AdFormatId = TERMINAL_FORMAT_ID;
+  let cols = TERMINAL_COLS;
+  for (const part of (args ?? "").split(":")) {
+    const arg = part.trim();
+    if (!arg) continue;
+    // A bare number is a column count; anything else names a format.
+    if (/^\d+$/.test(arg)) {
+      cols = clampCols(arg);
+      continue;
+    }
+    format = resolveFormat(arg) ?? format;
+  }
+  return { format, cols };
+}
+
+/** Every ad token in a template, in document order (duplicates included). */
+export function parseAdTokens(template: string): AdToken[] {
+  const out: AdToken[] = [];
+  for (const m of String(template ?? "").matchAll(TOKEN_RE)) {
+    out.push({ raw: m[0], ...parseArgs(m[1]) });
+  }
+  return out;
+}
+
+export function hasAdToken(template: string): boolean {
+  // matchAll avoids the lastIndex footgun of reusing a /g regex with .test().
+  return parseAdTokens(template).length > 0;
+}
+
+/**
+ * Replace every ad token with the fill returned by `fill(token)`.
+ *
+ * Tokens are filled concurrently and identical tokens are only filled once, so
+ * a template with three `{{ads}}` renders the same ad three times rather than
+ * metering three impressions. A fill that throws or returns null removes the
+ * token — a template must never leak `{{ads}}` into the output.
+ */
+export async function renderAdTemplate(
+  template: string,
+  fill: (token: AdToken) => Promise<string | null>,
+): Promise<string> {
+  const text = String(template ?? "");
+  const tokens = parseAdTokens(text);
+  if (tokens.length === 0) return text;
+
+  const byRaw = new Map<string, AdToken>();
+  for (const t of tokens) if (!byRaw.has(t.raw)) byRaw.set(t.raw, t);
+
+  const filled = new Map<string, string>();
+  await Promise.all(
+    [...byRaw.values()].map(async (token) => {
+      const value = await fill(token).catch(() => null);
+      filled.set(token.raw, value ?? "");
+    }),
+  );
+
+  return text.replace(TOKEN_RE, (raw) => filled.get(raw) ?? "");
+}
diff --git a/lib/ads/terminal.ts b/lib/ads/terminal.ts
new file mode 100644
index 00000000..a9d4db8d
--- /dev/null
+++ b/lib/ads/terminal.ts
@@ -0,0 +1,254 @@
+// ASCII "terminal" ad renderer - the text twin of renderCreativeHtml.
+//
+// Consumers are TTYs, not browsers: SSH login banners, shell MOTDs, BBS
+// screens, CLI tools. So the output is a fixed-width, pure-ASCII box that
+// survives `curl | cat` anywhere, with ANSI colour as an explicit opt-in.
+//
+// Pure and client-safe (no server-only imports) so the editor preview can
+// render exactly what the endpoint serves - same rule as ./formats.
+
+import type { AdCreative } from "./formats";
+
+/** Default box width in columns - fits an 80-col terminal with margin, and
+ * leaves room for a click URL carrying a surface tag on one line. */
+export const TERMINAL_COLS = 76;
+const MIN_COLS = 44;
+const MAX_COLS = 120;
+
+/** Disclosure label burned into the top border. */
+const SPONSORED_LABEL = "SPONSORED";
+/** Attribution burned into the bottom border - the terminal "Advertisement" caption. */
+const ATTRIBUTION = "ads by crawlproof.com";
+
+export type TerminalRenderOpts = {
+  /** Box width in columns (clamped to 44...120). */
+  cols?: number;
+  /** Emit ANSI truecolour escapes. Off by default: plain text is the safe wire format. */
+  color?: boolean;
+  /** Override the top-border label (the house ad uses its own). */
+  label?: string;
+};
+
+export function clampCols(v: unknown): number {
+  const n = typeof v === "string" ? parseInt(v, 10) : typeof v === "number" ? v : NaN;
+  if (!Number.isFinite(n)) return TERMINAL_COLS;
+  return Math.min(MAX_COLS, Math.max(MIN_COLS, Math.round(n)));
+}
+
+// Common non-ASCII punctuation that shows up in ad copy, folded to the ASCII
+// equivalent so we degrade to something readable rather than dropping chars.
+const FOLD: Array<[RegExp, string]> = [
+  [/[‘’‚′]/g, "'"],
+  [/[“”„″]/g, '"'],
+  [/[–—―]/g, "-"],
+  [/…/g, "..."],
+  [/[→➡➜]/g, "->"],
+  [/[•·]/g, "*"],
+  [/[\u00a0\u2007\u2009\u202f]/g, " "],
+  [/™/g, "(tm)"],
+  [/®/g, "(r)"],
+  [/€/g, "EUR"],
+  [/£/g, "GBP"],
+];
+
+/**
+ * Make advertiser copy safe to print into a TTY.
+ *
+ * Ad copy is untrusted, third-party text and we write it straight to someone's
+ * terminal, so every escape/control character is removed - an ESC sequence in a
+ * headline could otherwise repaint the screen, ring the bell, or spoof the rest
+ * of the MOTD. Stripping to printable ASCII also keeps the box aligned: the
+ * layout maths below assumes exactly one column per character, which is false
+ * for CJK and emoji.
+ */
+export function sanitizeTerminalText(input: string | null | undefined): string {
+  let s = String(input ?? "");
+  for (const [re, to] of FOLD) s = s.replace(re, to);
+  // Decompose accents and drop the combining marks, so "Café" degrades to
+  // "Cafe" rather than "Caf" once the non-ASCII pass runs.
+  s = s.normalize("NFKD").replace(/[\u0300-\u036f]/g, "");
+  return s
+    // Control chars (incl. ESC 0x1b, BEL, CR/LF) and the C1 range -> space.
+    .replace(/[\x00-\x1f\x7f-\x9f]/g, " ")
+    // Anything else outside printable ASCII -> dropped.
+    .replace(/[^\x20-\x7e]/g, "")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+/** Greedy word wrap to `width` columns; overlong words are hard-split. */
+export function wrapText(text: string, width: number): string[] {
+  const words = text.split(" ").filter(Boolean);
+  const lines: string[] = [];
+  let line = "";
+  for (const word of words) {
+    if (word.length > width) {
+      if (line) {
+        lines.push(line);
+        line = "";
+      }
+      for (let i = 0; i < word.length; i += width) lines.push(word.slice(i, i + width));
+      continue;
+    }
+    if (!line) line = word;
+    else if (line.length + 1 + word.length <= width) line += ` ${word}`;
+    else {
+      lines.push(line);
+      line = word;
+    }
+  }
+  if (line) lines.push(line);
+  return lines;
+}
+
+// --- Client classification -------------------------------------------------
+
+// Crawlers we still want to keep off paid inventory, even on a text endpoint.
+const CRAWLER_RE = /bot\b|crawler|spider|scraper|headless|preview|monitor|slurp|archive/i;
+// The legitimate audience for a terminal ad: shell fetchers and CLIs. The
+// generic tracker (lib/tracker/device) buckets all of these as "bot", which is
+// right for a web page and exactly wrong here — on /api/ads/motd, curl IS the
+// human. Misclassifying them means a terminal slot can only ever serve house
+// ads and never earns.
+const CLI_RE = /curl|wget|httpie|libwww|lwp|python-requests|go-http|node-fetch|powershell|http-client|axios|fetch|motd|ssh/i;
+
+/**
+ * Device bucket for a terminal ad request. Returns "bot" for real crawlers,
+ * "terminal" for shell clients (and for a missing UA, which curl-ish tooling
+ * often omits), otherwise falls through to the caller's own classification by
+ * returning null.
+ */
+export function terminalDeviceType(userAgent: string | null | undefined): string | null {
+  const ua = (userAgent ?? "").trim();
+  if (!ua) return "terminal";
+  if (CRAWLER_RE.test(ua)) return "bot";
+  if (CLI_RE.test(ua)) return "terminal";
+  return null;
+}
+
+// --- ANSI ------------------------------------------------------------------
+
+const ESC = "\x1b";
+const RESET = `${ESC}[0m`;
+const BOLD = `${ESC}[1m`;
+const DIM = `${ESC}[2m`;
+
+function fg(hex: string): string {
+  const m = /^#?([0-9a-f]{6})$/i.exec((hex ?? "").trim());
+  if (!m) return "";
+  const n = parseInt(m[1], 16);
+  return `${ESC}[38;2;${(n >> 16) & 255};${(n >> 8) & 255};${n & 255}m`;
+}
+
+// --- Layout ----------------------------------------------------------------
+
+// "+-- LABEL ---------+" / "+--------- LABEL --+". Label is optional; the
+// border is always exactly `cols` characters wide.
+function border(cols: number, label: string | null, align: "left" | "right"): string {
+  const inner = cols - 2; // between the two '+'
+  if (!label) return `+${"-".repeat(inner)}+`;
+  const tag = ` ${label} `;
+  const dashes = Math.max(0, inner - tag.length - 2);
+  return align === "left"
+    ? `+--${tag}${"-".repeat(dashes)}+`
+    : `+${"-".repeat(dashes)}${tag}--+`;
+}
+
+/**
+ * Render a creative as a self-contained ASCII block.
+ *
+ * `clickUrl` is printed verbatim so it stays copy-pasteable - if it can't fit
+ * inside the box it gets its own line below the frame rather than being
+ * truncated into a dead link.
+ */
+export function renderCreativeText(
+  creative: AdCreative,
+  clickUrl: string,
+  opts: TerminalRenderOpts = {},
+): string {
+  const cols = clampCols(opts.cols);
+  const color = opts.color === true;
+  const inner = cols - 4; // "| " + " |"
+
+  const headline = sanitizeTerminalText(creative.headline) || "Sponsored";
+  const body = sanitizeTerminalText(creative.body);
+  // Copy often already ends in an arrow ("Advertise ->"); we add our own, so
+  // strip a trailing one rather than printing "Advertise ->:".
+  const cta =
+    sanitizeTerminalText(creative.ctaText).replace(/\s*(->|>|:)\s*$/, "").trim() || "Learn more";
+  // The click URL is ours (never advertiser-authored), but sanitize anyway so a
+  // malformed destination can't smuggle an escape sequence through.
+  const url = sanitizeTerminalText(clickUrl).replace(/\s/g, "");
+
+  const accent = color ? fg(creative.accentColor) : "";
+  const body_ = color ? fg(creative.fgColor) : "";
+  const off = color ? RESET : "";
+
+  const rows: string[] = [];
+  const pipe = color ? `${accent}|${off}` : "|";
+  const row = (content: string, visibleLen: number) =>
+    rows.push(`${pipe} ${content}${" ".repeat(Math.max(0, inner - visibleLen))} ${pipe}`);
+  const blank = () => row("", 0);
+
+  blank();
+  for (const l of wrapText(headline, inner)) {
+    row(color ? `${BOLD}${body_}${l}${off}` : l, l.length);
+  }
+  if (body) {
+    for (const l of wrapText(body, inner)) {
+      row(color ? `${body_}${l}${off}` : l, l.length);
+    }
+  }
+  blank();
+
+  // "Try it free -> https://..." on one line when it fits, else CTA then URL.
+  const oneLine = `${cta} -> ${url}`;
+  const overflow: string[] = [];
+  if (oneLine.length <= inner) {
+    row(color ? `${accent}${cta} ->${off} ${body_}${url}${off}` : oneLine, oneLine.length);
+  } else if (url.length <= inner) {
+    row(color ? `${accent}${cta}:${off}` : `${cta}:`, cta.length + 1);
+    row(color ? `${body_}${url}${off}` : url, url.length);
+  } else {
+    // Pathologically long URL: keep it whole, outside the frame.
+    row(color ? `${accent}${cta}:${off}` : `${cta}:`, cta.length + 1);
+    overflow.push(color ? `${body_}${url}${off}` : url);
+  }
+  blank();
+
+  const top = border(cols, opts.label ?? SPONSORED_LABEL, "left");
+  const bottom = border(cols, ATTRIBUTION, "right");
+  return [
+    color ? `${accent}${top}${off}` : top,
+    ...rows,
+    color ? `${DIM}${accent}${bottom}${off}` : bottom,
+    ...overflow,
+  ].join("\n");
+}
+
+function esc(s: string): string {
+  return s
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}
+
+/**
+ * Browser rendering of the terminal format: the exact same ASCII, in a
+ * monospace <pre>. Lets the terminal creative still fill a normal web slot
+ * (and the /api/ads/frame iframe) without needing a separate design.
+ */
+export function renderTerminalHtml(creative: AdCreative, clickUrl: string): string {
+  const artwork = renderCreativeText(creative, clickUrl, { color: false });
+  return `<!doctype html><html><head><meta charset="utf-8"><style>
+    *{box-sizing:border-box;margin:0}
+    a{text-decoration:none;display:block}
+    .cp-ad{background:${creative.bgColor};color:${creative.fgColor};border-radius:8px;
+      border:1px solid rgba(255,255,255,.08);padding:10px 12px;overflow:auto}
+    pre{margin:0;font:12px/1.35 ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;
+      white-space:pre;color:${creative.fgColor}}
+  </style></head><body>
+    <a class="cp-ad" href="${esc(clickUrl)}" target="_blank" rel="noopener sponsored"><pre>${esc(artwork)}</pre></a>
+  </body></html>`;
+}
diff --git a/supabase/migrations/20260730120000_ad_terminal_ascii.sql b/supabase/migrations/20260730120000_ad_terminal_ascii.sql
new file mode 100644
index 00000000..a07b131f
--- /dev/null
+++ b/supabase/migrations/20260730120000_ad_terminal_ascii.sql
@@ -0,0 +1,74 @@
+-- Terminal (ASCII) ad format.
+--
+-- Adds `terminal_ascii` — a fixed-width ASCII box served as text/plain from
+-- /api/ads/motd for shell MOTDs, SSH login banners, BBS screens, and CLI tools.
+-- Three parts, mirroring how text_link was introduced:
+--   1. widen the creative format CHECK,
+--   2. add the format to slot inventory (default + backfill) so serveAd() will
+--      actually fill it,
+--   3. backfill a terminal creative for every existing campaign, derived from
+--      the copy it already has — no LLM call, no advertiser action needed.
+--
+-- NOTE: prod migration history diverged — apply this single file via psql over
+-- the pooler, do NOT `supabase db push`.
+
+alter table public.ad_creatives drop constraint if exists ad_creatives_format_check;
+alter table public.ad_creatives
+  add constraint ad_creatives_format_check
+  check (format in ('banner_300x250', 'banner_728x90', 'banner_320x50', 'text_link', 'terminal_ascii'));
+
+alter table public.ad_slots
+  alter column formats
+  set default array['banner_300x250', 'banner_728x90', 'banner_320x50', 'text_link', 'terminal_ascii'];
+
+update public.ad_slots
+  set formats = array_append(formats, 'terminal_ascii')
+  where not ('terminal_ascii' = any (formats));
+
+-- Backfill: one terminal creative per campaign that doesn't have one yet.
+--
+-- Copy is cloned from the campaign's best existing creative — text_link and the
+-- medium rectangle carry the full headline, while banner_320x50 holds the
+-- shortened mobile variant, so they're preferred in that order. image_url is
+-- dropped (a terminal has no artwork); colours are kept because they drive the
+-- optional ANSI palette. The source creative's status is carried over so a
+-- rejected campaign doesn't gain a servable creative.
+insert into public.ad_creatives (
+  campaign_id, owner_id, format, headline, body, cta_text,
+  image_url, logo_url, bg_color, fg_color, accent_color, font_family,
+  ai_provenance, status
+)
+select distinct on (c.campaign_id)
+  c.campaign_id,
+  c.owner_id,
+  'terminal_ascii',
+  c.headline,
+  c.body,
+  c.cta_text,
+  null,
+  c.logo_url,
+  c.bg_color,
+  c.fg_color,
+  c.accent_color,
+  c.font_family,
+  jsonb_build_object(
+    'source', 'backfill_terminal_ascii',
+    'from_creative', c.id,
+    'from_format', c.format
+  ),
+  c.status
+from public.ad_creatives c
+where c.format <> 'terminal_ascii'
+  and not exists (
+    select 1 from public.ad_creatives t
+    where t.campaign_id = c.campaign_id and t.format = 'terminal_ascii'
+  )
+order by
+  c.campaign_id,
+  case c.format
+    when 'text_link' then 0
+    when 'banner_300x250' then 1
+    when 'banner_728x90' then 2
+    else 3
+  end,
+  c.created_at;
diff --git a/tests/contract/ads-template.test.ts b/tests/contract/ads-template.test.ts
new file mode 100644
index 00000000..7af6cbcd
--- /dev/null
+++ b/tests/contract/ads-template.test.ts
@@ -0,0 +1,93 @@
+import { describe, expect, it, vi } from "vitest";
+import { hasAdToken, parseAdTokens, renderAdTemplate } from "@/lib/ads/template";
+import { TERMINAL_COLS } from "@/lib/ads/terminal";
+
+// {{ads}} is the substitution point for surfaces that can't run /ad.js — the
+// publisher's server swaps it for a fill before responding.
+
+describe("parseAdTokens", () => {
+  it("defaults to a terminal ad at the default width", () => {
+    expect(parseAdTokens("hello\n{{ads}}\nbye")).toEqual([
+      { raw: "{{ads}}", format: "terminal_ascii", cols: TERMINAL_COLS },
+    ]);
+  });
+
+  it("accepts the singular alias and inner whitespace", () => {
+    expect(parseAdTokens("{{ ad }}")[0].raw).toBe("{{ ad }}");
+    expect(parseAdTokens("{{ ad }}")[0].format).toBe("terminal_ascii");
+  });
+
+  it("reads a bare number as a column count", () => {
+    expect(parseAdTokens("{{ads:64}}")[0]).toMatchObject({ format: "terminal_ascii", cols: 64 });
+  });
+
+  it("clamps out-of-range widths", () => {
+    expect(parseAdTokens("{{ads:5}}")[0].cols).toBe(44);
+    expect(parseAdTokens("{{ads:9999}}")[0].cols).toBe(120);
+  });
+
+  it("reads a format name, by id or friendly alias", () => {
+    expect(parseAdTokens("{{ads:terminal}}")[0].format).toBe("terminal_ascii");
+    expect(parseAdTokens("{{ads:terminal_ascii}}")[0].format).toBe("terminal_ascii");
+    expect(parseAdTokens("{{ads:text_link}}")[0].format).toBe("text_link");
+    expect(parseAdTokens("{{ads:leaderboard}}")[0].format).toBe("banner_728x90");
+  });
+
+  it("reads format and width together", () => {
+    expect(parseAdTokens("{{ads:terminal:100}}")[0]).toMatchObject({
+      format: "terminal_ascii",
+      cols: 100,
+    });
+  });
+
+  it("falls back to the terminal format for unknown names", () => {
+    expect(parseAdTokens("{{ads:hologram}}")[0].format).toBe("terminal_ascii");
+  });
+
+  it("finds every token, in order", () => {
+    const tokens = parseAdTokens("{{ads}}\n---\n{{ads:48}}\n---\n{{ads}}");
+    expect(tokens.map((t) => t.cols)).toEqual([TERMINAL_COLS, 48, TERMINAL_COLS]);
+  });
+
+  it("ignores text that isn't a token", () => {
+    expect(parseAdTokens("no ads here, {{ adsense }}, {ads}")).toEqual([]);
+    expect(hasAdToken("plain text")).toBe(false);
+    expect(hasAdToken("x {{ads}} y")).toBe(true);
+  });
+});
+
+describe("renderAdTemplate", () => {
+  it("returns the template untouched when there is no token", async () => {
+    const fill = vi.fn();
+    expect(await renderAdTemplate("nothing here", fill)).toBe("nothing here");
+    expect(fill).not.toHaveBeenCalled();
+  });
+
+  it("substitutes the fill in place", async () => {
+    const out = await renderAdTemplate("top\n{{ads}}\nbottom", async () => "[AD]");
+    expect(out).toBe("top\n[AD]\nbottom");
+  });
+
+  it("fills each distinct token once, reusing it for repeats", async () => {
+    const fill = vi.fn(async (t) => `[${t.cols}]`);
+    const out = await renderAdTemplate("{{ads}} {{ads}} {{ads:48}}", fill);
+    expect(out).toBe(`[${TERMINAL_COLS}] [${TERMINAL_COLS}] [48]`);
+    expect(fill).toHaveBeenCalledTimes(2);
+  });
+
+  it("drops the token when the fill fails — never leaks {{ads}} to the reader", async () => {
+    const out = await renderAdTemplate("a{{ads}}b", async () => {
+      throw new Error("ad server down");
+    });
+    expect(out).toBe("ab");
+    expect(await renderAdTemplate("a{{ads}}b", async () => null)).toBe("ab");
+  });
+
+  it("is safe to call repeatedly (no regex lastIndex leakage)", async () => {
+    const t = "x {{ads}} y";
+    expect(await renderAdTemplate(t, async () => "AD")).toBe("x AD y");
+    expect(await renderAdTemplate(t, async () => "AD")).toBe("x AD y");
+    expect(hasAdToken(t)).toBe(true);
+    expect(hasAdToken(t)).toBe(true);
+  });
+});
diff --git a/tests/contract/ads-terminal.test.ts b/tests/contract/ads-terminal.test.ts
new file mode 100644
index 00000000..7f4ae7c6
--- /dev/null
+++ b/tests/contract/ads-terminal.test.ts
@@ -0,0 +1,201 @@
+import { describe, expect, it } from "vitest";
+import type { AdCreative } from "@/lib/ads/formats";
+import {
+  TERMINAL_COLS,
+  clampCols,
+  renderCreativeText,
+  renderTerminalHtml,
+  sanitizeTerminalText,
+  terminalDeviceType,
+  wrapText,
+} from "@/lib/ads/terminal";
+
+// The terminal creative is printed straight into someone's shell, so the two
+// things that must never break are (a) the box stays a rectangle at any width
+// and (b) advertiser copy can't emit escape sequences.
+
+const CLICK = "https://crawlproof.com/a/2b1f0c94-8a1e-4c3d-9b77-1f0a2c3d4e5f";
+
+function creative(over: Partial<AdCreative> = {}): AdCreative {
+  return {
+    format: "terminal_ascii",
+    headline: "Ship faster with CrawlProof",
+    body: "AI-readable audits for your site, in one command.",
+    ctaText: "Try it free",
+    bgColor: "#0b0d10",
+    fgColor: "#e7e9ee",
+    accentColor: "#6ee7b7",
+    fontFamily: "system-ui",
+    logoUrl: null,
+    imageUrl: null,
+    ...over,
+  };
+}
+
+const ESC = String.fromCharCode(27);
+
+describe("sanitizeTerminalText", () => {
+  it("strips ANSI escape sequences from advertiser copy", () => {
+    const out = sanitizeTerminalText(`${ESC}[2J${ESC}[HWiped your screen`);
+    expect(out).not.toContain(ESC);
+    expect(out).toContain("Wiped your screen");
+  });
+
+  it("strips control characters, including newlines that would fake a box row", () => {
+    const out = sanitizeTerminalText("Real ad\n| root@host: rm -rf / |\r\x07");
+    expect(out.split("\n")).toHaveLength(1);
+    expect(out).not.toMatch(/[\x00-\x1f\x7f]/);
+  });
+
+  it("folds smart punctuation and accents to ASCII instead of dropping them", () => {
+    expect(sanitizeTerminalText("Café — “oui” … 5€")).toBe('Cafe - "oui" ... 5EUR');
+  });
+
+  it("drops characters that would break column maths (CJK, emoji)", () => {
+    expect(sanitizeTerminalText("wide 世界 ok 🚀")).toBe("wide ok");
+  });
+
+  it("collapses whitespace and handles null/undefined", () => {
+    expect(sanitizeTerminalText("  a   b  ")).toBe("a b");
+    expect(sanitizeTerminalText(null)).toBe("");
+    expect(sanitizeTerminalText(undefined)).toBe("");
+  });
+});
+
+describe("wrapText", () => {
+  it("wraps on word boundaries within the width", () => {
+    expect(wrapText("one two three four", 9)).toEqual(["one two", "three", "four"]);
+  });
+
+  it("hard-splits a word longer than the width", () => {
+    expect(wrapText("abcdefghij", 4)).toEqual(["abcd", "efgh", "ij"]);
+  });
+});
+
+describe("clampCols", () => {
+  it("defaults when unparseable", () => {
+    expect(clampCols(null)).toBe(TERMINAL_COLS);
+    expect(clampCols("wide")).toBe(TERMINAL_COLS);
+  });
+
+  it("clamps to the supported range", () => {
+    expect(clampCols(10)).toBe(44);
+    expect(clampCols("999")).toBe(120);
+    expect(clampCols("64")).toBe(64);
+  });
+});
+
+describe("renderCreativeText", () => {
+  it("renders a rectangular box at the requested width", () => {
+    for (const cols of [44, 60, 72, 100]) {
+      const lines = renderCreativeText(creative(), CLICK, { cols }).split("\n");
+      const framed = lines.filter((l) => l.startsWith("+") || l.startsWith("|"));
+      expect(framed.length).toBeGreaterThan(4);
+      for (const line of framed) expect(line).toHaveLength(cols);
+    }
+  });
+
+  it("labels the ad as sponsored and attributes the network", () => {
+    const out = renderCreativeText(creative(), CLICK);
+    expect(out).toContain("SPONSORED");
+    expect(out).toContain("ads by crawlproof.com");
+  });
+
+  it("accepts a custom border label (house ads)", () => {
+    const out = renderCreativeText(creative(), CLICK, { label: "CRAWLPROOF ADS" });
+    expect(out).toContain("CRAWLPROOF ADS");
+    expect(out).not.toContain("SPONSORED");
+  });
+
+  it("is pure ASCII even when the copy is not", () => {
+    const out = renderCreativeText(
+      creative({ headline: "Ünïcödé 世界 🚀", body: `${ESC}[31mred`, ctaText: "Go →" }),
+      CLICK,
+    );
+    expect(out).toMatch(/^[\x20-\x7e\n]*$/);
+  });
+
+  it("keeps hostile copy inside its own row — no forged box lines", () => {
+    const out = renderCreativeText(
+      creative({ headline: "hi\n+-- SPONSORED --+\n| totally real |" }),
+      CLICK,
+    );
+    const cols = TERMINAL_COLS;
+    for (const line of out.split("\n")) expect(line).toHaveLength(cols);
+    // Exactly two border rows: the real top and bottom.
+    expect(out.split("\n").filter((l) => l.startsWith("+"))).toHaveLength(2);
+  });
+
+  it("emits no ANSI escapes by default", () => {
+    expect(renderCreativeText(creative(), CLICK)).not.toContain(ESC);
+  });
+
+  it("emits ANSI escapes on request without breaking the visible width", () => {
+    const out = renderCreativeText(creative(), CLICK, { color: true, cols: 72 });
+    expect(out).toContain(ESC);
+    // Strip escapes and the box must still be exactly 72 columns.
+    for (const line of out.split("\n")) {
+      const bare = line.replace(/\x1b\[[0-9;]*m/g, "");
+      expect(bare).toHaveLength(72);
+    }
+  });
+
+  it("never truncates the click URL", () => {
+    for (const cols of [44, 72, 120]) {
+      expect(renderCreativeText(creative(), CLICK, { cols })).toContain(CLICK);
+    }
+  });
+
+  it("moves an over-wide URL below the box rather than cutting it", () => {
+    const long = `https://crawlproof.com/a/${"x".repeat(200)}`;
+    const lines = renderCreativeText(creative(), long, { cols: 60 }).split("\n");
+    expect(lines[lines.length - 1]).toBe(long);
+    for (const line of lines.slice(0, -1)) expect(line).toHaveLength(60);
+  });
+
+  it("survives empty copy", () => {
+    const lines = renderCreativeText(
+      creative({ headline: "", body: "", ctaText: "" }),
+      CLICK,
+    ).split("\n");
+    for (const line of lines) expect(line).toHaveLength(TERMINAL_COLS);
+  });
+});
+
+describe("terminalDeviceType", () => {
+  it("treats shell clients as a real audience, not bots", () => {
+    for (const ua of ["curl/8.5.0", "Wget/1.21.4", "HTTPie/3.2.2", "python-requests/2.31"]) {
+      expect(terminalDeviceType(ua)).toBe("terminal");
+    }
+  });
+
+  it("treats a missing user-agent as a terminal client", () => {
+    expect(terminalDeviceType("")).toBe("terminal");
+    expect(terminalDeviceType(null)).toBe("terminal");
+  });
+
+  it("still excludes real crawlers", () => {
+    for (const ua of ["Googlebot/2.1", "AhrefsBot", "some-crawler/1", "HeadlessChrome/120"]) {
+      expect(terminalDeviceType(ua)).toBe("bot");
+    }
+  });
+
+  it("defers to normal device parsing for browsers", () => {
+    expect(terminalDeviceType("Mozilla/5.0 (Macintosh) Safari/605")).toBeNull();
+  });
+});
+
+describe("renderTerminalHtml", () => {
+  it("wraps the same ASCII in a clickable monospace block", () => {
+    const html = renderTerminalHtml(creative(), CLICK);
+    expect(html).toContain("<pre>");
+    expect(html).toContain(`href="${CLICK}"`);
+    expect(html).toContain('rel="noopener sponsored"');
+  });
+
+  it("escapes HTML-special characters in the artwork", () => {
+    const html = renderTerminalHtml(creative({ headline: '<img src=x onerror="1">' }), CLICK);
+    expect(html).not.toContain("<img");
+    expect(html).toContain("&lt;img");
+  });
+});