Docs / showcase.md · mirrored from the repo

Namaste Ji — the public showcase: the story site, the open console, and the Guide

Status: design v1.8 — COMPLETE, building. Every founder decision is in (2026-08-23): Karkhana confirmed, EN-first with i18n standards (SH-30), hero names every platform, images placed. Phase 0 of the ladder (§13) started 2026-08-23. Decided: host at namasteji.aiwithayushman.com (SH-15); the Guide is Ayushman Dash with the founder’s real photo (SH-5); the starter kit is deferred past launch (SH-12). Build by the PR ladder in §13. Design language locked to aiwithayushman.com (§8, SH-16). Decision IDs SH-*.

This is the plan for the public face of Namaste Ji: a story-driven site that explains what was built and why, for two audiences at once — people who just want to see it work, and engineers who want the architecture, the agents, the QA, the Cloudflare set-up, and a repo to start from. It reuses everything real (the running agents, the catalog, the back-office console in read-only form) and adds one new character: the Guide — the founder’s avatar, who walks visitors through it all as a game. Hosted on Cloudflare, like everything else.

0. TL;DR

One story, two doors. The site opens with the founder’s story in one breath — “My mom sends me a good-morning image on WhatsApp every day. So I built a team of AI agents that do exactly that.” — then offers two doors: See it (the product, the pictures, the pipeline running) and Build it (architecture, agents, QA, Cloudflare, a starter repo). Same narrative spine, two depths; a visitor can switch doors at any paragraph.
It’s an experience, not a site. Every chapter is a scene — scroll-driven, animated, data-fed — and the back-office is shown through bespoke public exhibits (the agent constellation, the pipeline river, the feed simulator, the Atlas graph, the strategy desk, the Heimdall QA theatre), each designed to make one concept land. The real console stays one click away (“see the real thing”, demo.namasteji.org, read-only) for those who want the unvarnished tool.
A performance is staged and rehearsed. The system is real — the agents, the pipeline, the QA, the console — and anything shown as live is live; but the scenes are rehearsed: curated data, generated imagery, hand-picked greetings (including the many rendered-but-not-yet-embedded ones), a clean lineage, a textbook scorecard. One site-wide “about this performance” note says so; nothing else needs a label.
The Guide is the founder (Ayushman Dash, real photo) as an RPG companion: no tour, no tutorial screens. The pages are intuitive and inviting enough that visitors do things — turn a knob, grab the river, redraw a sample, guess a flag — and the Guide notices and teaches on the go, in first person, witty, with a journal of discoveries and stamps. Entirely scripted and client-side — no LLM, zero tokens (SH-24/25). Honest, cheap, on-brand.
The starter kit is a separate public template repo, built for coding agents first: a coding agent given the repo + a .env holding only the keys the human must supply reaches a deployed, running app on Cloudflare in one session without asking anyone anything — AGENTS.md as the front door, one idempotent bootstrap, scaffolding commands, task runbooks, verification contracts. The site’s last chapter is that walkthrough (§9).
Cloudflare end to end: Astro (static-first, React islands) on Pages at namasteji.aiwithayushman.com for the story; the existing console on a second Pages custom domain (demo.namasteji.org) for the open BO; the Guide ships as static rules with the site (no backend); AI Gateway for every model call the product itself makes.

1. Why this, why now

Goal	What it means for the site
Show, don’t tell	The proof is the running system. The site should feel like looking over the founder’s shoulder at a live pipeline, not reading a pitch
Two audiences, zero compromise	A parent/friend/investor must get it in 60 seconds without a single acronym; an engineer must find the real design decisions, trade-offs and code in two clicks. Serving one badly to serve the other is the failure mode
The pipeline is the product (P-2)	The back-office console is a first-class surface, so it goes public as-is (read-only) rather than as screenshots
Credibility through honesty	Real data, real numbers, real failures (the Heimdall flags, the rejected shots). A demo that never breaks reads as a toy
Give something back	A blank-canvas repo + a walkthrough — the most useful thing a builder can leave other builders
Fun	The Guide turns documentation into a game. People remember what they played with

2. The audiences — two doors, one story (SH-1)

	Door A — “See it”	Door B — “Build it”
Who	Family, friends, non-tech founders, investors, journalists, the curious	Engineers, AI builders, Cloudflare devs, recruiters who read code
Wants	What is it, who is it for, does it work, can I try it, what do the greetings look like	How is it built, why these choices, how do agents talk, what’s the QA, how much does it cost, can I reuse it
Tone	Warm, plain words, images first, zero acronyms	Precise, opinionated, linked to docs + code, numbers
Proof	Greetings in a phone frame, the pipeline moving, a greeting’s “life story”	Architecture diagram, agent manifests, Langfuse traces, eval scorecards, the repo
Call to action	Try the app · Get the morning greeting · Share	Read the docs · Open the console · Clone the starter

Design rule: the two doors are the same pages at two depths, not two sites. Every story beat renders a See it layer (image/phone/animation + one sentence) and a Build it layer (the mechanism, the decision, the link). A persistent depth toggle (See it ⇄ Build it) is URL-state (?mode=see|build, remembered in localStorage) so a link shared by an engineer opens in Build mode. Each section also has “Why?” — one paragraph of rationale in the founder’s voice — visible in Build mode, offered by the Guide in See mode.

3. The story spine (SH-2)

The narrative is the same in both doors; only depth changes. Seven beats, each one page section (or sub-page when it earns it).

#	Beat	See it (what’s on screen)	Build it (what’s underneath)
1	The morning message — “Every day my mom sends me a good-morning image on WhatsApp.”	Her actual forwards (the founder shared six — the Hindi pencil-sketch मार्गदर्शन card, the Nag-Panchami Shivling, the cardinal with the anger/patience quote, the circus cellist, the farm-road girl, the pink daisies in a mug) arriving one by one in a WhatsApp thread, timestamps and all; then the phone tilts and the ritual is explained in one line. The family photo is the beat-1 hero (decided 2026-08-23; the founder supplied it — `apps/showcase/public/story/family.jpg`): mom at the railing, the lake behind, the founder beside her — this is who the messages come from.	The insight: hundreds of millions of people do this daily; the content is repetitive, often low-quality, and nobody is making it for them, in their language, with taste. Audience = next-billion, 35+, vernacular (P-6, P-7)
2	So I built a team — “Not one model — a small creative department of agents.”	The “org chart”: VP Content → Content Director → Content Creator → Heimdall QA → Events Calendar. Each with a face and a one-liner	The Agent Kernel (AGENT-KERNEL.md): one anatomy every agent instantiates — STM/LTM, calibrated stop, subagents-as-tools, prompts from Langfuse, Control DO gate. Why agents, why not one prompt
3	What to make next — “The VP reads the calendar, the strategy, and what already exists — and writes briefs.”	A real brief, rendered as a card: deity, festival, language, geography, the “why now”. The events calendar (380 events, all faiths)	Creative Head (CREATIVE-HEAD.md): portfolio of Content Briefs, diversity as the primary lever, versioned strategy artifact, cold-start bootstrap. The Zod contract. A real Langfuse trace
4	Making it — “Briefs become shots, shots become images, images become greetings.”	A live lineage: brief → shot → rendered image → staged greeting, as a horizontal “life story” with the actual pictures; the Studio pipeline strip moving	Content Director (expansion, dedup, Queue fan-out) → Content Creator (gpt-image-1 via AI Gateway, R2, Images variants, Cohere multimodal embed → Vectorize). Claim-at-enqueue, idempotent consumers, DLQ. What a batch costs
5	Keeping it honest — “Heimdall checks the work — cultural correctness, text on image, taste.”	A scorecard: a greeting, its score, what it was flagged for (e.g. the Buddha-in-an-Onam-card miss). Ship/flag/veto	Heimdall (CONTENT-PRODUCTION §12): stratified + risk-weighted + Wilson-sized sampling, metric evaluators as Langfuse prompts, veto enforced in code, the run-scoped publish gate. Why sample, why LLM-judge, why a hard veto
6	Getting it to you — “Your morning, your language, your taste — without ever being creepy.”	The consumer app in a phone frame (web-first v1, `app-staging`); the Feed Lab Atlas as a beautiful map of “what exists”	Distribution (DISTRIBUTION.md, FEED-SERVING.md): share-intent not watch-time (P-3), amplify the recipe not the dish (P-4), multi-interest medoids, server-side precompute, one isomorphic `rank()`. DPDP-by-design (EVENTS-AND-ANALYTICS.md)
7	Build your own — “Here is the canvas. Hand it to your coding agent.”	The Cloudflare set-up in one picture; “what broke and what I learned”; then the starter kit: “clone → add your Cloudflare token → tell your agent `bootstrap` → a running app by lunch” — shown as a real terminal recording	The starter kit (§9): Kernel + example pipeline + console shell + Alchemy + CI + local mesh, agent-first; the full docs mirrored on the site (SH-14); costs; decisions

