EricAndrechek · Jun 8, 2026 · Jun 6, 2026 · Jun 5, 2026 · Jun 6, 2026 · Jun 6, 2026
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -239,7 +239,16 @@ jobs:
           SHA: ${{ github.event.pull_request.head.sha }}
         run: |
           marker='<!-- docs-preview-comment -->'
-          body="$(printf '%s\n📚 **Docs preview** is live: %s\n\n_Updated for commit %s_' "$marker" "$URL" "${SHA:0:7}")"
+          # Surface what the preview is actually built on: the commit subject
+          # and the upload time, so a stale preview is obvious at a glance.
+          # %s args (not the format string) carry the subject so a `%` in a
+          # commit message can't be read as a printf directive.
+          subject="$(gh api "repos/${GITHUB_REPOSITORY}/commits/${SHA}" --jq '.commit.message' 2>/dev/null | head -1 || true)"
+          [ -z "$subject" ] && subject='(commit message unavailable)'
+          updated="$(date -u '+%Y-%m-%d %H:%M UTC')"
+          commit_url="${GITHUB_SERVER_URL:-https://github.com}/${GITHUB_REPOSITORY}/commit/${SHA}"
+          body="$(printf '%s\n📚 **Docs preview** is live: %s\n\nLive on [`%s`](%s) — %s\n_Updated %s_' \
+            "$marker" "$URL" "${SHA:0:7}" "$commit_url" "$subject" "$updated")"
           cid="$(gh api "repos/${GITHUB_REPOSITORY}/issues/${PR}/comments" --paginate \
             --jq 'map(select(.body | startswith("<!-- docs-preview-comment -->"))) | .[0].id // empty' | head -1 || true)"
           if [ -n "$cid" ]; then

diff --git a/AGENTS.md b/AGENTS.md
@@ -317,6 +317,15 @@ Source-of-truth pairs that must agree:
 
 Before finishing a task, grep for the identifiers you touched (field names, env var names, endpoint paths) across docs to catch staleness.
 
+### Authoring Mermaid diagrams
+
+Diagrams render inside the Starlight content column (~46–58rem wide) as build-time SVG via `astro-themed-mermaid`, themed by `docs/src/config/mermaid-theme.mjs`. **Author them vertically so they fit the page at a legible size** — the single most common diagram mistake here is a wide left-to-right flowchart that gets scaled down to fit the column until its labels are unreadable.
+
+- **Default to top-down**: `flowchart TB`/`TD`, and `direction TB` inside subgraphs — not `LR`/`RL`. A tall diagram keeps full-size nodes and just costs page height (cheap); a wide one shrinks to illegibility. Reserve `LR` for genuinely short chains (≤3–4 nodes) that read naturally as a single line.
+- **Never sit two large diagrams side-by-side.** Wrap comparisons in `<div class="diagram-pair">…</div>`, which stacks them vertically so each gets the full column width. (Two detailed diagrams in a row each shrink to ~half width and stop being readable.)
+- **Keep node labels short.** Labels are measured at build time to size the box; use `<br/>` for a second line rather than one long line. Lean on the `:::` semantic node classes (`wh`, `win`, `pain`, `fail`, `infra`, `neutral`, `store`, `client`) and the `--wh-mermaid-*` vars rather than inline colors.
+- Diagrams are **click-to-zoom** on the site (`docs/src/components/MermaidZoom.astro`), so fine detail is always recoverable — but that's a fallback, not a license to ship an illegible inline diagram.
+
 ## SDK Sync
 
 The TypeScript SDK (`@wavehouse/sdk` in `clients/ts/`) is the canonical client and ships from this repo. When backend changes alter the public API surface, the SDK needs corresponding updates. The `pre-commit` git hook flags likely misses informationally; consult this table when deciding what to update.

diff --git a/CHANGELOG.md b/CHANGELOG.md
diff --git a/Makefile b/Makefile
@@ -251,7 +251,7 @@ dev-ts: pnpm-install ## Watch-build SDK (tsup --watch)
 # Slower per change than Astro HMR; the raw dev server remains available as
 # `pnpm --filter wavehouse-docs run start` when fidelity doesn't matter.
 .PHONY: dev-docs
