Merge pull request #705 from PR0M3TH3AN/codex/update-moderation-documentation-for-clarity

Document moderation runtime flow and fixtures

docs/moderation/README.md

@@ -18,6 +18,15 @@ bitvid is follow-centric. Your Home feed comes from people you follow (F1). Disc
 - **Replies/threads**: NIP-10 (comments).
 - **Counts**: NIP-45 (relay COUNT; optional fallbacks).
 
+## Runtime flow (blur, hide, override)
+- [`ModerationService`](../../js/services/moderationService.js) orchestrates ingest and scoring. Review the service for the trusted-report math and helper entry points.
+- [`createModerationStage`](../../js/feedEngine/stages.js) wires the service into the feed engine where moderation summaries decorate timeline items.
+- [`bitvidApp.decorateVideoModeration`](../../js/app.js) connects stage output to the UI layer alongside feature-flag plumbing.
+- [`VideoCard.refreshModerationUi`](../../js/ui/components/VideoCard.js) applies badges, blur states, and "show anyway" toggles.
+
+## Where to extend
+Thread new moderation behaviors through the same service → stage → app → UI flow above. Extending the existing layers keeps overrides, feature flags, and QA hooks consistent—avoid spinning up parallel moderation modules unless the architecture document explicitly calls for it.
+
 ## Defaults (policy)
 - Blur video thumbnails if **≥ 3** F1 friends report `nudity`.
 - Disable autoplay preview if **≥ 2** F1 friends report `nudity`.

docs/moderation/testing.md

@@ -40,6 +40,8 @@ Expected:
 * After 2 reports → autoplay blocked.
 * After 3 reports → thumbnail blurred; reason chip shown.
 
+**Exercises:** [`ModerationService.ingestReportEvent()`](../../js/services/moderationService.js) and [`ModerationService.getTrustedReportSummary()`](../../js/services/moderationService.js) wire through [`createModerationStage()`](../../js/feedEngine/stages.js) so [`bitvidApp.decorateVideoModeration()`](../../js/app.js) can hand the summary to [`VideoCard.refreshModerationUi()`](../../js/ui/components/VideoCard.js).
+
 ### B) Mute list (10000)
 
 ```json
@@ -53,6 +55,8 @@ Expected:
 
 Expected: author’s items are downranked/hidden for this viewer.
 
+**Exercises:** [`ModerationService.ingestTrustedMuteEvent()`](../../js/services/moderationService.js) updates [`ModerationService.isAuthorMutedByTrusted()`](../../js/services/moderationService.js) / [`getTrustedMutersForAuthor()`](../../js/services/moderationService.js), which [`createModerationStage()`](../../js/feedEngine/stages.js) propagates to the video item before [`VideoCard.refreshModerationUi()`](../../js/ui/components/VideoCard.js) renders the mute state.
+
 ### C) Admin blacklist (30000)
 
 ```json
@@ -67,11 +71,15 @@ Expected: author’s items are downranked/hidden for this viewer.
 
 Expected: when viewer subscribes to this list, author is hard-hidden.
 
+**Exercises:** [`accessControl`](../../js/accessControl.js) hydration feeds [`ModerationService.getAdminListSnapshot()`](../../js/services/moderationService.js) / [`getAccessControlStatus()`](../../js/services/moderationService.js), giving [`createModerationStage()`](../../js/feedEngine/stages.js) the whitelist/blacklist flags that [`bitvidApp.decorateVideoModeration()`](../../js/app.js) and [`VideoCard.refreshModerationUi()`](../../js/ui/components/VideoCard.js) respect.
+
 ### D) COUNT fallback
 
 * Use a relay that doesn’t support COUNT.
 * Verify “—” placeholders; no spinner loops; no crashes.
 
+**Exercises:** Missing COUNT data flows through [`ModerationService.setActiveEventIds()`](../../js/services/moderationService.js) → [`ModerationService.getTrustedReportSummary()`](../../js/services/moderationService.js) defaults, letting [`createModerationStage()`](../../js/feedEngine/stages.js) emit neutral moderation metadata that [`VideoCard.refreshModerationUi()`](../../js/ui/components/VideoCard.js) renders as placeholders.
+
 ## Automated checks (suggested)
 
 * `npm run test:unit` — covers `tests/moderation/trusted-report-count.test.mjs` for deduping and mute handling.