docs: add workflow research, architecture, strategy, and critique

Generated by the planning workflow: validated API findings (Gemini/LiveKit/
GitHub/DO), full architecture synthesis, winning strategy, and red-team critique.
Canonical source files staged under docs/generated/files/.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

docs/generated/files/backend/src/agent.ts

@@ -0,0 +1,79 @@
+import {
+  Room,
+  RoomEvent,
+  TrackKind,
+  TrackSource,
+  VideoStream,
+  VideoBufferType,
+  dispose,
+  type RemoteTrack,
+  type RemoteTrackPublication,
+  type RemoteParticipant,
+} from '@livekit/rtc-node';
+import sharp from 'sharp';
+import { AccessToken } from 'livekit-server-sdk';
+import { env } from './env.js';
+import { PodMan } from './agent/podman.js';
+
+const POD_ROOM = process.env.POD_ROOM ?? 'demo-pod';
+const SAMPLE_INTERVAL_MS = 1000; // ~1 fps to the vision model
+
+async function agentToken(room: string): Promise<string> {
+  const at = new AccessToken(env.LIVEKIT_API_KEY, env.LIVEKIT_API_SECRET, {
+    identity: 'podman-agent',
+    name: 'PodMan',
+    ttl: '4h',
+  });
+  at.addGrant({ roomJoin: true, room, canPublish: true, canSubscribe: true, canPublishData: true });
+  return at.toJwt();
+}
+
+async function main() {
+  const room = new Room();
+  const podman = new PodMan(room, POD_ROOM);
+  await room.connect(env.LIVEKIT_URL, await agentToken(POD_ROOM), {
+    autoSubscribe: true,
+    dynacast: true,
+  });
+  await podman.start();
+  console.log(`[agent] PodMan joined room ${POD_ROOM}`);
+
+  const lastSent = new Map<string, number>();
+
+  room.on(
+    RoomEvent.TrackSubscribed,
+    (track: RemoteTrack, pub: RemoteTrackPublication, participant: RemoteParticipant) => {
+      if (track.kind !== TrackKind.KIND_VIDEO || pub.source !== TrackSource.SOURCE_SCREENSHARE) return;
+      const id = participant.identity;
+      const stream = new VideoStream(track);
+      void (async () => {
+        for await (const event of stream) {
+          const now = Date.now();
+          if (now - (lastSent.get(id) ?? 0) < SAMPLE_INTERVAL_MS) continue; // THROTTLE
+          lastSent.set(id, now);
+          const rgba = event.frame.convert(VideoBufferType.RGBA);
+          const jpeg = await sharp(Buffer.from(rgba.data), {
+            raw: { width: rgba.width, height: rgba.height, channels: 4 },
+          })
+            .resize({ width: 1280, withoutEnlargement: true })
+            .jpeg({ quality: 70 })
+            .toBuffer();
+          await podman.onScreenFrame(id, jpeg);
+        }
+      })();
+    },
+  );
+
+  const shutdown = async () => {
+    await room.disconnect();
+    await dispose();
+    process.exit(0);
+  };
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
+}
+
+main().catch((e) => {
+  console.error('[agent] fatal', e);
+  process.exit(1);
+});

docs/generated/files/backend/src/agent/podman.ts

