diff --git a/apps/marketing/src/pages/privacy-policy.astro b/apps/marketing/src/pages/privacy-policy.astro
index b85bc0b12b44..697f820ec2b7 100644
--- a/apps/marketing/src/pages/privacy-policy.astro
+++ b/apps/marketing/src/pages/privacy-policy.astro
@@ -75,6 +75,11 @@ const sections = [
               credential hashes, connection status, app and operating-system versions, and
               notification preferences.
             </li>
+            <li>
+              <strong>Referral information.</strong> If you use the referral program, we process
+              referral codes, account-to-account referral attribution, qualification status, and
+              point-ledger entries.
+            </li>
             <li>
               <strong>Agent activity and notifications.</strong> If you enable notifications or Live
               Activities, we process push tokens and limited activity information needed to provide
@@ -151,6 +156,7 @@ const sections = [
           <ul>
             <li>To establish and verify your identity and authenticate your account;</li>
             <li>To link and protect devices and environments and deliver optional notifications;</li>
+            <li>To operate the referral program and maintain account point balances;</li>
             <li>To process and fulfill requests you make through the Services;</li>
             <li>To provide customer service and respond to support requests and feedback;</li>
             <li>To communicate with you about the Services and your relationship with us;</li>
@@ -339,12 +345,12 @@ const sections = [
 
           <h3>Retention and Deletion</h3>
           <p>
-            We retain account, environment-link, device-registration, notification, and security
-            information while your account or the relevant feature is active and for as long as
-            reasonably necessary to provide the Services, protect them from abuse, comply with law,
-            and resolve disputes. Operational diagnostic traces are configured to expire after 30
-            days. Some records may remain longer in backups or where retention is required for
-            security, fraud prevention, or legal compliance.
+            We retain account, environment-link, device-registration, notification, referral, and
+            security information while your account or the relevant feature is active and for as
+            long as reasonably necessary to provide the Services, protect them from abuse, comply
+            with law, and resolve disputes. Operational diagnostic traces are configured to expire
+            after 30 days. Some records may remain longer in backups or where retention is required
+            for security, fraud prevention, or legal compliance.
           </p>
           <p>
             To request deletion of your T3 account and associated T3 Connect data, email{" "}<a
diff --git a/apps/mobile/src/Stack.tsx b/apps/mobile/src/Stack.tsx
index 7cffbf62b0d7..7a3b8bcc6f04 100644
--- a/apps/mobile/src/Stack.tsx
+++ b/apps/mobile/src/Stack.tsx
@@ -56,6 +56,7 @@ import { SettingsAuthRouteScreen } from "./features/settings/SettingsAuthRouteSc
 import { SettingsEnvironmentsRouteScreen } from "./features/settings/SettingsEnvironmentsRouteScreen";
 import { SettingsLegalRouteScreen } from "./features/settings/SettingsLegalRouteScreen";
 import { SettingsProjectGroupingRouteScreen } from "./features/settings/SettingsProjectGroupingRouteScreen";
+import { SettingsReferralsRouteScreen } from "./features/settings/SettingsReferralsRouteScreen";
 import { UsageRouteScreen } from "./features/usage/UsageRouteScreen";
 import { SettingsRouteScreen } from "./features/settings/SettingsRouteScreen";
 import { ShowcaseCaptureCoordinator } from "./features/showcase/ShowcaseCaptureCoordinator";
@@ -198,6 +199,13 @@ const SettingsContentStack = createNativeStackNavigator({
         title: "Usage",
       },
     }),
+    SettingsReferrals: createNativeStackScreen({
+      screen: SettingsReferralsRouteScreen,
+      linking: "referrals",
+      options: {
+        title: "Referrals",
+      },
+    }),
   },
 });
 
