recap/docs/path-2b-and-path-1-interweave.md

Path 2B + Path 1 Interweave Plan

Companion doc to architecture-simplification-plan.md (Path 1) and the chat thread that proposed Path 2A (relay-only upload, ship first).

This doc covers:

1. Path 2B — bringing internal-meeting analysis into the Recaps cloud frontend as a first-class feature alongside YouTube/podcast summaries.
2. How Path 2B depends on Path 1 — what Path 1 unlocks vs. what could be partially built without it.
3. Migration path — how Path 2A's relay-only upload data flows forward into Path 2B's cloud-side library.

---

Context

Recap Relay (the operator-side backend) is now generic enough to analyze ANY audio — not just YouTube/podcasts. The download step is the only YouTube-specific code; everything downstream (transcribe → diarize → cluster → analyze → polish) applies cleanly to arbitrary audio. Path 2A exposes this via a relay-admin-only upload UI so operator Grant can run internal meeting analysis on his own hardware TODAY without waiting on Recaps multi-tenant work.

Path 2B is the longer arc: same capability surfaced in the cloud Recaps app, so signed-in users can submit private meeting audio, manage it alongside their other content, and (optionally) share with colleagues.

---

Path 1 (recap) state

architecture-simplification-plan.md defines:

• One Recaps binary, two modes via RECAP_MODE=single|multi env var
• Magic-link + optional password auth via StartOS SMTP
• Per-user library at /data/history/<userId>/<sessionId>.json
• Per-user keysat license (mintable via Keysat admin API)
• BTCPay subscription + one-time credit-purchase flows
• Lite-settings UI for non-operator cloud users
• Self-hosted operator stays single-tenant by default; the .s9pk ships free + open

Status: written but not built. The relay-side work has continued in parallel (FIFO queue, clustering suppression, polish pass) which strengthens the case for Path 1 — the cloud user experience benefits from all of it, and the keysat-license layer is increasingly friction-without-value for cloud users who already have email-verified accounts.

---

Path 2B — internal meetings in cloud Recaps

What it looks like

A signed-in Recaps user gets a second submission affordance alongside the existing "Paste a YouTube/podcast link" input:

┌─────────────────────────────────────────────────────────┐
│ Submit content                                          │
│  ○ Paste a YouTube/podcast link                         │
│  ○ Upload audio file (private)        [Choose file…]    │
│                                                         │
│  Title:        [_____________________________]          │
│  Participants: [_____________________________]  (opt)   │
│  Meeting type: [▼ default / 1:1 / all-hands / …]        │
│                                                         │
│             [ Summarize ]                               │
└─────────────────────────────────────────────────────────┘

The submission flows the same way YouTube submissions do: Recaps-app → Relay (/relay/v1/summarize-upload for files, existing /relay/v1/summarize-url for URLs). The relay handles both via the same pipeline — only the input step differs (download vs. multipart receive).

Library + rendering

Each saved session in the cloud user's library has a type field:

• "youtube" — existing rendering (video player + topics + transcript chips)
• "podcast" — existing podcast rendering (audio player + topics + transcript)
• "meeting" — new rendering: no media player; topics + transcript chips expandable below each topic card; PLUS a "Meeting analysis" block at the top with Decisions / Action Items / Open Questions / Key Quotes (the structured-extras pass from Phase 2 of Path 2A)

Library list view shows a small icon distinguishing meeting items so the user can filter at a glance.

Privacy + sharing

Meetings are PRIVATE by default — visible only to the submitting user. Two later features:

• Share with team — a meeting can be optionally shared with N named cloud-Recaps users (each looks up by email). Other users see it in a "Shared with me" library section.
• Export to markdown / PDF — already exists for YouTube content; add the meeting-extras blocks to the export.

Audio handling

• Uploaded audio goes from browser → Recaps-app (Node Express, multipart middleware) → Recap Relay (forward as multipart to /relay/v1/summarize-upload).
• Recaps-app's tmp file is deleted immediately after the relay acknowledges receipt.
• Relay's tmp file is deleted after the pipeline completes.
• NEITHER side keeps the audio. The TRANSCRIPT + analysis are saved. If the user wants to re-process (different prompt set), they'd re-upload the audio.
• The transcript stays in the user's per-user library at /data/history/<userId>/<sessionId>.json, scoped + isolated.

---

Path 2B's hard prerequisite: Path 1

Path 2B fundamentally requires multi-tenant auth in Recaps. Without Path 1:

• No per-user library separation
• No way to know whether the meeting audio is private to a user vs. visible to everyone running this Recaps instance
• No way to share with named other users
• No way to bill upload-heavy users differently from URL-only users (uploads might warrant a different price tier given the storage cost)

You COULD build a stripped-down Path 2B on single-tenant Recaps — operator uploads audio, it's saved to the operator's library, no sharing. But that's roughly equivalent to Path 2A with a fancier UI, just on the wrong side of the codebase split (Recaps-app vs. relay). Not worth the duplication.

So: ship Path 2A as the immediate beachhead, do Path 1 next, then Path 2B on top.

What Path 1 unlocks (relevant to 2B)

The Path 1 doc already covers most of what 2B needs:

