Merge branch 'tinyhumansai:main' into feat/e2e-cross-platform

Author: CodeGhost21

.claude/memory.md

@@ -54,6 +54,14 @@ Quick reference for anyone starting with Claude on this project. Updated by the
 - **`DEV_FORCE_ONBOARDING` was a no-op** — The old ternary had identical branches; fixed to actually force-show when the flag is set.
 - **`isOnboardedRedux` must be in useEffect deps** — When reading a selector value inside a useEffect, add it to the dependency array or the effect won't re-run when Redux state changes.
 
+## CoreStateProvider & Auth Bootstrap
+
+- **Auth session tokens are NOT in Redux persist** — They live entirely in the Rust sidecar, fetched via `fetchCoreAppSnapshot()` RPC. `PersistGate` only gates non-auth state (AI config, threads, channel connections). `CoreStateProvider` bootstrap is the critical auth path.
+- **`CoreStateProvider` premature `isBootstrapping: false` causes blank Settings** — If the initial RPC call fails (sidecar still starting), the old error handler set `isBootstrapping: false` immediately, causing `ProtectedRoute` to redirect to `/` before the 3s poll could recover. Fix (issue #413): keep `isBootstrapping: true` on initial failure, let the poll retry, give up after 5 attempts (~15s).
+- **`CoreStateProvider` is consumed by ~25 components** — Changes to its state shape or bootstrap behavior affect routes, socket, onboarding, nav, settings, and hooks. Treat it as a high-blast-radius file.
+- **Settings is a full route, not a modal** — `/settings/*` uses nested `<Routes>` in `Settings.tsx`. The `.claude/rules/15-settings-modal-system.md` doc describing a portal/modal approach is outdated. A catch-all `<Route path="*">` redirects unmatched sub-paths to `/settings`.
+- **`PersistGate loading={null}` causes flash** — Changed to `loading={<RouteLoadingScreen />}` (issue #413). `RouteLoadingScreen` accepts an optional `label` prop (defaults to "Initializing OpenHuman...") and can be rendered with no props.
+
 ## Build Blockers: macOS Tahoe + whisper-rs
 
 - **`whisper-rs` breaks `cargo build` on macOS Tahoe (Apple Silicon)** — Added in main via `whisper-rs = "0.16"` (voice feature #178). Apple clang 21+ refuses `-mcpu=native` when `--target=arm64-apple-macosx` is also set. This is NOT fixable by updating CLT.
@@ -71,6 +79,15 @@ Quick reference for anyone starting with Claude on this project. Updated by the
 - **Agent message bubbles** need `bg-stone-200/80` (not `bg-stone-100`) on `#F5F5F5` background — `bg-stone-100` is nearly invisible.
 - **~55 files touched** — purely CSS class changes, zero logic/handler/state changes.
 
+## Upsell / Billing (Phase 1 — Issue #403)
+
+- **Upsell components** live in `app/src/components/upsell/` — `UpsellBanner`, `UsageLimitModal`, `GlobalUpsellBanner`, `upsellDismissState`. Shared hook: `app/src/hooks/useUsageState.ts`.
+- **Usage data sources** — `creditsApi.getTeamUsage()` returns `TeamUsage` (rolling 10h spend/cap + weekly budget/remaining). `billingApi.getCurrentPlan()` returns `CurrentPlanData` (plan tier, caps, subscription status). Both go through `callCoreCommand` (core RPC). No Redux slice — all local hook state.
+- **Module-level cache in `useUsageState`** — `_cache` variable with 60s TTL prevents duplicate API calls when multiple components mount simultaneously. New pattern; do not remove.
+- **Banner dismiss state uses localStorage** (prefix `openhuman:upsell:`), not Redux — consistent with CLAUDE.md exception for ephemeral UI state.
+- **Phased rollout** — Phase 1 = banners + limit modal + hook. Phase 2 = onboarding upsell + analytics. Phase 3 = remote config + A/B testing.
+- **"5-hour" label stragglers in Conversations.tsx** — `LimitPill` label and its hover tooltip still say "5h" / "5-hour". Commit 8c52236's "10-hour" terminology refactor missed those two spots.
+
 ## Environment
 
 - **Core sidecar port** — `7788` (default). Check with `lsof -i :7788`.

.env.example

@@ -34,6 +34,10 @@ OPENHUMAN_CORE_RPC_URL=http://127.0.0.1:7788/rpc
 OPENHUMAN_CORE_RUN_MODE=child
 # [optional] Override path to openhuman core binary (leave blank for auto-detection)
 OPENHUMAN_CORE_BIN=
+# [optional] Explicit .env path for `openhuman serve` / `openhuman run` (loaded before the server starts).
+# Must be set in the parent environment (exported in your shell or service manager). It is read before
+# any dotenv file is loaded, so defining OPENHUMAN_DOTENV_PATH inside a .env file cannot select that file.
+# OPENHUMAN_DOTENV_PATH=
 
 # ---------------------------------------------------------------------------
 # Config overrides (override config.toml values at runtime)

.github/workflows/build-windows.yml

@@ -63,6 +63,8 @@ jobs:
           VITE_BACKEND_URL: ${{ vars.BASE_URL }}
           VITE_SENTRY_DSN: ${{ vars.VITE_SENTRY_DSN }}
           VITE_DEBUG: ${{ vars.VITE_DEBUG }}
+          VITE_MINIMUM_SUPPORTED_APP_VERSION: ${{ vars.VITE_MINIMUM_SUPPORTED_APP_VERSION }}
+          VITE_LATEST_APP_DOWNLOAD_URL: ${{ vars.VITE_LATEST_APP_DOWNLOAD_URL }}
 
       - name: Resolve core manifest and binary names
         id: core-paths
@@ -129,6 +131,8 @@ jobs:
         id: tauri-build
         env:
           BASE_URL: ${{ vars.BASE_URL }}
+          VITE_MINIMUM_SUPPORTED_APP_VERSION: ${{ vars.VITE_MINIMUM_SUPPORTED_APP_VERSION }}
+          VITE_LATEST_APP_DOWNLOAD_URL: ${{ vars.VITE_LATEST_APP_DOWNLOAD_URL }}
         with:
           projectPath: app
           args: -c ${{ steps.config-overrides.outputs.json }} --target x86_64-pc-windows-msvc

.github/workflows/release.yml

@@ -309,6 +309,9 @@ jobs:
           VITE_BACKEND_URL: ${{ vars.BASE_URL }}
           VITE_SENTRY_DSN: ${{ vars.VITE_SENTRY_DSN }}
           VITE_DEBUG: ${{ vars.VITE_DEBUG }}
+          # OAuth guardrails (#365): block openhuman://oauth/success on outdated desktop builds.
+          VITE_MINIMUM_SUPPORTED_APP_VERSION: ${{ vars.VITE_MINIMUM_SUPPORTED_APP_VERSION }}
+          VITE_LATEST_APP_DOWNLOAD_URL: ${{ vars.VITE_LATEST_APP_DOWNLOAD_URL }}
 
       - name: Resolve core manifest and binary names
         id: core-paths
@@ -390,6 +393,9 @@ jobs:
           TAURI_SIGNING_PRIVATE_KEY_PASSWORD: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY_PASSWORD || secrets.UPDATER_PRIVATE_KEY_PASSWORD }}
           TAURI_SIGNING_PRIVATE_KEY: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY || secrets.UPDATER_PRIVATE_KEY }}
           WITH_UPDATER: "true"
