Capgo Builder — Contact Support (Simplified)

docs/superpowers/specs/2026-06-03-builder-contact-support-simple-design.md · 2026-06-03

✅ ACTIVE PLAN — local logs file + mailto:, zero backend. Supersedes the shelved backend/bridge design.

1 · Goal

When a builder run fails, save the user's logs to a local file and open a pre-filled email to support@capgo.app. The user attaches the file and sends. Zero backend. That's the whole feature.

2 · Why this is simpler AND more correct

Every hard problem in the shelved design came from us sending a ticket programmatically through the Cap-go/automations bridge (the ownedOutboundCopy heuristic, the double-delivery race, CC/Reply-To threading, a backend proxy, Email Service limits…). When the user sends from their own client, it all evaporates:

The user is a genuine external sender to support@capgo.app → the existing bridge ingests it natively, opens a Discord thread, and replies thread back to the user automatically.
The team (incl. michael) sees it in Discord as normal — no fan-out, no relay.
We build none of: backend endpoint, worker /support, Email Service binding, rate limiting, CC/BCC, bridge changes.

Only cost: mailto: can't auto-attach, so the user does one "attach + send" — made trivial via save + clipboard + Finder reveal.

3 · Flow

Hidden internal log captured during builder/onboarding (verbose, secret-redacted, CLI-only) — including non-build failures (onboarding errors, raw Apple/Google API errors). Build failures also fold in the captured build log.
On failure → menu offers 📨 Email Capgo support (+ 🤖 Ask AI when a build log exists).
On "Email Capgo support", the CLI first shows a confirmation ("We'll save your logs, reveal them in Finder (macOS), and open a pre-filled email to support@capgo.app — continue?" — the Finder clause shows only on macOS). Only on confirm it:
- writes ONE combined bundle in both forms: builder-support-<appId>-<ts>.log (readable) and .log.gz (compact), in ~/.capgo-credentials/support/;
- copies the GZIPPED .log.gz path to the clipboard; on macOS reveals it in Finder (open -R);
- opens mailto:support@capgo.app with a pre-filled subject + short body;
- prints: "Opened an email to support@capgo.app and saved your logs to <path>.log.gz (copied to clipboard). Attach that file and send."
Done. No network calls of our own.

mailto:support@capgo.app
  ?subject=Capgo Builder support — <appId> (<platform>)
  &body=<short greeting + 1-line problem + tiny diagnostics summary +
         "Please attach the logs file at <path> (copied to your clipboard).">

Body kept short (mailto URLs ~1.8–2 KB limit); full logs live in the attached file. Opened via the existing open npm package.

4 · Reuse map (all already in `cli/src`)

Need	Reuse
Open mail client	`open` npm pkg (used in init/command.ts, bundle/builder-cta.ts, onboarding UIs)
Save file + tell user where	the `.env` export pattern in `build/credentials-manage.ts`
Copy path to clipboard	`copyToClipboard()` (pbcopy/xclip/wl-copy) in `credentials-manage.ts`
Write the bundle	extend `writeOnboardingSupportBundle()` in `onboarding-support.ts`
Gzip variant	`node:zlib` `gzipSync`
Verbose log (non-build failures)	extend the `src/debug.ts` / internal-log idea

5 · Internal log

Module: cli/src/support/internal-log.ts, append-as-you-go → ~/.capgo-credentials/support/internal-<appId>-<ts>.log (survives crashes).
Captures: all levels incl. debug; API req/resp incl. raw Apple & Google API errors; shell commands w/ stdout/stderr; diagnostics.
Secret redaction (CLI-only) before bytes hit disk; the email body / CLI output tells the user secrets were removed.

6 · Components to build (CLI only)

support/internal-log.ts — verbose logger + redaction; wired into builder/onboarding + API/shell sites.
Extend writeOnboardingSupportBundle → one combined bundle, emit both .log and .log.gz.
support/contact-support.ts — write files → clipboard → macOS reveal → build mailto: URL → open() → print instructions (graceful fallbacks).
Wire 📨 Email Capgo support into iOS/Android failure menus + init/command.ts (support-first; AI only with a build log).
Tests: redaction, bundle assembly, both-file output, mailto URL (escaping + body length cap), menu logic, clipboard/reveal (mocked).

7 · Explicitly NOT built (vs shelved design)

Backend /build/support · worker /support · Cloudflare Email Service / send_email · automations-bridge changes · CC/BCC/Reply-To · server-side rate limiting · double-delivery-race handling · Discord threading code. All unnecessary — the user's own client sends the email and the existing bridge handles inbound natively.

8 · Trade-offs

+ Tiny, CLI-only, no infra, no new failure modes; bridge behavior correct by construction.
+ File saved locally regardless; if mailto/clipboard/reveal fail, the user still has the path + the address.
− One manual step: attach + send (mailto can't auto-attach) — mitigated by clipboard + Finder reveal.
− No automatic logs upload → no server-side support-volume telemetry by default (optional local sendEvent later, out of scope).

9 · Open items

Final mailto: subject/body + CLI instruction wording.
Bundle filename/format; both .log and .log.gz produced (current plan).
Non-macOS reveal (Linux/Windows: print path + clipboard; no Finder reveal).

Prior exploration (rejected as too complex): 2026-06-03-builder-contact-support-design.md