feat: clout rank-down protection and watch threshold (#122)

* docs: add UnderperformingClips to architecture directory tree

* feat(db): add clout_tier_changed_at column to users table

Tracks when a user's effective clout tier last changed, enabling
rank-down protection with a 4-day cooldown.

* feat(clout): add rank-down protection and 75% watch threshold

- Rank-ups apply immediately, rank-downs require 4-day stability
- Only clips watched by ≥75% of group members are eligible
- Remove 48h maturity timer (watch threshold replaces it)
- Add getEffectiveTier() for rank-down cooldown logic

* feat(clout): wire effective tier into API and share pacing

Pass stored tier history through getCloutScore for rank-down
protection. Update cloutTierChangedAt on actual tier changes.
Remove underperforming clips from API response.

* refactor(ui): remove underperforming clips section

With rank-down protection in place, showing clips that are
"dragging your rank down" is misleading. Remove the component
and all references from CloutTipsView and CloutChangeModal.

* docs: update clout docs for rank protection and watch threshold

- Document clout_tier_changed_at column and 4-day rank-down cooldown
- Update clout algorithm description (75% watch threshold, no 48h timer)
- Remove underperforming clips from API response docs
- Remove UnderperformingClips from architecture directory tree

Author: GraysonCAdams

docs/api.md

@@ -253,7 +253,7 @@ Response: { "ok": true }
 | POST | `/api/clout` | Acknowledge tier change modal was shown |
 
 ### GET /api/clout
-Returns the user's clout score and tier when queue pacing is enabled. Clout is computed from the engagement on the user's last 10 matured clips (48h+ old). Users with fewer than 10 matured clips default to Rising tier.
+Returns the user's clout score and tier when queue pacing is enabled. Clout is computed from the engagement on the user's last 10 eligible clips (watched by ≥75% of group). Users with fewer than 10 eligible clips default to Rising tier.
 ```
 Response: {
   "enabled": true,
@@ -266,17 +266,18 @@ Response: {
   "icon": "/icons/clout/viral.png",
   "breakdown": [{ "clipId": "...", "score": 2 }, ...],
   "nextTier": { "tier": "iconic", "tierName": "Iconic", "minScore": 1.0, "burst": 5, "queueLimit": null, "icon": "..." },
-  "underperforming": [{ "clipId": "...", "title": "...", "platform": "tiktok", "originalUrl": "...", "thumbnailPath": "..." }],
   "lastTier": "rising",
   "tierChanged": true
 }
 ```
 
 **Tiers:** Fresh (<0.4) → Rising (0.4–0.6) → Viral (0.7–0.9) → Iconic (≥1.0). Each tier adjusts cooldown multiplier, burst size, and queue depth limit.
 
-**Per-clip scoring:** 0 = no reactions/favorites from others, 1 = reaction or favorite but no comment, 2 = reaction/favorite AND comment. Self-interactions excluded.
+**Per-clip scoring:** 0 = no reactions/favorites from others, 1 = reaction or favorite but no comment, 2 = reaction/favorite AND comment. Self-interactions excluded. Only clips watched by ≥75% of other group members are eligible.
 
-**Tier change detection:** The server tracks each user's last acknowledged tier (`cloutTier`) and last modal shown time (`cloutChangeShownAt`). When the computed tier differs from the acked tier and the 3-day cooldown has elapsed, `tierChanged: true` is returned. The `lastTier` field shows what the user was previously at.
+**Rank-down protection:** Rank-ups apply immediately. Rank-downs only take effect if the user has held their current tier for ≥4 days. The `cloutTierChangedAt` column tracks when the effective tier last changed.
+
+**Tier change detection:** The server tracks each user's last effective tier (`cloutTier`) and when it changed (`cloutTierChangedAt`). When the tier actually changes (after rank-down protection), `tierChanged: true` is returned.
 
 ### POST /api/clout
 Acknowledges that the tier change modal was shown. Updates the user's stored tier and resets the cooldown timer.

docs/data-model.md

@@ -44,7 +44,8 @@ SQLite database via Drizzle ORM. All IDs are UUIDs stored as text. Timestamps ar
 | last_legacy_share_at | integer | Nullable. Unix timestamp of last legacy shortcut share. Used for upgrade banner. |
 | used_new_share_flow | integer | Boolean (0/1). Default 0. Tracks if user has adopted new web view share flow. |
 | clout_tier | text | Nullable. Last acknowledged clout tier (for tier change detection). |
-| clout_change_shown_at | integer | Nullable. Unix timestamp when tier change modal was last shown (3-day cooldown). |
+| clout_change_shown_at | integer | Nullable. Unix timestamp when tier change modal was last shown. |
+| clout_tier_changed_at | integer | Nullable. Unix timestamp when the user's effective clout tier last changed. Used for rank-down protection (4-day cooldown). |
 | removed_at | integer | Nullable. Unix timestamp when removed from group. |
 | created_at | integer | Unix timestamp |
 
@@ -252,4 +253,4 @@ users  1──∞ verification_codes
 - **Duplicate URL prevention:** A unique index on `(group_id, original_url)` prevents the same link from being shared twice within a group.
 - **Music clip trim workflow:** Music clips enter `pending_trim` status after download. The user can trim audio via the trim UI or skip trimming. If neither occurs before `trim_deadline`, the clip auto-publishes to `ready` status via the scheduler.
 - **Dismissed clips:** The `dismissed_clips` table tracks clips dismissed by users in the catch-up modal. Users can dismiss unwatched clips in bulk, then restore them later from the Skipped Clips viewer in settings.
-- **Clout (reputation):** Computed on-demand from `reactions`, `favorites`, and `comments` tables. A user's clout score is the rolling average of per-clip engagement scores (0/1/2) for their last 10 matured clips (48h+ old). Self-interactions are excluded. Tiers (Fresh/Rising/Viral/Iconic) determine queue cooldown multiplier, burst size, and queue depth limits. The `clout_enabled` flag on `groups` controls whether clout adjustments are applied. The `clout_tier` and `clout_change_shown_at` columns on `users` track server-driven tier change notifications with a 3-day cooldown.
+- **Clout (reputation):** Computed on-demand from `reactions`, `favorites`, and `comments` tables. A user's clout score is the rolling average of per-clip engagement scores (0/1/2) for their last 10 eligible clips. Only clips watched by ≥75% of other group members are eligible. Self-interactions are excluded. Tiers (Fresh/Rising/Viral/Iconic) determine queue cooldown multiplier, burst size, and queue depth limits. Rank-ups apply immediately; rank-downs require the user to have held their current tier for ≥4 days before taking effect. The `clout_enabled` flag on `groups` controls whether clout adjustments are applied. The `clout_tier` and `clout_tier_changed_at` columns on `users` track the effective tier and when it last changed.

src/lib/components/CloutChangeModal.svelte

@@ -23,20 +23,11 @@
 		icon: string;
 	}
 
