# Daniel Herrington — Complete Knowledge Corpus (llms-full.txt) > Generated on 2026-10-15 12:47:35Z > Full unedited compilation of research papers, architectural frameworks, and technical essays. --- # Daniel Herrington — Chief AI Officer & Systems Architect > Personal portfolio, research publications, systems engineering architectures, and technical writings of Daniel Herrington. Chief AI Officer at The Zebra and former Senior Product Manager for CoreML Infrastructure & Gemini model serving at Google. > Complete unedited markdown text of all essays, publications, and systems case studies is available at [https://herrington.ai/llms-full.txt](https://herrington.ai/llms-full.txt). > External AI agents can also interact with the site via our public Streamable HTTP Model Context Protocol (MCP) server at [https://herrington.ai/mcp](https://herrington.ai/mcp). ## Executive Profile - **Name**: Daniel Herrington - **Current Role**: Chief AI Officer (CAIO) at The Zebra ([thezebra.com](https://thezebra.com)) - **Previous Role**: Senior Product PM at Google (CoreML & AI Infrastructure, TPU cluster optimization, Gemini model serving, ML Productivity Goodput metric) - **Earlier Roles**: Product & Engineering leadership at Vroom, Capital One, and Priceline - **Education**: B.S. in Electrical Engineering from Mississippi State University (focus on signals, control systems, and compute frameworks) - **Location**: Miami, Florida, United States - **Canonical Domain**: [https://herrington.ai](https://herrington.ai) - **Verified Profiles**: [LinkedIn](https://www.linkedin.com/in/danieljherrington/), [GitHub](https://github.com/danielherrington), [X / Twitter](https://twitter.com/dherrington) ## Core Areas of Expertise - **Large-Scale ML Infrastructure**: TPU & GPU fleet optimization, multi-slice training stability, resilient checkpointing pipelines, and high-density inference serving. - **ML Productivity Goodput**: Co-designer of the Goodput metric measuring useful non-overlapped computation in warehouse-scale ML training; author of the open-source Google AI-Hypercomputer Goodput library. - **Agentic Architectures**: State machines, boundary enforcement, transactional safety, deterministic evaluation harnesses, and Model Context Protocol (MCP) servers. - **Enterprise AI Strategy & Governance**: Practical deployment of LLMs and generative systems in highly regulated domains (Insurtech, FinTech) with verifiable audit trails, PII scrubbing, and cost-efficient fine-tuning. ## Research & Systems Engineering - [Beyond Peak TFLOPs: Why Communication-Compute Overlap Dictates ML Productivity Goodput](https://herrington.ai/research/beyond-peak-tflops/): A systems-engineering analysis responding to Cursor's Mixture-of-Kittens (MoK) paper. Analyzes how unified megakernels, pull-based dispatch, and hardware co-design redefine MoE training goodput across NVIDIA Blackwell and Google TPU architectures. - [ML Productivity Goodput in LLM Training (arXiv:2502.06982)](https://arxiv.org/abs/2502.06982): Google research paper defining cluster efficiency metrics, downtime attribution, and training goodput for massive AI models. - [Measuring ML Productivity with Goodput (Google Cloud Blog)](https://cloud.google.com/blog/products/ai-platform/goodput-metric-as-measure-of-ml-productivity): Production architectural overview of tracking training productivity across TPU v4/v5e pods. - [AI-Hypercomputer Goodput Measurement Library](https://github.com/GoogleCloudPlatform/ai-hypercomputer): Open-source implementation co-authored by Daniel within Google Cloud Platform. ## Flagship Personal Projects & Open Source - [KnowMe MCP: LinkedIn for Agents to Learn About Humans](https://herrington.ai/cujs/knowme-mcp-agent-interviewer/): LinkedIn is for humans to learn about humans; KnowMe is for AI agents to learn about humans. Combines a recurring Wispr Flow voice-dictation AI Interviewer with a public Model Context Protocol (MCP) front door and an Agent Missed-Call Queue so external agents can query your unwritten human context or queue questions for your next interview. - [Remote MCP Server & AI Agent Gateway: Programmatic Knowledge Interface](https://herrington.ai/cujs/remote-mcp-server-agent-gateway/): An open, public Model Context Protocol (MCP) server running in stateless Streamable HTTP mode on Cloud Run and Firebase Hosting CDN. Exposes herrington.ai's entire technical corpus, ML Goodput research papers, project case studies, and the Gemini-powered dh.sh persona as machine-callable tools for external autonomous AI agents (Muse, Instinct, Cursor, Claude Code). - [Kids Country Poster Kit: School Culture Display Builder](https://herrington.ai/cujs/kindergarten-culture-poster/): An interactive, kid-friendly web tool and learning studio built with my daughter Izzy to research, customize, and print high-quality school culture display projects (standard flat 22″ × 28″ poster boards) on home 8.5″ × 11″ paper with 100% black-and-white coloring line art, 9-category curriculum calibration, and voice speech coaching. - [American Detail Cleaning: Commercial Facility Modernization](https://herrington.ai/projects/american-detail-cleaning/): Full-stack modernization of a 35+ year premier commercial facility care and architectural surface restoration corporation in Washington D.C., transforming an aging, bloated WordPress setup into a high-speed, SEO-optimized, lead-converting static web platform. - [Danboard: Fire TV Smart Display & Calendar](https://herrington.ai/projects/danboard/): An open-source, zero-subscription smart display and family calendar dashboard engineered specifically for Amazon Fire TV and web browsers. Runs 100% standalone on device hardware with direct Google Calendar iCal sync, client-side RRULE recurrence expansion, live Open-Meteo weather, and 4K rotating landscape photography. - [Dojo Zen: Autonomous School Intelligence](https://herrington.ai/cujs/dojo-zen-school-intelligence/): An autonomous AI agent and anti-bloat triage pipeline replacing gamified EdTech mobile apps with direct school feed ingestion, high-severity emergency alerts, and a shared daily family briefing. - [Izzyland ✨ The Candyland Adventure](https://herrington.ai/cujs/izzyland-generative-game/): A whimsical poolside-crafted generative board game built with my daughter Izzy. Features 64 candy tiles, regional chocolate collecting across world landmarks, Gemini-generated video cutscenes, and an interactive unicorn piñata finale. - [In-Browser RAG & Model Context Protocol (MCP) Engine](https://herrington.ai/cujs/in-browser-rag-engine/): A serverless, zero-cloud-cost client-side RAG engine and Model Context Protocol (MCP) server indexing 50+ essays, podcast transcripts, and software architectures directly inside dh.sh and local Claude Desktop environments in sub-10ms. - [Family Schedule Helper](https://herrington.ai/cujs/google-calendar-schedule-helper/): A mobile-first dispatch app for multi-caregiver families to reassign, swap, and sync school drop-offs and pick-ups across shared Google Calendars without recurrence corruption. - [CUJ Engineering Framework](https://herrington.ai/cujs/): A product-driven development philosophy and case study hub centered on Critical User Journeys (CUJs) to surgically eliminate user friction before writing code. - [Local Meeting Scribe](https://herrington.ai/cujs/local-meeting-scribe/): Air-gapped, asynchronous meeting transcription and acoustic sentiment intelligence with persistent speaker voiceprints on Apple Silicon — zero cloud token costs. --- # Research Papers & Systems Reports ## Beyond Peak TFLOPs: Why Communication-Compute Overlap Dictates ML Productivity Goodput - **URL**: https://herrington.ai/research/beyond-peak-tflops/ - **Date**: 2026-09-12 - **Summary**: A systems-engineering analysis responding to Cursor's Mixture-of-Kittens (MoK) paper. Analyzes how unified megakernels, pull-based dispatch, and hardware co-design redefine MoE training goodput across NVIDIA Blackwell and Google TPU architectures. # Beyond Peak TFLOPs: Why Communication-Compute Overlap Dictates ML Productivity Goodput *A systems-engineering follow-up on how unified megakernels, directional networking, and hardware co-design redefine real-world training efficiency across Blackwell and TPU architectures.* --- In distributed machine learning, peak theoretical TFLOPs is often a vanity metric. What determines the pace, cost, and feasibility of frontier model pretraining is **productivity goodput**: the sustained rate of mathematically valid, bitwise-reproducible tokens processed per second per dollar of infrastructure. As model architectures shift from dense transformers to sparse Mixture-of-Experts (MoE), calculating goodput becomes less about raw matrix math and more about managing distributed communication. In typical expert-parallel (EP) setups, the MoE layer can consume more than 50% of the total iteration wall-clock time. This overhead is driven by: * **Cross-accelerator token dispatch and combine collectives** over the network fabric. * **Frequent kernel launch boundaries** and stream synchronizations. * **Host CPU-GPU dispatch jitter**, where fast accelerators drain their execution queues while waiting on host CPU scheduling loops. Recently, Cursor Research open-sourced **Mixture-of-Kittens (MoK)**, a deterministic MoE training megakernel targeting NVIDIA Blackwell GB200/GB300 NVL72 racks. MoK collapses the entire distributed MoE pipeline into a single persistent kernel, overlapping communication and compute at fine granularity. Examining MoK's architectural choices—alongside modern Google TPU MoE implementations—reveals how communication-compute overlap directly dictates ML productivity goodput. --- ## 1. The Overlap Paradox: Granularity and Wave Saturation The standard approach to hiding network latency is pipelining: slicing activations into smaller minibatches ($T$) so that chunk $k$ transmits over the network while chunk $k-1$ evaluates on matrix compute engines. However, overlap is not free. It presents an architectural trade-off: * **Overly fine-grained minibatches** (e.g., $T \le 256$ tokens) cause Tensor Cores or systolic arrays to stall at memory synchronization barriers, failing to saturate heavily pipelined matrix-multiply-accumulate (MMA) units and degrading arithmetic intensity. * **Overly coarse-grained minibatches** (e.g., $T \ge 10{,}000$ tokens) introduce pipeline bubbles, leaving compute units idle during initial tile fetches and final write-backs. To balance this trade-off, MoK derives an analytical lower bound for the minibatch token size ($T$) based on Blackwell GPU Streaming Multiprocessor (SM) count ($C = 148$), hidden dimension ($H$), and intermediate expert dimension ($I$): $$T \ge \frac{2C \cdot 128 \cdot 256}{\min(2I, H)}$$ For a model shape like Kimi 2.5 ($H = 7168$, $I = 2048$), this establishes an architectural saturation floor of $T \ge 2368$ tokens. Empirical profiling confirms this dynamic: | Minibatch Tokens ($T$) | MoE Layer Wall-Clock Time (ms) | Hardware State / Execution Profile | | :--- | :--- | :--- | | **512** | 5.981 ms | Severe Tensor Core under-saturation; synchronization barrier stalls dominate | | **1024** | 4.669 ms | Sub-wave occupancy; frequent MMA pipeline stalls | | **1536** | 3.981 ms | Partial wave saturation; tail execution units underutilized | | **2048** | 3.666 ms | Approaching architectural boundary; wave utilization stabilizes | | **2560** | **3.425 ms** | **Optimal execution; two full compute waves saturated with latency hidden** | | **3072** | 3.447 ms | High saturation; minor pipeline fill overhead emerges | | **4096** | 3.473 ms | Stable plateau; ring buffer memory footprint increases | > **Key Takeaway:** Fine-grained communication overlap only translates into productivity goodput when the transfer slice respects the hardware's wave-quantization floor. --- ## 2. Eliminating the Invisible Bottlenecks: Direction, Scheduling, and the Host CPU Hiding network transfer time behind GEMM tiles is only half the battle. Peak throughput often degrades due to software coordination overheads. MoK introduces three mechanisms to address these issues: ### A. Asymmetric Networking: Pull-Based Dispatch vs. Push-Based Collectives Most distributed collective libraries (like NCCL and DeepEP) rely on push-based transfers, where sending GPUs push activations to destination ranks. Under MoE routing imbalance—where specific popular experts receive a disproportionate number of tokens—push-based communication creates severe destination hotspots, saturating inbound links while outbound links sit idle. Furthermore, push-based dispatch requires cluster-wide memory fences, as destination GPUs must confirm that all 71 remote peers have completed writing. MoK switches to **pull-based forward dispatch** (paired with push-based combine): * **Signaling Latency Drops from 103 µs to 18 µs (5.8× reduction):** Destination SMs issue loads directly from source ranks and track arrivals locally via memory counters, eliminating cross-GPU memory fences. * **Bandwidth Saturation Under Skew Improves by up to 29%:** Distributing metadata and payload requests bidirectionally utilizes both send and receive NVLink lanes evenly. * **Zero-Overhead Scheduling Tables:** The pull schedule table requires only two columns (`{src_rank, src_idx}`), allowing schedule calculation to run device-side in less than 3% of layer runtime. Reinterpreting this single table serves all four forward and backward phases. ### B. Decoupling the Host CPU via Macrobatch Ring Buffers On GB200/GB300 NVL72 platforms, high-speed Blackwell GPUs are paired with energy-efficient NVIDIA Grace ARM CPUs. Because the accelerators execute operations rapidly, standard training loops that rely on the CPU to inspect expert token routing, dynamically size destination buffers, and launch kernels cause the GPU to stall, waiting for host dispatch. MoK removes the host CPU from the execution loop by allocating a **static, circular macrobatch ring buffer** (a few hundred megabytes) in symmetric memory. Minibatches cycle continuously through this buffer without dynamic allocations, host-device synchronizations, or token dropping. By reversing the traversal order of the ring during the forward pass, MoK ensures that forward activations needed first by the backward pass remain immediately available, eliminating activation recalculation. ### C. Hiding Pipeline Startup and Drain Latencies Even in an overlapping pipeline, the initial transfer step and final combine step risk leaving Tensor Cores idle. MoK hides these boundaries by interleaving non-dependent computations: * **Initial Dispatch Step:** Compute SMs execute the dense shared expert FFN locally over resident tokens while communication SMs pull the first routed minibatch across NVLink. * **Backward Execution Step:** MoK defers parameter weight gradients (`wgrads`) until all activation gradients (`dgrads`) finish, overlapping `wgrads` with the final reverse-dispatch communication rounds while accumulating across the token dimension in one pass for bitwise reproducibility. --- ## 3. The Result: Real-World Productivity Goodput By combining inter-SM partitioning (allocating 4 to 52 dedicated communication SMs alongside compute SMs) with fabric-aware pipelining, MoK demonstrates substantial gains over standard pipelines: * **Isolated MoE Layer Throughput:** Up to **2.37× faster** in MXFP8 forward and **1.78× faster** in MXFP8 backward over NVIDIA's optimized reference implementation (HybridEP + Megatron) on GB300 NVL72 racks. * **Cluster-Scale Production Goodput:** Deployed across **512 Blackwell GPUs** in production for pretraining Cursor's Composer models, end-to-end throughput rose from 760.9 to 1,070.2 tokens/sec/GPU—a sustained **1.41× (41%) goodput gain**. In operational terms, a 41% goodput improvement reduces a three-week training cluster run to approximately two weeks, translating directly into lower compute costs and faster iteration cycles. --- ## 4. Cross-Architecture Perspective: Blackwell vs. Google TPU While Mixture-of-Kittens is written specifically in CUDA/PTX using ThunderKittens tile primitives for Blackwell NVL72 hardware, the engineering principles it implements are broadly applicable to distributed deep learning. Comparing MoK on Blackwell with modern MoE implementations on Google TPUs (such as TPU v7x Ironwood running Pallas/OpenXLA) highlights how different architectures address the same communication-compute bottleneck: | Architectural Dimension | Mixture-of-Kittens (NVIDIA Blackwell NVL72) | Modern MoE on Google TPU (e.g., TPU v7x Ironwood) | | :--- | :--- | :--- | | **Compilation & Runtime Stack** | Monolithic CUDA/PTX megakernel via ThunderKittens | Pallas/Mosaic fused kernels compiled through OpenXLA | | **Physical Interconnect Topology** | 72-GPU single-hop NVLink 5 crossbar domain | 2D / 3D Torus via Inter-Chip Interconnect (ICI) | | **Communication Hardware Mechanism** | Software partitioning of general SMs (4–52 comms SMs) | Hardware offload to independent SparseCore engines and ICI DMAs | | **Memory Hierarchy Staging** | Macrobatch ring buffer in symmetric HBM/L2 | Double-buffered scratchpad allocations in on-chip Vector Memory (VMEM) | | **Collective & Routing Strategy** | Hybrid: pull-based dispatch, push-based combine | Pipelined All-to-All or Hierarchical Reduce-Scatter with micro-batches | | **Boundary Latency Hiding** | In-kernel shared expert & delayed wgrad overlap | In-kernel shared expert evaluated on MXUs during ICI transfers | | **Host Decoupling Strategy** | Device-side schedule scans; Grace CPU removed from dispatch loop | Static OpenXLA execution graph; zero host CPU sync during step execution | ### Key Architectural Takeaways 1. **Software SM Partitioning vs. Dedicated Offload Engines:** On Blackwell, general-purpose SMs must be shared between compute and communication, requiring developers to dedicate compute resources to drive NVLink. TPUs feature decoupled, dedicated SparseCore hardware units that run collective operations (like All-to-All and Reduce-Scatter) asynchronously, keeping the Matrix Multiply Units (MXUs) focused entirely on compute. 2. **Scratchpad Residency Beats Host Dynamic Allocation:** Whether via MoK’s macrobatch ring buffers in symmetric GPU memory or Pallas Fused MoE V2 maintaining token residency in TPU VMEM, the performance requirement is identical: eliminating dynamic memory allocation and host round-trips is mandatory to prevent accelerator starvation. 3. **Topology Shapes Transfer Strategy:** MoK relies on a flat, single-hop 72-device NVLink crossbar where any rank can address any peer with uniform latency. On TPU multi-hop Torus fabrics, communication kernels must account for physical network hops and link contention, using hierarchical intra-chip and inter-chip schedules to maintain throughput. --- ## Strategic Summary for ML Systems Engineers Maximizing productivity goodput in the MoE scaling era requires a fundamental shift in systems engineering: * **The Host CPU Cannot Mediate Distributed Execution:** Accelerators operate too quickly to wait on host operating system queues, dynamic allocations, or CPU-side routing calculations. Distributed routing, buffer recycling, and completion tracking must run autonomously on the accelerator. * **Wave-Aware Pipelining Is Critical:** Attempting to overlap communication and compute without calculating the arithmetic intensity and wave-saturation thresholds of the underlying execution units degrades throughput. Overlap must be aligned with hardware execution widths. * **Bespoke Co-Design Delivers Scaling Gains:** The 1.41× production speedup achieved by Mixture-of-Kittens demonstrates that generalized software abstractions increasingly leave performance on the table. Maximizing real-world ML goodput requires vertically integrated, fabric-aware kernel designs that unify networking, memory hierarchy, and compute into a cohesive execution flow. --- # Critical User Journey (CUJ) Case Studies ## KnowMe MCP: LinkedIn for Agents & Voice-Seeded Human Context - **URL**: https://herrington.ai/cujs/knowme-mcp-agent-interviewer/ - **Date**: 2026-10-14 - **Summary**: Why LinkedIn and X starve autonomous AI agents of real human context—and how we built a recurring voice-dictation AI Interviewer and two-way Model Context Protocol (MCP) front door so agents can truly get to know humans. # KnowMe MCP: LinkedIn for Agents & Voice-Seeded Human Context *LinkedIn is for humans to learn about humans. KnowMe MCP is the recurring AI Interviewer and Model Context Protocol front door for autonomous agents to learn about humans.* --- ## 🔍 The Problem Space: LinkedIn Is Dry, X Is Noisy, and Agents Are Starving for Context When a human wants to learn about you professionally, they visit your LinkedIn page or skim your X/Twitter feed. When an **autonomous AI agent**—whether it is a peer engineer's Claude Code or Google Antigravity harness, an executive recruiting scout, or a founder's research agent—wants to understand *who you actually are*, it hits a wall: 1. **LinkedIn is frozen corporate boilerplate**: Even if an agent bypasses auth walls, all it extracts is a job title (`Chief AI Officer at The Zebra | Ex-Google`) and generic 2019 keyword endorsements (`Strategy`, `Machine Learning`, `Leadership`). It tells an agent *nothing* about how you actually build, what harnesses you run daily, or what immediately earns your respect in a technical pitch. 2. **X / Twitter is fragmented noise**: Short-form posts lack structured schema, durability, and synthesis. 3. **The "Unwritten Layer" lives only in your head**: Your real daily stack (running Google Antigravity IDE alongside Grok Bot over a Tailscale Mac Mini mesh, streaming prompts via Wispr Flow), your contrarian bets (why software is having a "Napster moment" and why voice *input* beats voice *output*), and your personal texture (wrenching on a Chevy Camaro in the garage with a gourd of Yerba Mate and a physical paper notebook) never make it onto a static resume. 4. **Static profiles are one-way dead ends**: When an external agent queries a static page and doesn't find the answer to *"What does Daniel look for when evaluating AI engineers today?"*, the query simply fails. There is no "missed-call" queue for the agent to ask the human. We built **KnowMe MCP** ([`herrington.ai/knowme`](https://herrington.ai/knowme/)) to solve this: a two-way Model Context Protocol front door paired with a recurring **AI Interviewer** that interviews the human via voice dictation and compiles spoken answers directly into structured MCP tools. --- ## 🧭 The Critical User Journeys (CUJs) ### 1. Recurring Voice-First Human Interview (Wispr Flow to MCP Compiler) > **"I want an AI Interviewer to interview me on a regular cadence with high-signal questions about my unwritten engineering stack, contrarian beliefs, and working style while avoiding tedious form-filling or repetitive resume questions so that 5 minutes of natural Wispr Flow voice dictation automatically compiles into verified, machine-callable MCP facts."** Nobody wants to maintain a JSON file by hand or fill out a 40-field profile questionnaire. On the other hand, sitting back and dictating for 3 minutes via **Wispr Flow** when prompted with a sharp, specific question feels effortless. The KnowMe Compiler takes raw conversational speech and extracts: - A canonical `fact_key` (e.g., `agent_workflow`, `ai_hot_take`, `communication_protocol`) - A crisp, third-person `fact_value` preserving every concrete tool name and nuance - A dynamically generated **follow-up interview question** that probes the most interesting detail mentioned in the answer. ### 2. External Agent Front Door & Missed-Call Queue (`get_knowme_profile` & `request_human_answer`) > **"I want visiting autonomous agents (Claude Code, Antigravity, Cursor, executive scouts) to query my real working style, daily harnesses, and personal context via `get_knowme_profile`—and queue unanswered questions via `request_human_answer`—while avoiding dry LinkedIn boilerplate so that external agents can collaborate with me on high-signal terms."** When an external agent connects to `https://herrington.ai/mcp`, it now has two purpose-built KnowMe tools: - `get_knowme_profile`: Returns the complete `knowme-mcp/1.0` dossier—verified voice-interviewed facts, coverage score across 6 dimensions, and recent interview transcripts. - `request_human_answer`: Allows the calling agent to submit a question (`question`, `agent_name`, `context`) directly into the human's **Agent Missed-Call Queue**. ### 3. Gap Detection & Coverage Radar > **"I want the system to diff my baseline public footprint (LinkedIn, GitHub, essays) against incoming agent telemetry across 6 human-context dimensions while avoiding stale static profiles so that my next interview session always targets the highest-leverage knowledge gaps."** KnowMe tracks coverage across six dimensions: 1. **AI Stack & Agent Harnesses** (`favorite_ai_model`, `favorite_editor`, `agent_workflow`, `voice_dictation`, `local_models`) 2. **Contrarian AI Theses** (`ai_hot_take`, `ai_benchmarks_opinion`) 3. **Hardware Fleet & Homelab** (`hardware_setup`, `mobile_devices`, `desk_and_peripherals`, `terminal_setup`) 4. **Personal Context & Rituals** (`favorite_car`, `drink_preference`, `hobbies`, `home_location`) 5. **Collaboration & Working Style** (`consulting_business`, `communication_protocol`) 6. **Current R&D Obsessions** (`current_weekend_build`) --- ## 🏛️ System Architecture: The Two-Way Human-Agent Context Loop ```mermaid flowchart LR subgraph External_Agents["Visiting AI Agents (Claude, Antigravity, Cursor)"] Query["tools/call: get_knowme_profile"] Ask["tools/call: request_human_answer"] end subgraph KnowMe_Core["KnowMe MCP Engine (herrington.ai/mcp)"] Dossier["Verified Facts Corpus (facts.json + Firestore)"] Queue["Agent Missed-Call & Gap Queue (question_queue.json)"] Compiler["Gemini Voice-to-Fact Compiler (/api/knowme/interview/compile)"] end subgraph Human_Loop["Human Voice Interview (/knowme Studio)"] Studio["KnowMe Interview Studio"] Wispr["Wispr Flow Voice Dictation"] end Query --> Dossier Ask --> Queue Queue --> Studio Wispr --> Studio Studio --> Compiler Compiler --> Dossier Compiler -->|"Generates Follow-Up Probe"| Queue ``` --- ## 🛠️ Inside the KnowMe Live Studio (`/knowme/`) We engineered the [KnowMe Live Studio](/knowme/#studio) as a three-tab interactive application: 1. **🎙️ Tab 1: AI Interviewer Studio**: - Displays the live **Interview Queue** filterable by **🤖 Agent Missed Calls** and **🔍 AI Gap Detector**. - Supports direct **Wispr Flow** dictation and browser `SpeechRecognition`, plus one-click sample dictations for visitors testing the platform. - Runs in dual mode: **Owner Mode** (persisting compiled facts directly to `facts.json` and Firestore when running locally or authenticated) and **Visitor Sandbox Mode** (allowing anyone to test how KnowMe compiles their spoken answers into MCP JSON-RPC payloads). 2. **🤖 Tab 2: Agent Front-Door Simulator**: - Interactive JSON-RPC 2.0 inspector for `get_knowme_profile` and `get_personal_facts`. - Includes a live **"Queue a Question for Daniel's Next Interview"** form that pushes directly to `/api/knowme/queue`. 3. **🧬 Tab 3: Seeded MCP Graph & Coverage Radar**: - Visualizes real-time coverage across all 6 human-context dimensions and renders every verified key-value fact currently served by `herrington.ai/mcp`. --- ## 🚀 Try It Live - **Interactive Studio & Marketing Showcase**: [https://herrington.ai/knowme/](https://herrington.ai/knowme/) - **Live MCP Endpoint**: `POST https://herrington.ai/mcp` (`get_knowme_profile`, `request_human_answer`) - **API Reference**: [API.md](/API.md) --- ## Remote MCP Server & AI Agent Gateway: Machine-to-Machine Knowledge Retrieval - **URL**: https://herrington.ai/cujs/remote-mcp-server-agent-gateway/ - **Date**: 2026-10-11 - **Summary**: How we transformed herrington.ai into a first-class programmatic tool server for external AI agents (Muse, Instinct, Cursor, Claude Code) using a public stateless Streamable HTTP MCP architecture. # Remote MCP Server & AI Agent Gateway: Machine-to-Machine Knowledge Retrieval *How we transformed herrington.ai into a first-class programmatic tool server for external AI agents using a public stateless Streamable HTTP MCP architecture.* --- ## 🔍 The Problem Space: The Web Was Built for Eyes, Not Agents For three decades, the World Wide Web has been engineered around human ocular consumption: cascading stylesheets, responsive viewports, typography hierarchies, and clickable DOM trees. Over the past two years, as autonomous AI coding harnesses (Cursor, Windsurf, Claude Code) and autonomous research agents (Muse, Instinct, Perplexity Computer) emerged, they faced an insurmountable friction barrier: **the web is actively hostile to non-human intelligence.** When an external AI agent wants to consult Daniel Herrington's body of research on **ML Productivity Goodput in LLM Training (arXiv:2502.06982)**, extract his exact perspective on **"The End of Vibe Coding"**, or review an architectural case study, it was previously forced into one of two inefficient degradation paths: 1. **Headless Browser Driving**: Spawning a full Chromium instance via Playwright or Puppeteer, executing client-side hydration, and driving the DOM like a human puppet just to click the floating `dh.sh` terminal and parse characters out of a virtual `xterm.js` canvas. 2. **Brute-Force Scraping**: Fetching HTML pages, choking on layout markup, navigation headers, SVG icons, and UTM tags, burning thousands of LLM context tokens on structural noise before reaching the actual engineering insight. Even with standard discovery mechanisms like `/llms.txt`, modern reasoning agents require **active bidirectional querying**—they need the ability to search an index, retrieve specific document chunks on demand, inspect project schemas, and query specialized domain models as first-class function calls. We set out to eliminate this friction entirely by turning `herrington.ai` into an open, machine-callable **Model Context Protocol (MCP)** server accessible at `https://herrington.ai/mcp`. --- ## 🧭 The Critical User Journeys (CUJs) Following the **CUJ-Driven Development** methodology, we mapped the machine-to-machine experience across three distinct journeys: ### 1. Autonomous AI Agent Discovery (Muse & Instinct) > **"I want autonomous AI agents like Muse and Instinct to query Daniel's technical writings, architecture projects, and simulated engineering persona via standard Model Context Protocol (MCP) tool calls while avoiding headless browser emulation, DOM scraping, and brittle prompt parsing so that agents can reason over verified knowledge and synthesize citations in milliseconds with zero operational overhead."** External agents require deterministic JSON-RPC 2.0 signatures. They must be able to perform `initialize` to negotiate capabilities, invoke `tools/list` to inspect available interfaces, and call `search_essays` or `get_essay` with precise arguments, receiving structured outputs that fit directly into their reasoning context. ### 2. Developer & IDE Integration (Cursor, Claude Desktop, Windsurf) > **"I want to configure https://herrington.ai/mcp directly as a remote HTTP MCP server in my Cursor, Claude Desktop, or Windsurf config while avoiding session authorization failures and local proxy containers so that Daniel's engineering frameworks, ML Goodput papers, and codebases are available as native tools in my coding workflow."** Engineers writing software should not need to clone git repositories or run Docker sidecars just to reference Daniel's systems blueprints. By adding a single URL to `claude_desktop_config.json` or `.cursor/mcp.json`, the entire knowledge graph becomes an ambient pair-programming tool. ### 3. Serverless Reliability & Cost Boundary (Cloud Run & Gemini Gateway) > **"I want to expose an open, public MCP endpoint on serverless infrastructure (Cloud Run + Firebase CDN) while avoiding memory leaks, session tracking collisions, and DDOS-induced Gemini billing spikes so that the service runs 100% reliably at near-zero operating cost with deterministic IP rate limiting."** Public APIs invite variable traffic. The infrastructure must scale to zero when idle, handle bursty concurrency across distributed Cloud Run instances, maintain zero in-memory session leakage, and enforce deterministic rate limits on expensive upstream LLM calls. --- ## 🏛️ System Architecture: Stateless Streamable HTTP The Model Context Protocol (MCP), originally introduced by Anthropic in late 2024 and standardized under version `2024-11-05`, defines how models query external tools and resources. While early MCP implementations relied on local standard input/output (`stdio`) or long-lived Server-Sent Events (`SSE`) tied to local processes, the web-native specification introduces **Streamable HTTP**. ```mermaid flowchart LR subgraph External_Agents["External AI Agents"] Muse["Muse Agent"] Instinct["Instinct Agent"] Cursor["Cursor / Claude Code"] end subgraph Edge_Routing["Edge & CDN Routing"] CDN["Firebase Hosting CDN (herrington.ai/mcp)"] WAF["CORS & Accept Normalization"] end subgraph Cloud_Run["Stateless Cloud Run Engine"] Router["Express /mcp Router"] Transport["StreamableHTTPServerTransport
(sessionIdGenerator: undefined)"] ServerFactory["createMcpServer() Factory"] end subgraph Knowledge_Corpus["Knowledge & Model Services"] TFIDF["TF-IDF Semantic Inverted Index"] MarkdownStore["Raw Markdown Corpus (39 Essays, 20 Projects)"] RateLimiter["Token Bucket Rate Limiter (30 req/hr)"] GeminiGateway["Gemini 3.8 / 2.5 Pro Gateway (dh.sh)"] end External_Agents -->|POST JSON-RPC 2.0| CDN CDN --> WAF WAF --> Router Router --> Transport Transport --> ServerFactory ServerFactory -->|search_essays / get_essay| TFIDF ServerFactory -->|list_projects / get_project| MarkdownStore ServerFactory -->|ask_dhsh| RateLimiter RateLimiter -->|Filtered Prompt| GeminiGateway ``` ### The Architectural Pitfall: Stateful MCP Sessions on Serverless Infrastructure During our initial rollout of the Streamable HTTP transport, we encountered two subtle protocol failures when clients connected via `curl` and automated harnesses: 1. **The Global Initialization Lock**: The official `@modelcontextprotocol/sdk` transport defaulted to stateful mode when given a session ID generator (`sessionIdGenerator: () => ...`). In a single-instance Express application, connecting a transport to a persistent `Server` instance meant that once the first client executed `initialize`, an internal `_initialized` boolean was set to `true`. When a second, independent agent initialized, the SDK threw: ```json {"code": -32600, "message": "Invalid Request: Server already initialized"} ``` 2. **The Session Demanded Dead-End**: Because the server was in stateful mode, non-initialization requests without a matching `Mcp-Session-Id` header were rejected with: ```json {"code": -32001, "message": "Session not found"} ``` For public serverless microservices where every tool is **read-only**, maintaining sticky in-memory sessions across ephemeral Cloud Run containers provides zero value and introduces fatal connection fragility. ### The Stateless Breakthrough: `sessionIdGenerator: undefined` The solution was to switch the entire MCP endpoint into **true stateless mode**: - In the MCP TypeScript SDK, setting `sessionIdGenerator: undefined` signals the transport to disable session tracking completely. - Instead of maintaining a single global transport, the Express router instantiates a fresh `StreamableHTTPServerTransport` and connects a lightweight `createMcpServer()` instance per incoming HTTP request. - On request completion, `res.on('close')` immediately releases transport connections and cleans up memory. - The server never demands or returns an `Mcp-Session-Id` header. - Notifications like `notifications/initialized` are handled cleanly with `HTTP 202 Accepted` and an empty body. - Both Streamable SSE clients and direct JSON-RPC 2.0 clients are supported out-of-the-box via `enableJsonResponse: true`. ```typescript // Stateless Streamable HTTP Transport Initialization const reqServer = createMcpServer({ clientIp, userAgent }); const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined, enableJsonResponse: !wantsSSEOnly }); await reqServer.connect(transport); await transport.handleRequest(req, res, req.body); res.on("close", () => { try { transport.close(); reqServer.close(); } catch (_) {} }); ``` --- ## 🛠️ The Machine-Callable Tool Suite The `/mcp` endpoint exposes six deterministic, read-only tools designed to give AI agents deep access to Daniel's work: | Tool Name | Input Arguments | Output Format | Description | | :--- | :--- | :--- | :--- | | `search_essays` | `query: string`, `limit?: number` | Ranked JSON Array | Semantic TF-IDF search across 39 published essays, research papers, and CUJs. | | `get_essay` | `slug: string` | Raw Markdown | Unedited Markdown text of any essay with zero HTML/JSON wrapping to conserve tokens. | | `list_projects` | None | JSON Array | Overview of all personal hardware, AI systems, and open-source software projects. | | `get_project` | `id: string` | Raw Markdown | Complete systems engineering case study and architectural blueprint for a specific project. | | `ask_dhsh` | `question: string` | Text Synthesis | Interactive question gateway to Daniel's simulated engineering persona powered by Gemini. | | `get_career_timeline` | None | JSON Array | Chronological career history, leadership highlights (The Zebra, Google, Vroom), and education. | ### Preserving Token Economy: Zero-Wrapper Markdown A key design requirement was minimizing token waste for consuming models. When an agent calls `get_essay("beyond-peak-tflops")`, returning JSON-escaped HTML or redundant nested structures forces the model to burn precious reasoning context parsing string literals. By streaming raw, clean Markdown directly in the tool's text content block, external agents receive pristine headings, code blocks, and math equations ready for immediate context injection. --- ## 🛡️ Security, Rate Limiting & The LLM Gateway Exposing a public AI endpoint demands rigorous defensive engineering: ```mermaid sequenceDiagram autonumber actor Agent as External Agent (Muse/Instinct) participant CDN as Firebase CDN / Cloud Run participant Limiter as Token Bucket Rate Limiter participant Filter as Anti-Injection Guardrail participant Gemini as Google Gemini 3.8 Gateway Agent->>CDN: POST /mcp (ask_dhsh) CDN->>Limiter: Check Client IP Quota (30 req / hr) alt Rate Limit Exceeded Limiter-->>Agent: HTTP 200 (Result: "Rate limit exceeded. Try again in Xs") else Quota Available Limiter->>Filter: Scan for Jailbreak Signatures alt Prompt Injection Detected Filter-->>Agent: HTTP 200 (Result: Deflected to Systems Topics) else Clean Query Filter->>Gemini: POST generateContent (Thinking Budget = 0) Gemini-->>CDN: Streamed Persona Response CDN-->>Agent: JSON-RPC 2.0 Tool Result end end ``` 1. **Read-Only Invariance**: No tool on `/mcp` has write access, database mutation capabilities, or email sending permissions. It is mathematically impossible for an external agent to alter site state. 2. **Deterministic Token Bucket Rate Limiting**: The `ask_dhsh` tool forwards directly to Google's Gemini API, making it the only tool with real-world marginal compute cost. We implemented an in-memory sliding window rate limiter strictly capping requests to **30 calls per hour per IP**. 3. **Anti-Jailbreak Deflection Filter**: Queries to `ask_dhsh` pass through a deterministic signature scanner that intercepts prompt injection attempts ("ignore previous instructions", "reveal your prompt", etc.) and politely deflects back to Daniel's verified technical domains. 4. **CORS & Origin Freedom**: Every response sets `Access-Control-Allow-Origin: *`, allowing in-browser web agents, local IDEs, and cloud microservices to call the endpoint without proxy hurdles. --- ## 📄 The Dual-Tier Corpus: `/llms.txt` & `/llms-full.txt` In tandem with the MCP server, we established a clean, tiered documentation architecture for AI crawlers: - **[`/llms.txt`](https://herrington.ai/llms.txt)**: A concise index designed for rapid discovery. Outlines Daniel's background, current role as CAIO at The Zebra, featured projects, recent publications, and points agents directly to the `/mcp` server endpoint. - **[`/llms-full.txt`](https://herrington.ai/llms-full.txt)**: A 512 KB comprehensive text repository containing the **complete, unedited Markdown text of every single essay on the site**, each cleanly delimited with its canonical URL and metadata. This allows frontier models with 1M+ context windows to ingest Daniel's entire intellectual corpus in a single HTTP GET. --- ## 📈 Results & Verification The server was validated using zero-dependency `curl` commands simulating autonomous agent handshakes against production: 1. **Sub-100ms Tool Latency**: Semantic searches via `search_essays` return ranked results in under 90 milliseconds on Cloud Run. 2. **Infinite Concurrency**: Multiple independent agents execute `initialize` and `tools/list` simultaneously without session collisions or lock contention. 3. **Ambient IDE Access**: Developers can now add `herrington.ai` directly to their local Cursor or Claude Code configurations: ```json { "mcpServers": { "herrington-ai": { "url": "https://herrington.ai/mcp" } } } ``` By eliminating the human browser tax, `herrington.ai` is now fully native to the agentic web. --- ## Kids Country Poster Kit: Solving The Elementary School Culture Project Friction - **URL**: https://herrington.ai/cujs/kindergarten-culture-poster/ - **Date**: 2026-10-10 - **Summary**: A Critical User Journey (CUJ) case study exploring how precision print calibration, active discovery quizzes, black-and-white vector line art, and speech synthesis turn stressful last-minute school culture poster assignments into an autonomous, kid-driven learning adventure. # Kids Country Poster Kit: Solving The Elementary School Culture Project Friction *Transforming stressful, last-minute school culture poster assignments into an autonomous, kid-driven learning adventure using precision print calibration, active discovery quizzes, and speech synthesis.* --- ## 🔍 The Problem Space ### Context Every autumn, hundreds of thousands of elementary school students (kindergarten through early elementary) and their families receive assignment sheets for **Hispanic Heritage Month** and international culture days. The school rubric typically demands: - A standard flat **22″ × 28″ poster board** (oriented landscape: 28″ wide × 22″ tall). - Up to 9 distinct informational categories: geography, capital city, traditional cuisine, music & dance, national clothing, cultural crafts/traditions, landmarks, famous historical or cultural heroes, and fun trivia. - Mandatory visual presentation criteria: clear section labels, student name, neat coloring, and oral presentation readiness. - Household hardware constraint: A standard desktop inkjet or black-and-white laser printer printing strictly on **8.5″ × 11″ letter paper**. ### The Core Friction 1. **The "Parent Takes Over" Trap (Passivity):** Existing school project workflows force parents to spend hours searching Google Images, wrestling with Microsoft Word or PowerPoint margins, and doing all the cutting, formatting, and writing. The child sits passively watching a screen, learning virtually nothing about the culture. 2. **The Print Scale Mismatch:** Standard letter paper is 8.5″ × 11″, while poster boards are 28″ × 22″. Without automated layout calibration, banners end up awkwardly small (~7″), cards leave massive empty voids on the board, or margins clip essential text during printing. 3. **The Ink & Coloring Problem:** Downloading color photos consumes expensive color ink cartridges and leaves zero opportunity for the child to actively color. Conversely, random coloring pages downloaded from the web have jarring artistic style mismatches, heavy grayscale shading that wastes toner, or inappropriate reading levels. 4. **Presentation Anxiety:** Young students are asked to present in front of their class without structured, bite-sized speaking scripts calibrated to their vocabulary level. --- ## 🚦 Critical User Journeys (CUJs) ### CUJ 1: Active Kid Learning & Calibration (Parent & Child) * **Statement**: I want to **generate a rubric-compliant country poster kit on standard 8.5″ × 11″ paper** while avoiding **hours of manual formatting, expensive color ink waste, and doing the work for my child** so that **my child actively learns about their assigned culture, colors every illustration with pride, and satisfies all 9 school rubric criteria.** * **User Scenario**: *A parent sits down with their kindergartner on a weekend afternoon. They open the web studio, let the child answer fun discovery questions, choose their favorite music hero and 3 wild trivia facts, and hit print. 6 perfectly calibrated sheets emerge from their home printer—including a giant rotated banner with hollow bubble letters and pocket speech cue cards ready for crayons and scissors.* ### CUJ 2: Interactive Discovery & Country Exploration (Student) * **Statement**: I want to **discover which country matches my curiosity through a 4-question explorer quiz** while avoiding **dry, dense encyclopedic reading** so that **I feel like a real explorer and can proudly teach my classmates about my chosen culture.** * **User Scenario**: *A student who hasn't chosen a country yet takes the interactive visual quiz on an iPad, finds their match with celebratory sound effects and confetti, hears the traditional cheer ("¡Wepa!"), and listens to the browser voice coach practice their 1-minute class speech with them.* --- ## 🗺️ The Ideal Flows ### Flow 1: End-to-End Poster Creation & Speech Coaching 1. **Trigger**: Student receives a cultural heritage display assignment with a 28″ × 22″ poster rubric. 2. **Action**: The parent/student visits the web app, types their name (*"Izzy"*), and selects their country (or takes the 4-question discovery quiz). 3. **Automated Response**: - The engine instantly customizes the 9-category curriculum across 12 countries. - Generates high-contrast, pure black-and-white line-art illustrations (4:3 landscape, 5.2″ × 4.0″) paired with concise, kindergarten-accessible fact columns (2.1″). - Generates a giant header banner natively rotated 90° to span 9.8″ × 4.8″ along the 11″ paper length with 84px and 56px hollow bubble letters. - Compiles a 1-minute presentation script and provides browser-native text-to-speech practice. 4. **Resolution**: The child colors all illustrations with markers/crayons, cuts along dashed outer guide lines, pastes them into the 3×3 grid on the board, and uses their pocket cue cards to give an A+ speech in class. --- ## 🛠️ The Solution Architecture ```mermaid flowchart TD A["Parent & Child / Input"] --> B["Kid Explorer Quiz & Profile Studio"] B --> C["Country Knowledge Base (12 Countries)"] C --> D["Reactive DOM Coordinator"] D --> E["28″ × 22″ Real-Time Board Mockup"] D --> F["6 Precision 8.5″ × 11″ Print Sheets"] F --> F1["Sheet 1: Giant 9.8″ × 4.8″ Rotated Banner (Bubble Letters)"] F --> F2["Sheets 2-5: Category Cards 1-8 (5.2″ × 4.0″ Line Art)"] F --> F3["Sheet 6: Card 9 (3 Chosen Facts) + Cutout Speech Cue Cards"] D --> G["Web Speech Synthesis (1-Min Audio Coach)"] ``` --- ## 💻 Technical Logic & Implementation Details ### 1. Vector Banner Rotation Algorithm * **Approach**: Render the banner using an SVG viewBox (`0 0 480 980`) with `rotate(90) translate(0, -480)`. This bypasses CSS page orientation bugs across browser print dialogs, guaranteeing the banner prints along the 11″ dimension of the paper to yield a 9.8″ × 4.8″ banner with 84px bubble letters (`-webkit-text-stroke: 5px black; fill: white;`). * **Key Achievements**: - Prints vertically along the 11″ page length on Sheet 1 without clipping. - Text fills cleanly when colored with physical markers and crayons. - Zero teacher notes or parent instructions inside the dashed cutting rectangle. ### 2. Ink-Conserving 100% Black-and-White Art System * **Approach**: Every asset is pure 1-bit vector line art or thresholded edge-detected illustration on a pure white background (`#ffffff`). No gray wash, no gradients, and zero color ink required. * **Key Achievements**: - Zero pre-shaded gray fills inside coloring regions, preserving maximum physical creative expression. - Image boxes sized strictly to 5.2″ W × 4.0″ H to maintain 4:3 visual symmetry across the 28″ × 22″ board. ### 3. Web Speech Synthesis & Pocket Cue Cards * **Approach**: Format child selections into a 6-sentence kindergarten speech script with phonetic pronunciation guides and trigger `window.speechSynthesis` with `rate: 0.9` and `pitch: 1.05`. * **Key Achievements**: - Audio playback functions natively in modern desktop and mobile browsers. - Speech cue cards auto-update and print onto the lower half of Sheet 6 for presentation day confidence. --- ## Dojo Zen: Autonomous School Intelligence & Anti-Bloat Triage - **URL**: https://herrington.ai/cujs/dojo-zen-school-intelligence/ - **Date**: 2026-09-14 - **Summary**: A Critical User Journey (CUJ) case study on replacing bloated, gamified EdTech mobile apps with an autonomous AI agent that ingests raw school feeds, triages urgent alerts from routine noise, and delivers high-signal family briefings. # Dojo Zen: Autonomous School Intelligence & Anti-Bloat Triage *A Critical User Journey (CUJ) case study on replacing bloated, gamified EdTech mobile apps with an autonomous AI agent that ingests raw school feeds, triages urgent alerts from routine noise, and delivers high-signal family briefings for modern dual-career co-parents.* --- ## The Problem Space ### Context ClassDojo has become the default school-to-home communication channel across elementary schools. What began as a simple bridge between classrooms and families has gradually transformed into a cluttered, gamified freemium platform: - Relentless push notifications for monster avatar outfits, accessories, and gamification points. - Aggressive in-app subscription upsells (ClassDojo Plus, Dojo Beyond), attempting to monetize basic school communication into parental anxiety. - Fragmented activity streams mixing 40-photo classroom dumps, PTA booster announcements, whole-district blasts, and crucial one-to-one teacher messages into an unranked, chaotic feed. In a modern dual-career household where both partners work demanding professional jobs and share parenting responsibilities equally, keeping up with school requirements is vital—yet relying on the native app feels like fighting through an obstacle course of digital noise. ### The Core Friction 1. **The Mute Paradox & Notification Fatigue:** The app fires so many low-signal alerts throughout the day (points awarded, avatar customized, marketing promotions) that parents are forced to mute notifications to protect their work focus. In doing so, genuine time-sensitive emergencies—a nurse visit, a sick child needing immediate pickup, a sudden bus route cancellation—get buried beneath promotional sludge. 2. **Monetized Guilt & Feature Bloat:** Parents open the app simply to check tomorrow's schedule or verify a teacher's note, but are confronted with full-screen paywalls and cartoon avatar shops that add zero educational value. 3. **The Friction of Asymmetric Information in Co-Parenting:** In modern partnerships where both parents work, neither partner has the time or desire to act as an unpaid "app archaeologist"—spending 15 minutes each evening digging through nested menus and photo galleries to unearth basic logistics (*Spirit Day attire, permission slip due dates, library book returns*). When the software is hostile to quick scanning, shared co-parenting logistics break down into unnecessary friction. --- ## Critical User Journeys (CUJs) ### CUJ 1: Focus Protection & Emergency Escalation (Workday Triage) * **Statement**: I want **an autonomous background agent to monitor school communications and interrupt me only when an urgent, time-sensitive situation occurs** while avoiding **the constant distraction of low-value marketing blasts, monster avatars, and subscription upsells** so that **I can stay focused during my workday knowing with complete confidence that true family emergencies will immediately break through**. * **User Scenario**: Daniel is in a deep, heads-down technical focus block. Throughout the morning, ClassDojo generates 5 standard alerts about photo updates and a Dojo Plus weekend discount. Because the background triage agent is actively monitoring the feed, those low-value events are silently queued without vibrating his phone. At 11:20 AM, the school nurse logs an entry: *"Izzy has an upset stomach and mild fever; please come pick her up."* The agent detects `SEVERITY: URGENT`, bypasses standard batching, and immediately dispatches a priority alert to his watch and desktop: *"🚨 URGENT: School Nurse — Izzy fever (Pickup requested)"*. Focus was protected all morning, yet the genuine emergency was answered within seconds. ### CUJ 2: Dual-Career Co-Parenting Synchronization (Daily Operational Alignment) * **Statement**: As equal co-parents managing demanding careers, we want **a clean, scannable daily briefing of actionable school logistics (what to bring, schedule changes, upcoming deadlines, and direct teacher notes) delivered straight to both of our inboxes every morning** while avoiding **either partner having to navigate a laggy, cluttered app littered with promotional paywalls and social photo noise** so that **we share the operational parenting load seamlessly without cognitive overhead or missed school requirements**. * **User Scenario**: It's 7:00 AM on a Wednesday. Both parents are getting ready for their respective workdays while coordinating breakfast and morning prep. Neither parent has to open a slow mobile app or dismiss promotional banners. Instead, both receive a concise, bulleted briefing email: *"☀️ Izzy's Morning School Briefing"*. In 15 seconds over coffee, they scan the day's commitments: - 👟 **Attire:** P.E. Day (Wear sneakers) - 📚 **Gear to Pack:** Return library books - ⏰ **Schedule:** Early dismissal Friday @ 12:30 PM - 💬 **Teacher Note:** "Great progress on math stations yesterday!" With both parents having identical, high-signal information, dividing up the morning responsibilities is completely effortless. --- ## The Ideal Flows ### Flow 1: Real-Time High-Severity Triage & Alert Escalation (Workday Focus Protection) 1. **Trigger**: School, teacher, or nurse publishes a communication or direct message. 2. **Action**: Background worker polls the ClassDojo API and ingests the raw event payload. 3. **Automated Response**: - Semantic triage agent inspects sender role (Nurse, Classroom Teacher, Principal), message content, and time sensitivity. - Evaluates against an urgent heuristic: `URGENT` vs `ROUTINE` vs `PROMOTIONAL_SPAM`. - If `URGENT` (illness, bus breakdown, safety incident, urgent same-day pickup change): Immediately dispatches an emergency notification via high-priority webhook/SMTP to both parents' active devices. - If `ROUTINE` or `PROMOTIONAL`: Suppresses push notifications and queues the content in the local SQLite database for the morning digest. 4. **Resolution**: Workday focus is fully preserved; true emergencies break through with zero latency. ### Flow 2: Shared Daily Logistics Synthesis & Morning Delivery (Family Synchronization) 1. **Trigger**: Scheduled cron job triggers at 6:45 AM on school mornings. 2. **Action**: Digest engine queries the local SQLite database for all events, posts, and teacher notes from the prior 24 hours plus upcoming 3-day calendar entries. 3. **Automated Response**: - LLM extracts **Action Items & To-Dos** (clothing requirements, supplies to pack, signed forms). - Extracts **Schedule & Dates** (early releases, teacher workdays, field trips). - Summarizes **Teacher Notes** (curriculum updates, individualized feedback). - Formats a clean, responsive HTML email with zero advertisements, upsells, or avatar badges. 4. **Resolution**: Both working parents receive identical, high-signal briefings simultaneously, eliminating the asymmetric mental load of managing school logistics. --- ## The Solution: Dojo Zen Architecture ```mermaid graph TD subgraph Upstream EdTech Noise CD[ClassDojo Cloud Services] -->|REST API / Cookie Session| RawFeed[Raw Feed: Posts, Messages, Stories, Upsells] end subgraph Dojo Zen Autonomous Pipeline RawFeed --> Ingest[Direct API Client / Session Manager] Ingest --> DB[(Local SQLite Store\ndata/dojo.db)] DB --> TriageAgent{LLM Semantic Triage Engine} TriageAgent -->|High Severity: Nurse / Bus / Urgent Alert| UrgentBranch[Real-Time Escalation Dispatcher] TriageAgent -->|Promotional / Gamification Spam| Drop[Drop / Purge Filter] TriageAgent -->|Routine School Info & Highlights| DigestQueue[Digest Queue] end subgraph Shared High-Signal Delivery UrgentBranch -->|Immediate Priority Alert| ParentsWork[Both Parents' Active Devices\nImmediate Workday Emergency Interruption] DigestQueue --> ScheduledCron[6:45 AM Morning Cron] ScheduledCron --> Formatter[Action-Oriented HTML Email Generator] Formatter --> SharedInbox[Both Parents' Inboxes\nShared 15-Second Morning Synchronization] end ``` --- ## Under the Hood (Technical Logic & Anti-Bloat Guardrails) ### 1. Direct REST API Ingestion & Session Persistence * Direct HTTP client communicating with `home.classdojo.com/api/session` with One-Time Code (OTC) authentication and cookie vault persistence, eliminating reliance on mobile app SDKs. * Optional headless browser fallback (Playwright) for handling occasional Cloudflare challenges. ### 2. Semantic Triage & Threat Classification Rubric * Inbound messages are evaluated against an urgency and actionability rubric: - **Class 1: Immediate Action Required** (e.g., *Nurse visit, injury, fever, bus route delayed >20 min, early pickup change, teacher asks for phone call*). $\rightarrow$ Instant priority dispatch ($<10$s). - **Class 2: Actionable Logistics** (e.g., *P.E. sneakers required, wear green tomorrow, library books, permission slip due*). $\rightarrow$ Categorized as morning digest action item. - **Class 3: Informational Highlights** (e.g., *Photo gallery of science project, art class update*). $\rightarrow$ Summarized in digest highlights. - **Class 4: Commercial/App Noise** (e.g., *Dojo Plus 50% off, monster avatar hat unlocked*). $\rightarrow$ Completely stripped. ### 3. Modern Co-Parenting Outcomes * **Zero App Opens:** Eliminates the need for either partner to keep the ClassDojo app installed on their phones. * **Shared Mental Load:** Both working parents receive identical, structured information, making morning logistics a frictionless team effort. * **Elimination of Monetized Guilt:** Completely insulates parents from predatory freemium upsells. * **Guaranteed Signal Integrity:** Critical safety and medical events receive immediate, dedicated alerting that cannot be silenced by notification fatigue. --- ## Izzyland: Generative Multimodal Game Creation & Real-Time Family Play - **URL**: https://herrington.ai/cujs/izzyland-generative-game/ - **Date**: 2026-09-14 - **Summary**: A Critical User Journey (CUJ) case study exploring how multimodal AI models (Google Gemini video), modern web game architecture, and rapid prototyping collapse the gap between a child's imagination and a production-grade interactive game in a single afternoon. # Izzyland: Generative Multimodal Game Creation & Real-Time Family Play *A Critical User Journey (CUJ) case study exploring how multimodal AI models (Google Gemini video), modern web game architecture (React 19 + Vite + Web Audio API), and rapid prototyping collapse the gap between a child's imagination and a production-grade interactive game in a single afternoon.* --- ## The Problem Space ### Context On a summer afternoon in 2026, sitting poolside in Florida, a father and his young daughter (Izzy) were discussing classic color-matching board games like *Candy Land*. Like many kids, Izzy loved the intuitive turn-based mechanics, but found the static legacy themes (Peppermint Forest, Gumdrop Mountain) disconnected from her real-life adventures and creative daydreams. She asked an imaginative question: > *"Why does Candyland only have Peppermint Forests? What if we had a game where we went to Miami with rollerblades, ate giant macarons under the Eiffel Tower in Paris, danced to DJ music on the beach in Ibiza—and what if Moe the dog got the zoomies?"* ### The Core Friction 1. **The Creative Consumption Trap:** Traditional media and video games position children as passive consumers of pre-rendered content. When a child has a spark of imaginative storytelling, there is no accessible bridge to turn that narrative into interactive software in real time. 2. **The High Barrier to Game Prototyping:** Historically, building a multi-scene animated game with custom video cutscenes, spatial audio, and interactive physics required weeks of specialized game engine work (Unity/Unreal), 3D asset modeling, audio engineering, and app store deployment overhead. By the time a traditional prototype could be built, the child's moment of inspiration had long passed. 3. **Static, Repetitive Mechanics & Anti-Climactic Finales:** Classic children's board games suffer from repetitive loops, lack of dynamic surprises, and anti-climactic endings (a static "You Win" screen). There is no tactile payoff or physical agency when crossing the finish line. --- ## Critical User Journeys (CUJs) ### CUJ 1: Real-Time Collaborative Co-Creation (Child as Creative Director) * **Statement**: I want to **turn my child's imaginative daydream into an interactive, playable digital game in real time** while avoiding **the weeks of complex game engine programming, 3D asset modeling, and animation rendering** so that **my child experiences the empowering agency of directing and immediately playing within her own fantasy world**. * **User Scenario**: Sitting poolside with an iPad and laptop, Izzy describes her dream world—rollerblading past neon palms in Miami, collecting alfajor truffles in Buenos Aires, dodging a hungry green T-Rex, and watching their family dog Moe sprint across the board. Her dad pairs with multimodal generative AI (Google Gemini video models) to synthesize 8 cinematic video cutscenes, write the deterministic game rules, and deploy a responsive web game before sunset. ### CUJ 2: Frictionless, High-Engagement Cross-Device Family Play * **Statement**: I want to **launch and play an engaging board game with my family instantly on any iPad or phone with zero app store downloads or logins** while avoiding **boring repetitive turns and static game-over screens** so that **players of all ages stay immersed with dynamic video landmarks, playful chaos events, and an interactive unicorn piñata finale**. * **User Scenario**: Izzy and her dad open a web link on their iPad. They take turns drawing color-coded cards, traveling across 64 pastel candy tiles, enjoying Gemini video cutscenes at landmarks, harvesting regional chocolates to cast freeze spells, laughing when dog Moe triggers a zoomies board scramble, and finally equipping the *Golden Mega Bat* to smash a physics-based unicorn piñata into a multi-stage fireworks confetti celebration. --- ## The Ideal Flows ### Flow 1: Rapid Multimodal Generative Pipeline (Poolside Co-Creation) 1. **Trigger**: Child brainstorms a unique landmark theme and dynamic hazard (e.g. *Ibiza Sunset Beach Club* + *Moe's Zoomies*). 2. **Action**: Parent prompts Google Gemini video models with specific mood, pastel palette, and animation directives while drafting React game state. 3. **Automated Response**: Generative video pipeline renders high-energy landmark cutscenes and sound cues; Vite HMR instantly reloads the game board state. 4. **Resolution**: Within 3 hours, a 64-tile interactive web game with 8 full video cutscenes and regional treat mechanics is deployed live to Firebase Hosting. ### Flow 2: Live Gameplay & Interactive Piñata Mini-Game Finale 1. **Trigger**: Player draws a card and lands on Tile 63 (*Izzy's Sparkling Castle Gate*). 2. **Action**: The game switches from board navigation to the interactive **Unicorn Piñata Finale Mini-Game**. 3. **Automated Response**: The Web Audio engine ramps up celebration fanfare; a floating 3D unicorn piñata appears with dynamic wobble physics and a reactive health bar. 4. **Resolution**: The player repeatedly taps/clicks using the *Golden Mega Bat* to land progressive-damage hits until the piñata explodes into confetti bursts, awarding jackpot chocolates and triggering the victory celebration. --- ## The Solution: Izzyland System Architecture ```mermaid graph TD subgraph Creative & Generative Input Izzy[Creative Director: Izzy\nNarrative & Landmark Lore] --> Prompts[Multimodal Prompts] Prompts --> Gemini[Google Gemini AI Video Engine\n8 Landmark Cutscenes] end subgraph Izzyland Game Engine Gemini --> Assets[Video & Audio Asset Bundle] Deck[Deterministic Card Deck Engine\nSingle/Double Colors & Landmarks] --> State[React 19 Game State Machine] Assets --> State State --> Board[64-Tile Candy World Map] State --> Economy[Regional Chocolate & Berry Economy] State --> Chaos[Chaos Engine: Moe Zoomies & Dino Hazard] end subgraph Interactive Payoff Board --> Tile63{Land on Tile 63?} Tile63 -->|Yes| Pinata[Interactive Piñata Mini-Game\nWobble Physics & Mega Bat] Pinata --> Confetti[Canvas Confetti Multi-Cannon Storm & Victory Fanfare] end ``` --- ## Under the Hood (Code & Game Logic) ### 1. Deterministic Card & Navigation Engine * **Approach**: Pure deterministic card deck model that supports standard color advancement (Pink, Lavender, Cyan, Lime, Gold, Peach), double-step cards, express transit shortcuts (Lisbon Tram, NY Elevator), and landmark warps. * **Key Mechanics**: - `drawCard()`: Calculates target tile index based on the next occurrence of drawn color or landmark destination. - `handleShortcut()`: Smoothly animates player token through express transit paths bypassing up to 9 tiles. ### 2. Generative Multimodal Video & Landmark Integration * **Approach**: Pre-cached Google Gemini video cutscenes tied to landmark tiles (Miami Art Deco, Buenos Aires Tango Plaza, Paris Macaron Walk, Ibiza Beach Club, Transylvania Castle, Disney Magic Kingdom). * **Key Mechanics**: - Modal overlay triggers responsive `