-dev-docs: install-playwright-docs ## Prod-faithful docs dev loop: rebuild-on-save + wrangler dev on :4321
+dev-docs: install-playwright-docs build-ts ## Prod-faithful docs dev loop: rebuild-on-save + wrangler dev on :4321
 	@$(PNPM) --filter $(DOCS_FILTER) run dev
 
 # preview-docs serves the production build through wrangler (Cloudflare Workers
@@ -526,8 +526,10 @@ build-ts: pnpm-install ## Build TypeScript SDK → clients/ts/dist/
 # `build-docs`, so make runs it once and serializes it before the build — Astro's
 # content-sync writes docs/.astro/, so check and build must not run concurrently.
 # (Link validation is separate: owned by starlight-links-validator at build.)
+# build-ts prereq: the landing page imports @wavehouse/sdk (workspace package),
+# which resolves to clients/ts/dist/ for both types and the browser bundle.
 .PHONY: check-docs
-check-docs: pnpm-install ## Type-check the docs (astro check — types + content schemas)
+check-docs: pnpm-install build-ts ## Type-check the docs (astro check — types + content schemas)
 	$(call run,check-docs (astro check),NODE_OPTIONS=--no-deprecation $(PNPM) -s --filter $(DOCS_FILTER) run check,)
 
 # build-docs: Astro site → docs/dist/. Pulls in Chromium (install-playwright-docs)

diff --git a/README.md b/README.md
@@ -58,6 +58,7 @@ docker compose -f deployments/compose/standalone.yaml exec clickhouse \
 # stream live events in one terminal, then ingest one in another and watch it arrive
 curl -N "http://localhost:8080/v1/stream?table=events" & sleep 1
 # in another terminal, ingest an event (no auth needed with the dev policy)
+# (a 404 "unknown table" here just means schema discovery hasn't seen the new table yet — retry; worst case 60s)
 curl -sX POST "http://localhost:8080/v1/ingest?table=events" \
   -H 'content-type: application/json' -d '{"kind":"click","user":"u_42"}'
 ```

diff --git a/clients/ts/README.md b/clients/ts/README.md
@@ -108,7 +108,7 @@ Generate TypeScript types from your live WaveHouse schema:
 npm run codegen -- --url http://localhost:8080 --out ./src/db.d.ts
 ```
 
-This introspects `/v1/schema`, maps ClickHouse column types to TypeScript, and outputs a `Database` interface you can pass to `createClient<Database>()`.
+This introspects `/v1/schema`, maps ClickHouse column types to TypeScript, and outputs a `Database` interface you can pass to `createClient<Database>()`. `/v1/schema` is **admin-only** — pass an admin-role token with `--auth <jwt>` (or `-a`) against any non-dev policy.
 
 ## Development & Testing
 

diff --git a/clients/ts/src/query-builder.ts b/clients/ts/src/query-builder.ts
@@ -134,7 +134,7 @@ export class QueryBuilder<Row = Record<string, unknown>> implements PromiseLike<
 
   // --- Execution ---
 
