Chore: Bump manifests for v1.3.1

Changes prefix-only LIKE to case-insensitive ILIKE with leading
wildcard so queries like "at" now match "cat", "scatter", etc.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

.env.example

@@ -11,6 +11,10 @@ S3_REGION=us-east-1
 # Angular SPA — injected at build or runtime
 API_BASE_URL=http://localhost:8000
 
+# CDN base URL for serving images (e.g. https://cdn.example.com).
+# Leave empty in local dev to use API proxy fallback.
+S3_PUBLIC_BASE_URL=
+
 # Upload size limit in bytes (default 50 MiB)
 MAX_UPLOAD_BYTES=52428800
 
@@ -27,3 +31,7 @@ LOGIN_COOLDOWN_SECONDS=900
 # Comma-separated IPs/CIDRs of trusted upstream proxies (e.g. nginx ingress pod CIDR).
 # Leave empty when not behind a reverse proxy.
 LOGIN_TRUSTED_PROXY_IPS=
+
+# API documentation endpoints (Swagger UI, ReDoc, OpenAPI schema)
+# Set to false in production to avoid exposing the API surface publicly.
+API_DOCS_ENABLED=true

.specify/feature.json

@@ -1,3 +1 @@
-{
-  "feature_directory": "specs/011-ui-prod-dockerfile"
-}
+{"feature_directory":"specs/016-copy-url-toast"}

.specify/memory/constitution.md

@@ -1,8 +1,8 @@
 <!--
 SYNC IMPACT REPORT
 ==================
-Version change: 1.2.0 → 1.3.0
-Ratified: 2026-05-01 | Last amended: 2026-05-06
+Version change: 1.3.0 → 1.4.0
+Ratified: 2026-05-01 | Last amended: 2026-05-08
 
 Principles introduced (first population from docs/CONSTITUTION.md):
   - §2  Architecture Principles (6 sub-principles)
@@ -171,11 +171,14 @@ OR/NOT logic is explicitly out of scope until the constitution is revised.
 
 ## 5. Testing Discipline
 
-### 5.1 TDD is non-negotiable
+### 5.1 Tests are required alongside every implementation task
 
-No production code MAY be written before a failing test exists for it. This
-applies to both API and UI. Tasks MUST include a "write failing test" step
-before any implementation step.
+Every implementation task MUST be accompanied by tests covering its behaviour.
+The ideal is red-green-refactor: write a failing test, then make it pass. In
+practice, tests written in the same task as the implementation are acceptable;
+what is non-negotiable is that no implementation task is marked done without
+corresponding test coverage. Tasks MUST NOT be split such that implementation
+is complete but tests are deferred to a later task.
 
 ### 5.2 Test pyramid
 
@@ -194,10 +197,15 @@ Unit and integration tests are required. E2E tests are best-effort in v1.
 API tests in `api/tests/`, UI tests colocated with their components. No
 separate top-level `tests/` directory that mirrors the source tree.
 
-### 5.4 CI must pass before any task is considered done
+### 5.4 The test suite must pass before any task is considered done
 
 "Done" means: all tests pass, linter passes, type checker passes. A task MUST
-NOT be marked complete while CI is failing.
+NOT be marked complete while any of these are failing.
+
+The acceptance gate is `make test-unit && make test-integration` plus `ruff
+check` / `ruff format --check` for the API. A formal CI pipeline is planned
+but not yet in place; until one exists, passing the above commands locally is
+the required gate. When CI is introduced it MUST enforce the same checks.
 
 ---
 
@@ -214,6 +222,9 @@ NOT be marked complete while CI is failing.
 | UI framework     | Angular (latest stable)                   | Job-relevant, learning goal               |
 | UI language      | TypeScript strict mode                    | No `any`, no implicit types               |
 | Containerisation | Docker + Docker Compose                   | Local dev must start with one command     |
+| Production runtime | k3s (Kubernetes)                        | Manifests in `k8s/`; see deployment docs  |
+| Ingress          | nginx ingress controller + cert-manager   | TLS via Let's Encrypt (`letsencrypt-prod` ClusterIssuer) |
+| Secret management | HashiCorp Vault + VSO (Vault Secrets Operator) | Secrets never committed; VSO syncs Vault KV v2 → K8s Secrets |
 
 ---
 
@@ -251,6 +262,15 @@ revised:
 - Mobile-native app
 - OIDC auth (planned Phase 3)
 
+**Known gaps carried forward from v1** — these are not out of scope; they are
+acknowledged deficiencies that MUST be resolved before the affected area is
+expanded:
+
+- **Password hashing**: The owner password is currently stored and compared in
+  plaintext. Hashing (bcrypt or Argon2) MUST be implemented before any
+  additional authentication work (e.g. OIDC, additional accounts) is started.
+  Specs that touch credential storage MUST address this first.
+
 ---
 
 ## 9. Governance
@@ -289,7 +309,8 @@ Phase 1 design is complete.
 | 1.1.1   | 2026-05-03 | Clarify that the only acceptable form of image transformation or editing is thumbnail generation                                |
 | 1.2.0   | 2026-05-03 | §2.4: Mark Phase 2 (JWT bearer auth) complete, reword phase status; §6: Add PyJWT to tech stack table; §8: Remove username/password auth from out-of-scope (now shipped) |
 | 1.3.0   | 2026-05-06 | §2.5: Remove planned PostgreSQL → SQLite refactor note; prohibit alternative database engines in integration tests. §5.2: Explicitly require PostgreSQL for integration tests; prohibit SQLite — a production HAVING/GROUP BY bug was masked by SQLite's permissive dialect. |
+| 1.4.0   | 2026-05-08 | §5.1: Soften strict TDD wording to reflect actual practice — tests alongside implementation are acceptable; deferring tests to a later task is not. §5.4: Replace "CI must pass" with local test suite gate; note CI is planned but not yet in place. §6: Add production runtime rows (k3s, nginx ingress + cert-manager, Vault + VSO). §8: Add "known gaps" subsection; document plaintext password storage as a deficiency that must be resolved before further auth work. |
 
 ---
 
-**Version**: 1.3.0 | **Ratified**: 2026-05-01 | **Last Amended**: 2026-05-06
+**Version**: 1.4.0 | **Ratified**: 2026-05-01 | **Last Amended**: 2026-05-08

.yamllint.yml

@@ -0,0 +1,4 @@
+extends: relaxed
+rules:
+  line-length:
+    max: 120

CLAUDE.md

@@ -1,5 +1,5 @@
 <!-- SPECKIT START -->
 For additional context about technologies to be used, project structure,
 shell commands, and other important information, read the current plan at
-`specs/011-ui-prod-dockerfile/plan.md`.
+`specs/016-copy-url-toast/plan.md`.
 <!-- SPECKIT END -->

Makefile

@@ -1,9 +1,10 @@
-.PHONY: test-unit test-integration build-prod verify-prod build-ui-prod verify-ui-prod
+.PHONY: test-unit test-integration build-prod verify-prod build-ui-prod verify-ui-prod validate-k8s
 
 test-unit:
 	cd api && python -m pytest tests/unit/ -v
 
 test-integration:
+	docker compose -f docker-compose.test.yml build api-test
 	docker compose -f docker-compose.test.yml run --rm api-test
 
 build-prod:
@@ -17,3 +18,8 @@ build-ui-prod:
 
 verify-ui-prod:
 	bash ui/tests/build/verify_production_image.sh
+
+# Offline: yamllint only. Online (requires kubeconfig): kubectl apply --dry-run=client -f k8s/
+validate-k8s:
+	yamllint -d relaxed k8s/
+	kubectl apply --dry-run=client -f k8s/

README.md

@@ -2,3 +2,141 @@
 _Organize your reaction images._
 
 ![Reactbin UI](.img/reactbin-ui.png)
+
+A self-hosted reaction image board. Single owner account, tag-based browsing, S3-compatible image storage.
+
+---
+
+## Local development
+
+```bash
+cp .env.example .env
+# Edit .env — defaults work out of the box for local dev
+docker compose up
+```
+
+- UI: http://localhost:4200
+- API: http://localhost:8000
+- MinIO console: http://localhost:9001 (minioadmin / minioadmin)
+
+The API serves on port 8000 directly in dev. In production the nginx ingress routes `/api/` there.
+
+### Running tests
+
+```bash
+make test-unit          # pytest unit tests (no Docker)
+make test-integration   # builds api-test image, runs full suite against Postgres + MinIO
+```
+
+### Production image builds
+
+```bash
+make build-prod         # builds reactbin-api-prod:latest from api/Dockerfile.prod
+make verify-prod        # smoke-tests the production image
+make build-ui-prod      # builds reactbin-ui-prod:latest from ui/Dockerfile.prod
+make verify-ui-prod     # smoke-tests the production UI image
+```
+
+---
+
+## Production deployment (k3s)
+
+### Cluster prerequisites
+
+- nginx ingress controller
+- cert-manager with a `letsencrypt-prod` ClusterIssuer
+- Vault Secrets Operator (VSO) installed and connected to Vault
+- Vault KV v2 secrets populated (see below)
+
+### Vault secrets
+
+Two KV v2 paths. VSO syncs these into Kubernetes Secrets automatically.
+
+**`reactbin/api/config`** → K8s Secret `api-env`
+
+| Key | Notes |
+|-----|-------|
+| `DATABASE_URL` | `postgresql+asyncpg://user:pass@host:5432/db` |
+| `JWT_SECRET_KEY` | Long random string — `openssl rand -base64 48` |
+| `OWNER_USERNAME` | Login username |
+| `OWNER_PASSWORD` | Login password |
+| `S3_ENDPOINT_URL` | `http://minio.reactbin.svc.cluster.local:9000` |
+| `S3_BUCKET_NAME` | `reactbin` |
+| `S3_ACCESS_KEY_ID` | Same value as `MINIO_ROOT_USER` |
+| `S3_SECRET_ACCESS_KEY` | Same value as `MINIO_ROOT_PASSWORD` |
+| `API_BASE_URL` | `https://<your-domain>` |
+| `LOGIN_TRUSTED_PROXY_IPS` | Pod CIDR of nginx ingress pods, e.g. `10.42.0.0/16` — needed for per-client login rate limiting behind the ingress |
+
+**`reactbin/minio/credentials`** → K8s Secret `minio-credentials`
+
+| Key | Notes |
+|-----|-------|
+| `MINIO_ROOT_USER` | MinIO admin username |
+| `MINIO_ROOT_PASSWORD` | `openssl rand -base64 32` |
+
+### Apply order
+
+```bash
+# 1. Namespace first
+kubectl apply -f k8s/namespace.yaml
+
+# 2. Vault CRDs — wait for VSO to create api-env and minio-credentials Secrets
+kubectl apply -f k8s/vault/
+kubectl get secret -n reactbin api-env minio-credentials   # wait until both appear
+
+# 3. API, UI, Ingress — replace 'latest' tags and <your-domain> first
+kubectl apply -f k8s/api/ -f k8s/ui/ -f k8s/ingress.yaml
+kubectl rollout status deployment/api -n reactbin          # Alembic init container runs here
+
+# 4. MinIO — wait for StatefulSet ready before running the bucket init Job
+kubectl apply -f k8s/minio/service.yaml -f k8s/minio/statefulset.yaml
+kubectl rollout status statefulset/minio -n reactbin
+kubectl apply -f k8s/minio/init-job.yaml
+```
+
+Before applying: substitute real image tags in the Deployment manifests and replace `<your-domain>` in `k8s/ingress.yaml`.
+
+### Updating a secret
+
+1. Update the value in Vault
+2. Force VSO to sync immediately (otherwise waits up to 1 hour):
+   ```bash
+   kubectl annotate vaultstaticsecret api-secret -n reactbin \
+     secrets.hashicorp.com/force-sync=$(date +%s) --overwrite
+   ```
+3. Restart the deployment to pick up the new Secret:
+   ```bash
+   kubectl rollout restart deployment/api -n reactbin
+   ```
+
+### Validating manifests
+
+```bash
+make validate-k8s   # yamllint + kubectl apply --dry-run=client (requires kubeconfig)
+```
+
+---
+
+## Environment variables reference
+
+All variables are read at startup from environment / `.env`.
+
+| Variable | Default | Notes |
+|----------|---------|-------|
+| `DATABASE_URL` | — | Async DSN: `postgresql+asyncpg://...` |
+| `JWT_SECRET_KEY` | — | Required; use a long random string in production |
+| `JWT_EXPIRY_SECONDS` | `86400` | Token lifetime (24 h) |
+| `OWNER_USERNAME` | — | Single owner account username |
+| `OWNER_PASSWORD` | — | Single owner account password |
+| `S3_ENDPOINT_URL` | — | MinIO or any S3-compatible endpoint |
+| `S3_BUCKET_NAME` | `reactbin` | |
+| `S3_ACCESS_KEY_ID` | — | |
+| `S3_SECRET_ACCESS_KEY` | — | |
+| `S3_REGION` | `us-east-1` | |
+| `MAX_UPLOAD_BYTES` | `52428800` | 50 MiB |
+| `API_BASE_URL` | — | Used for generating public URLs |
+| `API_DOCS_ENABLED` | `true` | Set to `false` in production |
+| `LOGIN_MAX_FAILURES` | `5` | Failed attempts before cooldown |
+| `LOGIN_WINDOW_SECONDS` | `300` | Sliding window for failure count |
+| `LOGIN_COOLDOWN_SECONDS` | `900` | Lock duration after threshold hit |
+| `LOGIN_TRUSTED_PROXY_IPS` | `""` | Comma-separated CIDRs of trusted upstream proxies |

api/.dockerignore

@@ -12,6 +12,3 @@ dist/
 .env
 .env.*
 !.env.example
-tests/
-alembic/
-alembic.ini

api/Dockerfile.prod

@@ -35,6 +35,8 @@ RUN groupadd --system --gid 1001 appgroup \
 
 COPY --from=builder --chown=appuser:appgroup /app/.venv /app/.venv
 COPY --chown=appuser:appgroup app/ ./app/
+COPY --chown=appuser:appgroup alembic/ ./alembic/
+COPY --chown=appuser:appgroup alembic.ini .
 
 USER appuser
 

api/app/auth/rate_limiter.py

@@ -14,20 +14,30 @@ def get_client_ip(
     request: Request,
     trusted_networks: list[IPv4Network | IPv6Network],
 ) -> str:
-    """Return the resolved client IP, honouring X-Forwarded-For when the
-    TCP peer is a trusted upstream proxy. Falls back to the TCP peer address
-    when no trusted networks are configured or the peer is not in the list."""
+    """Return the resolved client IP.
+
+    Prefers X-Real-IP over X-Forwarded-For when the TCP peer is a trusted
+    proxy. ingress-nginx sets X-Real-IP via its realip module using an
+    authoritative CIDR allowlist; it overwrites any client-supplied value, so
+    it cannot be spoofed via XFF injection. XFF[0] is the fallback for paths
+    that lack nginx (none currently exist, but kept for defence in depth).
+    """
     peer = request.client.host if request.client else "unknown"
     if trusted_networks and peer != "unknown":
         try:
             peer_addr = ipaddress.ip_address(peer)
             if any(peer_addr in net for net in trusted_networks):
-                xff = request.headers.get("X-Forwarded-For", "").split(",")[0].strip()
-                if xff:
-                    return xff
                 real_ip = request.headers.get("X-Real-IP", "").strip()
                 if real_ip:
                     return real_ip
+                # XFF[0] fallback — warn because this path should not be
+                # reached in production (nginx always sets X-Real-IP).
+                xff = request.headers.get("X-Forwarded-For", "").split(",")[0].strip()
+                if xff:
+                    logger.warning(
+                        "X-Real-IP absent from trusted peer %s; falling back to XFF[0]", peer
+                    )
+                    return xff
         except ValueError:
             pass
     return peer

api/app/config.py

@@ -1,5 +1,6 @@
 from functools import lru_cache
 
+from pydantic import field_validator
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
 
@@ -13,6 +14,7 @@ class Settings(BaseSettings):
     s3_secret_access_key: str
     s3_region: str = "us-east-1"
     api_base_url: str = "http://localhost:8000"
+    s3_public_base_url: str | None = None
     max_upload_bytes: int = 52_428_800  # 50 MiB
     jwt_secret_key: str
     jwt_expiry_seconds: int = 86400
@@ -22,6 +24,19 @@ class Settings(BaseSettings):
     login_window_seconds: int = 300
     login_cooldown_seconds: int = 900
     login_trusted_proxy_ips: str = ""
+    api_docs_enabled: bool = True
+
+    @field_validator("api_docs_enabled", mode="before")
+    @classmethod
+    def coerce_docs_enabled(cls, v):
+        if isinstance(v, bool):
+            return v
+        try:
+            from pydantic import TypeAdapter
+
+            return TypeAdapter(bool).validate_python(v)
+        except Exception:
+            return True
 
 
 @lru_cache

api/app/main.py

@@ -33,7 +33,16 @@ async def lifespan(application: FastAPI):
     await engine.dispose()
 
 
-app = FastAPI(title="Reactbin API", version="1.0.0", lifespan=lifespan)
+_settings = get_settings()
+
+app = FastAPI(
+    title="Reactbin API",
+    version="1.0.0",
+    lifespan=lifespan,
+    docs_url="/docs" if _settings.api_docs_enabled else None,
+    redoc_url="/redoc" if _settings.api_docs_enabled else None,
+    openapi_url="/openapi.json" if _settings.api_docs_enabled else None,
+)
 
 # Defaults so app.state is populated even when lifespan doesn't run (e.g. tests)
 app.state.login_rate_limiter = LoginRateLimiter()

api/app/repositories/tag_repo.py

@@ -88,7 +88,7 @@ class TagRepository:
 
         query = select(Tag, count_subq.label("image_count"))
         if prefix:
-            query = query.where(Tag.name.like(f"{prefix}%"))
+            query = query.where(Tag.name.ilike(f"%{prefix}%"))
         if min_count > 0:
             query = query.where(count_subq >= min_count)
 

api/app/routers/images.py

@@ -27,7 +27,16 @@ def _error(detail: str, code: str, status: int):
     raise HTTPException(status_code=status, detail={"detail": detail, "code": code})
 
 
