Merge pull request #2413 from PR0M3TH3AN/content-audit/fix-upload-docs-8160176985010143731

chore(agents): run content-audit-agent daily task

CONTEXT.md

@@ -1,14 +1,3 @@
-# Context
-
-**Goal:** Execute the `bitvid-const-refactor-agent` task (daily scheduler).
-**Scope:** Identify and refactor duplicated numeric constants in `js/` to use canonical named constants.
-**Focus:** Refactor `5000` (timeout) to `SHORT_TIMEOUT_MS` and `60000` (timeout) to `LONG_TIMEOUT_MS` in selected files.
-
-**Definition of Done:**
-- [ ] Identify candidate duplicates.
-- [ ] Refactor `js/ui/engagementController.js` (5000 -> SHORT_TIMEOUT_MS).
-- [ ] Refactor `js/ui/applicationBootstrap.js` (5000 -> SHORT_TIMEOUT_MS).
-- [ ] Refactor `js/webtorrent.js` (60000 -> LONG_TIMEOUT_MS).
-- [ ] Verify changes with `npm run lint` and `npm run test:unit`.
-- [ ] Update documentation (`DECISIONS.md`, `TEST_LOG.md`).
-- [ ] Update `docs/agents/AGENT_TASK_LOG.csv`.
+# Audit Goal: Validate and update upload documentation
+# Scope: content/docs/guides/upload-content.md
+# Date: 2026-02-12

DECISIONS.md

@@ -1,11 +1,3 @@
 # Decisions
 
-- **Refactor `5000` in UI controllers to `SHORT_TIMEOUT_MS`**:
-  - **Context**: Used in `setTimeout` for clearing status messages.
-  - **Decision**: Use `SHORT_TIMEOUT_MS` from `js/constants.js` which is already defined as 5000.
-  - **Rationale**: Increases consistency and makes the timeout configurable from a central location if needed.
-
-- **Refactor `60000` in `js/webtorrent.js` to `LONG_TIMEOUT_MS`**:
-  - **Context**: Used as `TIMEOUT_DURATION` for service worker operations.
-  - **Decision**: **REVERTED** to `60000`.
-  - **Rationale**: CI checks failed with timeouts. Reverting `webtorrent.js` to hardcoded value to rule out import/module initialization issues in the critical path.
+- Focusing on upload documentation as it is critical for user onboarding.

TEST_LOG.md

@@ -0,0 +1,3 @@
+# Test Log
+
+- Initialized environment.

TODO.md

@@ -1,8 +1,3 @@
-# Todo
-
-- [ ] Refactor `js/ui/engagementController.js`: Replace `5000` with `SHORT_TIMEOUT_MS`.
-- [ ] Refactor `js/ui/applicationBootstrap.js`: Replace `5000` with `SHORT_TIMEOUT_MS`.
-- [ ] Refactor `js/webtorrent.js`: Replace `60000` with `LONG_TIMEOUT_MS`.
-- [ ] Run `npm run lint`.
-- [ ] Run `npm run test:unit`.
-- [ ] Update `docs/agents/AGENT_TASK_LOG.csv`.
+- [ ] Audit content/docs/guides/upload-content.md
+- [ ] Verify claims against code
+- [ ] Update documentation if needed

artifacts/docs-audit/2026-02-12/inventory.md

@@ -0,0 +1,13 @@
+# Documentation Inventory
+
+| Page | Claim | Code Location | Verified? |
+|------|-------|---------------|-----------|
+| `content/docs/guides/upload-content.md` | Accepted Video Types: `.mp4`, `.webm`, `.mov`, `.mkv`, `.ts`, `.m3u8`, `.mpg`, `.mpeg` | `components/upload-modal.html` (input accept attribute) | Yes |
+| `content/docs/guides/upload-content.md` | Accepted Thumbnail Types: `image/*` | `components/upload-modal.html` (input accept attribute) | Yes |
+| `content/docs/guides/upload-content.md` | File Size Recommended: Up to 2GB (Client-side hashing limit) | `js/utils/torrentHash.js` (in-memory buffer usage impl) | Yes |
+| `content/docs/guides/upload-content.md` | Required Metadata: Title | `js/services/videoNotePayload.js` (`VIDEO_NOTE_ERROR_CODES.MISSING_TITLE`) | Yes |
+| `content/docs/guides/upload-content.md` | Required Source: URL, Magnet, or IMETA | `js/services/videoNotePayload.js` (`VIDEO_NOTE_ERROR_CODES.MISSING_SOURCE`) | Yes |
+| `content/docs/guides/upload-content.md` | HTTPS required for External URLs | `js/services/videoNotePayload.js` (`VIDEO_NOTE_ERROR_CODES.INVALID_URL_PROTOCOL`) | Yes |
+| `content/docs/guides/upload-content.md` | CORS Policy JSON | `js/storage/s3-multipart.js` (`ensureBucketCors`) | Yes |
+| `content/docs/guides/upload-content.md` | Automatic CORS Configuration | `js/services/s3Service.js` (`prepareS3Connection` calls `ensureBucketCors`) | Yes |
+| `content/docs/guides/upload-content.md` | Upload Methods: R2, S3, External, Magnet | `js/ui/components/UploadModal.js`, `js/services/s3UploadService.js` | Yes |

artifacts/docs-audit/2026-02-12/verification.md

@@ -0,0 +1,39 @@
+# Verification Report
+
+## 1. Accepted File Types
+- **Claim**: `.mp4`, `.webm`, `.mov`, `.mkv`, `.ts`, `.m3u8`, `.mpg`, `.mpeg`.
+- **Code**: `components/upload-modal.html`
+  ```html
+  <input id="input-file" type="file" class="hidden" accept="video/*,.m3u8,.ts,.mp4,.webm,.mov,.mkv,.mpg,.mpeg" />
+  ```
+- **Status**: **Verified**.
+
+## 2. File Size Limits
+- **Claim**: 2GB recommended due to browser memory hashing.
+- **Code**: `js/services/s3UploadService.js` calls `this.deps.calculateTorrentInfoHash(file)`. `js/utils/torrentHash.js` reads file into memory/buffer for hashing.
+- **Status**: **Verified**.
+
+## 3. Metadata Validation
+- **Claim**: Title required. HTTPS for URLs.
+- **Code**: `js/services/videoNotePayload.js`:
+  ```javascript
+  if (!legacyFormData.title) errors.push(VIDEO_NOTE_ERROR_CODES.MISSING_TITLE);
+  if (legacyFormData.url && !/^https:\/\//i.test(legacyFormData.url)) errors.push(VIDEO_NOTE_ERROR_CODES.INVALID_URL_PROTOCOL);
+  ```
+- **Status**: **Verified**.
+
+## 4. CORS Policy
+- **Claim**: JSON policy provided in docs.
+- **Code**: `js/storage/s3-multipart.js` `ensureBucketCors` constructs the policy dynamically but matches the structure (AllowedOrigins, AllowedMethods, AllowedHeaders=["*"], ExposeHeaders=[ETag, ...]).
+- **Status**: **Verified**.
+
+## 5. Upload Lifecycle
+- **Claim**: "The client handles the upload, generates a magnet link...".
+- **Code**: `js/ui/components/UploadModal.js` `handleVideoSelection` uploads video, then calls `generateTorrentMetadata`, then uploads `.torrent` file if successful.
+- **Gap**: Docs do not explicitly mention that a `.torrent` file is also uploaded to the bucket.
+- **Recommendation**: Update docs to mention `.torrent` file generation and upload.
+
+## 6. S3/R2 Configuration
+- **Claim**: Supports S3 and R2.
+- **Code**: `js/services/s3Service.js` and `js/services/storageService.js` handle these providers.
+- **Status**: **Verified**.

content/docs/guides/upload-content.md

@@ -147,9 +147,9 @@ bitvid will verify your credentials by attempting to list or upload a test file.
 
 ### How Uploads Work
 
-1. **Direct Upload:** Your browser uploads the file directly to your storage bucket. No video data passes through a bitvid server.
+1. **Direct Upload:** Your browser uploads the file directly to your storage bucket. The client also automatically generates and uploads a `.torrent` file to enable P2P swarming. No video data passes through a bitvid server.
 2. **External Link:** Your browser streams directly from the provided URL (or via WebTorrent if a magnet is also provided). No video data passes through the bitvid server.
-3. **Client-Side Hashing:** Your browser calculates a cryptographic hash (info hash) of the file locally to enable WebTorrent support. This happens in memory, so large files require sufficient RAM.
+3. **Client-Side Hashing:** Your browser calculates a cryptographic hash (info hash) of the file locally to enable WebTorrent support. This happens in memory, so large files (>2GB) may require significant RAM and can cause browser instability.
 4. **Publication:** The video metadata (title, URL, hash, tags) is signed by your Nostr key and published to relays.
 
 ### Moderation & Visibility

docs/agents/AGENT_TASK_LOG.csv

@@ -2,3 +2,4 @@ date,agent_name,prompt_file,status,branch,summary
 2026-02-12,audit-agent,bitvid-audit-agent.md,completed,unstable,"Ran audit scripts, created initial reports"
 2026-02-12,ci-health-agent,bitvid-ci-health-agent.md,completed,ai/ci-health-fix-watch-history-flake,"Fixed flaky test in watch-history.test.mjs using waitFor"
 2026-02-12,const-refactor-agent,bitvid-const-refactor-agent.md,completed,ai/constants-refactor/daily-run,"Refactored timeouts in UI controllers and webtorrent.js to use canonical constants"
+2026-02-12,content-audit-agent,bitvid-content-audit-agent.md,completed,content-audit/fix-upload-docs,"Audited upload docs, verified claims against code, updated details on .torrent generation"