OSS/podman
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

style: apply prettier formatting to docs

Browse Source 
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Kartikeya
2026-06-27 14:17:14 -07:00
parent 2223b190f6
commit 253c7438fb
2 changed files with 56 additions and 52 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+2 -2
View File
@@ -9,13 +9,13 @@ speaking up like Jarvis: _"Karti and Yahya are both editing `auth.ts`, Yahya has
changes — here's the diff, want a sync PR?"_ changes — here's the diff, want a sync PR?"_
> **The moat:** unpushed local code is invisible to the GitHub API. The realtime > **The moat:** unpushed local code is invisible to the GitHub API. The realtime
> screen-vision layer is the *only* way to catch a collision before the push. That is the > screen-vision layer is the _only_ way to catch a collision before the push. That is the
> whole product — and the reason this is an ambient agent, not a dashboard. > whole product — and the reason this is an ambient agent, not a dashboard.
## Monorepo layout ## Monorepo layout
| Folder | What | | Folder | What |
|---|---| | ----------- | -------------------------------------------------------------------------------------------------- |
| `frontend/` | React + Vite PWA — join pod, screen/mic/cam capture, PodMan voice + intervention cards | | `frontend/` | React + Vite PWA — join pod, screen/mic/cam capture, PodMan voice + intervention cards |
| `backend/` | PodMan agent: LiveKit room subscriber, Gemini vision, GitHub fusion, collision detector, voice out | | `backend/` | PodMan agent: LiveKit room subscriber, Gemini vision, GitHub fusion, collision detector, voice out |
| `infra/` | DigitalOcean deploy (App Platform / Droplet), IaC, Dockerfiles | | `infra/` | DigitalOcean deploy (App Platform / Droplet), IaC, Dockerfiles |
docs/PLAN.md
+24 -20
View File
@@ -14,16 +14,18 @@ prevent merge collisions before anyone pushes**, offering to open a sync PR.
- **Track:** Continual Learning - **Track:** Continual Learning
- **Prizes targeted (stacked):** Gemini 3.5 ($5k cash), LiveKit (keyboards), DigitalOcean (credits) - **Prizes targeted (stacked):** Gemini 3.5 ($5k cash), LiveKit (keyboards), DigitalOcean (credits)
- **Hero moment:** two laptops editing the same file → PodMan *speaks up live* and offers the fix. - **Hero moment:** two laptops editing the same file → PodMan _speaks up live_ and offers the fix.
--- ---
## 1. Why this fits the track (and stays eligible) ## 1. Why this fits the track (and stays eligible)
### Track = Continual Learning ### Track = Continual Learning
The official definition rewards systems that "continuously improve from real-world use… The official definition rewards systems that "continuously improve from real-world use…
becoming more useful the more they are used with as little user intervention as possible." becoming more useful the more they are used with as little user intervention as possible."
PodMan does exactly this: PodMan does exactly this:
- Builds and **continuously refines a live model of the team** — who owns which files/areas, - Builds and **continuously refines a live model of the team** — who owns which files/areas,
what's in-flight, recurring conflict patterns, each engineer's working style. what's in-flight, recurring conflict patterns, each engineer's working style.
- **Self-improves its own intervention policy** from outcomes: did the collision it predicted - **Self-improves its own intervention policy** from outcomes: did the collision it predicted
@@ -32,9 +34,10 @@ PodMan does exactly this:
- Grows a per-team **skill/memory store** (vector memory) that makes later sessions sharper. - Grows a per-team **skill/memory store** (vector memory) that makes later sessions sharper.
### ⚠️ Disqualification traps — and how we dodge them ### ⚠️ Disqualification traps — and how we dodge them
| Risk | Mitigation | | Risk | Mitigation |
|---|---| | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **"Dashboard is the main feature" = auto-DQ** | The pod grid is *secondary*. The hero is PodMan's **proactive voice/card interventions**. In the demo we barely show the grid; we show PodMan *acting*. | | **"Dashboard is the main feature" = auto-DQ** | The pod grid is _secondary_. The hero is PodMan's **proactive voice/card interventions**. In the demo we barely show the grid; we show PodMan _acting_. |
| Repo must be **public** | Make the GitHub repo public from the start. | | Repo must be **public** | Make the GitHub repo public from the start. |
| **Only what you built** during the event | Everything in this monorepo is new, timestamped by commits. Demo narrates "built today." | | **Only what you built** during the event | Everything in this monorepo is new, timestamped by commits. Demo narrates "built today." |
| New work only | No pre-existing project reuse. | | New work only | No pre-existing project reuse. |
@@ -44,7 +47,7 @@ PodMan does exactly this:
## 2. Prize-stacking map ## 2. Prize-stacking map
| Prize | How PodMan earns it | | Prize | How PodMan earns it |
|---|---| | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Best Gemini 3.5 ($5,000 cash)** | Realtime screen understanding via Gemini 3.5 Flash vision + PodMan's voice via Gemini Live API. Bonus: Live Translate so a multilingual pod hears PodMan in their language. | | **Best Gemini 3.5 ($5,000 cash)** | Realtime screen understanding via Gemini 3.5 Flash vision + PodMan's voice via Gemini Live API. Bonus: Live Translate so a multilingual pod hears PodMan in their language. |
| **Best LiveKit (keyboards)** | LiveKit is the realtime backbone: screen-share + mic + cam tracks in, PodMan voice + data-channel cards out. It's load-bearing, not bolted on. | | **Best LiveKit (keyboards)** | LiveKit is the realtime backbone: screen-share + mic + cam tracks in, PodMan voice + data-channel cards out. It's load-bearing, not bolted on. |
| **Best DigitalOcean (credits)** | Backend PodMan agent + LiveKit agent deployed on DigitalOcean; claim the $200 credits. | | **Best DigitalOcean (credits)** | Backend PodMan agent + LiveKit agent deployed on DigitalOcean; claim the $200 credits. |
@@ -79,27 +82,28 @@ PodMan does exactly this:
└──────────────────────────────────────────┘ └──────────────────────────────────────────┘
``` ```
**The critical reconciliation:** GitHub only knows *pushed* state. The "X is editing this and **The critical reconciliation:** GitHub only knows _pushed_ state. The "X is editing this and
hasn't pushed" signal comes from **vision on the live screen** (filename in the editor tab, hasn't pushed" signal comes from **vision on the live screen** (filename in the editor tab,
visible diff/gutter), optionally cross-checked by an *optional* lightweight local `git status` visible diff/gutter), optionally cross-checked by an _optional_ lightweight local `git status`
reporter the engineer can run. Vision is the headline; the local reporter is a nice-to-have. reporter the engineer can run. Vision is the headline; the local reporter is a nice-to-have.
### Continual-learning loop ### Continual-learning loop
1. **Observe** — per-engineer context every few seconds (sampled frames, not every frame). 1. **Observe** — per-engineer context every few seconds (sampled frames, not every frame).
2. **Store** — append observations to the team model; embed file/feature notes into Voyage 2. **Store** — append observations to the team model; embed file/feature notes into Voyage
vectors in Atlas for retrieval. vectors in Atlas for retrieval.
3. **Predict** — collision detector + PodMan brain decide if/when to intervene. 3. **Predict** — collision detector + PodMan brain decide if/when to intervene.
4. **Outcome** — record whether the warning was acted on / was a true positive. 4. **Outcome** — record whether the warning was acted on / was a true positive.
5. **Adapt** — adjust intervention thresholds, ownership attribution, and prompt context from 5. **Adapt** — adjust intervention thresholds, ownership attribution, and prompt context from
outcomes → fewer false alarms, better targeting over the session. *(This is the "gets outcomes → fewer false alarms, better targeting over the session. _(This is the "gets
better the more you use it" story judges want.)* better the more you use it" story judges want.)_
--- ---
## 4. Stack per folder ## 4. Stack per folder
| Folder | Stack | | Folder | Stack |
|---|---| | ----------- | ----------------------------------------------------------------------------------------------------------- |
| `frontend/` | React + Vite + TypeScript, `livekit-client`, PWA (vite-plugin-pwa), Tailwind | | `frontend/` | React + Vite + TypeScript, `livekit-client`, PWA (vite-plugin-pwa), Tailwind |
| `backend/` | Node + TypeScript, LiveKit server SDK + agents, `@google/genai`, GitHub (Octokit or GitHub MCP), Express/ws | | `backend/` | Node + TypeScript, LiveKit server SDK + agents, `@google/genai`, GitHub (Octokit or GitHub MCP), Express/ws |
| `database/` | MongoDB Atlas (team model, observations, outcomes) + Voyage embeddings for vector recall | | `database/` | MongoDB Atlas (team model, observations, outcomes) + Voyage embeddings for vector recall |
@@ -110,12 +114,12 @@ reporter the engineer can run. Vision is the headline; the local reporter is a n
## 5. 20-hour build order (MVP-first) ## 5. 20-hour build order (MVP-first)
1. **Plumbing** — monorepo installs, shared types, env wiring, LiveKit token endpoint. *(Karti)* 1. **Plumbing** — monorepo installs, shared types, env wiring, LiveKit token endpoint. _(Karti)_
2. **Capture** — frontend: join pod + publish screen/mic; render PodMan card + play voice. *(Zander)* 2. **Capture** — frontend: join pod + publish screen/mic; render PodMan card + play voice. _(Zander)_
3. **Eyes** — backend: subscribe to a screen track, grab a frame, Gemini vision → `EngineerContext`. *(Ramis)* 3. **Eyes** — backend: subscribe to a screen track, grab a frame, Gemini vision → `EngineerContext`. _(Ramis)_
4. **Brain + collision** — fuse two engineers' contexts + GitHub state → detect same-file/feature; PodMan brain composes the intervention. *(Yahya)* 4. **Brain + collision** — fuse two engineers' contexts + GitHub state → detect same-file/feature; PodMan brain composes the intervention. _(Yahya)_
5. **Voice + action** — PodMan speaks (Live API/TTS) into the room + "Open sync PR" via GitHub. *(Yahya + Ramis)* 5. **Voice + action** — PodMan speaks (Live API/TTS) into the room + "Open sync PR" via GitHub. _(Yahya + Ramis)_
6. **Memory/continual learning** — store observations + outcomes; show the team model improving. *(Karti)* 6. **Memory/continual learning** — store observations + outcomes; show the team model improving. _(Karti)_
7. **Deploy on DO + polish demo** — everyone. Rehearse the live demo 3×. 7. **Deploy on DO + polish demo** — everyone. Rehearse the live demo 3×.
> If behind: cut webcam, cut multilingual, cut the local git reporter, **mock the QR join**, > If behind: cut webcam, cut multilingual, cut the local git reporter, **mock the QR join**,
@@ -129,7 +133,7 @@ reporter the engineer can run. Vision is the headline; the local reporter is a n
> the official 4 before submission, or one stays unofficial/support. > the official 4 before submission, or one stays unofficial/support.
| Person | Owns | | Person | Owns |
|---|---| | ---------- | ---------------------------------------------------------------------------------- |
| **Karti** | Repo/infra/plumbing, shared types, memory + continual-learning store, DO deploy | | **Karti** | Repo/infra/plumbing, shared types, memory + continual-learning store, DO deploy |
| **Zander** | Frontend PWA: pod join, capture, PodMan card UI + voice playback | | **Zander** | Frontend PWA: pod join, capture, PodMan card UI + voice playback |
| **Ramis** | Backend realtime: LiveKit room subscribe + frame grab + Gemini vision pipeline | | **Ramis** | Backend realtime: LiveKit room subscribe + frame grab + Gemini vision pipeline |
@@ -141,8 +145,8 @@ reporter the engineer can run. Vision is the headline; the local reporter is a n
1. **(0:00)** Two laptops on screen. Both engineers "join the pod" (QR mock). PodMan greets them by voice. 1. **(0:00)** Two laptops on screen. Both engineers "join the pod" (QR mock). PodMan greets them by voice.
2. **(0:30)** Engineer A opens `auth.ts` and starts editing. PodMan quietly notes it (show the team model tick). 2. **(0:30)** Engineer A opens `auth.ts` and starts editing. PodMan quietly notes it (show the team model tick).
3. **(1:00)** Engineer B opens the *same* `auth.ts` and edits a related function — **neither has pushed.** 3. **(1:00)** Engineer B opens the _same_ `auth.ts` and edits a related function — **neither has pushed.**
4. **(1:20) MONEY MOMENT** — PodMan *interrupts by voice*: "Heads up — Karti and Yahya are both in `auth.ts`, Yahya has unpushed changes. Here's the diff. Want me to open a sync PR?" Card appears with the diff. 4. **(1:20) MONEY MOMENT** — PodMan _interrupts by voice_: "Heads up — Karti and Yahya are both in `auth.ts`, Yahya has unpushed changes. Here's the diff. Want me to open a sync PR?" Card appears with the diff.
5. **(1:50)** One click → PodMan opens a draft PR via GitHub (show it on github.com). 5. **(1:50)** One click → PodMan opens a draft PR via GitHub (show it on github.com).
6. **(2:20)** Show it **learned**: PodMan now knows Karti owns auth; second scenario it's faster/quieter where appropriate → "more useful the more you use it." 6. **(2:20)** Show it **learned**: PodMan now knows Karti owns auth; second scenario it's faster/quieter where appropriate → "more useful the more you use it."
7. **(2:45)** One-liner close: "PodMan — the teammate that sees what git can't." 7. **(2:45)** One-liner close: "PodMan — the teammate that sees what git can't."
@@ -176,9 +180,9 @@ VOYAGE_API_KEY=
## 9. Open risks ## 9. Open risks
| Risk | Mitigation | | Risk | Mitigation |
|---|---| | --------------------------------------------------- | -------------------------------------------------------------------------------- |
| Realtime vision latency/cost | Sample ~1 frame/sec or on-change; downscale frames; cache last context | | Realtime vision latency/cost | Sample ~1 frame/sec or on-change; downscale frames; cache last context |
| LiveKit ↔ Gemini frame plumbing is the hardest part | Build & de-risk it **first** (step 3); have a screenshot-fallback path | | LiveKit ↔ Gemini frame plumbing is the hardest part | Build & de-risk it **first** (step 3); have a screenshot-fallback path |
| "Unpushed" detection is fuzzy | Lead with vision; optional local `git status` reporter for accuracy | | "Unpushed" detection is fuzzy | Lead with vision; optional local `git status` reporter for accuracy |
| On-stage flakiness | Pre-stage the demo repo, rehearse 3×, have a recorded backup of the money moment | | On-stage flakiness | Pre-stage the demo repo, rehearse 3×, have a recorded backup of the money moment |
| Dashboard-DQ optics | Keep UI minimal; demo PodMan *acting*, not a grid | | Dashboard-DQ optics | Keep UI minimal; demo PodMan _acting_, not a grid |