docs: clean upload documentation

Dockerfile

@@ -1,7 +1,4 @@
-# =============================================================================
+# Coolify production image: Next.js standalone app with Blender for Draco compression.
-# Upload GLTF — Dockerfile for Coolify
-# Node 20 Debian · Blender (headless) · Multi-stage build
-# =============================================================================
 
 # --- Stage 1: Dependencies ---------------------------------------------------
 FROM node:20-slim AS deps

README.md

@@ -5,7 +5,7 @@ A secure web interface for uploading `model.gltf` with its associated `.bin` fil
 - **Nextcloud Drive** — Archives the original files with automatic versioning (VF/V1/V2...), so artists always have a history of past versions
 - **GitHub** — Delivers Draco-compressed GLB assets by default, with an optional GLTF delivery mode for specific models
 
-Built for La Fabrik Durable's internal use, but open-sourced for anyone looking for a similar solution. The app validates the upload locally, stages it server-side, then applies intelligent diffs to avoid unnecessary uploads and commits. The Drive upload serves as the source of truth and version history, while the GitHub upload delivers the prepared assets to developers
+Built for La Fabrik Durable's internal use, but open-sourced for anyone looking for a similar solution. The app validates the upload locally, stages it server-side, then compares file diffs to avoid unnecessary uploads and commits. The Drive upload serves as the source of truth and version history, while the GitHub upload delivers the prepared assets to developers.
 
 ## Stack
 
@@ -57,7 +57,7 @@ Invalid or unknown asset names still block the upload.
 ### Upload flow: Drive first, then Git
 
 5. **Drive upload (archiving)** — Original files from the staging area are uploaded to the Nextcloud Drive with automatic versioning (see below). This serves as the artists' source of truth and version history. If the Drive upload fails, a modal asks the user whether to send to Git only or cancel entirely.
-6. **Git upload (delivery to devs)** — The prepared Git payload is reused from staging. By default, Blender exports a single `model.glb` with Draco compression. For specific models, "Envoyer en GLTF" keeps the current separate `model.gltf` + `.bin` + compressed textures workflow.
+6. **Git upload (delivery to devs)** — The prepared Git payload is reused from staging. By default, Blender exports a single `model.glb` with Draco compression. If Blender cannot process a specific model, the upload falls back to the separate `model.gltf` + `.bin` + compressed textures workflow and shows a warning. For specific models, "Envoyer en GLTF" keeps that separate GLTF delivery mode from the start.
 
 ### Drive versioning (Nextcloud WebDAV)
 
@@ -123,13 +123,13 @@ Commit sections:
 Symbols: `✅` new — `🔄` modified — `↔️` unchanged (model always re-pushed) — `❌` deleted
 
 7. Orphan files (present on remote but not in the new upload) are deleted in the same commit
-8. Default Git delivery pushes `model.glb` only; "Envoyer en GLTF" pushes separate `model.gltf`, `.bin`, and compressed textures.
+8. Default Git delivery pushes `model.glb` when Blender compression succeeds. If Blender fails, the app falls back to separate `model.gltf`, `.bin`, and compressed textures with a warning. "Envoyer en GLTF" always uses separate GLTF delivery.
 
 Uploaded models are pushed to `public/models/<folderName>/` in the target repo.
 
 ## Limitations
 
-- Large uploads are faster than before because the folder is staged only once, but the Drive upload remains sequential.
+- Large uploads are staged once, but the Drive upload remains sequential.
 - Git LFS batch uploads are sequential by batch.
 - Default GLB Draco delivery reduces Git LFS usage by replacing many support files with one compressed model file.
 - Uploads expect a single `model.gltf` file plus optional flat support files (`.bin`, `.png`, `.jpg`, `.jpeg`, `.webp`).
@@ -222,7 +222,7 @@ NEXTCLOUD_BASE_PATH=Models
 | `UPLOAD_SECRET_KEY` | Secret key for upload authentication | Yes |
 | `GITHUB_TOKEN` | GitHub Personal Access Token (fine-grained, `Contents: Read and write`) | Yes |
 | `GIT_BRANCH` | Target branch (default: main) | No |
-| `GIT_REPO_URL` | Target GitHub repository URL | Yes |
+| `GIT_REPO_URL` | Target GitHub repository URL (`owner/repo`, HTTPS, or SSH) | Yes |
 | `NEXTCLOUD_URL` | Nextcloud instance URL | Yes |
 | `NEXTCLOUD_SHARE_TOKEN` | Public share token (the part after `/s/` in the share link) | Yes |
 | `NEXTCLOUD_SHARE_PASSWORD` | Public share password (empty if none) | No |
@@ -245,7 +245,7 @@ docker run -p 3000:3000 \
   upload-gltf
 ```
 
-The Docker image runs the Next.js app, Blender Draco compression, and server-side asset preparation in a single container. The `docker-entrypoint.sh` script checks for required environment variables before launching the app
+The Docker image runs the Next.js app, Blender Draco compression, and server-side asset preparation in a single container. The `docker-entrypoint.sh` script creates the upload temp directory and reports Blender availability before launching the app.
 
 ## Supported Formats
 

docker-entrypoint.sh

@@ -12,7 +12,7 @@ if command -v blender > /dev/null 2>&1; then
   echo "[upload-gltf] Blender found: $BLENDER_VERSION"
   echo "[upload-gltf] Draco compression is enabled."
 else
-  echo "[upload-gltf] WARNING: Blender not found. GLB Draco uploads will fail; use 'Envoyer en GLTF' if needed."
+  echo "[upload-gltf] WARNING: Blender not found. GLB Draco compression will fall back to separate GLTF delivery."
 fi
 
 echo "[upload-gltf] Ready. Launching application..."

lib/auth.ts

@@ -2,8 +2,7 @@ import { timingSafeEqual } from 'crypto'
 import { NextRequest, NextResponse } from 'next/server'
 
 /**
- * Validate the upload secret from request headers.
+ * Validate the shared upload secret before accepting mutation routes.
- * Returns null if valid, or a NextResponse error if invalid.
  */
 export function validateUploadSecret(req: NextRequest): NextResponse | null {
   const secret = req.headers.get('x-upload-secret')

lib/blender.ts

@@ -7,8 +7,7 @@ const execFileAsync = promisify(execFile)
 
 /**
  * Compress a GLTF/GLB model using Blender's Draco compression.
- * Returns { success: true } on success, or { success: false, error } on failure.
+ * Returns a structured result so callers can decide whether to fall back or stop.
- * GLB Draco is explicit: callers should fail instead of silently pushing heavy assets.
  */
 export async function compressWithBlender(
   inputPath: string,

lib/sanitize.ts

@@ -1,8 +1,7 @@
 import { basename } from 'path'
 
 /**
- * Sanitize a filename: strip path components, replace special chars,
+ * Normalize uploaded filenames before storing them or writing Git paths.
- * collapse underscores, lowercase.
  */
 export function sanitizeFilename(name: string): string {
   return basename(name)