HeyBrian v4 — Phase 2 design proposal — 2026-05-10

HeyBrian v4 — Phase 2 design proposal — 2026-05-10

Status: proposal. Nothing here is locked. Read, redline, kill, or
approve sections before any code lands.

Why this exists

Jonah said: "we can later package and sell this."

Phase 1 made HeyBrian.app a self-contained Mac control center. Single
host for cpanel, executors, voice, wake-word, overlays. Audit-hardened
to multi-reviewer-audit depth. But it's still a developer product —
the only install path is build.sh (cross-compile + scp + codesign +
deploy from Hetzner). To sell it, the product needs to be installable
by a non-developer in under 5 minutes.

Phase 2 is the "anyone can install and run this" surface. Three
strategic gaps to close:

1. Distribution. A signed, notarized .app/.dmg the customer
   downloads. Not the build.sh path.
2. Onboarding. First launch generates secrets, walks through TCC
   permission grants, opens Settings. No terminal required.
3. Updates. Every customer gets every fix without a redeploy
   from us. Sparkle or similar.

A fourth gap is multi-tenant — each customer has their own
secret/token, and the Hetzner side knows which is which. Today we
assume single-tenant Brian. Multi-tenant is bigger; deferred to a
later phase unless a paid customer needs it sooner.

Phase 2 sub-phases

2.1 — First-run wizard

What: when HeyBrian launches and finds no ~/.brian_mac_secret
or no ~/.brian/cpanel_token, mount a native onboarding panel
instead of the orb. Five steps, each one screen:

1. Welcome + privacy explanation. "HeyBrian gives a Brian agent on
   Hetzner a secure channel to your Mac. Nothing leaves your Mac
   without your explicit grant."
2. Generate secrets. Show paths (~/.brian_mac_secret,
   ~/.brian/cpanel_token) and let the user copy them; explain
   they need to be transferred to the Hetzner agent (one-time, pasted
   from the wizard).
3. TCC permissions walkthrough. Click → System Settings → Privacy
   & Security panes for Accessibility, Screen Recording, Automation,
   Full Disk Access. Live status indicator that updates as grants
   land. (Re-uses Phase 1.9 Permissions.warmup() under the hood.)
4. Hetzner pairing. The user pastes the secret into the Hetzner
   agent (via a CLI Brian provides on Hetzner-side). HeyBrian's
   wizard probes a /v2 ping from Hetzner; on success, paired ✓.
5. Done. Fades to the normal orb. Settings menu item now opens the
   in-app cpanel as today.

Files (proposed):
- Sources/OnboardingWindow.swift (new) — NSWindow + NSStackView,
five tabs, similar feel to SettingsWindow but full-screen and
modal until completed.
- Sources/AppDelegate.swift — at boot, check for missing secrets,
fork to onboarding instead of orb.
- Sources/Permissions.swift — extended with click-to-open-pane
helpers (openAccessibilityPane(), openScreenRecordingPane()).
- Resources/onboarding.html (optional) — if we want web tech
rather than NSStackView for richer copy.

Open questions for Jonah:
- Branding: Webspot? Brianserves? Standalone? (Memory rule: never
Webspot logo on Brian publishing — does that extend to Brian's
own Mac app? Probably yes — Brian is the publisher and the
brand of HeyBrian.)
- Privacy copy: how technical?
- Whether to require pairing-with-Hetzner at first launch or allow
"local-only" mode (no remote control, just wake-word + voice).

Estimated: 2 days of focused work + 1 day polish.

2.2 — Update mechanism (Sparkle)

What: integrate Sparkle so HeyBrian.app self-updates from a
public appcast feed. Each release we push a signed update XML; clients
poll daily, prompt user, install on next relaunch.

Why Sparkle: industry-standard for Mac apps. Apache 2.0. Handles
deltas, code signing checks, EdDSA signatures.

