docs: document moderationService.js and add overview

- Added JSDoc to ModerationService class and methods.
- Added architectural overview in docs/moderationService-overview.md.
- Created task log.

Co-authored-by: PR0M3TH3AN <[email protected]>

docs/agents/task-logs/daily/2026-02-16_docs-code-investigator_completed.md

@@ -0,0 +1,21 @@
+# Agent Task Log: docs-code-investigator
+
+- **Status**: Completed
+- **Agent**: docs-code-investigator
+- **Date**: 2026-02-16
+- **Target**: `js/services/moderationService.js`
+
+## Summary
+Analyzed and documented `js/services/moderationService.js`, the core Trust & Safety module implementing the "Web of Trust" model. Added JSDoc to the class and public methods, and created a high-level overview document.
+
+## Actions
+- Analyzed `js/services/moderationService.js` (2560 lines).
+- Added JSDoc for `ModerationService` class and methods: `constructor`, `setViewerPubkey`, `subscribeToReports`, `getTrustedReportSummary`, `refreshViewerFromClient`.
+- Added file-level architectural summary.
+- Created `docs/moderationService-overview.md` with usage examples and data flow description.
+- Verified with `npm run lint` and `tests/moderation-service.test.mjs` + `tests/moderation/*.test.mjs`.
+
+## Artifacts
+- `js/services/moderationService.js` (modified)
+- `docs/moderationService-overview.md` (created)
+- `context/CONTEXT_2026-02-16_docs-code-investigator.md` (created)

docs/moderationService-overview.md

@@ -0,0 +1,99 @@
+# Moderation Service Overview
+
+**File**: `js/services/moderationService.js`
+
+## Purpose
+
+The `ModerationService` implements the decentralized Trust & Safety model for bitvid. It filters content based on a "Web of Trust" derived from the current user's social graph (NIP-02 Contact List, Kind 3) and administrative overrides.
+
+Instead of a central authority deciding what is "safe," the service aggregates reports (NIP-56) only from users the viewer follows (their "trusted contacts"). This creates a personalized moderation layer where spam and abuse are filtered by community consensus within the user's network.
+
+## Key Concepts
+
+### Web of Trust
+-   **Viewer Context**: The service tracks the currently logged-in user (`viewerPubkey`).
+-   **Trusted Contacts**: The set of pubkeys the viewer follows (from their Kind 3 event).
+-   **Trust Score**: The number of unique trusted users who have reported a specific piece of content.
+-   **Thresholds**: Actions (e.g., blurring, disabling autoplay) are triggered when the Trust Score exceeds defined limits (`AUTOPLAY_TRUST_THRESHOLD`, `BLUR_TRUST_THRESHOLD`).
+
+### NIP-56 Reports (Kind 1984)
+-   Users can report content for reasons like `nudity`, `spam`, `illegal`, etc.
+-   Reports are public events signed by the reporter.
+-   The service subscribes to reports for active content and aggregates them locally.
+-   **Crucially**: Reports from users *outside* the trusted contact list are ignored (unless whitelisted by admin).
+
+### NIP-51 Mutes (Kind 10000)
+-   Users can mute other users to hide their content entirely.
+-   The service syncs with `UserBlocks` to enforce mutes.
+-   It also supports "Trusted Mutes" where mutes from trusted contacts can influence visibility (though this feature is evolving).
+
+### Admin Overrides
+-   The service integrates with `AccessControl` to respect an instance-wide **Blacklist** (always hidden) and **Whitelist** (always trusted).
+
+## Architecture & Data Flow
+
+### 1. Initialization (Setting the Viewer)
+When a user logs in, `setViewerPubkey(pubkey)` is called:
+1.  The service fetches the user's latest Kind 3 Contact List.
+2.  It extracts all followed pubkeys into `trustedContacts`.
+3.  It merges any admin-defined "Trust Seeds" (default trusted users).
+4.  It recomputes trust scores for all currently loaded content based on the new graph.
+
+### 2. Report Aggregation
+When viewing a video, the app calls `subscribeToReports(eventId)`:
+1.  The service subscribes to Kind 1984 events referencing the video ID.
+2.  Incoming reports are ingested via `ingestReportEvent`.
+3.  `recomputeSummaryForEvent` checks if the reporter is in `trustedContacts`.
+4.  If trusted, the report increments the score for its category.
+5.  If the score crosses a threshold, the service emits a `summary` event, updating the UI (e.g., to blur the video).
+
+## Usage Example
+
+```javascript
+import moderationService from './services/moderationService.js';
+
+// 1. Initialize with the logged-in user
+await moderationService.setViewerPubkey(myPubkey);
+
+// 2. Subscribe to reports for a video
+await moderationService.subscribeToReports(videoEventId);
+
+// 3. Listen for trust score updates
+const unsubscribe = moderationService.on('summary', ({ eventId, summary }) => {
+  if (summary.totalTrusted >= 1) {
+    console.log(`Video ${eventId} is flagged by trusted users!`);
+    // UI logic: blur thumbnail, show warning
+  }
+});
+
+// 4. Submit a report (as the viewer)
+await moderationService.submitReport({
+  eventId: videoEventId,
+  type: 'nudity',
+  targetPubkey: videoAuthorPubkey,
+  content: 'Contains explicit content'
+});
+```
+
+## Public API Summary
+
+| Method | Description |
+| :--- | :--- |
+| `setViewerPubkey(pubkey)` | Sets the active user and rebuilds the trust graph from their contacts. |
+| `subscribeToReports(eventId)` | Starts listening for NIP-56 reports for the given event ID. |
+| `submitReport(params)` | Publishes a signed Kind 1984 report event to relays. |
+| `getTrustedReportSummary(eventId)` | Returns the current aggregated trust score and report types. |
+| `isPubkeyBlockedByViewer(pubkey)` | Checks if the author is blocked/muted by the viewer. |
+| `refreshViewerFromClient()` | Helper to sync the viewer with the active Nostr client state. |
+
+## Invariants
+
+-   **Trust is Subjective**: A report only counts if the *viewer* follows the reporter. Changing the viewer changes all trust scores immediately.
+-   **Admin Trumps Trust**: Blacklisted users are ignored even if followed. Whitelisted users are trusted even if not followed.
+-   **Reactive**: The service emits events (`summary`, `contacts`, `user-blocks`) to drive UI updates; it does not directly manipulate the DOM.
+
+## When to Change
+
+-   **Refactoring**: Logic for "Trusted Mutes" (NIP-51 lists from others) is complex and partially deprecated/evolved. This area may need cleanup.
+-   **Performance**: If the number of reports or contacts grows large, the in-memory aggregation (`reportEvents` map) might need optimization or worker offloading.
+-   **Protocol Updates**: Changes to NIP-56 or NIP-51 should be reflected here.