docs: add comprehensive README with features and setup guidedocs: add comprehensive README with features and setup guide

README.md

@@ -0,0 +1,133 @@
+# WarpBox
+
+WarpBox is a small, self-hosted file sharing app with temporary upload boxes,
+simple download links, optional passwords, ZIP downloads, and a very deliberate
+retro desktop mood.
+
+It is meant to feel quick: pick files, choose how long the box should live,
+upload, and share the link.
+
+```mermaid
+flowchart LR
+    A[Choose files] --> B[Create box]
+    B --> C[Upload to box]
+    C --> D[Share link]
+    D --> E[Download files or ZIP]
+    E --> F[Expire or one-time cleanup]
+```
+
+## Features
+
+- Multi-file uploads through a browser UI.
+- Temporary boxes with configurable retention choices.
+- Optional password protection per box.
+- Individual file downloads or a single ZIP download.
+- One-time download mode for ZIP-only handoff.
+- Background thumbnails for image files.
+- Plain filesystem storage, with JSON manifests next to uploaded files.
+- No database required.
+
+## How It Fits Together
+
+```mermaid
+flowchart TB
+    Browser[Browser UI]
+    Server[Go HTTP server]
+    Manifest[Box manifest JSON]
+    Files[Uploaded files]
+    Thumbs[Generated thumbnails]
+
+    Browser -->|create box / upload / poll| Server
+    Server --> Manifest
+    Server --> Files
+    Server --> Thumbs
+    Thumbs -->|preview URLs| Browser
+    Files -->|downloads / ZIP| Browser
+```
+
+## Quick Start
+
+Requirements:
+
+- Go 1.22 or newer.
+
+Run the app:
+
+```bash
+go run ./cmd run
+```
+
+Then open:
+
+```text
+http://localhost:8080
+```
+
+To listen somewhere else:
+
+```bash
+go run ./cmd run --addr :3000
+```
+
+## Configuration
+
+WarpBox mostly works with defaults. These environment variables tune polling
+and thumbnail generation.
+
+| Variable | Default | Minimum | What it does |
+| --- | ---: | ---: | --- |
+| `WARPBOX_BOX_POLL_INTERVAL_MS` | `5000` | `1000` | Browser polling interval for box/file status updates. |
+| `WARPBOX_THUMBNAIL_BATCH_SIZE` | `10` | `1` | Number of pending thumbnails processed per worker pass. |
+| `WARPBOX_THUMBNAIL_INTERVAL_SECONDS` | `30` | `1` | Delay between thumbnail worker passes. |
+
+Example:
+
+```bash
+WARPBOX_BOX_POLL_INTERVAL_MS=2000 \
+WARPBOX_THUMBNAIL_BATCH_SIZE=20 \
+WARPBOX_THUMBNAIL_INTERVAL_SECONDS=10 \
+go run ./cmd run --addr :8080
+```
+
+## Storage
+
+Uploads are stored locally under:
+
+```text
+data/uploads/
+```
+
+Each box gets its own directory containing the uploaded files and a
+`.warpbox.json` manifest. Image thumbnails are stored inside a box-local
+`.thumbnails` directory.
+
+```text
+data/uploads/
++-- <box-id>/
+    +-- .warpbox.json
+    +-- file.txt
+    +-- .thumbnails/
+        +-- <file-id>.jpg
+```
+
+## Project Layout
+
+```text
+cmd/            CLI entrypoint
+lib/server/     HTTP handlers and server setup
+lib/routing/    Route registration
+lib/boxstore/   Box storage, manifests, downloads, thumbnails
+lib/helpers/    Small shared helpers
+lib/models/     Shared request/response models
+templates/      Server-rendered HTML
+static/         CSS, JavaScript, fonts, icons, and images
+docs/           Project documentation
+```
+
+## Notes
+
+WarpBox is intentionally simple. It uses the local filesystem as its backing
+store, relies on generated box IDs for share links, and keeps most behavior
+easy to follow from the Go handlers and the small browser scripts.
+
+For a short implementation overview, see [docs/tech.md](docs/tech.md).