Hero line (draft, founder voice):

My mom sends me a good-morning image on WhatsApp every single day. So I built a small team of AI agents — on OpenAI, Sarvam, Cohere and Cloudflare — to do exactly that, for everyone’s mom.

(Decided: the hero names the platforms — OpenAI, Sarvam, Cohere, Cloudflare — “because that’s the whole point”. Alternative last clause: “…for the next billion moms.” — warmer, but check it doesn’t read as exclusionary; the product is for everyone 35+ who starts the day this way.)

3b. The exhibits — the back-office as a performance (SH-17)

The founder’s brief: “an experience, almost like a performance — artistic, stylish, creative storytelling — wow, and very simple.” So the public BO pages are not the console restyled; they are bespoke scenes that each make one concept land, built on the same read APIs (and the same isomorphic code where it exists). Each exhibit: one idea · one hero interaction · real data · a “see the real thing” door to the console page it mirrors · the Guide on hand.

Exhibit	The concept to land	The scene (what the visitor sees & does)	Data
/agents — the constellation	It’s a team, not a model.	A dark-to-light reveal: five agent “stars” (VP Content, Director, Creator, Heimdall, Events Calendar) arranged as an org/constellation; edges = what flows between them (briefs, shots, assets, scores, events). Pulses travel along edges from real recent runs (a render that just happened sends a spark Creator→Heimdall). Hover = role in one line + what it reads/writes; click = the agent card (manifest v, autonomy, last run, tokens, its playbook excerpt). The Control DO appears as a quiet ring: a human can pause any of them.	`/api/agents`, `/api/agents/runs`, manifests
/studio — the pipeline river	Briefs become shots, shots become images, images become greetings.	A horizontal river flowing left→right: brief cards dissolve into shot cards, shot cards bloom into real thumbnails (rendered), thumbnails gain an “embedding” halo, then settle as staged greetings. Counts per stage as live numerals; the river’s flow speed = real throughput. Click any droplet → its lineage (brief → shot → asset, with the actual prompt text and the image). A “rerun failed” eddy shows what failure looks like (real failed shots, labelled).	`/api/content/overview`, shots/assets/briefs, lineage
/lab — the feed simulator & the Atlas	Diversity is the product; the LLM writes the policy, never serves the feed.	Simulator: three phone frames, three personas (from the Personas library), the same policy. Turn the policy knobs (diversity λ, novelty, festival ramp) and all three feeds re-rank live in the browser — the actual isomorphic `rank()` from `@namaste-ji/feed` running client-side (FL-1). Atlas: the content graph as a force-directed cluster map (real Cohere embeddings → precomputed layout), medoid mosaics, a diversity meter (ILD) that moves as you drag λ; the “zero-`en` Shiva/Ganesha” gap glows as an example of what the gap-finder catches.	Feed Lab APIs, `rank()`, Atlas layout JSON, personas
/strategy — the strategy desk	One versioned document drives everything.	The content strategy artifact as a desk: the document (headings fold/unfold), a festival timeline (the 380-event calendar, all faiths, as a year strip), a map of India lighting geographies by planned coverage, a language split (hi/en/hi-Latn). Version scrubber: watch `strategy@v1 → vN` diff — what the VP changed and why.	`/api/global-context(+history)`, events-calendar
/qa — the Heimdall theatre	Quality is sampled, measured, judged — and a human can veto.	Act 1 Scoping: the population (all staged greetings) → a candidate set (filters) → stratified + risk-weighted + Wilson-sized sample animates as dots being drawn from strata (the math shown as a one-line caption: n for 95%/±5% with FPC). Act 2 Metrics: pick any greeting; its scorecard builds metric by metric (radar/bars — one hue), the text-on-image metric highlights the overlay region, the cultural metric explains itself. Act 3 The judge: ship / flag / veto — a flagged card slides into the inbox with its reason; a veto is enforced in code (a lock icon, not a suggestion). Act 4 The gate: the run-scoped publish gate — what ships, what stays back, rollback. A gallery of real flags (the missing-overlay-text defect, the Onam/Buddha cultural miss) and real rejects (the 1,262 textless renders as “before”), all labelled.	`/api/eval/runs/:id`, scorecards, flagged, candidates

Design rules for exhibits: one hue for magnitude (dataviz rules already used in the BO); real thumbnails everywhere an image can carry the page; every scene has a static fallback (no motion, reduced-motion, small screens) that still tells the story; every scene ends with “See the real thing →” (the matching console page on demo.namasteji.org) and “Why? →” (Build mode).

3c. The Build-it track — top-down, graphical, the same performance (SH-22, SH-23)

The technical reader gets the same creative grammar as the exhibits — scenes, motion, real data — but organised top-down: one picture of the whole system, then zoom. Never a wall of text; never cluttered; every level answers what, why, and go deeper.

The spine: one zoomable system map. /build opens on a single picture — user · consumer app · feed serving ← catalog ← production plane (the agents) ← control plane (the console, the Control DO) — with data flowing along the edges. Every deeper page is a zoom into a region of that same picture (a breadcrumb System › Plane › Component keeps the reader oriented), so the mental model is built once and refined, not rebuilt per page.