-  /** Default row limit when none is specified. Matches backend DefaultMaxRows. */
+  /** Default row limit when none is specified — deliberately tighter than the backend's DefaultMaxRows (10000) safety cap. */
   static readonly DEFAULT_LIMIT = 1000;
 
   async fetch(opts?: FetchOptions): Promise<Result<Row[]>> {

diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs
@@ -117,7 +117,12 @@ export default defineConfig({
       expressiveCode: {
         themes: ["github-dark", "github-light"],
         styleOverrides: {
-          borderRadius: "0.5rem",
+          // 0.75rem − 1px so the frame's OUTER corner lands at exactly 12px
+          // (--radius-md, matching cards): EC adds the 1px border width to the
+          // configured radius for the frame, and derives the inner header/tab/
+          // <pre> corners from the same base, so frame and inner stay in sync
+          // (a manual `.frame` radius in global.css used to desync them).
+          borderRadius: "calc(0.75rem - 1px)",
           codeFontFamily: "'JetBrains Mono Variable', ui-monospace, 'SF Mono', Menlo, monospace",
           uiFontFamily: "'Inter Variable', ui-sans-serif, system-ui, sans-serif",
           frames: {

diff --git a/docs/package.json b/docs/package.json
@@ -18,8 +18,9 @@
     "@fontsource-variable/inter": "^5.2.8",
     "@fontsource-variable/jetbrains-mono": "^5.2.8",
     "@tailwindcss/vite": "^4.3.0",
+    "@wavehouse/sdk": "workspace:*",
     "astro": "^6.1.5",
-    "astro-themed-mermaid": "github:Wave-RF/astro-themed-mermaid#v0.2.0",
+    "astro-themed-mermaid": "github:Wave-RF/astro-themed-mermaid#7c7e0ff3d5c6b31737570d82cfa1956c88350dbd",
     "cloudflare-md-router": "github:Wave-RF/cloudflare-md-router",
     "katex": "^0.16.11",
     "rehype-katex": "^7.0.1",

diff --git a/docs/scripts/screenshot.mjs b/docs/scripts/screenshot.mjs
@@ -39,19 +39,24 @@ try {
         colorScheme: theme === "dark" ? "dark" : "light",
       });
       const page = await ctx.newPage();
-      await page.goto(`${BASE}${p.url}`, { waitUntil: "networkidle" });
+      // "load", not "networkidle": the landing page holds a live SSE stream
+      // open to stats.wavehouse.dev, so the network never goes idle and a
+      // networkidle wait would time the goto out.
+      await page.goto(`${BASE}${p.url}`, { waitUntil: "load" });
       await page.evaluate((t) => {
         document.documentElement.setAttribute("data-theme", t);
         try {
           localStorage.setItem("starlight-theme", t);
         } catch {}
       }, theme);
       // Wait on web fonts + the hero's own ready signal — Hero.astro stamps
-      // `[data-screenshot-ready]` on <html> via animationend on the last
-      // terminal line (first mount) or synchronously when the replay guard
-      // suppresses the entrance choreography (subsequent mounts). Pages
-      // without a hero never get the attribute, so we cap the wait at 5s
-      // and fall through to the screenshot regardless.
+      // `[data-screenshot-ready]` on <html> via animationend on the visual
+      // column's entrance (first mount) or synchronously when the replay
+      // guard suppresses the entrance choreography (subsequent mounts).
+      // Pages without a hero never get the attribute, so we cap the wait at
+      // 5s and fall through to the screenshot regardless. Live-demo data may
+      // or may not have arrived by then — the panel is layout-stable either
+      // way; screenshots assert layout, not live numbers.
       await page.evaluate(() => document.fonts.ready);
       await page.waitForSelector("html[data-screenshot-ready]", { timeout: 5000 }).catch(() => {});
       const filename = `${p.name}-${theme}.png`;

diff --git a/docs/src/components/Footer.astro b/docs/src/components/Footer.astro
@@ -6,6 +6,7 @@
 import EditLink from "virtual:starlight/components/EditLink";
 import LastUpdated from "virtual:starlight/components/LastUpdated";
 import Pagination from "virtual:starlight/components/Pagination";
+import MermaidZoom from "./MermaidZoom.astro";
 import WaveMark from "./WaveMark.astro";
 
 const year = new Date().getFullYear();
@@ -123,6 +124,10 @@ const repo = "https://github.com/Wave-RF/WaveHouse";
   )
 }
 
+{/* Click-to-zoom for Mermaid diagrams — rendered once per page from here
+    (Footer is on every page); self-contained script + styles, no markup. */}
+<MermaidZoom />
+
 <script is:inline>
   function setupFooterLinkTracking() {
     document.querySelectorAll('[data-ph-link]').forEach(function(el) {