-	interface Underperformer {
-		clipId: string;
-		title: string | null;
-		platform: string;
-		originalUrl: string;
-		thumbnailPath: string | null;
-	}
-
 	let visible = $state(false);
 	let change = $state<typeof $cloutChange>(null);
 	let showTips = $state(false);
 	let tipsData = $state<{
 		nextTier: NextTierInfo | null;
-		underperforming: Underperformer[];
 		breakdown: { clipId: string; score: number }[];
 		baseCooldownMinutes: number;
 	} | null>(null);
@@ -175,7 +166,6 @@
 				const data = await res.json();
 				tipsData = {
 					nextTier: data.nextTier,
-					underperforming: data.underperforming ?? [],
 					breakdown: data.breakdown ?? [],
 					baseCooldownMinutes: data.baseCooldownMinutes ?? 120
 				};
@@ -318,10 +308,8 @@
 				<CloutTipsView
 					currentTier={change.newTier}
 					nextTier={tipsData.nextTier}
-					underperforming={tipsData.underperforming}
 					breakdown={tipsData.breakdown}
 					baseCooldownMinutes={tipsData.baseCooldownMinutes}
-					ondismiss={dismiss}
 				/>
 			{/if}
 		</div>

src/lib/components/CloutTipsView.svelte

@@ -1,5 +1,4 @@
 <script lang="ts">
-	import UnderperformingClips from './UnderperformingClips.svelte';
 	import MinusCircleIcon from 'phosphor-svelte/lib/MinusCircleIcon';
 	import ThumbsUpIcon from 'phosphor-svelte/lib/ThumbsUpIcon';
 	import FireIcon from 'phosphor-svelte/lib/FireIcon';
@@ -36,13 +35,6 @@
 		selectedTier = selectedTier === tier ? null : tier;
 	}
 
-	interface Underperformer {
-		clipId: string;
-		title: string | null;
-		platform: string;
-		originalUrl: string;
-		thumbnailPath: string | null;
-	}
 	interface NextTierInfo {
 		tier: string;
 		tierName: string;
@@ -55,17 +47,13 @@
 	let {
 		currentTier,
 		nextTier,
-		underperforming,
 		breakdown,
-		baseCooldownMinutes = 120,
-		ondismiss
+		baseCooldownMinutes = 120
 	}: {
 		currentTier: string;
 		nextTier: NextTierInfo | null;
-		underperforming: Underperformer[];
 		breakdown: { clipId: string; score: number }[];
 		baseCooldownMinutes?: number;
-		ondismiss: () => void;
 	} = $props();
 
 	function formatCooldown(minutes: number): string {
@@ -191,10 +179,6 @@
 			<p class="at-top-sub">Maximum speed unlocked. Keep sharing clips the group loves.</p>
 		</div>
 	{/if}
-
-	{#if underperforming.length > 0}
-		<UnderperformingClips clips={underperforming} {ondismiss} />
-	{/if}
 </div>
 
 <style>