-def _image_to_dict(image: Image, *, duplicate: bool | None = None) -> dict[str, Any]:
+def _image_to_dict(
+    image: Image, *, cdn_base: str | None = None, duplicate: bool | None = None
+) -> dict[str, Any]:
+    _base = cdn_base.strip().rstrip("/") if cdn_base else None
+    file_url = f"{_base}/{image.storage_key}" if _base else f"/api/v1/images/{image.id}/file"
+    thumbnail_url = (
+        (f"{_base}/{image.thumbnail_key}" if _base else f"/api/v1/images/{image.id}/thumbnail")
+        if image.thumbnail_key
+        else None
+    )
     data: dict[str, Any] = {
         "id": str(image.id),
         "hash": image.hash,
@@ -38,6 +47,8 @@ def _image_to_dict(image: Image, *, duplicate: bool | None = None) -> dict[str,
         "height": image.height,
         "storage_key": image.storage_key,
         "thumbnail_key": image.thumbnail_key,
+        "file_url": file_url,
+        "thumbnail_url": thumbnail_url,
         "created_at": image.created_at.isoformat(),
         "tags": image.tags,
     }
@@ -133,10 +144,13 @@ async def upload_image(
 
     hash_hex = compute_sha256(data)
     image_repo = ImageRepository(db)
+    _cdn_base = settings.s3_public_base_url
     existing = await image_repo.get_by_hash(hash_hex)
     if existing:
         return Response(
-            content=__import__("json").dumps(_image_to_dict(existing, duplicate=True)),
+            content=__import__("json").dumps(
+                _image_to_dict(existing, cdn_base=_cdn_base, duplicate=True)
+            ),
             status_code=200,
             media_type="application/json",
         )
@@ -183,7 +197,7 @@ async def upload_image(
         await tag_repo.attach_tags(image, tag_names)
         image = await image_repo.reload_with_tags(image.id)
 
-    return _image_to_dict(image, duplicate=False)
+    return _image_to_dict(image, cdn_base=_cdn_base, duplicate=False)
 
 
 @router.get("/images")
@@ -192,13 +206,15 @@ async def list_images(
     limit: int = 50,
     offset: int = 0,
     db: AsyncSession = Depends(get_db),
+    settings=Depends(get_settings),
 ):
     limit = min(limit, 100)
+    _cdn_base = settings.s3_public_base_url
     tag_names = [t.strip() for t in tags.split(",") if t.strip()] if tags else None
     image_repo = ImageRepository(db)
     images, total = await image_repo.list_images(tag_names=tag_names, limit=limit, offset=offset)
     return {
-        "items": [_image_to_dict(img) for img in images],
+        "items": [_image_to_dict(img, cdn_base=_cdn_base) for img in images],
         "total": total,
         "limit": limit,
         "offset": offset,
@@ -209,7 +225,9 @@ async def list_images(
 async def get_image(
     image_id: uuid.UUID,
     db: AsyncSession = Depends(get_db),
+    settings=Depends(get_settings),
 ):
+    _cdn_base = settings.s3_public_base_url
     image_repo = ImageRepository(db)
     image = await image_repo.get_by_id(image_id)
     if not image:
@@ -217,7 +235,7 @@ async def get_image(
             status_code=404,
             detail={"detail": "Image not found", "code": "image_not_found"},
         )
-    return _image_to_dict(image)
+    return _image_to_dict(image, cdn_base=_cdn_base)
 
 
 @router.get("/images/{image_id}/file")
@@ -288,7 +306,9 @@ async def update_image_tags(
     body: dict,
     db: AsyncSession = Depends(get_db),
     _: Identity = Depends(require_auth),
+    settings=Depends(get_settings),
 ):
+    _cdn_base = settings.s3_public_base_url
     image_repo = ImageRepository(db)
     image = await image_repo.get_by_id(image_id)
     if not image:
@@ -309,7 +329,7 @@ async def update_image_tags(
 
     await tag_repo.replace_tags_on_image(image, tag_names)
     image = await image_repo.reload_with_tags(image.id)
-    return _image_to_dict(image)
+    return _image_to_dict(image, cdn_base=_cdn_base)
 
 
 @router.delete("/images/{image_id}", status_code=204)

api/tests/integration/test_docs_gate.py

@@ -0,0 +1,48 @@
+import importlib
+
+from starlette.testclient import TestClient
+
+from app.config import get_settings
+
+_BASE_ENV = {
+    "DATABASE_URL": "postgresql+asyncpg://u:p@localhost/db",
+    "JWT_SECRET_KEY": "test-secret",
+    "OWNER_USERNAME": "admin",
+    "OWNER_PASSWORD": "password",
+    "S3_ENDPOINT_URL": "http://localhost:9000",
+    "S3_BUCKET_NAME": "test-bucket",
+    "S3_ACCESS_KEY_ID": "key",
+    "S3_SECRET_ACCESS_KEY": "secret",
+}
+
+
+def _set_env(monkeypatch, extra=None):
+    for k, v in {**_BASE_ENV, **(extra or {})}.items():
+        monkeypatch.setenv(k, v)
+
+
+def test_docs_hidden_when_flag_disabled(monkeypatch):
+    _set_env(monkeypatch, {"API_DOCS_ENABLED": "false"})
+    get_settings.cache_clear()
+    import app.main as m
+
+    importlib.reload(m)
+    client = TestClient(m.app, raise_server_exceptions=False)
+    assert client.get("/docs").status_code == 404
+    assert client.get("/redoc").status_code == 404
+    assert client.get("/openapi.json").status_code == 404
+    assert client.get("/api/v1/health").status_code == 200
+    get_settings.cache_clear()
+
+
+def test_docs_visible_when_flag_enabled(monkeypatch):
+    _set_env(monkeypatch, {"API_DOCS_ENABLED": "true"})
+    get_settings.cache_clear()
+    import app.main as m
+
+    importlib.reload(m)
+    client = TestClient(m.app, raise_server_exceptions=False)
+    assert client.get("/docs").status_code == 200
+    assert client.get("/redoc").status_code == 200
+    assert client.get("/openapi.json").status_code == 200
+    get_settings.cache_clear()

api/tests/integration/test_upload.py

@@ -132,6 +132,10 @@ async def test_upload_returns_thumbnail_key(authed_client):
     assert "thumbnail_key" in body
     assert body["thumbnail_key"] is not None
     assert body["thumbnail_key"].endswith("-thumb")
+    assert "file_url" in body
+    assert body["file_url"].startswith("/api/v1/images/")
+    assert "thumbnail_url" in body
+    assert body["thumbnail_url"].startswith("/api/v1/images/")
 
 
 @pytest.mark.asyncio
@@ -172,3 +176,6 @@ async def test_upload_succeeds_when_thumbnail_fails(authed_client):
     assert response.status_code in (200, 201)
     body = response.json()
     assert body["thumbnail_key"] is None
+    assert "file_url" in body
+    assert body["file_url"].startswith("/api/v1/images/")
+    assert body["thumbnail_url"] is None

api/tests/unit/test_config.py

@@ -59,3 +59,39 @@ def test_settings_jwt_expiry_override(monkeypatch):
 
     s = config_module.Settings()
     assert s.jwt_expiry_seconds == 3600
+
+
+def test_api_docs_enabled_default(monkeypatch):
+    _apply_env(monkeypatch)
+
+    import importlib
+
+    import app.config as config_module
+    importlib.reload(config_module)
+
+    s = config_module.Settings()
+    assert s.api_docs_enabled is True
+
+
+def test_api_docs_enabled_false(monkeypatch):
+    _apply_env(monkeypatch, {"API_DOCS_ENABLED": "false"})
+
+    import importlib
+
+    import app.config as config_module
+    importlib.reload(config_module)
+
+    s = config_module.Settings()
+    assert s.api_docs_enabled is False
+
+
+def test_api_docs_invalid_value_defaults_to_enabled(monkeypatch):
+    _apply_env(monkeypatch, {"API_DOCS_ENABLED": "not-a-bool"})
+
+    import importlib
+
+    import app.config as config_module
+    importlib.reload(config_module)
+
+    s = config_module.Settings()
+    assert s.api_docs_enabled is True

api/tests/unit/test_rate_limiter.py

@@ -80,10 +80,17 @@ def test_get_client_ip_no_trusted_networks_returns_peer():
     assert get_client_ip(req, []) == "203.0.113.1"
 
 
-def test_get_client_ip_trusted_peer_uses_xff():
-    req = make_request("10.0.0.1", {"X-Forwarded-For": "203.0.113.5"})
+def test_get_client_ip_trusted_peer_uses_real_ip():
+    req = make_request("10.0.0.1", {"X-Real-IP": "203.0.113.9"})
     nets = [ipaddress.ip_network("10.0.0.0/8")]
-    assert get_client_ip(req, nets) == "203.0.113.5"
+    assert get_client_ip(req, nets) == "203.0.113.9"
+
+
+def test_get_client_ip_real_ip_wins_over_xff():
+    # Regression: spoofed XFF must not override nginx-set X-Real-IP.
+    req = make_request("10.0.0.1", {"X-Real-IP": "203.0.113.9", "X-Forwarded-For": "1.2.3.4"})
+    nets = [ipaddress.ip_network("10.0.0.0/8")]
+    assert get_client_ip(req, nets) == "203.0.113.9"
 
 
 def test_get_client_ip_untrusted_peer_ignores_xff():
@@ -92,7 +99,7 @@ def test_get_client_ip_untrusted_peer_ignores_xff():
     assert get_client_ip(req, nets) == "8.8.8.8"
 
 
-def test_get_client_ip_trusted_peer_falls_back_to_real_ip():
-    req = make_request("10.0.0.1", {"X-Real-IP": "203.0.113.9"})
+def test_get_client_ip_trusted_peer_falls_back_to_xff_when_no_real_ip():
+    req = make_request("10.0.0.1", {"X-Forwarded-For": "203.0.113.5"})
     nets = [ipaddress.ip_network("10.0.0.0/8")]
-    assert get_client_ip(req, nets) == "203.0.113.9"
+    assert get_client_ip(req, nets) == "203.0.113.5"

api/tests/unit/test_url_construction.py

@@ -0,0 +1,65 @@
+import uuid
+from unittest.mock import MagicMock
+
+import pytest
+
+from app.routers.images import _image_to_dict
+
+
+def _make_image(*, thumbnail_key=None):
+    img = MagicMock()
+    img.id = uuid.UUID("00000000-0000-0000-0000-000000000001")
+    img.hash = "abc123"
+    img.filename = "test.jpg"
+    img.mime_type = "image/jpeg"
+    img.size_bytes = 1024
+    img.width = 100
+    img.height = 100
+    img.storage_key = "abc123storagekey"
+    img.thumbnail_key = thumbnail_key
+    img.created_at.isoformat.return_value = "2026-05-09T00:00:00"
+    img.tags = []
+    return img
+
+
+def test_cdn_configured_with_thumbnail():
+    img = _make_image(thumbnail_key="abc123storagekey-thumb")
+    result = _image_to_dict(img, cdn_base="https://cdn.example.com")
+    assert result["file_url"] == "https://cdn.example.com/abc123storagekey"
+    assert result["thumbnail_url"] == "https://cdn.example.com/abc123storagekey-thumb"
+
+
+def test_cdn_configured_no_thumbnail():
+    img = _make_image(thumbnail_key=None)
+    result = _image_to_dict(img, cdn_base="https://cdn.example.com")
+    assert result["file_url"] == "https://cdn.example.com/abc123storagekey"
+    assert result["thumbnail_url"] is None
+
+
+def test_no_cdn_with_thumbnail():
+    img = _make_image(thumbnail_key="abc123storagekey-thumb")
+    result = _image_to_dict(img, cdn_base=None)
+    assert result["file_url"] == "/api/v1/images/00000000-0000-0000-0000-000000000001/file"
+    assert result["thumbnail_url"] == "/api/v1/images/00000000-0000-0000-0000-000000000001/thumbnail"
+
+
+def test_no_cdn_no_thumbnail():
+    img = _make_image(thumbnail_key=None)
+    result = _image_to_dict(img, cdn_base=None)
+    assert result["file_url"] == "/api/v1/images/00000000-0000-0000-0000-000000000001/file"
+    assert result["thumbnail_url"] is None
+
+
+def test_cdn_trailing_slash_normalised():
+    img = _make_image(thumbnail_key="abc123storagekey-thumb")
+    result = _image_to_dict(img, cdn_base="https://cdn.example.com/")
+    assert result["file_url"] == "https://cdn.example.com/abc123storagekey"
+    assert result["thumbnail_url"] == "https://cdn.example.com/abc123storagekey-thumb"
+    assert "//" not in result["file_url"].replace("https://", "")
+
+
+def test_cdn_trailing_whitespace_normalised():
+    img = _make_image(thumbnail_key="abc123storagekey-thumb")
+    result = _image_to_dict(img, cdn_base="https://cdn.example.com  ")
+    assert result["file_url"] == "https://cdn.example.com/abc123storagekey"
+    assert result["thumbnail_url"] == "https://cdn.example.com/abc123storagekey-thumb"

k8s/api/deployment.yaml

@@ -0,0 +1,52 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: api
+  namespace: reactbin
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: api
+  template:
+    metadata:
+      labels:
+        app: api
+    spec:
+      initContainers:
+        - name: migrate
+          image: git.juggalol.com/juggalol/reactbin-api:v1.3.1
+          command: ["alembic", "upgrade", "head"]
+          workingDir: /app
+          envFrom:
+            - secretRef:
+                name: api-env
+          securityContext:
+            runAsNonRoot: true
+            runAsUser: 1001
+      containers:
+        - name: api
+          image: git.juggalol.com/juggalol/reactbin-api:v1.3.1
+          ports:
+            - containerPort: 8000
+          envFrom:
+            - secretRef:
+                name: api-env
+          env:
+            - name: API_DOCS_ENABLED
+              value: "false"
+          livenessProbe:
+            httpGet:
+              path: /api/v1/health
+              port: 8000
+            initialDelaySeconds: 10
+            periodSeconds: 30
+          readinessProbe:
+            httpGet:
+              path: /api/v1/health
+              port: 8000
+            initialDelaySeconds: 5
+            periodSeconds: 10
+          securityContext:
+            runAsNonRoot: true
+            runAsUser: 1001

k8s/api/service.yaml

@@ -0,0 +1,13 @@
+apiVersion: v1
+kind: Service
+metadata:
+  name: api
+  namespace: reactbin
+spec:
+  type: ClusterIP
+  selector:
+    app: api
+  ports:
+    - name: http
+      port: 8000
+      targetPort: 8000

k8s/ingress.yaml

@@ -0,0 +1,34 @@
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  name: reactbin
+  namespace: reactbin
+  annotations:
+    cert-manager.io/cluster-issuer: letsencrypt-prod
+    kubernetes.io/tls-acme: "true"
+    nginx.ingress.kubernetes.io/ssl-redirect: "true"
+    nginx.ingress.kubernetes.io/proxy-body-size: "52m"
+spec:
+  ingressClassName: nginx-public
+  tls:
+    - hosts:
+        - reactbin.juggalol.com
+      secretName: reactbin-tls
+  rules:
+    - host: reactbin.juggalol.com
+      http:
+        paths:
+          - path: /api/
+            pathType: Prefix
+            backend:
+              service:
+                name: api
+                port:
+                  number: 8000
+          - path: /
+            pathType: Prefix
+            backend:
+              service:
+                name: ui
+                port:
+                  number: 8080

k8s/minio/init-job.yaml

@@ -0,0 +1,24 @@
+apiVersion: batch/v1
+kind: Job
+metadata:
+  name: minio-init
+  namespace: reactbin
+spec:
+  template:
+    spec:
+      restartPolicy: OnFailure
+      containers:
+        - name: mc
+          image: minio/mc:latest
+          # mc runs as root by default; FR-013 exception documented in spec
+          securityContext:
+            runAsNonRoot: false
+          command:
+            - sh
+            - -c
+            - |
+              mc alias set local http://minio:9000 "$MINIO_ROOT_USER" "$MINIO_ROOT_PASSWORD"
+              mc mb --ignore-existing local/reactbin
+          envFrom:
+            - secretRef:
+                name: minio-credentials

k8s/minio/service.yaml

@@ -0,0 +1,16 @@
+apiVersion: v1
+kind: Service
+metadata:
+  name: minio
+  namespace: reactbin
+spec:
+  type: ClusterIP
+  selector:
+    app: minio
+  ports:
+    - name: api
+      port: 9000
+      targetPort: 9000
+    - name: console
+      port: 9001
+      targetPort: 9001

k8s/minio/statefulset.yaml

@@ -0,0 +1,59 @@
+apiVersion: apps/v1
+kind: StatefulSet
+metadata:
+  name: minio
+  namespace: reactbin
+spec:
+  serviceName: minio
+  replicas: 1
+  selector:
+    matchLabels:
+      app: minio
+  template:
+    metadata:
+      labels:
+        app: minio
+    spec:
+      securityContext:
+        runAsNonRoot: true
+        runAsUser: 1000
+        runAsGroup: 1000
+        fsGroup: 1000
+      containers:
+        - name: minio
+          image: minio/minio:latest
+          args:
+            - server
+            - /data
+            - --console-address
+            - ":9001"
+          ports:
+            - containerPort: 9000
+            - containerPort: 9001
+          envFrom:
+            - secretRef:
+                name: minio-credentials
+          livenessProbe:
+            httpGet:
+              path: /minio/health/live
+              port: 9000
+            initialDelaySeconds: 10
+            periodSeconds: 30
+          readinessProbe:
+            httpGet:
+              path: /minio/health/ready
+              port: 9000
+            initialDelaySeconds: 5
+            periodSeconds: 10
+          volumeMounts:
+            - name: data
+              mountPath: /data
+  volumeClaimTemplates:
+    - metadata:
+        name: data
+      spec:
+        accessModes:
+          - ReadWriteOnce
+        resources:
+          requests:
+            storage: 10Gi

k8s/namespace.yaml

@@ -0,0 +1,4 @@
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: reactbin

k8s/ui/deployment.yaml

@@ -0,0 +1,29 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: ui
+  namespace: reactbin
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: ui
+  template:
+    metadata:
+      labels:
+        app: ui
+    spec:
+      containers:
+        - name: ui
+          image: git.juggalol.com/juggalol/reactbin-ui:v1.3.1
+          ports:
+            - containerPort: 8080
+          livenessProbe:
+            httpGet:
+              path: /
+              port: 8080
+            initialDelaySeconds: 10
+            periodSeconds: 30
+          securityContext:
+            runAsNonRoot: true
+            runAsUser: 101  # nginxinc/nginx-unprivileged default UID

k8s/ui/service.yaml

@@ -0,0 +1,13 @@
+apiVersion: v1
+kind: Service
+metadata:
+  name: ui
+  namespace: reactbin
+spec:
+  type: ClusterIP
+  selector:
+    app: ui
+  ports:
+    - name: http
+      port: 8080
+      targetPort: 8080

k8s/vault/api-secret.yaml

@@ -0,0 +1,18 @@
+apiVersion: secrets.hashicorp.com/v1beta1
+kind: VaultStaticSecret
+metadata:
+  name: api-secret
+  namespace: reactbin
+spec:
+  vaultAuthRef: reactbin-vault-auth
+  mount: kv
+  type: kv-v2
+  # Required Vault keys at this path:
+  #   DATABASE_URL, JWT_SECRET_KEY, OWNER_USERNAME, OWNER_PASSWORD,
+  #   S3_ENDPOINT_URL, S3_BUCKET_NAME, S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY,
+  #   API_BASE_URL
+  path: reactbin/api/config
+  refreshAfter: 1h
+  destination:
+    name: api-env
+    create: true

k8s/vault/minio-secret.yaml

@@ -0,0 +1,16 @@
+apiVersion: secrets.hashicorp.com/v1beta1
+kind: VaultStaticSecret
+metadata:
+  name: minio-secret
+  namespace: reactbin
+spec:
+  vaultAuthRef: reactbin-vault-auth
+  mount: kv
+  type: kv-v2
+  # Required Vault keys at this path:
+  #   MINIO_ROOT_USER, MINIO_ROOT_PASSWORD
+  path: reactbin/minio/credentials
+  refreshAfter: 1h
+  destination:
+    name: minio-credentials
+    create: true

k8s/vault/vault-auth.yaml

@@ -0,0 +1,22 @@
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+  name: vso-reactbin
+  namespace: reactbin
+---
+apiVersion: secrets.hashicorp.com/v1beta1
+kind: VaultAuth
+metadata:
+  name: reactbin-vault-auth
+  namespace: reactbin
+spec:
+  method: kubernetes
+  mount: kubernetes
+  kubernetes:
+    # The operator must create this role in Vault and bind it to the
+    # default service account in the reactbin namespace with read access
+    # to both reactbin/api/config and reactbin/minio/credentials.
+    role: vso-reactbin
+    serviceAccount: vso-reactbin
+    audiences:
+      - vault

scripts/test_lockout.sh

@@ -0,0 +1,67 @@
+#!/usr/bin/env bash
+#
+# Test reactbin's login rate limiter and demonstrate the XFF injection bypass.
+#
+# Phase 1: Send 6 bad login attempts in quick succession.
+#   Attempts 1-5 should return 401 (invalid credentials).
+#   Attempt 6 should return 429 (rate limited) — the limiter blocks after
+#   max_failures=5 within the window.
+#
+# Phase 2: Send a 7th bad attempt with a spoofed X-Forwarded-For header
+#   pointing at a different IP. If the lockout keys correctly on the trusted
+#   client IP, this should still return 429 (same client, still locked).
+#   If reactbin trusts client-supplied XFF blindly, this would return 401
+#   instead — the spoof would make the request look like a different client
+#   that hasn't accumulated failures.
+#
+# Interpretation:
+#   - 429 on attempt 7  → lockout is correctly identifying the client
+#   - 401 on attempt 7  → XFF injection succeeded; server treated us as a
+#                          new client because we set a fake XFF
+#
+# Note: this script is ONLY useful when run against the public origin path
+# where XFF spoofing is potentially possible. It does not exercise the
+# Cloudflare-proxied path because Cloudflare strips/replaces XFF before
+# forwarding to origin.
+
+set -u
+
+URL="${URL:-https://reactbin.juggalol.com/api/v1/auth/token}"
+SPOOFED_IP="${SPOOFED_IP:-198.51.100.99}"  # TEST-NET-2, never routed
+USERNAME="${USERNAME:-not-a-real-user}"
+PASSWORD="${PASSWORD:-not-a-real-password}"
+
+# JSON body for a bad login. Username/password chosen to be obviously fake;
+# adjust if your auth provider has its own validation that would 400 instead
+# of 401 on these values.
+BODY=$(printf '{"username":"%s","password":"%s"}' "$USERNAME" "$PASSWORD")
+
+echo "Target: $URL"
+echo "Body:   $BODY"
+echo
+
+echo "=== Phase 1: 6 bad logins from real client IP ==="
+for i in 1 2 3 4 5 6; do
+    code=$(curl -sS -o /dev/null -w '%{http_code}' \
+        -X POST \
+        -H 'Content-Type: application/json' \
+        --data "$BODY" \
+        "$URL")
+    echo "Attempt $i: HTTP $code"
+done
+
+echo
+echo "=== Phase 2: 7th attempt with spoofed X-Forwarded-For ==="
+echo "Setting X-Forwarded-For: $SPOOFED_IP"
+code=$(curl -sS -o /dev/null -w '%{http_code}' \
+    -X POST \
+    -H 'Content-Type: application/json' \
+    -H "X-Forwarded-For: $SPOOFED_IP" \
+    --data "$BODY" \
+    "$URL")
+echo "Attempt 7: HTTP $code"
+
+echo
+echo "Interpretation:"
+echo "  Attempt 7 = 429  → lockout correctly tracks real client; XFF spoof ineffective"
+echo "  Attempt 7 = 401  → XFF spoof succeeded; server believed the fake client IP"

specs/012-api-docs-gate/checklists/requirements.md

@@ -0,0 +1,34 @@
+# Specification Quality Checklist: API Documentation Visibility Gate
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2026-05-07
+**Feature**: [spec.md](../spec.md)
+
+## Content Quality
+
+- [X] No implementation details (languages, frameworks, APIs)
+- [X] Focused on user value and business needs
+- [X] Written for non-technical stakeholders
+- [X] All mandatory sections completed
+
+## Requirement Completeness
+
+- [X] No [NEEDS CLARIFICATION] markers remain
+- [X] Requirements are testable and unambiguous
+- [X] Success criteria are measurable
+- [X] Success criteria are technology-agnostic (no implementation details)
+- [X] All acceptance scenarios are defined
+- [X] Edge cases are identified
+- [X] Scope is clearly bounded
+- [X] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [X] All functional requirements have clear acceptance criteria
+- [X] User scenarios cover primary flows
+- [X] Feature meets measurable outcomes defined in Success Criteria
+- [X] No implementation details leak into specification
+
+## Notes
+
+- All items pass. Spec is ready for `/speckit-plan`.

specs/012-api-docs-gate/contracts/docs-endpoints.md

@@ -0,0 +1,40 @@
+# Contract: API Documentation Endpoints
+
+These three endpoints exist in FastAPI by default. This feature makes their availability conditional on a runtime configuration flag.
+
+## Affected Endpoints
+
+| Endpoint | Default path | Purpose |
+|----------|-------------|---------|
+| Swagger UI | `GET /docs` | Interactive browser-based API documentation |
+| ReDoc UI | `GET /redoc` | Alternative read-only API documentation |
+| OpenAPI schema | `GET /openapi.json` | Raw JSON schema of the entire API surface |
+
+## Behaviour by Flag State
+
+### `API_DOCS_ENABLED=true` (default)
+
+All three endpoints respond exactly as they did before this feature. No change.
+
+| Endpoint | Response |
+|----------|----------|
+| `GET /docs` | `200 OK` — Swagger UI HTML |
+| `GET /redoc` | `200 OK` — ReDoc UI HTML |
+| `GET /openapi.json` | `200 OK` — OpenAPI schema JSON |
+
+### `API_DOCS_ENABLED=false`
+
+All three endpoints are unregistered. Requests fall through to the framework's default 404 handler.
+
+| Endpoint | Response |
+|----------|----------|
+| `GET /docs` | `404 Not Found` |
+| `GET /redoc` | `404 Not Found` |
+| `GET /openapi.json` | `404 Not Found` |
+
+## Invariants
+
+- All other endpoints are unaffected in both flag states.
+- The `GET /api/v1/health` endpoint always returns `200 OK` regardless of the flag.
+- Internal OpenAPI schema generation (used for request/response validation) is not disabled — only the HTTP routes serving it are removed.
+- The flag is read once at application startup. A running process does not respond to live changes; a restart is required.

specs/012-api-docs-gate/plan.md

@@ -0,0 +1,138 @@
+# Implementation Plan: API Documentation Visibility Gate
+
+**Branch**: `012-api-docs-gate` | **Date**: 2026-05-07 | **Spec**: [spec.md](spec.md)
+**Input**: Feature specification from `specs/012-api-docs-gate/spec.md`
+
+## Summary
+
+Add `API_DOCS_ENABLED` (boolean, default `true`) to `app/config.py`. When `false`, pass `docs_url=None`, `redoc_url=None`, `openapi_url=None` to the `FastAPI()` constructor in `app/main.py`, making all three documentation routes return 404. A field validator provides graceful fallback for invalid flag values. Two new integration tests verify both flag states; the existing unit test suite is extended with two settings tests.
+
+## Technical Context
+
+**Language/Version**: Python 3.12
+**Primary Dependencies**: FastAPI (constructor params), pydantic-settings (field validator)
+**Storage**: None
+**Testing**: pytest unit (`api/tests/unit/test_config.py`), pytest + ASGI test client (`api/tests/integration/test_docs_gate.py`)
+**Target Platform**: API container (same as existing)
+**Project Type**: Web service configuration change
+**Performance Goals**: No measurable impact — one boolean read at startup
+**Constraints**: Default must be `true` (backwards compatible); invalid env var value must not crash startup; no other routes affected
+**Scale/Scope**: Three files changed (`config.py`, `main.py`, `.env.example`); one new test file; one existing test file extended
+
+## Constitution Check
+
+| Principle | Requirement | Status |
+|-----------|-------------|--------|
+| §5.1 TDD | Failing tests written before implementation | ✅ Tasks order tests first |
+| §5.2 Integration tests | New integration tests follow existing pattern | ✅ |
+| §5.3 Tests next to code | `api/tests/unit/` and `api/tests/integration/` | ✅ |
+| §5.4 CI before done | All tests pass before task marked done | ✅ |
+| §7.2 Env config | Flag via environment variable, not hardcoded | ✅ |
+| §7.3 Linting | `ruff` passes on all changed files | ✅ Enforced in polish task |
+| §2.6 No speculative abstraction | One boolean field, no plugin system | ✅ |
+
+**No violations. All gates pass.**
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/012-api-docs-gate/
+├── plan.md                    ← this file
+├── research.md                ← 6 decisions
+├── contracts/
+│   └── docs-endpoints.md     ← behaviour contract for 3 affected endpoints
+├── quickstart.md              ← 4 test scenarios
+└── tasks.md                  ← generated by /speckit-tasks
+```
+
+### Source Code Changes
+
+```text
+api/
+├── app/
+│   ├── config.py              ← MODIFIED: add api_docs_enabled field + validator
+│   └── main.py                ← MODIFIED: conditional docs_url/redoc_url/openapi_url
+├── tests/
+│   ├── unit/
+│   │   └── test_config.py     ← MODIFIED: 2 new tests for api_docs_enabled
+│   └── integration/
+│       └── test_docs_gate.py  ← NEW: 2 integration tests (disabled + enabled)
+
+.env.example                   ← MODIFIED: document API_DOCS_ENABLED
+```
+
+## Implementation Design
+
+### `app/config.py` — new field with graceful fallback validator
+
+```python
+from pydantic import field_validator
+
+class Settings(BaseSettings):
+    # ... existing fields ...
+    api_docs_enabled: bool = True
+
+    @field_validator('api_docs_enabled', mode='before')
+    @classmethod
+    def coerce_docs_enabled(cls, v):
+        if isinstance(v, bool):
+            return v
+        try:
+            from pydantic import TypeAdapter
+            return TypeAdapter(bool).validate_python(v)
+        except Exception:
+            return True  # FR-007: invalid value → safe default (enabled)
+```
+
+### `app/main.py` — conditional docs URLs
+
+```python
+_settings = get_settings()
+
+app = FastAPI(
+    title="Reactbin API",
+    version="1.0.0",
+    lifespan=lifespan,
+    docs_url="/docs" if _settings.api_docs_enabled else None,
+    redoc_url="/redoc" if _settings.api_docs_enabled else None,
+    openapi_url="/openapi.json" if _settings.api_docs_enabled else None,
+)
+```
+
+### Integration test pattern
+
+The `app` object is constructed at module import time. Tests reload the module with the env var pre-set:
+
+```python
+def test_docs_disabled(monkeypatch, _base_env):
+    monkeypatch.setenv("API_DOCS_ENABLED", "false")
+    from app.config import get_settings
+    get_settings.cache_clear()
+    import importlib, app.main as m
+    importlib.reload(m)
+    client = TestClient(m.app)
+    assert client.get("/docs").status_code == 404
+    assert client.get("/redoc").status_code == 404
+    assert client.get("/openapi.json").status_code == 404
+    assert client.get("/api/v1/health").status_code == 200
+```
+
+`get_settings.cache_clear()` is required before the reload so the new env var is picked up.
+
+### `.env.example` addition
+
+```bash
+# API documentation endpoints (Swagger UI, ReDoc, OpenAPI schema)
+# Set to false in production to avoid exposing the API surface publicly.
+API_DOCS_ENABLED=true
+```
+
+## Dependencies & Risks
+
+| Item | Risk | Mitigation |
+|------|------|------------|
+| `@lru_cache` on `get_settings()` | Tests may pick up cached settings across reloads | Always call `get_settings.cache_clear()` before reloading `app.main` in tests |
+| Module-level `get_settings()` in `main.py` | Import fails if required settings are absent (pre-existing behaviour) | Not a new risk; same as today |
+| `openapi_url=None` | Disables HTTP route but not internal schema generation | Intentional; request validation is unaffected |

specs/012-api-docs-gate/quickstart.md

@@ -0,0 +1,42 @@
+# Quickstart: API Documentation Visibility Gate
+
+## Verify docs are disabled
+
+```bash
+# Start API with docs disabled
+API_DOCS_ENABLED=false uvicorn app.main:app --reload
+
+curl -s -o /dev/null -w "%{http_code}" http://localhost:8000/docs        # → 404
+curl -s -o /dev/null -w "%{http_code}" http://localhost:8000/redoc       # → 404
+curl -s -o /dev/null -w "%{http_code}" http://localhost:8000/openapi.json # → 404
+curl -s -o /dev/null -w "%{http_code}" http://localhost:8000/api/v1/health # → 200
+```
+
+## Verify docs are enabled (default)
+
+```bash
+# Start API without the flag (or with it set to true)
+uvicorn app.main:app --reload
+
+curl -s -o /dev/null -w "%{http_code}" http://localhost:8000/docs         # → 200
+curl -s -o /dev/null -w "%{http_code}" http://localhost:8000/redoc        # → 200
+curl -s -o /dev/null -w "%{http_code}" http://localhost:8000/openapi.json # → 200
+```
+
+## Integration test scenarios
+
+### Scenario 1: flag disabled — all three docs endpoints return 404
+
+Start a test client with `API_DOCS_ENABLED=false` injected into settings. Assert each of the three endpoint paths returns 404. Assert `/api/v1/health` returns 200.
+
+### Scenario 2: flag enabled (default) — docs endpoints return 200
+
+Start a test client without the flag (or with `API_DOCS_ENABLED=true`). Assert each of the three endpoint paths returns 200.
+
+### Scenario 3: invalid flag value — app starts, docs enabled
+
+Set `API_DOCS_ENABLED=not-a-bool`. The app must start without error. Docs must be accessible (safe fallback to enabled).
+
+### Scenario 4: flag absent — docs enabled (backwards compatibility)
+
+Start the app with no `API_DOCS_ENABLED` variable set. Assert docs endpoints return 200 — identical to pre-feature behaviour.

specs/012-api-docs-gate/research.md

@@ -0,0 +1,36 @@
+# Research: API Documentation Visibility Gate
+
+## Decision 1: Env var name
+
+**Decision**: `API_DOCS_ENABLED` (boolean, default `true`)
+**Rationale**: Consistent with the existing `API_BASE_URL` naming convention in the project. The positive-phrasing default (`true` = enabled) preserves backwards compatibility — existing deployments that don't set the variable get the same behaviour as today.
+**Alternatives considered**: `HIDE_API_DOCS=false` (negative phrasing) — inverted booleans are error-prone and confusing in `.env` files; `DOCS_ENABLED` — too generic, could collide with other tools in a multi-service env file.
+
+## Decision 2: FastAPI docs suppression mechanism
+
+**Decision**: Pass `docs_url=None`, `redoc_url=None`, `openapi_url=None` to the `FastAPI()` constructor when the flag is disabled.
+**Rationale**: This is the official FastAPI-supported mechanism. Setting these to `None` causes FastAPI to register no routes for those paths — requests to them fall through to the default 404 handler. The internal OpenAPI schema is still generated in memory (for request validation), but no HTTP route exposes it.
+**Alternatives considered**: Route-level middleware that intercepts and returns 404 — more complex, not the canonical approach; removing routers at runtime — impossible, routers are registered at import time.
+
+## Decision 3: Settings read at module level
+
+**Decision**: Read `get_settings()` once at module import time in `main.py` to configure the `FastAPI()` constructor.
+**Rationale**: `FastAPI()` is instantiated at module level; the docs URL parameters must be known at that point. `get_settings()` is already `@lru_cache` so calling it at module level is cheap and consistent with calling it again inside `lifespan`. Tests that need to change the flag must reload the module or override `get_settings`.
+**Alternatives considered**: Lazy initialisation of `app` inside a factory function — would require restructuring `main.py` and all imports; not worth the complexity for this change.
+
+## Decision 4: Graceful fallback for invalid flag values (FR-007)
+
+**Decision**: Add a `@field_validator('api_docs_enabled', mode='before')` in `Settings` that wraps Pydantic's bool coercion in a try/except and returns `True` on any `ValueError`.
+**Rationale**: Pydantic v2 raises `ValidationError` for unrecognised boolean strings (e.g., `API_DOCS_ENABLED=maybe`). FR-007 requires the app to start rather than fail. The validator intercepts the invalid value before Pydantic's own coercion and returns the safe default.
+**Alternatives considered**: Using `Optional[bool] = True` without a validator — Pydantic would still raise on invalid input; using `str` field with manual parsing — duplicates Pydantic's boolean parsing logic unnecessarily.
+
+## Decision 5: Integration test approach
+
+**Decision**: Test both enabled and disabled states by overriding `get_settings` in integration tests using `app.dependency_overrides`, or by constructing a local `FastAPI` app instance with the appropriate `docs_url`/`redoc_url`/`openapi_url` values.
+**Rationale**: The `app` in `app.main` is created at import time. Since the unit tests already use `monkeypatch` + `importlib.reload` for config changes, the integration tests for docs visibility can follow the same pattern — reload `app.main` with the env var set before importing `app`. Alternatively, test the URL routing behaviour directly by constructing a minimal test app.
+**Alternatives considered**: Patching `app.docs_url` after import — FastAPI does not re-register routes when these attributes are changed post-construction; no effect on routing.
+
+## Decision 6: Production documentation
+
+**Decision**: Update `.env.example` to include `API_DOCS_ENABLED=true` with a comment recommending `false` for production. No changes to `api/Dockerfile.prod` (env vars are supplied by the deployment environment, not the image).
+**Rationale**: The Dockerfile intentionally contains no runtime secrets or config. The `.env.example` is the canonical documentation for operators. A comment is sufficient; the production Dockerfile.prod already has no docs-related config.

specs/012-api-docs-gate/spec.md

@@ -0,0 +1,80 @@
+# Feature Specification: API Documentation Visibility Gate
+
+**Feature Branch**: `012-api-docs-gate`
+**Created**: 2026-05-07
+**Status**: Draft
+**Input**: User description: "Add an environment variable flag to disable the FastAPI Swagger and ReDoc documentation endpoints (and the raw OpenAPI schema) in production. When disabled, all three endpoints return 404. When enabled (the default), behaviour is unchanged. The flag should be off by default in production and on by default in development."
+
+## User Scenarios & Testing *(mandatory)*
+
+### User Story 1 - Documentation Hidden in Production (Priority: P1)
+
+An operator deploys the API to a production environment and wants to ensure that the interactive documentation UI and the raw API schema are not publicly reachable. Setting a configuration flag causes all three documentation endpoints to return "not found", as if they do not exist.
+
+**Why this priority**: Exposing the full API schema and interactive console to anonymous users in production reveals the attack surface of the application. Hiding it is a low-effort, high-value hardening step.
+
+**Independent Test**: Start the API with the flag set to disabled. Request each of the three documentation endpoints. All three must return 404.
+
+**Acceptance Scenarios**:
+
+1. **Given** the API is started with documentation disabled, **When** a client requests the interactive documentation UI, **Then** the response is 404 Not Found.
+2. **Given** the API is started with documentation disabled, **When** a client requests the alternative documentation UI, **Then** the response is 404 Not Found.
+3. **Given** the API is started with documentation disabled, **When** a client requests the raw OpenAPI schema endpoint, **Then** the response is 404 Not Found.
+4. **Given** the API is started with documentation disabled, **When** a client requests any other API endpoint (e.g., the health check), **Then** the response is unaffected — normal behaviour continues.
+
+---
+
+### User Story 2 - Documentation Available in Development (Priority: P2)
+
+A developer runs the API locally without setting the flag. The documentation endpoints remain fully accessible — no change in behaviour from before this feature.
+
+**Why this priority**: Developer productivity depends on the interactive docs being available during local development. The default must not break existing workflows.
+
+**Independent Test**: Start the API without the flag set (or with it explicitly enabled). Request each of the three documentation endpoints. All three must respond successfully with their normal content.
+
+**Acceptance Scenarios**:
+
+1. **Given** the API is started without the flag set, **When** a client requests any documentation endpoint, **Then** the response is the same as it was before this feature was introduced.
+2. **Given** the API is started with the flag explicitly set to enabled, **When** a client requests any documentation endpoint, **Then** the response is the same as it was before this feature was introduced.
+3. **Given** the flag is changed from enabled to disabled (or vice versa), **When** the API is restarted, **Then** the new state takes effect immediately with no other changes required.
+
+---
+
+### Edge Cases
+
+- What happens if the flag is set to an unrecognised value (e.g., a typo)?
+- What happens if the flag is absent entirely — is the default enabled or disabled?
+- Does disabling documentation affect any other behaviour (e.g., internal schema generation used for validation)?
+- If a monitoring tool scrapes the schema endpoint for API drift detection, does disabling break it?
+
+## Requirements *(mandatory)*
+
+### Functional Requirements
+
+- **FR-001**: The system MUST support a configuration flag that controls whether the API documentation endpoints are reachable.
+- **FR-002**: When the flag is set to disabled, all three documentation endpoints (interactive UI, alternative UI, and raw schema) MUST return 404 Not Found.
+- **FR-003**: When the flag is set to enabled, the behaviour of all three documentation endpoints MUST be identical to the behaviour before this feature was introduced.
+- **FR-004**: The flag MUST default to **enabled** when not explicitly set (preserving backwards compatibility for existing deployments).
+- **FR-005**: Disabling documentation MUST NOT affect any other API endpoint, including the health check, authentication, and all resource endpoints.
+- **FR-006**: The flag MUST be configurable via an environment variable without requiring a code change or rebuild.
+- **FR-007**: An unrecognised or missing flag value MUST fall back to the enabled default rather than causing a startup failure.
+- **FR-008**: The existing `.env.example` file MUST be updated to document the flag and its default value.
+- **FR-009**: The production environment configuration MUST set the flag to disabled by default.
+
+## Success Criteria *(mandatory)*
+
+### Measurable Outcomes
+
+- **SC-001**: With the flag disabled, all three documentation endpoints return 404, confirmed by automated test.
+- **SC-002**: With the flag enabled (or absent), all three documentation endpoints respond successfully, confirmed by automated test.
+- **SC-003**: All existing tests continue to pass — zero regressions introduced.
+- **SC-004**: The flag takes effect on restart with no other intervention required.
+- **SC-005**: The `.env.example` file documents the flag so any developer setting up the project discovers it without reading source code.
+
+## Assumptions
+
+- There are exactly three documentation-related endpoints to gate: the primary interactive UI, the alternative documentation UI, and the raw OpenAPI schema JSON. No other endpoints are affected.
+- The flag is read once at application startup; a running process does not need to respond to live changes.
+- Internal schema generation (used by the framework for request validation) is not affected by hiding the documentation endpoints — only the public-facing HTTP routes are removed.
+- The production Dockerfile (`api/Dockerfile.prod`) does not hardcode the flag; it is supplied via the deployment environment (docker-compose, Kubernetes secret, etc.).
+- "Off by default in production" means the recommended value for production is disabled, documented in `.env.example` and in the production docker-compose or deployment config; it does not mean the application auto-detects its environment.

specs/012-api-docs-gate/tasks.md

@@ -0,0 +1,100 @@
+# Tasks: API Documentation Visibility Gate
+
+**Input**: Design documents from `specs/012-api-docs-gate/`
+**Prerequisites**: plan.md ✅, spec.md ✅, research.md ✅, contracts/docs-endpoints.md ✅, quickstart.md ✅
+
+**Tests**: TDD is non-negotiable (§5.1). Failing tests are written before implementation code in each phase.
+
+**Organization**: No setup or foundational phases — this feature modifies three existing files and adds one new test file. Phase 3 (US1) covers the disable path; Phase 4 (US2) verifies the enable/default path using the same implementation; Phase 5 polishes.
+
+## Format: `[ID] [P?] [Story] Description`
+
+- **[P]**: Can run in parallel with other [P] tasks in the same phase
+- **[Story]**: Which user story this task belongs to
+- Exact file paths included in every task description
+
+---
+
+## Phase 3: User Story 1 — Documentation Hidden in Production (Priority: P1) 🎯 MVP
+
+**Goal**: When `API_DOCS_ENABLED=false`, all three documentation endpoints (`/docs`, `/redoc`, `/openapi.json`) return 404. All other endpoints are unaffected.
+
+**Independent Test**: `make test-unit` passes the new settings tests; `make test-integration` passes the new `test_docs_disabled` integration test.
+
+### Tests for User Story 1 (TDD — write first, confirm failure before T003)
+
+- [X] T001 [US1] Add three failing unit tests to `api/tests/unit/test_config.py` using the existing `_apply_env`/`_BASE_ENV` pattern:
+  1. `test_api_docs_enabled_default` — call `Settings()` with `_BASE_ENV` only (no `API_DOCS_ENABLED`); assert `s.api_docs_enabled is True`
+  2. `test_api_docs_enabled_false` — call `Settings()` with `_BASE_ENV` + `{"API_DOCS_ENABLED": "false"}`; assert `s.api_docs_enabled is False`
+  3. `test_api_docs_invalid_value_defaults_to_enabled` — call `Settings()` with `_BASE_ENV` + `{"API_DOCS_ENABLED": "not-a-bool"}`; assert `s.api_docs_enabled is True` (graceful fallback, FR-007)
+  All three tests fail before T003 because `api_docs_enabled` does not yet exist on `Settings`.
+
+- [X] T002 [US1] Create `api/tests/integration/test_docs_gate.py` with two failing integration tests; the file MUST set up a minimal app client using `from starlette.testclient import TestClient` and the `importlib.reload` + `get_settings.cache_clear()` pattern shown in plan.md:
+  1. `test_docs_hidden_when_flag_disabled(monkeypatch)` — set `API_DOCS_ENABLED=false` via monkeypatch + all required env vars (`DATABASE_URL`, `JWT_SECRET_KEY`, `OWNER_USERNAME`, `OWNER_PASSWORD`, `S3_ENDPOINT_URL`, `S3_BUCKET_NAME`, `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY`); call `get_settings.cache_clear()`; `importlib.reload(app.main)`; create `TestClient(app.main.app)`; assert `/docs` → 404, `/redoc` → 404, `/openapi.json` → 404, `/api/v1/health` → 200; after test, call `get_settings.cache_clear()` again as cleanup
+  2. `test_docs_visible_when_flag_enabled(monkeypatch)` — same setup but with `API_DOCS_ENABLED=true` (or omit it); assert `/docs` → 200, `/redoc` → 200, `/openapi.json` → 200
+  Both tests fail before T003/T004 because `api_docs_enabled` does not exist on `Settings`.
+
+### Implementation for User Story 1
+
+- [X] T003 [US1] Add `api_docs_enabled: bool = True` field and a `coerce_docs_enabled` field validator to the `Settings` class in `api/app/config.py`: the validator MUST use `mode='before'`, be a `@classmethod`, and wrap Pydantic bool coercion in a try/except that returns `True` on any exception (implements FR-007); import `field_validator` from `pydantic` at the top of the file; the field goes after the existing `login_trusted_proxy_ips` field.
+
+- [X] T004 [US1] Update `api/app/main.py`: before the `app = FastAPI(...)` call, add `_settings = get_settings()`; add `docs_url="/docs" if _settings.api_docs_enabled else None`, `redoc_url="/redoc" if _settings.api_docs_enabled else None`, and `openapi_url="/openapi.json" if _settings.api_docs_enabled else None` as keyword arguments to the `FastAPI()` constructor; the existing module-level defaults for `app.state` (after the `app = FastAPI(...)` line) are unchanged.
+
+- [X] T005 [US1] Verify TDD green for US1: run `cd api && python -m pytest tests/unit/ -v -k "docs"` and confirm all three new unit tests pass; then run `cd api && python -m pytest tests/unit/ -v` to confirm no regressions in the full 102-test unit suite.
+
+**Checkpoint**: US1 is complete. With `API_DOCS_ENABLED=false` the three docs endpoints return 404; all other endpoints are unaffected.
+
+---
+
+## Phase 4: User Story 2 — Documentation Available in Development (Priority: P2)
+
+**Goal**: Without the flag set (or with it set to `true`), docs endpoints behave identically to before this feature. Default is backwards compatible.
+
+**Independent Test**: `make test-integration` — the `test_docs_visible_when_flag_enabled` test written in T002 passes, confirming the enabled/default path.
+
+- [X] T006 [US2] Verify TDD green for US2: run `make test-integration` from `/workspace` and confirm all integration tests pass, including `test_docs_gate.py::test_docs_visible_when_flag_enabled` and the full existing suite (102 tests + 2 new = 104 total).
+
+**Checkpoint**: Both user stories verified. Flag disabled → 404; flag enabled or absent → unchanged behaviour.
+
+---
+
+## Phase 5: Polish & Cross-Cutting Concerns
+
+- [X] T007 Add documentation for `API_DOCS_ENABLED` to `/workspace/.env.example`: insert a new section after the `LOGIN_TRUSTED_PROXY_IPS` block with a comment and `API_DOCS_ENABLED=true`; the comment MUST note that this should be set to `false` in production to avoid publicly exposing the API schema
+
+- [X] T008 Run `ruff check api/app/config.py api/app/main.py api/tests/integration/test_docs_gate.py` from `/workspace/api` and fix any lint violations; then run `ruff check api/` to confirm the full API directory is clean
+
+---
+
+## Dependencies & Execution Order
+
+- T001 and T002 can run in parallel (different files, both TDD-red before implementation)
+- T003 must complete before T004 (main.py reads from config.py)
+- T005 after T003 and T004
+- T006 after T005
+- T007 and T008 can run in parallel (different files, after all tests pass)
+
+### Execution Order Summary
+
+```
+Step 1: T001 ∥ T002   (write failing tests — TDD red)
+Step 2: T003          (implement config.py — turns T001 green)
+Step 3: T004          (implement main.py — turns T002 green)
+Step 4: T005          (verify unit tests green)
+Step 5: T006          (verify integration tests green — regression gate)
+Step 6: T007 ∥ T008   (polish — .env.example + ruff)
+```
+
+---
+
+## Implementation Strategy
+
+### MVP (US1 + US2 — one implementation covers both)
+
+1. Write failing tests (T001, T002)
+2. Add `api_docs_enabled` to `config.py` (T003)
+3. Update `FastAPI()` constructor in `main.py` (T004)
+4. Verify all tests green (T005, T006)
+5. Polish (T007, T008)
+
+US1 and US2 share the same implementation — the flag controls both paths. There is no separate implementation for US2; the default value of `true` is the entire implementation of US2.

specs/013-k8s-manifests/checklists/requirements.md

@@ -0,0 +1,35 @@
+# Specification Quality Checklist: Kubernetes Production Manifests
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2026-05-07
+**Feature**: [spec.md](../spec.md)
+
+## Content Quality
+
+- [x] No implementation details (languages, frameworks, APIs)
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Success criteria are technology-agnostic (no implementation details)
+- [x] All acceptance scenarios are defined
+- [x] Edge cases are identified
+- [x] Scope is clearly bounded
+- [x] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [x] All functional requirements have clear acceptance criteria
+- [x] User scenarios cover primary flows
+- [x] Feature meets measurable outcomes defined in Success Criteria
+- [x] No implementation details leak into specification
+
+## Notes
+
+- FR-014 (migration files in production image) is a prerequisite code change to `Dockerfile.prod`, not a manifest. Included in scope as it is required for the init container to function.
+- Image tag placeholder strategy is documented in Assumptions; the specifics of tag substitution (kustomize, sed, etc.) are left to planning.

specs/013-k8s-manifests/contracts/operator-deploy.md

@@ -0,0 +1,59 @@
+# Contract: Operator Deployment Interface
+
+The manifests in `k8s/` define the operator's deployment interface — the inputs required before applying and the observable outputs after applying.
+
+## Pre-deployment Prerequisites (Operator-supplied)
+
+| Prerequisite | Details |
+|---|---|
+| Vault KV v2 secret at `reactbin/api/config` | Must contain keys: `DATABASE_URL`, `JWT_SECRET_KEY`, `OWNER_USERNAME`, `OWNER_PASSWORD`, `S3_ENDPOINT_URL`, `S3_BUCKET_NAME`, `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY`, `API_BASE_URL` |
+| Vault KV v2 secret at `reactbin/minio/credentials` | Must contain keys: `MINIO_ROOT_USER`, `MINIO_ROOT_PASSWORD` |
+| Vault Kubernetes auth role | A role in the Vault Kubernetes auth mount bound to the `default` service account in the `reactbin` namespace with read access to both paths above |
+| `VaultConnection` resource | Named `default` in the operator's VSO namespace pointing to the Vault server address |
+| External PostgreSQL database | A dedicated database and user created; `DATABASE_URL` in Vault reflects the credentials |
+| DNS | The production domain resolves to the cluster ingress IP |
+| `ClusterIssuer` | A cert-manager `ClusterIssuer` named `letsencrypt-prod` exists in the cluster |
+| Image tags | The operator substitutes the `latest` placeholder in `k8s/api/deployment.yaml` and `k8s/ui/deployment.yaml` with the real image tag before applying |
+
+## Apply Command
+
+```bash
+# Substitute image tags
+sed -i 's|reactbin-api:latest|reactbin-api:<tag>|g' k8s/api/deployment.yaml
+sed -i 's|reactbin-ui:latest|reactbin-ui:<tag>|g' k8s/ui/deployment.yaml
+
+# Apply all manifests
+kubectl apply -f k8s/
+```
+
+Applying is idempotent — safe to re-run on every deployment.
+
+## Observable Outputs (Post-apply)
+
+| Resource | Expected State |
+|---|---|
+| `Namespace/reactbin` | Active |
+| `Deployment/api` in `reactbin` | 1/1 Ready (init container completes first) |
+| `Deployment/ui` in `reactbin` | 1/1 Ready |
+| `StatefulSet/minio` in `reactbin` | 1/1 Ready |
+| `Job/minio-init-bucket` in `reactbin` | Completed |
+| `Secret/api-env` in `reactbin` | Created by VSO, populated with all API env keys |
+| `Secret/minio-credentials` in `reactbin` | Created by VSO, populated with MinIO root keys |
+| `Certificate/reactbin-tls` in `reactbin` | Issued (may take up to 2 minutes on first apply) |
+| `Ingress/reactbin` in `reactbin` | Address populated with cluster ingress IP |
+
+## Verification Commands
+
+```bash
+# All pods running
+kubectl get pods -n reactbin
+
+# API health
+curl -sf https://<domain>/api/v1/health
+
+# UI reachable
+curl -sf https://<domain>/
+
+# Docs correctly gated (should return 404)
+curl -o /dev/null -w "%{http_code}" https://<domain>/docs
+```

specs/013-k8s-manifests/plan.md

@@ -0,0 +1,238 @@
+# Implementation Plan: Kubernetes Production Manifests
+
+**Branch**: `013-k8s-manifests` | **Date**: 2026-05-07 | **Spec**: [spec.md](spec.md)
+**Input**: Feature specification from `specs/013-k8s-manifests/spec.md`
+
+## Summary
+
+Write Kubernetes manifests deploying Reactbin to k3s: a `Namespace`, API `Deployment` (with Alembic init container) + `Service`, UI `Deployment` + `Service`, a shared `Ingress` with Let's Encrypt TLS, a MinIO `StatefulSet` + `Service` + bucket-init `Job`, and three VSO CRDs (`VaultConnection`, `VaultAuth`, `VaultStaticSecret` × 2) to sync secrets from Vault. A small update to `api/Dockerfile.prod` includes Alembic migration files in the production image so the init container can run them.
+
+## Technical Context
+
+**Language/Version**: YAML (Kubernetes manifests); Python 3.12 (Dockerfile.prod touch)
+**Primary Dependencies**: Kubernetes 1.29+ API, nginx Ingress controller, cert-manager (ClusterIssuer `letsencrypt-prod`), Vault Secrets Operator (`secrets.hashicorp.com/v1beta1`), MinIO
+**Storage**: MinIO StatefulSet with ReadWriteOnce PVC (cluster default storage class); external PostgreSQL (operator-provisioned)
+**Testing**: `kubectl apply --dry-run=client` for schema validation; `yamllint` for formatting
+**Target Platform**: k3s cluster (Kubernetes 1.29+, Linux)
+**Performance Goals**: No measurable impact — manifests are declarative config, not runtime code
+**Constraints**: All secrets must come from Vault (no plaintext in manifests); all containers run non-root; MinIO is ClusterIP-only (no external Ingress)
+**Scale/Scope**: 11 YAML files across `k8s/`; one Dockerfile.prod change; one Makefile target
+
+## Constitution Check
+
+| Principle | Requirement | Status |
+|-----------|-------------|--------|
+| §5.1 TDD | Failing tests before implementation | ✅ Dry-run validation script written before manifests |
+| §5.4 CI before done | All tests pass before task marked done | ✅ kubectl dry-run + yamllint gate |
+| §7.2 Env config | No hardcoded secrets or hostnames | ✅ All secrets via VSO; domain is operator-substituted placeholder |
+| §7.3 Linting | `ruff` / linting passes | ✅ `yamllint` on all manifests |
+| §2.6 No speculative abstraction | No Kustomize overlays or Helm chart | ✅ Plain YAML, single environment |
+| §8 Scope boundaries | No multi-user, no OIDC, no OR/NOT tags | ✅ Not affected |
+
+**No violations. All gates pass.**
+
+*Post-design re-check*: The Dockerfile.prod change (FR-014) adds `alembic/` to the runtime stage only — no builder-stage change, no new dependencies, no behaviour change to the running API. Constitution unchanged.
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/013-k8s-manifests/
+├── plan.md                          ← this file
+├── research.md                      ← 8 decisions
+├── contracts/
+│   └── operator-deploy.md           ← prerequisites + verification commands
+├── quickstart.md                    ← deploy + verify + scenario walkthroughs
+└── tasks.md                         ← generated by /speckit-tasks
+```
+
+### Source Code Changes
+
+```text
+k8s/                                 ← NEW directory
+├── namespace.yaml                   ← Namespace: reactbin
+├── api/
+│   ├── deployment.yaml              ← Deployment: api (with alembic init container)
+│   └── service.yaml                 ← Service: api (ClusterIP, port 8000)
+├── ui/
+│   ├── deployment.yaml              ← Deployment: ui
+│   └── service.yaml                 ← Service: ui (ClusterIP, port 8080)
+├── ingress.yaml                     ← Ingress: /api/ → api, / → ui, TLS via cert-manager
+├── minio/
+│   ├── statefulset.yaml             ← StatefulSet: minio (volumeClaimTemplates)
+│   ├── service.yaml                 ← Service: minio (ClusterIP, port 9000)
+│   └── init-job.yaml                ← Job: minio-init-bucket (mc mb --ignore-existing)
+└── vault/
+    ├── vault-auth.yaml              ← VaultAuth: kubernetes method, reactbin SA
+    ├── api-secret.yaml              ← VaultStaticSecret → K8s Secret: api-env
+    └── minio-secret.yaml            ← VaultStaticSecret → K8s Secret: minio-credentials
+
+api/Dockerfile.prod                  ← MODIFIED: add alembic/ and alembic.ini to runtime stage
+Makefile                             ← MODIFIED: add dry-run validation target
+```
+
+## Implementation Design
+
+### `api/Dockerfile.prod` — runtime stage addition
+
+```dockerfile
+# In the runtime stage, after copying app/:
+COPY --chown=appuser:appgroup alembic/ ./alembic/
+COPY --chown=appuser:appgroup alembic.ini .
+```
+
+No builder-stage change. No new base image. The init container uses the same image and `workingDir: /app`.
+
+### `k8s/namespace.yaml`
+
+```yaml
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: reactbin
+```
+
+### `k8s/vault/vault-auth.yaml`
+
+```yaml
+apiVersion: secrets.hashicorp.com/v1beta1
+kind: VaultAuth
+metadata:
+  name: reactbin-auth
+  namespace: reactbin
+spec:
+  method: kubernetes
+  mount: kubernetes
+  kubernetes:
+    role: reactbin
+    serviceAccount: default
+    audiences:
+      - https://kubernetes.default.svc
+```
+
+Note: `VaultConnection` is not included in the `k8s/` tree — it lives in the VSO operator's namespace and is operator-managed infrastructure, not application manifests.
+
+### `k8s/vault/api-secret.yaml`
+
+```yaml
+apiVersion: secrets.hashicorp.com/v1beta1
+kind: VaultStaticSecret
+metadata:
+  name: api-secret
+  namespace: reactbin
+spec:
+  vaultAuthRef: reactbin-auth
+  mount: secret
+  type: kv-v2
+  path: reactbin/api/config
+  refreshAfter: 1h
+  destination:
+    name: api-env
+    create: true
+```
+
+The API Deployment then uses `envFrom: [{secretRef: {name: api-env}}]`.
+
+### `k8s/vault/minio-secret.yaml`
+
+Same pattern, path `reactbin/minio/credentials`, destination `minio-credentials`.
+
+### `k8s/api/deployment.yaml` — init container
+
+```yaml
+initContainers:
+  - name: alembic-migrate
+    image: reactbin-api:latest          # same tag as main container
+    command: ["alembic", "upgrade", "head"]
+    workingDir: /app
+    envFrom:
+      - secretRef:
+          name: api-env
+containers:
+  - name: api
+    image: reactbin-api:latest
+    ports:
+      - containerPort: 8000
+    envFrom:
+      - secretRef:
+          name: api-env
+    env:
+      - name: API_DOCS_ENABLED
+          value: "false"
+    livenessProbe:
+      httpGet: {path: /api/v1/health, port: 8000}
+      initialDelaySeconds: 10
+      periodSeconds: 30
+    readinessProbe:
+      httpGet: {path: /api/v1/health, port: 8000}
+      initialDelaySeconds: 5
+      periodSeconds: 10
+    securityContext:
+      runAsNonRoot: true
+      runAsUser: 1001
+```
+
+### `k8s/ingress.yaml`
+
+```yaml
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  name: reactbin
+  namespace: reactbin
+  annotations:
+    cert-manager.io/cluster-issuer: letsencrypt-prod
+    nginx.ingress.kubernetes.io/ssl-redirect: "true"
+spec:
+  ingressClassName: nginx
+  tls:
+    - hosts: [<your-domain>]
+      secretName: reactbin-tls
+  rules:
+    - host: <your-domain>
+      http:
+        paths:
+          - path: /api/
+            pathType: Prefix
+            backend:
+              service: {name: api, port: {number: 8000}}
+          - path: /
+            pathType: Prefix
+            backend:
+              service: {name: ui, port: {number: 8080}}
+```
+
+`/api/` must be listed before `/`.
+
+### `k8s/minio/statefulset.yaml` — StatefulSet (not Deployment)
+
+StatefulSet gives stable pod name `minio-0` and automatic PVC reattachment via `volumeClaimTemplates`. ReadWriteOnce, default storage class.
+
+Health probes: `GET /minio/health/live:9000` (liveness), `GET /minio/health/ready:9000` (readiness).
+
+### `k8s/minio/init-job.yaml`
+
+```yaml
+command: ["sh", "-c", "mc alias set local http://minio:9000 $MINIO_ROOT_USER $MINIO_ROOT_PASSWORD && mc mb --ignore-existing local/reactbin"]
+```
+
+`restartPolicy: OnFailure`. `--ignore-existing` makes the job idempotent.
+
+### Makefile addition
+
+```makefile
+validate-k8s:
+    yamllint k8s/
+    kubectl apply --dry-run=client -f k8s/
+```
+
+## Dependencies & Risks
+
+| Item | Risk | Mitigation |
+|------|------|------------|
+| `VaultConnection` not in `k8s/` | Operator may not have it pre-created | Documented as prerequisite in contracts/operator-deploy.md |
+| `letsencrypt-prod` ClusterIssuer name | May differ in operator's cluster | Documented as prerequisite; easy to sed-replace |
+| Image tag placeholder `latest` | Operator forgets to substitute | `validate-k8s` dry-run will succeed but notes in quickstart.md and task descriptions warn explicitly |
+| MinIO PVC storage class | Default may be unsuitable (e.g., ephemeral) | Noted in Assumptions; operator can patch `storageClassName` |
+| `<your-domain>` placeholder in Ingress | `kubectl apply --dry-run=client` validates everything except host value | Noted in quickstart; hostname must be substituted before applying |

specs/013-k8s-manifests/quickstart.md

@@ -0,0 +1,92 @@
+# Quickstart: Kubernetes Production Deployment
+
+## Before You Apply
+
+1. Store API secrets in Vault at `reactbin/api/config` (KV v2):
+   ```
+   DATABASE_URL          = postgresql+asyncpg://reactbin:<pw>@<host>:5432/reactbin
+   JWT_SECRET_KEY        = <long-random-string>
+   OWNER_USERNAME        = <your-username>
+   OWNER_PASSWORD        = <your-password>
+   S3_ENDPOINT_URL       = http://minio.reactbin.svc.cluster.local:9000
+   S3_BUCKET_NAME        = reactbin
+   S3_ACCESS_KEY_ID      = <same as MINIO_ROOT_USER>
+   S3_SECRET_ACCESS_KEY  = <same as MINIO_ROOT_PASSWORD>
+   API_BASE_URL          = https://<your-domain>
+   API_DOCS_ENABLED      = false
+   ```
+
+2. Store MinIO credentials in Vault at `reactbin/minio/credentials` (KV v2):
+   ```
+   MINIO_ROOT_USER     = <choose a strong username>
+   MINIO_ROOT_PASSWORD = <choose a strong password>
+   ```
+
+3. Create a Vault Kubernetes auth role bound to the `default` service account in the `reactbin` namespace with read access to both paths above.
+
+4. Confirm DNS resolves to the cluster ingress IP and the `letsencrypt-prod` ClusterIssuer exists.
+
+## Deploy
+
+```bash
+# Substitute the real image tags
+sed -i 's|reactbin-api:latest|reactbin-api:v1.0.0|g' k8s/api/deployment.yaml
+sed -i 's|reactbin-ui:latest|reactbin-ui:v1.0.0|g' k8s/ui/deployment.yaml
+
+# Apply everything
+kubectl apply -f k8s/
+```
+
+## Verify
+
+```bash
+# Watch pods come up (init container runs first on the API pod)
+kubectl get pods -n reactbin -w
+
+# API health
+curl -sf https://<your-domain>/api/v1/health && echo "API OK"
+
+# UI reachable
+curl -sf -o /dev/null -w "%{http_code}\n" https://<your-domain>/
+
+# Docs correctly gated
+curl -o /dev/null -w "%{http_code}\n" https://<your-domain>/docs    # → 404
+curl -o /dev/null -w "%{http_code}\n" https://<your-domain>/redoc   # → 404
+
+# Check migration init container ran
+kubectl logs -n reactbin -l app=api -c alembic-migrate
+```
+
+## Scenario: Migration fails on deploy
+
+```bash
+# Pod will be stuck in Init state
+kubectl get pods -n reactbin
+# NAME          READY   STATUS                  RESTARTS
+# api-xxx-yyy   0/1     Init:CrashLoopBackOff   2
+
+# See why
+kubectl logs -n reactbin <pod-name> -c alembic-migrate
+
+# Fix the issue (e.g. correct DATABASE_URL in Vault, wait for VSO to resync)
+# Then delete the pod to force a fresh rollout
+kubectl rollout restart deployment/api -n reactbin
+```
+
+## Scenario: Update to a new image version
+
+```bash
+kubectl set image deployment/api api=reactbin-api:v1.1.0 -n reactbin
+kubectl set image deployment/ui ui=reactbin-ui:v1.1.0 -n reactbin
+# Kubernetes rolls out new pods; init container runs migrations before traffic switches
+```
+
+## Scenario: Restore after MinIO pod restart
+
+MinIO uses a PersistentVolumeClaim. Pod restarts do not affect stored data. Verify:
+
+```bash
+kubectl delete pod -n reactbin minio-0
+kubectl get pods -n reactbin -w   # minio-0 restarts, PVC reattaches
+# Previously uploaded images should still be accessible via the API
+```

specs/013-k8s-manifests/research.md

@@ -0,0 +1,63 @@
+# Research: Kubernetes Production Manifests
+
+## Decision 1: VSO CRD chain (VaultConnection → VaultAuth → VaultStaticSecret)
+
+**Decision**: Use three CRDs — `VaultConnection`, `VaultAuth`, and `VaultStaticSecret` — all under `apiVersion: secrets.hashicorp.com/v1beta1`.
+**Rationale**: This is the required VSO resource chain. `VaultConnection` points to the Vault server address. `VaultAuth` declares the Kubernetes auth method (role, service account, mount path). `VaultStaticSecret` references a `VaultAuth` via `vaultAuthRef` and declares the Vault KV path and the destination K8s Secret name. VSO syncs all Vault keys to the K8s Secret 1:1 by default — no explicit key mapping needed.
+**Alternatives considered**: `VaultAuthGlobal` for cross-namespace sharing — not needed; all resources are in the same `reactbin` namespace.
+
+Key fields:
+- `VaultStaticSecret.spec.type`: `kv-v2` (standard for modern Vault)
+- `VaultStaticSecret.spec.refreshAfter`: `1h` (Go duration string)
+- `VaultStaticSecret.spec.destination.create: true` — VSO creates the K8s Secret if absent
+- `VaultAuth.spec.kubernetes.role` — a Vault role the operator must pre-create and bind to the `reactbin` namespace service account
+
+## Decision 2: MinIO as StatefulSet (not Deployment)
+
+**Decision**: Run MinIO as a `StatefulSet` with `volumeClaimTemplates`.
+**Rationale**: StatefulSet gives the pod a stable name (`minio-0`) and automatically reattaches its PVC on pod recreation. A Deployment would require a manually-created PVC and is prone to PVC binding issues on reschedule. The marginal complexity of a StatefulSet over a Deployment is acceptable. `ReadWriteOnce` PVC is correct for single-replica MinIO.
+**Alternatives considered**: Deployment with explicit PVC — works but PVC lifecycle is decoupled from the pod, creating operational risk.
+
+MinIO health probes:
+- Liveness: `GET /minio/health/live:9000`
+- Readiness: `GET /minio/health/ready:9000`
+
+MinIO env vars: `MINIO_ROOT_USER`, `MINIO_ROOT_PASSWORD` (injected from a K8s Secret synced by VSO).
+
+## Decision 3: Bucket initialisation via Kubernetes Job with `minio/mc`
+
+**Decision**: A one-off `Job` using `minio/mc:latest` runs `mc mb --ignore-existing` to create the bucket idempotently.
+**Rationale**: This is the standard in-cluster pattern. `--ignore-existing` makes the job safe to re-apply (exits 0 if bucket already exists). `restartPolicy: OnFailure` retries transient failures (e.g. MinIO not yet ready).
+**Alternatives considered**: Init container on the API pod — tightly couples bucket creation to API startup; a Job is cleaner and independently rerunnable.
+
+## Decision 4: Ingress — single resource, `/api/` path before `/`
+
+**Decision**: One `Ingress` resource with `ingressClassName: nginx`, two path entries in a single rule: `/api/` (Prefix) → API Service, `/` (Prefix) → UI Service; `/api/` must be listed first.
+**Rationale**: nginx ingress evaluates paths in declaration order; the more specific `/api/` prefix must appear before `/` or all traffic is routed to the UI. No path rewriting annotation is needed — the API already handles full `/api/v1/...` paths.
+**TLS**: cert-manager annotation `cert-manager.io/cluster-issuer: letsencrypt-prod` triggers automatic certificate provisioning into a K8s Secret named in `spec.tls[].secretName`. HTTP→HTTPS redirect is on by default when TLS is configured (`nginx.ingress.kubernetes.io/ssl-redirect: "true"` is explicit but redundant).
+**Alternatives considered**: Two separate Ingress resources (one per service) — works but harder to reason about routing order; single Ingress is canonical.
+
+## Decision 5: Alembic init container — same image, workdir `/app`
+
+**Decision**: The API Deployment includes an init container with the same image as the main container, `command: ["alembic", "upgrade", "head"]`, and `workingDir: /app`. It shares the API's env secret via `envFrom` so it can read `DATABASE_URL`.
+**Rationale**: Alembic needs `DATABASE_URL` to connect and `alembic.ini` + `alembic/` to find migrations. Both are available in the production image once `Dockerfile.prod` is updated. Using the same image guarantees the migration files match the running version.
+**Dockerfile.prod update required**: Add `COPY --chown=appuser:appgroup alembic/ ./alembic/` and `COPY --chown=appuser:appgroup alembic.ini .` in the runtime stage (not the builder stage — no compilation needed).
+**Alternatives considered**: Separate migration image — adds a second image to build and push on every release; unnecessary when the source image already has everything.
+
+## Decision 6: Image tag strategy — placeholder `latest`, substituted at deploy time
+
+**Decision**: Manifests reference image tags using `latest` as a documented placeholder. The operator substitutes the real tag with `kubectl set image` or a `sed` one-liner before applying.
+**Rationale**: Kustomize's `images` transformer is the clean alternative, but introduces a tooling dependency. For a personal single-operator deployment, `sed` or `kubectl set image` after `kubectl apply` is simpler and requires no additional setup. The placeholder is documented in the operator guide (quickstart.md).
+**Alternatives considered**: Kustomize overlays — appropriate for multi-environment setups; over-engineered for one environment.
+
+## Decision 7: Two VaultStaticSecrets (API env and MinIO credentials)
+
+**Decision**: Separate VaultStaticSecret resources for API env vars and MinIO root credentials, syncing into `api-env` and `minio-credentials` K8s Secrets respectively.
+**Rationale**: The API's env secret contains database, JWT, and S3 access credentials. MinIO's root credentials are a different concern with a different rotation lifecycle. Keeping them separate makes Vault policies simpler (least privilege) and avoids giving the API pod access to MinIO's root password.
+**Vault paths assumed**: `reactbin/api/config` (KV v2) for API env; `reactbin/minio/credentials` (KV v2) for MinIO root credentials.
+
+## Decision 8: Namespace manifest included in `k8s/`
+
+**Decision**: `k8s/namespace.yaml` creates the `reactbin` namespace as part of the manifest set.
+**Rationale**: Makes the full deployment self-contained — operator runs `kubectl apply -f k8s/` without a prerequisite namespace creation step.
+**Note**: If the namespace already exists, `kubectl apply` is idempotent.

specs/013-k8s-manifests/spec.md

@@ -0,0 +1,124 @@
+# Feature Specification: Kubernetes Production Manifests
+
+**Feature Branch**: `013-k8s-manifests`
+**Created**: 2026-05-07
+**Status**: Draft
+**Input**: User description: "Kubernetes manifests for production deployment to k3s: Deployment, Service, and Ingress for the API and UI; VaultStaticSecret CRDs to sync secrets from HashiCorp Vault; Alembic init container on the API Deployment for schema migrations. The cluster uses an nginx ingress controller with Let's Encrypt TLS, a shared external Postgres instance, MinIO running in-cluster, and VSO (Vault Secrets Operator) for secret management."
+
+## User Scenarios & Testing *(mandatory)*
+
+### User Story 1 — Application Reachable in Production (Priority: P1)
+
+As an operator, I can apply the manifests to my k3s cluster and have both the API and UI reachable at the production domain over HTTPS, with all health checks passing.
+
+**Why this priority**: This is the core deployment goal. Nothing else matters if the application is not reachable.
+
+**Independent Test**: Apply the API and UI manifests with a manually-created K8s Secret (bypassing Vault). Confirm the UI loads at the domain root and the API health endpoint returns 200 at `/api/v1/health`. Confirm HTTPS is enforced and HTTP redirects to HTTPS.
+
+**Acceptance Scenarios**:
+
+1. **Given** the manifests are applied to the cluster, **When** a browser navigates to `https://<domain>/`, **Then** the UI loads successfully with a valid TLS certificate.
+2. **Given** the manifests are applied, **When** a request is made to `https://<domain>/api/v1/health`, **Then** a 200 response is returned.
+3. **Given** the API docs flag is disabled, **When** a request is made to `https://<domain>/docs`, **Then** a 404 is returned.
+4. **Given** the API pod is restarted, **When** it comes back up, **Then** it passes readiness checks before receiving traffic.
+5. **Given** a request for an unknown path, **When** it is made to the UI, **Then** the SPA serves the index page (client-side routing is preserved).
+
+---
+
+### User Story 2 — Secrets Sourced from Vault (Priority: P2)
+
+As an operator, no secrets are stored in version-controlled manifest files. All sensitive values are declared in Vault and synced automatically into the cluster as Kubernetes Secrets by the Vault Secrets Operator.
+
+**Why this priority**: Security prerequisite for production. Hardcoded secrets in manifests are a material risk.
+
+**Independent Test**: Run `git grep` for known secret patterns across `k8s/` and confirm zero matches. Confirm VaultStaticSecret CRDs reference a Vault path and that the synced K8s Secret is created and the API pod's environment is populated from it.
+
+**Acceptance Scenarios**:
+
+1. **Given** Vault contains the required secret values at the declared path, **When** VSO is running, **Then** a K8s Secret is created in the cluster namespace with the declared keys.
+2. **Given** the K8s Secret exists, **When** the API pod starts, **Then** its environment variables are populated from that secret.
+3. **Given** a `git grep` for plaintext credentials across `k8s/`, **When** run against the committed manifests, **Then** no plaintext secrets are found.
+
+---
+
+### User Story 3 — Schema Migrations Run Before API Starts (Priority: P3)
+
+As an operator, every time the API is deployed, database migrations run automatically in an init container before the main application container starts. A failed migration prevents the pod from starting, protecting against schema drift.
+
+**Why this priority**: Prevents the API from serving requests against a stale or incompatible schema. Safe deployment ordering is essential for production.
+
+**Independent Test**: Deploy with the init container pointing at a valid database. Confirm migrations run and the API starts. Simulate a failing migration by pointing the init container at an unreachable database and confirm the pod stays in init state and does not serve traffic.
+
+**Acceptance Scenarios**:
+
+1. **Given** the API Deployment is applied, **When** the pod starts, **Then** the init container completes `alembic upgrade head` before the main container starts.
+2. **Given** the schema is already current, **When** the pod starts, **Then** the migration init container exits successfully with no changes applied.
+3. **Given** the migration fails, **When** the pod starts, **Then** the init container exits non-zero, the main container does not start, and the pod enters a visible error state.
+
+---
+
+### User Story 4 — MinIO Runs In-Cluster with Persistent Storage (Priority: P4)
+
+As an operator, MinIO runs inside the cluster with a PersistentVolumeClaim for durable storage, is not externally reachable, and has the required bucket initialised on first deployment.
+
+**Why this priority**: Required for image storage, but decoupled from the other manifests — the S3 endpoint is just a config value the API reads.
+
+**Independent Test**: Confirm the MinIO pod is running and has no external Ingress. Confirm the required bucket exists. Restart the MinIO pod and confirm previously stored objects are still accessible.
+
+**Acceptance Scenarios**:
+
+1. **Given** the MinIO manifests are applied, **When** the MinIO pod starts, **Then** the required bucket is created and the API can store and retrieve images.
+2. **Given** the MinIO pod is restarted, **When** it comes back up, **Then** all previously stored objects remain accessible (PVC-backed storage persists).
+3. **Given** no Ingress is defined for MinIO, **When** a connection is attempted from outside the cluster, **Then** MinIO is not reachable.
+
+---
+
+### Edge Cases
+
+- What if Vault is unavailable when VSO tries to sync? VSO retries on a configurable interval; the pod will not start until the K8s Secret exists.
+- What if the database is unreachable during migration? The init container exits non-zero; the pod does not start and Kubernetes retries with backoff.
+- What if the MinIO PVC runs out of space? MinIO will fail writes; the API will return upload errors. Capacity monitoring is out of scope for this feature.
+- What if migrations and the main container use different image tags? They use the same tag in the same Deployment spec, so they are always in sync.
+
+## Requirements *(mandatory)*
+
+### Functional Requirements
+
+- **FR-001**: All manifests MUST target a single configurable namespace (default: `reactbin`).
+- **FR-002**: The API MUST be deployed as a Deployment with liveness and readiness probes on `/api/v1/health`.
+- **FR-003**: The API Deployment MUST include an init container using the same image that runs database schema migrations before the main container starts.
+- **FR-004**: The API Deployment MUST set `API_DOCS_ENABLED=false`.
+- **FR-005**: The UI MUST be deployed as a Deployment with a liveness probe confirming the nginx process is serving.
+- **FR-006**: A single Ingress MUST route `https://<domain>/api/` to the API Service and all other paths to the UI Service, with TLS termination via a cert-manager Let's Encrypt certificate.
+- **FR-007**: HTTP requests MUST be redirected to HTTPS via the Ingress.
+- **FR-008**: All API secrets MUST be declared in a VaultStaticSecret CRD and synced into a K8s Secret; no secret value MUST appear as plaintext in any manifest file.
+- **FR-009**: The API Deployment MUST source all environment variables from the synced K8s Secret via `envFrom`.
+- **FR-010**: MinIO MUST be deployed as a StatefulSet with a PersistentVolumeClaim using the cluster's default storage class.
+- **FR-011**: A Kubernetes Job MUST create the required S3 bucket in MinIO on first deployment and MUST be idempotent on re-apply.
+- **FR-012**: MinIO MUST have no Ingress; it MUST only be accessible within the cluster via ClusterIP.
+- **FR-013**: All containers MUST run as non-root users.
+- **FR-014**: The API production image MUST include migration files so the init container can run migrations without a separate image.
+
+## Success Criteria *(mandatory)*
+
+### Measurable Outcomes
+
+- **SC-001**: The application is accessible at the production domain within 120 seconds of `kubectl apply`.
+- **SC-002**: Schema migrations complete and the API begins serving traffic without manual operator intervention on every deployment.
+- **SC-003**: A `git grep` across `k8s/` finds zero plaintext secret values in committed files.
+- **SC-004**: A simulated migration failure holds the pod in init state and the application never serves traffic.
+- **SC-005**: Restarting the MinIO pod does not result in data loss — previously uploaded images remain accessible.
+
+## Assumptions
+
+- The k3s cluster is running with the nginx ingress controller installed.
+- cert-manager is installed and a `ClusterIssuer` named `letsencrypt-prod` is already configured.
+- The Vault Secrets Operator is installed in the cluster.
+- A HashiCorp Vault instance is accessible from the cluster and the required secret values are stored at the declared Vault path before deployment.
+- A shared external PostgreSQL instance is available; the operator creates a dedicated database and user before deploying.
+- DNS for the production domain is already pointing at the cluster ingress IP.
+- Manifests are stored in a `k8s/` directory at the repository root.
+- The cluster's default storage class supports ReadWriteOnce (sufficient for single-replica MinIO).
+- All Deployments run a single replica (personal tool, no HA requirement).
+- Image tags are managed externally; manifests use a placeholder tag that the operator substitutes at deploy time.
+- The `API_DOCS_ENABLED` flag exists on the API (implemented in feature 012).

specs/013-k8s-manifests/tasks.md

@@ -0,0 +1,174 @@
+# Tasks: Kubernetes Production Manifests
+
+**Input**: Design documents from `specs/013-k8s-manifests/`
+**Prerequisites**: plan.md ✅, spec.md ✅, research.md ✅, contracts/operator-deploy.md ✅, quickstart.md ✅
+
+**Tests**: K8s manifests have no unit test framework. Validation is via `yamllint` (format) and `kubectl apply --dry-run=client` (schema). Each phase ends with a validation step. The TDD analogue is: write the validate-k8s Makefile target (Phase 1) before any manifest exists, so it immediately fails — then manifests are written to make it pass.
+
+**Organization**: Phase 1 creates the directory structure and validation target. Phase 2 creates the namespace and Vault CRDs (foundational — required by all user story deployments). Phases 3–6 implement user stories. Phase 7 polishes.
+
+## Format: `[ID] [P?] [Story] Description`
+
+- **[P]**: Can run in parallel with other [P] tasks in the same phase
+- **[Story]**: Which user story this task belongs to
+- Exact file paths included in every task description
+
+---
+
+## Phase 1: Setup
+
+**Goal**: Create the `k8s/` directory structure and the validation Makefile target before any manifests exist.
+
+- [X] T001 Create the `k8s/` directory tree: `mkdir -p k8s/api k8s/ui k8s/minio k8s/vault` from the repository root; confirm the four subdirectories exist
+
+- [X] T002 Add a `validate-k8s` target to `Makefile` immediately after the existing `verify-ui-prod` target: the target MUST run `yamllint -d relaxed k8s/` then `kubectl apply --dry-run=client -f k8s/`; add `validate-k8s` to the `.PHONY` line; note in a comment that `kubectl apply --dry-run=client` requires a kubeconfig with cluster access — offline validation uses `yamllint` only
+
+---
+
+## Phase 2: Foundational (Namespace + Vault CRDs)
+
+**Goal**: Namespace and Vault secret-sync resources that every other manifest depends on.
+
+**⚠️ CRITICAL**: No user story manifest can be applied until this phase is complete — the namespace must exist before any namespaced resource, and the Vault CRDs must exist before the API or MinIO pods can start.
+
+- [X] T003 Create `k8s/namespace.yaml`: a single `Namespace` resource with `name: reactbin` and no additional labels
+
+- [X] T004 [P] Create `k8s/vault/vault-auth.yaml`: a `VaultAuth` resource (`apiVersion: secrets.hashicorp.com/v1beta1`) with `name: reactbin-auth`, `namespace: reactbin`, `spec.method: kubernetes`, `spec.mount: kubernetes`, `spec.kubernetes.role: reactbin`, `spec.kubernetes.serviceAccount: default`, `spec.kubernetes.audiences: [https://kubernetes.default.svc]`; add a comment noting the operator must create the Vault role and bind it to the `default` SA in the `reactbin` namespace with read access to both secret paths
+
+- [X] T005 [P] Create `k8s/vault/api-secret.yaml`: a `VaultStaticSecret` resource with `name: api-secret`, `namespace: reactbin`, `spec.vaultAuthRef: reactbin-auth`, `spec.mount: secret`, `spec.type: kv-v2`, `spec.path: reactbin/api/config`, `spec.refreshAfter: 1h`, `spec.destination.name: api-env`, `spec.destination.create: true`; add a comment listing all required Vault keys: `DATABASE_URL`, `JWT_SECRET_KEY`, `OWNER_USERNAME`, `OWNER_PASSWORD`, `S3_ENDPOINT_URL`, `S3_BUCKET_NAME`, `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY`, `API_BASE_URL`
+
+- [X] T006 [P] Create `k8s/vault/minio-secret.yaml`: same structure as T005 but `name: minio-secret`, `spec.path: reactbin/minio/credentials`, `spec.destination.name: minio-credentials`; comment listing required Vault keys: `MINIO_ROOT_USER`, `MINIO_ROOT_PASSWORD`
+
+**Checkpoint**: Foundational resources complete. User story implementation can now begin.
+
+---
+
+## Phase 3: User Story 1 — Application Reachable in Production (Priority: P1) 🎯 MVP
+
+**Goal**: API and UI are deployed and reachable at the production domain via HTTPS with TLS from cert-manager.
+
+**Independent Test**: Apply all Phase 2 + Phase 3 manifests. Confirm `kubectl get pods -n reactbin` shows api and ui pods Running. Confirm `curl https://<domain>/api/v1/health` returns 200 and `curl https://<domain>/` returns 200.
+
+- [X] T007 [P] [US1] Create `k8s/api/service.yaml`: `Service`, `name: api`, `namespace: reactbin`, `type: ClusterIP`, `selector: {app: api}`, `ports: [{port: 8000, targetPort: 8000, name: http}]`
+
+- [X] T008 [P] [US1] Create `k8s/ui/service.yaml`: `Service`, `name: ui`, `namespace: reactbin`, `type: ClusterIP`, `selector: {app: ui}`, `ports: [{port: 8080, targetPort: 8080, name: http}]`
+
+- [X] T009 [P] [US1] Create `k8s/ui/deployment.yaml`: `Deployment`, `name: ui`, `namespace: reactbin`, 1 replica, `selector.matchLabels: {app: ui}`; container `name: ui`, `image: reactbin-ui:latest` (placeholder — operator substitutes real tag), `ports: [{containerPort: 8080}]`; `livenessProbe: {httpGet: {path: /, port: 8080}, initialDelaySeconds: 10, periodSeconds: 30}`; `securityContext: {runAsNonRoot: true, runAsUser: 101}` (UID 101 is the nginxinc/nginx-unprivileged user); add comment: `# Replace 'latest' with the real image tag before applying`
+
+- [X] T010 [US1] Create `k8s/api/deployment.yaml`: `Deployment`, `name: api`, `namespace: reactbin`, 1 replica, `selector.matchLabels: {app: api}`; container `name: api`, `image: reactbin-api:latest` (placeholder), `ports: [{containerPort: 8000}]`; `envFrom: [{secretRef: {name: api-env}}]`; `env: [{name: API_DOCS_ENABLED, value: "false"}]`; `livenessProbe: {httpGet: {path: /api/v1/health, port: 8000}, initialDelaySeconds: 10, periodSeconds: 30}`; `readinessProbe: {httpGet: {path: /api/v1/health, port: 8000}, initialDelaySeconds: 5, periodSeconds: 10}`; `securityContext: {runAsNonRoot: true, runAsUser: 1001}`; add comment: `# initContainers block added in US3 (T015)`; add comment: `# Replace 'latest' with the real image tag before applying`
+
+- [X] T011 [US1] Create `k8s/ingress.yaml`: `Ingress`, `name: reactbin`, `namespace: reactbin`; `annotations: {"cert-manager.io/cluster-issuer": "letsencrypt-prod", "nginx.ingress.kubernetes.io/ssl-redirect": "true"}`; `spec.ingressClassName: nginx`; `spec.tls: [{hosts: ["<your-domain>"], secretName: reactbin-tls}]`; `spec.rules: [{host: "<your-domain>", http: {paths: [{path: /api/, pathType: Prefix, backend: {service: {name: api, port: {number: 8000}}}}, {path: /, pathType: Prefix, backend: {service: {name: ui, port: {number: 8080}}}}]}}]`; IMPORTANT — `/api/` path entry MUST appear before `/` in the YAML (nginx evaluates in declaration order); add comment: `# Replace <your-domain> with the real domain before applying`
+
+- [X] T012 [US1] Verify US1: run `yamllint -d relaxed k8s/` from the repository root and confirm no errors; run `kubectl apply --dry-run=client -f k8s/` (requires cluster kubeconfig) and confirm all resources in namespace.yaml, vault/, api/, ui/, and ingress.yaml are accepted; if no cluster is available, yamllint passing is sufficient for this checkpoint
+
+**Checkpoint**: US1 complete. API and UI manifests are schema-valid and ready to apply.
+
+---
+
+## Phase 4: User Story 2 — Secrets Sourced from Vault (Priority: P2)
+
+**Goal**: Confirm that no plaintext secret values appear in any committed manifest file. The implementation (VaultAuth + VaultStaticSecret × 2) was completed in Phase 2.
+
+**Independent Test**: `git grep` across `k8s/` finds no plaintext credential values.
+
+- [X] T013 [US2] Verify US2: run `git grep -rn "password\|secret_key\|access_key\|DATABASE_URL" k8s/` and confirm that only key names (in comments) and Vault path references appear — no actual values; also confirm that `k8s/vault/api-secret.yaml` and `k8s/vault/minio-secret.yaml` reference Vault paths under `spec.path` and that `spec.destination.create: true` is set so VSO creates the K8s Secrets
+
+**Checkpoint**: US2 complete. Zero plaintext secrets in manifests; all secrets flow through Vault.
+
+---
+
+## Phase 5: User Story 3 — Schema Migrations Run Before API Starts (Priority: P3)
+
+**Goal**: The API Deployment includes an Alembic init container. `api/Dockerfile.prod` is updated to include migration files.
+
+**Independent Test**: `docker build -f api/Dockerfile.prod api/ -t reactbin-api-prod:test` succeeds and `docker run --rm reactbin-api-prod:test ls /app/alembic` shows migration files. `make validate-k8s` confirms the init container spec is accepted by the Kubernetes schema.
+
+- [X] T014 [US3] Update `api/Dockerfile.prod`: in the **runtime stage** (the `FROM python:3.12-slim` stage), after the line `COPY --chown=appuser:appgroup app/ ./app/`, add two new lines: `COPY --chown=appuser:appgroup alembic/ ./alembic/` and `COPY --chown=appuser:appgroup alembic.ini .`; the builder stage is unchanged; verify with `docker build -f api/Dockerfile.prod api/ -t reactbin-api-prod:test && docker run --rm reactbin-api-prod:test ls /app/alembic /app/alembic.ini`
+
+- [X] T015 [US3] Update `k8s/api/deployment.yaml`: add an `initContainers` block to the pod spec (before the `containers` block) containing one init container: `name: alembic-migrate`, `image: reactbin-api:latest` (same placeholder tag as the main container), `command: ["alembic", "upgrade", "head"]`, `workingDir: /app`, `envFrom: [{secretRef: {name: api-env}}]`, `securityContext: {runAsNonRoot: true, runAsUser: 1001}`; remove the `# initContainers block added in US3 (T015)` comment added in T010
+
+- [X] T016 [US3] Verify US3: run `make validate-k8s` (or `yamllint -d relaxed k8s/`) and confirm the updated deployment.yaml with the init container passes validation; run `docker build -f api/Dockerfile.prod api/ -t reactbin-api-prod:test` and confirm it succeeds; run `docker run --rm reactbin-api-prod:test ls /app/alembic.ini` and confirm the file is present
+
+**Checkpoint**: US3 complete. API Deployment includes Alembic init container; production image includes migration files.
+
+---
+
+## Phase 6: User Story 4 — MinIO In-Cluster with Persistent Storage (Priority: P4)
+
+**Goal**: MinIO runs as a StatefulSet with a PVC, is accessible only within the cluster, and has the required bucket created by a Job.
+
+**Independent Test**: `make validate-k8s` confirms all MinIO manifests pass schema validation. On a live cluster: MinIO pod reaches Running state, bucket exists, no external Ingress for MinIO.
+
+- [X] T017 [P] [US4] Create `k8s/minio/service.yaml`: `Service`, `name: minio`, `namespace: reactbin`, `type: ClusterIP`, `selector: {app: minio}`, `ports: [{port: 9000, targetPort: 9000, name: s3}]`; add comment: `# No Ingress for MinIO — internal access only (FR-012)`
+
+- [X] T018 [US4] Create `k8s/minio/statefulset.yaml`: `StatefulSet` (NOT Deployment — StatefulSet ensures stable PVC binding on pod recreation), `name: minio`, `namespace: reactbin`, `replicas: 1`, `selector.matchLabels: {app: minio}`, `serviceName: minio`; pod `securityContext: {runAsUser: 1000, runAsGroup: 1000, fsGroup: 1000}`; container `name: minio`, `image: minio/minio:latest`, `args: ["server", "/data", "--console-address", ":9001"]`, `ports: [{containerPort: 9000, name: s3}]`; `env: [{name: MINIO_ROOT_USER, valueFrom: {secretKeyRef: {name: minio-credentials, key: MINIO_ROOT_USER}}}, {name: MINIO_ROOT_PASSWORD, valueFrom: {secretKeyRef: {name: minio-credentials, key: MINIO_ROOT_PASSWORD}}}]`; `livenessProbe: {httpGet: {path: /minio/health/live, port: 9000}, initialDelaySeconds: 30, periodSeconds: 20}`; `readinessProbe: {httpGet: {path: /minio/health/ready, port: 9000}, initialDelaySeconds: 15, periodSeconds: 10}`; `volumeMounts: [{name: minio-data, mountPath: /data}]`; `volumeClaimTemplates: [{metadata: {name: minio-data}, spec: {accessModes: [ReadWriteOnce], resources: {requests: {storage: 10Gi}}}}]`; add comment: `# storageClassName omitted — uses cluster default; override if needed`
+
+- [X] T019 [US4] Create `k8s/minio/init-job.yaml`: `Job`, `name: minio-init-bucket`, `namespace: reactbin`; `spec.template.spec.restartPolicy: OnFailure`; container `name: mc`, `image: minio/mc:latest`, `command: ["sh", "-c"]`, `args: ["mc alias set local http://minio.reactbin.svc.cluster.local:9000 $MINIO_ROOT_USER $MINIO_ROOT_PASSWORD && mc mb --ignore-existing local/reactbin"]`; `env: [{name: MINIO_ROOT_USER, valueFrom: {secretKeyRef: {name: minio-credentials, key: MINIO_ROOT_USER}}}, {name: MINIO_ROOT_PASSWORD, valueFrom: {secretKeyRef: {name: minio-credentials, key: MINIO_ROOT_PASSWORD}}}]`; `securityContext: {runAsNonRoot: false}` with comment `# minio/mc runs as root by default; FR-013 exception for this one-off init Job`; add comment: `# --ignore-existing makes this Job idempotent — safe to re-apply`
+
+- [X] T020 [US4] Verify US4: run `make validate-k8s` (or `yamllint -d relaxed k8s/`) and confirm all three MinIO manifests (statefulset.yaml, service.yaml, init-job.yaml) pass validation; confirm no Ingress resource references MinIO
+
+**Checkpoint**: All four user stories complete.
+
+---
+
+## Phase 7: Polish & Cross-Cutting Concerns
+
+- [X] T021 [P] Run `yamllint -d relaxed k8s/` from the repository root and fix any YAML formatting violations across all 12 manifest files; confirm output shows no errors
+
+- [X] T022 [P] Add `.yamllint.yml` at the repository root (if not already present) with `extends: relaxed` and `rules: {line-length: {max: 120}}` to keep line length reasonable for verbose K8s YAML
+
+- [X] T023 Run `make build-prod` to confirm `api/Dockerfile.prod` still builds cleanly after the T014 addition; run `docker run --rm reactbin-api-prod:latest ls /app/alembic.ini /app/alembic/` and confirm both are present in the production image
+
+---
+
+## Dependencies & Execution Order
+
+- T001 and T002 can run in parallel (directory creation vs Makefile edit)
+- T003, T004, T005, T006 can run in parallel after T001 (different files, same phase)
+- T007, T008, T009 can run in parallel after Phase 2 completes
+- T010 after T007 (deployment references service name, easier to write with service done) — but they're different files so technically parallel; keep sequential for clarity
+- T011 after T007 and T008 (Ingress references both service names)
+- T012 after T007–T011
+- T013 after Phase 2 (Vault CRDs exist to inspect)
+- T014 and T015 can run in parallel (different files: Dockerfile.prod vs deployment.yaml)
+- T016 after T014 and T015
+- T017, T018, T019 can run in parallel after Phase 2 completes
+- T020 after T017–T019
+- T021, T022, T023 can run in parallel
+
+### Execution Order Summary
+
+```
+Step 1: T001 ∥ T002                          (setup)
+Step 2: T003 ∥ T004 ∥ T005 ∥ T006           (foundational: namespace + Vault CRDs)
+Step 3: T007 ∥ T008 ∥ T009                  (US1: services + UI deployment)
+Step 4: T010                                  (US1: API deployment)
+Step 5: T011                                  (US1: Ingress)
+Step 6: T012                                  (US1: validate)
+Step 7: T013                                  (US2: verify no plaintext secrets)
+Step 8: T014 ∥ T015                          (US3: Dockerfile.prod + init container)
+Step 9: T016                                  (US3: verify)
+Step 10: T017 ∥ T018 ∥ T019                 (US4: MinIO manifests)
+Step 11: T020                                 (US4: validate MinIO)
+Step 12: T021 ∥ T022 ∥ T023                 (polish)
+```
+
+---
+
+## Implementation Strategy
+
+### MVP (US1 + US2 — application is reachable with Vault-backed secrets)
+
+1. Phase 1 (Setup) + Phase 2 (Foundational)
+2. Phase 3 (US1 — API, UI, Ingress)
+3. Phase 4 (US2 — verify no plaintext secrets)
+4. **STOP and VALIDATE**: apply to cluster, confirm `https://<domain>/` and `/api/v1/health` return 200
+5. Deploy MVP
+
+### Incremental Delivery
+
+1. Setup + Foundational → Apply → namespace and Vault sync ready
+2. Add US1 (API + UI + Ingress) → Deploy → application reachable at domain
+3. Add US3 (Alembic init container) → Deploy → migrations run automatically on rollout
+4. Add US4 (MinIO) → Deploy → persistent image storage in-cluster
+5. Polish → clean YAML, confirmed builds

specs/014-r2-cdn-serving/checklists/requirements.md

@@ -0,0 +1,34 @@
+# Specification Quality Checklist: CDN Image Serving
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2026-05-08
+**Feature**: [spec.md](../spec.md)
+
+## Content Quality
+
+- [X] No implementation details (languages, frameworks, APIs)
+- [X] Focused on user value and business needs
+- [X] Written for non-technical stakeholders
+- [X] All mandatory sections completed
+
+## Requirement Completeness
+
+- [X] No [NEEDS CLARIFICATION] markers remain
+- [X] Requirements are testable and unambiguous
+- [X] Success criteria are measurable
+- [X] Success criteria are technology-agnostic (no implementation details)
+- [X] All acceptance scenarios are defined
+- [X] Edge cases are identified
+- [X] Scope is clearly bounded
+- [X] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [X] All functional requirements have clear acceptance criteria
+- [X] User scenarios cover primary flows
+- [X] Feature meets measurable outcomes defined in Success Criteria
+- [X] No implementation details leak into specification
+
+## Notes
+
+- All items pass. Ready for `/speckit-plan`.

specs/014-r2-cdn-serving/contracts/image-response.md

@@ -0,0 +1,54 @@
+# Contract: Image Metadata Response
+
+**Version**: 2.0 (adds `file_url`, `thumbnail_url`)
+**Endpoints affected**: `GET /api/v1/images`, `GET /api/v1/images/{id}`, `POST /api/v1/images`, `PATCH /api/v1/images/{id}/tags`
+
+## Response Schema
+
+```json
+{
+  "id": "550e8400-e29b-41d4-a716-446655440000",
+  "hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
+  "filename": "reaction.gif",
+  "mime_type": "image/gif",
+  "size_bytes": 204800,
+  "width": 480,
+  "height": 270,
+  "storage_key": "e3b0c44298fc1c149afbf4c8996fb924",
+  "thumbnail_key": "e3b0c44298fc1c149afbf4c8996fb924.thumb",
+  "file_url": "https://cdn.reactbin.juggalol.com/e3b0c44298fc1c149afbf4c8996fb924",
+  "thumbnail_url": "https://cdn.reactbin.juggalol.com/e3b0c44298fc1c149afbf4c8996fb924.thumb",
+  "created_at": "2026-05-08T12:00:00.000000",
+  "tags": ["funny", "reaction"]
+}
+```
+
+## Field Descriptions
+
+| Field | Type | Nullable | Notes |
+|-------|------|----------|-------|
+| `id` | string (UUID) | No | Stable image identifier |
+| `hash` | string (hex) | No | SHA-256 of file content; deduplication key |
+| `filename` | string | No | Original upload filename |
+| `mime_type` | string | No | One of: `image/jpeg`, `image/png`, `image/gif`, `image/webp` |
+| `size_bytes` | integer | No | File size in bytes |
+| `width` | integer | No | Image width in pixels |
+| `height` | integer | No | Image height in pixels |
+| `storage_key` | string | No | Object storage key (retained for backward compat) |
+| `thumbnail_key` | string | Yes | Thumbnail object storage key; null if generation failed |
+| `file_url` | string | No | Full URL to fetch the image file — CDN URL in production, API proxy path in local dev |
+| `thumbnail_url` | string | Yes | Full URL to fetch the thumbnail — CDN URL in production, API proxy path in local dev; null if no thumbnail |
+| `created_at` | string (ISO 8601) | No | Upload timestamp |
+| `tags` | string[] | No | Lowercase normalised tag list |
+| `duplicate` | boolean | Yes | Present only on upload responses; true if hash matched an existing image |
+
+## URL Behaviour
+
+| Configuration | `file_url` example | `thumbnail_url` example |
+|---------------|--------------------|------------------------|
+| `S3_PUBLIC_BASE_URL` set | `https://cdn.reactbin.juggalol.com/{storage_key}` | `https://cdn.reactbin.juggalol.com/{thumbnail_key}` |
+| `S3_PUBLIC_BASE_URL` not set | `/api/v1/images/{id}/file` | `/api/v1/images/{id}/thumbnail` |
+
+## UI Contract
+
+The UI MUST use `file_url` and `thumbnail_url` from the response to render images. The UI MUST NOT construct image URLs from `id`, `storage_key`, or `thumbnail_key` directly. The UI MUST treat `thumbnail_url: null` as "no thumbnail available" and fall back to `file_url` for display.

specs/014-r2-cdn-serving/plan.md

@@ -0,0 +1,137 @@
+# Implementation Plan: CDN Image Serving
+
+**Branch**: `014-r2-cdn-serving` | **Date**: 2026-05-08 | **Spec**: [spec.md](spec.md)
+**Input**: Feature specification from `specs/014-r2-cdn-serving/spec.md`
+
+## Summary
+
+Extend the image metadata API response to include `file_url` and `thumbnail_url` fields. When `S3_PUBLIC_BASE_URL` is configured, these fields contain CDN URLs pointing directly to Cloudflare R2. When unconfigured, they fall back to the existing API proxy paths so local development requires no setup changes. The UI is updated to use these response fields instead of constructing proxy URLs client-side. Proxy endpoints are retained unchanged.
+
+## Technical Context
+
+**Language/Version**: Python 3.12 (API), TypeScript strict mode (UI)
+**Primary Dependencies**: FastAPI, SQLAlchemy 2.x async, Angular (latest stable), pydantic-settings
+**Storage**: PostgreSQL (image metadata), S3-compatible object storage (R2 in production, MinIO in dev)
+**Testing**: pytest (unit + integration), Angular component tests
+**Target Platform**: Linux (k3s), local Docker Compose
+**Project Type**: Web service (API) + SPA (UI)
+**Performance Goals**: No additional latency on API responses; image load latency reduced by eliminating API proxy hop in production
+**Constraints**: No breaking changes to existing API response fields; proxy endpoints must remain functional
+**Scale/Scope**: Single-owner app; ~100 existing images migrated to R2 prior to this feature
+
+## Constitution Check
+
+| Principle | Status | Notes |
+|-----------|--------|-------|
+| §2.1 Strict separation of concerns | PASS | URL construction stays in router layer; storage backend unchanged |
+| §2.3 Storage abstraction | PASS | No changes to `StorageBackend` interface or `S3StorageBackend` |
+| §2.6 No speculative abstraction | PASS | No new interfaces introduced; URL logic is a simple helper |
+| §3.1 API versioning (`/api/v1/`) | PASS | Adding fields to response is non-breaking per §3.1 |
+| §3.2 OpenAPI as contract | PASS | New fields documented in contracts/image-response.md |
+| §5.1 Tests alongside implementation | REQUIRED | Unit tests for URL construction; integration tests for response fields |
+| §7.2 Environment configuration | PASS | `S3_PUBLIC_BASE_URL` via env var; no hardcoded URLs |
+
+No constitution violations. All gates pass.
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/014-r2-cdn-serving/
+├── plan.md                     # This file
+├── research.md                 # Technical decisions
+├── contracts/
+│   └── image-response.md       # Updated image response schema
+├── quickstart.md               # Integration test scenarios
+└── tasks.md                    # Phase 2 output (speckit-tasks)
+```
+
+### Source Code Changes
+
+```text
+api/
+├── app/
+│   ├── config.py               # Add: s3_public_base_url: str | None = None
+│   └── routers/
+│       └── images.py           # Update: _image_to_dict gains cdn_base param;
+│                               #         add file_url + thumbnail_url to response;
+│                               #         pass cdn_base from get_settings() at endpoint level
+├── tests/
+│   ├── unit/
+│   │   └── test_url_construction.py   # New: pure unit tests for URL logic
+│   └── integration/
+│       └── test_images.py      # Update: assert file_url + thumbnail_url present in responses
+
+ui/src/app/
+├── services/
+│   └── image.service.ts        # Update: add file_url/thumbnail_url to ImageRecord;
+│                               #         remove getFileUrl()/getThumbnailUrl() methods
+├── library/
+│   └── library.component.ts    # Update: use img.thumbnail_url instead of getThumbnailUrl(img.id)
+└── detail/
+    └── detail.component.ts     # Update: use img.file_url instead of getFileUrl(img.id)
+
+.env.example                    # Add: S3_PUBLIC_BASE_URL= (empty = local dev proxy fallback)
+```
+
+## Key Implementation Details
+
+### URL construction logic (`api/app/routers/images.py`)
+
+`_image_to_dict` gains a `cdn_base: str | None` parameter:
+
+```python
+def _image_to_dict(image: Image, *, cdn_base: str | None = None, duplicate: bool | None = None):
+    base = cdn_base.rstrip("/") if cdn_base else None
+    file_url = f"{base}/{image.storage_key}" if base else f"/api/v1/images/{image.id}/file"
+    thumbnail_url = (
+        (f"{base}/{image.thumbnail_key}" if base else f"/api/v1/images/{image.id}/thumbnail")
+        if image.thumbnail_key else None
+    )
+    return {
+        ...,          # existing fields unchanged
+        "file_url": file_url,
+        "thumbnail_url": thumbnail_url,
+    }
+```
+
+Each endpoint calls `get_settings()` once and passes `settings.s3_public_base_url` as `cdn_base`.
+
+### Config addition (`api/app/config.py`)
+
+```python
+s3_public_base_url: str | None = None
+```
+
+No validator needed — `None` is the valid "not configured" state.
+
+### UI changes (`ui/src/app/services/image.service.ts`)
+
+`ImageRecord` gains two new fields:
+```typescript
+file_url: string;
+thumbnail_url: string | null;
+```
+
+`getFileUrl(id)` and `getThumbnailUrl(id)` methods are removed. Components use `image.file_url` and `image.thumbnail_url` directly.
+
+## Phase Breakdown
+
+### Phase 1: API — config + URL construction (US1 foundation)
+- Add `s3_public_base_url` to config
+- Update `_image_to_dict` with `cdn_base` parameter
+- Update all call sites to pass `cdn_base` from settings
+- Unit tests for URL construction (both CDN and fallback paths)
+- Integration tests verifying `file_url`/`thumbnail_url` in all image responses
+
+### Phase 2: UI — consume response URLs (US1 + US2)
+- Update `ImageRecord` interface
+- Remove `getFileUrl`/`getThumbnailUrl` methods from service
+- Update library component
+- Update detail component
+- Update service tests
+
+### Phase 3: Config + docs
+- Add `S3_PUBLIC_BASE_URL` to `.env.example`
+- Manual end-to-end verification (local dev + production)

specs/014-r2-cdn-serving/quickstart.md

@@ -0,0 +1,66 @@
+# Quickstart: CDN Image Serving
+
+## Local development (no CDN)
+
+No configuration change required. `S3_PUBLIC_BASE_URL` is unset by default.
+
+```bash
+docker compose up
+```
+
+Upload an image and inspect the API response:
+
+```bash
+curl -s http://localhost:8000/api/v1/images | jq '.items[0] | {file_url, thumbnail_url}'
+```
+
+Expected (local dev — relative proxy paths):
+```json
+{
+  "file_url": "/api/v1/images/550e8400-.../file",
+  "thumbnail_url": "/api/v1/images/550e8400-.../thumbnail"
+}
+```
+
+The UI loads images via these relative paths, which hit the API proxy as before.
+
+---
+
+## Production (CDN configured)
+
+Add `S3_PUBLIC_BASE_URL` to the Vault secret bundle at `reactbin/api/config`:
+
+```
+S3_PUBLIC_BASE_URL = https://cdn.reactbin.juggalol.com
+```
+
+Force VSO sync and restart:
+
+```bash
+kubectl annotate vaultstaticsecret api-secret -n reactbin \
+  secrets.hashicorp.com/force-sync=$(date +%s) --overwrite
+
+kubectl rollout restart deployment/api -n reactbin
+```
+
+Upload a test image and inspect the response:
+
+```bash
+curl -s https://reactbin.juggalol.com/api/v1/images | jq '.items[0] | {file_url, thumbnail_url}'
+```
+
+Expected (production — CDN URLs):
+```json
+{
+  "file_url": "https://cdn.reactbin.juggalol.com/e3b0c44...",
+  "thumbnail_url": "https://cdn.reactbin.juggalol.com/e3b0c44....thumb"
+}
+```
+
+Open the browser network panel on the library page and confirm image requests go to `cdn.reactbin.juggalol.com`, not `/api/`.
+
+---
+
+## Verifying existing images after migration
+
+All existing images were migrated to R2 with the same object keys before this feature was deployed. Once `S3_PUBLIC_BASE_URL` is configured, the API will return CDN URLs for all images immediately — no per-image migration step is needed.

specs/014-r2-cdn-serving/research.md

@@ -0,0 +1,51 @@
+# Research: CDN Image Serving
+
+## Decision 1: Where does URL construction logic live?
+
+**Decision**: In the image router's `_image_to_dict` helper, not in the `StorageBackend`.
+
+**Rationale**: The `StorageBackend` interface is responsible for put/get/delete of object bytes. Adding URL construction there conflates two concerns — storage operations and HTTP URL generation — and would require the storage abstraction to know about CDN configuration. The router already has access to application settings via `get_settings()` and knows the image ID and storage key, making it the natural place to construct URLs.
+
+**Alternatives considered**: Adding a `get_url(key)` method to `StorageBackend` — rejected because it leaks HTTP/CDN concerns into the storage abstraction, violating §2.3.
+
+---
+
+## Decision 2: Fallback URL format in local development
+
+**Decision**: Relative paths (`/api/v1/images/{id}/file`, `/api/v1/images/{id}/thumbnail`) when `S3_PUBLIC_BASE_URL` is not set.
+
+**Rationale**: Relative paths work regardless of the host the app is running on, require no additional configuration, and match how the UI currently constructs these URLs via `getFileUrl(id)` and `getThumbnailUrl(id)`. An absolute fallback would require `API_BASE_URL` to be set in local dev, adding unnecessary setup friction.
+
+**Alternatives considered**: Absolute URL fallback using `API_BASE_URL` — rejected because it adds a mandatory config dependency where none exists today.
+
+---
+
+## Decision 3: Trailing slash normalisation
+
+**Decision**: Strip trailing slash from `S3_PUBLIC_BASE_URL` at construction time using `rstrip('/')` in the config validator or at point of use.
+
+**Rationale**: Prevents double-slash URLs (`https://cdn.example.com//key`) if the operator includes a trailing slash in the configured value. Simple, defensive, zero-cost.
+
+---
+
+## Decision 4: Proxy endpoints retained or removed?
+
+**Decision**: Retained, fully functional, unchanged.
+
+**Rationale**: Spec FR-005 explicitly requires them. They serve as the local dev fallback and a safety net if the CDN is temporarily unavailable or misconfigured. Removing them would break local development immediately.
+
+---
+
+## Decision 5: `storage_key` and `thumbnail_key` in API response
+
+**Decision**: Keep both fields in the response alongside the new `file_url` and `thumbnail_url`.
+
+**Rationale**: Removing them is a breaking API change. The UI currently reads `thumbnail_key` to decide whether a thumbnail exists. After this change the UI will use `thumbnail_url` (null when no thumbnail), but the keys remain in the response for backward compatibility with any tooling.
+
+---
+
+## Decision 6: Settings access in `_image_to_dict`
+
+**Decision**: Pre-compute the CDN base URL string once per request at the endpoint level and pass it into `_image_to_dict` as a parameter, rather than calling `get_settings()` inside the helper.
+
+**Rationale**: Keeps `_image_to_dict` a pure function (easier to test), avoids calling `get_settings()` inside a helper that is called in a loop (image list endpoint), and makes the dependency explicit.

specs/014-r2-cdn-serving/spec.md

@@ -0,0 +1,93 @@
+# Feature Specification: CDN Image Serving
+
+**Feature Branch**: `014-r2-cdn-serving`
+**Created**: 2026-05-08
+**Status**: Draft
+**Input**: User description: "R2 CDN image serving with local dev fallback to API proxy"
+
+## Overview
+
+Images and thumbnails are currently served by proxying bytes through the API. This feature changes image delivery so that clients receive direct URLs pointing to a CDN edge network, eliminating the API as a middleman for image content. In local development, where no CDN is available, the API proxy endpoints remain as a fallback so the developer experience is unchanged.
+
+---
+
+## User Scenarios & Testing *(mandatory)*
+
+### User Story 1 - Images Load Directly from CDN (Priority: P1)
+
+When a visitor views the image library or opens an image detail page, images and thumbnails are fetched directly from the CDN rather than through the application server. The page loads faster because image bytes no longer pass through the API.
+
+**Why this priority**: Core value of the feature. Reduces API load and improves image load speed for all users.
+
+**Independent Test**: Upload an image, open the library page, and inspect the network requests. Image and thumbnail requests should go directly to the CDN domain, not to `/api/`. The API response for the image list should include direct CDN URLs for each image and thumbnail.
+
+**Acceptance Scenarios**:
+
+1. **Given** a published image, **When** the visitor loads the image library, **Then** each thumbnail `src` URL points to the CDN domain and loads without passing through the API
+2. **Given** a published image, **When** the visitor opens the detail page, **Then** the full image `src` URL points to the CDN domain
+3. **Given** the API returns image metadata, **When** the response is inspected, **Then** it includes a `file_url` and `thumbnail_url` field containing full CDN URLs
+
+---
+
+### User Story 2 - Local Development Works Without CDN (Priority: P2)
+
+In local development, where no CDN is configured, images continue to load via the existing API proxy endpoints. No additional setup is required to run the application locally.
+
+**Why this priority**: Developer experience must not regress. The proxy endpoints must remain functional and be used automatically when no CDN is configured.
+
+**Independent Test**: Run the application locally without setting a public base URL. Upload an image. Verify the library and detail pages load images correctly via the API proxy endpoints, with no errors or broken images.
+
+**Acceptance Scenarios**:
+
+1. **Given** no CDN base URL is configured, **When** the API returns image metadata, **Then** `file_url` and `thumbnail_url` point to the API proxy paths (e.g. `/api/v1/images/{id}/file`)
+2. **Given** no CDN base URL is configured, **When** a visitor views the library, **Then** thumbnails load via the API proxy with no broken images
+3. **Given** a CDN base URL is configured, **When** the application starts, **Then** all image URLs use the CDN domain instead of the proxy paths
+
+---
+
+### Edge Cases
+
+- What happens when the CDN base URL is set but the object does not exist in CDN storage? The browser receives a 404 from the CDN — the API does not re-proxy the content.
+- What happens if an image has no thumbnail (thumbnail generation failed)? The `thumbnail_url` field is absent or null; the UI falls back to the full image URL as it does today.
+- What happens if the CDN base URL has a trailing slash? The system normalises the URL to avoid double slashes in constructed paths.
+
+---
+
+## Requirements *(mandatory)*
+
+### Functional Requirements
+
+- **FR-001**: The API MUST include a `file_url` field in all image metadata responses, containing the full URL from which the image file can be fetched
+- **FR-002**: The API MUST include a `thumbnail_url` field in all image metadata responses when a thumbnail exists, containing the full URL from which the thumbnail can be fetched
+- **FR-003**: When a CDN base URL is configured, `file_url` and `thumbnail_url` MUST point to the CDN domain
+- **FR-004**: When no CDN base URL is configured, `file_url` and `thumbnail_url` MUST point to the existing API proxy endpoints so local development continues to work without additional setup
+- **FR-005**: The existing API proxy endpoints (`/images/{id}/file`, `/images/{id}/thumbnail`) MUST remain functional regardless of whether a CDN base URL is configured
+- **FR-006**: The UI MUST use `file_url` and `thumbnail_url` from the API response to render images, rather than constructing proxy URLs client-side
+- **FR-007**: The CDN base URL MUST be configurable via environment variable; no value is required in local development
+- **FR-008**: A trailing slash in the configured CDN base URL MUST NOT result in double slashes in constructed image URLs
+- **FR-009**: When `thumbnail_url` is null, the UI MUST fall back to `file_url` for thumbnail display rather than rendering a broken image
+
+### Key Entities
+
+- **Image metadata response**: Extended to include `file_url` and `thumbnail_url` fields alongside existing fields (`id`, `filename`, `tags`, `width`, `height`, `mime_type`, etc.)
+
+---
+
+## Success Criteria *(mandatory)*
+
+### Measurable Outcomes
+
+- **SC-001**: In production, zero image or thumbnail requests pass through the API server — all are served directly by the CDN
+- **SC-002**: Local development requires no additional configuration beyond what is already required — `docker compose up` continues to work with images loading correctly
+- **SC-003**: All existing image-related API integration tests continue to pass after the change
+- **SC-004**: Image metadata responses include `file_url` and `thumbnail_url` fields for 100% of images that have been successfully stored
+
+---
+
+## Assumptions
+
+- The CDN storage bucket and public domain are already configured and operational before this feature is deployed — this feature only changes how URLs are constructed and served, not how objects are stored
+- Object keys in CDN storage are identical to those used in the existing storage backend — no key remapping is needed
+- The CDN serves objects publicly without authentication — no signed URL generation is required
+- The existing API proxy endpoints are retained as functional fallbacks; the UI stops calling them in production but they are not removed
+- Local development uses the existing MinIO-backed proxy and does not require a locally running CDN

specs/014-r2-cdn-serving/tasks.md

@@ -0,0 +1,116 @@
+# Tasks: CDN Image Serving
+
+**Input**: Design documents from `specs/014-r2-cdn-serving/`
+**Prerequisites**: plan.md ✅, spec.md ✅, research.md ✅, contracts/image-response.md ✅, quickstart.md ✅
+
+**Tests**: Unit tests for URL construction logic; integration tests asserting `file_url` and `thumbnail_url` in all image responses. Tests accompany each implementation task per §5.1.
+
+**Organization**: Phase 1 adds the config value (foundational — blocks everything). Phase 2 implements US1 (CDN URL serving in API + UI consumption). Phase 3 verifies US2 (local dev fallback). Polish runs the full suite and manual end-to-end check.
+
+## Format: `[ID] [P?] [Story] Description`
+
+- **[P]**: Can run in parallel (different files, no dependencies)
+- **[Story]**: Which user story this task belongs to
+
+---
+
+## Phase 1: Foundational (Config)
+
+**Goal**: Add `s3_public_base_url` to config and `.env.example`. All US1 and US2 tasks depend on this.
+
+**⚠️ CRITICAL**: No user story work can begin until this phase is complete.
+
+- [X] T001 Add `s3_public_base_url: str | None = None` to the `Settings` class in `api/app/config.py` (after `api_base_url`); add `S3_PUBLIC_BASE_URL=` with comment "# CDN base URL for serving images (e.g. https://cdn.example.com). Leave empty in local dev to use API proxy fallback." to `.env.example` after the `API_BASE_URL` line
+
+**Checkpoint**: Config in place — user story work can begin.
+
+---
+
+## Phase 2: User Story 1 — Images Load Directly from CDN (Priority: P1) 🎯 MVP
+
+**Goal**: API returns `file_url` and `thumbnail_url` in all image responses; UI uses those fields to render images rather than constructing proxy URLs client-side.
+
+**Independent Test**: With `S3_PUBLIC_BASE_URL=https://cdn.reactbin.juggalol.com` set, call `GET /api/v1/images` and confirm each item has `file_url` starting with `https://cdn.reactbin.juggalol.com/` and `thumbnail_url` starting with `https://cdn.reactbin.juggalol.com/` (or null). Open the library page in a browser and confirm image requests go to the CDN domain in the network panel.
+
+- [X] T002 [US1] Write unit tests in `api/tests/unit/test_url_construction.py` covering four cases: (1) CDN base set, image has thumbnail — `file_url` and `thumbnail_url` are CDN URLs; (2) CDN base set, image has no thumbnail — `thumbnail_url` is None; (3) CDN base not set, image has thumbnail — `file_url` is `/api/v1/images/{id}/file` and `thumbnail_url` is `/api/v1/images/{id}/thumbnail`; (4) CDN base not set, no thumbnail — `thumbnail_url` is None. Test the trailing-slash normalisation case (CDN base with trailing slash produces no double-slash). Import and call `_image_to_dict` directly with a mock `Image` object.
+
+- [X] T003 [US1] Update `_image_to_dict` in `api/app/routers/images.py`: add `cdn_base: str | None = None` keyword parameter; compute `_base = cdn_base.rstrip("/") if cdn_base else None`; set `file_url = f"{_base}/{image.storage_key}" if _base else f"/api/v1/images/{image.id}/file"`; set `thumbnail_url = (f"{_base}/{image.thumbnail_key}" if _base else f"/api/v1/images/{image.id}/thumbnail") if image.thumbnail_key else None`; add `"file_url": file_url` and `"thumbnail_url": thumbnail_url` to the returned dict. Run `make test-unit` and confirm T002 tests pass.
+
+- [X] T004 [US1] Update every `_image_to_dict(...)` call site in `api/app/routers/images.py`: at the top of each endpoint function that calls `_image_to_dict`, add `_cdn_base = get_settings().s3_public_base_url` (import `get_settings` is already present); pass `cdn_base=_cdn_base` to every `_image_to_dict` call in that endpoint. Affected endpoints: `upload_image`, `list_images`, `get_image`, `patch_image_tags`. Confirm `get_settings()` is called once per endpoint, not once per image in a loop (for `list_images`, call it before the list comprehension).
+
+- [X] T005 [US1] Update integration tests: in `api/tests/integration/test_upload.py`, add assertions after existing response checks that `"file_url"` is present in the response body and starts with `/api/v1/images/` (since no CDN is configured in test env); add the same assertion for `"thumbnail_url"` in `test_upload_returns_thumbnail_key`; add assertion that `thumbnail_url` is None in the test that expects `thumbnail_key` to be None. Run `make test-integration` and confirm all pass.
+
+- [X] T006 [P] [US1] Update `ui/src/app/services/image.service.ts`: add `file_url: string` and `thumbnail_url: string | null` to the `ImageRecord` interface; remove the `getFileUrl(id: string): string` method; remove the `getThumbnailUrl(id: string): string` method.
+
+- [X] T007 [P] [US1] Update `ui/src/app/library/library.component.ts`: replace `[src]="imageService.getThumbnailUrl(img.id)"` (line 77) with `[src]="img.thumbnail_url ?? img.file_url"` — fall back to `file_url` when thumbnail is absent (FR-009); update `ui/src/app/library/library.component.spec.ts` to add `file_url` and `thumbnail_url` to any mock `ImageRecord` objects and remove any references to `getThumbnailUrl()`.
+
+- [X] T008 [P] [US1] Update `ui/src/app/detail/detail.component.ts`: replace `[src]="imageService.getFileUrl(image.id)"` (line 52) with `[src]="image.file_url"`; update `ui/src/app/detail/detail.component.spec.ts` to add `file_url` and `thumbnail_url` to any mock `ImageRecord` objects and remove any references to `getFileUrl()`.
+
+- [X] T009 [US1] Update `ui/src/app/services/image.service.spec.ts`: add `file_url` and `thumbnail_url` fields to any mock `ImageRecord` objects used in tests; remove any test cases that test `getFileUrl()` or `getThumbnailUrl()` (these methods no longer exist). Run UI tests and confirm they pass.
+
+**Checkpoint**: US1 complete. API returns CDN URLs when configured; UI uses response fields to render images.
+
+---
+
+## Phase 3: User Story 2 — Local Development Works Without CDN (Priority: P2)
+
+**Goal**: Confirm that with no `S3_PUBLIC_BASE_URL` configured, `file_url` and `thumbnail_url` fall back to API proxy paths and images load correctly in local dev.
+
+**Independent Test**: Run `make test-unit && make test-integration` with no `S3_PUBLIC_BASE_URL` set (the default). Confirm all tests pass and that `file_url` values in integration test responses begin with `/api/v1/images/`.
+
+- [X] T010 [US2] Verify US2: run `make test-unit` and confirm the url-construction unit tests for the "no CDN base" case (T002 cases 3 and 4) pass; run `make test-integration` and confirm the updated upload tests (T005) pass — they already assert relative proxy paths since the test environment has no `S3_PUBLIC_BASE_URL`. Confirm `docker compose up` starts cleanly and images load in the browser via the proxy paths with no console errors.
+
+**Checkpoint**: US2 verified. Local development requires no additional configuration.
+
+---
+
+## Phase 4: Polish & Cross-Cutting Concerns
+
+- [X] T011 [P] Run `ruff check api/app/routers/images.py api/app/config.py` and fix any lint issues; run `ruff format --check` and format if needed.
+
+- [X] T012 Run end-to-end verification per `specs/014-r2-cdn-serving/quickstart.md`: in production with `S3_PUBLIC_BASE_URL` set, call `GET /api/v1/images` and confirm `file_url` and `thumbnail_url` begin with `https://cdn.reactbin.juggalol.com/`; open the library page in a browser and confirm image requests in the network panel go to `cdn.reactbin.juggalol.com`, not `/api/`.
+
+---
+
+## Dependencies & Execution Order
+
+- T001 must complete before any other task
+- T002 before T003 (tests before implementation — unit test first)
+- T003 before T004 (update helper before call sites)
+- T004 before T005 (implementation before integration tests)
+- T006, T007, T008 can run in parallel after T001 (different files)
+- T009 after T006 (spec depends on updated interface)
+- T010 after T003–T009 (verification requires full implementation)
+- T011 after T003–T004 (lint the changed files)
+- T012 last (manual end-to-end)
+
+### Execution Order Summary
+
+```
+Step 1: T001                          (foundational: config)
+Step 2: T002                          (US1: unit tests first)
+Step 3: T003                          (US1: implement _image_to_dict)
+Step 4: T004 ∥ T006 ∥ T007 ∥ T008    (US1: call sites + UI in parallel)
+Step 5: T005 ∥ T009                   (US1: integration tests + service spec)
+Step 6: T010                          (US2: verify local dev fallback)
+Step 7: T011                          (polish: lint)
+Step 8: T012                          (polish: manual end-to-end)
+```
+
+---
+
+## Implementation Strategy
+
+### MVP (US1 only — CDN URLs in API + UI)
+
+1. T001 — config
+2. T002–T005 — API implementation and tests
+3. T006–T009 — UI updates
+4. **STOP and VALIDATE**: `make test-unit && make test-integration`, check browser network panel
+
+### Incremental Delivery
+
+1. T001–T005 (API only) → deploy → verify CDN URLs appear in API responses
+2. T006–T009 (UI) → deploy → verify browser fetches images from CDN
+3. T010 (local dev verification) → confirm fallback intact
+4. T011–T012 (polish + end-to-end) → ship

specs/015-library-pagination/checklists/requirements.md

@@ -0,0 +1,34 @@
+# Specification Quality Checklist: Library Pagination UI
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2026-05-09
+**Feature**: [spec.md](../spec.md)
+
+## Content Quality
+
+- [X] No implementation details (languages, frameworks, APIs)
+- [X] Focused on user value and business needs
+- [X] Written for non-technical stakeholders
+- [X] All mandatory sections completed
+
+## Requirement Completeness
+
+- [X] No [NEEDS CLARIFICATION] markers remain
+- [X] Requirements are testable and unambiguous
+- [X] Success criteria are measurable
+- [X] Success criteria are technology-agnostic (no implementation details)
+- [X] All acceptance scenarios are defined
+- [X] Edge cases are identified
+- [X] Scope is clearly bounded
+- [X] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [X] All functional requirements have clear acceptance criteria
+- [X] User scenarios cover primary flows
+- [X] Feature meets measurable outcomes defined in Success Criteria
+- [X] No implementation details leak into specification
+
+## Notes
+
+- All items pass. Ready for `/speckit-plan`.

specs/015-library-pagination/contracts/pagination-query.md

@@ -0,0 +1,52 @@
+# Contract: Image List Pagination Query
+
+No new API endpoints are introduced. This document records the existing API contract the UI relies on for pagination.
+
+## Endpoint
+
+```
+GET /api/v1/images?limit={limit}&offset={offset}&tags={tags}
+```
+
+## Parameters
+
+| Parameter | Type    | Required | Description                                      |
+|-----------|---------|----------|--------------------------------------------------|
+| `limit`   | integer | No       | Images per page. UI sends `24`. Max is 100.      |
+| `offset`  | integer | No       | Number of images to skip. UI computes `(page-1) * 24`. |
+| `tags`    | string  | No       | Comma-separated tag names for AND-filter.        |
+
+## Response
+
+```json
+{
+  "items": [ /* ImageRecord[] */ ],
+  "total": 143,
+  "limit": 24,
+  "offset": 48
+}
+```
+
+| Field    | Type    | Description                                      |
+|----------|---------|--------------------------------------------------|
+| `total`  | integer | Total images matching the filter (all pages).    |
+| `limit`  | integer | Page size echoed back.                           |
+| `offset` | integer | Offset echoed back.                              |
+| `items`  | array   | Images for this page only.                       |
+
+## UI-Computed Values
+
+```
+totalPages = Math.ceil(total / limit)       // e.g. ceil(143 / 24) = 6
+currentPage = offset / limit + 1            // e.g. 48 / 24 + 1 = 3
+offset = (page - 1) * limit                // e.g. (3 - 1) * 24 = 48
+```
+
+## URL State
+
+| Query Param | Source              | Example          |
+|-------------|---------------------|------------------|
+| `page`      | current page number | `?page=3`        |
+| `tags`      | active tag filters  | `?tags=cat,funny` |
+
+Both params coexist: `/?page=3&tags=cat,funny`

specs/015-library-pagination/plan.md

@@ -0,0 +1,82 @@
+# Implementation Plan: Library Pagination UI
+
+**Branch**: `015-library-pagination` | **Date**: 2026-05-09 | **Spec**: [spec.md](spec.md)
+**Input**: Feature specification from `specs/015-library-pagination/spec.md`
+
+## Summary
+
+Replace the current "Load more" append-on-scroll pattern in the library with discrete page navigation (Previous/Next buttons, page indicator, total count). Page state is persisted to the URL query string for bookmarkability. No API or backend changes required — the API already supports `limit` and `offset` parameters.
+
+## Technical Context
+
+**Language/Version**: TypeScript (strict), Angular latest stable
+**Primary Dependencies**: Angular Router (query params for URL state), Angular HttpClient (existing)
+**Storage**: N/A — UI-only change
+**Testing**: Angular TestBed / Jasmine (existing test suite)
+**Target Platform**: Browser SPA
+**Project Type**: UI feature within existing Angular standalone component
+**Performance Goals**: Page load of 24 images replaces 50-image Load More; no regression
+**Constraints**: Must preserve existing tag filter query param (`?tags=`) when updating page param; must not break existing spec tests
+**Scale/Scope**: Single component change (`library.component.ts`) + its spec file
+
+## Constitution Check
+
+*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
+
+| Principle | Status | Notes |
+|-----------|--------|-------|
+| §2.1 Strict separation | ✅ PASS | UI communicates with API only via HTTP; no storage or DB knowledge in component |
+| §2.6 No speculative abstraction | ✅ PASS | No new abstractions introduced; pagination is a concrete change to one component |
+| §3.2 OpenAPI as contract | ✅ PASS | Uses existing `GET /api/v1/images?limit=&offset=` contract; no new endpoints |
+| §3.4 Pagination | ✅ PASS | This feature is the UI surface for the API pagination already in place |
+| §5.1 Tests alongside implementation | ✅ REQUIRED | Component spec must be updated alongside each changed behaviour |
+| §5.4 Test gate | ✅ REQUIRED | UI tests must pass; `make test-unit` passes before task marked done |
+| §6 Tech stack | ✅ PASS | Angular + TypeScript strict — no new dependencies needed |
+| §7.3 Linting | ✅ REQUIRED | ESLint + Prettier enforced; no lint regressions |
+| §8 Scope boundaries | ✅ PASS | Pagination is explicitly required (§3.4); no out-of-scope additions |
+
+**Post-Phase-1 re-check**: No contracts or data model introduced; no new violations.
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/015-library-pagination/
+├── plan.md              ← this file
+├── research.md          ← Phase 0 output
+├── quickstart.md        ← Phase 1 output
+├── contracts/
+│   └── pagination-query.md  ← Phase 1 output
+└── tasks.md             ← Phase 2 output (/speckit-tasks)
+```
+
+### Source Code (changes only)
+
+```text
+ui/src/app/library/
+├── library.component.ts      ← primary change
+└── library.component.spec.ts ← tests updated alongside
+```
+
+No other files change. No new files added to source tree.
+
+## Key Design Decisions
+
+### Page size: 24
+Fixed at 24 images per page (spec FR-011). Fits common grid widths (2/3/4/6 columns), is a meaningful reduction from the current silent 50-image cap, and divides cleanly. Not user-configurable.
+
+### Replace, don't append
+Current `loadMore()` appends items to the array. The new `goToPage(n)` replaces `this.images` entirely. The `offset` field becomes derived from page: `offset = (page - 1) * limit`.
+
+### URL state via Angular Router query params
+- `?page=2` added alongside existing `?tags=cat,funny`
+- Use `queryParamsHandling: 'merge'` when updating page to preserve tag params
+- Use `queryParamsHandling: 'merge'` when updating tags to preserve page reset (page always resets to 1 on filter change, so page param is removed or set to 1)
+- On `ngOnInit`, read `page` from `snapshot.queryParamMap`; clamp to valid range
+
+### Out-of-page-range handling
+If URL `?page=99` is requested but only 3 pages exist: silently load page 1. No error state.
+
+### Pagination controls visibility
+Only shown when `totalPages > 1`. Total pages = `Math.ceil(total / limit)`.

specs/015-library-pagination/quickstart.md

@@ -0,0 +1,41 @@
+# Quickstart: Library Pagination UI
+
+## Happy Path — Navigating Pages
+
+**Setup**: Library contains more than 24 images.
+
+1. Open `http://localhost:4200/`
+2. Confirm the image grid shows 24 images (not 50).
+3. Confirm "Page 1 of N" indicator and total count are visible above or below the grid.
+4. Confirm "Previous" button is absent or disabled.
+5. Click "Next" → grid replaces with the next 24 images; indicator updates to "Page 2 of N".
+6. Click "Previous" → first 24 images return; indicator shows "Page 1 of N".
+7. Navigate to the last page → "Next" is absent or disabled.
+
+## Happy Path — URL State
+
+1. Navigate to page 3 via "Next" button twice.
+2. Copy URL from address bar (should contain `?page=3`).
+3. Open URL in a new tab → page 3 loads directly.
+4. Press browser Back → page 2 loads.
+
+## Happy Path — Tag Filter Resets Page
+
+1. Navigate to page 2.
+2. Add a tag filter.
+3. Confirm page resets to 1; URL shows `?page=1&tags=<tag>` (or just `?tags=<tag>`).
+
+## Edge Case — Single Page
+
+1. Filter to a tag with fewer than 25 images.
+2. Confirm no pagination controls are rendered.
+
+## Edge Case — Out-of-Range URL
+
+1. Manually enter `/?page=9999` in the address bar.
+2. Confirm page 1 loads with no error message.
+
+## Edge Case — Empty Library
+
+1. With no images uploaded, open `/`.
+2. Confirm the existing empty state is shown; no pagination controls visible.

specs/015-library-pagination/research.md

@@ -0,0 +1,33 @@
+# Research: Library Pagination UI
+
+## Decision: Angular Router query params for URL state
+
+**Decision**: Use `this.router.navigate([], { queryParams: { page: n }, queryParamsHandling: 'merge' })` for page navigation and `snapshot.queryParamMap.get('page')` on init.
+
+**Rationale**: The library component already uses Angular Router for `?tags=` query params (added in feature 007). Extending the same pattern to `?page=` is the natural fit and keeps a single source of truth in the URL. The `queryParamsHandling: 'merge'` flag ensures that navigating to a new page does not erase the active `?tags=` filter, and vice versa.
+
+**Alternatives considered**:
+- Component-local state only (no URL): rejected — FR-008 requires bookmarkable URLs
+- `queryParamsHandling: ''` (replace): rejected — would erase `?tags=` param when changing pages
+
+---
+
+## Decision: Replace `loadMore()` with `goToPage(page: number)`
+
+**Decision**: Remove `loadMore()`, `hasMore`, and the append pattern. Replace with `goToPage(n)` that sets `this.images = []` and loads from `offset = (page - 1) * limit`.
+
+**Rationale**: The spec requires discrete pages (FR-001, FR-006). Keeping `loadMore()` alongside pagination would create conflicting UX. Clean removal is simpler and avoids two code paths.
+
+**Alternatives considered**:
+- Keep `loadMore()` as a fallback: rejected — two navigation patterns in one view is confusing
+
+---
+
+## Decision: No new dependencies
+
+**Decision**: Implement using existing Angular Router, HttpClient, and CDR. No pagination library imported.
+
+**Rationale**: The pagination logic is trivial (previous/next buttons, a counter, clamped page index). Pulling in a library for two buttons and a text label adds bundle weight and a dependency for no meaningful gain.
+
+**Alternatives considered**:
+- `ngx-pagination`: rejected — overkill for two-button prev/next pattern

specs/015-library-pagination/spec.md

@@ -0,0 +1,84 @@
+# Feature Specification: Library Pagination UI
+
+**Feature Branch**: `015-library-pagination`
+**Created**: 2026-05-09
+**Status**: Draft
+**Input**: User description: "Pagination UI for the image library"
+
+## User Scenarios & Testing *(mandatory)*
+
+### User Story 1 - Navigate Pages of Images (Priority: P1)
+
+A user with a large image library currently sees at most 50 images and a "Load more" button that appends more images below. There is no way to jump to a specific point in the library or know how many images exist in total. This story replaces the append-on-load pattern with page-by-page navigation: Previous/Next buttons and a "Page N of M" indicator so the user always knows where they are.
+
+**Why this priority**: The core usability gap — a library of any meaningful size is effectively unnavigable today. Without this, the feature has no value.
+
+**Independent Test**: Load the library page. Confirm a page indicator ("Page 1 of N") is visible and the total image count is shown. Click "Next" — confirm the next set of images loads and the indicator updates. Click "Previous" — confirm the first set returns. On the first page, "Previous" is absent or disabled. On the last page, "Next" is absent or disabled. Changing a tag filter resets to page 1.
+
+**Acceptance Scenarios**:
+
+1. **Given** the library has more images than fit on one page, **When** the page loads, **Then** only the first page of images is shown with a "Next" button and "Page 1 of N" indicator visible.
+2. **Given** the user is on page 1, **When** they click "Next", **Then** the next page of images replaces the current grid (not appended) and the indicator updates to "Page 2 of N".
+3. **Given** the user is on the last page, **When** they view the page, **Then** the "Next" button is absent or disabled and "Previous" is present.
+4. **Given** the user is on page 1, **When** they view the page, **Then** the "Previous" button is absent or disabled.
+5. **Given** the library has fewer images than one page, **When** the page loads, **Then** no pagination controls are shown.
+6. **Given** active tag filters are applied, **When** the user changes the filter, **Then** the page resets to 1 and the indicator updates.
+
+---
+
+### User Story 2 - Page State Reflected in URL (Priority: P2)
+
+The current library URL is always `/`. After implementing page navigation, a user who shares or bookmarks a URL should land on the same page they were viewing, not always page 1.
+
+**Why this priority**: Useful for bookmarking and sharing a specific point in the library, but the library is fully functional without it.
+
+**Independent Test**: Navigate to page 3 of the library. Copy the URL from the browser address bar. Open it in a new tab. Confirm page 3 loads directly. Confirm the Back button in the browser returns to page 2.
+
+**Acceptance Scenarios**:
+
+1. **Given** the user navigates to page 3, **When** the page URL is copied and opened in a new tab, **Then** page 3 loads directly without navigating through prior pages.
+2. **Given** the user navigates Next through several pages, **When** they press the browser Back button, **Then** the previous page is restored.
+3. **Given** the URL includes a page number beyond the total pages available, **When** the page loads, **Then** page 1 is shown rather than an error.
+
+---
+
+### Edge Cases
+
+- What happens when the total drops below the current page (e.g., images deleted in another session)? → Display page 1.
+- What happens when the library is empty? → No pagination controls shown; existing empty state displayed.
+- What happens when only one page of results exists? → No pagination controls shown.
+- What happens when a filter change results in fewer pages than the current page? → Reset to page 1.
+
+## Requirements *(mandatory)*
+
+### Functional Requirements
+
+- **FR-001**: The library MUST display images in discrete pages rather than an appending list.
+- **FR-002**: The library MUST show a page indicator displaying the current page number and total page count (e.g., "Page 2 of 7").
+- **FR-003**: The library MUST show the total number of images matching the current filters (e.g., "143 images").
+- **FR-004**: A "Next" control MUST be available on all pages except the last; a "Previous" control MUST be available on all pages except the first.
+- **FR-005**: Pagination controls MUST NOT be shown when all images fit on a single page.
+- **FR-006**: Navigating to a new page MUST replace the displayed images, not append to them.
+- **FR-007**: Changing a tag filter MUST reset the current page to 1.
+- **FR-008**: The current page number MUST be reflected in the URL query string so that the URL is bookmarkable and shareable.
+- **FR-009**: Loading a URL with a page parameter MUST display the correct page directly.
+- **FR-010**: A page parameter beyond the available range MUST silently fall back to page 1.
+- **FR-011**: The page size (number of images per page) MUST be 24 images.
+
+## Success Criteria *(mandatory)*
+
+### Measurable Outcomes
+
+- **SC-001**: A user can navigate from page 1 to any other page using only Previous/Next controls within 2 clicks per page.
+- **SC-002**: The total image count and current position are visible without scrolling on page load.
+- **SC-003**: A bookmarked or shared page URL loads the correct page 100% of the time (within the valid range).
+- **SC-004**: Changing a tag filter always resets to page 1 with no stale images from the previous page visible.
+- **SC-005**: Pages with fewer images than the page size (the last page) display correctly without layout breakage.
+
+## Assumptions
+
+- Page size is fixed at 24 images; no user-configurable page size is required.
+- The API already supports `limit` and `offset` parameters; no backend changes are needed.
+- The existing "Load more" / infinite-scroll pattern is fully replaced by page navigation.
+- Browser history integration (Back/Forward) is satisfied by URL query parameter updates.
+- Mobile responsiveness of pagination controls is required to match the existing library layout.

specs/015-library-pagination/tasks.md

@@ -0,0 +1,82 @@
+# Tasks: Library Pagination UI
+
+**Input**: Design documents from `specs/015-library-pagination/`
+**Prerequisites**: plan.md ✅, spec.md ✅, research.md ✅, contracts/pagination-query.md ✅, quickstart.md ✅
+
+**Tests**: Tests accompany each implementation task per §5.1. All changes are in `ui/src/app/library/library.component.ts` and its spec file.
+
+**Organization**: No setup or foundational phase needed — the Angular project and library component already exist. Phase 1 implements US1 (page navigation controls). Phase 2 adds US2 (URL state). Polish runs lint and manual verification.
+
+## Format: `[ID] [P?] [Story] Description`
+
+- **[P]**: Can run in parallel (different files, no dependencies)
+- **[Story]**: Which user story this task belongs to
+
+---
+
+## Phase 1: User Story 1 — Previous/Next Page Navigation (Priority: P1) 🎯 MVP
+
+**Goal**: Replace the "Load more" append pattern with discrete Previous/Next page navigation, a "Page N of M" indicator, and a total image count. Page size changes from 50 to 24.
+
+**Independent Test**: With at least 25 images in the library, open `/`. Confirm 24 images are shown, a "Page 1 of N" indicator is visible, "Previous" is absent, and "Next" is present. Click "Next" — confirm the grid is replaced (not appended) with the next 24 images and the indicator updates. Click "Previous" — confirm the first page returns. Apply a tag filter — confirm the page resets to 1.
+
+- [X] T001 [US1] Write tests in `ui/src/app/library/library.component.spec.ts` covering: (1) page indicator text "Page 1 of N" renders when totalPages > 1; (2) total count text renders (e.g. "143 images"); (3) "Next" button present when not on last page; (4) "Previous" button absent on first page; (5) "Previous" present and "Next" absent on last page; (6) no pagination controls rendered when all images fit on one page (total ≤ 24); (7) clicking "Next" calls `imageService.list` with offset=24; (8) clicking "Previous" from page 2 calls `imageService.list` with offset=0; (9) applying a filter resets to page 1 (offset=0). Run `ng test` and confirm the new tests FAIL (implementation pending).
+
+- [X] T002 [US1] Update `ui/src/app/library/library.component.ts`: (a) change `private readonly limit = 50` to `private readonly limit = 24`; (b) remove `hasMore` property and `loadMore()` method; (c) add properties `currentPage = 1`, `totalPages = 1`, `total = 0`; (d) rename/replace `load()` to call `imageService.list(this.activeFilters, this.limit, (this.currentPage - 1) * this.limit)` and on success set `this.images = res.items` (replace, not append), `this.total = res.total`, `this.totalPages = Math.ceil(res.total / this.limit)`, clamp `currentPage` to `Math.max(1, Math.min(this.currentPage, this.totalPages))`; (e) add `nextPage()` that increments `currentPage` and calls `load()`; (f) add `prevPage()` that decrements `currentPage` and calls `load()`; (g) in `applyFilter()`, reset `this.currentPage = 1` before calling `load()`; (h) replace the `<button class="load-more">` element in the template with a pagination bar: a "Previous" button bound to `(click)="prevPage()"` disabled/hidden when `currentPage === 1`, a "Page {{ currentPage }} of {{ totalPages }}" span, a "Next" button bound to `(click)="nextPage()"` disabled/hidden when `currentPage === totalPages`, and place a total count element showing "{{ total }} images" **outside** the pagination bar and outside the `*ngIf="totalPages > 1"` guard so it always renders when images exist (FR-003, SC-002); wrap only the Previous button, page indicator span, and Next button inside `*ngIf="totalPages > 1"`. Run `ng test` and confirm T001 tests pass.
+
+**Checkpoint**: US1 complete. Library shows paginated results with Previous/Next controls and page indicator.
+
+---
+
+## Phase 2: User Story 2 — Page State in URL (Priority: P2)
+
+**Goal**: Persist the current page number in the URL query string (`?page=N`) so that the URL is bookmarkable and the browser Back button works.
+
+**Independent Test**: Navigate to page 3. Copy the URL (should contain `?page=3`). Open in a new tab — confirm page 3 loads directly. Press browser Back — confirm page 2 is shown. Navigate to `/?page=9999` — confirm page 1 loads without error.
+
+- [X] T003 [US2] Add tests to `ui/src/app/library/library.component.spec.ts` covering: (1) on init with `?page=2` in queryParamMap, `currentPage` is set to 2 and `list` is called with `offset=24`; (2) on init with `?page=9999` and total of 48 images, `currentPage` is clamped to page 1; (3) `nextPage()` calls `router.navigate` with `queryParams: { page: 2 }` and `queryParamsHandling: 'merge'`; (4) `applyFilter()` calls `router.navigate` with `queryParams: { page: 1 }` and `queryParamsHandling: 'merge'`. Run `ng test` and confirm new tests FAIL.
+
+- [X] T004 [US2] Update `ui/src/app/library/library.component.ts`: (a) in `ngOnInit`, after reading the `tags` param, read `const pageParam = this.route.snapshot.queryParamMap.get('page')` and set `this.currentPage = pageParam ? Math.max(1, parseInt(pageParam, 10)) : 1` (out-of-range clamping happens after load when totalPages is known); (b) update `nextPage()` and `prevPage()` to call `this.router.navigate([], { queryParams: { page: this.currentPage }, queryParamsHandling: 'merge' })` after updating `currentPage`; (c) update `applyFilter()` to call `this.router.navigate([], { queryParams: { page: 1, tags: tags.join(',') || null }, queryParamsHandling: 'merge' })` when resetting to page 1 (pass `null` for tags to remove param when empty); (d) after load resolves and `totalPages` is known, clamp `currentPage` to `Math.min(this.currentPage, Math.max(1, this.totalPages))` and if clamped, call navigate to correct the URL. Run `ng test` and confirm T003 tests pass.
+
+**Checkpoint**: US2 complete. Page state persists in URL; Back button and direct links work.
+
+---
+
+## Phase 3: Polish & Cross-Cutting Concerns
+
+- [X] T005 Run `ng lint` on `ui/src/app/library/library.component.ts` and fix any issues; confirm `ng test` passes with all existing and new tests green; manually verify all quickstart.md scenarios in a browser (pagination controls, URL state, tag filter reset, single-page no-controls, out-of-range URL, empty state).
+
+---
+
+## Dependencies & Execution Order
+
+- T001 before T002 (write failing tests before implementation)
+- T002 before T003 (US2 tests build on US1 implementation)
+- T003 before T004 (write failing tests before implementation)
+- T004 before T005 (polish after full implementation)
+
+### Execution Order Summary
+
+```
+Step 1: T001   (US1: failing tests)
+Step 2: T002   (US1: implementation — tests turn green)
+Step 3: T003   (US2: failing tests)
+Step 4: T004   (US2: implementation — tests turn green)
+Step 5: T005   (polish: lint + manual verification)
+```
+
+---
+
+## Implementation Strategy
+
+### MVP (US1 only)
+
+1. T001–T002 — page navigation controls, limit change, replace append
+2. **STOP and VALIDATE**: open browser, confirm pagination controls appear and work
+3. Deploy if ready
+
+### Full Delivery
+
+1. T001–T002 (US1) → validate
+2. T003–T004 (US2) → validate URL state
+3. T005 (polish) → ship

specs/016-copy-url-toast/checklists/requirements.md

@@ -0,0 +1,34 @@
+# Specification Quality Checklist: Copy URL & Toast Notifications
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2026-05-09
+**Feature**: [spec.md](../spec.md)
+
+## Content Quality
+
+- [X] No implementation details (languages, frameworks, APIs)
+- [X] Focused on user value and business needs
+- [X] Written for non-technical stakeholders
+- [X] All mandatory sections completed
+
+## Requirement Completeness
+
+- [X] No [NEEDS CLARIFICATION] markers remain
+- [X] Requirements are testable and unambiguous
+- [X] Success criteria are measurable
+- [X] Success criteria are technology-agnostic (no implementation details)
+- [X] All acceptance scenarios are defined
+- [X] Edge cases are identified
+- [X] Scope is clearly bounded
+- [X] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [X] All functional requirements have clear acceptance criteria
+- [X] User scenarios cover primary flows
+- [X] Feature meets measurable outcomes defined in Success Criteria
+- [X] No implementation details leak into specification
+
+## Notes
+
+- All items pass. Ready to proceed to `/speckit-plan`.

specs/016-copy-url-toast/contracts/toast-service.md

@@ -0,0 +1,50 @@
+# Contract: ToastService
+
+**Location**: `ui/src/app/services/toast.service.ts`
+**Provided in**: `root` (singleton)
+
+## Interface
+
+```typescript
+interface Toast {
+  message: string;
+  type: 'success' | 'error';
+}
+
+class ToastService {
+  // Observable — emits a Toast when one is active, null when none.
+  readonly current$: Observable<Toast | null>;
+
+  // Show a toast. Replaces any currently-visible toast.
+  // duration defaults to 3000ms.
+  show(message: string, type?: 'success' | 'error', duration?: number): void;
+}
+```
+
+## Behaviour
+
+- `show()` emits the toast immediately on `current$`.
+- After `duration` ms, emits `null` to dismiss.
+- Calling `show()` again before the timer expires resets the timer (new toast replaces old).
+- `type` defaults to `'success'`.
+- `duration` defaults to `3000`.
+
+## Usage Example
+
+```typescript
+// In any component:
+constructor(private toast: ToastService) {}
+
+async copyUrl() {
+  try {
+    await navigator.clipboard.writeText(url);
+    this.toast.show('URL copied!');
+  } catch {
+    this.toast.show('Failed to copy URL', 'error');
+  }
+}
+```
+
+## Consumer: ToastComponent
+
+`ToastComponent` subscribes to `current$` via the `async` pipe and renders/hides based on the emitted value. It is placed once in `AppComponent` and is always present in the DOM.

specs/016-copy-url-toast/plan.md

@@ -0,0 +1,74 @@
+# Implementation Plan: Copy URL & Toast Notifications
+
+**Branch**: `016-copy-url-toast` | **Date**: 2026-05-09 | **Spec**: [spec.md](spec.md)
+**Input**: Feature specification from `specs/016-copy-url-toast/spec.md`
+
+## Summary
+
+Add a "Copy URL" button to the image detail page that copies the image's direct file URL to the clipboard, with a reusable toast notification service wired to confirm success or failure. All changes are UI-only; no API changes are required.
+
+## Technical Context
+
+**Language/Version**: TypeScript (strict mode), Angular latest stable
+**Primary Dependencies**: Angular (`@angular/core`, `@angular/common`), RxJS (`BehaviorSubject`), browser Clipboard API (`navigator.clipboard.writeText`)
+**Storage**: N/A
+**Testing**: Karma/Jasmine (`ng test`)
+**Target Platform**: Browser (modern; Clipboard API requires HTTPS — already in place)
+**Project Type**: Angular standalone SPA
+**Performance Goals**: Copy action completes in < 100ms perceived latency; toast appears within 300ms of action
+**Constraints**: TypeScript strict mode, `ChangeDetectionStrategy.OnPush` on all components, no new npm dependencies
+**Scale/Scope**: Two new files (service + component), two modified files (detail + app component)
+
+## Constitution Check
+
+*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
+
+| Principle | Status | Notes |
+|-----------|--------|-------|
+| §2.1 Strict separation of concerns | ✓ PASS | Pure UI change; no API knowledge in UI beyond what's already in `ImageRecord.file_url` |
+| §2.6 No speculative abstraction | ✓ PASS | Toast service is justified: used immediately by this feature and explicitly planned for reuse (upload confirmation, delete confirmation, filter feedback). Two concrete use cases exist. |
+| §5.1 Tests alongside implementation | ✓ PASS | Tests required for `ToastService` and the copy button on `DetailComponent` |
+| §5.2 Test pyramid | ✓ PASS | Unit tests only (no API/DB involved); Karma/Jasmine |
+| §6 Tech stack | ✓ PASS | Angular, TypeScript strict — no new dependencies |
+| §7.3 Linting | ✓ PASS | `ng lint` must pass before task is done |
+| §8 Scope boundaries | ✓ PASS | No multi-user, no embeds, no public sharing infrastructure — just a clipboard copy |
+
+**Post-design re-check**: No violations. Feature is entirely additive.
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/016-copy-url-toast/
+├── plan.md              ← this file
+├── research.md          ← Phase 0 output
+├── quickstart.md        ← Phase 1 output
+├── contracts/
+│   └── toast-service.md ← Phase 1 output
+└── tasks.md             ← /speckit-tasks output
+```
+
+### Source Code
+
+```text
+ui/src/app/
+├── app.component.ts              ← modified: add <app-toast> to template
+├── services/
+│   └── toast.service.ts          ← new: singleton toast service
+├── toast/
+│   └── toast.component.ts        ← new: toast display component
+└── detail/
+    └── detail.component.ts       ← modified: add Copy URL button + inject ToastService
+
+ui/src/app/services/
+    toast.service.spec.ts         ← new: unit tests for ToastService
+
+ui/src/app/toast/
+    toast.component.spec.ts       ← new: unit tests for ToastComponent
+
+ui/src/app/detail/
+    detail.component.spec.ts      ← modified: tests for copy button behaviour
+```
+
+**Structure Decision**: Single-project Angular SPA. Toast service lives in `services/` alongside `ImageService` and `TagService`. Toast component gets its own `toast/` directory following the existing component-per-directory convention.

specs/016-copy-url-toast/quickstart.md

@@ -0,0 +1,33 @@
+# Quickstart: Copy URL & Toast Notifications
+
+## Happy Path — Copy URL
+
+1. Open any image detail page (e.g. `http://localhost:4200/images/{id}`).
+2. Confirm a "Copy URL" button is visible.
+3. Click "Copy URL".
+4. Confirm a success toast appears ("URL copied!" or similar) and then disappears automatically.
+5. Paste into a text editor — confirm the pasted value is the full image file URL.
+
+## Happy Path — Toast Auto-Dismiss
+
+1. Click "Copy URL".
+2. Confirm the toast appears.
+3. Do not interact — wait ~3 seconds.
+4. Confirm the toast disappears on its own.
+
+## Edge Case — Clipboard Unavailable
+
+1. In Firefox, navigate to `about:config` and set `dom.events.asyncClipboard.clipboardItem` to `false` (or test with a non-HTTPS localhost where clipboard API may be blocked).
+2. Click "Copy URL".
+3. Confirm an error toast appears (e.g. "Failed to copy URL") and auto-dismisses.
+
+## Edge Case — Rapid Clicks
+
+1. Click "Copy URL" three times quickly.
+2. Confirm only one toast is visible at a time (new toast replaces old, no overlapping stack).
+
+## Regression — Other Pages
+
+1. Navigate to the library (`/`), upload page (`/upload`), tags page (`/tags`).
+2. Confirm no toast or copy button is visible on these pages.
+3. Confirm existing functionality is unaffected.

specs/016-copy-url-toast/research.md

@@ -0,0 +1,55 @@
+# Research: Copy URL & Toast Notifications
+
+## Decision 1: Toast Service Architecture
+
+**Decision**: `BehaviorSubject<Toast | null>` singleton service, one active toast at a time — new toasts replace the current one.
+
+**Rationale**: The simplest approach that satisfies FR-007 (reusable from anywhere) and FR-008 (multiple toasts don't overlap illegibly). A queue adds complexity with no meaningful UX benefit for this app's usage pattern (copy URL, upload confirm, etc. — actions that don't overlap in practice). Replacing the current toast on rapid successive calls is acceptable and visually cleaner than a stack. The `BehaviorSubject` integrates naturally with Angular's `async` pipe and OnPush change detection.
+
+**Alternatives considered**:
+- `Subject` (not `BehaviorSubject`): Late subscribers miss toasts that already fired. Rejected — component may subscribe after service emits if change detection is deferred.
+- Toast queue (array): Adds observable complexity and UI layout decisions. Rejected — over-engineered for this use case.
+- Angular CDK Overlay: Official but heavy. Pulls in CDK dependency for a feature that needs ~30 lines of code. Rejected per §2.6 (no speculative abstraction) and §6 (no new dependencies).
+
+---
+
+## Decision 2: Clipboard API Usage
+
+**Decision**: `navigator.clipboard.writeText(url)` — no polyfill, no fallback to `document.execCommand`.
+
+**Rationale**: `execCommand('copy')` is deprecated and removed in some browsers. The Clipboard API is supported in all modern browsers (Chrome 66+, Firefox 63+, Safari 13.1+). The app already requires HTTPS in production (Let's Encrypt via cert-manager), which satisfies the Clipboard API's secure context requirement. On failure (permission denied, API unavailable), catch the rejected Promise and show an error toast.
+
+**Alternatives considered**:
+- `execCommand('copy')` fallback: Deprecated, inconsistent, adds code complexity. The failure path (error toast) covers the rare unavailability case more cleanly.
+
+---
+
+## Decision 3: What URL to Copy
+
+**Decision**: Copy `image.file_url` as-is (the direct image file URL).
+
+**Rationale**: `file_url` is the CDN URL in production (e.g. `https://cdn.reactbin.juggalol.com/…`) — already absolute. In development it is relative (`/api/v1/images/{id}/file`); for dev use, prepend `window.location.origin`. The direct file URL is the right thing to share for a reaction image library: it embeds inline when pasted into Discord/Slack without requiring a click-through.
+
+**Alternatives considered**:
+- Detail page URL (`/images/{id}`): The user can already copy this from the browser address bar. The file URL is the value-add.
+- Always prepend `window.location.origin`: Works for both environments, adds a guard. Included as a defensive measure for the dev case.
+
+---
+
+## Decision 4: Toast Positioning
+
+**Decision**: Fixed position, bottom-center of the viewport.
+
+**Rationale**: Bottom-center is less intrusive than top-right for a brief confirmation toast. It doesn't overlap the image or the copy button. `pointer-events: none` ensures it never blocks interaction.
+
+**Alternatives considered**:
+- Top-right: Common convention (Material, Bootstrap) but overlaps the header/nav area in this layout.
+- Top-center: Similar issue.
+
+---
+
+## Decision 5: OnPush compatibility
+
+**Decision**: `ToastComponent` uses `ChangeDetectionStrategy.OnPush` with the `async` pipe consuming `toastService.current$`. Angular's `async` pipe calls `markForCheck()` automatically when the observable emits, making it fully compatible with OnPush.
+
+**Rationale**: Consistent with all other components in the project. No manual `markForCheck()` calls needed in `ToastComponent`.

specs/016-copy-url-toast/spec.md

@@ -0,0 +1,76 @@
+# Feature Specification: Copy URL & Toast Notifications
+
+**Feature Branch**: `016-copy-url-toast`
+**Created**: 2026-05-09
+**Status**: Draft
+
+## User Scenarios & Testing *(mandatory)*
+
+### User Story 1 - Copy Image URL from Detail Page (Priority: P1)
+
+A user viewing an image on the detail page wants to share the direct link to that image. They click a "Copy URL" button and the image's direct URL is instantly copied to their clipboard, ready to paste anywhere.
+
+**Why this priority**: This is the core feature and the primary user value. Everything else builds on it.
+
+**Independent Test**: Open any image detail page. Click the "Copy URL" button. Paste into a text editor — confirm the pasted value is the direct URL to that image.
+
+**Acceptance Scenarios**:
+
+1. **Given** a user is on an image detail page, **When** they click "Copy URL", **Then** the image's direct URL is copied to their clipboard.
+2. **Given** a user clicks "Copy URL", **When** the copy succeeds, **Then** a confirmation toast appears briefly and disappears on its own.
+3. **Given** a user clicks "Copy URL", **When** the clipboard is unavailable (e.g. browser denies permission), **Then** a toast appears indicating the copy failed.
+
+---
+
+### User Story 2 - Reusable Toast Notification System (Priority: P2)
+
+Any part of the application can trigger a brief, non-blocking notification (toast) to confirm an action or surface an error. The toast appears, persists for a short time, then disappears automatically without user interaction.
+
+**Why this priority**: The toast infrastructure is needed by US1 and is designed as a foundation for future features (e.g. upload confirmation, filter saved, delete confirmed).
+
+**Independent Test**: Trigger a toast programmatically. Confirm it appears with the correct message, then disappears automatically after a few seconds without any user interaction.
+
+**Acceptance Scenarios**:
+
+1. **Given** a toast is triggered, **When** it appears, **Then** it displays the provided message and is visible above other content.
+2. **Given** a toast is visible, **When** sufficient time passes, **Then** it disappears automatically without user interaction.
+3. **Given** multiple toasts are triggered in quick succession, **When** they appear, **Then** they stack or queue without overlapping illegibly.
+4. **Given** a toast is visible, **When** the user interacts with the rest of the page, **Then** the toast does not block or intercept those interactions.
+
+---
+
+### Edge Cases
+
+- What happens when the clipboard API is not available or permission is denied? → Show an error toast.
+- What happens if the user clicks "Copy URL" multiple times rapidly? → Each click copies and shows a toast; toasts queue or stack cleanly.
+- What happens on a very long URL? → URL is copied in full; toast message is fixed (not the URL itself).
+
+## Requirements *(mandatory)*
+
+### Functional Requirements
+
+- **FR-001**: The image detail page MUST display a "Copy URL" button.
+- **FR-002**: Clicking "Copy URL" MUST copy the image's direct URL to the system clipboard.
+- **FR-003**: A success toast MUST appear after a successful copy, confirming the action to the user.
+- **FR-004**: A failure toast MUST appear if the copy cannot be completed (e.g. clipboard permission denied).
+- **FR-005**: Toasts MUST disappear automatically after a fixed duration without requiring user interaction.
+- **FR-006**: Toasts MUST NOT block user interaction with the rest of the page.
+- **FR-007**: The toast system MUST be reusable — any part of the application must be able to trigger a toast with a custom message.
+- **FR-008**: Multiple toasts triggered in quick succession MUST display without overlapping illegibly.
+
+## Success Criteria *(mandatory)*
+
+### Measurable Outcomes
+
+- **SC-001**: A user can copy an image URL in a single click with no additional steps.
+- **SC-002**: Toast confirmation appears within 300ms of the copy action completing.
+- **SC-003**: Toasts disappear automatically within 5 seconds of appearing.
+- **SC-004**: The toast system can be triggered from any page or component without modifying the toast component itself.
+
+## Assumptions
+
+- The image's direct URL is already available on the detail page (it is — currently displayed or derivable from the current route and API response).
+- Users are on modern browsers with Clipboard API support; graceful degradation covers the failure case via an error toast.
+- One toast variant is sufficient for v1: a simple text message with success/error styling. No actions, no dismiss button required.
+- Toast duration of approximately 3 seconds is appropriate (standard convention).
+- The detail page already exists; this feature adds to it without redesigning it.

specs/016-copy-url-toast/tasks.md

@@ -0,0 +1,94 @@
+# Tasks: Copy URL & Toast Notifications
+
+**Input**: Design documents from `specs/016-copy-url-toast/`
+**Prerequisites**: plan.md ✅, spec.md ✅, research.md ✅, contracts/toast-service.md ✅, quickstart.md ✅
+
+**Tests**: Tests accompany each implementation task per §5.1. All changes are in `ui/src/app/`.
+
+**Organization**: No project setup needed — Angular project exists. The toast infrastructure (US2) must be built before the copy URL feature (US1) can use it, so phases follow implementation dependency order rather than spec priority order.
+
+## Format: `[ID] [P?] [Story] Description`
+
+- **[P]**: Can run in parallel (different files, no dependencies)
+- **[Story]**: Which user story this task belongs to
+
+---
+
+## Phase 1: Toast Infrastructure — User Story 2 (Foundational)
+
+**Goal**: Build the reusable `ToastService` and `ToastComponent` that US1 and all future features depend on.
+
+**Independent Test**: In the browser console, call `toastService.show('Hello!')` from any page — confirm a toast appears at the bottom of the screen for ~3 seconds then disappears. Confirm no interaction with the rest of the UI is blocked.
+
+- [X] T001 [US2] Write tests in `ui/src/app/services/toast.service.spec.ts` covering: (1) `show()` emits a `Toast` object on `current$` with the correct `message` and `type`; (2) after the duration elapses, `current$` emits `null`; (3) `type` defaults to `'success'` when not provided; (4) calling `show()` a second time before the first timer fires replaces the active toast. Run `ng test` and confirm new tests FAIL.
+
+- [X] T002 [US2] Create `ui/src/app/services/toast.service.ts`: (a) define `export interface Toast { message: string; type: 'success' | 'error'; }`; (b) `@Injectable({ providedIn: 'root' })` class with a private `BehaviorSubject<Toast | null>(null)`; (c) expose `readonly current$: Observable<Toast | null>` from the subject; (d) implement `show(message: string, type: 'success' | 'error' = 'success', duration = 3000): void` — emits the toast immediately, then calls `setTimeout(() => this.subject.next(null), duration)` (store the timer handle and `clearTimeout` it at the start of `show()` so rapid calls replace correctly). Run `ng test` and confirm T001 tests pass.
+
+- [X] T003 [P] [US2] Write tests in `ui/src/app/toast/toast.component.spec.ts` covering: (1) when `ToastService.current$` emits a `{ message: 'Done', type: 'success' }` toast, a `.toast` element is rendered containing "Done"; (2) the element has the CSS class `success`; (3) when type is `'error'`, the element has class `error`; (4) when `current$` emits `null`, no `.toast` element is present. Run `ng test` and confirm new tests FAIL.
+
+- [X] T004 [US2] Create `ui/src/app/toast/toast.component.ts`: (a) standalone component, `selector: 'app-toast'`, `ChangeDetectionStrategy.OnPush`, imports `[CommonModule]`; (b) inject `ToastService` as public; (c) template: `<div *ngIf="toastService.current$ | async as toast" class="toast" [class.success]="toast.type === 'success'" [class.error]="toast.type === 'error'">{{ toast.message }}</div>`; (d) styles: `.toast { position: fixed; bottom: 24px; left: 50%; transform: translateX(-50%); padding: 10px 20px; border-radius: var(--radius); font-size: 0.9rem; pointer-events: none; z-index: 1000; white-space: nowrap; }` with `.success { background: var(--surface-raised); color: var(--text); border: 1px solid var(--border); }` and `.error { background: var(--danger); color: var(--danger-text); }`. Run `ng test` and confirm T003 tests pass.
+
+- [X] T005 [US2] Register `ToastComponent` in `ui/src/app/app.component.ts`: add `ToastComponent` to the `imports` array; add `<app-toast></app-toast>` to the template after `<router-outlet />`; add a test to `ui/src/app/app.component.spec.ts` asserting that an `app-toast` element is present in the rendered output. Confirm all existing AppComponent tests still pass and `ng build --configuration development` succeeds.
+
+**Checkpoint**: Toast infrastructure complete. Any component in the app can now inject `ToastService` and call `show()`.
+
+---
+
+## Phase 2: Copy URL Button — User Story 1 (Priority: P1) 🎯 MVP
+
+**Goal**: Add a "Copy URL" button to the image detail page. One click copies the direct image file URL to the clipboard and shows a confirmation toast.
+
+**Independent Test**: Open any image detail page. Click "Copy URL". Confirm a success toast appears. Paste into a text editor and confirm the pasted value is the full image file URL. Then simulate a clipboard failure (e.g. revoke clipboard permission) and confirm an error toast appears instead.
+
+- [X] T006 [US1] Write tests in `ui/src/app/detail/detail.component.spec.ts` covering: (1) a "Copy URL" button (`.copy-url-btn`) is present in the DOM when an image is loaded; (2) clicking it calls `navigator.clipboard.writeText` with the image's `file_url` when `file_url` is already absolute (starts with `http`); (3) when `file_url` is relative (starts with `/`), `writeText` is called with `window.location.origin + file_url`; (4) when `writeText` resolves, `toastService.show` is called with a success message; (5) when `writeText` rejects, `toastService.show` is called with an error message and type `'error'`. Spy on `navigator.clipboard.writeText` using `spyOn(navigator.clipboard, 'writeText')` returning `Promise.resolve()` / `Promise.reject()` as appropriate. Run `ng test` and confirm new tests FAIL.
+
+- [X] T007 [US1] Update `ui/src/app/detail/detail.component.ts`: (a) inject `ToastService` (add to constructor); (b) add `copyUrl(): void` method — resolves the URL as `this.image!.file_url.startsWith('http') ? this.image!.file_url : window.location.origin + this.image!.file_url`, then calls `navigator.clipboard.writeText(url).then(() => this.toastService.show('URL copied!')).catch(() => this.toastService.show('Failed to copy URL', 'error'))`; (c) add a `<button class="copy-url-btn" (click)="copyUrl()">Copy URL</button>` to the template inside the `*ngIf="image && !loading"` block, placed below the image and above the tags section; (d) style: `padding: 8px 20px; background: var(--surface-raised); color: var(--text); border: 1px solid var(--border); border-radius: var(--radius); cursor: pointer; margin: 12px 0;` with hover `border-color: var(--border-focus)`. Run `ng test` and confirm T006 tests pass.
+
+**Checkpoint**: US1 complete. Detail page has a working Copy URL button with toast feedback.
+
+---
+
+## Phase 3: Polish & Cross-Cutting Concerns
+
+- [X] T008 Run `ng lint` on all modified and created files in `ui/src/app/`; fix any issues. Confirm `ng test` passes with all new and existing tests green. Manually verify all `quickstart.md` scenarios in a browser: happy path copy, auto-dismiss, clipboard error, rapid clicks, regression on other pages.
+
+---
+
+## Dependencies & Execution Order
+
+- T001 before T002 (write failing tests before service implementation)
+- T002 before T003/T004 (service must exist for component tests to import it)
+- T003 before T004 (write failing tests before component implementation)
+- T004 before T005 (component must exist before registering in app)
+- T005 before T006 (toast infrastructure must be complete before copy URL tests)
+- T006 before T007 (write failing tests before detail component changes)
+- T007 before T008 (implementation before polish)
+
+### Execution Order Summary
+
+```
+Step 1: T001   (US2: failing ToastService tests)
+Step 2: T002   (US2: ToastService implementation — tests turn green)
+Step 3: T003   (US2: failing ToastComponent tests)  [can parallel with T002 if needed]
+Step 4: T004   (US2: ToastComponent implementation — tests turn green)
+Step 5: T005   (US2: wire ToastComponent into AppComponent)
+Step 6: T006   (US1: failing copy URL tests)
+Step 7: T007   (US1: copy URL implementation — tests turn green)
+Step 8: T008   (Polish: lint + manual verification)
+```
+
+---
+
+## Implementation Strategy
+
+### MVP (US1 — single story delivers full feature value)
+
+1. T001–T005 — toast infrastructure
+2. T006–T007 — copy URL button
+3. **STOP and VALIDATE**: open browser, click Copy URL, confirm toast, paste to verify URL
+4. T008 — polish
+5. Deploy
+
+### Note on Priority Ordering
+
+US2 (toast system) is listed as P2 in the spec because it is infrastructure rather than the end-user-visible feature. However it is a hard implementation prerequisite for US1 (P1). Phases follow implementation dependency order: US2 infrastructure is built first, US1 feature consumes it second.

ui/karma.conf.js

@@ -5,6 +5,7 @@ module.exports = function (config) {
     plugins: [
       require('karma-jasmine'),
       require('karma-chrome-launcher'),
+      require('karma-firefox-launcher'),
       require('karma-jasmine-html-reporter'),
       require('karma-coverage'),
       require('@angular-devkit/build-angular/plugins/karma'),

ui/package-lock.json

@@ -31,6 +31,7 @@
         "karma": "~6.4.0",
         "karma-chrome-launcher": "~3.2.0",
         "karma-coverage": "~2.2.0",
+        "karma-firefox-launcher": "^2.1.3",
         "karma-jasmine": "~5.1.0",
         "karma-jasmine-html-reporter": "~2.1.0",
         "prettier": "^3.2.0",
@@ -10829,6 +10830,62 @@
         "semver": "bin/semver.js"
       }
     },
+    "node_modules/karma-firefox-launcher": {
+      "version": "2.1.3",
+      "resolved": "https://registry.npmjs.org/karma-firefox-launcher/-/karma-firefox-launcher-2.1.3.tgz",
+      "integrity": "sha512-LMM2bseebLbYjODBOVt7TCPP9OI2vZIXCavIXhkO9m+10Uj5l7u/SKoeRmYx8FYHTVGZSpk6peX+3BMHC1WwNw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "is-wsl": "^2.2.0",
+        "which": "^3.0.0"
+      }
+    },
+    "node_modules/karma-firefox-launcher/node_modules/is-docker": {
+      "version": "2.2.1",
+      "resolved": "https://registry.npmjs.org/is-docker/-/is-docker-2.2.1.tgz",
+      "integrity": "sha512-F+i2BKsFrH66iaUFc0woD8sLy8getkwTwtOBjvs56Cx4CgJDeKQeqfz8wAYiSb8JOprWhHH5p77PbmYCvvUuXQ==",
+      "dev": true,
+      "license": "MIT",
+      "bin": {
+        "is-docker": "cli.js"
+      },
+      "engines": {
+        "node": ">=8"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/karma-firefox-launcher/node_modules/is-wsl": {
+      "version": "2.2.0",
+      "resolved": "https://registry.npmjs.org/is-wsl/-/is-wsl-2.2.0.tgz",
+      "integrity": "sha512-fKzAra0rGJUUBwGBgNkHZuToZcn+TtXHpeCgmkMJMMYx1sQDYaCSyjJBSCa2nH1DGm7s3n1oBnohoVTBaN7Lww==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "is-docker": "^2.0.0"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/karma-firefox-launcher/node_modules/which": {
+      "version": "3.0.1",
+      "resolved": "https://registry.npmjs.org/which/-/which-3.0.1.tgz",
+      "integrity": "sha512-XA1b62dzQzLfaEOSQFTCOd5KFf/1VSzZo7/7TUjnya6u0vGGKzU96UQBZTAThCb2j4/xjBAyii1OhRLJEivHvg==",
+      "dev": true,
+      "license": "ISC",
+      "dependencies": {
+        "isexe": "^2.0.0"
+      },
+      "bin": {
+        "node-which": "bin/which.js"
+      },
+      "engines": {
+        "node": "^14.17.0 || ^16.13.0 || >=18.0.0"
+      }
+    },
     "node_modules/karma-jasmine": {
       "version": "5.1.0",
       "resolved": "https://registry.npmjs.org/karma-jasmine/-/karma-jasmine-5.1.0.tgz",

ui/package.json

@@ -33,6 +33,7 @@
     "karma": "~6.4.0",
     "karma-chrome-launcher": "~3.2.0",
     "karma-coverage": "~2.2.0",
+    "karma-firefox-launcher": "^2.1.3",
     "karma-jasmine": "~5.1.0",
     "karma-jasmine-html-reporter": "~2.1.0",
     "prettier": "^3.2.0",

ui/public/site.webmanifest

@@ -0,0 +1 @@
+{"name":"","short_name":"","icons":[{"src":"/android-chrome-192x192.png","sizes":"192x192","type":"image/png"},{"src":"/android-chrome-512x512.png","sizes":"512x512","type":"image/png"}],"theme_color":"#ffffff","background_color":"#ffffff","display":"standalone"}

ui/src/app/app.component.spec.ts

@@ -83,6 +83,14 @@ describe('AppComponent', () => {
     expect(link.getAttribute('href')).toBe('/');
   });
 
+  it('renders app-toast element', () => {
+    authSpy.isAuthenticated.and.returnValue(false);
+    const fixture = TestBed.createComponent(AppComponent);
+    fixture.detectChanges();
+    const toast = (fixture.nativeElement as HTMLElement).querySelector('app-toast');
+    expect(toast).not.toBeNull();
+  });
+
   it('header height is 48px', () => {
     authSpy.isAuthenticated.and.returnValue(true);
     const fixture = TestBed.createComponent(AppComponent);

ui/src/app/app.component.ts

@@ -2,17 +2,19 @@ import { Component } from '@angular/core';
 import { CommonModule } from '@angular/common';
 import { Router, RouterLink, RouterOutlet } from '@angular/router';
 import { AuthService } from './auth/auth.service';
+import { ToastComponent } from './toast/toast.component';
 
 @Component({
   selector: 'app-root',
   standalone: true,
-  imports: [CommonModule, RouterLink, RouterOutlet],
+  imports: [CommonModule, RouterLink, RouterOutlet, ToastComponent],
   template: `
     <header class="app-header">
       <a routerLink="/" class="app-name">Reactbin</a>
       <button *ngIf="auth.isAuthenticated()" class="logout-btn" (click)="onLogout()">Sign out</button>
     </header>
     <router-outlet />
+    <app-toast></app-toast>
   `,
   styles: [`
     :host { display: block; }

ui/src/app/detail/detail.component.spec.ts

@@ -5,13 +5,16 @@ import { provideHttpClientTesting } from '@angular/common/http/testing';
 import { of, throwError, Subject } from 'rxjs';
 import { DetailComponent } from './detail.component';
 import { ImageService } from '../services/image.service';
+import { ToastService } from '../services/toast.service';
 import { routes } from '../app.routes';
 
 const MOCK_IMAGE = {
   id: 'img-1', hash: 'abc', filename: 'test.jpg', mime_type: 'image/jpeg',
   size_bytes: 100, width: 10, height: 10, storage_key: 'abc',
-  thumbnail_key: null, created_at: '2026-01-01T00:00:00Z', tags: ['cat', 'funny'],
+  thumbnail_key: null, file_url: '/api/v1/images/img-1/file', thumbnail_url: null,
+  created_at: '2026-01-01T00:00:00Z', tags: ['cat', 'funny'],
 };
+const MOCK_IMAGE_ABS = { ...MOCK_IMAGE, file_url: 'https://cdn.example.com/img-1.jpg' };
 
 describe('DetailComponent', () => {
   function setup(imageId = 'img-1', imageResponse = of(MOCK_IMAGE)) {
@@ -142,4 +145,52 @@ describe('DetailComponent', () => {
     fixture.componentInstance.onImgError({ target: imgEl } as unknown as Event);
     expect(imgEl.src).toBe(before);
   });
+
+  // ---- Copy URL ----
+
+  it('Copy URL button is present when image is loaded', () => {
+    const { fixture } = setup();
+    expect((fixture.nativeElement as HTMLElement).querySelector('.copy-url-btn')).not.toBeNull();
+  });
+
+  it('copyUrl() calls writeText with file_url when it is already absolute', async () => {
+    const { component } = setup('img-1', of(MOCK_IMAGE_ABS));
+    const toast = TestBed.inject(ToastService);
+    spyOn(toast, 'show');
+    spyOn(navigator.clipboard, 'writeText').and.returnValue(Promise.resolve());
+    component.copyUrl();
+    await Promise.resolve();
+    expect(navigator.clipboard.writeText).toHaveBeenCalledWith(MOCK_IMAGE_ABS.file_url);
+  });
+
+  it('copyUrl() prepends window.location.origin when file_url is relative', async () => {
+    const { component } = setup();
+    const toast = TestBed.inject(ToastService);
+    spyOn(toast, 'show');
+    spyOn(navigator.clipboard, 'writeText').and.returnValue(Promise.resolve());
+    component.copyUrl();
+    await Promise.resolve();
+    expect(navigator.clipboard.writeText).toHaveBeenCalledWith(window.location.origin + MOCK_IMAGE.file_url);
+  });
+
+  it('copyUrl() calls toast.show with success message on writeText resolve', async () => {
+    const { component } = setup();
+    const toast = TestBed.inject(ToastService);
+    spyOn(toast, 'show');
+    spyOn(navigator.clipboard, 'writeText').and.returnValue(Promise.resolve());
+    component.copyUrl();
+    await Promise.resolve();
+    expect(toast.show).toHaveBeenCalledWith('URL copied!');
+  });
+
+  it('copyUrl() calls toast.show with error message on writeText reject', async () => {
+    const { component } = setup();
+    const toast = TestBed.inject(ToastService);
+    spyOn(toast, 'show');
+    spyOn(navigator.clipboard, 'writeText').and.returnValue(Promise.reject(new Error('denied')));
+    component.copyUrl();
+    await Promise.resolve();
+    await Promise.resolve();
+    expect(toast.show).toHaveBeenCalledWith('Failed to copy URL', 'error');
+  });
 });

ui/src/app/detail/detail.component.ts

@@ -4,6 +4,7 @@ import { FormsModule } from '@angular/forms';
 import { ActivatedRoute, Router, RouterLink } from '@angular/router';
 import { ImageRecord, ImageService } from '../services/image.service';
 import { AuthService } from '../auth/auth.service';
+import { ToastService } from '../services/toast.service';
 
 const PLACEHOLDER_SVG = `data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="800" height="500" viewBox="0 0 800 500"><rect width="800" height="500" fill="%23111"/><text x="50%" y="50%" dominant-baseline="middle" text-anchor="middle" font-size="48" fill="%23444">&#x1F517;</text></svg>`;
 
@@ -49,11 +50,13 @@ const PLACEHOLDER_SVG = `data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/s
 
       <img
         class="full-image"
-        [src]="imageService.getFileUrl(image.id)"
+        [src]="image.file_url"
         [alt]="image.filename"
         (error)="onImgError($event)"
       />
 
+      <button class="copy-url-btn" (click)="copyUrl()">Copy URL</button>
+
       <section class="tags-section">
         <h3>Tags</h3>
         <div class="chips">
@@ -139,6 +142,10 @@ const PLACEHOLDER_SVG = `data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/s
     .add-tag input:focus { outline: none; border-color: var(--border-focus); }
     .delete-btn { padding: 10px 24px; background: var(--danger); color: var(--danger-text); border: none; border-radius: var(--radius); cursor: pointer; margin-left: auto; }
 
+    /* Copy URL */
+    .copy-url-btn { padding: 8px 20px; background: var(--surface-raised); color: var(--text); border: 1px solid var(--border); border-radius: var(--radius); cursor: pointer; margin: 12px 0; transition: border-color var(--transition); }
+    .copy-url-btn:hover { border-color: var(--border-focus); }
+
     /* Delete dialog */
     .dialog-overlay { position: fixed; inset: 0; background: rgba(0,0,0,0.7); display: flex; align-items: center; justify-content: center; z-index: 100; }
     .dialog { background: var(--surface); padding: 32px; border-radius: 10px; text-align: center; }
@@ -163,6 +170,7 @@ export class DetailComponent implements OnInit {
     private route: ActivatedRoute,
     public router: Router,
     private cdr: ChangeDetectorRef,
+    private toastService: ToastService,
   ) {}
 
   ngOnInit(): void {
@@ -235,6 +243,16 @@ export class DetailComponent implements OnInit {
     this.cdr.markForCheck();
   }
 
+  copyUrl(): void {
+    if (!this.image) return;
+    const url = this.image.file_url.startsWith('http')
+      ? this.image.file_url
+      : window.location.origin + this.image.file_url;
+    navigator.clipboard.writeText(url)
+      .then(() => this.toastService.show('URL copied!'))
+      .catch(() => this.toastService.show('Failed to copy URL', 'error'));
+  }
+
   goBack(): void { this.router.navigate(['/']); }
 
   onImgError(event: Event): void {

ui/src/app/library/library.component.spec.ts

@@ -1,26 +1,33 @@
 import { TestBed } from '@angular/core/testing';
-import { provideRouter, ActivatedRoute } from '@angular/router';
+import { provideRouter, ActivatedRoute, Router } from '@angular/router';
 import { provideHttpClient } from '@angular/common/http';
 import { provideHttpClientTesting } from '@angular/common/http/testing';
-import { of } from 'rxjs';
+import { of, throwError } from 'rxjs';
 import { LibraryComponent } from './library.component';
 import { ImageService } from '../services/image.service';
 import { routes } from '../app.routes';
 
 function makeActivatedRoute(queryParams: Record<string, string> = {}) {
+  const paramMap = { get: (key: string) => queryParams[key] ?? null };
   return {
-    snapshot: {
-      queryParamMap: {
-        get: (key: string) => queryParams[key] ?? null,
-      },
-    },
+    snapshot: { queryParamMap: paramMap },
+    queryParamMap: of(paramMap),
   };
 }
 
-const EMPTY_PAGE = { items: [], total: 0, limit: 50, offset: 0 };
+const EMPTY_PAGE = { items: [], total: 0, limit: 24, offset: 0 };
 const ONE_IMAGE = {
-  items: [{ id: '1', filename: 'a.jpg', tags: ['cat'], hash: '', mime_type: 'image/jpeg', size_bytes: 1, width: 1, height: 1, storage_key: '', thumbnail_key: null, created_at: '' }],
-  total: 1, limit: 50, offset: 0,
+  items: [{ id: '1', filename: 'a.jpg', tags: ['cat'], hash: '', mime_type: 'image/jpeg', size_bytes: 1, width: 1, height: 1, storage_key: '', thumbnail_key: null, file_url: '/api/v1/images/1/file', thumbnail_url: null, created_at: '' }],
+  total: 1, limit: 24, offset: 0,
+};
+const MULTI_PAGE = {
+  items: Array(24).fill(null).map((_, i) => ({
+    id: String(i + 1), filename: `img${i + 1}.jpg`, tags: [], hash: '',
+    mime_type: 'image/jpeg', size_bytes: 1, width: 1, height: 1,
+    storage_key: '', thumbnail_key: null,
+    file_url: `/api/v1/images/${i + 1}/file`, thumbnail_url: null, created_at: '',
+  })),
+  total: 48, limit: 24, offset: 0,
 };
 
 describe('LibraryComponent', () => {
@@ -74,14 +81,16 @@ describe('LibraryComponent', () => {
 
   it('shows error card when error is true', () => {
     const fixture = TestBed.createComponent(LibraryComponent);
-    fixture.componentInstance.error = true;
+    const imgSvc = TestBed.inject(ImageService);
+    spyOn(imgSvc, 'list').and.returnValue(throwError(() => new Error('fail')));
     fixture.detectChanges();
     expect((fixture.nativeElement as HTMLElement).querySelector('.error-card')).not.toBeNull();
   });
 
   it('error card has retry button that calls load()', () => {
     const fixture = TestBed.createComponent(LibraryComponent);
-    fixture.componentInstance.error = true;
+    const imgSvc = TestBed.inject(ImageService);
+    spyOn(imgSvc, 'list').and.returnValue(throwError(() => new Error('fail')));
     fixture.detectChanges();
     spyOn(fixture.componentInstance, 'load');
     const retryBtn = (fixture.nativeElement as HTMLElement).querySelector('.error-card .retry-btn') as HTMLButtonElement;
@@ -145,4 +154,142 @@ describe('LibraryComponent', () => {
     const link = (fixture.nativeElement as HTMLElement).querySelector('a[href="/tags"]');
     expect(link).not.toBeNull();
   });
+
+  // ---- Pagination: US1 ----
+
+  it('page indicator shows "Page 1 of 2" when totalPages > 1', () => {
+    const fixture = TestBed.createComponent(LibraryComponent);
+    const imgSvc = TestBed.inject(ImageService);
+    spyOn(imgSvc, 'list').and.returnValue(of(MULTI_PAGE));
+    fixture.detectChanges();
+    const indicator = (fixture.nativeElement as HTMLElement).querySelector('.page-indicator');
+    expect(indicator?.textContent).toContain('Page 1 of 2');
+  });
+
+  it('total count renders with correct number', () => {
+    const fixture = TestBed.createComponent(LibraryComponent);
+    const imgSvc = TestBed.inject(ImageService);
+    spyOn(imgSvc, 'list').and.returnValue(of(MULTI_PAGE));
+    fixture.detectChanges();
+    const el = (fixture.nativeElement as HTMLElement).querySelector('.total-count');
+    expect(el?.textContent).toContain('48');
+  });
+
+  it('"Next" button present when not on last page', () => {
+    const fixture = TestBed.createComponent(LibraryComponent);
+    const imgSvc = TestBed.inject(ImageService);
+    spyOn(imgSvc, 'list').and.returnValue(of(MULTI_PAGE));
+    fixture.detectChanges();
+    expect((fixture.nativeElement as HTMLElement).querySelector('.next-btn')).not.toBeNull();
+  });
+
+  it('"Previous" button absent on first page', () => {
+    const fixture = TestBed.createComponent(LibraryComponent);
+    const imgSvc = TestBed.inject(ImageService);
+    spyOn(imgSvc, 'list').and.returnValue(of(MULTI_PAGE));
+    fixture.detectChanges();
+    expect((fixture.nativeElement as HTMLElement).querySelector('.prev-btn')).toBeNull();
+  });
+
+  it('"Previous" present and "Next" absent on last page', () => {
+    TestBed.overrideProvider(ActivatedRoute, { useValue: makeActivatedRoute({ page: '2' }) });
+    const fixture = TestBed.createComponent(LibraryComponent);
+    const imgSvc = TestBed.inject(ImageService);
+    spyOn(imgSvc, 'list').and.returnValue(of(MULTI_PAGE));
+    fixture.detectChanges();
+    expect((fixture.nativeElement as HTMLElement).querySelector('.prev-btn')).not.toBeNull();
+    expect((fixture.nativeElement as HTMLElement).querySelector('.next-btn')).toBeNull();
+  });
+
+  it('no pagination controls when all images fit on one page', () => {
+    const fixture = TestBed.createComponent(LibraryComponent);
+    const imgSvc = TestBed.inject(ImageService);
+    spyOn(imgSvc, 'list').and.returnValue(of(ONE_IMAGE));
+    fixture.detectChanges();
+    expect((fixture.nativeElement as HTMLElement).querySelector('.pagination-bar')).toBeNull();
+  });
+
+  it('nextPage() calls imageService.list with offset=24', () => {
+    const fixture = TestBed.createComponent(LibraryComponent);
+    const imgSvc = TestBed.inject(ImageService);
+    const listSpy = spyOn(imgSvc, 'list').and.returnValue(of(MULTI_PAGE));
+    fixture.detectChanges();
+    listSpy.calls.reset();
+    fixture.componentInstance.nextPage();
+    expect(listSpy).toHaveBeenCalledWith(jasmine.any(Array), jasmine.any(Number), 24);
+  });
+
+  it('prevPage() from page 2 calls imageService.list with offset=0', () => {
+    const fixture = TestBed.createComponent(LibraryComponent);
+    const imgSvc = TestBed.inject(ImageService);
+    const listSpy = spyOn(imgSvc, 'list').and.returnValue(of(MULTI_PAGE));
+    fixture.detectChanges();
+    fixture.componentInstance.currentPage = 2;
+    fixture.componentInstance.totalPages = 2;
+    listSpy.calls.reset();
+    fixture.componentInstance.prevPage();
+    expect(listSpy).toHaveBeenCalledWith(jasmine.any(Array), jasmine.any(Number), 0);
+  });
+
+  it('applyFilter() resets to page 1 (offset=0)', () => {
+    const fixture = TestBed.createComponent(LibraryComponent);
+    const imgSvc = TestBed.inject(ImageService);
+    const listSpy = spyOn(imgSvc, 'list').and.returnValue(of(MULTI_PAGE));
+    fixture.detectChanges();
+    fixture.componentInstance.currentPage = 2;
+    listSpy.calls.reset();
+    fixture.componentInstance.applyFilter(['cat']);
+    expect(listSpy).toHaveBeenCalledWith(['cat'], jasmine.any(Number), 0);
+  });
+
+  // ---- Pagination: US2 — URL state ----
+
+  it('reads ?page=2 from queryParamMap on init and calls list with offset=24', () => {
+    TestBed.overrideProvider(ActivatedRoute, { useValue: makeActivatedRoute({ page: '2' }) });
+    const fixture = TestBed.createComponent(LibraryComponent);
+    const imgSvc = TestBed.inject(ImageService);
+    const listSpy = spyOn(imgSvc, 'list').and.returnValue(of(MULTI_PAGE));
+    fixture.detectChanges();
+    expect(fixture.componentInstance.currentPage).toBe(2);
+    expect(listSpy).toHaveBeenCalledWith(jasmine.any(Array), jasmine.any(Number), 24);
+  });
+
+  it('clamps out-of-range ?page=9999 to page 1 after load resolves', () => {
+    TestBed.overrideProvider(ActivatedRoute, { useValue: makeActivatedRoute({ page: '9999' }) });
+    const fixture = TestBed.createComponent(LibraryComponent);
+    const imgSvc = TestBed.inject(ImageService);
+    spyOn(imgSvc, 'list').and.returnValue(of(MULTI_PAGE));
+    fixture.detectChanges();
+    // After load, totalPages=2, currentPage should be clamped to 2 (not 9999), then router corrects URL
+    expect(fixture.componentInstance.currentPage).toBeLessThanOrEqual(fixture.componentInstance.totalPages);
+  });
+
+  it('nextPage() calls router.navigate with page=2 and queryParamsHandling merge', () => {
+    const fixture = TestBed.createComponent(LibraryComponent);
+    const imgSvc = TestBed.inject(ImageService);
+    spyOn(imgSvc, 'list').and.returnValue(of(MULTI_PAGE));
+    fixture.detectChanges();
+    const router = TestBed.inject(Router);
+    spyOn(router, 'navigate');
+    fixture.componentInstance.nextPage();
+    expect(router.navigate).toHaveBeenCalledWith([], jasmine.objectContaining({
+      queryParams: jasmine.objectContaining({ page: 2 }),
+      queryParamsHandling: 'merge',
+    }));
+  });
+
+  it('applyFilter() calls router.navigate with page=1 and queryParamsHandling merge', () => {
+    const fixture = TestBed.createComponent(LibraryComponent);
+    const imgSvc = TestBed.inject(ImageService);
+    spyOn(imgSvc, 'list').and.returnValue(of(MULTI_PAGE));
+    fixture.detectChanges();
+    fixture.componentInstance.currentPage = 2;
+    const router = TestBed.inject(Router);
+    spyOn(router, 'navigate');
+    fixture.componentInstance.applyFilter(['dog']);
+    expect(router.navigate).toHaveBeenCalledWith([], jasmine.objectContaining({
+      queryParams: jasmine.objectContaining({ page: 1 }),
+      queryParamsHandling: 'merge',
+    }));
+  });
 });

ui/src/app/library/library.component.ts

@@ -6,7 +6,7 @@ import {
 } from '@angular/core';
 import { CommonModule } from '@angular/common';
 import { Router, RouterLink, ActivatedRoute } from '@angular/router';
-import { Subject, debounceTime, distinctUntilChanged, share, timer } from 'rxjs';
+import { Subject, debounceTime, distinctUntilChanged, share, skip, timer } from 'rxjs';
 import { takeUntil } from 'rxjs/operators';
 import { ImageRecord, ImageService } from '../services/image.service';
 import { TagService } from '../services/tag.service';
@@ -21,7 +21,7 @@ const PLACEHOLDER_SVG = `data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/s
   template: `
     <div class="library">
       <header>
-        <h1>Reactbin</h1>
+        <h1><a class="home-link" routerLink="/" [queryParams]="{}">Reactbin</a></h1>
         <div class="header-actions">
           <a routerLink="/tags" class="tags-link">Browse tags</a>
           <button class="upload-btn" (click)="router.navigate(['/upload'])">Upload</button>
@@ -74,7 +74,7 @@ const PLACEHOLDER_SVG = `data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/s
           (keydown.enter)="router.navigate(['/images', img.id])"
         >
           <img
-            [src]="imageService.getThumbnailUrl(img.id)"
+            [src]="img.thumbnail_url ?? img.file_url"
             [alt]="img.filename"
             loading="lazy"
             (error)="onImgError($event)"
@@ -85,7 +85,15 @@ const PLACEHOLDER_SVG = `data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/s
         </div>
       </div>
 
-      <button *ngIf="hasMore && !showSpinner && !error" class="load-more" (click)="loadMore()">Load more</button>
+      <!-- Total count — always visible when images exist -->
+      <p *ngIf="total > 0 && !showSpinner && !error" class="total-count">{{ total }} images</p>
+
+      <!-- Pagination controls — only when more than one page -->
+      <div *ngIf="totalPages > 1 && !showSpinner && !error" class="pagination-bar">
+        <button *ngIf="currentPage > 1" class="prev-btn" (click)="prevPage()">← Previous</button>
+        <span class="page-indicator">Page {{ currentPage }} of {{ totalPages }}</span>
+        <button *ngIf="currentPage < totalPages" class="next-btn" (click)="nextPage()">Next →</button>
+      </div>
     </div>
   `,
   styles: [`
@@ -110,7 +118,9 @@ const PLACEHOLDER_SVG = `data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/s
     .image-card:hover { transform: translateY(-2px); box-shadow: 0 4px 16px rgba(0,0,0,0.4); }
     .image-card img { width: 100%; height: 160px; object-fit: cover; display: block; }
     .card-skeleton { height: 200px; }
-    .tag-row { padding: 6px; display: flex; flex-wrap: wrap; gap: 4px; }
+    .tag-row { padding: 6px; display: flex; flex-wrap: nowrap; gap: 4px; overflow: hidden; position: relative; }
+    .tag-row::after { content: ''; position: absolute; right: 0; top: 0; bottom: 0; width: 2rem; background: linear-gradient(to right, transparent, var(--surface)); pointer-events: none; }
+    .home-link { color: inherit; text-decoration: none; cursor: pointer; }
     .empty-state { text-align: center; padding: 60px 0; color: var(--text-muted); }
     .empty-icon { display: block; font-size: 2rem; margin-bottom: 12px; }
     .upload-link { display: inline-block; margin-top: 16px; color: var(--accent); text-decoration: none; font-weight: 600; }
@@ -119,7 +129,11 @@ const PLACEHOLDER_SVG = `data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/s
     .error-card p { color: var(--text-muted); margin-bottom: 16px; }
     .retry-btn { padding: 8px 24px; background: var(--surface-raised); color: var(--text); border: 1px solid var(--border); border-radius: var(--radius); cursor: pointer; transition: border-color var(--transition); }
     .retry-btn:hover { border-color: var(--border-focus); }
-    .load-more { display: block; margin: 24px auto; padding: 10px 32px; background: var(--surface-raised); color: var(--text); border: 1px solid var(--border); border-radius: var(--radius); cursor: pointer; }
+    .total-count { text-align: center; color: var(--text-muted); font-size: 0.85rem; margin: 16px 0 8px; }
+    .pagination-bar { display: flex; justify-content: center; align-items: center; gap: 16px; margin: 16px 0 24px; }
+    .prev-btn, .next-btn { padding: 8px 20px; background: var(--surface-raised); color: var(--text); border: 1px solid var(--border); border-radius: var(--radius); cursor: pointer; transition: border-color var(--transition); }
+    .prev-btn:hover, .next-btn:hover { border-color: var(--border-focus); }
+    .page-indicator { color: var(--text-muted); font-size: 0.9rem; }
   `],
 })
 export class LibraryComponent implements OnInit {
@@ -129,10 +143,11 @@ export class LibraryComponent implements OnInit {
   suggestions: { name: string; image_count: number }[] = [];
   showSpinner = false;
   error = false;
-  hasMore = false;
+  currentPage = 1;
+  totalPages = 1;
+  total = 0;
   readonly skeletonItems = Array(8).fill(null);
-  private offset = 0;
-  private readonly limit = 50;
+  private readonly limit = 24;
   private readonly filterChange$ = new Subject<string>();
 
   constructor(
@@ -148,7 +163,26 @@ export class LibraryComponent implements OnInit {
     if (tagsParam) {
       this.activeFilters = tagsParam.split(',').map((t) => t.trim()).filter((t) => t.length > 0);
     }
+    const pageParam = this.route.snapshot.queryParamMap.get('page');
+    if (pageParam) {
+      this.currentPage = Math.max(1, parseInt(pageParam, 10) || 1);
+    }
     this.load();
+    this.route.queryParamMap.pipe(skip(1)).subscribe((params) => {
+      const newPage = params.get('page') ? Math.max(1, parseInt(params.get('page')!, 10) || 1) : 1;
+      const newTagsParam = params.get('tags');
+      const newTags = newTagsParam
+        ? newTagsParam.split(',').map((t) => t.trim()).filter((t) => t.length > 0)
+        : [];
+      const pageChanged = newPage !== this.currentPage;
+      const tagsChanged = JSON.stringify(newTags) !== JSON.stringify(this.activeFilters);
+      if (pageChanged || tagsChanged) {
+        this.currentPage = newPage;
+        this.activeFilters = newTags;
+        this.images = [];
+        this.load();
+      }
+    });
     this.filterChange$.pipe(debounceTime(300), distinctUntilChanged()).subscribe((q) => {
       if (q) {
         this.tagService.list(q, 10).subscribe((r) => {
@@ -164,16 +198,22 @@ export class LibraryComponent implements OnInit {
 
   load(): void {
     this.error = false;
-    const req$ = this.imageService.list(this.activeFilters, this.limit, this.offset).pipe(share());
+    const offset = (this.currentPage - 1) * this.limit;
+    const req$ = this.imageService.list(this.activeFilters, this.limit, offset).pipe(share());
     timer(150).pipe(takeUntil(req$)).subscribe(() => {
       this.showSpinner = true;
       this.cdr.markForCheck();
     });
     req$.subscribe({
       next: (res) => {
-        this.images = [...this.images, ...res.items];
-        this.offset += res.items.length;
-        this.hasMore = this.offset < res.total;
+        this.images = res.items;
+        this.total = res.total;
+        this.totalPages = Math.ceil(res.total / this.limit) || 1;
+        const clamped = Math.max(1, Math.min(this.currentPage, this.totalPages));
+        if (clamped !== this.currentPage) {
+          this.currentPage = clamped;
+          this.router.navigate([], { queryParams: { page: this.currentPage }, queryParamsHandling: 'merge' });
+        }
         this.showSpinner = false;
         this.cdr.markForCheck();
       },
@@ -185,6 +225,22 @@ export class LibraryComponent implements OnInit {
     });
   }
 
+  nextPage(): void {
+    if (this.currentPage < this.totalPages) {
+      this.currentPage++;
+      this.router.navigate([], { queryParams: { page: this.currentPage }, queryParamsHandling: 'merge' });
+      this.load();
+    }
+  }
+
+  prevPage(): void {
+    if (this.currentPage > 1) {
+      this.currentPage--;
+      this.router.navigate([], { queryParams: { page: this.currentPage }, queryParamsHandling: 'merge' });
+      this.load();
+    }
+  }
+
   onTagInput(event: Event): void {
     const val = (event.target as HTMLInputElement).value;
     this.tagSearch = val;
@@ -207,12 +263,12 @@ export class LibraryComponent implements OnInit {
 
   applyFilter(tags: string[]): void {
     this.activeFilters = tags;
-    this.offset = 0;
+    this.currentPage = 1;
     this.images = [];
-    this.load();
-  }
-
-  loadMore(): void {
+    this.router.navigate([], {
+      queryParams: { page: 1, tags: tags.length ? tags.join(',') : null },
+      queryParamsHandling: 'merge',
+    });
     this.load();
   }
 

ui/src/app/services/image.service.ts

@@ -12,6 +12,8 @@ export interface ImageRecord {
   height: number;
   storage_key: string;
   thumbnail_key: string | null;
+  file_url: string;
+  thumbnail_url: string | null;
   created_at: string;
   tags: string[];
   duplicate?: boolean;
@@ -51,14 +53,6 @@ export class ImageService {
     return this.http.get<ImageRecord>(`${this.base}/images/${id}`);
   }
 
-  getFileUrl(id: string): string {
-    return `${this.base}/images/${id}/file`;
-  }
-
-  getThumbnailUrl(id: string): string {
-    return `${this.base}/images/${id}/thumbnail`;
-  }
-
   updateTags(id: string, tags: string[]): Observable<ImageRecord> {
     return this.http.patch<ImageRecord>(`${this.base}/images/${id}/tags`, { tags });
   }

ui/src/app/services/toast.service.spec.ts

@@ -0,0 +1,51 @@
+import { TestBed, fakeAsync, tick } from '@angular/core/testing';
+import { Toast, ToastService } from './toast.service';
+
+describe('ToastService', () => {
+  let service: ToastService;
+
+  beforeEach(() => {
+    TestBed.configureTestingModule({});
+    service = TestBed.inject(ToastService);
+  });
+
+  it('show() emits a toast with correct message and type', (done) => {
+    service.current$.subscribe((toast) => {
+      if (toast) {
+        expect(toast.message).toBe('Hello!');
+        expect(toast.type).toBe('error');
+        done();
+      }
+    });
+    service.show('Hello!', 'error');
+  });
+
+  it('type defaults to success when not provided', (done) => {
+    service.current$.subscribe((toast) => {
+      if (toast) {
+        expect(toast.type).toBe('success');
+        done();
+      }
+    });
+    service.show('Default type');
+  });
+
+  it('current$ emits null after the duration elapses', fakeAsync(() => {
+    const emitted: (string | null)[] = [];
+    service.current$.subscribe((t: Toast | null) => emitted.push(t ? t.message : null));
+    service.show('Auto-dismiss', 'success', 500);
+    tick(500);
+    expect(emitted).toContain(null);
+  }));
+
+  it('calling show() again before timer fires replaces the active toast', fakeAsync(() => {
+    const messages: (string | null)[] = [];
+    service.current$.subscribe((t: Toast | null) => messages.push(t ? t.message : null));
+    service.show('First', 'success', 1000);
+    tick(200);
+    service.show('Second', 'success', 1000);
+    tick(0);
+    const nonNull = messages.filter((m) => m !== null);
+    expect(nonNull[nonNull.length - 1]).toBe('Second');
+  }));
+});

ui/src/app/services/toast.service.ts

@@ -0,0 +1,25 @@
+import { Injectable } from '@angular/core';
+import { BehaviorSubject, Observable } from 'rxjs';
+
+export interface Toast {
+  message: string;
+  type: 'success' | 'error';
+}
+
+@Injectable({ providedIn: 'root' })
+export class ToastService {
+  private readonly subject = new BehaviorSubject<Toast | null>(null);
+  readonly current$: Observable<Toast | null> = this.subject.asObservable();
+  private timer: ReturnType<typeof setTimeout> | null = null;
+
+  show(message: string, type: 'success' | 'error' = 'success', duration = 3000): void {
+    if (this.timer !== null) {
+      clearTimeout(this.timer);
+    }
+    this.subject.next({ message, type });
+    this.timer = setTimeout(() => {
+      this.subject.next(null);
+      this.timer = null;
+    }, duration);
+  }
+}

ui/src/app/toast/toast.component.spec.ts

@@ -0,0 +1,49 @@
+import { TestBed } from '@angular/core/testing';
+import { of } from 'rxjs';
+import { ToastComponent } from './toast.component';
+import { ToastService } from '../services/toast.service';
+
+describe('ToastComponent', () => {
+  let toastSvc: jasmine.SpyObj<ToastService>;
+
+  beforeEach(async () => {
+    toastSvc = jasmine.createSpyObj('ToastService', [], { current$: of(null) });
+
+    await TestBed.configureTestingModule({
+      imports: [ToastComponent],
+      providers: [{ provide: ToastService, useValue: toastSvc }],
+    }).compileComponents();
+  });
+
+  it('renders a .toast element with the correct message when current$ emits a toast', async () => {
+    Object.defineProperty(toastSvc, 'current$', { value: of({ message: 'Done', type: 'success' as const }) });
+    const fixture = TestBed.createComponent(ToastComponent);
+    fixture.detectChanges();
+    const el = (fixture.nativeElement as HTMLElement).querySelector('.toast');
+    expect(el).not.toBeNull();
+    expect(el?.textContent?.trim()).toBe('Done');
+  });
+
+  it('adds the success CSS class when type is success', async () => {
+    Object.defineProperty(toastSvc, 'current$', { value: of({ message: 'OK', type: 'success' as const }) });
+    const fixture = TestBed.createComponent(ToastComponent);
+    fixture.detectChanges();
+    const el = (fixture.nativeElement as HTMLElement).querySelector('.toast');
+    expect(el?.classList.contains('success')).toBeTrue();
+  });
+
+  it('adds the error CSS class when type is error', async () => {
+    Object.defineProperty(toastSvc, 'current$', { value: of({ message: 'Fail', type: 'error' as const }) });
+    const fixture = TestBed.createComponent(ToastComponent);
+    fixture.detectChanges();
+    const el = (fixture.nativeElement as HTMLElement).querySelector('.toast');
+    expect(el?.classList.contains('error')).toBeTrue();
+  });
+
+  it('renders nothing when current$ emits null', () => {
+    const fixture = TestBed.createComponent(ToastComponent);
+    fixture.detectChanges();
+    const el = (fixture.nativeElement as HTMLElement).querySelector('.toast');
+    expect(el).toBeNull();
+  });
+});

ui/src/app/toast/toast.component.ts

@@ -0,0 +1,44 @@
+import { Component, ChangeDetectionStrategy } from '@angular/core';
+import { CommonModule } from '@angular/common';
+import { ToastService } from '../services/toast.service';
+
+@Component({
+  selector: 'app-toast',
+  standalone: true,
+  imports: [CommonModule],
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  template: `
+    <div
+      *ngIf="toastService.current$ | async as toast"
+      class="toast"
+      [class.success]="toast.type === 'success'"
+      [class.error]="toast.type === 'error'"
+    >{{ toast.message }}</div>
+  `,
+  styles: [`
+    .toast {
+      position: fixed;
+      bottom: 24px;
+      left: 50%;
+      transform: translateX(-50%);
+      padding: 10px 20px;
+      border-radius: var(--radius);
+      font-size: 0.9rem;
+      pointer-events: none;
+      z-index: 1000;
+      white-space: nowrap;
+    }
+    .success {
+      background: var(--surface-raised);
+      color: var(--text);
+      border: 1px solid var(--border);
+    }
+    .error {
+      background: var(--danger);
+      color: var(--danger-text);
+    }
+  `],
+})
+export class ToastComponent {
+  constructor(public toastService: ToastService) {}
+}

ui/src/index.html

@@ -5,6 +5,22 @@
   <title>Reactbin</title>
   <base href="/">
   <meta name="viewport" content="width=device-width, initial-scale=1">
+  <!-- Open Graph -->
+  <meta property="og:type" content="website">
+  <meta property="og:title" content="Reactbin">
+  <meta property="og:description" content="Find your perfect reaction image.">
+  <meta property="og:url" content="https://reactbin.juggalol.com">
+  <meta property="og:image" content="https://cdn.reactbin.juggalol.com/0bdaf046f534a1c913629d7ce8069ce407898c19794527bf842524ff4c0073de">
+  <!-- Twitter Card -->
+  <meta name="twitter:card" content="summary_large_image">
+  <meta name="twitter:title" content="Reactbin">
+  <meta name="twitter:description" content="Find your perfect reaction image.">
+  <meta name="twitter:image" content="https://cdn.reactbin.juggalol.com/0bdaf046f534a1c913629d7ce8069ce407898c19794527bf842524ff4c0073de">
+  <link rel="apple-touch-icon" sizes="180x180" href="apple-touch-icon.png">
+  <link rel="icon" type="image/png" sizes="32x32" href="favicon-32x32.png">
+  <link rel="icon" type="image/png" sizes="16x16" href="favicon-16x16.png">
+  <link rel="manifest" href="site.webmanifest">
+  <link rel="icon" href="favicon.ico">
 </head>
 <body>
   <app-root></app-root>