diff --git a/README.md b/README.md
index dfa7fb0..95f7eeb 100644
--- a/README.md
+++ b/README.md
@@ -1,19 +1,30 @@
 # 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.
+simple download links, optional passwords, ZIP downloads, generated image
+thumbnails, 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]
+    User[Person in browser]
+    UI[WarpBox UI]
+    API[Go HTTP server]
+    Manifest[(Box manifest JSON)]
+    Files[(Uploaded files)]
+    Thumbs[(Thumbnail JPEGs)]
+    DB[(BadgerDB metadata)]
+
+    User --> UI
+    UI -->|create box / upload / poll status| API
+    API --> Manifest
+    API --> Files
+    API --> DB
+    Files -->|download files or build ZIP| API
+    Thumbs -->|preview URLs| UI
+    Files -->|scan image files| Thumbs
 ```
 
 ## Features
@@ -25,7 +36,8 @@ flowchart LR
 - 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.
+- Local BadgerDB metadata store for users, tags, sessions, and settings.
+- No external database service required.
 
 ## How It Fits Together
 
@@ -36,11 +48,13 @@ flowchart TB
     Manifest[Box manifest JSON]
     Files[Uploaded files]
     Thumbs[Generated thumbnails]
+    DB[(BadgerDB metadata)]
 
-    Browser -->|create box / upload / poll| Server
+    Browser -->|POST /box, uploads, status polls| Server
     Server --> Manifest
     Server --> Files
     Server --> Thumbs
+    Server --> DB
     Thumbs -->|preview URLs| Browser
     Files -->|downloads / ZIP| Browser
 ```
@@ -101,6 +115,8 @@ settings remain environment controlled.
 | `WARPBOX_THUMBNAIL_BATCH_SIZE` | `10` | Number of pending thumbnails processed per worker pass. |
 | `WARPBOX_THUMBNAIL_INTERVAL_SECONDS` | `30` | Delay between thumbnail worker passes. |
 
