From a969b1396d8f67affe1240f5799b5b8928a59a69 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 12 Oct 2026 02:34:54 +0000
Subject: [PATCH] feat(storage): show disk usage and free space, warn before it
 runs out

Settings gains a Storage panel, and the header a drive icon that appears only
when free space is low.

Everyone sees their own library: totals by type, previews, and their ten
largest files as links, which is the quickest way to find something to delete.
Admins (ADMIN_USERS) also see the server:
- one bar per disk, split into GAM media, GAM database, everything else, the
  filesystem's reserve and free space; inside Docker these are the host's
  numbers, through the data/ bind mount
- stray files: files under data/media that no asset refers to, older than a
  day, with a button that removes them through storage.delete

Below DISK_RESERVE_GB (default 5) uploads, URL imports, generations and
sub-video extractions are refused with 507 disk_full. They are checked when
queued and again when the job starts. A generation is checked before it is
sent to fal, so nothing is billed for an output that cannot be saved, and a
request already submitted still saves. An upload stores the files that fit
and rejects the rest. DISK_WARN_FREE_GB (default 20) sets the header warning.
Both are fixed sizes because single large files are what fill the disk.

The container's temp directory is shown when it is a separate disk, but does
not count toward the level: nothing persistent lives there, and on a dev
machine it is often a small tmpfs that would otherwise block every upload.

