feat(referrals): add Kilo Pass sharing entry points

Author: jeanduplessis

.specs/impact-referrals.md

@@ -153,8 +153,9 @@ conversion, local referral rewards are authoritative and affiliate SALE reportin
    - UTT UUID: `A7138521-9724-4b8f-95f4-1db2fbae81141`
    - Advocate widget ID: `p/51699/w/referrerWidget`
 
-3. Existing unscoped Impact Advocate configuration MAY remain as KiloClaw fallback configuration only. Kilo Pass MUST
-   require explicit Kilo Pass Advocate program/widget configuration and MUST NOT fall back to KiloClaw configuration.
+3. Impact Advocate account SID, auth token, and tenant alias MAY be shared across Advocate programs. KiloClaw and Kilo
+   Pass MUST each require explicit product-scoped Advocate program ID and widget ID configuration. Products MUST NOT
+   fall back to unscoped or other-product program/widget configuration.
 
 4. Kilo Pass MUST use a different Impact Advocate program ID and widget ID than KiloClaw.
 
@@ -715,6 +716,11 @@ conversion, local referral rewards are authoritative and affiliate SALE reportin
 
 ## Changelog
 
+### 2026-05-25 -- Require product-scoped Advocate program/widget configuration
+
+Removed KiloClaw fallback to unscoped Impact Advocate program/widget configuration. KiloClaw and Kilo Pass now both
+require explicit product-scoped Advocate program ID and widget ID while sharing account SID, auth token, and tenant alias.
+
 ### 2026-05-22 -- Rename and expand to Kilo Pass
 
 Renamed `.specs/kiloclaw-referrals.md` to `.specs/impact-referrals.md`. Generalized shared Impact Advocate referral

apps/web/src/components/profile/kilo-pass/KiloPassActiveSubscriptionCard.tsx

@@ -5,7 +5,7 @@ import { useState } from 'react';
 import { useQuery } from '@tanstack/react-query';
 
 import { Alert, AlertDescription, AlertTitle } from '@/components/ui/alert';
-import { Badge } from '@/components/ui/badge';
+import { SubscriptionStatusBadge } from '@/components/subscriptions/SubscriptionStatusBadge';
 import { Button } from '@/components/ui/button';
 import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
 import { formatDollars, formatIsoDateString_UsaDateOnlyFormat } from '@/lib/utils';
@@ -14,6 +14,8 @@ import { dayjs } from '@/lib/kilo-pass/dayjs';
 import { useTRPC } from '@/lib/trpc/utils';
 import { getMonthlyPriceUsd } from '@/lib/kilo-pass/bonus';
 
