docs: add pow, cli client, and head method documentation

README.md

@@ -11,7 +11,9 @@ A lightweight, secure pastebin REST API built with Flask.
 - **Automatic expiry** - Pastes expire after configurable period of inactivity
 - **Size limits** - Configurable limits for anonymous and authenticated users
 - **Abuse prevention** - Content-hash deduplication throttles repeated identical submissions
+- **Proof-of-work** - Configurable computational puzzle prevents automated spam
 - **Security headers** - HSTS, CSP, X-Frame-Options, Cache-Control, and more
+- **CLI client** - Standalone `fpaste` command-line tool included
 - **Request tracing** - X-Request-ID support for log correlation
 - **Proxy trust validation** - Optional shared secret for defense-in-depth
 - **Minimal dependencies** - Flask only, SQLite built-in
@@ -36,9 +38,12 @@ python run.py
 |--------|----------|-------------|
 | `GET /` | API information and usage |
 | `GET /health` | Health check (returns DB status) |
+| `GET /challenge` | Get proof-of-work challenge |
 | `POST /` | Create a new paste |
 | `GET /<id>` | Retrieve paste metadata |
+| `HEAD /<id>` | Retrieve paste metadata (headers only) |
 | `GET /<id>/raw` | Retrieve raw paste content |
+| `HEAD /<id>/raw` | Retrieve paste headers (no body) |
 | `DELETE /<id>` | Delete paste (requires auth) |
 
 ## Usage Examples
@@ -77,6 +82,46 @@ curl -X DELETE \
      http://localhost:5000/abc12345
 ```
 
+## CLI Client
+
+A standalone command-line client `fpaste` is included (no external dependencies).
+
+### Basic Usage
+
+```bash
+# Create paste from file
+./fpaste create file.txt
+
+# Create paste from stdin
+echo "Hello" | ./fpaste
+
+# Get paste content
+./fpaste get abc12345
+
+# Get paste metadata
+./fpaste get -m abc12345
+
+# Delete paste (requires auth)
+./fpaste delete abc12345
+
+# Show server info
+./fpaste info
+```
+
+### Configuration
+
+Set server URL and authentication via environment or config file:
+
+```bash
+# Environment variables
+export FLASKPASTE_SERVER="https://paste.example.com"
+export FLASKPASTE_CERT_SHA1="your-cert-fingerprint"
+
+# Or config file (~/.config/fpaste/config)
+server = https://paste.example.com
+cert_sha1 = your-cert-fingerprint
+```
+
 ## Configuration
 
 Configuration via environment variables:
@@ -92,6 +137,9 @@ Configuration via environment variables:
 | `FLASKPASTE_DEDUP_WINDOW` | `3600` (1 hour) | Dedup throttle window in seconds |
 | `FLASKPASTE_DEDUP_MAX` | `3` | Max identical submissions per window |
 | `FLASKPASTE_PROXY_SECRET` | (empty) | Shared secret for proxy trust validation |
+| `FLASKPASTE_POW_DIFFICULTY` | `20` | PoW difficulty (leading zero bits, 0=disabled) |
+| `FLASKPASTE_POW_TTL` | `300` (5 min) | PoW challenge validity period |
+| `FLASKPASTE_POW_SECRET` | (auto) | Secret for signing PoW challenges |
 
 ## Authentication