Zoom	Page	The concept to land	The scene
0	/build	The whole thing fits in one picture.	The system map, animated: a greeting’s journey lights the path from brief to phone; hover any region for its one-line job; click to zoom. Three “why” pins: two planes, the spine, the human gate
1	/build/architecture	Two planes, one spine, a human can pause anything.	The production plane and the control plane slide apart; the catalog (D1 · R2 · Vectorize) is revealed as the spine both lean on; the Control DO appears as the ring every agent runs inside (auto ⇄ manual). Decisions D1–D8 as pins, each a sentence + “go deeper”
2	/build/cloudflare	Everything Cloudflare — and here is exactly how it’s wired.	A living substrate diagram generated from `infra/alchemy.run.ts` (SH-23): Workers · Queues (+DLQ) · D1 · R2 · KV · Vectorize · AI Gateway · Pages · Access · Secrets Store · Durable Objects · Images — each a tile, edges = bindings; pulses show a render job hopping Queue→Worker→R2→Images→D1→Vectorize. Side rail: why CF (one runtime, one bill, edge-native, no ops), where it isn’t (Langfuse; OpenAI/Cohere/Sarvam — but through the Gateway, so they’re observable and swappable), what it costs (real numbers), gotchas we hit (free-plan SSL depth, the rapid-deploy skew, Queue batch timeouts)
3	/build/agents	Every agent has the same anatomy; every model is a config value.	Exploded view of the Kernel: STM (working memory) · LTM (memory port) · tools · subagents-as-tools behind a context firewall · calibrated stop · prompts from Langfuse (`name@label`) · the Control DO gate — assembled piece by piece on scroll. Then the provider switchboard: a role (e.g. stm_writer) wired to OpenAI; flip the switch → Sarvam → Workers AI; the screen shows the actual KV config diff (`"provider": "sarvam", "model_id": "sarvam-105b"`) and the Gateway route change — nothing redeploys. Then easy to manage: the manifest, the Agent Hub, autonomy modes, a real run timeline with tokens/tools. Then the workbench (SH-28): pick an agent → its tools laid out as cards (name, purpose, input schema — the real Zod), its prompts — the actual Langfuse prompts, full text, versioned (`name@label`, a version scrubber, diff between versions), the manifest (autonomy, budgets, stop rules) and one real trace (turn by turn: prompt → tool call → result → STM write). Tools/SDKs named plainly: Agents SDK, Vercel AI SDK, Zod contracts, Langfuse, AI Gateway
4	/build/qa	Why QA exists, and how Heimdall is built.	Why — the origin story as data: the 62% missing-overlay-text finding (real before/after cards), “pretty images that don’t forward are worthless”. How — the engineering mirror of the /qa theatre: population → candidate set → stratified/risk-weighted/Wilson-sized sample (the formula, animated), metric evaluators as versioned prompts (one shown), the LLM judge, veto enforced in code (the actual guard, highlighted), feed-forward of findings into the Creator’s guardrails, the run-scoped publish gate + rollback. What it doesn’t catch yet
5	/build/tooling	How the tools connect — and how this repo is itself built by agents.	The dev loop as a circuit: repo → CI (typecheck/tests/secret-scan) → deploy-on-merge (path-scoped) → Alchemy IaC → staging; model calls → AI Gateway → providers; prompts/traces → Langfuse; MCP servers (GitHub · Cloudflare · Langfuse · Notion) wired into the coding agents; the local mesh (Docker Compose + local LLM). The meta-point, said once: this whole system is built by coding agents with the founder in the loop — the same way the product runs.
6	/build/feed · /build/data	Diversity is the objective; privacy is architecture.	Feed: the three loops (offline brain · per-user slates · on-device re-rank), the isomorphic `rank()`, LLM writes the policy never serves the feed. Data: state/stream/features split, the DPDP-by-design choices (consent, minors, pseudonymous events) — shown as a flow, not a policy document
7	/build/starter	Hand it to your coding agent.	§9, as a terminal recording

Rules for the track: top-down always (a reader who stops at zoom 0 still has the right picture); one graphic language across all zooms (same tiles, same edge style, same pulses — the map is a component, not seven drawings); diagrams generated from source where the source exists (infra → Alchemy file, agent anatomy → manifests, tooling → repo config; SH-23) so they can’t lie; “Why?” is a first-class element on every zoom (the decision ID, one sentence, the trade-off we rejected); “Go deeper” → /docs/* (SH-14) and, where it helps, the exact file path.

4. Site map & IA (SH-3)

namasteji.aiwithayushman.com/       Story (one long page, 7 beats, depth toggle)      Astro
├── /try                            Consumer app embed/link + "get tomorrow's greeting"
│                                   ── THE EXHIBITS (§3b): bespoke, animated, data-fed public BO pages ──
├── /agents                         The constellation: every agent + how they're linked (live pulses)
├── /studio                         The pipeline river: briefs → shots → images → embeds → staged
├── /lab                            Feed Lab: simulated feeds + the recommender's knobs; Atlas graph + diversity
├── /strategy                       The strategy desk: the versioned content strategy, calendar, map
├── /qa                             Heimdall theatre: sampling, metrics, the judge, what a flag does
├── /design                         Design system + why it looks like this (festive, never gaudy)
├── /build                          THE BUILD-IT TRACK (§3c): the system in ONE zoomable picture — the spine
│   ├── /build/architecture         Zoom 1: the two planes, the spine, the Control DO gate — and why
│   ├── /build/cloudflare           Zoom 2: the substrate as a living diagram (generated from infra/), why CF, where not, costs
│   ├── /build/agents               Zoom 3: anatomy of an agent (Kernel exploded view) + the provider switchboard
│   ├── /build/qa                   Zoom 4: why QA, how Heimdall is built (the engineering mirror of /qa)
│   ├── /build/feed                 Feed Lab + serving design
│   ├── /build/tooling              How the tools connect: Gateway · Langfuse · MCP · CI · Alchemy · local mesh
│   └── /build/starter              The starter kit walkthrough ("hand it to your coding agent")
├── /docs/*                         The repo's docs/**, rendered at build time (SH-14) — "Go deeper" lands here
├── /console  →  demo.namasteji.org "See the real thing": the OPEN back-office (read-only, public role) — §5
└── /guide                          The Guide's own page: what it is, how it works, its tour graph

Rules:

The story page is the product. Sub-pages are depth, reached from a beat; every sub-page starts with its beat’s See-it sentence so nobody lands cold.
Every Build-it page ends with “Go deeper”: the canonical doc(s) + code paths. The site retells, the repo remains the source of truth (no duplicated architecture prose to rot). Because the repo is private (free plan), “Go deeper” links land on /docs/* — the repo’s docs/**/*.md rendered into the site at build time (SH-14): one source, two renderings; the day the repo goes public the same links can point at GitHub.
Live where it can be live: counts, the lineage explorer, scorecards, the Atlas come from the public read API (§5). Static where live adds nothing (diagrams, decisions).
Shareable deep links everywhere (URL state for mode, beat, guide step) — same rule as the BO.

5. The open console — “see the real thing” (SH-4)

The exhibits (§3b) are the experience; the console is the unvarnished tool one click behind them — real BO, read-only, for anyone who wants to see the actual operator surface. The already-agreed plan (2026-08-22), restated:

