release: v2.4.37 — insider ISO-8859-1 fix + alt-data plane live

Aligns package.json + VERSION to the release (both had drifted). This is the
first deployable release carrying the four /v1/world/* macro signals with the
insider charset fix proven against the live SEC feed.

.dockerignore

@@ -0,0 +1,30 @@
+# Build the image from source only — never copy host-built artifacts or deps.
+#
+# The web stage runs `npm ci` + `npm run build` itself and the go stage copies
+# go.mod/cmd/internal explicitly (see Dockerfile), so the host must NOT ship its
+# own node_modules/dist into the context: at `COPY . .` a host node_modules
+# clobbers the image's fresh `npm ci` tree and poisons BuildKit's node_modules
+# cache-mount ("cannot replace directory with file"), which breaks every build.
+node_modules
+**/node_modules
+dist
+**/dist
+build
+out
+.next
+
+.git
+.gitignore
+.github
+
+*.log
+npm-debug.log*
+.env
+.env.*
+!.env.example
+
+.DS_Store
+.vscode
+.idea
+coverage
+*.tsbuildinfo

.github/hero.svg

@@ -0,0 +1,9 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1280" height="640" viewBox="0 0 1280 640" role="img" aria-label="world">
+<rect width="1280" height="640" fill="#0A0A0A"/>
+<svg x="96" y="215" width="210" height="210" viewBox="0 0 67 67"><path d="M22.21 67V44.6369H0V67H22.21Z" fill="#fff"/><path d="M66.7038 22.3184H22.2534L0.0878906 44.6367H44.4634L66.7038 22.3184Z" fill="#fff"/><path d="M22.21 0H0V22.3184H22.21V0Z" fill="#fff"/><path d="M66.7198 0H44.5098V22.3184H66.7198V0Z" fill="#fff"/><path d="M66.7198 67V44.6369H44.5098V67H66.7198Z" fill="#fff"/></svg>
+<text x="378" y="276" font-family="Inter,system-ui,-apple-system,sans-serif" font-size="78" font-weight="800" letter-spacing="-2" fill="#ffffff">world</text>
+<text x="378" y="322" font-family="Inter,system-ui,sans-serif" font-size="30" fill="#ffffff" opacity=".66">World Monitor</text>
+<rect x="378" y="338" width="806" height="3" rx="1.5" fill="#ffffff" opacity=".9"/>
+<text x="378" y="390" font-family="Inter,system-ui,sans-serif" font-size="24" font-weight="600" fill="#ffffff" opacity=".5">github.com/hanzoai</text>
+<text x="1184" y="390" text-anchor="end" font-family="Inter,system-ui,sans-serif" font-size="24" font-weight="600" fill="#ffffff" opacity=".5">hanzo.ai</text>
+</svg>

.github/workflows/cicd.yml

@@ -0,0 +1,22 @@
+# Canonical CI/CD — imports the shared hanzoai/ci reusable workflow, which
+# reads hanzo.yml (images + deploy + kms). No per-repo build logic, no
+# GitHub-hosted runners (defaults to the Hanzo cloud arc pool).
+name: CI/CD
+
+on:
+  push:
+    branches: [main]
+    tags: ['v*']
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  cicd:
+    uses: hanzoai/ci/.github/workflows/build.yml@v1
+    # Target the Hanzo arc scale set by its installation name. ARC scale sets
+    # are matched by name, not by the [self-hosted,linux,amd64] label triple
+    # that ci@v1 defaults to — without this override the job never gets a
+    # runner and sits queued.
+    with:
+      runner: '["hanzo-build-linux-amd64"]'
+    secrets: inherit

.gitignore

@@ -21,3 +21,19 @@ ideas/
 test-results/
 src-tauri/sidecar/node/*
 !src-tauri/sidecar/node/.gitkeep
+
+# world-model runtime snapshot + history ring (regenerated on boot)
+data/world-model.json
+data/world-model.json.tmp
+data/world-model-history.json.gz
+data/world-model-history.json.gz.tmp
+
+# embedded datastore lake + settings (SQLite, WAL mode) — regenerated on boot,
+# lands here only when WORLD_DATA_DIR points at the repo (local dev)
+world.db
+world.db-wal
+world.db-shm
+data/world.db
+data/world.db-wal
+data/world.db-shm
+/world

AGENTS.md

@@ -0,0 +1,45 @@
+# Hanzo World — agent guide
+
+Vite + TypeScript SPA (`world-monitor`). Real-time global-intelligence dashboard
+served at `world.hanzo.ai`, shipped by `hanzo.yml` CI/CD onto the `world`
+operator Service CR. Same-origin data plane under `/v1/world/*`.
+
+## Browser control — prefer the Hanzo MCP extension over Playwright
+
+When the **Hanzo browser MCP** (the `mcp__hanzo__browser` / `mcp__claude-in-chrome__*`
+tools, backed by the local extension in `~/work/hanzo/extension`) is available,
+use it by default to drive a real browser for interactive UI work — inspecting
+the globe, tweaking layers, checking live feeds, capturing screenshots against a
+running dev server. It talks to a real Chrome/Firefox with the real WebGL/deck.gl
+context, so what you see is what a user sees.
+
+Fall back to **Playwright only when** the MCP extension is not connected, or for
+the deterministic **e2e suite** (`e2e/*.spec.ts`) — those run headless in CI with
+mocked `/v1/world/cloud/*` feeds and must stay reproducible offline. E2e is not
+interactive editing; keep the two lanes separate.
+
+Order of preference for "look at / poke the UI": Hanzo MCP browser → Playwright.
+
+## The map / globe
+
+- Basemaps: `dark` · `dot` · `satellite` · `terrain`. **`dot` is the default**
+  for every variant (`DEFAULT_BASEMAP_STYLE` in `src/config/variant.ts`) — the
+  Kaspersky-style cybermap: land drawn only as a glowing dot-lattice over a black
+  ocean sphere, no country fills/borders/imagery.
+- The lattice is one pure value — `getLandDots()` in `src/services/land-dots.ts` —
+  consumed by BOTH the 2D mercator map (`DeckGLMap`) and the 3D globe
+  (`GlobeNative`). One source, two projections. Don't fork it.
+- Cloud view layers (default-on, `?variant=cloud`): live request-origin dots +
+  animated traffic arcs (`AnimatedArcLayer`, a travelling pulse advanced on RAF),
+  validator chain-nodes, BYO-GPU rings, datacenter clusters. Feeds are best-effort
+  and degrade to honest empty states — never fabricate volume.
+- `satellite`/`terrain` need `VITE_MAPBOX_TOKEN` (from KMS `hanzo/deploy/`, never
+  in git); `dark`/`dot` are keyless CartoDB.
+
+## Release
+
+Bump `package.json` PATCH (x.y.z → x.y.z+1, never a lazy major), tag `v<version>`,
+`workflow_dispatch` the `cicd` workflow. The image tag is the version WITHOUT the
+`v`. CI's "Deploy" step can false-negative while the operator finishes rolling —
+verify the live version, not just the CI square. Test/doc-only changes need no
+release (the image is byte-identical).

CHANGELOG.md

@@ -2,6 +2,81 @@
 
 All notable changes to World Monitor are documented here.
 
+## [2.4.19]
+
+### Fixed
+
+- **Moving/resizing a panel no longer shifts the others** (the "when I shift the 3D map it shifts all other components" report). The dashboard now DEFAULTS to the free layout: every panel owns its own {x,y,w,h}, so a drag or resize leaves every sibling exactly where it was — no more grid reflow. The switch is invisible: the current grid arrangement is frozen as the starting geometry (`grid-config.applyDefaultLayout`), and Grid stays one dropdown-click away for anyone who wants snap-to-grid back.
+- **Panels resize granularly** — pixel-exact width AND height from any edge or corner, instead of jumping between coarse column/row spans.
+- **Panels can be made much narrower/smaller** ("constrained on min width"): the free-mode floors drop to 96×40px (map 140px), and the grid widget-size slider now reaches a 120px column track (was 140).
+
+### Changed
+
+- A panel shown from the Panels menu / "+ Add widget" while in free mode seeds a tidy default slot below the placed panels (never a full-width block under its absolute siblings). Hidden panels no longer persist 0×0 geometry.
+
+## [2.4.13]
+
+### Fixed
+
+- **Globe overlays now sit ON the sphere with correct occlusion** (the "map spazzes" report). On the native deck.gl GlobeView, data layers (shared with the 2D map) carried no depth parameters, so the far hemisphere showed through and count badges floated above the limb. GlobeNative now seats every data layer against the depth-writing ocean sphere (test, don't write — no inter-marker z-fight), and the far-side billboard cull (`occludeFarSide`) faces the globe's OWN live camera instead of the parked (frozen) mapbox center — extended to `TextLayer` so a back-side "36" count badge disappears instead of hovering over the planet.
+- **Terrain striping on the globe**: the draped ESRI imagery tiles each wrote depth, so coplanar neighbours z-fought at the tile seams (horizontal stripes / partial render). Tiles now depth-TEST only; the ocean sphere owns the depth buffer.
+- **Live request-geo dots kept polling on the 3D globe**: the `/v1/world/cloud/*` poll was gated on `renderPaused`, which the native GlobeView sets on activation — so the realtime dots froze the moment you entered the default 3D view. It now gates on tab visibility, so the dots stay live (and fade) on the globe.
+
+### Changed
+
+- **Request-origin → serving-region arcs on by default** in the Cloud view: the `/cloud/traffic` arcs derive from the same real native request-geo points as the dots (origin country → nearest Hanzo region) and degrade to empty — never demo.
+
+## [2.4.6]
+
+### Added
+
+- **Enso Flywheel panel (AI variant)**: the router self-improvement loop made visible. New `/v1/world/enso-training` folds the routing-decision ledger tail + reward tail (`export-routing-ledger` / `export-routing-rewards`, super-admin) into ledger growth, engine-vs-heuristic mix, a routing-confidence histogram, and task/model distributions, alongside the latest enso-bench eval scores (an embedded `results/summary.json` snapshot, overridable live via `ENSO_BENCH_URL`). The response is event-typed so future retrain/deploy milestones slot into the same timeline. Eval scores render even signed-out; `state` (live/partial/demo) says which live sources resolved.
+
+## [2.4.5]
+
+### Added
+
+- **AI Compute panel (AI variant)**: live Hanzo inference-plane telemetry over SSE — tokens/s, requests/s, 24h spend, top models by real spend, and the serving fleet (GPUs, machines online, models served). New `/v1/world/ai-pulse` pushes typed `usage`/`fleet`/`status` frames (EventSource) and answers a plain GET with one JSON snapshot as the poll fallback. Honest "connecting"/"unavailable" states — never a zero dressed up as live; the service bearer stays server-side.
+
+## [2.4.4]
+
+### Changed
+
+- **Cloud Pulse is real when a service token is wired**: `/v1/world/cloud-pulse` now folds MEASURED platform-wide 24h request/token volume from the ClickHouse-backed usage ledger (`get-cloud-usages ?org=all`, super-admin) on top of the live model/node/GPU/region counts — dropping both `demo:true` and `volumeModeled:true`. Top models come from real ledger spend. Without a token, or with a non-admin token, it stays honestly demo/modeled — platform numbers are never faked silently. The service bearer stays server-side (never sent to the browser).
+
+## [2.4.2]
+
+### Added
+
+- **Streaming analyst**: answers flow in live over SSE — reasoning shows as dim thinking text, tool calls appear as chips the moment they run, the reply types itself in; the final render and command dispatch are unchanged (done event = the old JSON contract)
+- **Model menu**: the composer pill opens a grouped popover (Auto / Zen / GPT / Llama / Claude / Agents) with per-family marks and an active check
+
+### Fixed
+
+- **Model identity**: the Zen ring appears only on zen* models — gpt-oss/llama/claude get their own marks on the pill, menu rows, avatars, and the thinking row
+- **Dev server**: `npm run dev` proxies /v1 to production by default (VITE_DEV_API_PROXY overrides)
+
+## [2.4.1]
+
+### Added
+
+- **Western Pacific cyclones**: cross-agency tropical-cyclone attribution (GDACS + HKO warnings via new `/v1/world/hko-warnings` proxy) with per-agency wind observations, canonical dedup, and map popup detail rows
+- **China macro snapshot**: `/v1/world/china-macro` — CPI/CLI (OECD), policy rate, USD/CNY (FRED), HKMA context, NBS release calendar + PBoC LPR dates, surfaced with staleness-honest indicator tiles
+- **Model roster**: `Best (auto)` leads the analyst model picker — the gateway routing alias that always resolves
+
+### Changed
+
+- **AI default model**: `zen5` → `best`; a pinned family id goes dark when the inference plane's claim catalog shifts, the routing alias never does
+- **Server cache is now stale-while-revalidate**: `cachedJSON`/`passthrough` serve stale instantly and refresh in the background (single-flight); GDELT/theater-posture no longer stall requests ~10s on TTL expiry
+- **GDELT cache warmers**: hot keys (analyst grounding, protests layer) refreshed every ~4min so no user ever eats a cold miss
+- **Sparkline payloads**: close arrays rounded to 7 significant digits (float32-widening noise stripped, ~40% smaller; scalars untouched)
+
+### Fixed
+
+- **News first paint**: panels no longer gate their first DOM write on a 65MB ML sentiment model download — headlines paint immediately, sentiment refines in place
+- **Analyst grounding snapshot**: context fetches bounded at 2.5s so a cold endpoint can't hold the chat send hostage
+- **AI errors are honest**: upstream error codes (`insufficient_balance`, `spend_cap_exceeded`, …) surface in the chat instead of a bare `status 402`
+
 ## [2.4.0] - 2026-02-19
 
 ### Added

Dockerfile

@@ -0,0 +1,73 @@
+# world.hanzo.ai — Vite SPA + same-origin /api/* data backend, one Go binary.
+#
+# The SPA fetches SAME-ORIGIN /api/* (runtime.ts resolves to the current origin),
+# so world.hanzo.ai (and every *.hanzo.app fork) must serve /api/* itself. The
+# old static-only image (hanzoai/static) had no /api, so every data + live-video
+# request fell through to the SPA index.html — the app showed no data and no
+# video. This image fixes that: cmd/world serves BOTH the static build (with SPA
+# fallback for client routes) AND the ~48 /api/* endpoints (internal/world),
+# each a faithful Go port of the original edge function.
+#
+# Built on Hanzo's own hardware (platform.hanzo.ai -> arcd / in-cluster
+# BuildKit), never on GitHub builders.
+#
+# Build (BuildKit, on-cluster):
+#   --opt=context=https://github.com/hanzoai/world.git#<sha>
+#   --opt=filename=Dockerfile
+#   --output=type=image,name=ghcr.io/hanzoai/world:<tag>,push=true
+#
+# Data-source API keys (all optional; a missing key degrades that endpoint to a
+# clean empty payload, never a 5xx) are injected as env at deploy time from KMS:
+#   YOUTUBE_API_KEY (live-video reliability; scrape fallback needs no key),
+#   FRED_API_KEY, FINNHUB_API_KEY, NASA_FIRMS_API_KEY, EIA_API_KEY,
+#   ACLED_ACCESS_TOKEN, CLOUDFLARE_API_TOKEN, WINGBITS_API_KEY, WS_RELAY_URL,
+#   HANZO_AI_KEY (+ HANZO_AI_BASE / HANZO_AI_MODEL) for the AI endpoints.
+
+# ---- web stage: Vite static build (-> /app/dist) -------------------------
+FROM node:20-bookworm-slim AS web
+WORKDIR /app
+COPY package.json package-lock.json ./
+RUN npm ci
+COPY . .
+# vite.config.ts: default base '/', default outDir 'dist'. VITE_VARIANT defaults
+# to the full layer set; no build-time secrets are required (the runtime API base
+# is same-origin, resolved in the browser).
+ARG VITE_MAPBOX_TOKEN
+ENV VITE_MAPBOX_TOKEN=$VITE_MAPBOX_TOKEN
+RUN npm run build
+
+# ---- go stage: build the static server binary (CGO-free) -----------------
+# go 1.26: go.mod requires >= 1.26.4 (github.com/hanzoai/sqlite drop-in). The
+# binary stays CGO-free — with CGO_ENABLED=0, hanzoai/sqlite selects its vendored
+# pure-Go engine (zero modernc.org/* in the module graph). That engine gates FTS5
+# behind the `sqlite_fts5` build tag, which the store's items_fts virtual table
+# needs — so the build below MUST carry `-tags sqlite_fts5` or Open degrades.
+FROM golang:1.26-alpine AS gobuild
+WORKDIR /src
+# git: go resolves the PRIVATE indirect dep github.com/hanzoai/csqlite 'direct'
+# (not via the module proxy), which needs the git binary + an https credential.
+# alpine ships neither, so add git and mount the gh_token BuildKit secret that
+# hanzoai/ci passes (--secret id=gh_token); the mount is a no-op for public builds.
+RUN apk add --no-cache git
+ENV GOPRIVATE=github.com/hanzoai,github.com/luxfi,github.com/zooai
+# Deps: hanzo-kv client (go-redis) + embedded SQLite (modernc). Download once for
+# a cached layer before the source is copied.
+COPY go.mod go.sum ./
+RUN --mount=type=secret,id=gh_token \
+    if [ -s /run/secrets/gh_token ]; then \
+      git config --global url."https://x-access-token:$(cat /run/secrets/gh_token)@github.com/".insteadOf "https://github.com/"; \
+    fi; \
+    go mod download
+COPY cmd ./cmd
+COPY internal ./internal
+RUN CGO_ENABLED=0 GOOS=linux go build -tags sqlite_fts5 -trimpath -ldflags="-s -w" -o /out/world ./cmd/world
+
+# ---- final stage: minimal image running the Go binary --------------------
+FROM alpine:3.20
+RUN apk add --no-cache ca-certificates tzdata \
+  && adduser -D -H -u 10001 world
+COPY --from=gobuild /out/world /usr/local/bin/world
+COPY --from=web /app/dist /srv
+USER world
+EXPOSE 3000
+ENTRYPOINT ["/usr/local/bin/world", "--root=/srv", "--addr=:3000"]

LICENSE

@@ -1,13 +1,14 @@
 MIT License
 
-Copyright (c) 2025-2026 Elie Habib
+Copyright (c) 2024-2026 Elie Habib
+Copyright (c) 2026 Hanzo AI
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
 in the Software without restriction, including without limitation the rights
 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
+copies of the Software, and to permit persons to whom the Software is furnished
+to do so, subject to the following conditions:
 
 The above copyright notice and this permission notice shall be included in all
 copies or substantial portions of the Software.

NOTICE

@@ -0,0 +1,8 @@
+World Monitor — Hanzo fork
+Copyright (c) 2026 Hanzo AI. Licensed under the MIT License (see LICENSE).
+
+Forked from koala73/worldmonitor (https://github.com/koala73/worldmonitor) at
+v2.4.0 (commit 572f3808) — the last release under the MIT License. This fork
+tracks only the MIT-era code and develops forward independently.
+
+Original work © 2024-2026 Elie Habib, used under the MIT License.

README.md

@@ -1,3 +1,5 @@
+<p align="center"><img src=".github/hero.svg" alt="world" width="880"></p>
+
 # World Monitor
 
 **Real-time global intelligence dashboard** — AI-powered news aggregation, geopolitical monitoring, and infrastructure tracking in a unified situational awareness interface.

VERSION

@@ -0,0 +1 @@
+2.4.37

cmd/world/compress.go

@@ -0,0 +1,115 @@
+package main
+
+import (
+	"compress/gzip"
+	"io"
+	"net/http"
+	"strings"
+	"sync"
+)
+
+// gzip on the fly for the static SPA. The hanzoai/static image this binary
+// replaced compressed responses for us; serving the Vite bundle raw (main.js
+// 1.5MB, map.js 2.7MB) is the whole reason a cold load felt slow. Restoring
+// gzip here cuts the JS/CSS wire size ~75%. Paired with immutable cache headers
+// on hashed assets (see setCacheHeaders), each client pays the transfer once.
+//
+// Scope: wraps ONLY the SPA handler, never /v1/world/* — those include SSE /
+// streaming endpoints that must not be buffered through a gzip.Writer.
+
+var gzipPool = sync.Pool{
+	New: func() any {
+		w, _ := gzip.NewWriterLevel(io.Discard, gzip.DefaultCompression)
+		return w
+	},
+}
+
+// gzipStatic compresses compressible responses when the client accepts gzip.
+// Range requests pass through untouched (compressing a byte-range is invalid).
+func gzipStatic(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Header.Get("Range") != "" || !acceptsGzip(r) {
+			next.ServeHTTP(w, r)
+			return
+		}
+		gw := &gzipResponseWriter{ResponseWriter: w}
+		defer gw.close()
+		next.ServeHTTP(gw, r)
+	})
+}
+
+func acceptsGzip(r *http.Request) bool {
+	for _, enc := range strings.Split(r.Header.Get("Accept-Encoding"), ",") {
+		if strings.EqualFold(strings.TrimSpace(strings.SplitN(enc, ";", 2)[0]), "gzip") {
+			return true
+		}
+	}
+	return false
+}
+
+// compressible reports whether a content type shrinks under gzip. Already-
+// compressed media (png/jpg/woff2/…) is skipped so we never waste CPU or grow
+// the payload.
+func compressible(ct string) bool {
+	ct = strings.ToLower(ct)
+	switch {
+	case strings.HasPrefix(ct, "text/"),
+		strings.Contains(ct, "javascript"),
+		strings.Contains(ct, "json"),
+		strings.Contains(ct, "svg"),
+		strings.Contains(ct, "xml"),
+		strings.Contains(ct, "wasm"),
+		strings.Contains(ct, "manifest"):
+		return true
+	}
+	return false
+}
+
+type gzipResponseWriter struct {
+	http.ResponseWriter
+	gz       *gzip.Writer
+	decided  bool
+	compress bool
+}
+
+func (g *gzipResponseWriter) WriteHeader(status int) {
+	g.decide(status)
+	g.ResponseWriter.WriteHeader(status)
+}
+
+func (g *gzipResponseWriter) Write(b []byte) (int, error) {
+	if !g.decided {
+		g.decide(http.StatusOK) // FileServer may Write without an explicit WriteHeader
+	}
+	if g.compress {
+		return g.gz.Write(b)
+	}
+	return g.ResponseWriter.Write(b)
+}
+
+// decide inspects the headers the wrapped handler set (Content-Type is already
+// populated by http.ServeContent at this point) and commits to compress-or-not
+// exactly once.
+func (g *gzipResponseWriter) decide(status int) {
+	if g.decided {
+		return
+	}
+	g.decided = true
+	h := g.Header()
+	if status == http.StatusOK && h.Get("Content-Encoding") == "" && compressible(h.Get("Content-Type")) {
+		g.compress = true
+		h.Del("Content-Length") // length changes after compression
+		h.Set("Content-Encoding", "gzip")
+		h.Add("Vary", "Accept-Encoding")
+		g.gz = gzipPool.Get().(*gzip.Writer)
+		g.gz.Reset(g.ResponseWriter)
+	}
+}
+
+func (g *gzipResponseWriter) close() {
+	if g.gz != nil {
+		_ = g.gz.Close()
+		gzipPool.Put(g.gz)
+		g.gz = nil
+	}
+}

cmd/world/main.go

@@ -0,0 +1,191 @@
+// Command world is the single process baked into the world image. It serves
+// BOTH the static Vite SPA (world.hanzo.ai and every *.hanzo.app fork) and the
+// same-origin /v1/world/* data + live-video backend the SPA fetches.
+//
+// One binary, two responsibilities kept orthogonal:
+//   - /v1/world/*      → the Go data backend (internal/world), each endpoint a
+//     faithful port of the original edge function.
+//   - everything  → static files from --root, with SPA fallback to index.html
+//     else          for client-routed paths (never for /api or asset misses).
+//
+// It listens on :3000 (the container/CR port); override with --addr or PORT.
+package main
+
+import (
+	"context"
+	"errors"
+	"flag"
+	"io/fs"
+	"log"
+	"net/http"
+	"os"
+	"os/signal"
+	"path/filepath"
+	"strings"
+	"syscall"
+	"time"
+
+	"github.com/hanzoai/world/internal/world"
+)
+
+func main() {
+	var (
+		addr = flag.String("addr", envOr("WORLD_ADDR", ":"+envOr("PORT", "3000")), "listen address")
+		root = flag.String("root", envOr("WORLD_STATIC_ROOT", "dist"), "static SPA root directory")
+	)
+	flag.Parse()
+
+	// Root context cancelled on SIGINT/SIGTERM: drives the world-model ingest
+	// loop and triggers graceful HTTP shutdown from one signal source.
+	rootCtx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
+	defer stop()
+
+	// Fetch secrets from KMS and inject them into the environment BEFORE the
+	// server reads any config. Fail-open: no creds / unreachable KMS logs one
+	// line and continues on plain env (see internal/world/kms.go).
+	world.LoadKMSSecrets(rootCtx)
+
+	srv := world.NewServer()
+	defer srv.Close()           // release hanzo-kv + embedded datastore handles
+	srv.StartModel(rootCtx)     // continuously-folded world-state engine
+	srv.StartDatastore(rootCtx) // shared feed warmer + lake write-behind/prune
+	mux := http.NewServeMux()
+	srv.Mount(mux) // /v1/world/* routes
+
+	// Static SPA + fallback handles everything not matched by an /api route.
+	// gzipStatic wraps ONLY this handler — /v1/world/* keeps its streaming
+	// endpoints unbuffered.
+	mux.Handle("/", gzipStatic(newSPAHandler(*root)))
+
+	httpSrv := &http.Server{
+		Addr:              *addr,
+		Handler:           logRequests(mux),
+		ReadHeaderTimeout: 15 * time.Second,
+		WriteTimeout:      60 * time.Second,
+		IdleTimeout:       120 * time.Second,
+	}
+
+	go func() {
+		log.Printf("world: serving SPA from %q and /v1/world/* on %s", *root, *addr)
+		if err := httpSrv.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
+			log.Fatalf("world: server error: %v", err)
+		}
+	}()
+
+	<-rootCtx.Done()
+	log.Printf("world: shutting down")
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+	_ = httpSrv.Shutdown(ctx)
+}
+
+// spaHandler serves files from root and falls back to index.html for any GET
+// that doesn't resolve to a real file (client-side routing). It never serves the
+// SPA shell for /api paths (those are handled by the mux) and returns 404 for
+// missing static assets so a broken asset URL is visible, not masked by HTML.
+type spaHandler struct {
+	root      string
+	indexHTML []byte
+	csp       string
+	fileSrv   http.Handler
+}
+
+func newSPAHandler(root string) http.Handler {
+	// Honor the same CSP env the prior hanzoai/static image used, so the world
+	// CR needs no change on cutover; WORLD_CSP is an explicit alias.
+	h := &spaHandler{
+		root:    root,
+		fileSrv: http.FileServer(http.Dir(root)),
+		csp:     envOr("HANZO_STATIC_CSP", envOr("WORLD_CSP", "")),
+	}
+	if b, err := os.ReadFile(filepath.Join(root, "index.html")); err == nil {
+		h.indexHTML = b
+	} else {
+		log.Printf("world: warning: no index.html under %q: %v", root, err)
+	}
+	return h
+}
+
+func (h *spaHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodGet && r.Method != http.MethodHead {
+		http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)
+		return
+	}
+	clean := filepath.Clean(r.URL.Path)
+	// Resolve against root; reject traversal.
+	rel := strings.TrimPrefix(clean, "/")
+	full := filepath.Join(h.root, rel)
+	if !strings.HasPrefix(full, filepath.Clean(h.root)) {
+		http.Error(w, "Forbidden", http.StatusForbidden)
+		return
+	}
+
+	if rel == "" || rel == "." {
+		h.serveIndex(w, r)
+		return
+	}
+	info, err := os.Stat(full)
+	switch {
+	case err == nil && !info.IsDir():
+		setCacheHeaders(w, rel)
+		h.fileSrv.ServeHTTP(w, r) // real file
+	case errors.Is(err, fs.ErrNotExist) && !hasExt(rel):
+		h.serveIndex(w, r) // client-routed path → SPA shell
+	default:
+		http.NotFound(w, r) // missing asset (has extension) or dir
+	}
+}
+
+func (h *spaHandler) serveIndex(w http.ResponseWriter, r *http.Request) {
+	if h.indexHTML == nil {
+		http.NotFound(w, r)
+		return
+	}
+	w.Header().Set("Content-Type", "text/html; charset=utf-8")
+	w.Header().Set("Cache-Control", "no-cache")
+	if h.csp != "" {
+		w.Header().Set("Content-Security-Policy", h.csp)
+	}
+	w.WriteHeader(http.StatusOK)
+	if r.Method != http.MethodHead {
+		_, _ = w.Write(h.indexHTML)
+	}
+}
+
+// setCacheHeaders makes Vite's content-hashed bundles cacheable forever while
+// keeping every unhashed file (favicons, manifest, service worker) revalidated
+// so SW updates and icon swaps are never stuck behind a stale cache.
+func setCacheHeaders(w http.ResponseWriter, rel string) {
+	if strings.HasPrefix(rel, "assets/") {
+		w.Header().Set("Cache-Control", "public, max-age=31536000, immutable")
+		return
+	}
+	w.Header().Set("Cache-Control", "no-cache")
+}
+
+// hasExt reports whether the last path segment has a file extension, used to
+// distinguish an asset miss (foo.js → 404) from a client route (/country/US →
+// SPA shell).
+func hasExt(rel string) bool {
+	base := filepath.Base(rel)
+	return strings.Contains(base, ".")
+}
+
+func logRequests(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if strings.HasPrefix(r.URL.Path, "/v1/world/") {
+			start := time.Now()
+			next.ServeHTTP(w, r)
+			log.Printf("api %s %s %s", r.Method, r.URL.Path, time.Since(start).Round(time.Millisecond))
+			return
+		}
+		next.ServeHTTP(w, r)
+	})
+}
+
+func envOr(key, def string) string {
+	if v := strings.TrimSpace(os.Getenv(key)); v != "" {
+		return v
+	}
+	return def
+}

cmd/world/static_test.go

@@ -0,0 +1,123 @@
+package main
+
+import (
+	"bytes"
+	"compress/gzip"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// writeTree lays out a minimal Vite-style dist for the SPA handler tests.
+func writeTree(t *testing.T) string {
+	t.Helper()
+	root := t.TempDir()
+	if err := os.MkdirAll(filepath.Join(root, "assets"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	// A hashed JS bundle large enough that gzip clearly wins.
+	js := strings.Repeat("export const answer = 42;\n", 4000)
+	files := map[string]string{
+		"index.html":             "<!doctype html><title>world</title>",
+		"assets/main-abc123.js":  js,
+		"assets/main-abc123.css": strings.Repeat(".panel{display:flex}\n", 2000),
+		"favicon.ico":            "\x00\x00binary",
+		"manifest.webmanifest":   `{"name":"world"}`,
+	}
+	for name, body := range files {
+		if err := os.WriteFile(filepath.Join(root, name), []byte(body), 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+	return root
+}
+
+func TestStaticGzipAndCache(t *testing.T) {
+	root := writeTree(t)
+	srv := httptest.NewServer(gzipStatic(newSPAHandler(root)))
+	defer srv.Close()
+
+	get := func(path, ae string) *http.Response {
+		req, _ := http.NewRequest(http.MethodGet, srv.URL+path, nil)
+		req.Header.Set("Accept-Encoding", ae)
+		resp, err := http.DefaultTransport.RoundTrip(req) // no transparent gunzip
+		if err != nil {
+			t.Fatalf("GET %s: %v", path, err)
+		}
+		return resp
+	}
+
+	rawLen := func(root, name string) int {
+		b, _ := os.ReadFile(filepath.Join(root, name))
+		return len(b)
+	}
+
+	t.Run("hashed js is gzipped, immutable, and smaller on the wire", func(t *testing.T) {
+		resp := get("/assets/main-abc123.js", "gzip")
+		defer resp.Body.Close()
+		if got := resp.Header.Get("Content-Encoding"); got != "gzip" {
+			t.Fatalf("Content-Encoding = %q, want gzip", got)
+		}
+		if got := resp.Header.Get("Cache-Control"); !strings.Contains(got, "immutable") {
+			t.Fatalf("Cache-Control = %q, want immutable", got)
+		}
+		if !strings.Contains(resp.Header.Get("Vary"), "Accept-Encoding") {
+			t.Fatalf("Vary = %q, want Accept-Encoding", resp.Header.Get("Vary"))
+		}
+		body, _ := io.ReadAll(resp.Body)
+		raw := rawLen(root, "assets/main-abc123.js")
+		if len(body) >= raw {
+			t.Fatalf("gzip wire size %d not smaller than raw %d", len(body), raw)
+		}
+		// And it must actually decode back to the original bytes.
+		zr, err := gzip.NewReader(bytes.NewReader(body))
+		if err != nil {
+			t.Fatalf("gzip.NewReader: %v", err)
+		}
+		dec, _ := io.ReadAll(zr)
+		if len(dec) != raw {
+			t.Fatalf("decoded %d bytes, want %d", len(dec), raw)
+		}
+	})
+
+	t.Run("no gzip when client does not accept it", func(t *testing.T) {
+		resp := get("/assets/main-abc123.js", "identity")
+		defer resp.Body.Close()
+		if resp.Header.Get("Content-Encoding") != "" {
+			t.Fatalf("unexpected Content-Encoding %q", resp.Header.Get("Content-Encoding"))
+		}
+	})
+
+	t.Run("unhashed files revalidate, never immutable", func(t *testing.T) {
+		for _, p := range []string{"/favicon.ico", "/manifest.webmanifest"} {
+			resp := get(p, "gzip")
+			resp.Body.Close()
+			if cc := resp.Header.Get("Cache-Control"); cc != "no-cache" {
+				t.Fatalf("%s Cache-Control = %q, want no-cache", p, cc)
+			}
+		}
+	})
+
+	t.Run("already-compressed media is not re-gzipped", func(t *testing.T) {
+		resp := get("/favicon.ico", "gzip")
+		defer resp.Body.Close()
+		if resp.Header.Get("Content-Encoding") == "gzip" {
+			t.Fatal("favicon.ico should not be gzipped")
+		}
+	})
+
+	t.Run("index shell served with no-cache and gzip", func(t *testing.T) {
+		resp := get("/", "gzip")
+		defer resp.Body.Close()
+		if cc := resp.Header.Get("Cache-Control"); cc != "no-cache" {
+			t.Fatalf("index Cache-Control = %q, want no-cache", cc)
+		}
+		if resp.Header.Get("Content-Encoding") != "gzip" {
+			t.Fatalf("index should be gzipped, got %q", resp.Header.Get("Content-Encoding"))
+		}
+	})
+}

e2e/analyst-command.spec.ts

@@ -0,0 +1,125 @@
+import { expect, test, type Page, type Route } from '@playwright/test';
+
+/**
+ * Analyst control-surface e2e: signed-out shows the sign-in prompt (unchanged
+ * behaviour), and a signed-in command round-trip — a stubbed AI response carrying
+ * a {type:"move_panel"} command flows transport → dispatcher → AppHost and the
+ * panel visibly moves, with a ✓ action-log entry in the chat. No real inference:
+ * the analyst + models routes are stubbed so the test is deterministic offline.
+ */
+
+const SCREENS = 'e2e/screens';
+
+// Stub every /v1/world/* call the chat touches so the flow is deterministic.
+async function stubWorldApi(page: Page): Promise<void> {
+  await page.route('**/v1/world/**', (route: Route) => {
+    const url = route.request().url();
+    if (url.includes('/v1/world/analyst')) {
+      return route.fulfill({
+        status: 200,
+        contentType: 'application/json',
+        body: JSON.stringify({
+          reply: 'Done — moved Markets to the top and switched to the light theme.',
+          actions: [
+            { type: 'move_panel', key: 'markets', position: 'top' },
+            { type: 'set_theme', theme: 'light' },
+          ],
+          model: 'zen5',
+          tokens: 42,
+        }),
+      });
+    }
+    if (url.includes('/v1/world/models')) {
+      return route.fulfill({
+        status: 200,
+        contentType: 'application/json',
+        body: JSON.stringify({
+          data: [
+            { id: 'zen5', label: 'Zen 5', group: 'Zen' },
+            { id: 'zen5-flash', label: 'Zen 5 Flash', group: 'Zen' },
+            { id: 'zen3-omni', label: 'Zen 3 Omni', group: 'Zen' },
+          ],
+          default: 'zen5',
+        }),
+      });
+    }
+    // Everything else (context feeds) → empty, so collectContext degrades quietly.
+    return route.fulfill({ status: 200, contentType: 'application/json', body: '{}' });
+  });
+}
+
+async function signIn(page: Page): Promise<void> {
+  await page.addInitScript(() => {
+    localStorage.setItem('hanzo_iam_access_token', 'e2e-fake-token');
+    localStorage.setItem('hanzo_iam_expires_at', String(Date.now() + 3_600_000));
+    localStorage.setItem('hanzo_iam_owner', 'e2e-org');
+  });
+}
+
+async function appReady(page: Page): Promise<void> {
+  await page.goto('/');
+  await page.waitForSelector('#panelsGrid', { timeout: 60_000 });
+  await page.waitForSelector('[data-panel="markets"]', { timeout: 60_000 });
+}
+
+async function panelOrder(page: Page): Promise<string[]> {
+  return page.$$eval('#panelsGrid [data-panel]', (els) =>
+    els.map((e) => (e as HTMLElement).dataset.panel || ''),
+  );
+}
+
+test.describe('AI analyst control surface', () => {
+  test('signed-out: opening the dock shows the sign-in prompt (unchanged)', async ({ page }) => {
+    await stubWorldApi(page);
+    await appReady(page);
+
+    await page.click('.ai-dock-fab');
+    const prompt = page.locator('.ai-dock-body .ai-analyst-signedout');
+    await expect(prompt).toBeVisible();
+    await expect(prompt.locator('.ai-analyst-signin')).toHaveText(/sign in/i);
+    // No chat composer for anonymous users.
+    await expect(page.locator('.ai-dock-body .ai-analyst-input')).toHaveCount(0);
+
+    await page.screenshot({ path: `${SCREENS}/analyst-signedout.png` });
+  });
+
+  test('signed-in: a stubbed command round-trip moves a panel + logs the action', async ({ page }) => {
+    await signIn(page);
+    await stubWorldApi(page);
+    await appReady(page);
+
+    const before = await panelOrder(page);
+    const beforeIdx = before.indexOf('markets');
+    expect(beforeIdx).toBeGreaterThan(1); // markets starts well down the grid
+    await page.screenshot({ path: `${SCREENS}/round-trip-before.png` });
+
+    // Open the analyst dock and confirm the model dropdown populated.
+    await page.click('.ai-dock-fab');
+    const composer = page.locator('.ai-dock-body .ai-analyst-input');
+    await expect(composer).toBeVisible();
+    const modelSelect = page.locator('.ai-dock-body .ai-analyst-model');
+    await expect(modelSelect).toBeVisible();
+    await expect(modelSelect.locator('option')).toHaveCount(3);
+    await expect(modelSelect).toHaveValue('zen5');
+
+    // Send a command-style message; the stub returns the move+theme commands.
+    await composer.fill('Move markets to the top and go light');
+    await page.click('.ai-dock-body .ai-analyst-send');
+
+    // The prose reply renders…
+    await expect(page.locator('.ai-dock-body .ai-analyst-msg.assistant')).toContainText('moved Markets');
+    // …and the per-command action log shows a ✓ for the executed move.
+    const log = page.locator('.ai-dock-body .ai-analyst-actionlog .ai-analyst-action.ok');
+    await expect(log.first()).toBeVisible();
+    await expect(log.first()).toContainText(/moved markets/i);
+
+    // The panel VISIBLY moved: markets is now near the top of the grid.
+    await expect
+      .poll(async () => (await panelOrder(page)).indexOf('markets'), { timeout: 15_000 })
+      .toBeLessThan(beforeIdx);
+    // And the theme command took effect (whole-app visible change).
+    await expect(page.locator('html')).toHaveAttribute('data-theme', 'light');
+
+    await page.screenshot({ path: `${SCREENS}/round-trip-after.png` });
+  });
+});

e2e/analyst-full-control.spec.ts

@@ -0,0 +1,147 @@
+import { expect, test, type Page, type Route } from '@playwright/test';
+
+/**
+ * Full app control from the chat widget.
+ *
+ * The analyst's control surface is the app-command registry (services/app-commands.ts)
+ * driven through the AppHost port. Until now it could show/hide/move panels and
+ * touch the map, but it could NOT change the layout mode, add a topic to monitor,
+ * or drive the Watch Queue — so "reconfigure the layout and all widgets from the
+ * chat" was not actually true.
+ *
+ * Each test stubs the analyst to return ONE command and asserts the app really
+ * changed — the command is dispatched through the same path a real model reply
+ * takes. No mocked host, no unit-test stand-in for the DOM.
+ */
+
+const SCREENS = 'e2e/screens';
+
+async function stubAnalyst(page: Page, actions: unknown[], reply = 'Done.'): Promise<void> {
+  await page.route('**/v1/world/**', (route: Route) => {
+    const url = route.request().url();
+    if (url.includes('/v1/world/analyst')) {
+      return route.fulfill({
+        status: 200,
+        contentType: 'application/json',
+        body: JSON.stringify({ reply, actions, model: 'zen5', tokens: 0, traces: [] }),
+      });
+    }
+    if (url.includes('/v1/world/models')) {
+      return route.fulfill({
+        status: 200,
+        contentType: 'application/json',
+        body: JSON.stringify({ models: [{ id: 'zen5', name: 'Zen 5' }], default: 'zen5' }),
+      });
+    }
+    // Monitors: signed-in sync endpoints. Keep them empty + accepting.
+    if (url.includes('/v1/world/monitors')) {
+      return route.fulfill({
+        status: 200,
+        contentType: 'application/json',
+        body: JSON.stringify({ monitors: [], matches: [], ok: true }),
+      });
+    }
+    return route.fulfill({ status: 200, contentType: 'application/json', body: '[]' });
+  });
+}
+
+async function signIn(page: Page): Promise<void> {
+  await page.addInitScript(() => {
+    localStorage.setItem('hanzo_iam_access_token', 'e2e-fake-token');
+    localStorage.setItem('hanzo_iam_expires_at', String(Date.now() + 3_600_000));
+    localStorage.setItem('hanzo_iam_owner', 'e2e-org');
+  });
+}
+
+async function appReady(page: Page): Promise<void> {
+  await page.goto('/');
+  await page.waitForSelector('.panel', { timeout: 30_000 });
+}
+
+/** Send any message; the stub decides which command comes back. */
+// Two AnalystChats exist (the in-grid panel and the dock) — they share the SAME
+// code path, so drive the dock's explicitly rather than matching both.
+async function ask(page: Page, text: string): Promise<void> {
+  await page.click('.hzc-fab');
+  const dock = page.locator('.hzc-panel');
+  await expect(dock).toBeVisible();
+  const composer = dock.locator('.hzc-input');
+  await expect(composer).toBeVisible();
+  await composer.fill(text);
+  await dock.locator('.hzc-send').click();
+}
+
+test.describe('analyst full app control', () => {
+  test('set_layout_mode switches the app into immersive', async ({ page }) => {
+    await signIn(page);
+    await stubAnalyst(page, [{ type: 'set_layout_mode', mode: 'immersive' }]);
+    await appReady(page);
+
+    await expect(page.locator('body')).not.toHaveClass(/immersive/);
+    await ask(page, 'go immersive');
+
+    // The app really entered immersive (body class is the mode's source of truth)…
+    await expect(page.locator('body')).toHaveClass(/immersive/);
+    // …and the dock select agrees — the AI and the UI cannot disagree about mode.
+    await expect(page.locator('#dockModeSelect')).toHaveValue('immersive');
+    await page.screenshot({ path: `${SCREENS}/analyst-immersive.png` });
+  });
+
+  test('add_monitor makes the analyst able to watch a new topic', async ({ page }) => {
+    await signIn(page);
+    await stubAnalyst(page, [{ type: 'add_monitor', keywords: 'nvidia, gpu' }]);
+    await appReady(page);
+
+    await ask(page, 'watch for nvidia and gpu');
+
+    // The monitor list really gained the topic (the panel renders it).
+    const monitors = page.locator('#monitorsList');
+    await expect(monitors).toContainText(/nvidia/i);
+    await expect(monitors).toContainText(/gpu/i);
+
+    // And it persisted through the ONE monitor path (localStorage mirror).
+    const stored = await page.evaluate(() =>
+      JSON.parse(localStorage.getItem('worldmonitor-monitors') || '[]'),
+    );
+    expect(JSON.stringify(stored)).toContain('nvidia');
+  });
+
+  test('queue_next advances the Watch Queue', async ({ page }) => {
+    await signIn(page);
+    await stubAnalyst(page, [{ type: 'queue_next' }]);
+    await appReady(page);
+
+    // Seed two items straight into the queue's own store, then let the analyst advance it.
+    await page.evaluate(() => {
+      localStorage.setItem(
+        'hanzo-world-watch-queue',
+        JSON.stringify({
+          items: [
+            { id: 'a', kind: 'video', title: 'First talk', source: 'X', ref: 'aaaaaaaaaaa', addedAt: 1, status: 'queued' },
+            { id: 'b', kind: 'video', title: 'Second talk', source: 'X', ref: 'bbbbbbbbbbb', addedAt: 2, status: 'queued' },
+          ],
+          currentId: 'a',
+        }),
+      );
+    });
+    await page.reload();
+    await page.waitForSelector('.panel', { timeout: 30_000 });
+
+    await ask(page, 'next video');
+
+    // 'a' is finished and 'b' is now current — tracked consumption, driven by the AI.
+    await expect
+      .poll(async () =>
+        page.evaluate(() => {
+          const q = JSON.parse(localStorage.getItem('hanzo-world-watch-queue') || '{}');
+          return q.currentId;
+        }),
+      )
+      .toBe('b');
+    const statusOfA = await page.evaluate(() => {
+      const q = JSON.parse(localStorage.getItem('hanzo-world-watch-queue') || '{}');
+      return (q.items || []).find((i: { id: string }) => i.id === 'a')?.status;
+    });
+    expect(statusOfA).toBe('watched');
+  });
+});

e2e/cloud-mode.spec.ts

@@ -0,0 +1,155 @@
+import { expect, test } from '@playwright/test';
+import { clickMapControl } from './helpers/map-controls';
+
+// Cloud mode: on world.hanzo.ai (and local dev — a hanzo brand host) the H logo is a
+// toggle that reveals the [Hanzo | World | AI | Crypto | Finance | Tech] switcher,
+// and the flagship `hanzo` view ships the live-traffic globe layer. This spec drives
+// the real header + map on the main app, plus the TrafficGlobePanel in isolation.
+
+const TRAFFIC = {
+  updatedAt: '2026-07-16T12:00:00Z',
+  live: true,
+  window: { minutes: 60, since: '2026-07-16T11:00:00Z', until: '2026-07-16T12:00:00Z' },
+  points: [
+    { country: 'US', region: 'CA', lat: 36.12, lon: -119.68, count: 42, byService: { chat: 40, media: 2 } },
+    { country: 'GB', lat: 55.38, lon: -3.44, count: 12, byService: { models: 12 } },
+    { country: 'DE', lat: 51.17, lon: 10.45, count: 7, byService: { embeddings: 7 } },
+  ],
+  totals: { rps_1m: 0.7, rpm_60m: 0.35, top_countries: [{ country: 'US', count: 42 }, { country: 'GB', count: 12 }, { country: 'DE', count: 7 }] },
+};
+
+test.describe('Cloud mode', () => {
+  test('H logo reveals the switcher; cloud view ships the live-traffic globe layer', async ({ page }) => {
+    // Feed the globe layer real points so its poll resolves (avoids a 404 empty state).
+    await page.route('**/v1/world/cloud/traffic-globe', (route) =>
+      route.fulfill({ status: 200, contentType: 'application/json', body: JSON.stringify(TRAFFIC) }),
+    );
+
+    await page.goto('/?variant=cloud');
+
+    // The H logo renders as the Hanzo-mode toggle on this (hanzo brand) host.
+    const hLogo = page.locator('[data-hanzo-toggle]');
+    await expect(hLogo).toBeVisible();
+
+    // Flagship default: the switcher starts collapsed (revealed by the H, not shown
+    // by default), so the clean globe view leads.
+    const switcher = page.locator('.variant-switcher');
+    await expect(switcher).toBeHidden();
+
+    // Click the H → Cloud mode reveals the switcher.
+    await hLogo.click();
+    await expect(page.locator('.header.hanzo-mode')).toHaveCount(1);
+    await expect(switcher).toBeVisible();
+    await expect(hLogo).toHaveAttribute('aria-expanded', 'true');
+
+    // Exactly the [Cloud | World | AI | Crypto | Finance | Tech] tabs, Cloud first.
+    await expect(switcher.locator('.variant-option')).toHaveCount(6);
+    await expect(switcher.locator('.variant-option').first()).toHaveAttribute('data-variant', 'cloud');
+    await expect(page.locator('.variant-option[data-variant="cloud"].active')).toHaveCount(1);
+
+    // Click the H again → collapses.
+    await hLogo.click();
+    await expect(switcher).toBeHidden();
+
+    // The globe's native traffic layer is wired into the layer-toggle system and ON
+    // by default in the hanzo view — i.e. the globe layer is toggleable.
+    await expect(page.locator('.deckgl-map-wrapper')).toBeVisible({ timeout: 45000 });
+    const trafficToggle = page.locator('.layer-toggle[data-layer="traffic"]');
+    await expect(trafficToggle).toHaveCount(1);
+    await expect(trafficToggle.locator('input[type="checkbox"]')).toBeChecked();
+  });
+
+  test('TrafficGlobePanel renders live throughput + top origins, and an honest empty state', async ({ page }) => {
+    await page.goto('/tests/runtime-harness.html');
+
+    // Live payload → throughput tiles + ranked origin countries.
+    const live = await page.evaluate(async (payload) => {
+      const orig = window.fetch;
+      window.fetch = (async () => ({ ok: true, status: 200, json: async () => payload })) as typeof window.fetch;
+      const { TrafficGlobePanel } = await import('/src/components/TrafficGlobePanel.ts');
+      const panel = new TrafficGlobePanel();
+      const root = panel.getElement();
+      document.body.appendChild(root);
+      const deadline = Date.now() + 3000;
+      while (Date.now() < deadline && root.querySelectorAll('.traffic-row').length === 0) {
+        await new Promise((r) => setTimeout(r, 30));
+      }
+      const text = root.textContent ?? '';
+      const rows = root.querySelectorAll('.traffic-row').length;
+      panel.destroy(); root.remove(); window.fetch = orig;
+      return { text, rows };
+    }, TRAFFIC);
+    expect(live.rows).toBe(3);
+    expect(live.text).toContain('US');
+    expect(live.text).toContain('requests / sec');
+    expect(live.text.toLowerCase()).toContain('active regions');
+
+    // Empty payload → honest zero state, never fabricated numbers.
+    const empty = await page.evaluate(async () => {
+      const orig = window.fetch;
+      const EMPTY = { updatedAt: '', live: false, window: { minutes: 60, since: '', until: '' }, points: [], totals: { rps_1m: 0, rpm_60m: 0, top_countries: [] } };
+      window.fetch = (async () => ({ ok: true, status: 200, json: async () => EMPTY })) as typeof window.fetch;
+      const { TrafficGlobePanel } = await import('/src/components/TrafficGlobePanel.ts');
+      const panel = new TrafficGlobePanel();
+      const root = panel.getElement();
+      document.body.appendChild(root);
+      const deadline = Date.now() + 3000;
+      while (Date.now() < deadline && !(root.textContent ?? '').includes('No live traffic')) {
+        await new Promise((r) => setTimeout(r, 30));
+      }
+      const text = root.textContent ?? '';
+      panel.destroy(); root.remove(); window.fetch = orig;
+      return text;
+    });
+    expect(empty).toContain('No live traffic yet');
+  });
+
+  test('3D globe settles (no idle-spin flicker) + Cloud-accurate legend, no cables assertion', async ({ page }) => {
+    await page.route('**/v1/world/cloud/traffic-globe', (route) =>
+      route.fulfill({ status: 200, contentType: 'application/json', body: JSON.stringify(TRAFFIC) }),
+    );
+    const errors: string[] = [];
+    page.on('console', (m) => { if (m.type() === 'error') errors.push(m.text()); });
+
+    await page.goto('/?variant=cloud');
+    await expect(page.locator('.deckgl-map-wrapper')).toBeVisible({ timeout: 45000 });
+
+    // Legend must MATCH what the globe plots — the Cloud data classes, not the
+    // geopolitical default (which would mislabel a traffic dot as "high alert").
+    const legend = page.locator('.deckgl-legend');
+    await expect(legend).toBeVisible();
+    const legendText = (await legend.innerText()).toLowerCase();
+    for (const cls of ['request origin', 'validator node', 'gpu fleet', 'cloud region', 'datacenter']) {
+      expect(legendText).toContain(cls);
+    }
+    for (const geo of ['high alert', 'nuclear', 'elevated']) {
+      expect(legendText).not.toContain(geo);
+    }
+
+    // Switch to the 3D globe (GlobeNative is exposed on window in dev/e2e).
+    await clickMapControl(page, '.deckgl-projection-toggle .proj-btn[data-mode="3d"]');
+    await expect
+      .poll(() => page.evaluate(() => Boolean((window as unknown as { __globeNative?: unknown }).__globeNative)), { timeout: 20000 })
+      .toBe(true);
+
+    // Idle auto-rotate is OFF, so the globe SETTLES: the camera longitude does not
+    // drift and the deck render loop idles (a few data-sync renders, not ~40/s). A
+    // perpetually-spinning globe re-rasterizes thin vector lines every frame — that is
+    // the shimmer; a settled globe does not.
+    const settled = await page.evaluate(async () => {
+      const g = (window as unknown as {
+        __globeNative: { getCenter: () => { lon: number }; getDeck: () => { setProps: (p: unknown) => void } };
+      }).__globeNative;
+      const c0 = g.getCenter();
+      let renders = 0;
+      g.getDeck().setProps({ onAfterRender: () => { renders++; } });
+      await new Promise((r) => setTimeout(r, 1300));
+      return { lonDelta: Math.abs(g.getCenter().lon - c0.lon), renders };
+    });
+    expect(settled.lonDelta).toBeLessThan(0.001); // no idle auto-rotate drift
+    expect(settled.renders).toBeLessThan(12);      // render loop idles (vs ~40/s spinning)
+
+    // The broken cables PathLayer must not assert (cables off in Cloud + path guarded).
+    expect(errors.filter((e) => /cables-layer|assertion failed/i.test(e))).toEqual([]);
+  });
+});

e2e/context-menu.spec.ts

@@ -0,0 +1,174 @@
+import { expect, test, type Page, type Route } from '@playwright/test';
+
+/**
+ * Context-menu + analyst-data-tool e2e.
+ *
+ *   1. Right-click a news-shaped item (the exact data-ctx-* convention NewsPanel
+ *      emits) → the custom menu shows Open link / Copy link / Copy headline plus
+ *      the panel baseline; Copy actually writes to the clipboard.
+ *   2. Right-click the live map → the map menu shows Copy coordinates / Fly here /
+ *      the 2D-3D toggle (via the MapContainer capability port).
+ *   3. A stubbed analyst response carrying a data-tool trace renders the collapsed
+ *      "🔧 world_brief(...)" line before the grounded reply.
+ *
+ * No real inference or feeds: the analyst/models routes are stubbed and the news
+ * item is injected into a live panel so the menu code runs against production DOM.
+ */
+
+const SCREENS = 'e2e/screens';
+
+async function stubWorldApi(page: Page, analystBody?: unknown): Promise<void> {
+  await page.route('**/v1/world/**', (route: Route) => {
+    const url = route.request().url();
+    if (url.includes('/v1/world/analyst')) {
+      return route.fulfill({
+        status: 200,
+        contentType: 'application/json',
+        body: JSON.stringify(
+          analystBody ?? { reply: '', actions: [], model: 'zen5', tokens: 0, traces: [] },
+        ),
+      });
+    }
+    if (url.includes('/v1/world/models')) {
+      return route.fulfill({
+        status: 200,
+        contentType: 'application/json',
+        body: JSON.stringify({
+          data: [{ id: 'zen5', label: 'Zen 5', group: 'Zen' }],
+          default: 'zen5',
+        }),
+      });
+    }
+    return route.fulfill({ status: 200, contentType: 'application/json', body: '{}' });
+  });
+}
+
+async function signIn(page: Page): Promise<void> {
+  await page.addInitScript(() => {
+    localStorage.setItem('hanzo_iam_access_token', 'e2e-fake-token');
+    localStorage.setItem('hanzo_iam_expires_at', String(Date.now() + 3_600_000));
+    localStorage.setItem('hanzo_iam_owner', 'e2e-org');
+  });
+}
+
+async function appReady(page: Page): Promise<void> {
+  await page.goto('/');
+  await page.waitForSelector('#panelsGrid', { timeout: 60_000 });
+}
+
+// Read the current custom menu's item labels (buttons only, not separators/labels).
+async function menuItems(page: Page): Promise<string[]> {
+  return page.$$eval('#panelContextMenu .panel-context-menu-item', (els) =>
+    els.map((e) => (e.textContent || '').trim()),
+  );
+}
+
+test.describe('right-click context menus', () => {
+  test('news item → Open link / Copy link / Copy headline (+ clipboard)', async ({ page, context }) => {
+    await context.grantPermissions(['clipboard-read', 'clipboard-write']);
+    await stubWorldApi(page);
+    await appReady(page);
+
+    // Add a faithful news item (exactly the data-ctx-* attributes NewsPanel
+    // emits) inside its own panel appended to the grid. A synthetic panel is used
+    // so a live panel's periodic re-render can't wipe the item mid-test, and so it
+    // is not under the map canvas — the menu code path is identical either way.
+    await page.evaluate(() => {
+      const grid = document.querySelector('#panelsGrid')!;
+      const panel = document.createElement('div');
+      panel.className = 'panel';
+      panel.dataset.panel = 'e2e-test-panel';
+      panel.innerHTML =
+        '<div class="panel-content"><div class="item" id="e2e-news-item" ' +
+        'data-ctx-url="https://example.com/story" data-ctx-headline="Breaking test headline" ' +
+        'style="padding:12px;min-height:24px;">Breaking test headline</div></div>';
+      grid.appendChild(panel);
+    });
+
+    await page.locator('#e2e-news-item').scrollIntoViewIfNeeded();
+    await page.locator('#e2e-news-item').click({ button: 'right' });
+    await expect(page.locator('#panelContextMenu')).toBeVisible();
+
+    const items = await menuItems(page);
+    expect(items).toEqual(expect.arrayContaining(['Open link', 'Copy link', 'Copy headline']));
+    // Baseline panel actions still ride below the component items.
+    expect(items).toEqual(expect.arrayContaining(['Hide panel', 'Reset layout', 'Full']));
+
+    await page.screenshot({ path: `${SCREENS}/ctxmenu-news.png` });
+
+    // Copy headline actually writes to the clipboard.
+    await page.locator('#panelContextMenu .panel-context-menu-item', { hasText: 'Copy headline' }).click();
+    await expect
+      .poll(() => page.evaluate(() => navigator.clipboard.readText()))
+      .toBe('Breaking test headline');
+    // Menu dismisses after an action.
+    await expect(page.locator('#panelContextMenu')).toHaveCount(0);
+  });
+
+  test('map → Copy coordinates / Fly here / 2D-3D toggle', async ({ page }) => {
+    await stubWorldApi(page);
+    await appReady(page);
+
+    // The map is a first-class grid citizen in the full app; wait for its canvas.
+    await page.waitForSelector('.map-container canvas', { timeout: 60_000 });
+
+    // A stationary right-click on the map surface opens the map menu (a rotate
+    // drag would instead keep the maplibre gesture — not exercised here).
+    await expect
+      .poll(
+        async () => {
+          await page.locator('.map-container canvas').first().click({ button: 'right', position: { x: 300, y: 180 } });
+          if (!(await page.locator('#panelContextMenu').count())) return [];
+          return menuItems(page);
+        },
+        { timeout: 30_000 },
+      )
+      .toEqual(expect.arrayContaining(['Copy coordinates', 'Fly here']));
+
+    const items = await menuItems(page);
+    // The 2D-3D toggle is present (label depends on current projection).
+    expect(items.some((l) => /Switch to (2D map|3D globe)/.test(l))).toBe(true);
+
+    await page.screenshot({ path: `${SCREENS}/ctxmenu-map.png` });
+  });
+});
+
+test.describe('analyst data-tool traces', () => {
+  test('a stubbed tool round-trip renders the 🔧 trace + grounded reply', async ({ page }) => {
+    await signIn(page);
+    await stubWorldApi(page, {
+      reply: 'Composite instability is steady; Sudan and Ukraine lead the movers.',
+      actions: [],
+      model: 'zen5',
+      tokens: 128,
+      traces: [
+        {
+          label: 'world_brief({"n":5})',
+          ok: true,
+          result: '{"asOf":"2026-07-09T00:00:00Z","kind":"country","top":[{"iso":"SD","instability":0.82}]}',
+        },
+      ],
+    });
+    await appReady(page);
+
+    await page.click('.ai-dock-fab');
+    const composer = page.locator('.ai-dock-body .ai-analyst-input');
+    await expect(composer).toBeVisible();
+    await composer.fill('What is the state of global instability?');
+    await page.click('.ai-dock-body .ai-analyst-send');
+
+    // The collapsed tool trace renders before the reply that cites it.
+    const trace = page.locator('.ai-dock-body .ai-analyst-tool .ai-analyst-tool-summary');
+    await expect(trace).toBeVisible();
+    await expect(trace).toContainText('🔧 world_brief(');
+
+    // Expanding it reveals the raw result body.
+    await trace.click();
+    await expect(page.locator('.ai-dock-body .ai-analyst-tool-result')).toContainText('instability');
+
+    // …and the grounded prose reply is shown.
+    await expect(page.locator('.ai-dock-body .ai-analyst-msg.assistant')).toContainText('instability is steady');
+
+    await page.screenshot({ path: `${SCREENS}/analyst-tool-trace.png` });
+  });
+});

e2e/country-view.spec.ts

@@ -0,0 +1,203 @@
+import { expect, test, type Page, type Route } from '@playwright/test';
+
+/**
+ * Country application-view e2e: clicking a country opens a FULLSCREEN view with
+ * the intel content on the left and a docked AI analyst chat on the right
+ * (desktop), a bottom-sheet on mobile. Escape restores the dashboard; the URL
+ * reflects the view (?country=FR) via pushState so browser Back closes it.
+ *
+ * The open is driven through window.__app.openCountryBriefByCode — the EXACT call
+ * the map click handler makes (map.onCountryClicked → openCountryBriefByCode) —
+ * so the test exercises the real click code path deterministically, the same
+ * window.__app hook the repo's other e2e specs use.
+ */
+
+const SCREENS = 'e2e/screens';
+
+async function stubViewApi(page: Page): Promise<void> {
+  await page.route('**/v1/world/**', (route: Route) => {
+    const url = route.request().url();
+    if (url.includes('/v1/world/models')) {
+      return route.fulfill({
+        status: 200,
+        contentType: 'application/json',
+        body: JSON.stringify({
+          data: [
+            { id: 'zen5', label: 'Zen 5', group: 'Zen' },
+            { id: 'zen5-flash', label: 'Zen 5 Flash', group: 'Zen' },
+          ],
+          default: 'zen5',
+        }),
+      });
+    }
+    if (url.includes('/v1/world/country-intel')) {
+      return route.fulfill({
+        status: 200,
+        contentType: 'application/json',
+        body: JSON.stringify({
+          brief: 'France remains stable. Monitoring energy policy and labour actions across major cities.',
+          country: 'France',
+          code: 'FR',
+          cached: false,
+          generatedAt: new Date().toISOString(),
+        }),
+      });
+    }
+    if (url.includes('/v1/world/stock-index')) {
+      return route.fulfill({
+        status: 200,
+        contentType: 'application/json',
+        body: JSON.stringify({ available: true, indexName: 'CAC 40', price: '8000', weekChangePercent: '1.2' }),
+      });
+    }
+    if (url.includes('/v1/world/analyst')) {
+      return route.fulfill({
+        status: 200,
+        contentType: 'application/json',
+        body: JSON.stringify({ reply: 'Energy policy and labour actions are the current drivers.', actions: [], model: 'zen5', tokens: 12 }),
+      });
+    }
+    // Seed the two risk-required feeds (rss + gdelt) so the deep-link handler's
+    // dataFreshness.hasSufficientData() gate flips to 'sufficient' offline.
+    if (url.includes('/v1/world/feeds-batch')) {
+      const body = route.request().postDataJSON() as { urls?: string[] } | null;
+      const urls = body?.urls ?? [];
+      return route.fulfill({
+        status: 200,
+        contentType: 'application/json',
+        body: JSON.stringify({
+          feeds: urls.map((u) => ({
+            url: u,
+            ok: true,
+            items: [{ title: 'Deep-link seed headline', link: 'https://example.com/news', pubDate: new Date().toISOString() }],
+          })),
+        }),
+      });
+    }
+    if (url.includes('/v1/world/gdelt-geo')) {
+      return route.fulfill({
+        status: 200,
+        contentType: 'application/json',
+        body: JSON.stringify({
+          type: 'FeatureCollection',
+          features: [
+            { type: 'Feature', properties: { name: 'Paris, France', count: 60 }, geometry: { type: 'Point', coordinates: [2.3522, 48.8566] } },
+            { type: 'Feature', properties: { name: 'Lyon, France', count: 40 }, geometry: { type: 'Point', coordinates: [4.8357, 45.764] } },
+          ],
+        }),
+      });
+    }
+    return route.fulfill({ status: 200, contentType: 'application/json', body: '{}' });
+  });
+}
+
+async function signIn(page: Page): Promise<void> {
+  await page.addInitScript(() => {
+    localStorage.setItem('hanzo_iam_access_token', 'e2e-fake-token');
+    localStorage.setItem('hanzo_iam_expires_at', String(Date.now() + 3_600_000));
+    localStorage.setItem('hanzo_iam_owner', 'e2e-org');
+  });
+}
+
+async function appReady(page: Page): Promise<void> {
+  await page.goto('/');
+  await page.waitForSelector('#panelsGrid', { timeout: 60_000 });
+}
+
+async function openCountry(page: Page, code = 'FR', name = 'France'): Promise<void> {
+  await page.evaluate(
+    ([c, n]) => (window as unknown as { __app: { openCountryBriefByCode(c: string, n: string): Promise<void> } }).__app.openCountryBriefByCode(c, n),
+    [code, name],
+  );
+  await page.waitForSelector('.country-brief-overlay.active', { timeout: 30_000 });
+}
+
+test.describe('Country application view', () => {
+  test('desktop: fullscreen intel + docked analyst sidebar, URL + Escape', async ({ page }) => {
+    await signIn(page);
+    await stubViewApi(page);
+    await appReady(page);
+
+    await openCountry(page);
+
+    // Fullscreen, not the old centered card: page fills the viewport width.
+    const page_ = page.locator('.country-brief-page');
+    await expect(page_).toBeVisible();
+    const box = await page_.boundingBox();
+    const vp = page.viewportSize()!;
+    expect(box!.width).toBeGreaterThan(vp.width - 4); // no horizontal straitjacket
+
+    // Intel content on the left…
+    await expect(page.locator('.cb-main .cb-body')).toBeVisible();
+    // …docked analyst chat on the right (signed-in → composer, model picker present).
+    const sidebar = page.locator('.cb-analyst-sidebar');
+    await expect(sidebar).toBeVisible();
+    await expect(sidebar.locator('.ai-analyst-input')).toBeVisible();
+    await expect(sidebar.locator('.ai-analyst-model option')).toHaveCount(2);
+    // Sidebar is on the right of the intel content.
+    const mainBox = await page.locator('.cb-main').boundingBox();
+    const sideBox = await sidebar.boundingBox();
+    expect(sideBox!.x).toBeGreaterThan(mainBox!.x);
+
+    // URL reflects the view (pushState).
+    expect(page.url()).toContain('country=FR');
+
+    await page.screenshot({ path: `${SCREENS}/country-view-desktop.png` });
+
+    // Escape restores the dashboard and drops ?country=.
+    await page.keyboard.press('Escape');
+    await expect(page.locator('.country-brief-overlay.active')).toHaveCount(0);
+    expect(page.url()).not.toContain('country=');
+  });
+
+  test('desktop: analyst sidebar collapses and reopens via the pill', async ({ page }) => {
+    await signIn(page);
+    await stubViewApi(page);
+    await appReady(page);
+    await openCountry(page);
+
+    const brief = page.locator('.country-brief-page');
+    await expect(brief).not.toHaveClass(/cb-analyst-collapsed/);
+    await page.click('.cb-analyst-collapse');
+    await expect(brief).toHaveClass(/cb-analyst-collapsed/);
+    await expect(page.locator('.cb-analyst-fab')).toBeVisible();
+    await page.click('.cb-analyst-fab');
+    await expect(brief).not.toHaveClass(/cb-analyst-collapsed/);
+  });
+
+  test('mobile 390px: analyst is a bottom sheet, no horizontal scroll', async ({ page }) => {
+    await page.setViewportSize({ width: 390, height: 844 });
+    await signIn(page);
+    await stubViewApi(page);
+    await appReady(page);
+    await openCountry(page);
+
+    const brief = page.locator('.country-brief-page');
+    // On mobile the intel leads; the analyst starts collapsed with a reopen pill.
+    await expect(brief).toHaveClass(/cb-analyst-collapsed/);
+    await expect(page.locator('.cb-analyst-fab')).toBeVisible();
+    // No horizontal overflow.
+    const scrollW = await page.evaluate(() => document.documentElement.scrollWidth);
+    expect(scrollW).toBeLessThanOrEqual(390 + 1);
+
+    await page.screenshot({ path: `${SCREENS}/country-view-mobile-closed.png` });
+
+    // Open the bottom sheet.
+    await page.click('.cb-analyst-fab');
+    await expect(brief).not.toHaveClass(/cb-analyst-collapsed/);
+    await expect(page.locator('.cb-analyst-sidebar .ai-analyst-input')).toBeVisible();
+    await page.screenshot({ path: `${SCREENS}/country-view-mobile-open.png` });
+  });
+
+  test('deep link: ?country=FR opens the view directly', async ({ page }) => {
+    await signIn(page);
+    await stubViewApi(page);
+    // The deep-link handler waits for sufficient live data before opening; let the
+    // real proxied feeds load (news + gdelt), then assert the view appears.
+    await page.goto('/?country=FR');
+    await page.waitForSelector('#panelsGrid', { timeout: 60_000 });
+    await expect(page.locator('.country-brief-overlay.active')).toBeVisible({ timeout: 80_000 });
+    await expect(page.locator('.cb-analyst-sidebar')).toBeVisible();
+    expect(page.url()).toContain('country=FR');
+  });
+});

e2e/dashboard-sync.spec.ts

@@ -0,0 +1,128 @@
+import { expect, test, type Page } from '@playwright/test';
+
+// The signed-in dashboard-sync contract, verified end-to-end against the REAL app:
+//   1. on boot, this identity's server dashboard is written into localStorage
+//      BEFORE the app reads it (server precedence, cross-device),
+//   2. a change to a dashboard key is synced to the server (debounced PUT of the
+//      full snapshot),
+//   3. signed out, nothing ever touches the server (localStorage only).
+// IAM is faked (a non-expired token + a stubbed userinfo) and /v1/world/dashboard
+// is stubbed, so no real backend or identity is needed.
+
+const DASH = '**/v1/world/dashboard';
+const HIST = '**/v1/world/history';
+const LN = '[data-panel="live-news"]';
+
+async function fakeAuth(page: Page): Promise<void> {
+  await page.addInitScript(() => {
+    localStorage.setItem('hanzo_iam_access_token', 'faketoken');
+    localStorage.setItem('hanzo_iam_expires_at', String(Date.now() + 3_600_000));
+    localStorage.setItem('hanzo_iam_owner', 'acme');
+  });
+  // Keep the fake session valid: a userinfo 401 would let the app drop the token,
+  // and the sync (correctly) stops when signed out.
+  await page.route('**/v1/iam/oauth/userinfo', (r) =>
+    r.fulfill({ json: { sub: 'u1', owner: 'acme', email: 'u@acme.test' } }),
+  );
+  // Default empty history so boot's history hydrate never hits the real backend;
+  // tests that assert on history override this with a later page.route (last wins).
+  await page.route(HIST, (r) => r.fulfill({ json: { config: {} } }));
+}
+
+test.describe('dashboard sync (real app)', () => {
+  test.use({ viewport: { width: 1440, height: 900 } });
+
+  test('boot hydrates localStorage from the server (server precedence)', async ({ page }) => {
+    await fakeAuth(page);
+    await page.route(DASH, async (route) => {
+      if (route.request().method() === 'GET') {
+        await route.fulfill({ json: { config: { 'hanzo-world-map-mode': '3d' } } });
+      } else {
+        await route.fulfill({ json: { ok: true } });
+      }
+    });
+    await page.goto('/');
+    await page.waitForSelector(LN, { timeout: 45000 });
+    // The server value was applied to localStorage at boot, before the app read it.
+    await expect
+      .poll(() => page.evaluate(() => localStorage.getItem('hanzo-world-map-mode')), { timeout: 8000 })
+      .toBe('3d');
+  });
+
+  test('a dashboard change is synced to the server (debounced PUT of the snapshot)', async ({ page }) => {
+    await fakeAuth(page);
+    const puts: Array<Record<string, string>> = [];
+    await page.route(DASH, async (route) => {
+      if (route.request().method() === 'GET') {
+        await route.fulfill({ json: { config: {} } }); // empty server → first run
+      } else {
+        puts.push(route.request().postDataJSON() as Record<string, string>);
+        await route.fulfill({ json: { ok: true } });
+      }
+    });
+    await page.goto('/');
+    await page.waitForSelector(LN, { timeout: 45000 });
+    await page.waitForTimeout(2000); // let the boot writes flush their debounced PUT first
+    // Change an observed dashboard key; a debounced PUT carries a snapshot of ALL
+    // dashboard keys, including our change.
+    await page.evaluate(() => localStorage.setItem('worldmonitor-layers', '{"quakes":true}'));
+    await expect
+      .poll(() => puts.some((p) => p && p['worldmonitor-layers'] === '{"quakes":true}'), { timeout: 8000 })
+      .toBe(true);
+  });
+
+  test('signed out: never touches the server (localStorage only)', async ({ page }) => {
+    let hit = false;
+    await page.route(DASH, async (route) => {
+      hit = true;
+      await route.fulfill({ json: { config: {} } });
+    });
+    await page.goto('/'); // no fakeAuth → anonymous
+    await page.waitForSelector(LN, { timeout: 45000 });
+    await page.evaluate(() => localStorage.setItem('worldmonitor-layers', '{"a":1}'));
+    await page.waitForTimeout(1200);
+    expect(hit).toBe(false);
+  });
+
+  test('history keys sync to /v1/world/history, not /dashboard', async ({ page }) => {
+    await fakeAuth(page);
+    const dashPuts: string[] = [];
+    const histPuts: Array<Record<string, string>> = [];
+    await page.route(DASH, async (route) => {
+      if (route.request().method() === 'GET') await route.fulfill({ json: { config: {} } });
+      else {
+        dashPuts.push(route.request().postData() || '');
+        await route.fulfill({ json: { ok: true } });
+      }
+    });
+    await page.route(HIST, async (route) => {
+      if (route.request().method() === 'GET') await route.fulfill({ json: { config: {} } });
+      else {
+        histPuts.push(route.request().postDataJSON() as Record<string, string>);
+        await route.fulfill({ json: { ok: true } });
+      }
+    });
+    await page.goto('/');
+    await page.waitForSelector(LN, { timeout: 45000 });
+    await page.waitForTimeout(2000); // flush boot writes first
+
+    // A real user action (a recent search) is a HISTORY key → PUT to /history.
+    await page.evaluate(() => localStorage.setItem('worldmonitor_recent_searches', '["nvidia"]'));
+    await expect
+      .poll(() => histPuts.some((p) => p && p['worldmonitor_recent_searches'] === '["nvidia"]'), { timeout: 8000 })
+      .toBe(true);
+    // …and it was NOT mixed into a dashboard PUT (clean namespace separation).
+    expect(dashPuts.some((b) => b.includes('worldmonitor_recent_searches'))).toBe(false);
+  });
+
+  test('boot hydrates history from /v1/world/history (server precedence)', async ({ page }) => {
+    await fakeAuth(page);
+    await page.route(DASH, (r) => r.fulfill({ json: { config: {} } }));
+    await page.route(HIST, (r) => r.fulfill({ json: { config: { 'hanzo-world-watch-queue': '{"items":[7]}' } } }));
+    await page.goto('/');
+    await page.waitForSelector(LN, { timeout: 45000 });
+    await expect
+      .poll(() => page.evaluate(() => localStorage.getItem('hanzo-world-watch-queue')), { timeout: 8000 })
+      .toBe('{"items":[7]}');
+  });
+});

e2e/enso-real-models.spec.ts

@@ -0,0 +1,59 @@
+import { expect, test } from '@playwright/test';
+
+// Enso Live Training must reflect REAL models (the served catalog), never the opaque
+// upstream "arm-N" routing mix that read as random/meaningless amounts. Both feeds are
+// stubbed with real-shaped payloads; the router-stats stub deliberately includes an
+// arm-N by_model map to prove it is NOT rendered anymore.
+
+const ENSO = '.panel[data-panel="enso-training"]';
+
+const ROUTER_STATS = {
+  scope: 'platform',
+  window: { since: '2026-07-17T00:00:00Z', until: '2026-07-18T00:00:00Z', events: 12345 },
+  cost: { saved_pct: 0.23, cumulative_saved_index: 98765, baseline_model: 'x', priced_events: 100 },
+  quality: { reward_rate: 0.5, rewarded_events: 10, engine_share: 0.62, avg_confidence: 0.8, shadow_agreement: 0.91 },
+  by_task: {},
+  by_model: { 'arm-1': 100, 'arm-2': 50, 'arm-3': 25 }, // opaque arms — must NOT render
+  throughput: { per_hour: [1, 2, 3, 4, 5, 6], total_window: 21 },
+  retrain: {
+    version: 'v9', trained_time: '2026-07-17T12:00:00Z', events: 100, gate_passed: true,
+    published: true, gate_kind: 'reward', gate_metric: 'rate', gate_value: 0.5, gate_base: 0.4, note: '',
+  },
+};
+
+const CLOUD_MODELS = {
+  updatedAt: '2026-07-18T00:00:00Z',
+  totalModels: 42,
+  zenModels: 8,
+  cloudRegions: 5,
+  cloudPlans: 3,
+  families: ['Zen', 'Fable'],
+  models: [
+    { id: 'zen5', name: 'Zen 5', provider: 'hanzo', tier: 'flagship', context: 200000, inPrice: 3, outPrice: 15 },
+    { id: 'zen5-flash', name: 'Zen 5 Flash', provider: 'hanzo', tier: 'fast', context: 128000, inPrice: 0.5, outPrice: 1.5 },
+    { id: 'fable5', name: 'Fable 5', provider: 'hanzo', tier: 'premium', context: 400000, inPrice: 5, outPrice: 20 },
+  ],
+};
+
+test.describe('Enso Live Training — real models only', () => {
+  test.use({ viewport: { width: 1440, height: 900 } });
+
+  test('renders the real served-model catalog, never opaque arm-N amounts', async ({ page }) => {
+    await page.route('**/v1/world/cloud/router-stats*', (r) => r.fulfill({ json: ROUTER_STATS }));
+    await page.route('**/v1/world/cloud/models', (r) => r.fulfill({ json: CLOUD_MODELS }));
+
+    await page.goto('/');
+    await page.waitForSelector(ENSO, { timeout: 45000 });
+    const panel = page.locator(ENSO);
+
+    // Real model names from the catalog appear.
+    await expect(panel).toContainText('Zen 5 Flash', { timeout: 15000 });
+    await expect(panel).toContainText('Fable 5');
+    await expect(panel).toContainText('models served');
+    // Real aggregates still render (unchanged, real telemetry).
+    await expect(panel).toContainText('cost saved');
+    // The opaque per-arm amounts are GONE — no meaningless "Enso arm N" rows.
+    await expect(panel).not.toContainText('Enso arm');
+    await expect(panel).not.toContainText('arm-1');
+  });
+});

e2e/enso-training-panel.spec.ts

@@ -0,0 +1,69 @@
+import { expect, test } from '@playwright/test';
+
+// Mounts the real EnsoTrainingPanel against a stubbed router-stats payload and
+// asserts the rendered DOM: opaque "Enso arm N" labels (NEVER a vendor name),
+// the cost-saved headline, the retrain gate verdict, and the honest "—" shadow
+// state. Mirrors e2e/investments-panel.spec.ts (runtime-harness).
+test.describe('Enso Live Training panel', () => {
+  test('renders opaque arms, cost-saved headline and retrain gate — no vendor names', async ({ page }) => {
+    await page.goto('/tests/runtime-harness.html');
+
+    const result = await page.evaluate(async () => {
+      const CANNED = {
+        scope: 'platform',
+        window: { since: '2026-07-15T00:00:00Z', until: '2026-07-16T00:00:00Z', events: 48210 },
+        cost: { saved_pct: 21.5, cumulative_saved_index: 1372, baseline_model: 'arm-1', priced_events: 41000 },
+        quality: { reward_rate: 0.31, rewarded_events: 1200, engine_share: 0.62, avg_confidence: 0.74, shadow_agreement: null },
+        by_task: { chat: { events: 30000, models: { 'arm-1': 18000, 'arm-2': 12000 } } },
+        by_model: { 'arm-1': 30000, 'arm-2': 14000, 'arm-3': 4210 },
+        throughput: { per_hour: Array.from({ length: 24 }, (_, i) => 1500 + i * 40), total_window: 48210 },
+        retrain: {
+          version: 'router-2026.07.16', trained_time: '2026-07-16T00:00:00Z', events: 48210,
+          gate_passed: true, published: true, gate_kind: 'holdout', gate_metric: 'reward',
+          gate_value: 0.312, gate_base: 0.298, note: 'shipped',
+        },
+      };
+
+      // Stub the same-origin proxy the service calls.
+      const origFetch = window.fetch;
+      window.fetch = (async () =>
+        ({ ok: true, status: 200, json: async () => CANNED })) as typeof window.fetch;
+
+      const { EnsoTrainingPanel } = await import('/src/components/EnsoTrainingPanel.ts');
+      const panel = new EnsoTrainingPanel();
+      const root = panel.getElement();
+      document.body.appendChild(root);
+
+      // Wait for the async fetch → render to land.
+      const deadline = Date.now() + 3000;
+      while (Date.now() < deadline && root.querySelectorAll('.cloud-model-row').length === 0) {
+        await new Promise((r) => setTimeout(r, 30));
+      }
+
+      const armLabels = Array.from(root.querySelectorAll('.cloud-model-name')).map(
+        (n) => (n.textContent ?? '').trim(),
+      );
+      const text = root.textContent ?? '';
+
+      panel.destroy();
+      root.remove();
+      window.fetch = origFetch;
+
+      return { armLabels, text };
+    });
+
+    // Three opaque arms, labeled by tier — never a vendor name.
+    expect(result.armLabels.length).toBe(3);
+    expect(result.armLabels[0]).toContain('Enso arm 1');
+    expect(result.armLabels[1]).toContain('Enso arm 2');
+    expect(result.armLabels[2]).toContain('Enso arm 3');
+    for (const vendor of ['claude', 'anthropic', 'gpt', 'openai', 'deepseek', 'qwen', 'gemini', 'llama']) {
+      expect(result.text.toLowerCase()).not.toContain(vendor);
+    }
+
+    // Headline cost-saved + retrain gate verdict + honest empty shadow state.
+    expect(result.text).toContain('21.5%');
+    expect(result.text).toContain('passed');
+    expect(result.text).toContain('Shadow-vs-served agreement: —');
+  });
+});

e2e/globe-native.spec.ts

@@ -0,0 +1,136 @@
+import { expect, test } from '@playwright/test';
+
+// Native deck.gl GlobeView (GlobeNative) — the pure-deck 3D globe that replaces the
+// mapbox globe behind the ?globe=native flag.
+//
+// This guards the structural perf + correctness contract that a headless GPU CAN
+// verify:
+//   - the mode activates from the ?globe=native flag,
+//   - the whole page holds exactly ONE WebGL context (no mapbox, no overlay) — the
+//     single-context perf target,
+//   - deck's active viewport is a GlobeViewport (proves it's reprojecting onto the
+//     sphere, not a flat map),
+//   - a seeded hotspot picks at its globe-projected screen point (layers render AND
+//     reproject on the sphere).
+
+type PickResult = { found: boolean; layerId: string | null };
+
+type GlobeHarness = {
+  ready: boolean;
+  nativeEnabled: boolean;
+  getCanvasCount: () => number;
+  getViewportType: () => string | null;
+  getFirstHotspotLngLat: () => { lon: number; lat: number } | null;
+  setCamera: (lon: number, lat: number, zoom: number) => void;
+  stopSpin: () => void;
+  pickAtLonLat: (lon: number, lat: number, radius?: number) => PickResult;
+  setBasemapStyle: (style: 'dark' | 'satellite' | 'terrain') => void;
+  getBasemapStyle: () => string;
+  destroy: () => void;
+};
+
+type HarnessWindow = Window & { __globeHarness?: GlobeHarness };
+type Page = import('@playwright/test').Page;
+
+const ready = async (page: Page, query: string): Promise<void> => {
+  await page.goto(`/tests/globe-native-harness.html${query}`);
+  await expect(page.locator('.globe-native-wrapper')).toBeVisible();
+  await expect
+    .poll(() => page.evaluate(() => Boolean((window as HarnessWindow).__globeHarness?.ready)), {
+      timeout: 45000,
+    })
+    .toBe(true);
+};
+
+const pickHotspot = async (page: Page): Promise<PickResult> =>
+  page.evaluate(() => {
+    const w = (window as HarnessWindow).__globeHarness!;
+    const hs = w.getFirstHotspotLngLat();
+    if (!hs) return { found: false, layerId: null };
+    w.setCamera(hs.lon, hs.lat, 3);
+    w.stopSpin();
+    return w.pickAtLonLat(hs.lon, hs.lat, 12);
+  });
+
+test.describe('native deck.gl GlobeView', () => {
+  test.describe.configure({ retries: 1 });
+  test.use({ reducedMotion: 'reduce' });
+
+  test('flag activates; single WebGL context; GlobeViewport; hotspot picks on the sphere', async ({
+    page,
+  }, testInfo) => {
+    const pageErrors: string[] = [];
+    const ignorable = [/could not compile fragment shader/i, /image.*could not be decoded/i];
+    page.on('pageerror', (e) => pageErrors.push(e.message));
+
+    await ready(page, '?globe=native');
+
+    // The flag helper the app routes on reads native from ?globe=native.
+    expect(
+      await page.evaluate(() => (window as HarnessWindow).__globeHarness!.nativeEnabled),
+    ).toBe(true);
+
+    // Single WebGL context: exactly one <canvas> on the whole page (no mapbox basemap
+    // canvas, no deck overlay canvas — just GlobeNative's).
+    expect(await page.evaluate(() => document.querySelectorAll('canvas').length)).toBe(1);
+    expect(
+      await page.evaluate(() => (window as HarnessWindow).__globeHarness!.getCanvasCount()),
+    ).toBe(1);
+
+    // Active viewport is a GlobeViewport (deck is reprojecting onto the sphere).
+    await expect.poll(() =>
+      page.evaluate(() => (window as HarnessWindow).__globeHarness!.getViewportType()),
+    ).toMatch(/Globe/i);
+
+    // A seeded hotspot picks at its globe-projected screen point.
+    await expect.poll(async () => (await pickHotspot(page)).found, { timeout: 20000 }).toBe(true);
+
+    // CTO-facing proof: dots + monochrome basemap on the sphere.
+    await page.evaluate(() => {
+      const w = (window as HarnessWindow).__globeHarness!;
+      const hs = w.getFirstHotspotLngLat();
+      if (hs) w.setCamera(hs.lon, hs.lat, 2.2);
+      w.stopSpin();
+    });
+    await page.waitForTimeout(600);
+    const shot = await page.locator('.globe-native-wrapper').screenshot();
+    await testInfo.attach('globe-native-dots', { body: shot, contentType: 'image/png' });
+
+    expect(pageErrors.filter((e) => !ignorable.some((p) => p.test(e)))).toEqual([]);
+  });
+
+  test('native is the default; ?globe=mapbox is the escape hatch', async ({ page }) => {
+    // Default (no query param) → native is on.
+    await ready(page, '');
+    expect(
+      await page.evaluate(() => (window as HarnessWindow).__globeHarness!.nativeEnabled),
+    ).toBe(true);
+    expect(await page.evaluate(() => document.querySelectorAll('canvas').length)).toBe(1);
+
+    // Escape hatch → native off (the app would render the mapbox globe instead).
+    await ready(page, '?globe=mapbox');
+    expect(
+      await page.evaluate(() => (window as HarnessWindow).__globeHarness!.nativeEnabled),
+    ).toBe(false);
+  });
+
+  test('basemap style switches dark/satellite/terrain, stays single-context, data still picks', async ({
+    page,
+  }) => {
+    await ready(page, '?globe=native');
+
+    const setStyle = (s: 'dark' | 'satellite' | 'terrain') =>
+      page.evaluate((style) => (window as HarnessWindow).__globeHarness!.setBasemapStyle(style), s);
+    const getStyle = () =>
+      page.evaluate(() => (window as HarnessWindow).__globeHarness!.getBasemapStyle());
+
+    for (const style of ['satellite', 'terrain', 'dark'] as const) {
+      await setStyle(style);
+      expect(await getStyle()).toBe(style);
+      // Draping imagery must not spawn a second WebGL context...
+      expect(await page.evaluate(() => document.querySelectorAll('canvas').length)).toBe(1);
+      // ...and the data layers keep rendering ON TOP (still pickable on the sphere).
+      await expect.poll(async () => (await pickHotspot(page)).found, { timeout: 15000 }).toBe(true);
+    }
+  });
+});

e2e/globe-overlay.spec.ts

@@ -0,0 +1,152 @@
+import { expect, test } from '@playwright/test';
+import { clickMapControl } from './helpers/map-controls';
+
+// P0-1: deck.gl overlays must actually RENDER on the mapbox-gl v3 globe.
+//
+// The regression this guards: with interleaved:true, MapboxOverlay drew deck
+// layers inside mapbox's projection pass, which does NOT reproject onto the
+// globe — every overlay silently vanished in 3D (2D was fine). The fix flips the
+// overlay to interleaved:false (overlaid), giving deck its own canvas + its own
+// _GlobeView derived from the live map projection each frame.
+//
+// getDeckLayerSnapshot() (used by globe.spec) reads buildLayers() output and so
+// passed EVEN WITH THE BUG. This spec instead asserts the renderer mechanism and
+// a real on-globe pick — signals that are only true when layers reproject:
+//   - the overlay is overlaid (interleaved === false) and owns its own canvas,
+//   - deck's active viewport is a GlobeViewport in 3D (mercator in 2D),
+//   - picking a seeded feature at its globe-projected screen point hits it.
+// It exercises 2D→3D→2D round-trips and a live setStyle (theme swap).
+
+type PickResult = { found: boolean; layerId: string | null };
+
+type Harness = {
+  ready: boolean;
+  seedAllDynamicData: () => void;
+  setZoom: (zoom: number) => void;
+  setCamera: (camera: { lon: number; lat: number; zoom: number }) => void;
+  setLayersForSnapshot: (layers: string[]) => void;
+  setProjectionMode: (mode: '2d' | '3d') => void;
+  getProjectionType: () => string;
+  stopIdleSpin: () => void;
+  getDeckInterleaved: () => boolean | null;
+  getDeckCanvasCount: () => number;
+  getDeckViewportType: () => string | null;
+  getFirstHotspotLngLat: () => { lon: number; lat: number } | null;
+  pickAtLonLat: (lon: number, lat: number, radius?: number) => PickResult;
+};
+
+type HarnessWindow = Window & {
+  __mapHarness?: Harness;
+  __mapboxMap?: unknown;
+};
+
+type Page = import('@playwright/test').Page;
+
+const H = 'window.__mapHarness';
+
+const ready = async (page: Page): Promise<void> => {
+  await page.goto('/tests/map-harness.html');
+  await expect(page.locator('.deckgl-map-wrapper')).toBeVisible();
+  await expect
+    .poll(() => page.evaluate(() => Boolean((window as HarnessWindow).__mapHarness?.ready)), {
+      timeout: 45000,
+    })
+    .toBe(true);
+  // Only the hotspots layer needs to be on; it is fed by the static INTEL_HOTSPOTS
+  // config, so it is present regardless of any live data.
+  await page.evaluate(() => {
+    const w = (window as HarnessWindow).__mapHarness!;
+    w.seedAllDynamicData();
+    w.setLayersForSnapshot(['hotspots']);
+    w.stopIdleSpin();
+  });
+};
+
+const projection = (page: Page): Promise<string> =>
+  page.evaluate(() => (window as HarnessWindow).__mapHarness?.getProjectionType() ?? 'mercator');
+
+const viewportType = (page: Page): Promise<string | null> =>
+  page.evaluate(() => (window as HarnessWindow).__mapHarness?.getDeckViewportType() ?? null);
+
+// Centre on the seeded hotspot, freeze the spin, then pick it. Picking succeeds
+// only if the layer is actually rendered AND projected at that screen location.
+const pickHotspot = async (page: Page): Promise<PickResult> => {
+  return page.evaluate(() => {
+    const w = (window as HarnessWindow).__mapHarness!;
+    const hs = w.getFirstHotspotLngLat();
+    if (!hs) return { found: false, layerId: null };
+    w.setCamera({ lon: hs.lon, lat: hs.lat, zoom: 3 });
+    w.stopIdleSpin();
+    return w.pickAtLonLat(hs.lon, hs.lat, 12);
+  });
+};
+
+const pollPickFound = async (page: Page): Promise<void> => {
+  await expect
+    .poll(async () => (await pickHotspot(page)).found, { timeout: 20000 })
+    .toBe(true);
+};
+
+test.describe('P0-1 deck overlay renders on the globe', () => {
+  test.describe.configure({ retries: 1 });
+  test.use({ reducedMotion: 'reduce' });
+
+  test('overlaid mode; GlobeViewport in 3D; feature picks on the sphere; survives round-trips + setStyle', async ({
+    page,
+  }, testInfo) => {
+    const pageErrors: string[] = [];
+    const ignorable = [/could not compile fragment shader/i, /image.*could not be decoded/i];
+    page.on('pageerror', (e) => pageErrors.push(e.message));
+
+    await ready(page);
+
+    // The overlay is OVERLAID (the fix), not interleaved, and owns its own canvas.
+    expect(await page.evaluate(() => (window as HarnessWindow).__mapHarness!.getDeckInterleaved())).toBe(false);
+    expect(await page.evaluate(() => (window as HarnessWindow).__mapHarness!.getDeckCanvasCount())).toBeGreaterThanOrEqual(2);
+
+    // 2D baseline: mercator viewport + pickable dot.
+    expect(await projection(page)).toBe('mercator');
+    await expect.poll(() => viewportType(page)).toMatch(/Mercator|Web/i);
+    await pollPickFound(page);
+
+    // → 3D globe. Deck's active viewport must be a GlobeViewport (proves deck is
+    // reprojecting onto the sphere) and the dot must still pick on the globe.
+    await clickMapControl(page, '.deckgl-projection-toggle .proj-btn[data-mode="3d"]');
+    await expect.poll(() => projection(page), { timeout: 30000 }).toBe('globe');
+    await page.evaluate(() => (window as HarnessWindow).__mapHarness!.stopIdleSpin());
+    await expect.poll(() => viewportType(page), { timeout: 20000 }).toMatch(/Globe/i);
+    await pollPickFound(page);
+
+    // Screenshot the dots on the sphere (the CTO-facing proof).
+    await page.evaluate(() => {
+      const w = (window as HarnessWindow).__mapHarness!;
+      const hs = w.getFirstHotspotLngLat();
+      if (hs) w.setCamera({ lon: hs.lon, lat: hs.lat, zoom: 2.2 });
+      w.stopIdleSpin();
+    });
+    await page.waitForTimeout(600);
+    const shot = await page.locator('.deckgl-map-wrapper').screenshot();
+    await testInfo.attach('globe-3d-dots', { body: shot, contentType: 'image/png' });
+
+    // Round-trip 2D → 3D again; picks must survive each transition.
+    await clickMapControl(page, '.deckgl-projection-toggle .proj-btn[data-mode="2d"]');
+    await expect.poll(() => projection(page), { timeout: 20000 }).toBe('mercator');
+    await pollPickFound(page);
+    await clickMapControl(page, '.deckgl-projection-toggle .proj-btn[data-mode="3d"]');
+    await expect.poll(() => projection(page), { timeout: 20000 }).toBe('globe');
+    await page.evaluate(() => (window as HarnessWindow).__mapHarness!.stopIdleSpin());
+    await pollPickFound(page);
+
+    // setStyle: a full basemap swap (theme change) clears mapbox sources but the
+    // overlaid deck lives outside the style, so its layers must survive.
+    await page.evaluate(() =>
+      window.dispatchEvent(new CustomEvent('theme-changed', { detail: { theme: 'light' } })),
+    );
+    await page.waitForTimeout(1500); // style.load + re-applied projection/atmosphere
+    await page.evaluate(() => (window as HarnessWindow).__mapHarness!.stopIdleSpin());
+    expect(await page.evaluate(() => (window as HarnessWindow).__mapHarness!.getDeckInterleaved())).toBe(false);
+    await pollPickFound(page);
+
+    expect(pageErrors.filter((e) => !ignorable.some((p) => p.test(e)))).toEqual([]);
+  });
+});

e2e/globe-render.spec.ts

@@ -0,0 +1,223 @@
+import { expect, test } from '@playwright/test';
+
+// Globe render-fix acceptance suite (world.hanzo.ai Hanzo-Cloud view).
+//
+// Guards the three "spazz" bugs the CTO reported and the 2D/3D parity + live-analytics
+// contract:
+//   1. Overlays must sit ON the globe surface with correct occlusion — a back-hemisphere
+//      dot/badge is HIDDEN, a front one is drawn (no floating layers above the sphere).
+//   2. Terrain drapes on the globe in a single WebGL context (no second canvas, no
+//      striping regression — depth-write disabled on the coplanar imagery tiles).
+//   3. Every cloud data layer mounts in BOTH 2D (mercator) and 3D (globe) — parity.
+// Plus: the REAL live request-geo dots appear and update.
+//
+// Data is mocked at the same-origin /v1/world/cloud/* contracts so the run is
+// deterministic and offline (production serves the real, live payloads).
+
+type DeckLayer = { id: string; props: Record<string, unknown> };
+type Rgba = [number, number, number, number];
+
+const cloudMap = {
+  // Two request-origin points on OPPOSITE hemispheres so occlusion is testable:
+  // FRONT (lon 0) faces a camera centred at lon 0; BACK (lon 180) is behind the globe.
+  trafficGlobe: {
+    updatedAt: '2026-07-18T12:00:00Z',
+    live: true,
+    window: { minutes: 60, since: '2026-07-18T11:00:00Z', until: '2026-07-18T12:00:00Z' },
+    points: [
+      { country: 'FR', lat: 20, lon: 0, count: 90, byService: { models: 90 } },
+      { country: 'US', lat: 37.09, lon: -95.71, count: 42, byService: { models: 42 } },
+      { country: 'JP', lat: 20, lon: 180, count: 30, byService: { models: 30 } },
+    ],
+    totals: { rps_1m: 1.6, rpm_60m: 96, top_countries: [{ country: 'FR', count: 90 }, { country: 'US', count: 42 }, { country: 'JP', count: 30 }] },
+  },
+  traffic: {
+    updatedAt: '2026-07-18T12:00:00Z', demo: false,
+    arcs: [
+      { fromLat: 20, fromLon: 0, toLat: 51.5, toLon: -0.12, weight: 1, label: 'FR → lon' },
+      { fromLat: 37.09, fromLon: -95.71, toLat: 40.71, toLon: -74.0, weight: 0.6, label: 'US → nyc' },
+    ],
+  },
+  chainNodes: {
+    updatedAt: '2026-07-18T12:00:00Z', positionsModeled: true,
+    networks: [{ id: 'lux', name: 'Lux Network', chainId: 96369, blockHeight: 1096461, peers: 3, live: true,
+      nodes: [{ lat: 40.71, lon: -74.0, city: 'New York', kind: 'validator' }, { lat: 37.77, lon: -122.42, city: 'San Francisco', kind: 'validator' }] }],
+  },
+  byoGpu: { updatedAt: '2026-07-18T12:00:00Z', demo: false, gpus: [] },
+};
+
+// The flagship Cloud variant now OPENS on the native 3D globe (its immersive default),
+// which parks the mapbox 2D map — `.deckgl-map-wrapper` mounts hidden. These specs
+// exercise the 2D→3D toggle path (2D layer parity, then go3D), so they pin the start
+// to 2D with `?mode=2d` (resolveInitialMapMode: the URL wins over the variant default).
+// The globe-as-default render is proven separately (direct visual + the live prod shot).
+const CLOUD_2D = '/?variant=cloud&mode=2d';
+
+async function mockCloud(page: import('@playwright/test').Page, traffic = cloudMap.trafficGlobe): Promise<void> {
+  const json = (body: unknown) => ({ status: 200, contentType: 'application/json', body: JSON.stringify(body) });
+  await page.route('**/v1/world/cloud/traffic-globe', (r) => r.fulfill(json(traffic)));
+  await page.route('**/v1/world/cloud/traffic', (r) => r.fulfill(json(cloudMap.traffic)));
+  await page.route('**/v1/world/cloud/chain-nodes', (r) => r.fulfill(json(cloudMap.chainNodes)));
+  await page.route('**/v1/world/cloud/byo-gpu', (r) => r.fulfill(json(cloudMap.byoGpu)));
+}
+
+const layerIds = (page: import('@playwright/test').Page): Promise<string[]> =>
+  page.evaluate(() => {
+    const m = (window as unknown as { __deckMap?: { asGlobeSource: () => { buildLayers: () => DeckLayer[] } } }).__deckMap;
+    return (m?.asGlobeSource().buildLayers() ?? []).flat(Infinity).filter(Boolean).map((l: DeckLayer) => l.id);
+  });
+
+const go3D = async (page: import('@playwright/test').Page): Promise<void> => {
+  // Enter the 3D globe through the projection toggle's REAL click handler
+  // (proj-btn → setProjectionMode('3d') → activateNativeGlobe). The flagship Cloud
+  // view floats its control dock over the full-viewport globe canvas, so under
+  // headless swiftshader a synthesized mouse click's hit-test lands on the canvas,
+  // not the collapsed-dropdown button — dispatch the click on the element itself.
+  // This spec verifies the GLOBE render (occlusion/terrain/parity/live dots); the
+  // dock's pointer reachability is a separate controls concern, out of scope here.
+  await page.evaluate(() => {
+    const btn = document.querySelector('.deckgl-projection-toggle .proj-btn[data-mode="3d"]') as HTMLElement | null;
+    btn?.click();
+  });
+  await expect
+    .poll(() => page.evaluate(() => Boolean((window as unknown as { __globeNative?: unknown }).__globeNative)), { timeout: 25000 })
+    .toBe(true);
+  await page.waitForTimeout(1200); // let the first data-sync pull + push layers
+};
+
+test.describe('Globe render fixes — occlusion, terrain, 2D/3D parity, live dots', () => {
+  test.describe.configure({ retries: 1 });
+  test.use({ reducedMotion: 'reduce' });
+
+  // The cloud data layers that must exist on the Hanzo-Cloud globe once feeds resolve.
+  const CLOUD_LAYERS = ['traffic', 'trafficArcs', 'chainNodes', 'datacenter-clusters-layer'];
+
+  test('3D: cloud layers mount, live dots render on the sphere, no WebGL errors', async ({ page }, testInfo) => {
+    const errors: string[] = [];
+    const ignorable = [/could not compile fragment shader/i, /image.*could not be decoded/i, /the layer 'background'/i, /status of 40[13]/i];
+    page.on('console', (m) => { if (m.type() === 'error') errors.push(m.text()); });
+    page.on('pageerror', (e) => errors.push(e.message));
+
+    await mockCloud(page);
+    await page.goto(CLOUD_2D);
+    await expect(page.locator('.deckgl-map-wrapper')).toBeVisible({ timeout: 45000 });
+    await go3D(page);
+
+    // Single WebGL context for the globe (deck GlobeView, not a 2nd overlay canvas).
+    expect(await page.evaluate(() => document.querySelectorAll('.globe-native-canvas').length)).toBe(1);
+    await expect.poll(() => page.evaluate(() => (window as unknown as { __globeNative: { getViewportType: () => string | null } }).__globeNative.getViewportType())).toMatch(/Globe/i);
+
+    // Every cloud data layer is mounted.
+    const ids = await layerIds(page);
+    for (const id of CLOUD_LAYERS) expect(ids).toContain(id);
+
+    // The live request-geo dots are present with the real (mocked) point count.
+    const trafficCount = await page.evaluate(() => {
+      const m = (window as unknown as { __deckMap: { asGlobeSource: () => { buildLayers: () => DeckLayer[] } } }).__deckMap;
+      const t = m.asGlobeSource().buildLayers().flat(Infinity).find((l: DeckLayer) => l?.id === 'traffic');
+      return (t?.props?.data as unknown[])?.length ?? 0;
+    });
+    expect(trafficCount).toBe(cloudMap.trafficGlobe.points.length);
+
+    const shot = await page.locator('.globe-native-wrapper').screenshot();
+    await testInfo.attach('3d-globe-cloud-layers', { body: shot, contentType: 'image/png' });
+    expect(errors.filter((e) => !ignorable.some((p) => p.test(e)))).toEqual([]);
+  });
+
+  test('occlusion: a back-hemisphere dot is culled to transparent, a front dot is opaque', async ({ page }) => {
+    await mockCloud(page);
+    await page.goto(CLOUD_2D);
+    await expect(page.locator('.deckgl-map-wrapper')).toBeVisible({ timeout: 45000 });
+    await go3D(page);
+
+    // Face the camera at lon 0 (the FRONT point). Read the REAL traffic layer's fill
+    // accessor for each point: front → opaque (alpha>0), back (lon 180) → alpha 0.
+    const alphas = await page.evaluate(() => {
+      const m = (window as unknown as { __deckMap: { setOcclusionCenter: (lng: number, lat: number) => void; asGlobeSource: () => { buildLayers: () => DeckLayer[] } } }).__deckMap;
+      m.setOcclusionCenter(0, 20);
+      const t = m.asGlobeSource().buildLayers().flat(Infinity).find((l: DeckLayer) => l?.id === 'traffic') as DeckLayer;
+      const data = t.props.data as Array<{ lon: number }>;
+      const getFill = t.props.getFillColor as (d: unknown) => Rgba;
+      const front = getFill(data.find((d) => d.lon === 0));
+      const back = getFill(data.find((d) => d.lon === 180));
+      return { frontAlpha: front[3], backAlpha: back[3] };
+    });
+    expect(alphas.frontAlpha).toBeGreaterThan(0);
+    expect(alphas.backAlpha).toBe(0);
+  });
+
+  test('occlusion: a back-hemisphere count badge is culled (no floating badge over the globe)', async ({ page }) => {
+    await mockCloud(page);
+    await page.goto(CLOUD_2D);
+    await expect(page.locator('.deckgl-map-wrapper')).toBeVisible({ timeout: 45000 });
+    await go3D(page);
+
+    // datacenter count badges are a TextLayer; a back-side badge's glyph AND pill must
+    // both go transparent. Probe both hemispheres against a fixed camera centre.
+    const badge = await page.evaluate(() => {
+      const m = (window as unknown as { __deckMap: { setOcclusionCenter: (lng: number, lat: number) => void; asGlobeSource: () => { buildLayers: () => DeckLayer[] } } }).__deckMap;
+      m.setOcclusionCenter(0, 20);
+      const b = m.asGlobeSource().buildLayers().flat(Infinity).find((l: DeckLayer) => l?.id === 'datacenter-clusters-badge') as DeckLayer | undefined;
+      if (!b) return { skip: true };
+      const getColor = b.props.getColor as (d: unknown) => Rgba;
+      const getBg = b.props.getBackgroundColor as (d: unknown) => Rgba;
+      const front = { lon: 0, lat: 20, count: 5 };
+      const back = { lon: 180, lat: 20, count: 5 };
+      return { skip: false, frontText: getColor(front)[3], backText: getColor(back)[3], backBg: getBg(back)[3] };
+    });
+    if (badge.skip) test.skip(true, 'no datacenter badge in this build');
+    expect(badge.frontText).toBeGreaterThan(0);
+    expect(badge.backText).toBe(0);
+    expect(badge.backBg).toBe(0);
+  });
+
+  test('2D/3D parity: every cloud layer that mounts in 3D also mounts in 2D', async ({ page }, testInfo) => {
+    await mockCloud(page);
+    await page.goto(CLOUD_2D);
+    await expect(page.locator('.deckgl-map-wrapper')).toBeVisible({ timeout: 45000 });
+    await page.waitForTimeout(1500); // 2D feeds settle
+
+    const ids2d = await layerIds(page);
+    for (const id of CLOUD_LAYERS) expect(ids2d, `2D missing ${id}`).toContain(id);
+    await testInfo.attach('2d-map-cloud-layers', { body: await page.locator('.deckgl-map-wrapper').screenshot(), contentType: 'image/png' });
+
+    await go3D(page);
+    const ids3d = await layerIds(page);
+    for (const id of CLOUD_LAYERS) expect(ids3d, `3D missing ${id}`).toContain(id);
+    await testInfo.attach('3d-globe-cloud-layers-parity', { body: await page.locator('.globe-native-wrapper').screenshot(), contentType: 'image/png' });
+  });
+
+  test('terrain drapes on the globe in a single context (no second canvas)', async ({ page }, testInfo) => {
+    await mockCloud(page);
+    await page.goto(CLOUD_2D);
+    await expect(page.locator('.deckgl-map-wrapper')).toBeVisible({ timeout: 45000 });
+    await go3D(page);
+
+    await page.evaluate(() => (window as unknown as { __globeNative: { setBasemapStyle: (s: string) => void } }).__globeNative.setBasemapStyle('terrain'));
+    await expect
+      .poll(() => page.evaluate(() => (window as unknown as { __globeNative: { getDeck: () => { props: { layers: DeckLayer[] } } } }).__globeNative.getDeck().props.layers.flat(Infinity).some((l: DeckLayer) => l?.id?.startsWith('globe-imagery-terrain'))), { timeout: 20000 })
+      .toBe(true);
+    // Still exactly one canvas — imagery drapes as deck tiles, not a 2nd WebGL context.
+    expect(await page.evaluate(() => document.querySelectorAll('.globe-native-wrapper canvas').length)).toBe(1);
+    await page.waitForTimeout(2500);
+    await testInfo.attach('3d-terrain-globe', { body: await page.locator('.globe-native-wrapper').screenshot(), contentType: 'image/png' });
+  });
+
+  test('live dots update when the feed changes', async ({ page }) => {
+    await mockCloud(page, { ...cloudMap.trafficGlobe, points: cloudMap.trafficGlobe.points.slice(0, 1) });
+    await page.goto(CLOUD_2D);
+    await expect(page.locator('.deckgl-map-wrapper')).toBeVisible({ timeout: 45000 });
+    await go3D(page);
+
+    const count = () => page.evaluate(() => {
+      const m = (window as unknown as { __deckMap: { asGlobeSource: () => { buildLayers: () => DeckLayer[] } } }).__deckMap;
+      const t = m.asGlobeSource().buildLayers().flat(Infinity).find((l: DeckLayer) => l?.id === 'traffic');
+      return (t?.props?.data as unknown[])?.length ?? 0;
+    });
+    await expect.poll(count, { timeout: 15000 }).toBe(1);
+
+    // Swap the feed to the full 3-point payload; the DeckGLMap poll picks it up.
+    await mockCloud(page, cloudMap.trafficGlobe);
+    await expect.poll(count, { timeout: 20000 }).toBe(cloudMap.trafficGlobe.points.length);
+  });
+});

e2e/globe.spec.ts

@@ -0,0 +1,197 @@
+import { expect, test } from '@playwright/test';
+import { clickMapControl } from './helpers/map-controls';
+
+type LayerSnapshot = { id: string; dataCount: number };
+
+type Harness = {
+  ready: boolean;
+  seedAllDynamicData: () => void;
+  seedClimateAnomalies: () => void;
+  setZoom: (zoom: number) => void;
+  setProjectionMode: (mode: '2d' | '3d') => void;
+  getProjectionType: () => string;
+  getCenterLng: () => number | undefined;
+  isAutoRotateActive: () => boolean;
+  isUserInteracting: () => boolean;
+  autoRotateGateOpen: () => boolean;
+  rotateOneStep: (dtSec: number) => void;
+  stopIdleSpin: () => void;
+  getDeckLayerSnapshot: () => LayerSnapshot[];
+};
+
+type HarnessWindow = Window & { __mapHarness?: Harness };
+
+// One representative of every deck.gl layer type in use — each must still build
+// on the globe: PathLayer, GeoJsonLayer, IconLayer, ScatterplotLayer, Text.
+const GLOBE_SAFE_LAYERS = [
+  'cables-layer',            // PathLayer
+  'pipelines-layer',        // PathLayer
+  'conflict-zones-layer',   // GeoJsonLayer
+  'bases-layer',            // IconLayer
+  'nuclear-layer',          // IconLayer
+  'hotspots-layer',         // ScatterplotLayer
+  'datacenters-layer',      // IconLayer
+  'earthquakes-layer',      // ScatterplotLayer
+  'weather-layer',          // ScatterplotLayer
+  'military-flights-layer', // ScatterplotLayer
+  'ports-layer',            // ScatterplotLayer
+  'news-locations-layer',   // Text/Scatterplot
+];
+
+const waitForHarnessReady = async (
+  page: import('@playwright/test').Page
+): Promise<void> => {
+  await page.goto('/tests/map-harness.html');
+  await expect(page.locator('.deckgl-map-wrapper')).toBeVisible();
+  await expect
+    .poll(() => page.evaluate(() => Boolean((window as HarnessWindow).__mapHarness?.ready)), {
+      timeout: 45000,
+    })
+    .toBe(true);
+};
+
+const projectionType = (page: import('@playwright/test').Page): Promise<string> =>
+  page.evaluate(() => (window as HarnessWindow).__mapHarness?.getProjectionType() ?? 'mercator');
+
+const layerIds = async (page: import('@playwright/test').Page): Promise<Set<string>> => {
+  const snapshot = await page.evaluate(
+    () => (window as HarnessWindow).__mapHarness?.getDeckLayerSnapshot() ?? []
+  );
+  return new Set(snapshot.filter((l) => l.dataCount > 0).map((l) => l.id));
+};
+
+test.describe('3D globe', () => {
+  test.describe.configure({ retries: 1 });
+
+  // Runs FIRST and is deliberately light: the idle-spin rAF loop is engaged then
+  // cancelled in the same tick, so no sustained globe repaint occurs (a
+  // continuously repainting software-GL globe starves page.evaluate in CI). The
+  // rotation math and idle/interaction gate are exercised via discrete calls —
+  // setCenter mutates map state synchronously, independent of GL throughput.
+  test.describe('idle auto-rotate', () => {
+    test.use({ reducedMotion: 'no-preference' });
+
+    test('engages in 3D, rotates the globe, and its gate closes on interaction / in 2D', async ({
+      page,
+    }) => {
+      await waitForHarnessReady(page);
+
+      const engaged = await page.evaluate(() => {
+        const w = (window as HarnessWindow).__mapHarness!;
+        w.setZoom(1.6);
+        w.setProjectionMode('3d');
+        const active = w.isAutoRotateActive(); // rafId set synchronously
+        w.stopIdleSpin();                       // cancel before any sustained repaint
+        return { active, gate: w.autoRotateGateOpen() };
+      });
+      expect(engaged.active).toBe(true); // loop engaged in 3D
+      expect(engaged.gate).toBe(true);   // idle gate open
+
+      // One step (1s worth) rotates the globe eastward ~2 degrees (the calmer
+      // background drift — AUTO_ROTATE_DEG_PER_SEC was halved from 4 to 2).
+      const moved = await page.evaluate(() => {
+        const w = (window as HarnessWindow).__mapHarness!;
+        const before = w.getCenterLng() ?? 0;
+        w.rotateOneStep(1);
+        return Math.abs((w.getCenterLng() ?? 0) - before);
+      });
+      expect(moved).toBeGreaterThan(1);
+      expect(moved).toBeLessThan(3);
+
+      // A real pointer interaction closes the gate (spin pauses).
+      await page.evaluate(() =>
+        document.querySelector('.mapboxgl-canvas')?.dispatchEvent(
+          new MouseEvent('mousedown', { bubbles: true })
+        )
+      );
+      const afterInteract = await page.evaluate(() => {
+        const w = (window as HarnessWindow).__mapHarness!;
+        return { interacting: w.isUserInteracting(), gate: w.autoRotateGateOpen() };
+      });
+      expect(afterInteract.interacting).toBe(true);
+      expect(afterInteract.gate).toBe(false);
+
+      // Flat map never auto-rotates.
+      const flat = await page.evaluate(() => {
+        const w = (window as HarnessWindow).__mapHarness!;
+        w.setProjectionMode('2d');
+        return { active: w.isAutoRotateActive(), gate: w.autoRotateGateOpen() };
+      });
+      expect(flat.active).toBe(false);
+      expect(flat.gate).toBe(false);
+    });
+  });
+
+  // Runs LAST because rendering a full-layer globe under CI's software GL is the
+  // heaviest step. reducedMotion keeps auto-rotate off so there is no sustained
+  // repaint; every assertion is a pure buildLayers/getProjection state read plus
+  // real pill clicks. All static checks live in ONE page load to avoid repeated
+  // heavy globe initialisations.
+  test.describe('projection + layers (static)', () => {
+    test.use({ reducedMotion: 'reduce' });
+
+    test('2D<->3D toggle switches projection; every layer renders on the globe; heatmap is substituted; no deck errors', async ({
+      page,
+    }) => {
+      const pageErrors: string[] = [];
+      const deckAssertionErrors: string[] = [];
+      const ignorable = [/could not compile fragment shader/i];
+      page.on('pageerror', (e) => pageErrors.push(e.message));
+      page.on('console', (msg) => {
+        if (msg.type() === 'error' && msg.text().includes('deck.gl: assertion failed')) {
+          deckAssertionErrors.push(msg.text());
+        }
+      });
+
+      await waitForHarnessReady(page);
+      await page.evaluate(() => {
+        const w = (window as HarnessWindow).__mapHarness!;
+        w.seedAllDynamicData();
+        w.seedClimateAnomalies();
+        w.setZoom(5); // clears per-layer minZoom gates (bases/nuclear/datacenters)
+      });
+
+      // Flat map by default; climate uses the screen-space HeatmapLayer.
+      expect(await projectionType(page)).toBe('mercator');
+      await expect(page.locator('.deckgl-projection-toggle .proj-btn[data-mode="2d"]')).toHaveClass(/active/);
+      {
+        const ids = await layerIds(page);
+        expect(ids.has('climate-heatmap-layer')).toBe(true);
+        expect(ids.has('climate-anomaly-points-layer')).toBe(false);
+      }
+
+      // Click the real 3D pill in the map header.
+      await clickMapControl(page, '.deckgl-projection-toggle .proj-btn[data-mode="3d"]');
+      await expect.poll(() => projectionType(page), { timeout: 30000 }).toBe('globe');
+      await expect(page.locator('.deckgl-projection-toggle .proj-btn[data-mode="3d"]')).toHaveClass(/active/);
+
+      // Freeze the idle spin so the static layer checks don't run against a
+      // continuously repainting globe (a repainting software-GL globe starves
+      // page.evaluate in CI). reducedMotion disables it where the emulation is
+      // honored; this makes it deterministic everywhere.
+      await page.evaluate(() => (window as HarnessWindow).__mapHarness?.stopIdleSpin());
+
+      // Every representative deck.gl layer type still builds on the globe...
+      await expect
+        .poll(async () => {
+          const ids = await layerIds(page);
+          return GLOBE_SAFE_LAYERS.filter((id) => !ids.has(id)).length;
+        }, { timeout: 20000 })
+        .toBe(0);
+
+      // ...and the screen-space climate heatmap is swapped for a globe-safe scatter.
+      {
+        const ids = await layerIds(page);
+        expect(ids.has('climate-anomaly-points-layer')).toBe(true);
+        expect(ids.has('climate-heatmap-layer')).toBe(false);
+      }
+
+      // Flip back to the flat map.
+      await clickMapControl(page, '.deckgl-projection-toggle .proj-btn[data-mode="2d"]');
+      await expect.poll(() => projectionType(page), { timeout: 20000 }).toBe('mercator');
+
+      expect(pageErrors.filter((e) => !ignorable.some((p) => p.test(e)))).toEqual([]);
+      expect(deckAssertionErrors).toEqual([]);
+    });
+  });
+});

e2e/helpers/map-controls.ts

@@ -0,0 +1,18 @@
+import type { Page, Locator } from '@playwright/test';
+
+// The map's projection / basemap / time-range controls collapsed into dropdowns:
+// each option button (.proj-btn / .style-btn / .time-btn) lives in a popover that a
+// trigger opens. Tests that click an option must open its dropdown first. This helper
+// opens the button's parent .deckgl-dd (if it's in one) and clicks the option — a
+// no-op open when the button isn't inside a dropdown, so it's safe everywhere.
+export async function clickMapControl(page: Page, buttonSelector: string): Promise<void> {
+  const btn: Locator = page.locator(buttonSelector).first();
+  const dd = btn.locator('xpath=ancestor::div[contains(concat(" ", normalize-space(@class), " "), " deckgl-dd ")][1]');
+  if (await dd.count()) {
+    const trigger = dd.locator('.dd-trigger').first();
+    if (!(await dd.evaluate((el) => el.classList.contains('open')).catch(() => false))) {
+      await trigger.click();
+    }
+  }
+  await btn.click();
+}

e2e/immersive-screens.spec.ts

@@ -0,0 +1,111 @@
+import { expect, test, type Page } from '@playwright/test';
+import { mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { clickMapControl } from './helpers/map-controls';
+
+// Capture the CTO-facing proof screenshots for the layout/style batch. These drive
+// the REAL app (not a harness) so they show the shipped chrome + layout. They are
+// deliverables, not assertions — kept lenient so a flaky data feed never fails them.
+
+const OUT = join(process.cwd(), 'e2e', 'screens');
+mkdirSync(OUT, { recursive: true });
+const shot = (page: Page, name: string) => page.screenshot({ path: join(OUT, name), fullPage: false });
+
+async function boot(page: Page): Promise<void> {
+  await page.goto('/');
+  await expect(page.locator('#panelsGrid')).toBeVisible({ timeout: 60000 });
+  // The map + its chrome mount asynchronously; wait for the projection toggle.
+  await expect(page.locator('.deckgl-projection-toggle')).toBeVisible({ timeout: 60000 });
+  await page.waitForTimeout(1500); // let the first paint + a few panels settle
+}
+
+test.describe('layout/style batch — deliverable screenshots', () => {
+  test.describe.configure({ timeout: 120000 });
+
+  test('default panel sizes at 1440px', async ({ page }) => {
+    await page.setViewportSize({ width: 1440, height: 900 });
+    await boot(page);
+    // Panels should be ≥ 2 tracks wide (comfortable), not 160px slivers.
+    await shot(page, 'default-sizes-1440.png');
+  });
+
+  test('immersive 3D background + floating panels, then video background', async ({ page }) => {
+    await page.setViewportSize({ width: 1440, height: 900 });
+    await boot(page);
+
+    // Globe on.
+    await clickMapControl(page, '.deckgl-projection-toggle .proj-btn[data-mode="3d"]').catch(() => {});
+    await page.waitForTimeout(1200);
+
+    // Enter immersive.
+    await page.locator('#immersiveToggle').click();
+    await expect(page.locator('body')).toHaveClass(/immersive/);
+    await page.waitForTimeout(2000); // globe reprojects + panels restyle
+    await shot(page, 'immersive-3d-panels.png');
+
+    // Switch the background slot to the live video.
+    await page.locator('#immersiveBgSelect .ibg-btn[data-bg="video"]').click();
+    await expect(page.locator('body')).toHaveAttribute('data-immersive-bg', 'video');
+    await page.waitForTimeout(2500); // give the YouTube embed a chance to paint
+    await shot(page, 'immersive-video-bg.png');
+
+    // Collapse-to-edge affordance — the globe/video breathes.
+    await page.locator('#immersiveBgSelect .ibg-btn[data-bg="map"]').click();
+    await page.locator('#immersiveCollapse').click();
+    await expect(page.locator('body')).toHaveClass(/immersive-collapsed/);
+    await page.waitForTimeout(900);
+    await shot(page, 'immersive-collapsed.png');
+  });
+
+  test('basemap style switcher (dark / satellite / terrain)', async ({ page }) => {
+    await page.setViewportSize({ width: 1280, height: 800 });
+    await boot(page);
+    // The basemap control collapsed into a dropdown: assert its trigger, then open it.
+    await expect(page.locator('.deckgl-dd[data-dd="basemap"] .dd-trigger')).toBeVisible();
+    await page.locator('.deckgl-dd[data-dd="basemap"] .dd-trigger').click();
+    await expect(page.locator('.deckgl-style-switcher')).toBeVisible();
+    await shot(page, 'style-switcher-dark.png');
+
+    // Satellite + terrain need a Mapbox token (VITE_MAPBOX_TOKEN); the buttons are
+    // disabled without one. When a token is configured, actually switch and let the
+    // relief render before capturing. clickMapControl reopens the dropdown each time
+    // (picking an option closes it).
+    const sat = page.locator('.deckgl-style-switcher .style-btn[data-style="satellite"]');
+    if (!(await sat.isDisabled())) {
+      await clickMapControl(page, '.deckgl-style-switcher .style-btn[data-style="satellite"]');
+      await page.waitForTimeout(4000);
+      await shot(page, 'style-switcher-satellite.png');
+      await clickMapControl(page, '.deckgl-style-switcher .style-btn[data-style="terrain"]');
+      await page.waitForTimeout(4000);
+      await shot(page, 'style-switcher-terrain.png');
+    }
+  });
+
+  test('layers panel dragged + entries reordered', async ({ page }) => {
+    await page.setViewportSize({ width: 1280, height: 800 });
+    await boot(page);
+    const panel = page.locator('.deckgl-layer-toggles');
+    await expect(panel).toBeVisible();
+
+    // Drag the panel by its header grip to a new spot over the map.
+    const grip = panel.locator('.toggle-drag-grip');
+    const g = (await grip.boundingBox())!;
+    await page.mouse.move(g.x + g.width / 2, g.y + g.height / 2);
+    await page.mouse.down();
+    await page.mouse.move(g.x + 260, g.y + 120, { steps: 12 });
+    await page.mouse.up();
+
+    // Reorder: drag the first row's grip below the third row.
+    const rows = panel.locator('.layer-toggle');
+    const firstGrip = rows.nth(0).locator('.layer-reorder-grip');
+    const fg = (await firstGrip.boundingBox())!;
+    const third = (await rows.nth(2).boundingBox())!;
+    await page.mouse.move(fg.x + fg.width / 2, fg.y + fg.height / 2);
+    await page.mouse.down();
+    await page.mouse.move(fg.x, third.y + third.height, { steps: 14 });
+    await page.mouse.up();
+
+    await page.waitForTimeout(400);
+    await shot(page, 'layers-panel-dragged-reordered.png');
+  });
+});

e2e/panel-drag.spec.ts

@@ -0,0 +1,681 @@
+import { expect, test, type Page } from '@playwright/test';
+
+// Drives the real panel-drag module (pointer events, custom ghost, gap-opening
+// FLIP reflow, snapping resize) through the deterministic harness.
+
+const HARNESS = '/tests/panel-drag-harness.html';
+const LAYOUT_HARNESS = '/tests/layout-harness.html';
+// Screenshots land in a repo-relative artifacts dir (Playwright creates it).
+const SHOTS = 'e2e/layout-shots';
+
+interface PanelDragHarness {
+  ready: boolean;
+  reorderCount: number;
+  lastCommittedSpan: number | null;
+  order: () => string[];
+}
+
+interface Rect {
+  left: number;
+  top: number;
+  width: number;
+  height: number;
+}
+
+interface LayoutHarness {
+  ready: boolean;
+  mode: () => 'grid' | 'free';
+  setMode: (m: 'grid' | 'free') => void;
+  toggle: () => 'grid' | 'free';
+  cell: () => number;
+  setCell: (px: number) => void;
+  rect: (id: string) => Rect | null;
+  colStep: () => { step: number; cols: number; padL: number };
+  order: () => string[];
+  overlayVisible: () => boolean;
+  gridColumnOf: (id: string) => string;
+}
+
+declare global {
+  interface Window {
+    __panelDragHarness?: PanelDragHarness;
+    __layoutHarness?: LayoutHarness;
+  }
+}
+
+async function ready(page: Page): Promise<void> {
+  await page.goto(HARNESS);
+  await page.waitForFunction(() => window.__panelDragHarness?.ready === true);
+}
+
+async function order(page: Page): Promise<string[]> {
+  return page.evaluate(() => window.__panelDragHarness!.order());
+}
+
+test.describe('panel drag + resize', () => {
+  test('pointer drag reorders panels and fires onReorder', async ({ page }) => {
+    await ready(page);
+
+    const before = await order(page);
+    expect(before).toEqual(['p0', 'p1', 'p2', 'p3', 'p4', 'p5']);
+
+    const src = (await page.locator('[data-panel="p0"]').boundingBox())!;
+    const last = (await page.locator('[data-panel="p5"]').boundingBox())!;
+
+    // Grab p0 by its header, cross the 6px threshold, sweep to the right half of
+    // the last panel (→ drop after it), release.
+    await page.mouse.move(src.x + src.width / 2, src.y + 12);
+    await page.mouse.down();
+    await page.mouse.move(src.x + src.width / 2 + 24, src.y + 12, { steps: 4 });
+    await page.mouse.move(last.x + last.width * 0.8, last.y + last.height / 2, { steps: 16 });
+    await page.mouse.up();
+
+    const after = await order(page);
+    expect(after).not.toEqual(before);
+    expect(after[after.length - 1]).toBe('p0'); // p0 dropped at the end
+    expect(after[0]).toBe('p1');
+
+    const reorders = await page.evaluate(() => window.__panelDragHarness!.reorderCount);
+    expect(reorders).toBeGreaterThan(0);
+  });
+
+  test('a press without crossing the threshold does not reorder', async ({ page }) => {
+    await ready(page);
+
+    const before = await order(page);
+    const box = (await page.locator('[data-panel="p1"]').boundingBox())!;
+
+    await page.mouse.move(box.x + box.width / 2, box.y + 12);
+    await page.mouse.down();
+    await page.mouse.move(box.x + box.width / 2 + 3, box.y + 12); // under 6px threshold
+    await page.mouse.up();
+
+    expect(await order(page)).toEqual(before);
+    const reorders = await page.evaluate(() => window.__panelDragHarness!.reorderCount);
+    expect(reorders).toBe(0);
+  });
+
+  test('Escape cancels a drag and restores the original order', async ({ page }) => {
+    await ready(page);
+
+    const before = await order(page);
+    const src = (await page.locator('[data-panel="p0"]').boundingBox())!;
+    const mid = (await page.locator('[data-panel="p3"]').boundingBox())!;
+
+    await page.mouse.move(src.x + src.width / 2, src.y + 12);
+    await page.mouse.down();
+    await page.mouse.move(mid.x + mid.width / 2, mid.y + mid.height / 2, { steps: 12 });
+    await page.keyboard.press('Escape');
+    await page.mouse.up();
+
+    expect(await order(page)).toEqual(before);
+  });
+
+  test('resize handle snaps height to a grid row-span', async ({ page }) => {
+    await ready(page);
+
+    const p2 = page.locator('[data-panel="p2"]');
+    const handle = p2.locator('.panel-resize-handle');
+    const h = (await handle.boundingBox())!;
+
+    await page.mouse.move(h.x + h.width / 2, h.y + h.height / 2);
+    await page.mouse.down();
+    await page.mouse.move(h.x + h.width / 2, h.y + h.height / 2 + 230, { steps: 12 });
+    await page.mouse.up();
+
+    await expect(p2).toHaveClass(/span-2/);
+    const span = await page.evaluate(() => window.__panelDragHarness!.lastCommittedSpan);
+    expect(span).toBe(2);
+  });
+});
+
+// ── Layout engine: grid ⇄ free, corner resize, cell-size, overlay ──────────
+// Drives the real Panel grips + grid-config against the true main.css, at
+// 1440x900 (see playwright.layout.config.ts).
+
+const lh = async (page: Page): Promise<void> => {
+  await page.goto(LAYOUT_HARNESS);
+  await page.waitForFunction(() => window.__layoutHarness?.ready === true);
+  await page.waitForTimeout(60); // let the queued registerPanel microtasks settle
+};
+
+const rect = (page: Page, id: string): Promise<Rect> =>
+  page.evaluate((pid) => window.__layoutHarness!.rect(pid)!, id);
+
+const headerBox = async (page: Page, id: string) =>
+  (await page.locator(`[data-panel="${id}"] .panel-header`).first().boundingBox())!;
+
+test.describe('layout engine', () => {
+  // Gate viewport: 1440x900 (independent of the base config's default size).
+  test.use({ viewport: { width: 1440, height: 900 } });
+
+  test('grid mode: a dropped panel lands on a cell boundary', async ({ page }) => {
+    await lh(page);
+    expect(await page.evaluate(() => window.__layoutHarness!.mode())).toBe('grid');
+
+    const src = await headerBox(page, 'charlie');
+    const dst = (await page.locator('[data-panel="echo"]').boundingBox())!;
+
+    await page.mouse.move(src.x + 30, src.y + src.height / 2);
+    await page.mouse.down();
+    await page.mouse.move(src.x + 60, src.y + src.height / 2, { steps: 4 });
+    await page.mouse.move(dst.x + dst.width * 0.8, dst.y + dst.height / 2, { steps: 16 });
+    await page.mouse.up();
+
+    // Final resting position is snapped to a grid cell (multiple of the column step).
+    const { step, padL } = await page.evaluate(() => window.__layoutHarness!.colStep());
+    const r = await rect(page, 'charlie');
+    const k = Math.round((r.left - padL) / step);
+    expect(Math.abs(r.left - padL - k * step)).toBeLessThan(4);
+
+    await page.screenshot({ path: `${SHOTS}/grid-snap.png` });
+  });
+
+  test('grid mode: bottom-right corner resizes width + height (snapped)', async ({ page }) => {
+    await lh(page);
+    const corner = (await page
+      .locator('[data-panel="delta"] .panel-corner-resize-handle.se')
+      .boundingBox())!;
+    const { step } = await page.evaluate(() => window.__layoutHarness!.colStep());
+
+    await page.mouse.move(corner.x + corner.width / 2, corner.y + corner.height / 2);
+    await page.mouse.down();
+    // Pull out ~1.5 columns wide and ~250px tall.
+    await page.mouse.move(
+      corner.x + corner.width / 2 + step * 1.5,
+      corner.y + corner.height / 2 + 250,
+      { steps: 16 },
+    );
+    await page.mouse.up();
+
+    // Height grew (fine 16px row grid → a data-span well above the ~100px min) and
+    // width snapped to multiple columns. Resize lands on the fine grid, not the
+    // coarse span-N tier classes, so the panel carries `resized` + a data-span.
+    await expect(page.locator('[data-panel="delta"]')).toHaveClass(/resized/);
+    const span = await page.evaluate(() =>
+      parseInt(document.querySelector<HTMLElement>('[data-panel="delta"]')!.dataset.span ?? '0', 10),
+    );
+    expect(span).toBeGreaterThan(5); // taller than its start via the fine row grid
+    const gc = await page.evaluate(() => window.__layoutHarness!.gridColumnOf('delta'));
+    expect(gc).toMatch(/span [2-9]/);
+
+    await page.screenshot({ path: `${SHOTS}/resized-from-corner.png` });
+  });
+
+  test('grid mode: overlay appears only while dragging', async ({ page }) => {
+    await lh(page);
+    expect(await page.evaluate(() => window.__layoutHarness!.overlayVisible())).toBe(false);
+
+    const src = await headerBox(page, 'bravo');
+    await page.mouse.move(src.x + 30, src.y + src.height / 2);
+    await page.mouse.down();
+    await page.mouse.move(src.x + 120, src.y + 40, { steps: 8 });
+
+    // Mid-drag: the faint track overlay is shown.
+    await expect
+      .poll(() => page.evaluate(() => window.__layoutHarness!.overlayVisible()))
+      .toBe(true);
+    await page.screenshot({ path: `${SHOTS}/grid-overlay.png` });
+
+    await page.mouse.up();
+    await expect
+      .poll(() => page.evaluate(() => window.__layoutHarness!.overlayVisible()))
+      .toBe(false);
+  });
+
+  test('grid mode: changing cell size re-snaps the grid', async ({ page }) => {
+    await lh(page);
+    const before = await page.evaluate(() => window.__layoutHarness!.colStep());
+
+    await page.evaluate(() => window.__layoutHarness!.setCell(240));
+    await page.waitForTimeout(50);
+
+    const after = await page.evaluate(() => window.__layoutHarness!.colStep());
+    // Wider cells ⇒ fewer, wider columns: the panels re-snap to a new track grid.
+    expect(after.step).toBeGreaterThan(before.step + 20);
+    expect(after.cols).toBeLessThanOrEqual(before.cols);
+    expect(await page.evaluate(() => window.__layoutHarness!.cell())).toBe(240);
+  });
+
+  test('free mode: pixel drag + corner resize persist across reload', async ({ page }) => {
+    await lh(page);
+    await page.evaluate(() => window.__layoutHarness!.setMode('free'));
+    await page.waitForTimeout(40);
+    expect(await page.evaluate(() => window.__layoutHarness!.mode())).toBe('free');
+
+    // Hold Alt to bypass grid snapping — this test asserts that exact arbitrary-pixel
+    // geometry survives a reload (snapping has its own tests below).
+    await page.keyboard.down('Alt');
+    // Drag alpha by an arbitrary (non-cell) pixel delta.
+    const start = await rect(page, 'alpha');
+    const hdr = await headerBox(page, 'alpha');
+    const DX = 223;
+    const DY = -137;
+    await page.mouse.move(hdr.x + 30, hdr.y + hdr.height / 2);
+    await page.mouse.down();
+    await page.mouse.move(hdr.x + 40, hdr.y + hdr.height / 2, { steps: 3 });
+    await page.mouse.move(hdr.x + 30 + DX, hdr.y + hdr.height / 2 + DY, { steps: 16 });
+    await page.mouse.up();
+
+    const moved = await rect(page, 'alpha');
+    expect(Math.abs(moved.left - (start.left + DX))).toBeLessThan(6);
+    expect(Math.abs(moved.top - (start.top + DY))).toBeLessThan(6);
+    // Arbitrary pixel position — not snapped to a cell.
+    await page.screenshot({ path: `${SHOTS}/free-form.png` });
+
+    // Resize from the corner to an arbitrary size.
+    const corner = (await page
+      .locator('[data-panel="alpha"] .panel-corner-resize-handle.se')
+      .boundingBox())!;
+    const WD = 118;
+    const HD = 94;
+    await page.mouse.move(corner.x + corner.width / 2, corner.y + corner.height / 2);
+    await page.mouse.down();
+    await page.mouse.move(
+      corner.x + corner.width / 2 + WD,
+      corner.y + corner.height / 2 + HD,
+      { steps: 16 },
+    );
+    await page.mouse.up();
+
+    const resized = await rect(page, 'alpha');
+    expect(Math.abs(resized.width - (moved.width + WD))).toBeLessThan(6);
+    expect(Math.abs(resized.height - (moved.height + HD))).toBeLessThan(6);
+
+    await page.keyboard.up('Alt');
+    // Reload: the mode + exact geometry are restored.
+    await page.reload();
+    await page.waitForFunction(() => window.__layoutHarness?.ready === true);
+    await page.waitForTimeout(80);
+    expect(await page.evaluate(() => window.__layoutHarness!.mode())).toBe('free');
+    const restored = await rect(page, 'alpha');
+    expect(Math.abs(restored.left - resized.left)).toBeLessThan(3);
+    expect(Math.abs(restored.top - resized.top)).toBeLessThan(3);
+    expect(Math.abs(restored.width - resized.width)).toBeLessThan(3);
+    expect(Math.abs(restored.height - resized.height)).toBeLessThan(3);
+  });
+
+  test('free mode: all four corners resize and pin the opposite corner', async ({ page }) => {
+    await lh(page);
+    await page.evaluate(() => window.__layoutHarness!.setMode('free'));
+    await page.waitForTimeout(40);
+    expect(await page.evaluate(() => window.__layoutHarness!.mode())).toBe('free');
+
+    // Alt bypasses snapping so the shrink is exactly the drag delta; this test is
+    // about the anchor-pinning invariant, which holds with or without snapping.
+    await page.keyboard.down('Alt');
+    const D = 60; // drag each corner inward (toward the panel centre) — always in-bounds
+    // corner → inward drag sign + which opposite corner must stay pinned.
+    const cases = [
+      { panel: 'alpha', corner: 'nw', sx: 1, sy: 1, fix: 'br' },
+      { panel: 'bravo', corner: 'ne', sx: -1, sy: 1, fix: 'bl' },
+      { panel: 'charlie', corner: 'sw', sx: 1, sy: -1, fix: 'tr' },
+      { panel: 'delta', corner: 'se', sx: -1, sy: -1, fix: 'tl' },
+    ] as const;
+
+    for (const c of cases) {
+      const b = await rect(page, c.panel);
+      const h = (await page
+        .locator(`[data-panel="${c.panel}"] .panel-corner-resize-handle.${c.corner}`)
+        .boundingBox())!;
+      const px = h.x + h.width / 2;
+      const py = h.y + h.height / 2;
+      await page.mouse.move(px, py);
+      await page.mouse.down();
+      await page.mouse.move(px + c.sx * D, py + c.sy * D, { steps: 12 });
+      await page.mouse.up();
+      const a = await rect(page, c.panel);
+
+      // The grabbed corner pulled inward on both axes → the panel shrank.
+      expect(a.width).toBeLessThan(b.width - 20);
+      expect(a.height).toBeLessThan(b.height - 20);
+
+      // The OPPOSITE corner never moved — proof the resize is anchor-aware
+      // (nw/ne/sw shift left/top to hold the far edge, not just grow w/h).
+      const bR = b.left + b.width;
+      const bB = b.top + b.height;
+      const aR = a.left + a.width;
+      const aB = a.top + a.height;
+      if (c.fix === 'br') {
+        expect(Math.abs(aR - bR)).toBeLessThan(4);
+        expect(Math.abs(aB - bB)).toBeLessThan(4);
+      } else if (c.fix === 'bl') {
+        expect(Math.abs(a.left - b.left)).toBeLessThan(4);
+        expect(Math.abs(aB - bB)).toBeLessThan(4);
+      } else if (c.fix === 'tr') {
+        expect(Math.abs(aR - bR)).toBeLessThan(4);
+        expect(Math.abs(a.top - b.top)).toBeLessThan(4);
+      } else {
+        expect(Math.abs(a.left - b.left)).toBeLessThan(4);
+        expect(Math.abs(a.top - b.top)).toBeLessThan(4);
+      }
+    }
+    await page.keyboard.up('Alt');
+    await page.screenshot({ path: `${SHOTS}/free-all-corners.png` });
+  });
+
+  test('free mode: moving one panel never shifts its siblings (no reflow)', async ({ page }) => {
+    // The owner's #1 complaint: dragging the map/one panel "shifts all other
+    // components". In free mode each panel is independent — this proves a big drag
+    // of one leaves every sibling byte-for-byte where it was.
+    await lh(page);
+    await page.evaluate(() => window.__layoutHarness!.setMode('free'));
+    await page.waitForTimeout(40);
+
+    const siblings = ['bravo', 'charlie', 'delta', 'echo'] as const;
+    const before: Record<string, Rect> = {};
+    for (const id of siblings) before[id] = await rect(page, id);
+
+    const hdr = await headerBox(page, 'alpha');
+    await page.mouse.move(hdr.x + 30, hdr.y + hdr.height / 2);
+    await page.mouse.down();
+    await page.mouse.move(hdr.x + 40, hdr.y + hdr.height / 2, { steps: 3 });
+    await page.mouse.move(hdr.x + 300, hdr.y + hdr.height / 2 + 200, { steps: 18 });
+    await page.mouse.up();
+
+    for (const id of siblings) {
+      const a = await rect(page, id);
+      const b = before[id]!;
+      expect(Math.abs(a.left - b.left)).toBeLessThan(2);
+      expect(Math.abs(a.top - b.top)).toBeLessThan(2);
+      expect(Math.abs(a.width - b.width)).toBeLessThan(2);
+      expect(Math.abs(a.height - b.height)).toBeLessThan(2);
+    }
+  });
+
+  test('free mode: a panel resizes narrower than the old 160px min width', async ({ page }) => {
+    // The owner's #3 complaint: panels are "constrained on min width". Free mode's
+    // floor is now ~96px, so a panel can be pulled well under the old 160px track.
+    await lh(page);
+    await page.evaluate(() => window.__layoutHarness!.setMode('free'));
+    await page.waitForTimeout(40);
+
+    const before = await rect(page, 'bravo');
+    const corner = (await page
+      .locator('[data-panel="bravo"] .panel-corner-resize-handle.se')
+      .boundingBox())!;
+    // Pull the SE corner far left → collapse width toward the low floor. Hold Alt for
+    // fine (un-snapped) sizing — snapping would otherwise land on a whole cell (≥160).
+    await page.keyboard.down('Alt');
+    await page.mouse.move(corner.x + corner.width / 2, corner.y + corner.height / 2);
+    await page.mouse.down();
+    await page.mouse.move(corner.x - before.width, corner.y + corner.height / 2, { steps: 18 });
+    await page.mouse.up();
+    await page.keyboard.up('Alt');
+
+    const after = await rect(page, 'bravo');
+    expect(after.width).toBeLessThan(150); // narrower than the old 160px floor
+    expect(after.width).toBeGreaterThanOrEqual(90); // …but not past the new ~96px floor
+  });
+
+  test('free mode: the map participates with a 240px floor', async ({ page }) => {
+    await lh(page);
+    await page.evaluate(() => window.__layoutHarness!.setMode('free'));
+    await page.waitForTimeout(40);
+    const pos = await page.evaluate(
+      () => getComputedStyle(document.querySelector('[data-panel="map"]')!).position,
+    );
+    expect(pos).toBe('absolute');
+    const r = await rect(page, 'map');
+    expect(r.width).toBeGreaterThanOrEqual(240);
+    expect(r.height).toBeGreaterThanOrEqual(240);
+  });
+
+  test('free mode: dragging snaps to logical grid lines (panels align to shared tracks)', async ({ page }) => {
+    // The owner's feedback: "the snap is not logical." Two panels dragged to targets
+    // less than half a cell apart must land on the SAME grid line — proof placement is
+    // quantised to the logical grid, not arbitrary px.
+    await lh(page);
+    await page.evaluate(() => window.__layoutHarness!.setMode('free'));
+    await page.waitForTimeout(40);
+    const cell = await page.evaluate(() => window.__layoutHarness!.cell());
+    const colPitch = cell + 4; // + gap
+    const rowPitch = 16 + 4; // ROW_UNIT + gap
+
+    const dragTo = async (id: string, x: number, y: number) => {
+      const hdr = await headerBox(page, id);
+      await page.mouse.move(hdr.x + 20, hdr.y + hdr.height / 2);
+      await page.mouse.down();
+      await page.mouse.move(hdr.x + 30, hdr.y + hdr.height / 2, { steps: 3 });
+      await page.mouse.move(x, y, { steps: 16 });
+      await page.mouse.up();
+    };
+
+    const gridBox = (await page.locator('#panelsGrid').boundingBox())!;
+    const tx = gridBox.x + colPitch * 2 + 20;
+    const ty = gridBox.y + rowPitch * 8 + 30;
+    await dragTo('alpha', tx, ty);
+    await dragTo('bravo', tx + 30, ty + 8); // < half a cell/row from alpha's target
+
+    const a = await rect(page, 'alpha');
+    const b = await rect(page, 'bravo');
+    // Both snapped to the SAME grid line instead of sitting 30/8px apart.
+    expect(Math.abs(a.left - b.left)).toBeLessThanOrEqual(1);
+    expect(Math.abs(a.top - b.top)).toBeLessThanOrEqual(1);
+  });
+
+  test('free mode: resizing snaps width to whole cells and pins the opposite edge', async ({ page }) => {
+    await lh(page);
+    await page.evaluate(() => window.__layoutHarness!.setMode('free'));
+    await page.waitForTimeout(40);
+    const cell = await page.evaluate(() => window.__layoutHarness!.cell());
+    const GAP = 4;
+
+    const before = await rect(page, 'alpha');
+    const corner = (await page
+      .locator('[data-panel="alpha"] .panel-corner-resize-handle.se')
+      .boundingBox())!;
+    // Pull the SE corner out by a non-cell amount; width must land on a whole-cell size.
+    await page.mouse.move(corner.x + corner.width / 2, corner.y + corner.height / 2);
+    await page.mouse.down();
+    await page.mouse.move(corner.x + corner.width / 2 + 210, corner.y + corner.height / 2, { steps: 16 });
+    await page.mouse.up();
+
+    const after = await rect(page, 'alpha');
+    // width == N*cell + (N-1)*gap for some integer N ≥ 1.
+    const n = Math.round((after.width + GAP) / (cell + GAP));
+    expect(n).toBeGreaterThanOrEqual(1);
+    expect(Math.abs(after.width - (n * cell + (n - 1) * GAP))).toBeLessThanOrEqual(2);
+    // The SE resize pins the top-left corner — it must not have moved.
+    expect(Math.abs(after.left - before.left)).toBeLessThanOrEqual(1);
+    expect(Math.abs(after.top - before.top)).toBeLessThanOrEqual(1);
+  });
+
+  test('resize handles show no visible glyphs (owner request) but still resize', async ({ page }) => {
+    await lh(page);
+    await page.evaluate(() => window.__layoutHarness!.setMode('free'));
+    await page.waitForTimeout(40);
+    // The corner/edge resize glyphs are hidden (display:none on the ::after marks) —
+    // no visible "< >" chevrons — while the handles stay live.
+    const displays = await page.evaluate(() => {
+      const d = (sel: string) => {
+        const el = document.querySelector(sel);
+        return el ? getComputedStyle(el, '::after').display : 'missing';
+      };
+      return {
+        corner: d('[data-panel="alpha"] .panel-corner-resize-handle.se'),
+        col: d('[data-panel="alpha"] .panel-col-resize-handle'),
+        row: d('[data-panel="alpha"] .panel-resize-handle'),
+      };
+    });
+    expect(displays.corner).toBe('none');
+    expect(displays.col).toBe('none');
+    expect(displays.row).toBe('none');
+    // Functionality intact: the (now glyph-less) SE corner still resizes.
+    const before = await rect(page, 'alpha');
+    const corner = (await page.locator('[data-panel="alpha"] .panel-corner-resize-handle.se').boundingBox())!;
+    await page.mouse.move(corner.x + corner.width / 2, corner.y + corner.height / 2);
+    await page.mouse.down();
+    await page.mouse.move(corner.x + 180, corner.y + 120, { steps: 12 });
+    await page.mouse.up();
+    expect((await rect(page, 'alpha')).width).toBeGreaterThan(before.width + 40);
+  });
+
+  test('cell size can go down to the finer 80px floor', async ({ page }) => {
+    await lh(page);
+    await page.evaluate(() => window.__layoutHarness!.setCell(80));
+    await page.waitForTimeout(30);
+    expect(await page.evaluate(() => window.__layoutHarness!.cell())).toBe(80);
+    // Clamped: a request below the floor snaps back up to 80, never lower.
+    await page.evaluate(() => window.__layoutHarness!.setCell(40));
+    await page.waitForTimeout(30);
+    expect(await page.evaluate(() => window.__layoutHarness!.cell())).toBe(80);
+  });
+
+  test('toggle flips grid ⇄ free and back', async ({ page }) => {
+    await lh(page);
+    expect(await page.evaluate(() => window.__layoutHarness!.toggle())).toBe('free');
+    expect(await page.evaluate(() => window.__layoutHarness!.mode())).toBe('free');
+    expect(await page.evaluate(() => window.__layoutHarness!.toggle())).toBe('grid');
+    // Back in grid mode the free inline geometry is stripped.
+    const pos = await page.evaluate(
+      () => document.querySelector<HTMLElement>('[data-panel="alpha"]')!.style.position,
+    );
+    expect(pos).toBe('');
+  });
+});
+
+// ── Live News (video) resizes freely; the video fills the panel at any size ──
+// Real app: proves the CTO requirement — Live News can grow to 2-3 cols / full
+// width (grid) or any pixel size (free), and the 16:9 video (`.live-news-player`,
+// width-driven) scales to fill, never capped small. NOTE: in the offline e2e
+// runtime the YouTube embed eventually errors and replaces `.live-news-player`
+// with a message, so the video-fill invariant is asserted where it's reliably
+// present (default size) and the resize is proved via the player's containing
+// block (`.panel-content`, always present), which the player fills 1:1.
+
+const rectW = (page: Page, sel: string): Promise<number> =>
+  page.evaluate((s) => {
+    const el = document.querySelector<HTMLElement>(s);
+    return el ? Math.round(el.getBoundingClientRect().width) : -1;
+  }, sel);
+
+const LN = '[data-panel="live-news"]';
+const LN_CONTENT = `${LN} .panel-content`;
+const LN_PLAYER = `${LN} .live-news-player`;
+
+test.describe('live news video resize (real app)', () => {
+  test.use({ viewport: { width: 1440, height: 900 } });
+
+  test('grid: default → 3 cols → full-width; the video fills at every width', async ({ page }) => {
+    await page.goto('/');
+    await page.waitForSelector(LN, { timeout: 45000 });
+    await page.waitForTimeout(500);
+    // The app defaults to free layout now; this test asserts GRID column-span
+    // semantics, so pin grid explicitly (setLayoutMode marks it an explicit choice
+    // so the deferred default-to-free won't re-flip it).
+    await page.evaluate(() => (window as unknown as { worldGrid?: { setLayoutMode(m: string): void } }).worldGrid?.setLayoutMode('grid'));
+    await page.waitForTimeout(80);
+
+    const grid = (await page.locator('#panelsGrid').boundingBox())!;
+    const ln = page.locator(LN);
+    const colHandle = ln.locator('.panel-col-resize-handle');
+
+    // The fill setup is active: the panel-content is a full-bleed flex column
+    // (padding 0) so the width-driven 16:9 `.live-news-player` fills it edge-to-edge
+    // at any width. (Keyed on #live-news — dead until the id fix in LiveNewsPanel.)
+    const setup = await page.evaluate((sel) => {
+      const c = document.querySelector<HTMLElement>(sel);
+      if (!c) return null;
+      const s = getComputedStyle(c);
+      return { display: s.display, dir: s.flexDirection, padLeft: s.paddingLeft };
+    }, LN_CONTENT);
+    expect(setup).toEqual({ display: 'flex', dir: 'column', padLeft: '0px' });
+
+    // The video, while present (offline embed errors after a beat), fills the
+    // container 1:1 at the default width.
+    const startContent = await rectW(page, LN_CONTENT);
+    const startVideo = await rectW(page, LN_PLAYER);
+    if (startVideo > 0) expect(Math.abs(startVideo - startContent)).toBeLessThan(4);
+
+    // Drag the right edge out to ~3 columns.
+    const h1 = (await colHandle.boundingBox())!;
+    await page.mouse.move(h1.x + h1.width / 2, h1.y + h1.height / 2);
+    await page.mouse.down();
+    await page.mouse.move(grid.x + grid.width * 0.42, h1.y + h1.height / 2, { steps: 14 });
+    await page.mouse.up();
+    await page.waitForTimeout(200);
+    const midContent = await rectW(page, LN_CONTENT);
+    expect(midContent).toBeGreaterThan(startContent + 40); // genuinely wider
+
+    // Drag the right edge all the way out → full width. No column cap.
+    const h2 = (await colHandle.boundingBox())!;
+    await page.mouse.move(h2.x + h2.width / 2, h2.y + h2.height / 2);
+    await page.mouse.down();
+    await page.mouse.move(grid.x + grid.width + 200, h2.y + h2.height / 2, { steps: 16 });
+    await page.mouse.up();
+    await page.waitForTimeout(200);
+    const fullContent = await rectW(page, LN_CONTENT);
+    expect(fullContent).toBeGreaterThan(midContent);
+    expect(fullContent).toBeGreaterThan(grid.width * 0.9); // ~full grid width
+    // The video (when present) fills the now-full-width container 1:1.
+    const fullVideo = await rectW(page, LN_PLAYER);
+    if (fullVideo > 0) expect(Math.abs(fullVideo - fullContent)).toBeLessThan(6);
+
+    // Make it tall too (drag the bottom edge down) so the 16:9 video is large.
+    const bottom = ln.locator('.panel-resize-handle');
+    const b = (await bottom.boundingBox())!;
+    await page.mouse.move(b.x + b.width / 2, b.y + b.height / 2);
+    await page.mouse.down();
+    await page.mouse.move(b.x + b.width / 2, b.y + 520, { steps: 16 });
+    await page.mouse.up();
+    await page.waitForTimeout(250);
+    await page.evaluate(() => document.querySelector('[data-panel="live-news"]')?.scrollIntoView({ block: 'start' }));
+    await page.waitForTimeout(150);
+    await page.screenshot({ path: 'e2e/layout-shots/live-news-fullwidth.png' });
+
+    // Container is now full-width AND tall → a large video area.
+    expect(await rectW(page, LN_CONTENT)).toBeGreaterThan(900);
+  });
+
+  test('free: Live News resizes to an arbitrary pixel size; video fills', async ({ page }) => {
+    await page.goto('/');
+    await page.waitForSelector(LN_PLAYER, { timeout: 45000 });
+    await page.waitForTimeout(600);
+    const startContent = await rectW(page, LN_CONTENT);
+    await page.evaluate(() => (window as unknown as { worldGrid?: { setLayoutMode(m: string): void } }).worldGrid?.setLayoutMode('free'));
+    await page.waitForTimeout(200);
+
+    const corner = page.locator(`${LN} .panel-corner-resize-handle.se`);
+    const c = (await corner.boundingBox())!;
+    await page.mouse.move(c.x + c.width / 2, c.y + c.height / 2);
+    await page.mouse.down();
+    await page.mouse.move(c.x + 240, c.y + 260, { steps: 18 });
+    await page.mouse.up();
+    await page.waitForTimeout(200);
+
+    const content = await rectW(page, LN_CONTENT);
+    expect(content).toBeGreaterThan(startContent + 120); // grew to an arbitrary pixel width
+    const video = await rectW(page, LN_PLAYER);
+    if (video > 0) expect(Math.abs(video - content)).toBeLessThan(6); // fills at that size
+    await page.evaluate(() => (window as unknown as { worldGrid?: { setLayoutMode(m: string): void } }).worldGrid?.setLayoutMode('grid'));
+  });
+});
+
+// Text size / UI scale (accessibility) — real app.
+test.describe('text size control (real app)', () => {
+  test.use({ viewport: { width: 1440, height: 900 } });
+  test('the dock text-size slider scales panel content and persists across reload', async ({ page }) => {
+    await page.goto('/');
+    await page.waitForSelector('[data-panel="live-news"]', { timeout: 45000 });
+    // Drive the dock "Text size" slider to 1.4.
+    await page.evaluate(() => {
+      const el = document.getElementById('dockFontSize') as HTMLInputElement;
+      el.value = '1.4';
+      el.dispatchEvent(new Event('input', { bubbles: true }));
+    });
+    await expect
+      .poll(() => page.evaluate(() => getComputedStyle(document.documentElement).getPropertyValue('--ui-scale').trim()))
+      .toBe('1.4');
+    expect(await page.evaluate(() => localStorage.getItem('hanzo-world-ui-scale'))).toBe('1.4');
+    const zoom = await page.evaluate(() => {
+      const c = document.querySelector('.panel-content');
+      return c ? getComputedStyle(c).zoom : '';
+    });
+    expect(parseFloat(zoom)).toBeCloseTo(1.4, 1);
+    // Persists across reload (applyStoredUiScale runs at boot).
+    await page.reload();
+    await page.waitForSelector('[data-panel="live-news"]', { timeout: 45000 });
+    expect(await page.evaluate(() => getComputedStyle(document.documentElement).getPropertyValue('--ui-scale').trim())).toBe('1.4');
+  });
+});

e2e/ui-polish.spec.ts

@@ -0,0 +1,150 @@
+import { expect, test, type Page, type Route } from '@playwright/test';
+
+/**
+ * UI/UX polish e2e — the four changes shipped together, each asserted against
+ * the real DOM/CSS rather than by eye:
+ *
+ *   1. Right-click a headline → "Summarize with AI" is the FIRST item, and it
+ *      opens the analyst dock with the story as the question.
+ *   2. The app header carries no underline (border-bottom).
+ *   3. The map's drag pill is gone, but the grip strip is still the drag target.
+ *   4. "Try Hanzo" is an acquisition CTA: visible signed-out, hidden once
+ *      identity resolves as signed-in.
+ */
+
+const SCREENS = 'e2e/screens';
+
+async function stubWorldApi(page: Page): Promise<void> {
+  await page.route('**/v1/world/**', (route: Route) => {
+    const url = route.request().url();
+    if (url.includes('/v1/world/analyst')) {
+      return route.fulfill({
+        status: 200,
+        contentType: 'application/json',
+        body: JSON.stringify({
+          reply: 'Stubbed summary.',
+          actions: [],
+          model: 'zen5',
+          tokens: 0,
+          traces: [],
+        }),
+      });
+    }
+    if (url.includes('/v1/world/models')) {
+      return route.fulfill({
+        status: 200,
+        contentType: 'application/json',
+        body: JSON.stringify({ models: [{ id: 'zen5', name: 'Zen 5' }], default: 'zen5' }),
+      });
+    }
+    return route.fulfill({ status: 200, contentType: 'application/json', body: '[]' });
+  });
+}
+
+/** Sign in the way the analyst e2e does — the analyst only accepts a question
+ *  when identity is present, so the summarize path needs a signed-in session. */
+async function signIn(page: Page): Promise<void> {
+  await page.addInitScript(() => {
+    localStorage.setItem('hanzo_iam_access_token', 'e2e-fake-token');
+    localStorage.setItem('hanzo_iam_expires_at', String(Date.now() + 3_600_000));
+    localStorage.setItem('hanzo_iam_owner', 'e2e-org');
+  });
+}
+
+async function appReady(page: Page): Promise<void> {
+  await page.goto('/');
+  await page.waitForSelector('.panel', { timeout: 30_000 });
+}
+
+/** Inject a news-shaped item — the exact data-ctx-* convention NewsPanel emits. */
+async function addNewsItem(page: Page): Promise<void> {
+  await page.evaluate(() => {
+    const grid = document.querySelector('#panelsGrid')!;
+    const panel = document.createElement('div');
+    panel.className = 'panel';
+    panel.dataset.panel = 'e2e-ui-panel';
+    panel.innerHTML =
+      '<div class="panel-content"><div class="item" id="e2e-news-item" ' +
+      'data-ctx-url="https://example.com/story" data-ctx-headline="Nvidia unveils new GPU" ' +
+      'style="padding:12px;min-height:24px;">Nvidia unveils new GPU</div></div>';
+    grid.appendChild(panel);
+  });
+}
+
+test.describe('ui polish', () => {
+  test('headline right-click leads with "Summarize with AI" and opens the analyst', async ({ page }) => {
+    await stubWorldApi(page);
+    await signIn(page); // the analyst answers only for a signed-in identity
+    await appReady(page);
+    await addNewsItem(page);
+
+    await page.locator('#e2e-news-item').scrollIntoViewIfNeeded();
+    await page.locator('#e2e-news-item').click({ button: 'right' });
+    await expect(page.locator('#panelContextMenu')).toBeVisible();
+
+    const labels = await page
+      .locator('#panelContextMenu .panel-context-menu-item')
+      .allTextContents();
+    const trimmed = labels.map((l) => l.trim());
+    // It is the action you want on a headline → it leads the menu.
+    expect(trimmed[0]).toBe('Summarize with AI');
+    // The copy/open actions are still there, below it.
+    expect(trimmed).toEqual(expect.arrayContaining(['Open link', 'Copy link', 'Copy headline']));
+
+    await page.screenshot({ path: `${SCREENS}/ctxmenu-summarize.png` });
+
+    // Clicking it routes into the ONE analyst dock, pre-asked with the story.
+    await page
+      .locator('#panelContextMenu .panel-context-menu-item', { hasText: 'Summarize with AI' })
+      .click();
+    // .hzc is a 0x0 wrapper (children are position:fixed) — the panel is the
+    // surface that actually opens.
+    await expect(page.locator('.hzc-panel')).toBeVisible();
+    // The question carries the headline (the analyst is asked, not just opened).
+    await expect(page.locator('.hzc-row.user').first()).toContainText('Nvidia unveils new GPU');
+  });
+
+  test('app header has no underline', async ({ page }) => {
+    await stubWorldApi(page);
+    await appReady(page);
+    const borderBottom = await page
+      .locator('.header')
+      .first()
+      .evaluate((el) => getComputedStyle(el).borderBottomWidth);
+    expect(borderBottom).toBe('0px');
+  });
+
+  test('map shows no drag pill, but the grip strip still drags', async ({ page }) => {
+    await stubWorldApi(page);
+    await appReady(page);
+    const grip = page.locator('.map-panel .panel-header.map-drag-grip');
+    await expect(grip).toHaveCount(1);
+
+    // No visible indicator …
+    const pill = await grip.evaluate((el) => getComputedStyle(el, '::after').content);
+    expect(pill === 'none' || pill === 'normal').toBe(true);
+
+    // … but it is still the drag target (that is what makes hiding it safe).
+    await expect(grip).toHaveCSS('cursor', 'grab');
+  });
+
+  test('"Try Hanzo" hides once signed in', async ({ page }) => {
+    await stubWorldApi(page);
+    await appReady(page);
+
+    const cta = page.locator('.try-hanzo');
+    await expect(cta).toBeVisible(); // signed-out: the CTA is the point
+
+    // The one signal identity resolution emits.
+    await page.evaluate(() => {
+      document.dispatchEvent(new CustomEvent('hanzo:auth', { detail: { authed: true } }));
+    });
+    await expect(cta).toBeHidden();
+
+    // And it comes back on sign-out.
+    await page.evaluate(() => {
+      document.dispatchEvent(new CustomEvent('hanzo:auth', { detail: { authed: false } }));
+    });
+    await expect(cta).toBeVisible();
+  });
+});

e2e/video-drag-reset.spec.ts

@@ -0,0 +1,144 @@
+import { expect, test, type Page } from '@playwright/test';
+
+// Drives the REAL app module graph (via the vite dev server) to prove, on the
+// live dashboard, that:
+//   1. the live-news VIDEO panel is grabbable by its header and drags even
+//      though it hosts a YouTube iframe (iframes go pointer-events:none while a
+//      drag is in flight, so drop hit-testing stays accurate);
+//   2. a normal content panel can be reordered and the new order sticks;
+//   3. the bottom resize handle snaps a panel to a taller row-span;
+//   4. the Panels-menu "Reset layout" control returns the grid to its default.
+//
+// Complements panel-drag.spec.ts (which unit-tests the drag module in isolation).
+
+async function appReady(page: Page): Promise<void> {
+  await page.goto('/?variant=full');
+  await page.waitForSelector('#panelsGrid .panel[data-panel="live-news"]', { timeout: 45000 });
+  await page.waitForFunction(
+    () => document.querySelectorAll('#panelsGrid .panel').length > 4,
+    undefined,
+    { timeout: 45000 },
+  );
+  // The app now DEFAULTS to free layout (independent, non-reflowing panels). These
+  // specs exercise the GRID reorder/ghost/row-span/reset machinery specifically, so
+  // pin grid mode (still a first-class, dropdown-selectable mode). setLayoutMode
+  // marks the choice explicit, so the deferred default-to-free never re-flips it.
+  await page.evaluate(() =>
+    (window as unknown as { worldGrid?: { setLayoutMode(m: string): void } }).worldGrid?.setLayoutMode('grid'),
+  );
+  await page.waitForTimeout(80);
+}
+
+function gridOrder(page: Page): Promise<(string | undefined)[]> {
+  return page.evaluate(() =>
+    Array.from(document.querySelectorAll('#panelsGrid .panel')).map(
+      (p) => (p as HTMLElement).dataset.panel,
+    ),
+  );
+}
+
+test.describe('video panel drag + reset (live app)', () => {
+  test('the live-news video panel is grabbable by its header and its iframe yields during drag', async ({ page }) => {
+    await appReady(page);
+
+    const header = page.locator('#panelsGrid .panel[data-panel="live-news"] .panel-header').first();
+    const hb = (await header.boundingBox())!;
+
+    // Grab the header away from its buttons, cross the 6px press threshold, and
+    // sweep down into the grid.
+    await page.mouse.move(hb.x + 50, hb.y + hb.height / 2);
+    await page.mouse.down();
+    await page.mouse.move(hb.x + 70, hb.y + hb.height / 2 + 30, { steps: 6 });
+    await page.mouse.move(hb.x + 90, hb.y + hb.height / 2 + 220, { steps: 12 });
+
+    // Mid-drag invariants: a ghost exists, the body is flagged, and any iframe is
+    // pointer-events:none so it can't swallow the drop hit-test.
+    expect(await page.locator('.panel-drag-ghost').count()).toBeGreaterThan(0);
+    expect(await page.evaluate(() => document.body.classList.contains('panel-drag-active'))).toBe(true);
+    const iframePE = await page.evaluate(() => {
+      const f = document.querySelector('#panelsGrid .panel[data-panel="live-news"] iframe') as HTMLElement | null;
+      return f ? getComputedStyle(f).pointerEvents : 'none-or-absent';
+    });
+    expect(['none', 'none-or-absent']).toContain(iframePE);
+
+    await page.mouse.up();
+    // Ghost is cleaned up after release.
+    await expect(page.locator('.panel-drag-ghost')).toHaveCount(0);
+  });
+
+  test('a content panel can be dragged to a new slot and the order changes', async ({ page }) => {
+    await appReady(page);
+    const before = await gridOrder(page);
+
+    // Pick a mid-grid draggable content panel (not live-news, which is pinned).
+    const movable = before.find((k) => k && k !== 'live-news' && k !== 'map')!;
+    const src = page.locator(`#panelsGrid .panel[data-panel="${movable}"]`);
+    const sb = (await src.locator('.panel-header').first().boundingBox())!;
+    const grid = (await page.locator('#panelsGrid').boundingBox())!;
+
+    await page.mouse.move(sb.x + 40, sb.y + sb.height / 2);
+    await page.mouse.down();
+    await page.mouse.move(sb.x + 60, sb.y + sb.height / 2 + 20, { steps: 6 });
+    // Sweep to the bottom of the grid → drop near the end.
+    await page.mouse.move(grid.x + grid.width * 0.5, grid.y + grid.height - 30, { steps: 18 });
+    await page.mouse.up();
+
+    const after = await gridOrder(page);
+    expect(after).not.toEqual(before);
+    // The moved panel is no longer where it started.
+    expect(after.indexOf(movable)).not.toBe(before.indexOf(movable));
+  });
+
+  test('the resize handle snaps a panel to a taller span', async ({ page }) => {
+    await appReady(page);
+    const before = await gridOrder(page);
+    const key = before.find((k) => k && k !== 'live-news' && k !== 'map')!;
+    const panel = page.locator(`#panelsGrid .panel[data-panel="${key}"]`);
+    const handle = panel.locator('.panel-resize-handle');
+    const h = (await handle.boundingBox())!;
+
+    await page.mouse.move(h.x + h.width / 2, h.y + h.height / 2);
+    await page.mouse.down();
+    await page.mouse.move(h.x + h.width / 2, h.y + h.height / 2 + 230, { steps: 14 });
+    await page.mouse.up();
+
+    // Height resize lands on the fine 16px row grid (smooth ~20px steps), so the
+    // panel carries `resized` + a data-span well above the ~100px minSpan — not the
+    // coarse span-2 tier class the old assertion expected.
+    await expect(panel).toHaveClass(/resized/);
+    const span = await panel.evaluate((el) => parseInt((el as HTMLElement).dataset.span ?? '0', 10));
+    expect(span).toBeGreaterThan(5);
+  });
+
+  test('Reset layout returns the grid to the default order', async ({ page }) => {
+    await appReady(page);
+    const original = await gridOrder(page);
+
+    // Reorder a panel so the layout is dirty.
+    const movable = original.find((k) => k && k !== 'live-news' && k !== 'map')!;
+    const src = page.locator(`#panelsGrid .panel[data-panel="${movable}"]`);
+    const sb = (await src.locator('.panel-header').first().boundingBox())!;
+    const grid = (await page.locator('#panelsGrid').boundingBox())!;
+    await page.mouse.move(sb.x + 40, sb.y + sb.height / 2);
+    await page.mouse.down();
+    await page.mouse.move(sb.x + 60, sb.y + sb.height / 2 + 20, { steps: 6 });
+    await page.mouse.move(grid.x + grid.width * 0.5, grid.y + grid.height - 30, { steps: 18 });
+    await page.mouse.up();
+    expect(await gridOrder(page)).not.toEqual(original);
+
+    // Open the Panels menu and hit Reset layout (this reloads the app).
+    await page.click('#settingsBtn');
+    await page.waitForSelector('#resetLayoutBtn', { state: 'visible' });
+    await Promise.all([
+      page.waitForNavigation({ waitUntil: 'domcontentloaded' }).catch(() => {}),
+      page.click('#resetLayoutBtn'),
+    ]);
+
+    // After reset+reload the grid rebuilds from DEFAULT_PANELS: live-news first,
+    // and the order matches a fresh session.
+    await appReady(page);
+    const reset = await gridOrder(page);
+    expect(reset[0]).toBe('live-news');
+    expect(reset).toEqual(original);
+  });
+});

go.mod

@@ -0,0 +1,30 @@
+module github.com/hanzoai/world
+
+go 1.26.4
+
+require (
+	github.com/alicebob/miniredis/v2 v2.38.0
+	github.com/hanzoai/sqlite v0.3.2
+	github.com/redis/go-redis/v9 v9.20.0
+	golang.org/x/net v0.54.0
+)
+
+require (
+	github.com/cespare/xxhash/v2 v2.3.0 // indirect
+	github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc // indirect
+	github.com/dustin/go-humanize v1.0.1 // indirect
+	github.com/google/uuid v1.6.0 // indirect
+	github.com/hanzoai/csqlite v0.1.0 // indirect
+	github.com/hanzoai/sqlcipher v0.1.0 // indirect
+	github.com/klauspost/cpuid/v2 v2.3.0 // indirect
+	github.com/mattn/go-isatty v0.0.21 // indirect
+	github.com/ncruces/go-strftime v1.0.0 // indirect
+	github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 // indirect
+	github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec // indirect
+	github.com/stretchr/testify v1.11.1 // indirect
+	github.com/yuin/gopher-lua v1.1.1 // indirect
+	go.uber.org/atomic v1.11.0 // indirect
+	golang.org/x/crypto v0.52.0 // indirect
+	golang.org/x/sys v0.46.0 // indirect
+	golang.org/x/text v0.37.0 // indirect
+)

go.sum

@@ -0,0 +1,50 @@
+github.com/alicebob/miniredis/v2 v2.38.0 h1:nZAzCR+Lj+Vxk4ZXzm2NuKq2O33RXj1XxJ2e2uP9jiw=
+github.com/alicebob/miniredis/v2 v2.38.0/go.mod h1:TcL7YfarKPGDAthEtl5NBeHZfeUQj6OXMm/+iu5cLMM=
+github.com/bsm/ginkgo/v2 v2.12.0 h1:Ny8MWAHyOepLGlLKYmXG4IEkioBysk6GpaRTLC8zwWs=
+github.com/bsm/ginkgo/v2 v2.12.0/go.mod h1:SwYbGRRDovPVboqFv0tPTcG1sN61LM1Z4ARdbAV9g4c=
+github.com/bsm/gomega v1.27.10 h1:yeMWxP2pV2fG3FgAODIY8EiRE3dy0aeFYt4l7wh6yKA=
+github.com/bsm/gomega v1.27.10/go.mod h1:JyEr/xRbxbtgWNi8tIEVPUYZ5Dzef52k01W3YH0H+O0=
+github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs=
+github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
+github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc h1:U9qPSI2PIWSS1VwoXQT9A3Wy9MM3WgvqSxFWenqJduM=
+github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/dustin/go-humanize v1.0.1 h1:GzkhY7T5VNhEkwH0PVJgjz+fX1rhBrR7pRT3mDkpeCY=
+github.com/dustin/go-humanize v1.0.1/go.mod h1:Mu1zIs6XwVuF/gI1OepvI0qD18qycQx+mFykh5fBlto=
+github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
+github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
+github.com/hanzoai/csqlite v0.1.0 h1:suwC3dh0INlfP/U0Es6cDf6JNQ+2+GVLLATPWCUux6k=
+github.com/hanzoai/csqlite v0.1.0/go.mod h1:H31a/O6VXuklR9UBkgY++bmAK5uzVfXPqU0F6P9Wsos=
+github.com/hanzoai/sqlcipher v0.1.0 h1:V9gKG3ZltN2ZCteDrOnXWfOeEe/YDhhUm9AorQEAuBo=
+github.com/hanzoai/sqlcipher v0.1.0/go.mod h1:F0soUYM1i4sawOZUpRvVnWoUayPbeGVlGq01VXy9Aqg=
+github.com/hanzoai/sqlite v0.3.2 h1:B/TRunlIDZECEypmr6rHeNyWf37YZXvPJHBDEFMKn/g=
+github.com/hanzoai/sqlite v0.3.2/go.mod h1:a3llsefKbu2Iq/0rJ1mlWCaU2t2cXh+aze85x+oW72k=
+github.com/klauspost/cpuid/v2 v2.3.0 h1:S4CRMLnYUhGeDFDqkGriYKdfoFlDnMtqTiI/sFzhA9Y=
+github.com/klauspost/cpuid/v2 v2.3.0/go.mod h1:hqwkgyIinND0mEev00jJYCxPNVRVXFQeu1XKlok6oO0=
+github.com/mattn/go-isatty v0.0.21 h1:xYae+lCNBP7QuW4PUnNG61ffM4hVIfm+zUzDuSzYLGs=
+github.com/mattn/go-isatty v0.0.21/go.mod h1:ZXfXG4SQHsB/w3ZeOYbR0PrPwLy+n6xiMrJlRFqopa4=
+github.com/ncruces/go-strftime v1.0.0 h1:HMFp8mLCTPp341M/ZnA4qaf7ZlsbTc+miZjCLOFAw7w=
+github.com/ncruces/go-strftime v1.0.0/go.mod h1:Fwc5htZGVVkseilnfgOVb9mKy6w1naJmn9CehxcKcls=
+github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 h1:Jamvg5psRIccs7FGNTlIRMkT8wgtp5eCXdBlqhYGL6U=
+github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/redis/go-redis/v9 v9.20.0 h1:WnQYxLkgO2xiXTCJY0ldIiI8dNqCDlQAG+AtaH7a2a0=
+github.com/redis/go-redis/v9 v9.20.0/go.mod h1:v/M13XI1PVCDcm01VtPFOADfZtHf8YW3baQf57KlIkA=
+github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec h1:W09IVJc94icq4NjY3clb7Lk8O1qJ8BdBEF8z0ibU0rE=
+github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec/go.mod h1:qqbHyh8v60DhA7CoWK5oRCqLrMHRGoxYCSS9EjAz6Eo=
+github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
+github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
+github.com/yuin/gopher-lua v1.1.1 h1:kYKnWBjvbNP4XLT3+bPEwAXJx262OhaHDWDVOPjL46M=
+github.com/yuin/gopher-lua v1.1.1/go.mod h1:GBR0iDaNXjAgGg9zfCvksxSRnQx76gclCIb7kdAd1Pw=
+github.com/zeebo/xxh3 v1.1.0 h1:s7DLGDK45Dyfg7++yxI0khrfwq9661w9EN78eP/UZVs=
+github.com/zeebo/xxh3 v1.1.0/go.mod h1:IisAie1LELR4xhVinxWS5+zf1lA4p0MW4T+w+W07F5s=
+go.uber.org/atomic v1.11.0 h1:ZvwS0R+56ePWxUNi+Atn9dWONBPp/AUETXlHW0DxSjE=
+go.uber.org/atomic v1.11.0/go.mod h1:LUxbIzbOniOlMKjJjyPfpl4v+PKK2cNJn91OQbhoJI0=
+golang.org/x/crypto v0.52.0 h1:RMs7fP2rXdep0CftQlK8Uf+kibLm7qkCcradZWYz988=
+golang.org/x/crypto v0.52.0/go.mod h1:1QgfPxDqh0T2M/elOJtp9RvuR95kVjir0e6/BvEmGbc=
+golang.org/x/net v0.54.0 h1:2zJIZAxAHV/OHCDTCOHAYehQzLfSXuf/5SoL/Dv6w/w=
+golang.org/x/net v0.54.0/go.mod h1:Sj4oj8jK6XmHpBZU/zWHw3BV3abl4Kvi+Ut7cQcY+cQ=
+golang.org/x/sys v0.46.0 h1:noSf2Fq6F8DBgS+LysIkx7rIExoNHJsxOAtPp4rthXw=
+golang.org/x/sys v0.46.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
+golang.org/x/text v0.37.0 h1:Cqjiwd9eSg8e0QAkyCaQTNHFIIzWtidPahFWR83rTrc=
+golang.org/x/text v0.37.0/go.mod h1:a5sjxXGs9hsn/AJVwuElvCAo9v8QYLzvavO5z2PiM38=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

hanzo.yml

@@ -0,0 +1,40 @@
+# Canonical CI/CD config for hanzoai/world — read by both the hanzoai/ci
+# reusable workflow (.github/workflows/cicd.yml) and platform.hanzo.ai.
+# One image (the Vite SPA served by hanzoai/static), and a main-branch rollout
+# onto the existing `world` operator Service CR
+# (universe: infra/k8s/operator/crs/world.yaml).
+#
+# No separate `test:` block: the Dockerfile IS the gate — `npm ci && npm run
+# build` fails the image on any type error or build break, so nothing broken
+# ships (same pattern as hanzoai/finance + hanzoai/console).
+
+images:
+  - name: world
+    context: .
+    dockerfile: Dockerfile
+    repo: ghcr.io/hanzoai/world
+    # Publishable Mapbox token (pk, URL-restricted to world.hanzo.ai) baked into
+    # the Vite SPA at build so the Satellite/Terrain basemaps load (Dark stays
+    # keyless CartoDB). Sourced from KMS (hanzo/deploy/VITE_MAPBOX_TOKEN,
+    # env=prod) by hanzoai/ci — the key name IS the build-arg. Never in git.
+    build_secrets:
+      - VITE_MAPBOX_TOKEN
+
+# Deploy: roll the freshly-built image onto the `world` Service CR. Fires only
+# on `main` (+ tags); PRs and forks build but never deploy. KMS hands back the
+# kubeconfig at run time.
+deploy:
+  cluster: do-sfo3-hanzo-k8s
+  namespace: hanzo
+  # Quoted to dodge YAML 1.1 boolean coercion of a bare `on:` key.
+  "on": [main]
+  services:
+    - name: world
+      image: world
+
+# KMS (kms.hanzo.ai, Universal Auth) supplies the GHCR push token and the
+# target kubeconfig at run time. Only KMS_CLIENT_ID/KMS_CLIENT_SECRET live in
+# GitHub; everything else is fetched here.
+kms:
+  path: /deploy
+  environment: prod

index.html

@@ -3,56 +3,56 @@
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <meta http-equiv="Content-Security-Policy" content="default-src 'self'; connect-src 'self' https: http://localhost:5173 http://127.0.0.1:46123 ws: wss: blob: data:; img-src 'self' data: blob: https:; style-src 'self' 'unsafe-inline'; script-src 'self' 'unsafe-inline' 'wasm-unsafe-eval' https://www.youtube.com https://static.cloudflareinsights.com https://vercel.live; worker-src 'self' blob:; font-src 'self' data: https:; media-src 'self' data: blob: https:; frame-src 'self' http://127.0.0.1:46123 https://worldmonitor.app https://tech.worldmonitor.app https://www.youtube.com https://www.youtube-nocookie.com;" />
+    <meta http-equiv="Content-Security-Policy" content="default-src 'self'; connect-src 'self' https: http://localhost:5173 http://127.0.0.1:46123 ws: wss: blob: data:; img-src 'self' data: blob: https:; style-src 'self' 'unsafe-inline'; script-src 'self' 'unsafe-inline' 'wasm-unsafe-eval' https://www.youtube.com https://static.cloudflareinsights.com; worker-src 'self' blob:; font-src 'self' data: https:; media-src 'self' data: blob: https:; frame-src 'self' http://127.0.0.1:46123 https://www.youtube.com https://www.youtube-nocookie.com;" />
     <meta name="referrer" content="strict-origin-when-cross-origin" />
 
     <!-- Primary Meta Tags -->
-    <title>World Monitor - Global Situation with AI Insights</title>
-    <meta name="title" content="World Monitor - Global Situation with AI Insights" />
-    <meta name="description" content="AI-powered real-time global intelligence dashboard with live news, markets, military tracking, infrastructure monitoring, and geopolitical data. OSINT in one view." />
-    <meta name="keywords" content="AI intelligence, AI-powered dashboard, global intelligence, geopolitical dashboard, world news, market data, military bases, nuclear facilities, undersea cables, conflict zones, real-time monitoring, situation awareness, OSINT, flight tracking, AIS ships, earthquake monitor, protest tracker, power outages, oil prices, government spending, polymarket predictions" />
-    <meta name="author" content="Elie Habib" />
-    <meta name="theme-color" content="#0a0f0a" />
+    <title>Hanzo World — Real-Time Global Intelligence</title>
+    <meta name="title" content="Hanzo World — Real-Time Global Intelligence" />
+    <meta name="description" content="Hanzo World — AI-powered real-time global intelligence dashboard: live news, markets, strategic posture, infrastructure and geopolitical data in one view." />
+    <meta name="keywords" content="Hanzo, AI intelligence, global intelligence, geopolitical dashboard, world news, market data, real-time monitoring, situation awareness, prediction markets" />
+    <meta name="author" content="Hanzo AI" />
+    <meta name="theme-color" content="#000000" />
     <meta name="robots" content="index, follow" />
-    <link rel="canonical" href="https://worldmonitor.app/" />
+    <link rel="canonical" href="https://world.hanzo.ai/" />
 
     <!-- Additional Search Discovery -->
-    <meta name="application-name" content="World Monitor" />
+    <meta name="application-name" content="Hanzo World" />
     <meta name="subject" content="AI-Powered Global Intelligence and Situation Awareness" />
-    <meta name="classification" content="AI Intelligence Dashboard, OSINT Tool, News Aggregator" />
+    <meta name="classification" content="AI Intelligence Dashboard" />
     <meta name="coverage" content="Worldwide" />
     <meta name="distribution" content="Global" />
     <meta name="rating" content="General" />
 
     <!-- Open Graph / Facebook -->
     <meta property="og:type" content="website" />
-    <meta property="og:url" content="https://worldmonitor.app/" />
-    <meta property="og:title" content="World Monitor - Global Situation with AI Insights" />
-    <meta property="og:description" content="AI-powered real-time global intelligence dashboard with live news, markets, military tracking, infrastructure monitoring, and geopolitical data." />
-    <meta property="og:image" content="https://worldmonitor.app/favico/og-image.png" />
+    <meta property="og:url" content="https://world.hanzo.ai/" />
+    <meta property="og:title" content="Hanzo World — Real-Time Global Intelligence" />
+    <meta property="og:description" content="Hanzo World — AI-powered real-time global intelligence dashboard: live news, markets, strategic posture and geopolitical data." />
+    <meta property="og:image" content="https://world.hanzo.ai/favico/og-image.png" />
     <meta property="og:image:width" content="1200" />
     <meta property="og:image:height" content="630" />
-    <meta property="og:site_name" content="World Monitor" />
+    <meta property="og:site_name" content="Hanzo World" />
     <meta property="og:locale" content="en_US" />
 
     <!-- Twitter -->
     <meta name="twitter:card" content="summary_large_image" />
-    <meta name="twitter:url" content="https://worldmonitor.app/" />
-    <meta name="twitter:title" content="World Monitor - Global Situation with AI Insights" />
-    <meta name="twitter:description" content="AI-powered real-time global intelligence dashboard with live news, markets, military tracking, infrastructure monitoring, and geopolitical data." />
-    <meta name="twitter:image" content="https://worldmonitor.app/favico/og-image.png" />
-    <meta name="twitter:site" content="@worldmonitorapp" />
-    <meta name="twitter:creator" content="@eliehabib" />
+    <meta name="twitter:url" content="https://world.hanzo.ai/" />
+    <meta name="twitter:title" content="Hanzo World — Real-Time Global Intelligence" />
+    <meta name="twitter:description" content="Hanzo World — AI-powered real-time global intelligence dashboard." />
+    <meta name="twitter:image" content="https://world.hanzo.ai/favico/og-image.png" />
+    <meta name="twitter:site" content="@hanzoai" />
+    <meta name="twitter:creator" content="@hanzoai" />
 
     <!-- JSON-LD Structured Data -->
     <script type="application/ld+json">
     {
       "@context": "https://schema.org",
       "@type": "WebApplication",
-      "name": "World Monitor",
-      "alternateName": "WorldMonitor",
-      "url": "https://worldmonitor.app/",
-      "description": "AI-powered real-time global intelligence dashboard with live news, markets, military tracking, infrastructure monitoring, and geopolitical data.",
+      "name": "Hanzo World",
+      "alternateName": "Hanzo World Intelligence",
+      "url": "https://world.hanzo.ai/",
+      "description": "Hanzo World — AI-powered real-time global intelligence dashboard with live news, markets, strategic posture, infrastructure and geopolitical data.",
       "applicationCategory": "UtilitiesApplication",
       "operatingSystem": "Web Browser",
       "offers": {
@@ -61,8 +61,8 @@
         "priceCurrency": "USD"
       },
       "author": {
-        "@type": "Person",
-        "name": "Elie Habib"
+        "@type": "Organization",
+        "name": "Hanzo AI"
       },
       "featureList": [
         "AI-powered intelligence synthesis",
@@ -79,16 +79,15 @@
         "Infrastructure monitoring",
         "Geopolitical intelligence"
       ],
-      "screenshot": "https://worldmonitor.app/favico/og-image.png",
+      "screenshot": "https://world.hanzo.ai/favico/og-image.png",
       "keywords": "AI, OSINT, intelligence dashboard, geopolitical, real-time monitoring, situation awareness, AI-powered"
     }
     </script>
 
     <!-- Favicons -->
+    <link rel="icon" type="image/svg+xml" href="/favico/hanzo-favicon.svg" />
     <link rel="icon" type="image/x-icon" href="/favico/favicon.ico" />
-    <link rel="icon" type="image/png" sizes="32x32" href="/favico/favicon-32x32.png" />
-    <link rel="icon" type="image/png" sizes="16x16" href="/favico/favicon-16x16.png" />
-    <link rel="apple-touch-icon" sizes="180x180" href="/favico/apple-touch-icon.png" />
+    <link rel="apple-touch-icon" sizes="180x180" href="/favico/hanzo-favicon.svg" />
 
 
     <!-- Theme: apply stored preference before first paint to prevent FOUC -->

internal/agentskills/agentskills.go

@@ -0,0 +1,118 @@
+// Package agentskills builds and validates the /.well-known/agent-skills catalog
+// index.json from the SKILL.md files beside it. It is the SINGLE source of truth
+// for the index: the generator (cmd/genskills) writes exactly Marshal(Build(dir))
+// and the drift test asserts the on-disk index.json equals it — so a SKILL.md
+// edit that isn't regenerated fails CI instead of shipping a stale digest.
+//
+//go:generate go run ./cmd/genskills
+package agentskills
+
+import (
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+)
+
+// IndexName is the catalog file that lists every skill with its digest.
+const IndexName = "index.json"
+
+// RelDir is the catalog directory relative to THIS package's directory. Both the
+// generator (run via `go generate` here) and the drift test resolve it the same
+// way, so there is one path in one place.
+const RelDir = "../../public/.well-known/agent-skills"
+
+// skillSuffix identifies a skill document.
+const skillSuffix = ".SKILL.md"
+
+// SchemaVersion tags the catalog envelope.
+const SchemaVersion = 1
+
+// Skill is one catalog entry: enough to discover and fetch a skill, plus the
+// digest that pins its document.
+type Skill struct {
+	Name     string `json:"name"`
+	Endpoint string `json:"endpoint"`
+	File     string `json:"file"`
+	SHA256   string `json:"sha256"`
+}
+
+// Catalog is the index.json envelope.
+type Catalog struct {
+	Version int     `json:"version"`
+	Skills  []Skill `json:"skills"`
+}
+
+// Build scans dir for *.SKILL.md, reads name+endpoint from each file's YAML
+// frontmatter, and pins each with its sha256. Order is deterministic (by name).
+func Build(dir string) (Catalog, error) {
+	matches, err := filepath.Glob(filepath.Join(dir, "*"+skillSuffix))
+	if err != nil {
+		return Catalog{}, err
+	}
+	skills := make([]Skill, 0, len(matches))
+	for _, path := range matches {
+		b, err := os.ReadFile(path)
+		if err != nil {
+			return Catalog{}, err
+		}
+		fm := frontmatter(b)
+		name := fm["name"]
+		if name == "" {
+			return Catalog{}, fmt.Errorf("%s: missing frontmatter name", filepath.Base(path))
+		}
+		sum := sha256.Sum256(b)
+		skills = append(skills, Skill{
+			Name:     name,
+			Endpoint: fm["endpoint"],
+			File:     filepath.Base(path),
+			SHA256:   hex.EncodeToString(sum[:]),
+		})
+	}
+	sort.Slice(skills, func(i, j int) bool { return skills[i].Name < skills[j].Name })
+	return Catalog{Version: SchemaVersion, Skills: skills}, nil
+}
+
+// Marshal renders the catalog as the exact bytes written to index.json: indented
+// with a trailing newline, so generator output and the on-disk file compare
+// byte-for-byte.
+func Marshal(c Catalog) ([]byte, error) {
+	b, err := json.MarshalIndent(c, "", "  ")
+	if err != nil {
+		return nil, err
+	}
+	return append(b, '\n'), nil
+}
+
+// frontmatter parses the leading "--- ... ---" YAML block as flat key:value
+// pairs. Deliberately minimal (no dependency): the frontmatter is flat scalars.
+func frontmatter(b []byte) map[string]string {
+	out := map[string]string{}
+	s := string(b)
+	if !strings.HasPrefix(s, "---") {
+		return out
+	}
+	rest := s[len("---"):]
+	end := strings.Index(rest, "\n---")
+	if end < 0 {
+		return out
+	}
+	for _, line := range strings.Split(rest[:end], "\n") {
+		line = strings.TrimSpace(line)
+		k, v, ok := strings.Cut(line, ":")
+		if !ok {
+			continue
+		}
+		key := strings.TrimSpace(k)
+		val := strings.TrimSpace(v)
+		val = strings.Trim(val, `"'`)
+		if key != "" {
+			out[key] = val
+		}
+	}
+	return out
+}

internal/agentskills/agentskills_test.go

@@ -0,0 +1,107 @@
+package agentskills_test
+
+import (
+	"crypto/sha256"
+	"encoding/hex"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/hanzoai/world/internal/agentskills"
+	"github.com/hanzoai/world/internal/world"
+)
+
+// TestIndexNotDrifted is the drift guard: the on-disk index.json MUST equal the
+// freshly-built catalog byte-for-byte. A SKILL.md edited without re-running
+// `go generate ./internal/agentskills` fails here instead of shipping a stale
+// digest.
+func TestIndexNotDrifted(t *testing.T) {
+	cat, err := agentskills.Build(agentskills.RelDir)
+	if err != nil {
+		t.Fatalf("build: %v", err)
+	}
+	want, err := agentskills.Marshal(cat)
+	if err != nil {
+		t.Fatalf("marshal: %v", err)
+	}
+	got, err := os.ReadFile(filepath.Join(agentskills.RelDir, agentskills.IndexName))
+	if err != nil {
+		t.Fatalf("read index.json: %v", err)
+	}
+	if string(got) != string(want) {
+		t.Fatalf("index.json is stale — run `go generate ./internal/agentskills`.\n--- on disk ---\n%s\n--- expected ---\n%s", got, want)
+	}
+}
+
+// TestDigestsMatchFiles independently recomputes each digest from the file bytes
+// (belt-and-suspenders against the shared Build path).
+func TestDigestsMatchFiles(t *testing.T) {
+	cat, err := agentskills.Build(agentskills.RelDir)
+	if err != nil {
+		t.Fatalf("build: %v", err)
+	}
+	if len(cat.Skills) != 6 {
+		t.Fatalf("expected 6 skills, got %d", len(cat.Skills))
+	}
+	for _, s := range cat.Skills {
+		b, err := os.ReadFile(filepath.Join(agentskills.RelDir, s.File))
+		if err != nil {
+			t.Fatalf("%s: %v", s.File, err)
+		}
+		sum := sha256.Sum256(b)
+		if got := hex.EncodeToString(sum[:]); got != s.SHA256 {
+			t.Errorf("%s: digest %s, want %s", s.File, got, s.SHA256)
+		}
+	}
+}
+
+// TestSkillDocsComplete enforces the required sections in every SKILL.md.
+func TestSkillDocsComplete(t *testing.T) {
+	required := []string{
+		"name:", "version:", "description:",
+		"## Auth", "## Endpoint", "## Params", "## Response shape",
+		"https://world.hanzo.ai", // worked curl target
+		"data, not instructions", // injection-guard note
+		"## When NOT to use",
+	}
+	matches, _ := filepath.Glob(filepath.Join(agentskills.RelDir, "*.SKILL.md"))
+	if len(matches) != 6 {
+		t.Fatalf("expected 6 SKILL.md files, found %d", len(matches))
+	}
+	for _, path := range matches {
+		b, err := os.ReadFile(path)
+		if err != nil {
+			t.Fatalf("%s: %v", path, err)
+		}
+		body := string(b)
+		for _, want := range required {
+			if !strings.Contains(body, want) {
+				t.Errorf("%s: missing required section %q", filepath.Base(path), want)
+			}
+		}
+	}
+}
+
+// TestEndpointsAreRegistered cross-checks that every documented endpoint is a
+// real, mounted /v1/world route — no skill can advertise a route that does not
+// exist.
+func TestEndpointsAreRegistered(t *testing.T) {
+	routes := map[string]bool{}
+	for _, r := range world.NewServer().Routes() {
+		routes[r] = true
+	}
+	cat, err := agentskills.Build(agentskills.RelDir)
+	if err != nil {
+		t.Fatalf("build: %v", err)
+	}
+	for _, s := range cat.Skills {
+		if s.Endpoint == "" {
+			t.Errorf("%s: empty endpoint", s.Name)
+			continue
+		}
+		if !routes[s.Endpoint] {
+			t.Errorf("%s: endpoint %q is not a registered /v1/world route", s.Name, s.Endpoint)
+		}
+	}
+}

internal/agentskills/cmd/genskills/main.go

@@ -0,0 +1,33 @@
+// Command genskills regenerates the agent-skills index.json from the SKILL.md
+// files beside it. Run via `go generate ./internal/agentskills` (or directly:
+// `cd internal/agentskills && go run ./cmd/genskills`). It writes exactly
+// agentskills.Marshal(agentskills.Build(dir)); the drift test guards the result.
+package main
+
+import (
+	"log"
+	"os"
+	"path/filepath"
+
+	"github.com/hanzoai/world/internal/agentskills"
+)
+
+func main() {
+	dir := agentskills.RelDir
+	if len(os.Args) > 1 {
+		dir = os.Args[1] // allow an explicit dir override
+	}
+	cat, err := agentskills.Build(dir)
+	if err != nil {
+		log.Fatalf("genskills: build: %v", err)
+	}
+	b, err := agentskills.Marshal(cat)
+	if err != nil {
+		log.Fatalf("genskills: marshal: %v", err)
+	}
+	out := filepath.Join(dir, agentskills.IndexName)
+	if err := os.WriteFile(out, b, 0o644); err != nil {
+		log.Fatalf("genskills: write %s: %v", out, err)
+	}
+	log.Printf("genskills: wrote %s (%d skills)", out, len(cat.Skills))
+}

internal/world/ai.go

@@ -0,0 +1,359 @@
+package world
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"net/http"
+	"strings"
+	"time"
+)
+
+// AIClient talks to Hanzo's own OpenAI-compatible inference gateway
+// (api.hanzo.ai /v1 by default) instead of third-party LLM providers. The
+// summarize/classify/brief endpoints route here; when it is unconfigured or
+// fails, the handlers degrade cleanly (the SPA has a local fallback).
+type AIClient struct {
+	base  string
+	key   string
+	model string
+}
+
+func newAIClient() *AIClient {
+	base := env("HANZO_AI_BASE", "HANZO_API_BASE")
+	if base == "" {
+		base = "https://api.hanzo.ai/v1"
+	}
+	model := env("HANZO_AI_MODEL")
+	if model == "" {
+		// "best" is the gateway's own routing alias (owned_by hanzo in /v1/models):
+		// it always resolves to a servable model. A pinned family id (zen5) goes
+		// dark whenever the plane's claim catalog shifts — an unclaimed id falls
+		// through to a proxy that rejects every credential, killing all AI here.
+		model = "best"
+	}
+	return &AIClient{
+		base:  strings.TrimRight(base, "/"),
+		key:   env("HANZO_AI_KEY", "HANZO_API_KEY", "HANZO_AI_TOKEN"),
+		model: model,
+	}
+}
+
+// userBearer extracts the caller's IAM token exactly as Hanzo services accept
+// it: the Authorization header first, then the browser session cookies. This is
+// the logged-in world.hanzo.ai user's token — forwarding it lets api.hanzo.ai
+// derive their org + project + linked billing account and meter the inference to
+// THEM. No shared key: user-facing AI runs on the normal IAM login flow.
+func userBearer(r *http.Request) string {
+	if h := r.Header.Get("Authorization"); strings.HasPrefix(strings.ToLower(h), "bearer ") {
+		return h
+	}
+	for _, name := range []string{"hanzo_token", "access_token"} {
+		if c, err := r.Cookie(name); err == nil && c.Value != "" {
+			return "Bearer " + c.Value
+		}
+	}
+	return ""
+}
+
+// bearerFor returns the Authorization value to use for an inference call. The
+// signed-in user's IAM token is preferred (metered to their org/project/billing);
+// a.key is only a fallback for keyed self-host/dev deployments (env HANZO_AI_KEY),
+// never the path for a normal metered user on world.hanzo.ai.
+func (a *AIClient) bearerFor(r *http.Request) string {
+	if b := userBearer(r); b != "" {
+		return b
+	}
+	if a.key != "" {
+		return "Bearer " + a.key
+	}
+	return ""
+}
+
+// Tenant-selector headers the cloud gateway reads to scope a bearer call to a
+// specific org/project. Only X-Org-Id is honored as a requested org, and only
+// for a global-admin token (a normal token is re-pinned to its own owner); the
+// value is otherwise inert but correct to forward. Evidence:
+// hanzo/cloud/middleware_identity.go (Peek "X-Org-Id" / "X-Project-Id").
+const (
+	orgHeader     = "X-Org-Id"
+	projectHeader = "X-Project-Id"
+)
+
+// aiForwardHeaders lifts the caller's active org/project selectors off the
+// inbound request so the same-origin world backend forwards them upstream to
+// api.hanzo.ai — the inference then meters to the org the user is acting in.
+// Absent selectors forward nothing (the gateway falls back to the token owner),
+// so this is backward-compatible with callers that don't send them.
+func aiForwardHeaders(r *http.Request) map[string]string {
+	out := map[string]string{}
+	if v := strings.TrimSpace(r.Header.Get(orgHeader)); v != "" {
+		out[orgHeader] = v
+	}
+	if v := strings.TrimSpace(r.Header.Get(projectHeader)); v != "" {
+		out[projectHeader] = v
+	}
+	if len(out) == 0 {
+		return nil
+	}
+	return out
+}
+
+type chatMessage struct {
+	Role    string `json:"role"`
+	Content string `json:"content"`
+}
+
+type chatRequest struct {
+	Model       string        `json:"model"`
+	Messages    []chatMessage `json:"messages"`
+	Temperature float64       `json:"temperature"`
+	MaxTokens   int           `json:"max_tokens"`
+	TopP        float64       `json:"top_p,omitempty"`
+}
+
+type chatResponse struct {
+	// ID is the gateway's response id (OpenAI chat.completion `id`). It is the
+	// stable key a content-free reward signal is attributed to (POST /v1/feedback),
+	// so it is threaded back out of every completion — never the prompt/response.
+	ID      string `json:"id"`
+	Choices []struct {
+		Message struct {
+			Content string `json:"content"`
+			// A reasoning model (gpt-oss / harmony, deepseek-r1) surfaces its working
+			// on a SEPARATE channel; when it emits no final content we fall back to
+			// this so the analyst still recovers an answer, not a blank "empty response".
+			ReasoningContent string `json:"reasoning_content"`
+			Reasoning        string `json:"reasoning"`
+		} `json:"message"`
+		FinishReason string `json:"finish_reason"`
+	} `json:"choices"`
+	Usage struct {
+		TotalTokens int `json:"total_tokens"`
+	} `json:"usage"`
+}
+
+// chat runs a single system+user completion and returns the trimmed content.
+// bearer is the Authorization value (the signed-in user's IAM token, so the
+// inference meters to their org/project/billing); extra carries the caller's
+// org/project selectors to forward upstream (aiForwardHeaders), nil when absent.
+func (a *AIClient) chat(ctx context.Context, s *Server, bearer, system, user string, temperature float64, maxTokens int, extra map[string]string) (string, int, error) {
+	return a.chatMessages(ctx, s, bearer,
+		[]chatMessage{{Role: "system", Content: system}, {Role: "user", Content: user}},
+		temperature, maxTokens, extra)
+}
+
+// chatMessages runs a multi-turn completion over a full messages array (system +
+// prior turns) and returns the trimmed content. It is the single completion path;
+// chat is the system+user special case. bearer is the caller's IAM token so the
+// inference meters to their org/project/billing; extra forwards the caller's
+// org/project selectors so it meters to the org the user is acting in. It drops
+// the gateway response id — only the analyst's reward-signal path
+// (runAnalystLoop → chatMessagesModel) needs it.
+func (a *AIClient) chatMessages(ctx context.Context, s *Server, bearer string, messages []chatMessage, temperature float64, maxTokens int, extra map[string]string) (string, int, error) {
+	out, tokens, _, err := a.chatMessagesModel(ctx, s, bearer, a.model, messages, temperature, maxTokens, extra)
+	return out, tokens, err
+}
+
+// chatMessagesModel is chatMessages with an explicit model override — the single
+// completion path once a caller (the analyst's model dropdown) chooses the model.
+// An empty model falls back to the client default (a.model). Everything else —
+// auth forwarding, org/project selectors, degrade semantics — is identical. It
+// also returns the gateway response id (chatResponse.ID) so the analyst can key a
+// content-free reward signal to it; "" when the gateway omits one.
+func (a *AIClient) chatMessagesModel(ctx context.Context, s *Server, bearer, model string, messages []chatMessage, temperature float64, maxTokens int, extra map[string]string) (string, int, string, error) {
+	if strings.TrimSpace(model) == "" {
+		model = a.model
+	}
+	reqBody, err := json.Marshal(chatRequest{
+		Model:       model,
+		Messages:    messages,
+		Temperature: temperature,
+		MaxTokens:   maxTokens,
+		TopP:        0.9,
+	})
+	if err != nil {
+		return "", 0, "", err
+	}
+	headers := map[string]string{
+		"Authorization": bearer,
+		"Content-Type":  "application/json",
+	}
+	for k, v := range extra {
+		headers[k] = v
+	}
+	cctx, cancel := context.WithTimeout(ctx, 30*time.Second)
+	defer cancel()
+	body, status, err := s.do(cctx, "POST", a.base+"/chat/completions", headers, reqBody)
+	if err != nil {
+		logf("world: ai request error: model=%s: %v", model, err)
+		return "", 0, "", err
+	}
+	if status < 200 || status >= 300 {
+		e := newAIError(status, body)
+		logf("world: ai non-success: status=%d code=%q model=%s", status, e.code, model)
+		return "", status, "", e
+	}
+	var cr chatResponse
+	if err := json.Unmarshal(body, &cr); err != nil {
+		logf("world: ai decode error: status=%d model=%s: %v", status, model, err)
+		return "", status, "", err
+	}
+	if len(cr.Choices) == 0 {
+		// The gateway answers some failures — notably insufficient balance — with a
+		// 2xx AND an error envelope carrying NO choices. Parse that envelope with the
+		// SAME lenient logic aiStatusError uses so an out-of-credits user gets a typed,
+		// actionable error (→ top-up CTA) instead of an opaque "empty response".
+		if e := newAIError(status, body); e.code != "" || e.msg != "" {
+			logf("world: ai 2xx empty-choices error: status=%d code=%q model=%s", status, e.code, model)
+			return "", status, "", e
+		}
+		logf("world: ai 2xx no choices: status=%d model=%s", status, model)
+		return "", status, "", emptyAnswerErr(model)
+	}
+	// Prefer the answer (content) channel; fall back to the reasoning channel a
+	// reasoning model (gpt-oss/harmony, deepseek-r1) uses when it returns no content —
+	// so the analyst recovers its envelope/prose instead of a blank "empty response".
+	msg := cr.Choices[0].Message
+	// Pre-trim so a whitespace-only content channel falls through to reasoning.
+	out := firstNonEmpty(strings.TrimSpace(msg.Content), strings.TrimSpace(msg.ReasoningContent), strings.TrimSpace(msg.Reasoning))
+	if out == "" {
+		// A 2xx with a real but content-free choice (e.g. a reasoning model that hit the
+		// token cap before emitting content). The body IS a normal completion here — do
+		// NOT run it through newAIError (its top-level `id` would be misread as an error
+		// code); surface the model + stop reason honestly instead.
+		logf("world: ai 2xx empty answer: status=%d model=%s finish=%s", status, model, cr.Choices[0].FinishReason)
+		return "", status, cr.ID, emptyAnswerErr(model)
+	}
+	return out, cr.Usage.TotalTokens, cr.ID, nil
+}
+
+// emptyAnswerErr is the honest error for a 2xx completion that carried no usable
+// answer (neither a content nor a reasoning channel). It names the served model so
+// the chat surfaces "the <model> model returned an empty answer" — actionable (switch
+// model) — instead of an opaque "empty response". Not a balance error, so it never
+// trips the top-up CTA.
+func emptyAnswerErr(model string) error {
+	if model = strings.TrimSpace(model); model != "" {
+		return fmt.Errorf("the %s model returned an empty answer", model)
+	}
+	return fmt.Errorf("the model returned an empty answer")
+}
+
+// aiError is a typed inference error carrying the upstream HTTP status plus the
+// error {code,message} parsed from the response body, so callers can branch on
+// the code (isBalanceError) instead of string-matching the rendered message. Its
+// Error() reproduces the actionable one-liner the SPA renders verbatim in chat:
+// "hanzo ai status <n>" plus the upstream code (or a short message) when present.
+type aiError struct {
+	status int
+	code   string
+	msg    string
+}
+
+func (e *aiError) Error() string {
+	base := fmt.Sprintf("hanzo ai status %d", e.status)
+	switch {
+	case e.code != "":
+		return base + ": " + e.code
+	case e.msg != "":
+		return base + ": " + trim80(e.msg)
+	}
+	return base
+}
+
+// parseAIErrorBody leniently extracts an error {code, message} from an inference
+// or billing response body, across every shape the gateway/billing layers emit.
+// It is the SINGLE parse shared by the non-2xx path (newAIError) and the 2xx
+// empty-choices path (chatMessagesModel): the gateway answers some failures —
+// notably insufficient balance — with HTTP 2xx and an error envelope carrying no
+// choices, so both must read the same envelope. Empty strings ⇒ no error found.
+//
+//	{"error":{"code":"insufficient_balance","message":…}} → code
+//	{"error":"unauthorized","message":…}                  → "unauthorized"
+//	{"id":"Unauthorized","message":…}                     → "Unauthorized"
+//	{"detail":…}                                          → message
+func parseAIErrorBody(body []byte) (code, msg string) {
+	var p struct {
+		Error   json.RawMessage `json:"error"`
+		Detail  string          `json:"detail"`
+		ID      string          `json:"id"`
+		Message string          `json:"message"`
+	}
+	if json.Unmarshal(body, &p) != nil {
+		return "", ""
+	}
+	msg = strings.TrimSpace(p.Message)
+	if len(p.Error) > 0 {
+		// error is either a nested {code,message} object or a bare string.
+		var eo struct {
+			Code    string `json:"code"`
+			Message string `json:"message"`
+		}
+		if json.Unmarshal(p.Error, &eo) == nil {
+			code = strings.TrimSpace(eo.Code)
+			if msg == "" {
+				msg = strings.TrimSpace(eo.Message)
+			}
+		} else {
+			var es string
+			if json.Unmarshal(p.Error, &es) == nil {
+				code = strings.TrimSpace(es)
+			}
+		}
+	}
+	if code == "" {
+		code = strings.TrimSpace(p.ID)
+	}
+	if msg == "" {
+		msg = strings.TrimSpace(p.Detail)
+	}
+	return code, msg
+}
+
+// newAIError builds a typed aiError from a response status + body.
+func newAIError(status int, body []byte) *aiError {
+	code, msg := parseAIErrorBody(body)
+	return &aiError{status: status, code: code, msg: msg}
+}
+
+// aiStatusError turns a non-2xx inference response into an ACTIONABLE error. The
+// SPA renders it verbatim in chat, so surfacing e.g. "insufficient_balance" turns
+// a dead chat into a fixable one; a body it can't parse degrades to the bare status.
+func aiStatusError(status int, body []byte) error {
+	return newAIError(status, body)
+}
+
+// balanceErrorFrom reports whether err is the canonical "out of credits" signal
+// the ONE AI gateway emits — HTTP 402 with code=insufficient_balance
+// (hanzo/ai routers/filter_balance.go, the single balance-enforcement point).
+// World is a thin client of that contract: it neither re-derives balance
+// semantics (no message keyword-matching) nor invents codes the backend never
+// sends. The analyst renders a top-up CTA for exactly this case.
+func balanceErrorFrom(err error) bool {
+	var ae *aiError
+	if errors.As(err, &ae) {
+		return ae.status == http.StatusPaymentRequired || ae.code == "insufficient_balance"
+	}
+	return false
+}
+
+// trim80 trims s to at most 80 characters (runes, never splitting UTF-8) so a
+// long upstream message stays a compact one-liner in the chat error.
+func trim80(s string) string {
+	r := []rune(strings.TrimSpace(s))
+	if len(r) > 80 {
+		return strings.TrimSpace(string(r[:80]))
+	}
+	return string(r)
+}
+
+// dateContext mirrors the original prompts' current-date grounding.
+func dateContext(isTech bool) string {
+	base := "Current date: " + time.Now().UTC().Format("2006-01-02") + "."
+	if isTech {
+		return base
+	}
+	return base + " Donald Trump is the current US President (second term, inaugurated Jan 2025)."
+}

internal/world/ai_stream.go

@@ -0,0 +1,349 @@
+package world
+
+// Streaming inference — the SSE side of the ONE completion path.
+//
+// chatMessagesModelStream is chatMessagesModel with "stream":true: it reads the
+// upstream OpenAI-style SSE frames and hands each content delta to onDelta while
+// accumulating the full output, so callers keep the exact same (content, tokens,
+// error) contract and simply gain live deltas.
+//
+// replyExtractor solves the analyst's envelope problem: the model emits STRICT
+// JSON ({"reply":"…","actions":[…],"tools":[…]}), so raw deltas are not
+// user-presentable. The extractor is an incremental scanner fed those raw
+// deltas; it emits ONLY the unescaped contents of the top-level "reply" string
+// as it grows. Tool rounds ({"reply":"","tools":…}) therefore stream nothing,
+// and a model that ignores the envelope and answers in prose streams verbatim
+// (mirroring parseAnalystTurn's raw-output degrade).
+
+import (
+	"bufio"
+	"bytes"
+	"context"
+	"encoding/json"
+	"io"
+	"net/http"
+	"strconv"
+	"strings"
+	"time"
+)
+
+// chatMessagesModelStream runs one completion with streaming, calling onDelta
+// for every content chunk. Returns the full accumulated content, the token count,
+// and the gateway response id (first non-empty per-chunk id wins) so the analyst
+// can key a content-free reward signal to it. A nil onDelta degrades to a plain
+// buffered call semantically identical to chatMessagesModel.
+func (a *AIClient) chatMessagesModelStream(ctx context.Context, s *Server, bearer, model string, messages []chatMessage, temperature float64, maxTokens int, extra map[string]string, onDelta func(string)) (string, int, string, error) {
+	if strings.TrimSpace(model) == "" {
+		model = a.model
+	}
+	reqBody, err := json.Marshal(struct {
+		chatRequest
+		Stream bool `json:"stream"`
+	}{
+		chatRequest: chatRequest{Model: model, Messages: messages, Temperature: temperature, MaxTokens: maxTokens, TopP: 0.9},
+		Stream:      true,
+	})
+	if err != nil {
+		return "", 0, "", err
+	}
+	cctx, cancel := context.WithTimeout(ctx, 60*time.Second)
+	defer cancel()
+	req, err := http.NewRequestWithContext(cctx, http.MethodPost, a.base+"/chat/completions", bytes.NewReader(reqBody))
+	if err != nil {
+		return "", 0, "", err
+	}
+	req.Header.Set("Authorization", bearer)
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("Accept", "text/event-stream")
+	for k, v := range extra {
+		req.Header.Set(k, v)
+	}
+	resp, err := s.client.Do(req)
+	if err != nil {
+		return "", 0, "", err
+	}
+	defer func() { _ = resp.Body.Close() }()
+	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+		body, _ := io.ReadAll(io.LimitReader(resp.Body, 1<<20))
+		return "", resp.StatusCode, "", aiStatusError(resp.StatusCode, body)
+	}
+
+	// Some gateways answer a stream request with a plain JSON body (model or
+	// route not stream-capable). Sniff the content type and degrade quietly.
+	if ct := resp.Header.Get("Content-Type"); !strings.Contains(ct, "event-stream") {
+		body, err := io.ReadAll(io.LimitReader(resp.Body, maxBody))
+		if err != nil {
+			return "", resp.StatusCode, "", err
+		}
+		var cr chatResponse
+		if err := json.Unmarshal(body, &cr); err != nil {
+			return "", resp.StatusCode, "", err
+		}
+		if len(cr.Choices) == 0 {
+			return "", resp.StatusCode, "", emptyAnswerErr(model)
+		}
+		msg := cr.Choices[0].Message
+		out := firstNonEmpty(strings.TrimSpace(msg.Content), strings.TrimSpace(msg.ReasoningContent), strings.TrimSpace(msg.Reasoning))
+		if out == "" {
+			return "", resp.StatusCode, cr.ID, emptyAnswerErr(model)
+		}
+		if onDelta != nil {
+			onDelta(out)
+		}
+		return out, cr.Usage.TotalTokens, cr.ID, nil
+	}
+
+	var full strings.Builder
+	var reasoning strings.Builder
+	tokens := 0
+	id := ""
+	sc := bufio.NewScanner(resp.Body)
+	sc.Buffer(make([]byte, 0, 64<<10), 1<<20)
+	for sc.Scan() {
+		line := strings.TrimSpace(sc.Text())
+		if !strings.HasPrefix(line, "data:") {
+			continue
+		}
+		data := strings.TrimSpace(strings.TrimPrefix(line, "data:"))
+		if data == "" || data == "[DONE]" {
+			continue
+		}
+		var frame struct {
+			ID      string `json:"id"`
+			Choices []struct {
+				Delta struct {
+					Content          string `json:"content"`
+					ReasoningContent string `json:"reasoning_content"`
+					Reasoning        string `json:"reasoning"`
+				} `json:"delta"`
+			} `json:"choices"`
+			Usage *struct {
+				TotalTokens int `json:"total_tokens"`
+			} `json:"usage"`
+		}
+		if json.Unmarshal([]byte(data), &frame) != nil {
+			continue // tolerate keep-alives / vendor frames
+		}
+		if id == "" && frame.ID != "" {
+			id = frame.ID // first non-empty id wins (every chunk repeats it)
+		}
+		if frame.Usage != nil {
+			tokens = frame.Usage.TotalTokens
+		}
+		for _, c := range frame.Choices {
+			// Reasoning deltas (gpt-oss/harmony, deepseek-r1) ride a separate channel.
+			// Forward them too — the replyExtractor routes this pre-envelope prose to the
+			// live "thinking" line — and keep them as the answer fallback for a model that
+			// never emits a content channel. (Not trimmed: preserve inter-chunk spacing.)
+			rc := c.Delta.ReasoningContent
+			if rc == "" {
+				rc = c.Delta.Reasoning
+			}
+			if rc != "" {
+				reasoning.WriteString(rc)
+				if onDelta != nil {
+					onDelta(rc)
+				}
+			}
+			if c.Delta.Content != "" {
+				full.WriteString(c.Delta.Content)
+				if onDelta != nil {
+					onDelta(c.Delta.Content)
+				}
+			}
+		}
+	}
+	if err := sc.Err(); err != nil {
+		// A mid-stream drop still yields whatever arrived; the caller decides.
+		if full.Len() == 0 && reasoning.Len() == 0 {
+			return "", resp.StatusCode, "", err
+		}
+	}
+	// The content channel is the answer; fall back to the reasoning channel only when
+	// the model emitted no content at all (mirrors the buffered path above).
+	out := strings.TrimSpace(full.String())
+	if out == "" {
+		out = strings.TrimSpace(reasoning.String())
+	}
+	return out, tokens, id, nil
+}
+
+// ── incremental "reply" extraction ───────────────────────────────────────────
+
+// replyExtractor states.
+const (
+	rxSniff   = iota // deciding: JSON envelope or raw prose?
+	rxSeekKey        // scanning for "reply"
+	rxSeekColon
+	rxSeekQuote
+	rxInString // inside the reply value — emit unescaped runes
+	rxDone     // reply string closed (or prose mode ended)
+	rxProse    // no envelope — everything is the reply
+)
+
+// replyExtractor incrementally extracts the top-level "reply" string value from
+// a streaming JSON envelope, emitting decoded text via emit. Reasoning models
+// (gpt-oss, zen3-omni) write prose BEFORE the envelope — that pre-envelope text
+// goes to emitThink (nil-safe) so the UI can show it as live thinking, and the
+// moment a '{' appears the scanner switches to envelope mode. Feed() accepts
+// arbitrary chunk boundaries (escapes and \uXXXX may split across chunks).
+type replyExtractor struct {
+	state     int
+	emit      func(string)
+	emitThink func(string)
+	// key matching
+	keyBuf string
+	// string decoding
+	esc  bool   // last byte was a backslash
+	uBuf string // pending \uXXXX hex digits ("" when not in a unicode escape)
+	lead int    // sniff: bytes of leading whitespace seen
+}
+
+func newReplyExtractor(emit func(string)) *replyExtractor {
+	return &replyExtractor{state: rxSniff, emit: emit}
+}
+
+// Feed consumes the next raw chunk of model output.
+func (x *replyExtractor) Feed(chunk string) {
+	i := 0
+	for i < len(chunk) {
+		c := chunk[i]
+		switch x.state {
+		case rxSniff:
+			if c == ' ' || c == '\n' || c == '\r' || c == '\t' {
+				i++
+				continue
+			}
+			if c == '{' {
+				x.state = rxSeekKey
+				i++
+				continue
+			}
+			// Pre-envelope prose (a reasoning model thinking out loud) — stream
+			// it as thinking until the envelope's '{' shows up.
+			x.state = rxProse
+		case rxProse:
+			j := i
+			for j < len(chunk) && chunk[j] != '{' {
+				j++
+			}
+			if j > i && x.emitThink != nil {
+				x.emitThink(chunk[i:j])
+			}
+			if j >= len(chunk) {
+				return
+			}
+			x.state = rxSeekKey // envelope begins
+			i = j + 1
+		case rxSeekKey:
+			// scan for the exact key "reply" — cheap rolling match on quoted
+			// runs; the envelope contract puts reply first, so this stays
+			// shallow in practice.
+			if c == '"' {
+				x.keyBuf = ""
+				j := i + 1
+				for j < len(chunk) && chunk[j] != '"' {
+					x.keyBuf += string(chunk[j])
+					j++
+				}
+				if j >= len(chunk) {
+					// key name split across chunks — resume in rxKeyPartial
+					x.state = rxKeyPartial
+					return
+				}
+				if x.keyBuf == "reply" {
+					x.state = rxSeekColon
+				}
+				i = j + 1
+				continue
+			}
+			i++
+		case rxKeyPartial:
+			for i < len(chunk) && chunk[i] != '"' {
+				x.keyBuf += string(chunk[i])
+				i++
+			}
+			if i < len(chunk) { // closing quote
+				if x.keyBuf == "reply" {
+					x.state = rxSeekColon
+				} else {
+					x.state = rxSeekKey
+				}
+				i++
+			}
+		case rxSeekColon:
+			if c == ':' {
+				x.state = rxSeekQuote
+			}
+			i++
+		case rxSeekQuote:
+			if c == '"' {
+				x.state = rxInString
+			} else if c != ' ' && c != '\n' && c != '\r' && c != '\t' {
+				x.state = rxSeekKey // reply wasn't a string (defensive)
+			}
+			i++
+		case rxInString:
+			if x.uBuf != "" || x.esc {
+				i = x.feedEscape(chunk, i)
+				continue
+			}
+			if c == '\\' {
+				x.esc = true
+				i++
+				continue
+			}
+			if c == '"' {
+				x.state = rxDone
+				return
+			}
+			// emit the longest plain run in one call
+			j := i
+			for j < len(chunk) && chunk[j] != '\\' && chunk[j] != '"' {
+				j++
+			}
+			x.emit(chunk[i:j])
+			i = j
+		case rxDone:
+			return
+		}
+	}
+}
+
+// rxKeyPartial handles a key name split across chunk boundaries.
+const rxKeyPartial = 100
+
+// feedEscape consumes escape-sequence bytes (possibly across chunks).
+func (x *replyExtractor) feedEscape(chunk string, i int) int {
+	if x.uBuf != "" { // inside \uXXXX ("u" + collected hex)
+		for i < len(chunk) && len(x.uBuf) < 5 {
+			x.uBuf += string(chunk[i])
+			i++
+		}
+		if len(x.uBuf) == 5 {
+			if v, err := strconv.ParseUint(x.uBuf[1:], 16, 32); err == nil {
+				x.emit(string(rune(v)))
+			}
+			x.uBuf = ""
+		}
+		return i
+	}
+	// x.esc: the byte after a backslash
+	c := chunk[i]
+	x.esc = false
+	switch c {
+	case 'n':
+		x.emit("\n")
+	case 't':
+		x.emit("\t")
+	case 'r':
+		x.emit("\r")
+	case 'u':
+		x.uBuf = "u"
+	case '"', '\\', '/':
+		x.emit(string(c))
+	default:
+		x.emit(string(c))
+	}
+	return i + 1
+}

internal/world/ai_stream_test.go

@@ -0,0 +1,64 @@
+package world
+
+import (
+	"strings"
+	"testing"
+)
+
+// feedChunks drives an extractor with the given chunking and returns the
+// emitted reply text and thinking text.
+func feedChunks(t *testing.T, chunks []string) (reply, think string) {
+	t.Helper()
+	var r, th strings.Builder
+	x := newReplyExtractor(func(s string) { r.WriteString(s) })
+	x.emitThink = func(s string) { th.WriteString(s) }
+	for _, c := range chunks {
+		x.Feed(c)
+	}
+	return r.String(), th.String()
+}
+
+func TestReplyExtractor(t *testing.T) {
+	cases := []struct {
+		name      string
+		chunks    []string
+		want      string
+		wantThink string
+	}{
+		{"whole envelope", []string{`{"reply":"Hello world","actions":[]}`}, "Hello world", ""},
+		{"split mid-value", []string{`{"reply":"Hel`, `lo wor`, `ld","actions":[]}`}, "Hello world", ""},
+		{"split mid-key", []string{`{"re`, `ply":"hi"}`}, "hi", ""},
+		{"escapes", []string{`{"reply":"a\nb\t\"q\" c\\d"}`}, "a\nb\t\"q\" c\\d", ""},
+		{"escape split across chunks", []string{`{"reply":"x\`, `ny"}`}, "x\ny", ""},
+		{"unicode escape", []string{`{"reply":"snow ☃!"}`}, "snow ☃!", ""},
+		{"unicode escape split", []string{`{"reply":"a\u26`, `03b"}`}, "a☃b", ""},
+		{"tool round stays silent", []string{`{"reply":"","tools":[{"name":"world_brief","arguments":{"n":5}}]}`}, "", ""},
+		{"prose streams as thinking", []string{"Just a plain ", "prose answer."}, "", "Just a plain prose answer."},
+		{"reasoning preamble then envelope", []string{"We need to answer briefly. ", `{"reply":"The answer.","actions":[]}`}, "The answer.", "We need to answer briefly. "},
+		{"reasoning split around the brace", []string{"thinking…", " done ", `{"rep`, `ly":"yes"}`}, "yes", "thinking… done "},
+		{"leading whitespace then envelope", []string{"  \n ", `{"reply":"ok"}`}, "ok", ""},
+		{"other key first (defensive)", []string{`{"model":"x","reply":"later"}`}, "later", ""},
+		{"stops at closing quote", []string{`{"reply":"done","actions":[{"type":"noise \"reply\":\"nope\""}]}`}, "done", ""},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			got, think := feedChunks(t, tc.chunks)
+			if got != tc.want || think != tc.wantThink {
+				t.Errorf("got (%q, think %q), want (%q, think %q)", got, think, tc.want, tc.wantThink)
+			}
+		})
+	}
+}
+
+// Byte-at-a-time is the cruellest chunking — every state transition lands on a
+// boundary.
+func TestReplyExtractorByteAtATime(t *testing.T) {
+	in := `{"reply":"line1\nline2 é end","actions":[]}`
+	chunks := make([]string, 0, len(in))
+	for i := 0; i < len(in); i++ {
+		chunks = append(chunks, in[i:i+1])
+	}
+	if got, _ := feedChunks(t, chunks); got != "line1\nline2 é end" {
+		t.Errorf("got %q", got)
+	}
+}

internal/world/ai_test.go

@@ -0,0 +1,43 @@
+package world
+
+import "testing"
+
+// TestAIStatusError: the non-2xx inference body is parsed into an actionable
+// error across every shape the gateway/billing layers emit; an unparseable body
+// degrades to the bare status.
+func TestAIStatusError(t *testing.T) {
+	cases := []struct {
+		name   string
+		status int
+		body   string
+		want   string
+	}{
+		{"nested code", 402, `{"error":{"code":"insufficient_balance","message":"no funds"}}`, "hanzo ai status 402: insufficient_balance"},
+		{"nested spend cap", 402, `{"error":{"code":"spend_cap_exceeded","message":"cap hit"}}`, "hanzo ai status 402: spend_cap_exceeded"},
+		{"error string", 401, `{"error":"unauthorized","message":"bad token"}`, "hanzo ai status 401: unauthorized"},
+		{"id + message", 401, `{"id":"Unauthorized","message":"login required"}`, "hanzo ai status 401: Unauthorized"},
+		{"detail only", 400, `{"detail":"missing field query"}`, "hanzo ai status 400: missing field query"},
+		{"nested message no code", 403, `{"error":{"message":"forbidden here"}}`, "hanzo ai status 403: forbidden here"},
+		{"unparseable html", 500, `<html>502 bad gateway</html>`, "hanzo ai status 500"},
+		{"empty body", 429, ``, "hanzo ai status 429"},
+	}
+	for _, c := range cases {
+		if got := aiStatusError(c.status, []byte(c.body)).Error(); got != c.want {
+			t.Errorf("%s: aiStatusError(%d, %q) = %q, want %q", c.name, c.status, c.body, got, c.want)
+		}
+	}
+}
+
+// TestTrim80 caps a long upstream message to 80 runes without splitting UTF-8.
+func TestTrim80(t *testing.T) {
+	long := ""
+	for i := 0; i < 200; i++ {
+		long += "x"
+	}
+	if got := trim80(long); len([]rune(got)) != 80 {
+		t.Fatalf("trim80 long = %d runes, want 80", len([]rune(got)))
+	}
+	if got := trim80("  short  "); got != "short" {
+		t.Fatalf("trim80 trimmed = %q, want %q", got, "short")
+	}
+}

internal/world/cache.go

@@ -0,0 +1,121 @@
+package world
+
+import (
+	"sync"
+	"time"
+)
+
+// Cache is an in-memory, TTL-bounded value cache shared across all endpoints.
+// It is the Go twin of the edge functions' per-instance fallback caches: the
+// key is the UPSTREAM identity (endpoint + query), the value is public data
+// identical for every caller, so caching globally is correct and DRY.
+//
+// Each entry carries two horizons: a fresh TTL (served as a normal hit) and a
+// longer "stale" window (served only when the upstream fetch fails, mirroring
+// the STALE / stale-while-revalidate behavior of the originals). Growth is
+// bounded: at the cap, entries past their stale horizon are evicted first, then
+// the oldest remaining.
+type Cache struct {
+	mu  sync.Mutex
+	m   map[string]cacheEntry
+	max int
+}
+
+type cacheEntry struct {
+	val      any
+	freshExp time.Time
+	staleExp time.Time
+	stored   time.Time
+}
+
+// NewCache returns a cache bounded to max entries.
+func NewCache(max int) *Cache {
+	if max <= 0 {
+		max = 1024
+	}
+	return &Cache{m: make(map[string]cacheEntry), max: max}
+}
+
+// Get returns the cached value if it is still fresh.
+func (c *Cache) Get(key string) (any, bool) {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	e, ok := c.m[key]
+	if !ok || time.Now().After(e.freshExp) {
+		return nil, false
+	}
+	return e.val, true
+}
+
+// GetStale returns the cached value if it is within its stale window (used as a
+// last-resort fallback when the upstream is unavailable).
+func (c *Cache) GetStale(key string) (any, bool) {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	e, ok := c.m[key]
+	if !ok || time.Now().After(e.staleExp) {
+		return nil, false
+	}
+	return e.val, true
+}
+
+// Set stores val, fresh for ttl and served-when-degraded for an additional
+// staleFor beyond ttl.
+func (c *Cache) Set(key string, val any, ttl, staleFor time.Duration) {
+	now := time.Now()
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	if len(c.m) >= c.max {
+		c.evictLocked(now)
+	}
+	c.m[key] = cacheEntry{
+		val:      val,
+		freshExp: now.Add(ttl),
+		staleExp: now.Add(ttl + staleFor),
+		stored:   now,
+	}
+}
+
+// negPrefix namespaces negative-cache markers so they never collide with — or
+// clobber — a key's last-good value, which must stay available as a stale
+// fallback while the upstream is flapping.
+const negPrefix = "\x00neg\x00"
+
+// SetNegative records a short-lived failure marker for key so a flapping or
+// blank upstream is not re-hit on every request. It stores under a separate
+// namespaced key and therefore never touches the key's cached value, so a prior
+// good body remains servable via GetStale. staleFor is 0 (the marker itself is
+// never served, only observed), so it evicts first under memory pressure.
+func (c *Cache) SetNegative(key string, ttl time.Duration) {
+	c.Set(negPrefix+key, struct{}{}, ttl, 0)
+}
+
+// Negative reports whether key has a fresh failure marker (set by SetNegative).
+func (c *Cache) Negative(key string) bool {
+	_, ok := c.Get(negPrefix + key)
+	return ok
+}
+
+// evictLocked drops entries past their stale horizon; if still at the cap, it
+// drops the single oldest entry so a new one can be admitted.
+func (c *Cache) evictLocked(now time.Time) {
+	for k, e := range c.m {
+		if now.After(e.staleExp) {
+			delete(c.m, k)
+		}
+	}
+	if len(c.m) < c.max {
+		return
+	}
+	var oldestKey string
+	var oldest time.Time
+	first := true
+	for k, e := range c.m {
+		if first || e.stored.Before(oldest) {
+			oldestKey, oldest, first = k, e.stored, false
+		}
+	}
+	if oldestKey != "" {
+		delete(c.m, oldestKey)
+	}
+}

internal/world/cache_poison_test.go

@@ -0,0 +1,168 @@
+package world
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"sync/atomic"
+	"testing"
+	"time"
+)
+
+func TestIsBlankBody(t *testing.T) {
+	cases := []struct {
+		body string
+		want bool
+	}{
+		{"", true},
+		{" ", true},
+		{"\n\t  \r\n", true},
+		{"{}", false},
+		{"[]", false},
+		{" x ", false},
+		{`{"a":1}`, false},
+	}
+	for _, c := range cases {
+		if got := isBlankBody([]byte(c.body)); got != c.want {
+			t.Errorf("isBlankBody(%q) = %v, want %v", c.body, got, c.want)
+		}
+	}
+}
+
+func TestCacheNegativeDoesNotClobberValue(t *testing.T) {
+	c := NewCache(16)
+	c.Set("k", []byte("good"), time.Minute, time.Minute)
+	c.SetNegative("k", negativeTTL)
+
+	if !c.Negative("k") {
+		t.Fatal("Negative(k) = false, want true after SetNegative")
+	}
+	// The negative marker must not have overwritten the real value.
+	v, ok := c.Get("k")
+	if !ok {
+		t.Fatal("Get(k) lost the good value after SetNegative")
+	}
+	if string(v.([]byte)) != "good" {
+		t.Fatalf("Get(k) = %q, want %q", v, "good")
+	}
+	if c.Negative("absent") {
+		t.Fatal("Negative(absent) = true, want false")
+	}
+}
+
+// upstreamStub is a counting httptest upstream with a settable response.
+type upstreamStub struct {
+	srv    *httptest.Server
+	hits   int32
+	status int
+	body   string
+}
+
+func newUpstreamStub(status int, body string) *upstreamStub {
+	u := &upstreamStub{status: status, body: body}
+	u.srv = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		atomic.AddInt32(&u.hits, 1)
+		w.WriteHeader(u.status)
+		_, _ = w.Write([]byte(u.body))
+	}))
+	return u
+}
+
+func (u *upstreamStub) hitCount() int32 { return atomic.LoadInt32(&u.hits) }
+func (u *upstreamStub) close()          { u.srv.Close() }
+
+func TestPassthroughBlankBodyNotCached(t *testing.T) {
+	up := newUpstreamStub(http.StatusOK, "   \n  ") // 200 but whitespace-only
+	defer up.close()
+	s := NewServer()
+
+	degradedCalled := false
+	rec := httptest.NewRecorder()
+	s.passthrough(rec, "blank-key", up.srv.URL, "application/json", "public, max-age=300",
+		nil, time.Minute, time.Minute,
+		func(w http.ResponseWriter, err error) {
+			degradedCalled = true
+			writeJSON(w, http.StatusOK, "", map[string]any{"degraded": true})
+		})
+
+	if !degradedCalled {
+		t.Fatal("degraded callback was not invoked for a blank 200")
+	}
+	if got := rec.Header().Get("Cache-Control"); got != "no-store" {
+		t.Fatalf("degraded Cache-Control = %q, want no-store", got)
+	}
+	if _, ok := s.cache.Get("blank-key"); ok {
+		t.Fatal("blank body was cached as a value (poisoned)")
+	}
+	if !s.cache.Negative("blank-key") {
+		t.Fatal("blank body did not set a negative-cache marker")
+	}
+}
+
+func TestPassthroughNegativeCacheSkipsUpstream(t *testing.T) {
+	up := newUpstreamStub(http.StatusOK, "") // empty 200
+	defer up.close()
+	s := NewServer()
+
+	degraded := func(w http.ResponseWriter, err error) {
+		writeJSON(w, http.StatusOK, "", map[string]any{"degraded": true})
+	}
+	call := func() {
+		rec := httptest.NewRecorder()
+		s.passthrough(rec, "neg-key", up.srv.URL, "application/json", "public, max-age=300",
+			nil, time.Minute, time.Minute, degraded)
+	}
+	call() // fetches, sees blank, sets negative
+	call() // within negative window: must NOT hit upstream again
+
+	if got := up.hitCount(); got != 1 {
+		t.Fatalf("upstream hit %d times, want 1 (negative cache should short-circuit)", got)
+	}
+}
+
+func TestPassthroughBlankServesStale(t *testing.T) {
+	up := newUpstreamStub(http.StatusOK, "") // empty 200
+	defer up.close()
+	s := NewServer()
+
+	// Prime a last-good body that is already past its fresh horizon but still
+	// inside the stale window (deterministic: negative fresh ttl).
+	s.cache.Set("stale-key", []byte(`{"good":true}`), -time.Second, time.Minute)
+
+	rec := httptest.NewRecorder()
+	degradedCalled := false
+	s.passthrough(rec, "stale-key", up.srv.URL, "application/json", "public, max-age=300",
+		nil, time.Minute, time.Minute,
+		func(w http.ResponseWriter, err error) {
+			degradedCalled = true
+			writeJSON(w, http.StatusOK, "", map[string]any{"degraded": true})
+		})
+
+	if degradedCalled {
+		t.Fatal("degraded fired even though a stale body was available")
+	}
+	if body := rec.Body.String(); body != `{"good":true}` {
+		t.Fatalf("served body = %q, want the stale last-good body", body)
+	}
+}
+
+func TestPassthroughGoodBodyCachedNormally(t *testing.T) {
+	up := newUpstreamStub(http.StatusOK, `{"ok":true}`)
+	defer up.close()
+	s := NewServer()
+
+	rec := httptest.NewRecorder()
+	s.passthrough(rec, "good-key", up.srv.URL, "application/json", "public, max-age=300",
+		nil, time.Minute, time.Minute,
+		func(w http.ResponseWriter, err error) { t.Fatal("degraded fired for a good 200") })
+
+	if got := rec.Header().Get("Cache-Control"); got != "public, max-age=300" {
+		t.Fatalf("good Cache-Control = %q, want the fresh policy", got)
+	}
+	v, ok := s.cache.Get("good-key")
+	if !ok || string(v.([]byte)) != `{"ok":true}` {
+		t.Fatalf("good body was not cached; got %v ok=%v", v, ok)
+	}
+	if s.cache.Negative("good-key") {
+		t.Fatal("a good 200 set a negative-cache marker")
+	}
+}

internal/world/cache_warmer.go

@@ -0,0 +1,86 @@
+package world
+
+import (
+	"context"
+	"time"
+)
+
+// Boot cache warmer: keeps the hottest GDELT-backed cache keys warm so the
+// request path serves a fresh hit instead of blocking ~10s on a cold GDELT
+// fetch when a key's 5m TTL lapses.
+//
+// The hot keys are the ones the SPA hits on every load: the analyst grounding
+// snapshot (gdelt-doc query=world) and the protests panel (gdelt-geo default).
+// Each pod warms its OWN in-memory cache (unlike the shared hanzo-kv feed cache,
+// there is no cross-pod copy to reuse), on boot and every ~4min — just under the
+// TTL, so a key is refreshed before it can expire. GDELT rate-limits callers to
+// one request per ~5s, so the specs are walked sequentially with gdeltPace gaps.
+const cacheWarmInterval = 4 * time.Minute
+
+// warmSpec is one hot cache key. warm re-produces its value under the exact key
+// the handler reads (via the shared key/produce helpers in handlers_news.go).
+type warmSpec struct {
+	name string
+	warm func(ctx context.Context) error
+}
+
+// warmSpecs is the table of hot keys, each wired to the same produce path and
+// key strings its handler uses so warmer and handler can never drift.
+func (s *Server) warmSpecs() []warmSpec {
+	return []warmSpec{
+		{"gdelt-doc query=world", func(ctx context.Context) error {
+			v, err := s.produceGDELTDoc(ctx, "world", "72h", 8)
+			if err != nil {
+				return err
+			}
+			s.cache.Set(gdeltDocKey("world", 8, "72h"), v, gdeltTTL, gdeltStale)
+			return nil
+		}},
+		{"gdelt-geo query=protest", func(ctx context.Context) error {
+			key := gdeltGeoKey("protest", "geojson", 250, "7d")
+			_, err := s.fetchAndCache(ctx, key, gdeltGeoURL("protest", "geojson", 250, "7d"), nil, gdeltTTL, gdeltStale)
+			return err
+		}},
+	}
+}
+
+// startCacheWarmer launches the warmer loop until ctx is cancelled: it warms
+// once shortly after boot then on the jittered interval.
+func (s *Server) startCacheWarmer(ctx context.Context) {
+	go func() {
+		s.warmCaches(ctx)
+		for {
+			select {
+			case <-ctx.Done():
+				return
+			case <-time.After(jitter(cacheWarmInterval)):
+				s.warmCaches(ctx)
+			}
+		}
+	}()
+}
+
+// warmCaches (re)produces every hot key sequentially, each independently
+// bounded, with GDELT pacing between them. A failure is logged and skipped; the
+// next cycle retries and the stale value keeps serving in the meantime.
+func (s *Server) warmCaches(ctx context.Context) {
+	specs := s.warmSpecs()
+	for i, spec := range specs {
+		if ctx.Err() != nil {
+			return
+		}
+		wctx, cancel := context.WithTimeout(ctx, 24*time.Second)
+		err := spec.warm(wctx)
+		cancel()
+		if err != nil {
+			logf("world-warm: %s failed: %v", spec.name, err)
+		}
+		if i < len(specs)-1 {
+			select {
+			case <-ctx.Done():
+				return
+			case <-time.After(gdeltPace):
+			}
+		}
+	}
+}

internal/world/cloud_identity.go

@@ -0,0 +1,106 @@
+package world
+
+import (
+	"context"
+	"net/http"
+	"strings"
+	"time"
+)
+
+// Admin gate for the sensitive half of the Cloud tab.
+//
+// world.hanzo.ai's SaaS/Cloud view is public by design (the "excitement layer":
+// platform scale, global reach, public-chain activity — all non-sensitive). The
+// DEEP, operator-only panels (cross-fleet utilization, per-service internals,
+// exact web analytics, per-org LLM spend) are admin-only and MUST be enforced
+// server-side, not merely hidden in the client.
+//
+// The rule mirrors the cloud gateway's SanitizeIdentity decision
+// (~/work/hanzo/cloud/middleware_identity.go:194): a caller is a global admin iff
+// their IAM `owner` claim is an admin org (globalAdminOrgs = admin,built-in). The
+// world binary does not front the gateway, so we resolve the owner claim straight
+// from IAM's userinfo (IAM-signed, authoritative) rather than trusting any
+// client-supplied header. Fail-closed: no token → 401; any introspection failure
+// or non-admin owner → 403. The caller's bearer is returned to forward upstream,
+// where cloud independently re-verifies — defense in depth.
+
+// adminOrgs is the set of IAM owner claims world treats as a global admin: the
+// base {admin, built-in} (in sync with the cloud deploy's globalAdminOrgs) plus the
+// deployment's OPERATOR org, so the seeded superuser (z@hanzo.ai, owner "hanzo")
+// sees the full internal dashboard. Override per deployment with WORLD_ADMIN_ORGS
+// (comma-separated); unset defaults the operator org to "hanzo". The upstream cloud
+// subsystems independently re-verify the bearer, so this gate only decides which
+// callers world will ATTEMPT the full/admin reads for — never the final authz.
+func adminOrgs() map[string]bool {
+	m := map[string]bool{"admin": true, "built-in": true}
+	extra := env("WORLD_ADMIN_ORGS")
+	if extra == "" {
+		extra = "hanzo" // operator org: z@hanzo.ai is the seeded superuser
+	}
+	for _, o := range strings.Split(extra, ",") {
+		if o = strings.TrimSpace(o); o != "" {
+			m[o] = true
+		}
+	}
+	return m
+}
+
+// isAdminOrg reports whether an owner claim is one of the admin orgs.
+func isAdminOrg(owner string) bool { return adminOrgs()[strings.TrimSpace(owner)] }
+
+// apiHost returns the api.hanzo.ai origin (no /v1 suffix) that the cloud
+// subsystems are served from. HANZO_AI_BASE may legitimately carry a /v1 suffix
+// (it is the OpenAI-compatible base); strip it so subsystem paths like
+// /v1/machines compose correctly.
+func apiHost() string {
+	b := env("HANZO_API_BASE", "HANZO_AI_BASE")
+	if b == "" {
+		b = "https://api.hanzo.ai"
+	}
+	b = trimSlash(b)
+	return strings.TrimSuffix(b, "/v1")
+}
+
+// iamIssuer is the OIDC issuer used for userinfo introspection.
+func iamIssuer() string {
+	if v := env("HANZO_IAM_ISSUER"); v != "" {
+		return trimSlash(v)
+	}
+	return "https://hanzo.id"
+}
+
+// adminIdentity is the NON-writing admin probe: it returns the caller's bearer and
+// true iff a valid IAM identity resolves to an admin-org owner. It short-circuits
+// (no IAM call) when the request carries no bearer, so anonymous requests stay cheap.
+// Used by endpoints that have a public fallback (cloud-pulse): they upgrade to the
+// full admin view when the caller is an admin, and otherwise serve the public path.
+func (s *Server) adminIdentity(r *http.Request) (string, bool) {
+	bearer := userBearer(r)
+	if bearer == "" {
+		return "", false
+	}
+	ctx, cancel := context.WithTimeout(r.Context(), 10*time.Second)
+	defer cancel()
+	id, err := s.introspectIdentity(ctx, bearer)
+	if err != nil || !isAdminOrg(id.Org) {
+		return "", false
+	}
+	return bearer, true
+}
+
+// requireAdmin gates an admin-ONLY Cloud endpoint (no public fallback). It returns
+// the caller's bearer (to forward upstream) and true only for a validated admin-org
+// owner; otherwise it writes the fail-closed response (401 without a token, 403
+// otherwise) and returns false. Every admin handler calls this after preflight.
+func (s *Server) requireAdmin(w http.ResponseWriter, r *http.Request) (string, bool) {
+	if userBearer(r) == "" {
+		writeError(w, http.StatusUnauthorized, "Sign in required")
+		return "", false
+	}
+	bearer, ok := s.adminIdentity(r)
+	if !ok {
+		writeError(w, http.StatusForbidden, "Admin only — sign in with the admin org")
+		return "", false
+	}
+	return bearer, true
+}

internal/world/cloud_service.go

@@ -0,0 +1,161 @@
+package world
+
+import (
+	"context"
+	"errors"
+	"time"
+)
+
+// Service-plane access to the Hanzo Cloud (api.hanzo.ai) — the ONE place that
+// knows how world authenticates as a platform service and reads the platform-wide
+// aggregates the public dashboard surfaces (cloud-pulse volume, ai-pulse,
+// enso-training). Org-scoped drill-down never comes through here: those panels
+// call api.hanzo.ai directly with the CALLER's IAM bearer (see cloud-pulse.ts).
+//
+// One credential, one base. The service token is the repo's established,
+// KMS-injected bearer (kms.go's fetch list) — it is NEVER sent to the browser.
+// All aggregate reads share it, so there is exactly one secret for ops to
+// provision. For the platform-wide reads (get-cloud-usages ?org=all and the
+// routing-ledger exports) it must be a super-admin bearer; a non-admin token
+// 4xxes upstream and every caller degrades to its honest demo/unavailable state.
+
+// errNoServiceToken is returned by the service-plane readers when no service
+// token is configured, so callers keep their honest degrade instead of faking.
+var errNoServiceToken = errors.New("world: no service token configured")
+
+// serviceToken returns the platform service bearer (KMS-injected). Empty ⇒ every
+// service-side aggregate read degrades to demo/unavailable. Never exposed to the
+// browser.
+func serviceToken() string { return env("HANZO_CLOUD_PULSE_TOKEN") }
+
+// serviceAuth is the Authorization header map for a service-side call, or nil
+// when no service token is configured (so callers short-circuit to their demo
+// path).
+func serviceAuth() map[string]string {
+	tok := serviceToken()
+	if tok == "" {
+		return nil
+	}
+	return map[string]string{"Authorization": "Bearer " + tok}
+}
+
+// ── platform usage ledger (ai GET /v1/get-cloud-usages) ───────────────────────
+
+// cloudUsageOverview decodes the fields world aggregates from ai's
+// object.CloudUsageOverview. The upstream is ClickHouse-backed; ?org=all is the
+// platform-wide view and requires a super-admin bearer.
+type cloudUsageOverview struct {
+	Range    string                  `json:"range"`
+	Interval string                  `json:"interval"`
+	Totals   cloudUsageTotals        `json:"totals"`
+	Series   []cloudUsageSeriesPoint `json:"series"`
+	ByModel  cloudUsageByModel       `json:"byModel"`
+}
+
+type cloudUsageTotals struct {
+	Tokens     int64 `json:"tokens"`
+	Requests   int64 `json:"requests"`
+	SpendCents int64 `json:"spendCents"`
+	Models     int64 `json:"models"`
+}
+
+type cloudUsageSeriesPoint struct {
+	T          string `json:"t"`
+	Tokens     int64  `json:"tokens"`
+	SpendCents int64  `json:"spendCents"`
+	Requests   int64  `json:"requests"`
+}
+
+type cloudUsageModelSpend struct {
+	Model      string  `json:"model"`
+	SpendCents int64   `json:"spendCents"`
+	Tokens     int64   `json:"tokens"`
+	Requests   int64   `json:"requests"`
+	Pct        float64 `json:"pct"` // share of total spend, 0..100
+}
+
+type cloudUsageByModel struct {
+	Items []cloudUsageModelSpend `json:"items"`
+}
+
+// fetchCloudUsage reads the platform-wide usage overview (?org=all) for a range
+// label ("24h" | "7d" | "30d") using the supplied auth header — the KMS service
+// bearer (public path) or the signed-in admin's OWN bearer (the flagship admin
+// path). Either way the upstream independently authorizes ?org=all (super-admin),
+// so a non-admin bearer 4xxes and the caller keeps its honest fallback. Returns
+// errNoServiceToken when no auth is available at all.
+func (s *Server) fetchCloudUsage(ctx context.Context, rangeLabel string, hdr map[string]string) (*cloudUsageOverview, error) {
+	if hdr == nil {
+		return nil, errNoServiceToken
+	}
+	var ov cloudUsageOverview
+	url := apiHost() + "/v1/get-cloud-usages?org=all&range=" + rangeLabel
+	if err := s.getJSON(ctx, url, hdr, &ov); err != nil {
+		return nil, err
+	}
+	return &ov, nil
+}
+
+// intervalSeconds resolves the usage-series bucket width to seconds; 0 when
+// unresolvable so callers fall back to a window average instead of dividing by a
+// bogus interval. The upstream get-cloud-usages emits the width as a WORD enum
+// ("hour"/"day"/"minute"), NOT a Go duration — time.ParseDuration fails on those
+// ("hour" needs to be "1h"), which silently forced usageRate to the flat 24h mean
+// (the "AI Compute usage is dead flat" bug). Handle the enum first, then still
+// accept a real duration string for any caller that sends one.
+func intervalSeconds(d string) float64 {
+	switch d {
+	case "":
+		return 0
+	case "minute":
+		return 60
+	case "hour":
+		return 3600
+	case "day":
+		return 86400
+	case "week":
+		return 604800
+	}
+	v, err := time.ParseDuration(d)
+	if err != nil || v <= 0 {
+		return 0
+	}
+	return v.Seconds()
+}
+
+// usageRate returns the freshest honest per-second rate for a metric: the most
+// recent complete series bucket over its interval, falling back to the 24h
+// average when there is no usable interval/series. sel picks the metric from a
+// bucket. Shared by cloud-pulse and ai-pulse so the rate is derived one way.
+func usageRate(total24h int64, series []cloudUsageSeriesPoint, interval string, sel func(cloudUsageSeriesPoint) int64) float64 {
+	if n := len(series); n > 0 {
+		if iv := intervalSeconds(interval); iv > 0 {
+			return float64(sel(series[n-1])) / iv
+		}
+	}
+	const windowSecs = 86400.0
+	return float64(total24h) / windowSecs
+}
+
+// seriesRequests / seriesTokens are the bucket selectors for usageRate.
+func seriesRequests(p cloudUsageSeriesPoint) int64 { return p.Requests }
+func seriesTokens(p cloudUsageSeriesPoint) int64   { return p.Tokens }
+
+// topModelsFromUsage maps the ledger's ranked byModel spend into the shared
+// cloudModel shape (share normalized 0..1). nil when the ledger listed none.
+func topModelsFromUsage(ov *cloudUsageOverview) []cloudModel {
+	if len(ov.ByModel.Items) == 0 {
+		return nil
+	}
+	out := make([]cloudModel, 0, len(ov.ByModel.Items))
+	for _, m := range ov.ByModel.Items {
+		out = append(out, cloudModel{
+			ID:          m.Model,
+			Name:        m.Model,
+			Requests24h: m.Requests,
+			Tokens24h:   m.Tokens,
+			Share:       m.Pct / 100,
+		})
+	}
+	return out
+}

internal/world/cloud_service_test.go

@@ -0,0 +1,40 @@
+package world
+
+import "testing"
+
+// TestIntervalSeconds guards the "AI Compute usage is dead flat" regression: the
+// upstream usage series reports its bucket width as a WORD enum ("hour"/"day"), not a
+// Go duration, so time.ParseDuration failed and usageRate silently fell back to the
+// flat 24h mean. intervalSeconds must resolve the enums (and still accept a real
+// duration string).
+func TestIntervalSeconds(t *testing.T) {
+	cases := map[string]float64{
+		"minute": 60,
+		"hour":   3600,
+		"day":    86400,
+		"week":   604800,
+		"1h":     3600, // real Go-duration string still works
+		"30m":    1800,
+		"":       0, // unresolvable → 0 (caller falls back to window average)
+		"nope":   0,
+	}
+	for in, want := range cases {
+		if got := intervalSeconds(in); got != want {
+			t.Errorf("intervalSeconds(%q) = %v, want %v", in, got, want)
+		}
+	}
+}
+
+// TestUsageRate proves the freshest-bucket rate is used when the interval resolves
+// (the fix), and the 24h average is used only when it can't.
+func TestUsageRate(t *testing.T) {
+	series := []cloudUsageSeriesPoint{{Requests: 100}, {Requests: 720}} // last bucket = 720
+	// "hour" now resolves to 3600s → 720/3600 = 0.2 rps (fresh), NOT 999999/86400.
+	if got := usageRate(999999, series, "hour", seriesRequests); got != 720.0/3600.0 {
+		t.Errorf("usageRate(hour) = %v, want %v (fresh bucket, not 24h mean)", got, 720.0/3600.0)
+	}
+	// Unresolvable interval → 24h average.
+	if got := usageRate(86400, series, "", seriesRequests); got != 1.0 {
+		t.Errorf("usageRate(empty interval) = %v, want 1.0 (24h average)", got)
+	}
+}

internal/world/cloud_users.go

@@ -0,0 +1,84 @@
+package world
+
+import (
+	"context"
+	"time"
+)
+
+// Platform user metrics — REAL signups / active users from Hanzo IAM (Casdoor).
+//
+// Source: IAM GET /v1/iam/global-users (every user across every org; global-admin
+// only). We read it with the signed-in admin's OWN bearer (never a shared key),
+// fold it into NON-sensitive aggregates (counts + a daily-signup series), and return
+// ONLY those aggregates — no user record, email, name or other PII ever leaves this
+// function. Honest-empty (error) when the caller is not a global admin upstream or
+// IAM is unreachable, so the overview simply omits the user tiles rather than guess.
+
+type userMetrics struct {
+	Total        int     `json:"total"`
+	Signups24h   int     `json:"signups24h"`
+	Signups7d    int     `json:"signups7d"`
+	ActiveNow    int     `json:"activeNow"`
+	SignupSeries []int64 `json:"signupSeries"` // new users/day, last 14 days, chronological
+}
+
+// iamUser is the minimal, non-PII slice of Casdoor's object.User we read.
+type iamUser struct {
+	CreatedTime string `json:"createdTime"`
+	IsOnline    bool   `json:"isOnline"`
+	IsDeleted   bool   `json:"isDeleted"`
+}
+
+const userSignupDays = 14
+
+// fetchUserMetrics reads the platform-wide user list from IAM with auth and folds it
+// into non-sensitive aggregates. Requires a global-admin bearer upstream; any error
+// (non-admin, unreachable) leaves the caller to omit the tiles honestly — never a
+// fabricated count.
+func (s *Server) fetchUserMetrics(ctx context.Context, auth map[string]string) (*userMetrics, error) {
+	if auth == nil {
+		return nil, errNoServiceToken
+	}
+	var users []iamUser
+	if err := s.getJSON(ctx, iamIssuer()+"/v1/iam/global-users", auth, &users); err != nil {
+		return nil, err
+	}
+	now := time.Now().UTC()
+	m := &userMetrics{SignupSeries: make([]int64, userSignupDays)}
+	for _, u := range users {
+		if u.IsDeleted {
+			continue
+		}
+		m.Total++
+		if u.IsOnline {
+			m.ActiveNow++
+		}
+		t, ok := parseUserTime(u.CreatedTime)
+		if !ok {
+			continue
+		}
+		if age := now.Sub(t); age >= 0 {
+			if age <= 24*time.Hour {
+				m.Signups24h++
+			}
+			if age <= 7*24*time.Hour {
+				m.Signups7d++
+			}
+			if d := int(age.Hours() / 24); d < userSignupDays {
+				m.SignupSeries[userSignupDays-1-d]++ // chronological: oldest bucket first, today last
+			}
+		}
+	}
+	return m, nil
+}
+
+// parseUserTime parses Casdoor's createdTime (RFC3339, with a couple of legacy
+// fallbacks). ok=false when unparseable so a bad row is skipped, never guessed.
+func parseUserTime(s string) (time.Time, bool) {
+	for _, layout := range []string{time.RFC3339, time.RFC3339Nano, "2006-01-02 15:04:05"} {
+		if t, err := time.Parse(layout, s); err == nil {
+			return t.UTC(), true
+		}
+	}
+	return time.Time{}, false
+}

internal/world/coerce.go

@@ -0,0 +1,61 @@
+package world
+
+import (
+	"bytes"
+	"encoding/json"
+	"strconv"
+)
+
+// Several upstreams (ACLED, UCDP, World Bank, HAPI) emit numeric fields
+// inconsistently as JSON numbers or quoted strings. Decoding into map[string]any
+// with UseNumber and coercing per-field is the DRY way to stay faithful without
+// a bespoke struct per upstream quirk.
+
+// decodeNumber unmarshals body into v with numbers preserved as json.Number.
+func decodeNumber(body []byte, v any) error {
+	dec := json.NewDecoder(bytes.NewReader(body))
+	dec.UseNumber()
+	return dec.Decode(v)
+}
+
+func asString(v any) string {
+	switch t := v.(type) {
+	case string:
+		return t
+	case json.Number:
+		return t.String()
+	case float64:
+		return strconv.FormatFloat(t, 'f', -1, 64)
+	case bool:
+		return strconv.FormatBool(t)
+	case nil:
+		return ""
+	default:
+		return ""
+	}
+}
+
+func asFloat(v any) float64 {
+	switch t := v.(type) {
+	case json.Number:
+		f, _ := t.Float64()
+		return f
+	case float64:
+		return t
+	case string:
+		f, _ := strconv.ParseFloat(t, 64)
+		return f
+	default:
+		return 0
+	}
+}
+
+func asInt(v any) int { return int(asFloat(v)) }
+
+// mapGet safely reads a key from a decoded object.
+func mapGet(m map[string]any, key string) any {
+	if m == nil {
+		return nil
+	}
+	return m[key]
+}

internal/world/data/analyst_commands.json

@@ -0,0 +1,349 @@
+[
+  {
+    "name": "show_panel",
+    "description": "Show a hidden dashboard panel by its key.",
+    "params": {
+      "type": "object",
+      "properties": {
+        "key": {
+          "type": "string",
+          "description": "panel key exactly as it appears in the snapshot"
+        }
+      },
+      "required": [
+        "key"
+      ]
+    },
+    "authed": false
+  },
+  {
+    "name": "hide_panel",
+    "description": "Hide a visible dashboard panel by its key.",
+    "params": {
+      "type": "object",
+      "properties": {
+        "key": {
+          "type": "string",
+          "description": "panel key"
+        }
+      },
+      "required": [
+        "key"
+      ]
+    },
+    "authed": false
+  },
+  {
+    "name": "move_panel",
+    "description": "Reorder a panel: to the top/bottom, or before/after another panel.",
+    "params": {
+      "type": "object",
+      "properties": {
+        "key": {
+          "type": "string",
+          "description": "panel to move"
+        },
+        "position": {
+          "type": "string",
+          "enum": [
+            "top",
+            "bottom"
+          ],
+          "description": "move to the top or bottom"
+        },
+        "before": {
+          "type": "string",
+          "description": "place above this panel key"
+        },
+        "after": {
+          "type": "string",
+          "description": "place below this panel key"
+        }
+      },
+      "required": [
+        "key"
+      ]
+    },
+    "authed": false
+  },
+  {
+    "name": "resize_panel",
+    "description": "Set a panel height in grid rows (1 = short, 4 = tall).",
+    "params": {
+      "type": "object",
+      "properties": {
+        "key": {
+          "type": "string",
+          "description": "panel key"
+        },
+        "span": {
+          "type": "integer",
+          "description": "height in rows, 1-4",
+          "minimum": 1,
+          "maximum": 4
+        }
+      },
+      "required": [
+        "key",
+        "span"
+      ]
+    },
+    "authed": false
+  },
+  {
+    "name": "toggle_layer",
+    "description": "Turn a map data layer on or off by its key.",
+    "params": {
+      "type": "object",
+      "properties": {
+        "key": {
+          "type": "string",
+          "description": "map layer key"
+        },
+        "on": {
+          "type": "boolean",
+          "description": "true to enable, false to disable"
+        }
+      },
+      "required": [
+        "key",
+        "on"
+      ]
+    },
+    "authed": false
+  },
+  {
+    "name": "set_map_mode",
+    "description": "Switch the map between 2D flat and 3D globe.",
+    "params": {
+      "type": "object",
+      "properties": {
+        "mode": {
+          "type": "string",
+          "enum": [
+            "2d",
+            "3d"
+          ],
+          "description": "2d flat map or 3d globe"
+        }
+      },
+      "required": [
+        "mode"
+      ]
+    },
+    "authed": false
+  },
+  {
+    "name": "fly_to",
+    "description": "Move the map camera to a latitude/longitude, optionally at a zoom (1-12).",
+    "params": {
+      "type": "object",
+      "properties": {
+        "lat": {
+          "type": "number",
+          "description": "latitude",
+          "minimum": -90,
+          "maximum": 90
+        },
+        "lon": {
+          "type": "number",
+          "description": "longitude",
+          "minimum": -180,
+          "maximum": 180
+        },
+        "zoom": {
+          "type": "number",
+          "description": "zoom level 1-12",
+          "minimum": 0,
+          "maximum": 20
+        }
+      },
+      "required": [
+        "lat",
+        "lon"
+      ]
+    },
+    "authed": false
+  },
+  {
+    "name": "set_region",
+    "description": "Jump the map to a named region preset.",
+    "params": {
+      "type": "object",
+      "properties": {
+        "region": {
+          "type": "string",
+          "enum": [
+            "global",
+            "america",
+            "mena",
+            "eu",
+            "asia",
+            "latam",
+            "africa",
+            "oceania"
+          ],
+          "description": "region preset"
+        }
+      },
+      "required": [
+        "region"
+      ]
+    },
+    "authed": false
+  },
+  {
+    "name": "set_time_range",
+    "description": "Set the global time window for the map and feeds.",
+    "params": {
+      "type": "object",
+      "properties": {
+        "range": {
+          "type": "string",
+          "enum": [
+            "1h",
+            "6h",
+            "24h",
+            "48h",
+            "7d",
+            "all"
+          ],
+          "description": "time window"
+        }
+      },
+      "required": [
+        "range"
+      ]
+    },
+    "authed": false
+  },
+  {
+    "name": "set_variant",
+    "description": "Switch the dashboard variant (reloads to the chosen view).",
+    "params": {
+      "type": "object",
+      "properties": {
+        "variant": {
+          "type": "string",
+          "enum": [
+            "full",
+            "tech",
+            "finance",
+            "saas",
+            "ai",
+            "crypto"
+          ],
+          "description": "dashboard variant"
+        }
+      },
+      "required": [
+        "variant"
+      ]
+    },
+    "authed": false
+  },
+  {
+    "name": "set_theme",
+    "description": "Switch the colour theme between dark and light.",
+    "params": {
+      "type": "object",
+      "properties": {
+        "theme": {
+          "type": "string",
+          "enum": [
+            "dark",
+            "light"
+          ],
+          "description": "colour theme"
+        }
+      },
+      "required": [
+        "theme"
+      ]
+    },
+    "authed": false
+  },
+  {
+    "name": "search",
+    "description": "Open the global search and run a query (countries, markets, hotspots, …).",
+    "params": {
+      "type": "object",
+      "properties": {
+        "query": {
+          "type": "string",
+          "description": "search text"
+        }
+      },
+      "required": [
+        "query"
+      ]
+    },
+    "authed": false
+  },
+  {
+    "name": "reset_layout",
+    "description": "Reset all panels to the variant default layout (reloads).",
+    "params": {
+      "type": "object",
+      "properties": {},
+      "required": []
+    },
+    "authed": false
+  },
+  {
+    "name": "add_feed_panel",
+    "description": "Add a custom RSS/Atom feed panel (server allowlist enforced).",
+    "params": {
+      "type": "object",
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "short panel title"
+        },
+        "url": {
+          "type": "string",
+          "description": "https RSS/Atom feed URL"
+        }
+      },
+      "required": [
+        "name",
+        "url"
+      ]
+    },
+    "authed": false
+  },
+  {
+    "name": "remove_custom_panel",
+    "description": "Remove a custom feed panel by the title it was added with.",
+    "params": {
+      "type": "object",
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "title used when adding"
+        }
+      },
+      "required": [
+        "name"
+      ]
+    },
+    "authed": false
+  },
+  {
+    "name": "switch_org",
+    "description": "Switch the active organization (reloads scoped data). Sign-in required.",
+    "params": {
+      "type": "object",
+      "properties": {
+        "org": {
+          "type": "string",
+          "description": "organization id from the snapshot"
+        }
+      },
+      "required": [
+        "org"
+      ]
+    },
+    "authed": true
+  }
+]

internal/world/datastore.go

@@ -0,0 +1,124 @@
+package world
+
+import (
+	"context"
+	"encoding/json"
+	"time"
+
+	"github.com/hanzoai/world/internal/world/kv"
+	"github.com/hanzoai/world/internal/world/model"
+	"github.com/hanzoai/world/internal/world/store"
+)
+
+// datastore.go wires world's three storage concerns onto the Server and owns
+// their lifecycle, keeping each in its lane:
+//   - hanzo-kv (shared hot cache)  → instant feed bodies (FeedCache L2)
+//   - embedded SQLite (lake)       → the searchable "one place to query everything"
+//   - embedded SQLite (settings)   → signed-in per-identity dashboard sync
+//
+// Everything degrades cleanly: no hanzo-kv → per-pod in-mem feed cache; no
+// SQLite → search/analytics return empty and settings say "not stored". The
+// service never 5xxes over storage.
+
+// kvAddr is the hanzo-kv endpoint. Defaults to the in-cluster Service; set empty
+// (WORLD_KV_DISABLE=1) to force the pure in-mem path (local dev / CI).
+func kvAddr() string {
+	if env("WORLD_KV_DISABLE") != "" {
+		return ""
+	}
+	if a := env("HANZO_KV_ADDR", "WORLD_KV_ADDR"); a != "" {
+		return a
+	}
+	return "hanzo-kv:6379"
+}
+
+// kvPassword is optional — hanzo-kv currently requires none; the hook is here for
+// a future KMS-provisioned password (HANZO_KV_PASSWORD / world-secrets).
+func kvPassword() string { return env("HANZO_KV_PASSWORD", "WORLD_KV_PASSWORD") }
+
+// lakeRetention is the rolling window ingested items are kept for.
+func lakeRetention() time.Duration {
+	if v := env("WORLD_LAKE_RETENTION"); v != "" {
+		if d, err := time.ParseDuration(v); err == nil && d > 0 {
+			return d
+		}
+	}
+	return store.DefaultRetention
+}
+
+// initDatastore opens hanzo-kv + the embedded SQLite datastore and builds the
+// two-tier feed cache. Called once from NewServer; never fails hard.
+func (s *Server) initDatastore() {
+	s.kv = kv.Open(kvAddr(), kvPassword())
+
+	db, err := store.Open(modelDataDir(), lakeRetention())
+	if err != nil {
+		logf("world-store: degraded (no durable lake/settings): %v", err)
+	}
+	s.store = db
+	s.feeds = NewFeedCache(s.kv, 0, curatedFeedSeed)
+
+	// The world model dumps its folded observations into the lake so model state
+	// is queryable alongside news — the engine stays decomplected from storage,
+	// it just calls this sink.
+	s.worldModel.SetObservationSink(s.ingestObservations)
+}
+
+// StartDatastore starts the background loops: the lake write-behind/prune
+// consumer and the feed warmer. Call once from main after the server is built.
+func (s *Server) StartDatastore(ctx context.Context) {
+	if s.kv.Enabled() {
+		pctx, cancel := context.WithTimeout(ctx, 3*time.Second)
+		if err := s.kv.Ping(pctx); err != nil {
+			logf("world-kv: %s unreachable, using per-pod in-mem cache: %v", kvAddr(), err)
+		} else {
+			logf("world-kv: connected to %s (shared feed cache)", kvAddr())
+		}
+		cancel()
+	} else {
+		logf("world-kv: disabled, using per-pod in-mem feed cache")
+	}
+	go s.store.Lake.Run(ctx)
+	s.startFeedWarmer(ctx)
+	s.startCacheWarmer(ctx)
+}
+
+// Close releases the datastore handles. Safe to call once on shutdown.
+func (s *Server) Close() {
+	if s.kv != nil {
+		s.kv.Close()
+	}
+	if s.store != nil {
+		_ = s.store.Close()
+	}
+}
+
+// ingestObservations folds one cycle of world-model observations into the lake
+// (kind=observation), keyed so each entity+source keeps its latest value. This
+// is the model half of "dump ALL ingested data into the datastore".
+func (s *Server) ingestObservations(obs []model.Observation) {
+	if s.store == nil {
+		return
+	}
+	now := time.Now().UTC()
+	for _, o := range obs {
+		country := ""
+		if o.Kind == model.KindCountry {
+			country = o.ID
+		}
+		payload, _ := json.Marshal(map[string]any{
+			"id": o.ID, "kind": o.Kind, "name": o.Name,
+			"metrics": o.Metrics, "note": o.Note, "src": o.Src,
+		})
+		s.store.Lake.Add(store.Item{
+			ID:      "obs:" + o.Kind + ":" + o.ID + ":" + o.Src,
+			Kind:    "observation",
+			Source:  o.Src,
+			TS:      now,
+			Title:   o.Name,
+			Text:    o.Note,
+			Country: country,
+			Payload: string(payload),
+		})
+	}
+}

internal/world/enrich.go

@@ -0,0 +1,257 @@
+package world
+
+import (
+	_ "embed"
+	"encoding/json"
+	"log"
+	"regexp"
+	"sort"
+	"strings"
+	"sync"
+)
+
+// Server-side news enrichment: threat classification + geo inference.
+//
+// This is the Go-native home for work the browser used to do on every client,
+// on every render. The keyword tables and geo hubs are DATA (enrichdata/*.json)
+// — one source of truth, embedded here and imported by the frontend, so the two
+// runtimes can never drift. enrich_test.go proves byte-for-byte parity with the
+// TypeScript implementation over an exhaustive 494-case corpus.
+//
+// Two parity traps, both handled deliberately:
+//   - JS object key order IS the match priority (first match wins). Go maps are
+//     unordered, so the tables stay ORDERED SLICES.
+//   - JS Array.sort is stable. Go's sort.Slice is not — geo matches use
+//     sort.SliceStable so equal-confidence hubs keep index order.
+
+//go:embed enrichdata/threat-keywords.json
+var threatKeywordsJSON []byte
+
+//go:embed enrichdata/geo-hubs.json
+var geoHubsJSON []byte
+
+// ThreatClassification mirrors the frontend type (services/threat-classifier.ts).
+type ThreatClassification struct {
+	Level      string  `json:"level"`
+	Category   string  `json:"category"`
+	Confidence float64 `json:"confidence"`
+	Source     string  `json:"source"`
+}
+
+// GeoHub is a strategic location an item can be pinned to.
+type GeoHub struct {
+	ID       string   `json:"id"`
+	Name     string   `json:"name"`
+	Region   string   `json:"region"`
+	Country  string   `json:"country"`
+	Lat      float64  `json:"lat"`
+	Lon      float64  `json:"lon"`
+	Type     string   `json:"type"`
+	Tier     string   `json:"tier"`
+	Keywords []string `json:"keywords"`
+}
+
+// GeoMatch is one inferred hub for a headline.
+type GeoMatch struct {
+	HubID          string  `json:"hubId"`
+	Confidence     float64 `json:"confidence"`
+	MatchedKeyword string  `json:"matchedKeyword"`
+}
+
+type keywordEntry struct {
+	Keyword  string `json:"keyword"`
+	Category string `json:"category"`
+}
+
+type threatTier struct {
+	Level      string         `json:"level"`
+	Confidence float64        `json:"confidence"`
+	Variant    string         `json:"variant"` // "any" | "tech"
+	Keywords   []keywordEntry `json:"keywords"`
+}
+
+type threatTables struct {
+	Exclusions    []string     `json:"exclusions"`
+	ShortKeywords []string     `json:"shortKeywords"`
+	Tiers         []threatTier `json:"tiers"`
+}
+
+type enricher struct {
+	tables   threatTables
+	short    map[string]bool
+	res      map[string]*regexp.Regexp // keyword → compiled matcher
+	hubs     []GeoHub
+	hubIndex map[string]*GeoHub
+	// hubKeywords preserves insertion order, matching the JS Map iteration the
+	// frontend index relies on.
+	hubKeywords []hubKeyword
+}
+
+type hubKeyword struct {
+	keyword string
+	hubIDs  []string
+	re      *regexp.Regexp // non-nil only for short keywords (word-boundary)
+}
+
+var (
+	enrichOnce sync.Once
+	enr        *enricher
+)
+
+func enrichEngine() *enricher {
+	enrichOnce.Do(func() {
+		e := &enricher{
+			short:    map[string]bool{},
+			res:      map[string]*regexp.Regexp{},
+			hubIndex: map[string]*GeoHub{},
+		}
+		if err := json.Unmarshal(threatKeywordsJSON, &e.tables); err != nil {
+			log.Printf("world: enrich: threat tables: %v", err)
+		}
+		for _, s := range e.tables.ShortKeywords {
+			e.short[s] = true
+		}
+		// Precompile one matcher per keyword, mirroring getKeywordRegex: short
+		// keywords are word-bounded (so "war" never matches "wardrobe"), the rest
+		// are plain substring matches. Titles are lowercased before matching.
+		for _, tier := range e.tables.Tiers {
+			for _, k := range tier.Keywords {
+				e.res[k.Keyword] = compileKeyword(k.Keyword, e.short[k.Keyword])
+			}
+		}
+
+		var hubData struct {
+			Hubs []GeoHub `json:"hubs"`
+		}
+		if err := json.Unmarshal(geoHubsJSON, &hubData); err != nil {
+			log.Printf("world: enrich: geo hubs: %v", err)
+		}
+		e.hubs = hubData.Hubs
+		seen := map[string]int{} // keyword → index into hubKeywords
+		for i := range e.hubs {
+			h := &e.hubs[i]
+			e.hubIndex[h.ID] = h
+			for _, kw := range h.Keywords {
+				lower := strings.ToLower(kw)
+				if idx, ok := seen[lower]; ok {
+					e.hubKeywords[idx].hubIDs = append(e.hubKeywords[idx].hubIDs, h.ID)
+					continue
+				}
+				seen[lower] = len(e.hubKeywords)
+				var re *regexp.Regexp
+				// The frontend word-bounds geo keywords shorter than 5 chars.
+				if len(lower) < 5 {
+					re = regexp.MustCompile(`\b` + regexp.QuoteMeta(lower) + `\b`)
+				}
+				e.hubKeywords = append(e.hubKeywords, hubKeyword{keyword: lower, hubIDs: []string{h.ID}, re: re})
+			}
+		}
+		enr = e
+	})
+	return enr
+}
+
+func compileKeyword(kw string, short bool) *regexp.Regexp {
+	q := regexp.QuoteMeta(kw)
+	if short {
+		return regexp.MustCompile(`\b` + q + `\b`)
+	}
+	return regexp.MustCompile(q)
+}
+
+// ClassifyByKeyword is the Go port of services/threat-classifier.ts
+// classifyByKeyword. Same priority cascade, same confidences, same categories.
+func ClassifyByKeyword(title, variant string) ThreatClassification {
+	e := enrichEngine()
+	lower := strings.ToLower(title)
+
+	info := ThreatClassification{Level: "info", Category: "general", Confidence: 0.3, Source: "keyword"}
+	for _, ex := range e.tables.Exclusions {
+		if strings.Contains(lower, ex) {
+			return info
+		}
+	}
+	isTech := variant == "tech"
+	for _, tier := range e.tables.Tiers {
+		if tier.Variant == "tech" && !isTech {
+			continue
+		}
+		for _, k := range tier.Keywords {
+			if re := e.res[k.Keyword]; re != nil && re.MatchString(lower) {
+				return ThreatClassification{
+					Level:      tier.Level,
+					Category:   k.Category,
+					Confidence: tier.Confidence,
+					Source:     "keyword",
+				}
+			}
+		}
+	}
+	return info
+}
+
+// InferGeoHubs is the Go port of services/geo-hub-index.ts inferGeoHubsFromTitle:
+// keyword → hub, confidence by keyword length, boosted for conflict/strategic
+// type and critical tier, sorted by confidence (stable).
+func InferGeoHubs(title string) []GeoMatch {
+	e := enrichEngine()
+	lower := strings.ToLower(title)
+	matches := []GeoMatch{}
+	seen := map[string]bool{}
+
+	for _, hk := range e.hubKeywords {
+		if len(hk.keyword) < 2 {
+			continue
+		}
+		found := false
+		if hk.re != nil {
+			found = hk.re.MatchString(lower)
+		} else {
+			found = strings.Contains(lower, hk.keyword)
+		}
+		if !found {
+			continue
+		}
+		for _, id := range hk.hubIDs {
+			if seen[id] {
+				continue
+			}
+			seen[id] = true
+			hub := e.hubIndex[id]
+			if hub == nil {
+				continue
+			}
+			confidence := 0.5
+			switch n := len(hk.keyword); {
+			case n >= 10:
+				confidence = 0.9
+			case n >= 6:
+				confidence = 0.75
+			case n >= 4:
+				confidence = 0.6
+			}
+			if hub.Type == "conflict" || hub.Type == "strategic" {
+				confidence = min1(confidence + 0.1)
+			}
+			if hub.Tier == "critical" {
+				confidence = min1(confidence + 0.1)
+			}
+			matches = append(matches, GeoMatch{HubID: id, Confidence: confidence, MatchedKeyword: hk.keyword})
+		}
+	}
+	// JS Array.sort is stable — equal confidences keep discovery order.
+	sort.SliceStable(matches, func(i, j int) bool { return matches[i].Confidence > matches[j].Confidence })
+	return matches
+}
+
+// GeoHubByID exposes a hub for callers that need its coordinates/name.
+func GeoHubByID(id string) *GeoHub {
+	return enrichEngine().hubIndex[id]
+}
+
+func min1(v float64) float64 {
+	if v > 1 {
+		return 1
+	}
+	return v
+}

internal/world/enrich_test.go

@@ -0,0 +1,111 @@
+package world
+
+import (
+	"encoding/json"
+	"math"
+	"os"
+	"testing"
+)
+
+// Parity: the Go enrichment MUST agree with the TypeScript implementation it
+// replaces, or moving the work server-side would silently change what every
+// user sees. testdata/enrich_golden.json is generated by EVALUATING the real
+// frontend classifier/geo-index (not transcribed) over an exhaustive corpus:
+// every keyword in every tier, both variants, every geo-hub keyword, every
+// exclusion, plus adversarial word-boundary cases ("war" must not match
+// "wardrobe"). Any drift fails here.
+
+type goldenCase struct {
+	Title string               `json:"title"`
+	Full  ThreatClassification `json:"full"`
+	Tech  ThreatClassification `json:"tech"`
+	Geo   []GeoMatch           `json:"geo"`
+}
+
+func loadGolden(t *testing.T) []goldenCase {
+	t.Helper()
+	b, err := os.ReadFile("testdata/enrich_golden.json")
+	if err != nil {
+		t.Fatalf("read golden: %v", err)
+	}
+	var g struct {
+		Cases []goldenCase `json:"cases"`
+	}
+	if err := json.Unmarshal(b, &g); err != nil {
+		t.Fatalf("parse golden: %v", err)
+	}
+	if len(g.Cases) < 400 {
+		t.Fatalf("golden corpus too small (%d) — regenerate it", len(g.Cases))
+	}
+	return g.Cases
+}
+
+func sameClass(a, b ThreatClassification) bool {
+	return a.Level == b.Level && a.Category == b.Category &&
+		a.Source == b.Source && math.Abs(a.Confidence-b.Confidence) < 1e-9
+}
+
+func TestClassifyByKeywordMatchesTypeScript(t *testing.T) {
+	cases := loadGolden(t)
+	bad := 0
+	for _, c := range cases {
+		for _, v := range []struct {
+			variant string
+			want    ThreatClassification
+		}{{"full", c.Full}, {"tech", c.Tech}} {
+			got := ClassifyByKeyword(c.Title, v.variant)
+			if !sameClass(got, v.want) {
+				bad++
+				if bad <= 10 {
+					t.Errorf("classify(%q, %s)\n  got  %+v\n  want %+v", c.Title, v.variant, got, v.want)
+				}
+			}
+		}
+	}
+	if bad > 0 {
+		t.Fatalf("%d/%d classifications diverge from the TypeScript source of truth", bad, len(cases)*2)
+	}
+	t.Logf("parity: %d titles × 2 variants identical to TypeScript", len(cases))
+}
+
+func TestInferGeoHubsMatchesTypeScript(t *testing.T) {
+	cases := loadGolden(t)
+	bad, withGeo := 0, 0
+	for _, c := range cases {
+		got := InferGeoHubs(c.Title)
+		if len(c.Geo) > 0 {
+			withGeo++
+		}
+		if len(got) != len(c.Geo) {
+			bad++
+			if bad <= 10 {
+				t.Errorf("geo(%q): got %d matches, want %d", c.Title, len(got), len(c.Geo))
+			}
+			continue
+		}
+		for i := range got {
+			w := c.Geo[i]
+			if got[i].HubID != w.HubID || got[i].MatchedKeyword != w.MatchedKeyword ||
+				math.Abs(got[i].Confidence-w.Confidence) > 1e-9 {
+				bad++
+				if bad <= 10 {
+					t.Errorf("geo(%q)[%d]\n  got  %+v\n  want %+v", c.Title, i, got[i], w)
+				}
+				break
+			}
+		}
+	}
+	if bad > 0 {
+		t.Fatalf("%d/%d geo inferences diverge from the TypeScript source of truth", bad, len(cases))
+	}
+	t.Logf("parity: %d titles identical to TypeScript (%d carry geo matches)", len(cases), withGeo)
+}
+
+// The adversarial guarantee, asserted directly: short keywords are word-bounded.
+func TestShortKeywordsAreWordBounded(t *testing.T) {
+	for _, title := range []string{"The wardrobe warehouse expands", "Something banned entirely"} {
+		if got := ClassifyByKeyword(title, "full"); got.Level != "info" {
+			t.Errorf("%q classified %s — a short keyword matched inside a longer word", title, got.Level)
+		}
+	}
+}

internal/world/enrichdata/geo-hubs.json

@@ -0,0 +1,691 @@
+{
+  "hubs": [
+    {
+      "id": "washington",
+      "name": "Washington DC",
+      "region": "North America",
+      "country": "USA",
+      "lat": 38.9072,
+      "lon": -77.0369,
+      "type": "capital",
+      "tier": "critical",
+      "keywords": [
+        "washington",
+        "white house",
+        "pentagon",
+        "state department",
+        "congress",
+        "capitol hill",
+        "biden",
+        "trump"
+      ]
+    },
+    {
+      "id": "moscow",
+      "name": "Moscow",
+      "region": "Europe",
+      "country": "Russia",
+      "lat": 55.7558,
+      "lon": 37.6173,
+      "type": "capital",
+      "tier": "critical",
+      "keywords": [
+        "moscow",
+        "kremlin",
+        "putin",
+        "russia",
+        "russian"
+      ]
+    },
+    {
+      "id": "beijing",
+      "name": "Beijing",
+      "region": "Asia",
+      "country": "China",
+      "lat": 39.9042,
+      "lon": 116.4074,
+      "type": "capital",
+      "tier": "critical",
+      "keywords": [
+        "beijing",
+        "xi jinping",
+        "china",
+        "chinese",
+        "ccp",
+        "prc"
+      ]
+    },
+    {
+      "id": "brussels",
+      "name": "Brussels",
+      "region": "Europe",
+      "country": "Belgium",
+      "lat": 50.8503,
+      "lon": 4.3517,
+      "type": "capital",
+      "tier": "critical",
+      "keywords": [
+        "brussels",
+        "eu",
+        "european union",
+        "nato",
+        "european commission"
+      ]
+    },
+    {
+      "id": "london",
+      "name": "London",
+      "region": "Europe",
+      "country": "UK",
+      "lat": 51.5074,
+      "lon": -0.1278,
+      "type": "capital",
+      "tier": "critical",
+      "keywords": [
+        "london",
+        "uk",
+        "britain",
+        "british",
+        "downing street",
+        "parliament"
+      ]
+    },
+    {
+      "id": "jerusalem",
+      "name": "Jerusalem",
+      "region": "Middle East",
+      "country": "Israel",
+      "lat": 31.7683,
+      "lon": 35.2137,
+      "type": "capital",
+      "tier": "major",
+      "keywords": [
+        "jerusalem",
+        "israel",
+        "israeli",
+        "knesset",
+        "netanyahu"
+      ]
+    },
+    {
+      "id": "telaviv",
+      "name": "Tel Aviv",
+      "region": "Middle East",
+      "country": "Israel",
+      "lat": 32.0853,
+      "lon": 34.7818,
+      "type": "capital",
+      "tier": "major",
+      "keywords": [
+        "tel aviv",
+        "idf",
+        "mossad"
+      ]
+    },
+    {
+      "id": "tehran",
+      "name": "Tehran",
+      "region": "Middle East",
+      "country": "Iran",
+      "lat": 35.6892,
+      "lon": 51.389,
+      "type": "capital",
+      "tier": "major",
+      "keywords": [
+        "tehran",
+        "iran",
+        "iranian",
+        "khamenei",
+        "irgc",
+        "ayatollah"
+      ]
+    },
+    {
+      "id": "kyiv",
+      "name": "Kyiv",
+      "region": "Europe",
+      "country": "Ukraine",
+      "lat": 50.4501,
+      "lon": 30.5234,
+      "type": "capital",
+      "tier": "major",
+      "keywords": [
+        "kyiv",
+        "kiev",
+        "ukraine",
+        "ukrainian",
+        "zelensky",
+        "zelenskyy"
+      ]
+    },
+    {
+      "id": "taipei",
+      "name": "Taipei",
+      "region": "Asia",
+      "country": "Taiwan",
+      "lat": 25.033,
+      "lon": 121.5654,
+      "type": "capital",
+      "tier": "major",
+      "keywords": [
+        "taipei",
+        "taiwan",
+        "taiwanese",
+        "tsmc"
+      ]
+    },
+    {
+      "id": "tokyo",
+      "name": "Tokyo",
+      "region": "Asia",
+      "country": "Japan",
+      "lat": 35.6762,
+      "lon": 139.6503,
+      "type": "capital",
+      "tier": "major",
+      "keywords": [
+        "tokyo",
+        "japan",
+        "japanese"
+      ]
+    },
+    {
+      "id": "seoul",
+      "name": "Seoul",
+      "region": "Asia",
+      "country": "South Korea",
+      "lat": 37.5665,
+      "lon": 126.978,
+      "type": "capital",
+      "tier": "major",
+      "keywords": [
+        "seoul",
+        "south korea",
+        "korean"
+      ]
+    },
+    {
+      "id": "pyongyang",
+      "name": "Pyongyang",
+      "region": "Asia",
+      "country": "North Korea",
+      "lat": 39.0392,
+      "lon": 125.7625,
+      "type": "capital",
+      "tier": "major",
+      "keywords": [
+        "pyongyang",
+        "north korea",
+        "dprk",
+        "kim jong un"
+      ]
+    },
+    {
+      "id": "newdelhi",
+      "name": "New Delhi",
+      "region": "Asia",
+      "country": "India",
+      "lat": 28.6139,
+      "lon": 77.209,
+      "type": "capital",
+      "tier": "major",
+      "keywords": [
+        "new delhi",
+        "delhi",
+        "india",
+        "indian",
+        "modi"
+      ]
+    },
+    {
+      "id": "riyadh",
+      "name": "Riyadh",
+      "region": "Middle East",
+      "country": "Saudi Arabia",
+      "lat": 24.7136,
+      "lon": 46.6753,
+      "type": "capital",
+      "tier": "major",
+      "keywords": [
+        "riyadh",
+        "saudi",
+        "saudi arabia",
+        "mbs",
+        "mohammed bin salman"
+      ]
+    },
+    {
+      "id": "ankara",
+      "name": "Ankara",
+      "region": "Middle East",
+      "country": "Turkey",
+      "lat": 39.9334,
+      "lon": 32.8597,
+      "type": "capital",
+      "tier": "major",
+      "keywords": [
+        "ankara",
+        "turkey",
+        "turkish",
+        "erdogan"
+      ]
+    },
+    {
+      "id": "paris",
+      "name": "Paris",
+      "region": "Europe",
+      "country": "France",
+      "lat": 48.8566,
+      "lon": 2.3522,
+      "type": "capital",
+      "tier": "major",
+      "keywords": [
+        "paris",
+        "france",
+        "french",
+        "macron",
+        "elysee"
+      ]
+    },
+    {
+      "id": "berlin",
+      "name": "Berlin",
+      "region": "Europe",
+      "country": "Germany",
+      "lat": 52.52,
+      "lon": 13.405,
+      "type": "capital",
+      "tier": "major",
+      "keywords": [
+        "berlin",
+        "germany",
+        "german",
+        "scholz",
+        "bundestag"
+      ]
+    },
+    {
+      "id": "cairo",
+      "name": "Cairo",
+      "region": "Middle East",
+      "country": "Egypt",
+      "lat": 30.0444,
+      "lon": 31.2357,
+      "type": "capital",
+      "tier": "major",
+      "keywords": [
+        "cairo",
+        "egypt",
+        "egyptian",
+        "sisi"
+      ]
+    },
+    {
+      "id": "islamabad",
+      "name": "Islamabad",
+      "region": "Asia",
+      "country": "Pakistan",
+      "lat": 33.6844,
+      "lon": 73.0479,
+      "type": "capital",
+      "tier": "major",
+      "keywords": [
+        "islamabad",
+        "pakistan",
+        "pakistani"
+      ]
+    },
+    {
+      "id": "gaza",
+      "name": "Gaza",
+      "region": "Middle East",
+      "country": "Palestine",
+      "lat": 31.5,
+      "lon": 34.47,
+      "type": "conflict",
+      "tier": "critical",
+      "keywords": [
+        "gaza",
+        "hamas",
+        "palestinian",
+        "rafah",
+        "khan younis",
+        "gaza strip"
+      ]
+    },
+    {
+      "id": "westbank",
+      "name": "West Bank",
+      "region": "Middle East",
+      "country": "Palestine",
+      "lat": 31.9,
+      "lon": 35.2,
+      "type": "conflict",
+      "tier": "major",
+      "keywords": [
+        "west bank",
+        "ramallah",
+        "jenin",
+        "nablus",
+        "hebron"
+      ]
+    },
+    {
+      "id": "ukraine-front",
+      "name": "Ukraine Front",
+      "region": "Europe",
+      "country": "Ukraine",
+      "lat": 48.5,
+      "lon": 37.5,
+      "type": "conflict",
+      "tier": "critical",
+      "keywords": [
+        "donbas",
+        "donbass",
+        "donetsk",
+        "luhansk",
+        "kharkiv",
+        "bakhmut",
+        "avdiivka",
+        "zaporizhzhia",
+        "kherson",
+        "crimea"
+      ]
+    },
+    {
+      "id": "taiwan-strait",
+      "name": "Taiwan Strait",
+      "region": "Asia",
+      "country": "International",
+      "lat": 24.5,
+      "lon": 119.5,
+      "type": "conflict",
+      "tier": "critical",
+      "keywords": [
+        "taiwan strait",
+        "formosa",
+        "pla",
+        "chinese military"
+      ]
+    },
+    {
+      "id": "southchinasea",
+      "name": "South China Sea",
+      "region": "Asia",
+      "country": "International",
+      "lat": 12,
+      "lon": 114,
+      "type": "strategic",
+      "tier": "critical",
+      "keywords": [
+        "south china sea",
+        "spratlys",
+        "paracels",
+        "nine-dash line",
+        "scarborough"
+      ]
+    },
+    {
+      "id": "yemen",
+      "name": "Yemen",
+      "region": "Middle East",
+      "country": "Yemen",
+      "lat": 15.5527,
+      "lon": 48.5164,
+      "type": "conflict",
+      "tier": "major",
+      "keywords": [
+        "yemen",
+        "houthi",
+        "houthis",
+        "sanaa",
+        "aden"
+      ]
+    },
+    {
+      "id": "syria",
+      "name": "Syria",
+      "region": "Middle East",
+      "country": "Syria",
+      "lat": 34.8,
+      "lon": 39,
+      "type": "conflict",
+      "tier": "major",
+      "keywords": [
+        "syria",
+        "syrian",
+        "assad",
+        "damascus",
+        "idlib",
+        "aleppo"
+      ]
+    },
+    {
+      "id": "lebanon",
+      "name": "Lebanon",
+      "region": "Middle East",
+      "country": "Lebanon",
+      "lat": 33.8547,
+      "lon": 35.8623,
+      "type": "conflict",
+      "tier": "major",
+      "keywords": [
+        "lebanon",
+        "lebanese",
+        "hezbollah",
+        "beirut"
+      ]
+    },
+    {
+      "id": "sudan",
+      "name": "Sudan",
+      "region": "Africa",
+      "country": "Sudan",
+      "lat": 15.5007,
+      "lon": 32.5599,
+      "type": "conflict",
+      "tier": "major",
+      "keywords": [
+        "sudan",
+        "sudanese",
+        "khartoum",
+        "rsf",
+        "darfur"
+      ]
+    },
+    {
+      "id": "sahel",
+      "name": "Sahel",
+      "region": "Africa",
+      "country": "International",
+      "lat": 15,
+      "lon": 0,
+      "type": "conflict",
+      "tier": "major",
+      "keywords": [
+        "sahel",
+        "mali",
+        "niger",
+        "burkina faso",
+        "wagner",
+        "junta"
+      ]
+    },
+    {
+      "id": "ethiopia",
+      "name": "Ethiopia",
+      "region": "Africa",
+      "country": "Ethiopia",
+      "lat": 9.145,
+      "lon": 40.4897,
+      "type": "conflict",
+      "tier": "notable",
+      "keywords": [
+        "ethiopia",
+        "ethiopian",
+        "tigray",
+        "addis ababa",
+        "abiy ahmed"
+      ]
+    },
+    {
+      "id": "myanmar",
+      "name": "Myanmar",
+      "region": "Asia",
+      "country": "Myanmar",
+      "lat": 19.7633,
+      "lon": 96.0785,
+      "type": "conflict",
+      "tier": "notable",
+      "keywords": [
+        "myanmar",
+        "burma",
+        "rohingya",
+        "junta",
+        "naypyidaw"
+      ]
+    },
+    {
+      "id": "hormuz",
+      "name": "Strait of Hormuz",
+      "region": "Middle East",
+      "country": "International",
+      "lat": 26.5,
+      "lon": 56.5,
+      "type": "strategic",
+      "tier": "critical",
+      "keywords": [
+        "hormuz",
+        "strait of hormuz",
+        "persian gulf",
+        "gulf"
+      ]
+    },
+    {
+      "id": "redsea",
+      "name": "Red Sea",
+      "region": "Middle East",
+      "country": "International",
+      "lat": 20,
+      "lon": 38,
+      "type": "strategic",
+      "tier": "critical",
+      "keywords": [
+        "red sea",
+        "bab el-mandeb",
+        "bab al-mandab"
+      ]
+    },
+    {
+      "id": "suez",
+      "name": "Suez Canal",
+      "region": "Middle East",
+      "country": "Egypt",
+      "lat": 30.5,
+      "lon": 32.3,
+      "type": "strategic",
+      "tier": "critical",
+      "keywords": [
+        "suez",
+        "suez canal"
+      ]
+    },
+    {
+      "id": "baltic",
+      "name": "Baltic Sea",
+      "region": "Europe",
+      "country": "International",
+      "lat": 58,
+      "lon": 20,
+      "type": "strategic",
+      "tier": "major",
+      "keywords": [
+        "baltic",
+        "baltic sea",
+        "kaliningrad",
+        "gotland"
+      ]
+    },
+    {
+      "id": "arctic",
+      "name": "Arctic",
+      "region": "Arctic",
+      "country": "International",
+      "lat": 75,
+      "lon": 0,
+      "type": "strategic",
+      "tier": "major",
+      "keywords": [
+        "arctic",
+        "northern sea route",
+        "svalbard"
+      ]
+    },
+    {
+      "id": "blacksea",
+      "name": "Black Sea",
+      "region": "Europe",
+      "country": "International",
+      "lat": 43,
+      "lon": 35,
+      "type": "strategic",
+      "tier": "major",
+      "keywords": [
+        "black sea",
+        "bosphorus",
+        "sevastopol",
+        "odesa",
+        "odessa"
+      ]
+    },
+    {
+      "id": "un-nyc",
+      "name": "United Nations",
+      "region": "North America",
+      "country": "USA",
+      "lat": 40.7489,
+      "lon": -73.968,
+      "type": "organization",
+      "tier": "critical",
+      "keywords": [
+        "united nations",
+        "un",
+        "security council",
+        "general assembly",
+        "unsc"
+      ]
+    },
+    {
+      "id": "nato-hq",
+      "name": "NATO HQ",
+      "region": "Europe",
+      "country": "Belgium",
+      "lat": 50.8796,
+      "lon": 4.4284,
+      "type": "organization",
+      "tier": "critical",
+      "keywords": [
+        "nato",
+        "north atlantic",
+        "alliance",
+        "stoltenberg"
+      ]
+    },
+    {
+      "id": "iaea-vienna",
+      "name": "IAEA",
+      "region": "Europe",
+      "country": "Austria",
+      "lat": 48.2352,
+      "lon": 16.4156,
+      "type": "organization",
+      "tier": "major",
+      "keywords": [
+        "iaea",
+        "atomic energy",
+        "nuclear watchdog",
+        "grossi"
+      ]
+    }
+  ]
+}

internal/world/enrichdata/threat-keywords.json

@@ -0,0 +1,621 @@
+{
+  "exclusions": [
+    "protein",
+    "couples",
+    "relationship",
+    "dating",
+    "diet",
+    "fitness",
+    "recipe",
+    "cooking",
+    "shopping",
+    "fashion",
+    "celebrity",
+    "movie",
+    "tv show",
+    "sports",
+    "game",
+    "concert",
+    "festival",
+    "wedding",
+    "vacation",
+    "travel tips",
+    "life hack",
+    "self-care",
+    "wellness"
+  ],
+  "shortKeywords": [
+    "war",
+    "coup",
+    "ban",
+    "vote",
+    "riot",
+    "riots",
+    "hack",
+    "talks",
+    "ipo",
+    "gdp",
+    "virus",
+    "disease",
+    "flood"
+  ],
+  "tiers": [
+    {
+      "level": "critical",
+      "confidence": 0.9,
+      "variant": "any",
+      "keywords": [
+        {
+          "keyword": "nuclear strike",
+          "category": "military"
+        },
+        {
+          "keyword": "nuclear attack",
+          "category": "military"
+        },
+        {
+          "keyword": "nuclear war",
+          "category": "military"
+        },
+        {
+          "keyword": "invasion",
+          "category": "conflict"
+        },
+        {
+          "keyword": "declaration of war",
+          "category": "conflict"
+        },
+        {
+          "keyword": "martial law",
+          "category": "military"
+        },
+        {
+          "keyword": "coup",
+          "category": "military"
+        },
+        {
+          "keyword": "coup attempt",
+          "category": "military"
+        },
+        {
+          "keyword": "genocide",
+          "category": "conflict"
+        },
+        {
+          "keyword": "ethnic cleansing",
+          "category": "conflict"
+        },
+        {
+          "keyword": "chemical attack",
+          "category": "terrorism"
+        },
+        {
+          "keyword": "biological attack",
+          "category": "terrorism"
+        },
+        {
+          "keyword": "dirty bomb",
+          "category": "terrorism"
+        },
+        {
+          "keyword": "mass casualty",
+          "category": "conflict"
+        },
+        {
+          "keyword": "pandemic declared",
+          "category": "health"
+        },
+        {
+          "keyword": "health emergency",
+          "category": "health"
+        },
+        {
+          "keyword": "nato article 5",
+          "category": "military"
+        },
+        {
+          "keyword": "evacuation order",
+          "category": "disaster"
+        },
+        {
+          "keyword": "meltdown",
+          "category": "disaster"
+        },
+        {
+          "keyword": "nuclear meltdown",
+          "category": "disaster"
+        }
+      ]
+    },
+    {
+      "level": "high",
+      "confidence": 0.8,
+      "variant": "any",
+      "keywords": [
+        {
+          "keyword": "war",
+          "category": "conflict"
+        },
+        {
+          "keyword": "armed conflict",
+          "category": "conflict"
+        },
+        {
+          "keyword": "airstrike",
+          "category": "conflict"
+        },
+        {
+          "keyword": "air strike",
+          "category": "conflict"
+        },
+        {
+          "keyword": "drone strike",
+          "category": "conflict"
+        },
+        {
+          "keyword": "missile",
+          "category": "military"
+        },
+        {
+          "keyword": "missile launch",
+          "category": "military"
+        },
+        {
+          "keyword": "troops deployed",
+          "category": "military"
+        },
+        {
+          "keyword": "military escalation",
+          "category": "military"
+        },
+        {
+          "keyword": "bombing",
+          "category": "conflict"
+        },
+        {
+          "keyword": "casualties",
+          "category": "conflict"
+        },
+        {
+          "keyword": "hostage",
+          "category": "terrorism"
+        },
+        {
+          "keyword": "terrorist",
+          "category": "terrorism"
+        },
+        {
+          "keyword": "terror attack",
+          "category": "terrorism"
+        },
+        {
+          "keyword": "assassination",
+          "category": "crime"
+        },
+        {
+          "keyword": "cyber attack",
+          "category": "cyber"
+        },
+        {
+          "keyword": "ransomware",
+          "category": "cyber"
+        },
+        {
+          "keyword": "data breach",
+          "category": "cyber"
+        },
+        {
+          "keyword": "sanctions",
+          "category": "economic"
+        },
+        {
+          "keyword": "embargo",
+          "category": "economic"
+        },
+        {
+          "keyword": "earthquake",
+          "category": "disaster"
+        },
+        {
+          "keyword": "tsunami",
+          "category": "disaster"
+        },
+        {
+          "keyword": "hurricane",
+          "category": "disaster"
+        },
+        {
+          "keyword": "typhoon",
+          "category": "disaster"
+        }
+      ]
+    },
+    {
+      "level": "high",
+      "confidence": 0.75,
+      "variant": "tech",
+      "keywords": [
+        {
+          "keyword": "major outage",
+          "category": "infrastructure"
+        },
+        {
+          "keyword": "service down",
+          "category": "infrastructure"
+        },
+        {
+          "keyword": "global outage",
+          "category": "infrastructure"
+        },
+        {
+          "keyword": "zero-day",
+          "category": "cyber"
+        },
+        {
+          "keyword": "critical vulnerability",
+          "category": "cyber"
+        },
+        {
+          "keyword": "supply chain attack",
+          "category": "cyber"
+        },
+        {
+          "keyword": "mass layoff",
+          "category": "economic"
+        }
+      ]
+    },
+    {
+      "level": "medium",
+      "confidence": 0.7,
+      "variant": "any",
+      "keywords": [
+        {
+          "keyword": "protest",
+          "category": "protest"
+        },
+        {
+          "keyword": "protests",
+          "category": "protest"
+        },
+        {
+          "keyword": "riot",
+          "category": "protest"
+        },
+        {
+          "keyword": "riots",
+          "category": "protest"
+        },
+        {
+          "keyword": "unrest",
+          "category": "protest"
+        },
+        {
+          "keyword": "demonstration",
+          "category": "protest"
+        },
+        {
+          "keyword": "strike action",
+          "category": "protest"
+        },
+        {
+          "keyword": "military exercise",
+          "category": "military"
+        },
+        {
+          "keyword": "naval exercise",
+          "category": "military"
+        },
+        {
+          "keyword": "arms deal",
+          "category": "military"
+        },
+        {
+          "keyword": "weapons sale",
+          "category": "military"
+        },
+        {
+          "keyword": "diplomatic crisis",
+          "category": "diplomatic"
+        },
+        {
+          "keyword": "ambassador recalled",
+          "category": "diplomatic"
+        },
+        {
+          "keyword": "expel diplomats",
+          "category": "diplomatic"
+        },
+        {
+          "keyword": "trade war",
+          "category": "economic"
+        },
+        {
+          "keyword": "tariff",
+          "category": "economic"
+        },
+        {
+          "keyword": "recession",
+          "category": "economic"
+        },
+        {
+          "keyword": "inflation",
+          "category": "economic"
+        },
+        {
+          "keyword": "market crash",
+          "category": "economic"
+        },
+        {
+          "keyword": "flood",
+          "category": "disaster"
+        },
+        {
+          "keyword": "flooding",
+          "category": "disaster"
+        },
+        {
+          "keyword": "wildfire",
+          "category": "disaster"
+        },
+        {
+          "keyword": "volcano",
+          "category": "disaster"
+        },
+        {
+          "keyword": "eruption",
+          "category": "disaster"
+        },
+        {
+          "keyword": "outbreak",
+          "category": "health"
+        },
+        {
+          "keyword": "epidemic",
+          "category": "health"
+        },
+        {
+          "keyword": "infection spread",
+          "category": "health"
+        },
+        {
+          "keyword": "oil spill",
+          "category": "environmental"
+        },
+        {
+          "keyword": "pipeline explosion",
+          "category": "infrastructure"
+        },
+        {
+          "keyword": "blackout",
+          "category": "infrastructure"
+        },
+        {
+          "keyword": "power outage",
+          "category": "infrastructure"
+        },
+        {
+          "keyword": "internet outage",
+          "category": "infrastructure"
+        },
+        {
+          "keyword": "derailment",
+          "category": "infrastructure"
+        }
+      ]
+    },
+    {
+      "level": "medium",
+      "confidence": 0.65,
+      "variant": "tech",
+      "keywords": [
+        {
+          "keyword": "outage",
+          "category": "infrastructure"
+        },
+        {
+          "keyword": "breach",
+          "category": "cyber"
+        },
+        {
+          "keyword": "hack",
+          "category": "cyber"
+        },
+        {
+          "keyword": "vulnerability",
+          "category": "cyber"
+        },
+        {
+          "keyword": "layoff",
+          "category": "economic"
+        },
+        {
+          "keyword": "layoffs",
+          "category": "economic"
+        },
+        {
+          "keyword": "antitrust",
+          "category": "economic"
+        },
+        {
+          "keyword": "monopoly",
+          "category": "economic"
+        },
+        {
+          "keyword": "ban",
+          "category": "economic"
+        },
+        {
+          "keyword": "shutdown",
+          "category": "infrastructure"
+        }
+      ]
+    },
+    {
+      "level": "low",
+      "confidence": 0.6,
+      "variant": "any",
+      "keywords": [
+        {
+          "keyword": "election",
+          "category": "diplomatic"
+        },
+        {
+          "keyword": "vote",
+          "category": "diplomatic"
+        },
+        {
+          "keyword": "referendum",
+          "category": "diplomatic"
+        },
+        {
+          "keyword": "summit",
+          "category": "diplomatic"
+        },
+        {
+          "keyword": "treaty",
+          "category": "diplomatic"
+        },
+        {
+          "keyword": "agreement",
+          "category": "diplomatic"
+        },
+        {
+          "keyword": "negotiation",
+          "category": "diplomatic"
+        },
+        {
+          "keyword": "talks",
+          "category": "diplomatic"
+        },
+        {
+          "keyword": "peacekeeping",
+          "category": "diplomatic"
+        },
+        {
+          "keyword": "humanitarian aid",
+          "category": "diplomatic"
+        },
+        {
+          "keyword": "ceasefire",
+          "category": "diplomatic"
+        },
+        {
+          "keyword": "peace treaty",
+          "category": "diplomatic"
+        },
+        {
+          "keyword": "climate change",
+          "category": "environmental"
+        },
+        {
+          "keyword": "emissions",
+          "category": "environmental"
+        },
+        {
+          "keyword": "pollution",
+          "category": "environmental"
+        },
+        {
+          "keyword": "deforestation",
+          "category": "environmental"
+        },
+        {
+          "keyword": "drought",
+          "category": "environmental"
+        },
+        {
+          "keyword": "vaccine",
+          "category": "health"
+        },
+        {
+          "keyword": "vaccination",
+          "category": "health"
+        },
+        {
+          "keyword": "disease",
+          "category": "health"
+        },
+        {
+          "keyword": "virus",
+          "category": "health"
+        },
+        {
+          "keyword": "public health",
+          "category": "health"
+        },
+        {
+          "keyword": "covid",
+          "category": "health"
+        },
+        {
+          "keyword": "interest rate",
+          "category": "economic"
+        },
+        {
+          "keyword": "gdp",
+          "category": "economic"
+        },
+        {
+          "keyword": "unemployment",
+          "category": "economic"
+        },
+        {
+          "keyword": "regulation",
+          "category": "economic"
+        }
+      ]
+    },
+    {
+      "level": "low",
+      "confidence": 0.55,
+      "variant": "tech",
+      "keywords": [
+        {
+          "keyword": "ipo",
+          "category": "economic"
+        },
+        {
+          "keyword": "funding",
+          "category": "economic"
+        },
+        {
+          "keyword": "acquisition",
+          "category": "economic"
+        },
+        {
+          "keyword": "merger",
+          "category": "economic"
+        },
+        {
+          "keyword": "launch",
+          "category": "tech"
+        },
+        {
+          "keyword": "release",
+          "category": "tech"
+        },
+        {
+          "keyword": "update",
+          "category": "tech"
+        },
+        {
+          "keyword": "partnership",
+          "category": "economic"
+        },
+        {
+          "keyword": "startup",
+          "category": "tech"
+        },
+        {
+          "keyword": "ai model",
+          "category": "tech"
+        },
+        {
+          "keyword": "open source",
+          "category": "tech"
+        }
+      ]
+    }
+  ]
+}

internal/world/ensodata/summary.json

@@ -0,0 +1,771 @@
+{
+ "measured": {
+  "gpqa_diamond": {
+   "gpt-5.6-terra": {
+    "accuracy_pct": 91.1,
+    "stderr_pct": 2.1,
+    "n": 191,
+    "correct": 174,
+    "errors": 0,
+    "infra_excluded": 7,
+    "tokens": {
+     "prompt": 60695,
+     "completion": 25529,
+     "reasoning": 0,
+     "calls": 198
+    },
+    "usd_est": 0.0,
+    "wall_seconds": null,
+    "run_tag": "v2"
+   },
+   "deepseek-4-flash": {
+    "accuracy_pct": 76.9,
+    "stderr_pct": 3.1,
+    "n": 182,
+    "correct": 140,
+    "errors": 16,
+    "infra_excluded": 16,
+    "tokens": {
+     "prompt": 56442,
+     "completion": 101277,
+     "reasoning": 0,
+     "calls": 182
+    },
+    "usd_est": 0.0,
+    "wall_seconds": null,
+    "run_tag": "v2"
+   },
+   "enso-flash": {
+    "accuracy_pct": 75.8,
+    "stderr_pct": 3.0,
+    "n": 198,
+    "correct": 150,
+    "errors": 0,
+    "infra_excluded": 0,
+    "tokens": {
+     "prompt": 60695,
+     "completion": 361936,
+     "reasoning": 0,
+     "calls": 198
+    },
+    "usd_est": 0.0,
+    "wall_seconds": null,
+    "run_tag": "v2"
+   },
+   "fable-5": {
+    "accuracy_pct": 81.3,
+    "stderr_pct": 2.8,
+    "n": 198,
+    "correct": 161,
+    "errors": 0,
+    "infra_excluded": 0,
+    "tokens": {
+     "prompt": 78121,
+     "completion": 199072,
+     "reasoning": 0,
+     "calls": 198
+    },
+    "usd_est": 3.2204,
+    "wall_seconds": null,
+    "run_tag": "v1"
+   },
+   "deepseek-v4-pro": {
+    "accuracy_pct": 75.3,
+    "stderr_pct": 3.1,
+    "n": 198,
+    "correct": 149,
+    "errors": 0,
+    "infra_excluded": 0,
+    "tokens": {
+     "prompt": 60695,
+     "completion": 107808,
+     "reasoning": 0,
+     "calls": 198
+    },
+    "usd_est": 0.2113,
+    "wall_seconds": null,
+    "run_tag": "v2"
+   },
+   "gpt-5.5": {
+    "accuracy_pct": 90.4,
+    "stderr_pct": 2.1,
+    "n": 198,
+    "correct": 179,
+    "errors": 0,
+    "infra_excluded": 0,
+    "tokens": {
+     "prompt": 54916,
+     "completion": 362128,
+     "reasoning": 326158,
+     "calls": 198
+    },
+    "usd_est": 3.6899,
+    "wall_seconds": 2396.2,
+    "run_tag": "v1"
+   },
+   "glm-5.2": {
+    "accuracy_pct": null,
+    "stderr_pct": null,
+    "n": 69,
+    "correct": 60,
+    "errors": 0,
+    "infra_excluded": 129,
+    "tokens": {
+     "prompt": 60695,
+     "completion": 26595,
+     "reasoning": 0,
+     "calls": 198
+    },
+    "usd_est": 0.0,
+    "wall_seconds": null,
+    "run_tag": "max",
+    "degraded": true,
+    "blank_rate_pct": 65.2
+   },
+   "enso": {
+    "accuracy_pct": 87.9,
+    "stderr_pct": 2.3,
+    "n": 198,
+    "correct": 174,
+    "errors": 0,
+    "infra_excluded": 0,
+    "tokens": {
+     "prompt": 74531,
+     "completion": 152519,
+     "reasoning": 29387,
+     "calls": 198
+    },
+    "usd_est": 10.0211,
+    "wall_seconds": null,
+    "run_tag": "v1"
+   },
+   "enso-ultra": {
+    "accuracy_pct": 90.4,
+    "stderr_pct": 2.1,
+    "n": 198,
+    "correct": 179,
+    "errors": 0,
+    "infra_excluded": 0,
+    "tokens": {
+     "prompt": 217469,
+     "completion": 603501,
+     "reasoning": 325464,
+     "calls": 605
+    },
+    "usd_est": 15.8887,
+    "wall_seconds": null,
+    "run_tag": "v2"
+   },
+   "gpt-5.6-sol": {
+    "accuracy_pct": 94.8,
+    "stderr_pct": 1.6,
+    "n": 193,
+    "correct": 183,
+    "errors": 0,
+    "infra_excluded": 5,
+    "tokens": {
+     "prompt": 60695,
+     "completion": 34023,
+     "reasoning": 0,
+     "calls": 198
+    },
+    "usd_est": 0.0,
+    "wall_seconds": null,
+    "run_tag": "max"
+   },
+   "kimi-k3": {
+    "accuracy_pct": 92.5,
+    "stderr_pct": 4.2,
+    "n": 40,
+    "correct": 37,
+    "errors": 0,
+    "infra_excluded": 0,
+    "tokens": {
+     "prompt": 13917,
+     "completion": 90614,
+     "reasoning": 81847,
+     "calls": 40
+    },
+    "usd_est": 0.0,
+    "wall_seconds": null,
+    "run_tag": "k3-max"
+   },
+   "glm-5.2@openrouter": {
+    "accuracy_pct": null,
+    "stderr_pct": null,
+    "n": 119,
+    "correct": 95,
+    "errors": 79,
+    "infra_excluded": 79,
+    "tokens": {
+     "prompt": 32982,
+     "completion": 1228859,
+     "reasoning": 983679,
+     "calls": 119
+    },
+    "usd_est": 0.0,
+    "wall_seconds": null,
+    "run_tag": "glm-true",
+    "degraded": true,
+    "blank_rate_pct": 39.9
+   },
+   "opus-4.8": {
+    "accuracy_pct": 86.9,
+    "stderr_pct": 2.4,
+    "n": 198,
+    "correct": 172,
+    "errors": 0,
+    "infra_excluded": 0,
+    "tokens": {
+     "prompt": 78121,
+     "completion": 126069,
+     "reasoning": 0,
+     "calls": 198
+    },
+    "usd_est": 10.627,
+    "wall_seconds": 241.3,
+    "run_tag": "v1"
+   },
+   "deepseek-3.2": {
+    "accuracy_pct": 73.7,
+    "stderr_pct": 3.1,
+    "n": 198,
+    "correct": 146,
+    "errors": 0,
+    "infra_excluded": 0,
+    "tokens": {
+     "prompt": 60695,
+     "completion": 367921,
+     "reasoning": 0,
+     "calls": 198
+    },
+    "usd_est": 0.0,
+    "wall_seconds": null,
+    "run_tag": "v2"
+   },
+   "gpt-5.6-luna": {
+    "accuracy_pct": 89.6,
+    "stderr_pct": 2.3,
+    "n": 183,
+    "correct": 164,
+    "errors": 0,
+    "infra_excluded": 15,
+    "tokens": {
+     "prompt": 60695,
+     "completion": 31104,
+     "reasoning": 0,
+     "calls": 198
+    },
+    "usd_est": 0.0,
+    "wall_seconds": null,
+    "run_tag": "v2"
+   }
+  },
+  "livecodebench": {
+   "gpt-5.6-sol": {
+    "accuracy_pct": null,
+    "stderr_pct": null,
+    "n": 144,
+    "correct": 130,
+    "errors": 17,
+    "infra_excluded": 31,
+    "tokens": {
+     "prompt": 87763,
+     "completion": 43002,
+     "reasoning": 0,
+     "calls": 158
+    },
+    "usd_est": 0.0,
+    "wall_seconds": null,
+    "run_tag": "v2",
+    "degraded": true,
+    "blank_rate_pct": 17.7
+   },
+   "deepseek-v4-pro": {
+    "accuracy_pct": 51.4,
+    "stderr_pct": 3.8,
+    "n": 175,
+    "correct": 90,
+    "errors": 0,
+    "infra_excluded": 0,
+    "tokens": {
+     "prompt": 97404,
+     "completion": 75242,
+     "reasoning": 0,
+     "calls": 175
+    },
+    "usd_est": 0.1777,
+    "wall_seconds": null,
+    "run_tag": "v2"
+   },
+   "deepseek-3.2": {
+    "accuracy_pct": 56.0,
+    "stderr_pct": 3.8,
+    "n": 175,
+    "correct": 98,
+    "errors": 0,
+    "infra_excluded": 0,
+    "tokens": {
+     "prompt": 97404,
+     "completion": 353896,
+     "reasoning": 0,
+     "calls": 175
+    },
+    "usd_est": 0.0,
+    "wall_seconds": null,
+    "run_tag": "v2"
+   },
+   "fable-5": {
+    "accuracy_pct": 82.9,
+    "stderr_pct": 2.8,
+    "n": 175,
+    "correct": 145,
+    "errors": 0,
+    "infra_excluded": 0,
+    "tokens": {
+     "prompt": 125867,
+     "completion": 544855,
+     "reasoning": 0,
+     "calls": 175
+    },
+    "usd_est": 8.5504,
+    "wall_seconds": null,
+    "run_tag": "v1"
+   },
+   "enso": {
+    "accuracy_pct": 92.0,
+    "stderr_pct": 2.1,
+    "n": 174,
+    "correct": 160,
+    "errors": 1,
+    "infra_excluded": 1,
+    "tokens": {
+     "prompt": 92002,
+     "completion": 512599,
+     "reasoning": 454741,
+     "calls": 174
+    },
+    "usd_est": 5.241,
+    "wall_seconds": null,
+    "run_tag": "v1"
+   },
+   "opus-4.8": {
+    "accuracy_pct": 72.8,
+    "stderr_pct": 3.4,
+    "n": 173,
+    "correct": 126,
+    "errors": 2,
+    "infra_excluded": 2,
+    "tokens": {
+     "prompt": 124432,
+     "completion": 500884,
+     "reasoning": 0,
+     "calls": 173
+    },
+    "usd_est": 39.4328,
+    "wall_seconds": null,
+    "run_tag": "v1"
+   },
+   "gpt-5.6-luna": {
+    "accuracy_pct": null,
+    "stderr_pct": null,
+    "n": 156,
+    "correct": 135,
+    "errors": 0,
+    "infra_excluded": 19,
+    "tokens": {
+     "prompt": 97404,
+     "completion": 41596,
+     "reasoning": 0,
+     "calls": 175
+    },
+    "usd_est": 0.0,
+    "wall_seconds": null,
+    "run_tag": "v2",
+    "degraded": true,
+    "blank_rate_pct": 10.9
+   },
+   "enso-ultra": {
+    "accuracy_pct": 85.1,
+    "stderr_pct": 2.7,
+    "n": 175,
+    "correct": 149,
+    "errors": 0,
+    "infra_excluded": 0,
+    "tokens": {
+     "prompt": 975812,
+     "completion": 1329941,
+     "reasoning": 474476,
+     "calls": 693
+    },
+    "usd_est": 71.731,
+    "wall_seconds": null,
+    "run_tag": "v2"
+   },
+   "gpt-5.5": {
+    "accuracy_pct": 92.0,
+    "stderr_pct": 2.1,
+    "n": 174,
+    "correct": 160,
+    "errors": 1,
+    "infra_excluded": 1,
+    "tokens": {
+     "prompt": 92002,
+     "completion": 504668,
+     "reasoning": 444424,
+     "calls": 174
+    },
+    "usd_est": 5.1617,
+    "wall_seconds": null,
+    "run_tag": "v1"
+   },
+   "glm-5.2": {
+    "accuracy_pct": null,
+    "stderr_pct": null,
+    "n": 60,
+    "correct": 49,
+    "errors": 0,
+    "infra_excluded": 115,
+    "tokens": {
+     "prompt": 97404,
+     "completion": 14943,
+     "reasoning": 0,
+     "calls": 175
+    },
+    "usd_est": 0.0,
+    "wall_seconds": null,
+    "run_tag": "v2",
+    "degraded": true,
+    "blank_rate_pct": 65.7
+   },
+   "gpt-5.6-terra": {
+    "accuracy_pct": 88.3,
+    "stderr_pct": 2.5,
+    "n": 162,
+    "correct": 143,
+    "errors": 0,
+    "infra_excluded": 13,
+    "tokens": {
+     "prompt": 97404,
+     "completion": 49002,
+     "reasoning": 0,
+     "calls": 175
+    },
+    "usd_est": 0.0,
+    "wall_seconds": null,
+    "run_tag": "v2"
+   },
+   "enso-flash": {
+    "accuracy_pct": 49.1,
+    "stderr_pct": 3.8,
+    "n": 175,
+    "correct": 86,
+    "errors": 0,
+    "infra_excluded": 0,
+    "tokens": {
+     "prompt": 97404,
+     "completion": 367521,
+     "reasoning": 0,
+     "calls": 175
+    },
+    "usd_est": 0.0,
+    "wall_seconds": null,
+    "run_tag": "v2"
+   }
+  },
+  "hle": {
+   "gpt-5.5": {
+    "accuracy_pct": 35.4,
+    "stderr_pct": 2.1,
+    "n": 500,
+    "correct": 177,
+    "errors": 0,
+    "infra_excluded": 0,
+    "tokens": {
+     "prompt": 139619,
+     "completion": 2240161,
+     "reasoning": 2061227,
+     "calls": 500
+    },
+    "usd_est": 22.5761,
+    "wall_seconds": null,
+    "run_tag": "v1"
+   },
+   "deepseek-v4-pro": {
+    "accuracy_pct": 7.2,
+    "stderr_pct": 1.2,
+    "n": 500,
+    "correct": 36,
+    "errors": 0,
+    "infra_excluded": 0,
+    "tokens": {
+     "prompt": 134104,
+     "completion": 383371,
+     "reasoning": 0,
+     "calls": 500
+    },
+    "usd_est": 0.7063,
+    "wall_seconds": null,
+    "run_tag": "v1"
+   },
+   "opus-4.8": {
+    "accuracy_pct": 27.9,
+    "stderr_pct": 2.0,
+    "n": 498,
+    "correct": 139,
+    "errors": 2,
+    "infra_excluded": 2,
+    "tokens": {
+     "prompt": 204638,
+     "completion": 1265083,
+     "reasoning": 0,
+     "calls": 498
+    },
+    "usd_est": 97.9508,
+    "wall_seconds": null,
+    "run_tag": "v1"
+   },
+   "enso-ultra": {
+    "accuracy_pct": 34.6,
+    "stderr_pct": 2.1,
+    "n": 500,
+    "correct": 173,
+    "errors": 0,
+    "infra_excluded": 0,
+    "tokens": {
+     "prompt": 1457803,
+     "completion": 4095530,
+     "reasoning": 2052639,
+     "calls": 1819
+    },
+    "usd_est": 151.7767,
+    "wall_seconds": null,
+    "run_tag": "v2"
+   },
+   "enso": {
+    "accuracy_pct": 29.4,
+    "stderr_pct": 2.0,
+    "n": 500,
+    "correct": 147,
+    "errors": 0,
+    "infra_excluded": 0,
+    "tokens": {
+     "prompt": 180835,
+     "completion": 1429013,
+     "reasoning": 436163,
+     "calls": 500
+    },
+    "usd_est": 76.5405,
+    "wall_seconds": null,
+    "run_tag": "v1"
+   },
+   "fable-5": {
+    "accuracy_pct": 38.2,
+    "stderr_pct": 2.2,
+    "n": 500,
+    "correct": 191,
+    "errors": 0,
+    "infra_excluded": 0,
+    "tokens": {
+     "prompt": 205132,
+     "completion": 1660596,
+     "reasoning": 0,
+     "calls": 500
+    },
+    "usd_est": 25.5243,
+    "wall_seconds": null,
+    "run_tag": "v1"
+   }
+  },
+  "charxiv": {
+   "opus-4.8": {
+    "accuracy_pct": 78.0,
+    "stderr_pct": 2.9,
+    "n": 200,
+    "correct": 156,
+    "errors": 0,
+    "infra_excluded": 0,
+    "tokens": {
+     "prompt": 204206,
+     "completion": 5650,
+     "reasoning": 0,
+     "calls": 200
+    },
+    "usd_est": 3.4868,
+    "wall_seconds": null,
+    "run_tag": "v1"
+   },
+   "enso-ultra": {
+    "accuracy_pct": 85.5,
+    "stderr_pct": 2.5,
+    "n": 200,
+    "correct": 171,
+    "errors": 0,
+    "infra_excluded": 0,
+    "tokens": {
+     "prompt": 631448,
+     "completion": 85689,
+     "reasoning": 54757,
+     "calls": 636
+    },
+    "usd_est": 6.2855,
+    "wall_seconds": null,
+    "run_tag": "v2"
+   },
+   "gpt-5.5": {
+    "accuracy_pct": 85.5,
+    "stderr_pct": 2.5,
+    "n": 200,
+    "correct": 171,
+    "errors": 0,
+    "infra_excluded": 0,
+    "tokens": {
+     "prompt": 181387,
+     "completion": 50493,
+     "reasoning": 47582,
+     "calls": 200
+    },
+    "usd_est": 0.7317,
+    "wall_seconds": null,
+    "run_tag": "v1"
+   },
+   "fable-5": {
+    "accuracy_pct": 76.0,
+    "stderr_pct": 3.0,
+    "n": 200,
+    "correct": 152,
+    "errors": 0,
+    "infra_excluded": 0,
+    "tokens": {
+     "prompt": 204206,
+     "completion": 13961,
+     "reasoning": 0,
+     "calls": 200
+    },
+    "usd_est": 0.822,
+    "wall_seconds": null,
+    "run_tag": "v1"
+   },
+   "enso": {
+    "accuracy_pct": 78.0,
+    "stderr_pct": 2.9,
+    "n": 200,
+    "correct": 156,
+    "errors": 0,
+    "infra_excluded": 0,
+    "tokens": {
+     "prompt": 204206,
+     "completion": 5424,
+     "reasoning": 0,
+     "calls": 200
+    },
+    "usd_est": 3.4699,
+    "wall_seconds": null,
+    "run_tag": "v1"
+   }
+  }
+ },
+ "grading": {
+  "hle": {
+   "judge_arm": "gpt-5.5",
+   "judge_calls": 1,
+   "judge_usd_est": 0.0006,
+   "judge_prompt_tokens": 159,
+   "judge_completion_tokens": 36
+  }
+ },
+ "enso_reported": {},
+ "pending": [
+  "swebench_pro",
+  "terminal_bench"
+ ],
+ "ultra_ablation": {
+  "gpqa_diamond": {
+   "k3fix": {
+    "accuracy_pct": 32.8,
+    "n": 198,
+    "usd_est": 0.0,
+    "logic": "k3fix"
+   },
+   "v2": {
+    "accuracy_pct": 90.4,
+    "n": 198,
+    "usd_est": 15.8887,
+    "logic": "verify-then-select"
+   },
+   "v1": {
+    "accuracy_pct": 89.9,
+    "n": 198,
+    "usd_est": 16.4333,
+    "logic": "blind-synthesis"
+   }
+  },
+  "livecodebench": {
+   "v1": {
+    "accuracy_pct": 81.1,
+    "n": 175,
+    "usd_est": 90.682,
+    "logic": "blind-synthesis"
+   },
+   "v2": {
+    "accuracy_pct": 85.1,
+    "n": 175,
+    "usd_est": 71.731,
+    "logic": "verify-then-select"
+   }
+  },
+  "hle": {
+   "v1": {
+    "accuracy_pct": 29.2,
+    "n": 500,
+    "usd_est": 191.4856,
+    "logic": "blind-synthesis"
+   },
+   "v2": {
+    "accuracy_pct": 34.6,
+    "n": 500,
+    "usd_est": 151.7767,
+    "logic": "verify-then-select"
+   }
+  },
+  "charxiv": {
+   "v2": {
+    "accuracy_pct": 85.5,
+    "n": 200,
+    "usd_est": 6.2855,
+    "logic": "verify-then-select"
+   },
+   "v1": {
+    "accuracy_pct": 81.5,
+    "n": 200,
+    "usd_est": 10.1498,
+    "logic": "blind-synthesis"
+   }
+  }
+ },
+ "total_usd_est": 564.25,
+ "agentic": {
+  "swebench_pro": {
+   "bench": "SWE-Bench Pro",
+   "metric": "% resolved (agentic, Mini-SWE-Agent)",
+   "n_items": 25,
+   "systems": {
+    "step-routed": {
+     "n": 18,
+     "resolved": 7,
+     "resolved_rate": 0.3889,
+     "usd": 19.696,
+     "calls": 256
+    },
+    "single-opus": {
+     "n": 18,
+     "resolved": 3,
+     "resolved_rate": 0.1667,
+     "usd": 27.561,
+     "calls": 321
+    }
+   },
+   "note": "Agentic pilot: n=18 per system from the agent harness (agent pass/fail); official cross-scoring done on a small common set (results/agentic). Full 731-instance run pending (amd64-only task images + shared-key serialization)."
+  }
+ }
+}

internal/world/feed_fetch.go

@@ -0,0 +1,106 @@
+package world
+
+import (
+	"context"
+	"crypto/sha1"
+	"encoding/hex"
+	"encoding/json"
+	"net/url"
+	"time"
+
+	"github.com/hanzoai/world/internal/world/store"
+)
+
+// rssFetchHeaders is the single header set used for every allowlisted feed
+// fetch — by the on-demand fall-through (rss-proxy, feeds-batch) AND the
+// background warmer. One place, one behavior.
+var rssFetchHeaders = map[string]string{
+	"User-Agent": browserUA,
+	"Accept":     "application/rss+xml, application/xml, text/xml, */*",
+}
+
+// fetchFeedBody performs one bounded, allowlisted GET of a feed and returns the
+// body only when it is a usable (non-blank) 2xx. This is the ONLY live-fetch
+// path for feed bodies, shared by the request fall-through and the warmer. The
+// caller owns the timeout via ctx.
+func (s *Server) fetchFeedBody(ctx context.Context, feedURL string) ([]byte, bool) {
+	body, status, err := s.getAllowlisted(ctx, feedURL, allowedRSSDomains, rssFetchHeaders)
+	if err != nil || status < 200 || status >= 300 || isBlankBody(body) {
+		return nil, false
+	}
+	return body, true
+}
+
+// ingestFeedItems parses a feed body and folds its items into the searchable
+// data lake (kind=news). Cheap and write-behind (Lake.Add never blocks), so it
+// runs off both the request fall-through and the warmer without touching latency.
+func (s *Server) ingestFeedItems(feedURL string, body []byte) {
+	if s.store == nil {
+		return
+	}
+	host := feedHost(feedURL)
+	for _, it := range parseFeedItems(body, feedsBatchMaxItems) {
+		payload, _ := json.Marshal(map[string]any{
+			"title": it.Title, "link": it.Link, "pubDate": it.PubDate,
+			"source": host, "tickers": it.Tickers,
+		})
+		s.store.Lake.Add(store.Item{
+			ID:      newsItemID(it.Link, it.Title),
+			Kind:    "news",
+			Source:  host,
+			TS:      feedItemTime(it.PubDate),
+			Title:   it.Title,
+			Tickers: it.Tickers,
+			Payload: string(payload),
+		})
+	}
+}
+
+// newsItemID is the stable dedupe key for a news item: its link when present,
+// else its title. Re-ingesting the same story upserts instead of duplicating.
+func newsItemID(link, title string) string {
+	seed := link
+	if seed == "" {
+		seed = title
+	}
+	sum := sha1.Sum([]byte(seed))
+	return "news:" + hex.EncodeToString(sum[:])
+}
+
+// feedItemTime parses a normalized RFC3339 pubDate back to a time, defaulting to
+// now when the feed omitted or mangled the date.
+func feedItemTime(pubDate string) time.Time {
+	if pubDate != "" {
+		if t, err := time.Parse(time.RFC3339, pubDate); err == nil {
+			return t.UTC()
+		}
+	}
+	return time.Now().UTC()
+}
+
+// feedHost returns the feed's host for use as the item's source label.
+func feedHost(feedURL string) string {
+	if u, err := url.Parse(feedURL); err == nil && u.Hostname() != "" {
+		return u.Hostname()
+	}
+	return "feed"
+}
+
+// curatedFeedSeed is the bootstrap warm set: the highest-value feeds behind the
+// crypto, financial-regulation, and crypto-news panels, so a brand-new pod warms
+// THEM first (before any user request). Every URL is on the RSS allowlist. After
+// the first real page load the warm set becomes demand-driven and fleet-wide; the
+// seed only bridges the very first cold boot.
+var curatedFeedSeed = []string{
+	// crypto / crypto-news
+	"https://www.coindesk.com/arc/outboundfeeds/rss/",
+	"https://cointelegraph.com/rss",
+	// financial regulation
+	"https://www.sec.gov/news/pressreleases.rss",
+	"https://www.federalreserve.gov/feeds/press_all.xml",
+	// markets / financial
+	"https://www.cnbc.com/id/100003114/device/rss/rss.html",
+	"https://www.cnbc.com/id/19854910/device/rss/rss.html",
+	"https://seekingalpha.com/market_currents.xml",
+	"https://www.ft.com/rss/home",
+}

internal/world/feed_warmer.go

@@ -0,0 +1,94 @@
+package world
+
+import (
+	"context"
+	"math/rand"
+	"sync"
+	"time"
+)
+
+// Background feed warmer: the reason news is INSTANT.
+//
+// On boot and every interval (jittered) it fetches every warm feed, write-throughs
+// the body to the shared cache, and folds the items into the lake. So the
+// on-demand endpoints (rss-proxy, feeds-batch) ALWAYS serve from the warm cache
+// and never block a request on an upstream — stale-while-revalidate, with the
+// revalidation done here in the background instead of on the request path.
+//
+// Cross-pod dedupe is implicit: a feed whose SHARED (hanzo-kv) copy is still
+// fresh is skipped, so N pods don't all hammer the same upstream every cycle;
+// whichever pod refreshes first, the rest read its result.
+const (
+	feedWarmInterval     = 5 * time.Minute
+	feedWarmParallel     = 8
+	feedWarmFetchTimeout = 10 * time.Second
+	// feedWarmFreshWindow: skip refetch when a cached copy is younger than this
+	// (slightly under the interval so each cycle still refreshes its own feeds).
+	feedWarmFreshWindow = 4 * time.Minute
+)
+
+// startFeedWarmer launches the warmer loop until ctx is cancelled. It warms once
+// shortly after boot (so a cold pod fills fast) then on the jittered interval.
+func (s *Server) startFeedWarmer(ctx context.Context) {
+	go func() {
+		s.warmFeeds(ctx)
+		for {
+			select {
+			case <-ctx.Done():
+				return
+			case <-time.After(jitter(feedWarmInterval)):
+				s.warmFeeds(ctx)
+			}
+		}
+	}()
+}
+
+// warmFeeds refreshes every warm feed in parallel (bounded), skipping any whose
+// shared copy is still fresh. Each fetch is independently bounded; one slow
+// upstream cannot hold up the rest.
+func (s *Server) warmFeeds(ctx context.Context) {
+	urls := s.feeds.WarmURLs(ctx)
+	if len(urls) == 0 {
+		return
+	}
+	sem := make(chan struct{}, feedWarmParallel)
+	var wg sync.WaitGroup
+	refreshed := 0
+	var mu sync.Mutex
+	for _, u := range urls {
+		if ctx.Err() != nil {
+			break
+		}
+		if age, ok := s.feeds.Age(ctx, u); ok && age < feedWarmFreshWindow {
+			continue // a peer (or an earlier cycle) already refreshed it
+		}
+		wg.Add(1)
+		sem <- struct{}{}
+		go func(u string) {
+			defer wg.Done()
+			defer func() { <-sem }()
+			fctx, cancel := context.WithTimeout(ctx, feedWarmFetchTimeout)
+			defer cancel()
+			if body, ok := s.fetchFeedBody(fctx, u); ok {
+				s.feeds.Put(u, body)
+				s.ingestFeedItems(u, body)
+				mu.Lock()
+				refreshed++
+				mu.Unlock()
+			}
+		}(u)
+	}
+	wg.Wait()
+	if refreshed > 0 {
+		logf("world-feeds: warmed %d/%d feeds", refreshed, len(urls))
+	}
+}
+
+// jitter returns d spread by ±20% so pods don't synchronize their warm cycles.
+func jitter(d time.Duration) time.Duration {
+	spread := int64(d) / 5 // 20%
+	if spread <= 0 {
+		return d
+	}
+	return d + time.Duration(rand.Int63n(2*spread)-spread)
+}

internal/world/feed_warmer_test.go

@@ -0,0 +1,115 @@
+package world
+
+import (
+	"context"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/hanzoai/world/internal/world/kv"
+)
+
+const stubRSS = `<?xml version="1.0"?><rss version="2.0"><channel>
+<item><title>Bitcoin warms the cache</title><link>https://x/1</link><pubDate>Mon, 02 Jan 2006 15:04:05 -0700</pubDate></item>
+<item><title>SEC regulation update</title><link>https://x/2</link></item>
+</channel></rss>`
+
+// stubFeed stands up a counting RSS upstream and allowlists its host for the
+// duration of the test (the SSRF boundary is a package var).
+func stubFeed(t *testing.T) (feedURL string, hits *int32) {
+	t.Helper()
+	var n int32
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		atomic.AddInt32(&n, 1)
+		w.Header().Set("Content-Type", "application/xml")
+		_, _ = w.Write([]byte(stubRSS))
+	}))
+	t.Cleanup(srv.Close)
+	host := mustHost(t, srv.URL)
+	allowedRSSDomains[host] = true
+	t.Cleanup(func() { delete(allowedRSSDomains, host) })
+	return srv.URL + "/rss.xml", &n
+}
+
+// newTestServer builds a Server with the embedded store in a temp dir and
+// hanzo-kv disabled (pure per-pod cache) — hermetic, no external services.
+func newTestServer(t *testing.T) *Server {
+	t.Helper()
+	t.Setenv("WORLD_DATA_DIR", t.TempDir())
+	t.Setenv("WORLD_KV_DISABLE", "1")
+	s := NewServer()
+	t.Cleanup(s.Close)
+	return s
+}
+
+func TestWarmerPopulatesCache(t *testing.T) {
+	feedURL, hits := stubFeed(t)
+	s := newTestServer(t)
+	// Seed the warm set with the stub feed (demand-driven registration stand-in).
+	s.feeds = NewFeedCache(kv.Open("", ""), 0, []string{feedURL})
+
+	s.warmFeeds(context.Background())
+
+	if got := atomic.LoadInt32(hits); got != 1 {
+		t.Fatalf("upstream fetched %d times, want 1", got)
+	}
+	body, _, ok := s.feeds.Get(context.Background(), feedURL)
+	if !ok || len(body) == 0 {
+		t.Fatal("warmer did not populate the cache")
+	}
+	if string(body) != stubRSS {
+		t.Fatalf("cached body mismatch")
+	}
+}
+
+func TestWarmerSkipsFreshFeeds(t *testing.T) {
+	feedURL, hits := stubFeed(t)
+	s := newTestServer(t)
+	s.feeds = NewFeedCache(kv.Open("", ""), 0, nil)
+	// Pre-warm: a fresh copy already in cache (age < freshWindow).
+	s.feeds.Put(feedURL, []byte(stubRSS))
+
+	s.warmFeeds(context.Background())
+
+	if got := atomic.LoadInt32(hits); got != 0 {
+		t.Fatalf("upstream hit %d times, want 0 (fresh feed must be skipped)", got)
+	}
+}
+
+// TestWarmedFeedServedInstantly is the end-to-end promise: once warmed, the
+// feeds-batch fall-through serves from cache WITHOUT any upstream fetch.
+func TestWarmedFeedServedInstantly(t *testing.T) {
+	feedURL, hits := stubFeed(t)
+	s := newTestServer(t)
+	s.feeds = NewFeedCache(kv.Open("", ""), 0, []string{feedURL})
+	s.warmFeeds(context.Background()) // one upstream fetch
+
+	// A subsequent request must be served from the warm cache — no new fetch.
+	start := time.Now()
+	body, ok, fresh := s.feedXML(context.Background(), feedURL)
+	elapsed := time.Since(start)
+	if !ok || fresh {
+		t.Fatalf("feedXML ok=%v fresh=%v, want served-from-cache", ok, fresh)
+	}
+	if len(body) == 0 {
+		t.Fatal("empty body from warm cache")
+	}
+	if got := atomic.LoadInt32(hits); got != 1 {
+		t.Fatalf("upstream hit %d times, want 1 (warm read must not refetch)", got)
+	}
+	if elapsed > 50*time.Millisecond {
+		t.Fatalf("warm read took %s, want <50ms", elapsed)
+	}
+}
+
+func mustHost(t *testing.T, raw string) string {
+	t.Helper()
+	u, err := url.Parse(raw)
+	if err != nil {
+		t.Fatalf("parse %q: %v", raw, err)
+	}
+	return u.Hostname()
+}

internal/world/feedcache.go

@@ -0,0 +1,201 @@
+package world
+
+import (
+	"bytes"
+	"compress/gzip"
+	"context"
+	"encoding/binary"
+	"io"
+	"sync"
+	"time"
+
+	"github.com/hanzoai/world/internal/world/kv"
+)
+
+// FeedCache is the warm cache for raw RSS/Atom bodies behind the instant
+// news/feeds panels. It is a two-tier cache, ONE way to read a feed body:
+//
+//	L1 — a per-pod in-memory mirror: hot reads never touch the network.
+//	L2 — hanzo-kv (shared, cross-pod, survives pod restart): a warm body written
+//	     by any pod's warmer is instantly available to every pod, and a restarted
+//	     pod repopulates L1 from L2 instead of cold-starting.
+//
+// The warm-URL set (which feeds to keep fresh) is demand-driven: any feed served
+// once is registered, persisted fleet-wide in hanzo-kv, and kept fresh by the
+// background warmer. A curated seed guarantees the highest-value panels are warm
+// even on a brand-new pod before the first request. When hanzo-kv is
+// unreachable, everything degrades to the in-mem tier — still correct, just
+// per-pod and cold across restart.
+type FeedCache struct {
+	mu   sync.RWMutex
+	mem  map[string]feedRow  // L1
+	warm map[string]struct{} // in-mem warm-set fallback when kv is down
+	kv   *kv.Client
+	max  int
+}
+
+type feedRow struct {
+	body []byte
+	at   time.Time
+}
+
+const (
+	// feedKeyPrefix / warmSetKey namespace the shared hanzo-kv keys.
+	feedKeyPrefix = "world:feed:v1:"
+	warmSetKey    = "world:feed:warm:v1"
+	// feedKVTTL is the L2 safety horizon. The warmer refreshes every few minutes,
+	// so a live entry is normally far younger; the TTL only bounds abandoned feeds.
+	feedKVTTL = 3 * time.Hour
+	// defaultFeedCacheMax bounds the L1 mirror (news feeds are small; ~500 covers
+	// every frontend variant with room to spare).
+	defaultFeedCacheMax = 1024
+)
+
+// NewFeedCache builds the cache over an (optional) hanzo-kv client, seeding the
+// warm set with the curated bootstrap feeds so a cold pod warms them first.
+func NewFeedCache(kvc *kv.Client, max int, seed []string) *FeedCache {
+	if max <= 0 {
+		max = defaultFeedCacheMax
+	}
+	c := &FeedCache{
+		mem:  make(map[string]feedRow),
+		warm: make(map[string]struct{}),
+		kv:   kvc,
+		max:  max,
+	}
+	for _, u := range seed {
+		c.warm[u] = struct{}{}
+	}
+	// Publish the seed to the shared warm set too (best-effort), so every pod
+	// converges on the same fleet-wide set.
+	if len(seed) > 0 {
+		ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
+		c.kv.SAdd(ctx, warmSetKey, seed...)
+		cancel()
+	}
+	return c
+}
+
+// Get returns a cached feed body and its fetch time. L1 first (instant); on miss
+// it consults the shared L2 and, on a hit, backfills L1 so subsequent reads are
+// instant. Never touches upstream.
+func (c *FeedCache) Get(ctx context.Context, url string) ([]byte, time.Time, bool) {
+	c.mu.RLock()
+	row, ok := c.mem[url]
+	c.mu.RUnlock()
+	if ok {
+		return row.body, row.at, true
+	}
+	if raw, ok := c.kv.GetBytes(ctx, feedKeyPrefix+url); ok {
+		if at, body, ok := decodeFeed(raw); ok {
+			c.storeMem(url, body, at)
+			return body, at, true
+		}
+	}
+	return nil, time.Time{}, false
+}
+
+// Put write-throughs a freshly fetched body to both tiers and registers the URL
+// in the warm set (demand-driven). It uses a detached, bounded context for the
+// shared-tier writes so a write-through is never truncated by the request that
+// triggered it — durability must outlive the request. The fetch time is now.
+func (c *FeedCache) Put(url string, body []byte) {
+	at := time.Now()
+	c.storeMem(url, body, at)
+	c.mu.Lock()
+	c.warm[url] = struct{}{}
+	c.mu.Unlock()
+	raw := encodeFeed(at, body)
+	ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
+	defer cancel()
+	c.kv.SetBytes(ctx, feedKeyPrefix+url, raw, feedKVTTL)
+	c.kv.SAdd(ctx, warmSetKey, url)
+}
+
+// Age returns how old the cached copy is, if any (for the warmer's
+// skip-if-fresh, cross-pod dedupe).
+func (c *FeedCache) Age(ctx context.Context, url string) (time.Duration, bool) {
+	if _, at, ok := c.Get(ctx, url); ok {
+		return time.Since(at), true
+	}
+	return 0, false
+}
+
+// WarmURLs is the set of feeds to keep fresh: the fleet-wide set from hanzo-kv
+// unioned with the in-mem set (seed + demand). Deduped.
+func (c *FeedCache) WarmURLs(ctx context.Context) []string {
+	set := make(map[string]struct{})
+	for _, u := range c.kv.SMembers(ctx, warmSetKey) {
+		set[u] = struct{}{}
+	}
+	c.mu.RLock()
+	for u := range c.warm {
+		set[u] = struct{}{}
+	}
+	for u := range c.mem {
+		set[u] = struct{}{}
+	}
+	c.mu.RUnlock()
+	out := make([]string, 0, len(set))
+	for u := range set {
+		out = append(out, u)
+	}
+	return out
+}
+
+// Len reports the L1 mirror size (for tests/introspection).
+func (c *FeedCache) Len() int {
+	c.mu.RLock()
+	defer c.mu.RUnlock()
+	return len(c.mem)
+}
+
+// storeMem writes L1, evicting the oldest entry when at capacity.
+func (c *FeedCache) storeMem(url string, body []byte, at time.Time) {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	if _, exists := c.mem[url]; !exists && len(c.mem) >= c.max {
+		var oldestKey string
+		var oldest time.Time
+		first := true
+		for k, r := range c.mem {
+			if first || r.at.Before(oldest) {
+				oldestKey, oldest, first = k, r.at, false
+			}
+		}
+		if oldestKey != "" {
+			delete(c.mem, oldestKey)
+		}
+	}
+	c.mem[url] = feedRow{body: body, at: at}
+}
+
+// ── L2 encoding: [8-byte unix-nano fetch time][gzip(body)] ───────────────────
+
+func encodeFeed(at time.Time, body []byte) []byte {
+	var buf bytes.Buffer
+	var ts [8]byte
+	binary.BigEndian.PutUint64(ts[:], uint64(at.UnixNano()))
+	buf.Write(ts[:])
+	gz := gzip.NewWriter(&buf)
+	_, _ = gz.Write(body)
+	_ = gz.Close()
+	return buf.Bytes()
+}
+
+func decodeFeed(raw []byte) (time.Time, []byte, bool) {
+	if len(raw) < 8 {
+		return time.Time{}, nil, false
+	}
+	at := time.Unix(0, int64(binary.BigEndian.Uint64(raw[:8])))
+	gz, err := gzip.NewReader(bytes.NewReader(raw[8:]))
+	if err != nil {
+		return time.Time{}, nil, false
+	}
+	defer func() { _ = gz.Close() }()
+	body, err := io.ReadAll(io.LimitReader(gz, maxBody))
+	if err != nil {
+		return time.Time{}, nil, false
+	}
+	return at, body, true
+}

internal/world/feedcache_test.go

@@ -0,0 +1,118 @@
+package world
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	"github.com/alicebob/miniredis/v2"
+	"github.com/hanzoai/world/internal/world/kv"
+)
+
+func TestFeedEncodeDecodeRoundTrip(t *testing.T) {
+	at := time.Now().Truncate(time.Nanosecond)
+	body := []byte("<rss><item>hello</item></rss>")
+	gotAt, gotBody, ok := decodeFeed(encodeFeed(at, body))
+	if !ok {
+		t.Fatal("decode failed")
+	}
+	if !gotAt.Equal(at) {
+		t.Fatalf("time round-trip = %v, want %v", gotAt, at)
+	}
+	if string(gotBody) != string(body) {
+		t.Fatalf("body round-trip = %q, want %q", gotBody, body)
+	}
+	if _, _, ok := decodeFeed([]byte("short")); ok {
+		t.Fatal("decode of truncated blob should fail")
+	}
+}
+
+// TestFeedCacheSharedAcrossPods proves the L2 (hanzo-kv) tier: a body written by
+// one pod is served to another pod whose L1 is cold — i.e. warming once benefits
+// the fleet, and a restarted pod (empty L1) reads a still-warm shared cache.
+func TestFeedCacheSharedAcrossPods(t *testing.T) {
+	mr := miniredis.RunT(t)
+	kvA := kv.Open(mr.Addr(), "")
+	kvB := kv.Open(mr.Addr(), "")
+	t.Cleanup(func() { kvA.Close(); kvB.Close() })
+
+	podA := NewFeedCache(kvA, 0, nil)
+	podB := NewFeedCache(kvB, 0, nil) // separate pod: cold L1, shared L2
+
+	const url = "https://feeds.example.com/rss.xml"
+	body := []byte("<rss><channel><item><title>Shared</title></item></channel></rss>")
+	podA.Put(url, body)
+
+	if podB.Len() != 0 {
+		t.Fatalf("podB L1 should start cold, has %d", podB.Len())
+	}
+	got, _, ok := podB.Get(context.Background(), url)
+	if !ok || string(got) != string(body) {
+		t.Fatalf("podB Get via shared L2 = %q ok=%v, want the shared body", got, ok)
+	}
+	if podB.Len() != 1 {
+		t.Fatal("podB should have backfilled L1 from L2")
+	}
+	// The warm-URL set is fleet-wide (shared set), so podB knows to keep it fresh.
+	if !hasURL(podB.WarmURLs(context.Background()), url) {
+		t.Fatal("shared warm set missing the demand-added url")
+	}
+}
+
+// TestFeedCacheDegradesWithoutKV proves the graceful fallback: with hanzo-kv
+// disabled the cache is per-pod (L1 only) and correct — a "restart" (new cache)
+// is cold, never a crash.
+func TestFeedCacheDegradesWithoutKV(t *testing.T) {
+	disabled := kv.Open("", "") // no hanzo-kv
+	c := NewFeedCache(disabled, 0, nil)
+
+	const url = "https://feeds.example.com/x.xml"
+	body := []byte("<rss/>")
+	c.Put(url, body)
+
+	got, _, ok := c.Get(context.Background(), url)
+	if !ok || string(got) != string(body) {
+		t.Fatalf("same-pod L1 Get = %q ok=%v", got, ok)
+	}
+	// A fresh cache (simulated restart) with no shared L2 must miss — proving the
+	// per-pod degrade is honest, not silently wrong.
+	fresh := NewFeedCache(disabled, 0, nil)
+	if _, _, ok := fresh.Get(context.Background(), url); ok {
+		t.Fatal("restart with kv disabled should be cold, got a hit")
+	}
+}
+
+func TestFeedCacheSeedInWarmSet(t *testing.T) {
+	c := NewFeedCache(kv.Open("", ""), 0, []string{"https://a.example/rss", "https://b.example/rss"})
+	warm := c.WarmURLs(context.Background())
+	if !hasURL(warm, "https://a.example/rss") || !hasURL(warm, "https://b.example/rss") {
+		t.Fatalf("seed missing from warm set: %v", warm)
+	}
+}
+
+func TestFeedCacheEvictsOldest(t *testing.T) {
+	c := NewFeedCache(kv.Open("", ""), 2, nil)
+	c.Put("u1", []byte("1"))
+	time.Sleep(2 * time.Millisecond)
+	c.Put("u2", []byte("2"))
+	time.Sleep(2 * time.Millisecond)
+	c.Put("u3", []byte("3")) // over cap → evict u1 (oldest)
+	if c.Len() != 2 {
+		t.Fatalf("L1 size = %d, want 2 (bounded)", c.Len())
+	}
+	if _, _, ok := c.Get(context.Background(), "u1"); ok {
+		t.Fatal("oldest entry u1 was not evicted")
+	}
+	if _, _, ok := c.Get(context.Background(), "u3"); !ok {
+		t.Fatal("newest entry u3 missing")
+	}
+}
+
+func hasURL(ss []string, want string) bool {
+	for _, s := range ss {
+		if s == want {
+			return true
+		}
+	}
+	return false
+}

internal/world/handlers_ai.go

@@ -0,0 +1,322 @@
+package world
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"strings"
+	"time"
+)
+
+// decodeJSONBody decodes a bounded request body into v.
+func decodeJSONBody(r *http.Request, v any) error {
+	dec := json.NewDecoder(r.Body)
+	return dec.Decode(v)
+}
+
+var validLevels = map[string]bool{"critical": true, "high": true, "medium": true, "low": true, "info": true}
+var validCategories = map[string]bool{
+	"conflict": true, "protest": true, "disaster": true, "diplomatic": true, "economic": true, "terrorism": true,
+	"cyber": true, "health": true, "environmental": true, "military": true, "crime": true, "infrastructure": true,
+	"tech": true, "general": true,
+}
+
+// ── Summarize (groq/openrouter → Hanzo inference) ────────────────────────────
+
+// handleSummarize backs both /v1/world/groq-summarize and /v1/world/openrouter-summarize,
+// routed to Hanzo's own inference instead of a third-party LLM. Ported from
+// api/groq-summarize.js + api/openrouter-summarize.js.
+func (s *Server) handleSummarize(w http.ResponseWriter, r *http.Request) {
+	if preflight(w, r, "POST, OPTIONS") {
+		return
+	}
+	if r.Method != http.MethodPost {
+		writeError(w, http.StatusMethodNotAllowed, "Method not allowed")
+		return
+	}
+	var body struct {
+		Headlines  []string `json:"headlines"`
+		Mode       string   `json:"mode"`
+		GeoContext string   `json:"geoContext"`
+		Variant    string   `json:"variant"`
+		Lang       string   `json:"lang"`
+	}
+	if err := decodeJSONBody(r, &body); err != nil {
+		writeError(w, http.StatusBadRequest, "Invalid JSON body")
+		return
+	}
+	if len(body.Headlines) == 0 {
+		writeError(w, http.StatusBadRequest, "Headlines array required")
+		return
+	}
+	bearer := s.ai.bearerFor(r)
+	if bearer == "" {
+		writeJSON(w, http.StatusOK, "", map[string]any{"summary": nil, "fallback": true, "skipped": true, "reason": "Sign in to enable AI insights"})
+		return
+	}
+	mode := body.Mode
+	if mode == "" {
+		mode = "brief"
+	}
+	variant := body.Variant
+	if variant == "" {
+		variant = "full"
+	}
+	isTech := variant == "tech"
+	heads := body.Headlines
+	if len(heads) > 8 {
+		heads = heads[:8]
+	}
+	numbered := numberLines(heads)
+	intel := ""
+	if body.GeoContext != "" {
+		intel = "\n\n" + body.GeoContext
+	}
+	langNote := ""
+	if body.Lang != "" && body.Lang != "en" {
+		langNote = "\nIMPORTANT: Output the summary in " + body.Lang + " language."
+	}
+
+	var system, user string
+	switch mode {
+	case "analysis":
+		system = dateContext(isTech) + " You are a geopolitical analyst. Identify the single most important pattern or risk in these headlines in 2-3 sentences." + langNote
+		user = "What's the key pattern or risk?\n" + numbered + intel
+	case "translate":
+		system = "You are a professional news translator. Translate the text faithfully into " + variant + ", preserving meaning and tone. Output only the translation."
+		user = "Translate to " + variant + ":\n" + body.Headlines[0]
+	case "brief":
+		system = dateContext(isTech) + " Summarize the key development across these headlines in 2-3 clear sentences. Be factual and concise." + langNote
+		user = "Summarize the top story:\n" + numbered + intel
+	default:
+		system = dateContext(isTech) + " Synthesize the key takeaway from these headlines in 2 sentences." + langNote
+		user = "Key takeaway:\n" + numbered + intel
+	}
+
+	ctx, cancel := context.WithTimeout(r.Context(), 30*time.Second)
+	defer cancel()
+	out, tokens, err := s.ai.chat(ctx, s, bearer, system, user, 0.3, 150, aiForwardHeaders(r))
+	if err != nil || out == "" {
+		writeJSON(w, http.StatusOK, "", map[string]any{"summary": nil, "fallback": true, "error": errStr(err)})
+		return
+	}
+	writeJSON(w, http.StatusOK, "public, max-age=1800, s-maxage=1800, stale-while-revalidate=300",
+		map[string]any{"summary": out, "model": s.ai.model, "provider": "hanzo", "cached": false, "tokens": tokens})
+}
+
+// ── Classify batch ───────────────────────────────────────────────────────────
+
+// handleClassifyBatch classifies a batch of headlines into threat level +
+// category via Hanzo inference. Ported from api/classify-batch.js.
+func (s *Server) handleClassifyBatch(w http.ResponseWriter, r *http.Request) {
+	if preflight(w, r, "POST, OPTIONS") {
+		return
+	}
+	if r.Method != http.MethodPost {
+		writeError(w, http.StatusMethodNotAllowed, "Method not allowed")
+		return
+	}
+	var body struct {
+		Titles  []string `json:"titles"`
+		Variant string   `json:"variant"`
+	}
+	if err := decodeJSONBody(r, &body); err != nil {
+		writeError(w, http.StatusBadRequest, "Invalid JSON body")
+		return
+	}
+	if len(body.Titles) == 0 {
+		writeError(w, http.StatusBadRequest, "titles array required")
+		return
+	}
+	bearer := s.ai.bearerFor(r)
+	if bearer == "" {
+		writeJSON(w, http.StatusOK, "", map[string]any{"results": []any{}, "fallback": true, "skipped": true, "reason": "Sign in to enable AI insights"})
+		return
+	}
+	titles := body.Titles
+	if len(titles) > 20 {
+		titles = titles[:20]
+	}
+	system := classifySystemPrompt(body.Variant == "tech", true)
+	user := numberLines(titles)
+	ctx, cancel := context.WithTimeout(r.Context(), 30*time.Second)
+	defer cancel()
+	out, _, err := s.ai.chat(ctx, s, bearer, system, user, 0, len(titles)*60, aiForwardHeaders(r))
+	results := make([]any, len(titles))
+	if err == nil {
+		parsed := parseClassifyArray(out)
+		for i := range titles {
+			if i < len(parsed) && parsed[i] != nil {
+				results[i] = map[string]any{"level": parsed[i]["level"], "category": parsed[i]["category"], "cached": false}
+			}
+		}
+	}
+	fallback := err != nil
+	resp := map[string]any{"results": results}
+	if fallback {
+		resp["fallback"] = true
+	}
+	writeJSON(w, http.StatusOK, "public, max-age=3600, s-maxage=3600, stale-while-revalidate=600", resp)
+}
+
+// ── Classify single event ────────────────────────────────────────────────────
+
+// handleClassifyEvent classifies a single headline. Ported from
+// api/classify-event.js.
+func (s *Server) handleClassifyEvent(w http.ResponseWriter, r *http.Request) {
+	if preflight(w, r, "GET, OPTIONS") || methodNotGet(w, r) {
+		return
+	}
+	title := r.URL.Query().Get("title")
+	if title == "" {
+		writeError(w, http.StatusBadRequest, "title param required")
+		return
+	}
+	bearer := s.ai.bearerFor(r)
+	if bearer == "" {
+		writeJSON(w, http.StatusOK, "", map[string]any{"fallback": true, "skipped": true, "reason": "Sign in to enable AI insights"})
+		return
+	}
+	system := classifySystemPrompt(r.URL.Query().Get("variant") == "tech", false)
+	ctx, cancel := context.WithTimeout(r.Context(), 20*time.Second)
+	defer cancel()
+	out, _, err := s.ai.chat(ctx, s, bearer, system, title, 0, 50, aiForwardHeaders(r))
+	if err != nil {
+		writeJSON(w, http.StatusOK, "", map[string]any{"fallback": true})
+		return
+	}
+	obj := parseClassifyObject(out)
+	if obj == nil {
+		writeJSON(w, http.StatusOK, "", map[string]any{"fallback": true})
+		return
+	}
+	writeJSON(w, http.StatusOK, "public, max-age=3600, s-maxage=3600, stale-while-revalidate=600",
+		map[string]any{"level": obj["level"], "category": obj["category"], "confidence": 0.9, "source": "llm", "cached": false})
+}
+
+// ── Country intel brief ──────────────────────────────────────────────────────
+
+// handleCountryIntel generates an analyst brief for a country. Ported from
+// api/country-intel.js.
+func (s *Server) handleCountryIntel(w http.ResponseWriter, r *http.Request) {
+	if preflight(w, r, "POST, OPTIONS") {
+		return
+	}
+	if r.Method != http.MethodPost {
+		writeError(w, http.StatusMethodNotAllowed, "Method not allowed")
+		return
+	}
+	var body struct {
+		Country string         `json:"country"`
+		Code    string         `json:"code"`
+		Context map[string]any `json:"context"`
+	}
+	if err := decodeJSONBody(r, &body); err != nil {
+		writeError(w, http.StatusBadRequest, "Invalid JSON body")
+		return
+	}
+	if body.Country == "" || body.Code == "" {
+		writeError(w, http.StatusBadRequest, "country and code required")
+		return
+	}
+	bearer := s.ai.bearerFor(r)
+	if bearer == "" {
+		writeJSON(w, http.StatusOK, "", map[string]any{"intel": nil, "fallback": true, "skipped": true, "reason": "Sign in to enable AI insights"})
+		return
+	}
+	system := dateContext(false) + " You are a senior intelligence analyst. Produce a concise country brief with sections: Current Situation; Military & Security Posture; Key Risk Factors; Regional Context; Outlook & Watch Items. 5-6 paragraphs, factual, cite provided headlines as [N] where relevant."
+	dataSection := "\nNo real-time sensor data available for this country."
+	if len(body.Context) > 0 {
+		if b, err := json.Marshal(body.Context); err == nil {
+			dataSection = "\nCURRENT SENSOR DATA:\n" + string(b)
+		}
+	}
+	// Ground the brief in the world model: the country's continuously-folded
+	// state vector, so the narrative tracks the numbers rather than raw feeds.
+	modelSection := ""
+	if mv, ok := s.worldModel.CountryContext(body.Code); ok {
+		if b, err := json.Marshal(mv); err == nil {
+			modelSection = "\nWORLD-MODEL STATE VECTOR:\n" + string(b)
+		}
+	}
+	user := "Country: " + body.Country + " (" + body.Code + ")" + dataSection + modelSection
+	ctx, cancel := context.WithTimeout(r.Context(), 40*time.Second)
+	defer cancel()
+	brief, _, err := s.ai.chat(ctx, s, bearer, system, user, 0.4, 900, aiForwardHeaders(r))
+	if err != nil {
+		writeJSON(w, http.StatusOK, "", map[string]any{"error": "AI service error", "fallback": true})
+		return
+	}
+	writeJSON(w, http.StatusOK, "public, max-age=3600, s-maxage=3600, stale-while-revalidate=600",
+		map[string]any{"brief": brief, "country": body.Country, "code": body.Code, "model": s.ai.model, "generatedAt": nowISO()})
+}
+
+// ── AI helpers ───────────────────────────────────────────────────────────────
+
+func classifySystemPrompt(isTech, batch bool) string {
+	focus := "Focus on geopolitical, conflict and security relevance."
+	if isTech {
+		focus = "Focus on technology, AI, startups and markets."
+	}
+	ret := `Return: {"level":"...","category":"..."}`
+	if batch {
+		ret = `Return a JSON array with one object per headline in order: [{"level":"...","category":"..."},...]`
+	}
+	return "You classify news headlines into threat level and category. Return ONLY valid JSON, no other text.\n" +
+		"Levels: critical, high, medium, low, info\n" +
+		"Categories: conflict, protest, disaster, diplomatic, economic, terrorism, cyber, health, environmental, military, crime, infrastructure, tech, general\n" +
+		focus + "\n" + ret
+}
+
+func parseClassifyArray(raw string) []map[string]string {
+	raw = strings.TrimSpace(raw)
+	var arr []map[string]string
+	if json.Unmarshal([]byte(raw), &arr) != nil {
+		i, j := strings.Index(raw, "["), strings.LastIndex(raw, "]")
+		if i < 0 || j <= i {
+			return nil
+		}
+		if json.Unmarshal([]byte(raw[i:j+1]), &arr) != nil {
+			return nil
+		}
+	}
+	for k, item := range arr {
+		if !validLevels[item["level"]] || !validCategories[item["category"]] {
+			arr[k] = nil
+		}
+	}
+	return arr
+}
+
+func parseClassifyObject(raw string) map[string]string {
+	raw = strings.TrimSpace(raw)
+	var obj map[string]string
+	if json.Unmarshal([]byte(raw), &obj) != nil {
+		i, j := strings.Index(raw, "{"), strings.LastIndex(raw, "}")
+		if i < 0 || j <= i || json.Unmarshal([]byte(raw[i:j+1]), &obj) != nil {
+			return nil
+		}
+	}
+	if !validLevels[obj["level"]] || !validCategories[obj["category"]] {
+		return nil
+	}
+	return obj
+}
+
+func numberLines(items []string) string {
+	var b strings.Builder
+	for i, it := range items {
+		b.WriteString(itoa(i + 1))
+		b.WriteString(". ")
+		b.WriteString(it)
+		b.WriteString("\n")
+	}
+	return strings.TrimRight(b.String(), "\n")
+}
+
+func errStr(err error) any {
+	if err == nil {
+		return nil
+	}
+	return err.Error()
+}

internal/world/handlers_ai_pulse.go

@@ -0,0 +1,269 @@
+package world
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"strings"
+	"time"
+)
+
+// AI Compute pulse — the live "what is Hanzo's inference plane doing right now"
+// stream for the AI variant (world.hanzo.ai/?variant=ai). It is the same honest
+// platform aggregate cloud-pulse reads, reshaped for a compute-first panel and
+// PUSHED over SSE so the number moves without the client polling.
+//
+// ONE route, two representations (the handleAnalyst idiom): an EventSource client
+// (Accept: text/event-stream) gets typed events — `usage` (tokens/s, req/s, spend,
+// top models) and `fleet` (gpu/machine/region counts) — re-emitted each interval,
+// plus a `status` frame carrying the honest state. A plain GET gets ONE JSON
+// snapshot of the same data, which the frontend uses as its poll fallback.
+//
+// Honesty: with no service token, or when every upstream is unreachable, the
+// state is "unavailable" with a reason — the panel says so rather than showing a
+// zero as if it were live. The service bearer is read server-side only and never
+// reaches the browser.
+
+const (
+	aiPulseKey      = "ai-pulse"
+	aiPulseTTL      = 10 * time.Second // shared snapshot horizon (coalesces SSE clients)
+	aiPulseFailTTL  = 3 * time.Second  // retry an unavailable pulse sooner
+	aiPulseInterval = 15 * time.Second // SSE re-emit cadence
+)
+
+// aiUsage is the measured inference volume (get-cloud-usages ?org=all).
+type aiUsage struct {
+	Window         string       `json:"window"`
+	RequestsPerSec float64      `json:"requestsPerSec"`
+	TokensPerSec   float64      `json:"tokensPerSec"`
+	Requests24h    int64        `json:"requests24h"`
+	Tokens24h      int64        `json:"tokens24h"`
+	SpendCents     int64        `json:"spendCents"`
+	Models         []cloudModel `json:"models"` // top by real spend
+}
+
+// aiFleet is the live serving fleet (visor + ai catalog). Counts only.
+type aiFleet struct {
+	Machines       int `json:"machines"`
+	MachinesOnline int `json:"machinesOnline"`
+	Gpus           int `json:"gpus"`
+	Regions        int `json:"regions"`
+	ModelsServed   int `json:"modelsServed"`
+}
+
+// aiPulse is one snapshot of the compute plane. State is "live" when at least one
+// half resolved, else "unavailable" with a Reason.
+type aiPulse struct {
+	State     string   `json:"state"` // "live" | "unavailable"
+	Reason    string   `json:"reason,omitempty"`
+	UpdatedAt string   `json:"updatedAt"`
+	Usage     *aiUsage `json:"usage,omitempty"`
+	Fleet     *aiFleet `json:"fleet,omitempty"`
+}
+
+// typed SSE frames. Embedding the pointer flattens its JSON fields under the
+// envelope's "type", so the wire shape stays DRY with the snapshot structs.
+type aiUsageEvent struct {
+	Type string `json:"type"` // "usage"
+	*aiUsage
+	UpdatedAt string `json:"updatedAt"`
+}
+
+type aiFleetEvent struct {
+	Type string `json:"type"` // "fleet"
+	*aiFleet
+	UpdatedAt string `json:"updatedAt"`
+}
+
+// handleAIPulse serves the compute pulse as SSE (EventSource) or, for a plain GET,
+// a single JSON snapshot (the poll fallback). It never 5xxes.
+func (s *Server) handleAIPulse(w http.ResponseWriter, r *http.Request) {
+	if preflight(w, r, "GET, OPTIONS") || methodNotGet(w, r) {
+		return
+	}
+	ctx := r.Context()
+
+	if strings.Contains(r.Header.Get("Accept"), "text/event-stream") {
+		if f, ok := w.(http.Flusher); ok {
+			h := w.Header()
+			h.Set("Content-Type", "text/event-stream; charset=utf-8")
+			h.Set("Cache-Control", "no-cache")
+			h.Set("X-Accel-Buffering", "no")
+			w.WriteHeader(http.StatusOK)
+			emit := func(v any) {
+				b, _ := json.Marshal(v)
+				_, _ = w.Write([]byte("data: "))
+				_, _ = w.Write(b)
+				_, _ = w.Write([]byte("\n\n"))
+				f.Flush()
+			}
+			s.streamAIPulse(ctx, emit)
+			return
+		}
+	}
+
+	// Poll fallback: one JSON snapshot (never cached downstream — it is live).
+	// EventSource cannot send Authorization, so the AUTHED transport is this poll:
+	// a signed-in admin gets a fresh per-caller snapshot built with THEIR OWN bearer
+	// (full measured usage + fleet), never the shared service-token snapshot.
+	w.Header().Set("Vary", "Authorization")
+	sctx, cancel := context.WithTimeout(ctx, 20*time.Second)
+	defer cancel()
+	if bearer, ok := s.adminIdentity(r); ok {
+		writeJSON(w, http.StatusOK, "private, no-store", s.produceAIPulse(sctx, map[string]string{"Authorization": bearer}))
+		return
+	}
+	writeJSON(w, http.StatusOK, "no-store", s.aiPulseSnapshot(sctx))
+}
+
+// streamAIPulse pushes the snapshot immediately, then re-emits on the interval
+// until the client disconnects (ctx cancelled).
+func (s *Server) streamAIPulse(ctx context.Context, emit func(any)) {
+	send := func(p aiPulse) {
+		if p.Usage != nil {
+			emit(aiUsageEvent{Type: "usage", aiUsage: p.Usage, UpdatedAt: p.UpdatedAt})
+		}
+		if p.Fleet != nil {
+			emit(aiFleetEvent{Type: "fleet", aiFleet: p.Fleet, UpdatedAt: p.UpdatedAt})
+		}
+		emit(map[string]any{"type": "status", "state": p.State, "reason": p.Reason, "updatedAt": p.UpdatedAt})
+	}
+	send(s.aiPulseSnapshot(ctx))
+	t := time.NewTicker(aiPulseInterval)
+	defer t.Stop()
+	for {
+		select {
+		case <-ctx.Done():
+			return
+		case <-t.C:
+			send(s.aiPulseSnapshot(ctx))
+		}
+	}
+}
+
+// aiPulseSnapshot returns the shared snapshot: a fresh cache hit, else one
+// single-flighted produce that many concurrent SSE clients coalesce onto (so N
+// streams cause ~one upstream sweep per aiPulseTTL).
+func (s *Server) aiPulseSnapshot(ctx context.Context) aiPulse {
+	if v, ok := s.cache.Get(aiPulseKey); ok {
+		return v.(aiPulse)
+	}
+	v, _ := s.flight.do(aiPulseKey, func() (any, error) {
+		p := s.produceAIPulse(ctx, serviceAuth())
+		ttl := aiPulseTTL
+		if p.State != "live" {
+			ttl = aiPulseFailTTL
+		}
+		s.cache.Set(aiPulseKey, p, ttl, 30*time.Second)
+		return p, nil
+	})
+	return v.(aiPulse)
+}
+
+// produceAIPulse reads both honest halves using auth (the KMS service bearer for the
+// public SSE, or a signed-in admin's OWN bearer for the authed poll). It is "live"
+// when either resolves; "unavailable" (with a reason) when there is no auth or every
+// upstream fails.
+func (s *Server) produceAIPulse(ctx context.Context, auth map[string]string) aiPulse {
+	now := nowRFC()
+	if auth == nil {
+		return aiPulse{State: "unavailable", Reason: "sign in for live compute telemetry (or wire the service token)", UpdatedAt: now}
+	}
+	usage := s.buildAIUsage(ctx, auth)
+	fleet := s.buildAIFleet(ctx, auth)
+	if usage == nil && fleet == nil {
+		return aiPulse{State: "unavailable", Reason: "compute plane unreachable", UpdatedAt: now}
+	}
+	return aiPulse{State: "live", UpdatedAt: now, Usage: usage, Fleet: fleet}
+}
+
+// buildAIUsage maps the measured platform usage ledger into the compute-panel
+// shape, read with auth. nil when the ledger is unreachable (no auth / non-admin /
+// upstream down) so the panel degrades honestly.
+func (s *Server) buildAIUsage(ctx context.Context, auth map[string]string) *aiUsage {
+	ov, err := s.fetchCloudUsage(ctx, "24h", auth)
+	if err != nil {
+		// Exact ledger denied → REAL platform usage from LLM observability (measured
+		// requests/tokens + real model names), so AI Compute shows live numbers for an
+		// operator instead of zeros. nil only when that is also unauthorized.
+		if u, ok := s.fetchLLMUsage(ctx, auth); ok {
+			return &aiUsage{
+				Window:         "24h",
+				RequestsPerSec: round1(float64(u.Requests) / 86400),
+				TokensPerSec:   round1(float64(u.Tokens) / 86400),
+				Requests24h:    u.Requests,
+				Tokens24h:      u.Tokens,
+				Models:         u.Models,
+			}
+		}
+		return nil
+	}
+	window := ov.Range
+	if window == "" {
+		window = "24h"
+	}
+	return &aiUsage{
+		Window:         window,
+		RequestsPerSec: round1(usageRate(ov.Totals.Requests, ov.Series, ov.Interval, seriesRequests)),
+		TokensPerSec:   round1(usageRate(ov.Totals.Tokens, ov.Series, ov.Interval, seriesTokens)),
+		Requests24h:    ov.Totals.Requests,
+		Tokens24h:      ov.Totals.Tokens,
+		SpendCents:     ov.Totals.SpendCents,
+		Models:         topModelsFromUsage(ov),
+	}
+}
+
+// buildAIFleet reads the live serving fleet (visor machines/gpus + ai model
+// catalog) with auth. nil only when the machines read fails; gpus/models are
+// best-effort bonus counts.
+func (s *Server) buildAIFleet(ctx context.Context, hdr map[string]string) *aiFleet {
+	if hdr == nil {
+		return nil
+	}
+	host := apiHost()
+
+	var machines struct {
+		Machines []struct {
+			Region string `json:"region"`
+			Status string `json:"status"`
+		} `json:"machines"`
+	}
+	if err := s.getJSON(ctx, host+"/v1/machines", hdr, &machines); err != nil {
+		return nil
+	}
+	var gpus struct {
+		Gpus []struct {
+			Region string `json:"region"`
+		} `json:"gpus"`
+	}
+	_ = s.getJSON(ctx, host+"/v1/gpus", hdr, &gpus)
+	var models struct {
+		Data []struct {
+			ID string `json:"id"`
+		} `json:"data"`
+	}
+	_ = s.getJSON(ctx, host+"/v1/models", hdr, &models)
+
+	regions := map[string]struct{}{}
+	online := 0
+	for _, m := range machines.Machines {
+		if machineOnline(m.Status) {
+			online++
+		}
+		if m.Region != "" {
+			regions[m.Region] = struct{}{}
+		}
+	}
+	for _, g := range gpus.Gpus {
+		if g.Region != "" {
+			regions[g.Region] = struct{}{}
+		}
+	}
+	return &aiFleet{
+		Machines:       len(machines.Machines),
+		MachinesOnline: online,
+		Gpus:           len(gpus.Gpus),
+		Regions:        len(regions),
+		ModelsServed:   len(models.Data),
+	}
+}

internal/world/handlers_ai_pulse_test.go

@@ -0,0 +1,211 @@
+package world
+
+import (
+	"bufio"
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+	"time"
+)
+
+// aiPulseUpstream is a fake api.hanzo.ai serving the four reads ai-pulse folds.
+func aiPulseUpstream(t *testing.T) *httptest.Server {
+	t.Helper()
+	mux := http.NewServeMux()
+	mux.HandleFunc("/v1/machines", func(w http.ResponseWriter, _ *http.Request) {
+		_, _ = w.Write([]byte(`{"machines":[{"region":"nyc","status":"active"},{"region":"sfo","status":"active"},{"region":"nyc","status":"stopped"}]}`))
+	})
+	mux.HandleFunc("/v1/gpus", func(w http.ResponseWriter, _ *http.Request) {
+		_, _ = w.Write([]byte(`{"gpus":[{"region":"nyc"},{"region":"sfo"},{"region":"nyc"}]}`))
+	})
+	mux.HandleFunc("/v1/models", func(w http.ResponseWriter, _ *http.Request) {
+		_, _ = w.Write([]byte(`{"data":[{"id":"zen-1"},{"id":"zen-omni-30b"}]}`))
+	})
+	mux.HandleFunc("/v1/get-cloud-usages", func(w http.ResponseWriter, _ *http.Request) {
+		_, _ = w.Write([]byte(`{
+			"range":"24h","interval":"1h",
+			"totals":{"tokens":1180000000,"requests":1000000,"spendCents":42000,"models":2},
+			"series":[{"t":"2026-07-16T00:00:00Z","tokens":40000000,"requests":34000},
+			          {"t":"2026-07-16T01:00:00Z","tokens":72000000,"requests":36000}],
+			"byModel":{"items":[{"model":"zen-omni-30b","spendCents":24000,"tokens":600000000,"requests":520000,"pct":57.1}]}
+		}`))
+	})
+	up := httptest.NewServer(mux)
+	t.Cleanup(up.Close)
+	return up
+}
+
+func aiPulseServer(t *testing.T) *httptest.Server {
+	t.Helper()
+	s := NewServer()
+	mux := http.NewServeMux()
+	s.Mount(mux)
+	ts := httptest.NewServer(mux)
+	t.Cleanup(ts.Close)
+	return ts
+}
+
+// TestAIPulseUnavailableWithoutToken: the honest degrade — no token, so the JSON
+// snapshot is state:"unavailable" with a reason, never a zeroed "live".
+func TestAIPulseUnavailableWithoutToken(t *testing.T) {
+	t.Setenv("HANZO_CLOUD_PULSE_TOKEN", "")
+	ts := aiPulseServer(t)
+
+	resp, err := http.Get(ts.URL + "/v1/world/ai-pulse")
+	if err != nil {
+		t.Fatalf("request failed: %v", err)
+	}
+	defer resp.Body.Close()
+	var p aiPulse
+	if err := json.NewDecoder(resp.Body).Decode(&p); err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+	if p.State != "unavailable" || p.Reason == "" {
+		t.Fatalf("want unavailable+reason, got state=%q reason=%q", p.State, p.Reason)
+	}
+	if p.Usage != nil || p.Fleet != nil {
+		t.Fatalf("unavailable must carry no fabricated usage/fleet")
+	}
+}
+
+// TestAIPulseLiveSnapshot: with a token + reachable upstream, the poll-fallback
+// JSON snapshot carries measured usage and the live fleet.
+func TestAIPulseLiveSnapshot(t *testing.T) {
+	up := aiPulseUpstream(t)
+	t.Setenv("HANZO_CLOUD_PULSE_TOKEN", "svc-super-admin")
+	t.Setenv("HANZO_API_BASE", up.URL)
+	ts := aiPulseServer(t)
+
+	resp, err := http.Get(ts.URL + "/v1/world/ai-pulse")
+	if err != nil {
+		t.Fatalf("request failed: %v", err)
+	}
+	defer resp.Body.Close()
+	var p aiPulse
+	if err := json.NewDecoder(resp.Body).Decode(&p); err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+	if p.State != "live" {
+		t.Fatalf("want state=live, got %q (reason %q)", p.State, p.Reason)
+	}
+	if p.Usage == nil || p.Usage.Requests24h != 1_000_000 || p.Usage.SpendCents != 42000 {
+		t.Fatalf("want measured usage, got %+v", p.Usage)
+	}
+	if len(p.Usage.Models) != 1 || p.Usage.Models[0].ID != "zen-omni-30b" {
+		t.Fatalf("want ledger top model, got %+v", p.Usage.Models)
+	}
+	// Recent bucket over 1h interval: 36000 req / 3600s = 10 req/s.
+	if p.Usage.RequestsPerSec != 10 {
+		t.Fatalf("want recent-bucket rate 10 req/s, got %v", p.Usage.RequestsPerSec)
+	}
+	if p.Fleet == nil || p.Fleet.MachinesOnline != 2 || p.Fleet.Machines != 3 || p.Fleet.Gpus != 3 {
+		t.Fatalf("want live fleet 2/3 + 3 gpus, got %+v", p.Fleet)
+	}
+	if p.Fleet.ModelsServed != 2 {
+		t.Fatalf("want modelsServed=2, got %d", p.Fleet.ModelsServed)
+	}
+}
+
+// TestAIPulseSSEFrames: an EventSource-style request gets the typed usage/fleet/
+// status frames in the first (immediate) emit.
+func TestAIPulseSSEFrames(t *testing.T) {
+	up := aiPulseUpstream(t)
+	t.Setenv("HANZO_CLOUD_PULSE_TOKEN", "svc-super-admin")
+	t.Setenv("HANZO_API_BASE", up.URL)
+	ts := aiPulseServer(t)
+
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+	defer cancel()
+	req, _ := http.NewRequestWithContext(ctx, http.MethodGet, ts.URL+"/v1/world/ai-pulse", nil)
+	req.Header.Set("Accept", "text/event-stream")
+	resp, err := http.DefaultClient.Do(req)
+	if err != nil {
+		t.Fatalf("sse request failed: %v", err)
+	}
+	defer resp.Body.Close()
+	if ct := resp.Header.Get("Content-Type"); !strings.Contains(ct, "text/event-stream") {
+		t.Fatalf("want event-stream, got %q", ct)
+	}
+
+	seen := map[string]bool{}
+	sc := bufio.NewScanner(resp.Body)
+	for sc.Scan() {
+		line := strings.TrimSpace(sc.Text())
+		if !strings.HasPrefix(line, "data:") {
+			continue
+		}
+		var ev struct {
+			Type  string `json:"type"`
+			State string `json:"state"`
+		}
+		if json.Unmarshal([]byte(strings.TrimPrefix(line, "data:")), &ev) != nil {
+			continue
+		}
+		seen[ev.Type] = true
+		if ev.Type == "status" { // terminal frame of the first emit
+			if ev.State != "live" {
+				t.Fatalf("want status state=live, got %q", ev.State)
+			}
+			break
+		}
+	}
+	for _, want := range []string{"usage", "fleet", "status"} {
+		if !seen[want] {
+			t.Fatalf("missing %q frame (saw %v)", want, seen)
+		}
+	}
+}
+
+// TestAIPulseAdminPoll proves the authed poll: a signed-in admin (z@hanzo.ai) with
+// NO server-side service token gets the FULL measured compute pulse built with their
+// OWN bearer, served no-store. EventSource can't carry auth, so this poll is the
+// admin's live transport.
+func TestAIPulseAdminPoll(t *testing.T) {
+	iam := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/v1/iam/oauth/userinfo" || r.Header.Get("Authorization") == "" {
+			http.NotFound(w, r)
+			return
+		}
+		_, _ = w.Write([]byte(`{"owner":"hanzo","sub":"z@hanzo.ai"}`))
+	}))
+	t.Cleanup(iam.Close)
+	up := aiPulseUpstream(t)
+
+	t.Setenv("HANZO_CLOUD_PULSE_TOKEN", "") // no service token — the admin's bearer drives it
+	t.Setenv("HANZO_API_BASE", up.URL)
+	t.Setenv("HANZO_IAM_ISSUER", iam.URL)
+
+	s := NewServer()
+	mux := http.NewServeMux()
+	s.Mount(mux)
+	ts := httptest.NewServer(mux)
+	t.Cleanup(ts.Close)
+
+	req, _ := http.NewRequest(http.MethodGet, ts.URL+"/v1/world/ai-pulse", nil)
+	req.Header.Set("Authorization", "Bearer admin-token")
+	req.Header.Set("Accept", "application/json")
+	resp, err := http.DefaultClient.Do(req)
+	if err != nil {
+		t.Fatalf("request failed: %v", err)
+	}
+	defer resp.Body.Close()
+	if cc := resp.Header.Get("Cache-Control"); cc != "private, no-store" {
+		t.Fatalf("admin ai-pulse poll must be no-store, got %q", cc)
+	}
+	var p aiPulse
+	if err := json.NewDecoder(resp.Body).Decode(&p); err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+	if p.State != "live" {
+		t.Fatalf("admin poll must be live with the caller's bearer, got %q (%s)", p.State, p.Reason)
+	}
+	if p.Usage == nil || p.Usage.Requests24h != 1_000_000 {
+		t.Fatalf("admin must see measured usage, got %+v", p.Usage)
+	}
+	if p.Fleet == nil || p.Fleet.Gpus != 3 {
+		t.Fatalf("admin must see the live fleet, got %+v", p.Fleet)
+	}
+}

internal/world/handlers_analyst_test.go

@@ -0,0 +1,583 @@
+package world
+
+import (
+	"context"
+	"encoding/json"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"sync/atomic"
+	"testing"
+
+	"github.com/hanzoai/world/internal/world/mcp"
+)
+
+// canonicalCommands is the command set the SPA registry (app-commands.ts) defines.
+// The embedded mirror (data/analyst_commands.json, generated from that registry)
+// MUST cover exactly this set — this test is the drift guard between TS and Go.
+var canonicalCommands = []string{
+	"show_panel", "hide_panel", "move_panel", "resize_panel", "toggle_layer",
+	"set_map_mode", "fly_to", "set_region", "set_time_range", "set_variant",
+	"set_theme", "search", "reset_layout", "add_feed_panel", "remove_custom_panel",
+	"switch_org",
+}
+
+func TestAnalystCommandManifest(t *testing.T) {
+	cmds := defaultCommands()
+	if len(cmds) == 0 {
+		t.Fatal("embedded analyst_commands.json decoded to zero commands")
+	}
+	got := map[string]analystCommand{}
+	for _, c := range cmds {
+		if c.Name == "" {
+			t.Fatalf("command with empty name: %+v", c)
+		}
+		if strings.TrimSpace(c.Description) == "" {
+			t.Errorf("command %q has no description", c.Name)
+		}
+		if c.Params.Type != "object" {
+			t.Errorf("command %q params.type = %q, want object", c.Name, c.Params.Type)
+		}
+		got[c.Name] = c
+	}
+	// Exact coverage of the canonical set (no missing, no stray).
+	for _, name := range canonicalCommands {
+		if _, ok := got[name]; !ok {
+			t.Errorf("embedded manifest missing canonical command %q", name)
+		}
+	}
+	if len(got) != len(canonicalCommands) {
+		t.Errorf("embedded manifest has %d commands, canonical set has %d", len(got), len(canonicalCommands))
+	}
+	// Required params must exist in properties (well-formed schema).
+	for _, c := range got {
+		for _, req := range c.Params.Required {
+			if _, ok := c.Params.Properties[req]; !ok {
+				t.Errorf("command %q requires %q but it is not a declared property", c.Name, req)
+			}
+		}
+	}
+}
+
+func TestSanitizeCommands(t *testing.T) {
+	in := []analystCommand{
+		{Name: "show_panel", Params: analystParams{Type: "object"}},
+		{Name: "show_panel", Params: analystParams{Type: "object"}}, // dup dropped
+		{Name: "", Params: analystParams{Type: "object"}},           // empty dropped
+		{Name: "bad", Params: analystParams{Type: "string"}},        // non-object dropped
+		{Name: " fly_to ", Params: analystParams{Type: "object"}},   // trimmed + kept
+	}
+	out := sanitizeCommands(in)
+	if len(out) != 2 {
+		t.Fatalf("sanitizeCommands kept %d, want 2: %+v", len(out), out)
+	}
+	if out[0].Name != "show_panel" || out[1].Name != "fly_to" {
+		t.Fatalf("unexpected order/names: %+v", out)
+	}
+}
+
+func TestRenderCommandContract(t *testing.T) {
+	contract := renderCommandContract(defaultCommands())
+
+	// Every command type must appear as an emittable action.
+	for _, name := range canonicalCommands {
+		if !strings.Contains(contract, `{"type":"`+name+`"`) {
+			t.Errorf("contract missing command %q", name)
+		}
+	}
+	// Enum values are rendered inline (deterministic set) for the model.
+	for _, want := range []string{`"range":"1h|6h|24h|48h|7d|all"`, `"mode":"2d|3d"`, `"theme":"dark|light"`} {
+		if !strings.Contains(contract, want) {
+			t.Errorf("contract missing enum rendering %q", want)
+		}
+	}
+	// Optional fields are marked with a trailing ? (fly_to.zoom is optional).
+	if !strings.Contains(contract, `"zoom":<number>?`) {
+		t.Errorf("contract did not mark optional zoom: \n%s", contract)
+	}
+	// Number/boolean types render without quotes.
+	if !strings.Contains(contract, `"lat":<number>`) || !strings.Contains(contract, `"on":true|false`) {
+		t.Errorf("contract number/boolean rendering wrong:\n%s", contract)
+	}
+}
+
+func TestRenderCommandContractDeterministic(t *testing.T) {
+	a := renderCommandContract(defaultCommands())
+	for i := 0; i < 5; i++ {
+		if b := renderCommandContract(defaultCommands()); b != a {
+			t.Fatal("renderCommandContract is not deterministic across runs")
+		}
+	}
+}
+
+func TestParseAnalystOutput(t *testing.T) {
+	allowed := commandTypes(defaultCommands())
+
+	// Generic pass-through of allowed actions with arbitrary params.
+	raw := `{"reply":"done","actions":[{"type":"fly_to","lat":35.6,"lon":139.7,"zoom":6},{"type":"nope","x":1}]}`
+	reply, actions := parseAnalystOutput(raw, allowed)
+	if reply != "done" {
+		t.Fatalf("reply = %q, want done", reply)
+	}
+	if len(actions) != 1 {
+		t.Fatalf("kept %d actions, want 1 (unknown type dropped): %+v", len(actions), actions)
+	}
+	if actions[0]["type"] != "fly_to" || actions[0]["lat"].(float64) != 35.6 {
+		t.Fatalf("action not passed through intact: %+v", actions[0])
+	}
+
+	// Non-JSON output degrades to prose reply, no actions.
+	reply, actions = parseAnalystOutput("just a sentence, no json", allowed)
+	if reply != "just a sentence, no json" || actions != nil {
+		t.Fatalf("plain-text degrade wrong: reply=%q actions=%+v", reply, actions)
+	}
+
+	// Fenced JSON is recovered.
+	reply, actions = parseAnalystOutput("```json\n{\"reply\":\"hi\",\"actions\":[]}\n```", allowed)
+	if reply != "hi" || len(actions) != 0 {
+		t.Fatalf("fenced JSON not recovered: reply=%q actions=%+v", reply, actions)
+	}
+}
+
+func TestParseAnalystTurnTools(t *testing.T) {
+	allowed := commandTypes(defaultCommands())
+	toolNames := toolNameSet(mcp.ToolSpecs())
+
+	// A tool round: the model requests a known data tool (+ ignores an unknown one).
+	raw := `{"reply":"","tools":[{"name":"world_brief","arguments":{"n":5}},{"name":"not_a_tool","arguments":{}}]}`
+	reply, actions, calls := parseAnalystTurn(raw, allowed, toolNames)
+	if reply != "" || len(actions) != 0 {
+		t.Fatalf("tool round should have no reply/actions: reply=%q actions=%+v", reply, actions)
+	}
+	if len(calls) != 1 || calls[0].Name != "world_brief" {
+		t.Fatalf("expected 1 valid tool call (world_brief), got %+v", calls)
+	}
+	if n, _ := calls[0].Args["n"].(float64); n != 5 {
+		t.Fatalf("tool args not passed through: %+v", calls[0].Args)
+	}
+
+	// A final answer: reply + actions, no tools.
+	reply, actions, calls = parseAnalystTurn(`{"reply":"done","actions":[{"type":"fly_to","lat":1,"lon":2}]}`, allowed, toolNames)
+	if reply != "done" || len(actions) != 1 || len(calls) != 0 {
+		t.Fatalf("final answer parse wrong: reply=%q actions=%+v calls=%+v", reply, actions, calls)
+	}
+
+	// nil toolNames disables tool extraction (the non-loop path).
+	if _, _, calls = parseAnalystTurn(raw, allowed, nil); calls != nil {
+		t.Fatalf("nil toolNames must not extract tools, got %+v", calls)
+	}
+
+	// Tool calls are capped per round.
+	var many strings.Builder
+	many.WriteString(`{"tools":[`)
+	for i := 0; i < analystMaxToolsPerRound+3; i++ {
+		if i > 0 {
+			many.WriteByte(',')
+		}
+		many.WriteString(`{"name":"world_brief","arguments":{}}`)
+	}
+	many.WriteString(`]}`)
+	if _, _, calls = parseAnalystTurn(many.String(), allowed, toolNames); len(calls) != analystMaxToolsPerRound {
+		t.Fatalf("per-round cap not enforced: got %d, want %d", len(calls), analystMaxToolsPerRound)
+	}
+}
+
+func TestRenderToolContract(t *testing.T) {
+	contract := renderToolContract(mcp.ToolSpecs())
+	// Every data tool must appear as a callable line.
+	for _, want := range []string{"world_brief", "country_instability", "market_quotes", "feeds"} {
+		if !strings.Contains(contract, "- "+want+"(") {
+			t.Errorf("tool contract missing %q:\n%s", want, contract)
+		}
+	}
+	// Required params render bare; optional params carry a trailing ?.
+	if !strings.Contains(contract, "country_instability(iso)") {
+		t.Errorf("required param not rendered bare:\n%s", contract)
+	}
+	if !strings.Contains(contract, "metric?") || !strings.Contains(contract, "n?") {
+		t.Errorf("optional params not marked with ?:\n%s", contract)
+	}
+	// Deterministic across runs.
+	for i := 0; i < 5; i++ {
+		if renderToolContract(mcp.ToolSpecs()) != contract {
+			t.Fatal("renderToolContract is not deterministic")
+		}
+	}
+}
+
+// TestAnalystDataToolLoop drives the full agentic loop end-to-end: a stub
+// inference server first asks for the world_brief data tool, then (after the
+// handler runs it IN-PROCESS through the mcp dispatcher and feeds the result back)
+// returns a final grounded answer. The response must carry the tool trace and the
+// reply, and the inference server must have been called exactly twice.
+func TestAnalystDataToolLoop(t *testing.T) {
+	var calls int32
+	ai := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if !strings.HasSuffix(r.URL.Path, "/chat/completions") {
+			http.Error(w, "unexpected path "+r.URL.Path, http.StatusNotFound)
+			return
+		}
+		n := atomic.AddInt32(&calls, 1)
+		var content string
+		if n == 1 {
+			// Round 1: request the data tool.
+			content = `{"reply":"","tools":[{"name":"world_brief","arguments":{"n":3}}]}`
+		} else {
+			// Round 2: the handler must have injected a TOOL RESULTS turn carrying
+			// the model envelope (asOf marker) before this call.
+			body, _ := readAllString(r)
+			if !strings.Contains(body, "TOOL RESULTS") || !strings.Contains(body, "asOf") {
+				t.Errorf("final turn missing injected tool results: %s", body)
+			}
+			content = `{"reply":"Composite instability is steady; see the ranked movers.","actions":[]}`
+		}
+		writeChatCompletion(w, content)
+	}))
+	defer ai.Close()
+
+	s := NewServer()
+	s.ai.base = ai.URL
+	mux := http.NewServeMux()
+	s.Mount(mux)
+	ts := httptest.NewServer(mux)
+	defer ts.Close()
+
+	reqBody, _ := json.Marshal(map[string]any{
+		"messages": []map[string]string{{"role": "user", "content": "What is the state of global instability?"}},
+	})
+	// A signed-in caller drives the chat: their IAM bearer is forwarded upstream and
+	// meters to their org. Chat requires a user bearer — the funded key backs only the
+	// anonymous auto-insight endpoints (see TestAnalystChatRequiresUserBearer).
+	req, _ := http.NewRequest(http.MethodPost, ts.URL+"/v1/world/analyst", strings.NewReader(string(reqBody)))
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("Authorization", "Bearer user-token")
+	resp, err := http.DefaultClient.Do(req)
+	if err != nil {
+		t.Fatalf("request failed: %v", err)
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("status = %d, want 200", resp.StatusCode)
+	}
+	var out struct {
+		Reply   string           `json:"reply"`
+		Actions []map[string]any `json:"actions"`
+		Traces  []struct {
+			Label  string `json:"label"`
+			OK     bool   `json:"ok"`
+			Result string `json:"result"`
+		} `json:"traces"`
+	}
+	if err := json.NewDecoder(resp.Body).Decode(&out); err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+	if got := atomic.LoadInt32(&calls); got != 2 {
+		t.Fatalf("inference calls = %d, want 2 (one tool round + final answer)", got)
+	}
+	if out.Reply == "" {
+		t.Fatal("final reply is empty")
+	}
+	if len(out.Traces) != 1 {
+		t.Fatalf("traces = %d, want 1: %+v", len(out.Traces), out.Traces)
+	}
+	tr := out.Traces[0]
+	if !strings.HasPrefix(tr.Label, "world_brief(") {
+		t.Errorf("trace label = %q, want world_brief(...)", tr.Label)
+	}
+	if !tr.OK {
+		t.Errorf("world_brief trace should be ok=true: %+v", tr)
+	}
+	if !strings.Contains(tr.Result, "asOf") {
+		t.Errorf("trace result should carry the model envelope (asOf): %q", tr.Result)
+	}
+}
+
+// writeChatCompletion writes an OpenAI-shaped chat completion whose assistant
+// content is body (the analyst strict-JSON envelope).
+func writeChatCompletion(w http.ResponseWriter, body string) {
+	resp := map[string]any{
+		"choices": []any{map[string]any{"message": map[string]any{"content": body}}},
+		"usage":   map[string]any{"total_tokens": 12},
+	}
+	w.Header().Set("Content-Type", "application/json")
+	_ = json.NewEncoder(w).Encode(resp)
+}
+
+func readAllString(r *http.Request) (string, error) {
+	b, err := io.ReadAll(r.Body)
+	return string(b), err
+}
+
+// writeChatMessage writes an OpenAI-shaped completion whose single choice carries
+// the given assistant message object verbatim — used to model a reasoning model that
+// leaves `content` empty and puts its answer on `reasoning_content`.
+func writeChatMessage(w http.ResponseWriter, message map[string]any) {
+	resp := map[string]any{
+		"id":      "resp_test",
+		"choices": []any{map[string]any{"message": message}},
+		"usage":   map[string]any{"total_tokens": 7},
+	}
+	w.Header().Set("Content-Type", "application/json")
+	_ = json.NewEncoder(w).Encode(resp)
+}
+
+// postAnalyst drives the non-streaming analyst path with a signed-in bearer and
+// returns the decoded response envelope.
+func postAnalyst(t *testing.T, ts *httptest.Server, prompt string) map[string]any {
+	t.Helper()
+	reqBody, _ := json.Marshal(map[string]any{
+		"messages": []map[string]string{{"role": "user", "content": prompt}},
+	})
+	req, _ := http.NewRequest(http.MethodPost, ts.URL+"/v1/world/analyst", strings.NewReader(string(reqBody)))
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("Authorization", "Bearer user-token")
+	resp, err := http.DefaultClient.Do(req)
+	if err != nil {
+		t.Fatalf("request failed: %v", err)
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("status = %d, want 200 (never 5xx)", resp.StatusCode)
+	}
+	var out map[string]any
+	if err := json.NewDecoder(resp.Body).Decode(&out); err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+	return out
+}
+
+// TestAnalystRecoversReasoningWhenNoContent is the regression guard for the "empty
+// response" break: a reasoning model (gpt-oss-120b / harmony) returns a 2xx with an
+// EMPTY content channel and its answer on `reasoning_content`. The completion path
+// must fall back to that channel so the analyst recovers the reply — not blank out.
+func TestAnalystRecoversReasoningWhenNoContent(t *testing.T) {
+	ai := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		writeChatMessage(w, map[string]any{
+			"content":           "",
+			"reasoning_content": `{"reply":"Markets are steady.","actions":[]}`,
+		})
+	}))
+	defer ai.Close()
+
+	s := NewServer()
+	s.ai.base = ai.URL
+	mux := http.NewServeMux()
+	s.Mount(mux)
+	ts := httptest.NewServer(mux)
+	defer ts.Close()
+
+	out := postAnalyst(t, ts, "Reply with strict JSON only")
+	if got, _ := out["reply"].(string); got != "Markets are steady." {
+		t.Fatalf("reasoning-channel answer not recovered: reply=%q full=%+v", got, out)
+	}
+	if out["error"] != nil {
+		t.Errorf("recovered answer should carry no error: %+v", out["error"])
+	}
+}
+
+// TestAnalystEmptyAnswerNamesModel pins the honest-error contract: a genuinely empty
+// 2xx (a real choice, no content AND no reasoning) surfaces "the <model> model
+// returned an empty answer" — never an opaque "empty response", and never a balance
+// top-up (that is a distinct 402 contract).
+func TestAnalystEmptyAnswerNamesModel(t *testing.T) {
+	ai := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		writeChatMessage(w, map[string]any{"content": ""})
+	}))
+	defer ai.Close()
+
+	s := NewServer() // default model "best"
+	s.ai.base = ai.URL
+	mux := http.NewServeMux()
+	s.Mount(mux)
+	ts := httptest.NewServer(mux)
+	defer ts.Close()
+
+	out := postAnalyst(t, ts, "hi")
+	if got, _ := out["reply"].(string); got != "" {
+		t.Fatalf("expected empty reply, got %q", got)
+	}
+	errStr, _ := out["error"].(string)
+	if strings.Contains(errStr, "empty response") {
+		t.Fatalf("still surfacing the opaque 'empty response': %q", errStr)
+	}
+	if !strings.Contains(errStr, "empty answer") || !strings.Contains(errStr, "best") {
+		t.Fatalf("empty error not honest/model-named: %q", errStr)
+	}
+	if out["topup"] == true {
+		t.Fatalf("empty answer must not be a balance/top-up error: %+v", out)
+	}
+	if out["fallback"] != true {
+		t.Errorf("empty answer should mark fallback=true: %+v", out)
+	}
+}
+
+// TestChatStreamRecoversReasoning covers the SSE path: a model that streams only
+// `reasoning_content` deltas (no content channel) must still yield an answer, and the
+// reasoning must be forwarded live (onDelta) so the UI shows the model working.
+func TestChatStreamRecoversReasoning(t *testing.T) {
+	ai := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "text/event-stream")
+		fl, _ := w.(http.Flusher)
+		for _, f := range []string{
+			`{"id":"resp_1","choices":[{"delta":{"reasoning_content":"thinking… "}}]}`,
+			`{"id":"resp_1","choices":[{"delta":{"reasoning_content":"{\"reply\":\"from reasoning\"}"}}]}`,
+			`[DONE]`,
+		} {
+			_, _ = io.WriteString(w, "data: "+f+"\n\n")
+			if fl != nil {
+				fl.Flush()
+			}
+		}
+	}))
+	defer ai.Close()
+
+	s := NewServer()
+	s.ai.base = ai.URL
+	var streamed strings.Builder
+	out, _, id, err := s.ai.chatMessagesModelStream(context.Background(), s, "Bearer u", "gpt-oss-120b",
+		[]chatMessage{{Role: "user", Content: "hi"}}, 0.4, 700, nil, func(tok string) { streamed.WriteString(tok) })
+	if err != nil {
+		t.Fatalf("stream err: %v", err)
+	}
+	if id != "resp_1" {
+		t.Errorf("id = %q, want resp_1", id)
+	}
+	want := `thinking… {"reply":"from reasoning"}`
+	if out != want {
+		t.Fatalf("stream reasoning fallback wrong:\n got=%q\nwant=%q", out, want)
+	}
+	if streamed.String() != want {
+		t.Errorf("reasoning deltas not forwarded live: %q", streamed.String())
+	}
+}
+
+func TestSanitizeModelAndAgentRef(t *testing.T) {
+	cases := map[string]string{
+		"zen5":          "zen5",
+		"zen5-flash":    "zen5-flash",
+		"agent:my-bot":  "agent:my-bot",
+		"  zen3-omni  ": "zen3-omni",
+		"bad model!":    "", // space + ! invalid
+		"":              "",
+	}
+	for in, want := range cases {
+		if got := sanitizeModel(in); got != want {
+			t.Errorf("sanitizeModel(%q) = %q, want %q", in, got, want)
+		}
+	}
+	if agentRef("agent:my-bot") != "my-bot" {
+		t.Errorf("agentRef(agent:my-bot) != my-bot")
+	}
+	if agentRef("zen5") != "" {
+		t.Errorf("agentRef(zen5) should be empty")
+	}
+}
+
+func TestExtractAgentText(t *testing.T) {
+	cases := map[string]string{
+		`{"output":"hello"}`:                             "hello",
+		`{"result":"  spaced  "}`:                        "spaced",
+		`{"output":{"text":"nested"}}`:                   "nested",
+		`{"choices":[{"message":{"content":"openai"}}]}`: "openai",
+		`{"nothing":true}`:                               "",
+		`not json`:                                       "",
+	}
+	for in, want := range cases {
+		if got := extractAgentText([]byte(in)); got != want {
+			t.Errorf("extractAgentText(%q) = %q, want %q", in, got, want)
+		}
+	}
+}
+
+func TestHandleModelsCuratedRoster(t *testing.T) {
+	s := NewServer()
+	mux := http.NewServeMux()
+	s.Mount(mux)
+	ts := httptest.NewServer(mux)
+	defer ts.Close()
+
+	// No bearer → curated Zen roster only, never a 5xx.
+	resp, err := http.Get(ts.URL + "/v1/world/models")
+	if err != nil {
+		t.Fatalf("request failed: %v", err)
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("status = %d, want 200", resp.StatusCode)
+	}
+	if ct := resp.Header.Get("Content-Type"); !strings.Contains(ct, "application/json") {
+		t.Fatalf("content-type = %q, want json", ct)
+	}
+	var body struct {
+		Data []struct {
+			ID    string `json:"id"`
+			Label string `json:"label"`
+			Group string `json:"group"`
+		} `json:"data"`
+		Default string `json:"default"`
+	}
+	if err := json.NewDecoder(resp.Body).Decode(&body); err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+	if body.Default != "best" {
+		t.Errorf("default = %q, want best", body.Default)
+	}
+	if len(body.Data) == 0 {
+		t.Fatal("empty model roster")
+	}
+	var hasBest, hasZen5 bool
+	for _, m := range body.Data {
+		if m.ID == "best" {
+			hasBest = true
+		}
+		if m.ID == "zen5" {
+			hasZen5 = true
+		}
+		if m.Group == "" || m.Label == "" {
+			t.Errorf("model entry missing label/group: %+v", m)
+		}
+	}
+	if !hasBest || !hasZen5 {
+		t.Error("roster missing best/zen5")
+	}
+}
+
+// TestAnalystChatRequiresUserBearer pins the pro-model contract: the analyst CHAT
+// is paid usage, metered to the signed-in user's org via their OWN IAM bearer —
+// NEVER the funded service key. The funded key (a.key / HANZO_AI_KEY) backs only
+// the anonymous auto-insight endpoints (summarize/classify/country-intel). So even
+// with a funded key configured, an unauthenticated chat call must be refused with a
+// quiet sign-in prompt (200, skipped) — not silently answered on the shared key.
+//
+// Regression guard: if handleAnalyst reverts to bearerFor(r), the funded key would
+// satisfy the bearer, the handler would fall through to a real upstream call, and
+// this test would hang/fail instead of returning the deterministic skip below.
+func TestAnalystChatRequiresUserBearer(t *testing.T) {
+	s := NewServer()
+	s.ai.key = "hk-test-funded" // funded key present (backs anonymous auto-insights only)
+	mux := http.NewServeMux()
+	s.Mount(mux)
+	ts := httptest.NewServer(mux)
+	defer ts.Close()
+
+	body := `{"messages":[{"role":"user","content":"hi"}],"context":""}`
+	resp, err := http.Post(ts.URL+"/v1/world/analyst", "application/json", strings.NewReader(body))
+	if err != nil {
+		t.Fatalf("request failed: %v", err)
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("status = %d, want 200 (quiet sign-in prompt, never 5xx)", resp.StatusCode)
+	}
+	var out map[string]any
+	if err := json.NewDecoder(resp.Body).Decode(&out); err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+	if out["skipped"] != true {
+		t.Fatalf("anonymous chat not refused — funded key leaked into paid chat path: %+v", out)
+	}
+	if reason, _ := out["reason"].(string); !strings.Contains(reason, "Sign in") {
+		t.Errorf("reason = %q, want a sign-in prompt", reason)
+	}
+}

internal/world/handlers_china.go

@@ -0,0 +1,901 @@
+package world
+
+import (
+	"context"
+	"encoding/csv"
+	"encoding/json"
+	"fmt"
+	"math"
+	"net/http"
+	"net/url"
+	"regexp"
+	"sort"
+	"strconv"
+	"strings"
+	"time"
+)
+
+// China macro snapshot + official release calendar. A faithful Go port of the
+// worldmonitor seed adapters (scripts/china-macro/{adapters,calendar}.mjs) and
+// the merge in server/worldmonitor/economic/v1/get-china-macro-snapshot.ts.
+//
+// Every source parser is a small pure func over a raw body so it is unit-tested
+// against the same fixtures as the TypeScript original. handleChinaMacro is the
+// only impure piece: it fetches the live sources (<=2 sequential OECD requests,
+// per OECD's "<60 downloads/hour" ask), builds both flows, and merges them into
+// the exact upstream payload shape, cached aggressively (daily/monthly series).
+
+const (
+	oecdCPIURL        = "https://sdmx.oecd.org/public/rest/data/OECD.SDD.TPS,DSD_G20_PRICES@DF_G20_PRICES,1.0/CHN.M...PA...?startPeriod=2024-01&dimensionAtObservation=AllDimensions&format=csvfile"
+	oecdCLIURL        = "https://sdmx.oecd.org/public/rest/data/OECD.SDD.STES,DSD_STES@DF_CLI,4.1/CHN.M.LI...AA...H?startPeriod=2024-01&dimensionAtObservation=AllDimensions&format=csvfile"
+	hkmaCNYURL        = "https://api.hkma.gov.hk/public/market-data-and-statistics/monthly-statistical-bulletin/er-ir/er-eeri-daily?pagesize=2&fields=end_of_day,cny&sortby=end_of_day&sortorder=desc"
+	fredDEXCHUSURL    = "https://api.stlouisfed.org/fred/series/observations?series_id=DEXCHUS&file_type=json&sort_order=desc&limit=2"
+	bisPolicyCacheKey = "economic:bis:policy:v1"
+
+	nbsCalendarIndexURL    = "https://www.stats.gov.cn/english/PressRelease/ReleaseCalendar/"
+	chinaMoneyLPRURL       = "https://www.chinamoney.com.cn/chinese/bklpr/?tab=2"
+	chinaMoneyLPRNoticeAPI = "https://www.chinamoney.com.cn/ags/ms/cm-s-notice-query/contentsinshorttime"
+	chinaMoneyLPRChannelID = "3686"
+)
+
+// chinaIndicator is one macro series in the snapshot. Value/PriorValue are
+// pointers so an unavailable observation marshals as JSON null (never a fake 0),
+// matching the upstream `value: null` contract.
+type chinaIndicator struct {
+	ID                string   `json:"id"`
+	Label             string   `json:"label"`
+	Category          string   `json:"category"`
+	Value             *float64 `json:"value"`
+	PriorValue        *float64 `json:"priorValue"`
+	Unit              string   `json:"unit"`
+	ObservationDate   string   `json:"observationDate"`
+	Source            string   `json:"source"`
+	SourceURL         string   `json:"sourceUrl"`
+	Stale             bool     `json:"stale"`
+	UnavailableReason string   `json:"unavailableReason"`
+	ContextOnly       bool     `json:"contextOnly"`
+}
+
+type chinaSourceDecision struct {
+	Source       string `json:"source"`
+	Host         string `json:"host"`
+	Status       string `json:"status"`
+	Reason       string `json:"reason"`
+	CheckedAt    string `json:"checkedAt"`
+	Optional     bool   `json:"optional"`
+	RequestCount int    `json:"requestCount"`
+}
+
+type chinaReleaseEvent struct {
+	ID          string `json:"id"`
+	Event       string `json:"event"`
+	CountryCode string `json:"countryCode"`
+	ReleaseDate string `json:"releaseDate"`
+	ReleaseTime string `json:"releaseTime"`
+	Timezone    string `json:"timezone"`
+	Kind        string `json:"kind"`
+	Status      string `json:"status"`
+	Source      string `json:"source"`
+	SourceURL   string `json:"sourceUrl"`
+}
+
+// chinaMacroSnapshot is the merged payload the SPA consumes. Empty slices are
+// initialized so they marshal as [] rather than null.
+type chinaMacroSnapshot struct {
+	CountryCode            string                `json:"countryCode"`
+	GeneratedAt            string                `json:"generatedAt"`
+	Status                 string                `json:"status"`
+	LaunchReady            bool                  `json:"launchReady"`
+	ContentObservationDate string                `json:"contentObservationDate"`
+	LatestObservationDate  string                `json:"latestObservationDate"`
+	Indicators             []chinaIndicator      `json:"indicators"`
+	SourceDecisions        []chinaSourceDecision `json:"sourceDecisions"`
+	ReleaseEvents          []chinaReleaseEvent   `json:"releaseEvents"`
+	Unavailable            bool                  `json:"unavailable"`
+}
+
+// indicatorDef is the static description of a series (labels, source, staleness
+// horizon) shared by the complete/unavailable builders.
+type indicatorDef struct {
+	id, label, category, unit, source, sourceURL string
+	maxAgeDays                                    int
+}
+
+var chinaRequiredCategories = []string{"price", "activity", "policy", "fx"}
+
+// ── observation health ───────────────────────────────────────────────────────
+
+var (
+	reObsMonth   = regexp.MustCompile(`^(\d{4})-(\d{2})$`)
+	reObsDay     = regexp.MustCompile(`^\d{4}-\d{2}-\d{2}$`)
+	reStatusCode = regexp.MustCompile(`status (\d+)`)
+)
+
+// observationTime resolves a source timestamp to the instant used for staleness.
+// Monthly values ('2026-05') anchor at month-end 23:59:59 UTC so a fresh FX tick
+// never makes stale monthly content look current; daily values anchor at day-end.
+func observationTime(v string) (time.Time, bool) {
+	if v == "" {
+		return time.Time{}, false
+	}
+	if m := reObsMonth.FindStringSubmatch(v); m != nil {
+		y, _ := strconv.Atoi(m[1])
+		mo, _ := strconv.Atoi(m[2])
+		// day 0 of month mo+1 == last day of month mo.
+		return time.Date(y, time.Month(mo)+1, 0, 23, 59, 59, 0, time.UTC), true
+	}
+	if reObsDay.MatchString(v) {
+		if t, err := time.Parse("2006-01-02", v); err == nil {
+			return time.Date(t.Year(), t.Month(), t.Day(), 23, 59, 59, 0, time.UTC), true
+		}
+	}
+	if t, err := time.Parse(time.RFC3339, v); err == nil {
+		return t, true
+	}
+	return time.Time{}, false
+}
+
+func isStale(obsDate string, maxAgeDays int, now time.Time) bool {
+	t, ok := observationTime(obsDate)
+	if !ok {
+		return true
+	}
+	return now.Sub(t) > time.Duration(maxAgeDays)*24*time.Hour
+}
+
+func unavailableIndicator(def indicatorDef, reason string, contextOnly bool) chinaIndicator {
+	if reason == "" {
+		reason = "SOURCE_UNAVAILABLE"
+	}
+	return chinaIndicator{
+		ID: def.id, Label: def.label, Category: def.category, Unit: def.unit,
+		Source: def.source, SourceURL: def.sourceURL,
+		UnavailableReason: reason, ContextOnly: contextOnly,
+	}
+}
+
+func completeIndicator(def indicatorDef, value float64, prior *float64, obsDate string, now time.Time, contextOnly bool) chinaIndicator {
+	stale := isStale(obsDate, def.maxAgeDays, now)
+	reason := ""
+	if stale {
+		reason = "STALE_OBSERVATION"
+	}
+	v := value
+	return chinaIndicator{
+		ID: def.id, Label: def.label, Category: def.category, Value: &v, PriorValue: prior,
+		Unit: def.unit, ObservationDate: obsDate, Source: def.source, SourceURL: def.sourceURL,
+		Stale: stale, UnavailableReason: reason, ContextOnly: contextOnly,
+	}
+}
+
+// ── source parsers (pure) ────────────────────────────────────────────────────
+
+type dateValue struct {
+	date  string
+	value float64
+}
+
+func latestTwo(rows []dateValue) (dateValue, *float64) {
+	sort.SliceStable(rows, func(i, j int) bool { return rows[i].date < rows[j].date })
+	latest := rows[len(rows)-1]
+	if len(rows) >= 2 {
+		p := rows[len(rows)-2].value
+		return latest, &p
+	}
+	return latest, nil
+}
+
+func csvColumn(header []string, names ...string) int {
+	for i, h := range header {
+		for _, n := range names {
+			if h == n {
+				return i
+			}
+		}
+	}
+	return -1
+}
+
+// parseOecdCsvIndicator reads an OECD SDMX CSV (CPI YoY from DF_G20_PRICES or CLI
+// from DF_CLI), keeping only mainland-China (REF_AREA=CHN) observations and
+// returning the latest value with the prior for change context.
+func parseOecdCsvIndicator(body []byte, def indicatorDef, now time.Time) chinaIndicator {
+	r := csv.NewReader(strings.NewReader(string(body)))
+	r.FieldsPerRecord = -1
+	recs, _ := r.ReadAll()
+	if len(recs) == 0 {
+		return unavailableIndicator(def, "MALFORMED_RESPONSE", false)
+	}
+	header := recs[0]
+	area := csvColumn(header, "REF_AREA", "ReferenceArea")
+	date := csvColumn(header, "TIME_PERIOD", "TimePeriod")
+	val := csvColumn(header, "OBS_VALUE", "ObservationValue")
+	if area < 0 || date < 0 || val < 0 {
+		return unavailableIndicator(def, "MALFORMED_RESPONSE", false)
+	}
+	var rows []dateValue
+	for _, rec := range recs[1:] {
+		if area >= len(rec) || date >= len(rec) || val >= len(rec) {
+			continue
+		}
+		if strings.ToUpper(rec[area]) != "CHN" || rec[date] == "" {
+			continue
+		}
+		v, err := strconv.ParseFloat(rec[val], 64)
+		if err != nil || math.IsNaN(v) || math.IsInf(v, 0) {
+			continue
+		}
+		rows = append(rows, dateValue{rec[date], v})
+	}
+	if len(rows) == 0 {
+		return unavailableIndicator(def, "NO_CHINA_OBSERVATIONS", false)
+	}
+	latest, prior := latestTwo(rows)
+	return completeIndicator(def, latest.value, prior, latest.date, now, false)
+}
+
+var bisPolicyDef = indicatorDef{
+	id: "policy_rate", label: "Policy Rate", category: "policy", unit: "%",
+	source: "BIS (mainland China policy rate)", sourceURL: "https://stats.bis.org/api/v1/data/WS_CBPOL", maxAgeDays: 75,
+}
+
+// parseBisPolicy reads the seeded BIS central-bank policy-rate cache shape and
+// returns China's latest rate. Prior falls back to the row's previousRate when
+// only one observation is present.
+func parseBisPolicy(body []byte, now time.Time) chinaIndicator {
+	var payload struct {
+		Rates []struct {
+			CountryCode  string   `json:"countryCode"`
+			Rate         *float64 `json:"rate"`
+			PreviousRate *float64 `json:"previousRate"`
+			Date         string   `json:"date"`
+		} `json:"rates"`
+	}
+	if err := json.Unmarshal(body, &payload); err != nil {
+		return unavailableIndicator(bisPolicyDef, "NO_CHINA_POLICY_RATE", false)
+	}
+	type row struct {
+		date         string
+		rate         float64
+		previousRate *float64
+	}
+	var matches []row
+	for _, r := range payload.Rates {
+		if r.CountryCode != "CN" || r.Rate == nil || r.Date == "" || math.IsNaN(*r.Rate) {
+			continue
+		}
+		matches = append(matches, row{r.Date, *r.Rate, r.PreviousRate})
+	}
+	if len(matches) == 0 {
+		return unavailableIndicator(bisPolicyDef, "NO_CHINA_POLICY_RATE", false)
+	}
+	sort.SliceStable(matches, func(i, j int) bool { return matches[i].date < matches[j].date })
+	latest := matches[len(matches)-1]
+	var prior *float64
+	if len(matches) > 1 {
+		p := matches[len(matches)-2].rate
+		prior = &p
+	} else if latest.previousRate != nil && !math.IsNaN(*latest.previousRate) {
+		p := *latest.previousRate
+		prior = &p
+	}
+	return completeIndicator(bisPolicyDef, latest.rate, prior, latest.date, now, false)
+}
+
+var fredUsdCnyDef = indicatorDef{
+	id: "usd_cny", label: "USD/CNY", category: "fx", unit: "CNY per USD",
+	source: "FRED DEXCHUS (Federal Reserve H.10)", sourceURL: "https://fred.stlouisfed.org/series/DEXCHUS", maxAgeDays: 10,
+}
+
+// parseFredUsdCny reads FRED DEXCHUS observations (values are strings, '.' for
+// missing) and returns the latest USD/CNY fixing.
+func parseFredUsdCny(body []byte, now time.Time) chinaIndicator {
+	var payload struct {
+		Observations []struct {
+			Date  string `json:"date"`
+			Value string `json:"value"`
+		} `json:"observations"`
+	}
+	if err := json.Unmarshal(body, &payload); err != nil {
+		return unavailableIndicator(fredUsdCnyDef, "NO_CURRENT_DEXCHUS", false)
+	}
+	var rows []dateValue
+	for _, o := range payload.Observations {
+		v, err := strconv.ParseFloat(o.Value, 64)
+		if o.Date == "" || err != nil || math.IsNaN(v) || math.IsInf(v, 0) {
+			continue
+		}
+		rows = append(rows, dateValue{o.Date, v})
+	}
+	if len(rows) == 0 {
+		return unavailableIndicator(fredUsdCnyDef, "NO_CURRENT_DEXCHUS", false)
+	}
+	latest, prior := latestTwo(rows)
+	return completeIndicator(fredUsdCnyDef, latest.value, prior, latest.date, now, false)
+}
+
+var hkmaCnyDef = indicatorDef{
+	id: "cnh_context", label: "CNY/HKD Context", category: "context", unit: "HKD per CNY",
+	source:     "HKMA (Hong Kong/CNH context)",
+	sourceURL:  "https://apidocs.hkma.gov.hk/documentation/market-data-and-statistics/monthly-statistical-bulletin/er-ir/er-eeri-daily/",
+	maxAgeDays: 10,
+}
+
+// parseHkmaCnyContext reads the optional HKMA daily CNY/HKD context series. It is
+// context-only: it never gates the launch decision.
+func parseHkmaCnyContext(body []byte, now time.Time) chinaIndicator {
+	var payload struct {
+		Result struct {
+			Records []struct {
+				EndOfDay string   `json:"end_of_day"`
+				CNY      *float64 `json:"cny"`
+			} `json:"records"`
+		} `json:"result"`
+	}
+	if err := json.Unmarshal(body, &payload); err != nil {
+		return unavailableIndicator(hkmaCnyDef, "NO_HKMA_CNY_CONTEXT", true)
+	}
+	var rows []dateValue
+	for _, rec := range payload.Result.Records {
+		if rec.EndOfDay == "" || rec.CNY == nil || math.IsNaN(*rec.CNY) {
+			continue
+		}
+		rows = append(rows, dateValue{rec.EndOfDay, *rec.CNY})
+	}
+	if len(rows) == 0 {
+		return unavailableIndicator(hkmaCnyDef, "NO_HKMA_CNY_CONTEXT", true)
+	}
+	latest, prior := latestTwo(rows)
+	return completeIndicator(hkmaCnyDef, latest.value, prior, latest.date, now, true)
+}
+
+// ── release calendar (pure) ──────────────────────────────────────────────────
+
+var (
+	reNbsRow      = regexp.MustCompile(`(?is)<tr\b[^>]*>(.*?)</tr>`)
+	reNbsCell     = regexp.MustCompile(`(?is)<t[dh]\b[^>]*>(.*?)</t[dh]>`)
+	reNbsBr       = regexp.MustCompile(`(?i)<br\s*/?\s*>`)
+	reNbsTag      = regexp.MustCompile(`<[^>]+>`)
+	reNbsSpaces   = regexp.MustCompile(`[ \t]+`)
+	reNbsNumeric  = regexp.MustCompile(`^\d+$`)
+	reNbsEllipsis = regexp.MustCompile(`^(\x{2026}+|\.{3,})$`)
+	reNbsDay      = regexp.MustCompile(`(^|\s)(\d{1,2})\s*/[A-Za-z]+`)
+	reNbsTime     = regexp.MustCompile(`\b(\d{1,2}:\d{2})\b`)
+	reNbsWS       = regexp.MustCompile(`\s`)
+)
+
+func stripHTML(v string) string {
+	v = reNbsBr.ReplaceAllString(v, "\n")
+	v = reNbsTag.ReplaceAllString(v, " ")
+	v = strings.ReplaceAll(v, "&nbsp;", " ")
+	v = strings.ReplaceAll(v, "&#160;", " ")
+	v = strings.ReplaceAll(v, "&amp;", "&")
+	v = strings.ReplaceAll(v, "&#39;", "'")
+	v = strings.ReplaceAll(v, "&apos;", "'")
+	v = strings.ReplaceAll(v, "&quot;", "\"")
+	v = reNbsSpaces.ReplaceAllString(v, " ")
+	return strings.TrimSpace(v)
+}
+
+func nbsCells(row string) []string {
+	matches := reNbsCell.FindAllStringSubmatch(row, -1)
+	cells := make([]string, 0, len(matches))
+	for _, m := range matches {
+		cells = append(cells, stripHTML(m[1]))
+	}
+	return cells
+}
+
+func isoDate(year, month, day int) string {
+	return fmt.Sprintf("%04d-%02d-%02d", year, month, day)
+}
+
+// parseNbsReleaseCalendar scrapes the National Bureau of Statistics HTML release
+// grid (one row per statistic, one column per month) into dated release events.
+// Blank/ellipsis month cells stay empty; a cell may carry several days (e.g. the
+// Spring-Festival-shifted PMI) and each becomes its own event.
+func parseNbsReleaseCalendar(html []byte, year int, sourceURL string) []chinaReleaseEvent {
+	var events []chinaReleaseEvent
+	for _, rowMatch := range reNbsRow.FindAllStringSubmatch(string(html), -1) {
+		cells := nbsCells(rowMatch[1])
+		if len(cells) < 14 || !reNbsNumeric.MatchString(cells[0]) {
+			continue
+		}
+		event := cells[1]
+		rowNo, _ := strconv.Atoi(cells[0])
+		for month := 1; month <= 12; month++ {
+			cell := ""
+			if month+1 < len(cells) {
+				cell = cells[month+1]
+			}
+			if cell == "" || reNbsEllipsis.MatchString(reNbsWS.ReplaceAllString(cell, "")) {
+				continue
+			}
+			releaseTime := "09:30"
+			if m := reNbsTime.FindStringSubmatch(cell); m != nil {
+				releaseTime = m[1]
+			}
+			for _, dm := range reNbsDay.FindAllStringSubmatch(cell, -1) {
+				day, _ := strconv.Atoi(dm[2])
+				releaseDate := isoDate(year, month, day)
+				events = append(events, chinaReleaseEvent{
+					ID:          fmt.Sprintf("nbs-%02d-%s", rowNo, releaseDate),
+					Event:       event,
+					CountryCode: "CN",
+					ReleaseDate: releaseDate,
+					ReleaseTime: releaseTime,
+					Timezone:    "Asia/Shanghai",
+					Kind:        "nbs",
+					Status:      "scheduled",
+					Source:      "National Bureau of Statistics of China",
+					SourceURL:   sourceURL,
+				})
+			}
+		}
+	}
+	sortReleaseEvents(events)
+	return events
+}
+
+func sortReleaseEvents(events []chinaReleaseEvent) {
+	sort.SliceStable(events, func(i, j int) bool {
+		if events[i].ReleaseDate != events[j].ReleaseDate {
+			return events[i].ReleaseDate < events[j].ReleaseDate
+		}
+		return events[i].Event < events[j].Event
+	})
+}
+
+// chinaBusinessCalendar is the official mainland-China holiday + adjusted-workday
+// set for a year. LPR candidate dates are rolled forward over these.
+type chinaBusinessCalendar struct {
+	holidays         map[string]bool
+	adjustedWorkdays map[string]bool
+}
+
+func toSet(days ...string) map[string]bool {
+	m := make(map[string]bool, len(days))
+	for _, d := range days {
+		m[d] = true
+	}
+	return m
+}
+
+// chinaBusinessCalendars is the hardcoded official calendar. 2027 must be added
+// here before January 2027, or buildLprCandidates fails closed for that year.
+var chinaBusinessCalendars = map[int]chinaBusinessCalendar{
+	2026: {
+		holidays: toSet(
+			"2026-01-01", "2026-01-02", "2026-01-03",
+			"2026-02-15", "2026-02-16", "2026-02-17", "2026-02-18", "2026-02-19", "2026-02-20", "2026-02-21", "2026-02-22", "2026-02-23",
+			"2026-04-04", "2026-04-05", "2026-04-06",
+			"2026-05-01", "2026-05-02", "2026-05-03", "2026-05-04", "2026-05-05",
+			"2026-06-19", "2026-06-20", "2026-06-21",
+			"2026-09-25", "2026-09-26", "2026-09-27",
+			"2026-10-01", "2026-10-02", "2026-10-03", "2026-10-04", "2026-10-05", "2026-10-06", "2026-10-07",
+		),
+		adjustedWorkdays: toSet("2026-01-04", "2026-02-14", "2026-02-28", "2026-05-09", "2026-09-20", "2026-10-10"),
+	},
+}
+
+func businessCalendar(year int) (chinaBusinessCalendar, error) {
+	if cal, ok := chinaBusinessCalendars[year]; ok {
+		return cal, nil
+	}
+	return chinaBusinessCalendar{}, fmt.Errorf("CHINA_HOLIDAY_CALENDAR_UNAVAILABLE:%d", year)
+}
+
+func isChinaBusinessDay(d time.Time, cal chinaBusinessCalendar) bool {
+	iso := d.UTC().Format("2006-01-02")
+	if cal.adjustedWorkdays[iso] {
+		return true
+	}
+	if cal.holidays[iso] {
+		return false
+	}
+	wd := d.UTC().Weekday()
+	return wd != time.Sunday && wd != time.Saturday
+}
+
+// buildLprCandidates derives the provisional PBoC Loan Prime Rate release dates:
+// the 20th of each month rolled forward to the next mainland-China business day.
+// Realized dates are confirmed later via ChinaMoney (mergeVerifiedLprDates).
+func buildLprCandidates(year int) ([]chinaReleaseEvent, error) {
+	cal, err := businessCalendar(year)
+	if err != nil {
+		return nil, err
+	}
+	events := make([]chinaReleaseEvent, 0, 12)
+	for month := 1; month <= 12; month++ {
+		d := time.Date(year, time.Month(month), 20, 0, 0, 0, 0, time.UTC)
+		for !isChinaBusinessDay(d, cal) {
+			d = d.AddDate(0, 0, 1)
+		}
+		releaseDate := d.UTC().Format("2006-01-02")
+		events = append(events, chinaReleaseEvent{
+			ID:          "pboc-lpr-" + releaseDate[:7],
+			Event:       "Loan Prime Rate (LPR)",
+			CountryCode: "CN",
+			ReleaseDate: releaseDate,
+			ReleaseTime: "09:00",
+			Timezone:    "Asia/Shanghai",
+			Kind:        "pboc_lpr",
+			Status:      "provisional",
+			Source:      "PBoC rule; realized date verified by ChinaMoney/CFETS",
+			SourceURL:   chinaMoneyLPRURL,
+		})
+	}
+	return events, nil
+}
+
+var (
+	reLprNoticeTitle = regexp.MustCompile(`受权公布贷款市场报价利率.*LPR`)
+	reLprNoticeDate  = regexp.MustCompile(`^20\d{2}-\d{2}-\d{2}$`)
+)
+
+// parseChinaMoneyLprNotices extracts the realized LPR announcement dates from the
+// ChinaMoney notice feed, keeping only genuine rate-publication notices.
+func parseChinaMoneyLprNotices(body []byte) []string {
+	var payload struct {
+		Records []struct {
+			Title       string `json:"title"`
+			ReleaseDate string `json:"releaseDate"`
+		} `json:"records"`
+	}
+	if err := json.Unmarshal(body, &payload); err != nil {
+		return nil
+	}
+	seen := map[string]bool{}
+	var dates []string
+	for _, rec := range payload.Records {
+		if !reLprNoticeTitle.MatchString(rec.Title) {
+			continue
+		}
+		d := rec.ReleaseDate
+		if len(d) > 10 {
+			d = d[:10]
+		}
+		if !reLprNoticeDate.MatchString(d) || seen[d] {
+			continue
+		}
+		seen[d] = true
+		dates = append(dates, d)
+	}
+	sort.Strings(dates)
+	return dates
+}
+
+// mergeVerifiedLprDates promotes each provisional candidate to a verified date
+// when ChinaMoney published a realized announcement in the same month.
+func mergeVerifiedLprDates(candidates []chinaReleaseEvent, realizedDates []string) []chinaReleaseEvent {
+	realizedByMonth := map[string]string{}
+	for _, d := range realizedDates {
+		if len(d) >= 7 {
+			realizedByMonth[d[:7]] = d
+		}
+	}
+	out := make([]chinaReleaseEvent, len(candidates))
+	for i, c := range candidates {
+		out[i] = c
+		if realized, ok := realizedByMonth[c.ReleaseDate[:7]]; ok {
+			out[i].ReleaseDate = realized
+			out[i].Status = "verified"
+			out[i].ID = "pboc-lpr-" + realized[:7]
+		}
+	}
+	return out
+}
+
+// currentCalendarLink resolves the year's NBS calendar page from the index,
+// refusing any link that is not on the trusted www.stats.gov.cn release-calendar
+// path so a tampered index can never redirect the scrape off-origin.
+func currentCalendarLink(indexHTML string, year int) (string, error) {
+	re := regexp.MustCompile(`href=["']([^"']+)["'][^>]*>[^<]*` + strconv.Itoa(year) + `[^<]*<`)
+	m := re.FindStringSubmatch(indexHTML)
+	if m == nil {
+		return nbsCalendarIndexURL, nil
+	}
+	base, err := url.Parse(nbsCalendarIndexURL)
+	if err != nil {
+		return "", fmt.Errorf("NBS_CALENDAR_LINK_REJECTED:UNTRUSTED_NBS_CALENDAR_URL")
+	}
+	ref, err := base.Parse(m[1])
+	if err != nil {
+		return "", fmt.Errorf("NBS_CALENDAR_LINK_REJECTED:UNTRUSTED_NBS_CALENDAR_URL")
+	}
+	trustedOrigin := ref.Scheme == "https" && ref.Host == "www.stats.gov.cn"
+	trustedPath := strings.HasPrefix(ref.Path, "/english/PressRelease/ReleaseCalendar/")
+	if !trustedOrigin || !trustedPath {
+		return "", fmt.Errorf("NBS_CALENDAR_LINK_REJECTED:UNTRUSTED_NBS_CALENDAR_URL")
+	}
+	return ref.String(), nil
+}
+
+// ── merge ────────────────────────────────────────────────────────────────────
+
+func requiredIndicator(indicators []chinaIndicator, category string) *chinaIndicator {
+	for i := range indicators {
+		if indicators[i].Category == category && !indicators[i].ContextOnly {
+			return &indicators[i]
+		}
+	}
+	return nil
+}
+
+// buildChinaMacroSnapshot applies the launch gate: launchReady only when all four
+// required categories (price/activity/policy/fx) carry a current, non-stale
+// value. contentObservationDate is the OLDEST required observation — the anchor
+// that keeps a fresh FX tick from masking stale CPI/activity content.
+func buildChinaMacroSnapshot(indicators []chinaIndicator, decisions []chinaSourceDecision, generatedAt string) chinaMacroSnapshot {
+	launchReady := true
+	var requiredDates []string
+	for _, cat := range chinaRequiredCategories {
+		ind := requiredIndicator(indicators, cat)
+		if ind == nil || ind.Value == nil || ind.Stale || ind.UnavailableReason != "" {
+			launchReady = false
+		}
+		if ind != nil && ind.ObservationDate != "" {
+			requiredDates = append(requiredDates, ind.ObservationDate)
+		}
+	}
+	sort.Strings(requiredDates)
+	anyValue := false
+	for i := range indicators {
+		if indicators[i].Value != nil {
+			anyValue = true
+			break
+		}
+	}
+	status := "unavailable"
+	switch {
+	case launchReady:
+		status = "ready"
+	case anyValue:
+		status = "degraded"
+	}
+	content := ""
+	if launchReady && len(requiredDates) == len(chinaRequiredCategories) {
+		content = requiredDates[0]
+	}
+	latest := ""
+	if len(requiredDates) > 0 {
+		latest = requiredDates[len(requiredDates)-1]
+	}
+	return chinaMacroSnapshot{
+		CountryCode: "CN", GeneratedAt: generatedAt, Status: status, LaunchReady: launchReady,
+		ContentObservationDate: content, LatestObservationDate: latest,
+		Indicators: indicators, SourceDecisions: decisions,
+		ReleaseEvents: []chinaReleaseEvent{},
+	}
+}
+
+func chinaDecision(source, host, status, reason, checkedAt string, optional bool, requestCount int) chinaSourceDecision {
+	return chinaSourceDecision{Source: source, Host: host, Status: status, Reason: reason, CheckedAt: checkedAt, Optional: optional, RequestCount: requestCount}
+}
+
+func chinaUnavailable() chinaMacroSnapshot {
+	return chinaMacroSnapshot{
+		CountryCode: "CN", Status: "unavailable",
+		Indicators: []chinaIndicator{}, SourceDecisions: []chinaSourceDecision{}, ReleaseEvents: []chinaReleaseEvent{},
+		Unavailable: true,
+	}
+}
+
+// ── handler ──────────────────────────────────────────────────────────────────
+
+// handleChinaMacro serves GET /v1/world/china-macro: the merged China macro
+// snapshot + official release calendar. Cached 30m fresh / 6h stale (these are
+// daily/monthly series); on a required-source outage it serves last-good stale,
+// else an honest unavailable payload.
+func (s *Server) handleChinaMacro(w http.ResponseWriter, r *http.Request) {
+	if preflight(w, r, "GET, OPTIONS") || methodNotGet(w, r) {
+		return
+	}
+	s.cachedJSON(w, "china:macro:v1",
+		"public, max-age=1800, s-maxage=1800, stale-while-revalidate=600",
+		30*time.Minute, 6*time.Hour,
+		func(ctx context.Context) (any, error) { return s.chinaMacro(ctx) },
+		func(w http.ResponseWriter, _ error) { writeJSON(w, http.StatusOK, "", chinaUnavailable()) })
+}
+
+// oecdHeaders carries the Accept-Language the OECD CLI endpoint requires (it
+// answers 500 to language-less clients even where curl succeeds).
+var oecdHeaders = map[string]string{
+	"Accept":          "text/csv, text/plain;q=0.9, */*;q=0.1",
+	"Accept-Language": "en",
+	"User-Agent":      browserUA,
+}
+
+func chinaReasonFor(err error) string {
+	if err == nil {
+		return "OK"
+	}
+	msg := strings.ToLower(err.Error())
+	if strings.Contains(msg, "timeout") || strings.Contains(msg, "deadline") {
+		return "TIMEOUT"
+	}
+	if m := reStatusCode.FindStringSubmatch(msg); m != nil {
+		return "HTTP_" + m[1]
+	}
+	return "FETCH_FAILED"
+}
+
+func (s *Server) chinaMacro(ctx context.Context) (any, error) {
+	now := time.Now().UTC()
+	checkedAt := now.Format(time.RFC3339)
+	var decisions []chinaSourceDecision
+
+	// 1. OECD — required. Two sequential dataset requests, no retry: OECD asks
+	// consumers to stay under 60 downloads/hour, so a failure preserves last-good
+	// rather than replaying the flow.
+	cpiCSV, err := s.getText(ctx, oecdCPIURL, oecdHeaders)
+	reqCount := 1
+	if err == nil {
+		var cliCSV string
+		cliCSV, err = s.getText(ctx, oecdCLIURL, oecdHeaders)
+		reqCount = 2
+		if err == nil {
+			decisions = append(decisions, chinaDecision("OECD Data Explorer", "sdmx.oecd.org", "accepted", "OK", checkedAt, false, reqCount))
+			return s.chinaMerge(ctx, now, checkedAt, decisions, []byte(cpiCSV), []byte(cliCSV))
+		}
+	}
+	reason := chinaReasonFor(err)
+	decisions = append(decisions, chinaDecision("OECD Data Explorer", "sdmx.oecd.org", "blocked", reason, checkedAt, false, reqCount))
+	return nil, fmt.Errorf("OECD_REQUIRED_SOURCE_UNAVAILABLE:%s", reason)
+}
+
+func (s *Server) chinaMerge(ctx context.Context, now time.Time, checkedAt string, decisions []chinaSourceDecision, cpiCSV, cliCSV []byte) (any, error) {
+	indicators := []chinaIndicator{
+		parseOecdCsvIndicator(cpiCSV, indicatorDef{id: "cpi_yoy", label: "CPI (YoY)", category: "price", unit: "%", source: "OECD Data Explorer", sourceURL: oecdCPIURL, maxAgeDays: 120}, now),
+		parseOecdCsvIndicator(cliCSV, indicatorDef{id: "activity_cli", label: "Composite Leading Indicator", category: "activity", unit: "index", source: "OECD Data Explorer", sourceURL: oecdCLIURL, maxAgeDays: 120}, now),
+	}
+
+	// 2. BIS policy rate — read from the seed cache key the worldmonitor BIS job
+	// populates. Our fork ships no such job, so the key is empty and the indicator
+	// is honestly not_configured; parseBisPolicy lights up the moment it is seeded.
+	if b, ok := s.kvGet(ctx, bisPolicyCacheKey); ok {
+		ind := parseBisPolicy(b, now)
+		indicators = append(indicators, ind)
+		decisions = append(decisions, chinaDecision("BIS seed cache", "hanzo-kv", statusFor(ind), reasonOrOK(ind), checkedAt, false, 1))
+	} else {
+		indicators = append(indicators, unavailableIndicator(bisPolicyDef, "not_configured", false))
+		decisions = append(decisions, chinaDecision("BIS seed cache", "hanzo-kv", "blocked", "not_configured", checkedAt, false, 0))
+	}
+
+	// 3. FRED DEXCHUS — reuse the FRED_API_KEY env path the fred-data handler uses.
+	if key := env("FRED_API_KEY"); key != "" {
+		b, status, err := s.get(ctx, fredDEXCHUSURL+"&api_key="+key, map[string]string{"Accept": "application/json"})
+		if err == nil && status >= 200 && status < 300 {
+			ind := parseFredUsdCny(b, now)
+			indicators = append(indicators, ind)
+			decisions = append(decisions, chinaDecision("FRED DEXCHUS", "api.stlouisfed.org", statusFor(ind), reasonOrOK(ind), checkedAt, false, 1))
+		} else {
+			reason := chinaReasonFor(orStatusErr(err, status))
+			indicators = append(indicators, unavailableIndicator(fredUsdCnyDef, reason, false))
+			decisions = append(decisions, chinaDecision("FRED DEXCHUS", "api.stlouisfed.org", "blocked", reason, checkedAt, false, 1))
+		}
+	} else {
+		indicators = append(indicators, unavailableIndicator(fredUsdCnyDef, "not_configured", false))
+		decisions = append(decisions, chinaDecision("FRED DEXCHUS", "api.stlouisfed.org", "blocked", "not_configured", checkedAt, false, 0))
+	}
+
+	// 4. HKMA CNY/HKD context — optional.
+	if b, status, err := s.get(ctx, hkmaCNYURL, map[string]string{"Accept": "application/json", "User-Agent": browserUA}); err == nil && status >= 200 && status < 300 {
+		ind := parseHkmaCnyContext(b, now)
+		indicators = append(indicators, ind)
+		decisions = append(decisions, chinaDecision("HKMA CNY context", "api.hkma.gov.hk", statusFor(ind), reasonOrOK(ind), checkedAt, true, 1))
+	} else {
+		reason := chinaReasonFor(orStatusErr(err, status))
+		indicators = append(indicators, unavailableIndicator(hkmaCnyDef, reason, true))
+		decisions = append(decisions, chinaDecision("HKMA CNY context", "api.hkma.gov.hk", "blocked", reason, checkedAt, true, 1))
+	}
+
+	snapshot := buildChinaMacroSnapshot(indicators, decisions, checkedAt)
+
+	// Calendar is required for the merged product (mirrors get-china-macro-
+	// snapshot.ts, which returns unavailable when either indicators or events are
+	// empty). On outage, return an error so cachedJSON serves last-good stale.
+	events, calDecisions, calErr := s.chinaCalendar(ctx, now, checkedAt)
+	snapshot.SourceDecisions = append(snapshot.SourceDecisions, calDecisions...)
+	if calErr != nil || len(events) == 0 {
+		return nil, fmt.Errorf("CHINA_CALENDAR_UNAVAILABLE")
+	}
+	snapshot.ReleaseEvents = events
+	return snapshot, nil
+}
+
+func (s *Server) chinaCalendar(ctx context.Context, now time.Time, checkedAt string) ([]chinaReleaseEvent, []chinaSourceDecision, error) {
+	year := now.Year()
+	var decisions []chinaSourceDecision
+	htmlHeaders := map[string]string{"Accept": "text/html,application/xhtml+xml", "User-Agent": browserUA}
+
+	indexHTML, err := s.getText(ctx, nbsCalendarIndexURL, htmlHeaders)
+	nbsReq := 1
+	if err != nil {
+		decisions = append(decisions, chinaDecision("NBS release calendar", "www.stats.gov.cn", "blocked", chinaReasonFor(err), checkedAt, false, nbsReq))
+		return nil, decisions, err
+	}
+	calURL, err := currentCalendarLink(indexHTML, year)
+	if err != nil {
+		decisions = append(decisions, chinaDecision("NBS release calendar", "www.stats.gov.cn", "blocked", "UNTRUSTED_NBS_CALENDAR_URL", checkedAt, false, nbsReq))
+		return nil, decisions, err
+	}
+	calHTML := indexHTML
+	if calURL != nbsCalendarIndexURL {
+		nbsReq = 2
+		calHTML, err = s.getText(ctx, calURL, htmlHeaders)
+		if err != nil {
+			decisions = append(decisions, chinaDecision("NBS release calendar", "www.stats.gov.cn", "blocked", chinaReasonFor(err), checkedAt, false, nbsReq))
+			return nil, decisions, err
+		}
+	}
+	nbsEvents := parseNbsReleaseCalendar([]byte(calHTML), year, calURL)
+	if len(nbsEvents) == 0 {
+		decisions = append(decisions, chinaDecision("NBS release calendar", "www.stats.gov.cn", "blocked", "NO_NBS_EVENTS", checkedAt, false, nbsReq))
+		return nil, decisions, fmt.Errorf("NBS_REQUIRED_SOURCE_UNAVAILABLE:NO_NBS_EVENTS")
+	}
+	decisions = append(decisions, chinaDecision("NBS release calendar", "www.stats.gov.cn", "accepted", "OK", checkedAt, false, nbsReq))
+
+	lpr, err := buildLprCandidates(year)
+	if err != nil {
+		decisions = append(decisions, chinaDecision("PBoC/ChinaMoney LPR verification", "www.chinamoney.com.cn", "blocked", "CHINA_HOLIDAY_CALENDAR_UNAVAILABLE", checkedAt, false, 0))
+		return nil, decisions, err
+	}
+	if notices, err := s.chinaMoneyNotices(ctx); err == nil {
+		lpr = mergeVerifiedLprDates(lpr, parseChinaMoneyLprNotices(notices))
+		decisions = append(decisions, chinaDecision("PBoC/ChinaMoney LPR verification", "www.chinamoney.com.cn", "accepted", "OK", checkedAt, false, 1))
+	} else {
+		decisions = append(decisions, chinaDecision("PBoC/ChinaMoney LPR verification", "www.chinamoney.com.cn", "blocked", chinaReasonFor(err), checkedAt, false, 1))
+	}
+
+	events := append(nbsEvents, lpr...)
+	sortReleaseEvents(events)
+	return events, decisions, nil
+}
+
+func (s *Server) chinaMoneyNotices(ctx context.Context) ([]byte, error) {
+	body := []byte(url.Values{"channelId": {chinaMoneyLPRChannelID}, "pageSize": {"24"}, "pageNo": {"1"}}.Encode())
+	b, status, err := s.do(ctx, http.MethodPost, chinaMoneyLPRNoticeAPI, map[string]string{
+		"Accept":       "application/json",
+		"Content-Type": "application/x-www-form-urlencoded; charset=UTF-8",
+		"User-Agent":   browserUA,
+	}, body)
+	if err != nil {
+		return nil, err
+	}
+	if status < 200 || status >= 300 {
+		return nil, httpErr(status)
+	}
+	return b, nil
+}
+
+// kvGet reads a raw value from the shared hot cache, reporting absence (or a
+// disabled cache) as ok=false so callers degrade to not_configured.
+func (s *Server) kvGet(ctx context.Context, key string) ([]byte, bool) {
+	if s.kv == nil {
+		return nil, false
+	}
+	b, ok := s.kv.GetBytes(ctx, key)
+	return b, ok && len(b) > 0
+}
+
+func statusFor(ind chinaIndicator) string {
+	if ind.Value == nil {
+		return "blocked"
+	}
+	return "accepted"
+}
+
+func reasonOrOK(ind chinaIndicator) string {
+	if ind.UnavailableReason != "" {
+		return ind.UnavailableReason
+	}
+	return "OK"
+}
+
+func orStatusErr(err error, status int) error {
+	if err != nil {
+		return err
+	}
+	return httpErr(status)
+}

internal/world/handlers_china_test.go

@@ -0,0 +1,244 @@
+package world
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+)
+
+func chinaFixture(t *testing.T, name string) []byte {
+	t.Helper()
+	b, err := os.ReadFile(filepath.Join("testdata", "china-macro", name))
+	if err != nil {
+		t.Fatalf("read fixture %s: %v", name, err)
+	}
+	return b
+}
+
+var chinaNow = time.Date(2026, 7, 13, 0, 0, 0, 0, time.UTC)
+
+func deref(t *testing.T, p *float64) float64 {
+	t.Helper()
+	if p == nil {
+		t.Fatalf("expected a value, got nil")
+	}
+	return *p
+}
+
+// Parity with the TypeScript adapters: each source parser normalizes to
+// independent value / prior / date / source / staleness fields.
+func TestChinaSourceParsers(t *testing.T) {
+	cpi := parseOecdCsvIndicator(chinaFixture(t, "oecd-cpi.csv"),
+		indicatorDef{id: "cpi_yoy", label: "CPI (YoY)", category: "price", unit: "%", source: "OECD Data Explorer", maxAgeDays: 120}, chinaNow)
+	if deref(t, cpi.Value) != 0.6 || deref(t, cpi.PriorValue) != 0.3 || cpi.ObservationDate != "2026-05" ||
+		cpi.Source != "OECD Data Explorer" || cpi.Stale || cpi.UnavailableReason != "" {
+		t.Fatalf("cpi mismatch: %+v", cpi)
+	}
+
+	cli := parseOecdCsvIndicator(chinaFixture(t, "oecd-cli.csv"),
+		indicatorDef{id: "activity_cli", label: "Composite Leading Indicator", category: "activity", unit: "index", source: "OECD Data Explorer", maxAgeDays: 120}, chinaNow)
+	if deref(t, cli.Value) != 99.58 {
+		t.Fatalf("cli value = %v, want 99.58", cli.Value)
+	}
+
+	policy := parseBisPolicy(chinaFixture(t, "bis-policy.json"), chinaNow)
+	if deref(t, policy.Value) != 3 || deref(t, policy.PriorValue) != 3.1 {
+		t.Fatalf("policy mismatch: value=%v prior=%v", policy.Value, policy.PriorValue)
+	}
+
+	fx := parseFredUsdCny(chinaFixture(t, "fred-dexchus.json"), chinaNow)
+	if deref(t, fx.Value) != 7.1842 {
+		t.Fatalf("fx value = %v, want 7.1842", fx.Value)
+	}
+
+	hkma := parseHkmaCnyContext(chinaFixture(t, "hkma-cny.json"), chinaNow)
+	if !hkma.ContextOnly || hkma.Source != "HKMA (Hong Kong/CNH context)" || deref(t, hkma.Value) != 1.0881 {
+		t.Fatalf("hkma mismatch: %+v", hkma)
+	}
+}
+
+// An old observation is stale even when the fetch itself is fresh.
+func TestChinaStaleObservation(t *testing.T) {
+	stale := parseOecdCsvIndicator(chinaFixture(t, "oecd-cpi.csv"),
+		indicatorDef{id: "cpi_yoy", label: "CPI (YoY)", category: "price", unit: "%", source: "OECD Data Explorer", maxAgeDays: 30},
+		time.Date(2027, 1, 1, 0, 0, 0, 0, time.UTC))
+	if !stale.Stale || stale.UnavailableReason != "STALE_OBSERVATION" {
+		t.Fatalf("expected stale STALE_OBSERVATION, got stale=%v reason=%q", stale.Stale, stale.UnavailableReason)
+	}
+}
+
+// The launch gate needs current price, activity, policy, and FX; the oldest
+// required observation anchors contentObservationDate. Optional context states
+// are retained and never gate launch.
+func TestChinaLaunchGate(t *testing.T) {
+	indicators := []chinaIndicator{
+		parseOecdCsvIndicator(chinaFixture(t, "oecd-cpi.csv"), indicatorDef{id: "cpi_yoy", category: "price", unit: "%", source: "OECD Data Explorer", maxAgeDays: 120}, chinaNow),
+		parseOecdCsvIndicator(chinaFixture(t, "oecd-cli.csv"), indicatorDef{id: "activity_cli", category: "activity", unit: "index", source: "OECD Data Explorer", maxAgeDays: 120}, chinaNow),
+		parseBisPolicy(chinaFixture(t, "bis-policy.json"), chinaNow),
+		parseFredUsdCny(chinaFixture(t, "fred-dexchus.json"), chinaNow),
+		unavailableIndicator(hkmaCnyDef, "HOST_BLOCKED", true),
+	}
+	snap := buildChinaMacroSnapshot(indicators, nil, chinaNow.Format(time.RFC3339))
+	if !snap.LaunchReady || snap.Status != "ready" {
+		t.Fatalf("expected ready/launch, got status=%q launchReady=%v", snap.Status, snap.LaunchReady)
+	}
+	if snap.ContentObservationDate != "2026-05" {
+		t.Fatalf("contentObservationDate = %q, want oldest required 2026-05", snap.ContentObservationDate)
+	}
+	if snap.LatestObservationDate != "2026-07-10" {
+		t.Fatalf("latestObservationDate = %q, want 2026-07-10", snap.LatestObservationDate)
+	}
+	if last := snap.Indicators[len(snap.Indicators)-1]; last.UnavailableReason != "HOST_BLOCKED" {
+		t.Fatalf("optional context state not retained: %+v", last)
+	}
+
+	// A stale required category drops launch readiness to degraded.
+	indicators[1].Stale = true
+	degraded := buildChinaMacroSnapshot(indicators, nil, chinaNow.Format(time.RFC3339))
+	if degraded.LaunchReady || degraded.Status != "degraded" || degraded.ContentObservationDate != "" {
+		t.Fatalf("expected degraded with blank content date, got %+v", degraded)
+	}
+}
+
+// A missing policy source (our fork has no BIS feed) is honestly not_configured
+// and holds launch back rather than faking readiness.
+func TestChinaNotConfiguredPolicyBlocksLaunch(t *testing.T) {
+	indicators := []chinaIndicator{
+		parseOecdCsvIndicator(chinaFixture(t, "oecd-cpi.csv"), indicatorDef{id: "cpi_yoy", category: "price", source: "OECD Data Explorer", maxAgeDays: 120}, chinaNow),
+		parseOecdCsvIndicator(chinaFixture(t, "oecd-cli.csv"), indicatorDef{id: "activity_cli", category: "activity", source: "OECD Data Explorer", maxAgeDays: 120}, chinaNow),
+		unavailableIndicator(bisPolicyDef, "not_configured", false),
+		parseFredUsdCny(chinaFixture(t, "fred-dexchus.json"), chinaNow),
+	}
+	snap := buildChinaMacroSnapshot(indicators, nil, chinaNow.Format(time.RFC3339))
+	if snap.LaunchReady || snap.Status != "degraded" {
+		t.Fatalf("not_configured policy should degrade, got status=%q launchReady=%v", snap.Status, snap.LaunchReady)
+	}
+	if got := requiredIndicator(snap.Indicators, "policy"); got == nil || got.UnavailableReason != "not_configured" {
+		t.Fatalf("policy indicator not marked not_configured: %+v", got)
+	}
+}
+
+// The NBS grid keeps blank months empty and captures quarterly + Spring-Festival
+// shifted releases.
+func TestChinaParseNbsReleaseCalendar(t *testing.T) {
+	events := parseNbsReleaseCalendar(chinaFixture(t, "nbs-calendar.html"), 2026,
+		"https://www.stats.gov.cn/english/PressRelease/ReleaseCalendar/202512/t20251226_1962154.html")
+
+	for _, e := range events {
+		if e.Event == "National Economic Performance" && len(e.ReleaseDate) >= 7 && e.ReleaseDate[:7] == "2026-02" {
+			t.Fatalf("blank February month should stay empty, got %+v", e)
+		}
+	}
+
+	var prelim []string
+	for _, e := range events {
+		if strings.HasPrefix(e.Event, "Preliminary Accounting") {
+			prelim = append(prelim, e.ReleaseDate)
+		}
+	}
+	want := []string{"2026-01-20", "2026-04-17", "2026-07-16", "2026-10-20"}
+	if len(prelim) != len(want) {
+		t.Fatalf("preliminary accounting dates = %v, want %v", prelim, want)
+	}
+	for i := range want {
+		if prelim[i] != want[i] {
+			t.Fatalf("preliminary accounting dates = %v, want %v", prelim, want)
+		}
+	}
+
+	if !hasReleaseOn(events, "Purchasing Managers", "2026-03-04") || !hasReleaseOn(events, "Purchasing Managers", "2026-03-31") {
+		t.Fatalf("PMI Spring-Festival-shifted dual release not captured")
+	}
+}
+
+func hasReleaseOn(events []chinaReleaseEvent, eventSubstr, date string) bool {
+	for _, e := range events {
+		if e.ReleaseDate == date && strings.Contains(e.Event, eventSubstr) {
+			return true
+		}
+	}
+	return false
+}
+
+// LPR candidates roll over weekends and official holidays; only realized months
+// are promoted to verified.
+func TestChinaLprCandidates(t *testing.T) {
+	candidates, err := buildLprCandidates(2026)
+	if err != nil {
+		t.Fatalf("buildLprCandidates(2026): %v", err)
+	}
+	if got := monthDate(candidates, "2026-02"); got != "2026-02-24" {
+		t.Fatalf("Feb LPR candidate = %q, want 2026-02-24 (Spring Festival roll-forward)", got)
+	}
+	if got := monthDate(candidates, "2026-06"); got != "2026-06-22" {
+		t.Fatalf("Jun LPR candidate = %q, want 2026-06-22 (Dragon Boat roll-forward)", got)
+	}
+	for _, c := range candidates {
+		if c.Status != "provisional" {
+			t.Fatalf("candidate %s not provisional: %q", c.ReleaseDate, c.Status)
+		}
+	}
+
+	realized := parseChinaMoneyLprNotices(chinaFixture(t, "chinamoney-lpr.json"))
+	merged := mergeVerifiedLprDates(candidates, realized)
+	if statusOf(merged, "2026-02-24") != "verified" || statusOf(merged, "2026-06-22") != "verified" {
+		t.Fatalf("realized LPR dates not verified: %v", merged)
+	}
+	if statusOf(merged, "2026-07-20") != "provisional" {
+		t.Fatalf("unrealized July LPR should stay provisional")
+	}
+}
+
+// Fails closed when the official holiday calendar is not configured for a year.
+func TestChinaLprCalendarUnconfiguredYear(t *testing.T) {
+	if _, err := buildLprCandidates(2027); err == nil {
+		t.Fatalf("expected CHINA_HOLIDAY_CALENDAR_UNAVAILABLE for unconfigured 2027")
+	}
+}
+
+// The trusted-origin guard resolves same-origin links and refuses off-origin ones.
+func TestChinaCurrentCalendarLink(t *testing.T) {
+	got, err := currentCalendarLink(`<a href="calendar.html">2026 release calendar</a>`, 2026)
+	if err != nil || got != "https://www.stats.gov.cn/english/PressRelease/ReleaseCalendar/calendar.html" {
+		t.Fatalf("trusted relative link resolution failed: got=%q err=%v", got, err)
+	}
+
+	if _, err := currentCalendarLink(`<a href="https://attacker.example/calendar.html">2026 release calendar</a>`, 2026); err == nil {
+		t.Fatalf("off-origin NBS link must be rejected")
+	}
+
+	got, err = currentCalendarLink(`<p>no link here</p>`, 2026)
+	if err != nil || got != nbsCalendarIndexURL {
+		t.Fatalf("missing link should fall back to index URL, got=%q err=%v", got, err)
+	}
+}
+
+// The handler exposes the merged shape and degrades to an honest unavailable
+// payload (never a 5xx) — the fallback branch of the endpoint.
+func TestChinaUnavailableShape(t *testing.T) {
+	u := chinaUnavailable()
+	if u.CountryCode != "CN" || !u.Unavailable || u.Status != "unavailable" ||
+		u.Indicators == nil || u.ReleaseEvents == nil || u.SourceDecisions == nil {
+		t.Fatalf("unavailable fallback shape wrong: %+v", u)
+	}
+}
+
+func monthDate(events []chinaReleaseEvent, month string) string {
+	for _, e := range events {
+		if len(e.ReleaseDate) >= 7 && e.ReleaseDate[:7] == month {
+			return e.ReleaseDate
+		}
+	}
+	return ""
+}
+
+func statusOf(events []chinaReleaseEvent, date string) string {
+	for _, e := range events {
+		if e.ReleaseDate == date {
+			return e.Status
+		}
+	}
+	return ""
+}

internal/world/handlers_cloud.go

@@ -0,0 +1,586 @@
+package world
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/url"
+	"strconv"
+	"strings"
+	"time"
+)
+
+// Platform "cloud pulse": the anonymized, platform-wide aggregate the flagship
+// dashboard renders (world.hanzo.ai cloud/SaaS/AI variants). It is deliberately
+// non-sensitive — counts and volume buckets only, never per-org spend or names.
+//
+// HONESTY CONTRACT — NOTHING is fabricated. Every number is REAL (measured by an
+// actual backend) or an honest zero/empty. There is no diurnal-sine "demo" curve,
+// no hardcoded uptime, no invented model mix or per-region rate. The honest source
+// ladder (producePulse), best → last:
+//
+//   - VOLUME (requests/sec, 24h requests/tokens, series, model mix):
+//       1. the super-admin usage ledger (get-cloud-usages ?org=all, ClickHouse) —
+//          MEASURED and exact (tokens + spend); clears volumeModeled.
+//       2. else the REAL, public endpoints this same binary already serves: the
+//          native request-geo globe (traffic-globe, totals.rps_1m) for the
+//          headline rate, and the learned-router stats (router-stats) for total
+//          routed requests + hourly throughput + per-model mix. Token volume is not
+//          measured on this path, so tokens stay blank and volumeModeled stays true.
+//       3. else empty (zeros / empty arrays).
+//   - FLEET COUNTS + REGION breakdown: the service-token visor (/v1/machines,
+//     /v1/gpus) + ai catalog (/v1/models). Absent ⇒ zeros and an empty region list
+//     built from the real fleet — never the geo catalog as if it were live.
+//   - UPTIME: the public status page (Gatus up/total). Unreachable ⇒ 0 and the
+//     overview drops the tile — never a constant.
+//
+// demo:true means ONLY that nothing real resolved (a warming-up / not-wired state),
+// never that a number was invented. Signed-in / token-wired deployments see the
+// full measured aggregate; the tokenless public path still shows real request rate,
+// throughput, model mix, uptime and chain scale.
+//
+// Signed-in, org-scoped drill-down (the user's own fleet / models / bill) does NOT
+// come through here — those panels call api.hanzo.ai directly with the caller's IAM
+// token (no shared key). This route is the platform teaser only.
+
+type cloudOverview struct {
+	RequestsPerSec float64 `json:"requestsPerSec"`
+	Requests24h    int64   `json:"requests24h"`
+	Tokens24h      int64   `json:"tokens24h"`
+	ModelsServed   int     `json:"modelsServed"`
+	NodesOnline    int     `json:"nodesOnline"`
+	NodesTotal     int     `json:"nodesTotal"`
+	GpusOnline     int     `json:"gpusOnline"`
+	Regions        int     `json:"regions"`
+	UptimePct      float64 `json:"uptimePct"`
+}
+
+type cloudModel struct {
+	ID          string  `json:"id"`
+	Name        string  `json:"name"`
+	Requests24h int64   `json:"requests24h"`
+	Tokens24h   int64   `json:"tokens24h"`
+	Share       float64 `json:"share"`
+}
+
+type cloudRegion struct {
+	ID             string  `json:"id"`
+	Name           string  `json:"name"`
+	City           string  `json:"city"`
+	Country        string  `json:"country"`
+	Lat            float64 `json:"lat"`
+	Lon            float64 `json:"lon"`
+	Nodes          int     `json:"nodes"`
+	Gpus           int     `json:"gpus"`
+	Status         string  `json:"status"`
+	RequestsPerSec float64 `json:"requestsPerSec"`
+}
+
+type cloudPulse struct {
+	Demo          bool          `json:"demo"`
+	VolumeModeled bool          `json:"volumeModeled"`
+	Source        string        `json:"source"`
+	Note          string        `json:"note"`
+	UpdatedAt     string        `json:"updatedAt"`
+	Window        string        `json:"window"`
+	Overview      cloudOverview `json:"overview"`
+	RequestSeries []int64       `json:"requestSeries"`
+	TokenSeries   []int64       `json:"tokenSeries"`
+	Models        []cloudModel  `json:"models"`
+	Regions       []cloudRegion `json:"regions"`
+	// Users is populated ONLY on the signed-in admin path (real IAM aggregates:
+	// total users, signups, active now, daily-signup series). omitempty ⇒ the public
+	// teaser never carries it.
+	Users *userMetrics `json:"users,omitempty"`
+}
+
+// publicVolumeTimeout bounds each public fallback fetch (traffic-globe, router-stats,
+// status page) so a single slow/unreachable host can't stall the pulse produce.
+const publicVolumeTimeout = 5 * time.Second
+
+// handleCloudPulse serves the platform aggregate. Two honest representations:
+//
+//   - SIGNED-IN ADMIN (z@hanzo.ai / the admin org): the FULL real aggregate, with
+//     the token-plane reads (all-org usage ledger + visor fleet) made using the
+//     CALLER's OWN bearer, never edge-cached. The upstream independently authorizes
+//     the bearer, so a non-super-admin simply degrades to the public sources —
+//     never a fabricated number.
+//   - EVERYONE ELSE (public teaser): cached; service-token counts + real public
+//     volume/uptime.
+//
+// It never 5xxes: any upstream failure degrades to the honest empty pulse.
+func (s *Server) handleCloudPulse(w http.ResponseWriter, r *http.Request) {
+	if preflight(w, r, "GET, OPTIONS") || methodNotGet(w, r) {
+		return
+	}
+	// Authed responses must never be served from (or stored in) the shared public
+	// cache: vary on Authorization so an anonymous cache entry is never handed to a
+	// signed-in caller, and vice-versa.
+	w.Header().Set("Vary", "Authorization")
+
+	if bearer, ok := s.adminIdentity(r); ok {
+		ctx, cancel := context.WithTimeout(r.Context(), 20*time.Second)
+		defer cancel()
+		hdr := map[string]string{"Authorization": bearer}
+		p := s.producePulse(ctx, hdr)
+		// Real platform user metrics (IAM global-users) — admin path only; aggregates
+		// only, never PII. Omitted honestly if the caller isn't a global admin upstream.
+		if um, err := s.fetchUserMetrics(ctx, hdr); err == nil {
+			p.Users = um
+		}
+		// Real platform USAGE + per-model mix from LLM observability (measured requests,
+		// tokens, and REAL model names — not the opaque router arms), when the exact
+		// usage ledger was not available to this caller. Fixes an empty "Model Usage"
+		// and 0-token totals for an operator who can read platform observability.
+		if p.VolumeModeled || len(p.Models) == 0 {
+			s.applyLLMObservability(ctx, &p, hdr)
+		}
+		writeJSON(w, http.StatusOK, "private, no-store", p)
+		return
+	}
+
+	s.cachedJSON(w, "cloud-pulse", "public, max-age=15, s-maxage=15, stale-while-revalidate=60",
+		20*time.Second, 5*time.Minute,
+		func(ctx context.Context) (any, error) {
+			return s.producePulse(ctx, serviceAuth()), nil
+		},
+		func(w http.ResponseWriter, _ error) {
+			writeJSON(w, http.StatusOK, "", emptyPulse())
+		},
+	)
+}
+
+// emptyPulse is the honest zero baseline: no measured data resolved. Every number
+// is zero and the arrays are empty (never null) — flagged demo:true (nothing real
+// yet) and volumeModeled:true (no measured volume). We never fabricate.
+func emptyPulse() cloudPulse {
+	return cloudPulse{
+		Demo:          true,
+		VolumeModeled: true,
+		Source:        "empty",
+		Note:          "Platform metrics are warming up — no measured data is reachable yet. Wire the service token (KMS) for the full live aggregate.",
+		UpdatedAt:     nowRFC(),
+		Window:        "24h",
+		RequestSeries: []int64{},
+		TokenSeries:   []int64{},
+		Models:        []cloudModel{},
+		Regions:       []cloudRegion{},
+	}
+}
+
+// producePulse assembles the pulse from ONLY real sources (see the file header for
+// the honesty ladder). auth is the token-plane header (the KMS service bearer on the
+// public path, or the signed-in admin's own bearer on the flagship admin path); nil
+// leaves the token-plane reads out and the pulse falls back to the public sources.
+// demo:true iff nothing real resolved; every field is real or an honest zero/empty.
+func (s *Server) producePulse(ctx context.Context, auth map[string]string) cloudPulse {
+	p := emptyPulse()
+	real := false
+	volSrc := ""
+
+	// 1) Fleet COUNTS + REGION breakdown (auth → visor + ai catalog).
+	countsReal := s.applyServiceCounts(ctx, &p, auth)
+	if countsReal {
+		real = true
+	}
+
+	// 2) VOLUME — measured ledger first (super-admin ?org=all, exact); else the real
+	//    public request rate + throughput + model mix; else empty. Never modeled.
+	if ov, err := s.fetchCloudUsage(ctx, "24h", auth); err == nil && ov.Totals.Requests > 0 {
+		applyUsageToPulse(&p, ov) // clears volumeModeled, fills tokens/series/models
+		real, volSrc = true, "ledger"
+	} else if s.applyPublicVolume(ctx, &p) {
+		real, volSrc = true, "router" // real rate/throughput/mix; tokens unmeasured ⇒ volumeModeled stays true
+	}
+
+	// 3) UPTIME — real share of healthy endpoints (Gatus up/total). 0 ⇒ tile dropped.
+	if up, ok := s.fetchUptimePct(ctx); ok {
+		p.Overview.UptimePct = up
+		real = true
+	}
+
+	p.Demo = !real
+	switch {
+	case countsReal:
+		p.Source = "service" // the service-token plane resolved (counts, and usually ledger volume)
+	case real:
+		p.Source = "public" // tokenless, but real public volume/uptime landed
+	default:
+		p.Source = "empty"
+	}
+	if real && volSrc == "" {
+		p.Note = "Live fleet and status from Hanzo Cloud. Measured request and token volume appears when the platform usage ledger is reachable."
+	}
+	return p
+}
+
+// applyServiceCounts fills the real fleet counts (models served, nodes online/total,
+// GPUs) and the region breakdown from the service-token visor + ai catalog. Regions
+// are derived from the machines' OWN region strings (resolved to the geo catalog for
+// name/city/coords) — an empty fleet yields an empty regions list, never the geo
+// catalog as if it were live; per-region rate stays 0 (no real per-region source).
+// Returns false (leaving zeros) when no auth header is supplied or the core reads
+// fail. auth is the KMS service bearer (public path) or the caller's own admin
+// bearer (admin path).
+func (s *Server) applyServiceCounts(ctx context.Context, p *cloudPulse, hdr map[string]string) bool {
+	if hdr == nil {
+		return false
+	}
+	host := apiHost()
+
+	// Models served (ai gateway, OpenAI-compatible list).
+	var models struct {
+		Data []struct {
+			ID string `json:"id"`
+		} `json:"data"`
+	}
+	if err := s.getJSON(ctx, host+"/v1/models", hdr, &models); err != nil || len(models.Data) == 0 {
+		return false
+	}
+
+	// Fleet (visor). status is a free string; treat non-terminal states as online.
+	var machines struct {
+		Machines []struct {
+			Region string `json:"region"`
+			Status string `json:"status"`
+		} `json:"machines"`
+	}
+	if err := s.getJSON(ctx, host+"/v1/machines", hdr, &machines); err != nil {
+		return false
+	}
+	var gpus struct {
+		Gpus []struct {
+			Region string `json:"region"`
+		} `json:"gpus"`
+	}
+	// GPUs are a bonus count; a failure here should not sink real machine data.
+	_ = s.getJSON(ctx, host+"/v1/gpus", hdr, &gpus)
+
+	// Real region breakdown: place each machine/GPU into its resolved catalog region
+	// (name/city/coords), counting nodes + GPUs. rps stays 0 — no invented rate.
+	agg := map[string]*cloudRegion{}
+	var order []string
+	// Resolve to the geo catalog for coords/name when the region is known; otherwise
+	// keep the RAW region string as its own region (a real region, just without
+	// catalog coordinates) so EVERY real region shows — never dropped just because
+	// it's outside the 8-city catalog (e.g. tor1, GCP/AWS regions).
+	region := func(raw string) *cloudRegion {
+		raw = strings.TrimSpace(raw)
+		if raw == "" {
+			return nil
+		}
+		id := raw
+		nc := cloudRegion{ID: raw, Name: raw, City: raw, Status: "online"}
+		if rg, ok := resolveRegion(raw); ok {
+			id = rg.ID
+			nc = rg
+			nc.Nodes, nc.Gpus, nc.RequestsPerSec, nc.Status = 0, 0, 0, "online"
+		}
+		if c := agg[id]; c != nil {
+			return c
+		}
+		agg[id] = &nc
+		order = append(order, id)
+		return &nc
+	}
+
+	online := 0
+	for _, m := range machines.Machines {
+		if machineOnline(m.Status) {
+			online++
+		}
+		if c := region(m.Region); c != nil {
+			c.Nodes++
+		}
+	}
+	for _, g := range gpus.Gpus {
+		if c := region(g.Region); c != nil {
+			c.Gpus++
+		}
+	}
+
+	p.Overview.ModelsServed = len(models.Data)
+	p.Overview.NodesTotal = len(machines.Machines)
+	p.Overview.NodesOnline = online
+	p.Overview.GpusOnline = len(gpus.Gpus)
+	regions := make([]cloudRegion, 0, len(order))
+	for _, id := range order {
+		regions = append(regions, *agg[id])
+	}
+	p.Regions = regions
+	p.Overview.Regions = len(regions)
+	return true
+}
+
+// applyPublicVolume folds REAL, public request volume into p when the measured
+// ledger is unavailable — no fabrication. It reads the SAME endpoints this binary
+// already serves to other panels: the native request-geo globe (traffic-globe,
+// totals.rps_1m — the Live Traffic rate) for the headline requests/sec, and the
+// learned-router stats (router-stats, the Enso Training source) for total routed
+// requests, the hourly throughput series and the per-model request mix. Token
+// volume is NOT measured on this path, so Tokens24h / TokenSeries stay empty and
+// volumeModeled stays true. Returns true when at least one real datum landed.
+func (s *Server) applyPublicVolume(ctx context.Context, p *cloudPulse) bool {
+	cctx, cancel := context.WithTimeout(ctx, publicVolumeTimeout)
+	defer cancel()
+	got := false
+
+	// Headline requests/sec — real, from the native LB request-geo aggregate.
+	if g, ok := s.fetchNativeGlobe(cctx, 60); ok && g.Totals.RPS1m > 0 {
+		p.Overview.RequestsPerSec = round1(g.Totals.RPS1m)
+		got = true
+	}
+
+	// Routed-request volume + hourly throughput — real, from the public learned-router
+	// stats (the Enso Training source). NOTE: on platform scope the router relabels
+	// models to OPAQUE "arm-N" ids (a privacy measure), so by_model is NOT real model
+	// names — we never present it as the model mix. Real per-model usage comes only
+	// from the measured ledger (admin path); otherwise Models stays empty and the
+	// panel honestly shows "warming up" rather than "arm-8".
+	if rs, ok := s.fetchRouterStats(cctx, 24); ok {
+		events := rs.Window.Events
+		if events == 0 {
+			events = rs.Throughput.TotalWindow
+		}
+		if events > 0 {
+			p.Overview.Requests24h = events
+			if p.Overview.RequestsPerSec == 0 { // globe rate unavailable → window average
+				p.Overview.RequestsPerSec = round1(float64(events) / routerWindowSecs(rs))
+			}
+			got = true
+		}
+		if len(rs.Throughput.PerHour) > 0 {
+			p.RequestSeries = append([]int64{}, rs.Throughput.PerHour...)
+			got = true
+		}
+	}
+
+	if got {
+		p.Window = "24h"
+		p.Note = "Live platform request rate and throughput — measured across all orgs (traffic globe + learned router). Per-model usage and token volume come from the usage ledger (sign in as an admin)."
+	}
+	return got
+}
+
+// llmUsage is the measured platform usage from LLM observability (/v1/admin/o11y):
+// 24h request/token totals + top models by REAL name. ONE place shapes the o11y read
+// so cloud-pulse and ai-pulse share it (DRY) — the opaque router arms are never used.
+type llmUsage struct {
+	Requests int64
+	Tokens   int64
+	Models   []cloudModel
+}
+
+// fetchLLMUsage reads the platform LLM observability aggregate with the admin's own
+// bearer. ok=false when the caller isn't authorized upstream or it's unreachable, so
+// callers keep their honest fallback.
+func (s *Server) fetchLLMUsage(ctx context.Context, auth map[string]string) (*llmUsage, bool) {
+	if auth == nil {
+		return nil, false
+	}
+	var resp struct {
+		Totals struct {
+			Requests int64 `json:"requests"`
+			Tokens   int64 `json:"tokens"`
+		} `json:"totals"`
+		TopModels []struct {
+			Model    string `json:"model"`
+			Requests int64  `json:"requests"`
+			Tokens   int64  `json:"tokens"`
+		} `json:"topModels"`
+	}
+	if err := s.getJSON(ctx, apiHost()+"/v1/admin/o11y?range=24h", auth, &resp); err != nil {
+		return nil, false
+	}
+	u := &llmUsage{Requests: resp.Totals.Requests, Tokens: resp.Totals.Tokens}
+	var total int64
+	for _, m := range resp.TopModels {
+		total += m.Requests
+	}
+	if total > 0 {
+		for _, m := range resp.TopModels {
+			if m.Model == "" {
+				continue
+			}
+			u.Models = append(u.Models, cloudModel{
+				ID: m.Model, Name: m.Model, Requests24h: m.Requests, Tokens24h: m.Tokens,
+				Share: float64(m.Requests) / float64(total),
+			})
+		}
+	}
+	if u.Requests == 0 && len(u.Models) == 0 {
+		return nil, false
+	}
+	return u, true
+}
+
+// applyLLMObservability overlays REAL platform usage (fetchLLMUsage) onto the pulse:
+// measured requests/tokens + the real model mix (never the opaque router arms). It
+// clears volumeModeled when real numbers land and keeps the freshest rate (globe rps)
+// if already set. No-op (honest fallback kept) when the caller can't read o11y.
+func (s *Server) applyLLMObservability(ctx context.Context, p *cloudPulse, auth map[string]string) {
+	u, ok := s.fetchLLMUsage(ctx, auth)
+	if !ok {
+		return
+	}
+	if u.Requests > 0 {
+		p.Overview.Requests24h = u.Requests
+		p.Overview.Tokens24h = u.Tokens
+		if p.Overview.RequestsPerSec == 0 { // keep the globe's live rate when we have it
+			p.Overview.RequestsPerSec = round1(float64(u.Requests) / 86400)
+		}
+	}
+	if len(u.Models) > 0 {
+		p.Models = u.Models
+	}
+	p.VolumeModeled = false
+	p.Window = "24h"
+	p.Note = "Live platform usage from Hanzo LLM observability — measured requests, tokens and model mix across all orgs."
+}
+
+// routerStatsVolume is the subset of the public router-stats aggregate we fold into
+// the pulse: total routed events (requests), the hourly throughput series, and the
+// per-model event mix. Same upstream the Enso Training panel proxies.
+type routerStatsVolume struct {
+	Window struct {
+		Since  string `json:"since"`
+		Until  string `json:"until"`
+		Events int64  `json:"events"`
+	} `json:"window"`
+	Throughput struct {
+		PerHour     []int64 `json:"per_hour"`
+		TotalWindow int64   `json:"total_window"`
+	} `json:"throughput"`
+	// by_model is intentionally NOT decoded: on platform scope it is opaque "arm-N"
+	// ids, never real model names, so it is never used as the model mix.
+}
+
+// fetchRouterStats reads the PUBLIC learned-router aggregate (no token) and unwraps
+// the {status,data} envelope, exactly as handleCloudRouterStats does. ok=false when
+// unreachable or the envelope is not ok.
+func (s *Server) fetchRouterStats(ctx context.Context, hours int) (*routerStatsVolume, bool) {
+	var env struct {
+		Status string          `json:"status"`
+		Data   json.RawMessage `json:"data"`
+	}
+	u := apiHost() + "/v1/router/stats?scope=platform&hours=" + strconv.Itoa(hours)
+	if err := s.getJSON(ctx, u, nil, &env); err != nil {
+		return nil, false
+	}
+	if env.Status != "ok" || len(env.Data) == 0 || string(env.Data) == "null" {
+		return nil, false
+	}
+	var rs routerStatsVolume
+	if err := json.Unmarshal(env.Data, &rs); err != nil {
+		return nil, false
+	}
+	return &rs, true
+}
+
+// routerWindowSecs is the router-stats window length in seconds (since→until),
+// defaulting to 24h when the timestamps are missing/unparseable — so a window
+// average never divides by a bogus interval.
+func routerWindowSecs(rs *routerStatsVolume) float64 {
+	if t0, e0 := time.Parse(time.RFC3339, rs.Window.Since); e0 == nil {
+		if t1, e1 := time.Parse(time.RFC3339, rs.Window.Until); e1 == nil {
+			if d := t1.Sub(t0).Seconds(); d > 0 {
+				return d
+			}
+		}
+	}
+	return 86400
+}
+
+// fetchUptimePct derives a real platform uptime from the PUBLIC status page (Gatus):
+// the share of monitored endpoints currently healthy (up/total, 0..100). ok=false
+// when the page is unreachable or has no evaluated endpoints — the overview then
+// drops the uptime tile rather than showing a constant.
+func (s *Server) fetchUptimePct(ctx context.Context) (float64, bool) {
+	cctx, cancel := context.WithTimeout(ctx, publicVolumeTimeout)
+	defer cancel()
+	base := statusBase()
+	host := ""
+	if u, err := url.Parse(base); err == nil {
+		host = u.Hostname()
+	}
+	raw, ok := s.fetchGatusBoard(cctx, base, host)
+	if !ok {
+		return 0, false
+	}
+	sp := summarizeStatusPage(host, raw)
+	if sp.Total == 0 {
+		return 0, false
+	}
+	return round2s(float64(sp.Up) / float64(sp.Total) * 100), true
+}
+
+// applyUsageToPulse folds the real platform-wide usage overview into p: the headline
+// rate (recent series bucket, else 24h average), 24h totals, the real hourly
+// request/token series, and the top models by real spend. It clears volumeModeled —
+// these are measured, not modeled.
+func applyUsageToPulse(p *cloudPulse, ov *cloudUsageOverview) {
+	p.VolumeModeled = false
+	p.Window = ov.Range
+	if p.Window == "" {
+		p.Window = "24h"
+	}
+	p.Overview.Requests24h = ov.Totals.Requests
+	p.Overview.Tokens24h = ov.Totals.Tokens
+
+	// Headline rate: the most recent complete bucket is the freshest honest rate;
+	// fall back to the 24h average when there is no usable interval.
+	p.Overview.RequestsPerSec = round1(usageRate(ov.Totals.Requests, ov.Series, ov.Interval, seriesRequests))
+
+	// Real hourly buckets (chronological) drive both sparklines.
+	if n := len(ov.Series); n > 0 {
+		reqs := make([]int64, n)
+		toks := make([]int64, n)
+		for i, pt := range ov.Series {
+			reqs[i] = pt.Requests
+			toks[i] = pt.Tokens
+		}
+		p.RequestSeries = reqs
+		p.TokenSeries = toks
+	}
+
+	// Top models by real spend/volume (ledger byModel items, already ranked).
+	if m := topModelsFromUsage(ov); m != nil {
+		p.Models = m
+	}
+	p.Note = "Live platform aggregate from Hanzo Cloud — models, fleet, and measured 24h request/token volume across all orgs."
+}
+
+func machineOnline(status string) bool {
+	switch status {
+	case "active", "running", "online", "ready", "healthy", "":
+		return true
+	default:
+		return false
+	}
+}
+
+// regionCatalog is Hanzo's DOKS geo catalog — the reference coordinates (id / name /
+// city / country / lat / lon) the map layers place points against, plus per-region
+// capacity weights (Nodes / Gpus) the modeled-globe layer spreads real peer counts
+// across (flagged positionsModeled:true there). It is NOT live fleet data: the
+// cloud-pulse never presents it as such — the pulse's region breakdown is built from
+// the real visor fleet (applyServiceCounts).
+func regionCatalog() []cloudRegion {
+	return []cloudRegion{
+		{ID: "nyc", Name: "New York", City: "New York", Country: "USA", Lat: 40.7128, Lon: -74.0060, Nodes: 42, Gpus: 168, Status: "online"},
+		{ID: "sfo", Name: "San Francisco", City: "San Francisco", Country: "USA", Lat: 37.7749, Lon: -122.4194, Nodes: 38, Gpus: 152, Status: "online"},
+		{ID: "ams", Name: "Amsterdam", City: "Amsterdam", Country: "Netherlands", Lat: 52.3676, Lon: 4.9041, Nodes: 26, Gpus: 96, Status: "online"},
+		{ID: "fra", Name: "Frankfurt", City: "Frankfurt", Country: "Germany", Lat: 50.1109, Lon: 8.6821, Nodes: 22, Gpus: 88, Status: "online"},
+		{ID: "lon", Name: "London", City: "London", Country: "UK", Lat: 51.5074, Lon: -0.1278, Nodes: 18, Gpus: 64, Status: "online"},
+		{ID: "sgp", Name: "Singapore", City: "Singapore", Country: "Singapore", Lat: 1.3521, Lon: 103.8198, Nodes: 16, Gpus: 60, Status: "online"},
+		{ID: "blr", Name: "Bangalore", City: "Bangalore", Country: "India", Lat: 12.9716, Lon: 77.5946, Nodes: 12, Gpus: 40, Status: "degraded"},
+		{ID: "syd", Name: "Sydney", City: "Sydney", Country: "Australia", Lat: -33.8688, Lon: 151.2093, Nodes: 8, Gpus: 24, Status: "online"},
+	}
+}
+
+func trimSlash(s string) string {
+	for len(s) > 0 && s[len(s)-1] == '/' {
+		s = s[:len(s)-1]
+	}
+	return s
+}

internal/world/handlers_cloud_admin.go

@@ -0,0 +1,599 @@
+package world
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"sort"
+	"strconv"
+	"strings"
+	"sync"
+	"time"
+)
+
+// Admin-only Cloud aggregates. Every handler here is gated by requireAdmin
+// (fail-closed 403) and then forwards the caller's own IAM bearer to the cloud
+// subsystems on api.hanzo.ai — no shared key, and cloud independently re-verifies
+// the admin claim. Each degrades honestly: on any upstream failure it returns a
+// 200 with {available:false, note:"…"} rather than 5xx or invented numbers.
+
+// ── fleet: machines + GPUs grouped by provider/region ────────────────────────
+//
+// Real source: visor /v1/machines + /v1/gpus + /v1/fleet/workers. These carry
+// provider, region, status and (for BYO GPUs) VRAM total. Live GPU utilization /
+// memory-used / temperature are NOT instrumented anywhere in the data plane
+// today, so we surface what exists and label the gap honestly rather than faking
+// a utilization gauge.
+
+type fleetMachineRow struct {
+	ID       string `json:"id"`
+	Name     string `json:"name"`
+	Type     string `json:"type"`
+	Status   string `json:"status"`
+	GPUModel string `json:"gpuModel"`
+	GPUs     int    `json:"gpus"`
+	VRAM     string `json:"vram"` // BYO GPUs report VRAM total; "" when unknown
+	VCPU     int    `json:"vcpu"` // vCPU count (visor MachineView.vcpu); 0 when unknown
+	Mem      string `json:"mem"`  // system RAM, e.g. "8 GB"; "" when unknown
+	OS       string `json:"os"`
+}
+
+type fleetRegionGroup struct {
+	Region   string            `json:"region"`
+	GPUs     int               `json:"gpus"`
+	Machines []fleetMachineRow `json:"machines"`
+}
+
+type fleetProviderGroup struct {
+	Provider string             `json:"provider"`
+	Machines int                `json:"machines"`
+	Online   int                `json:"online"`
+	GPUs     int                `json:"gpus"`
+	Regions  []fleetRegionGroup `json:"regions"`
+}
+
+type fleetWorker struct {
+	ID           string   `json:"id"`
+	Hostname     string   `json:"hostname"`
+	Provider     string   `json:"provider"`
+	Location     string   `json:"location"`
+	Status       string   `json:"status"`
+	GPU          string   `json:"gpu"`
+	VRAM         string   `json:"vram"`
+	Capabilities []string `json:"capabilities"`
+	Version      string   `json:"version"`
+}
+
+type cloudFleet struct {
+	Available bool                 `json:"available"`
+	UpdatedAt string               `json:"updatedAt"`
+	Note      string               `json:"note"`
+	UtilNote  string               `json:"utilNote"`
+	Totals    fleetTotals          `json:"totals"`
+	Providers []fleetProviderGroup `json:"providers"`
+	Workers   []fleetWorker        `json:"workers"`
+}
+
+type fleetTotals struct {
+	Machines  int `json:"machines"`
+	Online    int `json:"online"`
+	GPUs      int `json:"gpus"`
+	Providers int `json:"providers"`
+	Regions   int `json:"regions"`
+}
+
+func (s *Server) handleCloudFleet(w http.ResponseWriter, r *http.Request) {
+	if preflight(w, r, "GET, OPTIONS") || methodNotGet(w, r) {
+		return
+	}
+	bearer, ok := s.requireAdmin(w, r)
+	if !ok {
+		return
+	}
+	ctx, cancel := context.WithTimeout(r.Context(), 20*time.Second)
+	defer cancel()
+	hdr := map[string]string{"Authorization": bearer}
+	base := apiHost()
+
+	var machines struct {
+		Machines []struct {
+			ID, Name, Region, Type, Status, Provider, GPU, OS, Mem string
+			Vcpu                                                   int `json:"vcpu"`
+		} `json:"machines"`
+	}
+	if err := s.getJSON(ctx, base+"/v1/machines", hdr, &machines); err != nil {
+		writeJSON(w, http.StatusOK, "", cloudFleet{Available: false, UpdatedAt: nowRFC(), Note: "Fleet inventory (visor) is unavailable right now."})
+		return
+	}
+	var gpus struct {
+		Gpus []struct {
+			ID, Model, Region, Status, Machine, Provider, Memory string
+		} `json:"gpus"`
+	}
+	_ = s.getJSON(ctx, base+"/v1/gpus", hdr, &gpus)
+	var workers struct {
+		Workers []struct {
+			ID, Hostname, Provider, Location, Status, Version string
+			GPUs                                              []struct{ Name, MemoryTotal string } `json:"gpus"`
+			Capabilities                                      []string                             `json:"capabilities"`
+		} `json:"workers"`
+	}
+	_ = s.getJSON(ctx, base+"/v1/fleet/workers", hdr, &workers)
+
+	// Index GPUs by machine: count + a representative VRAM string.
+	type gAgg struct {
+		count int
+		vram  string
+	}
+	byMachine := map[string]*gAgg{}
+	for _, g := range gpus.Gpus {
+		a := byMachine[g.Machine]
+		if a == nil {
+			a = &gAgg{}
+			byMachine[g.Machine] = a
+		}
+		a.count++
+		if a.vram == "" && isRealVRAM(g.Memory) {
+			a.vram = g.Memory
+		}
+	}
+
+	// Group machines by provider → region.
+	provIdx := map[string]*fleetProviderGroup{}
+	regIdx := map[string]map[string]*fleetRegionGroup{}
+	regionSet := map[string]struct{}{}
+	f := cloudFleet{Available: true, UpdatedAt: nowRFC()}
+	for _, m := range machines.Machines {
+		prov := orDash(m.Provider)
+		region := orDash(m.Region)
+		regionSet[region] = struct{}{}
+		pg := provIdx[prov]
+		if pg == nil {
+			pg = &fleetProviderGroup{Provider: prov}
+			provIdx[prov] = pg
+			regIdx[prov] = map[string]*fleetRegionGroup{}
+		}
+		rg := regIdx[prov][region]
+		if rg == nil {
+			rg = &fleetRegionGroup{Region: region}
+			regIdx[prov][region] = rg
+		}
+		ga := byMachine[m.ID]
+		row := fleetMachineRow{ID: m.ID, Name: orDash(m.Name), Type: m.Type, Status: m.Status, GPUModel: m.GPU, VCPU: m.Vcpu, Mem: m.Mem, OS: m.OS}
+		if ga != nil {
+			row.GPUs = ga.count
+			row.VRAM = ga.vram
+		}
+		rg.Machines = append(rg.Machines, row)
+		rg.GPUs += row.GPUs
+		pg.Machines++
+		pg.GPUs += row.GPUs
+		if machineOnline(m.Status) {
+			pg.Online++
+		}
+		f.Totals.Online += boolToInt(machineOnline(m.Status))
+		f.Totals.GPUs += row.GPUs
+		f.Totals.Machines++
+	}
+	// Materialize provider groups (sorted) with their region groups (sorted).
+	for _, pg := range provIdx {
+		pg.Regions = pg.Regions[:0]
+		for _, rg := range regIdx[pg.Provider] {
+			pg.Regions = append(pg.Regions, *rg)
+		}
+		sort.Slice(pg.Regions, func(i, j int) bool { return pg.Regions[i].Region < pg.Regions[j].Region })
+		f.Providers = append(f.Providers, *pg)
+	}
+	sort.Slice(f.Providers, func(i, j int) bool { return f.Providers[i].Machines > f.Providers[j].Machines })
+	f.Totals.Providers = len(provIdx)
+	f.Totals.Regions = len(regionSet)
+
+	for _, wk := range workers.Workers {
+		fw := fleetWorker{ID: wk.ID, Hostname: wk.Hostname, Provider: wk.Provider, Location: wk.Location, Status: wk.Status, Version: wk.Version, Capabilities: wk.Capabilities}
+		if len(wk.GPUs) > 0 {
+			fw.GPU = wk.GPUs[0].Name
+			if isRealVRAM(wk.GPUs[0].MemoryTotal) {
+				fw.VRAM = wk.GPUs[0].MemoryTotal
+			}
+		}
+		f.Workers = append(f.Workers, fw)
+	}
+
+	f.Note = "Live fleet from visor (DO / GCP / AWS / BYO), grouped by provider and region."
+	f.UtilNote = "Live GPU utilization, memory-used and temperature are not yet instrumented in the fleet data plane — only inventory, status and (BYO) VRAM total are reported."
+	writeJSON(w, http.StatusOK, "", f)
+}
+
+func isRealVRAM(s string) bool {
+	s = strings.TrimSpace(s)
+	return s != "" && s != "[N/A]" && !strings.EqualFold(s, "n/a")
+}
+
+// ── services: per-subsystem health + RED metrics ─────────────────────────────
+//
+// Real source: o11y /v1/o11y/status?product=<p> (live up/latency/deployments)
+// fused with /v1/o11y/metrics?product=<p> (request/error/latency series). We
+// probe a curated set of the unified binary's mounted subsystems concurrently.
+
+// cloudSubsystems is the curated set of unified-binary subsystems worth probing
+// on the operator status board. Adding a subsystem here is the one place to wire
+// a new service into the board.
+var cloudSubsystems = []string{
+	"ai", "gateway", "iam", "kms", "s3", "analytics", "o11y", "commerce",
+	"billing", "tasks", "visor", "world", "websearch", "docdb", "sql", "registry", "paas",
+}
+
+type serviceRow struct {
+	Product       string  `json:"product"`
+	Up            bool    `json:"up"`
+	LatencyMs     float64 `json:"latencyMs"`
+	Deployments   int     `json:"deployments"`
+	DeploymentsUp int     `json:"deploymentsUp"`
+	Requests      int64   `json:"requests"`
+	Errors        int64   `json:"errors"`
+	ErrorRate     float64 `json:"errorRate"`
+	P95Ms         float64 `json:"p95Ms"`
+	Instrumented  bool    `json:"instrumented"`
+	Source        string  `json:"source"`
+}
+
+type cloudServices struct {
+	Available bool         `json:"available"`
+	UpdatedAt string       `json:"updatedAt"`
+	Note      string       `json:"note"`
+	Window    string       `json:"window"`
+	Total     int          `json:"total"`
+	Up        int          `json:"up"`
+	Services  []serviceRow `json:"services"`
+}
+
+func (s *Server) handleCloudServices(w http.ResponseWriter, r *http.Request) {
+	if preflight(w, r, "GET, OPTIONS") || methodNotGet(w, r) {
+		return
+	}
+	bearer, ok := s.requireAdmin(w, r)
+	if !ok {
+		return
+	}
+	ctx, cancel := context.WithTimeout(r.Context(), 22*time.Second)
+	defer cancel()
+	hdr := map[string]string{"Authorization": bearer}
+	base := apiHost()
+
+	rows := make([]serviceRow, len(cloudSubsystems))
+	var wg sync.WaitGroup
+	sem := make(chan struct{}, 6)
+	for i, name := range cloudSubsystems {
+		wg.Add(1)
+		go func(i int, name string) {
+			defer wg.Done()
+			sem <- struct{}{}
+			defer func() { <-sem }()
+			rows[i] = s.probeService(ctx, base, name, hdr)
+		}(i, name)
+	}
+	wg.Wait()
+
+	out := cloudServices{Available: true, UpdatedAt: nowRFC(), Window: "1h", Services: rows}
+	for _, rw := range rows {
+		out.Total++
+		if rw.Up {
+			out.Up++
+		}
+	}
+	out.Note = "Per-subsystem health from o11y (live probe) fused with RED metrics over the last hour."
+	writeJSON(w, http.StatusOK, "", out)
+}
+
+// livenessURL maps a cloud subsystem to a real reachability endpoint, used to
+// decide `up` when o11y carries no per-deployment telemetry for it. Each path is
+// GET-able and answers (2xx/3xx or an auth gate) whenever the subsystem is live;
+// an empty string means "no liveness probe" (leave up as whatever o11y said).
+func livenessURL(name string) string {
+	api := apiHost()
+	switch name {
+	case "ai":
+		return api + "/v1/models"
+	case "gateway":
+		return api + "/health"
+	case "iam":
+		return api + "/v1/iam/.well-known/openid-configuration"
+	case "kms":
+		return api + "/v1/kms/health"
+	case "s3":
+		return api + "/v1/s3"
+	case "analytics":
+		return api + "/v1/analytics/overview"
+	case "o11y":
+		return api + "/v1/o11y"
+	case "commerce":
+		return api + "/v1/plans"
+	case "billing":
+		return api + "/v1/billing/balance"
+	case "tasks":
+		return api + "/v1/tasks"
+	case "websearch":
+		return api + "/v1/search"
+	case "docdb":
+		return api + "/v1/docdb"
+	case "sql":
+		return api + "/v1/sql"
+	case "paas":
+		return api + "/v1/platform/health"
+	case "visor":
+		return api + "/v1/machines"
+	case "world":
+		return "https://world.hanzo.ai/v1/world/health"
+	case "registry":
+		return "https://registry.hanzo.ai/v2/"
+	default:
+		return ""
+	}
+}
+
+func (s *Server) probeService(ctx context.Context, base, name string, hdr map[string]string) serviceRow {
+	row := serviceRow{Product: name}
+	var st struct {
+		Product     string  `json:"product"`
+		Up          bool    `json:"up"`
+		LatencyMs   float64 `json:"latencyMs"`
+		Source      string  `json:"source"`
+		Deployments []struct {
+			Instance string `json:"instance"`
+			Up       bool   `json:"up"`
+		} `json:"deployments"`
+	}
+	o11yKnows := false
+	if err := s.getJSON(ctx, base+"/v1/o11y/status?product="+name, hdr, &st); err == nil && len(st.Deployments) > 0 {
+		// o11y has real per-deployment telemetry for this subsystem — trust it.
+		o11yKnows = true
+		row.Up = st.Up
+		row.LatencyMs = st.LatencyMs
+		row.Source = st.Source
+		row.Deployments = len(st.Deployments)
+		for _, d := range st.Deployments {
+			if d.Up {
+				row.DeploymentsUp++
+			}
+		}
+	}
+	// Liveness is authoritative when o11y has no opinion. A subsystem that simply
+	// isn't wired into o11y is NOT down — probing its real endpoint keeps the board
+	// honest (a live-but-uninstrumented service shows UP with no metrics, never a
+	// false "down"). Any answer through the gateway (2xx/3xx, or an auth gate) means
+	// the service is alive; only a transport error or a 5xx is truly down.
+	if !o11yKnows {
+		if u := livenessURL(name); u != "" {
+			if _, code, err := s.get(ctx, u, hdr); err == nil {
+				row.Up = code > 0 && code < 500
+				row.Source = "liveness"
+			}
+		}
+	}
+	var mt struct {
+		Summary struct {
+			Requests  int64   `json:"requests"`
+			Errors    int64   `json:"errors"`
+			ErrorRate float64 `json:"errorRate"`
+			P95Ms     float64 `json:"p95Ms"`
+		} `json:"summary"`
+	}
+	if err := s.getJSON(ctx, base+"/v1/o11y/metrics?product="+name+"&sinceSec=3600&stepSec=300", hdr, &mt); err == nil {
+		row.Instrumented = true
+		row.Requests = mt.Summary.Requests
+		row.Errors = mt.Summary.Errors
+		row.ErrorRate = mt.Summary.ErrorRate
+		row.P95Ms = mt.Summary.P95Ms
+	}
+	return row
+}
+
+// ── analytics: web analytics (Umami-style, analytics.hanzo.ai) ────────────────
+//
+// Real source: the standalone hanzoai/analytics product (analytics.hanzo.ai),
+// Hanzo-IAM bearer. It exposes top pages/referrers/countries + live visitors +
+// pageview/visitor totals across the platform's registered websites. There is NO
+// aggregate endpoint in the cloud binary for these, so this handler is the thin
+// proxy that fans out per-website and merges. Degrades honestly to
+// {available:false} when the product is unreachable or has no websites.
+
+type analyticsMetric struct {
+	X string `json:"x"`
+	Y int64  `json:"y"`
+}
+
+type analyticsSite struct {
+	Name      string `json:"name"`
+	Domain    string `json:"domain"`
+	Pageviews int64  `json:"pageviews"`
+	Visitors  int64  `json:"visitors"`
+	Active    int64  `json:"active"`
+}
+
+type cloudAnalytics struct {
+	Available    bool              `json:"available"`
+	UpdatedAt    string            `json:"updatedAt"`
+	Note         string            `json:"note"`
+	Window       string            `json:"window"`
+	Pageviews    int64             `json:"pageviews"`
+	Visitors     int64             `json:"visitors"`
+	ActiveNow    int64             `json:"activeNow"`
+	Sites        []analyticsSite   `json:"sites"`
+	TopPages     []analyticsMetric `json:"topPages"`
+	TopReferrers []analyticsMetric `json:"topReferrers"`
+	TopCountries []analyticsMetric `json:"topCountries"`
+}
+
+func (s *Server) handleCloudAnalytics(w http.ResponseWriter, r *http.Request) {
+	if preflight(w, r, "GET, OPTIONS") || methodNotGet(w, r) {
+		return
+	}
+	bearer, ok := s.requireAdmin(w, r)
+	if !ok {
+		return
+	}
+	ctx, cancel := context.WithTimeout(r.Context(), 22*time.Second)
+	defer cancel()
+	hdr := map[string]string{"Authorization": bearer}
+	base := env("HANZO_ANALYTICS_BASE")
+	if base == "" {
+		base = "https://analytics.hanzo.ai"
+	}
+	base = trimSlash(base)
+
+	var sites struct {
+		Data []struct {
+			ID     string `json:"id"`
+			Name   string `json:"name"`
+			Domain string `json:"domain"`
+		} `json:"data"`
+	}
+	if err := s.getJSON(ctx, base+"/v1/analytics/websites", hdr, &sites); err != nil || len(sites.Data) == 0 {
+		writeJSON(w, http.StatusOK, "", cloudAnalytics{Available: false, UpdatedAt: nowRFC(), Window: "24h",
+			Note: "Web analytics (analytics.hanzo.ai) has no websites registered or is unreachable."})
+		return
+	}
+
+	end := time.Now()
+	start := end.Add(-24 * time.Hour)
+	q := "startAt=" + strconv.FormatInt(start.UnixMilli(), 10) + "&endAt=" + strconv.FormatInt(end.UnixMilli(), 10)
+
+	out := cloudAnalytics{Available: true, UpdatedAt: nowRFC(), Window: "24h"}
+	pages := map[string]int64{}
+	refs := map[string]int64{}
+	countries := map[string]int64{}
+	var mu sync.Mutex
+	var wg sync.WaitGroup
+	sem := make(chan struct{}, 6)
+	limit := len(sites.Data)
+	if limit > 8 {
+		limit = 8
+	}
+	for _, ws := range sites.Data[:limit] {
+		wg.Add(1)
+		go func(id, name, domain string) {
+			defer wg.Done()
+			sem <- struct{}{}
+			defer func() { <-sem }()
+			site := analyticsSite{Name: orDash(name), Domain: domain}
+			var stats struct {
+				Pageviews struct {
+					Value int64 `json:"value"`
+				} `json:"pageviews"`
+				Visitors struct {
+					Value int64 `json:"value"`
+				} `json:"visitors"`
+			}
+			_ = s.getJSON(ctx, base+"/v1/analytics/websites/"+id+"/stats?"+q, hdr, &stats)
+			site.Pageviews = stats.Pageviews.Value
+			site.Visitors = stats.Visitors.Value
+			var active struct {
+				X int64 `json:"x"`
+			}
+			_ = s.getJSON(ctx, base+"/v1/analytics/websites/"+id+"/active", hdr, &active)
+			site.Active = active.X
+
+			mergeMetric(ctx, s, base, id, "url", q, hdr, pages, &mu)
+			mergeMetric(ctx, s, base, id, "referrer", q, hdr, refs, &mu)
+			mergeMetric(ctx, s, base, id, "country", q, hdr, countries, &mu)
+
+			mu.Lock()
+			out.Sites = append(out.Sites, site)
+			out.Pageviews += site.Pageviews
+			out.Visitors += site.Visitors
+			out.ActiveNow += site.Active
+			mu.Unlock()
+		}(ws.ID, ws.Name, ws.Domain)
+	}
+	wg.Wait()
+
+	sort.Slice(out.Sites, func(i, j int) bool { return out.Sites[i].Pageviews > out.Sites[j].Pageviews })
+	out.TopPages = topMetrics(pages, 8)
+	out.TopReferrers = topMetrics(refs, 8)
+	out.TopCountries = topMetrics(countries, 8)
+	out.Note = "Live web analytics across all registered Hanzo sites (analytics.hanzo.ai), last 24h."
+	writeJSON(w, http.StatusOK, "", out)
+}
+
+func mergeMetric(ctx context.Context, s *Server, base, id, typ, q string, hdr map[string]string, into map[string]int64, mu *sync.Mutex) {
+	var rows []analyticsMetric
+	if err := s.getJSON(ctx, base+"/v1/analytics/websites/"+id+"/metrics?type="+typ+"&"+q, hdr, &rows); err != nil {
+		return
+	}
+	mu.Lock()
+	for _, m := range rows {
+		if strings.TrimSpace(m.X) == "" {
+			continue
+		}
+		into[m.X] += m.Y
+	}
+	mu.Unlock()
+}
+
+func topMetrics(m map[string]int64, n int) []analyticsMetric {
+	out := make([]analyticsMetric, 0, len(m))
+	for k, v := range m {
+		out = append(out, analyticsMetric{X: k, Y: v})
+	}
+	sort.Slice(out, func(i, j int) bool { return out[i].Y > out[j].Y })
+	if len(out) > n {
+		out = out[:n]
+	}
+	return out
+}
+
+// ── llm: platform LLM observability (per-org, per-model, RED) ─────────────────
+//
+// Real source: cloud admin /v1/admin/o11y?range= — already an aggregate over the
+// hanzo.cloud_usage ledger + trace RED. Admin-gated upstream too (double gate);
+// we pass it through. Honest degrade if the caller's token lacks the cloud-side
+// global-admin bit even though its owner is an admin org.
+
+func (s *Server) handleCloudLLM(w http.ResponseWriter, r *http.Request) {
+	if preflight(w, r, "GET, OPTIONS") || methodNotGet(w, r) {
+		return
+	}
+	bearer, ok := s.requireAdmin(w, r)
+	if !ok {
+		return
+	}
+	rng := r.URL.Query().Get("range")
+	if !oneOf(rng, "24h", "7d", "30d") {
+		rng = "24h"
+	}
+	ctx, cancel := context.WithTimeout(r.Context(), 20*time.Second)
+	defer cancel()
+
+	body, status, err := s.get(ctx, apiHost()+"/v1/admin/o11y?range="+rng, map[string]string{"Authorization": bearer})
+	if err != nil || status < 200 || status >= 300 {
+		writeJSON(w, http.StatusOK, "", map[string]any{
+			"available": false, "updatedAt": nowRFC(), "range": rng,
+			"note": "Platform LLM observability requires a cloud global-admin token; not available for this session.",
+		})
+		return
+	}
+	var payload map[string]any
+	if err := json.Unmarshal(body, &payload); err != nil {
+		writeJSON(w, http.StatusOK, "", map[string]any{"available": false, "range": rng, "note": "LLM observability response was unreadable."})
+		return
+	}
+	writeJSON(w, http.StatusOK, "", map[string]any{"available": true, "updatedAt": nowRFC(), "range": rng, "data": payload})
+}
+
+// ── small shared helpers ─────────────────────────────────────────────────────
+
+func nowRFC() string { return time.Now().UTC().Format(time.RFC3339) }
+
+func orDash(s string) string {
+	if strings.TrimSpace(s) == "" {
+		return "—"
+	}
+	return s
+}
+
+func boolToInt(b bool) int {
+	if b {
+		return 1
+	}
+	return 0
+}

internal/world/handlers_cloud_admin_test.go

@@ -0,0 +1,97 @@
+package world
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+)
+
+// TestCloudAdminGateFailsClosed proves the admin gate is enforced server-side:
+// every /v1/world/cloud/* admin route rejects an unauthenticated caller with a
+// 401 JSON error and leaks NONE of the aggregate payload. (A non-admin bearer is
+// rejected 403 via IAM introspection — that path is network-bound and covered by
+// the live gate; here we assert the hermetic fail-closed default.)
+func TestCloudAdminGateFailsClosed(t *testing.T) {
+	s := NewServer()
+	mux := http.NewServeMux()
+	s.Mount(mux)
+	ts := httptest.NewServer(mux)
+	t.Cleanup(ts.Close)
+
+	adminRoutes := []string{
+		"/v1/world/cloud/fleet",
+		"/v1/world/cloud/services",
+		"/v1/world/cloud/analytics",
+		"/v1/world/cloud/llm",
+	}
+	for _, route := range adminRoutes {
+		t.Run(route, func(t *testing.T) {
+			resp, err := http.Get(ts.URL + route)
+			if err != nil {
+				t.Fatalf("request failed: %v", err)
+			}
+			defer resp.Body.Close()
+			if resp.StatusCode != http.StatusUnauthorized {
+				t.Fatalf("want 401 for anon caller, got %d", resp.StatusCode)
+			}
+			if ct := resp.Header.Get("Content-Type"); !strings.Contains(ct, "application/json") {
+				t.Fatalf("want JSON error, got content-type %q", ct)
+			}
+			var body map[string]any
+			if err := json.NewDecoder(resp.Body).Decode(&body); err != nil {
+				t.Fatalf("decode: %v", err)
+			}
+			if body["error"] == nil {
+				t.Fatalf("expected an error field, got %v", body)
+			}
+			// The aggregate payload keys must NOT be present in a gated response.
+			for _, leak := range []string{"providers", "services", "topPages", "data", "workers"} {
+				if _, ok := body[leak]; ok {
+					t.Fatalf("gated response leaked %q: %v", leak, body)
+				}
+			}
+		})
+	}
+}
+
+// TestProbeServiceLivenessFallback proves a subsystem that o11y has no telemetry
+// for is reported UP (from a real liveness probe) rather than a false "down", and
+// stays uninstrumented. A subsystem o11y DOES know about keeps o11y's verdict.
+func TestProbeServiceLivenessFallback(t *testing.T) {
+	// Upstream: o11y status/metrics 404 (no telemetry); a liveness path answers 200.
+	live := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if strings.HasPrefix(r.URL.Path, "/v1/o11y/") {
+			http.Error(w, "no data", http.StatusNotFound)
+			return
+		}
+		w.WriteHeader(http.StatusOK) // liveness endpoint is alive
+	}))
+	t.Cleanup(live.Close)
+	t.Setenv("HANZO_API_BASE", live.URL) // apiHost() reads this
+
+	s := newTestServer(t)
+	row := s.probeService(context.Background(), live.URL, "kms", map[string]string{})
+	if !row.Up {
+		t.Fatalf("live-but-uninstrumented subsystem must be UP via liveness, got down (%+v)", row)
+	}
+	if row.Instrumented {
+		t.Fatalf("no o11y metrics ⇒ Instrumented must stay false, got true")
+	}
+	if row.Source != "liveness" {
+		t.Fatalf("Source should mark the liveness fallback, got %q", row.Source)
+	}
+}
+
+// TestLivenessURLCoversSubsystems proves every hardcoded cloudSubsystem has a
+// liveness probe URL, so none can silently fall through to a false "down".
+func TestLivenessURLCoversSubsystems(t *testing.T) {
+	t.Setenv("HANZO_API_BASE", "https://api.hanzo.ai")
+	for _, name := range cloudSubsystems {
+		if livenessURL(name) == "" {
+			t.Errorf("subsystem %q has no liveness URL — it can render a false 'down'", name)
+		}
+	}
+}

internal/world/handlers_cloud_map.go

@@ -0,0 +1,886 @@
+package world
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"math"
+	"net/http"
+	"net/url"
+	"sort"
+	"strconv"
+	"strings"
+	"sync"
+	"time"
+)
+
+// Public Cloud MAP data — the three globe layers the signed-out world.hanzo.ai
+// map renders: public-chain nodes, the BYO-GPU fleet, and request-traffic arcs.
+// Same contracts as the rest of the Cloud excitement layer (handlers_cloud.go /
+// handlers_cloud_public.go):
+//   - never 5xx: any upstream failure degrades to a clean 200 body,
+//   - honesty: real telemetry when reachable; anything modeled/demo carries an
+//     explicit flag (demo:true / positionsModeled:true) — never silently faked,
+//   - short-TTL in-memory cache via cachedJSON, CORS preflight + methodNotGet.
+
+// ── SSRF boundary + JSON-RPC POST helper ─────────────────────────────────────
+//
+// getJSON only does GET. The public-chain layer POSTs JSON-RPC to the L1 nodes,
+// so postJSON is the GET-twin for POST. Every destination host is re-validated
+// against an exact-host allowlist before dialing — the SSRF guard for the one
+// fetch path that reaches hosts outside the hanzo.ai family. The allowlist is
+// derived from the chain catalog so registering a network auto-allows its host
+// (one source of truth).
+var chainRPCHosts = func() map[string]bool {
+	m := map[string]bool{}
+	add := func(raw string) {
+		if raw == "" {
+			return
+		}
+		if u, err := url.Parse(raw); err == nil && u.Hostname() != "" {
+			m[u.Hostname()] = true
+		}
+	}
+	for _, cn := range chainNetworks {
+		add(cn.host)    // primary RPC / API host (and Bitcoin's height host)
+		add(cn.altHost) // failover host (e.g. rpc.hanzo.network)
+	}
+	return m
+}()
+
+// postJSON POSTs a JSON body to rawURL and decodes the 2xx JSON response into v.
+// rawURL's host MUST be in allowed (SSRF boundary). A non-2xx status is an error,
+// mirroring getJSON's "success or fail" contract.
+func (s *Server) postJSON(ctx context.Context, rawURL string, allowed map[string]bool, body, v any) error {
+	u, err := url.Parse(rawURL)
+	if err != nil {
+		return err
+	}
+	if !allowed[u.Hostname()] {
+		return fmt.Errorf("host not allowed: %s", u.Hostname())
+	}
+	buf, err := json.Marshal(body)
+	if err != nil {
+		return err
+	}
+	b, status, err := s.do(ctx, http.MethodPost, rawURL, map[string]string{"Content-Type": "application/json"}, buf)
+	if err != nil {
+		return err
+	}
+	if status < 200 || status >= 300 {
+		return fmt.Errorf("upstream status %d", status)
+	}
+	return json.Unmarshal(b, v)
+}
+
+// jsonRPCReq is the request envelope for both the info API (info.peers, params {})
+// and the C-Chain EVM (eth_*, params []). Params is `any` so each caller supplies
+// the shape the method expects.
+type jsonRPCReq struct {
+	JSONRPC string `json:"jsonrpc"`
+	ID      int    `json:"id"`
+	Method  string `json:"method"`
+	Params  any    `json:"params"`
+}
+
+// ── 1) chain-nodes: public L1 telemetry + modeled node positions ─────────────
+//
+// Real telemetry (per network, from its public API, luxfi/node):
+//   - peers:       POST /ext/info  info.peers  → result.numPeers / len(result.peers)
+//   - blockHeight: POST /ext/bc/C/rpc  eth_blockNumber (hex)
+//   - chainId:     POST /ext/bc/C/rpc  eth_chainId (hex) — verifies the catalog default
+// live:true only when eth_blockNumber actually returned a height. An unreachable
+// network keeps its catalog identity but reports zero counts + live:false — never
+// an invented height.
+//
+// nodes[] positions are MODELED: real per-node IP geolocation needs an IP-geo
+// dependency we don't carry, so the real peer COUNT is spread deterministically
+// across the regionCatalog() catalog coords. positionsModeled:true says so plainly.
+
+const maxModeledNodes = 250
+
+// perChainTimeout bounds each network's telemetry fetch so one unreachable chain
+// (e.g. an L1 whose public RPC is down) can't stall the whole chain-nodes
+// response. Live chains answer in well under a second; a dead host is dialed for
+// at most this long, then honestly reported live:false. Without it, an
+// unreachable host hangs until the request-wide deadline (~24s) and the Chains /
+// Cloud-Overview widgets sit on a loading spinner for that whole time.
+const perChainTimeout = 4 * time.Second
+
+// chainKind selects how a network's live head is read. Each kind is a distinct,
+// self-contained fetch strategy so adding a network is a data change (one catalog
+// row), never new branching at the call site.
+type chainKind int
+
+const (
+	// chainLuxNode: luxfi/node — POST /ext/info (info.peers) + /ext/bc/C/rpc
+	// (eth_blockNumber / eth_chainId). Lux, Zoo, Hanzo.
+	chainLuxNode chainKind = iota
+	// chainEVM: a public EVM JSON-RPC endpoint — POST eth_blockNumber /
+	// eth_chainId directly at host (no /ext/* path, no peer visibility). Ethereum.
+	chainEVM
+	// chainBitcoin: GET a plain-integer block-height URL (host+heightPath). Bitcoin.
+	chainBitcoin
+)
+
+type chainNet struct {
+	id, name, host string
+	chainID        int64     // catalog default; overridden by a live eth_chainId
+	kind           chainKind // how the live head is read (default chainLuxNode)
+	altHost        string    // failover host tried when host yields no height (luxnode)
+	heightPath     string    // path appended to host for a plain-integer height (bitcoin)
+}
+
+// chainNetworks is the public-chain catalog. Adding a row here also registers its
+// host(s) in chainRPCHosts (the SSRF allowlist). The first three run luxfi/node
+// (our own L1s); Ethereum and Bitcoin are public reference chains read live from
+// an exact-host-allowlisted public endpoint. An unreachable network keeps its
+// catalog identity and honestly reports live:false with zero counts — never an
+// invented height.
+var chainNetworks = []chainNet{
+	{id: "lux", name: "Lux Network", host: "https://api.lux.network", chainID: 96369, kind: chainLuxNode},
+	{id: "zoo", name: "Zoo Network", host: "https://api.zoo.network", chainID: 0, kind: chainLuxNode},
+	{id: "hanzo", name: "Hanzo Network", host: "https://api.hanzo.network", altHost: "https://rpc.hanzo.network", chainID: 0, kind: chainLuxNode},
+	{id: "ethereum", name: "Ethereum", host: "https://ethereum-rpc.publicnode.com", chainID: 1, kind: chainEVM},
+	{id: "bitcoin", name: "Bitcoin", host: "https://blockchain.info", heightPath: "/q/getblockcount", chainID: 0, kind: chainBitcoin},
+}
+
+type chainNode struct {
+	Lat  float64 `json:"lat"`
+	Lon  float64 `json:"lon"`
+	City string  `json:"city"`
+	Kind string  `json:"kind"`
+}
+
+type chainNetwork struct {
+	ID          string      `json:"id"`
+	Name        string      `json:"name"`
+	ChainID     int64       `json:"chainId"`
+	BlockHeight int64       `json:"blockHeight"`
+	Peers       int         `json:"peers"`
+	Live        bool        `json:"live"`
+	Nodes       []chainNode `json:"nodes"`
+}
+
+type chainNodes struct {
+	UpdatedAt        string         `json:"updatedAt"`
+	PositionsModeled bool           `json:"positionsModeled"`
+	Networks         []chainNetwork `json:"networks"`
+}
+
+func (s *Server) handleCloudChainNodes(w http.ResponseWriter, r *http.Request) {
+	if preflight(w, r, "GET, OPTIONS") || methodNotGet(w, r) {
+		return
+	}
+	s.cachedJSON(w, "cloud-chain-nodes", "public, max-age=15, s-maxage=15, stale-while-revalidate=60",
+		15*time.Second, 5*time.Minute,
+		func(ctx context.Context) (any, error) {
+			nets := make([]chainNetwork, len(chainNetworks))
+			var wg sync.WaitGroup
+			for i, cn := range chainNetworks {
+				wg.Add(1)
+				go func(i int, cn chainNet) {
+					defer wg.Done()
+					cctx, cancel := context.WithTimeout(ctx, perChainTimeout)
+					defer cancel()
+					nets[i] = s.fetchChainNetwork(cctx, cn)
+				}(i, cn)
+			}
+			wg.Wait()
+			return chainNodes{UpdatedAt: nowRFC(), PositionsModeled: true, Networks: nets}, nil
+		},
+		func(w http.ResponseWriter, _ error) {
+			// produce never errors; keep the never-5xx guarantee explicit.
+			writeJSON(w, http.StatusOK, "", chainNodes{UpdatedAt: nowRFC(), PositionsModeled: true, Networks: []chainNetwork{}})
+		},
+	)
+}
+
+// fetchChainNetwork gathers real telemetry for one network by its kind, degrading
+// each field independently: any failed call leaves its field at zero (and
+// live:false when the block height is unavailable). It never returns an error.
+func (s *Server) fetchChainNetwork(ctx context.Context, cn chainNet) chainNetwork {
+	switch cn.kind {
+	case chainEVM:
+		return s.fetchEVMChain(ctx, cn)
+	case chainBitcoin:
+		return s.fetchBitcoinChain(ctx, cn)
+	default:
+		return s.fetchLuxNodeChain(ctx, cn)
+	}
+}
+
+// fetchLuxNodeChain reads a luxfi/node L1 (peers + block height + chainId). It
+// tries host, then altHost if the primary yields no height, so a failover RPC
+// keeps the network live. peers feed the modeled globe layer.
+func (s *Server) fetchLuxNodeChain(ctx context.Context, cn chainNet) chainNetwork {
+	out := chainNetwork{ID: cn.id, Name: cn.name, ChainID: cn.chainID}
+	hosts := []string{cn.host}
+	if cn.altHost != "" {
+		hosts = append(hosts, cn.altHost)
+	}
+	for _, host := range hosts {
+		s.fillLuxNode(ctx, host, &out)
+		if out.Live {
+			break // got a head block from this host; no need to try the failover
+		}
+	}
+	out.Nodes = modeledNodes(out.Peers)
+	return out
+}
+
+// fillLuxNode populates peers/blockHeight/chainId from one luxfi/node host,
+// leaving any field that fails at its current value (additive across hosts).
+func (s *Server) fillLuxNode(ctx context.Context, host string, out *chainNetwork) {
+	info := host + "/ext/info"
+	rpc := host + "/ext/bc/C/rpc"
+
+	// peers (info.peers) — real count of connected peers, when the info API is exposed.
+	var pr struct {
+		Result struct {
+			NumPeers string            `json:"numPeers"`
+			Peers    []json.RawMessage `json:"peers"`
+		} `json:"result"`
+	}
+	if err := s.postJSON(ctx, info, chainRPCHosts,
+		jsonRPCReq{JSONRPC: "2.0", ID: 1, Method: "info.peers", Params: struct{}{}}, &pr); err == nil {
+		if n, e := strconv.Atoi(strings.TrimSpace(pr.Result.NumPeers)); e == nil && n >= 0 {
+			out.Peers = n
+		} else {
+			out.Peers = len(pr.Result.Peers)
+		}
+	}
+
+	// blockHeight (eth_blockNumber) — the definitive liveness signal.
+	if h, ok := s.ethBlockNumber(ctx, rpc); ok {
+		out.BlockHeight = h
+		out.Live = true
+	}
+
+	// chainId (eth_chainId) — verify / override the catalog default with the real value.
+	if id, ok := s.ethChainID(ctx, rpc); ok {
+		out.ChainID = id
+	}
+}
+
+// fetchEVMChain reads a public EVM JSON-RPC endpoint (Ethereum): eth_blockNumber
+// for the live head and eth_chainId to confirm identity. We do not peer with
+// public chains, so peers stays 0 (and the globe layer places no modeled nodes).
+func (s *Server) fetchEVMChain(ctx context.Context, cn chainNet) chainNetwork {
+	out := chainNetwork{ID: cn.id, Name: cn.name, ChainID: cn.chainID}
+	if h, ok := s.ethBlockNumber(ctx, cn.host); ok {
+		out.BlockHeight = h
+		out.Live = true
+	}
+	if id, ok := s.ethChainID(ctx, cn.host); ok {
+		out.ChainID = id
+	}
+	out.Nodes = modeledNodes(out.Peers) // peers==0 → empty (no invented positions)
+	return out
+}
+
+// fetchBitcoinChain reads Bitcoin's live block height from a plain-integer GET
+// endpoint (host+heightPath), SSRF-guarded by the same exact-host allowlist. No
+// EVM chainId and no peer visibility — height alone is the liveness signal.
+func (s *Server) fetchBitcoinChain(ctx context.Context, cn chainNet) chainNetwork {
+	out := chainNetwork{ID: cn.id, Name: cn.name, ChainID: cn.chainID}
+	txt, err := s.getAllowedText(ctx, cn.host+cn.heightPath, chainRPCHosts)
+	if err == nil {
+		if h, e := strconv.ParseInt(strings.TrimSpace(txt), 10, 64); e == nil && h > 0 {
+			out.BlockHeight = h
+			out.Live = true
+		}
+	}
+	out.Nodes = modeledNodes(out.Peers) // peers==0 → empty slice (never a null nodes array)
+	return out
+}
+
+// ethBlockNumber POSTs eth_blockNumber to an EVM RPC endpoint (SSRF-allowlisted)
+// and returns the decoded height. ok=false on any failure or a non-positive head.
+func (s *Server) ethBlockNumber(ctx context.Context, rpc string) (int64, bool) {
+	var br struct {
+		Result string `json:"result"`
+	}
+	if err := s.postJSON(ctx, rpc, chainRPCHosts,
+		jsonRPCReq{JSONRPC: "2.0", ID: 1, Method: "eth_blockNumber", Params: []any{}}, &br); err != nil {
+		return 0, false
+	}
+	if h, ok := parseHexInt(br.Result); ok && h > 0 {
+		return h, true
+	}
+	return 0, false
+}
+
+// ethChainID POSTs eth_chainId to an EVM RPC endpoint (SSRF-allowlisted) and
+// returns the decoded chain id. ok=false on any failure or a non-positive id.
+func (s *Server) ethChainID(ctx context.Context, rpc string) (int64, bool) {
+	var cr struct {
+		Result string `json:"result"`
+	}
+	if err := s.postJSON(ctx, rpc, chainRPCHosts,
+		jsonRPCReq{JSONRPC: "2.0", ID: 1, Method: "eth_chainId", Params: []any{}}, &cr); err != nil {
+		return 0, false
+	}
+	if id, ok := parseHexInt(cr.Result); ok && id > 0 {
+		return id, true
+	}
+	return 0, false
+}
+
+// getAllowedText GETs a plain-text body from an exact-host-allowlisted URL — the
+// GET twin of postJSON's SSRF boundary, for the one non-JSON public source
+// (Bitcoin's integer height). rawURL's host MUST be in allowed before dialing.
+func (s *Server) getAllowedText(ctx context.Context, rawURL string, allowed map[string]bool) (string, error) {
+	u, err := url.Parse(rawURL)
+	if err != nil {
+		return "", err
+	}
+	if !allowed[u.Hostname()] {
+		return "", fmt.Errorf("host not allowed: %s", u.Hostname())
+	}
+	return s.getText(ctx, rawURL, map[string]string{"Accept": "text/plain, */*"})
+}
+
+// getAllowedJSON GETs and decodes a JSON body from an exact-host-allowlisted URL
+// — the GET-JSON twin of postJSON's SSRF boundary. Used by the status-page proxy,
+// whose upstream host is operator-configured (env). rawURL's host MUST be in
+// allowed before dialing.
+func (s *Server) getAllowedJSON(ctx context.Context, rawURL string, allowed map[string]bool, v any) error {
+	u, err := url.Parse(rawURL)
+	if err != nil {
+		return err
+	}
+	if !allowed[u.Hostname()] {
+		return fmt.Errorf("host not allowed: %s", u.Hostname())
+	}
+	return s.getJSON(ctx, rawURL, nil, v)
+}
+
+// modeledNodes spreads a real peer COUNT across the region catalog deterministically
+// (proportional to each region's relative capacity, remainder round-robin). Positions
+// and kind are modeled — hence positionsModeled:true on the envelope; only the count
+// is real. Bounded to maxModeledNodes so a pathological peer count can't bloat the payload.
+func modeledNodes(peers int) []chainNode {
+	regions := regionCatalog()
+	nodes := make([]chainNode, 0)
+	if peers <= 0 || len(regions) == 0 {
+		return nodes
+	}
+	if peers > maxModeledNodes {
+		peers = maxModeledNodes
+	}
+	total := 0
+	for _, rg := range regions {
+		total += rg.Nodes
+	}
+	if total <= 0 {
+		total = len(regions)
+	}
+	for _, rg := range regions {
+		for j := 0; j < peers*rg.Nodes/total; j++ {
+			nodes = append(nodes, chainNode{Lat: rg.Lat, Lon: rg.Lon, City: rg.City, Kind: "validator"})
+		}
+	}
+	for i := len(nodes); i < peers; i++ {
+		rg := regions[i%len(regions)]
+		nodes = append(nodes, chainNode{Lat: rg.Lat, Lon: rg.Lon, City: rg.City, Kind: "validator"})
+	}
+	return nodes
+}
+
+// parseHexInt parses a 0x-prefixed hex string (eth_* result) into an int64.
+func parseHexInt(s string) (int64, bool) {
+	s = strings.TrimSpace(s)
+	s = strings.TrimPrefix(s, "0x")
+	s = strings.TrimPrefix(s, "0X")
+	if s == "" {
+		return 0, false
+	}
+	n, err := strconv.ParseInt(s, 16, 64)
+	if err != nil {
+		return 0, false
+	}
+	return n, true
+}
+
+// ── 2) byo-gpu: the GPU fleet placed on the globe ────────────────────────────
+//
+// Real path (service token, mirroring tryServicePulse): read the non-sensitive GPU
+// inventory from api /v1/gpus (+ /v1/machines fallback), aggregate by region+model+
+// status, and place each cluster with the region catalog's coords → demo:false.
+// Without a token we return a small, clearly-flagged demo set (demo:true) built
+// from the same catalog.
+
+type gpuCluster struct {
+	Lat    float64 `json:"lat"`
+	Lon    float64 `json:"lon"`
+	City   string  `json:"city"`
+	Region string  `json:"region"`
+	Model  string  `json:"model"`
+	Count  int     `json:"count"`
+	Status string  `json:"status"`
+}
+
+type byoGPU struct {
+	UpdatedAt string       `json:"updatedAt"`
+	Demo      bool         `json:"demo"`
+	GPUs      []gpuCluster `json:"gpus"`
+}
+
+func (s *Server) handleCloudBYOGPU(w http.ResponseWriter, r *http.Request) {
+	if preflight(w, r, "GET, OPTIONS") || methodNotGet(w, r) {
+		return
+	}
+	w.Header().Set("Vary", "Authorization")
+	// Signed-in admin (z@hanzo.ai / the operator org): the REAL GPU fleet placed on
+	// the globe, read with the caller's OWN bearer, never edge-cached. No fabricated
+	// demo clusters for a signed-in operator — an empty read shows an empty globe.
+	if bearer, ok := s.adminIdentity(r); ok {
+		ctx, cancel := context.WithTimeout(r.Context(), 20*time.Second)
+		defer cancel()
+		clusters, _ := s.tryRealGPUs(ctx, map[string]string{"Authorization": bearer})
+		if clusters == nil {
+			clusters = []gpuCluster{}
+		}
+		writeJSON(w, http.StatusOK, "private, no-store", byoGPU{UpdatedAt: nowRFC(), Demo: false, GPUs: clusters})
+		return
+	}
+	s.cachedJSON(w, "cloud-byo-gpu", "public, max-age=30, s-maxage=30, stale-while-revalidate=120",
+		30*time.Second, 5*time.Minute,
+		func(ctx context.Context) (any, error) {
+			if clusters, ok := s.tryRealGPUs(ctx, serviceAuth()); ok {
+				return byoGPU{UpdatedAt: nowRFC(), Demo: false, GPUs: clusters}, nil
+			}
+			// No service token → honest empty (no fabricated clusters). Real GPUs show
+			// for a signed-in admin (above) or when the service token is wired.
+			return byoGPU{UpdatedAt: nowRFC(), Demo: false, GPUs: []gpuCluster{}}, nil
+		},
+		func(w http.ResponseWriter, _ error) {
+			writeJSON(w, http.StatusOK, "", byoGPU{UpdatedAt: nowRFC(), Demo: false, GPUs: []gpuCluster{}})
+		},
+	)
+}
+
+// tryRealGPUs reads the real GPU inventory using the supplied auth header (the KMS
+// service bearer on the public path, or the caller's own admin bearer). Returns
+// ok=false when auth is absent, both sources fail, or no GPU maps to a known region.
+// Only non-sensitive fields (region/model/status) are read.
+func (s *Server) tryRealGPUs(ctx context.Context, hdr map[string]string) ([]gpuCluster, bool) {
+	if hdr == nil {
+		return nil, false
+	}
+	base := apiHost()
+
+	agg := map[string]*gpuCluster{}
+	var order []string
+	add := func(region, model, status string) {
+		rg, ok := resolveRegion(region)
+		if !ok {
+			return // don't fake coords for an unmappable region
+		}
+		if strings.TrimSpace(model) == "" {
+			model = "GPU"
+		}
+		if machineOnline(status) {
+			status = "online"
+		} else if strings.TrimSpace(status) == "" {
+			status = "offline"
+		}
+		key := rg.ID + "|" + model + "|" + status
+		c := agg[key]
+		if c == nil {
+			c = &gpuCluster{Lat: rg.Lat, Lon: rg.Lon, City: rg.City, Region: rg.ID, Model: model, Status: status}
+			agg[key] = c
+			order = append(order, key)
+		}
+		c.Count++
+	}
+
+	// Primary: /v1/gpus — one row per GPU (region, model, status), as handleCloudFleet reads.
+	var gpus struct {
+		Gpus []struct {
+			Model  string `json:"model"`
+			Region string `json:"region"`
+			Status string `json:"status"`
+		} `json:"gpus"`
+	}
+	_ = s.getJSON(ctx, base+"/v1/gpus", hdr, &gpus)
+	for _, g := range gpus.Gpus {
+		add(g.Region, g.Model, g.Status)
+	}
+
+	// Fallback: /v1/machines — BYO machines that report a GPU model but aren't in the pool.
+	if len(order) == 0 {
+		var machines struct {
+			Machines []struct {
+				Region string `json:"region"`
+				Status string `json:"status"`
+				GPU    string `json:"gpu"`
+			} `json:"machines"`
+		}
+		if err := s.getJSON(ctx, base+"/v1/machines", hdr, &machines); err == nil {
+			for _, m := range machines.Machines {
+				if strings.TrimSpace(m.GPU) != "" {
+					add(m.Region, m.GPU, m.Status)
+				}
+			}
+		}
+	}
+
+	if len(order) == 0 {
+		return nil, false
+	}
+	out := make([]gpuCluster, 0, len(order))
+	for _, k := range order {
+		out = append(out, *agg[k])
+	}
+	sort.SliceStable(out, func(i, j int) bool { return out[i].Count > out[j].Count })
+	return out, true
+}
+
+// ── 3) traffic: request arcs from visitor countries to the nearest region ────
+//
+// Real path (service token): read the visitor-COUNTRY breakdown from the same
+// analytics source handleCloudAnalytics uses (analytics.hanzo.ai), arc each country
+// centroid to the nearest catalog region, weight normalized 0..1 → demo:false.
+// Only country counts are read — non-sensitive. If the source is admin-gated,
+// tokenless, or unreachable, we fall back to the diurnal demo arcs (demo:true).
+
+type trafficArc struct {
+	FromLat float64 `json:"fromLat"`
+	FromLon float64 `json:"fromLon"`
+	ToLat   float64 `json:"toLat"`
+	ToLon   float64 `json:"toLon"`
+	Weight  float64 `json:"weight"`
+	Label   string  `json:"label"`
+}
+
+type cloudTraffic struct {
+	UpdatedAt string       `json:"updatedAt"`
+	Demo      bool         `json:"demo"`
+	Arcs      []trafficArc `json:"arcs"`
+}
+
+func (s *Server) handleCloudTraffic(w http.ResponseWriter, r *http.Request) {
+	if preflight(w, r, "GET, OPTIONS") || methodNotGet(w, r) {
+		return
+	}
+	s.cachedJSON(w, "cloud-traffic", "public, max-age=20, s-maxage=20, stale-while-revalidate=90",
+		20*time.Second, 5*time.Minute,
+		func(ctx context.Context) (any, error) {
+			if arcs, ok := s.tryRealTraffic(ctx); ok {
+				return cloudTraffic{UpdatedAt: nowRFC(), Demo: false, Arcs: arcs}, nil
+			}
+			// Honest empty — no fabricated arcs. The native request-geo globe
+			// (traffic-globe) carries the real traffic layer; arcs fill from real
+			// visitor geo when analytics is wired.
+			return cloudTraffic{UpdatedAt: nowRFC(), Demo: false, Arcs: []trafficArc{}}, nil
+		},
+		func(w http.ResponseWriter, _ error) {
+			writeJSON(w, http.StatusOK, "", cloudTraffic{UpdatedAt: nowRFC(), Demo: false, Arcs: []trafficArc{}})
+		},
+	)
+}
+
+// ── native request-geo globe (points + throughput) ───────────────────────────
+//
+// The Hanzo-mode globe plots WHERE api.hanzo.ai traffic comes from, from the ai
+// backend's OWN in-process aggregate (GET /v1/traffic/globe — public, aggregates
+// only, no IPs). This same-origin proxy passes those points + totals through, and
+// degrades to an HONEST EMPTY state (no points, zero rates) — never demo — because
+// "no traffic recorded yet" is a real answer the UI should show truthfully.
+
+type trafficGlobePoint struct {
+	Country   string         `json:"country"`
+	Region    string         `json:"region,omitempty"`
+	Lat       float64        `json:"lat"`
+	Lon       float64        `json:"lon"`
+	Count     int            `json:"count"`
+	ByService map[string]int `json:"byService"`
+}
+
+type trafficGlobeCountry struct {
+	Country string `json:"country"`
+	Count   int    `json:"count"`
+}
+
+type trafficGlobeTotals struct {
+	RPS1m        float64               `json:"rps_1m"`
+	RPM60m       float64               `json:"rpm_60m"`
+	TopCountries []trafficGlobeCountry `json:"top_countries"`
+}
+
+type trafficGlobeWindow struct {
+	Minutes int    `json:"minutes"`
+	Since   string `json:"since"`
+	Until   string `json:"until"`
+}
+
+type trafficGlobe struct {
+	UpdatedAt string              `json:"updatedAt"`
+	Live      bool                `json:"live"` // reached the native endpoint (even if 0 points)
+	Window    trafficGlobeWindow  `json:"window"`
+	Points    []trafficGlobePoint `json:"points"`
+	Totals    trafficGlobeTotals  `json:"totals"`
+}
+
+// emptyGlobe is the honest zero payload: reachable-but-no-data and unreachable both
+// render as an empty globe with zero throughput — we never fabricate traffic.
+func emptyGlobe() trafficGlobe {
+	return trafficGlobe{
+		UpdatedAt: nowRFC(),
+		Live:      false,
+		Window:    trafficGlobeWindow{Minutes: 60},
+		Points:    []trafficGlobePoint{},
+		Totals:    trafficGlobeTotals{TopCountries: []trafficGlobeCountry{}},
+	}
+}
+
+// fetchNativeGlobe reads the ai backend's public /v1/traffic/globe (no token) and
+// unwraps the {status,data} envelope. ok=false when the endpoint is unreachable.
+func (s *Server) fetchNativeGlobe(ctx context.Context, windowMin int) (trafficGlobe, bool) {
+	url := apiHost() + "/v1/traffic/globe?window=" + strconv.Itoa(windowMin)
+	var envlp struct {
+		Data struct {
+			Window trafficGlobeWindow  `json:"window"`
+			Points []trafficGlobePoint `json:"points"`
+			Totals trafficGlobeTotals  `json:"totals"`
+		} `json:"data"`
+	}
+	if err := s.getJSON(ctx, url, nil, &envlp); err != nil {
+		return trafficGlobe{}, false
+	}
+	g := trafficGlobe{
+		UpdatedAt: nowRFC(),
+		Live:      true,
+		Window:    envlp.Data.Window,
+		Points:    envlp.Data.Points,
+		Totals:    envlp.Data.Totals,
+	}
+	if g.Points == nil {
+		g.Points = []trafficGlobePoint{}
+	}
+	if g.Totals.TopCountries == nil {
+		g.Totals.TopCountries = []trafficGlobeCountry{}
+	}
+	return g, true
+}
+
+// handleCloudTrafficGlobe serves the native request-geo aggregate. It never 5xxes:
+// an unreachable backend degrades to the honest empty globe.
+func (s *Server) handleCloudTrafficGlobe(w http.ResponseWriter, r *http.Request) {
+	if preflight(w, r, "GET, OPTIONS") || methodNotGet(w, r) {
+		return
+	}
+	s.cachedJSON(w, "cloud-traffic-globe", "public, max-age=10, s-maxage=10, stale-while-revalidate=45",
+		12*time.Second, 2*time.Minute,
+		func(ctx context.Context) (any, error) {
+			if g, ok := s.fetchNativeGlobe(ctx, 60); ok {
+				return g, nil
+			}
+			return emptyGlobe(), nil
+		},
+		func(w http.ResponseWriter, _ error) {
+			writeJSON(w, http.StatusOK, "", emptyGlobe())
+		},
+	)
+}
+
+// arcsFromGlobe turns native request-geo points into origin→nearest-region arcs, so
+// the animated arc layer and the points layer share ONE source (native LB geo).
+func arcsFromGlobe(g trafficGlobe) []trafficArc {
+	maxC := 1
+	for _, p := range g.Points {
+		if p.Count > maxC {
+			maxC = p.Count
+		}
+	}
+	arcs := make([]trafficArc, 0, len(g.Points))
+	for _, p := range g.Points {
+		rg := nearestRegion(p.Lat, p.Lon)
+		label := p.Country
+		if p.Region != "" {
+			label += "-" + p.Region
+		}
+		arcs = append(arcs, trafficArc{
+			FromLat: p.Lat, FromLon: p.Lon, ToLat: rg.Lat, ToLon: rg.Lon,
+			Weight: round2s(clampF(float64(p.Count)/float64(maxC), 0.05, 1)),
+			Label:  label + " → " + rg.ID,
+		})
+	}
+	sort.SliceStable(arcs, func(i, j int) bool { return arcs[i].Weight > arcs[j].Weight })
+	if len(arcs) > 20 {
+		arcs = arcs[:20]
+	}
+	return arcs
+}
+
+// tryRealTraffic builds arcs from the real visitor-country breakdown. ok=false (→
+// demo) when tokenless, unreachable, or no country data. Reuses mergeMetric so the
+// analytics fan-out lives in exactly one place.
+func (s *Server) tryRealTraffic(ctx context.Context) ([]trafficArc, bool) {
+	// Native LB request-geo first (public, no token): arcs from the real
+	// /v1/traffic/globe points → nearest region — one source of truth with the
+	// traffic-globe layer. The analytics fallback below runs only when the native
+	// aggregate is empty (e.g. no traffic yet, or the ai release hasn't landed).
+	if g, ok := s.fetchNativeGlobe(ctx, 60); ok && len(g.Points) > 0 {
+		return arcsFromGlobe(g), true
+	}
+	tok := serviceToken()
+	if tok == "" {
+		return nil, false
+	}
+	base := env("HANZO_ANALYTICS_BASE")
+	if base == "" {
+		base = "https://analytics.hanzo.ai"
+	}
+	base = trimSlash(base)
+	hdr := map[string]string{"Authorization": "Bearer " + tok}
+
+	var sites struct {
+		Data []struct {
+			ID string `json:"id"`
+		} `json:"data"`
+	}
+	if err := s.getJSON(ctx, base+"/v1/analytics/websites", hdr, &sites); err != nil || len(sites.Data) == 0 {
+		return nil, false
+	}
+	end := time.Now()
+	start := end.Add(-24 * time.Hour)
+	q := "startAt=" + strconv.FormatInt(start.UnixMilli(), 10) + "&endAt=" + strconv.FormatInt(end.UnixMilli(), 10)
+
+	countries := map[string]int64{}
+	var mu sync.Mutex
+	limit := len(sites.Data)
+	if limit > 8 {
+		limit = 8
+	}
+	for _, ws := range sites.Data[:limit] {
+		mergeMetric(ctx, s, base, ws.ID, "country", q, hdr, countries, &mu)
+	}
+	if len(countries) == 0 {
+		return nil, false
+	}
+
+	var maxCount int64 = 1
+	for _, v := range countries {
+		if v > maxCount {
+			maxCount = v
+		}
+	}
+	arcs := make([]trafficArc, 0, len(countries))
+	for code, v := range countries {
+		lat, lon, ok := centroidFor(code)
+		if !ok {
+			continue
+		}
+		rg := nearestRegion(lat, lon)
+		arcs = append(arcs, trafficArc{
+			FromLat: lat, FromLon: lon, ToLat: rg.Lat, ToLon: rg.Lon,
+			Weight: round2s(clampF(float64(v)/float64(maxCount), 0, 1)),
+			Label:  strings.ToUpper(code) + " → " + rg.ID,
+		})
+	}
+	if len(arcs) == 0 {
+		return nil, false
+	}
+	sort.SliceStable(arcs, func(i, j int) bool { return arcs[i].Weight > arcs[j].Weight })
+	if len(arcs) > 20 {
+		arcs = arcs[:20]
+	}
+	return arcs, true
+}
+
+// countryCentroids is the small in-file centroid table (ISO 3166-1 alpha-2 → point)
+// with a relative traffic base weight, used by both the real and demo traffic paths.
+var countryCentroids = []struct {
+	code     string
+	lat, lon float64
+	weight   float64
+}{
+	{"US", 39.50, -98.35, 0.95},
+	{"IN", 22.00, 79.00, 0.70},
+	{"JP", 36.20, 138.25, 0.60},
+	{"DE", 51.16, 10.45, 0.62},
+	{"GB", 54.00, -2.00, 0.58},
+	{"SG", 1.35, 103.82, 0.55},
+	{"CA", 56.13, -106.35, 0.50},
+	{"FR", 46.60, 2.20, 0.50},
+	{"KR", 36.50, 127.85, 0.48},
+	{"BR", -10.00, -53.00, 0.45},
+	{"NL", 52.13, 5.29, 0.42},
+	{"MX", 23.63, -102.55, 0.40},
+	{"AU", -25.00, 133.00, 0.40},
+	{"ES", 40.00, -4.00, 0.40},
+	{"AE", 23.42, 53.85, 0.38},
+	{"IL", 31.05, 34.85, 0.34},
+	{"SE", 62.20, 17.60, 0.32},
+	{"ZA", -29.00, 24.00, 0.30},
+	{"UA", 48.38, 31.17, 0.30},
+	{"NG", 9.08, 8.68, 0.28},
+}
+
+func centroidFor(code string) (float64, float64, bool) {
+	code = strings.ToUpper(strings.TrimSpace(code))
+	for _, c := range countryCentroids {
+		if c.code == code {
+			return c.lat, c.lon, true
+		}
+	}
+	return 0, 0, false
+}
+
+// ── shared geo / math helpers ────────────────────────────────────────────────
+
+// regionCoords indexes the region catalog by its ID for O(1) coord lookup.
+func regionCoords() map[string]cloudRegion {
+	m := make(map[string]cloudRegion, 8)
+	for _, rg := range regionCatalog() {
+		m[rg.ID] = rg
+	}
+	return m
+}
+
+// resolveRegion maps an upstream region string ("nyc", "nyc3", "sfo1", …) to a
+// catalog region by exact ID then prefix. Returns ok=false when it can't be placed
+// (so we never invent coordinates).
+func resolveRegion(region string) (cloudRegion, bool) {
+	region = strings.ToLower(strings.TrimSpace(region))
+	if region == "" {
+		return cloudRegion{}, false
+	}
+	m := regionCoords()
+	if rg, ok := m[region]; ok {
+		return rg, true
+	}
+	for _, rg := range regionCatalog() { // ordered: match the highest-capacity region first
+		if strings.HasPrefix(region, rg.ID) {
+			return rg, true
+		}
+	}
+	return cloudRegion{}, false
+}
+
+// nearestRegion returns the catalog region closest to (lat, lon) by great-circle
+// distance. The catalog is non-empty (regionCatalog), so the first is a safe seed.
+func nearestRegion(lat, lon float64) cloudRegion {
+	regions := regionCatalog()
+	best := regions[0]
+	bestD := math.Inf(1)
+	for _, rg := range regions {
+		if d := haversineKm(lat, lon, rg.Lat, rg.Lon); d < bestD {
+			bestD, best = d, rg
+		}
+	}
+	return best
+}
+
+func haversineKm(lat1, lon1, lat2, lon2 float64) float64 {
+	const r = 6371.0
+	const rad = math.Pi / 180
+	dLat := (lat2 - lat1) * rad
+	dLon := (lon2 - lon1) * rad
+	a := math.Sin(dLat/2)*math.Sin(dLat/2) +
+		math.Cos(lat1*rad)*math.Cos(lat2*rad)*math.Sin(dLon/2)*math.Sin(dLon/2)
+	return 2 * r * math.Asin(math.Min(1, math.Sqrt(a)))
+}

internal/world/handlers_cloud_map_test.go

@@ -0,0 +1,151 @@
+package world
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+)
+
+// TestChainNodesCatalog exercises /v1/world/cloud/chain-nodes against the real
+// public sources (network). The honesty contract: every catalog network appears,
+// a network is live:true only when a real head block was read, and the response
+// never 5xxes. Ethereum + Bitcoin are public reference chains with real, large
+// heights; the luxfi/node L1s (lux/zoo/hanzo) may be live:false in CI.
+func TestChainNodesCatalog(t *testing.T) {
+	s := NewServer()
+	mux := http.NewServeMux()
+	s.Mount(mux)
+	ts := httptest.NewServer(mux)
+	t.Cleanup(ts.Close)
+
+	resp, err := http.Get(ts.URL + "/v1/world/cloud/chain-nodes")
+	if err != nil {
+		t.Fatalf("request failed: %v", err)
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("want 200, got %d", resp.StatusCode)
+	}
+
+	var cn chainNodes
+	if err := json.NewDecoder(resp.Body).Decode(&cn); err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+	if len(cn.Networks) != len(chainNetworks) {
+		t.Fatalf("want %d networks, got %d", len(chainNetworks), len(cn.Networks))
+	}
+
+	byID := map[string]chainNetwork{}
+	for _, n := range cn.Networks {
+		byID[n.ID] = n
+		// A live network must carry a real, positive head block; a down one must
+		// not invent a height. This is the core "never fake a number" invariant.
+		if n.Live && n.BlockHeight <= 0 {
+			t.Fatalf("%s live:true but blockHeight=%d", n.ID, n.BlockHeight)
+		}
+		if !n.Live && n.BlockHeight != 0 {
+			t.Fatalf("%s live:false but blockHeight=%d (must be zero)", n.ID, n.BlockHeight)
+		}
+	}
+	for _, want := range []string{"lux", "zoo", "hanzo", "ethereum", "bitcoin"} {
+		if _, ok := byID[want]; !ok {
+			t.Fatalf("catalog missing network %q", want)
+		}
+	}
+	// Ethereum reports chainId 1 when live (catalog default, confirmed by eth_chainId).
+	if eth := byID["ethereum"]; eth.Live && eth.ChainID != 1 {
+		t.Fatalf("ethereum live but chainId=%d, want 1", eth.ChainID)
+	}
+
+	pretty, _ := json.MarshalIndent(cn, "", "  ")
+	t.Logf("chain-nodes:\n%s", pretty)
+}
+
+// TestChainRPCAllowlist verifies the SSRF allowlist is derived from the catalog,
+// including failover and non-JSON (Bitcoin) hosts — so a registered network is
+// auto-allowed and nothing else is.
+func TestChainRPCAllowlist(t *testing.T) {
+	for _, host := range []string{
+		"api.lux.network", "api.zoo.network", "api.hanzo.network", "rpc.hanzo.network",
+		"ethereum-rpc.publicnode.com", "blockchain.info",
+	} {
+		if !chainRPCHosts[host] {
+			t.Fatalf("expected %q in the RPC allowlist", host)
+		}
+	}
+	if chainRPCHosts["evil.example.com"] {
+		t.Fatalf("unexpected host allowed")
+	}
+}
+
+// TestParseHexInt covers the eth_* hex decoder used by the EVM/luxnode paths.
+func TestParseHexInt(t *testing.T) {
+	cases := []struct {
+		in   string
+		want int64
+		ok   bool
+	}{
+		{"0x18518fe", 25499902, true},
+		{"0x1", 1, true},
+		{"0X10", 16, true},
+		{"", 0, false},
+		{"0x", 0, false},
+		{"nothex", 0, false},
+	}
+	for _, c := range cases {
+		got, ok := parseHexInt(c.in)
+		if ok != c.ok || (ok && got != c.want) {
+			t.Fatalf("parseHexInt(%q)=(%d,%v) want (%d,%v)", c.in, got, ok, c.want, c.ok)
+		}
+	}
+}
+
+// TestBYOGPUAdminReal proves the globe's GPU layer is REAL (not demo) for a
+// signed-in admin: the caller's own bearer reads /v1/gpus, clusters carry demo:false
+// and the response is no-store (never the shared public/demo cache).
+func TestBYOGPUAdminReal(t *testing.T) {
+	iam := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/v1/iam/oauth/userinfo" || r.Header.Get("Authorization") == "" {
+			http.NotFound(w, r)
+			return
+		}
+		_, _ = w.Write([]byte(`{"owner":"hanzo","sub":"z@hanzo.ai"}`))
+	}))
+	t.Cleanup(iam.Close)
+
+	api := http.NewServeMux()
+	api.HandleFunc("/v1/gpus", func(w http.ResponseWriter, r *http.Request) {
+		if r.Header.Get("Authorization") != "Bearer admin-token" {
+			t.Errorf("GPU inventory must be read with the caller's bearer, got %q", r.Header.Get("Authorization"))
+		}
+		_, _ = w.Write([]byte(`{"gpus":[{"model":"GB10","region":"nyc","status":"online"},{"model":"H100","region":"sfo","status":"online"}]}`))
+	})
+	up := httptest.NewServer(api)
+	t.Cleanup(up.Close)
+
+	t.Setenv("HANZO_CLOUD_PULSE_TOKEN", "") // no service token — the admin's bearer drives it
+	t.Setenv("HANZO_API_BASE", up.URL)
+	t.Setenv("HANZO_IAM_ISSUER", iam.URL)
+
+	req, _ := http.NewRequest(http.MethodGet, serveWorld(t)+"/v1/world/cloud/byo-gpu", nil)
+	req.Header.Set("Authorization", "Bearer admin-token")
+	resp, err := http.DefaultClient.Do(req)
+	if err != nil {
+		t.Fatalf("request failed: %v", err)
+	}
+	defer resp.Body.Close()
+	if cc := resp.Header.Get("Cache-Control"); cc != "private, no-store" {
+		t.Fatalf("admin GPU layer must be no-store, got %q", cc)
+	}
+	var g byoGPU
+	if err := json.NewDecoder(resp.Body).Decode(&g); err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+	if g.Demo {
+		t.Fatalf("signed-in admin must get real GPUs, not demo")
+	}
+	if len(g.GPUs) != 2 {
+		t.Fatalf("want 2 real GPU clusters (nyc GB10 + sfo H100), got %d: %+v", len(g.GPUs), g.GPUs)
+	}
+}