@@ -0,0 +1,75 @@
+import { RoomEvent, type Room } from '@livekit/rtc-node';
+import type { EngineerContext, Collision, Intervention, DataMessage } from '@podman/shared';
+import { DATA_TOPIC } from '@podman/shared';
+import { analyzeFrame } from '../vision/gemini.js';
+import { detectCollisions } from '../collision/detector.js';
+import { getGithubState } from '../github/client.js';
+import { recordObservation, recordCollision, recordIntervention } from '../memory/store.js';
+import { recallSimilar } from '../memory/vectors.js';
+import { shouldIntervene, preferredAction } from '../memory/policy.js';
+import { speak } from '../voice/live.js';
+
+export class PodMan {
+  private contexts = new Map<string, EngineerContext>();
+  private encoder = new TextEncoder();
+
+  constructor(
+    private room: Room,
+    private podId: string,
+  ) {}
+
+  async start(): Promise<void> {
+    // Tier-2 optional ground-truth + engineer ACKs arrive over the data channel.
+    this.room.on(RoomEvent.DataReceived, (payload) => {
+      try {
+        const msg = JSON.parse(new TextDecoder().decode(payload)) as DataMessage;
+        if (msg.type === 'GIT_REPORT') {
+          const c = this.contexts.get(msg.report.engineerId);
+          if (c) c.hasUnpushedChanges = msg.report.unpushedCount > 0 || msg.report.dirtyFiles.length > 0;
+        }
+      } catch { /* ignore malformed */ }
+    });
+  }
+
+  async onScreenFrame(engineerId: string, jpeg: Buffer): Promise<void> {
+    const ctx = await analyzeFrame(engineerId, this.podId, jpeg);
+    this.contexts.set(engineerId, ctx);
+    await recordObservation(ctx);
+
+    const github = await getGithubState(); // cached
+    const collisions = detectCollisions([...this.contexts.values()], github);
+    for (const collision of collisions) await this.handle(collision);
+  }
+
+  private async handle(collision: Collision): Promise<void> {
+    const prior = await recallSimilar(collision); // Loop A: vector recall raises confidence
+    if (prior) collision.severity = 'critical';
+    if (!shouldIntervene(collision, prior)) return; // Loop B: policy gate
+
+    await recordCollision(collision);
+    const action = preferredAction(collision, prior);
+    const names = collision.engineers.join(' and ');
+    const message = `${names} are both editing ${collision.file}` +
+      (collision.githubState?.unpushed ? ' and one has unpushed changes.' : '.') +
+      (prior ? ` I've seen this conflict pattern before.` : '');
+
+    const intervention: Intervention = {
+      id: `int_${Date.now()}`,
+      collisionId: collision.id,
+      podId: this.podId,
+      kind: 'card',
+      message,
+      suggestedAction: action,
+      status: 'pending',
+      createdAt: new Date().toISOString(),
+    };
+    await recordIntervention(intervention);
+
+    const data: DataMessage = { type: 'COLLISION', collision, intervention };
+    await this.room.localParticipant?.publishData(
+      this.encoder.encode(JSON.stringify(data)),
+      { reliable: true, topic: DATA_TOPIC },
+    );
+    await speak(this.room, message); // gemini-3.1-flash-live voice into the room
+  }
+}

docs/generated/files/backend/src/collision/detector.ts

@@ -0,0 +1,40 @@
+import type { EngineerContext, Collision, GithubStateSnapshot } from '@podman/shared';
+
+function normalize(path?: string): string | undefined {
+  if (!path) return undefined;
+  return path.replace(/^\.?\/?(src\/)?/, 'src/').toLowerCase();
+}
+
+export function detectCollisions(
+  contexts: EngineerContext[],
+  github: GithubStateSnapshot,
+): Collision[] {
+  const byFile = new Map<string, EngineerContext[]>();
+  for (const c of contexts) {
+    const f = normalize(c.currentFile);
+    if (!f) continue;
+    (byFile.get(f) ?? byFile.set(f, []).get(f)!).push(c);
+  }
+
+  const out: Collision[] = [];
+  for (const [file, group] of byFile) {
+    const engineers = [...new Set(group.map((g) => g.engineerId))];
+    if (engineers.length < 2) continue;
+
+    const anyUnpushed =
+      group.some((g) => g.hasUnpushedChanges) || github.unpushed === true;
+    if (!anyUnpushed) continue; // the crux GitHub alone cannot answer
+
+    out.push({
+      id: `col_${file}_${Date.now()}`,
+      podId: group[0]!.podId,
+      file,
+      symbol: group.find((g) => g.currentSymbol)?.currentSymbol,
+      engineers,
+      severity: 'warn',
+      githubState: { ...github, unpushed: anyUnpushed },
+      detectedAt: new Date().toISOString(),
+    });
+  }
+  return out;
+}

docs/generated/files/backend/src/env.ts

