podman/docs/generated/CRITIQUE.md

PodMan — Red-team critique

Go/No-Go: CONDITIONAL GO — but only if you cut to a ruthless MVP and de-risk in a specific order. The architecture is sound (I verified the load-bearing piece: @livekit/rtc-node installs on this machine and exposes exactly the API agent.ts assumes — VideoStream, VideoFrame.convert, VideoBufferType.RGBA, TrackSource.SOURCE_SCREENSHARE all present). The idea is genuinely differentiated and the moat ("unpushed changes are invisible to GitHub, only realtime vision sees them") is real and defensible. BUT the gap between the architecture doc and the actual repo is large: the doc describes ~25 files as "STARTER"/done; on disk there are 5 thin stubs and a single token-only backend entry. Nothing of the agent loop, vision wiring, voice, memory/vectors/policy, frontend LiveKit/PWA, or shared/messages.ts exists yet. You are building the entire load-bearing system in 20 hours across 4 people with 5+ external integrations (LiveKit, Gemini vision, Gemini voice, GitHub, MongoDB/Voyage, DO). That is doable for the core moat demo, NOT for the full doc. Go for the moat + ONE learning loop; treat everything else as optional. The continual-learning angle is the right competitive frame and is achievable in a thin form, but do not let it eat the realtime path's time.

24h feasibility: Tight but feasible for a SCOPED demo; NOT feasible for the full architecture as written. Reality check against the repo: backend is a single index.ts (token mint only) — the server/agent two-process split the doc calls 'the one load-bearing decision' is NOT built. Missing & uninstalled deps the design needs: @livekit/rtc-node (the moat; ~2 min native install — I timed it), sharp, ws, mongodb, voyageai, plus frontend vite-plugin-pwa/vite/@vitejs/plugin-react (frontend deps lists only react+livekit-client, no build toolchain). Honest hour budget for the HERO path only (capture -> 1fps frame grab -> Gemini vision -> collision detect -> card+voice -> real PR): ~14-18h of focused work with parallelism, and that assumes the LiveKit Cloud account, Gemini key, public repo, and a working screen-share-to-room round trip are all proven in hour 1-2. The doc's own estimate (~22h of listed steps) already exceeds the 20h budget BEFORE accounting for integration debugging, which always doubles. Continual-learning Loops A+B, Voyage vector recall, the Spanish translate flourish, the Tier-2 git sidecar, and DO Gradient are all over the line — ship them only if the hero path is solid by hour 12. Two unverified assumptions could blow the timeline: (1) the exact Gemini model IDs 'gemini-3.5-flash' / 'gemini-3.1-flash-live-preview' and the responseJsonSchema/mediaResolution API shape on @google/genai@2.10.0 — validate with one real API call in hour 1; (2) publishing a server-side AudioTrack via AudioSource.captureFrame for PodMan's voice is the fiddliest unproven bit — budget a half-day or fall back to browser-side TTS.

DQ check: Re-checked against the explicit rules. (1) DASHBOARD-AS-MAIN-FEATURE — REAL RISK. The pod grid of live screens is on the banned list and is the obvious thing to show. Mitigation is structural, not cosmetic: hero must be the proactive agent intervention (voice + card + real PR), grid stays a collapsed corner chip, demo opens on a single IDE. Rehearse the framing line. (2) PUBLIC REPO — NOT YET SATISFIED. Remote is git@github.com:karti-ai/podman over SSH and is almost certainly private; rules require public. Make the PodMan repo AND the target demo repo public before the demo, and verify on github.com. (3) ONLY-WHAT-YOU-BUILT / NEW WORK — currently OK (4 commits, all dated 2026-06-27, scaffold only) but enforce that no pre-existing or non-hackathon code lands, and that the demo repo's PR is opened against fresh hackathon content. (4) MAX 4 MEMBERS — team is exactly 4 (Karti, Ramis, Yahya, Zander), OK. (5) IMAGE-ANALYZER banned type — PodMan ingests screen frames with a vision model, which a hostile judge could caricature as 'image analyzer.' Defuse by framing vision as one sensor of an ambient agent that fuses with git state and acts, not an analysis product. (6) BASIC-RAG banned — the Voyage/Atlas vector recall must be framed as outcome-driven memory for a learning agent, not a RAG Q&A app. (7) Sponsor honesty — drop MiniMax/Modular claims; claim only DO, LiveKit, Gemini, MongoDB/Voyage that are actually integrated.

Top risks

