docs: direct-to-R2 ingest (video+files), media viewer suite, multi-file queues, sidecar + LLM ops notes

docs/admin-guide.md

@@ -194,6 +194,10 @@ The governance sim is re-runnable (all fixtures prefixed `e2e-gov-`) and writes
 
 ### 10.5 Known ops note
 - Restarting the api container repeatedly can trip the homeserver login rate limit (`M_LIMIT_EXCEEDED`) and crash bootstrap — wait **~2–3 min** between api restarts.
+- **DIRECT_EC_PRIVATE_KEY** (P-256 PKCS8 base64) is required by the api, media-worker and produce-worker (compose appenv) — it unwraps client-sealed SPENC2 frames. Rotation needs a re-seal migration (not yet designed).
+- The AI transcription sidecar (faster-whisper large-v3-turbo, OpenAI-compatible) runs on the moxexleyhp1-1 WSL GPU at `http://100.70.240.7:9000` (systemd unit `tmbh-transcribe`); cuBLAS/cuDNN come from pip wheels (`nvidia-cublas-cu12`, `nvidia-cudnn-cu12`) + `/usr/lib/wsl/lib`.
+- LLM serving for agent workflows: LiteLLM at `http://100.96.13.16:4000` (opencode3), key `sk-hub1-…` (hub1 virtual key), serving `qwen3.8-27b`.
+- Restarting the api container repeatedly can trip the homeserver login rate limit (`M_LIMIT_EXCEEDED`) and crash bootstrap — wait **~2–3 min** between api restarts.
 
 ## 11. Upgrading
 

docs/engineering-guide.md

@@ -186,7 +186,23 @@ Still planned: media-engine graph rewiring beyond the current FFmpeg-normalize p
 - 10 MiB chunks (`CHUNK_SIZE_BYTES`) sidestep Cloudflare's ~100 MB proxy body cap. The server reassembles, seals, stores to R2, then runs the normal probe pipeline.
 - Max chunked upload: **100 GiB** (`MAX_CHUNKED_UPLOAD_BYTES`).
 
-### 10.6 Upload caps
+### 10.7 Direct-to-R2 video ingest (worker-probed)
+- `GET /video/direct/config` → `POST /video/direct/init` (presigned PUT) → `POST /video/direct/complete` (HEAD-gated register + queued probe job). The browser seals SPENC2 and PUTs straight to object storage — the api box never touches video bytes.
+- The produce worker claims the probe job (042 widened `produce_job_claim`), fetches the sealed object off R2, opens by magic (SPENC1 kek / SPENC2 direct key via `DIRECT_EC_PRIVATE_KEY`), ffprobes, writes metadata, completes. Compose/mix jobs read direct objects the same way.
+- Requirements: `DIRECT_EC_PRIVATE_KEY` on api + media-worker + produce-worker (compose appenv).
+
+### 10.8 Files direct-to-R2 + media viewer
+- `GET /files/direct/config`, `POST /files/direct/init|complete`, `POST /files/:id/direct-download` (presigned GET + CEK ticket; the browser decrypts — the server never streams direct/ payloads).
+- Viewer suite: image lightbox (zoom/pan/rotate + filmstrip), brand video player (scrubber/buffered/volume/speed/PiP/fullscreen + keyboard), image EDITOR (crop with aspect presets, rotate 90s, flip H/V, brightness/contrast/saturation — saves as a NEW library file), video TRIM (in/out → the cut renders into the Video library via the assemble lane; the original is never modified), PDF (native iframe), text (+copy), HTML (sandboxed `allow-scripts` run + source toggle).
+- Thumbnails decrypt client-side; video stills are captured in-browser. Session cache dedupes decryption per item.
+- Browser memory caps the direct path at 512 MiB (sealing holds plaintext + frame); larger files fall back to the server path (Cloudflare-capped ~100 MB) until multipart lands.
+
+### 10.9 Multi-file upload queues
+- Both dropzones accept multiple files: sequential queue, per-file status (queued / % / done / failed), one failure never aborts the queue.
+- Video per-file transport: direct (when enabled, ≤512 MiB) → chunked (>10 MiB) → whole-body (≤10 MiB). Files per-file transport: direct (when enabled, ≤512 MiB) → server multipart.
+
+
+## 11. Key file map
 - Whole-body video upload cap: **2 GiB** (`MAX_VIDEO_UPLOAD_BYTES`).
 - Files group upload cap: **2 GiB** (was 20 MiB).
 

docs/user-guide.md

@@ -64,7 +64,11 @@ Every meaningful action (post published, role changed, connection added, credent
 - **Library (Files) tab:** upload up to **2 GiB per file**. Files are encrypted and stored in the hub's own object storage. The old 20 MiB limit and the separate Drive tab are gone — the Library replaces both.
 - **Compose:** attach up to **4 images or videos** per post (10 MiB per image, 64 MiB per video) and add **alt text** descriptions — they appear on Mastodon.
 - **Video producer:** apply **lower-third, logo, or clock overlays** and **voiceover** to any library video. Clips with no audio get a synthesized silence bed, so they always work. Results land back in the library and can be published like any other asset.
-- **Large videos:** uploads are automatically split into 10 MB chunks — big files work even through Cloudflare.
+- **Large videos:** uploads are automatically split into 10 MB chunks — big files work even through Cloudflare. When direct storage is enabled, files upload encrypted straight to object storage without passing through the server at all.
+- **View everything in-app:** photos open in a lightbox (zoom, pan, rotate), videos play in the hub's own player (scrubber, speed, PiP, fullscreen, keyboard shortcuts), PDFs open in place, text files are readable with one-click copy, and HTML files run in a sandboxed preview.
+- **Edit photos:** crop (free, 1:1, 16:9, 9:16), rotate, flip and adjust brightness/contrast/saturation — saving creates a new file, the original is never modified.
+- **Trim videos:** set start and end points and send the cut to the Video Studio — the cut renders as a new clip in the Video library.
+- **Upload several files at once:** drop or pick multiple files — each uploads in turn with its own progress, and one failure never blocks the rest.
 
 ## 10. What's real vs. coming