From c0fe424780ea477238efd4af32be56ea60298826 Mon Sep 17 00:00:00 2001 From: sb-iam <59984144+sb-iam@users.noreply.github.com> Date: Sun, 28 Jun 2026 13:11:27 -0500 Subject: [PATCH] docs: add visual HTML demo runbook (ascii architecture + RSI-loop diagrams) Self-contained one-pager: how-it-works ASCII diagrams (data flow + continual- learning loop), the 3-min demo timeline, sponsor coverage, last-hour caveats (suppression disabled, don't redeploy prod), and recovery. Demo-branch only. Co-Authored-By: Claude Opus 4.8 --- docs/demo_runbook.html | 189 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 189 insertions(+) create mode 100644 docs/demo_runbook.html diff --git a/docs/demo_runbook.html b/docs/demo_runbook.html new file mode 100644 index 0000000..272c71e --- /dev/null +++ b/docs/demo_runbook.html @@ -0,0 +1,189 @@ + + + + + +PodMan — Demo Runbook + + + +
+ +
+

PodMan ● Demo Runbook

+
A pair programmer for the whole team. It watches everyone's work live, catches + collisions before the push (when GitHub still can't see them), and learns the team's + dynamics so it nudges less and helps more over time.
+
+ +
+ The 10-second story: Coding isn't the bottleneck anymore — + coordination is. PodMan gives a team real-time awareness with zero interruptions, catches + the pre-push collision that costs an afternoon, and the Team-Memory Graph proves it learned — + materialized live from MongoDB, not a mock. +
+ +

How it works — architecture

+
+                              ░ PodMan data flow ░
+
+   ┌──────────────┐   screen-share track    ┌────────────────────────────┐
+   │  Engineers   │ ──────────────────────▶ │       LiveKit Cloud         │
+   │ (browsers)   │ ◀───────────────────────│      room = "demo-pod"      │
+   └──────┬───────┘   cards · voice · cues   └─────────────┬──────────────┘
+          │            (data channel)                      │ frames @ ~1 fps
+          │ live graph (poll 5s)                            │  + local git truth
+          │                                                 ▼
+          │                              ┌────────────────────────────────────┐
+          │                              │   HERMES AGENT  (Node, podman-hermes)│
+          │                              │   frame ─▶ GEMINI VISION  (file/    │
+          │                              │            symbol/activity)          │
+          │                              │   fuse with git watcher (unpushed!) │
+          │                              │   ─▶ detect same-file collision     │
+          │                              │   ─▶ Gemini TTS voice over LiveKit   │
+          │                              └──────────────────┬───────────────────┘
+          │                                                 │ read / write
+   ┌──────┴────────────┐    materialize live    ┌───────────▼──────────────────┐
+   │  TEAM-MEMORY      │ ◀──────────────────────│        MongoDB Atlas          │
+   │  GRAPH  (SVG)     │   graph/live.ts         │  observations · collisions    │
+   │  owns/edits/      │                         │  interventions · outcomes     │
+   │  collides/        │                         │  team_model · graph_nodes/edges│
+   │  learned_from     │                         │  + $vectorSearch recall        │
+   └───────────────────┘                         └───────────────────────────────┘
+
+   Infra: DigitalOcean droplet · systemd-supervised API + agent · Caddy static frontend
+   Models: Gemini (Vision · TTS · Live voice · embeddings · Lyria ambient score)
+
+ +

How it works — the continual-learning loop

+
+        observe  ──▶  store  ──▶  predict  ──▶  outcome  ──▶  adapt
+          │            │            │             │            │
+       Gemini       MongoDB     same-file     accept /      learned_from
+       Vision +     records     overlap       dismiss        edge + owner
+       git truth                detected      (1 tap)        persists
+          ▲                                                     │
+          └─────────────────  recall ($vectorSearch)  ◀─────────┘
+                   "Seen before." → escalates on a repeat
+
+   The proof: one accept/dismiss tap — no retraining, no labels — changes the
+   NEXT run. Run 2 of the same collision says "Seen before." and a violet
+   learned_from edge appears on the graph. That edge is read straight from Atlas.
+
+ +

The 3-minute demo (read off this)

+ + + + + + + + + + + + + + + + + + +
TimeDoSay — land the value
0:00Pod view, two live screen tiles"Coordination is the bottleneck now, not coding. PodMan watches everyone's work live — nobody has to ask 'what are you on?'"
0:30Point at tiles; activity stream fills"Real screen-shares over LiveKit; each frame → Gemini Vision → file/symbol/activity. A perception layer, not a chatbot."
1:05Two engineers edit the same file, unpushed"GitHub can't see this — nothing's pushed. We fuse live screen context with local git truth." → collision card appears.
1:40Accept the cardReal GitHub sync-PR created + outcome recorded. "One tap closes the loop."
2:10Trigger the same collision againCard now says "Seen before." and escalates to the Gemini TTS voice. "It recalled the prior event from MongoDB Atlas vector search and escalated — that's the learning."
2:35Cut to GraphView"This graph is materialized live from MongoDB right now — and here's the learned_from edge: PodMan learned who owns this file. Not a mock."
3:00Stack + close"All on DigitalOcean, systemd-supervised; ambient score is Gemini Lyria. Awareness, collisions caught pre-push, memory that sharpens each session."
+ +

Sponsor coverage — say each ≥ once

+ + + + + + + + +
PrizeSpoken momentBeat
GeminiVision perception · TTS voice · Lyria score (Live conversation if time)0:30 · 2:10 · 3:00
LiveKit"real screen-shares over LiveKit"; TTS audio over LiveKit0:30 · 2:10
MongoDB"Atlas vector-search recall" · "graph materialized live from MongoDB"2:10 · 2:35
DigitalOcean"all on DigitalOcean, systemd-supervised workers"3:00
+ +

⛔ Last-hour caveats — read before you run

+
+

1 · Suppression is DISABLED for the demo

+
Every collision now surfaces (good — no accidental silencing). The old + "it learned to stay QUIET / no card fires" beat will not work. Use the + escalate beat instead: trigger the same collision again → "Seen before." + voice + + learned_from edge. Don't promise silence on stage.
+
+
+

2 · Do NOT redeploy prod

+
The live build has demo code not on main (e.g. userPodContext); + redeploying would remove it and surface stale "SUPPRESSED" beats. If the auto-deploy timer is on, + stop it: systemctl stop podman-hermes-sync-deploy.timer.
+
+
+

3 · Never debug on stage

+
Narrate, fall back to the backup recording, keep moving.
+
+ +

If it breaks — live recovery

+ + + + + + + + +
FailureRecovery
Voice doesn't fireCut to the card, say the line aloud — cards are the default path. (Click "Enable audio" in-room first!)
Collision won't triggerUse the backup recording for that beat; keep narrating.
Graph looks empty / oddReload once; if still off, narrate from the recording.
Agent silentSuspect a duplicate podman-hermes process, not the UI — but don't fix on stage.
+ +

Pre-flight checklist

+
+
    +
  1. curl https://podman.live/health → {"ok":true}
    2. +
  2. Deploy timer stopped; exactly one agent — systemctl status podman-platform-agent
    3. +
  3. Browser on the pod; click "Enable audio" (TTS needs it)
    4. +
  4. Backup recording cued on a second device
    5. +
  5. Two screen-shares live (the two "engineers")
    6. +
+
+ + + +
+ +