• [critical] SCOPE: the repo is ~5% built vs. what the architecture doc presents as done. The agent loop, vision wiring, voice, memory/vectors/policy, all frontend LiveKit hooks + PWA, and shared/messages.ts do not exist. The team may believe they are 'extending starters' when they are actually writing everything from scratch under a 20h clock. → Fix: Reframe the doc as a spec, not a status. Hour 0: write the real file skeletons (empty exported functions) so the 4 people can work in parallel without merge stalls. Freeze scope to the hero path TODAY. Put the full file list on a board and mark only 8 files as P0 (agent.ts, vision/gemini.ts, collision/detector.ts [exists], podman.ts orchestrator, server token+ws, useScreenPublish, useInterventions, InterventionCard). Everything else is P1/P2.
• [high] DEPLOY HANG: the actual infra/app.yaml is a SINGLE Docker service with an http /health check — the exact trap the doc warns about. The agent (no HTTP port) cannot run as a health-checked service; it will deploy-hang or crash-loop. The doc's static_site+service+worker split is NOT implemented. Also @livekit/rtc-node is a native binding that took ~2 min to install — DO build timeouts and missing build deps (it pulls platform binaries) are a real risk. → Fix: Do NOT block the demo on DO. Run the live demo from localhost (or one laptop + ngrok) as primary; deploy to DO in parallel as the 'it's also in the cloud' talking point. If you do deploy: split into worker (agent, no port, no health check) + service (token/ws, http_port 8787 bound 0.0.0.0) + static_site (PWA) per the doc, and confirm rtc-node's native deps are present in the runtime image. Verify the deploy by hour 14, not hour 20.
• [high] MODEL ID / API DRIFT: 'gemini-3.5-flash' and 'gemini-3.1-flash-live-preview' and the responseJsonSchema + mediaResolution:'MEDIA_RESOLUTION_LOW' + thinkingBudget:0 shape are assumptions, unverified against installed @google/genai@2.10.0. If any ID is wrong or the config keys differ, the load-bearing vision call fails and the whole demo is dead. → Fix: Hour 1, before anything else: make ONE real generateContent call with a sample screenshot and the structured-output schema. Keep model IDs in env (already done) so they are swappable. If 3.5-flash isn't available on your key, fall back to the latest available flash vision model immediately. Confirm structured JSON actually returns and parses.
• [high] VISION FLAKINESS ON THE MONEY BEAT: detecting 'same file + >=1 unpushed' from screen pixels is the entire hero, but vision reading a file path and a dirty-git-gutter reliably under stage lighting/compression is fragile. A wrong read at the climax kills the demo and the Technicality score. → Fix: Build the Tier-2 local git-reporter sidecar (git rev-list @{u}..HEAD + git status over the data channel) — it is ~30 lines and gives ground-truth 'unpushed'. The detector already accepts either signal. Use real vision for the 'what file' read (impressive, true) but back the 'unpushed' predicate with the sidecar so the climax is deterministic. Pre-stage the two engineers on the same known file so the read target is large, high-contrast, and unambiguous.
• [high] DASHBOARD-AS-HERO DQ: a grid of live teammate screens is on the explicit banned list, and that grid is the most natural thing to put on screen. Judges DQ on this exact pattern. → Fix: Open the demo on a SINGLE engineer's IDE, never the grid. Keep PodGridCorner collapsed to a tiny peripheral chip. Say out loud 'PodMan is an agent, not a dashboard — the screens are just its eyes.' The hero on screen is the proactive intervention card + PodMan's voice + the real GitHub PR opening in a browser tab. Lead the 1-min video with the voice interruption, not any UI grid.
• [medium] VOICE OUT IS THE FIDDLIEST UNPROVEN PIECE: publishing PodMan's spoken audio as a server-side AudioTrack via AudioSource.captureFrame (Gemini live PCM -> AudioFrame) is the least-trodden path in the stack and easy to lose a day on. → Fix: Treat in-room agent voice as P1, not P0. P0 fallback: send the intervention text over the data channel and speak it with browser-side Web Speech API / a pre-generated TTS clip on the PWA. It sounds identical to the audience. Only attempt server-published AudioTrack once the card + PR path works end to end.
• [medium] PUBLIC REPO + ONLY-WHAT-YOU-BUILT RULES: remote is git@github.com:karti-ai/podman (SSH, likely private). Rules require PUBLIC repos, max 4 members, and demo only NEW hackathon work. A private demo repo or pre-existing code = DQ. → Fix: Make BOTH repos public now: the PodMan repo itself AND the target demo repo the PR is opened against (the doc shows its URL on screen). Confirm the GitHub PAT is fine-grained on the public demo repo with Contents R + PRs R/W. Ensure all committed code is dated within the hackathon window and the 4-member cap holds.
• [medium] INTEGRATION COUNT: 5-6 external services on the hot path (LiveKit, Gemini vision, Gemini voice, GitHub, Mongo/Voyage, DO). Each adds auth/latency/failure surface; the realtime chain is only as reliable as its weakest hop and venue wifi. → Fix: Drop everything not load-bearing: cut MiniMax and Modular from the pitch entirely (sponsor-padding hurts credibility). Make Mongo/Voyage optional behind a flag so a DB outage can't crash the agent. Cache the latest frame and degrade gracefully. Rehearse on a phone hotspot, not just venue wifi.
• [medium] CONTINUAL-LEARNING CLAIM IS THIN IF NOT SHOWN: the winning frame is Continual Learning, but Voyage vector recall + policy adaptation are P1 and at real risk of being cut, leaving the pitch making a claim the demo doesn't show. → Fix: Build the CHEAPEST honest version of 'it got smarter': persist collision signatures to Mongo and, on the 2nd identical collision, retrieve the prior record to raise confidence and lead with the previously-accepted action. That single retrieve-and-explain beat ('I've seen this conflict before') satisfies the track without the full vector+policy stack. Voyage embeddings are a bonus, not a requirement, for the beat.