Tests run against a fake disk (conftest's autouse `disk`), so the suite no
longer depends on how full the machine running it is.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017Ev6jNsXYxKEPPN6EpqpTE
---
 .env.example                                  |  12 +-
 README.md                                     |   3 +
 backend/app/config.py                         |  14 +
 backend/app/enrichment/extract_subvideo.py    |   6 +-
 backend/app/enrichment/import_url.py          |   7 +-
 backend/app/generation/run.py                 |   7 +-
 backend/app/main.py                           |   2 +
 backend/app/routers/assets.py                 |  19 +-
 backend/app/routers/clips.py                  |   4 +-
 backend/app/routers/generate.py               |   4 +-
 backend/app/routers/imports.py                |   2 +
 backend/app/routers/storage.py                |  70 +++
 backend/app/schemas_storage.py                |  81 +++
 backend/app/services/storage_usage.py         | 218 +++++++++
 backend/app/storage/capacity.py               | 170 +++++++
 backend/app/storage/local.py                  |  30 ++
 backend/tests/conftest.py                     |  39 ++
 backend/tests/test_clips_api.py               |  16 +
 backend/tests/test_generation_job.py          |  34 ++
 backend/tests/test_storage.py                 |  27 +
 backend/tests/test_storage_usage.py           | 463 ++++++++++++++++++
 backend/tests/test_url_import.py              |  15 +
 docker-compose.yml                            |   2 +
 docs/deployment.md                            |  42 ++
 frontend/src/api/storage.ts                   | 106 ++++
 frontend/src/components/AppShell.test.tsx     |   7 +
 frontend/src/components/AppShell.tsx          |   2 +
 frontend/src/components/StoragePanel.test.tsx | 248 ++++++++++
 frontend/src/components/StoragePanel.tsx      | 451 +++++++++++++++++
 .../src/components/StorageWarning.test.tsx    |  54 ++
 frontend/src/components/StorageWarning.tsx    |  67 +++
 frontend/src/views/SettingsView.test.tsx      |  13 +
 frontend/src/views/SettingsView.tsx           |   2 +
 33 files changed, 2230 insertions(+), 7 deletions(-)
 create mode 100644 backend/app/routers/storage.py
 create mode 100644 backend/app/schemas_storage.py
 create mode 100644 backend/app/services/storage_usage.py
 create mode 100644 backend/app/storage/capacity.py
 create mode 100644 backend/tests/test_storage_usage.py
 create mode 100644 frontend/src/api/storage.ts
 create mode 100644 frontend/src/components/StoragePanel.test.tsx
 create mode 100644 frontend/src/components/StoragePanel.tsx
 create mode 100644 frontend/src/components/StorageWarning.test.tsx
 create mode 100644 frontend/src/components/StorageWarning.tsx

diff --git a/.env.example b/.env.example
index 2579a4f..173a077 100644
--- a/.env.example
+++ b/.env.example
@@ -53,6 +53,15 @@ UPLOAD_MAX_SIZE=4g
 # large video; short enough that a leaked URL stops working. Default 1 hour.
 MEDIA_URL_TTL_SECONDS=3600
 
+# ─── Disk space ──────────────────────────────────────────────────────────────
+#
+# Free space, in GB, on the disk holding media (and, if separate, the database and the
+# container's temp space, where uploads and imports land first). Below the first, the
+# header shows a warning; below the second, uploads, imports, generations and clip
+# extractions are refused until space is freed. Settings → Storage shows the numbers.
+DISK_WARN_FREE_GB=20
+DISK_RESERVE_GB=5
+
 # ─── Background jobs ─────────────────────────────────────────────────────────
 
 JOB_HEARTBEAT_SECONDS=30
@@ -85,7 +94,8 @@ URL_IMPORT_COOKIES_FILE=
 
 # ─── Administrators ──────────────────────────────────────────────────────────
 
-# Who may edit the AI generation model catalogue: Gecko Notes user ids or usernames,
+# Who may edit the AI generation model catalogue, and see the server's disk space and
+# clear stray files under Settings → Storage: Gecko Notes user ids or usernames,
 # comma-separated, matched exactly (case included). Prefer ids: Notes lets anyone rename
 # themselves, so a username somebody gives up can be taken by somebody else. Notes'
 # token carries no admin flag, so this is the only way anyone becomes an admin here.
diff --git a/README.md b/README.md
index cf58cf2..ac27e63 100644
--- a/README.md
+++ b/README.md
@@ -53,6 +53,9 @@ user row. The changes that makes possible are specified in
   images, with the prompt and base assets recorded so a result stays reproducible.
 - **Cost visibility** — an estimate before anything paid runs, and the real cost tracked
   per asset and per library afterwards.
+- **Disk space** — what the library takes up and what the disk has left, a header
+  warning before it runs out, and new writes refused before a full disk can damage
+  anything. See [`docs/deployment.md`](docs/deployment.md#disk-space).
 
 ## Tech stack
 
diff --git a/backend/app/config.py b/backend/app/config.py
index 0821f9e..d374653 100644
--- a/backend/app/config.py
+++ b/backend/app/config.py
@@ -60,6 +60,20 @@ class Settings(BaseSettings):
     # video, short enough that a leaked URL stops working.
     media_url_ttl_seconds: int = 3600
 
+    # ─── disk space ──────────────────────────────────────────────────────────
+    # Absolute sizes, not percentages of the disk. What fills it is single files whose
+    # size has nothing to do with the disk's: a ninety-minute 1080p import is 1-2 GB on
+    # a 100 GB VPS or a 10 TB array alike, and one generation may download up to
+    # `generation_max_download_mb`. Ten percent of an 8 TB disk would cry wolf at
+    # 800 GB free.
+    #
+    # Below `disk_warn_free_gb` the header shows a warning. Below `disk_reserve_gb`
+    # uploads, imports, generations and extractions are refused, which keeps enough
+    # room for the writes already in flight and for SQLite, which does not recover
+    # gracefully from a disk that fills under it.
+    disk_warn_free_gb: float = 20
+    disk_reserve_gb: float = 5
+
     # ─── http ────────────────────────────────────────────────────────────────
     cors_origin: str = ""
 
diff --git a/backend/app/enrichment/extract_subvideo.py b/backend/app/enrichment/extract_subvideo.py
index 4a715de..9ab3068 100644
--- a/backend/app/enrichment/extract_subvideo.py
+++ b/backend/app/enrichment/extract_subvideo.py
@@ -29,7 +29,7 @@
 from app.ingest.probe import probe
 from app.models.asset import Asset
 from app.services import assets as asset_service
-from app.storage import build_storage, new_key, thumb_key_for
+from app.storage import build_storage, capacity, new_key, thumb_key_for
 
 logger = logging.getLogger(__name__)
 
@@ -72,6 +72,10 @@ def run(
         except (KeyError, TypeError, ValueError) as exc:
             raise SubvideoExtractionError("Missing or invalid in/out points") from exc
 
+    # Again, although the router already did: the job may have waited in the queue.
+    if not capacity.has_room():
+        raise SubvideoExtractionError(capacity.DISK_FULL_MESSAGE)
+
     storage = build_storage()
     progress("Extracting", 10, "")
 
diff --git a/backend/app/enrichment/import_url.py b/backend/app/enrichment/import_url.py
index 525f965..9449510 100644
--- a/backend/app/enrichment/import_url.py
+++ b/backend/app/enrichment/import_url.py
@@ -45,7 +45,7 @@
 from app.services import suggestions as suggestion_service
 from app.services import tags as tag_service
 from app.settings_store import load_deepgram_key
-from app.storage import StorageError, build_storage, thumb_key_for
+from app.storage import StorageError, build_storage, capacity, thumb_key_for
 
 logger = logging.getLogger(__name__)
 
@@ -112,6 +112,11 @@ def run(session: Session, job: EnrichmentJob, progress: Progress) -> ImportResul
     except HTTPException as exc:
         raise UrlImportError(readable_error(exc)) from exc
 
+    # Again, although the router already did: a job can sit queued behind others while
+    # the disk fills, and every playlist child arrives here without passing the router.
+    if not capacity.has_room():
+        raise UrlImportError(capacity.DISK_FULL_MESSAGE)
+
     with tempfile.TemporaryDirectory(prefix="gam-import-") as workdir:
         work = Path(workdir)
 
diff --git a/backend/app/generation/run.py b/backend/app/generation/run.py
index 80ad9b2..d44a1f8 100644
--- a/backend/app/generation/run.py
+++ b/backend/app/generation/run.py
@@ -55,7 +55,7 @@
 from app.providers.base import ProviderError
 from app.services import assets as asset_service
 from app.settings_store import load_fal_key
-from app.storage import StorageError, build_storage
+from app.storage import StorageError, build_storage, capacity
 from app.usage import events as usage_events
 
 logger = logging.getLogger(__name__)
@@ -166,6 +166,11 @@ def run(session: Session, job: EnrichmentJob, progress: Progress) -> GenerationR
 
     if state.result is None:
         if state.queued is None:
+            # Before submitting, and only then. fal bills when it runs the request, so this
+            # is the last moment refusing costs nothing; a request already submitted has
+            # been paid for, and is let try to save its output rather than thrown away.
+            if not capacity.has_room():
+                raise GenerationError(capacity.DISK_FULL_MESSAGE)
             body = _request_body(session, job, request, progress)
             progress(STAGE_SUBMITTING, 10, "")
             state.queued = fal.submit(request.endpoint_id, body, api_key=api_key)
diff --git a/backend/app/main.py b/backend/app/main.py
index ff6e948..5ce0071 100644
--- a/backend/app/main.py
+++ b/backend/app/main.py
@@ -34,6 +34,7 @@
 from app.routers import providers as providers_router
 from app.routers import search as search_router
 from app.routers import settings as settings_router
+from app.routers import storage as storage_router
 from app.routers import tags as tags_router
 from app.routers import usage as usage_router
 from app.routers import transcripts as transcripts_router
@@ -186,6 +187,7 @@ def me(
 app.include_router(providers_router.router, prefix="/api/providers", tags=["providers"])
 app.include_router(tags_router.router, prefix="/api/tags", tags=["tags"])
 app.include_router(usage_router.router, prefix="/api/usage", tags=["usage"])
+app.include_router(storage_router.router, prefix="/api/storage", tags=["storage"])
 # Not under /api: these URLs go straight into <img src> and <video src>, and the
 # signature in the query string is what authorises them.
 app.include_router(media_router.router, prefix="/media", tags=["media"])
diff --git a/backend/app/routers/assets.py b/backend/app/routers/assets.py
index 35865f1..71ff2c7 100644
--- a/backend/app/routers/assets.py
+++ b/backend/app/routers/assets.py
@@ -23,7 +23,7 @@
 from app.schemas_tags import AssetTagsWrite, BulkTagsResult, BulkTagsWrite, TagRead
 from app.services import assets as service
 from app.services import tags as tag_service
-from app.storage import LocalStorage, build_storage
+from app.storage import LocalStorage, build_storage, capacity
 
 router = APIRouter()
 
@@ -80,6 +80,19 @@ async def upload_assets(
     for upload in files:
         filename = upload.filename or "unnamed"
         try:
+            # Per file, not once for the batch, in keeping with the partial success
+            # above: the files that fit are stored and the rest say why they were not.
+            # The bytes are already spooled to temp space by now, so what is checked is
+            # the copy into media — which is where `has_room` counts the size.
+            if not capacity.has_room(upload.size or 0):
+                rejected.append(
+                    UploadRejection(
+                        filename=filename,
+                        code=capacity.DISK_FULL_CODE,
+                        message=capacity.DISK_FULL_MESSAGE,
+                    )
+                )
+                continue
             asset = await service.ingest_upload(
                 session,
                 storage,
@@ -112,6 +125,10 @@ async def upload_assets(
     if not created and rejected:
         # Nothing stored at all is a failed request, not a 201 describing an empty
         # result — the client should be able to tell without inspecting the body.
+        if all(r.code == capacity.DISK_FULL_CODE for r in rejected):
+            # Said as itself rather than as "none of the 3 files could be stored": the
+            # reason is the same for every file and is the one thing worth reading.
+            raise capacity.disk_full_error()
         raise HTTPException(
             status_code=status.HTTP_400_BAD_REQUEST,
             detail={
diff --git a/backend/app/routers/clips.py b/backend/app/routers/clips.py
index 2ed3bbf..a642fa5 100644
--- a/backend/app/routers/clips.py
+++ b/backend/app/routers/clips.py
@@ -22,7 +22,7 @@
 from app.schemas_jobs import ActivityJobRead
 from app.services import assets as asset_service
 from app.services import tags as tag_service
-from app.storage import LocalStorage
+from app.storage import LocalStorage, capacity
 
 router = APIRouter()
 
@@ -146,6 +146,7 @@ def start_subvideo_extraction(
             detail={"code": "bad_request", "message": "The out point must be after the in point"},
         )
     _require_no_active_extraction(session, asset.id)
+    capacity.require_room()
 
     job_payload = json.dumps(
         {
@@ -178,6 +179,7 @@ def promote_clip(
             detail={"code": "not_a_clip", "message": "This asset is not a clip"},
         )
     _require_no_active_extraction(session, clip.id)
+    capacity.require_room()
 
     job = enrichment_jobs.submit(
         session, clip, KIND_EXTRACT_SUBVIDEO, payload=json.dumps({"mode": "promote"})
diff --git a/backend/app/routers/generate.py b/backend/app/routers/generate.py
index 6b4b665..94f8bfb 100644
--- a/backend/app/routers/generate.py
+++ b/backend/app/routers/generate.py
@@ -55,7 +55,7 @@
 from app.schemas_jobs import ActivityJobRead
 from app.services.assets import generation_of
 from app.settings_store import FAL_API_KEY, has_setting
-from app.storage import LocalStorage, StorageError
+from app.storage import LocalStorage, StorageError, capacity
 
 router = APIRouter()
 
@@ -330,6 +330,8 @@ def _checked_sources(
 
 
 def _queue(session: Session, user_id: str, request: GenerationRequest) -> ActivityJobRead:
+    # Here, after every other check, so a bad request is still told what is wrong with it.
+    capacity.require_room()
     job = enrichment_jobs.submit_library(
         session,
         user_id,
diff --git a/backend/app/routers/imports.py b/backend/app/routers/imports.py
index 6bc4497..5194b4c 100644
--- a/backend/app/routers/imports.py
+++ b/backend/app/routers/imports.py
@@ -21,6 +21,7 @@
 from app.models.job import KIND_IMPORT_URL
 from app.schemas import DataResponse
 from app.schemas_jobs import ActivityJobRead
+from app.storage import capacity
 
 router = APIRouter()
 
@@ -58,6 +59,7 @@ def start_url_import(
     it rather than downloading it twice.
     """
     url = normalise_url(payload.url)
+    capacity.require_room()
     request = ImportRequest(
         url=url,
         audio_only=payload.audio_only,
diff --git a/backend/app/routers/storage.py b/backend/app/routers/storage.py
new file mode 100644
index 0000000..15a43cd
--- /dev/null
+++ b/backend/app/routers/storage.py
@@ -0,0 +1,70 @@
+"""How much disk GAM uses, how much is left, and clearing what nothing refers to.
+
+Two audiences. Anybody signed in sees their own library's share — what they could free
+by deleting things. The server's disk, every user's total and the stray-file sweep are
+for administrators: how full one person's server is, and what everybody else keeps on
+it, is not every account's business.
+"""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends
+from sqlmodel import Session
+
+from app.auth import AdminUser, CurrentUser, is_admin
+from app.database import get_session
+from app.models.user import User
+from app.routers.assets import get_storage
+from app.schemas import DataResponse
+from app.schemas_storage import CleanupResult, StorageStatus, StorageSummary
+from app.services import storage_usage
+from app.storage import LocalStorage, capacity
+
+router = APIRouter()
+
+
+@router.get("", response_model=DataResponse[StorageSummary])
+def read_storage(
+    user: CurrentUser,
+    session: Session = Depends(get_session),
+    storage: LocalStorage = Depends(get_storage),
+) -> DataResponse[StorageSummary]:
+    admin = is_admin(user, session.get(User, user.id))
+    volumes = capacity.volumes()
+    return DataResponse(
+        data=StorageSummary(
+            level=storage_usage.level(volumes),
+            library=storage_usage.library_usage(session, storage, user.id),
+            server=storage_usage.server_usage(session, storage, volumes) if admin else None,
+        )
+    )
+
+
+@router.get("/status", response_model=DataResponse[StorageStatus])
+def read_status(
+    user: CurrentUser, session: Session = Depends(get_session)
+) -> DataResponse[StorageStatus]:
+    """What the header polls. `statvfs` only — no walk, no table scan.
+
+    The level is everybody's, because a refused upload is everybody's problem and the
+    warning is what explains it before it happens. The numbers are an admin's.
+    """
+    volumes = capacity.volumes()
+    level = storage_usage.level(volumes)
+    tightest = capacity.tightest(volumes)
+    if tightest is None or not is_admin(user, session.get(User, user.id)):
+        return DataResponse(data=StorageStatus(level=level))
+    return DataResponse(
+        data=StorageStatus(
+            level=level, free_bytes=tightest.free_bytes, total_bytes=tightest.total_bytes
+        )
+    )
+
+
+@router.post("/cleanup", response_model=DataResponse[CleanupResult])
+def clean_up_strays(
+    user: AdminUser,
+    session: Session = Depends(get_session),
+    storage: LocalStorage = Depends(get_storage),
+) -> DataResponse[CleanupResult]:
+    return DataResponse(data=storage_usage.remove_strays(session, storage))
diff --git a/backend/app/schemas_storage.py b/backend/app/schemas_storage.py
new file mode 100644
index 0000000..7b79e62
--- /dev/null
+++ b/backend/app/schemas_storage.py
@@ -0,0 +1,81 @@
+"""What `/api/storage` returns."""
+
+from __future__ import annotations
+
+from typing import List, Optional
+
+from pydantic import BaseModel
+
+
+class FileGroup(BaseModel):
+    files: int = 0
+    bytes: int = 0
+
+
+class TypeUsage(BaseModel):
+    asset_type: str
+    files: int
+    bytes: int
+
+
+class LargestAsset(BaseModel):
+    id: str
+    name: str
+    asset_type: str
+    size_bytes: int
+
+
+class LibraryUsage(BaseModel):
+    """One user's share: what they could free by deleting things."""
+
+    total_bytes: int
+    files: int
+    by_type: List[TypeUsage]
+    thumbnails: FileGroup
+    largest: List[LargestAsset]
+
+
+class VolumeRead(BaseModel):
+    # media | database | working — every role GAM puts on this one filesystem.
+    roles: List[str]
+    total_bytes: int
+    used_bytes: int
+    free_bytes: int
+    level: str
+    # Whether this volume's level counts. The working volume alone does not; see
+    # `storage/capacity.py::Volume.guarded`.
+    guarded: bool
+
+
+class ServerUsage(BaseModel):
+    """Admin only. The whole server, every user included."""
+
+    volumes: List[VolumeRead]
+    # Every file under the media root: all users, thumbnails and strays included.
+    media: FileGroup
+    # None when the database is not a local SQLite file.
+    database_bytes: Optional[int] = None
+    stray: FileGroup
+    warn_free_bytes: int
+    reserve_bytes: int
+
+
+class StorageSummary(BaseModel):
+    # Everybody's: the header's level, so the panel can say why an upload was refused
+    # without telling a non-admin how full the server is.
+    level: str
+    library: LibraryUsage
+    server: Optional[ServerUsage] = None
+
+
+class StorageStatus(BaseModel):
+    level: str
+    # Admin only; null for everyone else, who is told the level and not the numbers.
+    free_bytes: Optional[int] = None
+    total_bytes: Optional[int] = None
+
+
+class CleanupResult(BaseModel):
+    removed: FileGroup
+    # Strays the sweep found and could not delete. Logged with the reason.
+    skipped: int = 0
diff --git a/backend/app/services/storage_usage.py b/backend/app/services/storage_usage.py
new file mode 100644
index 0000000..cfcd1aa
--- /dev/null
+++ b/backend/app/services/storage_usage.py
@@ -0,0 +1,218 @@
+"""What the library takes up on disk, and the files nothing refers to any more.
+
+A user's breakdown comes from the database rather than a walk: `size_bytes` is recorded
+as the bytes are written and files are write-once, so the column is exact and the query
+is one indexed GROUP BY. Only thumbnails are counted on disk, because their sizes are
+recorded nowhere — and a poster is shared between a parent and its clips, so counting
+per row would count one file several times.
+
+The server-wide numbers walk the media tree. That is a `stat` per file, which for a
+library of tens of thousands of files is well under a second, and it runs only when an
+admin opens Settings — not worth a cache that could disagree with the disk.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import time
+from datetime import timedelta
+
+from sqlalchemy import func, or_
+from sqlmodel import Session, col, select
+
+from app.config import settings
+from app.models.asset import Asset
+from app.schemas_storage import (
+    CleanupResult,
+    FileGroup,
+    LargestAsset,
+    LibraryUsage,
+    ServerUsage,
+    TypeUsage,
+    VolumeRead,
+)
+from app.storage import LocalStorage, StorageError, thumb_key_for, validate_key
+from app.storage import capacity
+
+logger = logging.getLogger(__name__)
+
+THUMB_SUFFIX = ".thumb.jpg"
+LARGEST_LIMIT = 10
+
+# A file is only a stray once it is this old. Every write path puts the bytes on disk
+# *before* it commits the row that points at them — an upload, an import, an extraction
+# and a generation alike — so a file nothing refers to yet may simply be one whose row
+# is a moment away. No write takes a day. A sweep that is wrong anyway is recoverable:
+# the backup sidecar snapshots `data/media` hourly.
+STRAY_MIN_AGE = timedelta(hours=24)
+
+
+# ─── one user ────────────────────────────────────────────────────────────────
+
+
+def library_usage(session: Session, storage: LocalStorage, user_id: str) -> LibraryUsage:
+    owns_file = (Asset.user_id == user_id, col(Asset.storage_key).is_not(None))
+
+    rows = session.exec(
+        select(Asset.asset_type, func.count(), func.coalesce(func.sum(Asset.size_bytes), 0))
+        .where(*owns_file)
+        .group_by(Asset.asset_type)
+    ).all()
+    by_type = sorted(
+        (TypeUsage(asset_type=kind, files=count, bytes=total) for kind, count, total in rows),
+        key=lambda row: row.bytes,
+        reverse=True,
+    )
+
+    thumbnails = FileGroup()
+    for key, stat in storage.files(user_id):
+        if key.endswith(THUMB_SUFFIX):
+            thumbnails.files += 1
+            thumbnails.bytes += stat.st_size
+
+    largest = [
+        LargestAsset(id=asset_id, name=name, asset_type=kind, size_bytes=size)
+        for asset_id, name, kind, size in session.exec(
+            select(Asset.id, Asset.name, Asset.asset_type, Asset.size_bytes)
+            .where(*owns_file)
+            .order_by(col(Asset.size_bytes).desc(), col(Asset.id))
+            .limit(LARGEST_LIMIT)
+        ).all()
+    ]
+
+    originals = sum(row.bytes for row in by_type)
+    return LibraryUsage(
+        total_bytes=originals + thumbnails.bytes,
+        files=sum(row.files for row in by_type),
+        by_type=by_type,
+        thumbnails=thumbnails,
+        largest=largest,
+    )
+
+
+# ─── the whole server ────────────────────────────────────────────────────────
+
+
+def level(volumes: list[capacity.Volume]) -> str:
+    tightest = capacity.tightest(volumes)
+    return capacity.level_for(tightest.free_bytes) if tightest else capacity.LEVEL_OK
+
+
+def server_usage(
+    session: Session, storage: LocalStorage, volumes: list[capacity.Volume]
+) -> ServerUsage:
+    media = FileGroup()
+    stray = FileGroup()
+    for _key, size in _scan(session, storage, media):
+        stray.files += 1
+        stray.bytes += size
+
+    return ServerUsage(
+        volumes=[
+            VolumeRead(
+                roles=volume.roles,
+                total_bytes=volume.total_bytes,
+                used_bytes=volume.used_bytes,
+                free_bytes=volume.free_bytes,
+                level=capacity.level_for(volume.free_bytes),
+                guarded=volume.guarded,
+            )
+            for volume in volumes
+        ],
+        media=media,
+        database_bytes=_database_bytes(),
+        stray=stray,
+        warn_free_bytes=int(settings.disk_warn_free_gb * capacity.GB),
+        reserve_bytes=int(settings.disk_reserve_gb * capacity.GB),
+    )
+
+
+def remove_strays(session: Session, storage: LocalStorage) -> CleanupResult:
+    """Delete every stray, found afresh rather than from what an earlier page showed.
+
+    Through `storage.delete`, which validates the key and resolves it inside the root,
+    so a sweep cannot reach anything a normal delete could not.
+    """
+    removed = FileGroup()
+    skipped = 0
+    for key, size in list(_scan(session, storage)):
+        if storage.delete(key):
+            removed.files += 1
+            removed.bytes += size
+        else:
+            skipped += 1
+    if removed.files:
+        logger.info("Removed %d stray files (%d bytes)", removed.files, removed.bytes)
+    return CleanupResult(removed=removed, skipped=skipped)
+
+
+def _scan(session: Session, storage: LocalStorage, totals: FileGroup | None = None):
+    """Yield `(key, size)` for each stray, adding every file seen to `totals`.
+
+    A stray is a file old enough (`STRAY_MIN_AGE`) that no row's `storage_key` or
+    `thumb_key` names — left by a delete whose unlink failed, or by an upload or job
+    that died between writing the bytes and committing the row. Interrupted writes'
+    `.partial` files are strays by the same rule: no row ever names one.
+
+    A name that is not a valid key is skipped rather than offered: GAM never writes
+    one, so it is somebody else's file, and `storage.delete` would refuse it anyway.
+    """
+    referenced = _referenced_keys(session)
+    cutoff = time.time() - STRAY_MIN_AGE.total_seconds()
+
+    for key, stat in storage.files():
+        if totals is not None:
+            totals.files += 1
+            totals.bytes += stat.st_size
+        if key in referenced or stat.st_mtime > cutoff:
+            continue
+        try:
+            validate_key(key)
+        except StorageError:
+            continue
+        yield key, stat.st_size
+
+
+def _referenced_keys(session: Session) -> set[str]:
+    """Every key any row points at, across all users.
+
+    The derived thumbnail name is kept as well as the column. A thumbnail write that
+    succeeded under a row whose `thumb_key` update did not is still that asset's poster
+    — `thumb_key_for` exists so one can always be found from the asset's own key — and
+    deleting it would be unrecoverable where keeping it costs a few kilobytes.
+    """
+    keys: set[str] = set()
+    rows = session.exec(
+        select(Asset.storage_key, Asset.thumb_key).where(
+            or_(col(Asset.storage_key).is_not(None), col(Asset.thumb_key).is_not(None))
+        )
+    ).all()
+    for storage_key, thumb_key in rows:
+        if storage_key:
+            keys.add(storage_key)
+            try:
+                keys.add(thumb_key_for(storage_key))
+            except StorageError:
+                pass
+        if thumb_key:
+            keys.add(thumb_key)
+    return keys
+
+
+def _database_bytes() -> int | None:
+    """The SQLite file with its WAL and shared-memory sidecars.
+
+    The WAL is not small change: between checkpoints it holds every committed write the
+    main file has not absorbed yet, and after a bulk import it can rival the database.
+    """
+    path = capacity.database_path()
+    if path is None:
+        return None
+    total = 0
+    for suffix in ("", "-wal", "-shm"):
+        try:
+            total += os.stat(f"{path}{suffix}").st_size
+        except OSError:
+            continue
+    return total
diff --git a/backend/app/storage/capacity.py b/backend/app/storage/capacity.py
new file mode 100644
index 0000000..cbfa61f
--- /dev/null
+++ b/backend/app/storage/capacity.py
@@ -0,0 +1,170 @@
+"""How much room the server has left, and the guard that stops writes when it has none.
+
+Read with `statvfs` on the directories GAM writes to. Inside Docker those are bind
+mounts, so the answer is the *host* disk's — which is what anyone asking "how full is
+the server" means, and the only number that predicts when a write will fail.
+
+The guard exists because nothing else stops a write. A full disk fails an import
+halfway, leaves `.partial` files behind, and can fail a SQLite commit mid-transaction;
+refusing new work while there is still a reserve left is far cheaper than any of those.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import shutil
+import tempfile
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional
+
+from fastapi import HTTPException, status
+from sqlalchemy.engine import make_url
+
+from app.config import settings
+
+logger = logging.getLogger(__name__)
+
+ROLE_MEDIA = "media"
+ROLE_DATABASE = "database"
+# The container's temp directory. Uploads spool there before the handler runs, and
+# imports, transcodes and generations download there before the copy into media — so a
+# two-gigabyte import needs two gigabytes here first. Under Docker it is the container's
+# own layer, commonly a different disk from the bind-mounted data.
+ROLE_WORKING = "working"
+
+LEVEL_OK = "ok"
+LEVEL_LOW = "low"
+LEVEL_CRITICAL = "critical"
+
+GB = 1024**3
+
+DISK_FULL_CODE = "disk_full"
+DISK_FULL_MESSAGE = (
+    "The server's disk is nearly full, so nothing new can be stored until space is "
+    "freed. Settings → Storage shows what is using it."
+)
+
+
+@dataclass
+class Volume:
+    """One filesystem, and every role GAM puts on it."""
+
+    roles: list[str] = field(default_factory=list)
+    total_bytes: int = 0
+    # Not `total - free`. ext4 reserves about 5% of blocks for root, and `free` here is
+    # what a non-root process can still write, so `used + free` falls short of `total`
+    # by that reserve. Computing free as the difference would promise space no write
+    # can have; the UI shows the gap as "reserved" instead.
+    used_bytes: int = 0
+    free_bytes: int = 0
+
+    @property
+    def guarded(self) -> bool:
+        """Whether filling this disk would damage anything that lasts.
+
+        The working volume alone is not. A download that does not fit there fails with
+        a plain error and its temp directory is removed; nothing persistent is touched.
+        It is also, on a development machine, often a tmpfs sized from RAM, and holding
+        it to a 5 GB reserve would refuse every upload on a laptop with 8 GB of memory.
+        """
+        return ROLE_MEDIA in self.roles or ROLE_DATABASE in self.roles
+
+
+def _disk_usage(path: Path):
+    """The seam tests patch: `shutil.disk_usage` cannot be made to report a full disk."""
+    return shutil.disk_usage(path)
+
+
+def _device(path: Path) -> int:
+    return os.stat(path).st_dev
+
+
+def database_path() -> Optional[Path]:
+    """The SQLite file, or None when the database is not a local file."""
+    url = make_url(settings.resolved_database_url)
+    if url.get_backend_name() != "sqlite" or not url.database or url.database == ":memory:":
+        return None
+    return Path(url.database)
+
+
+def _paths() -> list[tuple[str, Path]]:
+    paths = [(ROLE_MEDIA, settings.resolved_media_dir)]
+    database = database_path()
+    if database is not None:
+        paths.append((ROLE_DATABASE, database.parent))
+    paths.append((ROLE_WORKING, Path(tempfile.gettempdir())))
+    return paths
+
+
+def volumes() -> list[Volume]:
+    """Each distinct filesystem GAM writes to, media first.
+
+    Merged by device, so the usual layout — `data/db` and `data/media` side by side —
+    reads as one disk rather than as the same numbers twice. A path that cannot be read
+    is left out and logged rather than raised: an unreadable statvfs must not turn the
+    Settings page, or an upload, into a 500.
+    """
+    found: dict[int, Volume] = {}
+    for role, path in _paths():
+        try:
+            device = _device(path)
+            usage = _disk_usage(path)
+        except OSError as exc:
+            logger.warning("Could not read disk usage for %s (%s): %s", role, path, exc)
+            continue
+        if device in found:
+            found[device].roles.append(role)
+            continue
+        found[device] = Volume(
+            roles=[role],
+            total_bytes=usage.total,
+            used_bytes=usage.used,
+            free_bytes=usage.free,
+        )
+    return list(found.values())
+
+
+def level_for(free_bytes: int) -> str:
+    if free_bytes < settings.disk_reserve_gb * GB:
+        return LEVEL_CRITICAL
+    if free_bytes < settings.disk_warn_free_gb * GB:
+        return LEVEL_LOW
+    return LEVEL_OK
+
+
+def tightest(found: list[Volume]) -> Optional[Volume]:
+    """The guarded volume with the least room — the one that decides the level."""
+    guarded = [volume for volume in found if volume.guarded]
+    return min(guarded, key=lambda volume: volume.free_bytes) if guarded else None
+
+
+def has_room(needed_bytes: int = 0) -> bool:
+    """Whether a write of `needed_bytes` would still leave the reserve free.
+
+    The size counts against the media volume only: that is where the file lands, and
+    the database's share of any write is a few rows. True when nothing could be read —
+    the guard fails open, for the same reason `volumes()` does not raise.
+    """
+    reserve = settings.disk_reserve_gb * GB
+    for volume in volumes():
+        if not volume.guarded:
+            continue
+        needed = max(needed_bytes, 0) if ROLE_MEDIA in volume.roles else 0
+        if volume.free_bytes - needed < reserve:
+            return False
+    return True
+
+
+def disk_full_error() -> HTTPException:
+    return HTTPException(
+        status_code=status.HTTP_507_INSUFFICIENT_STORAGE,
+        detail={"code": DISK_FULL_CODE, "message": DISK_FULL_MESSAGE},
+    )
+
+
+def require_room(needed_bytes: int = 0) -> None:
+    """Raise a 507 unless `has_room`. For routers, before they queue the work."""
+    if not has_room(needed_bytes):
+        raise disk_full_error()
diff --git a/backend/app/storage/local.py b/backend/app/storage/local.py
index 026a35f..1eeba3d 100644
--- a/backend/app/storage/local.py
+++ b/backend/app/storage/local.py
@@ -164,6 +164,36 @@ def delete(self, key: str) -> bool:
             logger.warning("Could not delete %s: %s", key, exc)
             return False
 
+    def files(self, owner: str | None = None) -> Iterator[tuple[str, os.stat_result]]:
+        """Every file in the layout, as `(key, stat)` — one owner's, or everyone's.
+
+        Exactly two levels deep, `<owner>/<name>`, because that is the only shape a key
+        can have. Anything else under the root — a nested directory, a stray file at the
+        top — is not GAM's, so it is neither counted nor offered for removal. Symlinks
+        are not followed: one could point anywhere, and `_path` would refuse it anyway.
+        """
+        if not self.root.is_dir():
+            return
+        if owner is not None:
+            # The rule a key's first segment is held to, so an owner cannot name `..`.
+            # One that fails it cannot have been written under, so it has no files.
+            try:
+                validate_key(f"{owner}/x")
+            except StorageError:
+                return
+            owner_dirs = [self.root / owner]
+        else:
+            with os.scandir(self.root) as entries:
+                owner_dirs = [Path(e.path) for e in entries if e.is_dir(follow_symlinks=False)]
+
+        for owner_path in owner_dirs:
+            if owner_path.is_symlink() or not owner_path.is_dir():
+                continue
+            with os.scandir(owner_path) as entries:
+                for entry in entries:
+                    if entry.is_file(follow_symlinks=False):
+                        yield f"{owner_path.name}/{entry.name}", entry.stat(follow_symlinks=False)
+
     def usage_bytes(self, owner: str) -> int:
         """Total bytes held for one owner, thumbnails included."""
         owner_dir = self.root / owner
diff --git a/backend/tests/conftest.py b/backend/tests/conftest.py
index 6537afa..38471ef 100644
--- a/backend/tests/conftest.py
+++ b/backend/tests/conftest.py
@@ -47,6 +47,45 @@ def no_background_workers(monkeypatch):
     monkeypatch.setattr(enrichment, "start", lambda: None)
 
 
+class FakeDisk:
+    """What `storage/capacity.py` is told about the disk.
+
+    Autouse, because the guard on every upload, import and generation reads it: without
+    a fake, whether the suite passed would depend on how full the machine running it
+    was. Defaults to a disk with plenty of room. `devices` maps a path to a device id;
+    anything unlisted is device 1, so everything is one disk unless a test says not.
+    """
+
+    GB = 1024**3
+
+    def __init__(self) -> None:
+        self.set(free_gb=900)
+        self.devices: dict = {}
+
+    def set(self, *, free_gb: float, total_gb: float = 1000, reserved_gb: float = 0) -> None:
+        self.total = int(total_gb * self.GB)
+        self.free = int(free_gb * self.GB)
+        self.used = self.total - self.free - int(reserved_gb * self.GB)
+
+    def usage(self, path):
+        from types import SimpleNamespace
+
+        return SimpleNamespace(total=self.total, used=self.used, free=self.free)
+
+    def device(self, path) -> int:
+        return self.devices.get(str(path), 1)
+
+
+@pytest.fixture(autouse=True)
+def disk(monkeypatch):
+    from app.storage import capacity
+
+    fake = FakeDisk()
+    monkeypatch.setattr(capacity, "_disk_usage", fake.usage)
+    monkeypatch.setattr(capacity, "_device", fake.device)
+    return fake
+
+
 @pytest.fixture
 def anyio_backend():
     """Run `@pytest.mark.anyio` tests on asyncio only.
diff --git a/backend/tests/test_clips_api.py b/backend/tests/test_clips_api.py
index 72620cb..3a9ac8c 100644
--- a/backend/tests/test_clips_api.py
+++ b/backend/tests/test_clips_api.py
@@ -737,6 +737,22 @@ def test_running_extract_creates_a_standalone_asset(library, session):
     assert asset.storage_key == created["file_url"].split("?")[0].removeprefix("/media/")
 
 
+def test_a_full_disk_stops_a_queued_extraction_before_it_cuts(library, session, disk):
+    import json
+
+    from app.enrichment.extract_subvideo import run as run_extract_subvideo
+    from app.enrichment.subvideo import SubvideoExtractionError
+
+    created = _upload_video(library)
+    asset = session.get(Asset, created["id"])
+    disk.set(free_gb=1)
+
+    payload = json.dumps({"mode": "extract", "in_point": 0.2, "out_point": 1.5})
+    with pytest.raises(SubvideoExtractionError, match="disk is nearly full"):
+        run_extract_subvideo(session, asset, payload, lambda *a, **k: None)
+    assert session.exec(select(Asset).where(Asset.source == "sub_video")).all() == []
+
+
 @needs_ffmpeg
 def test_running_promote_updates_the_clip_in_place(library, session):
     import json
diff --git a/backend/tests/test_generation_job.py b/backend/tests/test_generation_job.py
index cb4f0dc..9d6348f 100644
--- a/backend/tests/test_generation_job.py
+++ b/backend/tests/test_generation_job.py
@@ -431,6 +431,40 @@ def test_a_restart_resumes_the_stored_request_instead_of_submitting_again(
     assert len(_generated(session)) == 1
 
 
+def test_a_full_disk_stops_a_queued_generation_before_fal_is_paid(
+    library, session, monkeypatch, ready, fal, disk
+):
+    job_id = _start(library, {"model_id": ready[T2I].id, "prompt": PROMPT})
+    # Filled while the job waited in the queue.
+    disk.set(free_gb=1)
+
+    job = run_job(session, monkeypatch, job_id)
+
+    assert job.status == "error"
+    assert job.error_message.startswith("The server's disk is nearly full")
+    assert fal.submissions() == []
+
+
+def test_a_generation_already_submitted_still_tries_to_save_on_a_full_disk(
+    library, session, monkeypatch, ready, fal, disk
+):
+    # fal has billed for it by now; refusing to save would throw away what was paid for.
+    fal.statuses = [{"status": "IN_QUEUE", "queue_position": 2}, ProcessDied]
+    job_id = _start(library, {"model_id": ready[T2I].id, "prompt": PROMPT})
+    with pytest.raises(ProcessDied):
+        run_job(session, monkeypatch, job_id)
+    queue = enrichment_jobs.generation_queue()
+    monkeypatch.setattr(queue, "engine", session.get_bind())
+    queue.recover_pending()
+
+    disk.set(free_gb=1)
+    fal.statuses = [{"status": "COMPLETED"}]
+    job = run_job(session, monkeypatch, job_id)
+
+    assert job.status == "done", job.error_message
+    assert len(_generated(session)) == 1
+
+
 def test_a_restart_after_saving_does_not_save_or_bill_twice(library, session, monkeypatch, ready, fal):
     # Dies looking up the price: after the asset is saved, before the cost is recorded.
     fal.pricing_raises = ProcessDied
diff --git a/backend/tests/test_storage.py b/backend/tests/test_storage.py
index 78a02a8..968562e 100644
--- a/backend/tests/test_storage.py
+++ b/backend/tests/test_storage.py
@@ -214,3 +214,30 @@ def test_usage_counts_only_that_owner(storage):
     assert storage.usage_bytes("user1") == 150
     assert storage.usage_bytes("user2") == 999
     assert storage.usage_bytes("nobody") == 0
+
+
+# ─── listing ─────────────────────────────────────────────────────────────────
+
+
+def test_files_lists_the_layout_and_nothing_outside_it(storage, tmp_path_factory):
+    mine = storage.write_bytes(new_key("user1", ".bin"), b"x" * 10).key
+    theirs = storage.write_bytes(new_key("user2", ".bin"), b"x" * 20).key
+    (storage.root / "loose.txt").write_bytes(b"not in an owner's directory")
+    (storage.root / "user1" / "nested").mkdir()
+    (storage.root / "user1" / "nested" / "deep.bin").write_bytes(b"too deep")
+    # Its own directory: `tmp_path` is the storage root here.
+    outside = tmp_path_factory.mktemp("outside")
+    (outside / "secret.bin").write_bytes(b"elsewhere")
+    (storage.root / "user1" / "link.bin").symlink_to(outside / "secret.bin")
+    (storage.root / "linked-owner").symlink_to(outside)
+
+    everyone = {key: stat.st_size for key, stat in storage.files()}
+    assert everyone == {mine: 10, theirs: 20}
+    assert {key for key, _ in storage.files("user1")} == {mine}
+
+
+def test_files_for_an_owner_that_cannot_be_a_key_is_empty(storage):
+    storage.write_bytes(new_key("user1", ".bin"), b"x")
+
+    assert list(storage.files("..")) == []
+    assert list(storage.files("nobody")) == []
diff --git a/backend/tests/test_storage_usage.py b/backend/tests/test_storage_usage.py
new file mode 100644
index 0000000..66dd99a
--- /dev/null
+++ b/backend/tests/test_storage_usage.py
@@ -0,0 +1,463 @@
+"""Disk space: the Settings breakdown, the header's level, the stray sweep, and the
+guard that refuses new writes when the disk is nearly full.
+
+The disk is the `disk` fixture's (conftest.py). `statvfs` cannot be made to report a
+full disk on demand, and a suite whose result depended on the runner's free space would
+not be testing anything.
+"""
+
+import os
+import socket
+import tempfile
+import time
+import uuid
+from pathlib import Path
+
+import pytest
+from sqlmodel import func, select
+
+from app.config import settings
+from app.models.asset import Asset
+from app.models.job import EnrichmentJob
+from app.storage import capacity, thumb_key_for
+from app.storage.capacity import DISK_FULL_CODE, DISK_FULL_MESSAGE, GB
+from tests.fal_stub import T2I, seed_models, set_fal_key
+
+FIXTURES = Path(__file__).parent / "fixtures"
+TEST_USER = "user-under-test"
+DAY = 24 * 3600
+
+
+def _upload(client, name: str, media_type: str) -> dict:
+    response = client.post(
+        "/api/assets", files=[("files", (name, (FIXTURES / name).read_bytes(), media_type))]
+    )
+    assert response.status_code == 201, response.text
+    return response.json()["created"][0]
+
+
+def _summary(client) -> dict:
+    response = client.get("/api/storage")
+    assert response.status_code == 200, response.text
+    return response.json()["data"]
+
+
+def _status(client) -> dict:
+    response = client.get("/api/storage/status")
+    assert response.status_code == 200, response.text
+    return response.json()["data"]
+
+
+def _write(path: Path, size: int, *, age: float = 2 * DAY) -> Path:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_bytes(b"x" * size)
+    past = time.time() - age
+    os.utime(path, (past, past))
+    return path
+
+
+def _row(session, *, user_id: str = TEST_USER, size: int = 0, kind: str = "video", **fields) -> Asset:
+    fields.setdefault("storage_key", f"{user_id}/{uuid.uuid4()}.mp4")
+    asset = Asset(user_id=user_id, name=f"{kind} {size}", asset_type=kind, size_bytes=size, **fields)
+    session.add(asset)
+    session.commit()
+    return asset
+
+
+@pytest.fixture
+def admin(monkeypatch):
+    monkeypatch.setattr(settings, "admin_users", "tester")
+
+
+# ─── one user's library ──────────────────────────────────────────────────────
+
+
+def test_the_library_is_broken_down_by_type_with_its_thumbnails(library, media_dir):
+    _upload(library, "sample_image.jpg", "image/jpeg")
+    _upload(library, "sample_image.png", "image/png")
+    _upload(library, "sample_document.txt", "text/plain")
+
+    library_usage = _summary(library)["library"]
+
+    images = (FIXTURES / "sample_image.jpg").stat().st_size + (FIXTURES / "sample_image.png").stat().st_size
+    text = (FIXTURES / "sample_document.txt").stat().st_size
+    assert library_usage["by_type"] == [
+        {"asset_type": "image", "files": 2, "bytes": images},
+        {"asset_type": "document", "files": 1, "bytes": text},
+    ]
+    assert library_usage["files"] == 3
+
+    # Counted on disk: thumbnail sizes are recorded nowhere else.
+    thumbs = list((media_dir / TEST_USER).glob("*.thumb.jpg"))
+    assert thumbs, "the images should have produced previews"
+    assert library_usage["thumbnails"] == {
+        "files": len(thumbs),
+        "bytes": sum(path.stat().st_size for path in thumbs),
+    }
+    assert library_usage["total_bytes"] == images + text + library_usage["thumbnails"]["bytes"]
+
+
+def test_window_clips_and_other_peoples_files_are_not_counted(library, session):
+    mine = _row(session, size=1000)
+    # A window clip owns no bytes, whatever its size column says.
+    _row(session, size=10**12, storage_key=None, parent_asset_id=mine.id)
+    _row(session, user_id="someone-else", size=10**12)
+
+    library_usage = _summary(library)["library"]
+
+    assert library_usage["by_type"] == [{"asset_type": "video", "files": 1, "bytes": 1000}]
+    assert [row["id"] for row in library_usage["largest"]] == [mine.id]
+
+
+def test_the_largest_are_my_ten_biggest_files_biggest_first(library, session):
+    rows = [_row(session, size=size * 1_000_000) for size in range(1, 13)]
+    _row(session, user_id="someone-else", size=10**12)
+
+    largest = _summary(library)["library"]["largest"]
+
+    assert [row["id"] for row in largest] == [row.id for row in reversed(rows)][:10]
+    assert largest[0] == {
+        "id": rows[-1].id,
+        "name": rows[-1].name,
+        "asset_type": "video",
+        "size_bytes": 12_000_000,
+    }
+
+
+def test_an_empty_library_is_all_zeros(library):
+    library_usage = _summary(library)["library"]
+
+    assert library_usage == {
+        "total_bytes": 0,
+        "files": 0,
+        "by_type": [],
+        "thumbnails": {"files": 0, "bytes": 0},
+        "largest": [],
+    }
+
+
+# ─── the server ──────────────────────────────────────────────────────────────
+
+
+def test_server_numbers_are_for_admins_only(library, monkeypatch):
+    assert _summary(library)["server"] is None
+
+    monkeypatch.setattr(settings, "admin_users", "tester")
+    assert _summary(library)["server"] is not None
+
+
+def test_the_server_reports_the_disk_and_every_users_files(library, admin, disk, media_dir, session):
+    _upload(library, "sample_image.jpg", "image/jpeg")
+    _write(media_dir / "someone-else" / f"{uuid.uuid4()}.mp4", 5000, age=0)
+    _row(session, user_id="someone-else", storage_key=f"someone-else/{uuid.uuid4()}.mp4")
+    disk.set(free_gb=400, total_gb=1000)
+
+    server = _summary(library)["server"]
+
+    (volume,) = server["volumes"]
+    assert volume["roles"] == ["media", "database", "working"]
+    assert volume["total_bytes"] == 1000 * GB
+    assert volume["free_bytes"] == 400 * GB
+    assert volume["level"] == "ok"
+    assert volume["guarded"] is True
+
+    on_disk = [path for path in media_dir.rglob("*") if path.is_file()]
+    assert server["media"] == {
+        "files": len(on_disk),
+        "bytes": sum(path.stat().st_size for path in on_disk),
+    }
+    assert server["warn_free_bytes"] == 20 * GB
+    assert server["reserve_bytes"] == 5 * GB
+
+
+def test_free_space_is_what_can_be_written_not_total_minus_used(library, admin, disk):
+    # ext4's root reserve: used + free falls short of total, and the gap is not free.
+    disk.set(free_gb=100, total_gb=1000, reserved_gb=50)
+
+    (volume,) = _summary(library)["server"]["volumes"]
+
+    assert volume["free_bytes"] == 100 * GB
+    assert volume["used_bytes"] == 850 * GB
+
+
+def test_the_database_counts_its_write_ahead_log(library, admin, monkeypatch, tmp_path):
+    database = tmp_path / "db" / "gam.db"
+    _write(database, 1000, age=0)
+    _write(Path(f"{database}-wal"), 400, age=0)
+    monkeypatch.setattr(settings, "database_url", f"sqlite:///{database}")
+
+    assert _summary(library)["server"]["database_bytes"] == 1400
+
+
+def test_a_database_that_is_not_a_file_reports_no_size(library, admin, monkeypatch):
+    monkeypatch.setattr(settings, "database_url", "postgresql://db/gam")
+
+    server = _summary(library)["server"]
+
+    assert server["database_bytes"] is None
+    assert server["volumes"][0]["roles"] == ["media", "working"]
+
+
+def test_separate_disks_are_listed_separately(library, admin, disk):
+    disk.devices = {tempfile.gettempdir(): 2}
+
+    media, working = _summary(library)["server"]["volumes"]
+
+    assert media["roles"] == ["media", "database"]
+    assert working["roles"] == ["working"]
+    assert working["guarded"] is False
+
+
+def test_a_small_temp_disk_alone_does_not_raise_the_level(library, admin, disk, monkeypatch):
+    # A laptop's /tmp is often a tmpfs sized from its memory. Nothing persistent is on
+    # it, so it is shown but does not warn, and does not block anything.
+    temp = tempfile.gettempdir()
+    disk.devices = {temp: 2}
+    roomy = disk.usage(None)
+    cramped = type(roomy)(total=4 * GB, used=3 * GB, free=1 * GB)
+    monkeypatch.setattr(capacity, "_disk_usage", lambda path: cramped if str(path) == temp else roomy)
+
+    summary = _summary(library)
+
+    assert summary["level"] == "ok"
+    assert summary["server"]["volumes"][1]["level"] == "critical"
+    assert _status(library)["level"] == "ok"
+    _upload(library, "sample_document.txt", "text/plain")
+
+
+# ─── the header's level ──────────────────────────────────────────────────────
+
+
+@pytest.mark.parametrize(
+    ("free_gb", "level"),
+    [(100, "ok"), (20, "ok"), (19.9, "low"), (5, "low"), (4.9, "critical"), (0, "critical")],
+)
+def test_the_level_follows_the_thresholds(library, admin, disk, free_gb, level):
+    disk.set(free_gb=free_gb, total_gb=200)
+
+    status = _status(library)
+
+    assert status["level"] == level
+    assert status["free_bytes"] == int(free_gb * GB)
+    assert status["total_bytes"] == 200 * GB
+
+
+def test_the_thresholds_are_settings(library, disk, monkeypatch):
+    disk.set(free_gb=50)
+    monkeypatch.setattr(settings, "disk_warn_free_gb", 100)
+    assert _status(library)["level"] == "low"
+
+    monkeypatch.setattr(settings, "disk_reserve_gb", 60)
+    assert _status(library)["level"] == "critical"
+
+
+def test_everyone_gets_the_level_and_only_admins_get_the_numbers(library, disk):
+    disk.set(free_gb=10)
+
+    assert _status(library) == {"level": "low", "free_bytes": None, "total_bytes": None}
+    summary = _summary(library)
+    assert summary["level"] == "low"
+    assert summary["server"] is None
+
+
+def test_an_unreadable_disk_reads_as_ok_rather_than_failing(library, admin, monkeypatch):
+    def unreadable(path):
+        raise OSError("statvfs failed")
+
+    monkeypatch.setattr(capacity, "_disk_usage", unreadable)
+
+    assert _status(library) == {"level": "ok", "free_bytes": None, "total_bytes": None}
+    summary = _summary(library)
+    assert summary["server"]["volumes"] == []
+    assert summary["level"] == "ok"
+
+
+def test_storage_needs_a_session(client):
+    assert client.get("/api/storage").status_code == 401
+    assert client.get("/api/storage/status").status_code == 401
+    assert client.post("/api/storage/cleanup").status_code == 401
+
+
+# ─── stray files ─────────────────────────────────────────────────────────────
+
+
+@pytest.fixture
+def strewn(library, media_dir, session):
+    """A library with every kind of file the sweep has to tell apart."""
+    kept = _upload(library, "sample_image.jpg", "image/jpeg")
+    own = media_dir / TEST_USER
+    for path in own.iterdir():
+        # Old enough to be swept, so only being referenced is keeping them.
+        _write(path, path.stat().st_size)
+
+    # A poster derivable from its asset's key, though the row never recorded it.
+    unrecorded = _row(session, size=10)
+    _write(media_dir / thumb_key_for(unrecorded.storage_key), 30)
+    _write(media_dir / unrecorded.storage_key, 10)
+
+    strays = [
+        _write(own / f"{uuid.uuid4()}.mp4", 1000),  # a delete whose unlink failed
+        _write(own / f"{uuid.uuid4()}.mp4.partial", 200),  # an interrupted upload
+        _write(media_dir / "someone-else" / f"{uuid.uuid4()}.jpg", 30),  # anybody's
+    ]
+    kept_files = [
+        *own.glob("*.jpg"),
+        media_dir / thumb_key_for(unrecorded.storage_key),
+        media_dir / unrecorded.storage_key,
+        _write(own / f"{uuid.uuid4()}.mp4", 5000, age=60),  # its row may be a moment away
+        _write(own / ".DS_Store", 6, age=2 * DAY),  # not a name GAM writes
+        _write(own / "nested" / f"{uuid.uuid4()}.mp4", 7),  # not the layout
+        _write(media_dir / "loose.txt", 8),  # not the layout
+    ]
+    return {"asset": kept, "strays": strays, "kept": [p for p in kept_files if p not in strays]}
+
+
+def test_strays_are_old_files_nothing_refers_to(library, admin, strewn):
+    stray = _summary(library)["server"]["stray"]
+
+    assert stray == {"files": 3, "bytes": 1230}
+
+
+def test_cleanup_removes_the_strays_and_nothing_else(library, admin, strewn):
+    response = library.post("/api/storage/cleanup")
+
+    assert response.status_code == 200, response.text
+    assert response.json()["data"] == {"removed": {"files": 3, "bytes": 1230}, "skipped": 0}
+    assert not any(path.exists() for path in strewn["strays"])
+    assert all(path.exists() for path in strewn["kept"])
+    assert _summary(library)["server"]["stray"] == {"files": 0, "bytes": 0}
+    # The asset that was there is still whole.
+    asset = library.get(f"/api/assets/{strewn['asset']['id']}").json()["data"]
+    assert asset["missing"] is False
+
+
+def test_cleanup_is_for_admins_only(library, strewn):
+    response = library.post("/api/storage/cleanup")
+
+    assert response.status_code == 403
+    assert response.json()["detail"]["code"] == "admin_required"
+    assert all(path.exists() for path in strewn["strays"])
+
+
+def test_a_poster_shared_with_a_clip_is_not_a_stray(library, admin, session, media_dir):
+    parent = _row(session, size=10)
+    poster = _write(media_dir / thumb_key_for(parent.storage_key), 30)
+    # The clip copies the parent's poster key; deleting the parent leaves it in use.
+    _row(session, storage_key=None, thumb_key=thumb_key_for(parent.storage_key), parent_asset_id=None)
+    session.delete(parent)
+    session.commit()
+
+    library.post("/api/storage/cleanup")
+
+    assert poster.exists()
+
+
+# ─── refusing writes when the disk is nearly full ────────────────────────────
+
+
+def test_an_upload_below_the_reserve_is_refused_as_disk_full(library, disk, session):
+    disk.set(free_gb=1)
+
+    response = library.post(
+        "/api/assets",
+        files=[
+            ("files", ("a.txt", b"one", "text/plain")),
+            ("files", ("b.txt", b"two", "text/plain")),
+        ],
+    )
+
+    assert response.status_code == 507
+    assert response.json()["detail"] == {"code": DISK_FULL_CODE, "message": DISK_FULL_MESSAGE}
+    assert session.exec(select(func.count()).select_from(Asset)).one() == 0
+
+
+def test_files_that_fit_are_stored_and_the_rest_say_why_not(library, disk):
+    disk.free = 5 * GB + 1000
+
+    response = library.post(
+        "/api/assets",
+        files=[
+            ("files", ("small.txt", b"x" * 10, "text/plain")),
+            ("files", ("large.txt", b"x" * 5000, "text/plain")),
+        ],
+    )
+
+    assert response.status_code == 201, response.text
+    body = response.json()
+    assert [asset["original_name"] for asset in body["created"]] == ["small.txt"]
+    assert body["rejected"] == [
+        {"filename": "large.txt", "code": DISK_FULL_CODE, "message": DISK_FULL_MESSAGE}
+    ]
+
+
+def test_an_unreadable_disk_does_not_block_uploads(library, monkeypatch):
+    def unreadable(path):
+        raise OSError("statvfs failed")
+
+    monkeypatch.setattr(capacity, "_disk_usage", unreadable)
+
+    _upload(library, "sample_document.txt", "text/plain")
+
+
+def _refused(response):
+    assert response.status_code == 507, response.text
+    assert response.json()["detail"]["code"] == DISK_FULL_CODE
+
+
+def _jobs(session) -> int:
+    return session.exec(select(func.count()).select_from(EnrichmentJob)).one()
+
+
+def test_an_import_is_refused_before_it_is_queued(library, disk, session, monkeypatch):
+    monkeypatch.setattr(
+        socket,
+        "getaddrinfo",
+        lambda host, port, *a, **k: [(socket.AF_INET, socket.SOCK_STREAM, 6, "", ("93.184.216.34", 0))],
+    )
+    disk.set(free_gb=1)
+
+    _refused(library.post("/api/assets/import", json={"url": "https://www.youtube.com/watch?v=abc"}))
+    assert _jobs(session) == 0
+
+
+def test_a_generation_is_refused_before_it_is_queued(library, disk, session):
+    models = seed_models(session)
+    set_fal_key(session)
+    disk.set(free_gb=1)
+
+    _refused(library.post("/api/generate", json={"model_id": models[T2I].id, "prompt": "A fox"}))
+    assert _jobs(session) == 0
+
+
+def test_a_bad_generation_request_is_still_told_what_is_wrong(library, disk, session):
+    set_fal_key(session)
+    disk.set(free_gb=1)
+
+    response = library.post("/api/generate", json={"model_id": "nope", "prompt": "A fox"})
+
+    assert response.status_code == 404
+
+
+def test_extractions_and_promotions_are_refused_before_they_are_queued(library, disk, session):
+    video = _upload(library, "sample_video.mp4", "video/mp4")
+    clip = library.post(
+        f"/api/assets/{video['id']}/clips", json={"in_point": 0.0, "out_point": 0.5}
+    ).json()["data"]
+    disk.set(free_gb=1)
+
+    _refused(library.post(f"/api/assets/{video['id']}/subvideo", json={"in_point": 0.0, "out_point": 0.5}))
+    _refused(library.post(f"/api/assets/{clip['id']}/promote"))
+    assert _jobs(session) == 0
+
+
+def test_a_clip_still_works_on_a_full_disk(library, disk):
+    # A window into its parent's bytes writes none of its own, so there is no reason
+    # to refuse it.
+    video = _upload(library, "sample_video.mp4", "video/mp4")
+    disk.set(free_gb=1)
+
+    response = library.post(
+        f"/api/assets/{video['id']}/clips", json={"in_point": 0.0, "out_point": 0.5}
+    )
+
+    assert response.status_code == 201, response.text
diff --git a/backend/tests/test_url_import.py b/backend/tests/test_url_import.py
index 1591fbf..d3ff13d 100644
--- a/backend/tests/test_url_import.py
+++ b/backend/tests/test_url_import.py
@@ -291,6 +291,21 @@ def test_a_missing_cookies_file_fails_with_a_message(library, session, monkeypat
     assert "URL_IMPORT_COOKIES_FILE" in job["error_message"]
 
 
+def test_a_full_disk_stops_a_queued_import_before_it_downloads(library, session, monkeypatch, disk):
+    response = library.post("/api/assets/import", json={"url": VIDEO_URL})
+    assert response.status_code == 202, response.text
+    job_id = response.json()["data"]["id"]
+    # Filled while the job waited in the queue.
+    disk.set(free_gb=1)
+
+    _run(session, monkeypatch, job_id)
+
+    job = _activity(library, job_id)
+    assert job["status"] == "error"
+    assert job["error_message"].startswith("The server's disk is nearly full")
+    assert FakeYoutubeDL.made == []
+
+
 # ─── tags ────────────────────────────────────────────────────────────────────
 
 
diff --git a/docker-compose.yml b/docker-compose.yml
index 50f6e9f..774fbc7 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -14,6 +14,8 @@ services:
       - CORS_ORIGIN=${CORS_ORIGIN:-}
       - NOTES_BASE_URL=${NOTES_BASE_URL:-https://notes.geckopico.com}
       - MEDIA_URL_TTL_SECONDS=${MEDIA_URL_TTL_SECONDS:-3600}
+      - DISK_WARN_FREE_GB=${DISK_WARN_FREE_GB:-20}
+      - DISK_RESERVE_GB=${DISK_RESERVE_GB:-5}
       - ENVIRONMENT=${ENVIRONMENT:-production}
       - JOB_HEARTBEAT_SECONDS=${JOB_HEARTBEAT_SECONDS:-30}
       - JOB_STALE_MINUTES=${JOB_STALE_MINUTES:-40}
diff --git a/docs/deployment.md b/docs/deployment.md
index 9c0a09c..0080046 100644
--- a/docs/deployment.md
+++ b/docs/deployment.md
@@ -110,6 +110,45 @@ GAM and Notes can share one Synology and one restic repository — the distinct
 `--host` tag and `BACKUP_SFTP_REMOTE_PATH` keep their snapshots apart, so
 `restic forget` prunes each app's history separately.
 
+## Disk space
+
+**Settings → Storage** shows what the library takes up and what the disk has left. Every
+user sees their own library, broken down by type, with their largest files as links. An
+[administrator](#administrators) also sees the server:
+
+- **One bar per disk**, split into GAM's media, GAM's database, everything else on that
+  disk, and free space. These are the host's numbers: `data/` is a bind mount, so the
+  container sees the real disk. "Everything else" is whatever else lives there, such as
+  the OS, Docker's images and Gecko Notes. GAM cannot break that part down from inside its
+  container; `docker system df` on the host shows Docker's own share.
+- **Reserved by the system**, when there is any. ext4 keeps about 5% of a disk back for
+  root, so used plus free falls short of the total by that much. Free space is shown as
+  what can actually be written, never as total minus used.
+- **Working space**, when the container's temp directory is on a different disk.
+  Uploads and imports land there before they are stored. It is shown, but it does not
+  count toward the warning: nothing persistent lives there, and on a development machine
+  it is often a small RAM-backed tmpfs.
+- **Stray files**: files under `data/media` that no asset refers to, left by a delete
+  whose unlink failed or by an upload or job that died between writing the file and
+  saving the row. Only files more than a day old count, because every write puts the
+  file on disk before it saves the row. **Remove them** deletes them. The hourly backup
+  still has them if that turns out to be a mistake.
+
+Two thresholds, in GB of free space:
+
+```env
+DISK_WARN_FREE_GB=20    # below this, a drive icon appears in the header
+DISK_RESERVE_GB=5       # below this, new writes are refused
+```
+
+Below the reserve, uploads, URL imports, AI generations and clip extractions are refused
+with "the server's disk is nearly full". They are checked when queued and again when the
+job starts. A generation is checked before it is sent to fal, so nothing is billed for an
+output that could not be saved; one already submitted still saves. Clips, tags,
+transcripts and previews are not refused, since they write next to nothing. The
+thresholds are fixed sizes rather than percentages because what fills the disk is single
+large files: a 90-minute import is 1–2 GB whatever size the disk is.
+
 ## Transcription
 
 Nothing to configure at deploy time. Each user adds their own Deepgram key at
@@ -154,6 +193,9 @@ the AI generation model catalogue (Settings → Generation); everyone else uses
 stands. Left empty, nobody can edit it and the catalogue the migration seeded is what
 everyone gets — which works, until fal retires one of those endpoints.
 
+An admin also sees the server's disk under **Settings → Storage**, and can clear stray
+files there. Everyone else sees only their own library's share.
+
 ## AI generation
 
 Per user, like transcription: each person adds their own fal.ai key at **Settings →
diff --git a/frontend/src/api/storage.ts b/frontend/src/api/storage.ts
new file mode 100644
index 0000000..c93e887
--- /dev/null
+++ b/frontend/src/api/storage.ts
@@ -0,0 +1,106 @@
+import client from '@/api/client'
+
+/**
+ * Disk space: what the library takes up, what the server has left, and the stray files
+ * nothing refers to.
+ *
+ * Everyone gets their own library's share. The server half — the disk, every user's
+ * total, the sweep — is for administrators, and comes back null for anyone else.
+ */
+
+interface DataResponse<T> {
+  data: T
+}
+
+/** `ok`, then `low` (the header warns), then `critical` (new writes are refused). */
+export type StorageLevel = 'ok' | 'low' | 'critical'
+
+export type VolumeRole = 'media' | 'database' | 'working'
+
+export interface FileGroup {
+  files: number
+  bytes: number
+}
+
+export interface TypeUsage {
+  asset_type: string
+  files: number
+  bytes: number
+}
+
+export interface LargestAsset {
+  id: string
+  name: string
+  asset_type: string
+  size_bytes: number
+}
+
+export interface LibraryUsage {
+  total_bytes: number
+  files: number
+  by_type: TypeUsage[]
+  thumbnails: FileGroup
+  largest: LargestAsset[]
+}
+
+export interface Volume {
+  roles: VolumeRole[]
+  total_bytes: number
+  /**
+   * `used + free` is usually short of `total`: ext4 keeps ~5% back for root. That gap is
+   * neither used by anything here nor free to write, and is shown as "reserved".
+   */
+  used_bytes: number
+  free_bytes: number
+  level: StorageLevel
+  /** False for a volume holding only temp space, whose level does not count. */
+  guarded: boolean
+}
+
+export interface ServerUsage {
+  volumes: Volume[]
+  /** Every file under the media root: all users, thumbnails and strays included. */
+  media: FileGroup
+  /** null when the database is not a local SQLite file. */
+  database_bytes: number | null
+  stray: FileGroup
+  warn_free_bytes: number
+  reserve_bytes: number
+}
+
+export interface StorageSummary {
+  /** Everyone's, unlike the numbers behind it. */
+  level: StorageLevel
+  library: LibraryUsage
+  server: ServerUsage | null
+}
+
+export interface StorageStatus {
+  level: StorageLevel
+  /** Admins only; null for everyone else. */
+  free_bytes: number | null
+  total_bytes: number | null
+}
+
+export interface CleanupResult {
+  removed: FileGroup
+  skipped: number
+}
+
+export const storageApi = {
+  summary(): Promise<StorageSummary> {
+    return client.get<DataResponse<StorageSummary>>('/storage').then((r) => r.data.data)
+  },
+
+  status(): Promise<StorageStatus> {
+    return client
+      .get<DataResponse<StorageStatus>>('/storage/status')
+      .then((r) => r.data.data)
+  },
+
+  cleanup(): Promise<CleanupResult> {
+    return client
+      .post<DataResponse<CleanupResult>>('/storage/cleanup')
+      .then((r) => r.data.data)
+  },
+}
diff --git a/frontend/src/components/AppShell.test.tsx b/frontend/src/components/AppShell.test.tsx
index 7ceb465..d4134b5 100644
--- a/frontend/src/components/AppShell.test.tsx
+++ b/frontend/src/components/AppShell.test.tsx
@@ -3,6 +3,7 @@ import userEvent from '@testing-library/user-event'
 import { MemoryRouter } from 'react-router-dom'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import AppShell from '@/components/AppShell'
+import { storageApi } from '@/api/storage'
 import { useActivityStore } from '@/stores/activity'
 import { useAuthStore } from '@/stores/auth'
 
@@ -10,6 +11,12 @@ beforeEach(() => {
   useAuthStore.getState().reset()
   // The shell mounts ActivityIndicator, which starts a poll.
   vi.spyOn(useActivityStore.getState(), 'start').mockImplementation(() => {})
+  // And StorageWarning, which checks the disk.
+  vi.spyOn(storageApi, 'status').mockResolvedValue({
+    level: 'ok',
+    free_bytes: null,
+    total_bytes: null,
+  })
 })
 
 afterEach(() => {
diff --git a/frontend/src/components/AppShell.tsx b/frontend/src/components/AppShell.tsx
index e4acfaa..dc6a069 100644
--- a/frontend/src/components/AppShell.tsx
+++ b/frontend/src/components/AppShell.tsx
@@ -2,6 +2,7 @@ import type { ReactNode } from 'react'
 import { LogOut, Moon, Search, Settings, Sun } from 'lucide-react'
 import { Link } from 'react-router-dom'
 import ActivityIndicator from '@/components/ActivityIndicator'
+import StorageWarning from '@/components/StorageWarning'
 import { useAuthStore } from '@/stores/auth'
 import { useThemeStore } from '@/stores/theme'
 
@@ -52,6 +53,7 @@ export default function AppShell({ children }: Props) {
             <Link to="/search" className="btn btn-ghost p-2" aria-label="Search">
               <Search className="h-4 w-4" />
             </Link>
+            <StorageWarning />
             <ActivityIndicator />
             <Link to="/settings" className="btn btn-ghost p-2" aria-label="Settings">
               <Settings className="h-4 w-4" />
diff --git a/frontend/src/components/StoragePanel.test.tsx b/frontend/src/components/StoragePanel.test.tsx
new file mode 100644
index 0000000..d241350
--- /dev/null
+++ b/frontend/src/components/StoragePanel.test.tsx
@@ -0,0 +1,248 @@
+import { render, screen, waitFor, within } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { MemoryRouter } from 'react-router-dom'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import StoragePanel from '@/components/StoragePanel'
+import {
+  storageApi,
+  type ServerUsage,
+  type StorageSummary,
+  type Volume,
+} from '@/api/storage'
+
+const GB = 1024 ** 3
+
+function volume(overrides: Partial<Volume> = {}): Volume {
+  return {
+    roles: ['media', 'database', 'working'],
+    total_bytes: 2048 * GB,
+    used_bytes: 1648 * GB,
+    free_bytes: 400 * GB,
+    level: 'ok',
+    guarded: true,
+    ...overrides,
+  }
+}
+
+function server(overrides: Partial<ServerUsage> = {}): ServerUsage {
+  return {
+    volumes: [volume()],
+    media: { files: 900, bytes: 1000 * GB },
+    database_bytes: 2 * GB,
+    stray: { files: 0, bytes: 0 },
+    warn_free_bytes: 20 * GB,
+    reserve_bytes: 5 * GB,
+    ...overrides,
+  }
+}
+
+function summary(overrides: Partial<StorageSummary> = {}): StorageSummary {
+  return {
+    level: 'ok',
+    library: {
+      total_bytes: 130 * GB,
+      files: 40,
+      by_type: [
+        { asset_type: 'video', files: 34, bytes: 120 * GB },
+        { asset_type: 'image', files: 6, bytes: 9 * GB },
+      ],
+      thumbnails: { files: 40, bytes: 1 * GB },
+      largest: [
+        { id: 'a1', name: 'Giordano interview', asset_type: 'video', size_bytes: 8 * GB },
+        { id: 'a2', name: 'Harbour at dusk', asset_type: 'image', size_bytes: 2 * GB },
+      ],
+    },
+    server: null,
+    ...overrides,
+  }
+}
+
+function renderPanel() {
+  return render(
+    <MemoryRouter>
+      <StoragePanel />
+    </MemoryRouter>
+  )
+}
+
+beforeEach(() => {
+  vi.spyOn(storageApi, 'summary').mockResolvedValue(summary())
+})
+
+afterEach(() => {
+  vi.restoreAllMocks()
+})
+
+describe('StoragePanel', () => {
+  it('breaks the library down by type and links its largest files', async () => {
+    renderPanel()
+
+    expect(await screen.findByText('130.0 GB')).toBeInTheDocument()
+    expect(screen.getByText('Video')).toBeInTheDocument()
+    expect(screen.getByText('34 files · 120.0 GB')).toBeInTheDocument()
+    expect(screen.getByText('Previews')).toBeInTheDocument()
+
+    // The point of the list is to go and delete something, so each is a way there.
+    const largest = screen.getByRole('link', { name: 'Giordano interview' })
+    expect(largest).toHaveAttribute('href', '/a/a1')
+    expect(screen.getByRole('link', { name: 'Harbour at dusk' })).toHaveAttribute(
+      'href',
+      '/a/a2'
+    )
+  })
+
+  it('shows a non-admin no server numbers and no sweep', async () => {
+    renderPanel()
+
+    await screen.findByText('130.0 GB')
+    expect(screen.queryByText(/free of/)).toBeNull()
+    expect(screen.queryByRole('img')).toBeNull()
+    expect(screen.queryByRole('button', { name: /remove them/i })).toBeNull()
+  })
+
+  it('shows an admin the disk, split into what is GAM’s and what is not', async () => {
+    vi.spyOn(storageApi, 'summary').mockResolvedValue(summary({ server: server() }))
+    renderPanel()
+
+    expect(await screen.findByText('Server disk')).toBeInTheDocument()
+    expect(screen.getByText(/400\.0 GB free of 2\.0 TB/)).toBeInTheDocument()
+    expect(
+      screen.getByText('Holds media, the database and temporary files')
+    ).toBeInTheDocument()
+
+    const legend = screen.getByRole('list', { name: /what is on the server disk/i })
+    expect(within(legend).getByText('GAM media')).toBeInTheDocument()
+    expect(within(legend).getByText('1000.0 GB')).toBeInTheDocument()
+    expect(within(legend).getByText('GAM database')).toBeInTheDocument()
+    // 1648 used, of which 1002 is GAM's.
+    expect(within(legend).getByText('Everything else')).toBeInTheDocument()
+    expect(within(legend).getByText('646.0 GB')).toBeInTheDocument()
+    // used + free == total here, so there is no reserve to show.
+    expect(within(legend).queryByText(/reserved/i)).toBeNull()
+  })
+
+  it('names the filesystem reserve rather than calling it free', async () => {
+    vi.spyOn(storageApi, 'summary').mockResolvedValue(
+      summary({ server: server({ volumes: [volume({ used_bytes: 1548 * GB })] }) })
+    )
+    renderPanel()
+
+    const legend = await screen.findByRole('list', {
+      name: /what is on the server disk/i,
+    })
+    expect(within(legend).getByText('Reserved by the system')).toBeInTheDocument()
+    expect(within(legend).getByText('100.0 GB')).toBeInTheDocument()
+  })
+
+  it('explains a separate temp disk that does not count', async () => {
+    vi.spyOn(storageApi, 'summary').mockResolvedValue(
+      summary({
+        server: server({
+          volumes: [
+            volume({ roles: ['media', 'database'] }),
+            volume({
+              roles: ['working'],
+              total_bytes: 8 * GB,
+              used_bytes: 7 * GB,
+              free_bytes: 1 * GB,
+              level: 'critical',
+              guarded: false,
+            }),
+          ],
+        }),
+      })
+    )
+    renderPanel()
+
+    expect(await screen.findByText('Media disk')).toBeInTheDocument()
+    expect(screen.getByText('Working space')).toBeInTheDocument()
+    expect(screen.getByText(/does not count toward the warning/)).toBeInTheDocument()
+    expect(screen.getByText(/a large import may not fit/)).toBeInTheDocument()
+  })
+
+  it('tells a non-admin why uploads stopped without the numbers', async () => {
+    vi.spyOn(storageApi, 'summary').mockResolvedValue(summary({ level: 'critical' }))
+    renderPanel()
+
+    expect(await screen.findByText(/nearly full/)).toHaveTextContent('a safe margin')
+  })
+
+  it('gives an admin the thresholds', async () => {
+    vi.spyOn(storageApi, 'summary').mockResolvedValue(
+      summary({ level: 'low', server: server() })
+    )
+    renderPanel()
+
+    expect(await screen.findByText(/Running low/)).toHaveTextContent('under 20.0 GB free')
+  })
+
+  it('says nothing about the level while there is room', async () => {
+    renderPanel()
+
+    await screen.findByText('130.0 GB')
+    expect(screen.queryByText(/running low|nearly full/i)).toBeNull()
+  })
+
+  it('removes stray files only after asking', async () => {
+    const strays = server({ stray: { files: 3, bytes: 2 * GB } })
+    vi.spyOn(storageApi, 'summary').mockResolvedValue(summary({ server: strays }))
+    const cleanup = vi
+      .spyOn(storageApi, 'cleanup')
+      .mockResolvedValue({ removed: { files: 3, bytes: 2 * GB }, skipped: 0 })
+    const confirm = vi.spyOn(window, 'confirm').mockReturnValue(false)
+    renderPanel()
+
+    const button = await screen.findByRole('button', { name: /remove them/i })
+    expect(
+      screen.getByText(/3 files \(2\.0 GB\) on disk that no asset refers to/)
+    ).toBeInTheDocument()
+
+    await userEvent.click(button)
+    expect(confirm).toHaveBeenCalled()
+    expect(cleanup).not.toHaveBeenCalled()
+
+    confirm.mockReturnValue(true)
+    vi.mocked(storageApi.summary).mockResolvedValue(summary({ server: server() }))
+    await userEvent.click(button)
+
+    expect(cleanup).toHaveBeenCalledTimes(1)
+    expect(await screen.findByText('Removed 3 files (2.0 GB).')).toBeInTheDocument()
+    // Reloaded afterwards, so the count is the disk's and not a subtraction.
+    expect(await screen.findByText('No stray files.')).toBeInTheDocument()
+  })
+
+  it('says when there is nothing in the library', async () => {
+    vi.spyOn(storageApi, 'summary').mockResolvedValue(
+      summary({
+        library: {
+          total_bytes: 0,
+          files: 0,
+          by_type: [],
+          thumbnails: { files: 0, bytes: 0 },
+          largest: [],
+        },
+      })
+    )
+    renderPanel()
+
+    expect(await screen.findByText('Nothing stored yet.')).toBeInTheDocument()
+  })
+
+  it('reloads on demand', async () => {
+    renderPanel()
+    await screen.findByText('130.0 GB')
+
+    await userEvent.click(screen.getByRole('button', { name: /refresh storage/i }))
+
+    await waitFor(() => expect(storageApi.summary).toHaveBeenCalledTimes(2))
+  })
+
+  it('shows the error when it cannot load', async () => {
+    vi.spyOn(storageApi, 'summary').mockRejectedValue(
+      new Error('Could not reach the server')
+    )
+    renderPanel()
+
+    expect(await screen.findByText('Could not reach the server')).toBeInTheDocument()
+  })
+})
diff --git a/frontend/src/components/StoragePanel.tsx b/frontend/src/components/StoragePanel.tsx
new file mode 100644
index 0000000..3378507
--- /dev/null
+++ b/frontend/src/components/StoragePanel.tsx
@@ -0,0 +1,451 @@
+import { useCallback, useEffect, useRef, useState, type CSSProperties } from 'react'
+import { AlertTriangle, Check, HardDrive, RefreshCw, Trash2 } from 'lucide-react'
+import { Link, useLocation } from 'react-router-dom'
+import { apiErrorMessage } from '@/api/client'
+import {
+  storageApi,
+  type ServerUsage,
+  type StorageLevel,
+  type StorageSummary,
+  type Volume,
+} from '@/api/storage'
+import { formatBytes } from '@/utils/format'
+
+/**
+ * What the disk holds and what is left of it.
+ *
+ * The library half answers "what could I delete", which is why the largest files are
+ * links. The disk half is an administrator's: `server` is null for everyone else, who
+ * still gets the level — it is what explains a refused upload.
+ */
+
+const TYPE_LABELS: Record<string, string> = {
+  video: 'Video',
+  image: 'Images',
+  audio: 'Audio',
+  document: 'Documents',
+}
+
+// The first two slots of the validated categorical palette (the dataviz skill's
+// reference instance), in its order: adjacent in the bar, so they are the pair it
+// checked for colour-blind separation. Each mode has its own step, not a flip.
+const MEDIA_FILL = 'bg-[#2a78d6] dark:bg-[#3987e5]'
+const DATABASE_FILL = 'bg-[#eb6834] dark:bg-[#d95926]'
+// Neutral rather than a third hue: what is not GAM's is context, not a series.
+const OTHER_FILL = 'bg-gray-400 dark:bg-gray-500'
+const FREE_FILL = 'bg-gray-100 dark:bg-gray-700'
+// Hatched over the free track. "Reserved" is neither used nor writable, and a texture
+// says so without a second gray that would read as more of "other".
+const RESERVED_FILL = `${FREE_FILL} text-gray-400 dark:text-gray-500`
+const RESERVED_STYLE: CSSProperties = {
+  backgroundImage:
+    'repeating-linear-gradient(135deg, currentColor 0 1.5px, transparent 1.5px 5px)',
+}
+
+// Below this share of the disk a segment is left out of the bar (it stays in the
+// legend). A database of a few megabytes on a terabyte disk is a fraction of a pixel,
+// and drawing it would leave only its two gaps — a mark that reads as something.
+const MIN_SHARE = 0.002
+
+interface Segment {
+  key: string
+  label: string
+  bytes: number
+  className: string
+  style?: CSSProperties
+}
+
+function plural(count: number, noun: string): string {
+  return `${count.toLocaleString()} ${noun}${count === 1 ? '' : 's'}`
+}
+
+function volumeTitle(volume: Volume, only: boolean): string {
+  if (only) return 'Server disk'
+  if (volume.roles.includes('media')) return 'Media disk'
+  if (volume.roles.includes('database')) return 'Database disk'
+  return 'Working space'
+}
+
+const ROLE_NAMES: Record<string, string> = {
+  media: 'media',
+  database: 'the database',
+  working: 'temporary files',
+}
+
+function holds(volume: Volume): string {
+  const names = volume.roles.map((role) => ROLE_NAMES[role] ?? role)
+  if (names.length === 1) return `Holds ${names[0]}`
+  return `Holds ${names.slice(0, -1).join(', ')} and ${names[names.length - 1]}`
+}
+
+function segmentsFor(volume: Volume, server: ServerUsage): Segment[] {
+  const media = volume.roles.includes('media') ? server.media.bytes : 0
+  const database = volume.roles.includes('database') ? (server.database_bytes ?? 0) : 0
+  const ours = media + database
+  const reserved = Math.max(volume.total_bytes - volume.used_bytes - volume.free_bytes, 0)
+
+  return [
+    { key: 'media', label: 'GAM media', bytes: media, className: MEDIA_FILL },
+    { key: 'database', label: 'GAM database', bytes: database, className: DATABASE_FILL },
+    {
+      key: 'other',
+      // On a volume holding nothing of GAM's own, everything used is "in use" — calling
+      // it "other" would imply there were something to compare it with.
+      label: ours > 0 ? 'Everything else' : 'In use',
+      bytes: Math.max(volume.used_bytes - ours, 0),
+      className: OTHER_FILL,
+    },
+    {
+      key: 'reserved',
+      label: 'Reserved by the system',
+      bytes: reserved,
+      className: RESERVED_FILL,
+      style: RESERVED_STYLE,
+    },
+    { key: 'free', label: 'Free', bytes: volume.free_bytes, className: FREE_FILL },
+  ].filter((segment) => segment.bytes > 0 || segment.key === 'free')
+}
+
+function DiskBar({ volume, segments }: { volume: Volume; segments: Segment[] }) {
+  const total = volume.total_bytes || 1
+  const drawn = segments.filter((s) => s.bytes / total >= MIN_SHARE)
+
+  return (
+    // flex-grow by bytes rather than a percentage width: the 2px gaps come out of the
+    // space first and the rest is shared in proportion, so the bar never overflows.
+    <div
+      className="flex h-3 w-full gap-[2px] overflow-hidden rounded"
+      role="img"
+      aria-label={segments.map((s) => `${s.label} ${formatBytes(s.bytes)}`).join(', ')}
+    >
+      {drawn.map((segment) => (
+        <div
+          key={segment.key}
+          className={segment.className}
+          style={{ flexGrow: segment.bytes, flexBasis: 0, ...segment.style }}
+          title={`${segment.label}: ${formatBytes(segment.bytes)}`}
+        />
+      ))}
+    </div>
+  )
+}
+
+function LevelNotice({
+  level,
+  server,
+}: {
+  level: StorageLevel
+  server: ServerUsage | null
+}) {
+  if (level === 'ok') return null
+
+  const critical = level === 'critical'
+  // An admin is given the threshold; everybody else the consequence, without the
+  // numbers they are not shown anywhere else either.
+  const message = critical
+    ? `The disk is nearly full. Uploads, imports and generations are paused until there is more than ${server ? formatBytes(server.reserve_bytes) : 'a safe margin'} free.`
+    : server
+      ? `Running low — under ${formatBytes(server.warn_free_bytes)} free.`
+      : 'The server is running low on disk space.'
+
+  return (
+    <p
+      className={
+        critical
+          ? 'flex items-start gap-1.5 rounded-md border border-red-300 bg-red-50 px-3 py-2 text-xs text-red-800 dark:border-red-800 dark:bg-red-950/30 dark:text-red-300'
+          : 'flex items-start gap-1.5 rounded-md border border-amber-300 bg-amber-50 px-3 py-2 text-xs text-amber-800 dark:border-amber-800 dark:bg-amber-950/30 dark:text-amber-300'
+      }
+    >
+      <AlertTriangle className="mt-px h-3.5 w-3.5 shrink-0" />
+      {message}
+    </p>
+  )
+}
+
+function VolumeBlock({
+  volume,
+  server,
+  only,
+}: {
+  volume: Volume
+  server: ServerUsage
+  only: boolean
+}) {
+  const segments = segmentsFor(volume, server)
+  const share = volume.total_bytes
+    ? Math.round((volume.free_bytes / volume.total_bytes) * 100)
+    : 0
+
+  return (
+    <div className="space-y-2">
+      <div className="flex items-baseline justify-between gap-2">
+        <div>
+          <h3 className="text-xs font-semibold text-gray-900 dark:text-gray-100">
+            {volumeTitle(volume, only)}
+          </h3>
+          <p className="text-xs text-gray-500 dark:text-gray-400">{holds(volume)}</p>
+        </div>
+        <p className="text-right text-xs text-gray-900 dark:text-gray-100">
+          {formatBytes(volume.free_bytes)} free of {formatBytes(volume.total_bytes)}
+          <span className="text-gray-500 dark:text-gray-400"> ({share}%)</span>
+        </p>
+      </div>
+
+      <DiskBar volume={volume} segments={segments} />
+
+      <ul
+        className="flex flex-wrap gap-x-4 gap-y-1 text-xs"
+        aria-label={`What is on the ${volumeTitle(volume, only).toLowerCase()}`}
+      >
+        {segments.map((segment) => (
+          <li key={segment.key} className="flex items-center gap-1.5">
+            <span
+              className={`inline-block h-2.5 w-2.5 rounded-sm ${segment.className}`}
+              style={segment.style}
+              aria-hidden="true"
+            />
+            <span className="text-gray-500 dark:text-gray-400">{segment.label}</span>
+            <span className="text-gray-900 dark:text-gray-100">
+              {formatBytes(segment.bytes)}
+            </span>
+          </li>
+        ))}
+      </ul>
+
+      {!volume.guarded && (
+        <p className="text-xs text-gray-500 dark:text-gray-400">
+          Uploads and imports pass through here before they are stored. Nothing is kept
+          here, so this disk does not count toward the warning.
+          {volume.level !== 'ok' &&
+            ' It is small enough that a large import may not fit.'}
+        </p>
+      )}
+    </div>
+  )
+}
+
+function StrayFiles({
+  server,
+  onCleaned,
+}: {
+  server: ServerUsage
+  onCleaned: () => void
+}) {
+  const [working, setWorking] = useState(false)
+  const [result, setResult] = useState<string | null>(null)
+  const [error, setError] = useState<string | null>(null)
+  const { files, bytes } = server.stray
+
+  const clean = async () => {
+    if (
+      !confirm(
+        `Delete ${plural(files, 'stray file')} (${formatBytes(bytes)})? Nothing in the library uses ${files === 1 ? 'it' : 'them'}.`
+      )
+    ) {
+      return
+    }
+    setWorking(true)
+    setError(null)
+    try {
+      const done = await storageApi.cleanup()
+      setResult(
+        `Removed ${plural(done.removed.files, 'file')} (${formatBytes(done.removed.bytes)})` +
+          (done.skipped ? `; ${done.skipped} could not be removed.` : '.')
+      )
+      onCleaned()
+    } catch (err) {
+      setError(apiErrorMessage(err, 'Could not remove them'))
+    } finally {
+      setWorking(false)
+    }
+  }
+
+  return (
+    <div className="space-y-2 border-t border-gray-100 pt-3 dark:border-gray-800">
+      {files > 0 ? (
+        <div className="flex items-center justify-between gap-3">
+          <p className="text-xs text-gray-600 dark:text-gray-400">
+            {plural(files, 'file')} ({formatBytes(bytes)}) on disk that no asset refers to
+            — left by interrupted uploads or failed jobs.
+          </p>
+          <button
+            type="button"
+            className="btn btn-secondary shrink-0 text-xs"
+            disabled={working}
+            onClick={() => void clean()}
+          >
+            <Trash2 className="h-3.5 w-3.5" />
+            Remove them
+          </button>
+        </div>
+      ) : (
+        <p className="flex items-center gap-1.5 text-xs text-gray-500 dark:text-gray-400">
+          <Check className="h-3.5 w-3.5" />
+          No stray files.
+        </p>
+      )}
+      {result && <p className="text-xs text-green-700 dark:text-green-400">{result}</p>}
+      {error && <p className="text-xs text-red-700 dark:text-red-400">{error}</p>}
+    </div>
+  )
+}
+
+export default function StoragePanel() {
+  const [summary, setSummary] = useState<StorageSummary | null>(null)
+  const [loading, setLoading] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+  // A refresh can overtake the load before it; only the latest answer is shown.
+  const latest = useRef(0)
+  const section = useRef<HTMLElement>(null)
+  const { hash } = useLocation()
+
+  const load = useCallback(() => {
+    const request = ++latest.current
+    setLoading(true)
+    storageApi
+      .summary()
+      .then((next) => {
+        if (request !== latest.current) return
+        setSummary(next)
+        setError(null)
+      })
+      .catch((err) => {
+        if (request !== latest.current) return
+        setError(apiErrorMessage(err, 'Could not load storage'))
+      })
+      .finally(() => {
+        if (request === latest.current) setLoading(false)
+      })
+  }, [])
+
+  useEffect(() => {
+    load()
+  }, [load])
+
+  // The header's warning links here. Scrolled once there is something to scroll to,
+  // since the panels above it load at their own pace and move it as they do.
+  const loaded = summary !== null
+  useEffect(() => {
+    if (loaded && hash === '#storage')
+      section.current?.scrollIntoView?.({ block: 'start' })
+  }, [loaded, hash])
+
+  const library = summary?.library
+  const server = summary?.server ?? null
+
+  return (
+    <section id="storage" ref={section} className="card scroll-mt-4 space-y-4 p-5">
+      <header className="flex items-center gap-2">
+        <HardDrive className="h-4 w-4 text-gray-500" />
+        <h2 className="text-sm font-semibold text-gray-900 dark:text-gray-100">
+          Storage
+        </h2>
+        <button
+          type="button"
+          className="btn btn-ghost ml-auto p-1.5"
+          onClick={load}
+          disabled={loading}
+          aria-label="Refresh storage"
+          title="Refresh"
+        >
+          <RefreshCw className={`h-3.5 w-3.5 ${loading ? 'animate-spin' : ''}`} />
+        </button>
+      </header>
+
+      {error && (
+        <p className="rounded-md border border-red-300 bg-red-50 px-3 py-2 text-xs text-red-800 dark:border-red-800 dark:bg-red-950/30 dark:text-red-300">
+          {error}
+        </p>
+      )}
+
+      {summary && <LevelNotice level={summary.level} server={server} />}
+
+      {server &&
+        server.volumes.map((volume) => (
+          <VolumeBlock
+            key={volume.roles.join('+')}
+            volume={volume}
+            server={server}
+            only={server.volumes.length === 1}
+          />
+        ))}
+
+      {library && (
+        <div
+          className={
+            server
+              ? 'space-y-3 border-t border-gray-100 pt-3 dark:border-gray-800'
+              : 'space-y-3'
+          }
+        >
+          <div>
+            <h3 className="text-xs font-semibold text-gray-900 dark:text-gray-100">
+              Your library
+            </h3>
+            <p className="mt-1 text-2xl font-semibold text-gray-900 dark:text-gray-100">
+              {formatBytes(library.total_bytes)}
+            </p>
+          </div>
+
+          {library.files === 0 ? (
+            <p className="text-xs text-gray-600 dark:text-gray-400">
+              Nothing stored yet.
+            </p>
+          ) : (
+            <dl className="space-y-1 text-xs">
+              {library.by_type.map((row) => (
+                <div key={row.asset_type} className="flex justify-between">
+                  <dt className="text-gray-500 dark:text-gray-400">
+                    {TYPE_LABELS[row.asset_type] ?? row.asset_type}
+                  </dt>
+                  <dd className="text-gray-900 dark:text-gray-100">
+                    {plural(row.files, 'file')} · {formatBytes(row.bytes)}
+                  </dd>
+                </div>
+              ))}
+              {library.thumbnails.files > 0 && (
+                <div className="flex justify-between">
+                  <dt className="text-gray-500 dark:text-gray-400">Previews</dt>
+                  <dd className="text-gray-900 dark:text-gray-100">
+                    {formatBytes(library.thumbnails.bytes)}
+                  </dd>
+                </div>
+              )}
+            </dl>
+          )}
+
+          {library.largest.length > 0 && (
+            <div>
+              <h3 className="mb-1 text-xs font-semibold text-gray-900 dark:text-gray-100">
+                Largest files
+              </h3>
+              <ol className="space-y-1 text-xs">
+                {library.largest.map((asset) => (
+                  <li
+                    key={asset.id}
+                    className="flex items-baseline justify-between gap-3"
+                  >
+                    <Link
+                      to={`/a/${asset.id}`}
+                      className="min-w-0 truncate text-blue-600 underline-offset-2 hover:underline dark:text-blue-400"
+                    >
+                      {asset.name}
+                    </Link>
+                    <span className="shrink-0 text-gray-500 dark:text-gray-400">
+                      {TYPE_LABELS[asset.asset_type] ?? asset.asset_type} ·{' '}
+                      <span className="text-gray-900 dark:text-gray-100">
+                        {formatBytes(asset.size_bytes)}
+                      </span>
+                    </span>
+                  </li>
+                ))}
+              </ol>
+            </div>
+          )}
+        </div>
+      )}
+
+      {server && <StrayFiles server={server} onCleaned={load} />}
+    </section>
+  )
+}
diff --git a/frontend/src/components/StorageWarning.test.tsx b/frontend/src/components/StorageWarning.test.tsx
new file mode 100644
index 0000000..ac095b6
--- /dev/null
+++ b/frontend/src/components/StorageWarning.test.tsx
@@ -0,0 +1,54 @@
+import { render, screen } from '@testing-library/react'
+import { MemoryRouter } from 'react-router-dom'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import StorageWarning from '@/components/StorageWarning'
+import { storageApi, type StorageStatus } from '@/api/storage'
+
+const GB = 1024 ** 3
+
+function renderWarning(status: StorageStatus | Error) {
+  if (status instanceof Error) vi.spyOn(storageApi, 'status').mockRejectedValue(status)
+  else vi.spyOn(storageApi, 'status').mockResolvedValue(status)
+  return render(
+    <MemoryRouter>
+      <StorageWarning />
+    </MemoryRouter>
+  )
+}
+
+afterEach(() => {
+  vi.restoreAllMocks()
+})
+
+describe('StorageWarning', () => {
+  it('shows nothing while there is room', async () => {
+    renderWarning({ level: 'ok', free_bytes: 400 * GB, total_bytes: 2048 * GB })
+
+    await vi.waitFor(() => expect(storageApi.status).toHaveBeenCalled())
+    expect(screen.queryByRole('link')).toBeNull()
+  })
+
+  it('warns when space is low and links to the panel', async () => {
+    renderWarning({ level: 'low', free_bytes: null, total_bytes: null })
+
+    const link = await screen.findByRole('link', { name: 'Disk space low' })
+    expect(link).toHaveAttribute('href', '/settings#storage')
+    expect(link.className).toContain('text-amber-600')
+  })
+
+  it('tells an admin how much is left when it is nearly full', async () => {
+    renderWarning({ level: 'critical', free_bytes: 3 * GB, total_bytes: 2048 * GB })
+
+    const link = await screen.findByRole('link', {
+      name: /disk nearly full — 3\.0 GB free/i,
+    })
+    expect(link.className).toContain('text-red-600')
+  })
+
+  it('shows nothing when the check fails', async () => {
+    renderWarning(new Error('Could not reach the server'))
+
+    await vi.waitFor(() => expect(storageApi.status).toHaveBeenCalled())
+    expect(screen.queryByRole('link')).toBeNull()
+  })
+})
diff --git a/frontend/src/components/StorageWarning.tsx b/frontend/src/components/StorageWarning.tsx
new file mode 100644
index 0000000..c133766
--- /dev/null
+++ b/frontend/src/components/StorageWarning.tsx
@@ -0,0 +1,67 @@
+import { useEffect, useState } from 'react'
+import { HardDrive } from 'lucide-react'
+import { Link } from 'react-router-dom'
+import { storageApi, type StorageStatus } from '@/api/storage'
+import { formatBytes } from '@/utils/format'
+
+/**
+ * A drive icon in the header, only while the disk is running out.
+ *
+ * Nothing at all while there is room: an always-on gauge is one more thing in the
+ * header to learn to ignore, and a warning people have learned to ignore is no warning.
+ * The endpoint is a `statvfs` and nothing more, so polling it costs nothing.
+ */
+
+const POLL_MS = 5 * 60 * 1000
+
+function describe(status: StorageStatus): string {
+  const free =
+    status.free_bytes !== null ? ` — ${formatBytes(status.free_bytes)} free` : ''
+  return status.level === 'critical'
+    ? `Disk nearly full${free}. New uploads are paused.`
+    : `Disk space low${free}`
+}
+
+export default function StorageWarning() {
+  const [status, setStatus] = useState<StorageStatus | null>(null)
+
+  useEffect(() => {
+    let live = true
+    const check = () => {
+      storageApi
+        .status()
+        .then((next) => {
+          if (live) setStatus(next)
+        })
+        // A failed check shows nothing rather than a warning about a disk it could
+        // not read; the next poll tries again.
+        .catch(() => {
+          if (live) setStatus(null)
+        })
+    }
+    check()
+    const timer = setInterval(check, POLL_MS)
+    return () => {
+      live = false
+      clearInterval(timer)
+    }
+  }, [])
+
+  if (!status || status.level === 'ok') return null
+
+  const label = describe(status)
+  return (
+    <Link
+      to="/settings#storage"
+      className={`btn btn-ghost p-2 ${
+        status.level === 'critical'
+          ? 'text-red-600 dark:text-red-400'
+          : 'text-amber-600 dark:text-amber-400'
+      }`}
+      aria-label={label}
+      title={label}
+    >
+      <HardDrive className="h-4 w-4" />
+    </Link>
+  )
+}
diff --git a/frontend/src/views/SettingsView.test.tsx b/frontend/src/views/SettingsView.test.tsx
index 8b3480e..dbe7602 100644
--- a/frontend/src/views/SettingsView.test.tsx
+++ b/frontend/src/views/SettingsView.test.tsx
@@ -16,6 +16,7 @@ import {
 } from '@/api/settings'
 import { providersApi } from '@/api/providers'
 import { usageApi } from '@/api/usage'
+import { storageApi } from '@/api/storage'
 import { makeGenerationModel } from '@/test-fixtures'
 
 function embedding(overrides: Partial<EmbeddingSettings> = {}): EmbeddingSettings {
@@ -70,6 +71,18 @@ beforeEach(() => {
   // The view mounts the provider panel too, which loads on mount. Left unmocked it
   // reaches the real axios client and every test here logs a network failure.
   vi.spyOn(providersApi, 'list').mockResolvedValue([])
+  // And the storage panel.
+  vi.spyOn(storageApi, 'summary').mockResolvedValue({
+    level: 'ok',
+    library: {
+      total_bytes: 0,
+      files: 0,
+      by_type: [],
+      thumbnails: { files: 0, bytes: 0 },
+      largest: [],
+    },
+    server: null,
+  })
   // The view mounts the usage panel too, which loads on mount.
   vi.spyOn(usageApi, 'summary').mockResolvedValue({
     totals: {
diff --git a/frontend/src/views/SettingsView.tsx b/frontend/src/views/SettingsView.tsx
index 48d36cc..181ca51 100644
--- a/frontend/src/views/SettingsView.tsx
+++ b/frontend/src/views/SettingsView.tsx
@@ -12,6 +12,7 @@ import { embeddingsApi, type EmbeddingCoverage } from '@/api/embeddings'
 import { isActive, useActivityStore } from '@/stores/activity'
 import GenerationSettingsPanel from '@/components/GenerationSettings'
 import ProviderPanel from '@/components/ProviderPanel'
+import StoragePanel from '@/components/StoragePanel'
 import TagPanel from '@/components/TagPanel'
 import UsagePanel from '@/components/UsagePanel'
 import { useSavedFlash } from '@/utils/useSavedFlash'
@@ -509,6 +510,7 @@ export default function SettingsView() {
 
       <ProviderPanel />
       <UsagePanel />
+      <StoragePanel />
       <EmbeddingPanel />
       <SpeechPanel />
       <GenerationSettingsPanel />