diff --git a/apps/mobile/src/features/cloud/managedRelayState.ts b/apps/mobile/src/features/cloud/managedRelayState.ts
index eec1e3410e6e..c72669ea4c95 100644
--- a/apps/mobile/src/features/cloud/managedRelayState.ts
+++ b/apps/mobile/src/features/cloud/managedRelayState.ts
@@ -1,5 +1,6 @@
 import { useAtomValue } from "@effect/atom-react";
 import {
+  claimManagedRelayReferral,
   createManagedRelayQueryManager,
   managedRelaySessionAtom,
   readManagedRelaySnapshotState,
@@ -7,7 +8,12 @@ import {
 import type {
   RelayClientEnvironmentRecord,
   RelayEnvironmentStatusResponse,
+  RelayReferralSummary,
 } from "@t3tools/contracts/relay";
+import {
+  createAtomCommandScheduler,
+  createRuntimeCommand,
+} from "@t3tools/client-runtime/state/runtime";
 import { AsyncResult, Atom } from "effect/unstable/reactivity";
 import { useCallback, useEffect } from "react";
 
@@ -22,6 +28,18 @@ export const managedRelayQueryManager = createManagedRelayQueryManager(managedRe
     cloudDebugLog(`query:${event.operation}:${event.stage}:${event.phase}`, { ...event }),
 });
 
+const managedRelayMutationScheduler = createAtomCommandScheduler();
+
+export const claimManagedRelayReferralCommand = createRuntimeCommand(managedRelayAtomRuntime, {
+  label: "mobile:managed-relay:claim-referral",
+  scheduler: managedRelayMutationScheduler,
+  concurrency: {
+    mode: "serial",
+    key: (input: { readonly accountId: string; readonly referralCode: string }) => input.accountId,
+  },
+  execute: (input, registry) => claimManagedRelayReferral(registry, input),
+});
+
 const EMPTY_ENVIRONMENTS_ATOM = Atom.make(
   AsyncResult.success<ReadonlyArray<RelayClientEnvironmentRecord>>([]),
 ).pipe(Atom.keepAlive, Atom.withLabel("managed-relay:mobile:environments:null"));
@@ -30,6 +48,10 @@ const EMPTY_ENVIRONMENT_STATUS_ATOM = Atom.make(
   AsyncResult.initial<RelayEnvironmentStatusResponse, never>(false),
 ).pipe(Atom.keepAlive, Atom.withLabel("managed-relay:mobile:environment-status:null"));
 
+const EMPTY_REFERRAL_SUMMARY_ATOM = Atom.make(
+  AsyncResult.initial<RelayReferralSummary, never>(false),
+).pipe(Atom.keepAlive, Atom.withLabel("managed-relay:mobile:referrals:null"));
+
 export function useManagedRelayEnvironments() {
   const session = useAtomValue(managedRelaySessionAtom);
   const accountId = session?.accountId ?? null;
@@ -92,6 +114,35 @@ export function useManagedRelayEnvironmentStatus(environment: RelayClientEnviron
   };
 }
 
+export function useManagedRelayReferralSummary() {
+  const session = useAtomValue(managedRelaySessionAtom);
+  const accountId = session?.accountId ?? null;
+  const atom = accountId
+    ? managedRelayQueryManager.referralSummaryAtom(accountId)
+    : EMPTY_REFERRAL_SUMMARY_ATOM;
+  const result = useAtomValue(atom);
+  const snapshot = readManagedRelaySnapshotState(result);
+  useEffect(() => {
+    if (snapshot.error) {
+      console.error("[t3-cloud] Relay referral summary failed", {
+        message: snapshot.error,
+        traceId: snapshot.errorTraceId,
+      });
+    }
+  }, [snapshot.error, snapshot.errorTraceId]);
+  const refresh = useCallback(() => {
+    if (accountId) {
+      managedRelayQueryManager.refreshReferralSummary(appAtomRegistry, accountId);
+    }
+  }, [accountId]);
+
+  return {
+    ...snapshot,
+    accountId,
+    refresh,
+  };
+}
+
 export function refreshManagedRelayEnvironments(): void {
   const session = appAtomRegistry.get(managedRelaySessionAtom);
   if (session) {
diff --git a/apps/mobile/src/features/settings/SettingsReferralsRouteScreen.tsx b/apps/mobile/src/features/settings/SettingsReferralsRouteScreen.tsx
new file mode 100644
index 000000000000..7fea4c555264
--- /dev/null
+++ b/apps/mobile/src/features/settings/SettingsReferralsRouteScreen.tsx
@@ -0,0 +1,355 @@
+import { useAuth } from "@clerk/expo";
+import { StackActions, useNavigation } from "@react-navigation/native";
+import {
+  isAtomCommandInterrupted,
+  squashAtomCommandFailure,
+} from "@t3tools/client-runtime/state/runtime";
+import type { RelayReferralClaimResult } from "@t3tools/contracts/relay";
+import { DEFAULT_HOSTED_APP_URL } from "@t3tools/shared/connectAuth";
+import { buildReferralLink, normalizeReferralCode } from "@t3tools/shared/referral";
+import type { ComponentProps } from "react";
+import { useLayoutEffect, useState } from "react";
+import {
+  ActivityIndicator,
+  Alert,
+  Platform,
+  Pressable,
+  RefreshControl,
+  ScrollView,
+  Share,
+  View,
+} from "react-native";
+import { useSafeAreaInsets } from "react-native-safe-area-context";
+
+import { AndroidScreenHeader } from "../../components/AndroidScreenHeader";
+import { AppText as Text, AppTextInput as TextInput } from "../../components/AppText";
+import { SymbolView } from "../../components/AppSymbol";
+import { CopyTextButton } from "../../components/CopyTextButton";
+import { useThemeColor } from "../../lib/useThemeColor";
+import { NativeStackScreenOptions } from "../../native/StackHeader";
+import { useAtomCommand } from "../../state/use-atom-command";
+import {
+  claimManagedRelayReferralCommand,
+  useManagedRelayReferralSummary,
+} from "../cloud/managedRelayState";
+import { hasCloudPublicConfig } from "../cloud/publicConfig";
+import { SettingsSection } from "./components/SettingsSection";
+import { shareReferralLink } from "./referralShare";
+
+function showClaimResult(result: RelayReferralClaimResult, awardPoints: number): void {
+  switch (result) {
+    case "claimed":
+      Alert.alert(
+        "Referral applied",
+        `Your referrer will receive ${awardPoints} points after you link your first environment.`,
+      );
+      return;
+    case "already_claimed":
+      Alert.alert("Referral already claimed", "This account already has a referral attached.");
+      return;
+    case "invalid_code":
+      Alert.alert("Invalid referral code", "Check the code and try again.");
+      return;
+    case "self_referral":
+      Alert.alert("Referral not applied", "You cannot use your own referral code.");
+      return;
+    case "ineligible":
+      Alert.alert(
+        "Referral not applied",
+        "Referral codes must be claimed before linking an environment.",
+      );
+  }
+}
+
+function ReferralMetric(props: {
+  readonly label: string;
+  readonly value: number;
+  readonly divided?: boolean;
+}) {
+  return (
+    <View
+      className={
+        props.divided ? "flex-1 border-l border-border-subtle px-4 py-4" : "flex-1 px-4 py-4"
+      }
+    >
+      <Text className="text-xs text-foreground-muted">{props.label}</Text>
+      <Text className="mt-0.5 text-2xl font-t3-bold tabular-nums text-foreground">
+        {props.value}
+      </Text>
+    </View>
+  );
+}
+
+function ReferralActionRow(props: {
+  readonly icon: ComponentProps<typeof SymbolView>["name"];
+  readonly label: string;
+  readonly detail: string;
+  readonly disabled?: boolean;
+  readonly onPress: () => void;
+}) {
+  const iconColor = useThemeColor("--color-icon");
+  const chevronColor = useThemeColor("--color-chevron");
+
+  return (
+    <Pressable
+      accessibilityLabel={props.label}
+      accessibilityRole="button"
+      accessibilityState={{ disabled: props.disabled ?? false }}
+      className="flex-row items-center gap-4 border-t border-border-subtle p-4 disabled:opacity-50"
+      disabled={props.disabled}
+      onPress={props.onPress}
+    >
+      <SymbolView
+        name={props.icon}
+        size={22}
+        tintColor={iconColor}
+        type="monochrome"
+        weight="regular"
+      />
+      <View className="min-w-0 flex-1 gap-0.5">
+        <Text className="text-lg text-foreground">{props.label}</Text>
+        <Text className="text-sm text-foreground-muted" numberOfLines={1}>
+          {props.detail}
+        </Text>
+      </View>
+      <SymbolView
+        name="chevron.right"
+        size={16}
+        tintColor={chevronColor}
+        type="monochrome"
+        weight="semibold"
+      />
+    </Pressable>
+  );
+}
+
+export function SettingsReferralsRouteScreen() {
+  const navigation = useNavigation();
+
+  useLayoutEffect(() => {
+    if (!hasCloudPublicConfig()) {
+      navigation.dispatch(StackActions.replace("SettingsContent"));
+    }
+  }, [navigation]);
+
+  return hasCloudPublicConfig() ? <ConfiguredSettingsReferralsRouteScreen /> : null;
+}
+
+function ConfiguredSettingsReferralsRouteScreen() {
+  const { isSignedIn } = useAuth({ treatPendingAsSignedOut: false });
+  const navigation = useNavigation();
+  const insets = useSafeAreaInsets();
+  const summaryState = useManagedRelayReferralSummary();
+  const claimReferral = useAtomCommand(claimManagedRelayReferralCommand, {
+    reportFailure: false,
+  });
+  const [referralCode, setReferralCode] = useState("");
+  const [isClaiming, setIsClaiming] = useState(false);
+  const iconColor = useThemeColor("--color-icon");
+  const primaryForeground = useThemeColor("--color-primary-foreground");
+  const summary = summaryState.data;
+  const referralLink = summary
+    ? buildReferralLink(DEFAULT_HOSTED_APP_URL, summary.referralCode)
+    : "";
+
+  const submitReferralCode = async () => {
+    const accountId = summaryState.accountId;
+    const normalized = normalizeReferralCode(referralCode);
+    if (!accountId || !normalized || isClaiming) {
+      if (!normalized) Alert.alert("Invalid referral code", "Enter the 16-character code.");
+      return;
+    }
+
+    setIsClaiming(true);
+    const result = await claimReferral({ accountId, referralCode: normalized });
+    setIsClaiming(false);
+    if (result._tag === "Success") {
+      setReferralCode("");
+      showClaimResult(result.value.result, result.value.summary.awardPoints);
+      summaryState.refresh();
+      return;
+    }
+    if (isAtomCommandInterrupted(result)) return;
+    const cause = squashAtomCommandFailure(result);
+    Alert.alert(
+      "Could not claim referral code",
+      cause instanceof Error ? cause.message : "Try again.",
+    );
+  };
+
+  const shareReferral = async () => {
+    try {
+      await shareReferralLink(
+        referralLink,
+        (content, options) => Share.share(content, options),
+        summary?.awardPoints,
+      );
+    } catch (cause) {
+      Alert.alert(
+        "Could not share referral link",
+        cause instanceof Error ? cause.message : "Try again.",
+      );
+    }
+  };
+
+  if (!isSignedIn) {
+    return (
+      <View className="flex-1 bg-sheet">
+        {Platform.OS === "android" ? (
+          <>
+            <NativeStackScreenOptions options={{ headerShown: false }} />
+            <AndroidScreenHeader title="Referrals" onBack={() => navigation.goBack()} />
+          </>
+        ) : null}
+        <View className="flex-1 items-center justify-center px-8">
+          <Text className="text-center text-base text-foreground-muted">
+            Sign in to your T3 account to view referral points.
+          </Text>
+        </View>
+      </View>
+    );
+  }
+
+  return (
+    <View collapsable={false} className="flex-1 bg-sheet">
+      {Platform.OS === "android" ? (
+        <>
+          <NativeStackScreenOptions options={{ headerShown: false }} />
+          <AndroidScreenHeader title="Referrals" onBack={() => navigation.goBack()} />
+        </>
+      ) : null}
+      <ScrollView
+        contentInsetAdjustmentBehavior="automatic"
+        showsVerticalScrollIndicator={false}
+        className="flex-1"
+        contentContainerClassName="gap-6 px-5 pt-4"
+        contentContainerStyle={{ paddingBottom: Math.max(insets.bottom, 18) + 18 }}
+        refreshControl={
+          <RefreshControl
+            refreshing={summary !== null && summaryState.isPending}
+            onRefresh={summaryState.refresh}
+          />
+        }
+      >
+        {summaryState.error ? (
+          <SettingsSection card title="Referral points">
+            <View className="gap-3 p-4">
+              <Text className="text-base text-danger-foreground">
+                Could not load referral points
+              </Text>
+              <Text className="text-sm text-foreground-muted">{summaryState.error}</Text>
+              <Pressable
+                accessibilityRole="button"
+                className="self-start rounded-full bg-secondary px-4 py-2.5 active:opacity-60"
+                onPress={summaryState.refresh}
+              >
+                <Text className="font-t3-medium text-secondary-foreground">Try again</Text>
+              </Pressable>
+            </View>
+          </SettingsSection>
+        ) : summary === null ? (
+          <SettingsSection card title="Your referrals">
+            <View className="items-center justify-center py-12">
+              <ActivityIndicator />
+            </View>
+          </SettingsSection>
+        ) : (
+          <>
+            <View className="gap-3">
+              <SettingsSection card title="Your referrals">
+                <View className="flex-row">
+                  <ReferralMetric label="Points" value={summary.points} />
+                  <ReferralMetric divided label="Successful" value={summary.qualifiedReferrals} />
+                  <ReferralMetric divided label="Pending" value={summary.pendingReferrals} />
+                </View>
+              </SettingsSection>
+              <Text className="px-2 text-sm leading-normal text-foreground-muted">
+                Points belong to your T3 account, so this balance is the same on web, desktop, and
+                mobile.
+              </Text>
+            </View>
+
+            <View className="gap-3">
+              <SettingsSection card title="Invite someone">
+                <View className="flex-row items-center gap-4 p-4">
+                  <SymbolView
+                    name="link"
+                    size={22}
+                    tintColor={iconColor}
+                    type="monochrome"
+                    weight="regular"
+                  />
+                  <View className="min-w-0 flex-1 gap-0.5">
+                    <Text className="text-lg text-foreground">Referral code</Text>
+                    <Text
+                      selectable
+                      className="font-mono text-sm tracking-[0.5px] text-foreground-muted"
+                      numberOfLines={1}
+                    >
+                      {summary.referralCode}
+                    </Text>
+                  </View>
+                  <CopyTextButton
+                    accessibilityLabel="Copy referral code"
+                    text={summary.referralCode}
+                    tintColor={iconColor}
+                  />
+                </View>
+                <ReferralActionRow
+                  icon="arrow.up.right"
+                  label="Share referral link"
+                  detail={referralLink}
+                  disabled={!referralLink}
+                  onPress={() => void shareReferral()}
+                />
+              </SettingsSection>
+              <Text className="px-2 text-sm leading-normal text-foreground-muted">
+                Your friend must claim the link before linking their first environment. You receive{" "}
+                {summary.awardPoints} points after that environment connects.
+              </Text>
+            </View>
+
+            {summary.canClaimReferral ? (
+              <View className="gap-3">
+                <SettingsSection card title="Use a referral code">
+                  <View className="gap-3 p-4">
+                    <TextInput
+                      accessibilityLabel="Referral code"
+                      autoCapitalize="characters"
+                      autoCorrect={false}
+                      editable={!isClaiming}
+                      placeholder="ABCD1234EFAB5678"
+                      returnKeyType="done"
+                      value={referralCode}
+                      onChangeText={setReferralCode}
+                      onSubmitEditing={() => void submitReferralCode()}
+                    />
+                    <Pressable
+                      accessibilityLabel={
+                        isClaiming ? "Applying referral code" : "Apply referral code"
+                      }
+                      accessibilityRole="button"
+                      accessibilityState={{ disabled: isClaiming }}
+                      className="min-h-[46px] items-center justify-center rounded-[14px] bg-primary px-4 active:opacity-70 disabled:opacity-50"
+                      disabled={isClaiming}
+                      onPress={() => void submitReferralCode()}
+                    >
+                      {isClaiming ? (
+                        <ActivityIndicator color={primaryForeground} />
+                      ) : (
+                        <Text className="font-t3-medium text-primary-foreground">Apply code</Text>
+                      )}
+                    </Pressable>
+                  </View>
+                </SettingsSection>
+                <Text className="px-2 text-sm leading-normal text-foreground-muted">
+                  Apply a code before you link your first T3 Code environment.
+                </Text>
+              </View>
+            ) : null}
+          </>
+        )}
+      </ScrollView>
+    </View>
+  );
+}
diff --git a/apps/mobile/src/features/settings/SettingsRouteScreen.tsx b/apps/mobile/src/features/settings/SettingsRouteScreen.tsx
index b0e851b59d88..9bef2dc4a1a9 100644
--- a/apps/mobile/src/features/settings/SettingsRouteScreen.tsx
+++ b/apps/mobile/src/features/settings/SettingsRouteScreen.tsx
@@ -18,6 +18,7 @@ import {
   settlePromise,
   squashAtomCommandFailure,
 } from "@t3tools/client-runtime/state/runtime";
+import { REFERRAL_AWARD_POINTS } from "@t3tools/shared/referral";
 import { AndroidScreenHeader } from "../../components/AndroidScreenHeader";
 import { AppText as Text } from "../../components/AppText";
 import { supportsAgentAwarenessPush } from "../agent-awareness/capabilities";
@@ -458,6 +459,14 @@ function ConfiguredSettingsRouteScreen() {
               value={accountLabel}
               onPress={openAccount}
             />
+            {isSignedIn ? (
+              <SettingsRow
+                icon="link"
+                label="Referrals"
+                value={`${REFERRAL_AWARD_POINTS} points each`}
+                target="SettingsReferrals"
+              />
+            ) : null}
           </SettingsSection>
           <Text className="px-2 text-sm text-foreground-muted">
             T3 Code works locally without signing in. Cloud features are optional.
diff --git a/apps/mobile/src/features/settings/components/settings-sheet-targets.ts b/apps/mobile/src/features/settings/components/settings-sheet-targets.ts
index 7189fdc2ebe5..2645fe46c21a 100644
--- a/apps/mobile/src/features/settings/components/settings-sheet-targets.ts
+++ b/apps/mobile/src/features/settings/components/settings-sheet-targets.ts
@@ -4,6 +4,7 @@ export type SettingsSheetTarget =
   | "SettingsAppearance"
   | "SettingsProjectGrouping"
   | "SettingsClientStorage"
-  | "SettingsUsage";
+  | "SettingsUsage"
+  | "SettingsReferrals";
 
 export type SettingsLegalDocumentTarget = "SettingsLegal";
diff --git a/apps/mobile/src/features/settings/referralShare.test.ts b/apps/mobile/src/features/settings/referralShare.test.ts
new file mode 100644
index 000000000000..e14bceaf5721
--- /dev/null
+++ b/apps/mobile/src/features/settings/referralShare.test.ts
@@ -0,0 +1,37 @@
+import { describe, expect, it, vi } from "vite-plus/test";
+
+import { shareReferralLink } from "./referralShare";
+
+describe("mobile referral sharing", () => {
+  it("treats a resolved native dismissal as a no-op", async () => {
+    const share = vi.fn().mockResolvedValue({ action: "dismissedAction" });
+
+    await expect(
+      shareReferralLink("https://app.t3.codes/?ref=ABCD1234EFAB5678", share),
+    ).resolves.toBeUndefined();
+
+    expect(share).toHaveBeenCalledWith(
+      expect.objectContaining({
+        message: expect.stringContaining("https://app.t3.codes/?ref=ABCD1234EFAB5678"),
+      }),
+      expect.objectContaining({ dialogTitle: "Share referral link" }),
+    );
+  });
+
+  it("propagates native sharing failures to the screen", async () => {
+    const failure = new Error("Native share failed");
+    const share = vi.fn().mockRejectedValue(failure);
+
+    await expect(
+      shareReferralLink("https://app.t3.codes/?ref=ABCD1234EFAB5678", share),
+    ).rejects.toBe(failure);
+  });
+
+  it("does not open an empty share sheet", async () => {
+    const share = vi.fn();
+
+    await shareReferralLink("", share);
+
+    expect(share).not.toHaveBeenCalled();
+  });
+});
diff --git a/apps/mobile/src/features/settings/referralShare.ts b/apps/mobile/src/features/settings/referralShare.ts
new file mode 100644
index 000000000000..7e2ae0bf5e91
--- /dev/null
+++ b/apps/mobile/src/features/settings/referralShare.ts
@@ -0,0 +1,24 @@
+import { buildReferralShareMessage, REFERRAL_SHARE_TITLE } from "@t3tools/shared/referral";
+
+type ShareReferral = (
+  content: { readonly title: string; readonly message: string },
+  options: { readonly dialogTitle: string; readonly subject: string },
+) => Promise<unknown>;
+
+export async function shareReferralLink(
+  referralLink: string,
+  share: ShareReferral,
+  awardPoints?: number,
+): Promise<void> {
+  if (!referralLink) return;
+  await share(
+    {
+      title: REFERRAL_SHARE_TITLE,
+      message: buildReferralShareMessage(referralLink, awardPoints),
+    },
+    {
+      dialogTitle: "Share referral link",
+      subject: REFERRAL_SHARE_TITLE,
+    },
+  );
+}
diff --git a/apps/web/src/cloud/linkEnvironment.test.ts b/apps/web/src/cloud/linkEnvironment.test.ts
index 38e205beabbb..c73a94d9c745 100644
--- a/apps/web/src/cloud/linkEnvironment.test.ts
+++ b/apps/web/src/cloud/linkEnvironment.test.ts
@@ -343,6 +343,177 @@ describe("web cloud link environment client", () => {
     }),
   );
 
+  it.effect("claims a captured referral before linking the first environment", () =>
+    Effect.gen(function* () {
+      const fetchMock = vi
+        .fn()
+        .mockResolvedValueOnce(
+          Response.json({
+            result: "claimed",
+            summary: {
+              points: 0,
+              referralCode: "1111222233334444",
+              awardPoints: 67,
+              qualifiedReferrals: 0,
+              pendingReferrals: 0,
+              canClaimReferral: false,
+            },
+          }),
+        )
+        .mockResolvedValueOnce(
+          Response.json({
+            challenge: "challenge",
+            expiresAt: "2026-06-06T00:05:00.000Z",
+          }),
+        )
+        .mockResolvedValueOnce(Response.json("signed-proof"))
+        .mockResolvedValueOnce(
+          Response.json({
+            ok: true,
+            environmentId: TARGET.environmentId,
+            endpoint: {
+              httpBaseUrl: "https://desktop.example.test",
+              wsBaseUrl: "wss://desktop.example.test",
+              providerKind: "cloudflare_tunnel",
+            },
+            endpointRuntime: null,
+            relayIssuer: "https://relay.example.test",
+            cloudUserId: "user-1",
+            environmentCredential: "environment-credential",
+            cloudMintPublicKey: "public-key",
+          }),
+        )
+        .mockResolvedValueOnce(
+          Response.json({ ok: true, endpointRuntimeStatus: { status: "configured" } }),
+        );
+      vi.stubGlobal("fetch", fetchMock);
+
+      yield* withServices(
+        linkPrimaryEnvironmentToCloud({
+          target: TARGET,
+          clerkToken: "clerk-token",
+          referralCode: "ABCD1234EFAB5678",
+        }),
+      );
+
+      expect(String(fetchMock.mock.calls[0]?.[0])).toBe(
+        "https://relay.example.test/v1/client/referrals/claim",
+      );
+      expect(String(fetchMock.mock.calls[3]?.[0])).toBe(
+        "https://relay.example.test/v1/client/environment-links",
+      );
+    }),
+  );
+
+  it.effect("does not link when the captured referral cannot be claimed", () =>
+    Effect.gen(function* () {
+      const fetchMock = vi.fn().mockResolvedValue(new Response(null, { status: 503 }));
+      vi.stubGlobal("fetch", fetchMock);
+
+      const error = yield* withServices(
+        linkPrimaryEnvironmentToCloud({
+          target: TARGET,
+          clerkToken: "clerk-token",
+          referralCode: "ABCD1234EFAB5678",
+        }),
+      ).pipe(Effect.flip);
+
+      expect(error.message).toContain("referrals/claim failed before environment linking");
+      expect(fetchMock).toHaveBeenCalledOnce();
+    }),
+  );
+
+  it.effect("continues linking for every non-rejected referral outcome", () =>
+    Effect.gen(function* () {
+      for (const claimResult of ["already_claimed", "ineligible"] as const) {
+        const fetchMock = vi
+          .fn()
+          .mockResolvedValueOnce(
+            Response.json({
+              result: claimResult,
+              summary: {
+                points: 0,
+                referralCode: "1111222233334444",
+                awardPoints: 67,
+                qualifiedReferrals: 0,
+                pendingReferrals: 0,
+                canClaimReferral: false,
+              },
+            }),
+          )
+          .mockResolvedValueOnce(
+            Response.json({
+              challenge: "challenge",
+              expiresAt: "2026-06-06T00:05:00.000Z",
+            }),
+          )
+          .mockResolvedValueOnce(Response.json("signed-proof"))
+          .mockResolvedValueOnce(
+            Response.json({
+              ok: true,
+              environmentId: TARGET.environmentId,
+              endpoint: {
+                httpBaseUrl: "https://desktop.example.test",
+                wsBaseUrl: "wss://desktop.example.test",
+                providerKind: "cloudflare_tunnel",
+              },
+              endpointRuntime: null,
+              relayIssuer: "https://relay.example.test",
+              cloudUserId: "user-1",
+              environmentCredential: "environment-credential",
+              cloudMintPublicKey: "public-key",
+            }),
+          )
+          .mockResolvedValueOnce(
+            Response.json({ ok: true, endpointRuntimeStatus: { status: "configured" } }),
+          );
+        vi.stubGlobal("fetch", fetchMock);
+
+        yield* withServices(
+          linkPrimaryEnvironmentToCloud({
+            target: TARGET,
+            clerkToken: "clerk-token",
+            referralCode: "ABCD1234EFAB5678",
+          }),
+        );
+
+        expect(fetchMock).toHaveBeenCalledTimes(5);
+      }
+    }),
+  );
+
+  it.effect("rejects invalid and cyclic referral codes before the environment is linked", () =>
+    Effect.gen(function* () {
+      for (const claimResult of ["invalid_code", "self_referral"] as const) {
+        const fetchMock = vi.fn().mockResolvedValue(
+          Response.json({
+            result: claimResult,
+            summary: {
+              points: 0,
+              referralCode: "1111222233334444",
+              awardPoints: 67,
+              qualifiedReferrals: 0,
+              pendingReferrals: 0,
+              canClaimReferral: true,
+            },
+          }),
+        );
+        vi.stubGlobal("fetch", fetchMock);
+
+        const error = yield* withServices(
+          linkPrimaryEnvironmentToCloud({
+            target: TARGET,
+            clerkToken: "clerk-token",
+            referralCode: "ABCD1234EFAB5678",
+          }),
+        ).pipe(Effect.flip);
+
+        expect(error).toMatchObject({ referralClaimResult: claimResult });
+        expect(fetchMock).toHaveBeenCalledOnce();
+      }
+    }),
+  );
+
   it.effect("links publish-only without a managed tunnel", () =>
     Effect.gen(function* () {
       const fetchMock = vi
diff --git a/apps/web/src/cloud/linkEnvironment.ts b/apps/web/src/cloud/linkEnvironment.ts
index a245cbc54db2..1964135f6414 100644
--- a/apps/web/src/cloud/linkEnvironment.ts
+++ b/apps/web/src/cloud/linkEnvironment.ts
@@ -21,6 +21,7 @@ import {
   type RelayEnvironmentLinkResponse,
   type RelayProtectedError as RelayProtectedErrorType,
   type RelayManagedEndpointProviderKind,
+  type RelayReferralClaimResult,
 } from "@t3tools/contracts/relay";
 import { EnvironmentRegistry } from "@t3tools/client-runtime/connection";
 import { request, runStream } from "@t3tools/client-runtime/rpc";
@@ -55,6 +56,10 @@ export class CloudEnvironmentLinkError extends Data.TaggedError("CloudEnvironmen
   readonly message: string;
   readonly cause?: unknown;
   readonly traceId?: string;
+  readonly referralClaimResult?: Extract<
+    RelayReferralClaimResult,
+    "invalid_code" | "self_referral"
+  >;
 }> {}
 
 const relayClientRpcError = (message: string) => (cause: unknown) =>
@@ -403,6 +408,7 @@ export function linkPrimaryEnvironmentToCloud(input: {
   readonly target: CloudLinkTarget;
   readonly clerkToken: string;
   readonly mode?: CloudLinkMode;
+  readonly referralCode?: string;
 }): Effect.Effect<
   void,
   CloudEnvironmentLinkError,
@@ -425,6 +431,39 @@ export function linkPrimaryEnvironmentToCloud(input: {
       yield* ensureRelayClientAvailable(EnvironmentId.make(input.target.environmentId));
     }
 
+    if (input.referralCode) {
+      const claimResponse = yield* relayClient
+        .claimReferral({
+          clerkToken: input.clerkToken,
+          referralCode: input.referralCode,
+        })
+        .pipe(
+          Effect.mapError(
+            decodedRelayClientError(
+              `${configuredRelayUrl}/v1/client/referrals/claim failed before environment linking`,
+            ),
+          ),
+        );
+      switch (claimResponse.result) {
+        case "claimed":
+        case "already_claimed":
+        case "ineligible":
+          break;
+        case "invalid_code":
+          return yield* new CloudEnvironmentLinkError({
+            message:
+              "The saved referral code is no longer valid. Apply a different code and try again.",
+            referralClaimResult: claimResponse.result,
+          });
+        case "self_referral":
+          return yield* new CloudEnvironmentLinkError({
+            message:
+              "You cannot link an environment while using a referral code from your account chain.",
+            referralClaimResult: claimResponse.result,
+          });
+      }
+    }
+
     const challenge = yield* relayClient
       .createEnvironmentLinkChallenge({
         clerkToken: input.clerkToken,
diff --git a/apps/web/src/cloud/linkEnvironmentAtoms.ts b/apps/web/src/cloud/linkEnvironmentAtoms.ts
index 1094e860e462..de86a3745d43 100644
--- a/apps/web/src/cloud/linkEnvironmentAtoms.ts
+++ b/apps/web/src/cloud/linkEnvironmentAtoms.ts
@@ -26,6 +26,7 @@ export const linkPrimaryEnvironment = createRuntimeCommand(connectionAtomRuntime
     readonly target: CloudLinkTarget;
     readonly clerkToken: string;
     readonly mode?: CloudLinkMode;
+    readonly referralCode?: string;
   }) => linkPrimaryEnvironmentToCloud(input),
 });
 
diff --git a/apps/web/src/cloud/managedRelayState.ts b/apps/web/src/cloud/managedRelayState.ts
index 9a56bde88514..e68cc3ac4a6d 100644
--- a/apps/web/src/cloud/managedRelayState.ts
+++ b/apps/web/src/cloud/managedRelayState.ts
@@ -1,6 +1,7 @@
 import { useAtomValue } from "@effect/atom-react";
 import {
   createManagedRelayQueryManager,
+  claimManagedRelayReferral,
   deregisterManagedRelayEnvironment,
   ManagedRelay,
   managedRelaySessionAtom,
@@ -13,6 +14,7 @@ import {
 import type {
   RelayClientDeviceRecord,
   RelayClientEnvironmentRecord,
+  RelayReferralSummary,
 } from "@t3tools/contracts/relay";
 import type { EnvironmentId } from "@t3tools/contracts";
 import * as Context from "effect/Context";
@@ -51,6 +53,16 @@ export const deregisterManagedRelayEnvironmentCommand = createRuntimeCommand(
   },
 );
 
+export const claimManagedRelayReferralCommand = createRuntimeCommand(managedRelayAtomRuntime, {
+  label: "web:managed-relay:claim-referral",
+  scheduler: managedRelayMutationScheduler,
+  concurrency: {
+    mode: "serial",
+    key: (input: { readonly accountId: string; readonly referralCode: string }) => input.accountId,
+  },
+  execute: (input, registry) => claimManagedRelayReferral(registry, input),
+});
+
 const EMPTY_ENVIRONMENTS_ATOM = Atom.make(
   AsyncResult.success<ReadonlyArray<RelayClientEnvironmentRecord>>([]),
 ).pipe(Atom.keepAlive, Atom.withLabel("managed-relay:web:environments:null"));
@@ -59,6 +71,10 @@ const EMPTY_DEVICES_ATOM = Atom.make(
   AsyncResult.success<ReadonlyArray<RelayClientDeviceRecord>>([]),
 ).pipe(Atom.keepAlive, Atom.withLabel("managed-relay:web:devices:null"));
 
+const EMPTY_REFERRAL_SUMMARY_ATOM = Atom.make(
+  AsyncResult.initial<RelayReferralSummary, never>(false),
+).pipe(Atom.keepAlive, Atom.withLabel("managed-relay:web:referrals:null"));
+
 export function useManagedRelayEnvironments() {
   const session = useAtomValue(managedRelaySessionAtom);
   const accountId = session?.accountId ?? null;
@@ -115,9 +131,45 @@ export function useManagedRelayDevices() {
   };
 }
 
+export function useManagedRelayReferralSummary() {
+  const session = useAtomValue(managedRelaySessionAtom);
+  const accountId = session?.accountId ?? null;
+  const atom = accountId
+    ? managedRelayQueryManager.referralSummaryAtom(accountId)
+    : EMPTY_REFERRAL_SUMMARY_ATOM;
+  const result = useAtomValue(atom);
+  const snapshot = readManagedRelaySnapshotState(result);
+  useEffect(() => {
+    if (snapshot.error) {
+      console.error("[t3-cloud] Relay referral summary failed", {
+        message: snapshot.error,
+        traceId: snapshot.errorTraceId,
+      });
+    }
+  }, [snapshot.error, snapshot.errorTraceId]);
+  const refresh = useCallback(() => {
+    if (accountId) {
+      managedRelayQueryManager.refreshReferralSummary(appAtomRegistry, accountId);
+    }
+  }, [accountId]);
+
+  return {
+    ...snapshot,
+    accountId,
+    refresh,
+  };
+}
+
 export function refreshManagedRelayEnvironments(): void {
   const session = appAtomRegistry.get(managedRelaySessionAtom);
   if (session) {
     managedRelayQueryManager.refreshEnvironments(appAtomRegistry, session.accountId);
   }
 }
+
+export function refreshManagedRelayReferralSummary(): void {
+  const session = appAtomRegistry.get(managedRelaySessionAtom);
+  if (session) {
+    managedRelayQueryManager.refreshReferralSummary(appAtomRegistry, session.accountId);
+  }
+}
diff --git a/apps/web/src/cloud/referralClaimResult.test.ts b/apps/web/src/cloud/referralClaimResult.test.ts
new file mode 100644
index 000000000000..50e108cb1207
--- /dev/null
+++ b/apps/web/src/cloud/referralClaimResult.test.ts
@@ -0,0 +1,16 @@
+import { describe, expect, it } from "vite-plus/test";
+
+import { referralClaimMessage } from "./referralClaimResult";
+
+describe("referralClaimMessage", () => {
+  it("describes every claim outcome and uses the server award", () => {
+    expect(referralClaimMessage("claimed", 100)).toMatchObject({
+      type: "success",
+      description: expect.stringContaining("100 points"),
+    });
+    expect(referralClaimMessage("already_claimed").type).toBe("info");
+    expect(referralClaimMessage("invalid_code").type).toBe("warning");
+    expect(referralClaimMessage("self_referral").title).toContain("account chain");
+    expect(referralClaimMessage("ineligible").description).toContain("before linking");
+  });
+});
diff --git a/apps/web/src/cloud/referralClaimResult.ts b/apps/web/src/cloud/referralClaimResult.ts
new file mode 100644
index 000000000000..907c5152e26e
--- /dev/null
+++ b/apps/web/src/cloud/referralClaimResult.ts
@@ -0,0 +1,34 @@
+import type { RelayReferralClaimResult } from "@t3tools/contracts/relay";
+import { REFERRAL_AWARD_POINTS } from "@t3tools/shared/referral";
+
+export interface ReferralClaimMessage {
+  readonly type: "success" | "warning" | "info";
+  readonly title: string;
+  readonly description?: string;
+}
+
+export function referralClaimMessage(
+  result: RelayReferralClaimResult,
+  awardPoints = REFERRAL_AWARD_POINTS,
+): ReferralClaimMessage {
+  switch (result) {
+    case "claimed":
+      return {
+        type: "success",
+        title: "Referral applied",
+        description: `Your referrer will receive ${awardPoints} points after you link your first environment.`,
+      };
+    case "already_claimed":
+      return { type: "info", title: "This account already claimed a referral" };
+    case "invalid_code":
+      return { type: "warning", title: "This referral code is not valid" };
+    case "self_referral":
+      return { type: "warning", title: "You cannot use a referral code from your account chain" };
+    case "ineligible":
+      return {
+        type: "info",
+        title: "Referral code not applied",
+        description: "Referral codes must be claimed before linking an environment.",
+      };
+  }
+}
diff --git a/apps/web/src/cloud/referralLinks.test.ts b/apps/web/src/cloud/referralLinks.test.ts
new file mode 100644
index 000000000000..28281290d46e
--- /dev/null
+++ b/apps/web/src/cloud/referralLinks.test.ts
@@ -0,0 +1,117 @@
+import { afterEach, describe, expect, it, vi } from "vite-plus/test";
+
+import {
+  buildReferralShareData,
+  captureReferralCodeFromUrl,
+  clearReferralCodeFromCurrentUrl,
+  clearPendingReferralCode,
+  PENDING_REFERRAL_CODE_STORAGE_KEY,
+  persistPendingReferralCode,
+  readPendingReferralCode,
+  referralCodeFromUrl,
+  urlWithoutMatchingReferralCode,
+  urlWithoutReferralCode,
+} from "./referralLinks";
+
+describe("referralLinks", () => {
+  afterEach(() => {
+    clearPendingReferralCode(() => ({ removeItem: vi.fn() }));
+  });
+
+  it("clears a pending code without exposing storage failures", () => {
+    const removeItem = vi.fn();
+    clearPendingReferralCode(() => ({ removeItem }));
+    expect(removeItem).toHaveBeenCalledWith(PENDING_REFERRAL_CODE_STORAGE_KEY);
+
+    expect(() =>
+      clearPendingReferralCode(() => {
+        throw new Error("storage unavailable");
+      }),
+    ).not.toThrow();
+  });
+
+  it("normalizes a pending referral read from storage", () => {
+    const storage = {
+      getItem: vi.fn(() => "abcd1234efab5678"),
+    };
+
+    expect(readPendingReferralCode(() => storage)).toBe("ABCD1234EFAB5678");
+    expect(storage.getItem).toHaveBeenCalledWith(PENDING_REFERRAL_CODE_STORAGE_KEY);
+  });
+
+  it("treats blocked browser storage as empty", () => {
+    expect(
+      readPendingReferralCode(() => {
+        throw new Error("Storage access denied");
+      }),
+    ).toBeNull();
+  });
+
+  it("keeps a captured code available for linking when browser storage is blocked", () => {
+    const url = new URL("https://app.t3.codes/?ref=abcd1234efab5678");
+    const blockedStorage = () => {
+      throw new Error("Storage access denied");
+    };
+
+    expect(
+      captureReferralCodeFromUrl(url, (referralCode) =>
+        persistPendingReferralCode(referralCode, blockedStorage),
+      ),
+    ).toEqual({
+      referralCode: "ABCD1234EFAB5678",
+      cleanedUrl: null,
+    });
+    expect(readPendingReferralCode(blockedStorage)).toBe("ABCD1234EFAB5678");
+  });
+
+  it("reads and removes only the referral parameter", () => {
+    const url = new URL("https://app.t3.codes/?channel=nightly&ref=abcd1234efab5678#thread");
+    expect(referralCodeFromUrl(url)).toBe("ABCD1234EFAB5678");
+    expect(urlWithoutReferralCode(url)).toBe("/?channel=nightly#thread");
+  });
+
+  it("only cleans the URL after the referral code is persisted", () => {
+    const url = new URL("https://app.t3.codes/?ref=abcd1234efab5678#thread");
+
+    expect(
+      captureReferralCodeFromUrl(url, () => {
+        throw new Error("storage unavailable");
+      }),
+    ).toEqual({ referralCode: "ABCD1234EFAB5678", cleanedUrl: null });
+
+    expect(captureReferralCodeFromUrl(url, () => undefined)).toEqual({
+      referralCode: "ABCD1234EFAB5678",
+      cleanedUrl: "/#thread",
+    });
+  });
+
+  it("does not clear a newer referral from the current URL", () => {
+    const currentUrl = new URL("https://app.t3.codes/?ref=BBBBBBBBBBBBBBBB#thread");
+
+    expect(urlWithoutMatchingReferralCode(currentUrl, "AAAAAAAAAAAAAAAA")).toBeNull();
+    expect(urlWithoutMatchingReferralCode(currentUrl, "bbbbbbbbbbbbbbbb")).toBe("/#thread");
+  });
+
+  it("removes a rejected referral from the current URL", () => {
+    const replaceUrl = vi.fn();
+
+    clearReferralCodeFromCurrentUrl(
+      "abcd1234efab5678",
+      () => new URL("https://app.t3.codes/?channel=nightly&ref=ABCD1234EFAB5678#thread"),
+      replaceUrl,
+    );
+
+    expect(replaceUrl).toHaveBeenCalledWith("/?channel=nightly#thread");
+  });
+
+  it("embeds the claim URL in web share text even when a share target drops the url field", () => {
+    const referralLink = "https://app.t3.codes/?ref=ABCD1234EFAB5678";
+    const shareData = buildReferralShareData(referralLink);
+
+    expect(shareData).toMatchObject({
+      title: "T3 Code referral",
+      url: referralLink,
+    });
+    expect(shareData.text).toContain(referralLink);
+  });
+});
diff --git a/apps/web/src/cloud/referralLinks.ts b/apps/web/src/cloud/referralLinks.ts
new file mode 100644
index 000000000000..d890f9d3406e
--- /dev/null
+++ b/apps/web/src/cloud/referralLinks.ts
@@ -0,0 +1,106 @@
+import {
+  buildReferralLink,
+  buildReferralShareMessage,
+  normalizeReferralCode,
+  REFERRAL_SHARE_TITLE,
+} from "@t3tools/shared/referral";
+
+export const PENDING_REFERRAL_CODE_STORAGE_KEY = "t3code.pending-referral-code";
+
+let inMemoryPendingReferralCode: string | null = null;
+
+export function persistPendingReferralCode(
+  referralCode: string,
+  getStorage: () => Pick<Storage, "setItem"> = () => window.localStorage,
+): boolean {
+  const normalized = normalizeReferralCode(referralCode);
+  if (!normalized) return false;
+
+  inMemoryPendingReferralCode = normalized;
+  try {
+    getStorage().setItem(PENDING_REFERRAL_CODE_STORAGE_KEY, normalized);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function readPendingReferralCode(
+  getStorage: () => Pick<Storage, "getItem"> = () => window.localStorage,
+): string | null {
+  try {
+    const storage = getStorage();
+    return (
+      inMemoryPendingReferralCode ??
+      normalizeReferralCode(storage.getItem(PENDING_REFERRAL_CODE_STORAGE_KEY) ?? "")
+    );
+  } catch {
+    return inMemoryPendingReferralCode;
+  }
+}
+
+export function clearPendingReferralCode(
+  getStorage: () => Pick<Storage, "removeItem"> = () => window.localStorage,
+): void {
+  inMemoryPendingReferralCode = null;
+  try {
+    getStorage().removeItem(PENDING_REFERRAL_CODE_STORAGE_KEY);
+  } catch {}
+}
+
+export function referralCodeFromUrl(url: URL): string | null {
+  return normalizeReferralCode(url.searchParams.get("ref") ?? "");
+}
+
+export function urlWithoutReferralCode(url: URL): string {
+  const next = new URL(url);
+  next.searchParams.delete("ref");
+  return `${next.pathname}${next.search}${next.hash}`;
+}
+
+export function urlWithoutMatchingReferralCode(
+  url: URL,
+  expectedReferralCode: string,
+): string | null {
+  const expected = normalizeReferralCode(expectedReferralCode);
+  if (!expected || referralCodeFromUrl(url) !== expected) return null;
+  return urlWithoutReferralCode(url);
+}
+
+export function clearReferralCodeFromCurrentUrl(
+  referralCode: string,
+  getUrl: () => URL = () => new URL(window.location.href),
+  replaceUrl: (url: string) => void = (url) =>
+    window.history.replaceState(window.history.state, "", url),
+): void {
+  const cleanedUrl = urlWithoutMatchingReferralCode(getUrl(), referralCode);
+  if (cleanedUrl) replaceUrl(cleanedUrl);
+}
+
+export function captureReferralCodeFromUrl(
+  url: URL,
+  persist: (referralCode: string) => boolean | void,
+): { referralCode: string; cleanedUrl: string | null } | null {
+  const referralCode = referralCodeFromUrl(url);
+  if (!referralCode) return null;
+
+  try {
+    if (persist(referralCode) === false) {
+      return { referralCode, cleanedUrl: null };
+    }
+  } catch {
+    return { referralCode, cleanedUrl: null };
+  }
+
+  return { referralCode, cleanedUrl: urlWithoutReferralCode(url) };
+}
+
+export function buildReferralShareData(referralLink: string, awardPoints?: number) {
+  return {
+    title: REFERRAL_SHARE_TITLE,
+    text: buildReferralShareMessage(referralLink, awardPoints),
+    url: referralLink,
+  };
+}
+
+export { buildReferralLink, normalizeReferralCode };
diff --git a/apps/web/src/cloud/useCloudLinkController.ts b/apps/web/src/cloud/useCloudLinkController.ts
index d91596880850..5b66326d60e5 100644
--- a/apps/web/src/cloud/useCloudLinkController.ts
+++ b/apps/web/src/cloud/useCloudLinkController.ts
@@ -10,6 +10,7 @@ import { useState } from "react";
 import { toastManager } from "../components/ui/toast";
 import { relayEnvironmentDiscovery } from "../state/relay";
 import { useAtomCommand } from "../state/use-atom-command";
+import { CloudEnvironmentLinkError } from "./linkEnvironment";
 import {
   linkPrimaryEnvironment as linkPrimaryEnvironmentAtom,
   unlinkPrimaryEnvironment as unlinkPrimaryEnvironmentAtom,
@@ -17,6 +18,11 @@ import {
 } from "./linkEnvironmentAtoms";
 import { usePrimaryCloudLinkState } from "./primaryCloudLinkState";
 import { resolveRelayClerkTokenOptions } from "./publicConfig";
+import {
+  clearPendingReferralCode,
+  clearReferralCodeFromCurrentUrl,
+  readPendingReferralCode,
+} from "./referralLinks";
 
 export interface CloudLinkDesiredState {
   readonly managedTunnel: boolean;
@@ -116,18 +122,30 @@ export function useCloudLinkController() {
         return false;
       }
       if (!linked || managedTunnelActive !== desired.managedTunnel) {
+        const referralCode = linked ? null : readPendingReferralCode();
         const linkResult = await linkPrimaryEnvironment({
           target,
           clerkToken,
           mode: desired.managedTunnel ? "managed" : "publish_only",
+          ...(referralCode ? { referralCode } : {}),
         });
         if (linkResult._tag === "Failure") {
           if (!isAtomCommandInterrupted(linkResult)) {
-            reportUpdateFailure(squashAtomCommandFailure(linkResult));
+            const cause = squashAtomCommandFailure(linkResult);
+            if (
+              referralCode &&
+              cause instanceof CloudEnvironmentLinkError &&
+              cause.referralClaimResult !== undefined
+            ) {
+              clearPendingReferralCode();
+              clearReferralCodeFromCurrentUrl(referralCode);
+            }
+            reportUpdateFailure(cause);
           }
           primaryCloudLinkState.refresh();
           return false;
         }
+        if (referralCode) clearPendingReferralCode();
       }
       const prefResult = await updatePrimaryEnvironmentPreferences({
         target,
diff --git a/apps/web/src/components/clerk/ClerkUserProfilePage.tsx b/apps/web/src/components/clerk/ClerkUserProfilePage.tsx
index 00f20e53fbe1..764ebbcb4e34 100644
--- a/apps/web/src/components/clerk/ClerkUserProfilePage.tsx
+++ b/apps/web/src/components/clerk/ClerkUserProfilePage.tsx
@@ -61,6 +61,26 @@ export function ClerkUserProfileRefreshButton({
   );
 }
 
+export function ClerkUserProfileIcon({
+  children,
+  className,
+}: {
+  readonly children: ReactNode;
+  readonly className?: string;
+}) {
+  return (
+    <div
+      aria-hidden="true"
+      className={cn(
+        "flex size-8 shrink-0 items-center justify-center rounded-lg border bg-muted/32 text-muted-foreground",
+        className,
+      )}
+    >
+      {children}
+    </div>
+  );
+}
+
 export function ClerkUserProfileRow({
   children,
   className,
@@ -73,12 +93,7 @@ export function ClerkUserProfileRow({
   return (
     <li className={cn("border-t py-4 first:border-t-0", className)}>
       <div className="flex items-start gap-3">
-        <div
-          aria-hidden="true"
-          className="flex size-8 shrink-0 items-center justify-center rounded-lg border bg-muted/32 text-muted-foreground"
-        >
-          {icon}
-        </div>
+        <ClerkUserProfileIcon>{icon}</ClerkUserProfileIcon>
         <div className="min-w-0 flex-1">{children}</div>
       </div>
     </li>
diff --git a/apps/web/src/components/clerk/ReferralsUserProfilePage.tsx b/apps/web/src/components/clerk/ReferralsUserProfilePage.tsx
new file mode 100644
index 000000000000..e54d700cabe1
--- /dev/null
+++ b/apps/web/src/components/clerk/ReferralsUserProfilePage.tsx
@@ -0,0 +1,295 @@
+import {
+  isAtomCommandInterrupted,
+  squashAtomCommandFailure,
+} from "@t3tools/client-runtime/state/runtime";
+import { REFERRAL_AWARD_POINTS } from "@t3tools/shared/referral";
+import { CheckIcon, CopyIcon, GiftIcon, LinkIcon, Share2Icon, TicketCheckIcon } from "lucide-react";
+import { type ReactNode, useMemo, useState } from "react";
+
+import {
+  claimManagedRelayReferralCommand,
+  useManagedRelayReferralSummary,
+} from "../../cloud/managedRelayState";
+import {
+  buildReferralLink,
+  buildReferralShareData,
+  normalizeReferralCode,
+} from "../../cloud/referralLinks";
+import { referralClaimMessage } from "../../cloud/referralClaimResult";
+import { configuredHostedAppUrl } from "../../hostedPairing";
+import { useCopyToClipboard } from "../../hooks/useCopyToClipboard";
+import { useAtomCommand } from "../../state/use-atom-command";
+import { Alert, AlertDescription, AlertTitle } from "../ui/alert";
+import { Button } from "../ui/button";
+import { Card, CardContent } from "../ui/card";
+import { Input } from "../ui/input";
+import { Skeleton } from "../ui/skeleton";
+import { toastManager } from "../ui/toast";
+import {
+  ClerkUserProfileIcon,
+  ClerkUserProfilePage,
+  ClerkUserProfileRefreshButton,
+} from "./ClerkUserProfilePage";
+
+function ReferralMetric(props: { readonly label: string; readonly value: number }) {
+  return (
+    <div className="min-w-0 rounded-lg px-3 py-3 sm:px-4">
+      <dt className="text-[0.6875rem] leading-4 font-medium text-muted-foreground">
+        {props.label}
+      </dt>
+      <dd className="mt-0.5 text-2xl leading-8 font-semibold tracking-tight tabular-nums">
+        {props.value}
+      </dd>
+    </div>
+  );
+}
+
+function ReferralSectionHeading({
+  icon,
+  title,
+  description,
+}: {
+  readonly icon: ReactNode;
+  readonly title: string;
+  readonly description: string;
+}) {
+  return (
+    <div className="flex items-start gap-3">
+      <ClerkUserProfileIcon className="border-0 bg-muted/55">{icon}</ClerkUserProfileIcon>
+      <div className="min-w-0 pt-0.5">
+        <h3 className="text-sm font-semibold">{title}</h3>
+        <p className="mt-0.5 max-w-[30rem] text-xs leading-5 text-muted-foreground">
+          {description}
+        </p>
+      </div>
+    </div>
+  );
+}
+
+export function ReferralsUserProfilePage() {
+  const summaryState = useManagedRelayReferralSummary();
+  const claimReferral = useAtomCommand(claimManagedRelayReferralCommand, {
+    reportFailure: false,
+  });
+  const [referralCode, setReferralCode] = useState("");
+  const [isClaiming, setIsClaiming] = useState(false);
+  const { copyToClipboard: copyReferralLink, isCopied: isLinkCopied } = useCopyToClipboard({
+    target: "referral link",
+    onCopy: () => toastManager.add({ type: "success", title: "Referral link copied" }),
+    onError: (error) =>
+      toastManager.add({
+        type: "error",
+        title: "Could not copy referral link",
+        description: error.message,
+      }),
+  });
+  const { copyToClipboard: copyReferralCode, isCopied: isCodeCopied } = useCopyToClipboard({
+    target: "referral code",
+    onCopy: () => toastManager.add({ type: "success", title: "Referral code copied" }),
+    onError: (error) =>
+      toastManager.add({
+        type: "error",
+        title: "Could not copy referral code",
+        description: error.message,
+      }),
+  });
+  const summary = summaryState.data;
+  const referralLink = useMemo(
+    () => (summary ? buildReferralLink(configuredHostedAppUrl(), summary.referralCode) : null),
+    [summary],
+  );
+  const canShare = typeof navigator !== "undefined" && typeof navigator.share === "function";
+
+  const submitReferralCode = async () => {
+    const accountId = summaryState.accountId;
+    const normalized = normalizeReferralCode(referralCode);
+    if (!accountId || !normalized || isClaiming) {
+      if (!normalized) {
+        toastManager.add({ type: "warning", title: "Enter a valid 16-character referral code" });
+      }
+      return;
+    }
+
+    setIsClaiming(true);
+    const result = await claimReferral({ accountId, referralCode: normalized });
+    setIsClaiming(false);
+    if (result._tag === "Success") {
+      const message = referralClaimMessage(result.value.result, result.value.summary.awardPoints);
+      toastManager.add(message);
+      setReferralCode("");
+      summaryState.refresh();
+      return;
+    }
+    if (isAtomCommandInterrupted(result)) return;
+    const cause = squashAtomCommandFailure(result);
+    toastManager.add({
+      type: "error",
+      title: "Could not claim referral code",
+      description: cause instanceof Error ? cause.message : "Try again.",
+    });
+  };
+
+  const shareReferral = async () => {
+    if (!referralLink) return;
+    if (!canShare) {
+      await copyReferralLink(referralLink);
+      return;
+    }
+
+    try {
+      await navigator.share(buildReferralShareData(referralLink, summary?.awardPoints));
+    } catch (error) {
+      if (error instanceof Error && error.name === "AbortError") return;
+      toastManager.add({
+        type: "error",
+        title: "Could not share referral link",
+        description: error instanceof Error ? error.message : "Try copying the link instead.",
+      });
+    }
+  };
+
+  const isInitialLoad =
+    !summaryState.accountId || (summaryState.data === null && !summaryState.error);
+
+  return (
+    <ClerkUserProfilePage
+      title="Referrals"
+      description={`Earn ${summary?.awardPoints ?? REFERRAL_AWARD_POINTS} points when a friend claims your link before connecting their first environment. Your balance follows your T3 account.`}
+      action={
+        <ClerkUserProfileRefreshButton
+          disabled={isClaiming}
+          isPending={summaryState.isPending}
+          onClick={summaryState.refresh}
+        />
+      }
+    >
+      {summaryState.error ? (
+        <Alert variant="error" className="mb-3 text-[0.8125rem]">
+          <AlertTitle>Could not load referral points</AlertTitle>
+          <AlertDescription className="text-xs">{summaryState.error}</AlertDescription>
+        </Alert>
+      ) : null}
+
+      {isInitialLoad ? (
+        <Card variant="muted" className="p-2" aria-label="Loading referrals" role="status">
+          <div className="grid grid-cols-3 gap-1.5">
+            <div className="p-2">
+              <Skeleton className="h-11 rounded-lg" />
+            </div>
+            <div className="p-2">
+              <Skeleton className="h-11 rounded-lg" />
+            </div>
+            <div className="p-2">
+              <Skeleton className="h-11 rounded-lg" />
+            </div>
+          </div>
+        </Card>
+      ) : summary ? (
+        <div className="space-y-3">
+          <Card variant="muted" className="p-2">
+            <dl className="grid grid-cols-3 gap-1.5">
+              <ReferralMetric label="Points" value={summary.points} />
+              <ReferralMetric label="Successful" value={summary.qualifiedReferrals} />
+              <ReferralMetric label="Pending" value={summary.pendingReferrals} />
+            </dl>
+          </Card>
+
+          <Card variant="muted">
+            <CardContent className="p-4 sm:p-5">
+              <ReferralSectionHeading
+                icon={<GiftIcon className="size-4" />}
+                title="Invite someone"
+                description="They need to claim your link before linking their first T3 Code environment."
+              />
+              <div className="mt-4 space-y-2 sm:ml-11">
+                <div className="flex flex-col gap-2 sm:flex-row sm:items-center">
+                  <div className="min-w-0 flex-1 rounded-lg bg-muted/40 px-3 py-2.5">
+                    <div className="flex items-center gap-1.5 text-[0.6875rem] font-medium text-muted-foreground">
+                      <LinkIcon className="size-3" aria-hidden="true" />
+                      Referral link
+                    </div>
+                    <p className="mt-0.5 truncate text-xs">{referralLink}</p>
+                  </div>
+                  <Button
+                    size="sm"
+                    variant="outline"
+                    className="shrink-0 text-[0.8125rem]"
+                    disabled={!referralLink}
+                    onClick={() => void shareReferral()}
+                  >
+                    {canShare ? (
+                      <Share2Icon className="size-3.5" aria-hidden="true" />
+                    ) : isLinkCopied ? (
+                      <CheckIcon className="size-3.5" aria-hidden="true" />
+                    ) : (
+                      <CopyIcon className="size-3.5" aria-hidden="true" />
+                    )}
+                    {canShare ? "Share" : isLinkCopied ? "Copied" : "Copy link"}
+                  </Button>
+                </div>
+                <div className="flex items-center justify-between gap-3 px-1 py-1">
+                  <div className="min-w-0">
+                    <span className="text-[0.6875rem] font-medium text-muted-foreground">
+                      Referral code
+                    </span>
+                    <code className="ml-2 text-xs tracking-[0.04em]">{summary.referralCode}</code>
+                  </div>
+                  <Button
+                    size="icon-xs"
+                    variant="ghost-muted"
+                    aria-label={isCodeCopied ? "Referral code copied" : "Copy referral code"}
+                    onClick={() => copyReferralCode(summary.referralCode)}
+                  >
+                    {isCodeCopied ? (
+                      <CheckIcon className="size-3.5" aria-hidden="true" />
+                    ) : (
+                      <CopyIcon className="size-3.5" aria-hidden="true" />
+                    )}
+                  </Button>
+                </div>
+              </div>
+            </CardContent>
+          </Card>
+
+          {summary.canClaimReferral ? (
+            <Card variant="muted">
+              <CardContent className="p-4 sm:p-5">
+                <ReferralSectionHeading
+                  icon={<TicketCheckIcon className="size-4" />}
+                  title="Use a referral code"
+                  description="Apply it before linking your first environment."
+                />
+                <div className="mt-4 flex flex-col gap-2 sm:ml-11 sm:flex-row">
+                  <Input
+                    autoCapitalize="characters"
+                    autoComplete="off"
+                    autoCorrect="off"
+                    nativeInput
+                    size="sm"
+                    spellCheck={false}
+                    value={referralCode}
+                    placeholder="ABCD1234EFAB5678"
+                    aria-label="Referral code"
+                    disabled={isClaiming}
+                    onChange={(event) => setReferralCode(event.currentTarget.value)}
+                    onKeyDown={(event) => {
+                      if (event.key === "Enter") void submitReferralCode();
+                    }}
+                  />
+                  <Button
+                    size="sm"
+                    className="shrink-0 text-[0.8125rem]"
+                    disabled={isClaiming}
+                    onClick={() => void submitReferralCode()}
+                  >
+                    {isClaiming ? "Applying..." : "Apply code"}
+                  </Button>
+                </div>
+              </CardContent>
+            </Card>
+          ) : null}
+        </div>
+      ) : null}
+    </ClerkUserProfilePage>
+  );
+}
diff --git a/apps/web/src/components/clerk/T3ConnectSidebarSignIn.tsx b/apps/web/src/components/clerk/T3ConnectSidebarSignIn.tsx
index 9dfd8dce13b1..1c7ff1ebf469 100644
--- a/apps/web/src/components/clerk/T3ConnectSidebarSignIn.tsx
+++ b/apps/web/src/components/clerk/T3ConnectSidebarSignIn.tsx
@@ -1,9 +1,10 @@
 import { UserButton, useAuth } from "@clerk/react";
-import { LogInIcon, ServerIcon, SmartphoneIcon } from "lucide-react";
+import { GiftIcon, LogInIcon, ServerIcon, SmartphoneIcon } from "lucide-react";
 
 import { hasCloudPublicConfig } from "../../cloud/publicConfig";
 import { SidebarMenu, SidebarMenuButton, SidebarMenuItem } from "../ui/sidebar";
 import { MobileClientsUserProfilePage } from "./MobileClientsUserProfilePage";
+import { ReferralsUserProfilePage } from "./ReferralsUserProfilePage";
 import { T3ConnectUserProfilePage } from "./T3ConnectUserProfilePage";
 import { useT3ConnectAuthPrompt } from "./useT3ConnectAuthPrompt";
 
@@ -33,6 +34,13 @@ function ConfiguredT3ConnectSidebarAvatar() {
         },
       }}
     >
+      <UserButton.MenuItems>
+        <UserButton.Action
+          label="Referrals"
+          labelIcon={<GiftIcon className="size-4" />}
+          open="referrals"
+        />
+      </UserButton.MenuItems>
       <UserButton.UserProfilePage
         label="Mobile clients"
         labelIcon={<SmartphoneIcon className="size-4" />}
@@ -47,6 +55,13 @@ function ConfiguredT3ConnectSidebarAvatar() {
       >
         <T3ConnectUserProfilePage />
       </UserButton.UserProfilePage>
+      <UserButton.UserProfilePage
+        label="Referrals"
+        labelIcon={<GiftIcon className="size-4" />}
+        url="referrals"
+      >
+        <ReferralsUserProfilePage />
+      </UserButton.UserProfilePage>
     </UserButton>
   );
 }
diff --git a/apps/web/src/components/clerk/useT3ConnectAuthPrompt.tsx b/apps/web/src/components/clerk/useT3ConnectAuthPrompt.tsx
index 859a122ffe4b..c05b6fe687de 100644
--- a/apps/web/src/components/clerk/useT3ConnectAuthPrompt.tsx
+++ b/apps/web/src/components/clerk/useT3ConnectAuthPrompt.tsx
@@ -1,12 +1,13 @@
 import { useClerk } from "@clerk/react";
+import { useCallback } from "react";
 
 import { isElectron } from "../../env";
 import { resolveClerkSignInProps } from "./authRedirect";
 
 export function useT3ConnectAuthPrompt() {
   const clerk = useClerk();
-  const openAuthPrompt = () => {
+  const openAuthPrompt = useCallback(() => {
     clerk.openSignIn(resolveClerkSignInProps(window.location.href, isElectron));
-  };
+  }, [clerk]);
   return { authPrompt: null, openAuthPrompt };
 }
diff --git a/apps/web/src/components/cloud/ReferralClaimCoordinator.logic.test.ts b/apps/web/src/components/cloud/ReferralClaimCoordinator.logic.test.ts
new file mode 100644
index 000000000000..08e2753875c2
--- /dev/null
+++ b/apps/web/src/components/cloud/ReferralClaimCoordinator.logic.test.ts
@@ -0,0 +1,82 @@
+import { describe, expect, it } from "vite-plus/test";
+
+import {
+  claimReferralWithRetry,
+  isCurrentReferralClaimAttempt,
+} from "./ReferralClaimCoordinator.logic";
+
+describe("claimReferralWithRetry", () => {
+  it("retries transient failures with bounded backoff", async () => {
+    const results = ["failure", "failure", "success"] as const;
+    const delays: number[] = [];
+    let attempts = 0;
+
+    const result = await claimReferralWithRetry({
+      claim: async () => results[attempts++] ?? "failure",
+      shouldRetry: (claimResult) => claimResult === "failure",
+      wait: async (delay) => {
+        delays.push(delay);
+      },
+    });
+
+    expect(result).toBe("success");
+    expect(attempts).toBe(3);
+    expect(delays).toEqual([250, 1_000]);
+  });
+
+  it("stops after three retries", async () => {
+    let attempts = 0;
+
+    const result = await claimReferralWithRetry({
+      claim: async () => {
+        attempts += 1;
+        return "failure";
+      },
+      shouldRetry: () => true,
+      wait: async () => undefined,
+    });
+
+    expect(result).toBe("failure");
+    expect(attempts).toBe(4);
+  });
+
+  it("does not retry after cancellation during backoff", async () => {
+    let attempts = 0;
+    let isCurrent = true;
+
+    const result = await claimReferralWithRetry({
+      claim: async () => {
+        attempts += 1;
+        return "failure";
+      },
+      shouldContinue: () => isCurrent,
+      shouldRetry: () => true,
+      wait: async () => {
+        isCurrent = false;
+      },
+    });
+
+    expect(result).toBe("failure");
+    expect(attempts).toBe(1);
+  });
+});
+
+describe("isCurrentReferralClaimAttempt", () => {
+  it("rejects a result after the account changes or the effect is cancelled", () => {
+    const accountAAttempt = { key: "account-a:ABCD1234EFAB5678" };
+
+    expect(isCurrentReferralClaimAttempt(false, accountAAttempt, accountAAttempt)).toBe(true);
+    expect(
+      isCurrentReferralClaimAttempt(false, { key: "account-b:ABCD1234EFAB5678" }, accountAAttempt),
+    ).toBe(false);
+    expect(isCurrentReferralClaimAttempt(true, accountAAttempt, accountAAttempt)).toBe(false);
+  });
+
+  it("rejects a stale result when a same-key successor is active", () => {
+    const staleAttempt = { key: "account-a:ABCD1234EFAB5678" };
+    const successorAttempt = { key: "account-a:ABCD1234EFAB5678" };
+
+    expect(isCurrentReferralClaimAttempt(false, successorAttempt, staleAttempt)).toBe(false);
+    expect(isCurrentReferralClaimAttempt(false, successorAttempt, successorAttempt)).toBe(true);
+  });
+});
diff --git a/apps/web/src/components/cloud/ReferralClaimCoordinator.logic.ts b/apps/web/src/components/cloud/ReferralClaimCoordinator.logic.ts
new file mode 100644
index 000000000000..e993d8ad7afe
--- /dev/null
+++ b/apps/web/src/components/cloud/ReferralClaimCoordinator.logic.ts
@@ -0,0 +1,41 @@
+const REFERRAL_CLAIM_RETRY_DELAYS_MS = [250, 1_000, 3_000] as const;
+
+export interface ReferralClaimAttempt {
+  readonly key: string;
+}
+
+function waitForRetry(delay: number): Promise<void> {
+  return new Promise((resolve) => globalThis.setTimeout(resolve, delay));
+}
+
+export function isCurrentReferralClaimAttempt(
+  isCancelled: boolean,
+  activeAttempt: ReferralClaimAttempt | null,
+  attempt: ReferralClaimAttempt,
+): boolean {
+  return !isCancelled && activeAttempt === attempt;
+}
+
+export async function claimReferralWithRetry<Result>({
+  claim,
+  shouldContinue = () => true,
+  shouldRetry,
+  wait = waitForRetry,
+}: {
+  readonly claim: () => Promise<Result>;
+  readonly shouldContinue?: () => boolean;
+  readonly shouldRetry: (result: Result) => boolean;
+  readonly wait?: (delay: number) => Promise<void>;
+}): Promise<Result> {
+  let failedAttempts = 0;
+  while (true) {
+    const result = await claim();
+    if (!shouldRetry(result)) return result;
+
+    const retryDelay = REFERRAL_CLAIM_RETRY_DELAYS_MS[failedAttempts];
+    if (retryDelay === undefined) return result;
+    failedAttempts += 1;
+    await wait(retryDelay);
+    if (!shouldContinue()) return result;
+  }
+}
diff --git a/apps/web/src/components/cloud/ReferralClaimCoordinator.tsx b/apps/web/src/components/cloud/ReferralClaimCoordinator.tsx
new file mode 100644
index 000000000000..132c36fce098
--- /dev/null
+++ b/apps/web/src/components/cloud/ReferralClaimCoordinator.tsx
@@ -0,0 +1,174 @@
+import { useAuth } from "@clerk/react";
+import { useAtomValue } from "@effect/atom-react";
+import { managedRelaySessionAtom } from "@t3tools/client-runtime/relay";
+import {
+  isAtomCommandInterrupted,
+  squashAtomCommandFailure,
+} from "@t3tools/client-runtime/state/runtime";
+import { useLocation } from "@tanstack/react-router";
+import { useCallback, useEffect, useRef, useState } from "react";
+
+import {
+  claimManagedRelayReferralCommand,
+  refreshManagedRelayReferralSummary,
+} from "../../cloud/managedRelayState";
+import { hasCloudPublicConfig } from "../../cloud/publicConfig";
+import { referralClaimMessage } from "../../cloud/referralClaimResult";
+import {
+  captureReferralCodeFromUrl,
+  clearReferralCodeFromCurrentUrl,
+  clearPendingReferralCode,
+  persistPendingReferralCode,
+  readPendingReferralCode,
+} from "../../cloud/referralLinks";
+import { useAtomCommand } from "../../state/use-atom-command";
+import { useT3ConnectAuthPrompt } from "../clerk/useT3ConnectAuthPrompt";
+import { toastManager } from "../ui/toast";
+import { stackedThreadToast } from "../ui/toastHelpers";
+import {
+  claimReferralWithRetry,
+  isCurrentReferralClaimAttempt,
+  type ReferralClaimAttempt,
+} from "./ReferralClaimCoordinator.logic";
+
+function captureReferralCode(): string | null {
+  const url = new URL(window.location.href);
+  const captured = captureReferralCodeFromUrl(url, persistPendingReferralCode);
+  if (!captured) return null;
+  if (captured.cleanedUrl) {
+    window.history.replaceState(window.history.state, "", captured.cleanedUrl);
+  }
+  return captured.referralCode;
+}
+
+export function ReferralClaimCoordinator() {
+  if (!hasCloudPublicConfig()) return null;
+  return <ConfiguredReferralClaimCoordinator />;
+}
+
+function ConfiguredReferralClaimCoordinator() {
+  const { isLoaded, isSignedIn, userId } = useAuth({ treatPendingAsSignedOut: false });
+  const locationHref = useLocation({ select: (location) => location.href });
+  const claimReferral = useAtomCommand(claimManagedRelayReferralCommand, {
+    reportFailure: false,
+  });
+  const relayAccountId = useAtomValue(managedRelaySessionAtom)?.accountId ?? null;
+  const { authPrompt, openAuthPrompt } = useT3ConnectAuthPrompt();
+  const [pendingReferralCode, setPendingReferralCode] = useState<string | null>(null);
+  const activeClaimRef = useRef<ReferralClaimAttempt | null>(null);
+  const completedClaimRef = useRef<string | null>(null);
+  const retryToastIdRef = useRef<ReturnType<typeof toastManager.add> | null>(null);
+  const initializedReferralRef = useRef(false);
+  const promptedSignInRef = useRef<string | null>(null);
+  const shouldPromptSignInRef = useRef(false);
+  const closeRetryToast = useCallback(() => {
+    if (retryToastIdRef.current === null) return;
+    toastManager.close(retryToastIdRef.current);
+    retryToastIdRef.current = null;
+  }, []);
+
+  useEffect(() => {
+    const capturedCode = captureReferralCode();
+    if (!capturedCode && initializedReferralRef.current) return;
+    initializedReferralRef.current = true;
+    shouldPromptSignInRef.current = capturedCode !== null;
+    setPendingReferralCode(capturedCode ?? readPendingReferralCode());
+  }, [locationHref]);
+
+  useEffect(() => {
+    if (!isLoaded || isSignedIn || !pendingReferralCode || !shouldPromptSignInRef.current) return;
+    if (promptedSignInRef.current === pendingReferralCode) return;
+    promptedSignInRef.current = pendingReferralCode;
+    toastManager.add({
+      type: "info",
+      title: "Referral link ready",
+      description: "Sign in to claim it before linking your first environment.",
+    });
+    openAuthPrompt();
+  }, [isLoaded, isSignedIn, openAuthPrompt, pendingReferralCode]);
+
+  useEffect(() => {
+    if (!isLoaded || !isSignedIn || !userId || relayAccountId !== userId) return;
+    const referralCode = pendingReferralCode ?? readPendingReferralCode();
+    if (!referralCode) return;
+    const attemptKey = `${userId}:${referralCode}`;
+    const attempt = { key: attemptKey };
+    let isCancelled = false;
+    const isCurrentAttempt = () =>
+      isCurrentReferralClaimAttempt(isCancelled, activeClaimRef.current, attempt);
+
+    const runClaim = async () => {
+      if (isCancelled) return;
+      if (activeClaimRef.current?.key === attemptKey || completedClaimRef.current === attemptKey)
+        return;
+      activeClaimRef.current = attempt;
+      try {
+        const result = await claimReferralWithRetry({
+          claim: () => claimReferral({ accountId: userId, referralCode }),
+          shouldContinue: isCurrentAttempt,
+          shouldRetry: (claimResult) =>
+            isCurrentAttempt() &&
+            claimResult._tag !== "Success" &&
+            !isAtomCommandInterrupted(claimResult),
+        });
+        if (result._tag === "Success") {
+          if (!isCurrentAttempt()) return;
+          completedClaimRef.current = attemptKey;
+          closeRetryToast();
+          clearPendingReferralCode();
+          clearReferralCodeFromCurrentUrl(referralCode);
+          setPendingReferralCode(null);
+          refreshManagedRelayReferralSummary();
+          if (result.value.result !== "already_claimed") {
+            toastManager.add(
+              referralClaimMessage(result.value.result, result.value.summary.awardPoints),
+            );
+          }
+          return;
+        }
+        if (!isCurrentAttempt() || isAtomCommandInterrupted(result)) return;
+        const cause = squashAtomCommandFailure(result);
+        console.error("[t3-cloud] Could not claim captured referral code", { cause });
+        const retryToast = stackedThreadToast({
+          type: "error",
+          title: "Referral still pending",
+          description: "Retry before linking an environment so your referrer can receive points.",
+          timeout: 0,
+          actionProps: {
+            children: "Retry",
+            onClick: () => void runClaim(),
+          },
+          data: {
+            onClose: () => {
+              retryToastIdRef.current = null;
+            },
+          },
+        });
+        if (retryToastIdRef.current === null) {
+          retryToastIdRef.current = toastManager.add(retryToast);
+        } else {
+          toastManager.update(retryToastIdRef.current, retryToast);
+        }
+      } finally {
+        if (activeClaimRef.current === attempt) activeClaimRef.current = null;
+      }
+    };
+
+    void runClaim();
+    return () => {
+      isCancelled = true;
+      if (activeClaimRef.current === attempt) activeClaimRef.current = null;
+      closeRetryToast();
+    };
+  }, [
+    claimReferral,
+    closeRetryToast,
+    isLoaded,
+    isSignedIn,
+    pendingReferralCode,
+    relayAccountId,
+    userId,
+  ]);
+
+  return authPrompt;
+}
diff --git a/apps/web/src/components/ui/card.tsx b/apps/web/src/components/ui/card.tsx
index f1428d13d909..aa069b963080 100644
--- a/apps/web/src/components/ui/card.tsx
+++ b/apps/web/src/components/ui/card.tsx
@@ -2,15 +2,32 @@
 
 import { mergeProps } from "@base-ui/react/merge-props";
 import { useRender } from "@base-ui/react/use-render";
+import { cva, type VariantProps } from "class-variance-authority";
 
 import { cn } from "~/lib/utils";
 
-function Card({ className, render, ...props }: useRender.ComponentProps<"div">) {
+const cardVariants = cva(
+  "relative flex flex-col rounded-2xl border bg-card not-dark:bg-clip-padding text-card-foreground shadow-xs/5 before:pointer-events-none before:absolute before:inset-0 before:rounded-[calc(var(--radius-2xl)-1px)] before:shadow-[0_1px_--theme(--color-black/4%)] dark:before:shadow-[0_-1px_--theme(--color-white/6%)]",
+  {
+    defaultVariants: {
+      variant: "default",
+    },
+    variants: {
+      variant: {
+        default: null,
+        muted: "rounded-xl border-border/40 bg-muted/20 shadow-none before:hidden",
+      },
+    },
+  },
+);
+
+type CardProps = useRender.ComponentProps<"div"> & {
+  variant?: VariantProps<typeof cardVariants>["variant"];
+};
+
+function Card({ className, render, variant, ...props }: CardProps) {
   const defaultProps = {
-    className: cn(
-      "relative flex flex-col rounded-2xl border bg-card not-dark:bg-clip-padding text-card-foreground shadow-xs/5 before:pointer-events-none before:absolute before:inset-0 before:rounded-[calc(var(--radius-2xl)-1px)] before:shadow-[0_1px_--theme(--color-black/4%)] dark:before:shadow-[0_-1px_--theme(--color-white/6%)]",
-      className,
-    ),
+    className: cn(cardVariants({ variant }), className),
     "data-slot": "card",
   };
 
diff --git a/apps/web/src/routes/__root.tsx b/apps/web/src/routes/__root.tsx
index 7c715dff9e95..2fddf59c56de 100644
--- a/apps/web/src/routes/__root.tsx
+++ b/apps/web/src/routes/__root.tsx
@@ -17,6 +17,7 @@ import { CommandPalette } from "../components/CommandPalette";
 import { ConfirmDialogHost } from "../components/ConfirmDialogHost";
 import { ConnectOnboardingDialog } from "../components/cloud/ConnectOnboardingDialog";
 import { RelayClientInstallDialog } from "../components/cloud/RelayClientInstallDialog";
+import { ReferralClaimCoordinator } from "../components/cloud/ReferralClaimCoordinator";
 import { SshPasswordPromptDialog } from "../components/desktop/SshPasswordPromptDialog";
 import { ProviderUpdateLaunchNotification } from "../components/ProviderUpdateLaunchNotification";
 import { SlowRpcRequestToastCoordinator } from "../components/SlowRpcRequestToastCoordinator";
@@ -111,14 +112,8 @@ function RootRouteView() {
     );
   }
 
-  if (authGateState.status !== "authenticated" && authGateState.status !== "hosted-static") {
-    return (
-      <>
-        <DocumentTitleSync />
-        <Outlet />
-      </>
-    );
-  }
+  const hasAppShell =
+    authGateState.status === "authenticated" || authGateState.status === "hosted-static";
 
   const appShell = (
     <CommandPalette>
@@ -128,27 +123,39 @@ function RootRouteView() {
     </CommandPalette>
   );
 
+  const routeContent = hasAppShell ? (
+    <>
+      <DocumentTitleSync />
+      <ContrastAppearanceSync />
+      <GlassAppearanceSync />
+      <FontAppearanceSync />
+      {primaryEnvironmentAuthenticated ? <AuthenticatedTracingBootstrap /> : null}
+      <RelayClientInstallDialog />
+      <ConnectOnboardingDialog />
+      <SshPasswordPromptDialog />
+      <ConfirmDialogHost />
+      <SlowRpcRequestToastCoordinator />
+      <HostedStaticEnvironmentBootstrap />
+      {primaryEnvironmentAuthenticated ? <EventRouter /> : null}
+      {primaryEnvironmentAuthenticated ? <PlanAgentSelectionHeal /> : null}
+      {primaryEnvironmentAuthenticated ? <ProviderUpdateLaunchNotification /> : null}
+      {appShell}
+      {/* Above the router: a theme draft is judged by walking the app, so the
+          editor has to survive navigation away from settings. */}
+      <ThemeEditorHost />
+    </>
+  ) : (
+    <>
+      <DocumentTitleSync />
+      <Outlet />
+    </>
+  );
+
   return (
     <ToastProvider>
       <AnchoredToastProvider>
-        <DocumentTitleSync />
-        <ContrastAppearanceSync />
-        <GlassAppearanceSync />
-        <FontAppearanceSync />
-        {primaryEnvironmentAuthenticated ? <AuthenticatedTracingBootstrap /> : null}
-        <RelayClientInstallDialog />
-        <ConnectOnboardingDialog />
-        <SshPasswordPromptDialog />
-        <ConfirmDialogHost />
-        <SlowRpcRequestToastCoordinator />
-        <HostedStaticEnvironmentBootstrap />
-        {primaryEnvironmentAuthenticated ? <EventRouter /> : null}
-        {primaryEnvironmentAuthenticated ? <PlanAgentSelectionHeal /> : null}
-        {primaryEnvironmentAuthenticated ? <ProviderUpdateLaunchNotification /> : null}
-        {appShell}
-        {/* Above the router: a theme draft is judged by walking the app, so the
-            editor has to survive navigation away from settings. */}
-        <ThemeEditorHost />
+        <ReferralClaimCoordinator />
+        {routeContent}
       </AnchoredToastProvider>
     </ToastProvider>
   );
diff --git a/docs/README.md b/docs/README.md
index 622d81064387..572af89fe856 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -7,6 +7,7 @@
 - [Keyboard shortcuts](./user/keybindings.md)
 - [Organizing threads](./user/thread-sidebar.md)
 - [Review usage](./user/usage.md)
+- [Referral points](./user/referrals.md)
 - [Customize a project icon](./user/project-settings.md)
 - [Mobile appearance](./user/mobile-appearance.md)
 - [Remote access](./user/remote-access.md)
diff --git a/docs/internals/t3-connect.md b/docs/internals/t3-connect.md
index 6f796123e98b..0139b07b080a 100644
--- a/docs/internals/t3-connect.md
+++ b/docs/internals/t3-connect.md
@@ -255,6 +255,26 @@ Desktop renders the same web bundle, so it has them too. The waitlist enrollment
 private beta was removed when Connect went GA; sign-up is open unless a Clerk restriction below is
 enabled.
 
+## Referral Points
+
+Referral points are account state owned by the hosted relay. `relay_referral_accounts` maps each
+Clerk user ID to one random referral code and records an optional referrer. The append-only
+`relay_referral_point_entries` table is the balance ledger; summaries derive the balance by summing
+the ledger instead of trusting a mutable counter.
+
+A signed-in user can claim one code only before their account has an environment link. The claim is
+pending until `linkEnvironment` succeeds for that account. The link handler then qualifies the
+referral and appends one 67-point ledger entry for the referrer. The ledger stores the account's
+first historical environment ID. Unique indexes make retries idempotent and allow a physical
+environment to qualify only one referral award, even if it is linked to multiple accounts.
+Claims lock both participating accounts and reject any edge that would create a referral-chain
+cycle. Referral summaries read the account, eligibility, balance, and referral counts in one SQL
+statement so the client never sees aggregates from mixed snapshots.
+
+Web and desktop expose referrals in the Clerk account menu. A hosted `?ref=` link is captured before
+sign-in and claimed after Clerk supplies the account session. Mobile exposes the same relay-backed
+summary under Settings and shares hosted links, so every client reads the same account balance.
+
 ## Restricting Sign-ups: Known-User Allowlist
 
 For a closed deployment where all permitted users are known in advance, restrict sign-up to
diff --git a/docs/user/referrals.md b/docs/user/referrals.md
new file mode 100644
index 000000000000..c8a8e7c14286
--- /dev/null
+++ b/docs/user/referrals.md
@@ -0,0 +1,22 @@
+# Referral points
+
+T3 Code referral points belong to your T3 account. Sign in with the same account to see the same
+balance on web, desktop, or mobile, even when you use a different machine.
+
+Open your account menu and choose **Referrals** to find your referral link and code. On mobile, open
+**Settings → Account → Referrals**.
+
+Referral links open the hosted T3 Code app. If the recipient is signed out, T3 Code saves the code
+and opens sign-in. It claims the referral after that account signs in. The shared message states
+that the referrer receives the 67 points; it does not promise points to the recipient.
+
+You earn 67 points when someone:
+
+1. Opens your referral link or enters your code while signed in.
+2. Claims the referral before linking any T3 Code environment to their account.
+3. Links their first environment.
+
+A referral appears as pending after the code is claimed. It becomes successful and adds 67 points
+when the referred account links its first environment. A code can be claimed only once per account,
+one physical environment can qualify only one referral award, and referral chains cannot loop back
+to an account that is already in the chain.
diff --git a/infra/relay/README.md b/infra/relay/README.md
index 0085c9c5b6b7..a1a465b1ff73 100644
--- a/infra/relay/README.md
+++ b/infra/relay/README.md
@@ -20,6 +20,7 @@ The relay currently owns:
 - Provisioning and tracking managed environment endpoints.
 - Issuing short-lived credentials used to connect clients to linked environments.
 - Listing linked environments and registered mobile devices for an account.
+- Tracking account referral codes, qualification, and the referral-point ledger.
 - Registering mobile notification preferences and APNs tokens.
 - Receiving published agent activity and delivering notifications or Live Activity updates.
 - Persisting relay state and exposing relay-specific traces for diagnostics.
@@ -38,6 +39,7 @@ credential, or authorization behavior.
   provisioning, and connection flows.
 - [`src/agentActivity`](./src/agentActivity) contains mobile device registration, activity state,
   APNs delivery, and queue processing.
+- [`src/referrals`](./src/referrals) contains referral claiming, qualification, and balance logic.
 - [`src/auth`](./src/auth) contains relay token and DPoP proof handling.
 - [`src/persistence/schema.ts`](./src/persistence/schema.ts) defines persisted relay state. Keep
   schema and migration changes together.
diff --git a/infra/relay/migrations/postgres/20260827203356_referral_points/migration.sql b/infra/relay/migrations/postgres/20260827203356_referral_points/migration.sql
new file mode 100644
index 000000000000..52b801392894
--- /dev/null
+++ b/infra/relay/migrations/postgres/20260827203356_referral_points/migration.sql
@@ -0,0 +1,25 @@
+CREATE TABLE "relay_referral_accounts" (
+	"user_id" varchar(191) PRIMARY KEY,
+	"referral_code" varchar(16) NOT NULL,
+	"referrer_user_id" varchar(191),
+	"referred_at" varchar(64),
+	"qualified_at" varchar(64),
+	"created_at" varchar(64) NOT NULL,
+	"updated_at" varchar(64) NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE "relay_referral_point_entries" (
+	"id" varchar(36) PRIMARY KEY,
+	"user_id" varchar(191) NOT NULL,
+	"points" integer NOT NULL,
+	"reason" varchar(32) NOT NULL,
+	"referred_user_id" varchar(191) NOT NULL,
+	"qualifying_environment_id" varchar(191) NOT NULL,
+	"created_at" varchar(64) NOT NULL
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX "idx_relay_referral_accounts_code" ON "relay_referral_accounts" ("referral_code");--> statement-breakpoint
+CREATE INDEX "idx_relay_referral_accounts_referrer" ON "relay_referral_accounts" ("referrer_user_id","qualified_at");--> statement-breakpoint
+CREATE INDEX "idx_relay_referral_point_entries_user" ON "relay_referral_point_entries" ("user_id","created_at");--> statement-breakpoint
+CREATE UNIQUE INDEX "idx_relay_referral_point_entries_award" ON "relay_referral_point_entries" ("user_id","reason","referred_user_id");--> statement-breakpoint
+CREATE UNIQUE INDEX "idx_relay_referral_point_entries_environment_award" ON "relay_referral_point_entries" ("reason","qualifying_environment_id");
\ No newline at end of file
diff --git a/infra/relay/migrations/postgres/20260827203356_referral_points/snapshot.json b/infra/relay/migrations/postgres/20260827203356_referral_points/snapshot.json
new file mode 100644
index 000000000000..373c0c0e683a
--- /dev/null
+++ b/infra/relay/migrations/postgres/20260827203356_referral_points/snapshot.json
@@ -0,0 +1,1853 @@
+{
+  "version": "8",
+  "dialect": "postgres",
+  "id": "84e959ac-2c9c-425c-a980-e26b93b5fb24",
+  "prevIds": ["2374caff-40bf-423c-9255-55e76dddbc2a"],
+  "ddl": [
+    {
+      "isRlsEnabled": false,
+      "name": "relay_agent_activity_rows",
+      "entityType": "tables",
+      "schema": "public"
+    },
+    {
+      "isRlsEnabled": false,
+      "name": "relay_delivery_attempts",
+      "entityType": "tables",
+      "schema": "public"
+    },
+    {
+      "isRlsEnabled": false,
+      "name": "relay_dpop_proofs",
+      "entityType": "tables",
+      "schema": "public"
+    },
+    {
+      "isRlsEnabled": false,
+      "name": "relay_environment_credentials",
+      "entityType": "tables",
+      "schema": "public"
+    },
+    {
+      "isRlsEnabled": false,
+      "name": "relay_environment_links",
+      "entityType": "tables",
+      "schema": "public"
+    },
+    {
+      "isRlsEnabled": false,
+      "name": "relay_live_activities",
+      "entityType": "tables",
+      "schema": "public"
+    },
+    {
+      "isRlsEnabled": false,
+      "name": "relay_managed_endpoint_allocations",
+      "entityType": "tables",
+      "schema": "public"
+    },
+    {
+      "isRlsEnabled": false,
+      "name": "relay_managed_tunnel_limits",
+      "entityType": "tables",
+      "schema": "public"
+    },
+    {
+      "isRlsEnabled": false,
+      "name": "relay_mobile_devices",
+      "entityType": "tables",
+      "schema": "public"
+    },
+    {
+      "isRlsEnabled": false,
+      "name": "relay_referral_accounts",
+      "entityType": "tables",
+      "schema": "public"
+    },
+    {
+      "isRlsEnabled": false,
+      "name": "relay_referral_point_entries",
+      "entityType": "tables",
+      "schema": "public"
+    },
+    {
+      "type": "varchar(191)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "environment_id",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_agent_activity_rows"
+    },
+    {
+      "type": "text",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "environment_public_key",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_agent_activity_rows"
+    },
+    {
+      "type": "varchar(191)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "thread_id",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_agent_activity_rows"
+    },
+    {
+      "type": "jsonb",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "state_json",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_agent_activity_rows"
+    },
+    {
+      "type": "varchar(64)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "updated_at",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_agent_activity_rows"
+    },
+    {
+      "type": "varchar(64)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "created_at",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_agent_activity_rows"
+    },
+    {
+      "type": "varchar(36)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "id",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_delivery_attempts"
+    },
+    {
+      "type": "varchar(64)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "created_at",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_delivery_attempts"
+    },
+    {
+      "type": "varchar(255)",
+      "typeSchema": null,
+      "notNull": false,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "user_id",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_delivery_attempts"
+    },
+    {
+      "type": "varchar(191)",
+      "typeSchema": null,
+      "notNull": false,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "environment_id",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_delivery_attempts"
+    },
+    {
+      "type": "varchar(191)",
+      "typeSchema": null,
+      "notNull": false,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "thread_id",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_delivery_attempts"
+    },
+    {
+      "type": "varchar(255)",
+      "typeSchema": null,
+      "notNull": false,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "device_id",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_delivery_attempts"
+    },
+    {
+      "type": "varchar(64)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "kind",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_delivery_attempts"
+    },
+    {
+      "type": "varchar(64)",
+      "typeSchema": null,
+      "notNull": false,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "source_job_id",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_delivery_attempts"
+    },
+    {
+      "type": "varchar(16)",
+      "typeSchema": null,
+      "notNull": false,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "token_suffix",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_delivery_attempts"
+    },
+    {
+      "type": "integer",
+      "typeSchema": null,
+      "notNull": false,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "apns_status",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_delivery_attempts"
+    },
+    {
+      "type": "text",
+      "typeSchema": null,
+      "notNull": false,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "apns_reason",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_delivery_attempts"
+    },
+    {
+      "type": "varchar(128)",
+      "typeSchema": null,
+      "notNull": false,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "apns_id",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_delivery_attempts"
+    },
+    {
+      "type": "text",
+      "typeSchema": null,
+      "notNull": false,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "transport_error",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_delivery_attempts"
+    },
+    {
+      "type": "varchar(128)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "thumbprint",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_dpop_proofs"
+    },
+    {
+      "type": "varchar(255)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "jti",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_dpop_proofs"
+    },
+    {
+      "type": "integer",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "iat",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_dpop_proofs"
+    },
+    {
+      "type": "varchar(64)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "expires_at",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_dpop_proofs"
+    },
+    {
+      "type": "varchar(64)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "created_at",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_dpop_proofs"
+    },
+    {
+      "type": "varchar(64)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "credential_id",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_environment_credentials"
+    },
+    {
+      "type": "varchar(191)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "environment_id",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_environment_credentials"
+    },
+    {
+      "type": "text",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "environment_public_key",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_environment_credentials"
+    },
+    {
+      "type": "varchar(191)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "credential_hash",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_environment_credentials"
+    },
+    {
+      "type": "varchar(64)",
+      "typeSchema": null,
+      "notNull": false,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "revoked_at",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_environment_credentials"
+    },
+    {
+      "type": "varchar(64)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "created_at",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_environment_credentials"
+    },
+    {
+      "type": "varchar(64)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "updated_at",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_environment_credentials"
+    },
+    {
+      "type": "varchar(191)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "user_id",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_environment_links"
+    },
+    {
+      "type": "varchar(191)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "environment_id",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_environment_links"
+    },
+    {
+      "type": "text",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": "'T3 Environment'",
+      "generated": null,
+      "identity": null,
+      "name": "environment_label",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_environment_links"
+    },
+    {
+      "type": "text",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "environment_public_key",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_environment_links"
+    },
+    {
+      "type": "text",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "endpoint_http_base_url",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_environment_links"
+    },
+    {
+      "type": "text",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "endpoint_ws_base_url",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_environment_links"
+    },
+    {
+      "type": "varchar(32)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "endpoint_provider_kind",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_environment_links"
+    },
+    {
+      "type": "boolean",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": "true",
+      "generated": null,
+      "identity": null,
+      "name": "notifications_enabled",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_environment_links"
+    },
+    {
+      "type": "boolean",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": "true",
+      "generated": null,
+      "identity": null,
+      "name": "live_activities_enabled",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_environment_links"
+    },
+    {
+      "type": "boolean",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": "false",
+      "generated": null,
+      "identity": null,
+      "name": "managed_tunnels_enabled",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_environment_links"
+    },
+    {
+      "type": "varchar(191)",
+      "typeSchema": null,
+      "notNull": false,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "created_by_device_id",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_environment_links"
+    },
+    {
+      "type": "varchar(64)",
+      "typeSchema": null,
+      "notNull": false,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "revoked_at",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_environment_links"
+    },
+    {
+      "type": "varchar(64)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "created_at",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_environment_links"
+    },
+    {
+      "type": "varchar(64)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "updated_at",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_environment_links"
+    },
+    {
+      "type": "varchar(255)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "user_id",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_live_activities"
+    },
+    {
+      "type": "varchar(255)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "device_id",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_live_activities"
+    },
+    {
+      "type": "text",
+      "typeSchema": null,
+      "notNull": false,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "activity_push_token",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_live_activities"
+    },
+    {
+      "type": "varchar(64)",
+      "typeSchema": null,
+      "notNull": false,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "remote_start_queued_at",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_live_activities"
+    },
+    {
+      "type": "varchar(64)",
+      "typeSchema": null,
+      "notNull": false,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "remote_started_at",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_live_activities"
+    },
+    {
+      "type": "varchar(64)",
+      "typeSchema": null,
+      "notNull": false,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "ended_at",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_live_activities"
+    },
+    {
+      "type": "jsonb",
+      "typeSchema": null,
+      "notNull": false,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "last_aggregate_json",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_live_activities"
+    },
+    {
+      "type": "varchar(64)",
+      "typeSchema": null,
+      "notNull": false,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "last_live_activity_delivery_at",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_live_activities"
+    },
+    {
+      "type": "varchar(64)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "created_at",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_live_activities"
+    },
+    {
+      "type": "varchar(64)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "updated_at",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_live_activities"
+    },
+    {
+      "type": "varchar(191)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "user_id",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_managed_endpoint_allocations"
+    },
+    {
+      "type": "varchar(191)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "environment_id",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_managed_endpoint_allocations"
+    },
+    {
+      "type": "text",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "hostname",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_managed_endpoint_allocations"
+    },
+    {
+      "type": "varchar(191)",
+      "typeSchema": null,
+      "notNull": false,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "tunnel_id",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_managed_endpoint_allocations"
+    },
+    {
+      "type": "text",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "tunnel_name",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_managed_endpoint_allocations"
+    },
+    {
+      "type": "varchar(191)",
+      "typeSchema": null,
+      "notNull": false,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "dns_record_id",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_managed_endpoint_allocations"
+    },
+    {
+      "type": "varchar(64)",
+      "typeSchema": null,
+      "notNull": false,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "ready_at",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_managed_endpoint_allocations"
+    },
+    {
+      "type": "varchar(64)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "created_at",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_managed_endpoint_allocations"
+    },
+    {
+      "type": "varchar(64)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "updated_at",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_managed_endpoint_allocations"
+    },
+    {
+      "type": "varchar(191)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "user_id",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_managed_tunnel_limits"
+    },
+    {
+      "type": "integer",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "max_tunnels",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_managed_tunnel_limits"
+    },
+    {
+      "type": "varchar(64)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "created_at",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_managed_tunnel_limits"
+    },
+    {
+      "type": "varchar(64)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "updated_at",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_managed_tunnel_limits"
+    },
+    {
+      "type": "varchar(255)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "user_id",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_mobile_devices"
+    },
+    {
+      "type": "varchar(255)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "device_id",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_mobile_devices"
+    },
+    {
+      "type": "text",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": "'iOS device'",
+      "generated": null,
+      "identity": null,
+      "name": "label",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_mobile_devices"
+    },
+    {
+      "type": "varchar(16)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "platform",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_mobile_devices"
+    },
+    {
+      "type": "integer",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "ios_major_version",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_mobile_devices"
+    },
+    {
+      "type": "varchar(64)",
+      "typeSchema": null,
+      "notNull": false,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "app_version",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_mobile_devices"
+    },
+    {
+      "type": "varchar(255)",
+      "typeSchema": null,
+      "notNull": false,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "bundle_id",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_mobile_devices"
+    },
+    {
+      "type": "varchar(16)",
+      "typeSchema": null,
+      "notNull": false,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "aps_environment",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_mobile_devices"
+    },
+    {
+      "type": "text",
+      "typeSchema": null,
+      "notNull": false,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "push_token",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_mobile_devices"
+    },
+    {
+      "type": "text",
+      "typeSchema": null,
+      "notNull": false,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "push_to_start_token",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_mobile_devices"
+    },
+    {
+      "type": "jsonb",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "preferences_json",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_mobile_devices"
+    },
+    {
+      "type": "varchar(64)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "created_at",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_mobile_devices"
+    },
+    {
+      "type": "varchar(64)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "updated_at",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_mobile_devices"
+    },
+    {
+      "type": "varchar(191)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "user_id",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_referral_accounts"
+    },
+    {
+      "type": "varchar(16)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "referral_code",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_referral_accounts"
+    },
+    {
+      "type": "varchar(191)",
+      "typeSchema": null,
+      "notNull": false,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "referrer_user_id",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_referral_accounts"
+    },
+    {
+      "type": "varchar(64)",
+      "typeSchema": null,
+      "notNull": false,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "referred_at",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_referral_accounts"
+    },
+    {
+      "type": "varchar(64)",
+      "typeSchema": null,
+      "notNull": false,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "qualified_at",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_referral_accounts"
+    },
+    {
+      "type": "varchar(64)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "created_at",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_referral_accounts"
+    },
+    {
+      "type": "varchar(64)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "updated_at",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_referral_accounts"
+    },
+    {
+      "type": "varchar(36)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "id",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_referral_point_entries"
+    },
+    {
+      "type": "varchar(191)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "user_id",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_referral_point_entries"
+    },
+    {
+      "type": "integer",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "points",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_referral_point_entries"
+    },
+    {
+      "type": "varchar(32)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "reason",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_referral_point_entries"
+    },
+    {
+      "type": "varchar(191)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "referred_user_id",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_referral_point_entries"
+    },
+    {
+      "type": "varchar(191)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "qualifying_environment_id",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_referral_point_entries"
+    },
+    {
+      "type": "varchar(64)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "created_at",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_referral_point_entries"
+    },
+    {
+      "nameExplicit": true,
+      "columns": [
+        {
+          "value": "updated_at",
+          "isExpression": false,
+          "asc": true,
+          "nullsFirst": false,
+          "opclass": null
+        }
+      ],
+      "isUnique": false,
+      "where": null,
+      "with": "",
+      "method": "btree",
+      "concurrently": false,
+      "name": "idx_relay_agent_activity_rows_updated",
+      "entityType": "indexes",
+      "schema": "public",
+      "table": "relay_agent_activity_rows"
+    },
+    {
+      "nameExplicit": true,
+      "columns": [
+        {
+          "value": "environment_id",
+          "isExpression": false,
+          "asc": true,
+          "nullsFirst": false,
+          "opclass": null
+        },
+        {
+          "value": "thread_id",
+          "isExpression": false,
+          "asc": true,
+          "nullsFirst": false,
+          "opclass": null
+        },
+        {
+          "value": "created_at",
+          "isExpression": false,
+          "asc": true,
+          "nullsFirst": false,
+          "opclass": null
+        }
+      ],
+      "isUnique": false,
+      "where": null,
+      "with": "",
+      "method": "btree",
+      "concurrently": false,
+      "name": "idx_relay_delivery_attempts_environment",
+      "entityType": "indexes",
+      "schema": "public",
+      "table": "relay_delivery_attempts"
+    },
+    {
+      "nameExplicit": true,
+      "columns": [
+        {
+          "value": "source_job_id",
+          "isExpression": false,
+          "asc": true,
+          "nullsFirst": false,
+          "opclass": null
+        }
+      ],
+      "isUnique": true,
+      "where": null,
+      "with": "",
+      "method": "btree",
+      "concurrently": false,
+      "name": "idx_relay_delivery_attempts_source_job",
+      "entityType": "indexes",
+      "schema": "public",
+      "table": "relay_delivery_attempts"
+    },
+    {
+      "nameExplicit": true,
+      "columns": [
+        {
+          "value": "expires_at",
+          "isExpression": false,
+          "asc": true,
+          "nullsFirst": false,
+          "opclass": null
+        }
+      ],
+      "isUnique": false,
+      "where": null,
+      "with": "",
+      "method": "btree",
+      "concurrently": false,
+      "name": "idx_relay_dpop_proofs_expires_at",
+      "entityType": "indexes",
+      "schema": "public",
+      "table": "relay_dpop_proofs"
+    },
+    {
+      "nameExplicit": true,
+      "columns": [
+        {
+          "value": "credential_hash",
+          "isExpression": false,
+          "asc": true,
+          "nullsFirst": false,
+          "opclass": null
+        }
+      ],
+      "isUnique": true,
+      "where": null,
+      "with": "",
+      "method": "btree",
+      "concurrently": false,
+      "name": "idx_relay_environment_credentials_hash",
+      "entityType": "indexes",
+      "schema": "public",
+      "table": "relay_environment_credentials"
+    },
+    {
+      "nameExplicit": true,
+      "columns": [
+        {
+          "value": "environment_id",
+          "isExpression": false,
+          "asc": true,
+          "nullsFirst": false,
+          "opclass": null
+        },
+        {
+          "value": "revoked_at",
+          "isExpression": false,
+          "asc": true,
+          "nullsFirst": false,
+          "opclass": null
+        }
+      ],
+      "isUnique": false,
+      "where": null,
+      "with": "",
+      "method": "btree",
+      "concurrently": false,
+      "name": "idx_relay_environment_credentials_environment",
+      "entityType": "indexes",
+      "schema": "public",
+      "table": "relay_environment_credentials"
+    },
+    {
+      "nameExplicit": true,
+      "columns": [
+        {
+          "value": "environment_id",
+          "isExpression": false,
+          "asc": true,
+          "nullsFirst": false,
+          "opclass": null
+        },
+        {
+          "value": "environment_public_key",
+          "isExpression": false,
+          "asc": true,
+          "nullsFirst": false,
+          "opclass": null
+        },
+        {
+          "value": "revoked_at",
+          "isExpression": false,
+          "asc": true,
+          "nullsFirst": false,
+          "opclass": null
+        }
+      ],
+      "isUnique": false,
+      "where": null,
+      "with": "",
+      "method": "btree",
+      "concurrently": false,
+      "name": "idx_relay_environment_credentials_environment_key",
+      "entityType": "indexes",
+      "schema": "public",
+      "table": "relay_environment_credentials"
+    },
+    {
+      "nameExplicit": true,
+      "columns": [
+        {
+          "value": "environment_id",
+          "isExpression": false,
+          "asc": true,
+          "nullsFirst": false,
+          "opclass": null
+        },
+        {
+          "value": "revoked_at",
+          "isExpression": false,
+          "asc": true,
+          "nullsFirst": false,
+          "opclass": null
+        }
+      ],
+      "isUnique": false,
+      "where": null,
+      "with": "",
+      "method": "btree",
+      "concurrently": false,
+      "name": "idx_relay_environment_links_environment",
+      "entityType": "indexes",
+      "schema": "public",
+      "table": "relay_environment_links"
+    },
+    {
+      "nameExplicit": true,
+      "columns": [
+        {
+          "value": "activity_push_token",
+          "isExpression": false,
+          "asc": true,
+          "nullsFirst": false,
+          "opclass": null
+        }
+      ],
+      "isUnique": true,
+      "where": null,
+      "with": "",
+      "method": "btree",
+      "concurrently": false,
+      "name": "idx_relay_live_activities_activity_push_token",
+      "entityType": "indexes",
+      "schema": "public",
+      "table": "relay_live_activities"
+    },
+    {
+      "nameExplicit": true,
+      "columns": [
+        {
+          "value": "hostname",
+          "isExpression": false,
+          "asc": true,
+          "nullsFirst": false,
+          "opclass": null
+        }
+      ],
+      "isUnique": true,
+      "where": null,
+      "with": "",
+      "method": "btree",
+      "concurrently": false,
+      "name": "idx_relay_managed_endpoint_allocations_hostname",
+      "entityType": "indexes",
+      "schema": "public",
+      "table": "relay_managed_endpoint_allocations"
+    },
+    {
+      "nameExplicit": true,
+      "columns": [
+        {
+          "value": "tunnel_name",
+          "isExpression": false,
+          "asc": true,
+          "nullsFirst": false,
+          "opclass": null
+        }
+      ],
+      "isUnique": true,
+      "where": null,
+      "with": "",
+      "method": "btree",
+      "concurrently": false,
+      "name": "idx_relay_managed_endpoint_allocations_tunnel_name",
+      "entityType": "indexes",
+      "schema": "public",
+      "table": "relay_managed_endpoint_allocations"
+    },
+    {
+      "nameExplicit": true,
+      "columns": [
+        {
+          "value": "push_token",
+          "isExpression": false,
+          "asc": true,
+          "nullsFirst": false,
+          "opclass": null
+        }
+      ],
+      "isUnique": true,
+      "where": null,
+      "with": "",
+      "method": "btree",
+      "concurrently": false,
+      "name": "idx_relay_mobile_devices_push_token",
+      "entityType": "indexes",
+      "schema": "public",
+      "table": "relay_mobile_devices"
+    },
+    {
+      "nameExplicit": true,
+      "columns": [
+        {
+          "value": "push_to_start_token",
+          "isExpression": false,
+          "asc": true,
+          "nullsFirst": false,
+          "opclass": null
+        }
+      ],
+      "isUnique": true,
+      "where": null,
+      "with": "",
+      "method": "btree",
+      "concurrently": false,
+      "name": "idx_relay_mobile_devices_push_to_start_token",
+      "entityType": "indexes",
+      "schema": "public",
+      "table": "relay_mobile_devices"
+    },
+    {
+      "nameExplicit": true,
+      "columns": [
+        {
+          "value": "referral_code",
+          "isExpression": false,
+          "asc": true,
+          "nullsFirst": false,
+          "opclass": null
+        }
+      ],
+      "isUnique": true,
+      "where": null,
+      "with": "",
+      "method": "btree",
+      "concurrently": false,
+      "name": "idx_relay_referral_accounts_code",
+      "entityType": "indexes",
+      "schema": "public",
+      "table": "relay_referral_accounts"
+    },
+    {
+      "nameExplicit": true,
+      "columns": [
+        {
+          "value": "referrer_user_id",
+          "isExpression": false,
+          "asc": true,
+          "nullsFirst": false,
+          "opclass": null
+        },
+        {
+          "value": "qualified_at",
+          "isExpression": false,
+          "asc": true,
+          "nullsFirst": false,
+          "opclass": null
+        }
+      ],
+      "isUnique": false,
+      "where": null,
+      "with": "",
+      "method": "btree",
+      "concurrently": false,
+      "name": "idx_relay_referral_accounts_referrer",
+      "entityType": "indexes",
+      "schema": "public",
+      "table": "relay_referral_accounts"
+    },
+    {
+      "nameExplicit": true,
+      "columns": [
+        {
+          "value": "user_id",
+          "isExpression": false,
+          "asc": true,
+          "nullsFirst": false,
+          "opclass": null
+        },
+        {
+          "value": "created_at",
+          "isExpression": false,
+          "asc": true,
+          "nullsFirst": false,
+          "opclass": null
+        }
+      ],
+      "isUnique": false,
+      "where": null,
+      "with": "",
+      "method": "btree",
+      "concurrently": false,
+      "name": "idx_relay_referral_point_entries_user",
+      "entityType": "indexes",
+      "schema": "public",
+      "table": "relay_referral_point_entries"
+    },
+    {
+      "nameExplicit": true,
+      "columns": [
+        {
+          "value": "user_id",
+          "isExpression": false,
+          "asc": true,
+          "nullsFirst": false,
+          "opclass": null
+        },
+        {
+          "value": "reason",
+          "isExpression": false,
+          "asc": true,
+          "nullsFirst": false,
+          "opclass": null
+        },
+        {
+          "value": "referred_user_id",
+          "isExpression": false,
+          "asc": true,
+          "nullsFirst": false,
+          "opclass": null
+        }
+      ],
+      "isUnique": true,
+      "where": null,
+      "with": "",
+      "method": "btree",
+      "concurrently": false,
+      "name": "idx_relay_referral_point_entries_award",
+      "entityType": "indexes",
+      "schema": "public",
+      "table": "relay_referral_point_entries"
+    },
+    {
+      "nameExplicit": true,
+      "columns": [
+        {
+          "value": "reason",
+          "isExpression": false,
+          "asc": true,
+          "nullsFirst": false,
+          "opclass": null
+        },
+        {
+          "value": "qualifying_environment_id",
+          "isExpression": false,
+          "asc": true,
+          "nullsFirst": false,
+          "opclass": null
+        }
+      ],
+      "isUnique": true,
+      "where": null,
+      "with": "",
+      "method": "btree",
+      "concurrently": false,
+      "name": "idx_relay_referral_point_entries_environment_award",
+      "entityType": "indexes",
+      "schema": "public",
+      "table": "relay_referral_point_entries"
+    },
+    {
+      "columns": ["environment_id", "environment_public_key", "thread_id"],
+      "nameExplicit": false,
+      "name": "relay_agent_activity_rows_pkey",
+      "entityType": "pks",
+      "schema": "public",
+      "table": "relay_agent_activity_rows"
+    },
+    {
+      "columns": ["thumbprint", "jti"],
+      "nameExplicit": false,
+      "name": "relay_dpop_proofs_pkey",
+      "entityType": "pks",
+      "schema": "public",
+      "table": "relay_dpop_proofs"
+    },
+    {
+      "columns": ["user_id", "environment_id"],
+      "nameExplicit": false,
+      "name": "relay_environment_links_pkey",
+      "entityType": "pks",
+      "schema": "public",
+      "table": "relay_environment_links"
+    },
+    {
+      "columns": ["user_id", "device_id"],
+      "nameExplicit": false,
+      "name": "relay_live_activities_pkey",
+      "entityType": "pks",
+      "schema": "public",
+      "table": "relay_live_activities"
+    },
+    {
+      "columns": ["user_id", "environment_id"],
+      "nameExplicit": false,
+      "name": "relay_managed_endpoint_allocations_pkey",
+      "entityType": "pks",
+      "schema": "public",
+      "table": "relay_managed_endpoint_allocations"
+    },
+    {
+      "columns": ["user_id", "device_id"],
+      "nameExplicit": false,
+      "name": "relay_mobile_devices_pkey",
+      "entityType": "pks",
+      "schema": "public",
+      "table": "relay_mobile_devices"
+    },
+    {
+      "columns": ["id"],
+      "nameExplicit": false,
+      "name": "relay_delivery_attempts_pkey",
+      "schema": "public",
+      "table": "relay_delivery_attempts",
+      "entityType": "pks"
+    },
+    {
+      "columns": ["credential_id"],
+      "nameExplicit": false,
+      "name": "relay_environment_credentials_pkey",
+      "schema": "public",
+      "table": "relay_environment_credentials",
+      "entityType": "pks"
+    },
+    {
+      "columns": ["user_id"],
+      "nameExplicit": false,
+      "name": "relay_managed_tunnel_limits_pkey",
+      "schema": "public",
+      "table": "relay_managed_tunnel_limits",
+      "entityType": "pks"
+    },
+    {
+      "columns": ["user_id"],
+      "nameExplicit": false,
+      "name": "relay_referral_accounts_pkey",
+      "schema": "public",
+      "table": "relay_referral_accounts",
+      "entityType": "pks"
+    },
+    {
+      "columns": ["id"],
+      "nameExplicit": false,
+      "name": "relay_referral_point_entries_pkey",
+      "schema": "public",
+      "table": "relay_referral_point_entries",
+      "entityType": "pks"
+    }
+  ],
+  "renames": []
+}
diff --git a/infra/relay/package.json b/infra/relay/package.json
index 4e9519671f22..320253800edb 100644
--- a/infra/relay/package.json
+++ b/infra/relay/package.json
@@ -23,6 +23,7 @@
   "devDependencies": {
     "@cloudflare/workers-types": "^4.20260601.1",
     "@effect/platform-node": "catalog:",
+    "@effect/sql-pglite": "catalog:",
     "@effect/vitest": "catalog:",
     "@types/node": "catalog:",
     "drizzle-kit": "1.0.0-rc.4",
diff --git a/infra/relay/src/http/Api.test.ts b/infra/relay/src/http/Api.test.ts
index daf756a2b7cc..daa3a708e90a 100644
--- a/infra/relay/src/http/Api.test.ts
+++ b/infra/relay/src/http/Api.test.ts
@@ -18,7 +18,9 @@ import { EnvironmentId } from "@t3tools/contracts";
 import { RelayEnvironmentAuth } from "@t3tools/contracts/relay";
 
 import {
+  REFERRAL_SUMMARY_RECOVERY_BUDGET_MS,
   RELAY_REQUEST_DEADLINE_MS,
+  loadReferralSummary,
   relayCors,
   relayDocsRedirectRoute,
   relayEnvironmentAuthLayer,
@@ -34,6 +36,7 @@ import * as RelayDb from "../db.ts";
 import * as EnvironmentCredentials from "../environments/EnvironmentCredentials.ts";
 import * as EnvironmentLinks from "../environments/EnvironmentLinks.ts";
 import * as ManagedEndpointProvider from "../environments/ManagedEndpointProvider.ts";
+import * as ReferralProgram from "../referrals/ReferralProgram.ts";
 
 vi.mock("@clerk/backend", () => ({
   createClerkClient: vi.fn(),
@@ -59,6 +62,57 @@ const relaySettings: RelayConfiguration.RelayConfiguration["Service"] = {
   managedEndpointNamespace: undefined,
 };
 
+const referralSummary = {
+  points: 67,
+  referralCode: "ABCDEF0123456789",
+  awardPoints: 67,
+  qualifiedReferrals: 1,
+  pendingReferrals: 0,
+  canClaimReferral: true,
+} as const;
+
+function referralService(
+  recoverPendingAwards: ReferralProgram.ReferralProgram["Service"]["recoverPendingAwards"],
+) {
+  return ReferralProgram.ReferralProgram.of({
+    getSummary: () => Effect.succeed(referralSummary),
+    claim: () => Effect.die("unused claim"),
+    qualify: () => Effect.die("unused qualify"),
+    recoverPendingAwards,
+  });
+}
+
+describe("relay referral summary", () => {
+  it.effect("returns the summary when pending award recovery fails", () => {
+    const failure = new ReferralProgram.ReferralProgramPersistenceError({
+      operation: "recover-referrals",
+      userId: "system",
+      cause: new Error("database unavailable"),
+    });
+    return Effect.gen(function* () {
+      expect(yield* loadReferralSummary("referrer")).toEqual(referralSummary);
+    }).pipe(
+      Effect.provideService(
+        ReferralProgram.ReferralProgram,
+        referralService(() => Effect.fail(failure)),
+      ),
+    );
+  });
+
+  it.effect("bounds pending award recovery before returning the summary", () =>
+    Effect.gen(function* () {
+      const fiber = yield* loadReferralSummary("referrer").pipe(Effect.forkChild);
+      yield* TestClock.adjust(Duration.millis(REFERRAL_SUMMARY_RECOVERY_BUDGET_MS));
+      expect(yield* Fiber.join(fiber)).toEqual(referralSummary);
+    }).pipe(
+      Effect.provideService(
+        ReferralProgram.ReferralProgram,
+        referralService(() => Effect.never),
+      ),
+    ),
+  );
+});
+
 describe("relay client authentication", () => {
   it.effect("preserves the existing Clerk session JWT path", () =>
     Effect.gen(function* () {
diff --git a/infra/relay/src/http/Api.ts b/infra/relay/src/http/Api.ts
index 50bcff665a9b..c2c1c491250b 100644
--- a/infra/relay/src/http/Api.ts
+++ b/infra/relay/src/http/Api.ts
@@ -67,6 +67,7 @@ import * as ManagedEndpointProvider from "../environments/ManagedEndpointProvide
 import * as ManagedEndpointAllocations from "../environments/ManagedEndpointAllocations.ts";
 import * as EnvironmentPublishSignatures from "../environments/EnvironmentPublishSignatures.ts";
 import * as MobileRegistrations from "../agentActivity/MobileRegistrations.ts";
+import * as ReferralProgram from "../referrals/ReferralProgram.ts";
 import { withSpanAttributes } from "../observability.ts";
 import * as RelayDb from "../db.ts";
 
@@ -165,6 +166,7 @@ export const relayDocsRedirectRoute = HttpRouter.add(
 // contains the exact child span that stalled, and the response still carries
 // the traceparent back to the client.
 export const RELAY_REQUEST_DEADLINE_MS = 9_000;
+export const REFERRAL_SUMMARY_RECOVERY_BUDGET_MS = 500;
 
 const relayRequestDeadline = <E, R>(
   httpEffect: Effect.Effect<
@@ -403,6 +405,34 @@ export const healthApi = HttpApiBuilder.group(
   }),
 );
 
+export const loadReferralSummary = Effect.fn("relay.api.client.loadReferralSummary")(function* (
+  userId: string,
+) {
+  const referrals = yield* ReferralProgram.ReferralProgram;
+  yield* referrals.recoverPendingAwards({ referrerUserId: userId }).pipe(
+    Effect.tapError((error) =>
+      Effect.logWarning("pending referral award recovery before summary failed", {
+        errorTag: error._tag,
+        operation: error.operation,
+        userId,
+      }),
+    ),
+    Effect.timeoutOption(Duration.millis(REFERRAL_SUMMARY_RECOVERY_BUDGET_MS)),
+    Effect.tap(
+      Option.match({
+        onNone: () =>
+          Effect.logWarning("pending referral award recovery before summary timed out", {
+            budgetMs: REFERRAL_SUMMARY_RECOVERY_BUDGET_MS,
+            userId,
+          }),
+        onSome: () => Effect.void,
+      }),
+    ),
+    Effect.ignore,
+  );
+  return yield* referrals.getSummary({ userId });
+});
+
 export const revokeEnvironmentLinkRecord = Effect.fn(
   "relay.api.client.revokeEnvironmentLinkRecord",
 )(function* (input: {
@@ -532,6 +562,7 @@ export const clientApi = HttpApiBuilder.group(
     const links = yield* EnvironmentLinks.EnvironmentLinks;
     const managedEndpointProvider = yield* ManagedEndpointProvider.ManagedEndpointProvider;
     const devices = yield* Devices.Devices;
+    const referrals = yield* ReferralProgram.ReferralProgram;
     return handlers
       .handle(
         "listEnvironments",
@@ -548,6 +579,20 @@ export const clientApi = HttpApiBuilder.group(
           return { devices: yield* devices.listForUser({ userId }) };
         }, mapRelayCommonApiErrors("not_authorized")),
       )
+      .handle(
+        "getReferralSummary",
+        Effect.fn("relay.api.client.getReferralSummary")(function* () {
+          const { userId } = yield* RelayClientPrincipal;
+          return yield* loadReferralSummary(userId);
+        }, mapRelayCommonApiErrors("not_authorized")),
+      )
+      .handle(
+        "claimReferral",
+        Effect.fn("relay.api.client.claimReferral")(function* ({ payload }) {
+          const { userId } = yield* RelayClientPrincipal;
+          return yield* referrals.claim({ userId, referralCode: payload.referralCode });
+        }, mapRelayCommonApiErrors("not_authorized")),
+      )
       .handle(
         "linkEnvironment",
         Effect.fn("relay.api.client.linkEnvironment")(
@@ -556,6 +601,15 @@ export const clientApi = HttpApiBuilder.group(
             yield* appendRelayCredentialResponseHeaders;
             const { userId } = yield* RelayClientPrincipal;
             const result = yield* linker.link({ userId, request: payload });
+            yield* referrals.qualify({ userId }).pipe(
+              Effect.tapError((error) =>
+                Effect.logWarning("referral qualification after environment link failed", {
+                  errorTag: error._tag,
+                  operation: error.operation,
+                }),
+              ),
+              Effect.ignore,
+            );
             return {
               ok: true,
               cloudUserId: userId,
@@ -1025,6 +1079,7 @@ const RelayCommonPersistenceError = Schema.Union([
   AgentActivityRows.AgentActivityRowListPersistenceError,
   LiveActivities.LiveActivityDeliveryMarkPersistenceError,
   DeliveryAttempts.DeliveryAttemptRecordPersistenceError,
+  ReferralProgram.ReferralProgramPersistenceError,
 ]);
 type RelayCommonPersistenceError = typeof RelayCommonPersistenceError.Type;
 const isRelayCommonPersistenceError = Schema.is(RelayCommonPersistenceError);
diff --git a/infra/relay/src/persistence/schema.ts b/infra/relay/src/persistence/schema.ts
index 61b72f2df868..8d7a4b1da11f 100644
--- a/infra/relay/src/persistence/schema.ts
+++ b/infra/relay/src/persistence/schema.ts
@@ -110,6 +110,48 @@ export const relayManagedTunnelLimits = pgTable("relay_managed_tunnel_limits", {
   updatedAt: varchar("updated_at", { length: 64 }).notNull(),
 });
 
+export const relayReferralAccounts = pgTable(
+  "relay_referral_accounts",
+  {
+    userId: varchar("user_id", { length: 191 }).primaryKey(),
+    referralCode: varchar("referral_code", { length: 16 }).notNull(),
+    referrerUserId: varchar("referrer_user_id", { length: 191 }),
+    referredAt: varchar("referred_at", { length: 64 }),
+    qualifiedAt: varchar("qualified_at", { length: 64 }),
+    createdAt: varchar("created_at", { length: 64 }).notNull(),
+    updatedAt: varchar("updated_at", { length: 64 }).notNull(),
+  },
+  (table) => [
+    uniqueIndex("idx_relay_referral_accounts_code").on(table.referralCode),
+    index("idx_relay_referral_accounts_referrer").on(table.referrerUserId, table.qualifiedAt),
+  ],
+);
+
+export const relayReferralPointEntries = pgTable(
+  "relay_referral_point_entries",
+  {
+    id: varchar("id", { length: 36 }).primaryKey(),
+    userId: varchar("user_id", { length: 191 }).notNull(),
+    points: integer("points").notNull(),
+    reason: varchar("reason", { length: 32 }).notNull().$type<"qualified_referral">(),
+    referredUserId: varchar("referred_user_id", { length: 191 }).notNull(),
+    qualifyingEnvironmentId: varchar("qualifying_environment_id", { length: 191 }).notNull(),
+    createdAt: varchar("created_at", { length: 64 }).notNull(),
+  },
+  (table) => [
+    index("idx_relay_referral_point_entries_user").on(table.userId, table.createdAt),
+    uniqueIndex("idx_relay_referral_point_entries_award").on(
+      table.userId,
+      table.reason,
+      table.referredUserId,
+    ),
+    uniqueIndex("idx_relay_referral_point_entries_environment_award").on(
+      table.reason,
+      table.qualifyingEnvironmentId,
+    ),
+  ],
+);
+
 export const relayEnvironmentCredentials = pgTable(
   "relay_environment_credentials",
   {
diff --git a/infra/relay/src/referrals/ReferralProgram.test.ts b/infra/relay/src/referrals/ReferralProgram.test.ts
new file mode 100644
index 000000000000..773b36b61d32
--- /dev/null
+++ b/infra/relay/src/referrals/ReferralProgram.test.ts
@@ -0,0 +1,283 @@
+import { PgliteClient } from "@effect/sql-pglite";
+import { describe, expect, it } from "@effect/vitest";
+import { sql } from "drizzle-orm";
+import * as PgDrizzle from "drizzle-orm/effect-pglite";
+import * as Crypto from "effect/Crypto";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+
+import * as RelayDb from "../db.ts";
+import { relayReferralAccounts, relayReferralPointEntries } from "../persistence/schema.ts";
+import * as ReferralProgram from "./ReferralProgram.ts";
+
+const TEST_SCHEMA = [
+  `create table relay_environment_links (
+    user_id varchar(191) not null,
+    environment_id varchar(191) not null,
+    created_at varchar(64) not null,
+    primary key (user_id, environment_id)
+  )`,
+  `create table relay_referral_accounts (
+    user_id varchar(191) primary key,
+    referral_code varchar(16) not null,
+    referrer_user_id varchar(191),
+    referred_at varchar(64),
+    qualified_at varchar(64),
+    created_at varchar(64) not null,
+    updated_at varchar(64) not null
+  )`,
+  `create unique index idx_relay_referral_accounts_code
+    on relay_referral_accounts (referral_code)`,
+  `create table relay_referral_point_entries (
+    id varchar(36) primary key,
+    user_id varchar(191) not null,
+    points integer not null,
+    reason varchar(32) not null,
+    referred_user_id varchar(191) not null,
+    qualifying_environment_id varchar(191) not null,
+    created_at varchar(64) not null
+  )`,
+  `create unique index idx_relay_referral_point_entries_award
+    on relay_referral_point_entries (user_id, reason, referred_user_id)`,
+  `create unique index idx_relay_referral_point_entries_environment_award
+    on relay_referral_point_entries (reason, qualifying_environment_id)`,
+] as const;
+
+function makeTestLayer() {
+  let randomByte = 0;
+  const crypto = Crypto.make({
+    randomBytes: (size) => {
+      randomByte += 1;
+      return new Uint8Array(size).fill(randomByte);
+    },
+    digest: (_algorithm, data) => Effect.succeed(data),
+  });
+  const relayDbLayer = Layer.effect(
+    RelayDb.RelayDb,
+    PgDrizzle.makeWithDefaults().pipe(
+      Effect.map((db) => db as unknown as RelayDb.RelayDb["Service"]),
+    ),
+  ).pipe(Layer.provide(PgliteClient.layer()));
+
+  return Layer.empty.pipe(
+    Layer.provideMerge(ReferralProgram.layer),
+    Layer.provideMerge(RelayDb.RelayTransactions.layer),
+    Layer.provideMerge(relayDbLayer),
+    Layer.provideMerge(Layer.succeed(Crypto.Crypto, crypto)),
+  );
+}
+
+const setupDatabase = Effect.gen(function* () {
+  const db = yield* RelayDb.RelayDb;
+  yield* Effect.forEach(TEST_SCHEMA, (statement) => db.execute(sql.raw(statement)), {
+    concurrency: 1,
+    discard: true,
+  });
+});
+
+function linkEnvironment(userId: string, environmentId: string, createdAt: string) {
+  return Effect.gen(function* () {
+    const db = yield* RelayDb.RelayDb;
+    yield* db.execute(
+      sql`insert into relay_environment_links (user_id, environment_id, created_at)
+          values (${userId}, ${environmentId}, ${createdAt})`,
+    );
+  });
+}
+
+function testEffect<A, E>(
+  effect: Effect.Effect<A, E, ReferralProgram.ReferralProgram | RelayDb.RelayDb>,
+) {
+  return Effect.gen(function* () {
+    yield* setupDatabase;
+    return yield* effect;
+  }).pipe(Effect.provide(makeTestLayer()));
+}
+
+describe("ReferralProgram with PostgreSQL", () => {
+  it.effect("uses all 64 random bits and reports historical link eligibility", () =>
+    testEffect(
+      Effect.gen(function* () {
+        const referrals = yield* ReferralProgram.ReferralProgram;
+
+        expect(yield* referrals.getSummary({ userId: "first" })).toMatchObject({
+          referralCode: "0101010101010101",
+          canClaimReferral: true,
+        });
+        expect((yield* referrals.getSummary({ userId: "second" })).referralCode).toBe(
+          "0202020202020202",
+        );
+
+        yield* linkEnvironment("linked-user", "environment-1", "2026-08-01T00:00:00.000Z");
+        expect(yield* referrals.getSummary({ userId: "linked-user" })).toMatchObject({
+          canClaimReferral: false,
+        });
+      }),
+    ),
+  );
+
+  it.effect("claims once, rejects late claims, and prevents referral-chain cycles", () =>
+    testEffect(
+      Effect.gen(function* () {
+        const referrals = yield* ReferralProgram.ReferralProgram;
+        const a = yield* referrals.getSummary({ userId: "account-a" });
+        const b = yield* referrals.getSummary({ userId: "account-b" });
+
+        const concurrentClaims = yield* Effect.all(
+          [
+            referrals.claim({ userId: "account-a", referralCode: b.referralCode }),
+            referrals.claim({ userId: "account-b", referralCode: a.referralCode }),
+          ],
+          { concurrency: "unbounded" },
+        );
+        expect(concurrentClaims.map((claim) => claim.result).sort()).toEqual([
+          "claimed",
+          "self_referral",
+        ]);
+
+        const referrer = yield* referrals.getSummary({ userId: "referrer" });
+        yield* linkEnvironment("linked-user", "environment-2", "2026-08-02T00:00:00.000Z");
+        expect(
+          (yield* referrals.claim({
+            userId: "linked-user",
+            referralCode: referrer.referralCode,
+          })).result,
+        ).toBe("ineligible");
+        expect(
+          (yield* referrals.claim({
+            userId: "referrer",
+            referralCode: referrer.referralCode,
+          })).result,
+        ).toBe("self_referral");
+        expect(
+          (yield* referrals.claim({
+            userId: "fresh-user",
+            referralCode: "FFFFFFFFFFFFFFFF",
+          })).result,
+        ).toBe("invalid_code");
+      }),
+    ),
+  );
+
+  it.effect("awards one account once under concurrent qualification", () =>
+    testEffect(
+      Effect.gen(function* () {
+        const referrals = yield* ReferralProgram.ReferralProgram;
+        const referrer = yield* referrals.getSummary({ userId: "referrer" });
+        expect(
+          (yield* referrals.claim({
+            userId: "referred",
+            referralCode: referrer.referralCode,
+          })).result,
+        ).toBe("claimed");
+        yield* linkEnvironment("referred", "environment-1", "2026-08-03T00:00:00.000Z");
+
+        const qualificationResults = yield* Effect.all(
+          [
+            referrals.qualify({ userId: "referred" }),
+            referrals.qualify({ userId: "referred" }),
+            referrals.qualify({ userId: "referred" }),
+          ],
+          { concurrency: "unbounded" },
+        );
+        expect(qualificationResults.filter(Boolean)).toHaveLength(1);
+        expect(yield* referrals.getSummary({ userId: "referrer" })).toMatchObject({
+          points: 67,
+          awardPoints: 67,
+          qualifiedReferrals: 1,
+          pendingReferrals: 0,
+        });
+      }),
+    ),
+  );
+
+  it.effect("allows only one award per physical environment across accounts", () =>
+    testEffect(
+      Effect.gen(function* () {
+        const referrals = yield* ReferralProgram.ReferralProgram;
+        const db = yield* RelayDb.RelayDb;
+        const referrer = yield* referrals.getSummary({ userId: "referrer" });
+
+        for (const userId of ["referred-a", "referred-b"] as const) {
+          expect(
+            (yield* referrals.claim({ userId, referralCode: referrer.referralCode })).result,
+          ).toBe("claimed");
+          yield* linkEnvironment(userId, "shared-environment", "2026-08-04T00:00:00.000Z");
+        }
+
+        const results = yield* Effect.all(
+          [
+            referrals.qualify({ userId: "referred-a" }),
+            referrals.qualify({ userId: "referred-b" }),
+          ],
+          { concurrency: "unbounded" },
+        );
+        expect(results.filter(Boolean)).toHaveLength(1);
+        expect(yield* referrals.getSummary({ userId: "referrer" })).toMatchObject({
+          points: 67,
+          qualifiedReferrals: 1,
+          pendingReferrals: 1,
+        });
+        const entries = yield* db.select().from(relayReferralPointEntries);
+        expect(entries).toHaveLength(1);
+        expect(entries[0]?.qualifyingEnvironmentId).toBe("shared-environment");
+      }),
+    ),
+  );
+
+  it.effect("rolls back a partial award and recovers it later", () =>
+    testEffect(
+      Effect.gen(function* () {
+        const referrals = yield* ReferralProgram.ReferralProgram;
+        const db = yield* RelayDb.RelayDb;
+        const referrer = yield* referrals.getSummary({ userId: "referrer" });
+        expect(
+          (yield* referrals.claim({
+            userId: "referred",
+            referralCode: referrer.referralCode,
+          })).result,
+        ).toBe("claimed");
+        yield* linkEnvironment("referred", "environment-1", "2026-08-05T00:00:00.000Z");
+        yield* db.execute(
+          sql.raw(`
+          create function reject_referral_qualification() returns trigger language plpgsql as $$
+          begin
+            if new.qualified_at is not null then
+              raise exception 'qualification update failed';
+            end if;
+            return new;
+          end;
+          $$
+        `),
+        );
+        yield* db.execute(
+          sql.raw(`
+          create trigger reject_referral_qualification
+          before update on relay_referral_accounts
+          for each row execute function reject_referral_qualification()
+        `),
+        );
+
+        yield* Effect.flip(referrals.qualify({ userId: "referred" }));
+        expect(yield* db.select().from(relayReferralPointEntries)).toHaveLength(0);
+        expect(
+          (yield* db
+            .select({ qualifiedAt: relayReferralAccounts.qualifiedAt })
+            .from(relayReferralAccounts)
+            .where(sql`${relayReferralAccounts.userId} = ${"referred"}`))[0]?.qualifiedAt,
+        ).toBeNull();
+
+        yield* db.execute(
+          sql.raw("drop trigger reject_referral_qualification on relay_referral_accounts"),
+        );
+        expect(yield* referrals.recoverPendingAwards({ referrerUserId: "referrer" })).toBe(1);
+        expect(yield* referrals.recoverPendingAwards()).toBe(0);
+        expect(yield* referrals.getSummary({ userId: "referrer" })).toMatchObject({
+          points: 67,
+          qualifiedReferrals: 1,
+          pendingReferrals: 0,
+        });
+      }),
+    ),
+  );
+});
diff --git a/infra/relay/src/referrals/ReferralProgram.ts b/infra/relay/src/referrals/ReferralProgram.ts
new file mode 100644
index 000000000000..f1a4ca3d16f4
--- /dev/null
+++ b/infra/relay/src/referrals/ReferralProgram.ts
@@ -0,0 +1,517 @@
+import type {
+  RelayReferralClaimResponse,
+  RelayReferralClaimResult,
+  RelayReferralSummary,
+} from "@t3tools/contracts/relay";
+import { normalizeReferralCode, REFERRAL_AWARD_POINTS } from "@t3tools/shared/referral";
+import { and, asc, eq, isNotNull, isNull, sql } from "drizzle-orm";
+import { alias } from "drizzle-orm/pg-core";
+import * as Context from "effect/Context";
+import * as Crypto from "effect/Crypto";
+import * as DateTime from "effect/DateTime";
+import * as Encoding from "effect/Encoding";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Schema from "effect/Schema";
+
+import * as RelayDb from "../db.ts";
+import {
+  relayEnvironmentLinks,
+  relayReferralAccounts,
+  relayReferralPointEntries,
+} from "../persistence/schema.ts";
+
+type ReferralAccountRecord = typeof relayReferralAccounts.$inferSelect;
+
+export class ReferralProgramPersistenceError extends Schema.TaggedErrorClass<ReferralProgramPersistenceError>()(
+  "ReferralProgramPersistenceError",
+  {
+    operation: Schema.Literals([
+      "create-account",
+      "load-account",
+      "load-summary",
+      "claim-referral",
+      "qualify-referral",
+      "recover-referrals",
+    ]),
+    userId: Schema.String,
+    cause: Schema.optionalKey(Schema.Defect()),
+  },
+) {
+  override get message(): string {
+    return `Referral program persistence failed during '${this.operation}' for user '${this.userId}'`;
+  }
+}
+
+const isReferralProgramPersistenceError = Schema.is(ReferralProgramPersistenceError);
+
+export class ReferralProgram extends Context.Service<
+  ReferralProgram,
+  {
+    readonly getSummary: (input: {
+      readonly userId: string;
+    }) => Effect.Effect<RelayReferralSummary, ReferralProgramPersistenceError>;
+    readonly claim: (input: {
+      readonly userId: string;
+      readonly referralCode: string;
+    }) => Effect.Effect<RelayReferralClaimResponse, ReferralProgramPersistenceError>;
+    readonly qualify: (input: {
+      readonly userId: string;
+    }) => Effect.Effect<boolean, ReferralProgramPersistenceError>;
+    readonly recoverPendingAwards: (input?: {
+      readonly referrerUserId?: string;
+    }) => Effect.Effect<number, ReferralProgramPersistenceError>;
+  }
+>()("t3code-relay/referrals/ReferralProgram") {}
+
+export const make = Effect.gen(function* () {
+  const crypto = yield* Crypto.Crypto;
+  const db = yield* RelayDb.RelayDb;
+  const transactions = yield* RelayDb.RelayTransactions;
+
+  const loadAccount = Effect.fn("relay.referrals.load_account")(function* (userId: string) {
+    const rows = yield* db
+      .select()
+      .from(relayReferralAccounts)
+      .where(eq(relayReferralAccounts.userId, userId))
+      .limit(1)
+      .pipe(
+        Effect.mapError(
+          (cause) =>
+            new ReferralProgramPersistenceError({
+              operation: "load-account",
+              userId,
+              cause,
+            }),
+        ),
+      );
+    return rows[0] ?? null;
+  });
+
+  const ensureAccount = Effect.fn("relay.referrals.ensure_account")(function* (
+    userId: string,
+  ): Effect.fn.Return<ReferralAccountRecord, ReferralProgramPersistenceError> {
+    const existing = yield* loadAccount(userId);
+    if (existing) return existing;
+
+    for (let attempt = 0; attempt < 5; attempt += 1) {
+      const now = DateTime.formatIso(yield* DateTime.now);
+      const referralCode = yield* crypto.randomBytes(8).pipe(
+        Effect.map((bytes) => Encoding.encodeHex(bytes).toUpperCase()),
+        Effect.mapError(
+          (cause) =>
+            new ReferralProgramPersistenceError({
+              operation: "create-account",
+              userId,
+              cause,
+            }),
+        ),
+      );
+      const inserted = yield* db
+        .insert(relayReferralAccounts)
+        .values({
+          userId,
+          referralCode,
+          referrerUserId: null,
+          referredAt: null,
+          qualifiedAt: null,
+          createdAt: now,
+          updatedAt: now,
+        })
+        .onConflictDoNothing()
+        .returning()
+        .pipe(
+          Effect.mapError(
+            (cause) =>
+              new ReferralProgramPersistenceError({
+                operation: "create-account",
+                userId,
+                cause,
+              }),
+          ),
+        );
+      if (inserted[0]) return inserted[0];
+
+      const raced = yield* loadAccount(userId);
+      if (raced) return raced;
+    }
+
+    return yield* new ReferralProgramPersistenceError({
+      operation: "create-account",
+      userId,
+    });
+  });
+
+  const getSummary = Effect.fn("relay.referrals.get_summary")(function* (input: {
+    readonly userId: string;
+  }) {
+    yield* ensureAccount(input.userId);
+    const account = alias(relayReferralAccounts, "referral_account");
+    const rows = yield* db
+      .select({
+        referralCode: account.referralCode,
+        points: sql<number>`(
+            select coalesce(sum(point_entries.points), 0)
+            from ${relayReferralPointEntries} as point_entries
+            where point_entries.user_id = ${input.userId}
+          )`.mapWith(Number),
+        qualifiedReferrals: sql<number>`(
+            select count(*)
+            from ${relayReferralAccounts} as referred_accounts
+            where referred_accounts.referrer_user_id = ${input.userId}
+              and referred_accounts.qualified_at is not null
+          )`.mapWith(Number),
+        pendingReferrals: sql<number>`(
+            select count(*)
+            from ${relayReferralAccounts} as referred_accounts
+            where referred_accounts.referrer_user_id = ${input.userId}
+              and referred_accounts.qualified_at is null
+          )`.mapWith(Number),
+        canClaimReferral: sql<boolean>`(
+          ${account.referrerUserId} is null
+          and not exists (
+            select 1 from ${relayEnvironmentLinks} as environment_links
+            where environment_links.user_id = ${input.userId}
+          )
+        )`.mapWith(Boolean),
+      })
+      .from(account)
+      .where(eq(account.userId, input.userId))
+      .limit(1)
+      .pipe(
+        Effect.mapError(
+          (cause) =>
+            new ReferralProgramPersistenceError({
+              operation: "load-summary",
+              userId: input.userId,
+              cause,
+            }),
+        ),
+      );
+    const summary = rows[0];
+    if (!summary) {
+      return yield* new ReferralProgramPersistenceError({
+        operation: "load-summary",
+        userId: input.userId,
+      });
+    }
+
+    return {
+      points: summary.points,
+      referralCode: summary.referralCode,
+      awardPoints: REFERRAL_AWARD_POINTS,
+      qualifiedReferrals: summary.qualifiedReferrals,
+      pendingReferrals: summary.pendingReferrals,
+      canClaimReferral: summary.canClaimReferral,
+    } satisfies RelayReferralSummary;
+  });
+
+  const firstEnvironmentLink = Effect.fn("relay.referrals.first_environment_link")(function* (
+    userId: string,
+    operation: "claim-referral" | "qualify-referral",
+  ) {
+    const rows = yield* db
+      .select({ environmentId: relayEnvironmentLinks.environmentId })
+      .from(relayEnvironmentLinks)
+      .where(eq(relayEnvironmentLinks.userId, userId))
+      .orderBy(asc(relayEnvironmentLinks.createdAt), asc(relayEnvironmentLinks.environmentId))
+      .limit(1)
+      .pipe(
+        Effect.mapError(
+          (cause) =>
+            new ReferralProgramPersistenceError({
+              operation,
+              userId,
+              cause,
+            }),
+        ),
+      );
+    return rows[0] ?? null;
+  });
+
+  const qualifyInCurrentTransaction = Effect.fn("relay.referrals.qualify_in_current_transaction")(
+    function* (input: { readonly userId: string }) {
+      const environmentLink = yield* firstEnvironmentLink(input.userId, "qualify-referral");
+      if (!environmentLink) return false;
+
+      const account = yield* loadAccount(input.userId);
+      if (!account?.referrerUserId || account.qualifiedAt !== null) return false;
+      const referrerUserId = account.referrerUserId;
+
+      const entryId = yield* crypto.randomUUIDv4.pipe(
+        Effect.mapError(
+          (cause) =>
+            new ReferralProgramPersistenceError({
+              operation: "qualify-referral",
+              userId: input.userId,
+              cause,
+            }),
+        ),
+      );
+      const now = DateTime.formatIso(yield* DateTime.now);
+      const inserted = yield* db
+        .insert(relayReferralPointEntries)
+        .values({
+          id: entryId,
+          userId: referrerUserId,
+          points: REFERRAL_AWARD_POINTS,
+          reason: "qualified_referral",
+          referredUserId: input.userId,
+          qualifyingEnvironmentId: environmentLink.environmentId,
+          createdAt: now,
+        })
+        .onConflictDoNothing()
+        .returning({ id: relayReferralPointEntries.id })
+        .pipe(
+          Effect.mapError(
+            (cause) =>
+              new ReferralProgramPersistenceError({
+                operation: "qualify-referral",
+                userId: input.userId,
+                cause,
+              }),
+          ),
+        );
+      if (inserted.length === 0) return false;
+
+      yield* db
+        .update(relayReferralAccounts)
+        .set({ qualifiedAt: now, updatedAt: now })
+        .where(eq(relayReferralAccounts.userId, input.userId))
+        .pipe(
+          Effect.mapError(
+            (cause) =>
+              new ReferralProgramPersistenceError({
+                operation: "qualify-referral",
+                userId: input.userId,
+                cause,
+              }),
+          ),
+        );
+      return true;
+    },
+  );
+
+  const qualify = Effect.fn("relay.referrals.qualify")(function* (input: {
+    readonly userId: string;
+  }) {
+    return yield* transactions.withTransaction(qualifyInCurrentTransaction(input)).pipe(
+      Effect.mapError((cause) =>
+        isReferralProgramPersistenceError(cause)
+          ? cause
+          : new ReferralProgramPersistenceError({
+              operation: "qualify-referral",
+              userId: input.userId,
+              cause,
+            }),
+      ),
+    );
+  });
+
+  const recoverPendingAwards = Effect.fn("relay.referrals.recover_pending_awards")(
+    function* (input?: { readonly referrerUserId?: string }) {
+      const pending = yield* db
+        .select({ userId: relayReferralAccounts.userId })
+        .from(relayReferralAccounts)
+        .where(
+          and(
+            isNotNull(relayReferralAccounts.referrerUserId),
+            isNull(relayReferralAccounts.qualifiedAt),
+            input?.referrerUserId
+              ? eq(relayReferralAccounts.referrerUserId, input.referrerUserId)
+              : undefined,
+            sql`exists (
+            select 1 from ${relayEnvironmentLinks}
+            where ${relayEnvironmentLinks.userId} = ${relayReferralAccounts.userId}
+          )`,
+          ),
+        )
+        .pipe(
+          Effect.mapError(
+            (cause) =>
+              new ReferralProgramPersistenceError({
+                operation: "recover-referrals",
+                userId: "system",
+                cause,
+              }),
+          ),
+        );
+      const recovered = yield* Effect.forEach(
+        pending,
+        ({ userId }) =>
+          qualify({ userId }).pipe(
+            Effect.tapError((error) =>
+              Effect.logWarning("pending referral award recovery failed", {
+                errorTag: error._tag,
+                operation: error.operation,
+                userId,
+              }),
+            ),
+            Effect.orElseSucceed(() => false),
+          ),
+        { concurrency: 4 },
+      );
+      return recovered.filter(Boolean).length;
+    },
+  );
+
+  const claimInCurrentTransaction = Effect.fn("relay.referrals.claim_in_current_transaction")(
+    function* (input: { readonly userId: string; readonly referrerUserId: string }) {
+      yield* db
+        .execute(
+          sql`select ${relayReferralAccounts.userId}
+            from ${relayReferralAccounts}
+            where ${relayReferralAccounts.userId} in (${input.userId}, ${input.referrerUserId})
+            order by ${relayReferralAccounts.userId}
+            for update`,
+        )
+        .pipe(
+          Effect.mapError(
+            (cause) =>
+              new ReferralProgramPersistenceError({
+                operation: "claim-referral",
+                userId: input.userId,
+                cause,
+              }),
+          ),
+        );
+
+      const current = yield* loadAccount(input.userId);
+      if (current?.referrerUserId !== null) return "already_claimed" as const;
+      if (yield* firstEnvironmentLink(input.userId, "claim-referral")) {
+        return "ineligible" as const;
+      }
+
+      const cycleRows = yield* db
+        .select({
+          createsCycle: sql<boolean>`exists (
+          with recursive referral_chain(user_id, referrer_user_id) as (
+            select referral_root.user_id, referral_root.referrer_user_id
+            from ${relayReferralAccounts} as referral_root
+            where referral_root.user_id = ${input.referrerUserId}
+            union
+            select referral_ancestor.user_id, referral_ancestor.referrer_user_id
+            from ${relayReferralAccounts} as referral_ancestor
+            inner join referral_chain
+              on referral_ancestor.user_id = referral_chain.referrer_user_id
+          )
+          select 1 from referral_chain where user_id = ${input.userId}
+        )`.mapWith(Boolean),
+        })
+        .from(relayReferralAccounts)
+        .limit(1)
+        .pipe(
+          Effect.mapError(
+            (cause) =>
+              new ReferralProgramPersistenceError({
+                operation: "claim-referral",
+                userId: input.userId,
+                cause,
+              }),
+          ),
+        );
+      if (cycleRows[0]?.createsCycle) return "self_referral" as const;
+
+      const now = DateTime.formatIso(yield* DateTime.now);
+      const claimed = yield* db
+        .update(relayReferralAccounts)
+        .set({ referrerUserId: input.referrerUserId, referredAt: now, updatedAt: now })
+        .where(
+          and(
+            eq(relayReferralAccounts.userId, input.userId),
+            isNull(relayReferralAccounts.referrerUserId),
+            sql`not exists (
+            select 1 from ${relayEnvironmentLinks}
+            where ${relayEnvironmentLinks.userId} = ${input.userId}
+          )`,
+          ),
+        )
+        .returning({ userId: relayReferralAccounts.userId })
+        .pipe(
+          Effect.mapError(
+            (cause) =>
+              new ReferralProgramPersistenceError({
+                operation: "claim-referral",
+                userId: input.userId,
+                cause,
+              }),
+          ),
+        );
+      if (claimed.length > 0) return "claimed" as const;
+
+      const raced = yield* loadAccount(input.userId);
+      return raced?.referrerUserId ? ("already_claimed" as const) : ("ineligible" as const);
+    },
+  );
+
+  const claim = Effect.fn("relay.referrals.claim")(function* (input: {
+    readonly userId: string;
+    readonly referralCode: string;
+  }) {
+    const account = yield* ensureAccount(input.userId);
+    let result: RelayReferralClaimResult;
+
+    if (account.referrerUserId !== null) {
+      result = "already_claimed";
+    } else {
+      const code = normalizeReferralCode(input.referralCode);
+      const referrerRows = yield* db
+        .select({ userId: relayReferralAccounts.userId })
+        .from(relayReferralAccounts)
+        .where(eq(relayReferralAccounts.referralCode, code ?? ""))
+        .limit(1)
+        .pipe(
+          Effect.mapError(
+            (cause) =>
+              new ReferralProgramPersistenceError({
+                operation: "claim-referral",
+                userId: input.userId,
+                cause,
+              }),
+          ),
+        );
+      const referrerUserId = referrerRows[0]?.userId;
+
+      if (!referrerUserId) {
+        result = "invalid_code";
+      } else if (referrerUserId === input.userId) {
+        result = "self_referral";
+      } else {
+        result = yield* transactions
+          .withTransaction(claimInCurrentTransaction({ userId: input.userId, referrerUserId }))
+          .pipe(
+            Effect.mapError((cause) =>
+              isReferralProgramPersistenceError(cause)
+                ? cause
+                : new ReferralProgramPersistenceError({
+                    operation: "claim-referral",
+                    userId: input.userId,
+                    cause,
+                  }),
+            ),
+          );
+      }
+    }
+
+    if (result === "claimed" || result === "already_claimed") {
+      yield* qualify({ userId: input.userId }).pipe(
+        Effect.tapError((error) =>
+          Effect.logWarning("referral qualification after claim failed", {
+            errorTag: error._tag,
+            operation: error.operation,
+          }),
+        ),
+        Effect.ignore,
+      );
+    }
+
+    return {
+      result,
+      summary: yield* getSummary({ userId: input.userId }),
+    } satisfies RelayReferralClaimResponse;
+  });
+
+  return ReferralProgram.of({ getSummary, claim, qualify, recoverPendingAwards });
+});
+
+export const layer = Layer.effect(ReferralProgram, make);
diff --git a/infra/relay/src/worker.ts b/infra/relay/src/worker.ts
index 77dfd845c5bc..cb0b028840a9 100644
--- a/infra/relay/src/worker.ts
+++ b/infra/relay/src/worker.ts
@@ -57,6 +57,7 @@ import * as EnvironmentPublishSignatures from "./environments/EnvironmentPublish
 import * as ManagedEndpointProvider from "./environments/ManagedEndpointProvider.ts";
 import * as ManagedTunnelLimits from "./environments/ManagedTunnelLimits.ts";
 import * as MobileRegistrations from "./agentActivity/MobileRegistrations.ts";
+import * as ReferralProgram from "./referrals/ReferralProgram.ts";
 
 const webcryptoLayer = Layer.succeed(
   Crypto.Crypto,
@@ -217,6 +218,7 @@ export const ApiLive = Api.make(
           EnvironmentLinks.layer,
           ManagedEndpointAllocations.layer,
           ManagedTunnelLimits.layer,
+          ReferralProgram.layer,
         ),
       ),
       Layer.provideMerge(LiveActivities.layer),
@@ -274,7 +276,12 @@ export const ApiLive = Api.make(
             ),
           ),
         ),
-        Effect.withSpan("relay.cron.prune_expired_state"),
+        Effect.andThen(
+          ReferralProgram.ReferralProgram.pipe(
+            Effect.flatMap((referrals) => referrals.recoverPendingAwards()),
+          ),
+        ),
+        Effect.withSpan("relay.cron.maintenance"),
         Effect.provide(runtimeLayer),
       ),
     );
diff --git a/packages/client-runtime/src/connection/resolver.test.ts b/packages/client-runtime/src/connection/resolver.test.ts
index d71c0f9602bf..01ee28cecf74 100644
--- a/packages/client-runtime/src/connection/resolver.test.ts
+++ b/packages/client-runtime/src/connection/resolver.test.ts
@@ -76,6 +76,8 @@ function relayClient(
     relayUrl: "https://relay.example.test",
     listEnvironments: () => unsupported("listEnvironments"),
     listDevices: () => unsupported("listDevices"),
+    getReferralSummary: () => unsupported("getReferralSummary"),
+    claimReferral: () => unsupported("claimReferral"),
     createEnvironmentLinkChallenge: () => unsupported("createEnvironmentLinkChallenge"),
     linkEnvironment: () => unsupported("linkEnvironment"),
     unlinkEnvironment: () => unsupported("unlinkEnvironment"),
diff --git a/packages/client-runtime/src/relay/discovery.test.ts b/packages/client-runtime/src/relay/discovery.test.ts
index 8cb963000bd3..94196cd6982c 100644
--- a/packages/client-runtime/src/relay/discovery.test.ts
+++ b/packages/client-runtime/src/relay/discovery.test.ts
@@ -105,6 +105,8 @@ const makeHarness = Effect.fn("RelayDiscoveryTest.makeHarness")(function* () {
         Effect.flatMap((requests) => Deferred.await(requests.get(environmentId)!)),
       ),
     listDevices: () => Effect.die("unused"),
+    getReferralSummary: () => Effect.die("unused"),
+    claimReferral: () => Effect.die("unused"),
     createEnvironmentLinkChallenge: () => Effect.die("unused"),
     linkEnvironment: () => Effect.die("unused"),
     unlinkEnvironment: () => Effect.die("unused"),
@@ -267,6 +269,8 @@ describe("RelayEnvironmentDiscovery", () => {
           ),
         getEnvironmentStatus: () => Effect.die("unused"),
         listDevices: () => Effect.die("unused"),
+        getReferralSummary: () => Effect.die("unused"),
+        claimReferral: () => Effect.die("unused"),
         createEnvironmentLinkChallenge: () => Effect.die("unused"),
         linkEnvironment: () => Effect.die("unused"),
         unlinkEnvironment: () => Effect.die("unused"),
diff --git a/packages/client-runtime/src/relay/managedRelay.ts b/packages/client-runtime/src/relay/managedRelay.ts
index 06769a4372f1..10d19dd9e328 100644
--- a/packages/client-runtime/src/relay/managedRelay.ts
+++ b/packages/client-runtime/src/relay/managedRelay.ts
@@ -22,6 +22,8 @@ import {
   RelayMobileRegistrationScope,
   type RelayOkResponse,
   type RelayPublicClientId,
+  type RelayReferralClaimResponse,
+  type RelayReferralSummary,
   RelayRegisterDeviceEndpoint,
   RelayAgentActivitySnapshotEndpoint,
   RelayRegisterLiveActivityEndpoint,
@@ -86,6 +88,8 @@ export const ManagedRelayRequestAction = Schema.Literals([
   "exchange relay DPoP access token",
   "list relay-managed environments",
   "list relay client devices",
+  "read referral points",
+  "claim referral code",
   "create relay environment link challenge",
   "link relay environment",
   "unlink relay environment",
@@ -102,6 +106,8 @@ export const ManagedRelayRequestActivity = Schema.Literals([
   "Relay DPoP access token exchange",
   "Relay environment listing",
   "Relay client device listing",
+  "Relay referral summary",
+  "Relay referral claim",
   "Relay environment link challenge",
   "Relay environment linking",
   "Relay environment unlinking",
@@ -259,6 +265,13 @@ export class ManagedRelayClient extends Context.Service<
     readonly listDevices: (input: {
       readonly clerkToken: string;
     }) => Effect.Effect<ReadonlyArray<RelayClientDeviceRecord>, ManagedRelayClientError>;
+    readonly getReferralSummary: (input: {
+      readonly clerkToken: string;
+    }) => Effect.Effect<RelayReferralSummary, ManagedRelayClientError>;
+    readonly claimReferral: (input: {
+      readonly clerkToken: string;
+      readonly referralCode: string;
+    }) => Effect.Effect<RelayReferralClaimResponse, ManagedRelayClientError>;
     readonly createEnvironmentLinkChallenge: (input: {
       readonly clerkToken: string;
       readonly payload: RelayEnvironmentLinkChallengeRequest;
@@ -407,6 +420,8 @@ function disabledManagedRelayClient(relayUrl: string): ManagedRelayClient["Servi
     relayUrl,
     listEnvironments: unavailable("clientRuntime.managedRelay.listEnvironments"),
     listDevices: unavailable("clientRuntime.managedRelay.listDevices"),
+    getReferralSummary: unavailable("clientRuntime.managedRelay.getReferralSummary"),
+    claimReferral: unavailable("clientRuntime.managedRelay.claimReferral"),
     createEnvironmentLinkChallenge: unavailable(
       "clientRuntime.managedRelay.createEnvironmentLinkChallenge",
     ),
@@ -721,6 +736,33 @@ export const make = Effect.fn("ManagedRelayClient.make")(function* (
       Effect.withSpan("clientRuntime.managedRelay.listDevices"),
       withRelayClientTracing,
     ),
+    getReferralSummary: Effect.fnUntraced(
+      function* (input) {
+        return yield* client.client
+          .getReferralSummary({ headers: bearerHeaders(input.clerkToken) })
+          .pipe(
+            Effect.mapError(relayRequestError("read referral points")),
+            timeoutRelayRequest("Relay referral summary"),
+          );
+      },
+      Effect.withSpan("clientRuntime.managedRelay.getReferralSummary"),
+      withRelayClientTracing,
+    ),
+    claimReferral: Effect.fnUntraced(
+      function* (input) {
+        return yield* client.client
+          .claimReferral({
+            headers: bearerHeaders(input.clerkToken),
+            payload: { referralCode: input.referralCode },
+          })
+          .pipe(
+            Effect.mapError(relayRequestError("claim referral code")),
+            timeoutRelayRequest("Relay referral claim"),
+          );
+      },
+      Effect.withSpan("clientRuntime.managedRelay.claimReferral"),
+      withRelayClientTracing,
+    ),
     createEnvironmentLinkChallenge: Effect.fnUntraced(
       function* (input) {
         return yield* client.client
diff --git a/packages/client-runtime/src/relay/managedRelayState.test.ts b/packages/client-runtime/src/relay/managedRelayState.test.ts
index 00ac733762fe..fca81b3bd2ad 100644
--- a/packages/client-runtime/src/relay/managedRelayState.test.ts
+++ b/packages/client-runtime/src/relay/managedRelayState.test.ts
@@ -14,6 +14,7 @@ import { afterEach, vi } from "vite-plus/test";
 
 import * as ManagedRelay from "./managedRelay.ts";
 import {
+  claimManagedRelayReferral,
   createManagedRelayQueryManager,
   createManagedRelaySession,
   deregisterManagedRelayEnvironment,
@@ -58,6 +59,15 @@ const device = {
   updatedAt: "2026-06-01T00:00:00.000Z",
 } satisfies RelayClientDeviceRecord;
 
+const referralSummary = {
+  points: 67,
+  referralCode: "ABCD1234EFAB5678",
+  awardPoints: 67,
+  qualifiedReferrals: 1,
+  pendingReferrals: 0,
+  canClaimReferral: true,
+} as const;
+
 function resetRegistry() {
   registry.dispose();
   registry = AtomRegistry.make();
@@ -68,6 +78,8 @@ function createClient(overrides?: Partial<ManagedRelay.ManagedRelayClient["Servi
     relayUrl: "https://relay.example.test",
     listEnvironments: () => Effect.succeed([environment]),
     listDevices: () => Effect.succeed([device]),
+    getReferralSummary: () => Effect.die("unused"),
+    claimReferral: () => Effect.die("unused"),
     createEnvironmentLinkChallenge: () => Effect.die("unused"),
     linkEnvironment: () => Effect.die("unused"),
     unlinkEnvironment: () => Effect.die("unused"),
@@ -146,6 +158,28 @@ describe("createManagedRelayQueryManager", () => {
     }),
   );
 
+  it.effect("claims a referral through the current account session", () =>
+    Effect.gen(function* () {
+      const claimReferral = vi.fn(() =>
+        Effect.succeed({ result: "claimed" as const, summary: referralSummary }),
+      );
+      setSession();
+
+      expect(
+        yield* claimManagedRelayReferral(registry, {
+          accountId: "account-1",
+          referralCode: referralSummary.referralCode,
+        }).pipe(
+          Effect.provideService(ManagedRelay.ManagedRelayClient, createClient({ claimReferral })),
+        ),
+      ).toEqual({ result: "claimed", summary: referralSummary });
+      expect(claimReferral).toHaveBeenCalledWith({
+        clerkToken: "clerk-token",
+        referralCode: referralSummary.referralCode,
+      });
+    }),
+  );
+
   it.effect("rejects deregistration after the account changes", () =>
     Effect.gen(function* () {
       const unlinkEnvironment = vi.fn(() => Effect.succeed({ ok: true }));
@@ -349,6 +383,19 @@ describe("createManagedRelayQueryManager", () => {
     });
   });
 
+  it("loads referral points through the current account session", async () => {
+    const getReferralSummary = vi.fn(() => Effect.succeed(referralSummary));
+    const manager = createManager({ getReferralSummary });
+    setSession();
+    const atom = manager.referralSummaryAtom("account-1");
+
+    registry.get(atom);
+    await vi.waitFor(() => {
+      expect(readManagedRelaySnapshotState(registry.get(atom)).data).toEqual(referralSummary);
+    });
+    expect(getReferralSummary).toHaveBeenCalledWith({ clerkToken: "clerk-token" });
+  });
+
   it("reports token and relay request phases for environment status queries", async () => {
     const onQueryEvent = vi.fn();
     const manager = createManager(undefined, onQueryEvent);
diff --git a/packages/client-runtime/src/relay/managedRelayState.ts b/packages/client-runtime/src/relay/managedRelayState.ts
index 1a3a22efb204..a653df808a64 100644
--- a/packages/client-runtime/src/relay/managedRelayState.ts
+++ b/packages/client-runtime/src/relay/managedRelayState.ts
@@ -47,7 +47,7 @@ export interface ManagedRelaySnapshotState<A> {
 }
 
 export interface ManagedRelayQueryEvent {
-  readonly operation: "environments" | "devices" | "environment-status";
+  readonly operation: "environments" | "devices" | "referrals" | "environment-status";
   readonly stage: "clerk-token" | "relay-request" | "validation";
   readonly phase: "start" | "success" | "failure";
   readonly accountId: string;
@@ -237,6 +237,23 @@ export const deregisterManagedRelayEnvironment = Effect.fn(
   yield* relay.unlinkEnvironment({ clerkToken, environmentId: input.environmentId });
 });
 
+export const claimManagedRelayReferral = Effect.fn(
+  "clientRuntime.managedRelaySession.claimReferral",
+)(function* (
+  registry: AtomRegistry.AtomRegistry,
+  input: { readonly accountId: string; readonly referralCode: string },
+) {
+  const session = registry.get(managedRelaySessionAtom);
+  if (!session || session.accountId !== input.accountId) {
+    return yield* new ManagedRelaySessionError({
+      message: "Sign in to T3 Connect before claiming a referral code.",
+    });
+  }
+  const clerkToken = yield* readSessionClerkToken(session);
+  const relay = yield* ManagedRelay.ManagedRelayClient;
+  return yield* relay.claimReferral({ clerkToken, referralCode: input.referralCode });
+});
+
 function requireClerkToken(
   get: Atom.AtomContext,
   accountId: string,
@@ -407,6 +424,29 @@ export function createManagedRelayQueryManager(
       ),
   );
 
+  const referralSummaryAtom = Atom.family((accountId: string) =>
+    runtime
+      .atom((get) =>
+        Effect.gen(function* () {
+          const base = { operation: "referrals" as const, accountId };
+          const clerkToken = yield* observe(
+            { ...base, stage: "clerk-token" },
+            requireClerkToken(get, accountId),
+          );
+          const relay = yield* ManagedRelay.ManagedRelayClient;
+          return yield* observe(
+            { ...base, stage: "relay-request" },
+            relay.getReferralSummary({ clerkToken }),
+          );
+        }),
+      )
+      .pipe(
+        Atom.swr({ staleTime, revalidateOnMount: true }),
+        Atom.setIdleTTL(idleTtl),
+        Atom.withLabel(`managed-relay:referrals:${accountId}`),
+      ),
+  );
+
   const environmentStatusAtom = Atom.family((key: string) => {
     const { accountId, environment } = parseStatusKey(key);
     return runtime
@@ -446,6 +486,7 @@ export function createManagedRelayQueryManager(
   return {
     environmentsAtom,
     devicesAtom,
+    referralSummaryAtom: (accountId: string) => referralSummaryAtom(accountId),
     environmentStatusAtom: (input: {
       readonly accountId: string;
       readonly environment: RelayClientEnvironmentRecord;
@@ -456,6 +497,9 @@ export function createManagedRelayQueryManager(
     refreshDevices(registry: AtomRegistry.AtomRegistry, accountId: string): void {
       registry.refresh(devicesAtom(accountId));
     },
+    refreshReferralSummary(registry: AtomRegistry.AtomRegistry, accountId: string): void {
+      registry.refresh(referralSummaryAtom(accountId));
+    },
     refreshEnvironmentStatus(
       registry: AtomRegistry.AtomRegistry,
       input: {
diff --git a/packages/contracts/src/relay.ts b/packages/contracts/src/relay.ts
index 52f7d7d43550..04adf79056c8 100644
--- a/packages/contracts/src/relay.ts
+++ b/packages/contracts/src/relay.ts
@@ -631,6 +631,38 @@ export const RelayListEnvironmentsResponse = Schema.Struct({
 });
 export type RelayListEnvironmentsResponse = typeof RelayListEnvironmentsResponse.Type;
 
+const RelayNonNegativeInt = Schema.Int.check(Schema.isGreaterThanOrEqualTo(0));
+
+export const RelayReferralSummary = Schema.Struct({
+  points: RelayNonNegativeInt,
+  referralCode: TrimmedNonEmptyString,
+  awardPoints: Schema.Int.check(Schema.isGreaterThan(0)),
+  qualifiedReferrals: RelayNonNegativeInt,
+  pendingReferrals: RelayNonNegativeInt,
+  canClaimReferral: Schema.Boolean,
+});
+export type RelayReferralSummary = typeof RelayReferralSummary.Type;
+
+export const RelayReferralClaimRequest = Schema.Struct({
+  referralCode: TrimmedNonEmptyString,
+});
+export type RelayReferralClaimRequest = typeof RelayReferralClaimRequest.Type;
+
+export const RelayReferralClaimResult = Schema.Literals([
+  "claimed",
+  "already_claimed",
+  "invalid_code",
+  "self_referral",
+  "ineligible",
+]);
+export type RelayReferralClaimResult = typeof RelayReferralClaimResult.Type;
+
+export const RelayReferralClaimResponse = Schema.Struct({
+  result: RelayReferralClaimResult,
+  summary: RelayReferralSummary,
+});
+export type RelayReferralClaimResponse = typeof RelayReferralClaimResponse.Type;
+
 export const RelayEnvironmentConnectRequest = Schema.Struct({
   deviceId: Schema.optional(
     TrimmedNonEmptyString.annotate({
@@ -958,6 +990,17 @@ export const RelayClientGroup = HttpApiGroup.make("client")
       success: RelayListDevicesResponse,
       error: RelayAuthAndInternalErrors,
     }).annotate(OpenApi.Summary, "List registered mobile devices"),
+    HttpApiEndpoint.get("getReferralSummary", "/v1/client/referrals", {
+      headers: RelayBearerRequestHeaders,
+      success: RelayReferralSummary,
+      error: RelayAuthAndInternalErrors,
+    }).annotate(OpenApi.Summary, "Read the signed-in account's referral points"),
+    HttpApiEndpoint.post("claimReferral", "/v1/client/referrals/claim", {
+      headers: RelayBearerRequestHeaders,
+      payload: RelayReferralClaimRequest,
+      success: RelayReferralClaimResponse,
+      error: RelayAuthAndInternalErrors,
+    }).annotate(OpenApi.Summary, "Claim a referral code"),
     HttpApiEndpoint.post("linkEnvironment", "/v1/client/environment-links", {
       headers: RelayBearerRequestHeaders,
       payload: RelayEnvironmentLinkRequest,
diff --git a/packages/shared/package.json b/packages/shared/package.json
index eeaa5f59e087..ee5c8b705d40 100644
--- a/packages/shared/package.json
+++ b/packages/shared/package.json
@@ -159,6 +159,10 @@
       "types": "./src/connectAuth.ts",
       "import": "./src/connectAuth.ts"
     },
+    "./referral": {
+      "types": "./src/referral.ts",
+      "import": "./src/referral.ts"
+    },
     "./path": {
       "types": "./src/path.ts",
       "import": "./src/path.ts"
diff --git a/packages/shared/src/referral.test.ts b/packages/shared/src/referral.test.ts
new file mode 100644
index 000000000000..2523a667af71
--- /dev/null
+++ b/packages/shared/src/referral.test.ts
@@ -0,0 +1,36 @@
+import { describe, expect, it } from "vite-plus/test";
+
+import {
+  buildReferralLink,
+  buildReferralShareMessage,
+  normalizeReferralCode,
+  REFERRAL_SHARE_TITLE,
+} from "./referral.js";
+
+describe("referral", () => {
+  it("normalizes referral codes shared with separators", () => {
+    expect(normalizeReferralCode(" abcd-1234-efab-5678 ")).toBe("ABCD1234EFAB5678");
+    expect(normalizeReferralCode("not-a-code")).toBeNull();
+  });
+
+  it("builds a hosted referral link", () => {
+    expect(buildReferralLink("https://app.t3.codes/somewhere", "abcd-1234-efab-5678")).toBe(
+      "https://app.t3.codes/?ref=ABCD1234EFAB5678",
+    );
+  });
+
+  it("rejects malformed referral links before they can be shared", () => {
+    expect(() => buildReferralLink("https://app.t3.codes", "not-a-code")).toThrow(
+      "valid 16-character referral code",
+    );
+  });
+
+  it("builds accurate cross-platform share copy", () => {
+    const link = "https://app.t3.codes/?ref=ABCD1234EFAB5678";
+    expect(REFERRAL_SHARE_TITLE).toBe("T3 Code referral");
+    expect(buildReferralShareMessage(link)).toBe(
+      `Try T3 Code with my referral. If you claim it before linking your first environment, I get 67 points.\n${link}`,
+    );
+    expect(buildReferralShareMessage(link, 100)).toContain("I get 100 points");
+  });
+});
diff --git a/packages/shared/src/referral.ts b/packages/shared/src/referral.ts
new file mode 100644
index 000000000000..c2ec29817856
--- /dev/null
+++ b/packages/shared/src/referral.ts
@@ -0,0 +1,26 @@
+const REFERRAL_CODE_LENGTH = 16;
+const REFERRAL_CODE_PATTERN = new RegExp(`^[A-F0-9]{${REFERRAL_CODE_LENGTH}}$`, "u");
+export const REFERRAL_SHARE_TITLE = "T3 Code referral";
+export const REFERRAL_AWARD_POINTS = 67;
+
+export function normalizeReferralCode(value: string): string | null {
+  const code = value.trim().replaceAll("-", "").toUpperCase();
+  return REFERRAL_CODE_PATTERN.test(code) ? code : null;
+}
+
+export function buildReferralLink(hostedAppUrl: string, referralCode: string): string {
+  const normalized = normalizeReferralCode(referralCode);
+  if (!normalized) {
+    throw new Error("Referral links require a valid 16-character referral code.");
+  }
+  const url = new URL("/", hostedAppUrl);
+  url.searchParams.set("ref", normalized);
+  return url.toString();
+}
+
+export function buildReferralShareMessage(
+  referralLink: string,
+  awardPoints = REFERRAL_AWARD_POINTS,
+): string {
+  return `Try T3 Code with my referral. If you claim it before linking your first environment, I get ${awardPoints} points.\n${referralLink}`;
+}
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 8986f0f8586a..7ecbd09e218f 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -64,6 +64,7 @@ overrides:
   '@effect/platform-node': 4.0.0-beta.103
   '@effect/platform-node-shared': 4.0.0-beta.103
   '@effect/sql-pg': 4.0.0-beta.103
+  '@effect/sql-pglite': 4.0.0-beta.103
   '@effect/sql-sqlite-bun': 4.0.0-beta.103
   '@effect/vitest': 4.0.0-beta.103
   '@effect/vitest>vitest': '-'
@@ -719,10 +720,10 @@ importers:
         version: link:../../packages/shared
       alchemy:
         specifier: 2.0.0-beta.65
-        version: 2.0.0-beta.65(75567d8add6e3362e26fe00f83a97bee)
+        version: 2.0.0-beta.65(04a0b03b072a2401cedb7e596732b3a5)
       drizzle-orm:
         specifier: 1.0.0-rc.4
-        version: 1.0.0-rc.4(@cloudflare/workers-types@4.20260604.1)(@effect/sql-d1@4.0.0-beta.101(effect@4.0.0-beta.103(patch_hash=af36b7948b6f9c56623074662b51dade5699880c1a7c71245de73e13c3185fb6)))(@effect/sql-pg@4.0.0-beta.103(effect@4.0.0-beta.103(patch_hash=af36b7948b6f9c56623074662b51dade5699880c1a7c71245de73e13c3185fb6)))(@effect/sql-sqlite-bun@4.0.0-beta.103(effect@4.0.0-beta.103(patch_hash=af36b7948b6f9c56623074662b51dade5699880c1a7c71245de73e13c3185fb6)))(@libsql/client@0.17.3(bufferutil@4.1.0)(utf-8-validate@6.0.6))(bun-types@1.3.14)(effect@4.0.0-beta.103(patch_hash=af36b7948b6f9c56623074662b51dade5699880c1a7c71245de73e13c3185fb6))(expo-sqlite@56.0.5(expo@56.0.12)(react-native@0.85.3(@babel/core@7.29.7)(@react-native/metro-config@0.85.3(@babel/core@7.29.7)(bufferutil@4.1.0)(utf-8-validate@6.0.6))(@types/react@19.2.16)(bufferutil@4.1.0)(react@19.2.6)(utf-8-validate@6.0.6))(react@19.2.6))(mysql2@3.22.4(@types/node@24.12.4))(pg@8.21.0)(zod@4.4.3)
+        version: 1.0.0-rc.4(1092673c7857e2d833af4a5f3ad85f01)
       effect:
         specifier: 4.0.0-beta.103
         version: 4.0.0-beta.103(patch_hash=af36b7948b6f9c56623074662b51dade5699880c1a7c71245de73e13c3185fb6)
@@ -733,6 +734,9 @@ importers:
       '@effect/platform-node':
         specifier: 4.0.0-beta.103
         version: 4.0.0-beta.103(bufferutil@4.1.0)(effect@4.0.0-beta.103(patch_hash=af36b7948b6f9c56623074662b51dade5699880c1a7c71245de73e13c3185fb6))(ioredis@5.11.0)(utf-8-validate@6.0.6)
+      '@effect/sql-pglite':
+        specifier: 4.0.0-beta.103
+        version: 4.0.0-beta.103(effect@4.0.0-beta.103(patch_hash=af36b7948b6f9c56623074662b51dade5699880c1a7c71245de73e13c3185fb6))
       '@effect/vitest':
         specifier: 4.0.0-beta.103
         version: 4.0.0-beta.103(patch_hash=a16b1e870d8c29e4a98b17cc4c638a4ff471753d8ca3487f78a22b759caf951b)(effect@4.0.0-beta.103(patch_hash=af36b7948b6f9c56623074662b51dade5699880c1a7c71245de73e13c3185fb6))
@@ -1980,6 +1984,11 @@ packages:
     peerDependencies:
       effect: 4.0.0-beta.103
 
+  '@effect/sql-pglite@4.0.0-beta.103':
+    resolution: {integrity: sha512-/a8I2rjfW6/0/Tvr70BTrRXXMLUQXbVDamhmnN97l3krWq1br+IH2ltbYn+358pJ+GJ+6UQ+eAR/P10WIs5anQ==}
+    peerDependencies:
+      effect: 4.0.0-beta.103
+
   '@effect/sql-sqlite-bun@4.0.0-beta.103':
     resolution: {integrity: sha512-u10I6SEWgUc1sKrlT0luxOBNzlUXunzxCChrD75pK5khIN1baKlPn2DD3f7bkh20NxwSzOfxF3hWsrO4VktvNg==}
     peerDependencies:
@@ -2033,6 +2042,9 @@ packages:
     resolution: {integrity: sha512-XQsZgjm2EcVUiZQf11UBJQfmZeEmOW8DpI1gsFeln6w0ae0ii4dMQEQ0kjl6DspdWX1aGY1/loyXnP0JS06e/A==}
     engines: {node: '>=0.8.0'}
 
+  '@electric-sql/pglite@0.5.8':
+    resolution: {integrity: sha512-n9tsbUOhwx2epK1V0ZG9Ar4SHWUju04dhmzZXiSBXwBoleOvIfals33NAaWgagQVAL4Rbvx/Ptsu3P+pA09f6Q==}
+
   '@electron/asar@3.4.1':
     resolution: {integrity: sha512-i4/rNPRS84t0vSRa2HorerGRXWyF4vThfHesw0dmcWHp+cspK743UanA0suA5Q5y8kzY2y6YKrvbIUn69BCAiA==}
     engines: {node: '>=10.12.0'}
@@ -6181,7 +6193,7 @@ packages:
       '@effect/sql-libsql': '>=4.0.0-beta.83 || >=4.0.0'
       '@effect/sql-mysql2': '>=4.0.0-beta.83 || >=4.0.0'
       '@effect/sql-pg': 4.0.0-beta.103
-      '@effect/sql-pglite': '>=4.0.0-beta.83 || >=4.0.0'
+      '@effect/sql-pglite': 4.0.0-beta.103
       '@effect/sql-sqlite-bun': 4.0.0-beta.103
       '@effect/sql-sqlite-do': '>=4.0.0-beta.83 || >=4.0.0'
       '@effect/sql-sqlite-node': '>=4.0.0-beta.83 || >=4.0.0'
@@ -11824,6 +11836,11 @@ snapshots:
     transitivePeerDependencies:
       - pg-native
 
+  '@effect/sql-pglite@4.0.0-beta.103(effect@4.0.0-beta.103(patch_hash=af36b7948b6f9c56623074662b51dade5699880c1a7c71245de73e13c3185fb6))':
+    dependencies:
+      '@electric-sql/pglite': 0.5.8
+      effect: 4.0.0-beta.103(patch_hash=af36b7948b6f9c56623074662b51dade5699880c1a7c71245de73e13c3185fb6)
+
   '@effect/sql-sqlite-bun@4.0.0-beta.103(effect@4.0.0-beta.103(patch_hash=af36b7948b6f9c56623074662b51dade5699880c1a7c71245de73e13c3185fb6))':
     dependencies:
       effect: 4.0.0-beta.103(patch_hash=af36b7948b6f9c56623074662b51dade5699880c1a7c71245de73e13c3185fb6)
@@ -11867,6 +11884,8 @@ snapshots:
     dependencies:
       '@types/hammerjs': 2.0.46
 
+  '@electric-sql/pglite@0.5.8': {}
+
   '@electron/asar@3.4.1':
     dependencies:
       commander: 5.1.0
@@ -15416,7 +15435,7 @@ snapshots:
       json-schema-traverse: 1.0.0
       require-from-string: 2.0.2
 
-  alchemy@2.0.0-beta.65(75567d8add6e3362e26fe00f83a97bee):
+  alchemy@2.0.0-beta.65(04a0b03b072a2401cedb7e596732b3a5):
     dependencies:
       '@alchemy.run/node-utils': 0.0.5
       '@aws-sdk/credential-providers': 3.1062.0
@@ -15461,7 +15480,7 @@ snapshots:
       '@effect/platform-node': 4.0.0-beta.103(bufferutil@4.1.0)(effect@4.0.0-beta.103(patch_hash=af36b7948b6f9c56623074662b51dade5699880c1a7c71245de73e13c3185fb6))(ioredis@5.11.0)(utf-8-validate@6.0.6)
       '@effect/sql-pg': 4.0.0-beta.103(effect@4.0.0-beta.103(patch_hash=af36b7948b6f9c56623074662b51dade5699880c1a7c71245de73e13c3185fb6))
       drizzle-kit: 1.0.0-rc.4
-      drizzle-orm: 1.0.0-rc.4(@cloudflare/workers-types@4.20260604.1)(@effect/sql-d1@4.0.0-beta.101(effect@4.0.0-beta.103(patch_hash=af36b7948b6f9c56623074662b51dade5699880c1a7c71245de73e13c3185fb6)))(@effect/sql-pg@4.0.0-beta.103(effect@4.0.0-beta.103(patch_hash=af36b7948b6f9c56623074662b51dade5699880c1a7c71245de73e13c3185fb6)))(@effect/sql-sqlite-bun@4.0.0-beta.103(effect@4.0.0-beta.103(patch_hash=af36b7948b6f9c56623074662b51dade5699880c1a7c71245de73e13c3185fb6)))(@libsql/client@0.17.3(bufferutil@4.1.0)(utf-8-validate@6.0.6))(bun-types@1.3.14)(effect@4.0.0-beta.103(patch_hash=af36b7948b6f9c56623074662b51dade5699880c1a7c71245de73e13c3185fb6))(expo-sqlite@56.0.5(expo@56.0.12)(react-native@0.85.3(@babel/core@7.29.7)(@react-native/metro-config@0.85.3(@babel/core@7.29.7)(bufferutil@4.1.0)(utf-8-validate@6.0.6))(@types/react@19.2.16)(bufferutil@4.1.0)(react@19.2.6)(utf-8-validate@6.0.6))(react@19.2.6))(mysql2@3.22.4(@types/node@24.12.4))(pg@8.21.0)(zod@4.4.3)
+      drizzle-orm: 1.0.0-rc.4(1092673c7857e2d833af4a5f3ad85f01)
       vite: '@voidzero-dev/vite-plus-core@0.2.2(@types/node@24.12.4)(esbuild@0.28.1)(jiti@2.7.0)(terser@5.48.0)(typescript@6.0.3)(unrun@0.2.39)(yaml@2.9.0)'
       ws: 8.21.0(bufferutil@4.1.0)(utf-8-validate@6.0.6)
     transitivePeerDependencies:
@@ -16484,12 +16503,14 @@ snapshots:
       get-tsconfig: 4.14.0
       jiti: 2.7.0
 
-  drizzle-orm@1.0.0-rc.4(@cloudflare/workers-types@4.20260604.1)(@effect/sql-d1@4.0.0-beta.101(effect@4.0.0-beta.103(patch_hash=af36b7948b6f9c56623074662b51dade5699880c1a7c71245de73e13c3185fb6)))(@effect/sql-pg@4.0.0-beta.103(effect@4.0.0-beta.103(patch_hash=af36b7948b6f9c56623074662b51dade5699880c1a7c71245de73e13c3185fb6)))(@effect/sql-sqlite-bun@4.0.0-beta.103(effect@4.0.0-beta.103(patch_hash=af36b7948b6f9c56623074662b51dade5699880c1a7c71245de73e13c3185fb6)))(@libsql/client@0.17.3(bufferutil@4.1.0)(utf-8-validate@6.0.6))(bun-types@1.3.14)(effect@4.0.0-beta.103(patch_hash=af36b7948b6f9c56623074662b51dade5699880c1a7c71245de73e13c3185fb6))(expo-sqlite@56.0.5(expo@56.0.12)(react-native@0.85.3(@babel/core@7.29.7)(@react-native/metro-config@0.85.3(@babel/core@7.29.7)(bufferutil@4.1.0)(utf-8-validate@6.0.6))(@types/react@19.2.16)(bufferutil@4.1.0)(react@19.2.6)(utf-8-validate@6.0.6))(react@19.2.6))(mysql2@3.22.4(@types/node@24.12.4))(pg@8.21.0)(zod@4.4.3):
+  drizzle-orm@1.0.0-rc.4(1092673c7857e2d833af4a5f3ad85f01):
     optionalDependencies:
       '@cloudflare/workers-types': 4.20260604.1
       '@effect/sql-d1': 4.0.0-beta.101(effect@4.0.0-beta.103(patch_hash=af36b7948b6f9c56623074662b51dade5699880c1a7c71245de73e13c3185fb6))
       '@effect/sql-pg': 4.0.0-beta.103(effect@4.0.0-beta.103(patch_hash=af36b7948b6f9c56623074662b51dade5699880c1a7c71245de73e13c3185fb6))
+      '@effect/sql-pglite': 4.0.0-beta.103(effect@4.0.0-beta.103(patch_hash=af36b7948b6f9c56623074662b51dade5699880c1a7c71245de73e13c3185fb6))
       '@effect/sql-sqlite-bun': 4.0.0-beta.103(effect@4.0.0-beta.103(patch_hash=af36b7948b6f9c56623074662b51dade5699880c1a7c71245de73e13c3185fb6))
+      '@electric-sql/pglite': 0.5.8
       '@libsql/client': 0.17.3(bufferutil@4.1.0)(utf-8-validate@6.0.6)
       bun-types: 1.3.14
       effect: 4.0.0-beta.103(patch_hash=af36b7948b6f9c56623074662b51dade5699880c1a7c71245de73e13c3185fb6)
diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml
index 5d13e60a0476..fdab045b2b64 100644
--- a/pnpm-workspace.yaml
+++ b/pnpm-workspace.yaml
@@ -36,6 +36,7 @@ catalog:
   "@effect/platform-node": 4.0.0-beta.103
   "@effect/platform-node-shared": 4.0.0-beta.103
   "@effect/sql-pg": 4.0.0-beta.103
+  "@effect/sql-pglite": 4.0.0-beta.103
   "@effect/sql-sqlite-bun": 4.0.0-beta.103
   "@effect/tsgo": 0.13.2
   "@effect/vitest": 4.0.0-beta.103
@@ -105,6 +106,7 @@ overrides:
   "@effect/platform-node": "catalog:"
   "@effect/platform-node-shared": "catalog:"
   "@effect/sql-pg": "catalog:"
+  "@effect/sql-pglite": "catalog:"
   "@effect/sql-sqlite-bun": "catalog:"
   "@effect/vitest": "catalog:"
   "@effect/vitest>vitest": "-"