Demo-day reliability

• RUN LIVE BUT CARRY A RECORDED MONEY-MOMENT. Record a clean take of the full collision->voice->card->real-PR beat early and keep it one keystroke away. If anything hiccups on stage, narrate over the recording without missing a beat.
• PRE-STAGE THE TWO COLLIDING ENGINEERS. Have both laptops already joined to a fixed room (POD_ROOM=demo-pod) with screen-share live and parked on the SAME known file (e.g. src/auth/session.ts) with large high-contrast text, one with uncommitted edits. Don't ask vision to find a needle live.
• MAKE 'UNPUSHED' DETERMINISTIC VIA THE TIER-2 SIDECAR. Use real vision for the 'what file' read, but feed the unpushed predicate from git rev-list @{u}..HEAD over the data channel so the climax can't misfire on a flaky pixel read. The detector already accepts either signal.
• VALIDATE GEMINI IN HOUR 1. One real generateContent call with a sample screenshot + the structured schema, on the actual installed @google/genai@2.10.0. Confirm the model ID resolves and JSON parses before building anything on top.
• DON'T DEPEND ON DO FOR THE LIVE RUN. Demo from localhost or one laptop + ngrok (secure context is required for getDisplayMedia anyway). Keep the DO deployment as a parallel 'also in the cloud' tab, verified by hour 14.
• BRING YOUR OWN NETWORK. Phone hotspot as primary, venue wifi as backup (not the reverse). The realtime chain dies on bad wifi. Test the full path on the hotspot during rehearsal.
• FALL BACK TO BROWSER TTS FOR VOICE. If server-published AudioTrack via AudioSource.captureFrame isn't rock-solid, speak the intervention text with Web Speech API / a pre-rendered clip on the PWA — sounds identical to the audience and removes the riskiest hop.
• OPEN A REAL PR, SHOW THE GITHUB TAB. The clickable PR on a public repo is the credibility anchor. Pre-create the branch base and confirm the PAT scopes so pulls.create can't 403 on stage. Have the github.com URL already on screen.
• PRE-WARM EVERYTHING. Agent already in the room, GitHub state cached, Mongo connected, frames flowing, BEFORE you start talking. Cold-starting @livekit/rtc-node + first Gemini call live wastes 10+ seconds of a 3-min slot.
• REHEARSE 3X END TO END with a stopwatch. The 3-min slot is unforgiving; lead with the voice interruption in the first 20 seconds, the 'I've seen this conflict before' learning beat in the middle, the real PR at the climax.

Scope cuts if behind (in order)

• FIRST CUT: Spanish live-translate flourish (gemini-3.5-live-translate). Pure bonus, zero impact on the core thesis.
• DigitalOcean Gradient secondary LLM call. The DO deploy alone earns the DO story; Gradient is a nice-to-have you can name without building.
• Voyage AI embeddings + Atlas $vectorSearch. Replace with an exact/normalized-signature match in Mongo to still get the 'I've seen this before' beat. Keep the beat, drop the vector machinery.
• Policy Loop B (outcome-driven threshold/preference adaptation). Keep the ACK plumbing so outcomes are recorded, but don't build the adaptive policy if time is short — the world-model recall (Loop A) carries the Continual Learning claim.
• Server-published agent AudioTrack. Fall back to browser-side TTS for PodMan's voice; identical audience experience, far less risk.
• PWA installability (vite-plugin-pwa, service worker, manifest). Ship a normal Vite web app; 'installable' is a one-line pitch claim, not a demo requirement.
• Tier-2 git sidecar — KEEP unless truly desperate; it's the cheapest reliability insurance for the climax. Only cut if vision's unpushed read is proven solid in rehearsal.
• Multi-pod / password+QR join. Hardcode a single demo-pod room. Join UX is not the hero.
• MongoDB persistence entirely (last resort). Run the learning beat from an in-memory map for the demo; you lose the 'persistent world-model' talking point but keep a working agent. Cut this only if the DB is actively breaking the run.