Host: demo.namasteji.org (first-level subdomain — free-plan SSL rule). Same Pages project + same console-api Worker, extra custom domain + /api/* route. Not behind Access. bo-staging untouched. Points at staging data (the real catalog, ~4.4k shots, the briefs, eval runs).
Identity: on the demo host console-api ignores every identity header (the Access header is client-controlled there) and assigns a synthetic public@demo identity with a new public role = content:read · brief:read · eval:read · temple:read · lab:view · agent:view — deliberately not audit:read (operator emails) — and rejects every non-GET on that host at the transport level. Read endpoints reachable with those perms get a leakage review (config/gateway URLs/model settings) before launch.
UI: a persistent “Read-only demo” banner; nav shows only what the role can open; a can(perm) sweep hides write controls (today only ~11/32 pages gate them). Landing route explains what the visitor is looking at — and hands over to the Guide.
Which surfaces, in priority: Dashboard → Studio (the pipeline strip + lineage) → Heimdall QA (runs, insights, a scorecard) → Agent Hub (agents + run timelines) → Strategy (the versioned strategy artifact) → Feed Lab (Atlas, Search, Feed side-by-side). Hidden: Users, Settings, Audit, Pipeline, Temples, Review.
Guardrails, since there is no gate: WAF rate-limit on the demo host, Bot Fight Mode, cache headers on image/thumb responses (egress is the only variable cost), the /assets guard already in place (public/_worker.js).
Rejected: Access “Everyone”+OTP (50-seat cap), hand-adding viewers, any login. Safety comes from the RBAC deny-by-default layer, not from a login.

6. The Guide — learn by doing, like a good RPG (SH-5, SH-24 … SH-27)

6.1 The idea

Not a tour. Good games never stop you to explain; they hand you something irresistible to try and a companion who reacts to what you just did. So: the exhibits are the game — every scene has an affordance that begs to be touched (a knob, a draggable λ, a river you can grab, a sample you can redraw, a greeting you can guess about) — and the Guide is the companion: Ayushman, in the corner, who notices your action and says the one thing worth knowing right then. Teaching is a consequence of play. If a visitor never touches anything, they still get the story; if they touch everything, they’ve learned the system without reading a manual.

Founder’s direction (2026-08-23): “Like in RPG games you play and the game teaches you on the go… the apps we show should be intuitive and wow enough for users to do something, and we teach them on the go.” And: no free-form Q&A — no tokens burned.

6.2 Persona & voice

Who: Ayushman Dash — real photo (apps/showcase/public/guide/ayushman.jpg), circular avatar, purple ring (your brand; §8), speech bubble in Space Grotesk. First person, present tense, reacting: “You just turned diversity all the way up — notice the three feeds stopped agreeing? That’s the whole point.”
Tone: Caregiver × Jester, tilted to Jester; short lines, one idea per bubble; never blocks the page; never repeats itself; quiet by default — it speaks when you do something, not on a timer (one exception: a single gentle nudge if you’re idle on an exhibit, §6.3).
Honesty rules (unchanged, SH-7): every number in a line is interpolated from the page’s live state or the API — the Guide never types a number from memory; it says when a scene uses labelled demo data (SH-21); it admits what the system doesn’t do yet.

6.3 Mechanics (the design)

Mechanic	What it is	Why
Triggers, not steps	A rule table: `on <event>` → `say <line>`, with context. Events are the visitor’s real actions: `lab.knob.diversity.changed{value}`, `lab.personas.disagree`, `studio.droplet.opened{stage}`, `studio.river.paused`, `studio.failed.found`, `qa.sample.redrawn{n}`, `qa.guess.correct	wrong{metric}`,` qa.veto.revealed`,` agents.edge.hovered{from,to}`,` agents.pause.toggled`,` build.switchboard.flipped{provider}`,` build.prompt.opened{name,version}`,` story.beat.reached{n}`,` idle{page,20s}`,` first.visit{page}`. Each rule:` once`/`cooldown`,` priority`,` page`,` mode`
Diegetic affordances	Every exhibit ships with 1–3 deliberately touchable things (the knob, the λ slider, the grab-able river, the redraw button, the “which one gets flagged?” choice, the agent pause ring, the provider switch, the prompt drawer). The UI itself invites; the Guide only comments	“Intuitive and wow enough to make people act” is a page-design requirement, not a Guide feature
Nudge before, not tutorial before	First time on an exhibit: one short, dismissible line pointing at one thing to try (“Drag that slider — I dare you”). Idle 20s → one hint. Never a modal, never a 5-step walkthrough	Guidance where needed, zero friction otherwise
Discoveries journal	A side sheet that fills as you do things: “You made two personas disagree”, “You traced a greeting to its brief”, “You found the veto lock”, “You swapped a model without a redeploy”, “You read the VP’s actual prompt”. Each discovery = a stamp (Namaste Ji gold, §8.2) + the one-paragraph “why” in the founder’s voice. A completion meter; no prescribed order; shareable discovery card	Progress and pride without quests-as-homework; the journal is the curriculum, filled by play
Set pieces (“boss moments”)	Per exhibit, one small game with a win state: Lab — make Priya and Ramesh agree (tune the policy until two personas’ top card matches → teaches relevance vs diversity); QA — beat Heimdall: three greetings, guess which gets flagged and for what, then the real scorecard reveals; Studio — catch the failed shot in the river and rerun it (labelled demo); Agents — pause the Creator and watch the river stop (the human gate, felt not read); Build/agents — flip the provider and see the KV diff. Winning = a rare stamp + one “why”	The parts people remember — and exactly the concepts we most want to land
Hint on demand	One `?` button: the single scripted hint for where you are (what to try here). Not a menu, not a chat	Replaces free-form Q&A at zero cost
Ending	All discoveries → the “Chai with the builder” card (links, the starter kit, a thank-you in the founder’s voice)	A finish line
Quiet mode	One toggle mutes the Guide; `prefers-reduced-motion` respected; everything skippable	Respect

6.4 How it’s built — client-side, scripted, zero tokens (SH-25)

Piece	Choice	Why
Widget	`packages/guide` — a React island; mounts on the story site and the exhibits (same component, same event bus)	One implementation; pages emit events, the Guide subscribes — pages never know what it will say
Script	Versioned Markdown with YAML frontmatter (`apps/showcase/guide/*.md`): `trigger`, `once`, `cooldown`, `priority`, `page`, `mode`, `discovery`, `stamp`, `says` (with `{placeholders}` filled from event context), `why`. Compiled to JSON at build; the founder edits the jokes in a PR	Reviewable, diffable, deterministic; the repo’s Markdown-artifact convention
Event bus	A tiny typed emitter (`guide.emit('qa.veto.revealed', {...})`) — exhibits call it at their affordances	Decoupled; testable (a rule table can be unit-tested against an event log)
State	localStorage: fired-once rules, discoveries, stamps, quiet mode; `?guide=off` / `?discovery=<id>` URL state for sharing	No accounts, no backend
Backend	None for v1. No LLM, no Vectorize index, no session DO, no budgets. Optional later: an anonymous discovery-completion beacon to a Worker for aggregate funnel stats	Zero token spend; nothing to abuse; nothing to operate
Copy volume	~60–100 rules across the story + exhibits + Build track at launch; each line ≤ 140 chars, each “why” ≤ 60 words	Enough to feel alive, small enough to keep sharp

6.5 What this replaces

The v1.0 design had a scripted tour plus LLM free-form “Ask me” (Hono+DO, Vectorize over docs, budgets, Sarvam). Dropped on the founder’s direction: no free-form Q&A, no tokens burned; the ? hint and the discovery “why” cover the need. The docs mirror (/docs/*, SH-14) remains the place for real depth.

7. What to show where — the evidence inventory (SH-10)

Everything real, everything read-only. The showcase does not create content; it exhibits it.

Evidence	Source	Where it appears
Real greetings (images + captions, hi/en/hi-Latn) — including the many `rendered`-not-yet-embedded ones (founder: use them freely)	catalog D1/R2 via public read API (`rendered`/`staged`/`scored`/`published`; `rejected`/vetoed only inside the QA exhibit, labelled)	Hero strip, /try phone frame, the pipeline river, the lineage explorer, everywhere an image can carry the page
Mom’s real forwards (the six images the founder shared — what actually arrives every morning)	founder → `apps/showcase/public/story/mom/*.jpg`	Beat 1’s WhatsApp thread, shown exactly as received (decided 2026-08-23) — watermarks and all; that is the truth of the ritual. No recreation, no cropping of anything meaningful
Generated scene art (hero illustrations, the river, the constellation backdrops, stamps)	`apps/showcase/scripts/gen-art.mjs` → gpt-image-1 via AI Gateway (same renderer as the product), prompts versioned in repo, outputs committed	Scenes, stamps, OG images
Rehearsed demo data (a clean lineage, a textbook scorecard, three personas, a tidy eval run)	`apps/showcase/data/*.json` snapshots, curated by hand from staging	Any scene where live data is too messy to teach — the norm for exhibits (SH-21)
A brief (the Zod-validated JSON, rendered)	`/api/content/briefs/:id`	Beat 3, /agents/creative-head
Brief → shot → asset lineage with pictures	`/briefs/:id/lineage`	Beat 4, /pipeline
Pipeline counts, live	`/api/content/overview`	Story beat 4 strip, open console Dashboard/Studio
A Heimdall run: sampling provenance, scores, flags, the veto logic	`/api/eval/runs/:id`, scorecards	Beat 5, /qa, open console Heimdall
Agent runs: timeline, tokens, tool calls, STM excerpt	`/api/agents/runs/:id`	Beat 2/3, /agents, Agent Hub
A Langfuse trace (screenshot/recording, not live)	Langfuse	/build/agents
The strategy artifact (`strategy@vN`)	`/api/global-context`	/agents/creative-head, Strategy page
Events calendar (380 events, all faiths)	events-calendar via console-api	Beat 3
Atlas (cluster map), Search bench, Feed side-by-side	Feed Lab	Beat 6, /build/feed, open console
Architecture diagrams (Mermaid → SVG)	docs/SYSTEM-DESIGN, INFRASTRUCTURE	/build/*
Decisions with IDs (D-, CP-, FL-, FS-, SH-*)	docs	/build/* “Why” blocks
Costs: what a batch of N greetings costs, what the site costs to run	measured	Beat 4 Build-it, /build/cloudflare
Failures & lessons (the 62% missing-overlay-text finding; the poisoned-cache saga)	memory/docs	/build — “what broke” — credibility
The family photo (optional hero)	founder	Beat 1 — only with consent (§14)

8. Design language — the host brand is yours, Namaste Ji is the exhibit (SH-11, SH-16)

The site lives on aiwithayushman.com, so it must feel like your site — and Namaste Ji must still look like Namaste Ji. The rule that reconciles them: your brand is the chrome, Namaste Ji’s brand lives inside the frames. (Read from the live site 2026-08-23: Framer, white ground, Space Grotesk, purple accent, playful hand-drawn stickers, photo-forward hero.)

8.1 Carry over from aiwithayushman.com (the chrome)

Element	Your site	Showcase rule
Ground	White `#FFFFFF`; soft sections `#FAFDFF` / `#F2F5F8`; hairlines `#E2E7EC`	Same. Light, airy, lots of whitespace; no warm-paper ground here (that’s Namaste Ji’s)
Ink	`#171A1F` text; secondary `#495460`; muted `#7F8995`	Same
Accent	Purple `#7852D9` — the emphasised line in headings (“No Code, No Math”), CTAs, tags	The one emphasis hue of the site: the depth toggle, primary buttons, the highlighted clause in each beat’s headline, link hover. The Guide’s avatar ring is purple — the Guide is you, not the product
Secondary accents	Warm orange `#FB9C2A`, marker yellow `#FFF48C`/`#FFE500` (the hand sticker), blue `#0099FF` (links), cream `#F7E8D3`	Yellow = hand-drawn marker language for the Guide’s hotspots/circles/arrows (your sticker style, reused); orange = the bridge to Namaste Ji’s Sunrise Orange — allowed only next to an exhibit; blue for inline links; cream for callouts
Type	Space Grotesk for everything (H1 48px/700/−1.5px, H2 48/700/−2px, H3 24/700/−0.5px, body 18px/400/1.56); Inter for small meta; Fragment Mono for code/labels	Space Grotesk display + body; Fragment Mono for eyebrows, stats, IDs, and everything in Build mode’s metadata (a quiet “engineer” texture); Inter for tiny meta only. Google Fonts with system fallbacks
Shape & motion	8–10px radii, pill-ish CTAs with an emoji, hand-drawn stickers, big photo of you, calm layout	Same radii; CTAs may carry one emoji (🚀/✨ — your convention); stickers only as Guide hotspots and stamps; motion calm and purposeful
Voice	Plain, direct, teacher-warm (“You have come to the right place”)	The See-it door speaks exactly like this; Build-it adds precision, not jargon

8.2 Namaste Ji inside the frames (the exhibit)

Wherever the product appears — greeting images, the phone frame, the open console, the sun mark, stamps — it keeps its own system untouched: warm paper, Sunrise Orange, gold once, Poppins/Inter, charcoal ink (PHILOSOPHY P1/P2). The console is embedded/linked as-is, never restyled; screenshots are real.
Stamps (quest badges) are Namaste Ji artefacts → they may use the brand gold; the Guide is you → purple ring, Space Grotesk bubbles, marker-yellow hotspots.
The morning-gradient / festive motifs stay inside exhibits; the page around them stays white.

8.3 Creative motifs worth keeping (optional, founder’s call)

Photo-forward hero like your site — decided: the family photo is the hero (mom at the railing), the beat-1 copy beside it; your headshot is reserved for the Guide.
The WhatsApp bubble as a recurring shape for quotes/asides — it’s the story’s origin object.
Marker annotations (your yellow hand) as the Guide’s way of pointing at real UI.
Mono “receipt” blocks in Build mode: costs, counts, run ids in Fragment Mono — reads like a lab notebook, not a sales page.

8.4 Motion & art direction — “a performance” (SH-18, SH-19)

Scenes, not sections. The story page and each exhibit are choreographed as scroll-driven scenes: pinned stages, scrubbed timelines, elements that arrive with purpose. One choreography library — GSAP + ScrollTrigger (free since 2025) — for scene timelines; Motion (framer-motion) for component micro-interactions; d3 for the graph/force layouts (already in the console); canvas where SVG would choke (the Atlas at 700+ nodes). Optional smooth-scroll (Lenis) only if it earns its keep on mid-range phones.
Motion has a budget. prefers-reduced-motion → static storyboard of the same scene; small screens get a lighter choreography, never a broken one; first-paint stays static (hero text + one image) so Lighthouse stays ≥95.
Art is generated, versioned, and on-brand — generate freely. Scene art (hero illustrations, river/constellation backdrops, stamps, OG cards, any picture a scene needs) is produced by apps/showcase/scripts/gen-art.mjs — gpt-image-1 through the AI Gateway, the product’s own renderer — from prompts checked into the repo, and the outputs are committed (no runtime generation, no surprise spend). Style brief for the prompts: pencil-and-watercolour warmth (the same register as mom’s मार्गदर्शन card), white space, one accent; never stock-photo gloss. Real greetings from the catalog are always preferred over generated art when a real image can do the job.
The greeting image carries the page. Big, real, many. The thumbnails are the decoration.
Images: quality is paramount, then speed (SH-29). Every raster asset (mom’s forwards, the family photo, the headshot, generated art, catalog greetings served by the site) goes through one build-time pipeline: originals kept lossless in the repo (public/…/src/), served as AVIF + WebP at high quality (AVIF q≈75–80 / WebP q≈85, never “web-crushed”) with JPEG fallback, responsive srcset at 480/960/1440/2048 widths, exact-size width/height to kill layout shift, lazy below the fold, eager + fetchpriority=high for the hero, LQIP/ThumbHash placeholders where the product already has them. Hero-grade images (family photo, forwards) get a visual check at 2× before shipping; if a format visibly softens text on a forward, that image ships as a larger file instead. Catalog images keep coming from the console-api (/image?variant=) with long immutable caching.
Sound: none by default; an optional, opt-in ambient layer is a v2 idea, not a launch item.

8.5 Token stub (phase 0 creates `apps/showcase/src/styles/tokens.css` from this)

--sc-bg:#FFFFFF; --sc-bg-soft:#FAFDFF; --sc-bg-alt:#F2F5F8; --sc-border:#E2E7EC;
--sc-ink:#171A1F; --sc-ink-2:#495460; --sc-muted:#7F8995;
--sc-accent:#7852D9; --sc-accent-hover:#6A46C9; --sc-warm:#FB9C2A; --sc-marker:#FFF48C; --sc-link:#0099FF; --sc-cream:#F7E8D3;
--sc-font-display:'Space Grotesk'; --sc-font-body:'Space Grotesk'; --sc-font-mono:'Fragment Mono'; --sc-font-meta:'Inter';
--sc-radius:8px; --sc-radius-lg:12px;

Namaste Ji exhibits import docs/design-system/tokens.css unchanged; the two token sets never mix on one element.

9. The starter kit — a blank canvas built for coding agents (SH-12)

Founder, 2026-08-23: “The repo would be for coding agents, not just for humans. Any coding agent should be able to take the boilerplate and kickstart an app on Cloudflare swiftly. Just the necessary API keys to be provided by the users and that’s it.” That sentence is the spec.

9.1 The success criterion (what “done” means)

A coding agent (Claude Code, Codex, Cursor, Gemini CLI…) is given only the repo and a .env containing the keys the human must supply. Without asking a human anything, in one session, it reaches: Cloudflare infra provisioned · the example pipeline running on staging · the console showing a rendered card · green checks · and it can then add a new agent with one command.

Everything below exists to make that sentence true.

9.2 Agent-first design principles

#	Principle	In practice
K-1	`AGENTS.md` is the front door	The first file any agent reads: what this is, the invariants, the ONE bootstrap command, the scaffolding commands, the verification contract, the task runbooks index. `CLAUDE.md` is a one-line import of it (same convention as this repo); nothing important lives only in prose for humans
K-2	One idempotent `bootstrap`	`npm run bootstrap` reads `.env`, then: install → Alchemy provisions D1 · KV · R2 · Queues · Vectorize · AI Gateway · Secrets Store (account-pinned) → migrations → config-KV seed → wrangler envs written → deploy staging → smoke test → prints the URLs. Re-runnable; resumes where it stopped; `npm run doctor` explains exactly what’s missing (token scopes, account id, a key) in agent-readable form
K-3	Every external dependency is configurable and user-supplied — the kit owns no accounts	`.env.example` lists every external dependency with required/optional and what unlocks what: Cloudflare (`CLOUDFLARE_API_TOKEN` + account id — required; it’s the user’s account), model providers (`OPENAI_API_KEY` / `COHERE_API_KEY` / `SARVAM_API_KEY` — optional; default roles run on Workers AI in the user’s own account via the Gateway, so the Cloudflare token alone suffices), observability (Langfuse keys — optional), search (Tavily — optional), MCP tokens (optional). Ports + KV model config (the house pattern) make every one swappable without code changes. Nothing in the kit points at the founder’s accounts, ids or keys
K-4	Scaffolding commands, not file archaeology	`npm run new:agent <name>` (a Kernel instance: manifest, inline starter prompts, wrangler env, CI workflow, console registration, a test) · `new:consumer <name>` (a queue consumer) · `new:page <name>` (a console page with RBAC guard + URL state) · `new:port <name>` (a port + stub adapter). Deterministic output; each prints the follow-up checklist
K-5	Verification contracts	`npm run check` (typecheck + tests + lint + secret-scan) and `npm run smoke` (hits the deployed endpoints). CI runs exactly these. “Done” = both green; agents are told so
K-6	Task runbooks as Markdown with frontmatter (`tasks/*.md`)	“Add an agent”, “add a tool to an agent”, “add a queue stage”, “add a console page”, “switch a role to OpenAI”, “deploy prod” — each: goal, exact files/commands, acceptance criteria. The Guide’s last quest walks the first one
K-7	Safety rails for agents	`.env*`/`.dev.vars`/`.mcp.json` gitignored from day one; pre-commit + CI secret scan; `doctor` refuses prod without `--prod --i-know`; keys never written into tracked files; Secrets Store mapping documented; local dev uses the mock identity header only in `local`
K-8	MCP-ready	`.mcp.json.example` for the Cloudflare + GitHub MCP servers (tokens inline by the human — same lesson as this repo); `AGENTS.md` tells the agent which MCP to prefer for which job
K-9	Runs without the cloud too	`npm run dev` = the local mesh (wrangler dev for each worker, optional docker-compose, stub renderer/embedder, local D1/KV) — no keys needed to see the pipeline move locally
K-10	Generated, never hand-forked; verified without owning any account	`scripts/export-starter.mjs` in this monorepo (allow-list + transforms: strip brand/prompts/ids, insert placeholders) → pushes to the public repo on manual dispatch. The public repo’s CI proves the promise without a scratch Cloudflare account (founder: none will be created): `npm run check` · `bootstrap --dry-run` (Alchemy plan + config validation, no cloud calls) · a local end-to-end on workerd/miniflare (the mesh boots with stubs, the example pipeline emits a brief → renders a stub card → the console lists it). The first real cloud bootstrap is always run by the user (or their agent) on their account; the founder may run it on his own account before a release, by hand

9.3 What’s in the canvas

In (from this monorepo)	Out
`packages/agent-kernel` (the Kernel) · `packages/shared` (versioned Zod contracts) · `packages/config` (KV config + defaults) · `packages/rbac`	The brand, the strategy playbooks, the Langfuse prompt library (replaced by inline starter prompts; Langfuse optional), our account ids
Example pipeline “Daily Card”: a calendar agent (events) → a creative agent (briefs) → a render consumer (Workers AI image by default; gpt-image-1 if keyed) → a catalog (D1/R2) → a tiny QA stub with the sampling design linked	Heimdall proper, Feed Lab, the real renderers/embedders as defaults
The console shell (AppShell, Access/RBAC guard, Agent Hub skeleton, a Studio-style strip, the chunk self-heal + `/assets` guard)	Temples, Heimdall UI, Feed Lab pages
`infra/` Alchemy (account-pinned) · CI (check/smoke/deploy-on-merge, path-scoped) · local mesh · `RUNNING-LOCALLY.md`	—
`AGENTS.md` · `CLAUDE.md` · `tasks/*.md` · `.env.example` · `.mcp.json.example` · the scaffolding scripts	—

9.4 Naming & license

Karkhana (कारख़ाना — the workshop; where things get made) — confirmed 2026-08-23. It says what the kit is (a workshop where agents make things), it’s distinctive, short, pronounceable, and free on npm (karkhana); repo dashayushman/karkhana, tagline “an agent-operated app on Cloudflare — a workshop built for coding agents.” Runner-up: Sutradhar (सूत्रधार — the one who holds the strings, the narrator-orchestrator; lovely meaning for an agent orchestrator, but the npm name is taken and there are a few small same-named repos). Founder confirms (§14). License MIT recommended. The site’s /build/starter and beat 7 are its walkthrough, shown as a real terminal recording of an agent doing it.

10. Hosting & infrastructure (SH-13)

Thing	Where	Notes
Story site (`apps/showcase`)	Cloudflare Pages (or Workers static assets) at `namasteji.aiwithayushman.com` — the founder’s domain; both zones (`aiwithayushman.com`, `namasteji.org`) live on the same CF account, free plan ⇒ first-level subdomain only (CI-6)	Astro static output + React islands; the same `/assets` guard pattern; `_headers` immutable assets; `/docs/` generated from `docs/*` at build (SH-14)
Open console	Pages project `namaste-ji-console-staging` + custom domain `demo.namasteji.org`; console-api route `demo.namasteji.org/api/*`	§5; no Access on that host
Guide	No backend (v1): `packages/guide` island + compiled rule JSON shipped with the site; state in localStorage	Zero tokens, zero ops (SH-25). Optional later: an anonymous discovery beacon Worker
Docs mirror build	CI job on merge to main renders `docs/*/.md` → `/docs/*` (SH-14)	The place for real depth
Analytics	Cloudflare Web Analytics (no cookies) + the Guide’s own anonymous funnel (quest starts/completions)	Privacy-light (P-8)
Consumer “try it”	Link/embed to the consumer web app (`app`/`app-staging`)	Phone-OTP auth stays the app’s; the site never collects phone numbers
Domains	Story = `namasteji.aiwithayushman.com`; product = `namasteji.org` (`demo`, `app`, `bo` first-level only, free-plan SSL)	CI-6; the story is the founder’s, the product is the product’s

Astro (SH-13 rationale): the site is 80% prose/imagery — content-first, MDX for the story, perfect scores on low-end phones (P-7) — while React islands reuse BO components (AssetImg, tokens, the Guide widget). A full SPA would cost first-paint for no benefit; a pure static site couldn’t host the live bits. If the team would rather not add a framework, the fallback is the console’s Vite+React stack with prerendering — Astro is the recommendation, not a hill.

11. Analytics, privacy, abuse

No cookies, no accounts, no phone numbers on the story site. Guide progress is localStorage only.
The Guide is client-side and scripted: no sessions, no transcripts, no model calls, nothing to rate-limit. Rate limits (WAF) stay on the demo host’s read API.
The open console exposes content (greetings, briefs, scores, run summaries) by design; a pre-launch leakage review of every readable endpoint (config values, gateway URLs, model names, emails) gates the launch (§5).

12. Decisions log

#	Decision	Rationale
SH-1	Two doors, one story — same pages at two depths (`?mode=see\|build`), not two sites	Keeps one narrative; lets any reader go deeper at any paragraph; one thing to maintain
SH-2	Seven-beat spine, story page = the product, sub-pages = depth	Linear story for the See-it reader; every beat is an entry point for the Build-it reader
SH-3	Site retells, repo is truth — every Build-it page ends in canonical doc + code links	Architecture prose lives once; the site can’t rot independently
SH-4	Open console = the real BO, read-only, `public` role, no login	P-2; safety from RBAC deny-by-default, not from a gate; honest demo
SH-5	The Guide is the founder’s avatar, first person	The story is personal; the avatar carries the “why” in the founder’s voice
SH-6	Fully scripted Guide — versioned Markdown rules compiled to JSON, no LLM anywhere in it	Deterministic, reviewable, zero tokens (founder: “no free-form Q&A”); depth lives in `/docs/*`
SH-7	Never invent numbers — every figure in a Guide line is interpolated from live page state/API; demo data is labelled	Honesty is the brand
SH-8	Game mechanics: discoveries journal · stamps · set pieces (boss moments) · hint-on-demand · shareable progress	Engagement without accounts; the journal is the curriculum, filled by play
SH-9	One Guide widget for both the site and the open console	The tour crosses from story into the real console; one implementation
SH-10	Everything shown is real staging data	Credibility; “nothing is faked” is a claim we can make
SH-11	Design system is law here too (chrome zone, tokens, one primary, gold once)	Consistency with app + BO; festive never gaudy
SH-12	Starter kit “Karkhana” = generated public template repo, agent-first (`AGENTS.md` front door, one idempotent `bootstrap`, every external dependency user-supplied with Workers AI defaults, scaffolding commands, task runbooks, verification contracts, CI proof via dry-run + local e2e — no accounts owned by the kit) + the site’s last beat	A coding agent must reach a running app on Cloudflare from the repo + the user’s keys alone; give-back that stays in sync
SH-13	Astro + React islands on Pages; Guide = Hono Worker + DO; models via Gateway from KV	Content-first performance + reuse; house stack; cost/observability
SH-14	`docs/` rendered into the site at build time (`/docs/`)*; repo stays the source of truth	The repo is private — public “Go deeper” links must resolve; one source, two renderings, zero drift
SH-15	Host the story on the founder’s domain (`namasteji.aiwithayushman.com`), the open console on the product domain (`demo.namasteji.org`)	The story is personal and portfolio-grade; the product keeps its own identity; both zones are on the same CF account
SH-17	Public BO pages are bespoke exhibits, not the console restyled — one concept per exhibit (constellation · river · simulator+Atlas · strategy desk · QA theatre), same read APIs + isomorphic code, with a “see the real thing” door to the read-only console	“Wow and simple” needs staging and choreography a tool’s UI can’t give; the tool stays available for the unvarnished view
SH-18	Performance-grade motion with a budget: GSAP+ScrollTrigger scenes, Motion micro-interactions, d3/canvas graphs; reduced-motion + small-screen static fallbacks; static first paint	Creative storytelling is the brief; accessibility and low-end phones are the constraint
SH-19	Generated art via gpt-image-1 through the AI Gateway, prompts versioned, outputs committed; real catalog imagery preferred wherever an image can do the job	Same renderer as the product (coherent style), zero runtime spend, reviewable in PRs
SH-20	Catalog imagery incl. `rendered`-not-embedded is fair game; `rejected`/vetoed only inside the QA exhibit, labelled	Founder’s call — there are many good renders awaiting embedding; rejects teach what QA catches
SH-21	Staged and rehearsed — curated demo data and generated imagery are the norm of the exhibits, not an exception; one site-wide “about this performance” note (the mechanisms are real, the scenes are rehearsed) replaces per-item labels; anything presented as live (counts, a run you trigger) is live	Founder: “this is a performance — like every performance, everything is staged and rehearsed.” Honesty is kept at the level that matters: the system is real, the numbers shown as live are live
SH-22	The Build-it track is top-down and graphical: one zoomable system map is the spine; every technical page is a zoom into it, same scene grammar as the exhibits; “Why?” is a first-class element on every zoom	The technical audience deserves the same craft; top-down keeps it uncluttered and the mental model stable
SH-23	Diagrams generated from source where the source exists (substrate from `infra/alchemy.run.ts`, agent anatomy from manifests, tooling from repo config)	A generated diagram can’t drift from reality; it’s also the most honest “how it’s wired”
SH-24	Learn by doing: triggers, not tours — the exhibits carry diegetic affordances; the Guide reacts to the visitor’s real actions (event → scripted line with context), with at most one nudge/hint when idle	RPG-style teaching on the go (founder’s direction); guidance only where needed
SH-25	The Guide has no backend in v1 — client-side rules + localStorage; no LLM, no Vectorize, no DO	Zero token spend, nothing to abuse or operate
SH-26	Every exhibit ships with 1–3 irresistible affordances and one set piece with a win state	“Intuitive and wow enough that people act” is a page requirement; set pieces land the concepts we care most about
SH-27	Pages emit events, the Guide subscribes (typed event bus; pages never know what the Guide will say)	Decoupled, unit-testable against an event log, copy editable without touching pages
SH-28	The agent workbench is public: tools (with schemas), the full Langfuse prompts (versioned), manifests, real traces	Founder: showing full prompts is fine and, for the technical reader, essential — it’s how the agents are built
SH-29	Images: quality first, then speed — lossless originals in repo, AVIF/WebP at high quality + JPEG fallback, responsive srcset, fixed dimensions, LQIP; hero-grade images visually checked at 2×	Founder: “optimize for load, but quality is paramount”; the greeting image carries the page
SH-30	English first, i18n-ready from day one: Astro i18n routing (`en` default, no prefix; `hi` reserved), every string — page copy, Guide rules, alt text — lives in locale files (`src/i18n/<locale>/…`), `lang`/`dir` set per locale, no hardcoded UI strings, dates/numbers via `Intl`	Translate later without a rewrite; the product itself is vernacular-first (P-6)
SH-16	Your brand is the chrome, Namaste Ji’s brand is the exhibit — aiwithayushman.com’s white/Space Grotesk/purple system wraps the page; the product keeps its own tokens inside frames; Guide = purple ring, stamps = product gold	Consistency with your site without diluting the product’s identity; one rule settles every “which colour?” question

13. Build plan — the PR ladder

Phase	PRs	Done when
0. Foundations	`apps/showcase` scaffold (Astro, tokens, layout, depth toggle), Pages project + custom domain `namasteji.aiwithayushman.com`, `/assets` guard, the avatar asset in place	`namasteji.aiwithayushman.com` serves a hero + the seven beat headings, Lighthouse ≥ 95 on mobile
1. Story MVP (See it)	Beats 1–7 as scroll scenes (GSAP), beat 1 = mom’s WhatsApp thread, real imagery + live pipeline counts; the art pipeline + first generated scenes; `/try`; copy pass in the founder’s voice	A non-tech reader understands it in 60s and says “wow”; shareable; Lighthouse ≥95
2. Exhibits, one at a time	`/agents` constellation → `/studio` river → `/qa` Heimdall theatre → `/lab` simulator + Atlas → `/strategy` desk; each with live data, static fallback, “see the real thing” + “why” doors	Each exhibit lands its one concept in under a minute; each is shareable on its own
2b. Open console (the door)	`public` role + demo-host identity + non-GET block + endpoint leakage review; landing + read-only banner; `can()` sweep; domain/route/WAF	`demo.namasteji.org` opens to anyone, read-only, with the agreed surfaces
3. The Build-it track	`/docs/*` mirror (SH-14); the zoomable system map component; zooms 0→5 (`/build`, architecture, cloudflare generated from `infra/`, agents anatomy + provider switchboard, qa, tooling), then feed/data; costs; “Why?” pins with decision IDs	An engineer can reconstruct the design from the site alone — and says “wow” too
4. Guide v1 (reactive)	`packages/guide` island + event bus; rule compiler (Markdown → JSON); first ~40 rules across story + two exhibits; discoveries journal + stamps; nudge/idle hint; quiet mode; URL/localStorage state	A visitor who only plays learns the pipeline and the QA idea without reading
5. Guide v2 (set pieces)	The five boss moments (agree-the-personas · beat Heimdall · catch the failed shot · pause the Creator · flip the provider); remaining rules (Build track); the “Chai with the builder” ending; shareable discovery card	Completion feels earned; the concepts we care most about are the ones people win
6. Starter kit (agent-first) — can run in parallel with phases 2–5	`export-starter.mjs` + public repo; `AGENTS.md`/`CLAUDE.md`/`tasks/`; `bootstrap` + `doctor` + `new:*` scaffolds + `check`/`smoke`; Workers-AI-default example pipeline; weekly `bootstrap-e2e`; `/build/starter` walkthrough + quest 5 (terminal recording)	A coding agent, given the repo + `.env`, reaches a deployed running app + green checks in one session with zero human questions — proven weekly by CI
7. Polish	TTS toggle, Hindi UI option, OG images, recordings of traces, the “Chai with the builder” ending	—

Each PR small, single-purpose, merged on green; the site deploys on merge like the console.

Story v2 — “One phone, one morning” (2026-08-23, approved). After founder review of the shipped v1 story page, the seven beats are being recut into six named chapters on a sunrise progress rail, scroll-scrubbed (pin + scrub, GSAP 3.13 all-plugins-free): the open + bridge line → 1 · Her messages → 2 · The relay (five badge-avatar AI agents hand one real artifact along a conveyor; real Control-DO pause) → 3 · The judge (stamp verdicts with the judge’s verbatim reasons) → 4 · Full circle (mom forwards a card back into the chapter-1 thread, GSAP Flip) → 5 · For builders (Claude Code named, stack-logo orbit, Karkhana repo + copy-ready agent prompt) → 6 · Your path (all doors consolidated). Cut: “Beat n of 7” labels, per-beat Why? boxes, the See-it/Build-it toggle on the story page (single voice; toggle survives on /build), agent portraits (→ iconic badge avatars), three-door clusters. The approved frame-by-frame storyboard with motion specs and copy lives at docs/showcase/storyboard-one-phone-one-morning.html.

14. Open questions for the founder

Answered 2026-08-23: the Guide = Ayushman Dash, real photo (SH-5) — please drop the headshot at apps/showcase/public/guide/ayushman.jpg (square, ≥1024px) or share a path; host = namasteji.aiwithayushman.com (SH-15); starter kit deferred (SH-12).

Still open: 0. ~~Files to place in the repo~~ — done 2026-08-23: headshot 2556² (guide/ayushman.jpg), family 4608×2176 (story/family.jpg), six forwards (story/mom/forward1-6.jpeg). Phase 0 moves them under apps/showcase/src/assets/ so Astro’s image pipeline (SH-29) optimises them at build. 2. ~~The family photo as hero~~ — answered: yes (founder supplied it; beat 1 hero). 4. ~~Starter kit name + license~~ — Karkhana, MIT; no scratch account (CI proves via dry-run + local e2e). 5. ~~Which staging data is public-safe~~ — answered: full prompts are fine (SH-28); briefs, strategy, run summaries all public. Only operator emails (audit) and secrets/config stay out. 6. ~~Languages~~ — EN first, i18n-ready (SH-30); Hinglish flourishes in See mode stay. 7. ~~Claims~~ — name them all (OpenAI, Sarvam, Cohere, Cloudflare, Langfuse…) — “that’s the whole point”. 8. ~~Ask-me scope~~ — answered: no free-form Q&A (SH-6/SH-25).

15. Appendix — story copy, first draft (founder voice)

Beat 1. Every morning, before the day has decided what it wants from me, my mom sends me a good-morning image on WhatsApp. A sun, a flower, a deity, a line in Hindi. Hundreds of millions of people across India start their day exactly like this — sending, forwarding, wishing. It is the most human thing on the internet, and almost nobody is making it for them: in their language, with taste, fresh every day.

Beat 2. So I didn’t build a model. I built a small creative department — a VP who decides what to make, a director who turns ideas into shot lists, a creator who makes the pictures, a QA lead named Heimdall who says no, and a calendar keeper who knows that Onam and Chhath are not the same morning. They are AI agents. They share one anatomy, one memory model, and one rule: a human can pause any of them at any time.

Beat 3 → 7. (drafted per section in the story page; each ends with “Why?” and, in Build mode, “Go deeper →”.)