+Size limits also accept `_MB` variants for the same settings.
+
 Example:
 
 ```bash
@@ -144,23 +160,29 @@ data/db/
 ## 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/config/     Typed environment and runtime settings config
-lib/metastore/  BadgerDB metadata store for users, tags, settings, sessions
-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
+cmd/                CLI entrypoint
+lib/server/         HTTP handlers and server setup
+lib/routing/        Route registration
+lib/boxstore/       Box storage, manifests, downloads, thumbnails
+lib/config/         Typed environment and runtime settings config
+lib/metastore/      BadgerDB metadata store for users, tags, settings, sessions
+lib/helpers/        Small shared helpers
+lib/models/         Shared request/response models
+templates/          Server-rendered HTML
+static/css/         Stylesheets
+static/js/          Browser scripts
+static/img/         Icons, sprites, and backgrounds
+static/fonts/       Bitmap/pixel fonts
+static/cursors/     Custom cursor packs
+static/popups/      HTML popup content
+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.
+WarpBox is intentionally simple. It uses the local filesystem for box data,
+BadgerDB for app metadata, 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).
diff --git a/docs/tech.md b/docs/tech.md
index b34dc6d..58ebc35 100644
--- a/docs/tech.md
+++ b/docs/tech.md
@@ -19,6 +19,20 @@ The app starts from `cmd/main.go`. The `warpbox run` command calls the server
 package, loads templates from `templates/*.html`, registers routes, mounts
 `/static`, starts the thumbnail worker, and serves HTTP.
 
+The main request surfaces are:
+
+- `GET /` for the upload box UI.
+- `GET /box/:id` for shared box pages.
+- `GET /box/:id/login` and `POST /box/:id/login` for password-protected boxes.
+- `GET /box/:id/download` for ZIP downloads.
+- `GET /box/:id/files/:filename` for individual file downloads.
+- `GET /box/:id/thumbnails/:file_id` for image previews.
+- `POST /box` for new upload box creation.
+- `POST /box/:id/files/:file_id/upload` for manifest-based uploads.
+- `POST /box/:id/files/:file_id/status` for upload status updates.
+- `POST /box/:id/upload` and `POST /upload` for legacy upload compatibility.
+- `/admin/*` for the admin UI and settings.
+
 ## Frontend
 
 The frontend is server-rendered HTML with vanilla JavaScript.
@@ -26,14 +40,15 @@ The frontend is server-rendered HTML with vanilla JavaScript.
 - Templates live in `templates/`.
 - Browser behavior lives in `static/js/app.js` and `static/js/box.js`.
 - Styling lives in `static/css/`.
-- Visual assets, fonts, icons, cursors, and sprites live under `static/`.
+- Visual assets, fonts, icons, cursors, popups, and sprites live under
+  `static/`.
 
 There is no frontend build step. The browser receives HTML from Gin templates
 and static assets directly from the Go server.
 
 ## Storage
 
-WarpBox uses the local filesystem instead of a database.
+WarpBox uses the local filesystem for box data and BadgerDB for app metadata.
 
 Uploaded boxes are stored under:
 
@@ -43,26 +58,30 @@ data/uploads/
 
 Each box directory contains uploaded files plus a `.warpbox.json` manifest.
 The manifest tracks file names, statuses, retention, password metadata,
-download options, and thumbnail state.
+download options, and thumbnail state. BadgerDB stores users, tags, sessions,
+and runtime settings overrides.
 
 ## Upload Flow
 
 ```mermaid
 sequenceDiagram
-    participant UI as Browser UI
-    participant API as Gin server
+    participant Browser as Browser UI
+    participant Server as Gin server
     participant Store as boxstore
     participant Disk as Local disk
 
-    UI->>API: POST /box
-    API->>Store: create manifest
-    Store->>Disk: write box directory + manifest
-    API-->>UI: box id + upload URLs
-    UI->>API: POST /box/:id/files/:file_id/upload
-    API->>Store: save file and update status
+    Browser->>Server: POST /box
+    Server->>Store: create box directory + manifest
+    Store->>Disk: write .warpbox.json
+    Server-->>Browser: box id + upload URLs
+    Browser->>Server: POST /box/:id/files/:file_id/upload
+    Server->>Store: save file and update manifest
     Store->>Disk: write file + manifest
-    UI->>API: GET /box/:id/status
-    API-->>UI: current file states
+    Browser->>Server: POST /box/:id/files/:file_id/status
+    Server->>Store: update file status
+    Store->>Disk: rewrite manifest
+    Browser->>Server: GET /box/:id/status
+    Server-->>Browser: current file states
 ```
 
 ## Download Flow
@@ -73,6 +92,20 @@ Users can download individual files when the box allows it. ZIP downloads are
 created on demand from the files currently marked complete. One-time download
 boxes force ZIP download and delete the box after a successful ZIP response.
 
+```mermaid
+flowchart LR
+    Shared[Shared box page]
+    File[Individual file download]
+    Zip[ZIP download]
+    OneTime[One-time ZIP only]
+    Delete[Delete box after success]
+
+    Shared --> File
+    Shared --> Zip
+    OneTime --> Zip
+    Zip --> Delete
+```
+
 ## Thumbnail Worker
 
 The thumbnail worker is a background goroutine. On each pass it scans upload
@@ -126,6 +159,9 @@ Primary environment variables:
 - `WARPBOX_THUMBNAIL_BATCH_SIZE`
 - `WARPBOX_THUMBNAIL_INTERVAL_SECONDS`
 
+Size limit settings accept `_MB` or `_BYTES` env names. `WARPBOX_ADMIN_ENABLED`
+accepts `auto`, `true`, or `false`.
+
 The HTTP listen address is configured through the CLI flag:
 
 ```bash
@@ -150,7 +186,8 @@ lib/models/models.go     Shared data structures
 
 ## Tests
 
-Existing tests currently focus on the storage layer. Run them with:
+Existing tests cover config, storage, server security, and metastore behavior.
+Run them with:
 
 ```bash
 go test ./...