@@ -0,0 +1,35 @@
+import 'dotenv/config';
+
+function req(name: string): string {
+  const v = process.env[name];
+  if (!v) throw new Error(`Missing required env var: ${name}`);
+  return v;
+}
+function opt(name: string, fallback = ''): string {
+  return process.env[name] ?? fallback;
+}
+
+export const env = {
+  // LiveKit
+  LIVEKIT_URL: req('LIVEKIT_URL'),
+  LIVEKIT_API_KEY: req('LIVEKIT_API_KEY'),
+  LIVEKIT_API_SECRET: req('LIVEKIT_API_SECRET'),
+  // Gemini
+  GEMINI_API_KEY: req('GEMINI_API_KEY'),
+  GEMINI_VISION_MODEL: opt('GEMINI_VISION_MODEL', 'gemini-3.5-flash'),
+  GEMINI_LIVE_MODEL: opt('GEMINI_LIVE_MODEL', 'gemini-3.1-flash-live-preview'),
+  // GitHub
+  GITHUB_TOKEN: req('GITHUB_TOKEN'),
+  GITHUB_REPO: req('GITHUB_REPO'), // owner/name
+  // Mongo + Voyage
+  MONGODB_URI: req('MONGODB_URI'),
+  VOYAGE_API_KEY: opt('VOYAGE_API_KEY'),
+  // Server
+  PORT: Number(opt('PORT', '8787')),
+} as const;
+
+export function repoParts(): { owner: string; repo: string } {
+  const [owner, repo] = env.GITHUB_REPO.split('/');
+  if (!owner || !repo) throw new Error('GITHUB_REPO must be "owner/name"');
+  return { owner, repo };
+}

docs/generated/files/backend/src/github/client.ts

@@ -0,0 +1,46 @@
+import { Octokit } from 'octokit';
+import type { GithubStateSnapshot } from '@podman/shared';
+import { env, repoParts } from '../env.js';
+
+const gh = new Octokit({ auth: env.GITHUB_TOKEN });
+let cache: { at: number; state: GithubStateSnapshot } | null = null;
+const TTL_MS = 5000;
+
+export async function getGithubState(): Promise<GithubStateSnapshot> {
+  if (cache && Date.now() - cache.at < TTL_MS) return cache.state;
+  const { owner, repo } = repoParts();
+  const [{ data: branches }] = await Promise.all([
+    gh.rest.repos.listBranches({ owner, repo, per_page: 50 }),
+  ]);
+  const state: GithubStateSnapshot = {
+    branches: Object.fromEntries(branches.map((b) => [b.name, b.commit.sha])),
+    openPrs: [],
+    unpushed: undefined, // vision/Tier-2 fills this; API cannot know
+  };
+  cache = { at: Date.now(), state };
+  return state;
+}
+
+export async function remoteHasFile(path: string, ref = 'main'): Promise<boolean> {
+  const { owner, repo } = repoParts();
+  return gh.rest.repos
+    .getContent({ owner, repo, path, ref })
+    .then(() => true)
+    .catch(() => false);
+}
+
+export async function createSyncPr(input: { headBranch: string; file: string; summary: string }) {
+  const { owner, repo } = repoParts();
+  const { data: mainRef } = await gh.rest.git.getRef({ owner, repo, ref: 'heads/main' });
+  const branch = `podman-sync-${Date.now()}`;
+  await gh.rest.git.createRef({ owner, repo, ref: `refs/heads/${branch}`, sha: mainRef.object.sha });
+  const { data: pr } = await gh.rest.pulls.create({
+    owner,
+    repo,
+    title: `PodMan: sync ${input.file} before collision`,
+    head: branch,
+    base: 'main',
+    body: input.summary,
+  });
+  return pr;
+}

docs/generated/files/backend/src/server.ts

@@ -0,0 +1,59 @@
+import express from 'express';
+import { createServer } from 'node:http';
+import { WebSocketServer } from 'ws';
+import { AccessToken } from 'livekit-server-sdk';
+import { env } from './env.js';
+import { createSyncPr } from './github/client.js';
+import { recordOutcome } from './memory/store.js';
+import type { InterventionOutcome } from '@podman/shared';
+
+const app = express();
+app.use(express.json());
+app.get('/health', (_req, res) => res.json({ ok: true }));
+
+// Mint a LiveKit token for an engineer joining a pod.
+app.post('/api/token', async (req, res) => {
+  const { room, identity, name, githubLogin } = req.body ?? {};
+  if (!room || !identity) return res.status(400).json({ error: 'room+identity required' });
+  const at = new AccessToken(env.LIVEKIT_API_KEY, env.LIVEKIT_API_SECRET, {
+    identity,
+    name,
+    ttl: '4h',
+    metadata: JSON.stringify({ githubLogin: githubLogin ?? name }),
+  });
+  at.addGrant({ roomJoin: true, room, canPublish: true, canSubscribe: true, canPublishData: true });
+  res.json({ token: await at.toJwt(), url: env.LIVEKIT_URL });
+});
+
+// PodMan's hero action: open a real sync PR on the PUBLIC repo.
+app.post('/api/sync-pr', async (req, res) => {
+  try {
+    const { headBranch, file, summary } = req.body ?? {};
+    const pr = await createSyncPr({ headBranch, file, summary });
+    res.json({ url: pr.html_url, number: pr.number });
+  } catch (e) {
+    res.status(500).json({ error: (e as Error).message });
+  }
+});
+
+// Outcome ACK -> closes the continual-learning policy loop.
+app.post('/api/outcome', async (req, res) => {
+  await recordOutcome(req.body as InterventionOutcome);
+  res.json({ ok: true });
+});
+
+const http = createServer(app);
+
+// ws relay: the agent pushes collision/intervention JSON here; PWAs subscribed by pod receive it.
+const wss = new WebSocketServer({ server: http, path: '/api/events' });
+const clients = new Set<import('ws').WebSocket>();
+wss.on('connection', (ws) => {
+  clients.add(ws);
+  ws.on('close', () => clients.delete(ws));
+  ws.on('message', (buf) => {
+    // fan out agent->PWA events; (auth/pod-scoping omitted for hackathon brevity)
+    for (const c of clients) if (c !== ws && c.readyState === 1) c.send(buf.toString());
+  });
+});
+
+http.listen(env.PORT, '0.0.0.0', () => console.log(`[server] :${env.PORT}`));

docs/generated/files/backend/src/vision/gemini.ts

@@ -0,0 +1,53 @@
+import { GoogleGenAI, Type } from '@google/genai';
+import type { EngineerContext } from '@podman/shared';
+import { env } from '../env.js';
+
+const ai = new GoogleGenAI({ apiKey: env.GEMINI_API_KEY });
+
+const SCHEMA = {
+  type: Type.OBJECT,
+  properties: {
+    currentFile: { type: Type.STRING, description: 'open file path if visible, e.g. src/auth/session.ts' },
+    currentSymbol: { type: Type.STRING, description: 'function/class under the cursor' },
+    activity: { type: Type.STRING, description: 'editing | reading | debugging | terminal | PR review' },
+    hasUnpushedChanges: { type: Type.BOOLEAN, description: 'dirty git gutter / modified markers visible' },
+    confidence: { type: Type.NUMBER, description: '0..1 confidence in this read' },
+  },
+  propertyOrdering: ['currentFile', 'currentSymbol', 'activity', 'hasUnpushedChanges', 'confidence'],
+} as const;
+
+export async function analyzeFrame(
+  engineerId: string,
+  podId: string,
+  jpeg: Buffer,
+): Promise<EngineerContext> {
+  const res = await ai.models.generateContent({
+    model: env.GEMINI_VISION_MODEL,
+    contents: [
+      {
+        role: 'user',
+        parts: [
+          { text: "You are PodMan watching an engineer's screen. Identify what file/symbol they are working on and whether there are uncommitted edits. JSON only." },
+          { inlineData: { mimeType: 'image/jpeg', data: jpeg.toString('base64') } },
+        ],
+      },
+    ],
+    config: {
+      responseMimeType: 'application/json',
+      responseJsonSchema: SCHEMA,
+      thinkingConfig: { thinkingBudget: 0 }, // minimal thinking: low latency/cost for ambient loop
+      mediaResolution: 'MEDIA_RESOLUTION_LOW',
+    },
+  });
+  const parsed = JSON.parse(res.text ?? '{}') as Partial<EngineerContext>;
+  return {
+    engineerId,
+    podId,
+    currentFile: parsed.currentFile,
+    currentSymbol: parsed.currentSymbol,
+    activity: parsed.activity,
+    hasUnpushedChanges: parsed.hasUnpushedChanges,
+    confidence: parsed.confidence ?? 0.5,
+    observedAt: new Date().toISOString(),
+  };
+}