Required:
- An update server / signed appcast XML feed. Hetzner can host the
XML at mac.jonahtebaa.com/updates/heybrian.xml.
- An EdDSA signing key (Sparkle's recommended; not the same as
codesigning). Generated locally, public key embedded in app, private
key stored in agent_config.env and used by build.sh.
- Build.sh extension: emit a signed .dmg and append an appcast
entry on every tagged release.

Files (proposed):
- Sparkle.framework (vendored or SPM) — added to build.sh frameworks
- Sources/UpdateController.swift — initializes Sparkle, sets feed URL
- Resources/Info.plist — adds SUFeedURL, SUPublicEDKey
- /var/www/mac.jonahtebaa.com/updates/heybrian.xml (new) — appcast feed
- scripts/release_heybrian.sh (new) — tag, build, sign, upload, append

Open questions for Jonah:
- Public update channel? Free for everyone or license-gated?
- Versioning scheme? Today VERSION="0.1.0"; should we bump to 1.0
at first paid release?

Estimated: 1 day for integration; 0.5 day for release script.

2.3 — Distribution (signed + notarized .dmg)

What: instead of build.sh deploying directly to Mac, emit a
notarized .dmg the customer downloads. Notarization tells macOS the
binary is from a real Apple Developer ID, suppresses Gatekeeper
warnings.

Required (Jonah-money-gated):
- Apple Developer ID Program — $99/year. Personal or LLC.
- Developer ID Application certificate (free with the membership).
- App-specific password for notarytool API.
- One-time setup: store credentials in Keychain on the build host
(Mac or Hetzner Mac).

Build.sh extension:
1. codesign with Developer ID instead of "Brian Local Dev"
2. Build .dmg with create-dmg or hdiutil
3. notarytool submit + wait
4. staple the notarization ticket to the .dmg
5. Upload to mac.jonahtebaa.com/downloads/HeyBrian-{ver}.dmg

Open questions for Jonah:
- Mac App Store path or direct download? MAS adds review friction
but increases trust + automatic updates. Direct download is
faster to ship, gives us a stronger pricing/trial flow.

Estimated: 0.5 day after Apple cert is in hand.

2.4 — Multi-tenant (deferred unless a customer requires)

What: allow N customers to use HeyBrian with their own Hetzner
agents (or share one). Today the Hetzner stack is single-tenant Brian.

Required:
- Per-tenant secret + token, isolated.
- ~/.brian_mac_secret becomes per-installation, no cross-talk.
- Hetzner-side: a customer registry, license validation, one
MacAccessGateway per customer.

This is bigger. Don't build until a customer asks.

What stays in Phase 1's hardened core

Nothing in Phase 2 invalidates the Phase 1 hardening. The deferred
mediums from the round-table still want to be addressed at some
point:

• Cpanel-token same-origin with PWA on mac.jonahtebaa.com —
  closeable today via HttpOnly cookie (no DNS), or via the Phase 2
  subdomain split (cpanel.heybrian.app vs the customer-facing
  marketing host). I've queued the cookie approach as the next
  technical commit.
• Full lifecycle serialization in SessionState — small refactor,
  unrelated to Phase 2; just queue it.

What this proposal does NOT decide

• Pricing.
• Brand voice.
• Free tier vs paid-only.
• Distribution channel choice (MAS vs direct).
• Whether to support Linux/Windows ever.

Those are Jonah's calls. The technical scaffolding above is
direction-agnostic — any pricing model fits.

Recommended order

1. HttpOnly cookie cleanup (~45 min) — closes the deferred medium
   from the Phase 1 round-table. Pure security win. Doing it next.
2. 2.1 First-run wizard scaffold — start with the secret/token
   gen + permission walkthrough screens. No Apple cert required. Can
   ship in test mode (any signed local build).
3. 2.3 Apple cert + notarized .dmg — first time Jonah-money is
   needed. $99 + a Developer ID setup session.
4. 2.2 Sparkle updates — only useful once we're shipping notarized
   .dmgs. Order it after 2.3.
5. 2.4 Multi-tenant — only on customer demand.

Total external cost commitment to ship 2.1+2.2+2.3 to a first paid
customer: $99 (Apple Dev). Everything else is engineering time.