docs: web-to-app identity bridging investigation and proposal

[devin-ai-integration]

Summary

Adds a developer docs page (apps/web/content/docs/developers/13.web-to-app-identity-bridging.mdx) that investigates why 86% of app installs are unattributed and proposes a solution for bridging PostHog identity between the website and the desktop app.

The document covers:

• Current state: How PostHog is initialized on the web (browser anonymous ID via posthog.init()) vs. desktop (machine fingerprint via hypr_host::fingerprint()), how $identify calls link them at sign-in, and what events are tracked on each side.
• Identity gap: An ASCII diagram showing exactly where the chain breaks — at the download redirect (no ID passed to Crabnebula URL) and at app install (no mechanism for DMG to carry a token into the installed app).
• Proposal: A two-phase approach — Phase 1 improves the existing sign-in bridge with posthog.alias() and localStorage persistence; Phase 2 adds a silent browser-based attribution link during onboarding that works without sign-in.
• Alternatives considered: Deferred deep links, custom download server, clipboard-based passing, alias-only at sign-in.

This is investigation + proposal only — no implementation changes.

Updates since last revision

• Fixed MDX build failure caused by --> and <-- arrow characters being parsed as JSX. Replaced with Unicode arrows (→ / ←). CI now passes.

Review & Testing Checklist for Human

• Verify the identity flow description is accurate: Confirm that the web auth callback (apps/web/src/routes/_view/callback/auth.tsx) and desktop auth handler (apps/desktop/src/auth/context.tsx) work as described — specifically that sign-in opens in the user's default browser and that the two $identify calls merge browser → supabaseUserId ← machineFingerprint.
• Validate Phase 2 assumption: The proposal assumes onboarding can open a browser page (char.com/link) before sign-in. Confirm this is feasible within the current onboarding flow without adding friction.
• Review privacy section: Ensure the localStorage-based approach and server-side attribution endpoint with 30-day TTL are acceptable from a privacy/compliance perspective.

Notes

• The "~20-30% unattributed" estimate after implementation is speculative — actual impact depends on what fraction of users complete onboarding and use the same browser.
• The document is placed in apps/web/content/docs/developers/ alongside the existing analytics inventory doc (12.analytics.mdx).
• This is a docs-only change — no functional code is modified. The proposal document will render on the Netlify deploy preview.

Link to Devin session: https://app.devin.ai/sessions/62368e7c5e134597918cd1df0d7148c1
Requested by: @ComputelessComputer

[netlify]

✅ Deploy Preview for hyprnote-storybook canceled.

Name	Link
🔨 Latest commit	c8af886
🔍 Latest deploy log	https://app.netlify.com/projects/hyprnote-storybook/deploys/69b28d0b71662e0008c17679

[netlify]

✅ Deploy Preview for hyprnote ready!

Name	Link
🔨 Latest commit	c8af886
🔍 Latest deploy log	https://app.netlify.com/projects/hyprnote/deploys/69b28d0b679ba200078f5343
😎 Deploy Preview	https://deploy-preview-4543--hyprnote.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR that start with 'DevinAI' or '@devin'.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring