Align /content user docs with actual upload & contribution behavior

- Updated `content/docs/guides/upload-content.md` with accurate file types, size limit explanations, and troubleshooting steps.
- Updated `content/docs/getting-started.md` to link to the detailed upload guide and clarify "Invite-only" (Whitelist) mode.
- Verified changes against `js/ui/components/UploadModal.js`, `js/storage/s3-multipart.js`, and `js/accessControl.js`.
- Included `VALIDATION_REPORT.md` documenting the verification process.

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

VALIDATION_REPORT.md

@@ -0,0 +1,69 @@
+# Validation Report
+
+This report documents the verification of user-facing documentation in `/content` against the codebase.
+
+## 1. Storage Configuration (CORS)
+
+**Claim:** Users must configure CORS with specific headers to allow browser uploads.
+**Source:** `content/docs/guides/upload-content.md`
+**Code:** `js/storage/s3-multipart.js` (function `ensureBucketCors`)
+
+**Verification:**
+The `ensureBucketCors` function hardcodes the following CORS rules:
+- `AllowedHeaders`: `["*"]` (Matches docs)
+- `AllowedMethods`: `["GET", "HEAD", "PUT", "POST", "DELETE", "OPTIONS"]` (Matches docs, order irrelevant)
+- `ExposeHeaders`: `["ETag", "Content-Length", "Content-Range", "Accept-Ranges"]` (Matches docs)
+- `MaxAgeSeconds`: `3600` (Matches docs)
+
+The `AllowedOrigins` in code is dynamic (`allowedOrigins` variable), while the docs provide a concrete example (`["http://localhost:5500", "https://bitvid.network"]`) which is correct for users.
+
+## 2. File Type Limits
+
+**Claim:** Accepted file types are `.mp4, .webm, .mov, .mkv, .ts, .m3u8, .mpg, .mpeg`.
+**Source:** `content/docs/guides/upload-content.md`
+**Code:** `components/upload-modal.html`
+
+**Verification:**
+The input element is defined as:
+```html
+<input id="input-file" type="file" class="hidden" accept="video/*,.m3u8,.ts,.mp4,.webm,.mov,.mkv,.mpg,.mpeg" />
+```
+The documentation matches the specific extensions listed in the code. The docs now also clarify that "other standard video formats" are accepted via `video/*`.
+
+## 3. File Size Limit
+
+**Claim:** Recommended limit is 2GB due to browser memory.
+**Source:** `content/docs/guides/upload-content.md`
+**Code:** `js/utils/torrentHash.js`
+
+**Verification:**
+The client-side hashing logic uses `FileReader.readAsArrayBuffer(file)`. This loads the entire file into memory. Browser implementations (especially Chrome) typically crash or fail when allocating ArrayBuffers larger than ~2GB. This technical constraint confirms the documentation's warning.
+
+## 4. Moderation (Whitelist Mode)
+
+**Claim:** "Whitelist Mode" restricts visibility to approved accounts.
+**Source:** `content/docs/guides/upload-content.md` & `getting-started.md`
+**Code:** `js/accessControl.js`
+
+**Verification:**
+The `AccessControl` class implements `canAccess(candidate)`:
+```javascript
+if (this.whitelistEnabled && !this.whitelistPubkeys.has(hex)) {
+    return false;
+}
+```
+If `whitelistEnabled` is true (Whitelist Mode), non-whitelisted pubkeys return `false`, blocking their content from being displayed in feeds that use this check. This confirms the documentation.
+
+## 5. Upload Lifecycle
+
+**Claim:** Direct upload to bucket -> Client-side hashing -> NIP-71/Nostr publication.
+**Source:** `content/docs/guides/upload-content.md`
+**Code:** `js/ui/components/UploadModal.js`
+
+**Verification:**
+`handleVideoSelection` in `UploadModal.js`:
+1.  Calls `service.uploadFile` (Direct upload to R2/S3).
+2.  Calls `generateTorrentMetadata` (Client-side hashing).
+3.  Calls `publish` -> `publishVideoNote` (Nostr publication).
+
+This flow matches the documentation exactly.

content/docs/getting-started.md

@@ -14,7 +14,7 @@ Ready to jump in? Here's everything you need to know to start watching and shari
 
 ### Step 1: Set Up Your Account
 
-> ⚠️ **Note:** We are currently invite-only. [Submit an application](https://bitvid.network/?modal=application) to request approval for posting content.
+> ⚠️ **Note:** We are currently invite-only (Whitelist Mode). While you can upload content, it will only appear in public feeds if your account has been approved. [Submit an application](https://bitvid.network/?modal=application) to request approval.
 
 1. Install a [Nostr extension](https://nostrapps.com/#signers#all) (like Alby or Nos2x) in your browser.
 2. The extension creates your secure login key automatically.
@@ -22,7 +22,7 @@ Ready to jump in? Here's everything you need to know to start watching and shari
 
 ### Step 2: Prepare Your Video
 
-1. **Format:** We accept **.mp4, .webm, .mov, .mkv, .ts, .m3u8, .mpg, .mpeg** (Max 2GB recommended).
+1. **Format:** We accept **.mp4, .webm, .mov, .mkv, .ts, .m3u8, .mpg, .mpeg** (Max 2GB recommended). For detailed requirements and troubleshooting, see our [Upload Guide](../guides/upload-content.md).
 2. **Hosting:** You can upload directly via bitvid (requires your own Cloudflare R2 or S3 bucket) or host your video elsewhere (CDN, Cloudflare Stream, etc.) and provide the HTTPS URL. For external hosting, ensure the format is streamable (MP4/WebM/HLS/DASH).
 3. **(Optional) WebTorrent:** If hosting externally, you can generate a WebTorrent magnet so viewers can fall back to peer-to-peer delivery.
 

content/docs/guides/upload-content.md

@@ -15,8 +15,8 @@ bitvid offers three ways to publish content:
 Before you start, ensure your content meets the following requirements:
 
 ### Accepted File Types
-- **Video:** `.mp4`, `.webm`, `.mov`, `.mkv`, `.ts`, `.m3u8`, `.mpg`, `.mpeg`
+- **Video:** `.mp4`, `.webm`, `.mov`, `.mkv`, `.ts`, `.m3u8`, `.mpg`, `.mpeg`, and other standard video formats supported by your browser.
-- **Thumbnail:** Any standard image format (`image/*`)
+- **Thumbnail:** Any standard image format (`image/*`) supported by your browser.
 
 ### File Size
 - **Recommended:** Up to **2GB** per file.
@@ -79,7 +79,7 @@ bitvid will attempt to configure CORS automatically if your API keys have "Admin
   }
 ]
 ```
-> **Note:** Replace `AllowedOrigins` with your actual origins. If you are using the official site, keep `https://bitvid.network`. If you are running a local instance, use `http://localhost:5500`.
+> **Note:** Replace `AllowedOrigins` with your actual origins. If you are using the official site, keep `https://bitvid.network`. If you are running a local instance, use `http://localhost:5500` or your custom domain.
 
 **S3 Compatible Providers:**
 bitvid will attempt to configure CORS automatically for generic S3 providers if your credentials have sufficient permissions. However, if uploads fail with CORS errors, apply a similar policy manually in your provider's console.
@@ -115,22 +115,22 @@ bitvid will verify your credentials by attempting to list or upload a test file.
 
 ### Common Issues
 
-- **CORS Errors:** If you see "Network Error" or "CORS" in the console during upload, verify your bucket's CORS policy matches the JSON above. Ensure `AllowedHeaders` includes `*` or `amz-sdk-*`.
+- **CORS Errors ("Network Error"):** If uploads fail immediately or the console shows "CORS", verify your bucket's CORS policy matches the JSON above. Ensure `AllowedHeaders` includes `*` and `ExposeHeaders` lists `ETag`.
-- **Upload Fails Immediately:** Check your API credentials and ensure the bucket name is correct.
+- **Permission Errors ("Access Denied"):** Check your API credentials. Ensure the token has `Object Read & Write` permissions (specifically `s3:PutObject` and `s3:DeleteObject`).
 - **Browser Crashes / Slow Performance:** Large files (>2GB) can exhaust browser memory during the hashing process. Try using a smaller file or ensuring you have plenty of free RAM.
-- **Playback Issues:** If the video uploads but doesn't play, ensure the "Public Access URL" is correct and publicly reachable.
+- **Playback Issues:** If the video uploads but doesn't play, ensure the "Public Access URL" is correct and publicly reachable. Test the URL directly in a browser.
 
 ## Upload Lifecycle & Moderation
 
 ### How Uploads Work
 1. **Direct Upload:** Your browser uploads the file directly to your storage bucket. No video data passes through a bitvid server.
 2. **Client-Side Hashing:** Your browser calculates a cryptographic hash (info hash) of the file to enable WebTorrent support.
-3. **Publication**: The video metadata (title, URL, hash, tags) is signed by your Nostr key and published to relays.
+3. **Publication:** The video metadata (title, URL, hash, tags) is signed by your Nostr key and published to relays.
 
 ### Moderation & Visibility
-While publication is decentralized and permissionless, the bitvid.network instance may enforce moderation policies:
+While publication is decentralized and permissionless, individual bitvid instances (clients) may enforce moderation policies:
-- **Whitelists**: If the instance is in "whitelist mode", you may need approval before your videos appear in public feeds.
+- **Whitelists ("Invite-only"):** If the instance is in "whitelist mode", your videos will only appear in public feeds if your account has been approved by an admin. You can still share direct links, but discovery is restricted.
-- **Blacklists**: Violating community guidelines may result in your account being hidden from this instance.
+- **Blacklists:** Violating community guidelines may result in your account being hidden from this instance.
-- **User Blocks**: Viewers can mute or block your content individually.
+- **User Blocks:** Viewers can mute or block your content individually.
 
 Check the [Community Guidelines](../community/community-guidelines.md) for more details.