25 — Onboarding
The user-facing flow from “I heard about Locara” to “I’m using a Locara app.” This is the make-or-break user moment.
In the revised architecture, there is no Locara client app to install. Locara is a website + standalone signed Mac apps. Onboarding is therefore conceptually closer to “downloading any Mac app from a website” than to “installing an app store.”
This document covers the website-side flow + the first-run UX inside each Locara app.
Principles
- Working app in 60 seconds. A new user lands on locara.app, picks an app, installs, runs it. Under a minute on broadband.
- No accounts, no friction. Browse, download, install — all anonymous.
- Capability transparency on first launch. The app’s own first-run UI shows what it can and cannot do, before any sensitive operation.
- No Locara intermediary. Installing a Locara app feels like installing any other Mac app. The Locara framework is invisible to the user; what they see is the app itself.
The flow
1. Discovery
User finds Locara via:
- Word of mouth.
- Hacker News / blog post / podcast.
- Direct link to a specific app (
locara.app/apps/kingtongchoo/transcribe). - Search result for “local AI Mac apps.”
Lands on locara.app (the website).
2. Browse the catalog
The website is a normal site. No login wall, no popup.
┌─────────────────────────────────────────────────┐
│ locara.app ☰ 🔍 │
├─────────────────────────────────────────────────┤
│ │
│ Apps that run on your Mac. │
│ No cloud. No tracking. Just yours. │
│ │
│ Featured │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │Transcribe│ │ DocVault │ │ Chat │ │
│ │ ★★★★ │ │ ★★★★★ │ │ ★★★★ │ │
│ │ Download │ │ Download │ │ Download │ │
│ └──────────┘ └──────────┘ └──────────┘ │
│ │
│ Categories: Productivity | Creative | Dev … │
│ │
│ ⚡ Fully local | 💻 Fits your Mac (32 GB) │
│ │
└─────────────────────────────────────────────────┘
User clicks an app card.
3. App page
┌─────────────────────────────────────────────────┐
│ Transcribe │
│ by kingtongchoo (Domain-verified) │
│ │
│ Fully-local audio and meeting transcription. │
│ │
│ [ ⬇ Download for Mac (1.4 GB) ] │
│ │
│ ────────────────────────────────────── │
│ │
│ This app: │
│ ✓ Uses your microphone │
│ ✓ Reads files you choose │
│ │
│ This app does NOT: │
│ ✗ Use the network │
│ ✗ Read other files on your Mac │
│ ✗ Phone home or send telemetry │
│ │
│ Models used: Whisper-large-v3 (1.4 GB) │
│ Requires: 16 GB RAM, 4 GB disk │
│ │
│ Screenshots: [• • • •] │
│ │
│ Reviews ★★★★ (47) Source code Changelog │
└─────────────────────────────────────────────────┘
Capability summary auto-generated from the manifest. Privacy badges computed from declared capabilities, not author claims.
User clicks “Download for Mac.”
4. Download + install
User’s browser downloads Transcribe-0.1.0.dmg from Locara’s CDN.
1. Browser saves Transcribe-0.1.0.dmg (~1.4 GB if model is bundled, smaller if not)
2. User opens the DMG
3. Standard macOS DMG view: Transcribe.app on the left, /Applications shortcut on the right
4. User drags Transcribe.app to /Applications
5. macOS Gatekeeper verifies signature + notarization — silent if valid
6. App appears in /Applications, Spotlight, Launchpad
If the user has never installed a Locara-signed app before, macOS may show a one-time “Are you sure you want to open this app from the internet?” prompt. They click Open. Future Locara apps download silently.
No “install Locara client first” step. No user account. No setup wizard.
5. First launch
User double-clicks Transcribe.app (or finds it in Spotlight / Launchpad).
The app’s own first-run consent UI appears:
┌──────────────────────────────────────────────────┐
│ Welcome to Transcribe │
│ by kingtongchoo (Domain-verified) │
│ │
│ This app will: │
│ ✓ Use your microphone (when you're recording) │
│ ✓ Read audio files you choose │
│ ✓ Use Whisper, a 1.4 GB local AI model │
│ │
│ This app cannot: │
│ ✗ Access the network │
│ ✗ Read other files on your Mac │
│ ✗ Phone home or send telemetry │
│ │
│ Built and signed by Locara CI. │
│ Source: github.com/kingtongchoo/transcribe │
│ Verify: locara.app/apps/kingtongchoo/transcribe │
│ │
│ [ Continue ] [ Quit ] │
└──────────────────────────────────────────────────┘
The capability list is read from the app’s embedded manifest. Each line is verifiable: clicking opens a link to the manifest field + macOS entitlement.
User clicks Continue. Now:
- App downloads any missing models (to shared cache
~/Library/Caches/Locara/models/) with a progress bar. First-time: 1.4 GB Whisper download. Cached: instant. - macOS may prompt for microphone permission via TCC the first time the app actually uses the mic.
- App’s own onboarding UI (if any) appears — that’s the publisher’s responsibility, not Locara’s.
This UI ships as a standard <FirstRunConsent> component from @locara/components. App authors include it in their first-launch flow.
6. Subsequent uses
Standard Mac app behavior. The user opens Transcribe via Dock, Spotlight, or Launchpad.
- App reads its manifest, initializes the runtime.
- Models load from cache (already downloaded).
- App is ready in seconds.
No Locara process is running other than the app itself.
What we deliberately don’t do at first run
- No “install Locara” step. The website is HTML; nothing to install before getting to the app.
- No account creation. Browse, download, install — all anonymous.
- No email collection. No newsletter signup popup.
- No survey (“How did you hear about us?”). No.
- No tutorial / interactive walkthrough at the website level. Each app handles its own onboarding.
- No upfront permissions request at the OS level beyond what macOS does naturally (Gatekeeper prompt the first time).
- No telemetry opt-in/out dialog. There is no telemetry; nothing to opt into.
Failure / empty states
Network unavailable when downloading
User can’t download — that’s the user’s network’s problem, not ours. If they have an old .dmg already, it still works (apps don’t depend on network to launch).
Gatekeeper warning (“unidentified developer”)
Should never happen if the app is signed + notarized. If it does, something went wrong with our CI; users would file an issue. Crisis runbook covers it.
App won’t launch
If a model is corrupted (cache file changed externally) or missing:
Transcribe can't start.
Reason: Model "whisper-large-v3-q4" verification failed (hash mismatch).
Action: Re-downloading model… ████████░░░░ 60%
If this keeps happening, please re-download Transcribe from locara.app.
Self-healing where possible.
Model download fails
Couldn't download Whisper (1.4 GB).
What went wrong:
• Network timeout
What you can do:
• Try again
• Check your network
• Quit and try later
[ Try again ] [ Quit ]
Failure messages are concrete. No “Something went wrong” without specifics.
Pre-installed apps
There are no pre-installed apps. The user installs apps one at a time as they want them.
(In the prior architecture, we considered shipping a “Locara client” with a pre-installed Transcribe demo. That’s no longer applicable — there’s no client to ship anything pre-installed in.)
Developer-side onboarding
Covered in 06-cli.md. Key flow:
$ locara init transcribe my-app
$ cd my-app
$ locara dev
# Working app in 60 seconds; can publish in another 60.
The locara init --from-prompt "..." flow targets developers paired with Cursor / Claude Code. See the agent-friendly section of 00-overview.md.
The optional “Locara Manager” utility (phase 3+)
A tiny menubar app could provide:
- A unified view of all installed Locara apps.
- Update status across them.
- Aggregated capability profile (“you have 3 apps using your microphone”).
- Quick disk reclamation (clear shared model cache).
This is not v1. Each Locara app handles its own updates, and users can use Spotlight to find their installed apps. The unified manager is a nice-to-have for power users, not blocking adoption.
If/when shipped, it would be: a tiny Tauri app, optional download, no privileged status — just a UI that reads from the same manifest API the website uses.
Localization for onboarding
v1 is English-only. The website’s first-run consent UI dialogs ship in English. i18n is deferred (see 39-i18n.md).
Phasing
- Phase 1: No website yet. Reference apps (Transcribe) distributed as
.dmgfrom a personal site or directly to friends. Onboarding is the app’s first-launch consent UI. - Phase 2: Same; DocVault joins. Manual
.dmgdistribution. - Phase 3: Website goes live with catalog + downloads. Full website-driven onboarding flow.
- Phase 4: Optional Locara Manager menubar utility if user demand justifies.
Open questions
- (open) Should the website include a 30-second product video on the home page, or just text? Lean text — videos require maintenance and can’t be localized cheaply.
- (open) Default catalog landing — “Featured” or “Categories”? Probably Featured, with categories one click away.
- (open) Should locara.app detect a user’s hardware via WebAuthn-adjacent APIs and show “fits your Mac” automatically? Privacy concern; probably opt-in.
- (open) Direct app downloads vs. landing page — when a Twitter link points to
locara.app/apps/transcribe, do we auto-trigger download or show the app page? Probably show the page (don’t surprise users with downloads).
Cross-references
- Distribution mechanics: 15-distribution.md
- Capability consent UI details: 13-security-privacy.md, 14-trust-safety.md
- Components for first-run UI: 11-components.md
- Developer-side onboarding (
locara init): 06-cli.md - Architecture: 01-architecture.md