+          # Must match standalone "Build frontend" so tauri-action's beforeBuildCommand embeds the gate.
+          VITE_MINIMUM_SUPPORTED_APP_VERSION: ${{ vars.VITE_MINIMUM_SUPPORTED_APP_VERSION }}
+          VITE_LATEST_APP_DOWNLOAD_URL: ${{ vars.VITE_LATEST_APP_DOWNLOAD_URL }}
         with:
           projectPath: app
           args: -c ${{ steps.config-overrides.outputs.json }} ${{ matrix.settings.args }}

Cargo.lock

@@ -60,6 +60,7 @@ prost = { version = "0.14", default-features = false }
 postgres = { version = "0.19", features = ["with-chrono-0_4"] }
 chrono-tz = "0.10"
 dialoguer = { version = "0.12", features = ["fuzzy-select"] }
+dotenvy = "0.15"
 console = "0.16"
 glob = "0.3"
 regex = "1.10"

Cargo.toml

@@ -0,0 +1,108 @@
+# Referral System
+
+## Overview
+
+Referral rewards are paid to the referrer based on real successful payments from referred users.
+
+- Reward rate: `20%` of payment (`2000` basis points)
+- Referred user reward: none
+- Behavior flag: `RECURRING_REFERRAL_REWARD`
+  - `true`: reward every successful eligible payment
+  - `false`: reward only once per referral
+
+## Main Rules
+
+- Each user has one unique referral code.
+- A user can apply a code only before their first confirmed payment.
+- Self-referral is blocked (user id + identity fields).
+- Rewarding is idempotent:
+  - same payment cannot reward twice
+  - non-recurring mode allows only one reward for that referral
+
+## Data Model
+
+### `ReferralCode` (`referralcodes`)
+
+- `userId` (unique)
+- `referralCode` (unique)
+
+### `Referral` (`referrals`)
+
+- `referrerId`
+- `referredUserId` (unique)
+- `referralCode`
+- `status`: `pending | converted`
+- `sourceIp`, `deviceFingerprint`, `convertedAt`
+
+### `ReferralTransaction` (`referraltransactions`)
+
+- `referralId`, `referrerId`, `referredUserId`
+- `sourcePaymentId`, `sourcePaymentGateway`, `sourcePaymentObjectId`
+- `paymentAmountUsd`, `rewardAmountUsd`, `rewardRate` (Decimal128)
+- `creditTransactionId`
+- `idempotencyKey` (unique)
+
+## Migration
+
+Migration file: `src/migrations/1744200000000-referral-system.ts`
+
+What it does:
+
+- creates indexes for referral collections
+- backfills missing referral codes for existing users
+- backfills `Referral` records from legacy `user.referral.invitedBy`
+- supports `users` and `tgusers` collections
+
+### Run migration (non-interactive)
+
+```bash
+npx ts-migrate-mongoose up -f src/migrate.ts -a true
+```
+
+### Check migration status
+
+```bash
+npm run migrate:list
+```
+
+### Roll back referral migration (if needed)
+
+```bash
+npm run migrate:down
+```
+
+## Core Services
+
+- `src/services/referral/referralCodeService.ts`
+  - ensures and fetches user referral codes
+- `src/services/referral/referralService.ts`
+  - apply code, enforce eligibility, return referral stats
+- `src/services/referral/referralRewardService.ts`
+  - compute reward in cents, award credits, upsert audit transaction, mark referral converted
+
+## API
+
+- `GET /referral/stats`
+  - returns code, referral link, totals, and referral rows
+- `POST /referral/apply`
+  - request: `{ "code": "ABCD1234", "deviceFingerprint": "optional" }`
+  - supports `x-device-fingerprint` header
+
+## Payment Integration
+
+Reward processing is triggered on successful payment flows in:
+
+- `src/controllers/payment/coinbase/webhook.ts`
+- `src/controllers/payment/stripe/handleWebhook.ts`
+
+## Config
+
+`RECURRING_REFERRAL_REWARD` is read via `nconf`. Truthy values: `true`, `1`, `yes`.
+
+## Tests
+
+Key test: `src/services/referral/__tests__/referralRewardService.test.ts`
+
+- non-recurring behavior
+- recurring behavior
+- payment idempotency

Referral-doc.md

@@ -28,3 +28,8 @@ VITE_DEV_FORCE_ONBOARDING=false
 # [optional] Client-side timeout for skill callTool/triggerSync (seconds; default 120, max 3600).
 # Should match OPENHUMAN_TOOL_TIMEOUT_SECS on the core when set.
 # VITE_TOOL_TIMEOUT_SECS=
+
+# [optional] Minimum desktop app semver to complete OAuth deep links (openhuman://oauth/success). Leave unset in dev.
+# VITE_MINIMUM_SUPPORTED_APP_VERSION=0.51.0
+# [optional] Download page when OAuth is blocked due to an outdated build (default: GitHub releases/latest).
+# VITE_LATEST_APP_DOWNLOAD_URL=https://github.com/tinyhumansai/openhuman/releases/latest

app/.env.example

@@ -1,6 +1,6 @@
 {
   "name": "openhuman-app",
-  "version": "0.51.17",
+  "version": "0.51.19",
   "type": "module",
   "scripts": {
     "dev": "vite",