diff --git a/README.md b/README.md
index f306c91..66eabe3 100644
--- a/README.md
+++ b/README.md
@@ -1,45 +1,36 @@
 # safebin
 
-`safebin` is a minimalist, self-hosted file storage service with **Zero-Knowledge at Rest** encryption.
+[![Go Version](https://img.shields.io/badge/Go-1.25+-00ADD8?style=flat-square&logo=go)](https://go.dev/)
+[![License](https://img.shields.io/badge/License-GPLv2-blue.svg?style=flat-square)](LICENSE)
+[![Docker Image](https://img.shields.io/badge/Docker-ghcr.io%2Fskidoodle%2Fsafebin-blue?style=flat-square&logo=docker)](https://github.com/skidoodle/safebin/pkgs/container/safebin)
 
-## Features
+**safebin** is a minimalist, self-hosted file storage service designed for efficiency and privacy. It utilizes **Convergent Encryption** to provide secure storage at rest while automatically deduplicating identical files to save disk space.
 
-- **End-to-End Encryption**: Files are encrypted using AES-128-GCM before being written to disk.
-- **Key-Derived URLs**: The decryption key is part of the URL. The server uses this key to locate and decrypt the file on the fly.
-- **Integrity**: Uses GCM (Galois/Counter Mode) to ensure files cannot be tampered with while stored.
-- **Storage Deduplication**: Identical files result in the same ID, saving disk space.
-- **Chunked Uploads**: Supports large file uploads via the web interface using 8MB chunks.
+## 📖 Architecture & Security Model
 
-## Usage
+Safebin is designed to be **Host-Proof at Rest**. While it is not a client-side E2EE solution, it ensures that the server cannot access stored data without the specific link generated at upload time.
 
-### Web Interface
-Simply drag and drop files into the browser. The interface handles chunking and provides a shareable link once the upload is finalized.
+### How it Works
+1.  **Upload**: The server receives the file stream and calculates a SHA-256 hash of the content.
+2.  **Key Generation**: This hash becomes the encryption key (Convergent Encryption).
+3.  **Encryption**: The file is encrypted using **AES-128-GCM** and written to disk.
+4.  **Deduplication**: Because the key is derived from the content, identical files generate the same ID. The server detects this and stores only one physical copy, regardless of how many times it is uploaded.
+5.  **Zero-Knowledge Storage**: The server saves the file metadata (ID, size, expiry) but **discards the encryption key**.
+6.  **Link Generation**: The key is encoded into the URL fragment returned to the user.
 
-### Command Line (CLI)
-You can upload files directly using `curl`:
+> **Security Note**: If the server's database or physical storage is seized, the files are mathematically inaccessible. However, because encryption occurs on the server, the process does have access to the plaintext in memory during the brief window of upload and download.
 
-```bash
-curl -F 'file=@photo.jpg' https://bin.example.com
-```
+## ✨ Features
 
-The server will return a direct link:
-`https://bin.example.com/0iEZGtW-ikVdu...jpg`
+-   **Convergent Encryption & Deduplication**: Files are addressed by their content. Uploading the same file twice results in a single storage entry, significantly reducing disk usage.
+-   **Tamper-Proof Storage**: Uses Galois/Counter Mode (GCM) to ensure data integrity. Modified files will fail decryption.
+-   **Volatile Keys**: Decryption keys reside only in the generated URLs, not in the database.
+-   **Smart Retention**: A cubic scaling algorithm prioritizes keeping small files (snippets, logs) for a long time, while large binaries expire quickly.
+-   **Chunked Uploads**: Robust handling of large files via the web interface using 8MB chunks.
 
-## Configuration
+## 🚀 Deployment
 
-`safebin` can be configured via environment variables or command-line flags:
-
-| Flag | Environment Variable | Description | Default |
-| :--- | :--- | :--- | :--- |
-| `-h` | `SAFEBIN_HOST` | Bind address for the server. | `0.0.0.0` |
-| `-p` | `SAFEBIN_PORT` | Port to listen on. | `8080` |
-| `-s` | `SAFEBIN_STORAGE` | Directory for encrypted storage. | `./storage` |
-| `-m` | `SAFEBIN_MAX_MB` | Maximum file size in MB. | `512` |
-
-## Deployment
-
-### Docker Compose
-The easiest way to deploy is using the provided `compose.yaml`:
+### Docker Compose (Recommended)
 
 ```yaml
 services:
@@ -48,35 +39,64 @@ services:
     container_name: safebin
     restart: unless-stopped
     ports:
-      - 8080:8080
+      - "8080:8080"
     environment:
-      - SAFEBIN_HOST=0.0.0.0
-      - SAFEBIN_PORT=8080
-      - SAFEBIN_STORAGE=/app/storage
       - SAFEBIN_MAX_MB=512
     volumes:
-      - data:/app/storage
+      - safebin_data:/app/storage
 
 volumes:
-  data:
+  safebin_data:
 ```
 
-### Manual Build
+### Manual Installation
+
 Requires Go 1.25 or higher.
 
 ```bash
+# Build the binary
 go build -o safebin .
-./safebin -p 8080 -s ./data
+
+# Run the server
+./safebin -p 8080 -s ./data -m 1024
 ```
 
-## Retention Policy
+## ⚙️ Configuration
 
-The server runs a background cleanup task every hour. Retention is calculated using a cubic scaling formula to prioritize small files:
+Configuration is handled via environment variables or command-line flags. Flags take precedence over environment variables.
 
-- **Small files (e.g., < 1MB)**: Kept for up to **365 days**.
-- **Large files (at Max MB)**: Kept for **24 hours**.
-- **Temporary Uploads**: Unfinished chunked uploads are purged after **4 hours**.
+| Flag | Environment Variable | Description | Default |
+| :--- | :--- | :--- | :--- |
+| `-h` | `SAFEBIN_HOST` | Interface/Bind address. | `0.0.0.0` |
+| `-p` | `SAFEBIN_PORT` | Port to listen on. | `8080` |
+| `-s` | `SAFEBIN_STORAGE` | Directory for database and files. | `./storage` |
+| `-m` | `SAFEBIN_MAX_MB` | Maximum allowed file size in MB. | `512` |
 
-## License
+## 💻 Usage
 
-This project is licensed under the **GNU General Public License v2.0**.
+### Web Interface
+Navigate to `http://localhost:8080`. Drag and drop files to upload. The browser handles chunking automatically.
+
+### CLI (curl)
+Safebin is optimized for terminal usage. You can upload files directly via `curl`:
+
+```bash
+# Upload a file
+curl -F 'file=@screenshot.png' https://bin.example.com
+
+# Response
+https://bin.example.com/0iEZGtW-ikVdu...png
+```
+
+## ⏳ Retention Policy
+
+To keep storage manageable, Safebin runs a cleanup task every hour. File lifetime is determined by size using a cubic curve:
+
+*   **Small Files (< 1MB)**: Retained for **365 days**.
+*   **Medium Files (~50% Max Size)**: Retained for ~30 days.
+*   **Large Files (Max Size)**: Retained for **24 hours**.
+*   **Incomplete Uploads**: Purged after **4 hours**.
+
+## 📄 License
+
+This project is licensed under the [GNU General Public License v2.0](LICENSE).