Implementation notes for the subsystems whose behaviour isn't obvious from the code alone — the parts where a wrong assumption costs real debugging time. Read the relevant note before changing these areas.

Local-first data layer#

How Glide stores its data on-device (MMKV + a Zustand store) so every feature works with no account, no network, and no Convex link; the repository seam the UI talks to; the sync-ready shape of a stored task; and how an optional Convex sync attaches later.

Path: docs/engineering/local-first.md

Convex sync#

How the local store syncs to Convex (single-user / dogfood mode today): an offline outbox of optimistic writes, idempotent upserts keyed by the client UUID, last-write-wins conflict resolution, the two auth swap points, and why it deliberately avoids a CRDT.

Path: docs/engineering/convex-sync.md

Subscriptions & access tiers#

Why the app is fully functional with no account or subscription, and what the paid tier actually gates: the access model (free local-only / subscribed / lapsed-grace), and the decided-but-unbuilt billing design — auto-renewable IAP via RevenueCat, the Clerk identity as sync owner, schedule-driven RevenueCat REST entitlement checks anchored at expiry, and a read-only grace period that never blocks local writes or wipes local data.

Path: docs/engineering/subscriptions.md

Private Sync protocol#

Versioned E2EE protocol, threat boundaries, key hierarchy, setup/cutover state machine, linking, recovery, revocation limits, corruption behavior, rollout order, and production release gates.

Path: docs/engineering/private-sync-protocol.md

Private Sync blocker register#

Fable 5 security/distributed-systems findings, remediation invariants, regression signals, policy decisions, and the audit/QA loop that must close before release.

Path: docs/engineering/private-sync-blockers.md

End-to-end encryption business case#

Legal-risk, trust, marketing, and revenue analysis for making synchronized task content unreadable to Glide and Convex, including the recovery UX and product tradeoffs.

Path: docs/engineering/e2ee-business-case.md

Schema migrations (zero-downtime)#

The widen→migrate→narrow process for breaking Convex schema changes with a lingering mobile client: the read/write asymmetry, the forward-compat client step, the @convex-dev/migrations component, and a worked example (removing a column).

Path: docs/engineering/migrations.md

EAS Update (over-the-air JS)#

How to ship JS-only changes to installed builds without an App Store round-trip: the build↔channel↔branch↔runtime-version model, the fingerprint constraint (it hashes config and .gitignore but not app JS, so publish from a clean tree or the update silently won't match), what's OTA-able vs needs a rebuild, and how a device receives an update.

Path: docs/engineering/eas-update.md

The iOS home-screen widget (expo-widgets): how its UI is authored and shipped to a separate WidgetKit runtime, the local board → widget bridge, and the gotchas of that runtime (serialised body, payload constraints, App Group signing).

Path: docs/engineering/home-screen-widget.md

Liquid Glass surfaces#

The Action view's scroll-driven Liquid Glass header & footer: the layout that lets content scroll behind them, and the Reanimated opacity-animation workaround that fades the glass in and out without breaking the effect.

Path: docs/engineering/liquid-glass.md

Configure Feed