# Emergency Fix Pack — MetoYou / Toju

> **Purpose:** Give other agents a single, user-first map of what this app is, how critical features are supposed to work, where the code lies, and the exact order to fix failures.
>
> **Constraint for this pack:** Analysis and planning only. Product code was not changed when this pack was authored (2026-08-12).
>
> **Primary surface:** `toju-app/` + targeted `electron/` (auth secret store / IPC). Expand to `server/` / `e2e/` only when a packet says so.

---

## How to use this pack

1. Read **this file** + `01-product-overview.md`.
2. Pick a work packet from `12-agent-work-packets.md` (do not invent parallel scope).
3. Open the matching issue file (`04`–`09`) for user story, intended behavior, failure modes, code paths, and proof.
4. Follow priority order in `11-fix-priority-plan.md` unless the user overrides.
5. Before coding: run the repo **interview-before-implement** ritual (choices A/B/C) unless the user says “just fix it” / “no interview” or an active handoff already records approved decisions.
6. When a packet finishes: update `11-fix-priority-plan.md` status checkboxes and clear or rewrite `agents-docs/HANDOFF.md` per `.cursor/rules/handoff.mdc`.

---

## File index

| File | Contents |
|------|----------|
| `00-README.md` | This index and rules of engagement |
| `01-product-overview.md` | What MetoYou/Toju is (user + architecture) |
| `02-user-journeys.md` | End-to-end journeys: login → rooms → chat → voice → multi-server |
| `03-architecture-map.md` | Domains, transports, identity model, key paths |
| `04-auth-login-bugs.md` | Login / authorize / silent provision failures |
| `05-signaling-multi-server.md` | Signal servers, WS drops, room affinity, presence |
| `06-voice-webrtc-bugs.md` | Voice, camera, screen-share, peer negotiation |
| `07-data-channel-drops.md` | Control-plane DC failures and recovery gaps |
| `08-messaging-visibility.md` | “Messages not seen” / sync / fallback |
| `09-identity-cross-signal.md` | Home vs foreign actor ids (calls, DMs, voice routing) |
| `10-code-lies-doc-debt.md` | Docs/lessons that disagree with the tree |
| `11-fix-priority-plan.md` | Ordered waves, acceptance, proof |
| `12-agent-work-packets.md` | Copy-paste packets for new chats |
| `13-validated-findings-fable-5-handoff.md` | Code-validated findings, corrected priorities, E2E limits, and implementation handoff |
| `e2e-failures/` | Latest full Playwright e2e run baseline (errors + slow tests) |

---

## Product in one paragraph (user view)

MetoYou (product client **Toju**) is a **desktop-first P2P chat app**: you log in once to a **signal server**, join **chat-servers** (communities with text + voice channels), talk in text, join voice, share screen/camera, and DM / call people. Media and most chat go **peer-to-peer over WebRTC**. The signal server only authenticates you, tracks who is in which room, and relays WebRTC offers / narrow chat & DM fallbacks. You may use **many signal servers**; the app is supposed to create a linked account on each new host **silently** after the first home login.

---

## Critical bug themes (user language)

1. **“It keeps asking me to log in”** even though I’m already signed in (especially when joining something on another signal server).
2. **“Voice doesn’t work / one-way / connecting forever”** — often after reconnect or when people registered on different signal servers.
3. **“Connection / data channel drops”** — chat, attachments, emoji, and sometimes voice die; recovery is silent or tears everything down.
4. **“I sent a message but they don’t see it”** (or only some devices see it) — presence missing, P2P sync dead, or wrong identity.
5. **“Call rings nobody / I’m In Voice alone”** — cross-signal identity mismatch on outbound or inbound paths.
6. **Different signal servers** make all of the above worse because **home user id ≠ foreign provisioned actor id**, and signaling is **not federated**.

---

## Related existing research (do not redo)

- Active research story: `agents-docs/user-stories/silent-cross-signal-server-auth.md`
- Feature contracts: `agents-docs/features/{authentication,signaling,voice-webrtc,messaging,server-directory}.md`
- Realtime deep dive: `toju-app/src/app/infrastructure/realtime/README.md`
- Lessons index: `agents-docs/LESSONS-INDEX.md` — tags `[auth] [realtime] [direct-call] [direct-message] [identity] [signaling]`

---

## Non-goals of this pack

- Implementing fixes (separate chats / packets).
- Rewriting the whole monorepo.
- Treating unit-green alone as “done” — each packet lists user-visible proof.