+import { KiloPassReferralButton } from '@/components/referrals/KiloPassReferralButton';
+
 import { KiloPassSubscriptionSettingsModal } from './KiloPassSubscriptionSettingsModal';
 import type { KiloPassSubscription } from './kiloPassSubscription';
 import {
@@ -140,15 +142,18 @@ function HeaderRow() {
           <Coins className="h-5 w-5 text-amber-300" />
         </span>
         <span className="leading-none">
-          <span className="block text-base">Kilo Pass</span>
+          <span className="flex flex-wrap items-center gap-2">
+            <span className="block text-base">Kilo Pass</span>
+            <SubscriptionStatusBadge status={view.status.kind} />
+          </span>
           <span className="text-muted-foreground block text-sm font-normal">
             {view.header.tierLabel} • {view.header.cadenceLabel}
           </span>
         </span>
       </CardTitle>
 
-      <div className="flex items-center gap-2">
-        <Badge variant={view.status.badgeVariant}>{view.status.label}</Badge>
+      <div className="flex flex-wrap items-center justify-end gap-2">
+        <KiloPassReferralButton />
         {providerManagement.externalManagementAction ? (
           <Button asChild variant="outline" size="icon" className="h-9 w-9">
             <a

apps/web/src/components/referrals/KiloPassReferralButton.tsx

@@ -0,0 +1,19 @@
+import Link from 'next/link';
+import { Gift } from 'lucide-react';
+
+import { Button } from '@/components/ui/button';
+import { cn } from '@/lib/utils';
+
+export function KiloPassReferralButton({ className }: { className?: string }) {
+  return (
+    <Button asChild variant="outline" className={cn('h-9 gap-2 pr-2.5', className)}>
+      <Link href="/subscriptions/kilo-pass/refer">
+        <Gift className="h-4 w-4" aria-hidden="true" />
+        <span>Refer &amp; earn</span>
+        <span className="bg-brand-primary text-primary-foreground rounded-full px-1.5 py-0.5 text-[10px] leading-none font-bold tracking-wide uppercase ring-1 ring-brand-primary/30">
+          New
+        </span>
+      </Link>
+    </Button>
+  );
+}

apps/web/src/components/referrals/KiloPassReferralPageContent.test.ts

@@ -34,8 +34,10 @@ describe('KiloPassReferralPageContent', () => {
     expect(html).toContain('Earn Kilo Pass referral bonuses');
     expect(html).toContain('50% monthly Kilo Pass bonus');
     expect(html).toContain('No Kilo Pass referral rewards yet.');
-    expect(html).toContain('aria-labelledby="kilo-pass-referral-widget-heading"');
+    expect(html).toContain('aria-label="Kilo Pass referral sharing"');
     expect(html).toContain('data-testid="share-widget"');
+    expect(html).not.toContain('Share your Kilo Pass referral link');
+    expect(html).not.toContain('Use the Kilo Pass referral widget');
     expect(html).not.toContain('KiloClaw');
     expect(html).not.toContain('free month');
   });

apps/web/src/components/referrals/KiloPassReferralPageContent.tsx

@@ -6,7 +6,7 @@ import { CalendarDays, Gift, History, Info, Sparkles } from 'lucide-react';
 
 import { Alert, AlertDescription, AlertTitle } from '@/components/ui/alert';
 import { Button } from '@/components/ui/button';
-import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/components/ui/card';
+import { Card, CardContent } from '@/components/ui/card';
 import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip';
 import { formatIsoDateString_UsaDateOnlyFormat } from '@/lib/utils';
 
@@ -138,7 +138,7 @@ export function KiloPassReferralPageContent({
           <div className="space-y-2">
             <h1 className="text-3xl font-bold tracking-tight">Earn Kilo Pass referral bonuses</h1>
             <p className="max-w-3xl text-sm leading-6 text-muted-foreground">
-              Share Kilo Pass with another developer. When their first eligible monthly payment is
+              Share Kilo Pass with someone else and when their first eligible monthly payment is
               confirmed, you both earn a 50% monthly Kilo Pass bonus based on their tier.
             </p>
           </div>
@@ -149,30 +149,10 @@ export function KiloPassReferralPageContent({
       </div>
 
       <Card>
-        <CardHeader>
-          <CardTitle>How rewards apply</CardTitle>
-          <CardDescription>
-            One pending referral reward is consumed per eligible monthly base issuance. Referral
-            bonus credits replace the normal monthly bonus for that issuance, and unused bonus
-            credits expire at month end.
-          </CardDescription>
-        </CardHeader>
-      </Card>
-
-      <Card>
-        <CardHeader>
-          <CardTitle id="kilo-pass-referral-widget-heading" className="flex items-center gap-2">
-            <Sparkles className="size-4" aria-hidden="true" />
-            Share your Kilo Pass referral link
-          </CardTitle>
-          <CardDescription>
-            Use the Kilo Pass referral widget to copy your link and track Impact Advocate sharing.
-          </CardDescription>
-        </CardHeader>
-        <CardContent>
+        <CardContent className="space-y-6 p-6">
           <section
             id={SHARE_WIDGET_ANCHOR_ID}
-            aria-labelledby="kilo-pass-referral-widget-heading"
+            aria-label="Kilo Pass referral sharing"
             className="rounded-lg border border-border bg-input/30 p-4"
           >
             {shareWidget ?? (
@@ -181,100 +161,107 @@ export function KiloPassReferralPageContent({
               </div>
             )}
           </section>
+
+          {isLoading ? (
+            <div
+              className="border-t border-border pt-6 text-sm text-muted-foreground"
+              role="status"
+            >
+              Loading Kilo Pass referral rewards…
+            </div>
+          ) : errorMessage ? (
+            <div className="border-t border-border pt-6">
+              <Alert variant="destructive" role="alert">
+                <AlertTitle>Kilo Pass referral rewards are unavailable</AlertTitle>
+                <AlertDescription>{errorMessage || 'Try again in a minute.'}</AlertDescription>
+              </Alert>
+            </div>
+          ) : summary ? (
+            <KiloPassReferralSummary summary={summary} />
+          ) : null}
         </CardContent>
       </Card>
-
-      {isLoading ? (
-        <Card>
-          <CardContent className="p-6 text-sm text-muted-foreground" role="status">
-            Loading Kilo Pass referral rewards…
-          </CardContent>
-        </Card>
-      ) : errorMessage ? (
-        <Alert variant="destructive" role="alert">
-          <AlertTitle>Kilo Pass referral rewards are unavailable</AlertTitle>
-          <AlertDescription>{errorMessage || 'Try again in a minute.'}</AlertDescription>
-        </Alert>
-      ) : summary ? (
-        <KiloPassReferralSummary summary={summary} />
-      ) : null}
     </div>
   );
 }
 
 function KiloPassReferralSummary({ summary }: { summary: KiloPassReferralRewardSummary }) {
   return (
-    <Card>
-      <CardHeader>
-        <CardTitle>Reward summary</CardTitle>
-        <CardDescription>
+    <section
+      aria-labelledby="kilo-pass-referral-summary-heading"
+      className="space-y-6 border-t border-border pt-6"
+    >
+      <div className="space-y-1.5">
+        <h2 id="kilo-pass-referral-summary-heading" className="font-semibold tracking-tight">
+          Reward summary
+        </h2>
+        <p className="text-sm text-muted-foreground">
           Track pending referral bonuses and previous Kilo Pass referral reward history.
-        </CardDescription>
-      </CardHeader>
-      <CardContent className="space-y-6">
-        {summary.referrerCap.reached ? (
-          <div className="flex flex-col gap-2 rounded-lg border border-yellow-500/20 bg-yellow-500/10 p-3 text-sm sm:flex-row sm:items-center sm:justify-between">
-            <div>
-              <div className="font-medium text-yellow-400">Cap reached</div>
-              <div className="text-muted-foreground">
-                {summary.referrerCap.grantedRewards} of {summary.referrerCap.limit} referrer rewards
-                granted. Referee rewards do not count toward this cap.
-              </div>
+        </p>
+      </div>
+
+      {summary.referrerCap.reached ? (
+        <div className="flex flex-col gap-2 rounded-lg border border-yellow-500/20 bg-yellow-500/10 p-3 text-sm sm:flex-row sm:items-center sm:justify-between">
+          <div>
+            <div className="font-medium text-yellow-400">Cap reached</div>
+            <div className="text-muted-foreground">
+              {summary.referrerCap.grantedRewards} of {summary.referrerCap.limit} referrer rewards
+              granted. Referee rewards do not count toward this cap.
             </div>
           </div>
-        ) : null}
-
-        <div className="grid gap-3 md:grid-cols-3">
-          <SummaryTile label="Total rewards" value={String(summary.totals.totalRewards)} />
-          <SummaryTile
-            label="Pending rewards"
-            value={String(summary.totals.pendingRewards)}
-            info="Pending rewards wait for a future eligible monthly Kilo Pass issuance."
-            indicator={summary.totals.pendingRewards > 0 ? 'warning' : undefined}
-          />
-          <SummaryTile label="Applied rewards" value={String(summary.totals.appliedRewards)} />
-          <SummaryTile
-            label="Total bonus value"
-            value={formatUsd(summary.totals.totalRewardAmountUsd)}
-          />
-          <SummaryTile
-            label="Pending bonus value"
-            value={formatUsd(summary.totals.pendingRewardAmountUsd)}
-          />
-          <SummaryTile
-            label="Applied bonus value"
-            value={formatUsd(summary.totals.appliedRewardAmountUsd)}
-          />
         </div>
+      ) : null}
 
-        <section aria-labelledby="kilo-pass-rewards-heading" className="space-y-3">
-          <h2 id="kilo-pass-rewards-heading" className="text-sm font-semibold text-foreground">
-            Reward history
-          </h2>
-          {summary.rewards.length === 0 ? (
-            <div className="rounded-lg border border-dashed border-border p-4 text-sm text-muted-foreground">
-              No Kilo Pass referral rewards yet.{' '}
-              <a
-                href={`#${SHARE_WIDGET_ANCHOR_ID}`}
-                className="rounded-sm text-foreground underline decoration-foreground/35 underline-offset-2 hover:decoration-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
-              >
-                Share your referral link
-              </a>{' '}
-              to earn a future monthly bonus.
-            </div>
-          ) : (
-            <div className="divide-y divide-border rounded-lg border border-border">
-              {summary.rewards.map((reward, index) => (
-                <RewardRow
-                  key={`${reward.role}-${reward.status}-${reward.earnedAt}-${index}`}
-                  reward={reward}
-                />
-              ))}
-            </div>
-          )}
-        </section>
-      </CardContent>
-    </Card>
+      <div className="grid gap-3 md:grid-cols-3">
+        <SummaryTile label="Total rewards" value={String(summary.totals.totalRewards)} />
+        <SummaryTile
+          label="Pending rewards"
+          value={String(summary.totals.pendingRewards)}
+          info="Pending rewards wait for a future eligible monthly Kilo Pass issuance."
+          indicator={summary.totals.pendingRewards > 0 ? 'warning' : undefined}
+        />
+        <SummaryTile label="Applied rewards" value={String(summary.totals.appliedRewards)} />
+        <SummaryTile
+          label="Total bonus value"
+          value={formatUsd(summary.totals.totalRewardAmountUsd)}
+        />
+        <SummaryTile
+          label="Pending bonus value"
+          value={formatUsd(summary.totals.pendingRewardAmountUsd)}
+        />
+        <SummaryTile
+          label="Applied bonus value"
+          value={formatUsd(summary.totals.appliedRewardAmountUsd)}
+        />
+      </div>
+
+      <section aria-labelledby="kilo-pass-rewards-heading" className="space-y-3">
+        <h3 id="kilo-pass-rewards-heading" className="text-sm font-semibold text-foreground">
+          Reward history
+        </h3>
+        {summary.rewards.length === 0 ? (
+          <div className="rounded-lg border border-dashed border-border p-4 text-sm text-muted-foreground">
+            No Kilo Pass referral rewards yet.{' '}
+            <a
+              href={`#${SHARE_WIDGET_ANCHOR_ID}`}
+              className="rounded-sm text-foreground underline decoration-foreground/35 underline-offset-2 hover:decoration-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+            >
+              Share your referral link
+            </a>{' '}
+            to earn a future monthly bonus.
+          </div>
+        ) : (
+          <div className="divide-y divide-border rounded-lg border border-border">
+            {summary.rewards.map((reward, index) => (
+              <RewardRow
+                key={`${reward.role}-${reward.status}-${reward.earnedAt}-${index}`}
+                reward={reward}
+              />
+            ))}
+          </div>
+        )}
+      </section>
+    </section>
   );
 }
 

apps/web/src/components/subscriptions/PersonalSubscriptions.tsx

@@ -12,9 +12,12 @@ import { KiloClawGroup } from './kiloclaw/KiloClawGroup';
 import { CodingPlansGroup } from './coding-plans/CodingPlansGroup';
 import { ENABLE_CODING_PLAN_SUBSCRIPTIONS } from '@/lib/constants';
 
+const defaultExpandedSections = ENABLE_CODING_PLAN_SUBSCRIPTIONS
+  ? ['kilo-pass', 'kiloclaw', 'coding-plans']
+  : ['kilo-pass', 'kiloclaw'];
+
 export function PersonalSubscriptions() {
   const [showTerminal, setShowTerminal] = useState(false);
-  const [expandedSection, setExpandedSection] = useState('kilo-pass');
   const trpc = useTRPC();
   const kiloPassQuery = useQuery(trpc.kiloPass.getState.queryOptions());
   const kiloClawQuery = useQuery(trpc.kiloclaw.listPersonalSubscriptions.queryOptions());
@@ -41,13 +44,7 @@ export function PersonalSubscriptions() {
         ) : null
       }
     >
-      <Accordion
-        type="single"
-        collapsible
-        value={expandedSection}
-        onValueChange={setExpandedSection}
-        className="space-y-8"
-      >
+      <Accordion type="multiple" defaultValue={defaultExpandedSections} className="space-y-8">
         <KiloPassGroup showTerminal={showTerminal} accordionValue="kilo-pass" />
         <KiloClawGroup showTerminal={showTerminal} accordionValue="kiloclaw" />
         {ENABLE_CODING_PLAN_SUBSCRIPTIONS ? (

apps/web/src/components/subscriptions/kilo-pass/KiloPassDetail.tsx

@@ -1,6 +1,5 @@
 'use client';
 
-import Link from 'next/link';
 import { useCallback, useMemo, useState } from 'react';
 import { useQuery, useQueryClient } from '@tanstack/react-query';
 import { toast } from 'sonner';
@@ -22,6 +21,7 @@ import { cn } from '@/lib/utils';
 import { useRawTRPCClient, useTRPC } from '@/lib/trpc/utils';
 import { formatDollars, formatIsoDateString_UsaDateOnlyFormat } from '@/lib/utils';
 import { DetailPageHeader } from '@/components/subscriptions/DetailPageHeader';
+import { KiloPassReferralButton } from '@/components/referrals/KiloPassReferralButton';
 import { BillingHistoryTable } from '@/components/subscriptions/BillingHistoryTable';
 import { CreditHistory } from './CreditHistory';
 import {
@@ -190,6 +190,7 @@ export function KiloPassDetail() {
           backLabel="Back to subscriptions"
           title="Kilo Pass"
           status={subscriptionDisplay.status}
+          actions={isKiloPassTerminal(subscription.status) ? null : <KiloPassReferralButton />}
         />
 
         {subscriptionDisplay.detailAlert ? (
@@ -384,9 +385,6 @@ function KiloPassInlineActions({
   return (
     <>
       <div className="flex flex-wrap gap-2">
-        <Button asChild variant="outline">
-          <Link href="/subscriptions/kilo-pass/refer">View referral rewards</Link>
-        </Button>
         {providerManagement.externalManagementAction ? (
           <Button asChild variant="outline">
             <a