• Per-user library at /data/history/<userId>/*.json
• Auth-aware request scoping (req.userId)
• Per-user keysat license OR the simplified user-id + tier headers
• BTCPay subscription tracking (for billing upload-heavy use)

Path 1's "Lite-settings panel for cloud users" already imagines a post-auth Recaps UI without operator config noise. The submission input would extend in 2B to add the upload option.

The relay-side header migration Path 1 proposes (X-Recap-User-Id + X-Recap-User-Tier replacing the bearer license token) is also beneficial for 2B — uploads from a single user with N concurrent browsers all carry the same user-id, so credit accounting is per-user not per-install.

---

How Path 2A's data flows into Path 2B

When Path 2A ships (relay-only upload, results saved to /data/internal-meetings/<id>.json on the relay), those summaries are tied to the OPERATOR (Grant) — there's no cloud-user concept yet.

When Path 2B lands:

1. Migration script — walks /data/internal-meetings/*.json and re-homes each entry under the operator's cloud user account (/data/history/owner/*.json initially, then /data/history/ <operator-user-id>/*.json after Path 1's owner→admin rename).
2. Same JSON shape — Path 2A should save in a shape compatible with Path 2B's expected library shape (chunks + entries + speakers
   • meeting-extras). One way to guarantee this: design the Phase 1 save shape now to match what Recaps' saveToHistory produces for type=meeting, even though no Recaps UI consumes it yet.
3. No re-processing needed — transcripts and analysis transfer verbatim. The user just sees them appear in their cloud library.

The relay-side upload endpoint (/relay/v1/summarize-upload) is the same in both worlds. Path 2A calls it via the operator dashboard's admin auth; Path 2B calls it via Recaps-app server proxying a signed-in cloud user's POST.

So the relay code path is built once and serves both.

---

Operator-editable prompt sets (Phase 3 in 2A; carries to 2B)

The "meeting type" dropdown is operator-editable. Each set has:

• Name (e.g. "1:1 with direct report")
• Topic-analysis prompt template (replaces the YouTube/podcast version)
• Meeting-extras prompt template (Decisions / Action Items / ...)
• Optional metadata schema overrides (e.g. "this meeting type always expects 2 participants")

Stored in relay_meeting_prompt_sets_json config field. Operator edits via the dashboard (similar to existing prompts panel). Cloud Recaps users pick a set at submission time; the relay applies it during analyze + polish.

Default sets ship built-in:

• default — neutral meeting prompt, all sections enabled
• 1on1 — emphasizes Action Items + Open Questions; light on Decisions
• all-hands — emphasizes Decisions + Key Quotes; less actionable
• customer-interview — emphasizes Key Quotes + Open Questions; light on Decisions
• standup — short-form; Action Items + Open Questions only

---

Suggested order of operations

1. Path 2A Phase 1 — relay-only upload, no extras, basic topic+transcript rendering. ~2-3 days.
2. Path 2A Phase 2 — meeting-extras analysis pass (Decisions / Action Items / Open Questions / Key Quotes). ~1-2 days.
3. Path 2A Phase 3 — prompt sets dropdown. ~1 day.
4. (Use Path 2A in production for some weeks; gather feedback on prompts, output quality, UX.)
5. Path 1 — multi-tenant Recaps. ~3-4 weeks per the existing architecture-simplification doc, modulo amendments.
6. Path 2B — surface internal meetings in cloud Recaps. ~1.5-2 weeks given Path 1 has shipped. Migrates the Path 2A artifacts into the new per-user library.

Total wall time: ~6-8 weeks for the full arc. Path 2A capability available to operator after step 1 (~2-3 days). Cloud users get meetings after step 6.

---

Open questions

These should be settled BEFORE Path 2B build starts:

1. Pricing for uploads. Does an upload count the same as a URL submission against a user's monthly credit cap? Or is it priced differently to reflect the upload bandwidth + storage cost? My default: same price (1 credit per submission) — bandwidth cost is trivial, storage is just JSON.

2. Audio retention. Default: never retain. Optional per-user setting "keep audio for 7/30/90 days so I can re-process with a different prompt set"? Adds operator storage cost; only worth it if users actually want it.

3. Sharing model. Path 2B Phase 1 = no sharing, private only. Phase 2 = shared with N named users. Phase 3 = optional public share URL. Each phase adds auth/permission complexity. Worth designing the data model now ({ ownerId, sharedWith: [userId] }) even if only ownerId is populated in Phase 1.

4. Speaker name persistence. If a user identifies "Speaker_A" as "Matt Hill" in one meeting, should that name auto-suggest in the next meeting if a fingerprint match is found? Requires storing fingerprints per-user across meetings. Big privacy + product decision. My instinct: opt-in toggle in user settings, default off.

5. Meeting type defaults. Should Recaps' submission flow have a default meeting type, or force the user to pick? My instinct: default to "default" set; let users pick if they want.

---

Decision points for Grant

• Confirm the phasing above (2A → 1 → 2B) is the right order
• Pre-commit to the "uploaded audio is never retained" default — it's the privacy-safer choice and aligns with how YouTube downloads already work
• Pick a side on the open questions above before Path 2B starts, OR defer them as Phase 2/3 of Path 2B