Hosted Capture Pipeline — Email + Voice + Push

Status: design. Target: ADR-0029.

This is the hosted-only continuation of Phase 10. Local self-host already ships the synchronous POST /api/inbox endpoint (ADR-0024). What this doc covers: inbound email, voice transcription, and web push notifications — all of which need hosted infrastructure.

Inbound email (Postmark)

Address shape

Each tenant gets inbox+<slug>@in.Lycato. Configurable forwarder so founder can use a friendlier address ([email protected] → +<slug>@in.Lycato).

Webhook

• Postmark inbound parse posts to https://control.Lycato/webhook/postmark/<tenant_id>?token=....
• Token rotates monthly; mismatch returns 401.
• Webhook handler:
  1. Validates Postmark signature.
  2. Pulls subject, body (text part preferred), attachments.
  3. Calls the tenant container's POST /api/inbox with: { title: subject, body: text, source: "email" }.
  4. Saves attachments (PDFs, etc.) into inbox/attachments/<id>/.
• 5 MB total per-email cap. Larger → bounce with explanation.

Reply-by-email

Out of scope for v0.4.0. Reply path is "founder edits in cockpit."

Spam

Postmark's built-in spam filter + sender allowlist on the tenant side (set in Settings).

Voice capture (Whisper)

Flow

1. PWA "record" button → captures audio as audio/webm (Opus).
2. POSTs to /api/inbox/voice with the audio blob (≤2 minutes, ≤5 MB).
3. Server stores raw audio under inbox/attachments/<id>/audio.webm.
4. Server calls Whisper (BYO OpenAI key from the tenant secret store) with the audio.
5. Transcript written to inbox/<id>.md as the body. Title is the first sentence (capped 80 chars).
6. Original audio retained for 30 days then deleted (founder can opt-in to keep longer).

Why Whisper not local

Local Whisper.cpp would require shipping a 200MB+ model per container. Cost asymmetry: a paid Whisper API call is ~$0.006/min of audio; voice capture is rare; the per-tenant amortised cost is negligible.

Cost guardrails

• Tenant-side per-day cap: 60 minutes default.
• Tenant-side per-month cap: 1000 minutes default.
• Both raise/lower in Settings; both have a hard ceiling at 10x default to protect runaway scripts.

Web push notifications

Use cases

1. High-risk approval pending for >2 hours.
2. Daily-digest agent failed during scheduled run.
3. Cofounder approved a branch (J2 closes faster).

Stack

• Web Push API (RFC 8030) — browser-agnostic, no Firebase / APNs bridge needed for the alpha.
• VAPID keys per tenant; subscription endpoint stored alongside the user session.
• Payloads are tiny: { kind, title, url }. The actual content lives in the cockpit, never in the push.

Opt-in

Per-user, per-kind. Founder can subscribe to "approval pending" but mute "daily-digest failed" if it's noisy. Default = all off; opt-in on first cockpit visit after enabling notifications.

Privacy

No content in payloads. Subscription endpoints are encrypted with the tenant DEK (treated as a key-equivalent because they can be abused to send push to the founder's device).

Local self-host

Self-host installs do NOT get any of this. Workarounds:

• Email: any IMAP-poller can land emails as files in inbox/ — write a tiny adapter.
• Voice: use lycato inbox voice <file> (future) — a local Whisper call via BYO key.
• Push: use macOS Shortcut + the local POST /api/inbox endpoint.

Self-host parity for these is not a v0.4.0 goal; if a self-host founder pushes for it, the SDK already provides the surface to build it.

What's intentionally absent

• SMS capture. Twilio cost / spam risk not worth it for the segment.
• Multi-language voice. Whisper handles many languages OK; we don't add per-language tuning in v0.4.0.
• Native iOS / Android apps. PWA covers 90% of capture; native enters scope post v1.0.