release: v3.1.0-beta Image variants

.dockerignore

@@ -0,0 +1,17 @@
+.git
+.gitignore
+.dockerignore
+.env
+docker.env
+tmp/
+bin/
+data/
+node_modules
+web/node_modules
+internal/infrastructure/assets/dist
+.task/
+.claude/
+.idea
+.vscode
+*.db
+*.exe

.env.example

@@ -15,3 +15,28 @@ AUTH_RATE_LIMIT_MAX_ATTEMPTS=5
 AUTH_RATE_LIMIT_WINDOW_SECONDS=60
 TRUSTED_PROXIES=
 UPDATE_FEED_URL=https://git.floriansylvain.fr
+RENEWCMS_CONTAINER=false
+IMAGE_VARIANT_MAX_SOURCE_BYTES=10485760
+IMAGE_VARIANT_MAX_SOURCE_PIXELS=50000000
+IMAGE_VARIANT_MAX_CONCURRENT_RENDERS=4
+DB_DRIVER=sqlite
+DATA_DIR=
+DB_HOST=
+DB_PORT=
+DB_USER=
+DB_PASSWORD=
+DB_NAME=
+DB_TLS=false
+DB_SSLMODE=disable
+DB_MAX_OPEN_CONNS=10
+DB_MAX_IDLE_CONNS=5
+DB_CONN_MAX_LIFETIME_SECONDS=300
+STORAGE_DRIVER=local
+S3_BUCKET=
+S3_REGION=us-east-1
+S3_ENDPOINT=
+S3_ACCESS_KEY_ID=
+S3_SECRET_ACCESS_KEY=
+S3_KEY_PREFIX=
+S3_PATH_STYLE=false
+S3_TLS=true

.gitignore

@@ -4,7 +4,7 @@
 
 # DB
 *.db
-data/
+/data/
 
 # Build
 bin
@@ -12,6 +12,7 @@ dist/
 
 # Environment
 .env
+docker.env
 
 # Generated files
 tmp/

Dockerfile

@@ -0,0 +1,30 @@
+FROM oven/bun:1-alpine AS web
+WORKDIR /src/web
+COPY web/package.json web/bun.lock ./
+RUN bun install --frozen-lockfile
+COPY web/ ./
+RUN bun run build-only
+
+FROM golang:1.27.1-alpine AS server
+ARG VERSION=dev
+ENV CGO_ENABLED=0
+WORKDIR /src
+COPY go.mod go.sum ./
+RUN go mod download
+COPY . .
+COPY --from=web /src/internal/infrastructure/assets/dist ./internal/infrastructure/assets/dist
+RUN go build -trimpath -ldflags "-s -w -X main.version=${VERSION}" -o /out/renewcms ./cmd/server
+
+FROM alpine:3.22
+RUN addgroup -S -g 10001 renewcms \
+	&& adduser -S -u 10001 -G renewcms -H -s /sbin/nologin renewcms \
+	&& mkdir /data \
+	&& chown renewcms:renewcms /data
+COPY --from=server /out/renewcms /usr/local/bin/renewcms
+ENV RENEWCMS_CONTAINER=true
+USER renewcms
+WORKDIR /data
+VOLUME /data
+EXPOSE 8080
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 CMD ["wget", "-qO-", "http://127.0.0.1:8080/healthz"]
+ENTRYPOINT ["/usr/local/bin/renewcms"]

README.md

@@ -15,6 +15,16 @@ cp .env.example .env    # fill in PUBLIC_URL, JWT_SECRET and SMTP_*
 
 Data is stored in `./data/` by default. For a real server (systemd, HTTPS, backups), see **[docs/deployment.md](docs/deployment.md)**.
 
+### Run with Docker
+
+```sh
+cp docker.env.example docker.env    # fill in PUBLIC_URL, JWT_SECRET and SMTP_*
+docker compose pull
+docker compose up -d                # http://localhost:8080
+```
+
+Upgrade with `docker compose pull && docker compose up -d`. The image `git.floriansylvain.fr/fsylvain/renewcms` is published by the maintainer with `task docker:publish` (no CI). Tags: `vX.Y.Z`, `X.Y.Z`, `X.Y` and `latest` for a stable release; `vX.Y.Z-<pre>`, `X.Y.Z-<pre>` and the moving `beta` or `rc` for a pre-release (`latest` never moves for those, so the default is `beta` for now). To build from source use the override described in **[docs/docker.md](docs/docker.md)**.
+
 ### Updates from the browser
 
 On Linux with systemd, install v2.6.0-beta or newer manually, then follow [the browser-update setup guide](docs/deployment.md#browser-updates). It covers finding the actual database directory, installing the helper, testing a restart and troubleshooting. Other platforms use manual upgrades.
@@ -35,6 +45,7 @@ task dev                # API with hot reload + Vite HMR → http://localhost:51
 |---|---|
 | [docs/development.md](docs/development.md) | Dev setup, how Vite and the API fit together, tests, lint, `task` commands |
 | [docs/deployment.md](docs/deployment.md) | Building release binaries, running as a service, HTTPS, backups, upgrades |
+| [docs/docker.md](docs/docker.md) | Running RenewCMS in Docker: image, Compose, data volume, backups, reverse proxy, tags, upgrades, publishing |
 | [docs/configuration.md](docs/configuration.md) | Every environment variable |
 | [docs/architecture.md](docs/architecture.md) | Backend layering and how the SPA is embedded |
 

Taskfile.yml

@@ -10,6 +10,7 @@ vars:
 
 env:
   CGO_ENABLED: '0'
+  __COMPAT_LAYER: RunAsInvoker
 
 tasks:
   default:
@@ -46,6 +47,127 @@ tasks:
     cmds:
       - go test -tags nofrontend ./test/... -count=1 {{.CLI_ARGS}}
 
+  test:mysql:
+    desc: Run the MySQL tests against real servers (mysql:8.4 then mariadb:11 in Docker, removed afterwards)
+    cmds:
+      - cmd: |
+          PASSWORD=renewcms-test-root
+          STATUS=0
+          run_engine() {
+            NAME="renewcms-test-$1"
+            IMAGE="$2"
+            docker rm -f "$NAME" >/dev/null 2>&1
+            docker run -d --name "$NAME" -e MYSQL_ROOT_PASSWORD="$PASSWORD" -p 127.0.0.1::3306 "$IMAGE" >/dev/null || return 1
+            MAPPING="$(docker port "$NAME" 3306/tcp)"
+            PORT="${MAPPING##*:}"
+            READY=no
+            TRIES=0
+            while [ "$TRIES" -lt 90 ]; do
+              if docker exec "$NAME" sh -c "\$(command -v mariadb || command -v mysql) -h127.0.0.1 -uroot -p$PASSWORD -e 'SELECT 1'" >/dev/null 2>&1; then
+                READY=yes
+                break
+              fi
+              TRIES=$((TRIES + 1))
+              sleep 2
+            done
+            if [ "$READY" != yes ]; then
+              echo "$IMAGE did not become ready" >&2
+              docker logs "$NAME" 2>&1 | tail -n 20 >&2
+              docker rm -f "$NAME" >/dev/null 2>&1
+              return 1
+            fi
+            echo "== $IMAGE on 127.0.0.1:$PORT"
+            RENEWCMS_TEST_MYSQL_DSN="root:$PASSWORD@tcp(127.0.0.1:$PORT)/mysql" go test -tags nofrontend ./test/... -run MySQL -count=1 {{.CLI_ARGS}}
+            RESULT=$?
+            docker rm -f "$NAME" >/dev/null 2>&1
+            return $RESULT
+          }
+          run_engine mysql mysql:8.4 || STATUS=1
+          run_engine mariadb mariadb:11 || STATUS=1
+          exit $STATUS
+        silent: true
+
+  test:postgres:
+    desc: Run the PostgreSQL tests against real servers (postgres:16 then postgres:17 in Docker, removed afterwards)
+    cmds:
+      - cmd: |
+          PASSWORD=renewcms-test-postgres
+          STATUS=0
+          run_engine() {
+            NAME="renewcms-test-postgres-$1"
+            IMAGE="postgres:$1"
+            docker rm -f "$NAME" >/dev/null 2>&1
+            docker run -d --name "$NAME" -e POSTGRES_PASSWORD="$PASSWORD" -p 127.0.0.1::5432 "$IMAGE" >/dev/null || return 1
+            MAPPING="$(docker port "$NAME" 5432/tcp | head -n 1)"
+            PORT="${MAPPING##*:}"
+            READY=no
+            TRIES=0
+            while [ "$TRIES" -lt 90 ]; do
+              if docker exec "$NAME" pg_isready -h 127.0.0.1 -U postgres >/dev/null 2>&1 && docker exec "$NAME" psql -h 127.0.0.1 -U postgres -c 'SELECT 1' >/dev/null 2>&1; then
+                READY=yes
+                break
+              fi
+              TRIES=$((TRIES + 1))
+              sleep 2
+            done
+            if [ "$READY" != yes ]; then
+              echo "$IMAGE did not become ready" >&2
+              docker logs "$NAME" 2>&1 | tail -n 20 >&2
+              docker rm -f "$NAME" >/dev/null 2>&1
+              return 1
+            fi
+            echo "== $IMAGE on 127.0.0.1:$PORT"
+            RENEWCMS_TEST_POSTGRES_DSN="postgres://postgres:$PASSWORD@127.0.0.1:$PORT/postgres?sslmode=disable" go test -tags nofrontend ./test/... -run Postgres -count=1 {{.CLI_ARGS}}
+            RESULT=$?
+            docker rm -f "$NAME" >/dev/null 2>&1
+            return $RESULT
+          }
+          run_engine 16 || STATUS=1
+          run_engine 17 || STATUS=1
+          exit $STATUS
+        silent: true
+
+  test:s3:
+    desc: Run the S3 storage integration test against a throwaway SeaweedFS in Docker (skipped when Docker is unavailable)
+    cmds:
+      - cmd: |
+          if ! docker info >/dev/null 2>&1; then
+            echo "Docker is not available, skipping the S3 integration test"
+            exit 0
+          fi
+          export MSYS_NO_PATHCONV=1
+          NAME=renewcms-test-seaweedfs
+          IMAGE=chrislusf/seaweedfs:4.48
+          BUCKET=renewcms-test
+          ACCESS_KEY=renewcms-test
+          SECRET_KEY=renewcms-test-secret
+          docker rm -f "$NAME" >/dev/null 2>&1
+          docker run -d --name "$NAME" -e AWS_ACCESS_KEY_ID="$ACCESS_KEY" -e AWS_SECRET_ACCESS_KEY="$SECRET_KEY" -p 127.0.0.1::8333 "$IMAGE" server -dir=/data -s3 -s3.port=8333 >/dev/null || exit 1
+          MAPPING="$(docker port "$NAME" 8333/tcp | head -n 1)"
+          PORT="${MAPPING##*:}"
+          READY=no
+          TRIES=0
+          while [ "$TRIES" -lt 60 ]; do
+            if docker run --rm --network "container:$NAME" --entrypoint sh "$IMAGE" -c "echo 's3.bucket.create -name $BUCKET' | timeout 30 weed shell -master=127.0.0.1:9333 && echo s3.bucket.list | timeout 30 weed shell -master=127.0.0.1:9333 | grep -q $BUCKET" >/dev/null 2>&1; then
+              READY=yes
+              break
+            fi
+            TRIES=$((TRIES + 1))
+            sleep 2
+          done
+          if [ "$READY" != yes ]; then
+            echo "SeaweedFS did not become ready" >&2
+            docker logs "$NAME" 2>&1 | tail -n 20 >&2
+            docker rm -f "$NAME" >/dev/null 2>&1
+            exit 1
+          fi
+          echo "== SeaweedFS on 127.0.0.1:$PORT"
+          RENEWCMS_TEST_S3_ENDPOINT="http://127.0.0.1:$PORT" RENEWCMS_TEST_S3_BUCKET="$BUCKET" RENEWCMS_TEST_S3_ACCESS_KEY="$ACCESS_KEY" RENEWCMS_TEST_S3_SECRET_KEY="$SECRET_KEY" go test -tags nofrontend ./test/... -run S3StorageIntegration -count=1 -v {{.CLI_ARGS}}
+          RESULT=$?
+          docker rm -f "$NAME" >/dev/null 2>&1
+          exit $RESULT
+        silent: true
+
   cover:
     desc: Go test coverage of the use cases → tmp/coverage.out
     cmds:
@@ -56,8 +178,7 @@ tasks:
   mutate:
     desc: Gremlins mutation testing of the use cases → tmp/gremlins.json
     cmds:
-      - mkdir -p tmp
-      - gremlins unleash --integration --tags nofrontend --coverpkg=./internal/infrastructure/useCases/...,./api/middleware/...,./api/pkg/claims/... --timeout-coefficient 10 --output tmp/gremlins.json ./internal/infrastructure/useCases ./api/middleware ./api/pkg/claims
+      - bash scripts/mutate.sh {{.CLI_ARGS}}
 
   test:web:
     desc: Run the SPA test suite (Vitest) in run mode
@@ -170,6 +291,132 @@ tasks:
     cmds:
       - ./bin/{{.BINARY}}{{exeExt}}
 
+  docker:build:
+    desc: Build the Docker image tagged with the git describe version and latest
+    cmds:
+      - docker build --build-arg VERSION={{.VERSION}} -t renewcms:{{.VERSION}} -t renewcms:latest .
+
+  docker:run:
+    desc: Run the image once on a named volume, reading docker.env, on http://localhost:8080
+    cmds:
+      - docker run --rm --name renewcms -p 8080:8080 --env-file docker.env -e DB_FILE=/data/renewcms.db -e UPLOAD_DIR=/data/uploads -v renewcms-data:/data --stop-timeout 15 renewcms:latest
+
+  docker:up:
+    desc: Build from the local sources and start the Compose service in the background
+    env:
+      VERSION: '{{.VERSION}}'
+    cmds:
+      - docker compose -f docker-compose.yml -f docker-compose.build.yml up -d --build
+
+  docker:pull:
+    desc: Pull the published image (RENEWCMS_IMAGE, default the beta tag)
+    cmds:
+      - docker compose pull
+
+  docker:upgrade:
+    desc: Pull the published image and recreate the Compose service on it
+    cmds:
+      - docker compose pull
+      - docker compose up -d
+
+  docker:down:
+    desc: Stop and remove the Compose service (the data volume is kept)
+    cmds:
+      - docker compose down
+
+  docker:logs:
+    desc: Follow the Compose service logs
+    cmds:
+      - docker compose logs -f renewcms
+
+  docker:publish:
+    desc: 'Build and push the multi-arch image to the registry. Usage, task docker:publish [-- --dry-run]'
+    vars:
+      REGISTRY_IMAGE:
+        sh: echo "${REGISTRY_IMAGE-git.floriansylvain.fr/fsylvain/renewcms}"
+    cmds:
+      - cmd: |
+          IMAGE='{{.REGISTRY_IMAGE}}'
+          V='{{.VERSION}}'
+          ARGS='{{.CLI_ARGS}}'
+          fail() { echo "docker:publish refused: $1" >&2; exit 1; }
+          DRY=no
+          case "$ARGS" in
+            "") ;;
+            "--dry-run") DRY=yes ;;
+            *) fail "unknown argument '$ARGS' (only --dry-run is accepted)" ;;
+          esac
+          [ -n "$IMAGE" ] || fail "REGISTRY_IMAGE is empty"
+          case "$V" in
+            v*) ;;
+            *) fail "VERSION '$V' must be an exact tag vX.Y.Z or vX.Y.Z-<pre>" ;;
+          esac
+          R="${V#v}"
+          CORE="${R%%-*}"
+          PRE=""
+          [ "$CORE" = "$R" ] || PRE="${R#*-}"
+          MAJOR="${CORE%%.*}"
+          REST="${CORE#*.}"
+          MINOR="${REST%%.*}"
+          PATCH="${REST#*.}"
+          for N in "$MAJOR" "$MINOR" "$PATCH"; do
+            case "$N" in
+              ""|*[!0-9]*) fail "VERSION '$V' must be an exact tag vX.Y.Z or vX.Y.Z-<pre>" ;;
+            esac
+          done
+          [ "$CORE" = "$MAJOR.$MINOR.$PATCH" ] || fail "VERSION '$V' must be an exact tag vX.Y.Z or vX.Y.Z-<pre>"
+          if [ "$R" != "$CORE" ]; then
+            case "$PRE" in
+              ""|*[!0-9A-Za-z.-]*) fail "VERSION '$V' has an invalid pre-release part" ;;
+            esac
+            PRENAME="${PRE%%[!A-Za-z]*}"
+            [ -n "$PRENAME" ] || fail "VERSION '$V' pre-release must start with letters, for example -beta or -rc.1"
+          fi
+          if [ "$DRY" = no ]; then
+            [ -z "$(git status --porcelain)" ] || fail "the work tree has uncommitted changes"
+            [ "$(git describe --tags --exact-match 2>/dev/null)" = "$V" ] || fail "VERSION '$V' is not an exact git tag on HEAD (an override is accepted only with --dry-run)"
+          fi
+          TAGS="$V $R"
+          if [ -n "$PRE" ]; then
+            TAGS="$TAGS $PRENAME"
+          else
+            TAGS="$TAGS $MAJOR.$MINOR latest"
+          fi
+          ARGS_TAGS=""
+          LIST=""
+          for T in $TAGS; do
+            ARGS_TAGS="$ARGS_TAGS -t $IMAGE:$T"
+            LIST="$LIST, $T"
+          done
+          echo "image: $IMAGE"
+          echo "tags: ${LIST#, }"
+          if [ "$DRY" = yes ]; then
+            echo "dry run: building for the host platform only, loading locally, pushing nothing"
+            docker buildx build --load --build-arg VERSION="$V" $ARGS_TAGS .
+            exit 0
+          fi
+          BUILDER="$(docker buildx inspect 2>&1)" || fail "docker buildx is not available or no builder is selected (see docs/docker.md, Maintainer: publishing)"
+          STORE="$(docker info 2>&1)"
+          case "$BUILDER" in
+            *linux/amd64*) ;;
+            *) fail "the selected buildx builder does not support linux/amd64 (see docs/docker.md, Maintainer: publishing)" ;;
+          esac
+          case "$BUILDER" in
+            *linux/arm64*) ;;
+            *) fail "the selected buildx builder does not support linux/arm64: enable QEMU/binfmt (see docs/docker.md, Maintainer: publishing)" ;;
+          esac
+          case "$BUILDER" in
+            *"Driver:"*"docker-container"*|*"Driver:"*"kubernetes"*|*"Driver:"*"remote"*) ;;
+            *)
+              case "$STORE" in
+                *io.containerd.snapshotter*) ;;
+                *) fail "the selected builder uses the plain docker driver without the containerd image store, which cannot build multi-platform images: run 'docker buildx create --use' (see docs/docker.md, Maintainer: publishing)" ;;
+              esac
+              ;;
+          esac
+          docker buildx build --platform linux/amd64,linux/arm64 --build-arg VERSION="$V" $ARGS_TAGS --push .
+        silent: true
+
   clean:
     desc: Remove build output, the built SPA and tmp/
     cmds:

api/dependecyInjection.go

@@ -1,35 +1,47 @@
 package api
 
 import (
+	domainAPIKey "RenewCMS/internal/domain/apikey"
 	domainArticle "RenewCMS/internal/domain/article"
+	domainAudit "RenewCMS/internal/domain/audit"
 	domainImage "RenewCMS/internal/domain/image"
 	domainInvite "RenewCMS/internal/domain/invite"
 	domainMail "RenewCMS/internal/domain/mail"
+	domainPurge "RenewCMS/internal/domain/purge"
 	domainUpdate "RenewCMS/internal/domain/update"
 	domainUser "RenewCMS/internal/domain/user"
+	"RenewCMS/internal/infrastructure/auditing"
 	"RenewCMS/internal/infrastructure/config"
 	"RenewCMS/internal/infrastructure/hashing"
+	"RenewCMS/internal/infrastructure/imaging"
 	"RenewCMS/internal/infrastructure/mailer"
 	"RenewCMS/internal/infrastructure/markdown"
-	"RenewCMS/internal/infrastructure/persistence/models"
+	"RenewCMS/internal/infrastructure/persistence/database"
 	persistence "RenewCMS/internal/infrastructure/persistence/repositories"
+	"RenewCMS/internal/infrastructure/scheduler"
+	"RenewCMS/internal/infrastructure/storage"
 	"RenewCMS/internal/infrastructure/update"
+	"RenewCMS/internal/infrastructure/usage"
 	"RenewCMS/internal/infrastructure/useCases"
+	"context"
 	"crypto/ed25519"
-	"fmt"
 	"log"
+	"net/http"
 	"os"
 	"path/filepath"
 	"runtime"
+	"sync"
 	"time"
 
-	"github.com/glebarez/sqlite"
 	"github.com/go-chi/jwtauth/v5"
-	"gorm.io/gorm"
 )
 
 type UseCases struct {
+	apiKeyAuthOnce                  sync.Once
+	apiKeyAuthMiddleware            func(http.Handler) http.Handler
 	Token                           *jwtauth.JWTAuth
+	PurgeScheduler                  *scheduler.Runner
+	ActivityCleanupScheduler        *scheduler.Runner
 	CreateArticleUseCase            *useCases.CreateArticleUseCase
 	GetArticleUseCase               *useCases.GetArticleUseCase
 	ListArticlesUseCase             *useCases.ListArticlesUseCase
@@ -52,24 +64,77 @@ type UseCases struct {
 	AcceptInviteUseCase             *useCases.AcceptInviteUseCase
 	SendMailUseCase                 *useCases.SendMailUseCase
 	CreateImageUseCase              *useCases.CreateImageUseCase
+	OpenMediaUseCase                *useCases.OpenMediaUseCase
 	ListMediaUseCase                *useCases.ListMediaUseCase
 	RenameMediaUseCase              *useCases.RenameMediaUseCase
 	DeleteMediaUseCase              *useCases.DeleteMediaUseCase
 	MergeMediaUseCase               *useCases.MergeMediaUseCase
 	GetMediaUsageUseCase            *useCases.GetMediaUsageUseCase
+	GetPurgeSettingsUseCase         *useCases.GetPurgeSettingsUseCase
+	UpdatePurgeSettingsUseCase      *useCases.UpdatePurgeSettingsUseCase
+	PreviewPurgeUseCase             *useCases.PreviewPurgeUseCase
+	RunPurgeUseCase                 *useCases.RunPurgeUseCase
 	GetSettingsUseCase              *useCases.GetSettingsUseCase
 	GetUpdateStatusUseCase          *useCases.GetUpdateStatusUseCase
 	CheckForUpdateUseCase           *useCases.CheckForUpdateUseCase
 	StartUpdateDownloadUseCase      *useCases.StartUpdateDownloadUseCase
 	RequestRestartUseCase           *useCases.RequestRestartUseCase
 	RecordRunningInfoUseCase        *useCases.RecordRunningInfoUseCase
+	CreateAPIKeyUseCase             *useCases.CreateAPIKeyUseCase
+	ListAPIKeysUseCase              *useCases.ListAPIKeysUseCase
+	RevokeAPIKeyUseCase             *useCases.RevokeAPIKeyUseCase
+	AuthenticateAPIKeyUseCase       *useCases.AuthenticateAPIKeyUseCase
+	ListActivityUseCase             *useCases.ListActivityUseCase
+	GetActivitySummaryUseCase       *useCases.GetActivitySummaryUseCase
+	ExportActivityUseCase           *useCases.ExportActivityUseCase
+	GetActivityRetentionUseCase     *useCases.GetActivityRetentionUseCase
+	UpdateActivityRetentionUseCase  *useCases.UpdateActivityRetentionUseCase
+	ListVariantsUseCase             *useCases.ListVariantsUseCase
+	CreateVariantUseCase            *useCases.CreateVariantUseCase
+	UpdateVariantUseCase            *useCases.UpdateVariantUseCase
+	SetVariantEnabledUseCase        *useCases.SetVariantEnabledUseCase
+	DeleteVariantUseCase            *useCases.DeleteVariantUseCase
+	PurgeVariantUseCase             *useCases.PurgeVariantUseCase
+	ServeVariantUseCase             *useCases.ServeVariantUseCase
+	ListImageVariantsUseCase        *useCases.ListImageVariantsUseCase
+	GenerateImageVariantUseCase     *useCases.GenerateImageVariantUseCase
+	GenerateAllImageVariantsUseCase *useCases.GenerateAllImageVariantsUseCase
+	PurgeImageVariantUseCase        *useCases.PurgeImageVariantUseCase
+	GenerateVariantsOnUploadUseCase *useCases.GenerateVariantsOnUploadUseCase
+	GetVariantCacheStatsUseCase     *useCases.GetVariantCacheStatsUseCase
+	PurgeVariantCacheUseCase        *useCases.PurgeVariantCacheUseCase
+	VariantUsageTracker             *usage.Tracker
+}
+
+func (c *UseCases) RunSchedulers(ctx context.Context) {
+	var running sync.WaitGroup
+	for _, runner := range []*scheduler.Runner{c.PurgeScheduler, c.ActivityCleanupScheduler} {
+		if runner == nil {
+			continue
+		}
+		running.Add(1)
+		go func() {
+			defer running.Done()
+			runner.Run(ctx)
+		}()
+	}
+	running.Wait()
 }
 
 type Repositories struct {
 	ArticleRepo       domainArticle.Repository
 	UserRepo          domainUser.Repository
 	ImageRepo         domainImage.Repository
+	VariantRepo       domainImage.VariantRepository
+	VariantFileRepo   domainImage.VariantFileRepository
+	VariantCacheRepo  domainImage.VariantCacheRepository
+	VariantUsageRepo  domainImage.VariantUsageRepository
+	VariantRenderer   domainImage.VariantRenderer
 	InviteRepo        domainInvite.Repository
+	APIKeyRepo        domainAPIKey.Repository
+	PurgeSettingsRepo domainPurge.Repository
+	AuditRepo         domainAudit.Repository
+	AuditSettingsRepo domainAudit.SettingsRepository
 	MailRepo          domainMail.Repository
 	ReleaseFeed       domainUpdate.ReleaseFeed
 	UpdateStore       domainUpdate.StatusStore
@@ -85,7 +150,6 @@ type Repositories struct {
 }
 
 const (
-	sqliteBusyTimeoutMs  = 5000
 	updateStatusFileName = "update-status.json"
 	updateJobFileName    = "update-job.json"
 	updateHelperFileName = "update-helper.json"
@@ -93,32 +157,94 @@ const (
 	backupsDirName       = "backups"
 )
 
-func SQLiteDSN(dbName string) string {
-	return fmt.Sprintf("%s?_pragma=busy_timeout(%d)", dbName, sqliteBusyTimeoutMs)
+func imageStorageConfig(settings config.Settings) storage.Config {
+	if settings.Storage.Driver == config.StorageDriverS3 {
+		s3 := settings.Storage.S3
+		return storage.Config{
+			Driver: storage.DriverS3,
+			S3: storage.S3Config{
+				Bucket:          s3.Bucket,
+				Region:          s3.Region,
+				Endpoint:        s3.Endpoint,
+				AccessKeyID:     s3.AccessKeyID,
+				SecretAccessKey: s3.SecretAccessKey,
+				KeyPrefix:       s3.KeyPrefix,
+				PathStyle:       s3.PathStyle,
+				TLS:             s3.TLS,
+			},
+		}
+	}
+	return storage.Config{Driver: storage.DriverLocal, Location: settings.UploadDir}
 }
 
-func getDb(dbName string, uploadDir string) *gorm.DB {
-	if err := os.MkdirAll(filepath.Dir(dbName), os.ModePerm); err != nil {
-		panic("Unable to create necessary subdirectories: " + err.Error())
+func openImageStorage(settings config.Settings) domainImage.Storage {
+	imageStorage, err := storage.Open(imageStorageConfig(settings))
+	if err != nil {
+		panic("Unable to open the image storage: " + err.Error())
 	}
-	db, err := gorm.Open(sqlite.Open(SQLiteDSN(dbName)), &gorm.Config{})
+	return imageStorage
+}
+
+func databaseConfig(settings config.Settings) database.Config {
+	switch settings.Database.Driver {
+	case config.DatabaseDriverMySQL:
+		return mysqlDatabaseConfig(settings.Database)
+	case config.DatabaseDriverPostgres:
+		return postgresDatabaseConfig(settings.Database)
+	case "", config.DatabaseDriverSQLite:
+		return database.Config{Driver: database.DriverSQLite, Source: settings.DBFile}
+	default:
+		return database.Config{Driver: settings.Database.Driver}
+	}
+}
+
+func mysqlDatabaseConfig(settings config.DatabaseSettings) database.Config {
+	return database.Config{
+		Driver: database.DriverMySQL,
+		Source: database.MySQLDSN(database.MySQLConfig{
+			Host:     settings.Host,
+			Port:     settings.Port,
+			User:     settings.User,
+			Password: settings.Password,
+			Name:     settings.Name,
+			TLS:      settings.TLS,
+		}),
+		Pool: &database.PoolSettings{
+			MaxOpenConns:    settings.MaxOpenConns,
+			MaxIdleConns:    settings.MaxIdleConns,
+			ConnMaxLifetime: settings.ConnMaxLifetime,
+		},
+	}
+}
+
+func postgresDatabaseConfig(settings config.DatabaseSettings) database.Config {
+	return database.Config{
+		Driver: database.DriverPostgres,
+		Source: database.PostgresDSN(database.PostgresConfig{
+			Host:     settings.Host,
+			Port:     settings.Port,
+			User:     settings.User,
+			Password: settings.Password,
+			Name:     settings.Name,
+			SSLMode:  settings.SSLMode,
+		}),
+		Pool: &database.PoolSettings{
+			MaxOpenConns:    settings.MaxOpenConns,
+			MaxIdleConns:    settings.MaxIdleConns,
+			ConnMaxLifetime: settings.ConnMaxLifetime,
+		},
+	}
+}
+
+func openDatabase(settings config.Settings) *database.Connection {
+	connection, err := database.Connect(databaseConfig(settings))
 	if err != nil {
 		panic("Unable to open the database: " + err.Error())
 	}
-
-	if err := db.AutoMigrate(&models.Article{}, &models.Image{}, &models.User{}, &models.Invite{}); err != nil {
+	if err := database.Migrate(connection.DB); err != nil {
 		panic("Failed to migrate database: " + err.Error())
 	}
-
-	if err := persistence.BackfillUserRoles(db); err != nil {
-		panic("Failed to backfill user roles: " + err.Error())
-	}
-
-	if err := persistence.BackfillImageMetadata(db, uploadDir); err != nil {
-		panic("Failed to backfill image metadata: " + err.Error())
-	}
-
-	return db
+	return connection
 }
 
 func releasePublicKey() ed25519.PublicKey {
@@ -129,71 +255,123 @@ func releasePublicKey() ed25519.PublicKey {
 	return key
 }
 
-func getRepositories(db *gorm.DB, settings config.Settings) *Repositories {
-	dataDir := filepath.Dir(settings.DBFile)
+func getRepositories(connection *database.Connection, settings config.Settings) *Repositories {
+	db := connection.DB
+	dataDir := settings.DataDir()
+	variantFiles := persistence.NewVariantFileRepository(db)
 	return &Repositories{
 		ArticleRepo:       persistence.NewArticleRepository(db),
 		UserRepo:          persistence.NewUserRepository(db),
-		ImageRepo:         persistence.NewImageRepository(db, settings.UploadDir),
+		ImageRepo:         persistence.NewImageRepository(db),
+		VariantRepo:       persistence.NewVariantRepository(db),
+		VariantFileRepo:   variantFiles,
+		VariantCacheRepo:  variantFiles,
+		VariantUsageRepo:  persistence.NewVariantUsageRepository(db),
+		VariantRenderer:   imaging.NewVariantRenderer(),
 		InviteRepo:        persistence.NewInviteRepository(db),
+		APIKeyRepo:        persistence.NewAPIKeyRepository(db),
+		PurgeSettingsRepo: persistence.NewPurgeSettingsRepository(db),
+		AuditRepo:         persistence.NewAuditEventRepository(db),
+		AuditSettingsRepo: persistence.NewAuditSettingsRepository(db),
 		MailRepo:          mailer.NewMailRepository(settings.Smtp),
 		ReleaseFeed:       update.NewGiteaReleaseFeed(settings.UpdateFeedURL),
 		UpdateStore:       update.NewJSONStatusStore(filepath.Join(dataDir, updateStatusFileName)),
 		UpdateJobs:        update.NewJSONJobStore(filepath.Join(dataDir, updateJobFileName)),
-		UpdateHelper:      update.NewFileHelperDetector(filepath.Join(dataDir, updateHelperFileName)),
+		UpdateHelper:      update.NewContainerHelperDetector(update.NewFileHelperDetector(filepath.Join(dataDir, updateHelperFileName)), settings.Container),
 		AssetFetcher:      update.NewHTTPAssetFetcher(settings.UpdateFeedURL),
 		SignatureVerifier: update.NewEd25519SignatureVerifier(releasePublicKey()),
 		StagedRunner:      update.NewExecStagedBinaryRunner(),
-		DatabaseBackup:    update.NewSQLiteDatabaseBackup(db, filepath.Join(dataDir, backupsDirName), time.Now),
+		DatabaseBackup:    connection.NewBackup(filepath.Join(dataDir, backupsDirName), time.Now),
 		UpdateResults:     update.NewJSONResultStore(filepath.Join(dataDir, domainUpdate.ResultFileName)),
 		RestartRequests:   update.NewJSONRestartRequestStore(filepath.Join(dataDir, domainUpdate.RestartRequestFileName)),
 		RunningInfo:       update.NewJSONRunningInfoStore(filepath.Join(dataDir, domainUpdate.RunningInfoFileName)),
 	}
 }
 
-func getUseCases(repos *Repositories, settings config.Settings) *UseCases {
+func getUseCases(repos *Repositories, imageStorage domainImage.Storage, settings config.Settings) *UseCases {
 	hasher := hashing.NewBcryptHasher()
 	renderer := markdown.NewConverter()
+	keyGenerator := hashing.NewSHA256KeyGenerator()
+	recorder := auditing.NewRecorder(repos.AuditRepo, time.Now, log.Default())
+	mergeMedia := useCases.NewMergeMediaUseCase(repos.ImageRepo, repos.ArticleRepo, imageStorage, repos.VariantFileRepo, recorder)
+
+	runPurge := useCases.NewRunPurgeUseCase(repos.ImageRepo, repos.ArticleRepo, mergeMedia, repos.PurgeSettingsRepo, time.Now, log.Default(), recorder)
+	purgeScheduler := useCases.NewPurgeSchedulerUseCase(repos.PurgeSettingsRepo, runPurge, recorder)
+	activityCleanup := useCases.NewCleanupActivityUseCase(repos.AuditRepo, repos.AuditSettingsRepo, recorder)
+
+	usageTracker := usage.NewTracker(repos.VariantUsageRepo, time.Now)
+	serveVariant := useCases.NewServeVariantUseCase(repos.VariantRepo, repos.VariantFileRepo, repos.ImageRepo, imageStorage, repos.VariantRenderer, useCases.ServeVariantLimits{MaxSourceBytes: settings.ImageVariantMaxSourceBytes, MaxSourcePixels: settings.ImageVariantMaxSourcePixels, MaxConcurrentRenders: settings.ImageVariantMaxConcurrentRenders}).WithUsageTracker(usageTracker)
 
 	return &UseCases{
+		PurgeScheduler:                  scheduler.NewSystemRunner(purgeScheduler, log.Default()),
+		ActivityCleanupScheduler:        scheduler.NewSystemCleanupRunner(activityCleanup, log.Default()),
 		Token:                           jwtauth.New("HS256", []byte(settings.JWTSecret), nil),
-		CreateArticleUseCase:        useCases.NewCreateArticleUseCase(repos.ArticleRepo, renderer),
+		CreateArticleUseCase:            useCases.NewCreateArticleUseCase(repos.ArticleRepo, renderer, recorder),
 		GetArticleUseCase:               useCases.NewGetArticleUseCase(repos.ArticleRepo, renderer),
 		ListArticlesUseCase:             useCases.NewListArticlesUseCase(repos.ArticleRepo, renderer),
-		UpdateArticleUseCase:        useCases.NewUpdateArticleUseCase(repos.ArticleRepo, renderer),
-		DeleteArticleUseCase:        useCases.NewDeleteArticleUseCase(repos.ArticleRepo),
+		UpdateArticleUseCase:            useCases.NewUpdateArticleUseCase(repos.ArticleRepo, renderer, recorder),
+		DeleteArticleUseCase:            useCases.NewDeleteArticleUseCase(repos.ArticleRepo, recorder),
 		GetUserUseCase:                  useCases.NewGetUserUseCase(repos.UserRepo),
-		CreateUserUseCase:           useCases.NewCreateUserUseCase(repos.UserRepo, hasher, repos.MailRepo, settings.PublicURL),
-		AuthenticateUserUseCase:     useCases.NewAuthenticateUserUseCase(repos.UserRepo, hasher),
-		VerifyUserUseCase:           useCases.NewVerifyUserUseCase(repos.UserRepo, hasher),
+		CreateUserUseCase:               useCases.NewCreateUserUseCase(repos.UserRepo, hasher, repos.MailRepo, settings.PublicURL, recorder),
+		AuthenticateUserUseCase:         useCases.NewAuthenticateUserUseCase(repos.UserRepo, hasher, recorder),
+		VerifyUserUseCase:               useCases.NewVerifyUserUseCase(repos.UserRepo, hasher, recorder),
 		CancelRegistrationUseCase:       useCases.NewCancelRegistrationUseCase(repos.UserRepo),
-		RequestPasswordResetUseCase: useCases.NewRequestPasswordResetUseCase(repos.UserRepo, hasher, repos.MailRepo, settings.PublicURL),
-		ResetPasswordUseCase:        useCases.NewResetPasswordUseCase(repos.UserRepo, hasher),
-		UpdateUserProfileUseCase:    useCases.NewUpdateUserProfileUseCase(repos.UserRepo),
+		RequestPasswordResetUseCase:     useCases.NewRequestPasswordResetUseCase(repos.UserRepo, hasher, repos.MailRepo, settings.PublicURL, recorder),
+		ResetPasswordUseCase:            useCases.NewResetPasswordUseCase(repos.UserRepo, hasher, repos.APIKeyRepo, time.Now, recorder),
+		UpdateUserProfileUseCase:        useCases.NewUpdateUserProfileUseCase(repos.UserRepo, recorder),
 		ListUsersUseCase:                useCases.NewListUsersUseCase(repos.UserRepo),
-		CreateInviteUseCase:         useCases.NewCreateInviteUseCase(repos.UserRepo, repos.InviteRepo, hasher, repos.MailRepo, settings.PublicURL),
-		CancelInviteUseCase:         useCases.NewCancelInviteUseCase(repos.InviteRepo),
-		RenewInviteUseCase:          useCases.NewRenewInviteUseCase(repos.UserRepo, repos.InviteRepo, hasher, repos.MailRepo, settings.PublicURL),
+		CreateInviteUseCase:             useCases.NewCreateInviteUseCase(repos.UserRepo, repos.InviteRepo, hasher, repos.MailRepo, settings.PublicURL, recorder),
+		CancelInviteUseCase:             useCases.NewCancelInviteUseCase(repos.InviteRepo, recorder),
+		RenewInviteUseCase:              useCases.NewRenewInviteUseCase(repos.UserRepo, repos.InviteRepo, hasher, repos.MailRepo, settings.PublicURL, recorder),
 		ListUsersAndInvitesUseCase:      useCases.NewListUsersAndInvitesUseCase(repos.UserRepo, repos.InviteRepo),
 		GetInviteUseCase:                useCases.NewGetInviteUseCase(repos.InviteRepo, hasher),
-		AcceptInviteUseCase:         useCases.NewAcceptInviteUseCase(repos.UserRepo, repos.InviteRepo, hasher),
+		AcceptInviteUseCase:             useCases.NewAcceptInviteUseCase(repos.UserRepo, repos.InviteRepo, hasher, recorder),
 		SendMailUseCase:                 useCases.NewSendMailUseCase(repos.MailRepo),
-		CreateImageUseCase:          useCases.NewCreateImageUseCase(repos.ImageRepo),
-		ListMediaUseCase:            useCases.NewListMediaUseCase(repos.ImageRepo, repos.ArticleRepo, repos.UserRepo),
-		RenameMediaUseCase:          useCases.NewRenameMediaUseCase(repos.ImageRepo),
-		DeleteMediaUseCase:          useCases.NewDeleteMediaUseCase(repos.ImageRepo),
-		MergeMediaUseCase:           useCases.NewMergeMediaUseCase(repos.ImageRepo, repos.ArticleRepo),
+		CreateImageUseCase:              useCases.NewCreateImageUseCase(repos.ImageRepo, imageStorage, recorder),
+		OpenMediaUseCase:                useCases.NewOpenMediaUseCase(imageStorage),
+		ListMediaUseCase:                useCases.NewListMediaUseCase(repos.ImageRepo, repos.ArticleRepo, repos.UserRepo, repos.VariantFileRepo),
+		RenameMediaUseCase:              useCases.NewRenameMediaUseCase(repos.ImageRepo, recorder),
+		DeleteMediaUseCase:              useCases.NewDeleteMediaUseCase(repos.ImageRepo, imageStorage, repos.VariantFileRepo, recorder),
+		MergeMediaUseCase:               mergeMedia,
 		GetMediaUsageUseCase:            useCases.NewGetMediaUsageUseCase(repos.ImageRepo, repos.ArticleRepo),
+		GetPurgeSettingsUseCase:         useCases.NewGetPurgeSettingsUseCase(repos.PurgeSettingsRepo),
+		UpdatePurgeSettingsUseCase:      useCases.NewUpdatePurgeSettingsUseCase(repos.PurgeSettingsRepo, time.Now),
+		PreviewPurgeUseCase:             useCases.NewPreviewPurgeUseCase(repos.ImageRepo, repos.ArticleRepo),
+		RunPurgeUseCase:                 runPurge,
 		GetSettingsUseCase:              useCases.NewGetSettingsUseCase(settings.Version),
-		GetUpdateStatusUseCase:      useCases.NewGetUpdateStatusUseCase(repos.UpdateStore, repos.UpdateJobs, repos.UpdateHelper, repos.UpdateResults, repos.RestartRequests, settings.Version, time.Now),
-		CheckForUpdateUseCase:       useCases.NewCheckForUpdateUseCase(repos.ReleaseFeed, repos.UpdateStore, settings.Version, time.Now),
-		StartUpdateDownloadUseCase:  startUpdateDownloadUseCase(repos, settings),
-		RequestRestartUseCase:       useCases.NewRequestRestartUseCase(repos.UpdateStore, repos.UpdateJobs, repos.UpdateHelper, repos.UpdateResults, repos.RestartRequests, settings.Version, time.Now),
+		GetUpdateStatusUseCase:          useCases.NewGetUpdateStatusUseCase(repos.UpdateStore, repos.UpdateJobs, repos.UpdateHelper, repos.UpdateResults, repos.RestartRequests, settings.Version, settings.Container, time.Now),
+		CheckForUpdateUseCase:           useCases.NewCheckForUpdateUseCase(repos.ReleaseFeed, repos.UpdateStore, settings.Version, time.Now, recorder),
+		StartUpdateDownloadUseCase:      startUpdateDownloadUseCase(repos, settings, recorder),
+		RequestRestartUseCase:           useCases.NewRequestRestartUseCase(repos.UpdateStore, repos.UpdateJobs, repos.UpdateHelper, repos.UpdateResults, repos.RestartRequests, settings.Version, time.Now, recorder),
 		RecordRunningInfoUseCase:        useCases.NewRecordRunningInfoUseCase(repos.RunningInfo, settings.Version, os.Getpid(), time.Now),
+		CreateAPIKeyUseCase:             useCases.NewCreateAPIKeyUseCase(repos.APIKeyRepo, keyGenerator, time.Now, recorder),
+		ListAPIKeysUseCase:              useCases.NewListAPIKeysUseCase(repos.APIKeyRepo, repos.UserRepo, time.Now),
+		RevokeAPIKeyUseCase:             useCases.NewRevokeAPIKeyUseCase(repos.APIKeyRepo, repos.UserRepo, time.Now, recorder),
+		AuthenticateAPIKeyUseCase:       useCases.NewAuthenticateAPIKeyUseCase(repos.APIKeyRepo, keyGenerator, repos.UserRepo, time.Now),
+		ListActivityUseCase:             useCases.NewListActivityUseCase(repos.AuditRepo, repos.UserRepo, repos.ArticleRepo, repos.ImageRepo, repos.APIKeyRepo, time.Now),
+		GetActivitySummaryUseCase:       useCases.NewGetActivitySummaryUseCase(repos.AuditRepo, time.Now),
+		ExportActivityUseCase:           useCases.NewExportActivityUseCase(repos.AuditRepo, time.Now),
+		GetActivityRetentionUseCase:     useCases.NewGetActivityRetentionUseCase(repos.AuditSettingsRepo, repos.AuditRepo, time.Now),
+		UpdateActivityRetentionUseCase:  useCases.NewUpdateActivityRetentionUseCase(repos.AuditSettingsRepo, repos.AuditRepo, recorder, time.Now),
+		ListVariantsUseCase:             useCases.NewListVariantsUseCase(repos.VariantRepo, repos.VariantFileRepo),
+		CreateVariantUseCase:            useCases.NewCreateVariantUseCase(repos.VariantRepo, repos.VariantRenderer, time.Now, recorder),
+		UpdateVariantUseCase:            useCases.NewUpdateVariantUseCase(repos.VariantRepo, repos.VariantFileRepo, imageStorage, repos.VariantRenderer, time.Now, recorder),
+		SetVariantEnabledUseCase:        useCases.NewSetVariantEnabledUseCase(repos.VariantRepo, repos.VariantFileRepo, time.Now, recorder),
+		DeleteVariantUseCase:            useCases.NewDeleteVariantUseCase(repos.VariantRepo, repos.VariantFileRepo, imageStorage, recorder),
+		PurgeVariantUseCase:             useCases.NewPurgeVariantUseCase(repos.VariantRepo, repos.VariantFileRepo, imageStorage, recorder),
+		ServeVariantUseCase:             serveVariant,
+		ListImageVariantsUseCase:        useCases.NewListImageVariantsUseCase(repos.ImageRepo, repos.VariantRepo, repos.VariantFileRepo, repos.VariantRenderer),
+		GenerateImageVariantUseCase:     useCases.NewGenerateImageVariantUseCase(repos.ImageRepo, repos.VariantRepo, repos.VariantFileRepo, repos.VariantRenderer, serveVariant),
+		GenerateAllImageVariantsUseCase: useCases.NewGenerateAllImageVariantsUseCase(repos.ImageRepo, repos.VariantRepo, repos.VariantFileRepo, repos.VariantRenderer, serveVariant, recorder),
+		PurgeImageVariantUseCase:        useCases.NewPurgeImageVariantUseCase(repos.ImageRepo, repos.VariantRepo, repos.VariantFileRepo, imageStorage, recorder),
+		GenerateVariantsOnUploadUseCase: useCases.NewGenerateVariantsOnUploadUseCase(repos.VariantRepo, serveVariant, log.Default()),
+		GetVariantCacheStatsUseCase:     useCases.NewGetVariantCacheStatsUseCase(repos.VariantRepo, repos.VariantFileRepo, repos.VariantCacheRepo, repos.ImageRepo, repos.VariantUsageRepo, usageTracker, time.Now),
+		PurgeVariantCacheUseCase:        useCases.NewPurgeVariantCacheUseCase(repos.VariantRepo, repos.ImageRepo, repos.VariantCacheRepo, repos.VariantFileRepo, imageStorage, time.Now, recorder),
+		VariantUsageTracker:             usageTracker,
 	}
 }
 
-func startUpdateDownloadUseCase(repos *Repositories, settings config.Settings) *useCases.StartUpdateDownloadUseCase {
+func startUpdateDownloadUseCase(repos *Repositories, settings config.Settings, recorder domainAudit.Recorder) *useCases.StartUpdateDownloadUseCase {
 	return useCases.NewStartUpdateDownloadUseCase(useCases.StartUpdateDownloadDependencies{
 		Store:          repos.UpdateStore,
 		Jobs:           repos.UpdateJobs,
@@ -204,28 +382,48 @@ func startUpdateDownloadUseCase(repos *Repositories, settings config.Settings) *
 		Verifier:       repos.SignatureVerifier,
 		Runner:         repos.StagedRunner,
 		Backup:         repos.DatabaseBackup,
-		Staging:        update.NewOSStagingArea(filepath.Join(filepath.Dir(settings.DBFile), updatesDirName)),
+		Staging:        update.NewOSStagingArea(filepath.Join(settings.DataDir(), updatesDirName)),
 		Logger:         log.Default(),
 		CurrentVersion: settings.Version,
 		Platform:       domainUpdate.Platform{OS: runtime.GOOS, Arch: runtime.GOARCH},
 		FeedURL:        settings.UpdateFeedURL,
 		Now:            time.Now,
+		Recorder:       recorder,
 	})
 }
 
-func InitContainer(settings config.Settings) (*UseCases, func() error) {
-	db := getDb(settings.DBFile, settings.UploadDir)
-	repos := getRepositories(db, settings)
-	return getUseCases(repos, settings), closeDb(db)
+func backfillImageMetadata(imageRepo domainImage.Repository, imageStorage domainImage.Storage, settings config.Settings) error {
+	run := func(readable domainImage.Storage) error {
+		return useCases.NewBackfillImageMetadataUseCase(imageRepo, readable).Run()
+	}
+	if settings.Storage.Driver == config.StorageDriverS3 {
+		return storage.RunBackfillReportingReads(imageStorage, log.Default(), run)
+	}
+	return run(imageStorage)
 }
 
-func closeDb(db *gorm.DB) func() error {
-	return func() error {
-		sqlDb, err := db.DB()
-		if err != nil {
-			return err
+func InitContainer(settings config.Settings) (*UseCases, func() error) {
+	imageStorage := openImageStorage(settings)
+	connection := openDatabase(settings)
+	repos := getRepositories(connection, settings)
+	if err := backfillImageMetadata(repos.ImageRepo, imageStorage, settings); err != nil {
+		panic("Failed to backfill image metadata: " + err.Error())
 	}
-		return sqlDb.Close()
+	container := getUseCases(repos, imageStorage, settings)
+	return container, container.runUsageTracker(connection.Close)
+}
+
+func (c *UseCases) runUsageTracker(closeDatabase func() error) func() error {
+	ctx, stop := context.WithCancel(context.Background())
+	stopped := make(chan struct{})
+	go func() {
+		defer close(stopped)
+		c.VariantUsageTracker.Run(ctx)
+	}()
+	return func() error {
+		stop()
+		<-stopped
+		return closeDatabase()
 	}
 }
 

api/handlers/activity/activityHandler.go

@@ -0,0 +1,243 @@
+package activity
+
+import (
+	"RenewCMS/api/pkg/apperr"
+	"RenewCMS/api/pkg/claims"
+	validator "RenewCMS/api/pkg/validator"
+	"RenewCMS/internal/domain/audit"
+	"RenewCMS/internal/domain/user"
+	"RenewCMS/internal/infrastructure/useCases"
+	"encoding/json"
+	"errors"
+	"net/http"
+	"net/url"
+	"strconv"
+	"time"
+)
+
+const (
+	csvContentType        = "text/csv; charset=utf-8"
+	csvContentDisposition = `attachment; filename="activity.csv"`
+)
+
+type Handler struct {
+	ListUseCase    *useCases.ListActivityUseCase
+	SummaryUseCase *useCases.GetActivitySummaryUseCase
+	ExportUseCase  *useCases.ExportActivityUseCase
+}
+
+type filterQuery struct {
+	Q        string `validate:"max=200"`
+	Actor    string `validate:"max=40"`
+	Category string `validate:"omitempty,oneof=articles media users api_keys auth system"`
+	Outcome  string `validate:"omitempty,oneof=all success failed"`
+	Security string `validate:"omitempty,oneof=true"`
+	Range    string `validate:"omitempty,oneof=today 7d 30d custom"`
+	From     string `validate:"max=10"`
+	To       string `validate:"max=10"`
+}
+
+type listQuery struct {
+	filterQuery
+	Page int `validate:"gte=1"`
+	Size int `validate:"oneof=5 25 50 100"`
+}
+
+type actorResponse struct {
+	Type audit.ActorType `json:"type"`
+	ID   *uint32         `json:"id"`
+	Name string          `json:"name"`
+}
+
+type targetResponse struct {
+	Type   string `json:"type"`
+	ID     string `json:"id"`
+	Name   string `json:"name"`
+	Exists bool   `json:"exists"`
+}
+
+type itemResponse struct {
+	ID            uint64          `json:"id"`
+	CreatedAt     time.Time       `json:"created_at"`
+	Action        string          `json:"action"`
+	Category      audit.Category  `json:"category"`
+	Actor         actorResponse   `json:"actor"`
+	Target        *targetResponse `json:"target"`
+	Outcome       audit.Outcome   `json:"outcome"`
+	FailureReason *string         `json:"failure_reason"`
+	Security      bool            `json:"security"`
+	Source        audit.Source    `json:"source"`
+	IP            *string         `json:"ip"`
+	UserAgent     *string         `json:"user_agent"`
+	Params        map[string]any  `json:"params"`
+	Changes       []audit.Change  `json:"changes"`
+}
+
+type listResponse struct {
+	Items []itemResponse `json:"items"`
+	Total int            `json:"total"`
+	Page  int            `json:"page"`
+	Size  int            `json:"size"`
+}
+
+func NewHandler(list *useCases.ListActivityUseCase, summary *useCases.GetActivitySummaryUseCase, export *useCases.ExportActivityUseCase) *Handler {
+	return &Handler{ListUseCase: list, SummaryUseCase: summary, ExportUseCase: export}
+}
+
+func readFilterQuery(values url.Values) filterQuery {
+	return filterQuery{
+		Q:        values.Get("q"),
+		Actor:    values.Get("actor"),
+		Category: values.Get("category"),
+		Outcome:  values.Get("outcome"),
+		Security: values.Get("security"),
+		Range:    values.Get("range"),
+		From:     values.Get("from"),
+		To:       values.Get("to"),
+	}
+}
+
+func readListQuery(values url.Values) (listQuery, error) {
+	page, err := intParam(values, "page", 1)
+	if err != nil {
+		return listQuery{}, err
+	}
+	size, err := intParam(values, "size", 25)
+	if err != nil {
+		return listQuery{}, err
+	}
+	return listQuery{filterQuery: readFilterQuery(values), Page: page, Size: size}, nil
+}
+
+func intParam(values url.Values, name string, fallback int) (int, error) {
+	if !values.Has(name) {
+		return fallback, nil
+	}
+	return strconv.Atoi(values.Get(name))
+}
+
+func toActivityQuery(query filterQuery) useCases.ActivityQuery {
+	return useCases.ActivityQuery{
+		Q:        query.Q,
+		Actor:    query.Actor,
+		Category: query.Category,
+		Outcome:  query.Outcome,
+		Security: query.Security,
+		Range:    query.Range,
+		From:     query.From,
+		To:       query.To,
+	}
+}
+
+func writeActivityError(w http.ResponseWriter, err error) {
+	switch {
+	case errors.Is(err, audit.ErrInvalidFilter):
+		http.Error(w, apperr.BodyErrorMessage, http.StatusBadRequest)
+	case errors.Is(err, audit.ErrActorNotAllowed):
+		http.Error(w, apperr.OwnerOrAdminRequiredErrorMessage, http.StatusForbidden)
+	case errors.Is(err, user.ErrUserNotFound):
+		http.Error(w, apperr.UnauthorizedErrorMessage, http.StatusUnauthorized)
+	default:
+		http.Error(w, "Internal server error", http.StatusInternalServerError)
+	}
+}
+
+func (h *Handler) List(w http.ResponseWriter, r *http.Request) {
+	query, err := readListQuery(r.URL.Query())
+	if err != nil || validator.Validate.Struct(query) != nil {
+		http.Error(w, apperr.BodyErrorMessage, http.StatusBadRequest)
+		return
+	}
+	viewerId, ok := claims.UserId(r)
+	if !ok {
+		http.Error(w, apperr.UnauthorizedErrorMessage, http.StatusUnauthorized)
+		return
+	}
+
+	activityQuery := toActivityQuery(query.filterQuery)
+	activityQuery.Page, activityQuery.Size = query.Page, query.Size
+	page, err := h.ListUseCase.ListActivity(useCases.ListActivityCommand{ViewerID: viewerId, Query: activityQuery})
+	if err != nil {
+		writeActivityError(w, err)
+		return
+	}
+
+	items := make([]itemResponse, 0, len(page.Items))
+	for _, entry := range page.Items {
+		items = append(items, toItemResponse(entry))
+	}
+	writeJSON(w, listResponse{Items: items, Total: page.Total, Page: page.Page, Size: page.Size})
+}
+
+func toItemResponse(entry useCases.ActivityEntry) itemResponse {
+	event := entry.Event
+	item := itemResponse{
+		ID:            event.ID,
+		CreatedAt:     event.CreatedAt,
+		Action:        event.Action,
+		Category:      event.Category,
+		Actor:         actorResponse{Type: event.Actor.Type, ID: event.Actor.ID, Name: event.Actor.Name},
+		Outcome:       event.Outcome,
+		FailureReason: event.FailureReason,
+		Security:      event.Security,
+		Source:        event.Source,
+		IP:            event.IP,
+		UserAgent:     event.UserAgent,
+		Params:        event.Params,
+		Changes:       event.Changes,
+	}
+	if item.Params == nil {
+		item.Params = map[string]any{}
+	}
+	if item.Changes == nil {
+		item.Changes = []audit.Change{}
+	}
+	if event.Target.Type != "" {
+		item.Target = &targetResponse{Type: event.Target.Type, ID: event.Target.ID, Name: event.Target.Name, Exists: entry.TargetExists}
+	}
+	return item
+}
+
+func (h *Handler) Summary(w http.ResponseWriter, r *http.Request) {
+	query := readFilterQuery(r.URL.Query())
+	if validator.Validate.Struct(query) != nil {
+		http.Error(w, apperr.BodyErrorMessage, http.StatusBadRequest)
+		return
+	}
+
+	summary, err := h.SummaryUseCase.GetActivitySummary(toActivityQuery(query))
+	if err != nil {
+		writeActivityError(w, err)
+		return
+	}
+	writeJSON(w, summary)
+}
+
+func (h *Handler) Export(w http.ResponseWriter, r *http.Request) {
+	query := readFilterQuery(r.URL.Query())
+	if validator.Validate.Struct(query) != nil {
+		http.Error(w, apperr.BodyErrorMessage, http.StatusBadRequest)
+		return
+	}
+
+	prepared, err := h.ExportUseCase.Prepare(toActivityQuery(query))
+	if err != nil {
+		writeActivityError(w, err)
+		return
+	}
+
+	w.Header().Set("Content-Type", csvContentType)
+	w.Header().Set("Content-Disposition", csvContentDisposition)
+	w.Header().Set("Cache-Control", "no-store")
+	_ = prepared.WriteCSV(w)
+}
+
+func writeJSON(w http.ResponseWriter, payload any) {
+	body, err := json.Marshal(payload)
+	if err != nil {
+		http.Error(w, "Internal server error", http.StatusInternalServerError)
+		return
+	}
+	w.Header().Set("Cache-Control", "no-store")
+	_, _ = w.Write(body)
+}

api/handlers/apikey/apiKeyHandler.go

@@ -0,0 +1,176 @@
+package apikey
+
+import (
+	"RenewCMS/api/pkg/apperr"
+	"RenewCMS/api/pkg/claims"
+	validator "RenewCMS/api/pkg/validator"
+	domain "RenewCMS/internal/domain/apikey"
+	"RenewCMS/internal/domain/user"
+	"RenewCMS/internal/infrastructure/useCases"
+	"encoding/json"
+	"errors"
+	"net/http"
+	"strconv"
+	"time"
+
+	"github.com/go-chi/chi/v5"
+)
+
+type Handler struct {
+	CreateUseCase *useCases.CreateAPIKeyUseCase
+	ListUseCase   *useCases.ListAPIKeysUseCase
+	RevokeUseCase *useCases.RevokeAPIKeyUseCase
+}
+
+type CreateAPIKeyRequest struct {
+	Name      string     `json:"name" validate:"required,max=60"`
+	ExpiresAt *time.Time `json:"expires_at"`
+}
+
+type createdKeyResponse struct {
+	ID        uint32     `json:"id"`
+	Name      string     `json:"name"`
+	Prefix    string     `json:"prefix"`
+	Key       string     `json:"key"`
+	CreatedAt time.Time  `json:"created_at"`
+	ExpiresAt *time.Time `json:"expires_at"`
+}
+
+type keyListItem struct {
+	ID            uint32        `json:"id"`
+	UserID        uint32        `json:"user_id"`
+	Name          string        `json:"name"`
+	Prefix        string        `json:"prefix"`
+	Status        domain.Status `json:"status"`
+	CreatedAt     time.Time     `json:"created_at"`
+	LastUsedAt    *time.Time    `json:"last_used_at"`
+	ExpiresAt     *time.Time    `json:"expires_at"`
+	RevokedAt     *time.Time    `json:"revoked_at"`
+	CreatedByName *string       `json:"created_by_name,omitempty"`
+}
+
+func NewHandler(create *useCases.CreateAPIKeyUseCase, list *useCases.ListAPIKeysUseCase, revoke *useCases.RevokeAPIKeyUseCase) *Handler {
+	return &Handler{CreateUseCase: create, ListUseCase: list, RevokeUseCase: revoke}
+}
+
+func (h *Handler) Create(w http.ResponseWriter, r *http.Request) {
+	var request CreateAPIKeyRequest
+	if err := json.NewDecoder(r.Body).Decode(&request); err != nil {
+		http.Error(w, apperr.BodyErrorMessage, http.StatusBadRequest)
+		return
+	}
+
+	if err := validator.Validate.Struct(request); err != nil {
+		http.Error(w, err.Error(), http.StatusBadRequest)
+		return
+	}
+
+	userId, ok := claims.UserId(r)
+	if !ok {
+		http.Error(w, apperr.UnauthorizedErrorMessage, http.StatusUnauthorized)
+		return
+	}
+
+	created, err := h.CreateUseCase.CreateAPIKey(r.Context(), useCases.CreateAPIKeyCommand{
+		UserID:    userId,
+		Name:      request.Name,
+		ExpiresAt: request.ExpiresAt,
+	})
+	if err != nil {
+		if errors.Is(err, domain.ErrExpiryNotInFuture) {
+			http.Error(w, apperr.APIKeyExpiryErrorMessage, http.StatusBadRequest)
+			return
+		}
+		http.Error(w, "Internal server error", http.StatusInternalServerError)
+		return
+	}
+
+	body, err := json.Marshal(createdKeyResponse{
+		ID:        created.Key.ID,
+		Name:      created.Key.Name,
+		Prefix:    created.Key.Prefix,
+		Key:       created.RawKey,
+		CreatedAt: created.Key.CreatedAt,
+		ExpiresAt: created.Key.ExpiresAt,
+	})
+	if err != nil {
+		http.Error(w, "Internal server error", http.StatusInternalServerError)
+		return
+	}
+	w.Header().Set("Cache-Control", "no-store")
+	w.WriteHeader(http.StatusCreated)
+	_, _ = w.Write(body)
+}
+
+func (h *Handler) List(w http.ResponseWriter, r *http.Request) {
+	userId, ok := claims.UserId(r)
+	if !ok {
+		http.Error(w, apperr.UnauthorizedErrorMessage, http.StatusUnauthorized)
+		return
+	}
+
+	entries, err := h.ListUseCase.ListAPIKeys(userId)
+	if err != nil {
+		if errors.Is(err, user.ErrUserNotFound) {
+			http.Error(w, apperr.UnauthorizedErrorMessage, http.StatusUnauthorized)
+			return
+		}
+		http.Error(w, "Internal server error", http.StatusInternalServerError)
+		return
+	}
+
+	items := make([]keyListItem, 0, len(entries))
+	for _, entry := range entries {
+		key := entry.Key
+		item := keyListItem{
+			ID:         key.ID,
+			UserID:     key.UserID,
+			Name:       key.Name,
+			Prefix:     key.Prefix,
+			Status:     entry.Status,
+			CreatedAt:  key.CreatedAt,
+			LastUsedAt: key.LastUsedAt,
+			ExpiresAt:  key.ExpiresAt,
+			RevokedAt:  key.RevokedAt,
+		}
+		if entry.ListsCreator {
+			item.CreatedByName = &entry.CreatorName
+		}
+		items = append(items, item)
+	}
+
+	body, err := json.Marshal(items)
+	if err != nil {
+		http.Error(w, "Internal server error", http.StatusInternalServerError)
+		return
+	}
+	w.Header().Set("Cache-Control", "no-store")
+	_, _ = w.Write(body)
+}
+
+func (h *Handler) Revoke(w http.ResponseWriter, r *http.Request) {
+	id, err := strconv.ParseUint(chi.URLParam(r, "id"), 10, 32)
+	if err != nil {
+		http.Error(w, apperr.IdUint32ErrorMessage, http.StatusBadRequest)
+		return
+	}
+
+	userId, ok := claims.UserId(r)
+	if !ok {
+		http.Error(w, apperr.UnauthorizedErrorMessage, http.StatusUnauthorized)
+		return
+	}
+
+	if err := h.RevokeUseCase.RevokeAPIKey(r.Context(), userId, uint32(id)); err != nil {
+		switch {
+		case errors.Is(err, domain.ErrAPIKeyNotFound):
+			http.Error(w, apperr.APIKeyNotFoundErrorMessage, http.StatusNotFound)
+		case errors.Is(err, user.ErrUserNotFound):
+			http.Error(w, apperr.UnauthorizedErrorMessage, http.StatusUnauthorized)
+		default:
+			http.Error(w, "Internal server error", http.StatusInternalServerError)
+		}
+		return
+	}
+	w.WriteHeader(http.StatusNoContent)
+}

api/handlers/article/articleHandler.go

@@ -149,7 +149,7 @@ func (h *Handler) PostArticle(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	createdArticle, err := h.CreateUseCase.CreateArticle(useCases.CreateArticleCommand{
+	createdArticle, err := h.CreateUseCase.CreateArticle(r.Context(), useCases.CreateArticleCommand{
 		Title:  localArticle.Title,
 		Body:   localArticle.Body,
 		Format: format,
@@ -201,7 +201,7 @@ func (h *Handler) setIsOnline(w http.ResponseWriter, r *http.Request, isOnline b
 		return
 	}
 
-	updatedArticle, err := h.UpdateUseCase.UpdateIsOnline(id, isOnline, format)
+	updatedArticle, err := h.UpdateUseCase.UpdateIsOnline(r.Context(), id, isOnline, format)
 	if err != nil {
 		writeArticleErrorResponse(w, err)
 		return
@@ -237,7 +237,7 @@ func (h *Handler) UpdateArticleBody(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	updatedArticle, err := h.UpdateUseCase.UpdateBody(id, localArticle.Body, format)
+	updatedArticle, err := h.UpdateUseCase.UpdateBody(r.Context(), id, localArticle.Body, format)
 	if err != nil {
 		writeArticleErrorResponse(w, err)
 		return
@@ -314,7 +314,7 @@ func (h *Handler) DeleteArticle(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	if err := h.DeleteUseCase.DeleteArticle(id); err != nil {
+	if err := h.DeleteUseCase.DeleteArticle(r.Context(), id); err != nil {
 		if errors.Is(err, domain.ErrArticleNotFound) {
 			http.Error(w, apperr.ArticleNotFoundErrorMessage, http.StatusNotFound)
 			return

api/handlers/auth/acceptInviteHandler.go

@@ -67,7 +67,7 @@ func (h *AcceptInviteHandler) AcceptInvite(w http.ResponseWriter, r *http.Reques
 		return
 	}
 
-	createdUser, err := h.AcceptInviteUseCase.AcceptInvite(useCases.AcceptInviteCommand{
+	createdUser, err := h.AcceptInviteUseCase.AcceptInvite(r.Context(), useCases.AcceptInviteCommand{
 		Code:     request.Code,
 		Username: request.Username,
 		Password: request.Password,

api/handlers/auth/loginHandler.go

@@ -87,7 +87,7 @@ func (h *LoginHandler) Login(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	dbUser, err := h.AuthenticateUseCase.Authenticate(credentials.Username, credentials.Password)
+	dbUser, err := h.AuthenticateUseCase.Authenticate(r.Context(), credentials.Username, credentials.Password)
 	if err != nil {
 		http.Error(w, apperr.LogsErrorMessage, http.StatusForbidden)
 		return
@@ -113,7 +113,7 @@ func (h *LoginHandler) Register(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	createdUser, err := h.CreateUseCase.CreateUser(useCases.CreateUserCommand{
+	createdUser, err := h.CreateUseCase.CreateUser(r.Context(), useCases.CreateUserCommand{
 		Username: credentials.Username,
 		Password: credentials.Password,
 		Email:    credentials.Email,
@@ -139,7 +139,8 @@ func (h *LoginHandler) RegistrationStatus(w http.ResponseWriter, _ *http.Request
 	_, _ = w.Write(body)
 }
 
-func (h *LoginHandler) Logout(w http.ResponseWriter, _ *http.Request) {
+func (h *LoginHandler) Logout(w http.ResponseWriter, r *http.Request) {
+	h.AuthenticateUseCase.Logout(r.Context())
 	removeJwtCookie(w, h.IsProduction)
 	message, _ := json.Marshal(map[string]any{"message": "User logged out! HTTPonly jwt cookie deleted"})
 	_, _ = w.Write(message)

api/handlers/auth/passwordResetHandler.go

@@ -46,7 +46,7 @@ func (h *PasswordResetHandler) RequestPasswordReset(w http.ResponseWriter, r *ht
 		return
 	}
 
-	_ = h.RequestPasswordResetUseCase.RequestPasswordReset(credentials.Email)
+	_ = h.RequestPasswordResetUseCase.RequestPasswordReset(r.Context(), credentials.Email)
 
 	message, _ := json.Marshal(map[string]any{"message": apperr.PasswordResetRequestedMessage})
 	_, _ = w.Write(message)
@@ -66,7 +66,7 @@ func (h *PasswordResetHandler) ResetPassword(w http.ResponseWriter, r *http.Requ
 		return
 	}
 
-	err = h.ResetPasswordUseCase.ResetPassword(credentials.Email, credentials.Code, credentials.Password)
+	err = h.ResetPasswordUseCase.ResetPassword(r.Context(), credentials.Email, credentials.Code, credentials.Password)
 	if err != nil {
 		if errors.Is(err, user.ErrInvalidPasswordResetCode) || errors.Is(err, user.ErrPasswordResetCodeExpired) {
 			http.Error(w, apperr.PasswordResetFailedErrorMessage, http.StatusForbidden)

api/handlers/auth/verificationHandler.go

@@ -50,7 +50,7 @@ func (h *VerificationHandler) Verify(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	verifiedUser, err := h.VerifyUseCase.Verify(userId, credentials.Code)
+	verifiedUser, err := h.VerifyUseCase.Verify(r.Context(), userId, credentials.Code)
 	if err != nil {
 		if errors.Is(err, user.ErrUserNotFound) {
 			http.Error(w, apperr.UnauthorizedErrorMessage, http.StatusUnauthorized)

api/handlers/frontend/frontHandler.go

@@ -2,6 +2,7 @@ package frontend
 
 import (
 	"RenewCMS/internal/infrastructure/assets"
+	"bytes"
 	"io"
 	"io/fs"
 	"net/http"
@@ -93,12 +94,15 @@ func (h *spaHandler) serveIndex(w http.ResponseWriter, r *http.Request) {
 	}
 	defer f.Close()
 
-	content, ok := f.(io.ReadSeeker)
-	if !ok {
-		http.Error(w, "File not seekable", http.StatusInternalServerError)
+	html, err := io.ReadAll(f)
+	if err != nil {
+		http.Error(w, "Index not readable", http.StatusInternalServerError)
 		return
 	}
 
 	w.Header().Set("Cache-Control", indexCacheControl)
-	http.ServeContent(w, r, "index.html", h.modTime, content)
+	if policy := w.Header().Get("Content-Security-Policy"); policy != "" {
+		w.Header().Set("Content-Security-Policy", AllowInlineScripts(policy, html))
+	}
+	http.ServeContent(w, r, "index.html", h.modTime, bytes.NewReader(html))
 }

api/handlers/frontend/inlineScripts.go

@@ -0,0 +1,33 @@
+package frontend
+
+import (
+	"crypto/sha256"
+	"encoding/base64"
+	"regexp"
+	"strings"
+)
+
+const scriptSrcSelf = "script-src 'self'"
+
+var inlineScriptPattern = regexp.MustCompile(`(?is)<script(\s[^>]*)?>(.*?)</script>`)
+var srcAttributePattern = regexp.MustCompile(`(?i)\ssrc\s*=`)
+
+func inlineScriptSources(html []byte) []string {
+	var sources []string
+	for _, match := range inlineScriptPattern.FindAllSubmatch(html, -1) {
+		if srcAttributePattern.Match(match[1]) || strings.TrimSpace(string(match[2])) == "" {
+			continue
+		}
+		digest := sha256.Sum256(match[2])
+		sources = append(sources, "'sha256-"+base64.StdEncoding.EncodeToString(digest[:])+"'")
+	}
+	return sources
+}
+
+func AllowInlineScripts(policy string, html []byte) string {
+	sources := inlineScriptSources(html)
+	if len(sources) == 0 {
+		return policy
+	}
+	return strings.Replace(policy, scriptSrcSelf, scriptSrcSelf+" "+strings.Join(sources, " "), 1)
+}

api/handlers/imagevariant/cacheHandler.go

@@ -0,0 +1,141 @@
+package imagevariant
+
+import (
+	"RenewCMS/api/pkg/apperr"
+	validator "RenewCMS/api/pkg/validator"
+	"RenewCMS/internal/domain/image"
+	"RenewCMS/internal/infrastructure/useCases"
+	"encoding/json"
+	"errors"
+	"math"
+	"net/http"
+
+	validatorlib "github.com/go-playground/validator/v10"
+)
+
+type cacheUnusedResponse struct {
+	Files int   `json:"files"`
+	Bytes int64 `json:"bytes"`
+	Days  int   `json:"days"`
+}
+
+type cacheVariantResponse struct {
+	Name    string `json:"name"`
+	Enabled bool   `json:"enabled"`
+	Files   int    `json:"files"`
+	Bytes   int64  `json:"bytes"`
+}
+
+type cacheImageResponse struct {
+	ID       uint32 `json:"id"`
+	Filename string `json:"filename"`
+	URL      string `json:"url"`
+	Files    int    `json:"files"`
+	Bytes    int64  `json:"bytes"`
+}
+
+type cacheResponse struct {
+	GeneratedFiles     int                    `json:"generated_files"`
+	DiskUsed           int64                  `json:"disk_used"`
+	VariantsDefined    int                    `json:"variants_defined"`
+	VariantsEnabled    int                    `json:"variants_enabled"`
+	VariantsDisabled   int                    `json:"variants_disabled"`
+	RejectedRequests   int                    `json:"rejected_requests"`
+	RejectedWindowDays int                    `json:"rejected_window_days"`
+	Unused             cacheUnusedResponse    `json:"unused"`
+	ByVariant          []cacheVariantResponse `json:"by_variant"`
+	TopImages          []cacheImageResponse   `json:"top_images"`
+}
+
+type cachePurgeRequest struct {
+	Scope   string `json:"scope" validate:"required,oneof=all unused variant image"`
+	Variant string `json:"variant" validate:"required_if=Scope variant"`
+	ImageID int64  `json:"image_id" validate:"required_if=Scope image,omitempty,gt=0,lte=4294967295"`
+}
+
+type cachePurgeResponse struct {
+	Scope       string `json:"scope"`
+	PurgedFiles int    `json:"purged_files"`
+	PurgedBytes int64  `json:"purged_bytes"`
+	FailedFiles int    `json:"failed_files"`
+}
+
+func (r *cachePurgeRequest) ignoreUnusedTargets() {
+	if r.Scope != string(image.CacheScopeVariant) {
+		r.Variant = ""
+	}
+	if r.Scope != string(image.CacheScopeImage) {
+		r.ImageID = 0
+	}
+}
+
+func cacheResponseOf(stats useCases.VariantCacheStats) cacheResponse {
+	response := cacheResponse{
+		GeneratedFiles:     stats.GeneratedFiles,
+		DiskUsed:           stats.DiskUsed,
+		VariantsDefined:    stats.VariantsDefined,
+		VariantsEnabled:    stats.VariantsEnabled,
+		VariantsDisabled:   stats.VariantsDisabled,
+		RejectedRequests:   stats.RejectedRequests,
+		RejectedWindowDays: stats.RejectedWindowDays,
+		Unused:             cacheUnusedResponse{Files: stats.Unused.Files, Bytes: stats.Unused.Bytes, Days: stats.UnusedDays},
+		ByVariant:          make([]cacheVariantResponse, 0, len(stats.ByVariant)),
+		TopImages:          make([]cacheImageResponse, 0, len(stats.TopImages)),
+	}
+	for _, entry := range stats.ByVariant {
+		response.ByVariant = append(response.ByVariant, cacheVariantResponse{Name: entry.Name, Enabled: entry.Enabled, Files: entry.Files, Bytes: entry.Bytes})
+	}
+	for _, top := range stats.TopImages {
+		response.TopImages = append(response.TopImages, cacheImageResponse{ID: top.ID, Filename: top.Filename, URL: top.URL, Files: top.Files, Bytes: top.Bytes})
+	}
+	return response
+}
+
+func (h *Handler) CacheStats(w http.ResponseWriter, _ *http.Request) {
+	stats, err := h.cacheStats.Get()
+	if err != nil {
+		h.writeError(w, "", err)
+		return
+	}
+	writeJSON(w, http.StatusOK, cacheResponseOf(stats))
+}
+
+func (h *Handler) PurgeCache(w http.ResponseWriter, r *http.Request) {
+	var request cachePurgeRequest
+	if err := json.NewDecoder(r.Body).Decode(&request); err != nil {
+		http.Error(w, apperr.BodyErrorMessage, http.StatusBadRequest)
+		return
+	}
+	request.ignoreUnusedTargets()
+	if err := validator.Validate.Struct(request); err != nil {
+		http.Error(w, cachePurgeValidationMessage(err), http.StatusUnprocessableEntity)
+		return
+	}
+
+	result, err := h.purgeCache.Purge(r.Context(), useCases.PurgeVariantCacheCommand{
+		Scope:   image.CachePurgeScope(request.Scope),
+		Variant: request.Variant,
+		ImageID: uint32(min(request.ImageID, math.MaxUint32)),
+	})
+	if err != nil {
+		h.writePurgeCacheError(w, err)
+		return
+	}
+	writeJSON(w, http.StatusOK, cachePurgeResponse{Scope: string(result.Scope), PurgedFiles: result.Files, PurgedBytes: result.Bytes, FailedFiles: result.Failed})
+}
+
+func cachePurgeValidationMessage(err error) string {
+	var failures validatorlib.ValidationErrors
+	if errors.As(err, &failures) && len(failures) > 0 && failures[0].StructField() != "Scope" {
+		return apperr.CachePurgeTargetErrorMessage
+	}
+	return apperr.CachePurgeScopeErrorMessage
+}
+
+func (h *Handler) writePurgeCacheError(w http.ResponseWriter, err error) {
+	if errors.Is(err, image.ErrImageNotFound) {
+		http.Error(w, apperr.ImageNotFoundErrorMessage, http.StatusNotFound)
+		return
+	}
+	h.writeError(w, "", err)
+}

api/handlers/imagevariant/imageVariantHandler.go

@@ -0,0 +1,266 @@
+package imagevariant
+
+import (
+	"RenewCMS/api/pkg/apperr"
+	validator "RenewCMS/api/pkg/validator"
+	"RenewCMS/internal/domain/image"
+	"RenewCMS/internal/infrastructure/useCases"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"net/http"
+	"strings"
+	"time"
+
+	validatorlib "github.com/go-playground/validator/v10"
+
+	"github.com/go-chi/chi/v5"
+)
+
+type Handler struct {
+	list       *useCases.ListVariantsUseCase
+	create     *useCases.CreateVariantUseCase
+	update     *useCases.UpdateVariantUseCase
+	setEnabled *useCases.SetVariantEnabledUseCase
+	remove     *useCases.DeleteVariantUseCase
+	purge      *useCases.PurgeVariantUseCase
+	cacheStats *useCases.GetVariantCacheStatsUseCase
+	purgeCache *useCases.PurgeVariantCacheUseCase
+}
+
+func NewHandler(list *useCases.ListVariantsUseCase, create *useCases.CreateVariantUseCase, update *useCases.UpdateVariantUseCase, setEnabled *useCases.SetVariantEnabledUseCase, remove *useCases.DeleteVariantUseCase, purge *useCases.PurgeVariantUseCase, cacheStats *useCases.GetVariantCacheStatsUseCase, purgeCache *useCases.PurgeVariantCacheUseCase) *Handler {
+	return &Handler{list, create, update, setEnabled, remove, purge, cacheStats, purgeCache}
+}
+
+type definitionRequest struct {
+	Width   *int   `json:"width" validate:"required_without=Height,omitempty,min=1,max=8000"`
+	Height  *int   `json:"height" validate:"required_without=Width,omitempty,min=1,max=8000"`
+	Fit     string `json:"fit" validate:"omitempty,oneof=cover contain inside"`
+	Format  string `json:"format" validate:"omitempty,oneof=original jpeg png webp"`
+	Quality *int   `json:"quality" validate:"omitempty,min=1,max=100"`
+}
+
+type switchesRequest struct {
+	GenerateOnUpload *bool `json:"generate_on_upload"`
+	Enabled          *bool `json:"enabled"`
+}
+
+type createRequest struct {
+	Name string `json:"name" validate:"required,variantname"`
+	definitionRequest
+	switchesRequest
+}
+
+type updateRequest struct {
+	definitionRequest
+	switchesRequest
+}
+
+type enabledRequest struct {
+	Enabled *bool `json:"enabled" validate:"required"`
+}
+
+type variantResponse struct {
+	Name             string              `json:"name"`
+	Width            *int                `json:"width"`
+	Height           *int                `json:"height"`
+	Fit              image.VariantFit    `json:"fit"`
+	Format           image.VariantFormat `json:"format"`
+	Quality          *int                `json:"quality"`
+	GenerateOnUpload bool                `json:"generate_on_upload"`
+	Enabled          bool                `json:"enabled"`
+	GeneratedFiles   int                 `json:"generated_files"`
+	CacheSize        int64               `json:"cache_size"`
+	CreatedAt        time.Time           `json:"created_at"`
+	UpdatedAt        time.Time           `json:"updated_at"`
+}
+
+type updatedVariantResponse struct {
+	variantResponse
+	PurgedFiles int `json:"purged_files"`
+}
+
+type listResponse struct {
+	Items []variantResponse `json:"items"`
+}
+
+type purgeResponse struct {
+	PurgedFiles int   `json:"purged_files"`
+	PurgedBytes int64 `json:"purged_bytes"`
+}
+
+func responseOf(summary useCases.VariantSummary) variantResponse {
+	variant := summary.Variant
+	return variantResponse{
+		Name:             variant.Name,
+		Width:            variant.Width,
+		Height:           variant.Height,
+		Fit:              variant.Fit,
+		Format:           variant.Format,
+		Quality:          variant.Quality,
+		GenerateOnUpload: variant.GenerateOnUpload,
+		Enabled:          variant.Enabled,
+		GeneratedFiles:   summary.GeneratedFiles,
+		CacheSize:        summary.CacheSize,
+		CreatedAt:        variant.CreatedAt,
+		UpdatedAt:        variant.UpdatedAt,
+	}
+}
+
+func (h *Handler) List(w http.ResponseWriter, _ *http.Request) {
+	summaries, err := h.list.List()
+	if err != nil {
+		h.writeError(w, "", err)
+		return
+	}
+	items := make([]variantResponse, 0, len(summaries))
+	for _, summary := range summaries {
+		items = append(items, responseOf(summary))
+	}
+	writeJSON(w, http.StatusOK, listResponse{items})
+}
+
+func (h *Handler) Create(w http.ResponseWriter, r *http.Request) {
+	var request createRequest
+	if !h.decode(w, r, &request) {
+		return
+	}
+
+	summary, err := h.create.Create(r.Context(), useCases.CreateVariantCommand{
+		Name:                     request.Name,
+		VariantDefinitionCommand: request.definitionRequest.command(),
+		GenerateOnUpload:         request.GenerateOnUpload,
+		Enabled:                  request.Enabled,
+	})
+	if err != nil {
+		h.writeError(w, request.Name, err)
+		return
+	}
+	writeJSON(w, http.StatusCreated, responseOf(summary))
+}
+
+func (h *Handler) Update(w http.ResponseWriter, r *http.Request) {
+	var request updateRequest
+	if !h.decode(w, r, &request) {
+		return
+	}
+
+	name := chi.URLParam(r, "name")
+	result, err := h.update.Update(r.Context(), useCases.UpdateVariantCommand{
+		Name:                     name,
+		VariantDefinitionCommand: request.definitionRequest.command(),
+		GenerateOnUpload:         request.GenerateOnUpload,
+		Enabled:                  request.Enabled,
+	})
+	if err != nil {
+		h.writeError(w, name, err)
+		return
+	}
+	writeJSON(w, http.StatusOK, updatedVariantResponse{responseOf(result.VariantSummary), result.PurgedFiles})
+}
+
+func (h *Handler) SetEnabled(w http.ResponseWriter, r *http.Request) {
+	var request enabledRequest
+	if !h.decode(w, r, &request) {
+		return
+	}
+
+	name := chi.URLParam(r, "name")
+	summary, err := h.setEnabled.SetEnabled(r.Context(), name, *request.Enabled)
+	if err != nil {
+		h.writeError(w, name, err)
+		return
+	}
+	writeJSON(w, http.StatusOK, responseOf(summary))
+}
+
+func (h *Handler) Delete(w http.ResponseWriter, r *http.Request) {
+	name := chi.URLParam(r, "name")
+	if err := h.remove.Delete(r.Context(), name); err != nil {
+		h.writeError(w, name, err)
+		return
+	}
+	w.WriteHeader(http.StatusNoContent)
+}
+
+func (h *Handler) Purge(w http.ResponseWriter, r *http.Request) {
+	name := chi.URLParam(r, "name")
+	purged, err := h.purge.Purge(r.Context(), name)
+	if err != nil {
+		h.writeError(w, name, err)
+		return
+	}
+	writeJSON(w, http.StatusOK, purgeResponse{purged.Files, purged.Bytes})
+}
+
+func (d definitionRequest) command() useCases.VariantDefinitionCommand {
+	return useCases.VariantDefinitionCommand{Width: d.Width, Height: d.Height, Fit: d.Fit, Format: d.Format, Quality: d.Quality}
+}
+
+func (h *Handler) decode(w http.ResponseWriter, r *http.Request, request any) bool {
+	if err := json.NewDecoder(r.Body).Decode(request); err != nil {
+		http.Error(w, apperr.BodyErrorMessage, http.StatusBadRequest)
+		return false
+	}
+	if err := validator.Validate.Struct(request); err != nil {
+		http.Error(w, h.validationMessage(err), http.StatusUnprocessableEntity)
+		return false
+	}
+	return true
+}
+
+func (h *Handler) validationMessage(err error) string {
+	var failures validatorlib.ValidationErrors
+	if !errors.As(err, &failures) || len(failures) == 0 {
+		return apperr.VariantInvalidErrorMessage
+	}
+	switch failures[0].StructField() {
+	case "Name":
+		return apperr.VariantNameErrorMessage
+	case "Width", "Height":
+		return apperr.VariantDimensionsErrorMessage
+	case "Fit":
+		return apperr.VariantFitErrorMessage
+	case "Format":
+		return h.formatMessage()
+	case "Quality":
+		return apperr.VariantQualityErrorMessage
+	default:
+		return apperr.VariantInvalidErrorMessage
+	}
+}
+
+func (h *Handler) formatMessage() string {
+	encodable := h.create.EncodableFormats()
+	names := make([]string, 0, len(encodable))
+	for _, format := range encodable {
+		names = append(names, string(format))
+	}
+	last := len(names) - 1
+	return fmt.Sprintf(apperr.VariantFormatErrorMessageFormat, strings.Join(names[:last], ", ")+" or "+names[last])
+}
+
+func (h *Handler) writeError(w http.ResponseWriter, name string, err error) {
+	switch {
+	case errors.Is(err, image.ErrVariantNotFound):
+		http.Error(w, apperr.VariantNotFoundErrorMessage, http.StatusNotFound)
+	case errors.Is(err, image.ErrVariantExists):
+		http.Error(w, fmt.Sprintf(apperr.VariantExistsErrorMessageFormat, name), http.StatusConflict)
+	case errors.Is(err, image.ErrVariantFormatUnavailable):
+		http.Error(w, h.formatMessage(), http.StatusUnprocessableEntity)
+	case errors.Is(err, image.ErrVariantInvalid):
+		http.Error(w, apperr.VariantInvalidErrorMessage, http.StatusUnprocessableEntity)
+	default:
+		http.Error(w, "Internal server error", http.StatusInternalServerError)
+	}
+}
+
+func writeJSON(w http.ResponseWriter, status int, value any) {
+	body, err := json.Marshal(value)
+	if err != nil {
+		http.Error(w, "Internal server error", http.StatusInternalServerError)
+		return
+	}
+	w.WriteHeader(status)
+	_, _ = w.Write(body)
+}

api/handlers/media/mediaHandler.go

@@ -25,6 +25,15 @@ type Handler struct {
 	DeleteUseCase              *useCases.DeleteMediaUseCase
 	MergeUseCase               *useCases.MergeMediaUseCase
 	UsageUseCase               *useCases.GetMediaUsageUseCase
+	PurgeSettingsUseCase       *useCases.GetPurgeSettingsUseCase
+	UpdatePurgeSettingsUseCase *useCases.UpdatePurgeSettingsUseCase
+	PreviewPurgeUseCase        *useCases.PreviewPurgeUseCase
+	RunPurgeUseCase            *useCases.RunPurgeUseCase
+	ListVariantsUseCase        *useCases.ListImageVariantsUseCase
+	GenerateVariantUseCase     *useCases.GenerateImageVariantUseCase
+	GenerateAllUseCase         *useCases.GenerateAllImageVariantsUseCase
+	PurgeVariantUseCase        *useCases.PurgeImageVariantUseCase
+	GenerateOnUploadUseCase    *useCases.GenerateVariantsOnUploadUseCase
 }
 
 type RenameRequest struct {
@@ -49,6 +58,9 @@ type mediaItemResponse struct {
 	CreatedAt   time.Time `json:"created_at"`
 	UsedIn      int       `json:"used_in"`
 	Duplicate   bool      `json:"duplicate"`
+
+	VariantCount int   `json:"variant_count"`
+	VariantSize  int64 `json:"variant_size"`
 }
 
 type countsResponse struct {
@@ -74,7 +86,7 @@ type mergeResponse struct {
 	Merged          int `json:"merged"`
 }
 
-func NewHandler(create *useCases.CreateImageUseCase, list *useCases.ListMediaUseCase, rename *useCases.RenameMediaUseCase, deleteUseCase *useCases.DeleteMediaUseCase, merge *useCases.MergeMediaUseCase, usage *useCases.GetMediaUsageUseCase) *Handler {
+func NewHandler(create *useCases.CreateImageUseCase, list *useCases.ListMediaUseCase, rename *useCases.RenameMediaUseCase, deleteUseCase *useCases.DeleteMediaUseCase, merge *useCases.MergeMediaUseCase, usage *useCases.GetMediaUsageUseCase, purgeSettings *useCases.GetPurgeSettingsUseCase, updatePurgeSettings *useCases.UpdatePurgeSettingsUseCase, previewPurge *useCases.PreviewPurgeUseCase, runPurge *useCases.RunPurgeUseCase, listVariants *useCases.ListImageVariantsUseCase, generateVariant *useCases.GenerateImageVariantUseCase, generateAll *useCases.GenerateAllImageVariantsUseCase, purgeVariant *useCases.PurgeImageVariantUseCase, generateOnUpload *useCases.GenerateVariantsOnUploadUseCase) *Handler {
 	return &Handler{
 		CreateUseCase:              create,
 		ListUseCase:                list,
@@ -82,6 +94,15 @@ func NewHandler(create *useCases.CreateImageUseCase, list *useCases.ListMediaUse
 		DeleteUseCase:              deleteUseCase,
 		MergeUseCase:               merge,
 		UsageUseCase:               usage,
+		PurgeSettingsUseCase:       purgeSettings,
+		UpdatePurgeSettingsUseCase: updatePurgeSettings,
+		PreviewPurgeUseCase:        previewPurge,
+		RunPurgeUseCase:            runPurge,
+		ListVariantsUseCase:        listVariants,
+		GenerateVariantUseCase:     generateVariant,
+		GenerateAllUseCase:         generateAll,
+		PurgeVariantUseCase:        purgeVariant,
+		GenerateOnUploadUseCase:    generateOnUpload,
 	}
 }
 
@@ -137,6 +158,9 @@ func toResponse(item useCases.MediaItem) mediaItemResponse {
 		CreatedAt:   item.Image.CreatedAt,
 		UsedIn:      item.UsedIn,
 		Duplicate:   item.Duplicate,
+
+		VariantCount: item.VariantCount,
+		VariantSize:  item.VariantSize,
 	}
 }
 
@@ -153,6 +177,12 @@ func parseListQuery(r *http.Request) (domainImage.ListQuery, error) {
 	if values.Has("filter") {
 		query.Filter = domainImage.Filter(values.Get("filter"))
 	}
+	if values.Has("variants") {
+		if values.Get("variants") == "" {
+			return domainImage.ListQuery{}, domainImage.ErrInvalidQuery
+		}
+		query.Variants = domainImage.VariantsFilter(values.Get("variants"))
+	}
 	if values.Has("sort") {
 		query.Sort = domainImage.Sort(values.Get("sort"))
 	}
@@ -205,12 +235,13 @@ func (h *Handler) Upload(w http.ResponseWriter, r *http.Request) {
 	}
 	defer closeFile()
 
-	created, err := h.CreateUseCase.CreateImage(input)
+	created, err := h.CreateUseCase.CreateImage(r.Context(), input)
 	if err != nil {
 		upload.WriteCreateError(w, err)
 		return
 	}
 
+	h.GenerateOnUploadUseCase.Generate(r.Context(), created)
 	h.writeItem(w, http.StatusCreated, created)
 }
 
@@ -239,7 +270,7 @@ func (h *Handler) Rename(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	renamed, err := h.RenameUseCase.Rename(id, request.Filename)
+	renamed, err := h.RenameUseCase.Rename(r.Context(), id, request.Filename)
 	if err != nil {
 		if errors.Is(err, domainImage.ErrInvalidFilename) {
 			http.Error(w, apperr.MediaFilenameErrorMessage, http.StatusBadRequest)
@@ -258,7 +289,7 @@ func (h *Handler) Delete(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	if err := h.DeleteUseCase.Delete(id); err != nil {
+	if err := h.DeleteUseCase.Delete(r.Context(), id); err != nil {
 		writeImageError(w, err)
 		return
 	}
@@ -296,7 +327,7 @@ func (h *Handler) Merge(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	result, err := h.MergeUseCase.Merge(request.KeepID, request.MergeIDs)
+	result, err := h.MergeUseCase.Merge(r.Context(), request.KeepID, request.MergeIDs)
 	if err != nil {
 		writeMergeError(w, err)
 		return

api/handlers/media/purgeHandler.go

@@ -0,0 +1,169 @@
+package media
+
+import (
+	"RenewCMS/api/pkg/apperr"
+	validator "RenewCMS/api/pkg/validator"
+	"RenewCMS/internal/domain/purge"
+	"RenewCMS/internal/infrastructure/useCases"
+	"encoding/json"
+	"errors"
+	"io"
+	"net/http"
+	"time"
+)
+
+type PurgeSettingsRequest struct {
+	AutoPurgeEnabled      *bool `json:"auto_purge_enabled"`
+	AutoPurgeIntervalDays *int  `json:"auto_purge_interval_days" validate:"omitempty,gte=1,lte=365"`
+}
+
+type PurgeRunRequest struct {
+	Fingerprint *string `json:"fingerprint"`
+}
+
+type purgeSettingsResponse struct {
+	AutoPurgeEnabled         bool       `json:"auto_purge_enabled"`
+	AutoPurgeIntervalDays    int        `json:"auto_purge_interval_days"`
+	LastPurgeAt              *time.Time `json:"last_purge_at"`
+	LastPurgeMerged          int        `json:"last_purge_merged"`
+	LastPurgeArticlesUpdated int        `json:"last_purge_articles_updated"`
+	EnabledAt                *time.Time `json:"enabled_at"`
+	NextPurgeAt              *time.Time `json:"next_purge_at"`
+}
+
+type purgePreviewGroupResponse struct {
+	KeepID   uint32 `json:"keep_id"`
+	Filename string `json:"filename"`
+	URL      string `json:"url"`
+	UsedIn   int    `json:"used_in"`
+	Merged   int    `json:"merged"`
+}
+
+type purgePreviewResponse struct {
+	Groups      int                         `json:"groups"`
+	Copies      int                         `json:"copies"`
+	Articles    int                         `json:"articles"`
+	List        []purgePreviewGroupResponse `json:"list"`
+	More        int                         `json:"more"`
+	Fingerprint string                      `json:"fingerprint"`
+}
+
+type purgeRunResponse struct {
+	GroupsTotal     int `json:"groups_total"`
+	GroupsPurged    int `json:"groups_purged"`
+	Merged          int `json:"merged"`
+	ArticlesUpdated int `json:"articles_updated"`
+	FailedGroups    int `json:"failed_groups"`
+}
+
+func toPurgeSettingsResponse(settings purge.Settings) purgeSettingsResponse {
+	return purgeSettingsResponse{
+		AutoPurgeEnabled:         settings.AutoPurgeEnabled,
+		AutoPurgeIntervalDays:    settings.AutoPurgeIntervalDays,
+		LastPurgeAt:              settings.LastPurgeAt,
+		LastPurgeMerged:          settings.LastPurgeMerged,
+		LastPurgeArticlesUpdated: settings.LastPurgeArticlesUpdated,
+		EnabledAt:                settings.EnabledAt,
+		NextPurgeAt:              settings.NextPurgeAt(),
+	}
+}
+
+func writePurgeError(w http.ResponseWriter, err error) {
+	switch {
+	case errors.Is(err, purge.ErrInvalidPurgeInterval):
+		http.Error(w, apperr.PurgeIntervalErrorMessage, http.StatusBadRequest)
+	case errors.Is(err, purge.ErrPurgeConflict):
+		http.Error(w, apperr.PurgeConflictErrorMessage, http.StatusConflict)
+	case errors.Is(err, purge.ErrPurgeBusy):
+		http.Error(w, apperr.PurgeBusyErrorMessage, http.StatusConflict)
+	default:
+		writeInternalServerError(w)
+	}
+}
+
+func (h *Handler) GetPurgeSettings(w http.ResponseWriter, _ *http.Request) {
+	settings, err := h.PurgeSettingsUseCase.Get()
+	if err != nil {
+		writePurgeError(w, err)
+		return
+	}
+	writeJSON(w, http.StatusOK, toPurgeSettingsResponse(settings))
+}
+
+func (h *Handler) UpdatePurgeSettings(w http.ResponseWriter, r *http.Request) {
+	var request PurgeSettingsRequest
+	if err := json.NewDecoder(r.Body).Decode(&request); err != nil {
+		http.Error(w, apperr.BodyErrorMessage, http.StatusBadRequest)
+		return
+	}
+	if err := validator.Validate.Struct(request); err != nil {
+		http.Error(w, apperr.PurgeIntervalErrorMessage, http.StatusBadRequest)
+		return
+	}
+
+	settings, err := h.UpdatePurgeSettingsUseCase.Update(useCases.UpdatePurgeSettingsCommand{
+		AutoPurgeEnabled:      request.AutoPurgeEnabled,
+		AutoPurgeIntervalDays: request.AutoPurgeIntervalDays,
+	})
+	if err != nil {
+		writePurgeError(w, err)
+		return
+	}
+	writeJSON(w, http.StatusOK, toPurgeSettingsResponse(settings))
+}
+
+func (h *Handler) PreviewPurge(w http.ResponseWriter, _ *http.Request) {
+	preview, err := h.PreviewPurgeUseCase.Preview()
+	if err != nil {
+		writePurgeError(w, err)
+		return
+	}
+
+	list := make([]purgePreviewGroupResponse, 0, len(preview.List))
+	for _, group := range preview.List {
+		list = append(list, purgePreviewGroupResponse{
+			KeepID:   group.KeepID,
+			Filename: group.Filename,
+			URL:      group.URL,
+			UsedIn:   group.UsedIn,
+			Merged:   group.Merged,
+		})
+	}
+	writeJSON(w, http.StatusOK, purgePreviewResponse{
+		Groups:      preview.Groups,
+		Copies:      preview.Copies,
+		Articles:    preview.Articles,
+		List:        list,
+		More:        preview.More,
+		Fingerprint: preview.Fingerprint,
+	})
+}
+
+func (h *Handler) RunPurge(w http.ResponseWriter, r *http.Request) {
+	raw, err := io.ReadAll(r.Body)
+	if err != nil {
+		http.Error(w, apperr.BodyErrorMessage, http.StatusBadRequest)
+		return
+	}
+
+	var request PurgeRunRequest
+	if len(raw) > 0 {
+		if err := json.Unmarshal(raw, &request); err != nil {
+			http.Error(w, apperr.BodyErrorMessage, http.StatusBadRequest)
+			return
+		}
+	}
+
+	result, err := h.RunPurgeUseCase.Run(r.Context(), request.Fingerprint)
+	if err != nil {
+		writePurgeError(w, err)
+		return
+	}
+	writeJSON(w, http.StatusOK, purgeRunResponse{
+		GroupsTotal:     result.GroupsTotal,
+		GroupsPurged:    result.GroupsPurged,
+		Merged:          result.Merged,
+		ArticlesUpdated: result.ArticlesUpdated,
+		FailedGroups:    result.FailedGroups,
+	})
+}

api/handlers/media/variantsHandler.go

@@ -0,0 +1,161 @@
+package media
+
+import (
+	"RenewCMS/api/pkg/apperr"
+	domainImage "RenewCMS/internal/domain/image"
+	"RenewCMS/internal/infrastructure/useCases"
+	"errors"
+	"net/http"
+
+	"github.com/go-chi/chi/v5"
+)
+
+type imageVariantResponse struct {
+	Name         string                    `json:"name"`
+	Width        *int                      `json:"width"`
+	Height       *int                      `json:"height"`
+	Fit          domainImage.VariantFit    `json:"fit"`
+	Format       domainImage.VariantFormat `json:"format"`
+	OutputWidth  int                       `json:"output_width"`
+	OutputHeight int                       `json:"output_height"`
+	OutputFormat domainImage.VariantFormat `json:"output_format"`
+	Generated    bool                      `json:"generated"`
+	Size         *int64                    `json:"size"`
+	URL          string                    `json:"url"`
+}
+
+type imageVariantListResponse struct {
+	Unsupported *string                `json:"unsupported"`
+	Items       []imageVariantResponse `json:"items"`
+}
+
+type variantFailureResponse struct {
+	Name  string `json:"name"`
+	Cause string `json:"cause"`
+}
+
+type generateAllResponse struct {
+	Generated int                      `json:"generated"`
+	Failed    int                      `json:"failed"`
+	Failures  []variantFailureResponse `json:"failures"`
+	Items     []imageVariantResponse   `json:"items"`
+}
+
+type variantPurgeResponse struct {
+	PurgedFiles int   `json:"purged_files"`
+	PurgedBytes int64 `json:"purged_bytes"`
+}
+
+func toImageVariantResponse(view useCases.ImageVariantView) imageVariantResponse {
+	response := imageVariantResponse{
+		Name:         view.Variant.Name,
+		Width:        view.Variant.Width,
+		Height:       view.Variant.Height,
+		Fit:          view.Variant.Fit,
+		Format:       view.Variant.Format,
+		OutputWidth:  view.OutputWidth,
+		OutputHeight: view.OutputHeight,
+		OutputFormat: view.OutputFormat,
+		Generated:    view.Generated,
+		URL:          view.URL,
+	}
+	if view.Generated {
+		size := view.Size
+		response.Size = &size
+	}
+	return response
+}
+
+func toImageVariantResponses(views []useCases.ImageVariantView) []imageVariantResponse {
+	items := make([]imageVariantResponse, 0, len(views))
+	for _, view := range views {
+		items = append(items, toImageVariantResponse(view))
+	}
+	return items
+}
+
+func writeImageVariantError(w http.ResponseWriter, err error) {
+	switch {
+	case errors.Is(err, domainImage.ErrVariantNotFound):
+		http.Error(w, apperr.VariantNotFoundErrorMessage, http.StatusNotFound)
+	case errors.Is(err, domainImage.ErrVariantSourceUnsupported):
+		http.Error(w, apperr.VariantSourceUnsupportedErrorMessage, http.StatusUnprocessableEntity)
+	case errors.Is(err, domainImage.ErrSourceTooLarge):
+		http.Error(w, apperr.VariantSourceTooLargeErrorMessage, http.StatusRequestEntityTooLarge)
+	case errors.Is(err, domainImage.ErrVariantSourceUnreadable):
+		http.Error(w, apperr.VariantSourceUnreadableErrorMessage, http.StatusUnsupportedMediaType)
+	default:
+		writeImageError(w, err)
+	}
+}
+
+func (h *Handler) ListVariants(w http.ResponseWriter, r *http.Request) {
+	id, ok := parseImageId(w, r)
+	if !ok {
+		return
+	}
+
+	list, err := h.ListVariantsUseCase.List(id)
+	if err != nil {
+		writeImageVariantError(w, err)
+		return
+	}
+
+	response := imageVariantListResponse{Items: toImageVariantResponses(list.Items)}
+	if list.Unsupported != "" {
+		response.Unsupported = &list.Unsupported
+	}
+	writeJSON(w, http.StatusOK, response)
+}
+
+func (h *Handler) GenerateVariant(w http.ResponseWriter, r *http.Request) {
+	id, ok := parseImageId(w, r)
+	if !ok {
+		return
+	}
+
+	view, err := h.GenerateVariantUseCase.Generate(r.Context(), id, chi.URLParam(r, "name"))
+	if err != nil {
+		writeImageVariantError(w, err)
+		return
+	}
+	writeJSON(w, http.StatusOK, toImageVariantResponse(view))
+}
+
+func (h *Handler) GenerateAllVariants(w http.ResponseWriter, r *http.Request) {
+	id, ok := parseImageId(w, r)
+	if !ok {
+		return
+	}
+
+	result, err := h.GenerateAllUseCase.Generate(r.Context(), id)
+	if err != nil {
+		writeImageVariantError(w, err)
+		return
+	}
+
+	failures := make([]variantFailureResponse, 0, len(result.Failures))
+	for _, failure := range result.Failures {
+		failures = append(failures, variantFailureResponse{Name: failure.Name, Cause: failure.Cause})
+	}
+	writeJSON(w, http.StatusOK, generateAllResponse{
+		Generated: result.Generated,
+		Failed:    result.Failed,
+		Failures:  failures,
+		Items:     toImageVariantResponses(result.Items),
+	})
+}
+
+func (h *Handler) PurgeVariant(w http.ResponseWriter, r *http.Request) {
+	id, ok := parseImageId(w, r)
+	if !ok {
+		return
+	}
+
+	purged, err := h.PurgeVariantUseCase.Purge(r.Context(), id, chi.URLParam(r, "name"))
+	if err != nil {
+		writeImageVariantError(w, err)
+		return
+	}
+	writeJSON(w, http.StatusOK, variantPurgeResponse{PurgedFiles: purged.Files, PurgedBytes: purged.Bytes})
+}

api/handlers/settings/settingsHandler.go

@@ -1,21 +1,105 @@
 package settings
 
 import (
+	"RenewCMS/api/pkg/apperr"
+	validator "RenewCMS/api/pkg/validator"
+	"RenewCMS/internal/domain/audit"
 	"RenewCMS/internal/infrastructure/useCases"
 	"encoding/json"
+	"errors"
+	"io"
 	"net/http"
+	"time"
 )
 
 type Handler struct {
 	GetSettingsUseCase             *useCases.GetSettingsUseCase
+	GetActivityRetentionUseCase    *useCases.GetActivityRetentionUseCase
+	UpdateActivityRetentionUseCase *useCases.UpdateActivityRetentionUseCase
 }
 
-func NewHandler(getSettings *useCases.GetSettingsUseCase) *Handler {
-	return &Handler{GetSettingsUseCase: getSettings}
+type UpdateSettingsRequest struct {
+	ActivityRetentionDays  *int `json:"activity_retention_days" validate:"omitempty,oneof=0 30 90 365"`
+	ActivityRetentionMaxGB *int `json:"activity_retention_max_gb" validate:"omitempty,oneof=0 1 5 10 25 50"`
+}
+
+type settingsResponse struct {
+	Version                    string     `json:"version"`
+	ActivityRetentionDays      int        `json:"activity_retention_days"`
+	ActivityRetentionMaxGB     int        `json:"activity_retention_max_gb"`
+	ActivityLogSizeBytes       int64      `json:"activity_log_size_bytes"`
+	ActivityLastCleanupAt      *time.Time `json:"activity_last_cleanup_at"`
+	ActivityLastCleanupRemoved int        `json:"activity_last_cleanup_removed"`
+	ActivityNextCleanupAt      *time.Time `json:"activity_next_cleanup_at"`
+}
+
+func NewHandler(getSettings *useCases.GetSettingsUseCase, getRetention *useCases.GetActivityRetentionUseCase, updateRetention *useCases.UpdateActivityRetentionUseCase) *Handler {
+	return &Handler{GetSettingsUseCase: getSettings, GetActivityRetentionUseCase: getRetention, UpdateActivityRetentionUseCase: updateRetention}
 }
 
 func (h *Handler) GetSettings(w http.ResponseWriter, _ *http.Request) {
-	body, err := json.Marshal(h.GetSettingsUseCase.GetSettings())
+	retention, err := h.GetActivityRetentionUseCase.GetActivityRetention()
+	if err != nil {
+		http.Error(w, "Internal server error", http.StatusInternalServerError)
+		return
+	}
+	h.write(w, retention)
+}
+
+func (h *Handler) UpdateSettings(w http.ResponseWriter, r *http.Request) {
+	body, err := io.ReadAll(r.Body)
+	if err != nil || hasNullValue(body) {
+		http.Error(w, apperr.BodyErrorMessage, http.StatusBadRequest)
+		return
+	}
+	var request UpdateSettingsRequest
+	if err := json.Unmarshal(body, &request); err != nil {
+		http.Error(w, apperr.BodyErrorMessage, http.StatusBadRequest)
+		return
+	}
+	if err := validator.Validate.Struct(request); err != nil {
+		http.Error(w, apperr.BodyErrorMessage, http.StatusBadRequest)
+		return
+	}
+
+	retention, err := h.UpdateActivityRetentionUseCase.UpdateActivityRetention(r.Context(), useCases.UpdateActivityRetentionCommand{
+		Days:  request.ActivityRetentionDays,
+		MaxGB: request.ActivityRetentionMaxGB,
+	})
+	if err != nil {
+		if errors.Is(err, audit.ErrInvalidRetention) {
+			http.Error(w, apperr.BodyErrorMessage, http.StatusBadRequest)
+			return
+		}
+		http.Error(w, "Internal server error", http.StatusInternalServerError)
+		return
+	}
+	h.write(w, retention)
+}
+
+func hasNullValue(body []byte) bool {
+	var fields map[string]json.RawMessage
+	if err := json.Unmarshal(body, &fields); err != nil {
+		return false
+	}
+	for _, value := range fields {
+		if string(value) == "null" {
+			return true
+		}
+	}
+	return false
+}
+
+func (h *Handler) write(w http.ResponseWriter, retention audit.Settings) {
+	body, err := json.Marshal(settingsResponse{
+		Version:                    h.GetSettingsUseCase.GetSettings().Version,
+		ActivityRetentionDays:      retention.RetentionDays,
+		ActivityRetentionMaxGB:     retention.RetentionMaxGB,
+		ActivityLogSizeBytes:       retention.LogSizeBytes,
+		ActivityLastCleanupAt:      retention.LastCleanupAt,
+		ActivityLastCleanupRemoved: retention.LastCleanupRemoved,
+		ActivityNextCleanupAt:      retention.NextCleanupAt,
+	})
 	if err != nil {
 		http.Error(w, "Internal server error", http.StatusInternalServerError)
 		return

api/handlers/staticimages/staticImagesHandler.go

@@ -1,11 +1,15 @@
 package staticimages
 
 import (
+	"RenewCMS/api/pkg/apperr"
+	"RenewCMS/internal/domain/image"
+	"RenewCMS/internal/infrastructure/useCases"
+	"encoding/json"
+	"errors"
 	"io"
-	"io/fs"
 	"net/http"
-	"os"
 	"path"
+	"strconv"
 	"strings"
 	"time"
 
@@ -15,51 +19,147 @@ import (
 const cacheControl = "public, no-cache"
 const svgContentSecurityPolicy = "default-src 'none'; style-src 'unsafe-inline'; sandbox"
 const fallbackContentType = "application/octet-stream"
+const unknownVariantCode = "unknown_variant"
+const unsupportedParameterCode = "unsupported_parameter"
 
 var contentTypeExtensions = map[string]string{
 	".png":  "image/png",
 	".jpeg": "image/jpeg",
 	".webp": "image/webp",
 	".svg":  "image/svg+xml",
+	".gif":  "image/gif",
 }
 
 type Handler struct {
-	uploadDir fs.FS
+	openMedia    *useCases.OpenMediaUseCase
+	serveVariant *useCases.ServeVariantUseCase
 	modTime      time.Time
 }
 
-func NewHandler(uploadDir string) *Handler {
+func NewHandler(openMedia *useCases.OpenMediaUseCase, serveVariant *useCases.ServeVariantUseCase) *Handler {
 	return &Handler{
-		uploadDir: os.DirFS(uploadDir),
+		openMedia:    openMedia,
+		serveVariant: serveVariant,
 		modTime:      time.Now(),
 	}
 }
 
+type requestErrorBody struct {
+	Status  int    `json:"status"`
+	Error   string `json:"error"`
+	Message string `json:"message"`
+	Detail  string `json:"detail"`
+}
+
 func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 	w.Header().Set("X-Content-Type-Options", "nosniff")
 
 	cleaned := cleanPath(requestedPath(r))
-	file, stat, ok := h.openFile(cleaned)
-	if !ok {
+	served, err := h.serveVariant.Serve(variantRequestFrom(r, cleaned))
+	if err != nil {
+		writeServeError(w, r, err)
+		return
+	}
+	switch {
+	case served.NotModified:
+		writeNotModified(w, served)
+	case served.Original:
+		h.serveOriginal(w, r, cleaned)
+	default:
+		serveVariantFile(w, r, cleaned, served)
+	}
+}
+
+func variantRequestFrom(r *http.Request, storedName string) useCases.ServeVariantRequest {
+	query := r.URL.Query()
+	request := useCases.ServeVariantRequest{Context: r.Context(), StoredName: storedName, IfNoneMatch: r.Header.Get("If-None-Match")}
+	for parameter := range query {
+		request.Parameters = append(request.Parameters, parameter)
+	}
+	if query.Has(image.VariantQueryParameter) {
+		name := query.Get(image.VariantQueryParameter)
+		request.Variant = &name
+	}
+	return request
+}
+
+func writeServeError(w http.ResponseWriter, r *http.Request, err error) {
+	switch {
+	case errors.Is(err, image.ErrUnknownVariant):
+		writeRequestError(w, unknownVariantCode, apperr.VariantUnknownMessage, err)
+	case errors.Is(err, image.ErrUnsupportedParameter):
+		writeRequestError(w, unsupportedParameterCode, apperr.VariantUnsupportedParameterMessage, err)
+	case errors.Is(err, image.ErrBlobNotFound), errors.Is(err, image.ErrImageNotFound):
+		http.NotFound(w, r)
+	case errors.Is(err, image.ErrSourceTooLarge):
+		http.Error(w, apperr.VariantSourceTooLargeErrorMessage, http.StatusRequestEntityTooLarge)
+	default:
+		http.Error(w, "Unable to read the file", http.StatusInternalServerError)
+	}
+}
+
+func writeRequestError(w http.ResponseWriter, code string, message string, err error) {
+	body, marshalErr := json.Marshal(requestErrorBody{
+		Status:  http.StatusBadRequest,
+		Error:   code,
+		Message: message,
+		Detail:  image.VariantRequestDetail(err),
+	})
+	if marshalErr != nil {
+		http.Error(w, "Unable to read the file", http.StatusInternalServerError)
+		return
+	}
+	w.Header().Set("Content-Type", "application/json")
+	w.WriteHeader(http.StatusBadRequest)
+	_, _ = w.Write(body)
+}
+
+func writeNotModified(w http.ResponseWriter, served useCases.ServedVariant) {
+	w.Header().Set("ETag", served.ETag)
+	w.Header().Set("Cache-Control", cacheControl)
+	w.WriteHeader(http.StatusNotModified)
+}
+
+func serveVariantFile(w http.ResponseWriter, r *http.Request, name string, served useCases.ServedVariant) {
+	defer served.Content.Close()
+	w.Header().Set("ETag", served.ETag)
+	serveContent(w, r, name, served.ContentType, image.Blob{Content: served.Content, Size: served.Size, ModTime: served.ModTime})
+}
+
+func (h *Handler) serveOriginal(w http.ResponseWriter, r *http.Request, name string) {
+	blob, err := h.openMedia.Open(name)
+	if errors.Is(err, image.ErrBlobNotFound) {
 		http.NotFound(w, r)
 		return
 	}
-	defer file.Close()
-
-	content, ok := file.(io.ReadSeeker)
-	if !ok {
-		http.Error(w, "File not seekable", http.StatusInternalServerError)
+	if err != nil {
+		http.Error(w, "Unable to read the file", http.StatusInternalServerError)
 		return
 	}
+	defer blob.Content.Close()
 
-	contentType := contentTypeFor(cleaned)
+	serveContent(w, r, name, contentTypeFor(name), blob)
+}
+
+func serveContent(w http.ResponseWriter, r *http.Request, name string, contentType string, blob image.Blob) {
 	w.Header().Set("Content-Type", contentType)
 	w.Header().Set("Cache-Control", cacheControl)
 	if contentType == "image/svg+xml" {
 		w.Header().Set("Content-Security-Policy", svgContentSecurityPolicy)
 	}
 
-	http.ServeContent(w, r, cleaned, stat.ModTime(), content)
+	if content, ok := blob.Content.(io.ReadSeeker); ok {
+		http.ServeContent(w, r, name, blob.ModTime, content)
+		return
+	}
+	w.Header().Set("Content-Length", strconv.FormatInt(blob.Size, 10))
+	if !blob.ModTime.IsZero() {
+		w.Header().Set("Last-Modified", blob.ModTime.UTC().Format(http.TimeFormat))
+	}
+	w.WriteHeader(http.StatusOK)
+	if r.Method != http.MethodHead {
+		_, _ = io.Copy(w, blob.Content)
+	}
 }
 
 func requestedPath(r *http.Request) string {
@@ -73,22 +173,6 @@ func cleanPath(p string) string {
 	return strings.TrimPrefix(path.Clean("/"+p), "/")
 }
 
-func (h *Handler) openFile(p string) (fs.File, fs.FileInfo, bool) {
-	if p == "" || p == "." {
-		return nil, nil, false
-	}
-	file, err := h.uploadDir.Open(p)
-	if err != nil {
-		return nil, nil, false
-	}
-	stat, err := file.Stat()
-	if err != nil || stat.IsDir() {
-		file.Close()
-		return nil, nil, false
-	}
-	return file, stat, true
-}
-
 func contentTypeFor(p string) string {
 	ext := path.Ext(p)
 	if contentType, ok := contentTypeExtensions[ext]; ok {

api/handlers/update/updateHandler.go

@@ -47,7 +47,7 @@ func (h *Handler) GetStatus(w http.ResponseWriter, r *http.Request) {
 }
 
 func (h *Handler) Check(w http.ResponseWriter, r *http.Request) {
-	if _, err := h.CheckForUpdateUseCase.Check(); err != nil {
+	if _, err := h.CheckForUpdateUseCase.Check(r.Context()); err != nil {
 		http.Error(w, "Internal server error", http.StatusInternalServerError)
 		return
 	}
@@ -58,8 +58,8 @@ func (h *Handler) Check(w http.ResponseWriter, r *http.Request) {
 	writeStatus(w, http.StatusOK, h.GetUpdateStatusUseCase.GetStatus(isOwner))
 }
 
-func (h *Handler) Download(w http.ResponseWriter, _ *http.Request) {
-	status, err := h.StartUpdateDownloadUseCase.Start()
+func (h *Handler) Download(w http.ResponseWriter, r *http.Request) {
+	status, err := h.StartUpdateDownloadUseCase.Start(r.Context())
 	if err != nil {
 		writeDownloadError(w, err)
 		return
@@ -77,7 +77,7 @@ func (h *Handler) Restart(w http.ResponseWriter, r *http.Request) {
 		http.Error(w, apperr.UnauthorizedErrorMessage, http.StatusUnauthorized)
 		return
 	}
-	status, err := h.RequestRestartUseCase.Request(userId, kind)
+	status, err := h.RequestRestartUseCase.Request(r.Context(), userId, kind)
 	if err != nil {
 		writeRestartError(w, err)
 		return

api/handlers/user/inviteHandler.go

@@ -82,7 +82,7 @@ func (h *InviteHandler) CreateInvite(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	created, err := h.CreateInviteUseCase.CreateInvite(useCases.CreateInviteCommand{
+	created, err := h.CreateInviteUseCase.CreateInvite(r.Context(), useCases.CreateInviteCommand{
 		Email:     request.Email,
 		InvitedBy: userId,
 	})
@@ -124,7 +124,7 @@ func (h *InviteHandler) CancelInvite(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	if err := h.CancelInviteUseCase.CancelInvite(id); err != nil {
+	if err := h.CancelInviteUseCase.CancelInvite(r.Context(), id); err != nil {
 		writeManageInviteError(w, err)
 		return
 	}
@@ -144,7 +144,7 @@ func (h *InviteHandler) RenewInvite(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	renewed, err := h.RenewInviteUseCase.RenewInvite(useCases.RenewInviteCommand{ID: id, RenewedBy: userId})
+	renewed, err := h.RenewInviteUseCase.RenewInvite(r.Context(), useCases.RenewInviteCommand{ID: id, RenewedBy: userId})
 	if err != nil {
 		writeManageInviteError(w, err)
 		return

api/handlers/user/userHandler.go

@@ -46,7 +46,7 @@ func (h *Handler) UpdateMe(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	updatedUser, err := h.UpdateProfileUseCase.UpdateDisplayName(userId, *request.DisplayName)
+	updatedUser, err := h.UpdateProfileUseCase.UpdateDisplayName(r.Context(), userId, *request.DisplayName)
 	if err != nil {
 		if errors.Is(err, user.ErrInvalidDisplayName) {
 			http.Error(w, apperr.DisplayNameErrorMessage, http.StatusBadRequest)

api/middleware/apiKey.go

@@ -0,0 +1,118 @@
+package middleware
+
+import (
+	"RenewCMS/api/pkg/apperr"
+	"RenewCMS/internal/domain/apikey"
+	"RenewCMS/internal/infrastructure/useCases"
+	"context"
+	"errors"
+	"net/http"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/go-chi/jwtauth/v5"
+	"github.com/lestrrat-go/jwx/v2/jwt"
+)
+
+const bearerScheme = "bearer "
+
+type apiKeyIdContextKey struct{}
+
+type apiKeyNameContextKey struct{}
+
+func bearerAPIKey(r *http.Request) (string, bool) {
+	header := r.Header.Get("Authorization")
+	if len(header) < len(bearerScheme) || !strings.EqualFold(header[:len(bearerScheme)], bearerScheme) {
+		return "", false
+	}
+
+	credential := strings.TrimSpace(header[len(bearerScheme):])
+	return credential, strings.HasPrefix(credential, apikey.RawKeyPrefix)
+}
+
+func apiKeyIdFrom(r *http.Request) (uint32, bool) {
+	id, ok := r.Context().Value(apiKeyIdContextKey{}).(uint32)
+	return id, ok
+}
+
+func apiKeyNameFrom(r *http.Request) string {
+	name, _ := r.Context().Value(apiKeyNameContextKey{}).(string)
+	return name
+}
+
+func RequireSession(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if _, isKey := bearerAPIKey(r); isKey {
+			http.Error(w, apperr.SessionRequiredErrorMessage, http.StatusForbidden)
+			return
+		}
+		next.ServeHTTP(w, r)
+	})
+}
+
+func RejectAPIKey(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if _, authenticatedByKey := apiKeyIdFrom(r); authenticatedByKey {
+			http.Error(w, apperr.UnauthorizedErrorMessage, http.StatusUnauthorized)
+			return
+		}
+		next.ServeHTTP(w, r)
+	})
+}
+
+func APIKeyAuth(authenticate *useCases.AuthenticateAPIKeyUseCase, maxRequests int, window time.Duration) func(http.Handler) http.Handler {
+	limiter := newKeyedRateLimiter(maxRequests, window, apiKeyRateLimitKey)
+
+	return func(next http.Handler) http.Handler {
+		limited := limiter(next)
+		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			rawKey, isKey := bearerAPIKey(r)
+			if !isKey {
+				next.ServeHTTP(w, r)
+				return
+			}
+
+			authenticated, err := authenticate.AuthenticateAPIKey(rawKey)
+			if err != nil {
+				writeAPIKeyError(w, err)
+				return
+			}
+
+			token, err := sessionTokenFor(authenticated)
+			if err != nil {
+				http.Error(w, "Internal server error", http.StatusInternalServerError)
+				return
+			}
+
+			ctx := jwtauth.NewContext(r.Context(), token, nil)
+			ctx = context.WithValue(ctx, apiKeyIdContextKey{}, authenticated.Key.ID)
+			ctx = context.WithValue(ctx, apiKeyNameContextKey{}, authenticated.Key.Name)
+			limited.ServeHTTP(w, r.WithContext(ctx))
+		})
+	}
+}
+
+func writeAPIKeyError(w http.ResponseWriter, err error) {
+	if errors.Is(err, apikey.ErrAPIKeyInvalid) {
+		http.Error(w, apperr.UnauthorizedErrorMessage, http.StatusUnauthorized)
+		return
+	}
+	http.Error(w, "Internal server error", http.StatusInternalServerError)
+}
+
+func sessionTokenFor(authenticated useCases.AuthenticatedAPIKey) (jwt.Token, error) {
+	token := jwt.New()
+	if err := token.Set("user_id", float64(authenticated.User.ID)); err != nil {
+		return nil, err
+	}
+	if err := token.Set("token_version", float64(authenticated.User.TokenVersion)); err != nil {
+		return nil, err
+	}
+	return token, nil
+}
+
+func apiKeyRateLimitKey(r *http.Request) string {
+	id, _ := apiKeyIdFrom(r)
+	return strconv.FormatUint(uint64(id), 10)
+}

api/middleware/auditContext.go

@@ -0,0 +1,64 @@
+package middleware
+
+import (
+	"RenewCMS/api/pkg/claims"
+	"RenewCMS/internal/domain/audit"
+	"RenewCMS/internal/infrastructure/useCases"
+	"net/http"
+)
+
+func AuditContext(getUser *useCases.GetUserUseCase, trustedProxies []string) func(http.Handler) http.Handler {
+	return func(next http.Handler) http.Handler {
+		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			origin := audit.Origin{
+				Actor:     auditActor(getUser, r),
+				Source:    auditSource(r),
+				IP:        clientIP(r, trustedProxies),
+				UserAgent: truncatedUserAgent(r),
+			}
+			next.ServeHTTP(w, r.WithContext(audit.WithOrigin(r.Context(), origin)))
+		})
+	}
+}
+
+func auditActor(getUser *useCases.GetUserUseCase, r *http.Request) audit.Actor {
+	if id, ok := apiKeyIdFrom(r); ok {
+		return audit.APIKeyActor(id, apiKeyNameFrom(r))
+	}
+	userId, ok := claims.UserId(r)
+	if !ok {
+		return audit.AnonymousActor("")
+	}
+	current, err := getUser.GetUser(userId)
+	if err != nil {
+		return audit.AnonymousActor("")
+	}
+	tokenVersion, ok := claims.TokenVersion(r)
+	if !ok || tokenVersion != current.TokenVersion {
+		return audit.AnonymousActor("")
+	}
+	return audit.UserActor(current)
+}
+
+func auditSource(r *http.Request) audit.Source {
+	if _, ok := apiKeyIdFrom(r); ok {
+		return audit.SourceAPIKey
+	}
+	return audit.SourceWeb
+}
+
+func clientIP(r *http.Request, trustedProxies []string) string {
+	realIP := r.Header.Get("X-Real-IP")
+	if realIP != "" && isTrustedProxy(r.RemoteAddr, trustedProxies) {
+		return realIP
+	}
+	return hostOf(r.RemoteAddr)
+}
+
+func truncatedUserAgent(r *http.Request) string {
+	runes := []rune(r.Header.Get("User-Agent"))
+	if len(runes) > audit.MaxUserAgentLength {
+		runes = runes[:audit.MaxUserAgentLength]
+	}
+	return string(runes)
+}

api/middleware/auth.go

@@ -95,3 +95,21 @@ func RequireOwner(getUser *useCases.GetUserUseCase) func(http.Handler) http.Hand
 		})
 	}
 }
+
+func RequireOwnerOrAdmin(getUser *useCases.GetUserUseCase) func(http.Handler) http.Handler {
+	return func(next http.Handler) http.Handler {
+		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			currentUser, ok := resolveCurrentUser(getUser, w, r)
+			if !ok {
+				return
+			}
+
+			if currentUser.Role != user.RoleOwner && currentUser.Role != user.RoleAdmin {
+				http.Error(w, apperr.OwnerOrAdminRequiredErrorMessage, http.StatusForbidden)
+				return
+			}
+
+			next.ServeHTTP(w, r)
+		})
+	}
+}

api/middleware/requireSignedIn.go

@@ -0,0 +1,20 @@
+package middleware
+
+import (
+	"RenewCMS/api/pkg/apperr"
+	"net/http"
+
+	"github.com/go-chi/jwtauth/v5"
+	"github.com/lestrrat-go/jwx/v2/jwt"
+)
+
+func RequireSignedIn(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		token, _, err := jwtauth.FromContext(r.Context())
+		if err != nil || token == nil || jwt.Validate(token) != nil {
+			http.Error(w, apperr.UnauthorizedErrorMessage, http.StatusUnauthorized)
+			return
+		}
+		next.ServeHTTP(w, r)
+	})
+}

api/middleware/securityHeaders.go

@@ -0,0 +1,33 @@
+package middleware
+
+import "net/http"
+
+const contentSecurityPolicy = "default-src 'self'; " +
+	"script-src 'self' 'wasm-unsafe-eval'; " +
+	"style-src 'self' 'unsafe-inline' https://fonts.googleapis.com; " +
+	"font-src 'self' https://fonts.gstatic.com; " +
+	"img-src 'self' data: blob: https:; " +
+	"connect-src 'self'; " +
+	"object-src 'none'; " +
+	"base-uri 'self'; " +
+	"form-action 'self'; " +
+	"frame-ancestors 'none'"
+
+const strictTransportSecurity = "max-age=31536000"
+
+func SecurityHeaders(hsts bool) func(http.Handler) http.Handler {
+	return func(next http.Handler) http.Handler {
+		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			h := w.Header()
+			h.Set("Content-Security-Policy", contentSecurityPolicy)
+			h.Set("X-Content-Type-Options", "nosniff")
+			h.Set("X-Frame-Options", "DENY")
+			h.Set("Referrer-Policy", "strict-origin-when-cross-origin")
+			h.Set("Cross-Origin-Opener-Policy", "same-origin")
+			if hsts {
+				h.Set("Strict-Transport-Security", strictTransportSecurity)
+			}
+			next.ServeHTTP(w, r)
+		})
+	}
+}

api/pkg/apperr/messages.go

@@ -35,3 +35,25 @@ const NothingToUpdateErrorMessage = "There is nothing to update."
 const UpdateRefusedErrorMessage = "This update cannot be downloaded."
 const UpdateRestartMismatchErrorMessage = "The update state changed. Reload the page and try again."
 const ArticleBodyFormatErrorMessage = "The format must be one of: markdown, html, json."
+const APIKeyNotFoundErrorMessage = "API key not found"
+const APIKeyExpiryErrorMessage = "The expiry must be a date in the future."
+const SessionRequiredErrorMessage = "This action needs a real session."
+const OwnerOrAdminRequiredErrorMessage = "Only owners and admins can do this."
+const PurgeConflictErrorMessage = "The library changed, so nothing was purged. Check the new summary and try again."
+const PurgeBusyErrorMessage = "A purge is already running."
+const PurgeIntervalErrorMessage = "Enter a whole number of days between 1 and 365."
+const VariantNotFoundErrorMessage = "Variant not found"
+const VariantNameErrorMessage = "Use lowercase letters, numbers and dashes, 2 to 32 characters."
+const VariantDimensionsErrorMessage = "Width and height must be between 1 and 8000, and one of them is required."
+const VariantFitErrorMessage = "Fit must be cover, contain or inside."
+const VariantQualityErrorMessage = "Quality must be between 1 and 100."
+const VariantInvalidErrorMessage = "The variant is not valid."
+const VariantExistsErrorMessageFormat = "A variant named “%s” already exists. Choose another name."
+const VariantFormatErrorMessageFormat = "Format must be %s."
+const VariantSourceTooLargeErrorMessage = "The source image is too large to generate this variant."
+const VariantSourceUnsupportedErrorMessage = "Variants aren't generated for this format."
+const VariantSourceUnreadableErrorMessage = "The source image can't be read, so this variant can't be generated."
+const CachePurgeScopeErrorMessage = "Scope must be all, unused, variant or image."
+const CachePurgeTargetErrorMessage = "A variant name or an image id is required for this scope."
+const VariantUnknownMessage = "Unknown variant"
+const VariantUnsupportedParameterMessage = "Unsupported parameter"

api/pkg/validator/validator.go

@@ -1,12 +1,14 @@
 package validator
 
 import (
+	"RenewCMS/internal/domain/image"
 	"regexp"
 
 	"github.com/go-playground/validator/v10"
 )
 
 const inviteEmailTag = "inviteemail"
+const variantNameTag = "variantname"
 
 var inviteEmailPattern = regexp.MustCompile(`^[^\s@]+@[^\s@.]+(\.[^\s@.]+)+$`)
 
@@ -15,6 +17,11 @@ var Validate *validator.Validate
 func InitValidator() {
 	Validate = validator.New()
 	_ = Validate.RegisterValidation(inviteEmailTag, isInviteEmail)
+	_ = Validate.RegisterValidation(variantNameTag, isVariantName)
+}
+
+func isVariantName(field validator.FieldLevel) bool {
+	return image.IsValidVariantName(field.Field().String())
 }
 
 func isInviteEmail(field validator.FieldLevel) bool {

api/router.go

@@ -1,9 +1,12 @@
 package api
 
 import (
+	"RenewCMS/api/handlers/activity"
+	"RenewCMS/api/handlers/apikey"
 	"RenewCMS/api/handlers/article"
 	"RenewCMS/api/handlers/auth"
 	"RenewCMS/api/handlers/frontend"
+	"RenewCMS/api/handlers/imagevariant"
 	"RenewCMS/api/handlers/media"
 	"RenewCMS/api/handlers/settings"
 	"RenewCMS/api/handlers/staticimages"
@@ -33,8 +36,22 @@ func GetHelloWorld(w http.ResponseWriter, _ *http.Request) {
 	_, _ = w.Write(msg)
 }
 
-func NewArticleRouter(container *UseCases) http.Handler {
+const (
+	apiKeyMaxRequests = 120
+	apiKeyWindow      = time.Minute
+)
+
+func (c *UseCases) apiKeyAuth() func(http.Handler) http.Handler {
+	c.apiKeyAuthOnce.Do(func() {
+		c.apiKeyAuthMiddleware = middleware.APIKeyAuth(c.AuthenticateAPIKeyUseCase, apiKeyMaxRequests, apiKeyWindow)
+	})
+	return c.apiKeyAuthMiddleware
+}
+
+func NewArticleRouter(container *UseCases, trustedProxies []string) http.Handler {
 	r := chi.NewRouter()
+	r.Use(container.apiKeyAuth())
+	r.Use(middleware.AuditContext(container.GetUserUseCase, trustedProxies))
 
 	articleHandler := article.NewHandler(container.CreateArticleUseCase, container.GetArticleUseCase, container.ListArticlesUseCase, container.DeleteArticleUseCase, container.UpdateArticleUseCase, container.GetUserUseCase)
 
@@ -57,6 +74,8 @@ func NewArticleRouter(container *UseCases) http.Handler {
 
 func NewAuthRouter(container *UseCases, isProduction bool, rateLimit config.AuthRateLimitSettings, trustedProxies []string) http.Handler {
 	r := chi.NewRouter()
+	r.Use(jwtauth.Verifier(container.Token))
+	r.Use(middleware.AuditContext(container.GetUserUseCase, trustedProxies))
 
 	loginHandler := auth.NewLoginHandler(container.Token, container.CreateUserUseCase, container.AuthenticateUserUseCase, isProduction)
 	verificationHandler := auth.NewVerificationHandler(container.VerifyUserUseCase, container.CancelRegistrationUseCase, isProduction)
@@ -85,11 +104,18 @@ func NewAuthRouter(container *UseCases, isProduction bool, rateLimit config.Auth
 		r.Post("/invite/accept", acceptInviteHandler.AcceptInvite)
 	})
 	r.Group(func(r chi.Router) {
+		r.Use(middleware.RequireSession)
 		r.Use(jwtauth.Verifier(container.Token))
 		r.Use(jwtauth.Authenticator(container.Token))
 		r.Use(middleware.RequireCurrentToken(container.GetUserUseCase))
 		r.Post("/verify", verificationHandler.Verify)
 		r.Delete("/register", verificationHandler.CancelRegistration)
+	})
+	r.Group(func(r chi.Router) {
+		r.Use(jwtauth.Verifier(container.Token))
+		r.Use(container.apiKeyAuth())
+		r.Use(jwtauth.Authenticator(container.Token))
+		r.Use(middleware.RequireCurrentToken(container.GetUserUseCase))
 		r.Get("/me", meHandler.Me)
 	})
 	return r
@@ -102,6 +128,8 @@ func NewUserRouter(container *UseCases, rateLimit config.AuthRateLimitSettings,
 	inviteHandler := user.NewInviteHandler(container.CreateInviteUseCase, container.CancelInviteUseCase, container.RenewInviteUseCase, container.ListUsersAndInvitesUseCase)
 
 	r.Use(jwtauth.Verifier(container.Token))
+	r.Use(container.apiKeyAuth())
+	r.Use(middleware.AuditContext(container.GetUserUseCase, trustedProxies))
 	r.Use(jwtauth.Authenticator(container.Token))
 	r.Use(middleware.RequireCurrentToken(container.GetUserUseCase))
 	r.Use(middleware.RequireVerifiedUser(container.GetUserUseCase))
@@ -118,16 +146,51 @@ func NewUserRouter(container *UseCases, rateLimit config.AuthRateLimitSettings,
 	return r
 }
 
-func NewSettingsRouter(container *UseCases) http.Handler {
+func NewSettingsRouter(container *UseCases, trustedProxies []string) http.Handler {
 	r := chi.NewRouter()
 
-	settingsHandler := settings.NewHandler(container.GetSettingsUseCase)
+	settingsHandler := settings.NewHandler(container.GetSettingsUseCase, container.GetActivityRetentionUseCase, container.UpdateActivityRetentionUseCase)
 
+	r.Group(func(r chi.Router) {
 		r.Use(jwtauth.Verifier(container.Token))
+		r.Use(container.apiKeyAuth())
 		r.Use(jwtauth.Authenticator(container.Token))
 		r.Use(middleware.RequireCurrentToken(container.GetUserUseCase))
 		r.Use(middleware.RequireVerifiedUser(container.GetUserUseCase))
 		r.Get("/", settingsHandler.GetSettings)
+	})
+	r.Group(func(r chi.Router) {
+		r.Use(middleware.RequireSession)
+		r.Use(jwtauth.Verifier(container.Token))
+		r.Use(middleware.AuditContext(container.GetUserUseCase, trustedProxies))
+		r.Use(middleware.RequireSignedIn)
+		r.Use(jwtauth.Authenticator(container.Token))
+		r.Use(middleware.RequireCurrentToken(container.GetUserUseCase))
+		r.Use(middleware.RequireVerifiedUser(container.GetUserUseCase))
+		r.Use(middleware.RequireOwner(container.GetUserUseCase))
+		r.Patch("/", settingsHandler.UpdateSettings)
+	})
+	return r
+}
+
+func NewActivityRouter(container *UseCases, trustedProxies []string) http.Handler {
+	r := chi.NewRouter()
+
+	activityHandler := activity.NewHandler(container.ListActivityUseCase, container.GetActivitySummaryUseCase, container.ExportActivityUseCase)
+
+	r.Use(middleware.RequireSession)
+	r.Use(jwtauth.Verifier(container.Token))
+	r.Use(middleware.AuditContext(container.GetUserUseCase, trustedProxies))
+	r.Use(middleware.RequireSignedIn)
+	r.Use(jwtauth.Authenticator(container.Token))
+	r.Use(middleware.RequireCurrentToken(container.GetUserUseCase))
+	r.Use(middleware.RequireVerifiedUser(container.GetUserUseCase))
+	r.Get("/", activityHandler.List)
+	r.Group(func(r chi.Router) {
+		r.Use(middleware.RequireOwnerOrAdmin(container.GetUserUseCase))
+		r.Get("/summary", activityHandler.Summary)
+		r.Get("/export", activityHandler.Export)
+	})
 	return r
 }
 
@@ -138,12 +201,14 @@ const (
 	updateDownloadWindow      = time.Minute
 )
 
-func NewSystemRouter(container *UseCases) http.Handler {
+func NewSystemRouter(container *UseCases, trustedProxies []string) http.Handler {
 	r := chi.NewRouter()
 
 	updateHandler := update.NewHandler(container.GetUpdateStatusUseCase, container.CheckForUpdateUseCase, container.StartUpdateDownloadUseCase, container.RequestRestartUseCase, container.GetUserUseCase)
 
+	r.Use(middleware.RequireSession)
 	r.Use(jwtauth.Verifier(container.Token))
+	r.Use(middleware.AuditContext(container.GetUserUseCase, trustedProxies))
 	r.Use(jwtauth.Authenticator(container.Token))
 	r.Use(middleware.RequireCurrentToken(container.GetUserUseCase))
 	r.Use(middleware.RequireVerifiedUser(container.GetUserUseCase))
@@ -165,15 +230,50 @@ func NewSystemRouter(container *UseCases) http.Handler {
 	return r
 }
 
-func NewMediaRouter(container *UseCases) http.Handler {
+func NewAPIKeyRouter(container *UseCases, trustedProxies []string) http.Handler {
 	r := chi.NewRouter()
 
-	mediaHandler := media.NewHandler(container.CreateImageUseCase, container.ListMediaUseCase, container.RenameMediaUseCase, container.DeleteMediaUseCase, container.MergeMediaUseCase, container.GetMediaUsageUseCase)
+	apiKeyHandler := apikey.NewHandler(container.CreateAPIKeyUseCase, container.ListAPIKeysUseCase, container.RevokeAPIKeyUseCase)
 
+	r.Use(middleware.RequireSession)
 	r.Use(jwtauth.Verifier(container.Token))
+	r.Use(middleware.AuditContext(container.GetUserUseCase, trustedProxies))
 	r.Use(jwtauth.Authenticator(container.Token))
 	r.Use(middleware.RequireCurrentToken(container.GetUserUseCase))
 	r.Use(middleware.RequireVerifiedUser(container.GetUserUseCase))
+	r.Post("/", apiKeyHandler.Create)
+	r.Get("/", apiKeyHandler.List)
+	r.Delete("/{id}", apiKeyHandler.Revoke)
+	return r
+}
+
+func NewMediaRouter(container *UseCases, trustedProxies []string) http.Handler {
+	r := chi.NewRouter()
+
+	mediaHandler := media.NewHandler(container.CreateImageUseCase, container.ListMediaUseCase, container.RenameMediaUseCase, container.DeleteMediaUseCase, container.MergeMediaUseCase, container.GetMediaUsageUseCase, container.GetPurgeSettingsUseCase, container.UpdatePurgeSettingsUseCase, container.PreviewPurgeUseCase, container.RunPurgeUseCase, container.ListImageVariantsUseCase, container.GenerateImageVariantUseCase, container.GenerateAllImageVariantsUseCase, container.PurgeImageVariantUseCase, container.GenerateVariantsOnUploadUseCase)
+
+	r.Use(jwtauth.Verifier(container.Token))
+	r.Use(container.apiKeyAuth())
+	r.Use(middleware.AuditContext(container.GetUserUseCase, trustedProxies))
+	r.Use(middleware.RequireSignedIn)
+	r.Use(jwtauth.Authenticator(container.Token))
+	r.Use(middleware.RequireCurrentToken(container.GetUserUseCase))
+	r.Use(middleware.RequireVerifiedUser(container.GetUserUseCase))
+	r.Group(func(r chi.Router) {
+		r.Use(middleware.RequireOwnerOrAdmin(container.GetUserUseCase))
+		r.Get("/purge-settings", mediaHandler.GetPurgeSettings)
+		r.Patch("/purge-settings", mediaHandler.UpdatePurgeSettings)
+		r.Get("/purge-preview", mediaHandler.PreviewPurge)
+		r.Post("/purge", mediaHandler.RunPurge)
+	})
+	r.Group(func(r chi.Router) {
+		r.Use(middleware.RejectAPIKey)
+		r.Use(middleware.RequireOwnerOrAdmin(container.GetUserUseCase))
+		r.Get("/{id}/variants", mediaHandler.ListVariants)
+		r.Post("/{id}/variants", mediaHandler.GenerateAllVariants)
+		r.Post("/{id}/variants/{name}", mediaHandler.GenerateVariant)
+		r.Delete("/{id}/variants/{name}", mediaHandler.PurgeVariant)
+	})
 	r.Get("/", mediaHandler.List)
 	r.Post("/", mediaHandler.Upload)
 	r.Post("/merge", mediaHandler.Merge)
@@ -183,6 +283,29 @@ func NewMediaRouter(container *UseCases) http.Handler {
 	return r
 }
 
+func NewImageVariantRouter(container *UseCases, trustedProxies []string) http.Handler {
+	r := chi.NewRouter()
+
+	variantHandler := imagevariant.NewHandler(container.ListVariantsUseCase, container.CreateVariantUseCase, container.UpdateVariantUseCase, container.SetVariantEnabledUseCase, container.DeleteVariantUseCase, container.PurgeVariantUseCase, container.GetVariantCacheStatsUseCase, container.PurgeVariantCacheUseCase)
+
+	r.Use(jwtauth.Verifier(container.Token))
+	r.Use(middleware.AuditContext(container.GetUserUseCase, trustedProxies))
+	r.Use(middleware.RequireSignedIn)
+	r.Use(jwtauth.Authenticator(container.Token))
+	r.Use(middleware.RequireCurrentToken(container.GetUserUseCase))
+	r.Use(middleware.RequireVerifiedUser(container.GetUserUseCase))
+	r.Use(middleware.RequireOwnerOrAdmin(container.GetUserUseCase))
+	r.Get("/", variantHandler.List)
+	r.Post("/", variantHandler.Create)
+	r.Get("/cache", variantHandler.CacheStats)
+	r.Post("/cache/purge", variantHandler.PurgeCache)
+	r.Put("/{name}", variantHandler.Update)
+	r.Patch("/{name}", variantHandler.SetEnabled)
+	r.Delete("/{name}", variantHandler.Delete)
+	r.Post("/{name}/purge", variantHandler.Purge)
+	return r
+}
+
 func InitBackendRoutes(container *UseCases, settings config.Settings) *chi.Mux {
 	r := chi.NewRouter()
 
@@ -193,12 +316,15 @@ func InitBackendRoutes(container *UseCases, settings config.Settings) *chi.Mux {
 	r.Get("/", GetHelloWorld)
 	r.Group(func(r chi.Router) {
 		r.Use(jwtauth.Verifier(container.Token))
-		r.Mount("/article", NewArticleRouter(container))
+		r.Mount("/article", NewArticleRouter(container, settings.TrustedProxies))
 	})
 	r.Mount("/user", NewUserRouter(container, settings.AuthRateLimit, settings.TrustedProxies))
-	r.Mount("/settings", NewSettingsRouter(container))
-	r.Mount("/media", NewMediaRouter(container))
-	r.Mount("/system", NewSystemRouter(container))
+	r.Mount("/settings", NewSettingsRouter(container, settings.TrustedProxies))
+	r.Mount("/activity", NewActivityRouter(container, settings.TrustedProxies))
+	r.Mount("/media", NewMediaRouter(container, settings.TrustedProxies))
+	r.Mount("/image-variants", NewImageVariantRouter(container, settings.TrustedProxies))
+	r.Mount("/api-key", NewAPIKeyRouter(container, settings.TrustedProxies))
+	r.Mount("/system", NewSystemRouter(container, settings.TrustedProxies))
 	r.Mount("/auth", NewAuthRouter(container, settings.IsProduction(), settings.AuthRateLimit, settings.TrustedProxies))
 
 	return r
@@ -225,7 +351,7 @@ func enableCorsIfConfigured(r *chi.Mux, origins []string) {
 	}
 	r.Use(cors.Handler(cors.Options{
 		AllowedOrigins:   origins,
-		AllowedMethods:   []string{"GET", "POST", "PUT", "DELETE", "OPTIONS"},
+		AllowedMethods:   []string{"GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"},
 		AllowedHeaders:   []string{"Accept", "Authorization", "Content-Type", "X-CSRF-Token"},
 		ExposedHeaders:   []string{"Link"},
 		AllowCredentials: false,
@@ -238,11 +364,12 @@ func InitRoutes(container *UseCases, settings config.Settings) *chi.Mux {
 	frontend := InitFrontendRoutes(settings.Environment)
 
 	apiRouter := chi.NewRouter()
+	apiRouter.Use(middleware.SecurityHeaders(settings.IsProduction()))
 	enableCorsIfConfigured(apiRouter, settings.CorsAllowedOrigins)
 	apiRouter.Use(chimiddleware.GetHead)
 	apiRouter.Get("/healthz", GetHealth)
 	apiRouter.Mount("/v1", backend)
-	apiRouter.Mount("/static/uploadedImages", staticimages.NewHandler(settings.UploadDir))
+	apiRouter.Mount("/static/uploadedImages", staticimages.NewHandler(container.OpenMediaUseCase, container.ServeVariantUseCase))
 	apiRouter.Mount("/", frontend)
 
 	return apiRouter

cmd/server/main.go

@@ -12,6 +12,7 @@ import (
 	"net/http"
 	"os"
 	"os/signal"
+	"slices"
 	"syscall"
 	"time"
 
@@ -44,11 +45,25 @@ var envDefaults = map[string]string{
 	"ENVIRONMENT":                         "production",
 	"PORT":                                "8080",
 	"DB_FILE":                             "./data/renewcms.db",
+	config.EnvDatabaseDriver:              config.DefaultDatabaseDriver,
+	"DB_TLS":                              config.DefaultDatabaseTLS,
+	"DB_SSLMODE":                          config.DefaultDatabaseSSLMode,
+	"DB_MAX_OPEN_CONNS":                   config.DefaultMaxOpenConns,
+	"DB_MAX_IDLE_CONNS":                   config.DefaultMaxIdleConns,
+	"DB_CONN_MAX_LIFETIME_SECONDS":        config.DefaultConnMaxLifetimeSeconds,
 	"UPLOAD_DIR":                          "./data/uploads",
+	config.EnvStorageDriver:               config.DefaultStorageDriver,
+	"S3_REGION":                           config.DefaultS3Region,
+	"S3_PATH_STYLE":                       config.DefaultS3PathStyle,
+	"S3_TLS":                              config.DefaultS3TLS,
 	"AUTH_RATE_LIMIT_MAX_ATTEMPTS":        "5",
 	"AUTH_RATE_LIMIT_WINDOW_SECONDS":      "60",
 	"TRUSTED_PROXIES":                     "",
 	"UPDATE_FEED_URL":                     "https://git.floriansylvain.fr",
+	"RENEWCMS_CONTAINER":                  "false",
+	config.EnvImageVariantMaxSourceBytes:  config.DefaultImageVariantMaxSourceBytes,
+	config.EnvImageVariantMaxSourcePixels: config.DefaultImageVariantMaxSourcePixels,
+	config.EnvImageVariantMaxConcurrentRenders: config.DefaultImageVariantMaxConcurrentRenders,
 }
 
 const versionFlag = "--version"
@@ -80,7 +95,7 @@ func run() error {
 	validator.InitValidator()
 
 	server := newServer(api.InitRoutes(container, settings), settings)
-	return serveUntilStopped(server, settings, container.RecordRunningInfoUseCase.Record)
+	return serveUntilStopped(server, settings, container.RecordRunningInfoUseCase.Record, container.RunSchedulers)
 }
 
 func initEnvVariables() {
@@ -107,10 +122,13 @@ func applyEnvDefaults() {
 }
 
 func ensureRequiredEnvVars() {
-	for _, envVar := range requiredEnvVars {
-		if _, isSet := os.LookupEnv(envVar); !isSet {
-			panic(fmt.Sprintf("Environment variable %s is not set", envVar))
-		}
+	required := slices.Concat(
+		requiredEnvVars,
+		config.DatabaseRequiredEnvVars(os.Getenv(config.EnvDatabaseDriver)),
+		config.StorageRequiredEnvVars(os.Getenv(config.EnvStorageDriver)),
+	)
+	if err := config.MissingEnvVarError(required, os.LookupEnv); err != nil {
+		panic(err.Error())
 	}
 }
 
@@ -131,9 +149,18 @@ func newServer(handler http.Handler, settings config.Settings) *http.Server {
 	}
 }
 
-func serveUntilStopped(server *http.Server, settings config.Settings, recordRunning func() error) error {
+func serveUntilStopped(server *http.Server, settings config.Settings, recordRunning func() error, runScheduler func(context.Context)) error {
 	stopSignal, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
-	defer stop()
+
+	schedulerDone := make(chan struct{})
+	go func() {
+		defer close(schedulerDone)
+		runScheduler(stopSignal)
+	}()
+	defer func() {
+		stop()
+		<-schedulerDone
+	}()
 
 	serverErr := make(chan error, 1)
 	go listen(server, serverErr, settings, recordRunning)

docker-compose.build.yml

@@ -0,0 +1,7 @@
+services:
+  renewcms:
+    build:
+      context: .
+      args:
+        VERSION: ${VERSION:-dev}
+    image: renewcms:${VERSION:-dev}

docker-compose.mysql.yml

@@ -0,0 +1,51 @@
+services:
+  mysql:
+    image: mysql:8.4
+    restart: unless-stopped
+    environment:
+      MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD:?set MYSQL_ROOT_PASSWORD}
+      MYSQL_DATABASE: renewcms
+      MYSQL_USER: renewcms
+      MYSQL_PASSWORD: ${DB_PASSWORD:?set DB_PASSWORD}
+    volumes:
+      - mysql-data:/var/lib/mysql
+    healthcheck:
+      test: ["CMD-SHELL", "mysqladmin ping -h 127.0.0.1 -u root -p\"$$MYSQL_ROOT_PASSWORD\" --silent"]
+      interval: 10s
+      timeout: 5s
+      retries: 10
+      start_period: 30s
+
+  renewcms:
+    image: ${RENEWCMS_IMAGE:-git.floriansylvain.fr/fsylvain/renewcms:beta}
+    restart: unless-stopped
+    depends_on:
+      mysql:
+        condition: service_healthy
+    env_file:
+      - docker.env
+    environment:
+      DB_DRIVER: mysql
+      DB_HOST: mysql
+      DB_PORT: "3306"
+      DB_NAME: renewcms
+      DB_USER: renewcms
+      DB_PASSWORD: ${DB_PASSWORD:?set DB_PASSWORD}
+      DATA_DIR: /data
+      UPLOAD_DIR: /data/uploads
+      RENEWCMS_CONTAINER: "true"
+    ports:
+      - "8080:8080"
+    volumes:
+      - renewcms-data:/data
+    stop_grace_period: 15s
+    healthcheck:
+      test: ["CMD", "wget", "-qO-", "http://127.0.0.1:8080/healthz"]
+      interval: 30s
+      timeout: 5s
+      retries: 3
+      start_period: 10s
+
+volumes:
+  renewcms-data:
+  mysql-data:

docker-compose.postgres.yml

@@ -0,0 +1,51 @@
+services:
+  postgres:
+    image: postgres:17
+    restart: unless-stopped
+    environment:
+      POSTGRES_DB: renewcms
+      POSTGRES_USER: renewcms
+      POSTGRES_PASSWORD: ${DB_PASSWORD:?set DB_PASSWORD}
+    volumes:
+      - postgres-data:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U renewcms -d renewcms"]
+      interval: 10s
+      timeout: 5s
+      retries: 10
+      start_period: 30s
+
+  renewcms:
+    image: ${RENEWCMS_IMAGE:-git.floriansylvain.fr/fsylvain/renewcms:beta}
+    restart: unless-stopped
+    depends_on:
+      postgres:
+        condition: service_healthy
+    env_file:
+      - docker.env
+    environment:
+      DB_DRIVER: postgres
+      DB_HOST: postgres
+      DB_PORT: "5432"
+      DB_NAME: renewcms
+      DB_USER: renewcms
+      DB_PASSWORD: ${DB_PASSWORD:?set DB_PASSWORD}
+      DB_SSLMODE: disable
+      DATA_DIR: /data
+      UPLOAD_DIR: /data/uploads
+      RENEWCMS_CONTAINER: "true"
+    ports:
+      - "8080:8080"
+    volumes:
+      - renewcms-data:/data
+    stop_grace_period: 15s
+    healthcheck:
+      test: ["CMD", "wget", "-qO-", "http://127.0.0.1:8080/healthz"]
+      interval: 30s
+      timeout: 5s
+      retries: 3
+      start_period: 10s
+
+volumes:
+  renewcms-data:
+  postgres-data:

docker-compose.s3.yml

@@ -0,0 +1,56 @@
+services:
+  seaweedfs:
+    image: ${SEAWEEDFS_IMAGE:-chrislusf/seaweedfs:4.48}
+    restart: unless-stopped
+    command: ["server", "-dir=/data", "-s3", "-s3.port=8333"]
+    environment:
+      AWS_ACCESS_KEY_ID: ${S3_ACCESS_KEY_ID:-renewcms}
+      AWS_SECRET_ACCESS_KEY: ${S3_SECRET_ACCESS_KEY:?set S3_SECRET_ACCESS_KEY}
+    volumes:
+      - seaweedfs-data:/data
+
+  seaweedfs-init:
+    image: ${SEAWEEDFS_IMAGE:-chrislusf/seaweedfs:4.48}
+    restart: "no"
+    depends_on:
+      - seaweedfs
+    entrypoint: ["sh", "-c"]
+    command:
+      - |
+        until echo "s3.bucket.create -name renewcms-media" | timeout 30 weed shell -master=seaweedfs:9333 && echo "s3.bucket.list" | timeout 30 weed shell -master=seaweedfs:9333 | grep -q renewcms-media; do
+          sleep 2
+        done
+
+  renewcms:
+    image: ${RENEWCMS_IMAGE:-git.floriansylvain.fr/fsylvain/renewcms:beta}
+    restart: unless-stopped
+    depends_on:
+      seaweedfs-init:
+        condition: service_completed_successfully
+    env_file:
+      - docker.env
+    environment:
+      STORAGE_DRIVER: s3
+      S3_ENDPOINT: http://seaweedfs:8333
+      S3_BUCKET: renewcms-media
+      S3_REGION: us-east-1
+      S3_ACCESS_KEY_ID: ${S3_ACCESS_KEY_ID:-renewcms}
+      S3_SECRET_ACCESS_KEY: ${S3_SECRET_ACCESS_KEY:?set S3_SECRET_ACCESS_KEY}
+      S3_PATH_STYLE: "true"
+      DB_FILE: /data/renewcms.db
+      RENEWCMS_CONTAINER: "true"
+    ports:
+      - "8080:8080"
+    volumes:
+      - renewcms-data:/data
+    stop_grace_period: 15s
+    healthcheck:
+      test: ["CMD", "wget", "-qO-", "http://127.0.0.1:8080/healthz"]
+      interval: 30s
+      timeout: 5s
+      retries: 3
+      start_period: 10s
+
+volumes:
+  renewcms-data:
+  seaweedfs-data:

docker-compose.yml

@@ -0,0 +1,24 @@
+services:
+  renewcms:
+    image: ${RENEWCMS_IMAGE:-git.floriansylvain.fr/fsylvain/renewcms:beta}
+    restart: unless-stopped
+    env_file:
+      - docker.env
+    environment:
+      DB_FILE: /data/renewcms.db
+      UPLOAD_DIR: /data/uploads
+      RENEWCMS_CONTAINER: "true"
+    ports:
+      - "8080:8080"
+    volumes:
+      - renewcms-data:/data
+    stop_grace_period: 15s
+    healthcheck:
+      test: ["CMD", "wget", "-qO-", "http://127.0.0.1:8080/healthz"]
+      interval: 30s
+      timeout: 5s
+      retries: 3
+      start_period: 10s
+
+volumes:
+  renewcms-data:

docker.env.example

@@ -0,0 +1,34 @@
+PUBLIC_URL=https://cms.example.com
+JWT_SECRET=replace-with-output-of-openssl-rand-hex-32
+SMTP_HOST=smtp.example.com
+SMTP_PORT=465
+SMTP_LOGIN=noreply@example.com
+SMTP_PASSWORD=replace-me
+SMTP_SENDER=noreply@example.com
+
+ENVIRONMENT=production
+CORS_ALLOWED_ORIGINS=
+AUTH_RATE_LIMIT_MAX_ATTEMPTS=5
+AUTH_RATE_LIMIT_WINDOW_SECONDS=60
+TRUSTED_PROXIES=
+DB_DRIVER=sqlite
+DATA_DIR=
+DB_HOST=
+DB_PORT=
+DB_USER=
+DB_PASSWORD=
+DB_NAME=
+DB_TLS=false
+DB_SSLMODE=disable
+DB_MAX_OPEN_CONNS=10
+DB_MAX_IDLE_CONNS=5
+DB_CONN_MAX_LIFETIME_SECONDS=300
+STORAGE_DRIVER=local
+S3_BUCKET=
+S3_REGION=us-east-1
+S3_ENDPOINT=
+S3_ACCESS_KEY_ID=
+S3_SECRET_ACCESS_KEY=
+S3_KEY_PREFIX=
+S3_PATH_STYLE=false
+S3_TLS=true

docs/api.md

@@ -0,0 +1,182 @@
+# API reference
+
+The full, searchable reference is the Integration page of the running app (`/integration`). It
+renders `web/src/data/apiCatalogue.ts`, which is the single source for this page. This file is for
+readers without the UI.
+
+## Base URL
+The origin that serves the app, for example `https://cms.example`. Every path starts with `/v1`,
+for example `https://cms.example/v1/article/`.
+
+## Authentication
+- Public routes need nothing: `GET /v1/article/` and `GET /v1/article/{id}`. They return online
+  articles only.
+- Everything else needs a signed-in browser session (the `jwt` cookie) or an API key:
+  `Authorization: Bearer rcms_...`. Create keys at `/integration/api-keys`. A key acts as its
+  creator, with that user's role, and shows in full once.
+- A key cannot call `POST /v1/auth/verify`, `DELETE /v1/auth/register`, `/v1/api-key/*` or
+  `/v1/system/*`. Those answer 403 "This action needs a real session." An invalid, unknown, expired
+  or revoked key answers 401, even on public routes.
+- Each key can make 120 requests per minute. Beyond that: 429 with a `Retry-After` header.
+
+## Routes a key can call (24)
+| Group | Routes |
+| --- | --- |
+| Articles | GET /v1/article/, GET /v1/article/{id}, POST /v1/article/, PATCH /v1/article/{id}, PATCH /v1/article/{id}/publish, PATCH /v1/article/{id}/unpublish, DELETE /v1/article/{id} |
+| Media | GET /v1/media/, POST /v1/media/, PATCH /v1/media/{id}, DELETE /v1/media/{id}, POST /v1/media/merge, GET /v1/media/{id}/usage, GET /v1/media/purge-settings (owner or admin), PATCH /v1/media/purge-settings (owner or admin), GET /v1/media/purge-preview (owner or admin), POST /v1/media/purge (owner or admin), GET /v1/media/{id}/variants (owner or admin, session only), POST /v1/media/{id}/variants (owner or admin, session only), POST /v1/media/{id}/variants/{name} (owner or admin, session only), DELETE /v1/media/{id}/variants/{name} (owner or admin, session only) |
+| Users and invites | GET /v1/user/, PATCH /v1/user/me, POST /v1/user/invite (owner only), DELETE /v1/user/invite/{id} (owner only), POST /v1/user/invite/{id}/renew (owner only), GET /v1/auth/me |
+| Settings | GET /v1/settings |
+
+## Activity log
+The activity routes are session only: a key answers 403 "This action needs a real session." and a
+key never reads the audit trail. Events are append-only; there is no `POST`, `PUT`, `PATCH` or
+`DELETE` under `/v1/activity`.
+
+| Route | Who | Purpose |
+| --- | --- | --- |
+| `GET /v1/activity` | Any verified user | Filtered, paged events. Owner and admin see every event; any other role is scoped to its own events, and `actor` set to someone else answers 403 "Only owners and admins can do this." |
+| `GET /v1/activity/summary` | Owner, admin | Counts for the range, the previous period, active people and seven-bucket series. |
+| `GET /v1/activity/export` | Owner, admin | The same filters as the list without `page` or `size`, as a `text/csv; charset=utf-8` attachment (`when,actor,action,target,outcome,source,ip`). Cells starting with `=`, `+`, `-` or `@` get a leading quote. |
+
+Query: `q`, `actor` (`user:ID`, `key:ID`, `system`), `category` (`articles`, `media`, `users`,
+`api_keys`, `auth`, `system`), `outcome` (`all`, `success`, `failed`), `security` (`true`), `range`
+(`today`, `7d`, `30d`, `custom`; default `7d`), `from` and `to` (dates, with `custom`), `page` (from
+1) and `size` (25, 50 or 100). Any invalid value answers 400 with the body-mismatch message. Dates
+are UTC. The list answers `{ items, total, page, size }`, newest first (`created_at`, then `id`).
+
+`GET /v1/settings` also returns `activity_retention_days` (30, 90, 365 or 0 for forever, default
+90), `activity_retention_max_gb` (0 for no size limit), `activity_log_size_bytes`,
+`activity_last_cleanup_at` and `activity_last_cleanup_removed`. `PATCH /v1/settings` with
+`{"activity_retention_days": 30}`, `{"activity_retention_max_gb": 5}` or both is session only and
+owner only (403 "Only the owner can do this."); any other value answers 400. The daily cleanup
+removes events past the age limit, then the oldest events until the log fits the size limit.
+Whichever limit is reached first wins.
+
+### What is recorded
+Every real action is recorded by its use case, once, after the change was made (outcome `success`)
+or after the use case refused it (outcome `failed`, with a plain `failure_reason`). Nothing is
+recorded for a read (no `GET`, no list, no public article read, no status poll), for a request that
+fails validation, or for a target that does not exist (404). A failed audit write is logged and
+never changes the response or the change itself.
+
+| Category | Actions |
+| --- | --- |
+| `articles` | `article.create`, `article.edit`, `article.publish`, `article.unpublish`, `article.delete` |
+| `media` | `media.upload`, `media.rename`, `media.delete`, `media.merge`, `media.purge`, `media.variant_create`, `media.variant_update`, `media.variant_delete`, `media.variant_enable`, `media.variant_disable`, `media.variant_purge`, `media.variant_generate_all`, `media.variant_purge_image`, `media.variant_purge_all`, `media.variant_purge_unused` |
+| `users` | `user.register`, `user.verify`, `user.update_profile`, `invite.create`, `invite.cancel`, `invite.renew`, `invite.accept` |
+| `system` | `system.media_purge` (scheduled), `system.update_checked`, `system.update_downloaded`, `system.restart_requested`, `system.activity_cleanup`, `system.activity_retention_changed` |
+
+Target types: `article`, `image`, `image_variant` (id and name are the variant name), `user`, `invite`,
+`api_key` and `release` (id and name are the tag).
+Only the fields `title`, `online`, `body`, `filename`, `display_name`, `width`, `height`, `fit`, `format` and `quality` appear in `changes`, with the
+kinds `text` and `body`; a body edit carries a signed character count delta and never the text. A
+change that leaves a value as it was (same body, same publish state, same file name, same display
+name) records nothing. Params: `media.merge` and `media.purge` and `system.media_purge` carry
+`merged` and `articles_updated`, plus `failed_groups` when a group failed (still outcome `success`);
+`media.variant_generate_all` carries `generated`, `failed` and `causes` (a list of `too_large`,
+`unsupported_format` or `failed`) and is `failed` only when nothing was generated and something failed;
+`media.variant_purge_image` carries `purged_files` and `purged_bytes`; both have an `image` target
+and are recorded only when files were generated or removed;
+`media.variant_purge_all` and `media.variant_purge_unused` (no target) carry `purged_files` and
+`purged_bytes`, the latter also `older_than_days`; a partial purge adds `failed_files` and stays
+`success`, and a purge that removed nothing while some files failed is `failed`; nothing is recorded
+when no file was removed or failed;
+`system.update_checked` carries `update_available`; `system.restart_requested` carries `kind` and,
+for an update, `tag` (it has no target). `system.update_downloaded` is recorded when the job reaches
+`ready` or `failed`, with the origin captured at request time; a refusal at the start is recorded
+immediately. A failed registration or invite acceptance has an `anonymous` actor named by the
+attempted username.
+
+`failure_reason` is one fixed sentence per domain error, matched with `errors.Is`, at most 255
+characters, for example "The title must be between 3 and 200 characters.", "That file name is not
+valid.", "The merge request is not valid.", "A purge is already running.", "Registration is closed
+on this site.", "That invitation has expired.", "The release feed could not be reached." or "The
+update could not be downloaded.". Any other error becomes "Something went wrong on our side. Please
+try again."; the text of the error never reaches the event, the API or the CSV. Passwords, hashes,
+codes, article bodies, file bytes, storage paths and asset urls are never recorded.
+
+Article routes accept `?format=markdown|html|json` (default `markdown`). `GET /v1/media/` accepts
+`q`, `hash`, `cursor`, `filter`, `sort` (`newest`, `oldest`, `name`, `largest` or `total_size`, the
+original plus its generated variants), `variants` (`with` or `without` generated variant files) and
+`limit`. Every item carries `variant_count` and `variant_size` (the index rows of the image and
+their bytes, 0 when none); `counts` stays library-wide. Any other `variants` or `sort` value is 400.
+
+## Image variants
+Owners and admins manage named variants of the stored images. These routes are session only (no API
+key) and sit behind the verified-user check; any other role gets 403 "Only owners and admins can do
+this." Behaviour, caching and the public `?v=<name>` contract are in [image-variants.md](image-variants.md).
+
+| Route | Purpose |
+| --- | --- |
+| `GET /v1/image-variants` | `{ "items": [...] }`, ordered by name. |
+| `POST /v1/image-variants` | Create. 201 with the variant. 409 when the name exists. |
+| `PUT /v1/image-variants/{name}` | Replace the definition (the name in the body is ignored). 200 with the variant and `purged_files`. |
+| `PATCH /v1/image-variants/{name}` | `{ "enabled": true }` or `{ "enabled": false }`. Keeps the generated files. |
+| `DELETE /v1/image-variants/{name}` | 204. Removes the definition and its generated files. |
+| `POST /v1/image-variants/{name}/purge` | `{ "purged_files", "purged_bytes" }`. Keeps the definition. |
+| `GET /v1/image-variants/cache` | Cache statistics, see below. |
+| `POST /v1/image-variants/cache/purge` | Purge generated files by scope, see below. |
+
+A variant is `{ name, width, height, fit, format, quality, generate_on_upload, enabled,
+generated_files, cache_size, created_at, updated_at }`. `width` and `height` are 1 to 8000 or `null`
+(at least one is required), `fit` is `cover`, `contain` or `inside` (default `cover`), `format` is
+`original`, `jpeg`, `png` or `webp` (default `original`), `quality` is 1 to 100 (default 82, `null`
+for `png`), `generate_on_upload` defaults to `false`, `enabled` to `true`, and `cache_size` is in
+bytes. A `PUT` that omits `generate_on_upload` or `enabled` keeps the stored value.
+
+Errors are plain text: 400 for a body that is not valid JSON, 404 "Variant not found", 409 "A variant
+named “thumb” already exists. Choose another name." and 422 with one sentence for the first invalid
+field (name, width and height, fit, format, quality).
+
+### Cache statistics and purge by scope
+
+`GET /v1/image-variants/cache` answers `{ generated_files, disk_used, variants_defined,
+variants_enabled, variants_disabled, rejected_requests, rejected_window_days, unused: { files, bytes,
+days }, by_variant: [{ name, enabled, files, bytes }], top_images: [{ id, filename, url, files, bytes }] }`.
+`by_variant` lists every defined variant by bytes descending then name; `top_images` lists the ten
+images using the most variant bytes (ties by id, images that no longer exist are skipped). `unused`
+counts the files of enabled variants whose reference time (the last public request, or the creation
+time when never requested) is older than 30 days. `rejected_requests` counts the public requests
+refused with 400 over today and the six previous UTC days. Pending request tracking is flushed before
+the read. Arrays are never `null`.
+
+`POST /v1/image-variants/cache/purge` takes `{ "scope": "all" | "unused" | "variant" | "image",
+"variant": "<name>", "image_id": <id> }` (`variant` for the scope `variant`, `image_id` for `image`; a
+target given for another scope is ignored) and answers `{ scope, purged_files, purged_bytes,
+failed_files }`. A purge that fails on some files still answers 200 with `failed_files` above 0; the
+failed rows are kept so the same request can be sent again. Errors are plain text: 400 for a body that
+is not valid JSON, 422 "Scope must be all, unused, variant or image." or "A variant name or an image
+id is required for this scope.", 404 "Variant not found" or "Image not found", 500 when the rows
+cannot be listed.
+
+### Variants of one image
+Owners and admins only, session only: a request with an API key is 401. All ids are image ids.
+
+| Route | Purpose |
+| --- | --- |
+| `GET /v1/media/{id}/variants` | `{ "unsupported": null, "items": [...] }` for the enabled variants in name order. `unsupported` is `"svg"` (with `items: []`) for an SVG. |
+| `POST /v1/media/{id}/variants` | Generates every enabled variant that is missing. `{ "generated", "failed", "failures": [{ "name", "cause" }], "items": [...] }`, 200 even when some fail. |
+| `POST /v1/media/{id}/variants/{name}` | Generates one enabled variant. 200 with the item. |
+| `DELETE /v1/media/{id}/variants/{name}` | Removes the generated file. `{ "purged_files", "purged_bytes" }`, also for a disabled variant. |
+
+An item is `{ name, width, height, fit, format, output_width, output_height, output_format,
+generated, size, url }`: `width` and `height` are the settings (`null` when auto), `output_*` the
+size and format the file has or will have (never above the source), `generated` is true only when
+the file exists with the variant's current settings, `size` is its bytes or `null`, and `url` is
+`/static/uploadedImages/<stored name>?v=<name>`. A `cause` is `too_large`, `unsupported_format` or
+`failed`. A file generated here is the same file the public url serves, and the other way round.
+Uploads generate the variants flagged `generate_on_upload` (enabled ones, raster sources only)
+before answering; a failure there is logged and never fails the upload.
+
+Errors are plain text: 400 for a malformed id, 404 "Image not found" or "Variant not found" (also for a
+disabled variant on `POST`), 413 "The source image is too large to generate this variant.", 415 "The
+source image can't be read, so this variant can't be generated.", 422 "Variants aren't generated for
+this format." and 500 "Internal server error".
+
+## Errors
+Every error is a plain-text body with one sentence; the status is in the HTTP status line. The
+statuses are 400, 401, 403, 404, 409, 429 and 500. Messages are listed on the Integration page.
+
+## Notes
+- Images in `body` use paths like `/static/uploadedImages/<uuid>.png`. Prefix them with the base URL.
+- Browsers can call the API only from origins in the server's CORS setting.

docs/api/api-keys.md

@@ -0,0 +1,23 @@
+# API keys
+
+Developers can authenticate against `/v1` with a named API key sent as `Authorization: Bearer rcms_...` instead of the `jwt` cookie. A key acts with exactly the rights of the user who created it.
+
+## Managing keys
+
+Key management needs a real session (the `jwt` cookie from a verified user).
+
+- `POST /v1/api-key` with `{"name": "ci", "expires_at": "<RFC3339, optional>"}` answers `201` with `id`, `name`, `prefix`, `key`, `created_at`, `expires_at`. The full `key` is shown once and never again.
+- `GET /v1/api-key` lists the caller's keys (all keys for the owner), newest first, with a `status` of `active`, `expired` or `revoked`.
+- `DELETE /v1/api-key/{id}` revokes a key and answers `204`. Revoking twice keeps the first `revoked_at`.
+
+Only the SHA-256 hash and a 12 character prefix are stored.
+
+## Where a key is accepted
+
+`/v1/article` (public and protected routes), `/v1/user`, `/v1/media`, `/v1/settings` and `GET /v1/auth/me`. An invalid, expired or revoked `rcms_` key answers `401` and is never treated as anonymous. Each key is limited to 120 requests per minute (`429` with `Retry-After`). `last_used_at` is updated at most once per minute.
+
+## Session-only routes
+
+`/v1/api-key`, `POST /v1/auth/verify`, `DELETE /v1/auth/register` and every `/v1/system` route answer `403 This action needs a real session.` to any `rcms_` Bearer header. The public auth routes ignore the header.
+
+A successful password reset revokes every key of that user.

docs/architecture.md

@@ -15,8 +15,10 @@ api/  ──▶  internal/infrastructure/useCases  ──▶  internal/domain
 | Domain | `internal/domain/<name>/` | Entities, `Err…` sentinel errors, `Repository` interfaces. Imports only the stdlib and other domain packages, with no GORM tags. |
 | Use cases | `internal/infrastructure/useCases/` | Application logic. Depends only on domain interfaces, never on persistence, mailer, GORM or `net/http`. |
 | Adapters | `internal/infrastructure/persistence/{models,mappers,repositories}`, `internal/infrastructure/mailer` | Implement a domain `Repository` (assert with `var _ domain.Repository = &X{}`). GORM structs stay in `models` and are converted by `mappers`. |
+| Database drivers | `internal/infrastructure/persistence/database` | `database.Connect(Config{Driver, Source})` looks the driver up in a registry and returns a `Connection` (GORM handle, `NewBackup`, `Close`). A `Driver` implements `Open` and `NewBackup`, so a new database is one new file plus one registry entry. `database.Migrate` owns the `AutoMigrate` model list and the user-role backfill. Only `sqlite` exists today. |
+| Blob storage | `domain/image.Storage`, `internal/infrastructure/storage` | `Storage` (`Put`, `Open`, `Delete`) is the port for uploaded image bytes. `storage.Open(Config{Driver, Location})` picks the adapter; `local` is the only one. Repositories never touch files: use cases coordinate `Storage` and `image.Repository`. |
 | Delivery | `api/handlers/<name>/`, `api/router.go` | HTTP handlers receive use cases through `NewHandler(...)`. They never import persistence, mailer or GORM. |
-| Composition root | `api/dependecyInjection.go` | The only place that opens the DB, builds repositories and use cases, and lists models for `AutoMigrate`. |
+| Composition root | `api/dependecyInjection.go` | The only place that picks the database and storage drivers, builds repositories and use cases, and runs `database.Migrate` and the image metadata backfill at boot. |
 | Entry point | `cmd/server/main.go` | Env/config, HTTP server, graceful shutdown. |
 
 Nothing under `internal/` imports `api/`.
@@ -30,9 +32,54 @@ Nothing under `internal/` imports `api/`.
 | `api/pkg/upload` | Multipart `file` reading and the mapping of upload errors (415, 413, 400) shared by both upload routes. |
 | `api/pkg/publicuser` | `PublicUser`, the JSON shape of a user with no password, codes or token version. `publicuser.New` converts a domain `user.User`, so handlers never serialise the domain struct directly. |
 
+### Media purge
+
+`internal/domain/purge` holds `Settings` (automatic purge on or off, interval of 1 to 365 days, `last_purge_*` history, `enabled_at`), the `Repository` interface (`Get` returns the defaults when nothing was saved, `Save`, and `SaveLastRun`, which writes only the `last_purge_*` columns so a settings change made during a run is never overwritten) and the sentinels `ErrInvalidPurgeInterval`, `ErrPurgeConflict` (stale fingerprint) and `ErrPurgeBusy` (a run is already in progress). `Settings.NextPurgeAt` is `max(last_purge_at, enabled_at)` plus the interval when automatic purge is on, and null otherwise. The settings live in a single-row `purge_settings` table (`models.PurgeSettings`, `mappers.PurgeSettings*`, `persistence.PurgeSettingsRepository`), created by `AutoMigrate`.
+
+The use cases `GetPurgeSettings`, `UpdatePurgeSettings`, `PreviewPurge` and `RunPurge` depend only on domain interfaces, an injected clock and an injected `*log.Logger`, so a scheduler can call them. `PreviewPurge` and `RunPurge` share one plan (`purgePlan.go`): a duplicate group (same non-empty sha256) is planned only when a copy is used in an article, the most used copy is kept (ties: oldest `created_at`, then lowest id) and every other copy is merged into it. The fingerprint is a SHA-256 over the planned groups. `RunPurge` takes a non-blocking in-process lock (`ErrPurgeBusy` for a concurrent call), refuses a non-matching fingerprint with `ErrPurgeConflict`, merges group by group with `MergeMedia` (a failing group is counted and skipped), unions the `UpdatedArticleIDs` of the fully merged groups, and records `last_purge_*` after every run.
+
+#### Automatic purge scheduler
+
+`PurgeSchedulerUseCase.Tick(now)` returns the `purge.RunResult` of the run, whether it ran and an error. It reads the purge settings on every call and runs `RunPurge.Run(nil)` (no fingerprint) when `Settings.NextPurgeAt()` is set and `now` is not before it. It never writes settings: only `RunPurge` records `last_purge_*`, through `SaveLastRun`, which moves the anchor forward even when nothing was purged. The runner in `internal/infrastructure/scheduler` calls `Tick` and logs one line with `groups_purged`, `merged`, `articles_updated` and `failed_groups` when a run happened. It calls `Tick` once after a startup delay of 1 minute, which catches up a run missed during downtime in a single purge, then once every hour. `api/dependecyInjection.go` builds it and `cmd/server/main.go` starts it with the signal context of the server. Changes to the settings apply on the next tick, with no restart.
+
+- Overlap guard: a manual run holds the `RunPurge` lock, so `Tick` returns `ErrPurgeBusy` at once. The runner treats it as a skip, logs nothing and re-evaluates at the next tick.
+- Failures: any other error is logged and the loop keeps going. There is no retry inside a tick; the next hourly tick evaluates the schedule again.
+- Shutdown: on SIGINT or SIGTERM the runner stops taking ticks and waits, with no time limit, for a `Tick` in progress. `main` waits for the runner to return before the database is closed.
+
+`middleware.RequireOwnerOrAdmin` lets only the roles owner and admin through (403 otherwise, including an empty role). The media router mounts these routes after the verified chain and before the `/{id}` routes:
+
+| Route | Purpose |
+|---|---|
+| `GET /v1/media/purge-settings` | Settings with `next_purge_at`. |
+| `PATCH /v1/media/purge-settings` | Partial update of `auto_purge_enabled` and `auto_purge_interval_days`. |
+| `GET /v1/media/purge-preview` | Groups, copies, distinct articles, the first 5 groups, `more` and the fingerprint. |
+| `POST /v1/media/purge` | Runs the purge. Optional `fingerprint`; 409 when stale or when a run is in progress. |
+
+### Activity log
+
+`internal/domain/audit` holds the append-only `Event` (actor, target and failure-reason snapshots, outcome, security flag, source, ip, user agent, `params` and `changes`), the closed vocabularies (actor type, category, outcome, source, change kind), the `Filter`, `Summary` and `Settings` types, the `Repository` interface (`Append`, `List`, `Summary`, `DeleteOlderThan`: no way to edit or delete one event), the `SettingsRepository` (`Get`, `SaveRetention`, `SaveLastCleanup`; no row means 90 days) and the sentinels `ErrInvalidFilter`, `ErrInvalidRetention`, `ErrInvalidEvent` and `ErrActorNotAllowed`. The `Recorder` port is `Record(ctx, event)`; it returns nothing, so a caller can never fail on it.
+
+`internal/infrastructure/auditing.Recorder` is the adapter. It fills a missing actor, source, ip and user agent from the `audit.Origin` carried by the request context, stamps `created_at` from the injected clock in UTC, bounds long names, drops an event outside the vocabulary, and recovers from any error or panic of the repository by writing one line to the process log (the action and the error only). `middleware.AuditContext` builds the origin after the credential middleware: a session gives a `user` actor and source `web`, an API key an `api_key` actor and source `api_key`, no valid credential an `anonymous` actor; the ip is the peer address, or `X-Real-IP` when the peer is a trusted proxy; the user agent is cut to 255 characters. Use cases that produce events (authenticate and logout, password reset request and completion, API key create and revoke, retention change, cleanup) take the context and an `audit.Recorder`; secrets (passwords, raw keys, reset codes, tokens and their hashes) are never put in an event or in its log line.
+
+Persistence is `models.AuditEvent` (`audit_events`, indexes on `created_at`, `(actor_type, actor_id, created_at)` and `(category, created_at)`; `params` and `changes` are JSON text) and `models.AuditSettings` (one row), both in `AutoMigrate`. The queries use only portable SQL (`LOWER(...) LIKE ... ESCAPE '!'`, `COUNT(DISTINCT ...)`, `CASE` sums), so they run on SQLite, MySQL/MariaDB and PostgreSQL. The summary splits the range into seven equal buckets, oldest first.
+
+The use cases `ListActivity`, `GetActivitySummary` and `ExportActivity` turn the raw query into a domain filter (`range` defaults to 7 days; `custom` needs two dates, `to` included), scope a caller who is not owner or admin to its own events, and resolve `target.exists` at read time. The export reads the log through `List` in pages of 500 and writes the CSV with `encoding/csv`. `/v1/activity` and the settings `PATCH` sit behind `RequireSession`, the verifier, the current-token and verified-user checks; summary and export also behind `RequireOwnerOrAdmin`, the settings `PATCH` behind `RequireOwner`.
+
+`CleanupActivityUseCase.Tick(now)` follows the `PurgeScheduler` model. With a retention of 0 it never runs. Otherwise it is due once a day, at or after 03:00 in the location of `now` and when the last cleanup is before today's 03:00. It deletes events older than `now` minus the retention days (never newer than 24 hours), records the run (`activity_last_cleanup_at`, `activity_last_cleanup_removed`) even when nothing was removed, and only then records a `system.activity_cleanup` event when something was removed. A failing delete returns the error and leaves the last-cleanup fields as they were, so the next tick retries. `scheduler.Runner` now wraps a task with a label: `NewRunner` keeps the purge behaviour and log line, and `NewCleanupRunner` ticks the cleanup. `UseCases.RunSchedulers` runs both runners and `cmd/server/main.go` starts it with the server's signal context.
+
+Producers: `ArticleChanges`, `TextChange` and `BodyChange` in `internal/domain/audit` build the change lists (the body change holds only a signed rune count delta), and `NewTarget` and `ReleaseTarget` build the target snapshots (types `article`, `image`, `user`, `invite`, `api_key`, `release`). The use cases create, edit, publish, unpublish and delete article, upload, rename, delete, merge and purge media, register, verify, update profile, create, cancel, renew and accept invite, check, download and restart take the request context first and an `audit.Recorder` last, and record exactly one event after the change or the refusal (the action catalogue is in `docs/api.md`). Events are never written by handlers, middleware or GORM hooks, and nothing is recorded for reads or for a target that does not exist. `useCases/auditFailures.go` holds the fixed table of failure sentences keyed by domain `Err...` sentinels (matched with `errors.Is`, each at most 255 characters; the restart action overrides `ErrJobInProgress`) with the generic fallback "Something went wrong on our side. Please try again."; raw error text is never stored. The manual purge runs the groups through the non-recording `MergeMediaUseCase.merge`, so only one `media.purge` event is written; `RunPurgeUseCase.Execute` is the non-recording run that `PurgeSchedulerUseCase.Tick(now)` uses to record one `system.media_purge` event with the system actor and `context.Background()`. `StartUpdateDownloadUseCase` hands `context.WithoutCancel(ctx)` to its job goroutine so the `system.update_downloaded` event, written when the job becomes `ready` or `failed`, keeps the origin of the request. `middleware.AuditContext` is mounted on the article, user, media and system routers (after the API key middleware where keys are accepted), so API key calls are attributed to the key.
+
+### Image variants
+
+`internal/domain/image` holds the `Variant` entity and its rules (`VariantSettings.Normalized`, the settings `Fingerprint`, `VariantETag`, `ETagMatches`, `IsAnimatedGIF`), the sentinels (`ErrVariantNotFound`, `ErrVariantExists`, `ErrVariantInvalid`, `ErrVariantFormatUnavailable`, `ErrUnknownVariant`, `ErrUnsupportedParameter`, `ErrSourceTooLarge`) and three ports: `VariantRepository` (definitions), `VariantFileRepository` (the index of generated files: variant name, source stored name, cached stored name, content type, size and the settings fingerprint, needed because `Storage.Put` chooses the stored name itself) and `VariantRenderer` (decode a source, encode a variant, report the formats it can encode). `internal/infrastructure/imaging` is the renderer adapter, free of GORM and HTTP; the persistence adapters are `VariantRepository` and `VariantFileRepository` over `models.ImageVariant` and `models.ImageVariantFile`.
+
+Generated bytes are stored only through `image.Storage`, so they follow `STORAGE_DRIVER`, and are never rows of `images`. `ServeVariantUseCase` checks, in order: unsupported parameters, the variant (it must exist and be enabled), the source blob, SVG and animated GIF (served as they are), the size cap, the `If-None-Match` ETag, then the cached file, and generates under a `singleflight` keyed by variant, settings and source. A row whose fingerprint no longer matches, or whose blob vanished, is replaced. `UpdateVariantUseCase` purges a variant's files when a rendering setting changes; `DeleteVariantUseCase` and `PurgeVariantUseCase` purge a blob and then its row, so a failed blob delete keeps the row and a retry can finish; `mediaRemover` purges the files of a source before it deletes the source (delete and merge).
+
+The cache screen adds three ports in `internal/domain/image`: `VariantCacheRepository` (unused totals, top sources by bytes and cursor-paged row listing, implemented by the same persistence type as `VariantFileRepository`), `VariantUsageRepository` (one batched write of request times and per-day rejection counts, and the rejection total of a window) and `VariantUsageTracker` (in-memory hits and rejections). `internal/infrastructure/usage.Tracker` implements the tracker; `GetVariantCacheStatsUseCase` and `PurgeVariantCacheUseCase` use the ports only. See [image-variants.md](image-variants.md).
+
 ### Image metadata backfill
 
-At boot, `BackfillImageMetadata` fills `filename`, `size`, `content_type`, `width`, `height` and `sha256` for image rows that lack them, reading the files in `UPLOAD_DIR`. It is idempotent, and a row whose file is missing or unreadable is left as it is without stopping the boot. The old `article_id` column and the `article_images` table are kept and never written.
+At boot, `BackfillImageMetadataUseCase` (through `image.Repository.ListMissingMetadata` and `UpdateMetadata`) fills `filename`, `size`, `content_type`, `width`, `height` and `sha256` for image rows that lack them, reading the bytes through `image.Storage` (the files in `UPLOAD_DIR` with the local adapter, the bucket objects with the S3 adapter). It is idempotent, and a row whose file is missing or unreadable is left as it is without stopping the boot. The old `article_id` column and the `article_images` table are kept and never written.
 
 ## Frontend ↔ backend
 
@@ -50,3 +97,36 @@ bin/renewcms  ──  /v1/*  API
 
 - **Production:** a single origin. The SPA calls the API with relative URLs, so the JWT cookie works without CORS. Files under `assets/` are content-hashed by Vite and cached for a year. `index.html` is never cached.
 - **Development:** built with `-tags nofrontend` (`assets_stub.go`, `assets.Dist == nil`). Vite serves the SPA on :5173 and proxies `/v1` to the API on :8080. See [development.md](development.md).
+
+## Storage and database seams
+
+Uploaded images are addressed by a stored name (`<uuid>.<ext>`). `CreateImageUseCase` calls `Storage.Put` (which generates the name), then `Repository.Create` with `Path = /static/uploadedImages/<name>`, and deletes the blob again if the row cannot be created. `DeleteMediaUseCase` and `MergeMediaUseCase` remove the blob first and the row second (`mediaRemover`), so a failed blob delete keeps the row and the delete can be retried. `GET /static/uploadedImages/<name>` is served by `OpenMediaUseCase` through `api/handlers/staticimages`, which uses `http.ServeContent` when the blob is seekable and streams it otherwise; `ErrBlobNotFound` maps to 404 and any other error to 500.
+
+SQL in repositories must run on SQLite, MySQL/MariaDB and PostgreSQL: substring searches use `LIKE ... ESCAPE '!'` through `containsPattern` instead of `instr`. `Settings.DataDir()` is where update state, staging and backups live; it is `DATA_DIR` when set and the directory of `DB_FILE` otherwise, so it does not depend on where the database is.
+
+Three drivers are registered in `database.drivers`: `sqlite` (default), `mysql` (MySQL 8 and MariaDB 11, through `gorm.io/driver/mysql`) and `postgres` (PostgreSQL 16 and 17, alias `postgresql`, through `gorm.io/driver/postgres` on pgx v5); all are pure Go so `CGO_ENABLED=0` and the six release targets still build. `DB_DRIVER` picks one in `databaseConfig` (composition root); an unknown name fails in `database.Connect` with `unsupported database driver "<name>"`. `database.MySQLDSN` and `database.PostgresDSN` build the DSN from separate variables (the PostgreSQL one as an escaped URL with `sslmode`, `timezone=UTC` and a connect timeout), and the driver redacts the password from every error and names only host and port. `Connect` applies the optional `PoolSettings` to any driver. What keeps the repositories identical on both engines, all without touching the domain, use cases or handlers:
+
+- Indexed and unique strings carry `size:` tags in the models (a MySQL index needs a bounded `varchar`). SQLite maps them to the same `text` column, so an existing SQLite file migrates with no schema or row change (`test/sqlite_schema_unchanged_test.go` builds a file from the old model definitions and compares `sqlite_master` and every row).
+- `Migrate` creates MySQL tables with `utf8mb4_bin` (`gorm:table_options`), so `Bob` and `bob` are distinct like in SQLite. The DSN also sets `collation=utf8mb4_bin`.
+- The DSN sets `clientFoundRows=true`: an update that matches a row but changes nothing still reports one affected row, as in SQLite. `InviteRepository.Renew`, `deleteOrNotFound` and `PurgeSettingsRepository.SaveLastRun` depend on that.
+- The Go driver sends a zero `time.Time` as `0000-00-00`, which MySQL's default `NO_ZERO_DATE` rejects, so each session sets `sql_mode` to the server default minus `NO_ZERO_DATE`. Reading `0000-00-00` gives the zero time back.
+- `UserRepository.Create` returns the filled model instead of re-reading it, because MySQL has no `RETURNING`.
+
+On PostgreSQL the MySQL-only table options are not applied, pgx returns `timestamptz` values in the local zone so a query callback in the driver converts them to UTC, and only the `public` schema is used.
+
+Backups are a `domain/update.DatabaseBackup` per driver. SQLite uses `VACUUM INTO`. MySQL uses `DumpBackup`, a pure Go logical dump (`SHOW CREATE TABLE` plus every row, strings escaped and binary values as hex, NULL and zero dates kept) written inside one repeatable-read transaction to `DATA_DIR/backups/renewcms-<time>.sql.partial` and renamed once complete. Any failure removes the partial file and returns an error, so the update download fails instead of claiming a backup. PostgreSQL reuses `DumpBackup` with its own `dumpDialect` (double-quoted identifiers, doubled single quotes, `\x` bytea literals): `CREATE TABLE` is rebuilt from `pg_catalog` (serial columns, defaults, primary key, unique and check constraints), followed by the indexes, the rows and a `setval` per `id` sequence, all inside one repeatable-read read-only transaction. All drivers keep the newest 3 files (`pruneBackups`).
+
+`task test` runs everything that needs no server. The repository contract tests (`test/repository_contract_test.go`) run on SQLite always, and on MySQL when `RENEWCMS_TEST_MYSQL_DSN` points at a server (admin DSN; each test creates and drops its own database). `task test:mysql` starts `mysql:8.4` and then `mariadb:11` in Docker and runs the `MySQL` tests against each. The same contract tests run on PostgreSQL when `RENEWCMS_TEST_POSTGRES_DSN` points at a server (admin DSN, for example `postgres://postgres:pw@127.0.0.1:5432/postgres?sslmode=disable`), and `task test:postgres` starts `postgres:16` then `postgres:17` in Docker and runs the `Postgres` tests against each.
+
+Two storage adapters implement `image.Storage`: `local` (default, files in `UPLOAD_DIR`) and `s3` (`storage.S3Storage`, `aws-sdk-go-v2` over plain HTTPS, pure Go so `CGO_ENABLED=0` still holds). `STORAGE_DRIVER` picks one in `imageStorageConfig` (composition root, from `config.StorageSettings`); `storage.Open` fails with `unsupported storage driver "<name>"` for anything else, and `openImageStorage` panics with the error. The S3 adapter works as follows, with no change to the domain, use cases, repositories or the `staticimages` handler:
+
+- `Open` calls `GetObject` and returns a `Blob` whose `Content` is an `io.ReadSeeker` (`s3Reader`): `Size` and `ModTime` come from `ContentLength` and `LastModified`, the first bytes are read from that response and every `Seek` to another offset makes the next `Read` issue a ranged `GetObject`. `http.ServeContent` therefore answers `Range` (206, 416) and `If-Modified-Since` (304) with no `ETag`. A 404 maps to `image.ErrBlobNotFound`; any other failure is a plain error (500 in the handler).
+- `Put` does one `PutObject` of `<S3_KEY_PREFIX><uuid>.<ext>` with the upload's `Content-Type`. `Delete` treats 404 as success. Names that are not plain file names are never requested, as in the local adapter.
+- Each call has a 30 second timeout to get a response (the body then streams without a deadline) and the SDK default retries. Request checksums are only sent when required, so older S3-compatible servers work.
+- `storage.Open` checks the bucket with `HeadBucket`. The failure text names the bucket and the reason (404, 403, other status or transport error) and never the credentials.
+- At boot, `RunBackfillReportingReads` wraps the storage in a counter for the `BackfillImageMetadataUseCase` run and logs how many images it read; the use case itself is unchanged.
+- Update backups (`DATA_DIR`) never include uploads, whatever the driver.
+
+`task test:s3` starts SeaweedFS in Docker and runs `TestS3StorageIntegration` against it (skipped without Docker, and not part of `task test`). Everything else uses an in-process fake S3 server listening on `127.0.0.1`.
+
+Adding a database driver: implement `database.Driver` (`Open`, and `NewBackup` returning a `domain/update.DatabaseBackup`), register it in `drivers`, then select it in `databaseConfig` in the composition root (and add the env vars to `main.go`, `.env.example` and `configuration.md`). Adding a storage backend: implement `image.Storage`, add a case to `storage.Open`, and select it in `openImageStorage`. No use case, handler or repository changes.

docs/configuration.md

@@ -24,22 +24,96 @@ Copy [`.env.example`](../.env.example) to `.env` to get started. When a required
 |------------------------|----------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | `ENVIRONMENT`          | `production`         | `production` or `development`. In `production` the auth cookie is `Secure`, so it is only sent over HTTPS. `development` turns on HTTP request logging.                                                                           |
 | `PORT`                 | `8080`               | Port the HTTP server listens on (all interfaces).                                                                                                                                                                               |
-| `DB_FILE`              | `./data/renewcms.db` | Path to the SQLite database file. Missing parent directories are created. The schema is migrated automatically at startup.                                                                                                      |
-| `UPLOAD_DIR`           | `./data/uploads`     | Directory where uploaded images are stored.                                                                                                                                                                                     |
+| `DB_DRIVER`            | `sqlite`             | `sqlite`, `mysql` (MySQL and MariaDB) or `postgres` (alias `postgresql`). Any other value stops the server with `unsupported database driver "<value>"`. See [Database](#database).                                                                             |
+| `DB_FILE`              | `./data/renewcms.db` | Path to the SQLite database file. Missing parent directories are created. The schema is migrated automatically at startup. Ignored when `DB_DRIVER` is `mysql` or `postgres`.                                                                     |
+| `DATA_DIR`             | directory of `DB_FILE` | Directory for update state, staged updates and database backups (`backups/`). Set it with `DB_DRIVER=mysql` or `postgres`, where there is no database file to sit beside (the default still follows `DB_FILE`). With SQLite, leave it unset to keep everything beside the database. |
+| `STORAGE_DRIVER`       | `local`              | `local` (files in `UPLOAD_DIR`) or `s3` (an S3-compatible bucket). Any other value stops the server with `unsupported storage driver "<value>"`. See [Image storage](#image-storage). |
+| `UPLOAD_DIR`           | `./data/uploads`     | Directory where uploaded images are stored. Ignored, without error, when `STORAGE_DRIVER=s3`.                                                                                                                                                                                     |
 | `CORS_ALLOWED_ORIGINS` | *(empty)*            | Semicolon-separated list of origins allowed to call the API. When empty, no CORS headers are sent. That is the right setting whenever the SPA is served by RenewCMS itself (production) or through the Vite proxy (development). |
 | `AUTH_RATE_LIMIT_MAX_ATTEMPTS` | `5`           | Maximum number of requests a single client IP may send to `POST /v1/auth/login`, `POST /v1/auth/password-reset` or the invite-accept pair (`GET /v1/auth/invite` and `POST /v1/auth/invite/accept`, sharing one counter) within the window, tracked independently per route.                                                          |
 | `AUTH_RATE_LIMIT_WINDOW_SECONDS` | `60`        | Length, in seconds, of the fixed rate-limit window for the routes above.                                                                                                                                                    |
 | `TRUSTED_PROXIES`      | *(empty)*            | Semicolon-separated list of exact IP addresses (no CIDR) of reverse proxies allowed to supply the client IP via `X-Real-IP` for the rate limiting of the routes above. When a request's connection address is not in this list, any `X-Real-IP` or `X-Forwarded-For` header it sends is ignored and the connection address is used instead. See [deployment.md](deployment.md).      |
-| `UPDATE_FEED_URL`      | `https://git.floriansylvain.fr` | Base URL of the Gitea server that publishes RenewCMS releases. The Settings page asks `{UPDATE_FEED_URL}/api/v1/repos/fsylvain/RenewCMS/releases` when the owner checks for updates. The last result is kept in `update-status.json`, next to `DB_FILE`. |
+| `RENEWCMS_CONTAINER` | `false` | Set to `true` (case-insensitive; any other value means `false`) when the app runs in a container. Settings then tells the owner to update by pulling a new image instead of offering browser updates, and `can_apply` is always `false`. The Dockerfile and `docker-compose.yml` set it to `true`. Update checks still work. |
+| `IMAGE_VARIANT_MAX_SOURCE_BYTES` | `10485760` | Largest stored image, in bytes, that an [image variant](image-variants.md) may be generated from. A request for a bigger source answers 413 with a plain-text body. The original is never affected, and SVG and animated GIF are always served as they are. A value that is not a whole number greater than zero stops the server at boot with an error naming the variable. |
+| `IMAGE_VARIANT_MAX_SOURCE_PIXELS` | `50000000` | Largest declared width x height, in pixels, that an [image variant](image-variants.md) may be generated from. It is read from the image header before any pixel buffer is allocated; a bigger source answers 413 with the same plain-text body as the byte cap. The original is never affected, and SVG and animated GIF are always served as they are. A value that is not a whole number greater than zero stops the server at boot with an error naming the variable. |
+| `IMAGE_VARIANT_MAX_CONCURRENT_RENDERS` | `4` | Number of [image variant](image-variants.md) renders that may run at once. Other requests wait for a free slot until their client goes away; cached files never wait. A value that is not a whole number greater than zero stops the server at boot with an error naming the variable. |
+| `UPDATE_FEED_URL`      | `https://git.floriansylvain.fr` | Base URL of the Gitea server that publishes RenewCMS releases. The Settings page asks `{UPDATE_FEED_URL}/api/v1/repos/fsylvain/RenewCMS/releases` when the owner checks for updates. The last result is kept in `update-status.json`, in the data directory. |
+
+Automatic media purge has no environment variable. Its schedule (on or off, interval, `enabled_at`, `last_purge_at`) lives in the purge settings row of the database, is changed from the Settings page or `PATCH /v1/media/purge-settings`, and is read again at every hourly tick.
+
+## Image storage
+
+By default uploaded images are files in `UPLOAD_DIR`. To keep them in an S3-compatible bucket (AWS S3, MinIO, Ceph, Cloudflare R2, Backblaze B2 and similar), set `STORAGE_DRIVER=s3` and the variables below. They are only read when `STORAGE_DRIVER=s3`. Image URLs do not change: the app still serves `/static/uploadedImages/<name>`, reading the object from the bucket (the bucket stays private, and `Range` and `If-Modified-Since` requests keep working; there is no `ETag`).
+
+| Name                   | Default     | Description                                                                                                                                                                      |
+|------------------------|-------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `S3_BUCKET`            | required    | Name of an existing bucket. A missing value stops the server with `Environment variable S3_BUCKET is not set`.                                                                  |
+| `S3_REGION`            | `us-east-1` | Bucket region. Most S3-compatible servers accept the default.                                                                                                                    |
+| `S3_ENDPOINT`          | *(empty)*   | Host (with optional port) or full URL of an S3-compatible server. Leave empty for AWS S3.                                                                                       |
+| `S3_ACCESS_KEY_ID`     | *(empty)*   | Access key. Set it together with `S3_SECRET_ACCESS_KEY`, or set neither. Setting only one stops the server with an error naming the missing one.                                |
+| `S3_SECRET_ACCESS_KEY` | *(empty)*   | Secret key. Never logged and never in an error message. When both keys are empty, the default AWS credential chain is used (`AWS_*` variables, shared credentials file, instance or task role). |
+| `S3_KEY_PREFIX`        | *(empty)*   | Prefix put before every object key, for example `uploads/`. Include the trailing slash.                                                                                          |
+| `S3_PATH_STYLE`        | `false`     | `true` addresses the bucket as `endpoint/bucket` instead of `bucket.endpoint`. SeaweedFS, MinIO and most self-hosted servers need `true`.                                                  |
+| `S3_TLS`               | `true`      | Only used when `S3_ENDPOINT` has no `http://` or `https://` prefix: `true` means `https`, `false` means `http`.                                                                 |
+
+At startup the server checks the bucket (`HeadBucket`). A missing bucket, refused credentials or an unreachable server stop startup with `Unable to open the image storage: S3 bucket "<name>" is not usable: <reason>`; the error never contains the secret. Each S3 call has a 30 second timeout and the SDK default retries. At boot, images whose metadata is missing are read back from the bucket to fill it; when there were some, one log line says how many.
+
+### Moving existing uploads to a bucket
+
+There is no automatic migration and the database does not change: image rows only hold the stored name, so the same names must exist in the bucket. With the site stopped, copy the files under the same names, under `S3_KEY_PREFIX` if you set one, then set `STORAGE_DRIVER=s3` and restart:
+
+```sh
+aws s3 sync ./data/uploads s3://my-bucket/uploads/
+rclone sync ./data/uploads remote:my-bucket/uploads
+```
+
+Keep `UPLOAD_DIR` until you have checked the site. Moving back is the same copy in the other direction.
+
+### Backups
+
+The pre-update backup covers the database only (and `DATA_DIR` state). Neither the update backup nor the data directory includes uploads, so back the bucket up with your provider (versioning, replication) or with `aws s3 sync` / `mc mirror`.
+
+## Database
+
+SQLite is the default and needs nothing but `DB_FILE`. To run against MySQL 8 or MariaDB 11 instead, set `DB_DRIVER=mysql` and the connection variables below. They are only read (and the four required ones only checked) when `DB_DRIVER` is `mysql` or `postgres`. A required variable that is not set stops the server with `Environment variable DB_HOST is not set` (or `DB_USER`, `DB_PASSWORD`, `DB_NAME`).
+
+| Name                           | Default  | Description                                                                                                                      |
+|--------------------------------|----------|----------------------------------------------------------------------------------------------------------------------------------|
+| `DB_HOST`                      | required | Server host name or IP address.                                                                                                  |
+| `DB_PORT`                      | `3306` (`5432` for PostgreSQL) | Server port.                                                                                                       |
+| `DB_USER`                      | required | Database user. It needs full rights on `DB_NAME`, because the schema is created and migrated at startup.                        |
+| `DB_PASSWORD`                  | required | Database password. It is never logged and never appears in an error message.                                                     |
+| `DB_NAME`                      | required | Name of an existing database. The server does not create it.                                                                     |
+| `DB_TLS`                       | `false`  | `false`, `true`, `skip-verify` or `preferred`. Any other value stops the server with an error naming `DB_TLS` and these values. `true` verifies the server certificate; `skip-verify` encrypts without verifying it. |
+| `DB_SSLMODE`                   | `disable` | PostgreSQL only: `disable`, `require`, `verify-ca` or `verify-full`. Any other value stops the server with an error naming `DB_SSLMODE` and these values. Ignored for SQLite and MySQL (use `DB_TLS` there). |
+| `DB_MAX_OPEN_CONNS`            | `10`     | Maximum open connections in the pool. `0` means unlimited.                                                                       |
+| `DB_MAX_IDLE_CONNS`            | `5`      | Maximum idle connections kept in the pool.                                                                                       |
+| `DB_CONN_MAX_LIFETIME_SECONDS` | `300`    | Seconds after which a connection is closed and replaced. `0` keeps connections forever. Keep it below the server's `wait_timeout`. |
+
+A non numeric (or negative) pool value stops the server with an error naming the variable. There is no DSN variable: the connection string is built from the variables above, with `parseTime=true`, `loc=UTC`, `charset=utf8mb4`, `collation=utf8mb4_bin` and `clientFoundRows=true`. Connecting uses a 5 second timeout, so a wrong host, port, password or database name stops startup quickly with `Unable to open the database`, naming the host and port but never the password.
+
+### PostgreSQL
+
+Set `DB_DRIVER=postgres` (or `postgresql`) and the same connection variables, with `DB_PORT` defaulting to `5432` and `DB_SSLMODE` instead of `DB_TLS`. PostgreSQL 16 and 17 are tested. The database must already exist and `DB_USER` needs full rights on the `public` schema, which is the only schema used. The connection string is built with escaping from the variables (a password may contain spaces, quotes, `@` or `/`), sets the session time zone to UTC and a 5 second connect timeout, and the pool variables above apply. A failure to connect stops startup with `Unable to open the database`, naming the host and port but never the password. Usernames and emails compare case-sensitively, as on SQLite. Before an update download RenewCMS writes a logical dump to `DATA_DIR/backups/renewcms-<time>.sql` (the newest 3 are kept); replay it into an empty database with `psql -f`. For routine backups prefer `pg_dump`.
+
+### MySQL settings
+
+Why those settings: tables are created with the `utf8mb4_bin` collation so that usernames and emails compare case-sensitively exactly like in SQLite (`Bob` and `bob` are different users). The collation of `DB_NAME` itself does not matter, but tables that already exist keep the collation they have. `clientFoundRows` makes an update that does not change a row still count as matched, which the invite and purge-settings code relies on. Each session also drops the server's `NO_ZERO_DATE` SQL mode, because the Go driver sends a zero time as `0000-00-00`. The other strict modes stay on.
+
+With MySQL the data directory (`DATA_DIR`) holds update state and backups only. The pre-update backup is a `renewcms-<time>.sql` logical dump (schema and rows, written by RenewCMS itself, no `mysqldump` needed) that keeps the newest 3. If the dump fails, the update download fails with it. The dump holds your data, such as password hashes, but not the connection password.
 
 Relative paths are resolved against the process's working directory. In production, use absolute paths (see [deployment.md](deployment.md)).
 
 For example, `WorkingDirectory=/var/lib/renewcms` with `DB_FILE=./data/renewcms.db` puts the database in `/var/lib/renewcms/data`. Browser-update `--data-dir` must name that directory, because the app reads helper status and update records beside the database. It is not necessarily `WorkingDirectory` or `ReadWritePaths`. Do not change an existing `DB_FILE` merely to match the helper: that could open a different, empty database. See [browser-update setup](deployment.md#browser-updates).
 
+## Activity log retention
+
+The activity log needs no environment variable. Its retention (an age of 30, 90, 365 days or forever, 90 by default, and an optional maximum size in GB, none by default; whichever limit is reached first removes the oldest events) is a setting the owner changes with `PATCH /v1/settings`, and the daily cleanup runs at 03:00 in the server's time zone (`TZ`, or the host's zone).
+
 ## Adding a variable
 
 1. Read it in the code where it is needed (infrastructure or `api/`, never `internal/domain`).
-2. Register it in [`cmd/server/main.go`](../cmd/server/main.go): add it to `requiredEnvVars` if it is required, or to `envDefaults` if it has a default.
+2. Register it in [`cmd/server/main.go`](../cmd/server/main.go): add it to `requiredEnvVars` if it is required (or to `DatabaseRequiredEnvVars` in `internal/infrastructure/config` if only one database driver needs it), or to `envDefaults` if it has a default.
 3. Add it to [`.env.example`](../.env.example) and to the tables above.
 
 Never hardcode a secret, and never commit `.env`.

docs/deployment.md

@@ -8,7 +8,9 @@ RenewCMS ships as **one self-contained executable**. It serves:
 | `/healthz` | Liveness check, returns `200 ok`        |
 | `/*`       | The Vue SPA (embedded), with fallback to `index.html` for client-side routes |
 
-Runtime state includes the SQLite database (`DB_FILE`), uploads (`UPLOAD_DIR`), and update records, staged binaries and backups beside the database. Running a release binary needs no Go, Bun or Node installation. Browser updates additionally require Linux with systemd and the helper setup below.
+Runtime state includes the SQLite database (`DB_FILE`, or a MySQL/MariaDB or PostgreSQL server, see [Using MySQL or MariaDB](#using-mysql-or-mariadb) and [Using PostgreSQL](#using-postgresql)), uploads (`UPLOAD_DIR`, or an S3-compatible bucket with `STORAGE_DRIVER=s3`, see [configuration.md](configuration.md#image-storage)), and update records, staged binaries and backups beside the database. Running a release binary needs no Go, Bun or Node installation. Browser updates additionally require Linux with systemd and the helper setup below.
+
+To run it in a container instead, see [docker.md](docker.md). The published image `git.floriansylvain.fr/fsylvain/renewcms` is upgraded with `docker compose pull && docker compose up -d`. Tags are `vX.Y.Z`, `X.Y.Z`, `X.Y` and `latest` for a stable release, and `vX.Y.Z-<pre>`, `X.Y.Z-<pre>` and the moving `<pre-name>` (`beta`, `rc`) for a pre-release, which never moves `latest`. Maintainers publish with `task docker:publish` after `docker login git.floriansylvain.fr`; there is no CI. See [Maintainer: publishing](docker.md#maintainer-publishing).
 
 ## 1. Build
 
@@ -33,7 +35,7 @@ To check a download by hand: `go run ./cmd/releasesign verify checksums.txt`, wi
 
 ### Update checks
 
-The owner's Settings page asks the release feed for the newest release (see `UPDATE_FEED_URL` in [configuration.md](configuration.md)) and keeps the last result in `update-status.json`, next to `DB_FILE`. Back it up with the rest of the data directory if you like; it is rebuilt by the next check when missing. The Settings page reports a newer version. To install it from the browser, set up [Browser updates](#browser-updates) once on the server.
+The owner's Settings page asks the release feed for the newest release (see `UPDATE_FEED_URL` in [configuration.md](configuration.md)) and keeps the last result in `update-status.json`, next to `DB_FILE`. Back it up with the rest of the data directory if you like; it is rebuilt by the next check when missing. The Settings page reports a newer version. To install it from the browser, set up [Browser updates](#browser-updates) once on the server. In Docker (`RENEWCMS_CONTAINER=true`) browser updates are not offered; Settings tells the owner to pull a new image instead, see [docker.md](docker.md).
 
 ### Update downloads
 
@@ -268,8 +270,59 @@ If RenewCMS runs on the same host as the proxy, consider firewalling port 8080.
 
 Either way, set `TRUSTED_PROXIES` (see [configuration.md](configuration.md)) to the proxy's own address as seen by RenewCMS, typically `127.0.0.1` when the proxy and RenewCMS share a host, so the login/password-reset rate limiter honors the forwarded client IP instead of the proxy's own address.
 
+### Security headers
+
+RenewCMS sends `Content-Security-Policy` (including `frame-ancestors 'none'`), `X-Content-Type-Options`, `X-Frame-Options`, `Referrer-Policy` and `Cross-Origin-Opener-Policy` itself, so the proxy doesn't need to add them. With `ENVIRONMENT=production` it also sends `Strict-Transport-Security: max-age=31536000` (browsers ignore it over plain HTTP, so serve the site over HTTPS only). Don't add the same headers in the proxy, or they will be duplicated.
+
+The CSP allows Google Fonts (`fonts.googleapis.com`, `fonts.gstatic.com`) and `https:` images, because the SPA loads its fonts from Google and articles may embed remote images. `style-src` keeps `'unsafe-inline'` for the article editor; `script-src` is `'self'` only.
+
+## Using MySQL or MariaDB
+
+SQLite is the default. To use an existing MySQL 8 or MariaDB 11 server instead, create an empty database and a user with full rights on it, then set in `/etc/renewcms/renewcms.env`:
+
+```sh
+DB_DRIVER=mysql
+DB_HOST=db.example.com
+DB_USER=renewcms
+DB_PASSWORD=<generated password>
+DB_NAME=renewcms
+DB_TLS=true
+DATA_DIR=/var/lib/renewcms
+```
+
+`DB_FILE` is then ignored. `DATA_DIR` is where update state, staged updates and backups live, so give it the same value as the helper's `--data-dir` (see [browser updates](#browser-updates)). Use `DB_TLS=true` (or `preferred`) whenever the server is not on the same host. Every variable is described in [configuration.md](configuration.md#database). The schema is created and migrated at startup, so the first start on an empty database needs nothing else.
+
+## Using PostgreSQL
+
+To use an existing PostgreSQL 16 or 17 server, create an empty database and a user with full rights on its `public` schema, then set in `/etc/renewcms/renewcms.env`:
+
+```sh
+DB_DRIVER=postgres
+DB_HOST=db.example.com
+DB_USER=renewcms
+DB_PASSWORD=<generated password>
+DB_NAME=renewcms
+DB_SSLMODE=require
+DATA_DIR=/var/lib/renewcms
+```
+
+`DB_FILE` is then ignored, and `DB_PORT` defaults to `5432`. `DATA_DIR` is where update state, staged updates and backups live, so give it the same value as the helper's `--data-dir`. Use `DB_SSLMODE=require` (or `verify-full`) whenever the server is not on the same host. Every variable is described in [configuration.md](configuration.md#database). The schema is created and migrated at startup. Moving an existing SQLite site is a manual procedure like the MySQL one below, and RenewCMS writes a logical `.sql` dump to `DATA_DIR/backups` before each update download.
+
+### Moving an existing SQLite site to MySQL
+
+There is no migration tool. The manual procedure, with the site stopped:
+
+1. Take a backup of the data directory (database file and uploads).
+2. Start RenewCMS once on the empty MySQL database so it creates the schema, then stop it.
+3. Export the rows from the SQLite file with `sqlite3 renewcms.db .dump`, keep only the `INSERT INTO` statements for `articles`, `images`, `users`, `invites`, `api_keys` and `purge_settings`, and import them into MySQL. Quoting and date formats differ between the two engines, so check a sample first: SQLite writes times such as `2026-01-02 03:04:05.123456789+00:00`, and the `+00:00` suffix must be removed for MariaDB and older MySQL versions. An unset time (`0001-01-01 00:00:00`) is valid as it is in MySQL and is read back as unset.
+4. Copy `uploads/` to the new `UPLOAD_DIR`, set `DB_DRIVER=mysql` and the connection variables, and start the service.
+
+Keep the SQLite file until you have checked the site.
+
 ## Backups
 
+With MySQL, MariaDB or PostgreSQL, back the database up with your server's own tools (for example `mysqldump --single-transaction` or `pg_dump`), plus the uploads directory. RenewCMS also writes a logical dump to `DATA_DIR/backups` before each update download. The rest of this section is about SQLite.
+
 Everything worth backing up is under the data directory. Take a consistent SQLite copy while the service is running:
 
 ```sh

docs/design/README.md

@@ -30,8 +30,11 @@ The visual spec of record for the back-office SPA and the transactional emails,
 | [New article](screens/new-article.md) | `modal from anywhere · /article/new` | 5 | `source/RenewCMS Screens Back-office.dc.html` |
 | [Editor](screens/editor.md) | `/article/:id/edit` | 22 | `source/RenewCMS Screens Back-office.dc.html` |
 | [Media](screens/media.md) | `/media` | 41 | `source/RenewCMS Screens Back-office.dc.html` |
+| [Image variants](screens/image-variants.md) | `/settings/media/variants` · `/settings/media/cache` (plus `/media` and the editor picker) | 51 | `source/RenewCMS Screens Image variants.dc.html` |
 | [Media picker](screens/media-picker.md) | `/article/:id/edit` (dialog) | 13 | `source/RenewCMS Screens Back-office.dc.html` |
-| [Integration](screens/integration.md) | `/integration` | 2 | `source/RenewCMS Screens Back-office.dc.html` |
+| [Integration](screens/integration.md) | `/integration` | 8 | `source/RenewCMS Screens Back-office.dc.html` |
+| [API keys](screens/integration-api-keys.md) | `/integration/api-keys` | 12 | `source/RenewCMS Screens API keys.dc.html` |
+| [Activity](screens/activity.md) | `/activity` | 9 (plus 6 details, 3 My activity) | `source/RenewCMS Screens Back-office.dc.html` |
 | [Users](screens/users.md) | `/users` | 17 | `source/RenewCMS Screens Back-office.dc.html` |
 | [Settings](screens/settings.md) | `/settings` | 25 | `source/RenewCMS Screens Back-office.dc.html` |
 | [Profile](screens/profile.md) | `/profile` | 13 | `source/RenewCMS Screens Back-office.dc.html` |
@@ -40,8 +43,15 @@ The visual spec of record for the back-office SPA and the transactional emails,
 
 ## Other boards
 
+The Back-office board is now the one place where every back-office screen is drawn together, including Activity, Media cleanup, Retention and the Home activity section, all through `source/AppFrame.dc.html`. The separate Activity and Media cleanup boards and `SettingsFrame.dc.html` were removed from the export; their states now live in the Back-office board.
+
+
+- `source/ActivityFrame.dc.html`: the frame that draws every Activity state (the Back-office board imports it). Its copy, component and API tables are in `source/activity-spec.js`, rendered at the bottom of the Back-office board. It holds the exact values. The Home activity section and the Retention card are drawn by `AppFrame.dc.html`.
 - `source/MediaFrame.dc.html`: the frame that draws the Media and Media picker states (the Back-office board imports it). Like `AppFrame.dc.html`, it holds the exact values.
+- `source/IntegrationPage.dc.html` and `source/ApiKeysPage.dc.html`: the page components for the Integration and API keys screens (imported by `AppFrame.dc.html`). They hold the exact values.
 - `source/RenewCMS Prototype.dc.html`: the clickable flows (first run, edit and publish, password reset, delete, session expiry mid-edit).
 - `source/RenewCMS Handoff.dc.html`: the handoff page the first markdown here was generated from. It predates the Users and Profile screens and the invitation email, so it does not list them. Those are written by hand from the Back-office board, `AppFrame.dc.html`, the Prototype and `emails/invitation.html`.
 - `source/RenewCMS Components Product.dc.html`: not regenerated for the new screens either. The matching component changes are in `components.md`, under "Added with the Users and Profile screens" and "Added with roles, invite actions and Settings".
 - `source/RenewCMS Directions.dc.html`: the three brand directions (history only).
+
+- `source/VariantsFrame.dc.html`: the frame that draws every Image variants state (the Image variants board imports it, inside `AppFrame.dc.html`). Like `AppFrame.dc.html`, it holds the exact values. The board is the only place the variants screens are drawn; the Back-office board does not include them.

docs/design/components.md

@@ -30,7 +30,12 @@
 | PasswordStrengthHint | custom (in UFormField #help) | rules: { label, met }[], showErrors: boolean | none | none | Register, Reset, Accept invite |
 | ResultPanel | custom + UButton | tone: 'success'\|'error'\|'info', icon, title, description, actions: ButtonProps[] | none | default | Pending, Verify, Reset request, Reset, Accept invite, Register (403) |
 | CodeBlock | custom (shiki) + UButton | code: string, lang: string, label? | none | none | Integration |
-| EndpointCard | UCard, UBadge, UTabs | method: 'GET', path, description, examples: { fetch, curl, response } | none | none | Integration |
+| EndpointCard | UCollapsible, UBadge, UTable, UTabs | method: 'GET'\|'POST'\|'PATCH'\|'DELETE', path, description, access, keyAccess, body?, examples: { fetch, curl, response }, errors, sessionOnly? | none | none | Integration |
+| SectionIndex | custom nav (desktop), USelectMenu "Jump to" (mobile) | sections: { id, label }[], active: string | jump | none | Integration |
+| SessionOnlyGroup | UAlert-style note + list rows | routes: { method, path }[] | none | none | Integration |
+| ApiKeysTable | UTable, UBadge | keys: ApiKey[], showCreatedBy: boolean | revoke | none | API keys |
+| CreateApiKeyModal | UModal, UForm, UFormField, UInput | open: boolean | create | none | API keys |
+| ApiKeyReveal | UModal, UAlert, UButton | key: string | done | none | API keys |
 | ErrorView | custom + UButton | kind: 'not-found'\|'error' | retry | none | Not found, error boundary |
 | OfflineBanner | UBanner | none (reads useOnline) | none | none | DashboardShell |
 | AppBoot | USkeleton inside DashboardShell | none | none | none | First load of any verified route |
@@ -65,7 +70,7 @@ Responsive 400 px card from sm up, with its top 12 vh from the top. Below sm , t
 
 ### DashboardShell
 
-The sidebar has five destinations (Home, Articles, Users, Integration, Settings), and the user menu sits at its foot. The top bar carries the breadcrumbs and page title. Collapsing the sidebar leaves a 56 px icon rail. Below lg , the sidebar becomes a slideover.
+The sidebar has seven destinations for owner and admin (Home, Articles, Media, Users, Activity, Integration, Settings; regular users get Home, Articles, Media, Activity), and the user menu sits at its foot. For owner and admin, Settings expands to a Media group with Variants and Cache (see "Sidebar entry (1l)" in [image-variants](screens/image-variants.md)); it is built with the `children` of UNavigationMenu, and the same group appears in the mobile drawer. The top bar carries the breadcrumbs and page title. Collapsing the sidebar leaves a 56 px icon rail. Below lg , the sidebar becomes a slideover.
 
 RenewCMS
 
@@ -395,7 +400,7 @@ The chip at the foot of the sidebar no longer logs out on click. It opens the ac
 
 ### DashboardShell (changed)
 
-The navigation gains **Users** (users icon) between Articles and Integration, in the sidebar and in the mobile drawer. Breadcrumbs for the new pages are "Users" and "Profile". It later gains **Settings** (settings icon) after Integration, with the breadcrumb "Settings".
+The navigation gains **Users** (users icon) between Articles and Integration, in the sidebar and in the mobile drawer. Breadcrumbs for the new pages are "Users" and "Profile". It later gains **Settings** (settings icon) after Integration, with the breadcrumb "Settings". **Activity** (history icon) sits between Users and Integration; see `screens/activity.md`, "Sidebar".
 
 ### UsersTable, UserCardList
 
@@ -809,3 +814,42 @@ Exact values live in `source/AppFrame.dc.html` (the Settings and Home states). C
 | RestartOverlay | custom full-page `role="status"` | title, text, startedAt, slow | reload | App shell |
 | UpdateBanner | UAlert | state: 'available'\|'ready' | go-to-settings, dismiss | Home (owner) |
 | UpdatePill | UBadge | none | none | DashboardShell Settings item (dot on mobile) |
+
+## Added with Media cleanup
+### PurgeDuplicatesDialog
+Used by Settings ("Purge now") and Media, Duplicates tab ("Purge duplicates"). Built on `UModal`, `sm:max-w-md`, bottom sheet on mobile, cancel first, confirm is `color="error"`.
+- Props: `open`, `preview` (`groups`, `copies`, `articles`, `list[]`, `more`), `status` (`loading | ready | purging | nothing | error | partial | conflict`).
+- While `purging`: confirm shows `loader-circle` and reads "Purging…"; `dismissible` false, Cancel disabled.
+- Group row: 40×30 thumbnail, filename, "Kept · used in N articles", right-aligned "N copies merged". Max 5 rows, then "and N more groups".
+- Notices sit above the summary in a `UAlert` (soft): error for failure, warning for partial and conflict.
+- Emits `purged` (with counts). The parent shows the toast.
+
+### MediaCleanupCard
+Settings card. `USwitch` (square, `rounded-none`), `UInputNumber` with "days" suffix, read-only lines, divider, outline button. Saves on change and on blur or Enter; shows "Saving…" then "Saved" in the header. Read-only mode disables controls, hides the button and shows an info `UAlert`.
+
+### Media toolbar button
+Secondary `UButton` icon `merge`, label "Purge duplicates", after the sort menu on desktop; full width in the stacked toolbar on mobile (44 px).
+
+## Added with Activity
+Source: `source/activity-spec.js` (component inventory) and `source/ActivityFrame.dc.html`. All built on existing Nuxt UI v4 components and tokens; no new token.
+
+| Component | Nuxt UI base | Props | Emits | Slots | Used on |
+|---|---|---|---|---|---|
+| ActivityPage | custom page | none (reads the session role) | none | none | Activity |
+| ActivitySummaryStrip | UCard (as button) | summary, loading, activeFilter | apply-filter | none | Activity (owner, admin) |
+| ActivityFilterBar | UInput, USelectMenu, UButton, UBadge | filters, people, canFilterPeople | update:filters, clear | none | Activity |
+| ActivityTable | UTable (day separator rows), UAvatar, UBadge, UPagination, USelectMenu | items, total, page, size, loading | open, update:page, update:size | empty | Activity (md and up) |
+| ActivityCardList | UCard | same as ActivityTable | open | empty | Activity (below md) |
+| ActivityDetailsPanel | USlideover (right on desktop, bottom on mobile), UCard, UButton | item, index, total, open | previous, next, close | none | Activity |
+| ActivityDiff | custom list | changes | none | none | ActivityDetailsPanel |
+| ActivityFeedCard | UCard, UAvatar, UButton | items, loading, error, own | retry | none | Home |
+| RetentionCard | UCard, USelectMenu, UAlert, UButton | settings, canEdit | saved | none | Settings (owner) |
+
+- Sparkline: seven `div` bars inside the strip card, no chart library. The strip cards are real `button`s with the card as their label.
+- Day separators are full-width rows of the table. The "When" cell carries the exact time as its `title`.
+- The sentence is composed from the `action` code and params with the i18n messages (English and French); the target name is user content and is not translated.
+- Failed and security rows use `--rc-error-soft` / `--ui-error` and `--rc-warning-soft` / `--ui-warning` for emphasis, always paired with an icon or a word, never colour alone.
+
+## Added with Image variants
+
+The full inventory with the Nuxt UI mapping is in [image-variants](screens/image-variants.md#component-inventory). New components: Variants table (and its mobile card row), Variant row (image detail), Variant form, Split comparison slider (`ImageCompare`, a custom component on a native range input, since Nuxt UI has no match), Stat tile, Bar list, Top-N list, Type-to-confirm dialog, Variant select, Variants badge, Filter, Request reference card. Alerts, toasts, dialogs, empty states and skeletons are reused as they are. The only token not already in the system is `--rc-on-sand`.

docs/design/routes.md

@@ -11,16 +11,24 @@ A global `router.beforeEach` guard reads `meta.auth`. On the first navigation it
 | `/register/validate` | AuthShell | public | VerifyPage | POST /v1/auth/verify (+ POST /login inline on 401) |
 | `/register/reset/request` | AuthShell | public | ResetRequestPage | POST /v1/auth/password-reset |
 | `/register/reset/validate` | AuthShell | public | ResetConfirmPage | POST /v1/auth/password-reset/confirm |
-| `/home` | DashboardShell | verified | HomePage | GET /v1/article/ · GET /v1/system/update (owner, for the banner) |
+| `/home` | DashboardShell | verified | HomePage | GET /v1/article/ · GET /v1/activity?size=5 · GET /v1/system/update (owner, for the banner) |
 | `/article` | DashboardShell | verified | ArticlesPage | GET /v1/article/ · PATCH /{id}/publish\|unpublish · DELETE /{id} |
 | `/article/new` | DashboardShell | verified | ArticlesPage + NewArticleModal | POST /v1/article/ |
 | `/article/:id/edit` | DashboardShell | verified | EditorPage | GET /{id} · PATCH /{id} · PATCH /{id}/publish\|unpublish · GET /v1/media/ · POST /v1/media/ · DELETE /{id} |
-| `/media` | DashboardShell | verified | MediaPage | GET /v1/media/ · POST /v1/media/ · PATCH /v1/media/{id} · DELETE /v1/media/{id} · POST /v1/media/merge · GET /v1/media/{id}/usage |
+| `/media` | DashboardShell | verified | MediaPage | GET /v1/media/purge-preview · POST /v1/media/purge · GET /v1/media/ · POST /v1/media/ · PATCH /v1/media/{id} · DELETE /v1/media/{id} · POST /v1/media/merge · GET /v1/media/{id}/usage |
+| `/activity` | DashboardShell | verified | ActivityPage + ActivityDetailsPanel | GET /v1/activity · GET /v1/activity/summary (owner, admin) · GET /v1/activity/export (owner, admin) |
 | `/integration` | DashboardShell | verified | IntegrationPage | none |
+| `/integration/api-keys` | DashboardShell | verified | ApiKeysPage + CreateApiKeyModal | GET /v1/api-key · POST /v1/api-key · DELETE /v1/api-key/{id} |
 | `/users` | DashboardShell | verified | UsersPage + InviteUserModal | GET /v1/user/ · POST /v1/user/invite · DELETE /v1/user/invite/:id · POST /v1/user/invite/:id/renew |
-| `/settings` | DashboardShell | verified | SettingsPage | GET /v1/settings · GET /v1/system/update · POST /v1/system/update/check · POST /v1/system/update/download · POST /v1/system/update/restart |
+| `/settings` | DashboardShell | verified | SettingsPage | GET /v1/settings · PATCH /v1/settings (owner, retention) · GET /v1/system/update · POST /v1/system/update/check · POST /v1/system/update/download · POST /v1/system/update/restart · GET /v1/media/purge-settings · PATCH /v1/media/purge-settings · GET /v1/media/purge-preview · POST /v1/media/purge |
+| `/settings/media/variants` | DashboardShell | admin | VariantsPage + VariantFormSlideover | GET /v1/image-variants · POST /v1/image-variants · PUT /v1/image-variants/{name} · PATCH /v1/image-variants/{name} · DELETE /v1/image-variants/{name} · POST /v1/image-variants/{name}/purge (all proposed) |
+| `/settings/media/cache` | DashboardShell | admin | CachePage | GET /v1/image-variants/cache · POST /v1/image-variants/cache/purge (proposed) |
 | `/profile` | DashboardShell | verified | ProfilePage | GET /v1/auth/me · PATCH /v1/user/me · POST /v1/auth/password-reset |
 | `/invite/accept` | AuthShell | public | AcceptInvitePage | GET /v1/auth/invite?c=* · POST /v1/auth/invite/accept* |
 | `/:pathMatch(.*)*` | either | any | NotFoundPage | none |
 
-Auth values: `public` needs no session, `session` needs a logged-in account (verified or not), `verified` needs a verified account, `any` applies to redirects and the catch-all.
+The sidebar reaches `/settings/media/variants` and `/settings/media/cache` through the Media group under Settings (owner and admin only). See [image-variants](screens/image-variants.md), frame 1l.
+
+`/media` and `/article/:id/edit` also gain image variants: GET /v1/media/{id}/variants · POST|DELETE /v1/media/{id}/variants/{name} and the `variants` and `sort=total_size` query parameters on GET /v1/media/ (proposed). See [image-variants](screens/image-variants.md).
+
+Auth values: `public` needs no session, `session` needs a logged-in account (verified or not), `verified` needs a verified account, `admin` needs an admin or owner account, `any` applies to redirects and the catch-all.

docs/design/screens/activity.md

@@ -0,0 +1,183 @@
+# Activity
+
+- **Route:** `/activity`
+- **API:** GET /v1/activity · GET /v1/activity/summary · GET /v1/activity/export (see "API contract" below)
+- **Visual reference:** `source/RenewCMS Screens Back-office.dc.html`, group "Activity" (the same board also has the groups "Activity details" and "My activity"), drawn by `source/AppFrame.dc.html` with the page from `source/ActivityFrame.dc.html` (open it in a browser; each state is drawn at desktop and mobile, with a light/dark toggle). The frame is `source/ActivityFrame.dc.html`; its copy, component mapping and API tables are `source/activity-spec.js`.
+
+The audit log of the back-office: who did what, and when, across articles, media, users and invites, API keys, authentication and system tasks. It is for non-technical owners, so every row reads as a sentence, not a log line. Events are append-only: nothing in the app edits or deletes them. Only the retention period removes them (Settings, "Retention").
+
+Other groups of the same board:
+
+| Group | What it draws | Written up in |
+|---|---|---|
+| Details slide-over | The slide-over and its bottom-sheet variant, six events | this file, "Details slide-over" |
+| My activity | The same screen for a user who is not owner or admin | this file, "My activity" |
+| Home section | The Recent activity section on Home | `screens/home.md`, "Recent activity" |
+| Settings retention | The Retention card, last on Settings | `screens/settings.md`, "Activity retention" |
+
+## Roles
+
+Owner and admin see every event, the summary strip, the Person filter and Export. Any other role sees only its own events: the title becomes "My activity", the strip, the Person filter and Export are hidden, and the server scopes the list to that user (asking for another actor answers 403).
+
+Today the product has only `owner` and `admin` (see `screens/users.md`, "Roles"), so "My activity" and the scoped answer cannot be reached by a real account yet. They are specified and tested now so a future role needs no rework. The board's sample "Editor" role and the nav it draws for a regular user (Home, Articles, Media, Activity) are illustrative.
+
+## Sidebar
+
+"Activity" (icon `history`) sits between Users and Integration for owner and admin: Home, Articles, Media, Users, Activity, Integration, Settings. The board draws the order that way. It is visible to every verified user. The mobile drawer gets the same item.
+
+## The page
+
+Title "Activity" (regular users: "My activity"). Subtitle "Who did what, and when, across your site." (regular users: "Everything you've done on this site."). Page padding 24 px desktop, 16 px mobile; the sidebar and top bar are the existing DashboardShell.
+
+1. **Header action** (owner and admin): outline `UButton` with icon `download`, "Export CSV". While the file is prepared: "Preparing file…" and disabled. Success toast "Export started. Your file will download shortly." Error toast "Couldn't export activity. Try again." Disabled in "Empty, no activity yet".
+2. **Summary strip** (owner and admin): four `UCard`, each a `button`. Labels: "Total actions", "Active people", "Failed actions", "Security events". Each shows the number, a sub-line and a seven-bar sparkline (seven `div` bars, no chart library, oldest left).
+   - Total: "12% vs previous 7 days" with `trending-up` / `trending-down` (the comparison is against the equal-length period just before the selected range). Click clears the filters.
+   - Active people: "7 people, 2 API keys". Click does nothing (no equivalent filter).
+   - Failed: "0.5% of all actions". Emphasis with `--rc-error-soft` and `--ui-error`, icon `circle-x`. Click applies Outcome = Failed.
+   - Security: "5 failed logins". Emphasis with `--rc-warning-soft` and `--ui-warning`, icon `shield-alert`. Click applies the security filter (auth, role changes, API key create and revoke).
+   - Zero: Failed shows "0" with "Nothing failed" and `circle-check`; Security shows "0" with "Nothing to flag" and `circle-check`; both drop the emphasis fill. No data at all: every card reads "0" with the sub-line "No data yet" (Failed and Security keep their calm lines).
+   - The strip follows the date range filter. Mobile: a 2×2 grid.
+3. **Filter bar**: `UInput` (icon `search`, clearable, "Search activity"), Person `USelectMenu` (grouped: users, API keys, "System"; "All people"), Category `USelectMenu` ("All categories": Articles, Media, Users and invites, API keys, Authentication, System), Outcome button group (All / Succeeded / Failed; `soft` is the selected one), date presets (Today / 7 days / 30 days / Custom; Custom opens a date-range popover). Mobile: the bar collapses to a search field and a "Filters" button with a count badge; the controls move to a bottom sheet.
+4. **Active filter chips**: `UBadge` (subtle) with a trailing ghost `x` button: "Search: spring", "Person: Marta Alves", "Category: Authentication", "Outcome: Failed", "Dates: 1 – 30 Sep 2026", then a `link` button "Clear all". The default date range (7 days) is not a chip.
+5. **Timeline table**: newest first, grouped by day with full-width separator rows ("Today", "Yesterday", "3 Oct 2026"). Columns: When (relative within the day, clock time before; the full time is the cell's `title`), Actor (`UAvatar` with initials, a key icon for API keys or a cog for System, plus the name; badges "API key" / "System"; a signed-out actor reads "Not signed in"), Action (category icon and the sentence with the target name in semibold; a `shield` marker on security rows), Target (a link when it still exists; struck through with a "Deleted" badge when it does not), Outcome (`UBadge` "Succeeded" / "Failed"). Row click and Enter open the details.
+6. **Pagination**: "Showing 1–25 of 1,284", `UPagination`, "Rows per page" select (25, 50, 100). Mobile: "Page 1 of 52" with previous and next.
+7. **Mobile list**: below `md` the table is a stacked list of `UCard` rows (actor, sentence, time, outcome, "Target deleted" when relevant), 44 px touch targets.
+
+Sentences are composed in the SPA from a stable `action` code and the event params, in the user's language (English and French), never stored as text. The target name and the typed values in a diff stay as the user wrote them.
+
+## States
+
+### Default, large dataset
+**Trigger:** Both requests resolved with 1,284 events over 52 pages. Newest first, day separators, a security row. Hover on the first row shows its exact time.
+
+### Loading
+**Trigger:** Both requests in flight. Skeleton strip and table rows after 150 ms.
+
+### Zero-value summary strip
+**Trigger:** A quiet period. Failed and Security show a calm 0.
+
+### Filtered, card applied
+**Trigger:** The Failed actions card was clicked. Chips plus "Clear all"; mobile shows the count on Filters. Six results.
+
+### Mobile filters sheet
+**Trigger:** Filters open as a bottom sheet on mobile. The desktop frame keeps the inline bar. Sheet: title "Filters", Person (owner and admin), Category, Outcome, Dates (two date fields when Custom), footer "Clear all" and "Show 23 results".
+
+### Empty, no activity yet
+**Trigger:** A new site. `UEmpty` with icon `history`, title "No activity yet", description "Actions on articles, media, users and API keys will appear here." Export disabled.
+
+### Empty, filters match nothing
+**Trigger:** Filters with zero results. Title "No activity matches these filters", description "Try a different search or a wider date range.", action "Clear filters".
+
+### Error with retry
+**Trigger:** The list request failed (500 or network). `UEmpty` in the table area: "Couldn't load activity", "Check your connection and try again.", action "Try again". The strip still shows if its own call succeeded.
+
+### Forbidden (403)
+**Trigger:** The API answered 403 for this role or filter. "You can't view this activity.", "Your role doesn't include this page. Ask an owner or admin if you need access.", action "Back to home". The 401 is global.
+
+## Details slide-over
+
+`USlideover`, right side on desktop (about 440 px wide), bottom sheet on mobile. Opens from a row (click or Enter), closes with Escape, the close button or the scrim; focus returns to the row. Title "Activity details".
+
+Body, in `UCard` sections:
+
+- The full sentence, with the target name in semibold.
+- When: the user's local time, then a muted "UTC" line.
+- Actor (with the same badges), Source ("Web app", "API key", "System task"), IP address, Browser. For a system event, IP address and Browser read "Not applicable".
+- Target: name (struck through with a "Deleted" badge, plus "This item was deleted. Its name is kept for reference." when it no longer exists), and a link when it exists.
+- Why it failed (failed events only): the plain-language reason from the API, never a stack trace.
+- Changes (edits only): rows of field, Before, After. Values longer than two lines clamp with "Show more" / "Show less". A body edit is a single row "Body edited (+312 characters)" and never shows text.
+- Footer: "Previous event" and "Next event" buttons and "Event 2 of 1,284". They move through the current filtered list, across page boundaries.
+
+### Edit with a diff
+**Trigger:** A title change and a body edit. Title Before and After, then "Body edited (+312 characters)".
+
+### Settings diff, long text
+**Trigger:** Long values clamp to two lines with "Show more".
+
+### Failed action, very long target title
+**Trigger:** A failed publish. The reason is shown and the long target title wraps.
+
+### Deleted target, no diff
+**Trigger:** A deleted image. Struck-through target, "Deleted" badge, no Changes section.
+
+### System-initiated, no human actor
+**Trigger:** A scheduled task. "System" badge, source "System task", IP and Browser "Not applicable".
+
+### Security event, failed login
+**Trigger:** The actor was not signed in. "Not signed in", a restrained `shield` marker, the reason, the IP and browser.
+
+## My activity
+
+The same screen for a role that is not owner or admin. No summary strip, no Person filter, no Export. The list is the user's own events (server scoped).
+
+### Default
+**Trigger:** The user has events. Title "My activity".
+
+### Empty
+**Trigger:** No events yet: "No activity yet", "Your actions will appear here once you start working on the site."
+
+### Details
+**Trigger:** The slide-over on one of the user's own events.
+
+## API contract
+
+401 and 403 on every route follow `states.md`, "HTTP status to copy". The board's table in `source/activity-spec.js` is the source; this section fixes the parts it leaves open.
+
+**`GET /v1/activity`**
+
+- Query: `q`, `actor` (`user:ID`, `key:ID`, `system`), `category` (`articles`, `media`, `users`, `api_keys`, `auth`, `system`), `outcome` (`all`, `success`, `failed`), `security` (`true`), `range` (`today`, `7d`, `30d`, `custom`), `from`, `to` (ISO dates, with `custom`), `page` (from 1), `size` (25, 50 or 100; default 25). Sorted by `created_at` descending, then `id` descending. Invalid values answer 400 "The request cannot be processed due to a mismatch in the format of the body."
+- `security=true` is what the Security card applies; it is a flag on the event, not a category.
+- Response: `{ items, total, page, size }`. An item:
+
+```json
+{
+  "id": 4821,
+  "created_at": "2026-10-06T10:42:18Z",
+  "action": "article.publish",
+  "category": "articles",
+  "actor": { "type": "user", "id": 3, "name": "Marta Alves" },
+  "target": { "type": "article", "id": "8", "name": "Spring release", "exists": true },
+  "outcome": "success",
+  "failure_reason": null,
+  "security": false,
+  "source": "web",
+  "ip": "203.0.113.12",
+  "user_agent": "Chrome 129 on Windows",
+  "changes": [{ "field": "online", "kind": "text", "before": "false", "after": "true" }]
+}
+```
+
+- `actor.type` is `user`, `api_key`, `system` or `anonymous` (a failed login). `actor.name` is a snapshot taken when the event was recorded, so a renamed or deleted user still reads correctly. `target.name` is a snapshot too; `target.exists` is resolved when the list is read.
+- `action` is a stable dotted code. The SPA owns the wording, in English and French. `params` holds extra values a sentence needs (for example `{ "merged": 3, "articles_updated": 5 }` on a media purge); they are never secrets.
+- `changes[].kind` is `text` or `body`. A `body` change has `delta` (a signed number of characters) and no `before` or `after`. Only allowlisted fields ever appear in `changes`, and never a password, hash, API key, token or article body.
+- `source` is `web`, `api_key` or `system`. `ip` and `user_agent` are `null` for `system`.
+- A caller who is not owner or admin is scoped to its own events; `actor` other than itself answers 403.
+
+**`GET /v1/activity/summary`** (owner and admin; 403 otherwise)
+
+Same `range`, `from`, `to`. Response: `total`, `previous_total`, `active_people: { users, api_keys }`, `failed`, `security`, and `series` with seven daily counts for `total`, `active`, `failed` and `security`. The previous period is the equal-length period immediately before the range.
+
+**`GET /v1/activity/export`** (owner and admin; 403 otherwise)
+
+The same filters without `page` or `size`. Streams `text/csv; charset=utf-8` with `Content-Disposition: attachment`. Columns: `when` (RFC3339 UTC), `actor`, `action` (the code), `target`, `outcome`, `source`, `ip`. No changes, no user agent, no secrets. Cells that start with `=`, `+`, `-` or `@` are prefixed with a quote so a spreadsheet does not evaluate them.
+
+**`GET /v1/settings` and `PATCH /v1/settings`**: see `screens/settings.md`, "Activity retention".
+
+These routes are session only: with an API key they answer 403 "This action needs a real session." (A key never reads the audit trail.)
+
+## What is recorded
+
+Every row of the board is a sample. The real catalogue is the set of actions that exist in the product, in these categories:
+
+| Category | Events |
+|---|---|
+| `articles` | create, edit (title, publish state, body size delta), publish, unpublish, delete |
+| `media` | upload, rename, delete, merge, purge (manual; the scheduled run is a `system` event) |
+| `users` | register, verify account, update profile (display name), invite create, cancel, renew, accept |
+| `api_keys` | create, revoke |
+| `auth` | login succeeded, login failed (security), logout, password reset requested (security), password reset completed (security) |
+| `system` | update checked, update downloaded, restart requested, scheduled media purge, activity retention changed, activity cleanup |
+
+Not drawn as real events: the "Editor" role and role changes, a "Site description" or "Comments" setting, "Ran the nightly backup" (backups are a step of the update job, not a schedule), "Removed 3 expired invites" and an administrator resetting another user's password. They stay in the board as sample data and are only recorded if the matching feature exists.
+
+Read requests are not recorded (no "article viewed"), and neither are public API reads.

docs/design/screens/home.md

@@ -54,3 +54,13 @@ The greeting reads "Good morning, {name}", where the name is the display name wh
 **Trigger:** The download is checked. The same banner changes its copy, and a dismiss comes back on the next visit because the update is waiting.
 
 - Banner: success tone, `circle-check` icon, title "Version 2.3.0 is ready to install", text "Restart from Settings to finish. The site is unavailable for about 10 seconds.", button "Go to Settings"
+
+## Recent activity
+
+**API:** GET /v1/activity?size=5. Visual reference: `source/RenewCMS Screens Back-office.dc.html`, group "Home" (states Default, Recent activity: loading, error and empty, Regular user), drawn by `source/AppFrame.dc.html`. This is the layout of record. The older Home card on the Activity board is superseded.
+
+A section with the last five events, built like "Recently updated" above it: a 16 px semibold heading on the left ("Recent activity") and an underlined "View all" link on the right, then a bordered list. Header "Recent activity" (regular users: "Your recent activity") and a "View all" link with `arrow-right` to `/activity`. Each row: a 24 px avatar, the sentence clamped to two lines with the target in semibold, then "Marta Alves · 2 min ago" (own events: only the time). A failed event gets a "Failed" badge; a successful security event a small `shield`.
+
+- Placement: full width, below the stats and the "Recently updated" list, on desktop and mobile. There is no side column. "View all" links to `/activity`.
+- States: Owner or admin, Regular user, Loading (five skeleton rows after 150 ms), Error ("Couldn't load recent activity" with "Try again"), Empty ("No activity yet", "Actions on your site will appear here." / own: "Your actions will appear here.").
+- The section never blocks the page: an error or empty card leaves the stats and the article list as they are.

docs/design/screens/image-variants.md

@@ -0,0 +1,330 @@
+# Image variants
+
+- **Routes:** `/settings/media/variants` and `/settings/media/cache` (admins and owners), plus additions to `/media` and `/article/:id/edit`
+- **API (proposed by the design, to be fixed by the feature spec):** GET/POST /v1/image-variants · PUT/PATCH/DELETE /v1/image-variants/{name} · POST /v1/image-variants/{name}/purge · GET /v1/image-variants/cache · POST /v1/image-variants/cache/purge · GET /v1/media/{id}/variants · POST/DELETE /v1/media/{id}/variants/{name}
+- **Public contract:** `<public image URL>?v=<name>`, see section 7
+- **Visual reference:** `source/RenewCMS Screens Image variants.dc.html`, drawn by `source/VariantsFrame.dc.html` inside the `AppFrame.dc.html` back-office frame (open it in a browser; each state is drawn at desktop and mobile, with a light/dark toggle). Every frame is numbered; the numbers below match.
+
+Named variants of an original image. The original is never changed. An admin defines variants (a name, a width and/or height, a fit, a format, a quality). A request for an image with `?v=<name>` generates the variant on first use, caches it, and serves the cached file afterwards. Only variants that exist and are enabled are served: anything else is a 400. There is no arbitrary-size mode and no raw `width`, `height`, `format` or `quality` parameter.
+
+Vocabulary: "variant", "generated", "purge". Delete removes a variant definition; purge removes only its generated files. Never "thumbnail preset", "version" or "rendition".
+
+Variant fields: name (slug, 2 to 32 lowercase letters, numbers and dashes, unique, immutable after creation), width and height (1 to 8000 px, at least one required, images are never enlarged), fit (cover, contain, inside), format (original, JPEG, PNG, WebP; no AVIF), quality (1 to 100, hidden for PNG), generate on upload, enabled.
+
+## 1. Settings → Media → Variants
+
+- **Route:** /settings/media/variants
+- **API:** GET /v1/image-variants · PATCH /v1/image-variants/{name} · DELETE /v1/image-variants/{name} · POST /v1/image-variants/{name}/purge (proposed)
+
+Admin-only page under Settings → Media, with two tabs: Variants and Cache. Desktop shows a table; mobile stacks each variant as a card. The status switch always pairs with an icon and the words Enabled or Disabled. The reference card "How requests are handled" sits under the table (section 7 of the brief).
+
+| State | Name | Trigger |
+|---|---|---|
+| 1a | Loaded | Six variants, one of them disabled (print). |
+| 1b | Loading | Skeleton rows appear after 150 ms. |
+| 1c | Empty | No variants. Two templates pre-fill the Add variant form. |
+| 1d | Error loading | A 500 or network failure on the list request. |
+| 1e | Forbidden | A signed-in user who is not an admin opens the URL. |
+| 1f | Row menu | The ellipsis button on a row. |
+| 1g | Row action in progress | Purge cache was confirmed on hero. The row is dimmed and its controls are disabled. |
+| 1h | Purge confirm | Purge cache in the row menu. |
+| 1i | Delete confirm | Delete in the row menu. |
+| 1j | Delete in progress | Delete was confirmed. The button shows a spinner. |
+| 1k | Request reference | Mobile scrolled to the reference card. On desktop it is visible below the table. |
+| 1l | Entry: sidebar | From any page, Settings expands in the sidebar to Media: Variants and Cache. Admin only. On mobile the menu button opens it as a drawer. |
+
+**Sidebar entry (1l).** For owner and admin, the Settings item has a chevron (right when closed, down when open) and expands to a group: a muted uppercase label "Media" (11 px, semibold, 0.04em tracking), then "Variants" (layers icon) and "Cache" (database icon). The group is indented 19 px with a 1 px left border; its items are 32 px high (44 px in the mobile drawer) with 14 px icons. The group is open on every `/settings` route. When a subpage is current, its item takes the sand fill and Settings keeps only the highlighted text and medium weight. On `/settings` itself Settings is the current item. Other roles see no chevron and no group. Cache stays inert until its screen exists.
+
+### Copy: Variants list
+
+| State | Where | Copy |
+|---|---|---|
+| Header | Title, description, button | Image variants · Named sizes and formats generated from your original images. Originals are never changed. · Add variant |
+| Table columns | Header row | Name · Dimensions · Fit · Format · Quality · Generated · Cache size · Status |
+| Dimensions | Cell | 400×300 · 800 × auto · auto × 2400 |
+| Quality | Cell | 80 · — (PNG has no quality) |
+| Status | Switch + text | Enabled · Disabled (aria-label: "Enable variant hero") |
+| Row menu | Menu items | Edit · Purge cache · Delete |
+| Footer summary | Under the table | 6 variants · 1,284 generated files · 212 MB |
+| Footer summary (singular) | One variant | 1 variant · 1 generated file · 18 KB |
+| Loading | Skeleton | No text. Region announces "Loading variants". |
+| Empty | Title · text | No variants yet · A variant is a named size that an image can be requested in, like ?v=thumb. Start with one of these. |
+| Empty | Template cards | thumb · 400×300 · cover · WebP — hero · 1200×630 · cover · WebP — Use template |
+| Error | Alert | Couldn't load variants · Check your connection and try again. · Try again |
+| Forbidden | Title · text · button | You don't have access · Only admins can manage image variants. Ask an admin if you need one changed. · Back to Home |
+| Row in progress | Status cell | Purging… |
+| Purge success | Toast | Purged 244 files from “hero” |
+| Purge dialog | Title · text · buttons | Purge cache for “hero”? · This removes 244 generated files (84 MB). Files are generated again on the next request. · Cancel · Purge 244 files |
+| Delete dialog | Title · text · buttons | Delete variant “hero”? · This removes the variant and its 244 generated files (84 MB). Articles that use ?v=hero will start returning 400. This can't be undone. · Cancel · Delete variant |
+| Delete success | Toast | Variant “hero” deleted |
+| Request reference | Card | How requests are handled · Body of a 400 response · unsupported_parameter replaces unknown_variant when a raw parameter is sent. There is no arbitrary-size mode. |
+
+## 2. Add / edit variant
+
+- **Route:** Slide-over on desktop · full page on mobile
+- **API:** POST /v1/image-variants · PUT /v1/image-variants/{name}
+
+Form on the left, live preview on the right (stacked on mobile). The preview uses a sample image with a before/after divider. The divider is a slider: arrow keys move it by 1%, Shift+arrow by 10%, Home and End jump to the ends. Name is locked in edit mode. The edit warning is always visible in edit mode. Preview images are placeholders.
+
+| State | Name | Trigger |
+|---|---|---|
+| 2a | Create: pristine | Add variant just opened. Save is disabled. |
+| 2b | Create: dirty | Valid values. The divider has keyboard focus. Mobile is scrolled to the preview. |
+| 2c | Field errors | On blur and on submit. Name format, width above 8000, quality above 100. |
+| 2d | No dimension | Width and height are both empty on submit. |
+| 2e | Name already taken | POST returns 409. |
+| 2f | Saving | Request in flight. Fields and buttons are disabled. |
+| 2g | Save error | A 500 or network failure. Values are kept. |
+| 2h | Edit: pristine | Opened from Edit. Name is locked. Save is disabled. |
+| 2i | Edit: dirty | Quality changed from 82 to 70. |
+| 2j | Unsaved changes | Close, Cancel or Escape while dirty. |
+| 2k | PNG: no quality | Quality is hidden when the format is PNG. |
+
+### Copy: Add / edit variant
+
+| State | Where | Copy |
+|---|---|---|
+| Titles | Slide-over header | Add variant · Edit variant: hero |
+| Name | Label · placeholder · help | Name · e.g. hero · Lowercase letters, numbers and dashes. Can't be changed later. |
+| Name (edit) | Help | The name can't be changed. |
+| Name error: format | Inline | Use lowercase letters, numbers and dashes, 2 to 32 characters. |
+| Name error: taken | Inline | A variant named “thumb” already exists. Choose another name. |
+| Width · Height | Label · suffix · placeholder · help | Width · Height · px · auto · Set a width, a height, or both. 1–8000 px. Images are never enlarged. |
+| Dimension error | Inline | Set a width, a height, or both. |
+| Dimension range error | Inline | Enter a value from 1 to 8000. |
+| Fit | Options · help | Cover: Fills the box and crops what overflows. · Contain: Whole image inside the box, padded to the box size. · Inside: Whole image inside the box, no padding. |
+| Format | Options · help | Original · JPEG · PNG · WebP · Keeps the format of each source image. |
+| Quality | Label · help · error | Quality · 1–100. Higher is sharper and larger. · Enter a value from 1 to 100. |
+| Toggles | Label · help | Generate on upload: Creates this variant when an image is uploaded. · Enabled: Disabled variants return 400 on the public site. |
+| Edit warning | Alert (edit only) | Changing dimensions, fit, format or quality purges 244 generated files; they will be regenerated on next request. |
+| Preview | Heading · labels · hint | Preview · Sample: north-wall.jpg · Original — 4032 × 3024 · 3.9 MB · hero — 1200×630 · about 96 KB · Drag the divider, or focus it and use the arrow keys. The estimate comes from a sample; output is never larger than the source. |
+| Preview (no size) | Over the image | Set a width or height to see a preview. |
+| Slider | aria-label · aria-valuetext | Compare original and hero · 50% hero |
+| URL | Label · button | URL · /media/north-wall.jpg?v=hero · Copy · Copied |
+| Footer | Status · buttons | Unsaved changes · Cancel · Add variant · Save changes · Saving… |
+| Save error | Alert | Couldn't save the variant · Check your connection and try again. · Try again |
+| Save success | Toast | Variant “hero” added · Variant “hero” saved. 244 files purged. |
+| Unsaved dialog | Title · text · buttons | Discard changes? · You have unsaved changes to “hero”. If you close now, they're lost. · Keep editing · Discard changes |
+
+## 3. Media library
+
+- **Route:** /media
+- **API:** GET /v1/media?variants=with|without&sort=total_size (proposed)
+
+The existing grid with three additions: a "N variants" badge on cards that have cached files, an All / With variants / Without filter, and the sort option "Largest total size (original + variants)". When sorted by total size, the meta line shows the total.
+
+| State | Name | Trigger |
+|---|---|---|
+| 3a | Grid with badges | Default view. Images with no cached variants have no badge. |
+| 3b | Sort menu | The sort select is open. The new option is last. |
+| 3c | Filter: With variants, sorted by total size | The meta line becomes total · original + variants. |
+| 3d | Filter: Without variants | Images no variant has been generated for. |
+| 3e | Filter: nothing to show | With variants, and the cache is empty. |
+| 3f | Delete confirm | Delete on an image that has cached variants. |
+
+### Copy: Media library additions
+
+| State | Where | Copy |
+|---|---|---|
+| Badge | Card | 4 variants · 1 variant |
+| Filter | Segmented control | All · With variants · Without |
+| Sort | Select, new option | Largest total size (original + variants) · mobile label: Largest total size |
+| Meta line (sorted by total) | Card | 4.2 MB total · 3.9 MB + 260 KB |
+| Empty filter | Title · text · button | No images with variants · Variants are generated when an image is requested with ?v=<name>, or from its Variants tab. · Show all images |
+| Delete dialog | Title · text · note · buttons | Delete this image? · "north-wall.jpg" is used in 2 articles. If you delete it, they will show a broken image. This can't be undone. · Also removes 4 generated variants (260 KB) · Cancel · Delete image |
+| Bulk delete | Dialog line | Also removes 11 generated variants (1.1 MB) |
+
+## 4. Image detail: Variants tab
+
+- **Route:** /media (detail panel)
+- **API:** GET /v1/media/{id}/variants · POST /v1/media/{id}/variants/{name} · DELETE /v1/media/{id}/variants/{name} (proposed)
+
+The detail panel gets a Variants tab with one row per enabled variant. On desktop the row actions are icon buttons with tooltips and accessible names; on mobile they are labeled buttons on their own line. Only actions that apply are shown: generated rows offer Copy URL, Preview and Purge; others offer Copy URL and Generate now. The tab shows output dimensions as they will be generated, capped at the source size.
+
+| State | Name | Trigger |
+|---|---|---|
+| 4a | Partly generated | Four of five generated. Saving is shown against the original. |
+| 4b | Nothing generated yet | No cached files for this image. |
+| 4c | Generating | Generate all or Generate now was pressed. Rows show a spinner. |
+| 4d | Generation failed | The row shows the cause and Retry. Both causes are shown together for reference. |
+| 4e | No variants defined | There are no enabled variants. |
+| 4f | Source is an SVG | Variants aren't generated for vector images. |
+| 4g | Source is an animated GIF | Same rule as SVG. |
+| 4h | Preview dialog | Preview on a generated row. Both at actual size. |
+
+### Copy: Variants tab
+
+| State | Where | Copy |
+|---|---|---|
+| Tabs | Panel | Details · Variants |
+| Original | Header block | Original · kept untouched · north-wall.jpg · JPEG · 4032 × 3024 · 3.9 MB |
+| Summary | Above the list | 4 of 5 generated · Nothing generated yet. · Generating variants… |
+| Generate all | Button | Generate all · Generating… |
+| Row status | Badge | Generated · Not generated · Generating · Failed |
+| Row meta (generated) | Under the name | 400×300 · WebP · 18 KB · -99% vs original |
+| Row meta (not generated) | Under the name | 400×300 · WebP |
+| Row actions | Tooltip · aria-label | Copy URL · Preview · Generate now · Purge · Retry |
+| Failed: cause | Row line | Unsupported source format · Image too large |
+| No variants defined | Title · text · link | No variants defined · Define a variant in Settings to get resized copies of this image. · Settings → Media → Variants |
+| SVG / GIF | Alert | Variants aren't generated for this format. · SVG images are served as they are. · Animated GIFs are served as they are. |
+| Preview dialog | Title · panes · hint | Preview: thumb · thumb · 400×300 · WebP — 18 KB · saves 99% · Original · 4032×3024 · JPEG — 3.9 MB · Both images are shown at actual size. Scroll to pan. · Close |
+| Toasts | After actions | Generated 5 variants · Generated thumb · Purged 4 files (260 KB) · Couldn't generate hero. Image too large. |
+
+## 5. Settings → Media → Cache
+
+- **Route:** /settings/media/cache
+- **API:** GET /v1/image-variants/cache · POST /v1/image-variants/cache/purge {scope: all|unused|variant|image} (proposed)
+
+Stat tiles, a per-variant bar list (bar length is the disk size relative to the largest variant) and the ten images with the most variant disk usage. Purge all needs the word "purge" typed. Purge unused removes files of enabled variants not requested in 30 days.
+
+| State | Name | Trigger |
+|---|---|---|
+| 5a | Loaded | Default view. |
+| 5b | Loading | Tiles and lists show skeletons. |
+| 5c | Empty cache | Nothing generated. Purge buttons are disabled. |
+| 5d | Purging | Progress for a purge in progress. Content is dimmed. |
+| 5e | Purge done | The cache is empty and a toast reports the result. |
+| 5f | Purge failed | Part of the purge did not complete. |
+| 5g | Error loading | A 500 or network failure. |
+| 5h | Purge all: confirm | The word is not typed yet. The button is disabled. |
+| 5i | Purge all: confirm, typed | The input matches "purge". |
+| 5j | Purge unused: confirm | Variants of enabled variants not requested for 30 days. |
+
+### Copy: Cache panel
+
+| State | Where | Copy |
+|---|---|---|
+| Header | Title · text · buttons | Cache · Generated variant files. Purged files are generated again on the next request. · Purge unused · Purge all variants |
+| Tiles | Label · sub text | Generated files · Across 6 variants — Disk used · Originals not included — Variants defined · 5 enabled, 1 disabled — Rejected requests · Last 7 days |
+| Bar list | Heading · row | By variant · hero 244 files · 84 MB · Disabled (badge on disabled variants) |
+| Top 10 | Heading · row · button | Top 10 images by variant disk usage · north-wall.jpg · 6 variants · 5.8 MB · Purge |
+| Empty cache | Title · text | Nothing generated yet · Variants are generated on the first request with ?v=<name>, or from an image's Variants tab. |
+| Purging | Banner | Purging 1,284 files · 640 of 1,284 · 106 MB freed |
+| Purge done | Toast | Purged 1,284 files, freed 212 MB |
+| Purge failed | Toast | Purge didn't finish · 640 of 1,284 files were removed. Try again. · Try again |
+| Error | Alert | Couldn't load cache stats · Check your connection and try again. · Try again |
+| Purge all dialog | Title · text · field · buttons | Purge all variants? · This removes 1,284 generated files (212 MB) for every variant. Originals aren't touched. Files are generated again on request. · Type purge to confirm · Cancel · Purge all variants |
+| Purge unused dialog | Title · text · buttons | Purge unused variants? · This removes 312 files (41 MB) from enabled variants that haven't been requested for 30 days. Files are generated again on request. · Cancel · Purge 312 files |
+| Purge image (row) | Toast | Purged 6 files (5.8 MB) for north-wall.jpg |
+
+## 6. Editor image picker
+
+- **Route:** /articles/{id}/edit
+- **API:** Inserted URL: /media/{file}?v={name}
+
+The Library tab of the picker gets a Variant select. Options are Original plus the enabled variants, each with its dimensions and format. Once inserted, a block whose variant was deleted or disabled shows an inline warning with a way to fix it. Disabled variants do not appear in the select.
+
+| State | Name | Trigger |
+|---|---|---|
+| 6a | Variant select | An image is selected. The URL line shows what will be inserted. |
+| 6b | Select open | Original plus five enabled variants. |
+| 6c | No variants defined | Only Original is offered. |
+| 6d | Variant deleted | The block keeps its URL. Pick another variant opens the select. |
+| 6e | Variant disabled | Same block, different cause. Proposed copy. |
+
+### Copy: Editor picker
+
+| State | Where | Copy |
+|---|---|---|
+| Select | Label | Variant |
+| Options | Option label | Original · 4032×3024 · JPEG — Thumb · 400×300 · WebP — Card · 800 × auto · WebP — Hero · 1200×630 · WebP — Square · 600×600 · JPEG — Og · 1200×630 · JPEG |
+| URL line | Under the select | /media/north-wall.jpg?v=hero |
+| No variants | Help | No variants defined. Add one in Settings → Media → Variants. |
+| Block warning: deleted | Inline warning | Variant 'hero' no longer exists. This image returns an error on the public site. · Pick another variant |
+| Block warning: disabled | Inline warning (proposed) | Variant 'hero' is disabled. This image returns an error on the public site. · Pick another variant |
+| Block label | Chip on the image | hero · 1200×630 |
+
+## 7. Public request contract
+
+Shown as the "How requests are handled" card in section 1. Only variants that exist and are enabled are served. There is no arbitrary-size mode.
+
+| Request | Status | Body or result |
+|---|---|---|
+| /media/photo.png?v=thumb | 200 | The cached image. Generated on first request. |
+| /media/photo.png?v=unknown | 400 | Unknown variant |
+| /media/photo.png?v=hero (disabled) | 400 | Unknown variant |
+| /media/photo.png?width=400 | 400 | Unsupported parameter |
+| height, format or quality parameters | 400 | Unsupported parameter |
+| /media/missing.png?v=thumb | 404 | Not found |
+| 400 body shape |  | { "status": 400, "error": "unknown_variant" | "unsupported_parameter", "message": "Unknown variant", "detail": "banner" } |
+
+## 8. Activity log entries
+
+Row copy for the existing activity log. The actor name is bold, the quoted name is the variant name, and the detail line is secondary text.
+
+| Event | Row copy | Detail line |
+|---|---|---|
+| Variant created | Marta Alves created variant “hero” | 1200×630 · cover · WebP · quality 82 |
+| Variant updated | Marta Alves updated variant “hero” | Quality 82 → 70 · purged 244 files |
+| Variant deleted | Marta Alves deleted variant “hero” | Removed 244 generated files (84 MB) |
+| Variant enabled | Marta Alves enabled variant “hero” | Requests for ?v=hero are served |
+| Variant disabled | Marta Alves disabled variant “hero” | Requests for ?v=hero return 400 |
+| Cache purged: all | Marta Alves purged all variants | Removed 1,284 files (212 MB) |
+| Cache purged: unused | Marta Alves purged unused variants | Removed 312 files (41 MB) not requested for 30 days |
+| Cache purged: by variant | Marta Alves purged the cache of variant “hero” | Removed 244 files (84 MB) |
+| Cache purged: by image | Marta Alves purged the variants of north-wall.jpg | Removed 4 files (260 KB) |
+| Generate all | Marta Alves generated all variants of north-wall.jpg | 5 variants generated |
+| Generate all, with a failure | Marta Alves generated all variants of north-wall.jpg | 4 generated · 1 failed (Image too large) |
+| Image deleted | Marta Alves deleted north-wall.jpg | Also removed 4 generated variants (260 KB) |
+
+## States matrix
+
+Frame: a numbered state above. Copy: covered by the copy tables, with no separate frame. Existing: unchanged behavior of the existing screen.
+
+| Screen | Loaded | Empty | Loading | Error | Forbidden | In progress | Confirm | Validation | Success |
+|---|---|---|---|---|---|---|---|---|---|
+| 1 Variants list | Frame 1a | Frame 1c | Frame 1b | Frame 1d | Frame 1e | Frame 1g, 1j | Frame 1h, 1i | – | Copy |
+| 2 Add / edit | Frame 2a, 2h | – | – | Frame 2g | Copy | Frame 2f | Frame 2j | Frame 2c, 2d, 2e | Copy |
+| 3 Media library | Frame 3a | Frame 3e | Existing | Existing | – | – | Frame 3f | – | – |
+| 4 Image detail | Frame 4a | Frame 4b, 4e, 4f, 4g | Existing | Frame 4d | – | Frame 4c | – | – | Copy |
+| 5 Cache | Frame 5a | Frame 5c | Frame 5b | Frame 5g, 5f | Copy | Frame 5d | Frame 5h, 5i, 5j | Frame 5h, 5i | Frame 5e |
+| 6 Editor picker | Frame 6a, 6b | Frame 6c | Existing | Frame 6d, 6e | – | – | – | – | – |
+
+## Back-office API errors
+
+Shown as a toast, or inline where a field is named. The first line is the title, the second the text. The public media URL does not use these; see section 7.
+
+| Status | Title | Text | Where it shows |
+|---|---|---|---|
+| 400 | Check the request | A value in the request isn't valid. Reload the page and try again. | Toast |
+| 401 | Session expired | Sign in again to continue. | Redirect to sign in, then a toast |
+| 403 | You don't have access | Only admins can manage image variants. | Toast, or the forbidden state on the list |
+| 404 | Not found | This variant or image no longer exists. Refresh the page. | Toast |
+| 409 | Name already taken | A variant named “thumb” already exists. Choose another name. | Inline under Name |
+| 413 | Image too large | The source image is too large to generate this variant. | Row cause in the Variants tab |
+| 422 | Check the fields | Width and height must be between 1 and 8000, and one of them is required. | Inline under each field |
+| 500 | Something went wrong | The server couldn't finish. Try again. If it keeps happening, check the server log. | Alert or toast with Try again |
+
+## Component inventory
+
+Existing components are reused as they are. New components are built on Nuxt UI parts and use only existing tokens. Every icon-only button needs an aria-label and a UTooltip.
+
+| Component | Status | Nuxt UI mapping | Notes |
+|---|---|---|---|
+| Variants table | New | UTable | Cell slots for the status switch and actions. Below 640 px it renders as a list of UCard. |
+| Variant row (settings, mobile) | New | UCard + USwitch + UDropdownMenu | Name, spec line, counts, status switch and menu. |
+| Variant row (image detail) | New | UBadge + UButton + UTooltip | Status badge, meta line, contextual actions, error line. Spinner uses UIcon. |
+| Variant form | New | UForm, UFormField, UInput, USelect, USlider, USwitch, URadioGroup | Fit is a URadioGroup, horizontal, 3 options. Quality hides when the format is PNG. |
+| Slide-over / full page | New | USlideover (desktop) · routed page (mobile) | Close with unsaved changes opens the discard UModal. |
+| Split comparison slider | New | No match. Custom ImageCompare on a native range input | Two stacked images, clip-path on the top one. role="slider", arrow keys 1%, Shift 10%, Home and End. Handle ≥ 44 px on touch. |
+| Stat tile | New | UCard (default slot) | Icon, label, value, sub text. Skeleton uses USkeleton. |
+| Bar list | New | UProgress per row | Row with name, stats and a bar. Value is disk size over the largest variant. |
+| Top-N list | New | UCard + list rows + UButton | Thumbnail, name, count, size, Purge. |
+| Type-to-confirm dialog | New | UModal + UInput | Confirm button disabled until the input equals "purge". |
+| Variant select | New | USelectMenu | Item slot shows name, dimensions, format. Only enabled variants. |
+| Variants badge | New | UBadge (outline, icon layers) | Shown on media cards when count > 0. |
+| Filter | New | UTabs (variant link) or UButtonGroup | All, With variants, Without. |
+| Request reference card | New | UCard + code block | Table of responses and a JSON body. |
+| Alerts, toasts, dialogs, empty states, skeletons | Existing | UAlert, useToast, UModal, UEmpty pattern, USkeleton | Same copy patterns as the Media and API keys screens. |
+
+## Vocabulary and accessibility
+
+Use "variant", "generated" and "purge" everywhere. Never "thumbnail preset", "version" or "rendition". Delete removes a variant definition; purge removes only its generated files. Every status is an icon plus text: Generated (circle-check), Not generated (circle-dashed), Generating (loader), Failed (circle-x), Enabled (circle-check), Disabled (circle-off). The comparison slider has a visible focus ring and works from the keyboard. Dialogs trap focus and return it to the opener. Progress is announced with aria-live="polite". Touch targets on mobile are at least 44 px. The only token not already in the system is --rc-on-sand (dark ink on the sand selection color), used for the active nav item in both themes.
+
+## Implementation notes
+
+The board predates two decisions. Where the board and these notes differ, these notes win for behaviour and the board stays the reference for layout and copy structure.
+
+- The public URL is `/static/uploadedImages/<storedName>?v=<name>` (`image.PublicPathPrefix`), not `/media/<file>`. Every `/media/...?v=...` string in the copy tables above (URL field, Copy URL, URL line in the picker, request contract rows) shows that URL instead. `/media` stays the SPA library route.
+- WebP output depends on a CGO-free lossy encoder. If none is viable, the Format select offers Original, JPEG and PNG only.
+- The padding colour of `contain` is not drawn. The feature spec decides it.

docs/design/screens/integration-api-keys.md

@@ -0,0 +1,58 @@
+# Integration: API keys
+
+Route: `/integration/api-keys`. Component: `ApiKeysPage.dc.html`, mounted by `AppFrame`.
+
+- **Visual reference:** `source/RenewCMS Screens API keys.dc.html`, group "API keys", drawn by `source/ApiKeysPage.dc.html` (open it in a browser; each state is drawn at desktop and mobile, with a light/dark toggle).
+
+## API
+`POST /v1/api-key` · `GET /v1/api-key` · `DELETE /v1/api-key/{id}`. Access: Session only. An API key cannot manage keys; with a key these routes answer 403 "This action needs a real session."
+- `POST /v1/api-key` body: `name` (string, required, max 60), `expires_at` (RFC3339 string, optional, in the future). A past date answers 400 "The expiry must be a date in the future."
+- `DELETE /v1/api-key/{id}`: unknown id answers 404 "API key not found".
+
+## Placement
+Under Integration, as a sub-page linked from the Authentication section ("Manage API keys") and the sidebar item. Keys exist to call the API and admins can create them; Settings is owner-only today. The mobile top bar has a back arrow that returns to Integration.
+
+## Content
+- Columns: Name, Key (prefix, mono), Status (active, expired, revoked), Created by (owners only), Created, Last used, Expires, Revoke. Owners see all keys; admins see their own.
+- Create key modal: Name (required, up to 60, counter), Expiry date (optional, must be in the future). Errors: "Enter a name." / "Use 60 characters or fewer." / "Choose a date in the future."
+- The Expiry field is a native date input. The displayed format follows the browser's locale, so there is no custom format. The board draws one example date only.
+- One-time reveal: warning "You won't be able to see this key again.", monospace key, Copy / Copied, "Closing this window discards the key from the screen. Copy it first." Button "Done".
+- Revoke: "Revoke this key?" / ""Nightly media import" (rcms_Mq7b…) will stop working right away. Requests that use it answer 401. This can't be undone." Buttons "Keep key", "Revoke key". Toast "Key revoked".
+- Empty: "No API keys yet" / "Create a key to call the API from a script or service." Error: "Couldn't load your API keys" / "Check your connection and try again."
+- Note: "Resetting a user's password revokes all of their keys."
+
+## Mobile: pinned Create key
+On mobile the "Create key" button is pinned to the bottom of the viewport (44 px high, full width, on a bar with a top border). It shows in Owner list, Admin own keys only, Loading, Empty, Error and Revoked, and is hidden behind every modal state. In Empty it replaces the inline button. The content has bottom padding so nothing sits under the bar, and the toast sits above it. Desktop keeps "Create key" in the page header (and in the Empty card).
+
+## States
+
+Names are matched exactly by the visual-check script.
+
+### Owner: list
+
+### Admin: own keys only
+
+### Loading
+the list request is in flight. Skeleton rows appear only after 150 ms.
+
+### Empty
+
+### Error
+a 500 or network failure on the list request. If a key is created while this state is showing, the list reloads, the new key appears and the error alert is cleared.
+
+### Create key
+
+### Create key: validation
+
+### Create key: name too long
+
+### One-time reveal
+
+### One-time reveal: copied
+
+### Revoke: confirm
+
+### Revoked
+
+## Component inventory (Nuxt UI v4)
+`UTable`, `UBadge`, `UModal` with `UForm`/`UFormField`/`UInput` (type date), `UAlert` color warning, `UButton`, `useClipboard`.

docs/design/screens/integration.md

@@ -1,22 +1,82 @@
-# Connect your website
+# Integration (API reference)
 
-- **Route:** `/integration`
-- **API:** none (static)
-- **Visual reference:** `source/RenewCMS Screens Back-office.dc.html`, group "Integration" (open it in a browser; each state is drawn at desktop and mobile, with a light/dark toggle).
+Route: `/integration`. Component: `IntegrationPage.dc.html`, mounted by `AppFrame`. The API keys sub-page is in `screens/integration-api-keys.md`.
 
-Written for a developer. The base URL is window.location.origin.
+- **Visual reference:** `source/RenewCMS Screens Back-office.dc.html`, group "Integration", drawn by `source/IntegrationPage.dc.html` (open it in a browser; each state is drawn at desktop and mobile, with a light/dark toggle).
+
+## Navigation decision
+Sticky section index on the right (desktop), "Jump to" select (mobile). A reference is read in one scroll and searched with the browser, so tabs would hide content and break find-in-page and deep links; the index keeps one page with anchors and shows position.
+
+## Page copy
+- Header: breadcrumb "Integration", title "API reference", description "Everything a developer needs to build on RenewCMS."
+- Intro: "RenewCMS is headless: it stores your content and your own code displays it. There are two ways in. Public read-only access lets a website read online articles. API keys let a script or service manage articles, media and users without the back-office."
+- Base URL: label "Base URL", button "Copy" / "Copied" (2 s, announced).
+- Authentication, card "Public": "No key needed. Two read-only routes, and only online articles are returned." `GET /v1/article/`, `GET /v1/article/{id}`.
+- Card "API key": "Send `Authorization: Bearer rcms_…`. Requests act as the user who created the key, with that user's role (owner or admin). A key never has more rights than its creator." CodeBlock tabs curl, fetch (GET /v1/auth/me). "Keys start with `rcms_` and are shown in full once, when you create them." Link "Manage API keys".
+- Note 1: "A key can't create, list or revoke API keys, log in, register, verify or reset a password, or call anything under `/v1/system`. Those routes answer 403 "This action needs a real session." An invalid, unknown, expired or revoked key answers 401, even on public routes, and so does a key whose user was deleted or unverified."
+- Note 2: "Each key can make 120 requests per minute. Beyond that the API answers 429 with a `Retry-After` header."
+- Groups: Articles (7), Media (6), Users and invites (6), Settings (1), Session only (12 routes, 3 sub-groups; every `/v1/system` route is in this group). Session-only banner: "These routes need a signed-in browser session. With an API key they answer 403 "This action needs a real session.""
+- Errors: "Every error is a plain-text body with a single sentence. The status code is in the HTTP status line, and the Content-Type is text/plain." Table 400, 401, 403, 404, 429, 500 with the real messages below. Sample: a status line plus the text body (`HTTP/1.1 403 Forbidden`, `Content-Type: text/plain`, blank line, `This action needs a real session.`).
+- Notes: image URL prefix, CORS (existing copy), and "Article routes accept `?format=markdown`, `?format=html` or `?format=json` to choose how `body` is returned. With `json`, `body` is the stored JSON structure. Articles have `body_format: markdown` by default."
+
+## EndpointCard states
+- Collapsed (44 px row): method badge, mono path, one-line description, chips, chevron. Desktop is one line; mobile is three (method and path, description, chips).
+- Expanded: "Request body" table (Name, Type, Required, Rule; "No request body." when empty), tabs fetch / curl / Response with one CodeBlock and Copy, then "Errors": status chip plus one-line caption (also its `title` tooltip).
+- Session only: dashed border, muted fill, lock icon, "Session only" chip, no method colour, no expand.
+- Chips: access "Public", "Verified user", "Owner only"; key "API key OK" (success soft) or "Session only" (dashed, muted).
+- Method badges: GET `--ui-bg-inverted`, POST success soft, PATCH warning soft, DELETE error soft. Existing tokens only.
 
 ## States
+Desktop 1440×900, mobile 390×844, light and dark. Names are matched exactly by the visual-check script.
 
-### Default
+### 1. Default
 
-**Trigger:** Opened from the sidebar or the Home card.
+### 2. Group scrolled, one card expanded
 
-- Breadcrumbs: Integration (mobile title "Integration")
+### 3a. Copied: base URL
 
-### Copied
+### 3b. Copied: CodeBlock
 
-**Trigger:** The base URL was copied. The button reads "Copied" for 2 s and this is announced.
+### 4. Authentication
 
-- Breadcrumbs: Integration (mobile title "Integration")
-- copied: true
+### 5. Session only
+
+### 6. Errors
+
+### 7. Navigation
+
+## Error messages
+Plain text, one sentence. Used in the table and in the per-endpoint error captions.
+- 400: "The request cannot be processed due to a mismatch in the format of the body." / "The expiry must be a date in the future."
+- 401: "You must be logged in to access this resource."
+- 403: "This action needs a real session." (session-only routes called with a key) / "Only the owner can do this." / "You must verify your account to access this resource."
+- 404: "Article not found" / "Image not found" / "Invite not found" / "API key not found"
+- 429: "Too many requests. Please try again later." A per-key limit also sends `Retry-After`.
+- 500: "Internal server error"
+- 409, only as examples under their endpoints: `POST /v1/user/invite` "This address already has an account."; `POST /v1/media/merge` "Some of the images to merge changed. Refresh and try again." There is no 409 or 422 row in the table.
+- 413 and 415 on `POST /v1/media/` keep their earlier plain captions; no real message is known.
+
+## Request bodies
+- `POST /v1/article/`: `title` (string, required, 3 to 200 characters), `body` (string, required, max 10000).
+- `PATCH /v1/article/{id}`: `body` (string, required, max 10000).
+- `PATCH /v1/media/{id}` (rename): `filename` (string, required).
+- `POST /v1/media/merge`: `keep_id` (number, required, > 0), `merge_ids` (number[], required, at least 1, each > 0).
+- `POST /v1/media/`: multipart/form-data, 1 file field (shown as "multipart/form-data, 1 file field").
+- `PATCH /v1/user/me`: `display_name` (string, required, max 60 characters).
+- `POST /v1/user/invite`: `email` (string, required, valid email).
+- `POST /v1/system/update/restart`: optional body `{ "kind": "update" | "restart" }`.
+
+## Component inventory and Nuxt UI v4
+- EndpointCard (extended): `UCollapsible` (trigger is a button with aria-expanded), `UBadge` (method, chips, status), `UTable` (body fields), `UTabs` (fetch, curl, Response), CodeBlock.
+- SectionIndex (new): custom `<nav>` of anchor buttons with `aria-current`; sticky, scroll-spy. Mobile: `USelectMenu` labelled "Jump to".
+- SessionOnlyGroup (new): `UAlert`-style info note plus list rows; no new colour.
+- ErrorTable: `UTable`. Info notes: existing note style (or `UAlert` variant `naked`).
+
+## Assumptions to confirm
+- Paths not in the brief: `/v1/settings`, `/v1/system/update/*`, `POST /v1/auth/register|verify|logout`.
+- [to confirm] The multipart field name on `POST /v1/media/` is written as `file` as a placeholder.
+- Response field names in the samples (for example `articlesUpdated`, `display_name` in the profile response) are illustrative.
+- Code samples use a simple keyword and string colouring.
+
+## Tokens
+No new tokens. Foundations check: colours, radius (0) and spacing come from existing `--ui-*` and `--rc-*` values; every control has a 2 px primary focus ring; index, select and cards are keyboard operable. Open question: the board hard-codes a few pixel sizes, as the other screens do.

docs/design/screens/media.md

@@ -1,7 +1,7 @@
 # Media
 
 - **Route:** `/media` (verified users)
-- **API:** GET /v1/media/ · POST /v1/media/ · PATCH /v1/media/{id} · DELETE /v1/media/{id} · POST /v1/media/merge · GET /v1/media/{id}/usage
+- **API:** GET /v1/media/purge-preview · POST /v1/media/purge · GET /v1/media/ · POST /v1/media/ · PATCH /v1/media/{id} · DELETE /v1/media/{id} · POST /v1/media/merge · GET /v1/media/{id}/usage
 - **Visual reference:** `source/RenewCMS Screens Back-office.dc.html`, group "Media", drawn by `source/MediaFrame.dc.html` (open it in a browser; each state is drawn at desktop and mobile, with a light/dark toggle).
 
 The library of every uploaded image. It replaces "images belong to one article": an image belongs to the library and can be used in any number of articles. Deleting an article never deletes images. The sidebar gains **Media** (`images` icon) between Articles and Users, breadcrumb "Media".
@@ -12,7 +12,7 @@ New route for verified users, in the sidebar between Articles and Users with the
 
 Header: title "Media", subtitle "Every image you've uploaded, ready to use in any article.", primary "Upload" button (`upload` icon) on the right. On mobile the button is a full-width 48 px button pinned to the bottom (it turns into "Try again in 0:42" while rate limited, and is replaced by the bulk bar while items are selected).
 
-Toolbar: tabs **All**, **Unused** and **Duplicates** (count badge of duplicate groups, only while groups exist), then search ("Search by filename"), sort and the grid/list toggle. Sort options: Newest (default), Oldest, Name, Largest. Below md the toolbar stacks: search, tabs, then sort and toggle.
+Toolbar: tabs **All**, **Unused** and **Duplicates** (count badge of duplicate groups, only while groups exist), then search ("Search by filename"), sort and the grid/list toggle. Sort options: Newest (default), Oldest, Name, Largest. On the Duplicates tab, owners and admins also get a secondary "Purge duplicates" button (`merge` icon) after the sort menu (full width, 44 px, in the stacked toolbar on mobile), hidden while there are no groups; it opens the PurgeDuplicatesDialog described in [settings](settings.md#media-cleanup-second-card). Below md the toolbar stacks: search, tabs, then sort and toggle.
 
 Grid (default): 5 columns on desktop, 2 on mobile, 16 px gap (10 px on mobile). Each card is one button: 4:3 thumbnail (checkerboard behind transparent PNG and SVG), filename (medium, ellipsis), `size · dimensions` (SVG dimensions read "Vector"), then badges. The accessible name reads "north-wall.jpg, 3.9 MB, used in 2 articles" or "…, unused". A "Select all" row with the image count sits above the grid.
 
@@ -36,6 +36,10 @@ Detail panel copy:
 | Used | "Used in 2 articles", then one row per article: title (underlined link to the editor), badge "Online" (`globe`, inverted) or "Draft" (`pencil-line`, outline), `arrow-up-right`. Footnote: "Counted from the text of your articles each time you open this page." |
 | Not used | "Not used in any article" / "This image is safe to delete. No article shows it." |
 
+## Image variants
+
+The Library gains a "N variants" badge, an All / With variants / Without filter, the sort option "Largest total size (original + variants)", a delete dialog that names the generated variants it removes, and a Variants tab in the detail panel. Those states are in [image-variants](image-variants.md), sections 3 and 4.
+
 ## Dialogs
 
 All dialogs use the existing ConfirmDialog look (`UModal`, `sm:max-w-md`, bottom sheet on mobile, cancel first). While a request runs the confirm button shows a `loader-circle`, both buttons are disabled and the dialog cannot be dismissed. A failure shows an error alert at the top of the dialog body and the dialog stays open.
@@ -149,6 +153,7 @@ Grid items are buttons, one tab stop each. Enter opens the detail panel, Space t
 | Upload: rejected files (413, 400) | Type and size are checked in the browser first, so nothing is sent. A server 413 or 400 for a file that got through shows the same row with its own message. |
 | Upload: too many requests (429) | Rate limited. Retry-After is counted down in the button. It re-enables at zero. Already-added files are kept. |
 | Duplicates: groups | The Duplicates tab. Groups of identical images side by side, each with its uploader, upload date and "Used in N articles". The suggested copy to keep is the most used, then the oldest. |
+| Duplicates: purge all | Owner or admin, groups exist. "Purge duplicates" opens the purge dialog (preview, confirm, progress, results), the same one as Settings "Purge now". "Merge into this one" is unchanged. |
 | Duplicates: empty | No groups. The Duplicates tab loses its count badge. |
 | Merge: confirm | "Merge into this one" on floorboards.jpg. The dialog says articles using the other copies will switch to this image and the other copies will be deleted, with the article count. |
 | Merge: in progress | Request in flight. The dialog can't be dismissed. |

docs/design/screens/settings.md

@@ -1,7 +1,7 @@
 # Settings
 
 - **Route:** `/settings`
-- **API:** GET /v1/settings (version) · GET /v1/system/update · POST /v1/system/update/check · POST /v1/system/update/download · POST /v1/system/update/restart
+- **API:** GET /v1/media/purge-settings · PATCH /v1/media/purge-settings · GET /v1/media/purge-preview · POST /v1/media/purge (see "Media cleanup (third card)" at the end) · GET /v1/settings (version) · GET /v1/system/update · POST /v1/system/update/check · POST /v1/system/update/download · POST /v1/system/update/restart
 - **Visual reference:** `source/RenewCMS Screens Back-office.dc.html`, group "Settings", drawn by `source/AppFrame.dc.html` (open it in a browser; each state is drawn at desktop and mobile, with a light/dark toggle).
 
 Opened from the sidebar (Settings, settings icon, after Integration) and from the mobile drawer. Every verified user sees it. It holds two sections: Version (everyone) and Updates (the owner has the buttons, admins read the status).
@@ -12,7 +12,7 @@ Out of scope: choosing versions, downgrades, automatic updates, update history.
 
 ## The page
 
-Title "Settings", subtitle "Workspace information.", 720 px at most, 20 px between sections. Page padding 32 px on desktop and `20px 16px 88px` on mobile.
+One column of cards, top to bottom: Version, Updates, Media cleanup, Retention (owner only). Title "Settings" (20 px/28 px semibold), subtitle "Workspace information.", 720 px at most, 20 px between sections. Every card heading (Version, Updates, Media cleanup, Retention) is 15 px/24 px semibold in `--ui-text-highlighted`; a card heading is never larger than the page title and never smaller than a body line. The Back-office board draws this page scrolled to the card each state is about. Page padding 32 px on desktop and `20px 16px 88px` on mobile.
 
 **Version card** (unchanged): label "Version" and the running build's version in IBM Plex Mono 14 px, shown exactly as the server reports it (for example `v2.2.0-beta`).
 
@@ -28,7 +28,7 @@ Title "Settings", subtitle "Workspace information.", 720 px at most, 20 px betwe
 | Server command | Only in the "Not prepared" state: "For whoever manages the server", a one-line `code` block, a Copy button (reads "Copied" with a check for 2 s, announced), and the note "They run this once on the server. After that, Update and Restart appear here." The command shown is `renewcms enable-browser-updates` and is subject to the real one. |
 | Buttons | 32 px high (44 px on mobile, stacked full width), 14 px side padding. One primary at most. Disabled buttons use 40 % opacity. |
 | Hint | 12 px muted line under the buttons. |
-| Link | Underlined, with an `arrow-up-right`: "How to update" or "Read the release notes". |
+| Link | Underlined, with an `external-link`: "How to update" or "Read the release notes". |
 
 Buttons used: **Check for updates** (`refresh-cw`, secondary), **Update** (`download`, primary), **Restart** (`power`, primary and inside the status block when an update is ready, otherwise secondary in the buttons row), **Try again** (`rotate-cw`, primary), and the disabled "Checking…" and "Updating…" (`loader-circle`). Copy such as "Version 2.3.0" names the newer release. Decision for the spec: show the release tag without its leading `v` ("Version 2.3.0-beta" for tag `v2.3.0-beta`), while the Version card keeps the running build exactly as the server reports it.
 
@@ -125,3 +125,71 @@ For the owner only: an **Update** pill on the Settings sidebar item, and a dot o
 | Admin view | Admins see the version and the note, with no buttons. Up to date: "You're up to date" and "Only the owner can update or restart the site." No Home banner or Settings pill. |
 | Role changed (403) | An owner was changed to admin while the page was open and pressed a button. The card reloads in the admin view. |
 | Update already running (409) | Another owner started it. The card switches to that run's progress. |
+
+## Media cleanup (third card)
+
+Route: `/settings`. Visual reference: `source/RenewCMS Screens Back-office.dc.html`, groups "Settings: Media cleanup", "Purge dialog", "Purge results" and "Media duplicates entry" (frames: `source/AppFrame.dc.html`, `source/MediaFrame.dc.html`).
+API: `GET/PATCH /v1/media/purge-settings` (owner, admin), `GET /v1/media/purge-preview`, `POST /v1/media/purge`. 401 and 403 are global: no local copy.
+
+Rule: a group is purged only if at least one copy is used in an article. All copies merge into the one used in the most articles (ties: oldest, then lowest id). Groups with no used copy are left alone. Automatic purge is off by default.
+
+### Card
+Third card, below Updates, 20 px gap, same card styling as the others. The board scrolls the page to this card for its states.
+- Title: "Media cleanup". Description: "Merge identical images so your library stays tidy. Articles that use a copy are switched to the most used one."
+- "Automatic purge" / helper "Runs in the background. Off by default." / USwitch.
+- When on: "Every" / helper "Between 1 and 365 days." / number input, suffix "days", default 30.
+- Read-only lines: "Last purge: 14 Jun 2026 · 3 copies merged · 5 articles updated" or "Never run". When on, also "Next purge: 14 Jul 2026".
+- Divider, then "Purge now" / "Merge every group of duplicates that has an image in use, right away." / outline button "Purge duplicates" (merge).
+- No Save button. Saves on toggle and on blur or Enter of the days field. "Saved" (check, success) sits in the card header and fades after 2 s; "Saving…" (loader-circle) while pending.
+- Non-owner/admin: switch and input disabled, button and divider hidden, info alert "Only owners and admins can change this."
+
+### States (names matched exactly)
+- Default: off, never run
+- On: 30 days, last run
+- Saving
+- Saved
+- Save failed: "Couldn't save. Try again in a moment." under the field; the control reverts.
+- Validation error: "Enter a whole number of days between 1 and 365." Nothing is sent.
+- Read-only (non-admin)
+- Loading skeleton (after 150 ms)
+- Offline: banner "You're offline. Changing automatic purge and purging duplicates need a connection." Switch, input and button disabled.
+
+### Dialog
+UModal, `sm:max-w-md`, bottom sheet on mobile, cancel first.
+- Title "Purge duplicates?". Description "Articles that use a duplicate will be switched to the most used copy of that image, and the other copies will be deleted. This can't be undone."
+- Summary: "4 groups · 9 copies will be deleted · 12 articles will be updated". Singular: "1 group · 1 copy will be deleted · 2 articles will be updated".
+- Bordered list of up to 5 groups: thumbnail, filename, "Kept · used in 4 articles", and "2 copies merged". More: "and 3 more groups".
+- Link "Review in Duplicates" to `/media?filter=duplicates`.
+- Buttons: "Cancel", danger "Purge 4 groups". Pending: "Purging…" with loader-circle, dialog can't be dismissed.
+- Loading preview: skeleton rows, confirm disabled.
+- Nothing to purge: icon copy, "Nothing to purge", "No duplicate is used in an article, so there is nothing to merge.", button "Close". No confirm.
+- Error (stays open): "Couldn't purge the duplicates. Nothing was changed. Try again in a moment."
+- Partial: "Some groups couldn't be merged. 3 of 4 groups were purged. Try again to finish." Buttons "Close", "Retry". Summary refreshes to the remaining groups.
+- Conflict (409): "The library changed, so nothing was purged. Check the new summary and try again." Summary refreshes.
+
+### Results
+- Toast (5 s): circle-check, "Duplicates purged" / "9 copies merged. 12 articles updated."
+- "Last purge" updates in place; "Next purge" moves forward by the interval.
+- An unattended run shows no toast. The next visit shows the updated line.
+
+### Media entry point
+Duplicates tab: secondary "Purge duplicates" button (merge) next to the sort menu; stacked toolbar on mobile. Opens the same dialog. Hidden for non-owner/admin and when there are no groups. "Merge into this one" is unchanged.
+
+### Components (Nuxt UI v4)
+`UCard`, `USwitch`, `UInputNumber` (min 1, max 365, suffix), `UFormField`, `UAlert`, `UButton`, `UModal`, `USkeleton`, `useToast`.
+
+## Activity retention
+
+**API:** GET /v1/settings · PATCH /v1/settings (owner only). Visual reference: `source/RenewCMS Screens Back-office.dc.html`, group "Settings: Retention", drawn by `source/AppFrame.dc.html`.
+
+The last card on the page, below Media cleanup, owner only (hidden for admins and for the read-only Media cleanup view), same card styling and 720 px column as the others.
+
+- Header: "Retention" / "How long activity is kept, or how much of it. Whichever limit is reached first removes the oldest events." "Saved" (check, success) at the right after a save, fading after 2 s.
+- "Keep activity for" `USelectMenu`: 30 days, 90 days, 365 days, Forever. Default 90 days. Helper: "Events older than this are removed." when a size limit is set, otherwise "Older events are removed automatically." For Forever: "Nothing is removed automatically. The log grows over time." without a size limit, "No age limit. Only the size limit applies." with one.
+- An "or" divider, then "Keep at most" `USelectMenu` (160 px wide, full width on mobile): "No size limit" (default) and sizes in GB. Helper without a limit: "Optional. Logs can grow without a size cap." With one: "When logs pass 5 GB, the oldest events are removed. Currently 3.2 GB." The figure after "Currently" is the real size of the activity log. The size options are listed in the API note below.
+- Info alert (`lock`): "Activity logs are append-only", "Events can't be edited or deleted from the app. Only the retention limits remove them."
+- Divider, then read-only lines: "Last cleanup: 6 Oct 2026, 03:00 · 142 events removed" and "Next cleanup: 7 Oct 2026, 03:00". Forever with no size limit: "Never" and "Not scheduled". Forever with a size limit still shows a schedule, because the size check runs at every cleanup.
+- Both selects save on change. Choosing a shorter age, or a smaller size limit than the current one, first shows a warning alert, "Events older than 30 days will be removed" (or "Events over 5 GB will be removed"), "This happens at the next cleanup on 7 Oct 2026, 03:00. It can't be undone.", buttons "Apply 30 days" (or "Apply 5 GB") and "Cancel"; nothing is sent until Apply. Lengthening, raising, choosing Forever or choosing "No size limit" saves at once.
+- Save error alert: "Couldn't save the retention period", "Your previous setting is still in place.", "Try again". The control reverts.
+- States: "Default, 90 days or 5 GB", "Age only (no size limit)", "Size only (forever)", "Shortening the period" (also with a 5 GB limit), "Forever" and "Save error". Loading and Offline follow the Media cleanup card.
+- `GET /v1/settings` adds `activity_retention_days` (30, 90, 365 or 0 for forever), `activity_retention_max_gb` (0 for no size limit, otherwise one of the size options), `activity_log_size_bytes`, `activity_last_cleanup_at` (null before the first cleanup) and `activity_last_cleanup_removed`. `PATCH /v1/settings` takes `{ "activity_retention_days": 30 }`, `{ "activity_retention_max_gb": 5 }` or both; any other value answers 400 "The request cannot be processed due to a mismatch in the format of the body."; a non-owner gets 403 "Only the owner can do this.". The cleanup runs once a day at 03:00 server time, removes events older than the age limit, then removes the oldest events until the log is under the size limit, and never touches the last 24 hours.

docs/design/source/ActivityFrame.dc.html

@@ -0,0 +1,252 @@
+<!DOCTYPE html>
+<html>
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<script src="./support.js"></script>
+</head>
+<body>
+<x-dc>
+<div style="display:contents">{{ view }}</div>
+</x-dc>
+<script type="text/x-dc" data-dc-script data-props="{&quot;$preview&quot;:{&quot;width&quot;:1440,&quot;height&quot;:900},&quot;s&quot;:{&quot;editor&quot;:null,&quot;tsType&quot;:&quot;object&quot;},&quot;mobile&quot;:{&quot;editor&quot;:null,&quot;tsType&quot;:&quot;boolean&quot;}}">
+class Component extends DCLogic {
+	renderVals() {
+		const s = this.props.s || {}, m = !!this.props.mobile, h = React.createElement
+		const P = t => Object.fromEntries(t.split(';').filter(x => x.trim()).map(x => { const i = x.indexOf(':'); const k = x.slice(0, i).trim(); return [k.startsWith('--') ? k : k.replace(/-([a-z])/g, (_, c) => c.toUpperCase()), x.slice(i + 1).trim()] }))
+		const D = (t, ...c) => h('div', { style: P(t) }, ...c)
+		const S = (t, ...c) => h('span', { style: P(t) }, ...c)
+		const I = (n, z = 16, t = '') => h('span', { 'aria-hidden': 'true', style: { display: 'inline-block', flexShrink: 0, width: z, height: z, backgroundColor: 'currentColor', WebkitMask: 'url(https://api.iconify.design/lucide/' + n + '.svg) center / contain no-repeat', mask: 'url(https://api.iconify.design/lucide/' + n + '.svg) center / contain no-repeat', ...(t ? P(t) : {}) } })
+		const bh = m ? 44 : 32
+		const MONO = "font-family:'IBM Plex Mono',monospace"
+		const B = (label, o = {}) => {
+			const k = o.k || 'outline'
+			const bg = k === 'primary' ? 'var(--ui-primary)' : 'var(--ui-bg)'
+			const fg = k === 'primary' ? 'var(--ui-bg)' : 'var(--ui-text-highlighted)'
+			const bd = k === 'primary' ? bg : 'var(--ui-border-accented)'
+			return S('height:' + (o.h || bh) + 'px;' + (o.w ? 'width:' + o.w + 'px;' : '') + 'padding:0 ' + (o.px ?? 12) + 'px;display:flex;align-items:center;justify-content:center;gap:6px;background:' + bg + ';color:' + fg + ';border:1px solid ' + bd + ';font-weight:500;font-size:' + (o.fs || 13) + 'px;white-space:nowrap;flex-shrink:0;opacity:' + (o.dis ? 0.4 : 1) + ';' + (o.full ? 'flex:1;' : ''), o.icon && I(o.icon, o.z || 16), label)
+		}
+		const BG = { ok: ['border:1px solid var(--ui-border-accented);color:var(--ui-text-toned)', 'check'], fail: ['background:var(--rc-error-soft);color:var(--ui-error)', 'circle-x'], sec: ['background:var(--rc-warning-soft);color:var(--ui-warning)', 'shield-alert'], del: ['border:1px solid var(--ui-border-accented);color:var(--ui-text-toned)', 'trash-2'], neutral: ['border:1px solid var(--ui-border-accented);color:var(--ui-text-toned)'], info: ['background:var(--rc-info-soft);color:var(--ui-info)'] }
+		const Bd = (t, k, sz = 20) => S('height:' + sz + 'px;padding:0 6px;display:inline-flex;align-items:center;gap:4px;font-size:12px;font-weight:500;white-space:nowrap;flex-shrink:0;' + BG[k][0], BG[k][1] && I(BG[k][1], 12), t)
+		const Out = e => e.ok ? Bd('Succeeded', 'ok') : Bd('Failed', 'fail')
+		const Alert = (tone, icon, title, text, action) => D('display:flex;gap:10px;padding:12px 14px;background:var(--rc-' + tone + '-soft);color:var(--ui-' + tone + ')', S('display:flex;padding-top:2px', I(icon)), D('flex:1;display:flex;flex-direction:column;gap:8px', D('display:flex;flex-direction:column;gap:2px', S('font-weight:600', title), text && S('color:var(--ui-text-toned)', text)), action && D('display:flex;gap:8px', ...[].concat(action).map(a => B(a, { h: m ? 44 : 28, fs: 12 })))))
+		const Empty = (icon, title, text, action, primary, pad = 56) => D('background:var(--ui-bg);border:1px solid var(--ui-border);padding:' + pad + 'px 24px;display:flex;flex-direction:column;align-items:center;gap:12px;text-align:center', S('width:44px;height:44px;display:flex;align-items:center;justify-content:center;background:var(--ui-bg-elevated);color:var(--ui-text-toned)', I(icon, 20)), S('font-weight:600;font-size:15px;color:var(--ui-text-highlighted)', title), S('color:var(--ui-text-muted);max-width:340px;text-wrap:pretty', text), action && B(action, { k: primary ? 'primary' : 'outline', px: 16 }))
+		const Note = t => S('align-self:flex-start;height:20px;padding:0 6px;display:inline-flex;align-items:center;border:1px dashed var(--ui-border-accented);color:var(--ui-text-toned);font:500 11px \'IBM Plex Mono\',monospace', t)
+		const sk = (w, hh = 12, extra = '') => S('display:block;width:' + w + ';height:' + hh + 'px;background:var(--ui-bg-accented);flex-shrink:0;' + extra)
+
+		// ---------- data
+		const U = n => ({ n, k: 'user' }), KEY = n => ({ n, k: 'key' }), SYS = { n: 'Scheduler', k: 'system' }, ANON = { n: 'Not signed in', k: 'anon' }
+		const p2 = n => String(n).padStart(2, '0')
+		const T = (d, hh, mm, ss) => ({ abs: d + ' 2026, ' + p2(hh) + ':' + p2(mm) + ':' + p2(ss), utc: d + ' 2026, ' + p2(hh - 1) + ':' + p2(mm) + ':' + p2(ss) + ' UTC' })
+		const WEB = { src: 'Web app', ip: '203.0.113.24', ua: 'Firefox 131 on macOS' }
+		const LONG = 'The complete guide to restoring a nineteenth-century timber-framed farmhouse: structural surveys, lime mortar, breathable insulation and what it all costs'
+		const E = [
+			{ id: 1, day: 'Today', rel: '2 min ago', ...T('6 Oct', 10, 42, 18), a: U('Marta Alves'), cat: 'articles', s: 'Published the article ', em: 'Spring release', tk: 'Article', ex: 1, ok: 1, tid: 'art_8f3k2', ...WEB, diff: [{ f: 'Publish state', b: 'Draft', a: 'Published' }] },
+			{ id: 2, day: 'Today', rel: '29 min ago', ...T('6 Oct', 10, 15, 4), a: U('Marta Alves'), cat: 'articles', s: 'Edited the article ', em: 'Why we reuse original floorboards', tk: 'Article', ex: 1, ok: 1, tid: 'art_2m9xq', ...WEB, diff: [{ f: 'Title', b: 'Why we reuse floorboards', a: 'Why we reuse original floorboards' }, { f: 'Body', note: 'Body edited (+312 characters)' }] },
+			{ id: 3, day: 'Today', rel: '1 h ago', ...T('6 Oct', 9, 31, 47), a: ANON, cat: 'auth', s: 'Failed login attempt for ', em: 'alex@example.com', ok: 0, sec: 1, why: 'The password did not match. 3 attempts in 10 minutes.', src: 'Web app', ip: '198.51.100.77', ua: 'Chrome 129 on Windows' },
+			{ id: 4, day: 'Today', rel: '2 h ago', ...T('6 Oct', 8, 50, 9), a: U('Jonas Weber'), cat: 'keys', s: 'Revoked API key ', em: 'Mobile app', tk: 'API key', ex: 1, ok: 1, sec: 1, tid: 'key_71ab0', src: 'Web app', ip: '203.0.113.90', ua: 'Safari 18 on iOS' },
+			{ id: 5, day: 'Today', rel: '7 h ago', ...T('6 Oct', 3, 0, 2), a: SYS, cat: 'system', s: 'Ran the nightly backup', em: '', ok: 1, src: 'System task', ip: null, ua: null },
+			{ id: 6, day: 'Yesterday', rel: '18:20', ...T('5 Oct', 18, 20, 36), a: U('Inès Duarte'), cat: 'users', s: 'Changed the role of ', em: 'Jonas Weber', tk: 'User', ex: 1, ok: 1, sec: 1, tid: 'usr_c40d1', tail: ' from Editor to Admin', ...WEB, ip: '203.0.113.12', diff: [{ f: 'Role', b: 'Editor', a: 'Admin' }] },
+			{ id: 7, day: 'Yesterday', rel: '16:05', ...T('5 Oct', 16, 5, 51), a: KEY('Website sync'), cat: 'media', s: 'Uploaded the image ', em: 'north-wall.jpg', tk: 'Image', ex: 1, ok: 1, tid: 'img_0pk4w', src: 'API key', ip: '192.0.2.18', ua: 'node-fetch 3.3' },
+			{ id: 8, day: 'Yesterday', rel: '14:40', ...T('5 Oct', 14, 40, 13), a: U('Marta Alves'), cat: 'media', s: 'Deleted the image ', em: 'old-banner.png', tk: 'Image', ex: 0, ok: 1, tid: 'img_9zq1c', ...WEB },
+			{ id: 9, day: 'Yesterday', rel: '11:12', ...T('5 Oct', 11, 12, 27), a: U('Inès Duarte'), cat: 'articles', s: 'Failed to publish the article ', em: LONG, tk: 'Article', ex: 1, ok: 0, tid: 'art_5t7yh', why: 'The article has no cover image. Add one, then publish again.', ...WEB, ip: '203.0.113.12' },
+			{ id: 10, day: 'Yesterday', rel: '03:00', ...T('5 Oct', 3, 0, 1), a: SYS, cat: 'users', s: 'Removed 3 expired invites', em: '', ok: 1, src: 'System task', ip: null, ua: null },
+			{ id: 11, day: '3 Oct 2026', rel: '16:48', ...T('3 Oct', 16, 48, 22), a: U('Inès Duarte'), cat: 'system', s: 'Changed the setting ', em: 'Site description', tk: 'Setting', ex: 1, ok: 1, tid: 'set_site_desc', ...WEB, ip: '203.0.113.12', diff: [{ f: 'Site description', b: 'Renovation notes, project write-ups and practical guides from the Renew studio team in Lisbon, covering timber, lime plaster and stone restoration for older homes.', a: 'Renovation notes, project write-ups and practical guides from the Renew studio team in Lisbon, covering timber, lime plaster and stone restoration for older homes, plus a seasonal maintenance checklist.', long: 1 }, { f: 'Comments', b: 'Off', a: 'On' }] },
+			{ id: 12, day: '3 Oct 2026', rel: '15:02', ...T('3 Oct', 15, 2, 40), a: U('Jonas Weber'), cat: 'keys', s: 'Created API key ', em: 'Mobile app', tk: 'API key', ex: 0, ok: 1, sec: 1, tid: 'key_71ab0', ...WEB, ip: '203.0.113.90' },
+			{ id: 13, day: '3 Oct 2026', rel: '14:20', ...T('3 Oct', 14, 20, 5), a: U('Inès Duarte'), cat: 'users', s: 'Updated the user ', em: 'Sam Rivera', tk: 'User', ex: 1, ok: 1, tid: 'usr_77ea2', ...WEB, ip: '203.0.113.12', diff: [{ f: 'Name', b: 'Sam Rivera', a: 'Samuel Rivera' }, { f: 'Email', b: 'sam@example.com', a: 'samuel@example.com' }] },
+			{ id: 14, day: '3 Oct 2026', rel: '11:36', ...T('3 Oct', 11, 36, 58), a: U('Marta Alves'), cat: 'media', s: 'Uploaded the image ', em: 'floorboards-copy.jpg', tk: 'Image', ex: 1, ok: 1, tid: 'img_4ww8e', ...WEB },
+			{ id: 15, day: '3 Oct 2026', rel: '09:05', ...T('3 Oct', 9, 5, 12), a: U('Inès Duarte'), cat: 'auth', s: 'Reset the password for ', em: 'Sam Rivera', tk: 'User', ex: 1, ok: 1, sec: 1, tid: 'usr_77ea2', ...WEB, ip: '203.0.113.12' }
+		]
+		const CI = { articles: 'file-text', media: 'image', users: 'users', keys: 'key-round', auth: 'shield-check', system: 'server-cog' }
+		const CL = { articles: 'Articles', media: 'Media', users: 'Users & invites', keys: 'API keys', auth: 'Authentication', system: 'System' }
+		const user = s.role === 'user'
+		const ME = user ? 'Marta Alves' : 'Inès Duarte'
+		let list = s.ids ? s.ids.map(i => E.find(e => e.id === i)) : (user ? E.filter(e => e.a.n === 'Marta Alves') : E)
+		const total = s.total || (user ? '41' : '1,284')
+		const sentence = e => e.s + e.em + (e.tail || '')
+		const Av = (a, z = 24) => {
+			const base = 'width:' + z + 'px;height:' + z + 'px;flex-shrink:0;display:flex;align-items:center;justify-content:center;'
+			if (a.k === 'user') return S(base + 'background:var(--rc-sand);color:var(--rc-on-sand);font:600 ' + Math.round(z * 0.42) + "px 'IBM Plex Sans',sans-serif", a.n.split(' ').map(x => x[0]).join('').slice(0, 2).toUpperCase())
+			return S(base + 'border:1px solid var(--ui-border-accented);background:var(--ui-bg-elevated);color:var(--ui-text-toned)', I({ key: 'key-round', system: 'cog', anon: 'user-round-x' }[a.k], Math.round(z * 0.6)))
+		}
+		const ActorBd = a => a.k === 'key' ? Bd('API key', 'neutral') : a.k === 'system' ? Bd('System', 'neutral') : null
+		const ell = 'overflow:hidden;text-overflow:ellipsis;white-space:nowrap;min-width:0'
+		const link = 'text-decoration:underline;text-underline-offset:3px;color:var(--ui-text-highlighted)'
+		const SecIcon = z => S('display:flex;color:var(--ui-warning)', I('shield-alert', z))
+
+		// ---------- controls
+		const Search = () => D('height:' + bh + 'px;' + (m ? 'flex:1;' : 'width:240px;') + 'padding:0 4px 0 10px;display:flex;align-items:center;gap:8px;border:1px solid var(--ui-border-accented);background:var(--ui-bg);color:' + (F.q ? 'var(--ui-text-highlighted)' : 'var(--ui-text-muted)') + (m ? ';font-size:16px' : ''), I('search', 14), S('flex:1;' + ell, F.q || 'Search activity'), F.q && S('width:24px;height:24px;display:flex;align-items:center;justify-content:center;color:var(--ui-text-muted)', I('x', 14)))
+		const Sel = (val, ph, w, icon) => D('height:' + bh + 'px;padding:0 10px;display:flex;align-items:center;gap:8px;border:1px solid var(--ui-border-accented);background:var(--ui-bg);color:' + (val ? 'var(--ui-text-highlighted)' : 'var(--ui-text-muted)') + ';' + (w ? 'width:' + w + 'px;flex-shrink:0' : 'width:100%'), icon && I(icon, 14, 'color:var(--ui-text-muted)'), S('flex:1;' + ell, val || ph), I('chevron-down', 14, 'color:var(--ui-text-muted)'))
+		const Seg = (opts, on, fw) => D('display:flex;border:1px solid var(--ui-border-accented);flex-shrink:0;' + (fw ? 'width:100%' : ''), ...opts.map(o => S('height:' + (bh - 2) + 'px;padding:0 ' + (m ? 12 : 10) + 'px;' + (fw ? 'flex:1;justify-content:center;' : '') + 'display:flex;align-items:center;gap:6px;white-space:nowrap;font-weight:' + (o === on ? 500 : 400) + ';background:' + (o === on ? 'var(--rc-sand)' : 'var(--ui-bg)') + ';color:' + (o === on ? 'var(--rc-on-sand)' : 'var(--ui-text-toned)'), o === 'Custom' && I('calendar', 14), o)))
+		const F = { q: '', actor: '', cat: '', out: 'All', range: '7 days', ...(s.f || {}) }
+		const RANGES = ['Today', '7 days', '30 days', 'Custom']
+		const chips = []
+		if (F.q) chips.push('Search: ' + F.q)
+		if (F.actor && !user) chips.push('Person: ' + F.actor)
+		if (F.cat) chips.push('Category: ' + F.cat)
+		if (F.out !== 'All') chips.push('Outcome: ' + F.out)
+		if (F.range !== '7 days') chips.push('Dates: ' + (F.range === 'Custom' ? (F.custom || '1 – 30 Sep 2026') : F.range))
+		const nF = chips.length
+		const Chips = () => nF > 0 && D('display:flex;flex-wrap:wrap;align-items:center;gap:8px', ...chips.map(c => S('height:' + (m ? 32 : 24) + 'px;padding:0 4px 0 8px;display:inline-flex;align-items:center;gap:4px;background:var(--ui-bg-elevated);border:1px solid var(--ui-border);color:var(--ui-text-highlighted);font-size:12px;font-weight:500', c, S('width:20px;height:20px;display:flex;align-items:center;justify-content:center;color:var(--ui-text-muted)', I('x', 12)))), S('height:' + (m ? 44 : 24) + 'px;display:flex;align-items:center;padding:0 6px;font-weight:500;font-size:12px;' + link, 'Clear all'))
+		const FilterBar = () => m
+			? D('display:flex;gap:8px', Search(), h('span', { style: P('height:44px;padding:0 12px;display:flex;align-items:center;gap:6px;border:1px solid var(--ui-border-accented);background:var(--ui-bg);color:var(--ui-text-highlighted);font-weight:500;font-size:13px;flex-shrink:0') }, I('sliders-horizontal', 16), 'Filters', nF > 0 && S('min-width:18px;height:18px;padding:0 5px;display:inline-flex;align-items:center;justify-content:center;background:var(--ui-primary);color:var(--ui-bg);font:500 11px \'IBM Plex Mono\',monospace', String(nF))))
+			: D('display:flex;align-items:center;gap:8px;flex-wrap:wrap', Search(), !user && Sel(F.actor, 'All people', 168, 'user-round'), Sel(F.cat, 'All categories', 176, 'layout-list'), Seg(['All', 'Succeeded', 'Failed'], F.out), D('flex:1;min-width:0'), Seg(RANGES, F.range))
+
+		// ---------- summary
+		const mk = (l, v, sub, ic, tone, ser) => ({ l, v, sub, ic, tone, ser })
+		const STAT = s.sum === 'zero' ? [mk('Total actions', '214', '4% vs previous 7 days', 'trending-down', 'n', [3, 5, 2, 6, 4, 1, 2]), mk('Active people', '5', '4 people, 1 API key', '', 'n', [2, 3, 2, 3, 2, 1, 2]), mk('Failed actions', '0', 'Nothing failed', 'circle-check', 'ok0', [0, 0, 0, 0, 0, 0, 0]), mk('Security events', '0', 'Nothing to flag', 'circle-check', 'ok0', [0, 0, 0, 0, 0, 0, 0])]
+			: s.sum === 'none' ? [mk('Total actions', '0', 'No data yet', '', 'n', [0, 0, 0, 0, 0, 0, 0]), mk('Active people', '0', 'No data yet', '', 'n', [0, 0, 0, 0, 0, 0, 0]), mk('Failed actions', '0', 'Nothing failed', 'circle-check', 'ok0', [0, 0, 0, 0, 0, 0, 0]), mk('Security events', '0', 'Nothing to flag', 'circle-check', 'ok0', [0, 0, 0, 0, 0, 0, 0])]
+			: [mk('Total actions', '1,284', '12% vs previous 7 days', 'trending-up', 'n', [4, 6, 5, 8, 7, 9, 6]), mk('Active people', '9', '7 people, 2 API keys', '', 'n', [5, 6, 6, 7, 7, 8, 9]), mk('Failed actions', '6', '0.5% of all actions', 'circle-x', 'error', [0, 1, 0, 2, 1, 0, 2]), mk('Security events', '11', '5 failed logins', 'shield-alert', 'warning', [1, 0, 2, 1, 3, 2, 2])]
+		const Bars = (ser, tone, z) => {
+			const mx = Math.max(...ser, 1), col = tone === 'error' ? 'var(--ui-error)' : tone === 'warning' ? 'var(--ui-warning)' : tone === 'ok0' ? 'var(--ui-border-accented)' : 'var(--ui-text-muted)'
+			return D('display:flex;align-items:flex-end;gap:2px;height:' + z + 'px;flex-shrink:0', ...ser.map(v => S('display:block;width:4px;height:' + Math.max(2, Math.round(v / mx * z)) + 'px;background:' + col)))
+		}
+		const StatCard = (c, i) => {
+			const act = s.card === i, tone = c.tone
+			const bg = tone === 'error' ? 'var(--rc-error-soft)' : tone === 'warning' ? 'var(--rc-warning-soft)' : 'var(--ui-bg)'
+			const vc = tone === 'error' ? 'var(--ui-error)' : tone === 'warning' ? 'var(--ui-warning)' : 'var(--ui-text-highlighted)'
+			const sc = tone === 'ok0' ? 'var(--ui-success)' : 'var(--ui-text-muted)'
+			return D('display:flex;flex-direction:column;gap:2px;padding:' + (m ? '10px 12px' : '12px 14px') + ';background:' + bg + ';border:1px solid ' + (act ? 'var(--ui-primary)' : 'var(--ui-border)') + ';' + (act ? 'box-shadow:inset 0 0 0 1px var(--ui-primary);' : '') + (m ? 'flex:0 0 156px;' : 'min-width:0;'),
+				D('display:flex;align-items:center;justify-content:space-between;gap:8px', S('color:var(--ui-text-toned);font-weight:500;' + ell, c.l), Bars(c.ser, tone, m ? 16 : 20)),
+				S('font:600 ' + (m ? 22 : 24) + "px/32px 'IBM Plex Sans',sans-serif;color:" + vc, c.v),
+				S('display:flex;align-items:center;gap:4px;font-size:12px;color:' + sc + ';' + ell, c.ic && I(c.ic, 12), c.sub))
+		}
+		const SkelCard = () => D('display:flex;flex-direction:column;gap:8px;padding:' + (m ? '10px 12px' : '14px') + ';background:var(--ui-bg);border:1px solid var(--ui-border);' + (m ? 'flex:0 0 156px' : 'min-width:0'), sk('55%', 12), sk('40%', 22), sk('70%', 10))
+		const Strip = () => {
+			if (user) return null
+			const kids = s.state === 'loading' ? [0, 1, 2, 3].map(SkelCard) : STAT.map(StatCard)
+			return m ? D('display:flex;gap:8px;overflow:hidden;margin:0 -16px;padding:0 16px', ...kids) : D('display:grid;grid-template-columns:repeat(4,minmax(0,1fr));gap:12px', ...kids)
+		}
+
+		// ---------- table
+		const cols = user ? '96px minmax(0,1fr) 230px 120px' : '96px 210px minmax(0,1fr) 230px 120px'
+		const TableHead = () => D('display:grid;grid-template-columns:' + cols + ';height:36px;align-items:center;padding-right:16px;background:var(--ui-bg-elevated);color:var(--ui-text-muted);font-weight:500;flex-shrink:0', S('padding-left:16px;display:flex;align-items:center;gap:4px;color:var(--ui-text-highlighted)', 'When', I('arrow-down', 12)), !user && S('', 'Actor'), S('', 'Action'), S('', 'Target'), S('', 'Outcome'))
+		const Day = d => D('display:flex;align-items:center;height:32px;padding:0 ' + (m ? 16 : 16) + 'px;background:var(--ui-bg-muted);border-top:1px solid var(--ui-border);font-weight:600;font-size:12px;color:var(--ui-text-highlighted);flex-shrink:0', d)
+		const Tip = e => S('position:absolute;left:12px;top:38px;z-index:5;padding:6px 8px;background:var(--ui-bg-inverted);color:var(--ui-text-inverted);font-size:12px;white-space:nowrap;box-shadow:var(--rc-shadow-pop)', e.abs)
+		const TargetCell = e => !e.tk ? S('color:var(--ui-text-muted)', '—') : D('display:flex;flex-direction:column;min-width:0;padding-right:12px', e.ex ? S('display:flex;align-items:center;gap:4px;' + link, S(ell, e.em), I('arrow-up-right', 12, 'color:var(--ui-text-muted)')) : D('display:flex;align-items:center;gap:6px;min-width:0', S('flex:1;text-decoration:line-through;color:var(--ui-text-muted);' + ell, e.em), Bd('Deleted', 'del')), S('font-size:12px;color:var(--ui-text-muted)', e.tk))
+		const Row = e => {
+			const hov = s.tip === e.id, sel = s.panel === e.id
+			return D('position:relative;z-index:' + (hov ? 3 : 1) + ';display:grid;grid-template-columns:' + cols + ';align-items:center;min-height:52px;padding-right:16px;border-top:1px solid var(--ui-border);background:' + (sel || hov ? 'var(--ui-bg-elevated)' : 'var(--ui-bg)') + ';' + (e.sec ? 'box-shadow:inset 2px 0 0 var(--ui-warning);' : ''),
+				S('padding-left:16px;position:relative;color:var(--ui-text-toned);white-space:nowrap', e.rel, hov && Tip(e)),
+				!user && D('display:flex;align-items:center;gap:8px;min-width:0;padding-right:12px', Av(e.a), S('font-weight:500;color:var(--ui-text-highlighted);' + ell, e.a.n), ActorBd(e.a)),
+				D('display:flex;align-items:center;gap:10px;min-width:0;padding-right:16px', S('display:flex;color:var(--ui-text-muted)', I(CI[e.cat], 16)), S('color:var(--ui-text);' + ell, e.s, S('font-weight:600;color:var(--ui-text-highlighted)', e.em), e.tail || ''), e.sec && SecIcon(14)),
+				TargetCell(e), D('display:flex', Out(e)))
+		}
+		const Card = e => {
+			const sel = s.panel === e.id
+			return D('display:flex;flex-direction:column;gap:8px;padding:12px 16px;border-top:1px solid var(--ui-border);background:' + (sel ? 'var(--ui-bg-elevated)' : 'var(--ui-bg)') + ';' + (e.sec ? 'box-shadow:inset 2px 0 0 var(--ui-warning)' : ''),
+				D('display:flex;align-items:center;gap:8px;min-width:0', !user && Av(e.a, 24), !user && S('font-weight:500;color:var(--ui-text-highlighted);' + ell, e.a.n), !user && ActorBd(e.a), D('flex:1'), S('color:var(--ui-text-muted);font-size:12px;white-space:nowrap', e.rel)),
+				D('display:flex;gap:8px;align-items:flex-start', S('display:flex;padding-top:2px;color:var(--ui-text-muted)', I(CI[e.cat], 16)), S('flex:1;min-width:0;color:var(--ui-text);font-size:15px;line-height:22px;overflow-wrap:anywhere;display:-webkit-box;-webkit-line-clamp:3;-webkit-box-orient:vertical;overflow:hidden', e.s, S('font-weight:600;color:var(--ui-text-highlighted)', e.em), e.tail || '')),
+				D('display:flex;align-items:center;gap:6px;flex-wrap:wrap', Out(e), e.sec && Bd('Security', 'sec'), e.tk && !e.ex && Bd('Target deleted', 'del')))
+		}
+		const rowsOf = fn => { const out = []; let day = null; list.forEach(e => { if (e.day !== day) { out.push(Day(e.day)); day = e.day } out.push(fn(e)) }); return out }
+		const SkelRows = () => Array.from({ length: m ? 5 : 9 }, (_, i) => m
+			? D('display:flex;flex-direction:column;gap:10px;padding:14px 16px;border-top:1px solid var(--ui-border)', D('display:flex;gap:8px;align-items:center', sk('24px', 24), sk('90px', 12), D('flex:1'), sk('40px', 10)), sk(['90%', '75%', '85%'][i % 3], 14), sk('70px', 20))
+			: D('display:grid;grid-template-columns:' + cols + ';align-items:center;height:52px;padding-right:16px;border-top:1px solid var(--ui-border)', S('padding-left:16px', sk('56px')), !user && D('display:flex;gap:8px;align-items:center', sk('24px', 24), sk('90px')), sk(['70%', '55%', '82%'][i % 3], 12), sk('60%'), sk('72px', 20)))
+		const Table = () => D('flex:1;min-height:0;overflow:hidden;display:flex;flex-direction:column;background:var(--ui-bg);border:1px solid var(--ui-border)', !m && TableHead(), ...(s.state === 'loading' ? (m ? [] : []).concat(SkelRows()) : rowsOf(m ? Card : Row)))
+		const PgBtn = (c, on, dis) => S('width:' + bh + 'px;height:' + bh + 'px;display:flex;align-items:center;justify-content:center;border:1px solid ' + (on ? 'var(--ui-primary)' : 'var(--ui-border-accented)') + ';background:' + (on ? 'var(--ui-primary)' : 'var(--ui-bg)') + ';color:' + (on ? 'var(--ui-bg)' : 'var(--ui-text-highlighted)') + ';font-weight:500;flex-shrink:0;opacity:' + (dis ? 0.4 : 1), c)
+		const Pager = () => s.state === 'loading' ? null : m
+			? D('display:flex;align-items:center;gap:8px;flex-shrink:0', PgBtn(I('chevron-left'), 0, 1), D('flex:1;display:flex;flex-direction:column;align-items:center;font-size:12px;color:var(--ui-text-muted)', S('color:var(--ui-text-highlighted);font-weight:500', 'Page 1 of ' + (user ? '2' : '52')), S('', '1–25 of ' + total)), D('width:96px;flex-shrink:0', Sel('25', '', 0)), PgBtn(I('chevron-right')))
+			: D('display:flex;align-items:center;gap:16px;flex-shrink:0', S('color:var(--ui-text-muted)', 'Showing 1–' + (user ? '25' : '25') + ' of ' + total), D('flex:1'), D('display:flex;align-items:center;gap:8px;color:var(--ui-text-muted)', 'Rows per page', D('width:80px', Sel('25', '', 0))), D('display:flex;gap:4px', PgBtn(I('chevron-left'), 0, 1), PgBtn('1', 1), PgBtn('2'), PgBtn('3'), PgBtn('…'), PgBtn(user ? '2' : '52'), PgBtn(I('chevron-right'))))
+
+		// ---------- header + page
+		const title = user ? 'My activity' : 'Activity'
+		const sub = user ? 'Everything you\'ve done on this site.' : 'Who did what, and when, across your site.'
+		const noData = s.state === 'none'
+		const Header = () => D('display:flex;align-items:flex-end;gap:16px;flex-wrap:wrap;flex-shrink:0', D('flex:1;min-width:180px;display:flex;flex-direction:column;gap:2px', S('font:600 20px/28px \'IBM Plex Sans\',sans-serif;color:var(--ui-text-highlighted)', title), S('color:var(--ui-text-muted)', sub)), !user && s.state !== 'forbidden' && B('Export CSV', { icon: 'download', dis: noData || s.state === 'error' }))
+		const Page = () => {
+			const k = [Header()]
+			if (s.state === 'forbidden') { k.push(Empty('lock', 'You can\'t view this activity', 'Your role doesn\'t include this page. Ask an owner or admin if you need access.', 'Back to home', false)); return k }
+			const st = Strip(); if (st) k.push(st)
+			k.push(FilterBar()); const c = Chips(); if (c) k.push(c)
+			if (s.state === 'error') k.push(Alert('error', 'circle-x', 'Couldn\'t load activity', 'Check your connection and try again.', 'Try again'))
+			else if (s.state === 'none') k.push(Empty('history', 'No activity yet', user ? 'Your actions will appear here once you start working on the site.' : 'Actions on articles, media, users and API keys will appear here.'))
+			else if (s.state === 'nomatch') k.push(Empty('search-x', 'No activity matches these filters', 'Try a different search or a wider date range.', 'Clear filters', false))
+			else { k.push(Table()); const pg = Pager(); if (pg) k.push(pg) }
+			return k
+		}
+
+		// ---------- slide-over
+		const Av2 = Av
+		const Panel = () => {
+			const e = E.find(x => x.id === s.panel), i = list.indexOf(e)
+			const lab = t => S('color:var(--ui-text-muted)', t)
+			const val = (...c) => D('display:flex;align-items:center;gap:8px;flex-wrap:wrap;min-width:0;color:var(--ui-text-highlighted)', ...c)
+			const Diff = d => {
+				if (d.note) return D('display:flex;flex-direction:column;gap:6px;padding:12px;border-top:1px solid var(--ui-border-muted)', S('font-weight:500;color:var(--ui-text-highlighted)', d.f), S('display:flex;align-items:center;gap:6px;color:var(--ui-text-toned)', I('file-pen-line', 14), d.note))
+				const clamp = d.long && !s.expand
+				const box = (t, bg, bd, c) => S('display:block;padding:8px 10px;background:' + bg + ';border:1px solid ' + bd + ';color:' + c + ';overflow-wrap:anywhere;' + (clamp ? 'display:-webkit-box;-webkit-line-clamp:2;-webkit-box-orient:vertical;overflow:hidden' : ''), t)
+				return D('display:flex;flex-direction:column;gap:8px;padding:12px;border-top:1px solid var(--ui-border-muted)', S('font-weight:500;color:var(--ui-text-highlighted)', d.f),
+					D('display:grid;grid-template-columns:' + (m ? 'minmax(0,1fr)' : 'minmax(0,1fr) 16px minmax(0,1fr)') + ';gap:' + (m ? 6 : 8) + 'px;align-items:' + (m ? 'stretch' : 'start'), D('display:flex;flex-direction:column;gap:2px;min-width:0', S('font-size:11px;color:var(--ui-text-muted)', 'Before'), box(d.b, 'var(--ui-bg-elevated)', 'var(--ui-border)', 'var(--ui-text-toned)')), m ? S('display:flex;justify-content:center;color:var(--ui-text-muted)', I('arrow-down', 14)) : S('display:flex;padding-top:30px;color:var(--ui-text-muted)', I('arrow-right', 14)), D('display:flex;flex-direction:column;gap:2px;min-width:0', S('font-size:11px;color:var(--ui-text-muted)', 'After'), box(d.a, 'var(--ui-bg)', 'var(--ui-border-accented)', 'var(--ui-text-highlighted)'))),
+					d.long && S('align-self:flex-start;font-weight:500;font-size:12px;min-height:' + (m ? 32 : 16) + 'px;' + link, clamp ? 'Show more' : 'Show less'))
+			}
+			const body = D('flex:1;min-height:0;overflow:hidden;padding:' + (m ? 16 : 20) + 'px;display:flex;flex-direction:column;gap:20px',
+				D('display:flex;flex-direction:column;gap:10px', S('font:600 18px/26px \'IBM Plex Sans\',sans-serif;color:var(--ui-text-highlighted);overflow-wrap:anywhere', sentence(e)), D('display:flex;gap:6px;flex-wrap:wrap;align-items:center', Out(e), e.sec && Bd('Security', 'sec'), S('display:inline-flex;align-items:center;gap:4px;font-size:12px;color:var(--ui-text-muted)', I(CI[e.cat], 14), CL[e.cat]))),
+				!e.ok && Alert('error', 'circle-x', 'Why it failed', e.why),
+				D('display:grid;grid-template-columns:96px minmax(0,1fr);gap:10px 12px;align-items:start', lab('When'), D('display:flex;flex-direction:column;gap:2px', S('color:var(--ui-text-highlighted)', e.abs + ' (your time)'), S('color:var(--ui-text-muted);font-size:12px', e.utc)), lab('Actor'), val(Av(e.a, 24), S('font-weight:500', e.a.n), ActorBd(e.a)), lab('Source'), val(e.src), lab('IP address'), e.ip ? S(MONO + ';font-size:12px;color:var(--ui-text-highlighted)', e.ip) : S('color:var(--ui-text-muted)', 'Not applicable'), lab('Browser'), e.ua ? S('color:var(--ui-text-highlighted)', e.ua) : S('color:var(--ui-text-muted)', 'Not applicable')),
+				e.tk && D('display:flex;flex-direction:column;gap:8px', S('font:600 14px/22px \'IBM Plex Sans\',sans-serif;color:var(--ui-text-highlighted)', 'Target'), D('display:flex;flex-direction:column;gap:6px;border:1px solid var(--ui-border);padding:10px 12px', D('display:flex;align-items:center;gap:8px;min-width:0', e.ex ? S('flex:1;display:flex;align-items:center;gap:4px;overflow-wrap:anywhere;' + link, e.em, I('arrow-up-right', 14, 'color:var(--ui-text-muted)')) : S('flex:1;text-decoration:line-through;color:var(--ui-text-muted);overflow-wrap:anywhere', e.em), !e.ex && Bd('Deleted', 'del')), S('font-size:12px;color:var(--ui-text-muted)', e.tk + ' · ' + e.tid), !e.ex && S('font-size:12px;color:var(--ui-text-toned)', 'This item was deleted. Its name is kept for reference.'))),
+				e.diff && D('display:flex;flex-direction:column;gap:8px', S('font:600 14px/22px \'IBM Plex Sans\',sans-serif;color:var(--ui-text-highlighted)', 'Changes'), D('border:1px solid var(--ui-border)', ...e.diff.map((d, j) => { const r = Diff(d); return r }))))
+			const foot = D('flex-shrink:0;display:flex;align-items:center;gap:8px;padding:12px ' + (m ? 16 : 20) + 'px;border-top:1px solid var(--ui-border)', B('Previous event', { icon: 'chevron-up', dis: i === 0, full: m }), B('Next event', { icon: 'chevron-down', dis: i === list.length - 1, full: m }), !m && D('flex:1'), !m && S('color:var(--ui-text-muted);font-size:12px', 'Event ' + (i + 1) + ' of ' + total))
+			const head = D('height:56px;flex-shrink:0;display:flex;align-items:center;gap:12px;padding:0 ' + (m ? 8 : 20) + 'px 0 ' + (m ? 16 : 20) + 'px;border-bottom:1px solid var(--ui-border)', S('flex:1;font:600 16px/24px \'IBM Plex Sans\',sans-serif;color:var(--ui-text-highlighted)', 'Activity details'), m && S('color:var(--ui-text-muted);font-size:12px', (i + 1) + ' of ' + total), S('width:' + (m ? 44 : 28) + 'px;height:' + (m ? 44 : 28) + 'px;display:flex;align-items:center;justify-content:center;color:var(--ui-text-muted)', I('x')))
+			return D('position:absolute;inset:0;z-index:40;display:flex;justify-content:' + (m ? 'stretch' : 'flex-end') + ';align-items:' + (m ? 'flex-end' : 'stretch') + ';background:var(--rc-overlay)',
+				D((m ? 'width:100%;height:88%;' : 'width:480px;height:100%;') + 'background:var(--ui-bg);display:flex;flex-direction:column;box-shadow:var(--rc-shadow-modal)', m && D('flex-shrink:0;display:flex;justify-content:center;padding-top:8px', S('display:block;width:36px;height:4px;background:var(--ui-border-accented)')), head, body, foot))
+		}
+		const Drawer = () => {
+			const sec = (l, c) => D('display:flex;flex-direction:column;gap:6px', S('font-weight:500;color:var(--ui-text-highlighted)', l), c)
+			return D('position:absolute;inset:0;z-index:40;display:flex;align-items:flex-end;background:var(--rc-overlay)', D('width:100%;background:var(--ui-bg);display:flex;flex-direction:column;box-shadow:var(--rc-shadow-modal)',
+				D('display:flex;justify-content:center;padding-top:8px', S('display:block;width:36px;height:4px;background:var(--ui-border-accented)')),
+				D('height:56px;display:flex;align-items:center;padding:0 8px 0 16px;border-bottom:1px solid var(--ui-border)', S('flex:1;font:600 16px/24px \'IBM Plex Sans\',sans-serif;color:var(--ui-text-highlighted)', 'Filters'), S('width:44px;height:44px;display:flex;align-items:center;justify-content:center;color:var(--ui-text-muted)', I('x'))),
+				D('padding:16px;display:flex;flex-direction:column;gap:16px', !user && sec('Person', Sel(F.actor, 'All people', 0, 'user-round')), sec('Category', Sel(F.cat, 'All categories', 0, 'layout-list')), sec('Outcome', Seg(['All', 'Succeeded', 'Failed'], F.out, 1)), sec('Dates', D('display:flex;flex-direction:column;gap:8px', Seg(['Today', '7 days', '30 days', 'Custom'], F.range, 1), F.range === 'Custom' && D('display:flex;gap:8px;align-items:center', D('flex:1', Sel('1 Sep 2026', '', 0, 'calendar')), D('flex:1', Sel('30 Sep 2026', '', 0, 'calendar')))))),
+				D('display:flex;gap:8px;padding:12px 16px 16px;border-top:1px solid var(--ui-border)', B('Clear all', { full: true, dis: nF === 0 }), B('Show ' + (s.count || '23') + ' results', { k: 'primary', full: true }))))
+		}
+
+		// ---------- home + settings
+		const Rows5 = (ls, own) => ls.map((e, i) => D('display:flex;gap:10px;align-items:flex-start;padding:10px 0;border-top:' + (i ? '1px solid var(--ui-border-muted)' : '0'), Av(e.a, 24), D('flex:1;min-width:0;display:flex;flex-direction:column;gap:2px', S('color:var(--ui-text);overflow-wrap:anywhere;display:-webkit-box;-webkit-line-clamp:2;-webkit-box-orient:vertical;overflow:hidden', e.s, S('font-weight:600;color:var(--ui-text-highlighted)', e.em), e.tail || ''), S('font-size:12px;color:var(--ui-text-muted)', own ? e.rel : e.a.n + ' · ' + e.rel)), !e.ok && Bd('Failed', 'fail'), e.sec && e.ok && SecIcon(14)))
+		const ActCard = () => {
+			const own = user, ls = own ? E.filter(e => e.a.n === 'Marta Alves') : E.slice(0, 5)
+			const st = s.card || 'ok'
+			const inner = st === 'loading' ? Array.from({ length: 5 }, (_, i) => D('display:flex;gap:10px;padding:10px 0;border-top:' + (i ? '1px solid var(--ui-border-muted)' : '0'), sk('24px', 24), D('flex:1;display:flex;flex-direction:column;gap:6px', sk(['85%', '70%', '90%', '60%', '78%'][i], 12), sk('35%', 10))))
+				: st === 'error' ? [Alert('error', 'circle-x', 'Couldn\'t load recent activity', null, 'Try again')]
+				: st === 'empty' ? [D('padding:24px 0;display:flex;flex-direction:column;align-items:center;gap:6px;text-align:center', S('color:var(--ui-text-muted)', I('history', 20)), S('font-weight:600;color:var(--ui-text-highlighted)', 'No activity yet'), S('color:var(--ui-text-muted);max-width:240px', own ? 'Your actions will appear here.' : 'Actions on your site will appear here.'))]
+				: Rows5(ls, own)
+			return D('background:var(--ui-bg);border:1px solid var(--ui-border);display:flex;flex-direction:column;min-width:0', D('display:flex;align-items:center;gap:8px;padding:12px 16px;border-bottom:1px solid var(--ui-border)', S('flex:1;font:600 14px/22px \'IBM Plex Sans\',sans-serif;color:var(--ui-text-highlighted)', own ? 'Your recent activity' : 'Recent activity'), S('display:flex;align-items:center;gap:4px;font-weight:500;min-height:' + (m ? 44 : 20) + 'px;' + link, 'View all', I('arrow-right', 14))), D('padding:4px 16px 6px;display:flex;flex-direction:column', ...inner))
+		}
+		const Ph = (t, hh) => D('height:' + hh + 'px;border:1px dashed var(--ui-border-accented);display:flex;align-items:center;justify-content:center;color:var(--ui-text-muted);text-align:center;padding:16px', t)
+		const HomeBody = () => [D('display:flex;flex-direction:column;gap:2px', S('font:600 20px/28px \'IBM Plex Sans\',sans-serif;color:var(--ui-text-highlighted)', 'Home'), S('color:var(--ui-text-muted)', 'Welcome back, ' + ME.split(' ')[0] + '.')), m ? D('display:flex;flex-direction:column;gap:16px', ActCard(), Ph('Existing Home cards', 160)) : D('display:grid;grid-template-columns:minmax(0,1fr) 420px;gap:16px;align-items:start', Ph('Existing Home cards', 420), ActCard())]
+		const RET = { '30': '30 days', '90': '90 days', '365': '365 days', '0': 'Forever' }
+		const SettingsBody = () => {
+			const r = s.ret || '90', fv = r === '0'
+			const dl = (k, v) => D('display:flex;flex-direction:' + (m ? 'column' : 'row') + ';gap:' + (m ? 0 : 12) + 'px', S('width:' + (m ? 'auto' : '120px') + ';color:var(--ui-text-muted);flex-shrink:0', k), S('color:var(--ui-text-highlighted)', v))
+			const card = D('background:var(--ui-bg);border:1px solid var(--ui-border);max-width:640px;display:flex;flex-direction:column',
+				D('display:flex;align-items:center;gap:8px;padding:12px 16px;border-bottom:1px solid var(--ui-border)', D('flex:1;display:flex;flex-direction:column', S('font:600 14px/22px \'IBM Plex Sans\',sans-serif;color:var(--ui-text-highlighted)', 'Retention'), S('color:var(--ui-text-muted);font-size:12px', 'How long activity is kept.')), s.saved && S('display:flex;align-items:center;gap:4px;color:var(--ui-success);font-size:12px', I('check', 14), 'Saved')),
+				D('padding:16px;display:flex;flex-direction:column;gap:16px',
+					s.err && Alert('error', 'circle-x', 'Couldn\'t save the retention period', 'Your previous setting is still in place.', 'Try again'),
+					D('display:flex;flex-direction:column;gap:6px;max-width:260px', S('font-weight:500;color:var(--ui-text-highlighted)', 'Keep activity for'), Sel(RET[s.shorten ? '30' : r], '', 0), S('color:var(--ui-text-muted);font-size:12px', fv ? 'Nothing is removed automatically. The log grows over time.' : 'Older events are removed automatically.')),
+					s.shorten && Alert('warning', 'triangle-alert', 'Events older than 30 days will be removed', 'This happens at the next cleanup on 7 Oct 2026, 03:00. It can\'t be undone.', ['Apply 30 days', 'Cancel']),
+					Alert('info', 'lock', 'Activity logs are append-only', 'Events can\'t be edited or deleted from the app. Only the retention period removes them.'),
+					D('display:flex;flex-direction:column;gap:6px;padding-top:12px;border-top:1px solid var(--ui-border)', dl('Last cleanup', fv ? 'Never' : '6 Oct 2026, 03:00 · 142 events removed'), dl('Next cleanup', fv ? 'Not scheduled' : '7 Oct 2026, 03:00'))))
+			return [D('display:flex;flex-direction:column;gap:2px', S('font:600 20px/28px \'IBM Plex Sans\',sans-serif;color:var(--ui-text-highlighted)', 'Settings'), S('color:var(--ui-text-muted)', 'Site-wide options. Only owners can change them.')), Ph('Existing Settings cards', m ? 100 : 120), card]
+		}
+
+		// ---------- shell
+		const logo = h('svg', { width: 26, height: 26, viewBox: '0 0 16 16', shapeRendering: 'crispEdges', style: { color: 'var(--ui-text-highlighted)', flexShrink: 0 } }, h('rect', { width: 16, height: 16, fill: 'currentColor' }), h('path', { fill: 'var(--ui-bg)', fillRule: 'evenodd', d: 'M4 3h6v1h1v1h1v3h-1v1h-1v1h1v1h1v2h-2v-2h-1v-1H6v3H4zm2 2v3h4V5z' }))
+		const kind = s.kind || 'page'
+		const navKey = kind === 'home' ? 'home' : kind === 'settings' ? 'settings' : 'activity'
+		const nav = (user ? [['home', 'house', 'Home'], ['articles', 'file-text', 'Articles'], ['media', 'images', 'Media'], ['activity', 'history', 'Activity']] : [['home', 'house', 'Home'], ['articles', 'file-text', 'Articles'], ['media', 'images', 'Media'], ['users', 'users', 'Users'], ['activity', 'history', 'Activity'], ['integration', 'plug', 'Integration'], ['settings', 'settings', 'Settings']])
+		const side = D('width:224px;flex-shrink:0;background:var(--ui-bg);border-right:1px solid var(--ui-border);display:flex;flex-direction:column;padding:12px;gap:2px', D('display:flex;align-items:center;gap:10px;height:40px;padding:0 6px;margin-bottom:10px', logo, S('font-weight:600;font-size:14px;color:var(--ui-text-highlighted)', 'RenewCMS')),
+			...nav.map(([k, ic, t]) => D('display:flex;align-items:center;gap:10px;height:32px;padding:0 10px;background:' + (k === navKey ? 'var(--rc-sand)' : 'transparent') + ';color:' + (k === navKey ? 'var(--rc-on-sand)' : 'var(--ui-text-toned)') + ';font-weight:' + (k === navKey ? 500 : 400), I(ic), t)),
+			D('flex:1'), D('display:flex;align-items:center;gap:10px;height:40px;padding:0 6px;color:var(--ui-text-highlighted)', Av(U(ME), 26), S('flex:1;font-weight:500', ME), I('chevrons-up-down', 14)))
+		const crumb = { page: title, home: 'Home', settings: 'Settings' }[kind]
+		const topbar = m
+			? D('height:56px;flex-shrink:0;border-bottom:1px solid var(--ui-border);background:var(--ui-bg);display:flex;align-items:center;padding:0 6px;gap:4px;color:var(--ui-text-highlighted)', S('width:44px;height:44px;display:flex;align-items:center;justify-content:center', I('menu', 20)), S('flex:1;font-weight:600;font-size:16px', crumb))
+			: D('height:48px;flex-shrink:0;border-bottom:1px solid var(--ui-border);background:var(--ui-bg);display:flex;align-items:center;padding:0 24px;gap:8px;color:var(--ui-text-muted)', I('panel-left-close'), S('width:1px;height:16px;background:var(--ui-border);margin:0 6px'), S('color:var(--ui-text-highlighted);font-weight:500', crumb))
+		const kids = kind === 'home' ? HomeBody() : kind === 'settings' ? SettingsBody() : Page()
+		const content = D('flex:1;min-height:0;overflow:hidden;padding:' + (m ? 16 : 24) + 'px;display:flex;flex-direction:column;gap:16px', ...kids)
+		const root = D('width:' + (m ? 390 : 1440) + 'px;height:' + (m ? 844 : 900) + 'px;position:relative;display:flex;flex-direction:' + (m ? 'column' : 'row') + ';background:var(--ui-bg-muted);color:var(--ui-text);font-family:\'IBM Plex Sans\',sans-serif;font-size:13px;line-height:20px;overflow:hidden',
+			!m && side, D('flex:1;min-width:0;min-height:0;display:flex;flex-direction:column', topbar, content), s.panel && Panel(), m && s.drawer && Drawer())
+		return { view: root }
+	}
+}
+</script>
+</body>
+</html>

docs/design/source/ApiKeysPage.dc.html

@@ -0,0 +1,94 @@
+<!DOCTYPE html>
+<html>
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<script src="./support.js"></script>
+</head>
+<body>
+<x-dc>
+<div style="flex:1;min-height:0;overflow:hidden;background:var(--ui-bg-muted);color:var(--ui-text);font-family:'IBM Plex Sans',sans-serif;font-size:13px;line-height:20px;padding:{{ pad }};position:relative;display:flex;flex-direction:column;gap:16px">
+<div style="display:flex;align-items:flex-end;gap:16px;flex-wrap:wrap">
+<div style="flex:1;min-width:200px;display:flex;flex-direction:column;gap:4px"><span style="color:var(--ui-text-muted)">Integration › API keys</span><span style="font:600 {{ h1 }} 'IBM Plex Sans',sans-serif;color:var(--ui-text-highlighted)">API keys</span><span style="color:var(--ui-text-muted);text-wrap:pretty">{{ sub }}</span></div>
+<sc-if value="{{ desk }}"><span style="height:36px;padding:0 14px;display:flex;align-items:center;gap:6px;background:var(--ui-primary);color:var(--ui-bg);font-weight:500">Create key</span></sc-if>
+</div>
+<sc-if value="{{ err }}"><div role="alert" style="display:flex;gap:10px;padding:12px 14px;background:var(--rc-error-soft);color:var(--ui-error)"><span style="flex:1"><strong>Couldn't load your API keys</strong><br>Check your connection and try again.</span><span style="font-weight:500;color:var(--ui-text-highlighted)">Try again</span></div></sc-if>
+<sc-if value="{{ empty }}"><div style="background:var(--ui-bg);border:1px solid var(--ui-border);padding:48px 24px;display:flex;flex-direction:column;align-items:center;gap:10px;text-align:center"><span style="font:600 16px/24px 'IBM Plex Sans',sans-serif;color:var(--ui-text-highlighted)">No API keys yet</span><span style="color:var(--ui-text-toned);max-width:360px;text-wrap:pretty">Create a key to call the API from a script or service.</span><sc-if value="{{ desk }}"><span style="height:36px;padding:0 14px;display:flex;align-items:center;background:var(--ui-primary);color:var(--ui-bg);font-weight:500">Create key</span></sc-if></div></sc-if>
+<sc-if value="{{ showList }}">
+<sc-if value="{{ desk }}"><div style="background:var(--ui-bg);border:1px solid var(--ui-border)">
+<div style="display:grid;grid-template-columns:{{ cols }};gap:12px;height:36px;align-items:center;padding:0 12px;background:var(--ui-bg-elevated);color:var(--ui-text-muted);font-weight:500"><span>Name</span><span>Key</span><span>Status</span><sc-if value="{{ owner }}"><span>Created by</span></sc-if><span>Created</span><span>Last used</span><span>Expires</span><span></span></div>
+<sc-for list="{{ rows }}" as="r" hint-placeholder-count="4"><div style="display:grid;grid-template-columns:{{ cols }};gap:12px;height:48px;align-items:center;padding:0 12px;border-top:1px solid var(--ui-border);background:{{ r.bg }}">
+<sc-if value="{{ r.skel }}"><span style="height:12px;width:60%;background:var(--ui-bg-accented)"></span><span style="height:12px;width:70%;background:var(--ui-bg-accented)"></span><span style="height:20px;width:56px;background:var(--ui-bg-accented)"></span><span style="height:12px;width:60%;background:var(--ui-bg-accented)"></span><span></span><span></span><span></span></sc-if>
+<sc-if value="{{ r.name }}"><span style="overflow:hidden;text-overflow:ellipsis;white-space:nowrap;font-weight:500;color:{{ r.fg }}">{{ r.name }}</span><span style="font:400 12px 'IBM Plex Mono',monospace;color:{{ r.fg2 }}">{{ r.prefix }}</span><span><span style="height:20px;padding:0 6px;display:inline-flex;align-items:center;background:{{ r.sbg }};color:{{ r.sfg }};font-size:12px;font-weight:500">{{ r.status }}</span></span>
+<sc-if value="{{ owner }}"><span style="color:{{ r.fg2 }};overflow:hidden;text-overflow:ellipsis;white-space:nowrap">{{ r.by }}</span></sc-if><span style="color:{{ r.fg2 }}">{{ r.created }}</span><span style="color:{{ r.fg2 }}">{{ r.used }}</span><span style="color:{{ r.fg2 }}">{{ r.exp }}</span>
+<span style="display:flex;justify-content:flex-end"><sc-if value="{{ r.canRevoke }}"><span style="height:28px;padding:0 10px;display:flex;align-items:center;border:1px solid var(--ui-border-accented);color:var(--ui-text-highlighted);font-weight:500">Revoke</span></sc-if></span></sc-if>
+</div></sc-for></div></sc-if>
+<sc-if value="{{ mob }}"><div style="background:var(--ui-bg);border:1px solid var(--ui-border);margin:0 -16px;border-left:0;border-right:0">
+<sc-for list="{{ rows }}" as="r" hint-placeholder-count="4"><div style="display:flex;flex-direction:column;gap:6px;padding:12px 16px;border-bottom:1px solid var(--ui-border);background:{{ r.bg }}">
+<sc-if value="{{ r.skel }}"><span style="height:14px;width:55%;background:var(--ui-bg-accented)"></span><span style="height:12px;width:40%;background:var(--ui-bg-accented)"></span></sc-if>
+<sc-if value="{{ r.name }}"><div style="display:flex;align-items:center;gap:8px"><span style="flex:1;min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;font-weight:500;font-size:15px;color:{{ r.fg }}">{{ r.name }}</span><span style="height:20px;padding:0 6px;display:inline-flex;align-items:center;background:{{ r.sbg }};color:{{ r.sfg }};font-size:12px;font-weight:500">{{ r.status }}</span></div>
+<span style="font:400 12px 'IBM Plex Mono',monospace;color:{{ r.fg2 }}">{{ r.prefix }}</span>
+<span style="color:{{ r.fg2 }}">Created {{ r.created }}<sc-if value="{{ owner }}"> by {{ r.by }}</sc-if> · Last used {{ r.used }} · Expires {{ r.exp }}</span>
+<sc-if value="{{ r.canRevoke }}"><span style="align-self:flex-start;height:44px;padding:0 14px;display:flex;align-items:center;border:1px solid var(--ui-border-accented);color:var(--ui-text-highlighted);font-weight:500">Revoke</span></sc-if></sc-if>
+</div></sc-for></div></sc-if>
+</sc-if>
+<div style="display:flex;flex-direction:column;gap:8px;font-size:14px;line-height:22px;color:var(--ui-text-toned)">
+<div style="display:flex;gap:10px"><span style="display:flex;padding-top:3px;color:var(--ui-info)"><span aria-hidden="true" style="display:inline-block;width:16px;height:16px;background-color:currentColor;-webkit-mask:url('https://api.iconify.design/lucide/info.svg') center / contain no-repeat;mask:url('https://api.iconify.design/lucide/info.svg') center / contain no-repeat"></span></span><span style="text-wrap:pretty">Resetting a user's password revokes all of their keys.</span></div>
+</div>
+<sc-if value="{{ pinned }}"><div style="position:absolute;left:0;right:0;bottom:0;z-index:40;padding:12px 16px;background:var(--ui-bg);border-top:1px solid var(--ui-border)"><span style="height:44px;display:flex;align-items:center;justify-content:center;gap:6px;background:var(--ui-primary);color:var(--ui-bg);font-weight:500">Create key</span></div></sc-if>
+<sc-if value="{{ toast }}"><div role="status" style="position:absolute;{{ toastPos }};z-index:60;display:flex;gap:10px;padding:12px 14px;background:var(--ui-bg);border:1px solid var(--ui-border);box-shadow:var(--rc-shadow-pop);color:var(--ui-success)"><span style="display:flex;flex-direction:column"><strong>Key revoked</strong><span style="color:var(--ui-text-toned)">"Nightly media import" can no longer be used.</span></span></div></sc-if>
+</div>
+<sc-if value="{{ modal }}"><div style="position:absolute;inset:0;z-index:50;background:var(--rc-overlay);display:flex;align-items:{{ mAlign }};justify-content:center;padding:{{ mPad }}">
+<div role="dialog" aria-modal="true" style="width:{{ mW }};max-width:100%;background:var(--ui-bg);border:1px solid var(--ui-border);box-shadow:var(--rc-shadow-modal);padding:20px;display:flex;flex-direction:column;gap:14px;color:var(--ui-text)">
+<div style="display:flex;flex-direction:column;gap:4px"><span style="font:600 18px/26px 'IBM Plex Sans',sans-serif;color:var(--ui-text-highlighted)">{{ m.title }}</span><span style="color:var(--ui-text-toned);font-size:14px;line-height:22px;text-wrap:pretty">{{ m.desc }}</span></div>
+<sc-if value="{{ m.form }}">
+<div style="display:flex;flex-direction:column;gap:6px"><div style="display:flex;justify-content:space-between"><span style="font-weight:500;color:var(--ui-text-highlighted)">Name</span><span style="font:400 12px 'IBM Plex Mono',monospace;color:{{ m.cntFg }}">{{ m.count }}</span></div><span style="height:40px;padding:0 12px;display:flex;align-items:center;border:1px solid {{ m.nameBd }};background:var(--ui-bg);color:var(--ui-text-highlighted)">{{ m.name }}</span><span style="color:{{ m.nameFg }}">{{ m.nameHelp }}</span></div>
+<div style="display:flex;flex-direction:column;gap:6px"><span style="font-weight:500;color:var(--ui-text-highlighted)">Expiry date <span style="font-weight:400;color:var(--ui-text-muted)">(optional)</span></span><span style="height:40px;padding:0 12px;display:flex;align-items:center;border:1px solid {{ m.expBd }};background:var(--ui-bg);color:{{ m.expTx }}">{{ m.exp }}</span><span style="color:{{ m.expFg }}">{{ m.expHelp }}</span></div>
+</sc-if>
+<sc-if value="{{ m.reveal }}">
+<div style="display:flex;gap:10px;padding:10px 12px;background:var(--rc-warning-soft);color:var(--ui-warning)"><span style="display:flex;padding-top:2px"><span aria-hidden="true" style="display:inline-block;width:16px;height:16px;background-color:currentColor;-webkit-mask:url('https://api.iconify.design/lucide/triangle-alert.svg') center / contain no-repeat;mask:url('https://api.iconify.design/lucide/triangle-alert.svg') center / contain no-repeat"></span></span><span style="font-weight:500">You won't be able to see this key again.</span></div>
+<div style="display:flex;flex-direction:{{ keyDir }};border:1px solid var(--ui-border-accented);background:var(--ui-bg-elevated)"><span style="flex:1;min-width:0;padding:10px 12px;font:400 12px/20px 'IBM Plex Mono',monospace;word-break:break-all;color:var(--ui-text-highlighted)">rcms_Kf3x9QwL0aBcT7nV2uYdE5sHjR8mPz4WqXg6C1oIyNe</span><span style="height:44px;padding:0 14px;display:flex;align-items:center;justify-content:center;gap:6px;border-left:1px solid var(--ui-border-accented);font-weight:500;color:{{ m.cpFg }}"><span aria-hidden="true" style="display:inline-block;width:14px;height:14px;background-color:currentColor;-webkit-mask:url('https://api.iconify.design/lucide/{{ m.cpIcon }}.svg') center / contain no-repeat;mask:url('https://api.iconify.design/lucide/{{ m.cpIcon }}.svg') center / contain no-repeat"></span>{{ m.cpT }}</span></div>
+<span style="color:var(--ui-text-muted)">Closing this window discards the key from the screen. Copy it first.</span>
+</sc-if>
+<div style="display:flex;flex-direction:{{ btnDir }};justify-content:flex-end;gap:8px"><sc-if value="{{ m.cancel }}"><span style="height:44px;padding:0 14px;display:flex;align-items:center;justify-content:center;border:1px solid var(--ui-border-accented);color:var(--ui-text-highlighted);font-weight:500">{{ m.cancel }}</span></sc-if><span style="height:44px;padding:0 14px;display:flex;align-items:center;justify-content:center;font-weight:500;background:{{ m.cbg }};color:{{ m.cfg }};opacity:{{ m.cop }}">{{ m.confirm }}</span></div>
+</div></div></sc-if>
+</x-dc>
+<script type="text/x-dc" data-dc-script>
+class Component extends DCLogic {
+	renderVals() {
+		const mob = !!this.props.mobile, k = (this.props.s && this.props.s.ak) || {}
+		const owner = k.view !== 'admin'
+		const R = (name, prefix, status, by, created, used, exp) => {
+			const rv = status === 'revoked', tone = { active: ['var(--rc-success-soft)', 'var(--ui-success)'], expired: ['var(--rc-warning-soft)', 'var(--ui-warning)'], revoked: ['var(--ui-bg-elevated)', 'var(--ui-text-muted)'] }[status]
+			return { name, prefix, status, by, created, used, exp, sbg: tone[0], sfg: tone[1], bg: rv ? 'var(--ui-bg-muted)' : 'var(--ui-bg)', fg: rv ? 'var(--ui-text-muted)' : 'var(--ui-text-highlighted)', fg2: rv ? 'var(--ui-text-muted)' : 'var(--ui-text-toned)', canRevoke: !rv }
+		}
+		let all = owner
+			? [R('Website build', 'rcms_Kf3x…', 'active', 'Marta Alves', '12 Mar 2026', '3 Oct 2026', 'None'), R('Nightly media import', 'rcms_Mq7b…', k.revoked ? 'revoked' : 'active', 'Jonas', '2 Apr 2026', '3 Oct 2026', '31 Dec 2026'), R('Staging preview', 'rcms_Zt2d…', 'expired', 'Marta Alves', '14 Jun 2026', '20 Aug 2026', '30 Aug 2026'), R('Old migration script', 'rcms_Hn5w…', 'revoked', 'Inès Duarte', '3 Apr 2026', '9 May 2026', 'None')]
+			: [R('Nightly media import', 'rcms_Mq7b…', 'active', 'Jonas', '2 Apr 2026', '3 Oct 2026', '31 Dec 2026'), R('Old CI token', 'rcms_Lp9c…', 'revoked', 'Jonas', '18 Jan 2026', '2 Feb 2026', 'None')]
+		const st = k.state || 'list'
+		const rows = st === 'loading' ? Array.from({ length: 4 }, () => ({ skel: true, bg: 'var(--ui-bg)' })) : all
+		const cp = { reveal: true }
+		const b = (o) => ({ cancel: 'Cancel', cbg: 'var(--ui-primary)', cfg: 'var(--ui-bg)', cop: '1', ...o })
+		const form = (o) => b({ form: true, title: 'Create API key', desc: 'The key acts as you, with your role. It is shown in full once.', confirm: 'Create key', name: 'Nightly media import', count: '20 / 60', cntFg: 'var(--ui-text-muted)', nameBd: 'var(--ui-border-accented)', nameFg: 'var(--ui-text-muted)', nameHelp: 'Required. Up to 60 characters.', exp: '31 Dec 2026', expTx: 'var(--ui-text-highlighted)', expBd: 'var(--ui-border-accented)', expFg: 'var(--ui-text-muted)', expHelp: 'Optional. Must be in the future. Leave it empty for a key that does not expire.', ...o })
+		const M = {
+			create: form({}),
+			invalid: form({ name: '', count: '0 / 60', nameBd: 'var(--ui-error)', nameFg: 'var(--ui-error)', nameHelp: 'Enter a name.', exp: '12 Mar 2026', expBd: 'var(--ui-error)', expFg: 'var(--ui-error)', expHelp: 'Choose a date in the future.' }),
+			toolong: form({ name: 'Nightly import of the new media library from the Brussels office file server', count: '75 / 60', cntFg: 'var(--ui-error)', nameBd: 'var(--ui-error)', nameFg: 'var(--ui-error)', nameHelp: 'Use 60 characters or fewer.' }),
+			reveal: b({ reveal: true, title: 'Your new API key', desc: '"Nightly media import" is ready. Copy the key and store it somewhere safe.', cancel: '', confirm: 'Done', cpT: 'Copy', cpIcon: 'copy', cpFg: 'var(--ui-text-highlighted)' }),
+			copied: b({ reveal: true, title: 'Your new API key', desc: '"Nightly media import" is ready. Copy the key and store it somewhere safe.', cancel: '', confirm: 'Done', cpT: 'Copied', cpIcon: 'check', cpFg: 'var(--ui-success)' }),
+			revoke: b({ title: 'Revoke this key?', desc: '"Nightly media import" (rcms_Mq7b…) will stop working right away. Requests that use it answer 401. This can\'t be undone.', cancel: 'Keep key', confirm: 'Revoke key', cbg: 'var(--ui-error)', cfg: 'var(--ui-bg)' })
+		}
+		const m = k.modal ? M[k.modal] : null
+		return {
+			mob, desk: !mob, owner, rows, pad: mob ? '20px 16px 84px' : '32px', pinned: mob && !m, h1: mob ? '20px/28px' : '28px/36px',
+			sub: owner ? 'Keys act as the user who created them. As an owner you see everyone\'s keys.' : 'Keys act as you, with your role. You only see your own keys.',
+			err: st === 'error', empty: st === 'empty', showList: st === 'list' || st === 'loading',
+			cols: owner ? 'minmax(0,1.3fr) 110px 76px minmax(0,1fr) 100px 100px 100px 80px' : 'minmax(0,1.3fr) 110px 76px 100px 100px 100px 80px',
+			toast: !!k.toast, toastPos: mob ? 'left:16px;right:16px;bottom:84px' : 'right:24px;bottom:24px;width:320px',
+			modal: !!m, m: m || {}, mAlign: mob ? 'flex-end' : 'flex-start', mPad: mob ? '16px' : '120px 16px 16px', mW: mob ? '100%' : '480px', btnDir: mob ? 'column-reverse' : 'row', keyDir: mob ? 'column' : 'row'
+		}
+	}
+}
+</script>
+</body>
+</html>

docs/design/source/AppFrame.dc.html

@@ -27,7 +27,7 @@
 <sc-if value="{{ mob }}">
 <div style="height:56px;flex-shrink:0;border-bottom:1px solid var(--ui-border);background:var(--ui-bg);display:flex;align-items:center;padding:0 6px;gap:4px;color:var(--ui-text-highlighted)"><span data-act="m-lead" style="position:relative;width:44px;height:44px;display:flex;align-items:center;justify-content:center"><sc-if value="{{ s.navBadge }}"><span aria-label="Update available" style="position:absolute;top:9px;right:9px;width:10px;height:10px;background:var(--ui-info);border:2px solid var(--ui-bg)"></span></sc-if><span aria-hidden="true" style="display:inline-block;flex-shrink:0;width:20px;height:20px;background-color:currentColor;-webkit-mask:url('https://api.iconify.design/lucide/{{ mLead }}.svg') center / contain no-repeat;mask:url('https://api.iconify.design/lucide/{{ mLead }}.svg') center / contain no-repeat"></span></span><span style="flex:1;min-width:0;font-weight:600;font-size:16px;overflow:hidden;text-overflow:ellipsis;white-space:nowrap">{{ s.mTitle }}</span><sc-if value="{{ s.mAction }}"><span data-act="m-action" style="width:44px;height:44px;display:flex;align-items:center;justify-content:center"><span aria-hidden="true" style="display:inline-block;flex-shrink:0;width:20px;height:20px;background-color:currentColor;-webkit-mask:url('https://api.iconify.design/lucide/{{ s.mAction }}.svg') center / contain no-repeat;mask:url('https://api.iconify.design/lucide/{{ s.mAction }}.svg') center / contain no-repeat"></span></span></sc-if></div>
 </sc-if>
-<sc-if value="{{ s.offline }}"><div role="status" style="flex-shrink:0;display:flex;align-items:center;gap:10px;padding:10px 16px;background:var(--ui-bg-inverted);color:var(--ui-text-inverted)"><span aria-hidden="true" style="display:inline-block;flex-shrink:0;width:16px;height:16px;background-color:currentColor;-webkit-mask:url('https://api.iconify.design/lucide/wifi-off.svg') center / contain no-repeat;mask:url('https://api.iconify.design/lucide/wifi-off.svg') center / contain no-repeat"></span><span style="flex:1">You're offline. You can keep writing, but saving and publishing will wait until you're back online.</span></div></sc-if>
+<sc-if value="{{ s.offline }}"><div role="status" style="flex-shrink:0;display:flex;align-items:center;gap:10px;padding:10px 16px;background:var(--ui-bg-inverted);color:var(--ui-text-inverted)"><span aria-hidden="true" style="display:inline-block;flex-shrink:0;width:16px;height:16px;background-color:currentColor;-webkit-mask:url('https://api.iconify.design/lucide/wifi-off.svg') center / contain no-repeat;mask:url('https://api.iconify.design/lucide/wifi-off.svg') center / contain no-repeat"></span><span style="flex:1">{{ offText }}</span></div></sc-if>
 
 <div style="flex:1;min-height:0;overflow:hidden;display:flex;flex-direction:column">
 
@@ -66,6 +66,14 @@
 </div>
 </div>
 </sc-if>
+<sc-if value="{{ act.show }}">
+<div style="display:flex;flex-direction:column;gap:10px">
+<div style="display:flex;align-items:baseline;justify-content:space-between"><span style="font:600 16px/24px 'IBM Plex Sans',sans-serif;color:var(--ui-text-highlighted)">{{ act.title }}</span><span data-act="nav-activity" style="color:var(--ui-text-toned);text-decoration:underline;text-underline-offset:3px">View all</span></div>
+<sc-if value="{{ act.error }}"><div style="display:flex;gap:10px;padding:12px 14px;background:var(--rc-error-soft);color:var(--ui-error)"><span style="display:flex;padding-top:2px"><span aria-hidden="true" style="display:inline-block;flex-shrink:0;width:16px;height:16px;background-color:currentColor;-webkit-mask:url('https://api.iconify.design/lucide/circle-x.svg') center / contain no-repeat;mask:url('https://api.iconify.design/lucide/circle-x.svg') center / contain no-repeat;"></span></span><div style="flex:1;display:flex;flex-direction:column;gap:8px"><div style="display:flex;flex-direction:column;gap:2px"><span style="font-weight:600">Couldn't load recent activity</span><span style="color:var(--ui-text-toned)">Check your connection and try again.</span></div><span role="button" style="height:28px;padding:0 10px;display:flex;align-items:center;justify-content:center;gap:6px;border:1px solid var(--ui-border-accented);background:var(--ui-bg);color:var(--ui-text-highlighted);font-weight:500;font-size:12px;white-space:nowrap;opacity:1"><span aria-hidden="true" style="display:inline-block;flex-shrink:0;width:16px;height:16px;background-color:currentColor;-webkit-mask:url('https://api.iconify.design/lucide/rotate-cw.svg') center / contain no-repeat;mask:url('https://api.iconify.design/lucide/rotate-cw.svg') center / contain no-repeat;"></span>Try again</span></div></div></sc-if>
+<sc-if value="{{ act.empty }}"><div style="background:var(--ui-bg);border:1px solid var(--ui-border);padding:32px 24px;display:flex;flex-direction:column;align-items:center;gap:6px;text-align:center"><span style="color:var(--ui-text-muted)"><span aria-hidden="true" style="display:inline-block;flex-shrink:0;width:20px;height:20px;background-color:currentColor;-webkit-mask:url('https://api.iconify.design/lucide/history.svg') center / contain no-repeat;mask:url('https://api.iconify.design/lucide/history.svg') center / contain no-repeat;"></span></span><span style="font-weight:600;color:var(--ui-text-highlighted)">No activity yet</span><span style="color:var(--ui-text-muted);max-width:260px">{{ act.emptyText }}</span></div></sc-if>
+<sc-if value="{{ act.rows }}"><div style="background:var(--ui-bg);border:1px solid var(--ui-border)"><sc-for list="{{ act.rows }}" as="r" hint-placeholder-count="5"><div style="display:flex;align-items:center;gap:12px;min-height:{{ rowH }};padding:8px 12px;border-top:1px solid var(--ui-border-muted)"><sc-if value="{{ r.skel }}"><span style="width:24px;height:24px;flex-shrink:0;background:var(--ui-bg-accented)"></span><span style="flex:1;height:12px;background:var(--ui-bg-accented);max-width:60%"></span></sc-if><sc-if value="{{ r.s }}"><span style="width:24px;height:24px;flex-shrink:0;display:flex;align-items:center;justify-content:center;background:var(--rc-sand);color:#111;font:600 10px 'IBM Plex Sans',sans-serif">{{ r.ini }}</span><div style="flex:1;min-width:0;display:flex;flex-direction:column"><span style="overflow:hidden;text-overflow:ellipsis;white-space:nowrap;color:var(--ui-text)">{{ r.s }}<span style="font-weight:600;color:var(--ui-text-highlighted)">{{ r.em }}</span></span><span style="font-size:12px;color:var(--ui-text-muted)">{{ r.meta }}</span></div><sc-if value="{{ r.fail }}"><span style="height:20px;padding:0 6px;display:inline-flex;align-items:center;gap:4px;background:var(--rc-error-soft);color:var(--ui-error);font-size:12px;font-weight:500"><span aria-hidden="true" style="display:inline-block;flex-shrink:0;width:12px;height:12px;background-color:currentColor;-webkit-mask:url('https://api.iconify.design/lucide/circle-x.svg') center / contain no-repeat;mask:url('https://api.iconify.design/lucide/circle-x.svg') center / contain no-repeat;"></span>Failed</span></sc-if></sc-if></div></sc-for></div></sc-if>
+</div>
+</sc-if>
 <div style="background:var(--ui-bg);border:1px solid var(--ui-border);padding:16px;display:flex;gap:14px;align-items:flex-start"><span style="width:36px;height:36px;flex-shrink:0;display:flex;align-items:center;justify-content:center;background:var(--rc-sand);color:#111"><span aria-hidden="true" style="display:inline-block;flex-shrink:0;width:18px;height:18px;background-color:currentColor;-webkit-mask:url('https://api.iconify.design/lucide/plug.svg') center / contain no-repeat;mask:url('https://api.iconify.design/lucide/plug.svg') center / contain no-repeat"></span></span><div style="flex:1;display:flex;flex-direction:column;gap:4px"><span style="font-weight:600;font-size:14px;color:var(--ui-text-highlighted)">Connect your website</span><span style="color:var(--ui-text-muted);text-wrap:pretty">Your site reads published articles from RenewCMS. Share this guide with whoever builds it.</span><span data-act="nav-integration" style="color:var(--ui-text-highlighted);font-weight:500;text-decoration:underline;text-underline-offset:3px;margin-top:4px">Open the guide</span></div></div>
 </div>
 </sc-if>
@@ -177,25 +185,8 @@
 </sc-if>
 </sc-if>
 
-<sc-if value="{{ isInteg }}">
-<div style="padding:{{ pad }};display:flex;flex-direction:column;gap:24px;max-width:860px;overflow:hidden">
-<div style="display:flex;flex-direction:column;gap:4px"><span style="font:600 20px/28px 'IBM Plex Sans',sans-serif;color:var(--ui-text-highlighted)">Connect your website</span><span style="color:var(--ui-text-muted)">A guide for the developer who builds your public site.</span></div>
-<p style="margin:0;font-size:14px;line-height:22px;color:var(--ui-text-toned);text-wrap:pretty">RenewCMS is headless: it stores and publishes your articles but doesn't show them to visitors. Your website fetches published articles from the two addresses below and displays them in its own design.</p>
-<div style="display:flex;flex-direction:column;gap:6px"><span style="font-weight:500;color:var(--ui-text-highlighted)">Base URL</span><div style="display:flex;border:1px solid var(--ui-border-accented);background:var(--ui-bg)"><span style="flex:1;min-width:0;height:40px;padding:0 12px;display:flex;align-items:center;font:400 13px 'IBM Plex Mono',monospace;overflow:hidden;white-space:nowrap">https://cms.renew.example</span><span data-act="copy" style="height:40px;padding:0 12px;display:flex;align-items:center;gap:6px;border-left:1px solid var(--ui-border-accented);font-weight:500;color:{{ copyFg }}"><span aria-hidden="true" style="display:inline-block;flex-shrink:0;width:14px;height:14px;background-color:currentColor;-webkit-mask:url('https://api.iconify.design/lucide/{{ copyIcon }}.svg') center / contain no-repeat;mask:url('https://api.iconify.design/lucide/{{ copyIcon }}.svg') center / contain no-repeat"></span>{{ copyText }}</span></div></div>
-<sc-for list="{{ endpoints }}" as="e" hint-placeholder-count="2">
-<div style="background:var(--ui-bg);border:1px solid var(--ui-border)">
-<div style="padding:16px;display:flex;flex-direction:column;gap:8px;border-bottom:1px solid var(--ui-border)"><div style="display:flex;align-items:center;gap:10px;flex-wrap:wrap"><span style="height:22px;padding:0 7px;display:inline-flex;align-items:center;background:var(--ui-bg-inverted);color:var(--ui-text-inverted);font:500 12px 'IBM Plex Mono',monospace">GET</span><span style="font:500 14px 'IBM Plex Mono',monospace;color:var(--ui-text-highlighted)">{{ e.path }}</span></div><span style="color:var(--ui-text-toned)">{{ e.desc }}</span></div>
-<div style="display:flex;gap:20px;padding:0 16px;border-bottom:1px solid var(--ui-border)"><span style="height:36px;display:flex;align-items:center;border-bottom:2px solid {{ e.l1 }};margin-bottom:-1px;font-weight:500;color:var(--ui-text-highlighted)">fetch</span><span style="height:36px;display:flex;align-items:center;color:var(--ui-text-toned)">curl</span><span style="height:36px;display:flex;align-items:center;color:var(--ui-text-toned)">Response</span></div>
-<div style="background:var(--ui-bg-elevated)"><div style="height:32px;padding:0 8px 0 16px;display:flex;align-items:center;justify-content:space-between;border-bottom:1px solid var(--ui-border)"><span style="font:500 12px 'IBM Plex Mono',monospace;color:var(--ui-text-muted)">JavaScript</span><span style="display:flex;align-items:center;gap:6px;color:var(--ui-text-toned);font-weight:500"><span aria-hidden="true" style="display:inline-block;flex-shrink:0;width:14px;height:14px;background-color:currentColor;-webkit-mask:url('https://api.iconify.design/lucide/copy.svg') center / contain no-repeat;mask:url('https://api.iconify.design/lucide/copy.svg') center / contain no-repeat"></span>Copy</span></div><pre style="margin:0;padding:14px 16px;overflow:hidden;font:400 12px/19px 'IBM Plex Mono',monospace;color:var(--ui-text);white-space:pre">{{ e.code }}</pre></div>
-</div>
-</sc-for>
-<div style="display:flex;flex-direction:column;gap:10px;font-size:14px;line-height:22px;color:var(--ui-text-toned)">
-<div style="display:flex;gap:10px"><span style="display:flex;padding-top:3px;color:var(--ui-info)"><span aria-hidden="true" style="display:inline-block;flex-shrink:0;width:16px;height:16px;background-color:currentColor;-webkit-mask:url('https://api.iconify.design/lucide/info.svg') center / contain no-repeat;mask:url('https://api.iconify.design/lucide/info.svg') center / contain no-repeat"></span></span><span style="text-wrap:pretty">Anonymous callers only ever get online articles. Drafts stay private until you publish them.</span></div>
-<div style="display:flex;gap:10px"><span style="display:flex;padding-top:3px;color:var(--ui-info)"><span aria-hidden="true" style="display:inline-block;flex-shrink:0;width:16px;height:16px;background-color:currentColor;-webkit-mask:url('https://api.iconify.design/lucide/info.svg') center / contain no-repeat;mask:url('https://api.iconify.design/lucide/info.svg') center / contain no-repeat"></span></span><span style="text-wrap:pretty">Images in <code>body</code> use paths like <code>/static/uploadedImages/&lt;uuid&gt;.png</code>. Prefix them with the base URL before rendering.</span></div>
-<div style="display:flex;gap:10px"><span style="display:flex;padding-top:3px;color:var(--ui-info)"><span aria-hidden="true" style="display:inline-block;flex-shrink:0;width:16px;height:16px;background-color:currentColor;-webkit-mask:url('https://api.iconify.design/lucide/info.svg') center / contain no-repeat;mask:url('https://api.iconify.design/lucide/info.svg') center / contain no-repeat"></span></span><span style="text-wrap:pretty">Browsers can only call the API from origins listed in the server's CORS setting. Ask whoever runs the server to add your site's address.</span></div>
-</div>
-</div>
-</sc-if>
+<sc-if value="{{ isInteg }}"><div style="position:relative;flex:1;min-height:0;overflow:hidden"><dc-import name="IntegrationPage" s="{{ s }}" mobile="{{ mob }}" style="display:flex;flex-direction:column;flex:1;min-height:0;overflow:hidden" hint-size="100%,100%"></dc-import></div></sc-if>
+<sc-if value="{{ isKeys }}"><div style="display:flex;flex-direction:column;flex:1;min-height:0;overflow:hidden"><dc-import name="ApiKeysPage" s="{{ s }}" mobile="{{ mob }}" style="display:flex;flex-direction:column;flex:1;min-height:0;overflow:hidden" hint-size="100%,100%"></dc-import></div></sc-if>
 
 <sc-if value="{{ isUsers }}">
 <div style="padding:{{ pad }};display:flex;flex-direction:column;gap:16px;flex:1;min-height:0">
@@ -228,7 +219,7 @@
 </sc-if>
 
 <sc-if value="{{ isSettings }}">
-<div style="padding:{{ pad }};display:flex;flex-direction:column;gap:20px;max-width:720px;overflow:hidden">
+<div style="padding:{{ pad }};display:flex;flex-direction:column;gap:20px;max-width:720px;flex-shrink:0;margin-top:{{ setScroll }}">
 <div style="display:flex;flex-direction:column;gap:2px"><span style="font:600 20px/28px 'IBM Plex Sans',sans-serif;color:var(--ui-text-highlighted)">Settings</span><span style="color:var(--ui-text-muted)">Workspace information.</span></div>
 <div style="background:var(--ui-bg);border:1px solid var(--ui-border);padding:{{ cardPad }};display:flex;align-items:center;justify-content:space-between;gap:16px"><span style="font:600 15px/24px 'IBM Plex Sans',sans-serif;color:var(--ui-text-highlighted)">Version</span><span style="font:400 14px/22px 'IBM Plex Mono',monospace;color:var(--ui-text-toned)">{{ s.upd.v }}</span></div>
 <div role="region" aria-labelledby="updates-h" style="background:var(--ui-bg);border:1px solid var(--ui-border);padding:{{ cardPad }};display:flex;flex-direction:column;gap:16px">
@@ -240,6 +231,8 @@
 <sc-if value="{{ s.upd.hint }}"><span style="font-size:12px;color:var(--ui-text-muted);text-wrap:pretty">{{ s.upd.hint }}</span></sc-if>
 <sc-if value="{{ s.upd.link }}"><span style="align-self:flex-start;display:flex;align-items:center;gap:6px;color:var(--ui-text-highlighted);text-decoration:underline;text-underline-offset:3px;font-weight:500">{{ s.upd.link }}<span aria-hidden="true" style="display:inline-block;width:14px;height:14px;background-color:currentColor;-webkit-mask:url('https://api.iconify.design/lucide/external-link.svg') center / contain no-repeat;mask:url('https://api.iconify.design/lucide/external-link.svg') center / contain no-repeat"></span></span></sc-if>
 </div>
+<div role="region" aria-labelledby="cleanup-h" style="background:var(--ui-bg);border:1px solid var(--ui-border);padding:{{ cardPad }};display:flex;flex-direction:column;gap:16px"><sc-if value="{{ cl.loading }}"><div aria-busy="true" style="display:flex;flex-direction:column;gap:16px"><span style="display:block;width:140px;height:16px;background:var(--ui-bg-accented)"></span><span style="display:block;width:90%;height:13px;background:var(--ui-bg-accented)"></span><span style="display:block;width:55%;height:13px;background:var(--ui-bg-accented)"></span><div style="display:flex;justify-content:space-between;align-items:center"><div style="display:flex;flex-direction:column;gap:6px"><span style="display:block;width:120px;height:13px;background:var(--ui-bg-accented)"></span><span style="display:block;width:180px;height:11px;background:var(--ui-bg-accented)"></span></div><span style="display:block;width:36px;height:20px;background:var(--ui-bg-accented)"></span></div><span style="display:block;width:60%;height:13px;background:var(--ui-bg-accented)"></span><div style="height:1px;background:var(--ui-border)"></div><div style="display:flex;justify-content:space-between;align-items:center"><div style="display:flex;flex-direction:column;gap:6px"><span style="display:block;width:100px;height:13px;background:var(--ui-bg-accented)"></span><span style="display:block;width:220px;height:11px;background:var(--ui-bg-accented)"></span></div><span style="display:block;width:140px;height:32px;background:var(--ui-bg-accented)"></span></div></div></sc-if><sc-if value="{{ cl.ready }}"><div style="display:flex;align-items:flex-start;gap:12px"><div style="flex:1;display:flex;flex-direction:column;gap:2px"><span id="cleanup-h" tabindex="-1" style="align-self:flex-start;font:600 15px/24px 'IBM Plex Sans',sans-serif;color:var(--ui-text-highlighted)">Media cleanup</span><span style="color:var(--ui-text-muted);text-wrap:pretty">Merge identical images so your library stays tidy. Articles that use a copy are switched to the most used one.</span></div><div style="height:24px;display:flex;align-items:center;flex-shrink:0"><sc-if value="{{ cl.saving }}"><span style="display:flex;align-items:center;gap:6px;font-size:12px;color:var(--ui-text-muted)"><span aria-hidden="true" style="display:inline-block;flex-shrink:0;width:14px;height:14px;background-color:currentColor;-webkit-mask:url('https://api.iconify.design/lucide/loader-circle.svg') center / contain no-repeat;mask:url('https://api.iconify.design/lucide/loader-circle.svg') center / contain no-repeat;"></span>Saving…</span></sc-if><sc-if value="{{ cl.saved }}"><span role="status" style="display:flex;align-items:center;gap:6px;font-size:12px;color:var(--ui-success)"><span aria-hidden="true" style="display:inline-block;flex-shrink:0;width:14px;height:14px;background-color:currentColor;-webkit-mask:url('https://api.iconify.design/lucide/check.svg') center / contain no-repeat;mask:url('https://api.iconify.design/lucide/check.svg') center / contain no-repeat;"></span>Saved</span></sc-if></div></div><sc-if value="{{ cl.ro }}"><div style="display:flex;gap:10px;padding:12px 14px;background:var(--rc-info-soft);color:var(--ui-info)"><span style="display:flex;padding-top:2px"><span aria-hidden="true" style="display:inline-block;flex-shrink:0;width:16px;height:16px;background-color:currentColor;-webkit-mask:url('https://api.iconify.design/lucide/info.svg') center / contain no-repeat;mask:url('https://api.iconify.design/lucide/info.svg') center / contain no-repeat;"></span></span><span style="color:var(--ui-text-toned)">Only owners and admins can change this.</span></div></sc-if><div style="display:flex;flex-direction:{{ rowDir }};align-items:{{ rowAlign }};justify-content:{{ rowJust }};gap:{{ rowGap }}"><div style="display:flex;flex-direction:column;gap:2px;min-width:0"><span style="font-weight:500;color:var(--ui-text-highlighted)">Automatic purge</span><span style="font-size:12px;color:var(--ui-text-muted)">Runs in the background. Off by default.</span></div><div role="switch" aria-checked="{{ cl.on }}" style="display:flex;align-items:center;justify-content:center;width:{{ cl.swW }};height:{{ cl.swH }};flex-shrink:0;opacity:{{ cl.swOp }}"><div style="position:relative;width:36px;height:20px;border:1px solid {{ cl.swBd }};background:{{ cl.swBg }};outline:{{ cl.swRing }};outline-offset:2px"><div style="position:absolute;top:1px;left:{{ cl.knobL }};width:16px;height:16px;background:var(--ui-bg);border:1px solid {{ cl.knobBd }};box-sizing:border-box"></div></div></div></div><sc-if value="{{ cl.on }}"><div style="display:flex;flex-direction:{{ rowDir }};align-items:{{ rowAlign }};justify-content:{{ rowJust }};gap:{{ rowGap }}"><div style="display:flex;flex-direction:column;gap:2px;min-width:0"><span style="font-weight:500;color:var(--ui-text-highlighted)">Every</span><span style="font-size:12px;color:var(--ui-text-muted)">Between 1 and 365 days.</span></div><div style="display:flex;flex-direction:column;gaLine truncated
+<sc-if value="{{ rt.show }}"><div role="region" aria-labelledby="retention-h" style="background:var(--ui-bg);border:1px solid var(--ui-border);padding:{{ cardPad }};display:flex;flex-direction:column;gap:16px"><div style="display:flex;align-items:flex-start;gap:12px"><div style="flex:1;display:flex;flex-direction:column;gap:2px"><span id="retention-h" tabindex="-1" style="align-self:flex-start;font:600 15px/24px 'IBM Plex Sans',sans-serif;color:var(--ui-text-highlighted)">Retention</span><span style="color:var(--ui-text-muted);text-wrap:pretty">How long activity is kept, and how much log data to keep. Whichever limit is reached first removes the oldest events. Only owners can change it.</span></div><div style="height:24px;display:flex;align-items:center;flex-shrink:0"><sc-if value="{{ rt.saving }}"><span style="display:flex;align-items:center;gap:6px;font-size:12px;color:var(--ui-text-muted)"><span aria-hidden="true" style="display:inline-block;flex-shrink:0;width:14px;height:14px;background-color:currentColor;-webkit-mask:url('https://api.iconify.design/lucide/loader-circle.svg') center / contain no-repeat;mask:url('https://api.iconify.design/lucide/loader-circle.svg') center / contain no-repeat;"></span>Saving…</span></sc-if><sc-if value="{{ rt.saved }}"><span role="status" style="display:flex;align-items:center;gap:6px;font-size:12px;color:var(--ui-success)"><span aria-hidden="true" style="display:inline-block;flex-shrink:0;width:14px;height:14px;background-color:currentColor;-webkit-mask:url('https://api.iconify.design/lucide/check.svg') center / contain no-repeat;mask:url('https://api.iconify.design/lucide/check.svg') center / contain no-repeat;"></span>Saved</span></sc-if></div></div><sc-if value="{{ rt.err }}"><div style="display:flex;gap:10px;padding:12px 14px;background:var(--rc-error-soft);color:var(--ui-error)"><span style="display:flex;padding-top:2px"><span aria-hidden="true" style="display:inline-block;flex-shrink:0;width:16px;height:16px;background-color:currentColor;-webkit-mask:url('https://api.iconify.design/lucide/circle-x.svg') center / contain no-repeat;mask:url('https://api.iconify.design/lucide/circle-x.svg') center / contain no-repeat;"></span></span><div style="flex:1;display:flex;flex-direction:column;gap:8px"><div style="display:flex;flex-direction:column;gap:2px"><span style="font-weight:600">Couldn't save the retention period</span><span style="color:var(--ui-text-toned)">Your previous setting is still in place.</span></div><span role="button" style="height:28px;padding:0 10px;display:flex;align-items:center;justify-content:center;gap:6px;border:1px solid var(--ui-border-accented);background:var(--ui-bg);color:var(--ui-text-highlighted);font-weight:500;font-size:12px;white-space:nowrap;opacity:1">Try again</span></div></div></sc-if><div style="display:flex;flex-direction:{{ rowDir }};align-items:{{ rowAlign }};justify-content:{{ rowJust }};gap:{{ rowGap }}"><div style="display:flex;flex-direction:column;gap:2px;min-width:0"><span style="font-weight:500;color:var(--ui-text-highlighted)">Keep activity for</span><span style="font-size:12px;color:var(--ui-text-muted)">{{ rt.help }}</span></div><div style="display:flex;align-items:center;width:{{ rt.selW }};min-height:{{ inH }};padding:0 12px;border:1px solid var(--ui-border-accented);background:var(--ui-bg);font-size:{{ inF }};color:var(--ui-text-highlighted)"><span style="flex:1">{{ rt.val }}</span><span aria-hidden="true" style="display:inline-block;flex-shrink:0;width:16px;height:16px;background-color:currentColor;-webkit-mask:url('https://api.iconify.design/lucide/chevron-down.svg') center / contain no-repeat;mask:url('https://api.iconify.design/lucide/chevron-down.svg') center / contain no-repeat;color:var(--ui-text-muted)"></span></div></div><div style="display:flex;align-items:center;gap:12px;color:var(--ui-text-muted);font-size:12px;font-weight:500"><span style="flex:1;height:1px;background:var(--ui-border)"></span><span>or</span><span style="flex:1;height:1px;background:var(--ui-border)"></span></div><div style="display:flex;flex-direction:{{ rowDir }};align-items:{{ rowAlign }};justify-content:{{ rowJust }};gap:{{ rowGap }}"><div style="display:flex;flex-direction:column;gap:2px;min-width:0"><span style="font-weight:500;color:var(--ui-text-highlighted)">Keep at most</span><span style="font-size:12px;color:var(--ui-text-muted)">{{ rt.sizeHelp }}</span></div><div style="display:flex;align-items:center;width:{{ rt.selW }};min-height:{{ inH }};padding:0 12px;border:1px solid var(--ui-border-accented);background:var(--ui-bg);font-size:{{ inF }};color:var(--ui-text-highlighted)"><span style="flex:1">{{ rt.sizeVal }}</span><span aria-hidden="true" style="display:inline-block;flex-shrink:0;width:16px;height:16px;background-color:currentColor;-webkit-mask:url('https://api.iconify.design/lucide/chevron-down.svg') center / contain no-repeat;mask:url('https://api.iconify.design/lucide/chevron-down.svg') center / contain no-repeat;cLine truncated
 </div>
 </sc-if>
 
@@ -340,6 +333,7 @@
 </div>
 </sc-if>
 
+{{ purgeDlg }}
 <sc-if value="{{ hasToasts }}">
 <div style="position:absolute;z-index:60;display:flex;flex-direction:column;gap:8px;left:{{ tL }};right:{{ tR }};bottom:{{ tB }};width:{{ tW }}">
 <sc-for list="{{ toasts }}" as="t" hint-placeholder-count="1">
@@ -355,7 +349,7 @@ class Component extends DCLogic {
 		const s = this.props.s || {}
 		const m = !!this.props.mobile
 		const k = s.kind || 'home'
-		const navItems = [['home', 'house', 'Home'], ['articles', 'file-text', 'Articles'], ['media', 'images', 'Media'], ['users', 'users', 'Users'], ['integration', 'plug', 'Integration'], ['settings', 'settings', 'Settings']]
+		const navItems = s.role === 'user' ? [['home', 'house', 'Home'], ['articles', 'file-text', 'Articles'], ['media', 'images', 'Media'], ['activity', 'history', 'Activity']] : [['home', 'house', 'Home'], ['articles', 'file-text', 'Articles'], ['media', 'images', 'Media'], ['users', 'users', 'Users'], ['activity', 'history', 'Activity'], ['integration', 'plug', 'Integration'], ['settings', 'settings', 'Settings']]
 		const nav = navItems.map(([key, icon, t]) => ({ key, icon, t, bg: s.nav === key ? 'var(--rc-sand)' : 'transparent', badge: key === 'settings' && !!s.navBadge, fg: s.nav === key ? '#111111' : 'var(--ui-text-toned)', fw: s.nav === key ? 500 : 400 }))
 		const crumbs = (s.crumbs || []).map((t, i, a) => ({ t, sep: i > 0, fg: i === a.length - 1 ? 'var(--ui-text-highlighted)' : 'var(--ui-text-muted)', fw: i === a.length - 1 ? 500 : 400 }))
 		const L = s.list || {}
@@ -423,6 +417,71 @@ class Component extends DCLogic {
 		const rsMap = { sent: { bg: 'var(--rc-success-soft)', fg: 'var(--ui-success)', icon: 'mail-check', title: 'Reset link sent', text: 'Check marta@renew.example. The link works once, within 1 hour.' }, limited: { bg: 'var(--rc-warning-soft)', fg: 'var(--ui-warning)', icon: 'clock-alert', title: 'Too many requests', text: 'You\'ve asked for several links recently. Wait a few minutes, then try again.' }, error: { bg: 'var(--rc-error-soft)', fg: 'var(--ui-error)', icon: 'circle-x', title: 'Couldn\'t send the link', text: 'Check your connection and try again.' } }
 		const rsNote = rsMap[rs] || null
 		const rsBtn = { t: rs === 'sending' ? 'Sending…' : rs === 'sent' ? 'Send again' : 'Send reset link', icon: rs === 'sending' ? 'loader-circle' : 'mail', op: rs === 'limited' ? '0.4' : '1' }
+		const E5 = [['Marta Alves', 'Published the article ', 'Spring release', '2 min ago', 1], ['Marta Alves', 'Edited the article ', 'Why we reuse original floorboards', '29 min ago', 1], ['Not signed in', 'Failed login attempt for ', 'alex@example.com', '1 h ago', 0], ['Jonas Weber', 'Revoked API key ', 'Mobile app', '2 h ago', 1], ['Scheduler', 'Ran the nightly backup', '', '7 h ago', 1]]
+		const E4 = [['Marta Alves', 'Published the article ', 'Spring release', '2 min ago', 1], ['Marta Alves', 'Edited the article ', 'Why we reuse original floorboards', '29 min ago', 1], ['Marta Alves', 'Deleted the image ', 'old-banner.png', 'Yesterday', 1], ['Marta Alves', 'Uploaded the image ', 'floorboards-copy.jpg', '3 Oct 2026', 1]]
+		const ho = s.home || {}, own = s.role === 'user'
+		const actRows = ho.act === 'loading' ? Array.from({ length: 5 }, () => ({ skel: true })) : ho.act === 'ok' ? (own ? E4 : E5).map(([a, t, em, rel, ok]) => ({ s: t, em, meta: own ? rel : a + ' · ' + rel, fail: !ok, ini: a === 'Scheduler' ? 'SY' : a === 'Not signed in' ? '?' : a.split(' ').map(w => w[0]).join('') })) : null
+		const act = { show: !!ho.act && k === 'home' && !s.boot, title: own ? 'Your recent activity' : 'Recent activity', rows: actRows, error: ho.act === 'error', empty: ho.act === 'empty', emptyText: own ? 'Your actions will appear here.' : 'Actions on your site will appear here.' }
+		const C = s.cleanup || {}, cOn = !!C.on, cDis = !!(C.ro || C.offline || C.loading), cErr = !!(C.invalid || C.saveErr)
+		const cl = { loading: !!C.loading, ready: !C.loading, ro: !!C.ro, notRo: !C.ro, on: cOn, saving: !!C.saving, saved: !!C.saved && !C.saving, swW: m ? '44px' : '36px', swH: m ? '44px' : '24px', swOp: cDis ? '0.4' : '1', swRing: C.focusSw ? '2px solid var(--ui-primary)' : '0', swBd: cOn ? 'var(--ui-primary)' : 'var(--ui-border-accented)', swBg: cOn ? 'var(--ui-primary)' : 'var(--ui-bg-accented)', knobL: cOn ? '17px' : '1px', knobBd: cOn ? 'transparent' : 'var(--ui-border-accented)', daysW: m ? '100%' : '140px', daysAlign: m ? 'stretch' : 'flex-end', daysBd: cErr ? 'var(--ui-error)' : C.focusDays ? 'var(--ui-primary)' : 'var(--ui-border-accented)', daysSh: C.focusDays && !cErr ? '0 0 0 1px var(--ui-primary)' : 'none', daysOp: cDis ? '0.4' : '1', daysVal: C.days ?? '30', hasErr: cErr, errTxt: C.invalid ? 'Enter a whole number of days between 1 and 365.' : 'Couldn\'t save. Try again in a moment.', errMax: m ? 'none' : '300px', errTA: m ? 'left' : 'right', lastLine: C.last ? 'Last purge: ' + C.last.d + ' · ' + C.last.c + ' copies merged · ' + C.last.a + ' articles updated' : 'Never run', nextLine: 'Next purge: ' + (C.next || '14 Jul 2026'), purgeOp: C.offline || C.loading ? '0.4' : '1', btnShrink: m ? '1' : '0' }
+		const R = s.ret || {}, rd = R.days || '90', fv = rd === '0', sz = R.size || '0', hs = sz !== '0'
+		const rt = { show: !s.noRet, saving: !!R.saving, saved: !!R.saved, err: !!R.err, shorten: !!R.shorten, val: { '30': '30 days', '90': '90 days', '365': '365 days', '0': 'Forever' }[R.shorten ? '30' : rd], help: fv ? (hs ? 'No age limit. Only the size limit applies.' : 'Nothing is removed automatically. The log grows over time.') : (hs ? 'Events older than this are removed.' : 'Older events are removed automatically.'), last: fv && !hs ? 'Last cleanup: Never' : 'Last cleanup: 6 Oct 2026, 03:00 · 142 events removed', next: fv && !hs ? 'Next cleanup: Not scheduled' : 'Next cleanup: 7 Oct 2026, 03:00', sizeVal: hs ? sz + ' GB' : 'No size limit', sizeHelp: hs ? 'When logs pass ' + sz + ' GB, the oldest events are removed. Currently 3.2 GB.' : 'Optional. Logs can grow without a size cap.', selW: m ? '100%' : '160px' }
+		const purgeDlg = (() => {
+			if (!s.purge) return null
+			const h = React.createElement, bh = m ? 44 : 32
+			const P = t => Object.fromEntries(t.split(';').filter(x => x.trim()).map(x => { const i = x.indexOf(':'); const k = x.slice(0, i).trim(); return [k.startsWith('--') ? k : k.replace(/-([a-z])/g, (_, c) => c.toUpperCase()), x.slice(i + 1).trim()] }))
+		const D = (t, ...c) => h('div', { style: P(t) }, ...c)
+		const S = (t, ...c) => h('span', { style: P(t) }, ...c)
+		const I = (n, z = 16, t = '') => h('span', { 'aria-hidden': 'true', style: { display: 'inline-block', flexShrink: 0, width: z, height: z, backgroundColor: 'currentColor', WebkitMask: 'url(https://api.iconify.design/lucide/' + n + '.svg) center / contain no-repeat', mask: 'url(https://api.iconify.design/lucide/' + n + '.svg) center / contain no-repeat', ...(t ? P(t) : {}) } })
+				const B = (label, o = {}) => {
+			const k = o.k || 'outline'
+			const bg = k === 'primary' ? 'var(--ui-primary)' : k === 'danger' ? 'var(--ui-error)' : 'var(--ui-bg)'
+			const fg = k === 'primary' || k === 'danger' ? 'var(--ui-bg)' : 'var(--ui-text-highlighted)'
+			const bd = k === 'primary' || k === 'danger' ? bg : 'var(--ui-border-accented)'
+			return S('height:' + (o.h || bh) + 'px;padding:0 ' + (o.px || 12) + 'px;display:flex;align-items:center;justify-content:center;gap:6px;background:' + bg + ';color:' + fg + ';border:1px solid ' + bd + ';font-weight:500;font-size:13px;white-space:nowrap;opacity:' + (o.dis ? 0.4 : 1) + ';' + (o.full ? 'flex:1;' : ''), o.icon && I(o.icon, 16), label)
+		}
+		const CHECK = 'conic-gradient(var(--ui-bg-accented) 25%, var(--ui-bg) 0 50%, var(--ui-bg-accented) 0 75%, var(--ui-bg) 0) 0 0/16px 16px'
+		const TONES = ['var(--rc-sand)', 'var(--ui-bg-accented)', 'color-mix(in srgb, var(--ui-border-accented) 35%, var(--ui-bg))', 'var(--ui-bg-elevated)']
+		const mark = h('svg', { width: 20, height: 20, viewBox: '0 0 16 16', shapeRendering: 'crispEdges' }, h('rect', { width: 16, height: 16, fill: '#111' }), h('path', { fill: '#fff', fillRule: 'evenodd', d: 'M4 3h6v1h1v1h1v3h-1v1h-1v1h1v1h1v2h-2v-2h-1v-1H6v3H4zm2 2v3h4V5z' }))
+		const Th = (im, t = '') => D('position:relative;overflow:hidden;display:flex;align-items:center;justify-content:center;color:var(--ui-text-muted);background:' + (im.alpha ? CHECK : 'repeating-linear-gradient(135deg, rgb(128 128 128 / 0.12) 0 1px, transparent 1px 12px), ' + TONES[im.tone % 4]) + ';' + t, im.svg ? mark : I('image', 16, 'opacity:0.55'))
+		const IMX = { 12: { tone: 0 }, 7: { tone: 2 }, 2: { tone: 1 }, 4: { tone: 3, alpha: true, svg: true }, 11: { tone: 1 } }
+		const Alert = (tone, icon, text, title) => D('display:flex;gap:10px;padding:12px 14px;background:var(--rc-' + tone + '-soft);color:var(--ui-' + tone + ')', S('display:flex;padding-top:2px', I(icon)), D('flex:1;display:flex;flex-direction:column;gap:2px', title && S('font-weight:600', title), S('color:var(--ui-text-toned)', text)))
+		const hl = 'color:var(--ui-text-highlighted)'
+		const mono = "font-family:'IBM Plex Mono',monospace"
+
+		const SkelBar = (w, hh = 13) => S('display:block;width:' + w + ';height:' + hh + 'px;background:var(--ui-bg-accented)')
+		// ---------- dialog
+		const G = [{ im: 12, n: 'floorboards.jpg', u: 4, c: 2 }, { im: 7, n: 'IMG_4471.jpg', u: 2, c: 1 }, { im: 2, n: 'kitchen-after.webp', u: 3, c: 3 }, { im: 4, n: 'logo-renew.svg', u: 5, c: 3 }, { im: 11, n: 'lime-plaster.jpg', u: 2, c: 1 }]
+		const pl = (n, w) => n + ' ' + w + (n === 1 ? '' : 's')
+		const PV = { groups: 4, copies: 9, arts: 12, list: G.slice(0, 4), more: 0, ...(s.purge && s.purge.pv) }
+		const summary = pv => pl(pv.groups, 'group') + ' · ' + pv.copies + (pv.copies === 1 ? ' copy' : ' copies') + ' will be deleted · ' + pl(pv.arts, 'article') + ' will be updated'
+		const GList = pv => D('border:1px solid var(--ui-border)', ...pv.list.map((g, i) => D('display:flex;align-items:center;gap:12px;padding:8px 12px;border-top:' + (i ? '1px solid var(--ui-border-muted)' : '0'), Th(IMX[g.im], 'width:40px;height:30px;flex-shrink:0;border:1px solid var(--ui-border)'), D('flex:1;min-width:0;display:flex;flex-direction:column', S('font-weight:500;' + hl + ';overflow:hidden;text-overflow:ellipsis;white-space:nowrap', g.n), S('font-size:12px;color:var(--ui-text-muted)', 'Kept · used in ' + pl(g.u, 'article'))), S('font-size:12px;color:var(--ui-text-toned);white-space:nowrap;text-align:right', pl(g.c, 'copy').replace('copys', 'copies') + ' merged'))), pv.more > 0 && D('padding:8px 12px;border-top:1px solid var(--ui-border-muted);color:var(--ui-text-muted)', 'and ' + pv.more + ' more groups'))
+		const Link = () => S('display:inline-flex;align-items:center;gap:4px;align-self:flex-start;font-weight:500;' + hl + ';text-decoration:underline;text-underline-offset:3px;min-height:' + (m ? 44 : 20) + 'px', 'Review in Duplicates', I('arrow-right', 14))
+		const dg = s.purge
+		const Shell = (o, body) => D('position:absolute;inset:0;z-index:50;background:var(--rc-overlay);display:flex;align-items:' + (m ? 'flex-end' : 'flex-start') + ';justify-content:center;padding:' + (m ? 16 : 140) + 'px 16px 16px',
+			D('width:' + (m ? '100%' : '448px') + ';max-height:100%;background:var(--ui-bg);box-shadow:var(--rc-shadow-modal);display:flex;flex-direction:column',
+				o.center ? D('padding:28px 24px 0;display:flex;flex-direction:column;align-items:center;gap:12px;text-align:center', S('width:44px;height:44px;display:flex;align-items:center;justify-content:center;background:var(--rc-info-soft);color:var(--ui-info)', I(o.icon, 20)), S('font:600 16px/24px \'IBM Plex Sans\',sans-serif;' + hl, o.title), S('color:var(--ui-text-muted);text-wrap:pretty;max-width:340px', o.desc))
+				: D('padding:20px 24px 0;display:flex;flex-direction:column;gap:4px', S('font:600 16px/24px \'IBM Plex Sans\',sans-serif;' + hl, o.title), o.desc && S('color:var(--ui-text-muted);text-wrap:pretty', o.desc)),
+				body && D('padding:20px 24px 0;display:flex;flex-direction:column;gap:16px;min-height:0;overflow:hidden', ...body),
+				D('padding:20px 24px;display:flex;flex-direction:' + (m ? 'column-reverse' : 'row') + ';justify-content:flex-end;gap:8px;flex-shrink:0', o.cancel && B(o.cancel, { dis: o.loading, full: false }), o.confirm && S('height:' + bh + 'px;padding:0 12px;display:flex;align-items:center;justify-content:center;gap:6px;background:var(--ui-error);color:var(--ui-bg);font-weight:500;opacity:' + (o.cdis ? 0.4 : 1), o.loading ? I('loader-circle') : o.cicon && I(o.cicon), o.confirm))))
+		const DESC = 'Articles that use a duplicate will be switched to the most used copy of that image, and the other copies will be deleted. This can\'t be undone.'
+		const DSkel = () => [SkelBar('80%', 16), D('border:1px solid var(--ui-border)', ...[0, 1, 2].map(i => D('display:flex;align-items:center;gap:12px;padding:8px 12px;border-top:' + (i ? '1px solid var(--ui-border-muted)' : '0'), SkelBar('40px', 30), D('flex:1;display:flex;flex-direction:column;gap:6px', SkelBar('45%'), SkelBar('60%', 11)))))]
+		const Dialog = () => {
+			const k = dg.k, pv = PV
+			const gp = 'Purge ' + pl(pv.groups, 'group')
+			const note = (tone, icon, t) => Alert(tone, icon, t)
+			if (k === 'loading') return Shell({ title: 'Purge duplicates?', desc: DESC, cancel: 'Cancel', confirm: 'Purge duplicates', cdis: true }, DSkel())
+			if (k === 'nothing') return Shell({ center: true, icon: 'copy', title: 'Nothing to purge', desc: 'No duplicate is used in an article, so there is nothing to merge.', cancel: 'Close' }, null)
+			const body = [S('font-weight:500;' + hl, summary(pv)), GList(pv), Link()]
+			if (k === 'confirm') return Shell({ title: 'Purge duplicates?', desc: DESC, cancel: 'Cancel', confirm: gp }, body)
+			if (k === 'progress') return Shell({ title: 'Purge duplicates?', desc: DESC, cancel: 'Cancel', confirm: 'Purging…', loading: true }, body)
+			if (k === 'error') return Shell({ title: 'Purge duplicates?', desc: DESC, cancel: 'Cancel', confirm: gp }, [note('error', 'circle-x', 'Couldn\'t purge the duplicates. Nothing was changed. Try again in a moment.'), ...body])
+			if (k === 'partial') return Shell({ title: 'Purge duplicates?', desc: DESC, cancel: 'Close', confirm: 'Retry', cicon: 'rotate-cw' }, [note('warning', 'triangle-alert', 'Some groups couldn\'t be merged. 3 of 4 groups were purged. Try again to finish.'), ...body])
+			if (k === 'conflict') return Shell({ title: 'Purge duplicates?', desc: DESC, cancel: 'Cancel', confirm: gp }, [note('warning', 'triangle-alert', 'The library changed, so nothing was purged. Check the new summary and try again.'), ...body])
+		}
+		
+			return Dialog()
+		})()
 		const toasts = (s.toasts || []).map(t => ({ ...t, fg: 'var(--ui-' + t.tone + ')' }))
 		const endpoints = [
 			{ path: '/v1/article/', desc: 'Lists every online article.', l1: 'var(--ui-primary)', code: "const res = await fetch('https://cms.renew.example/v1/article/')\nconst articles = await res.json()" },
@@ -434,7 +493,7 @@ class Component extends DCLogic {
 		const edReady = k === 'editor' && !e.loading && !e.notfound
 		const edTitle = e.title || 'How we price a bathroom renovation'
 		return {
-			cr, s, nav, crumbs, who, ini, pf, dn, dnSave, rsNote, rsBtn,
+			act, cl, rt, purgeDlg, rowDir: m ? 'column' : 'row', rowAlign: m ? 'stretch' : 'flex-start', rowJust: m ? 'flex-start' : 'space-between', rowGap: m ? '12px' : '16px', setScroll: -(s.scrollY || 0) + 'px', offText: s.offText || 'You\'re offline. You can keep writing, but saving and publishing will wait until you\'re back online.', cr, s, nav, crumbs, who, ini, pf, dn, dnSave, rsNote, rsBtn,
 			langSeg: [['en','English'],['fr','Français']].map(([k,tt])=>{const on=(s.lang||'en')===k;return {act:'lang-'+k,code:k,t:tt,on,op:on?1:0}}), themeSeg: [['system','monitor','System'],['light','sun','Light'],['dark','moon','Dark']].map(([k,icon,tt])=>{const on=(s.mode||'light')===k;return {act:'theme-'+k,icon,t:tt,on,op:on?1:0}}), menuOpen: !!s.userMenu, deskMenu: !m && !!s.userMenu, mobMenu: m && !!s.userMenu, pfItemBg: 'var(--ui-bg-elevated)',
 			chipBg: s.userMenu || s.nav === 'profile' ? 'var(--rc-sand)' : 'transparent', chipFg: s.userMenu || s.nav === 'profile' ? '#111111' : 'var(--ui-text-highlighted)',
 			isSettings: k === 'settings', isProfile: k === 'profile', pfLoading: k === 'profile' && !!pf.loading, pfReady: k === 'profile' && !pf.loading,
@@ -442,7 +501,7 @@ class Component extends DCLogic {
 			desk: !m, mob: m, notBoot: !s.boot,
 			fw: m ? '390px' : '1440px', fh: m ? '844px' : '900px', dir: m ? 'column' : 'row',
 			mLead: s.mLead || 'menu',
-			isBoot: !!s.boot, isHome: k === 'home' && !s.boot, isList: k === 'articles', isEditor: k === 'editor', isInteg: k === 'integration', isError: k === 'error', isUsers: k === 'users',
+			isBoot: !!s.boot, isHome: k === 'home' && !s.boot, isList: k === 'articles', isEditor: k === 'editor', isInteg: k === 'integration', isKeys: k === 'apikeys', isError: k === 'error', isUsers: k === 'users',
 			usRows, usError: !!US.error, usOnly: !!US.only && !US.error, usTable: !m && !US.error, usCards: m && !US.error,
 			pad: m ? '20px 16px 88px' : '32px', gap: m ? '20px' : '28px', cols3: m ? 'repeat(3,minmax(0,1fr))' : 'repeat(3,minmax(0,1fr))',
 			upBannerAlign: m ? 'stretch' : 'center', upCmdDir: m ? 'column' : 'row', btnH: m ? '44px' : '32px', rowH: m ? '52px' : '44px', inF: m ? '16px' : '14px',

docs/design/source/IntegrationPage.dc.html

@@ -0,0 +1,290 @@
+<!DOCTYPE html>
+<html>
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<script src="./support.js"></script>
+</head>
+<body>
+<x-dc>
+<div ref="{{ rootRef }}" onScroll="{{ onScroll }}" style="position:absolute;inset:0;overflow-y:auto;overflow-x:hidden;scrollbar-width:thin;background:var(--ui-bg-muted);color:var(--ui-text);font-family:'IBM Plex Sans',sans-serif;font-size:13px;line-height:20px">
+<sc-if value="{{ mob }}">
+<div style="position:sticky;top:0;z-index:5;background:var(--ui-bg);border-bottom:1px solid var(--ui-border);padding:8px 16px;display:flex;flex-direction:column;gap:4px">
+<button aria-haspopup="listbox" aria-expanded="{{ jumpOpen }}" aria-label="Jump to section" onClick="{{ toggleJump }}" style="all:unset;box-sizing:border-box;cursor:pointer;height:44px;padding:0 12px;display:flex;align-items:center;gap:8px;border:1px solid var(--ui-border-accented);background:var(--ui-bg);font-size:14px" style-focus-visible="outline:2px solid var(--ui-primary);outline-offset:2px"><span style="color:var(--ui-text-muted)">Jump to</span><span style="flex:1;font-weight:500;color:var(--ui-text-highlighted)">{{ activeLabel }}</span><span aria-hidden="true" style="display:inline-block;width:16px;height:16px;background-color:var(--ui-text-muted);-webkit-mask:url('https://api.iconify.design/lucide/chevrons-up-down.svg') center / contain no-repeat;mask:url('https://api.iconify.design/lucide/chevrons-up-down.svg') center / contain no-repeat"></span></button>
+<sc-if value="{{ jumpOpen }}"><div role="listbox" aria-label="Sections" style="position:absolute;left:16px;right:16px;top:56px;background:var(--ui-bg);border:1px solid var(--ui-border);box-shadow:var(--rc-shadow-pop);padding:4px">
+<sc-for list="{{ index }}" as="i" hint-placeholder-count="8"><button role="option" aria-selected="{{ i.on }}" onClick="{{ i.go }}" style="all:unset;box-sizing:border-box;cursor:pointer;width:100%;height:44px;padding:0 10px;display:flex;align-items:center;justify-content:space-between;font-size:14px;background:{{ i.bg }};color:var(--ui-text-highlighted);font-weight:{{ i.fw }}" style-focus-visible="outline:2px solid var(--ui-primary);outline-offset:-2px">{{ i.t }}<span aria-hidden="true" style="display:inline-block;width:16px;height:16px;background-color:currentColor;opacity:{{ i.op }};-webkit-mask:url('https://api.iconify.design/lucide/check.svg') center / contain no-repeat;mask:url('https://api.iconify.design/lucide/check.svg') center / contain no-repeat"></span></button></sc-for>
+</div></sc-if>
+</div>
+</sc-if>
+<div style="position:relative;padding:{{ pad }};display:flex;gap:40px;align-items:flex-start">
+<div style="flex:1;min-width:0;display:flex;flex-direction:column;gap:{{ secGap }}">
+
+<div style="display:flex;flex-direction:column;gap:6px">
+<span style="color:var(--ui-text-muted)">Integration</span>
+<span style="font:600 {{ h1 }} 'IBM Plex Sans',sans-serif;color:var(--ui-text-highlighted)">API reference</span>
+<span style="color:var(--ui-text-muted);font-size:14px;line-height:22px">Everything a developer needs to build on RenewCMS.</span>
+</div>
+<p style="margin:0;font-size:14px;line-height:22px;color:var(--ui-text-toned);text-wrap:pretty;max-width:720px">RenewCMS is headless: it stores your content and your own code displays it. There are two ways in. Public read-only access lets a website read online articles. API keys let a script or service manage articles, media and users without the back-office.</p>
+
+<div style="display:flex;flex-direction:column;gap:6px">
+<span style="font-weight:500;color:var(--ui-text-highlighted)">Base URL</span>
+<div style="display:flex;border:1px solid var(--ui-border-accented);background:var(--ui-bg)"><span style="flex:1;min-width:0;height:40px;padding:0 12px;display:flex;align-items:center;font:400 13px 'IBM Plex Mono',monospace;overflow:hidden;white-space:nowrap">https://cms.renew.example</span>
+<button aria-label="Copy base URL" onClick="{{ copyBase }}" style="all:unset;box-sizing:border-box;cursor:pointer;height:40px;padding:0 12px;display:flex;align-items:center;gap:6px;border-left:1px solid var(--ui-border-accented);font-weight:500;color:{{ baseCopy.fg }}" style-focus-visible="outline:2px solid var(--ui-primary);outline-offset:-2px"><span aria-hidden="true" style="display:inline-block;flex-shrink:0;width:14px;height:14px;background-color:currentColor;-webkit-mask:url('https://api.iconify.design/lucide/{{ baseCopy.icon }}.svg') center / contain no-repeat;mask:url('https://api.iconify.design/lucide/{{ baseCopy.icon }}.svg') center / contain no-repeat"></span><span aria-live="polite">{{ baseCopy.t }}</span></button></div>
+</div>
+
+<section data-anchor="auth" aria-labelledby="h-auth" style="display:flex;flex-direction:column;gap:14px">
+<h2 id="h-auth" style="margin:0;font:600 18px/26px 'IBM Plex Sans',sans-serif;color:var(--ui-text-highlighted)">Authentication</h2>
+<div style="display:grid;grid-template-columns:{{ authCols }};gap:12px;align-items:start">
+<div style="background:var(--ui-bg);border:1px solid var(--ui-border);padding:16px;display:flex;flex-direction:column;gap:10px">
+<div style="display:flex;align-items:center;gap:8px"><span style="font:600 15px/22px 'IBM Plex Sans',sans-serif;color:var(--ui-text-highlighted)">Public</span><span style="height:20px;padding:0 6px;display:inline-flex;align-items:center;border:1px solid var(--ui-border-accented);color:var(--ui-text-toned);font-size:12px">No key</span></div>
+<span style="color:var(--ui-text-toned);text-wrap:pretty">No key needed. Two read-only routes, and only online articles are returned.</span>
+<div style="display:flex;flex-direction:column;gap:6px;font:500 12px 'IBM Plex Mono',monospace;color:var(--ui-text-highlighted)"><span>GET /v1/article/</span><span>GET /v1/article/{id}</span></div>
+</div>
+<div style="background:var(--ui-bg);border:1px solid var(--ui-border);padding:16px;display:flex;flex-direction:column;gap:10px;min-width:0">
+<div style="display:flex;align-items:center;gap:8px"><span style="font:600 15px/22px 'IBM Plex Sans',sans-serif;color:var(--ui-text-highlighted)">API key</span><span style="height:20px;padding:0 6px;display:inline-flex;align-items:center;background:var(--rc-success-soft);color:var(--ui-success);font-size:12px;font-weight:500">Full access</span></div>
+<span style="color:var(--ui-text-toned);text-wrap:pretty">Send <code>Authorization: Bearer rcms_…</code>. Requests act as the user who created the key, with that user's role (owner or admin). A key never has more rights than its creator.</span>
+<div style="border:1px solid var(--ui-border);min-width:0">
+<div role="tablist" aria-label="Example language" style="display:flex;gap:16px;padding:0 12px;border-bottom:1px solid var(--ui-border)"><sc-for list="{{ authTabs }}" as="t" hint-placeholder-count="2"><button role="tab" aria-selected="{{ t.on }}" onClick="{{ t.pick }}" style="all:unset;box-sizing:border-box;cursor:pointer;height:36px;display:flex;align-items:center;border-bottom:2px solid {{ t.bd }};margin-bottom:-1px;font-weight:500;color:{{ t.fg }}" style-focus-visible="outline:2px solid var(--ui-primary);outline-offset:-2px">{{ t.t }}</button></sc-for></div>
+<div style="background:var(--ui-bg-elevated)"><div style="height:32px;padding:0 4px 0 12px;display:flex;align-items:center;justify-content:space-between;border-bottom:1px solid var(--ui-border)"><span style="font:500 12px 'IBM Plex Mono',monospace;color:var(--ui-text-muted)">{{ authLang }}</span><button aria-label="Copy example" onClick="{{ copyAuth }}" style="all:unset;box-sizing:border-box;cursor:pointer;height:28px;padding:0 8px;display:flex;align-items:center;gap:6px;font-weight:500;color:{{ authCopy.fg }}" style-focus-visible="outline:2px solid var(--ui-primary);outline-offset:-2px"><span aria-hidden="true" style="display:inline-block;width:14px;height:14px;background-color:currentColor;-webkit-mask:url('https://api.iconify.design/lucide/{{ authCopy.icon }}.svg') center / contain no-repeat;mask:url('https://api.iconify.design/lucide/{{ authCopy.icon }}.svg') center / contain no-repeat"></span><span aria-live="polite">{{ authCopy.t }}</span></button></div>
+<pre tabindex="0" style="margin:0;padding:12px;overflow-x:auto;font:400 12px/19px 'IBM Plex Mono',monospace;color:var(--ui-text)">{{ authCode }}</pre></div>
+</div>
+<span style="color:var(--ui-text-muted);text-wrap:pretty">Keys start with <code>rcms_</code> and are shown in full once, when you create them.</span>
+<a href="#" style="align-self:flex-start;display:inline-flex;align-items:center;gap:6px;min-height:{{ linkH }};font-weight:500;color:var(--ui-text-highlighted)" style-focus-visible="outline:2px solid var(--ui-primary);outline-offset:2px">Manage API keys<span aria-hidden="true" style="display:inline-block;width:14px;height:14px;background-color:currentColor;-webkit-mask:url('https://api.iconify.design/lucide/arrow-right.svg') center / contain no-repeat;mask:url('https://api.iconify.design/lucide/arrow-right.svg') center / contain no-repeat"></span></a>
+</div>
+</div>
+<div style="display:flex;flex-direction:column;gap:10px;font-size:14px;line-height:22px;color:var(--ui-text-toned)">
+<div style="display:flex;gap:10px"><span style="display:flex;padding-top:3px;color:var(--ui-info)"><span aria-hidden="true" style="display:inline-block;flex-shrink:0;width:16px;height:16px;background-color:currentColor;-webkit-mask:url('https://api.iconify.design/lucide/info.svg') center / contain no-repeat;mask:url('https://api.iconify.design/lucide/info.svg') center / contain no-repeat"></span></span><span style="text-wrap:pretty">A key can't create, list or revoke API keys, log in, register, verify or reset a password, or call anything under <code>/v1/system</code>. Those routes answer 403 "This action needs a real session." An invalid, unknown, expired or revoked key answers 401, even on public routes, and so does a key whose user was deleted or unverified.</span></div>
+<div style="display:flex;gap:10px"><span style="display:flex;padding-top:3px;color:var(--ui-info)"><span aria-hidden="true" style="display:inline-block;flex-shrink:0;width:16px;height:16px;background-color:currentColor;-webkit-mask:url('https://api.iconify.design/lucide/info.svg') center / contain no-repeat;mask:url('https://api.iconify.design/lucide/info.svg') center / contain no-repeat"></span></span><span style="text-wrap:pretty">Each key can make 120 requests per minute. Beyond that the API answers 429 with a <code>Retry-After</code> header.</span></div>
+</div>
+</section>
+
+<sc-for list="{{ groups }}" as="g" hint-placeholder-count="4">
+<section data-anchor="{{ g.key }}" style="display:flex;flex-direction:column;gap:10px">
+<div style="display:flex;align-items:baseline;gap:10px;flex-wrap:wrap"><h2 style="margin:0;font:600 18px/26px 'IBM Plex Sans',sans-serif;color:var(--ui-text-highlighted)">{{ g.title }}</h2><span style="color:var(--ui-text-muted)">{{ g.count }}</span></div>
+<span style="color:var(--ui-text-toned);text-wrap:pretty">{{ g.desc }}</span>
+<div style="border:1px solid var(--ui-border);border-top:0;background:var(--ui-bg)">
+<sc-for list="{{ g.eps }}" as="ep" hint-placeholder-count="6">
+<div data-anchor="{{ ep.anchor }}" style="border-top:1px solid var(--ui-border)">
+<button aria-expanded="{{ ep.open }}" aria-label="{{ ep.label }}" onClick="{{ ep.toggle }}" style="all:unset;box-sizing:border-box;cursor:pointer;width:100%;display:{{ rowDisplay }};grid-template-columns:{{ rowCols }};flex-direction:column;align-items:{{ rowAlign }};gap:{{ rowGap }};padding:{{ rowPad }};min-height:44px;background:{{ ep.rowBg }}" style-focus-visible="outline:2px solid var(--ui-primary);outline-offset:-2px">
+<span style="display:flex;align-items:center;gap:10px;min-width:0"><span style="width:56px;height:22px;flex-shrink:0;display:inline-flex;align-items:center;justify-content:center;background:{{ ep.mBg }};color:{{ ep.mFg }};border:1px solid {{ ep.mBd }};font:500 11px 'IBM Plex Mono',monospace">{{ ep.m }}</span><span style="min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;font:500 13px 'IBM Plex Mono',monospace;color:var(--ui-text-highlighted)">{{ ep.p }}</span><sc-if value="{{ mob }}"><span style="flex:1"></span><span aria-hidden="true" style="display:inline-block;flex-shrink:0;width:16px;height:16px;color:var(--ui-text-muted);background-color:currentColor;-webkit-mask:url('https://api.iconify.design/lucide/{{ ep.chev }}.svg') center / contain no-repeat;mask:url('https://api.iconify.design/lucide/{{ ep.chev }}.svg') center / contain no-repeat"></span></sc-if></span>
+<span style="min-width:0;color:var(--ui-text-toned);overflow:hidden;text-overflow:ellipsis;white-space:{{ descWrap }}">{{ ep.d }}</span>
+<span style="display:flex;gap:6px;flex-wrap:wrap;justify-content:flex-start"><sc-for list="{{ ep.chips }}" as="c" hint-placeholder-count="2"><span style="height:20px;padding:0 6px;display:inline-flex;align-items:center;gap:4px;white-space:nowrap;background:{{ c.bg }};color:{{ c.fg }};border:1px {{ c.bs }} {{ c.bd }};font-size:12px;font-weight:{{ c.fw }}"><sc-if value="{{ c.icon }}"><span aria-hidden="true" style="display:inline-block;width:12px;height:12px;background-color:currentColor;-webkit-mask:url('https://api.iconify.design/lucide/{{ c.icon }}.svg') center / contain no-repeat;mask:url('https://api.iconify.design/lucide/{{ c.icon }}.svg') center / contain no-repeat"></span></sc-if>{{ c.t }}</span></sc-for></span>
+<sc-if value="{{ desk }}"><span aria-hidden="true" style="display:inline-block;width:16px;height:16px;color:var(--ui-text-muted);background-color:currentColor;-webkit-mask:url('https://api.iconify.design/lucide/{{ ep.chev }}.svg') center / contain no-repeat;mask:url('https://api.iconify.design/lucide/{{ ep.chev }}.svg') center / contain no-repeat"></span></sc-if>
+</button>
+<sc-if value="{{ ep.open }}">
+<div style="padding:4px {{ detX }} 16px;display:flex;flex-direction:column;gap:14px;border-top:1px solid var(--ui-border-muted)">
+<div style="padding-top:10px;display:flex;flex-direction:column;gap:6px"><span style="font-weight:600;color:var(--ui-text-highlighted)">{{ ep.bodyTitle }}</span>
+<sc-if value="{{ ep.hasFields }}"><div style="border:1px solid var(--ui-border)">
+<div style="display:grid;grid-template-columns:{{ fCols }};gap:4px 12px;padding:6px 10px;background:var(--ui-bg-elevated);color:var(--ui-text-muted);font-weight:500"><span>Name</span><span>Type</span><span>Required</span><sc-if value="{{ desk }}"><span>Rule</span></sc-if></div>
+<sc-for list="{{ ep.fields }}" as="f" hint-placeholder-count="2"><div style="display:grid;grid-template-columns:{{ fCols }};gap:2px 12px;padding:8px 10px;border-top:1px solid var(--ui-border)"><span style="font:500 12px 'IBM Plex Mono',monospace;color:var(--ui-text-highlighted)">{{ f.n }}</span><span style="font:400 12px 'IBM Plex Mono',monospace;color:var(--ui-text-toned)">{{ f.t }}</span><span style="color:var(--ui-text-toned)">{{ f.req }}</span><span style="grid-column:{{ ruleCol }};color:var(--ui-text-toned);text-wrap:pretty">{{ f.rule }}</span></div></sc-for></div></sc-if>
+<sc-if value="{{ ep.noFields }}"><span style="color:var(--ui-text-muted)">No request body.</span></sc-if></div>
+<div style="border:1px solid var(--ui-border);min-width:0">
+<div role="tablist" aria-label="Example" style="display:flex;gap:16px;padding:0 12px;border-bottom:1px solid var(--ui-border)"><sc-for list="{{ ep.tabs }}" as="t" hint-placeholder-count="3"><button role="tab" aria-selected="{{ t.on }}" onClick="{{ t.pick }}" style="all:unset;box-sizing:border-box;cursor:pointer;height:{{ tabH }};display:flex;align-items:center;border-bottom:2px solid {{ t.bd }};margin-bottom:-1px;font-weight:500;color:{{ t.fg }}" style-focus-visible="outline:2px solid var(--ui-primary);outline-offset:-2px">{{ t.t }}</button></sc-for></div>
+<div style="background:var(--ui-bg-elevated)"><div style="height:32px;padding:0 4px 0 12px;display:flex;align-items:center;justify-content:space-between;border-bottom:1px solid var(--ui-border)"><span style="font:500 12px 'IBM Plex Mono',monospace;color:var(--ui-text-muted)">{{ ep.lang }}</span><button aria-label="{{ ep.copyLabel }}" onClick="{{ ep.copy }}" style="all:unset;box-sizing:border-box;cursor:pointer;height:28px;padding:0 8px;display:flex;align-items:center;gap:6px;font-weight:500;color:{{ ep.cFg }}" style-focus-visible="outline:2px solid var(--ui-primary);outline-offset:-2px"><span aria-hidden="true" style="display:inline-block;width:14px;height:14px;background-color:currentColor;-webkit-mask:url('https://api.iconify.design/lucide/{{ ep.cIcon }}.svg') center / contain no-repeat;mask:url('https://api.iconify.design/lucide/{{ ep.cIcon }}.svg') center / contain no-repeat"></span><span aria-live="polite">{{ ep.cT }}</span></button></div>
+<pre tabindex="0" style="margin:0;padding:12px;overflow-x:auto;font:400 12px/19px 'IBM Plex Mono',monospace;color:var(--ui-text)">{{ ep.code }}</pre></div>
+</div>
+<div style="display:flex;flex-direction:column;gap:6px"><span style="font-weight:600;color:var(--ui-text-highlighted)">Errors</span>
+<sc-for list="{{ ep.errs }}" as="e" hint-placeholder-count="2"><div title="{{ e.cap }}" style="display:flex;align-items:baseline;gap:10px"><span style="width:36px;height:20px;flex-shrink:0;display:inline-flex;align-items:center;justify-content:center;border:1px solid var(--ui-border-accented);color:var(--ui-text-toned);font:500 11px 'IBM Plex Mono',monospace">{{ e.c }}</span><span style="min-width:0;color:var(--ui-text-toned);text-wrap:pretty">{{ e.cap }}</span></div></sc-for></div>
+</div>
+</sc-if>
+</div>
+</sc-for>
+</div>
+</section>
+</sc-for>
+
+<section data-anchor="session" aria-labelledby="h-sess" style="display:flex;flex-direction:column;gap:10px">
+<div style="display:flex;align-items:baseline;gap:10px;flex-wrap:wrap"><h2 id="h-sess" style="margin:0;font:600 18px/26px 'IBM Plex Sans',sans-serif;color:var(--ui-text-highlighted)">Session only</h2><span style="color:var(--ui-text-muted)">12 routes, not available to API keys</span></div>
+<div style="background:var(--ui-bg-muted);border:1px dashed var(--ui-border-accented)">
+<div style="display:flex;gap:10px;padding:12px 14px;color:var(--ui-text-toned);text-wrap:pretty"><span style="display:flex;padding-top:2px;color:var(--ui-text-muted)"><span aria-hidden="true" style="display:inline-block;width:16px;height:16px;background-color:currentColor;-webkit-mask:url('https://api.iconify.design/lucide/lock.svg') center / contain no-repeat;mask:url('https://api.iconify.design/lucide/lock.svg') center / contain no-repeat"></span></span><span>These routes need a signed-in browser session. With an API key they answer 403 "This action needs a real session."</span></div>
+<sc-for list="{{ sessGroups }}" as="sg" hint-placeholder-count="3">
+<div style="border-top:1px dashed var(--ui-border-accented)">
+<div style="padding:8px 14px 4px;font-size:11px;font-weight:500;letter-spacing:.04em;text-transform:uppercase;color:var(--ui-text-muted)">{{ sg.t }}</div>
+<sc-for list="{{ sg.rows }}" as="r" hint-placeholder-count="4"><div style="display:{{ rowDisplay }};grid-template-columns:{{ sessCols }};flex-direction:column;align-items:{{ rowAlign }};gap:{{ sessGap }};padding:{{ sessPad }};min-height:36px"><span style="display:flex;align-items:center;gap:10px;min-width:0"><span style="width:56px;flex-shrink:0;font:500 11px 'IBM Plex Mono',monospace;color:var(--ui-text-muted)">{{ r.m }}</span><span style="min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;font:400 13px 'IBM Plex Mono',monospace;color:var(--ui-text-toned)">{{ r.p }}</span></span><span style="color:var(--ui-text-muted)">{{ r.d }}</span><span style="height:20px;padding:0 6px;display:inline-flex;align-items:center;gap:4px;align-self:{{ chipSelf }};border:1px dashed var(--ui-border-accented);color:var(--ui-text-muted);font-size:12px;white-space:nowrap"><span aria-hidden="true" style="display:inline-block;width:12px;height:12px;background-color:currentColor;-webkit-mask:url('https://api.iconify.design/lucide/lock.svg') center / contain no-repeat;mask:url('https://api.iconify.design/lucide/lock.svg') center / contain no-repeat"></span>Session only</span></div></sc-for>
+</div>
+</sc-for>
+</div>
+</section>
+
+<section data-anchor="errors" aria-labelledby="h-err" style="display:flex;flex-direction:column;gap:10px">
+<h2 id="h-err" style="margin:0;font:600 18px/26px 'IBM Plex Sans',sans-serif;color:var(--ui-text-highlighted)">Errors</h2>
+<span style="color:var(--ui-text-toned);text-wrap:pretty">Every error is a plain-text body with a single sentence. The status code is in the HTTP status line, and the Content-Type is text/plain.</span>
+<div style="border:1px solid var(--ui-border);background:var(--ui-bg);overflow:hidden">
+<div style="display:grid;grid-template-columns:{{ errCols }};gap:12px;padding:8px 12px;background:var(--ui-bg-elevated);color:var(--ui-text-muted);font-weight:500"><span>Status</span><span>Meaning</span><sc-if value="{{ desk }}"><span>Typical cause</span></sc-if></div>
+<sc-for list="{{ errRows }}" as="r" hint-placeholder-count="8"><div style="display:grid;grid-template-columns:{{ errCols }};gap:2px 12px;padding:10px 12px;border-top:1px solid var(--ui-border)"><span style="font:500 13px 'IBM Plex Mono',monospace;color:var(--ui-text-highlighted)">{{ r.c }}</span><span style="font-weight:500;color:var(--ui-text-highlighted)">{{ r.m }}</span><span style="grid-column:{{ errCause }};color:var(--ui-text-toned);text-wrap:pretty">{{ r.w }}</span></div></sc-for>
+</div>
+<div style="border:1px solid var(--ui-border);min-width:0"><div style="background:var(--ui-bg-elevated)"><div style="height:32px;padding:0 12px;display:flex;align-items:center;border-bottom:1px solid var(--ui-border);font:500 12px 'IBM Plex Mono',monospace;color:var(--ui-text-muted)">Error response · text/plain</div>
+<pre tabindex="0" style="margin:0;padding:12px;overflow-x:auto;font:400 12px/19px 'IBM Plex Mono',monospace;color:var(--ui-text)">{{ errBody }}</pre></div></div>
+</section>
+
+<section data-anchor="notes" aria-labelledby="h-notes" style="display:flex;flex-direction:column;gap:10px">
+<h2 id="h-notes" style="margin:0;font:600 18px/26px 'IBM Plex Sans',sans-serif;color:var(--ui-text-highlighted)">Notes</h2>
+<div style="display:flex;flex-direction:column;gap:10px;font-size:14px;line-height:22px;color:var(--ui-text-toned)">
+<div style="display:flex;gap:10px"><span style="display:flex;padding-top:3px;color:var(--ui-info)"><span aria-hidden="true" style="display:inline-block;flex-shrink:0;width:16px;height:16px;background-color:currentColor;-webkit-mask:url('https://api.iconify.design/lucide/info.svg') center / contain no-repeat;mask:url('https://api.iconify.design/lucide/info.svg') center / contain no-repeat"></span></span><span style="text-wrap:pretty">Images in <code>body</code> use paths like <code>/static/uploadedImages/&lt;uuid&gt;.png</code>. Prefix them with the base URL before rendering.</span></div>
+<div style="display:flex;gap:10px"><span style="display:flex;padding-top:3px;color:var(--ui-info)"><span aria-hidden="true" style="display:inline-block;flex-shrink:0;width:16px;height:16px;background-color:currentColor;-webkit-mask:url('https://api.iconify.design/lucide/info.svg') center / contain no-repeat;mask:url('https://api.iconify.design/lucide/info.svg') center / contain no-repeat"></span></span><span style="text-wrap:pretty">Browsers can only call the API from origins listed in the server's CORS setting. Ask whoever runs the server to add your site's address.</span></div>
+<div style="display:flex;gap:10px"><span style="display:flex;padding-top:3px;color:var(--ui-info)"><span aria-hidden="true" style="display:inline-block;flex-shrink:0;width:16px;height:16px;background-color:currentColor;-webkit-mask:url('https://api.iconify.design/lucide/info.svg') center / contain no-repeat;mask:url('https://api.iconify.design/lucide/info.svg') center / contain no-repeat"></span></span><span style="text-wrap:pretty">Article routes accept <code>?format=markdown</code>, <code>?format=html</code> or <code>?format=json</code> to choose how <code>body</code> is returned. With <code>json</code>, <code>body</code> is the stored JSON structure. Articles have <code>body_format: markdown</code> by default.</span></div>
+</div>
+</section>
+
+</div>
+<sc-if value="{{ desk }}">
+<nav aria-label="On this page" style="position:sticky;top:32px;width:168px;flex-shrink:0;display:flex;flex-direction:column;gap:2px;border-left:1px solid var(--ui-border)">
+<span style="padding:0 12px 6px;font-size:11px;font-weight:500;letter-spacing:.04em;text-transform:uppercase;color:var(--ui-text-muted)">On this page</span>
+<sc-for list="{{ index }}" as="i" hint-placeholder-count="8"><button aria-current="{{ i.cur }}" onClick="{{ i.go }}" style="all:unset;box-sizing:border-box;cursor:pointer;height:28px;padding:0 12px;margin-left:-1px;display:flex;align-items:center;border-left:2px solid {{ i.bd }};color:{{ i.fg }};font-weight:{{ i.fw }}" style-hover="color:var(--ui-text-highlighted)" style-focus-visible="outline:2px solid var(--ui-primary);outline-offset:-2px">{{ i.t }}</button></sc-for>
+</nav>
+</sc-if>
+</div>
+</div>
+</x-dc>
+<script type="text/x-dc" data-dc-script>
+class Component extends DCLogic {
+	state = (() => { const i = (this.props.s && this.props.s.int) || {}; return { open: i.open ? { [i.open]: true } : {}, tab: i.open ? { [i.open]: i.tab || 'fetch' } : {}, copied: i.copied || null, jump: !!i.jump, active: i.scroll === 'ep-' + i.open ? 'media' : (i.scroll || 'auth'), authTab: i.authTab || 'curl' } })()
+	rootRef = React.createRef()
+	BASE = 'https://cms.renew.example'
+	KEY = 'rcms_Kf3x9QwL0aBc…'
+	IDX = [['auth', 'Authentication'], ['articles', 'Articles'], ['media', 'Media'], ['users', 'Users and invites'], ['settings', 'Settings'], ['session', 'Session only'], ['errors', 'Errors'], ['notes', 'Notes']]
+	componentDidMount() {
+		const i = (this.props.s && this.props.s.int) || {}
+		const go = () => { if (i.scroll) this.scrollTo(i.scroll, !!this.props.mobile) }
+		go(); setTimeout(go, 250); setTimeout(go, 900)
+		if (document.fonts && document.fonts.ready) document.fonts.ready.then(go)
+	}
+	scrollTo(a, mob) {
+		const r = this.rootRef.current; if (!r) return
+		const el = r.querySelector('[data-anchor="' + a + '"]'); if (!el) return
+		const off = a.indexOf('ep-') === 0 ? 24 : 0
+		r.scrollTop = Math.max(0, this.yOf(el, r) - (mob ? 64 : 32) - off)
+	}
+	yOf(el, r) { const w = el.offsetParent; return el.offsetTop + (w && w !== r ? w.offsetTop : 0) }
+	onScroll = () => {
+		const r = this.rootRef.current; if (!r) return
+		let cur = this.IDX[0][0]
+		for (const [k] of this.IDX) { const el = r.querySelector('[data-anchor="' + k + '"]'); if (el && this.yOf(el, r) <= r.scrollTop + 120) cur = k }
+		if (cur !== this.state.active) this.setState({ active: cur })
+	}
+	flash(k) {
+		this.setState({ copied: k }); clearTimeout(this._t); this._t = setTimeout(() => this.setState({ copied: null }), 2000)
+	}
+	hl(code) {
+		const re = /("[^"\n]*"|'[^'\n]*')|\b(const|await|fetch|curl|new)\b|\b(\d+)\b/g
+		const out = []; let last = 0, m, k = 0
+		while ((m = re.exec(code))) {
+			if (m.index > last) out.push(code.slice(last, m.index))
+			const c = m[1] ? 'var(--ui-success)' : m[2] ? 'var(--ui-info)' : 'var(--ui-warning)'
+			out.push(React.createElement('span', { key: k++, style: { color: c } }, m[0])); last = m.index + m[0].length
+		}
+		out.push(code.slice(last)); return out
+	}
+	eps() {
+		const A = (id, m, p, d, acc, key, errs, fields, x = {}) => ({ id, m, p, d, acc, key, errs: acc === 'Verified user' ? errs.flatMap(e => e[0] === 401 ? [e, e403] : [e]) : errs, fields, ...x })
+		const S = (n, t, req, rule) => ({ n, t, req, rule })
+		const e401 = [401, 'You must be logged in to access this resource.']
+		const e403 = [403, 'You must verify your account to access this resource.']
+		const e404 = [404, 'Article not found']
+		const m404 = [404, 'Image not found']
+		const i404 = [404, 'Invite not found']
+		const mm = 'The request cannot be processed due to a mismatch in the format of the body.'
+		const j = o => JSON.stringify(o, null, 2)
+		const G = {
+			articles: { title: 'Articles', desc: 'Read, write and publish articles. Titles can\'t be changed after creation.', eps: [
+				A('art-list', 'GET', '/v1/article/', 'List articles. Anonymous callers get online articles only.', 'Public', 1, [e401], [], { pub: 1, r: j([{ id: 12, title: 'How we price a bathroom renovation', status: 'online' }]) }),
+				A('art-get', 'GET', '/v1/article/{id}', 'Get one article. Drafts answer 404 to anonymous callers.', 'Public', 1, [e401, e404], [], { pub: 1, r: j({ id: 12, title: 'How we price a bathroom renovation', status: 'online', body: 'A bathroom renovation is priced by room size, plumbing changes and finish level.', body_format: 'markdown' }) }),
+				A('art-create', 'POST', '/v1/article/', 'Create a draft article.', 'Verified user', 1, [[400, mm], e401], [S('title', 'string', 'Yes', '3 to 200 characters. Can\'t be changed later.'), S('body', 'string', 'Yes', 'Up to 10 000 characters.')], { body: { title: 'Choosing tiles for a small bathroom', body: 'Small rooms show every grout line.' }, r: j({ id: 13, status: 'draft' }) }),
+				A('art-update', 'PATCH', '/v1/article/{id}', 'Update the body of an article.', 'Verified user', 1, [[400, mm], e401, e404], [S('body', 'string', 'Yes', 'Up to 10 000 characters.')], { body: { body: 'Updated text.' }, r: j({ id: 12, status: 'draft' }) }),
+				A('art-pub', 'PATCH', '/v1/article/{id}/publish', 'Publish an article.', 'Verified user', 1, [e401, e404], [], { r: j({ id: 12, status: 'online' }) }),
+				A('art-unpub', 'PATCH', '/v1/article/{id}/unpublish', 'Unpublish an article.', 'Verified user', 1, [e401, e404], [], { r: j({ id: 12, status: 'draft' }) }),
+				A('art-del', 'DELETE', '/v1/article/{id}', 'Delete an article and its images.', 'Verified user', 1, [e401, e404], [], { r: '204 No Content' })
+			] },
+			media: { title: 'Media', desc: 'The image library. One image can be used in many articles.', eps: [
+				A('med-list', 'GET', '/v1/media/', 'List images.', 'Verified user', 1, [e401], [], { r: j([{ id: 4, filename: 'north-wall.jpg', size: 3900000 }]) }),
+				A('med-up', 'POST', '/v1/media/', 'Upload an image (multipart).', 'Verified user', 1, [[400, mm], e401, [413, 'The file is over 10 MB.'], [415, 'Not a PNG, JPEG, WEBP or SVG image.']], [S('file', 'file', 'Yes', 'PNG, JPEG, WEBP or SVG, up to 10 MB.')], { multi: true, form: [['file', '@north-wall.jpg']], r: j({ id: 4, filename: 'north-wall.jpg', url: '/static/uploadedImages/3f9c.jpg' }) }),
+				A('med-ren', 'PATCH', '/v1/media/{id}', 'Rename an image. The URL stays the same.', 'Verified user', 1, [[400, mm], e401, m404], [S('filename', 'string', 'Yes', 'The new filename.')], { body: { filename: 'north-wall-01.jpg' }, r: j({ id: 4, filename: 'north-wall-01.jpg' }) }),
+				A('med-del', 'DELETE', '/v1/media/{id}', 'Delete an image. Articles that use it show a broken image.', 'Verified user', 1, [e401, m404], [], { r: '204 No Content' }),
+				A('med-merge', 'POST', '/v1/media/merge', 'Merge identical copies into one image.', 'Verified user', 1, [[400, mm], e401, [409, 'Some of the images to merge changed. Refresh and try again.']], [S('keep_id', 'number', 'Yes', 'Greater than 0. The image to keep.'), S('merge_ids', 'number[]', 'Yes', 'At least 1, each greater than 0. Identical copies to delete. Articles switch to the kept image.')], { body: { keep_id: 4, merge_ids: [9, 11] }, r: j({ merged: 2, articlesUpdated: 5 }) }),
+				A('med-use', 'GET', '/v1/media/{id}/usage', 'List the articles that use an image.', 'Verified user', 1, [e401, m404], [], { r: j([{ id: 12, title: 'How we price a bathroom renovation', status: 'online' }]) })
+			] },
+			users: { title: 'Users and invites', desc: 'People who can sign in, and pending invitations.', eps: [
+				A('usr-list', 'GET', '/v1/user/', 'List users and invites.', 'Verified user', 1, [e401], [], { r: j([{ email: 'marta@renew.example', role: 'owner', status: 'accepted' }]) }),
+				A('usr-me', 'PATCH', '/v1/user/me', 'Update my profile.', 'Verified user', 1, [[400, mm], e401], [S('display_name', 'string', 'Yes', 'Up to 60 characters.')], { body: { display_name: 'Marta Alves' }, r: j({ display_name: 'Marta Alves' }) }),
+				A('usr-inv', 'POST', '/v1/user/invite', 'Invite a user by email.', 'Verified user', 1, [[400, mm], e401, [409, 'This address already has an account.']], [S('email', 'string', 'Yes', 'A valid email address. The link expires after 3 days.')], { body: { email: 'lea.martin@renew.example' }, r: j({ id: 7, status: 'pending' }) }),
+				A('usr-cancel', 'DELETE', '/v1/user/invite/{id}', 'Cancel a pending invite.', 'Verified user', 1, [e401, i404], [], { r: '204 No Content' }),
+				A('usr-renew', 'POST', '/v1/user/invite/{id}/renew', 'Renew an expired invite.', 'Verified user', 1, [e401, i404], [], { r: j({ id: 7, status: 'pending' }) }),
+				A('auth-me', 'GET', '/v1/auth/me', 'Get the current user. With a key, the key\'s owner.', 'Verified user', 1, [e401], [], { r: j({ username: 'marta', email: 'marta@renew.example', role: 'owner' }) })
+			] },
+			settings: { title: 'Settings', desc: 'Read the site settings.', eps: [
+				A('set-get', 'GET', '/v1/settings', 'Get settings.', 'Verified user', 1, [e401], [], { r: j({ version: 'v2.2.0-beta' }) })
+			] }
+		}
+		const MB = { GET: ['var(--ui-bg-inverted)', 'var(--ui-text-inverted)', 'var(--ui-bg-inverted)'], POST: ['var(--rc-success-soft)', 'var(--ui-success)', 'var(--ui-success)'], PATCH: ['var(--rc-warning-soft)', 'var(--ui-warning)', 'var(--ui-warning)'], DELETE: ['var(--rc-error-soft)', 'var(--ui-error)', 'var(--ui-error)'] }
+		const mob = !!this.props.mobile
+		return Object.keys(G).map(key => {
+			const g = G[key]
+			return { key, title: g.title, desc: g.desc, count: g.eps.length + (g.eps.length === 1 ? ' route' : ' routes'), eps: g.eps.map(e => {
+				const open = !!this.state.open[e.id], tab = this.state.tab[e.id] || 'fetch', url = this.BASE + e.p.replace('{id}', '12')
+				const hdr = e.pub ? [] : ['Authorization: Bearer ' + this.KEY]
+				let curl = 'curl ' + (e.m === 'GET' ? '' : '-X ' + e.m + ' ') + '"' + url + '"'
+				hdr.forEach(h => curl += ' \\\n  -H "' + h + '"')
+				if (e.body) curl += ' \\\n  -H "Content-Type: application/json" \\\n  -d \'' + JSON.stringify(e.body) + '\''
+				if (e.form) e.form.forEach(f => curl += ' \\\n  -F "' + f[0] + '=' + f[1] + '"')
+				let fe = (e.form ? 'const form = new FormData()\n' + e.form.map(f => f[1][0] === '@' ? "form.append('file', file)" : "form.append('" + f[0] + "', '" + f[1] + "')").join('\n') + '\n\n' : '') + "const res = await fetch('" + url + "'"
+				const opts = []
+				if (e.m !== 'GET') opts.push("method: '" + e.m + "'")
+				if (hdr.length || e.body) opts.push('headers: { ' + [hdr.length ? "Authorization: 'Bearer " + this.KEY + "'" : null, e.body ? "'Content-Type': 'application/json'" : null].filter(Boolean).join(', ') + ' }')
+				if (e.body) opts.push('body: JSON.stringify(' + JSON.stringify(e.body) + ')')
+				if (e.form) opts.push('body: form')
+				fe += opts.length ? ', {\n  ' + opts.join(',\n  ') + '\n})' : ')'
+				const code = tab === 'curl' ? curl : tab === 'fetch' ? fe : e.r
+				const lang = tab === 'curl' ? 'Shell' : tab === 'fetch' ? 'JavaScript' : 'JSON'
+				const cp = this.state.copied === e.id
+				const chip = (t, o) => ({ t, bg: 'transparent', fg: 'var(--ui-text-toned)', bd: 'var(--ui-border-accented)', bs: 'solid', fw: 400, ...o })
+				const chips = [chip(e.acc, e.acc === 'Owner only' ? { bg: 'var(--ui-bg-elevated)', fg: 'var(--ui-text-highlighted)', fw: 500 } : {}), chip('API key OK', { icon: 'check', bg: 'var(--rc-success-soft)', fg: 'var(--ui-success)', bd: 'transparent', fw: 500 })]
+				return { anchor: 'ep-' + e.id, open, m: e.m, p: e.p, d: e.d, mBg: MB[e.m][0], mFg: MB[e.m][1], mBd: MB[e.m][2], chev: open ? 'chevron-up' : 'chevron-down', rowBg: open ? 'var(--ui-bg-muted)' : 'transparent', label: e.m + ' ' + e.p + '. ' + e.d, chips,
+					toggle: () => this.setState(s => ({ open: { ...s.open, [e.id]: !s.open[e.id] } })),
+					bodyTitle: e.multi ? 'Request body · multipart/form-data, 1 file field' : e.body ? 'Request body · JSON' : 'Request body', hasFields: e.fields.length > 0, noFields: e.fields.length === 0, fields: e.fields,
+					tabs: ['fetch', 'curl', 'Response'].map(t => { const k = t === 'Response' ? 'response' : t, on = (k === tab) || (t === tab); return { t, on, bd: on ? 'var(--ui-primary)' : 'transparent', fg: on ? 'var(--ui-text-highlighted)' : 'var(--ui-text-toned)', pick: () => this.setState(s => ({ tab: { ...s.tab, [e.id]: k } })) } }),
+					lang, code: this.hl(code), copyLabel: 'Copy ' + lang + ' example', cT: cp ? 'Copied' : 'Copy', cIcon: cp ? 'check' : 'copy', cFg: cp ? 'var(--ui-success)' : 'var(--ui-text-toned)',
+					copy: () => { try { navigator.clipboard && navigator.clipboard.writeText(code) } catch (x) { } this.flash(e.id) },
+					errs: e.errs.map(([c, cap]) => ({ c, cap })) }
+			}) }
+		})
+	}
+	renderVals() {
+		const mob = !!this.props.mobile, st = this.state
+		const code = {
+			curl: 'curl "' + this.BASE + '/v1/auth/me" \\\n  -H "Authorization: Bearer ' + this.KEY + '"',
+			fetch: "const res = await fetch('" + this.BASE + "/v1/auth/me', {\n  headers: { Authorization: 'Bearer " + this.KEY + "' }\n})\nconst me = await res.json()"
+		}[st.authTab]
+		const cp = k => ({ t: st.copied === k ? 'Copied' : 'Copy', icon: st.copied === k ? 'check' : 'copy', fg: st.copied === k ? 'var(--ui-success)' : 'var(--ui-text-toned)' })
+		const bc = cp('base'); if (st.copied !== 'base') bc.fg = 'var(--ui-text-highlighted)'
+		const index = this.IDX.map(([k, t]) => { const on = st.active === k; return { t, on, cur: on ? 'true' : undefined, bd: on ? 'var(--ui-primary)' : 'transparent', fg: on ? 'var(--ui-text-highlighted)' : 'var(--ui-text-toned)', fw: on ? 500 : 400, bg: on ? 'var(--ui-bg-elevated)' : 'transparent', op: on ? 1 : 0, go: () => { this.setState({ jump: false, active: k }); this.scrollTo(k, mob) } } })
+		const sg = (t, rows) => ({ t, rows: rows.map(([m, p, d]) => ({ m, p, d })) })
+		const D = (a) => 'rowDisplay'
+		return {
+			rootRef: this.rootRef, onScroll: this.onScroll, mob, desk: !mob, jumpOpen: st.jump, toggleJump: () => this.setState(s => ({ jump: !s.jump })),
+			activeLabel: (this.IDX.find(x => x[0] === st.active) || this.IDX[0])[1], index,
+			pad: mob ? '20px 16px 96px' : '32px', secGap: mob ? '28px' : '32px', h1: mob ? '20px/28px' : '28px/36px', detX: mob ? '12px' : '16px', linkH: mob ? '44px' : '28px', tabH: mob ? '44px' : '36px',
+			authCols: mob ? 'minmax(0,1fr)' : 'minmax(0,5fr) minmax(0,7fr)',
+			baseCopy: bc, copyBase: () => { try { navigator.clipboard && navigator.clipboard.writeText(this.BASE) } catch (x) { } this.flash('base') },
+			authTabs: ['curl', 'fetch'].map(t => { const on = st.authTab === t; return { t, on, bd: on ? 'var(--ui-primary)' : 'transparent', fg: on ? 'var(--ui-text-highlighted)' : 'var(--ui-text-toned)', pick: () => this.setState({ authTab: t }) } }),
+			authLang: st.authTab === 'curl' ? 'Shell' : 'JavaScript', authCode: this.hl(code), authCopy: cp('auth'), copyAuth: () => { try { navigator.clipboard && navigator.clipboard.writeText(code) } catch (x) { } this.flash('auth') },
+			groups: this.eps(),
+			rowDisplay: mob ? 'flex' : 'grid', rowCols: mob ? 'none' : '300px minmax(0,1fr) auto 16px', rowAlign: mob ? 'stretch' : 'center', rowGap: mob ? '6px' : '16px', rowPad: mob ? '12px 12px' : '0 16px', descWrap: mob ? 'normal' : 'nowrap',
+			fCols: mob ? 'minmax(0,1fr) auto auto' : '120px 72px 72px minmax(0,1fr)', ruleCol: mob ? '1 / -1' : 'auto',
+			sessGroups: [sg('System · owner only', [['GET', '/v1/system/update', 'Update status'], ['POST', '/v1/system/update/check', 'Check for update'], ['POST', '/v1/system/update/download', 'Download update'], ['POST', '/v1/system/update/restart', 'Restart']]), sg('Sign in and account', [['POST', '/v1/auth/login', 'Log in'], ['POST', '/v1/auth/logout', 'Log out'], ['POST', '/v1/auth/register', 'Register'], ['POST', '/v1/auth/verify', 'Verify email'], ['POST', '/v1/auth/password-reset', 'Reset password']]), sg('API key management', [['GET', '/v1/api-key', 'List keys'], ['POST', '/v1/api-key', 'Create a key'], ['DELETE', '/v1/api-key/{id}', 'Revoke a key']])],
+			sessCols: mob ? 'none' : '280px minmax(0,1fr) auto', sessGap: mob ? '2px' : '16px', sessPad: mob ? '8px 14px' : '0 14px', chipSelf: mob ? 'flex-start' : 'center',
+			errCols: mob ? '56px minmax(0,1fr)' : '64px 200px minmax(0,1fr)', errCause: mob ? '2' : 'auto',
+			errRows: [
+				{ c: 400, m: 'Bad request', w: '"The request cannot be processed due to a mismatch in the format of the body." or "The expiry must be a date in the future."' },
+				{ c: 401, m: 'Unauthorized', w: '"You must be logged in to access this resource." Sent for an invalid, unknown, expired or revoked key, even on public routes, and for a key whose user was deleted or unverified.' },
+				{ c: 403, m: 'Forbidden', w: '"This action needs a real session." (a session-only route called with a key), "Only the owner can do this." or "You must verify your account to access this resource."' },
+				{ c: 404, m: 'Not found', w: '"Article not found", "Image not found", "Invite not found" or "API key not found". Drafts answer 404 to anonymous callers.' },
+				{ c: 429, m: 'Too many requests', w: '"Too many requests. Please try again later." A per-key limit of 120 requests per minute also sends a Retry-After header.' },
+				{ c: 500, m: 'Server error', w: '"Internal server error"' }
+			],
+			errBody: 'HTTP/1.1 403 Forbidden\nContent-Type: text/plain\n\nThis action needs a real session.'
+		}
+	}
+}
+</script>
+</body>
+</html>

docs/design/source/MediaFrame.dc.html

@@ -144,9 +144,10 @@ class Component extends DCLogic {
 			if (s.empty === 'first') { parts.push(Empty('images', 'No images yet', 'Upload your first image. You can use it in any article.', 'Upload an image', true), S('align-self:center;color:var(--ui-text-muted);font-size:12px', 'PNG, JPEG, WEBP, SVG · max 10 MB each')); return parts }
 			if (s.limited) parts.push(Alert('info', 'timer', 'Too many uploads', 'For your security, wait a moment before uploading again.'))
 			if (s.error) parts.push(Alert('error', 'circle-x', 'Couldn\'t load your images', 'Check your connection and try again.', 'Try again'))
+			const pb = tab === 'dups' && !s.member && !s.dupEmpty && B('Purge duplicates', { icon: 'merge', dis: s.offline, full: m })
 			const tb = m
-				? D('display:flex;flex-direction:column;gap:12px', Search(), TabRow(), D('display:flex;gap:8px', Sort(), Toggle()))
-				: D('display:flex;align-items:flex-end;gap:12px;border-bottom:1px solid var(--ui-border)', TabRow(), S('display:flex;padding-bottom:6px;gap:8px', Search(), Sort(), Toggle()))
+				? D('display:flex;flex-direction:column;gap:12px', Search(), TabRow(), D('display:flex;gap:8px', Sort(), Toggle()), pb && D('display:flex', pb))
+				: D('display:flex;align-items:flex-end;gap:12px;border-bottom:1px solid var(--ui-border)', TabRow(), S('display:flex;padding-bottom:6px;gap:8px', Search(), Sort(), pb, Toggle()))
 			parts.push(tb)
 			if (UP) parts.push(UpPanel())
 			if (s.loading) parts.push(Skel())
@@ -189,6 +190,7 @@ class Component extends DCLogic {
 			if (k === 'delUsed') return { title: 'Delete an image that\'s in use?', desc: '"north-wall.jpg" is used in 2 articles. If you delete it, they will show a broken image. This can\'t be undone.', body: [ArtBox(usedList(2))], cancel: 'Cancel', confirm: md.loading ? 'Deleting…' : 'Delete image', tone: 'danger' }
 			if (k === 'bulk') return { title: 'Delete 3 images?', desc: '2 of them are used in 5 articles, which will show a broken image. The other one isn\'t used anywhere. This can\'t be undone.', body: [D('display:flex;flex-direction:column;border:1px solid var(--ui-border)', ...[['north-wall.jpg', 'Used in 2'], ['kitchen-after.webp', 'Used in 3'], ['window-frame.jpg', 'Unused']].map(([n, u], i) => D('display:flex;align-items:center;gap:8px;min-height:36px;padding:0 12px;border-top:' + (i ? '1px solid var(--ui-border-muted)' : '0'), S('flex:1;color:var(--ui-text-highlighted);overflow:hidden;text-overflow:ellipsis;white-space:nowrap', n), Bd(u === 'Unused' ? 'Unused' : u, u === 'Unused' ? 'unused' : 'used'))))], cancel: 'Cancel', confirm: md.loading ? 'Deleting…' : 'Delete 3 images', tone: 'danger' }
 			if (k === 'merge') return { title: 'Merge into floorboards.jpg?', desc: 'Articles that use the other 2 copies will be switched to floorboards.jpg, and the other 2 copies will be deleted. 5 articles will be updated. This can\'t be undone.', body: [D('display:flex;gap:12px;align-items:center;border:1px solid var(--ui-border);padding:10px 12px', Th(byId(12), 'width:56px;height:42px;flex-shrink:0;border:1px solid var(--ui-border)', 16), D('display:flex;flex-direction:column;min-width:0', S('font-weight:500;color:var(--ui-text-highlighted)', 'floorboards.jpg'), S('font-size:12px;color:var(--ui-text-muted)', 'Kept · used in 4 articles now')))], cancel: 'Cancel', confirm: md.loading ? 'Merging…' : 'Merge 2 copies', tone: 'danger' }
+			if (k === 'purge') return { title: 'Purge duplicates?', desc: 'Articles that use a duplicate will be switched to the most used copy of that image, and the other copies will be deleted. This can\'t be undone.', body: [S('font-weight:500;color:var(--ui-text-highlighted)', '4 groups · 9 copies will be deleted · 12 articles will be updated'), D('border:1px solid var(--ui-border)', ...[[12, 'floorboards.jpg', 4, '2 copies'], [7, 'IMG_4471.jpg', 2, '1 copy'], [2, 'kitchen-after.webp', 3, '3 copies'], [4, 'logo-renew.svg', 5, '3 copies']].map(([id, n, u, c], i) => D('display:flex;align-items:center;gap:12px;padding:8px 12px;border-top:' + (i ? '1px solid var(--ui-border-muted)' : '0'), Th(byId(id), 'width:40px;height:30px;flex-shrink:0;border:1px solid var(--ui-border)', 16), D('flex:1;min-width:0;display:flex;flex-direction:column', S('font-weight:500;color:var(--ui-text-highlighted);overflow:hidden;text-overflow:ellipsis;white-space:nowrap', n), S('font-size:12px;color:var(--ui-text-muted)', 'Kept · used in ' + pl(u))), S('font-size:12px;color:var(--ui-text-toned);white-space:nowrap', c + ' merged')))), S('display:inline-flex;align-items:center;gap:4px;align-self:flex-start;font-weight:500;color:var(--ui-text-highlighted);text-decoration:underline;text-underline-offset:3px;min-height:' + (m ? 44 : 20) + 'px', 'Review in Duplicates', I('arrow-right', 14))], cancel: 'Cancel', confirm: 'Purge 4 groups', tone: 'danger' }
 			if (k === 'remove') return { title: 'Remove this image from the article?', desc: 'It\'s removed from this article only. The file stays in your library and in any other article that uses it.', body: [D('display:flex;gap:12px;align-items:center;border:1px solid var(--ui-border);padding:10px 12px', Th(byId(1), 'width:56px;height:42px;flex-shrink:0;border:1px solid var(--ui-border)', 16), D('display:flex;flex-direction:column;min-width:0', S('font-weight:500;color:var(--ui-text-highlighted)', 'north-wall.jpg'), S('font-size:12px;color:var(--ui-text-muted)', 'Stays in the library · 3.9 MB')))], cancel: 'Cancel', confirm: 'Remove image' }
 		}
 		const Shell = (o, body) => D('position:absolute;inset:0;z-index:50;background:var(--rc-overlay);display:flex;align-items:' + (m ? 'flex-end' : 'flex-start') + ';justify-content:center;padding:' + (m ? 16 : o.top || 140) + 'px 16px 16px',

docs/design/source/RenewCMS Screens API keys.dc.html

@@ -0,0 +1,106 @@
+<!DOCTYPE html>
+<html>
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<script src="./support.js"></script>
+</head>
+<body>
+<x-dc>
+<helmet>
+<meta name="design_doc_mode" content="canvas">
+<link rel="icon" href="brand/favicon.svg">
+<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Sans:wght@400;500;600&family=IBM+Plex+Mono:wght@400;500&family=Source+Serif+4:ital,opsz,wght@0,8..60,400;0,8..60,600;1,8..60,400&display=swap" rel="stylesheet">
+<style>body{margin:0;font-family:'IBM Plex Sans',sans-serif;font-size:13px;line-height:20px}*{box-sizing:border-box}a{color:inherit;text-underline-offset:3px}a:hover{opacity:.8}code{font-family:'IBM Plex Mono',monospace;font-size:12px}</style>
+</helmet>
+<div ref="{{ rootRef }}" data-screen-label="Back-office screens" style="--ui-bg:#ffffff;--ui-bg-muted:#fafafa;--ui-bg-elevated:#f3f2f0;--ui-bg-accented:#e6e4e0;--ui-bg-inverted:#111111;--ui-text-dimmed:#999999;--ui-text-muted:#666666;--ui-text-toned:#444444;--ui-text:#222222;--ui-text-highlighted:#111111;--ui-text-inverted:#ffffff;--ui-border:#e6e4e0;--ui-border-muted:#f3f2f0;--ui-border-accented:#8a8783;--ui-primary:#111111;--ui-secondary:#635643;--ui-success:#315b33;--ui-info:#34536d;--ui-warning:#6c4700;--ui-error:#882c21;--rc-sand:#e8dfd1;--rc-success-soft:#eaefea;--rc-info-soft:#ebeef0;--rc-warning-soft:#f0ede6;--rc-error-soft:#f3eae9;--rc-overlay:rgb(10 10 10 / 0.4);--rc-shadow-pop:0 4px 16px rgb(17 17 17 / 0.08), 0 1px 2px rgb(17 17 17 / 0.06);--rc-shadow-modal:0 16px 48px rgb(17 17 17 / 0.18);--rc-canvas:#ecebe8;background:var(--rc-canvas);color:var(--ui-text);padding:64px;display:flex;flex-direction:column;gap:72px;width:max-content;min-width:100%">
+
+<div style="display:flex;align-items:flex-end;gap:32px;max-width:1400px">
+<div style="flex:1;display:flex;flex-direction:column;gap:10px">
+<h1 style="margin:0;font:600 36px/44px 'IBM Plex Sans',sans-serif;letter-spacing:-0.02em;color:var(--ui-text-highlighted)">Screen: API keys</h1>
+<p style="margin:0;max-width:880px;font-size:16px;line-height:26px;color:var(--ui-text-toned);text-wrap:pretty">The screen the Authentication section of <a href="RenewCMS Screens Back-office.dc.html">the Integration screen</a> links to. 1440 px at 50%, 390 px at 75%. The theme switch shows every state in dark mode.</p>
+</div>
+<div role="radiogroup" aria-label="Theme" style="display:flex;border:1px solid var(--ui-border-accented);background:var(--ui-bg)">
+<sc-for list="{{ modes }}" as="m" hint-placeholder-count="3">
+<button role="radio" aria-checked="{{ m.on }}" onClick="{{ m.pick }}" style="all:unset;cursor:pointer;height:36px;padding:0 14px;display:flex;align-items:center;font-weight:500;font-size:14px;background:{{ m.bg }};color:{{ m.fg }}" style-focus-visible="outline:2px solid var(--ui-primary);outline-offset:2px">{{ m.label }}</button>
+</sc-for>
+</div>
+</div>
+
+<sc-for list="{{ groups }}" as="g" hint-placeholder-count="7">
+<section data-screen-label="{{ g.label }}" style="display:flex;flex-direction:column;gap:28px">
+<div style="display:flex;flex-direction:column;gap:6px;max-width:1100px">
+<h2 style="margin:0;font:600 28px/36px 'IBM Plex Sans',sans-serif;color:var(--ui-text-highlighted)">{{ g.title }}</h2>
+<div style="display:flex;gap:16px;flex-wrap:wrap;font:400 14px/22px 'IBM Plex Mono',monospace;color:var(--ui-text-toned)"><span>{{ g.route }}</span><span style="color:var(--ui-text-muted)">{{ g.api }}</span></div>
+<sc-if value="{{ g.note }}"><p style="margin:4px 0 0;font-size:15px;line-height:24px;color:var(--ui-text-toned);text-wrap:pretty">{{ g.note }}</p></sc-if>
+</div>
+<div style="display:flex;flex-wrap:wrap;gap:40px;align-items:flex-start">
+<sc-for list="{{ g.states }}" as="st" hint-placeholder-count="4">
+<div style="display:flex;flex-direction:column;gap:12px">
+<div style="display:flex;flex-direction:column;gap:2px;max-width:1040px"><span style="font:600 16px/24px 'IBM Plex Sans',sans-serif;color:var(--ui-text-highlighted)">{{ st.name }}</span><span style="font-size:13px;color:var(--ui-text-muted)">{{ st.trigger }}</span></div>
+<div style="display:flex;gap:24px;align-items:flex-start">
+<div style="width:720px;height:450px;overflow:hidden;border:1px solid var(--ui-border);flex-shrink:0"><div style="width:1440px;height:900px;zoom:0.5"><sc-if value="{{ st.notMedia }}"><dc-import name="AppFrame" s="{{ st }}" mobile="{{ false }}" hint-size="1440px,900px"></dc-import></sc-if><sc-if value="{{ st.isMedia }}"><dc-import name="MediaFrame" s="{{ st }}" mobile="{{ false }}" hint-size="1440px,900px"></dc-import></sc-if></div></div>
+<div style="width:293px;height:633px;overflow:hidden;border:1px solid var(--ui-border);flex-shrink:0"><div style="width:390px;height:844px;zoom:0.75"><sc-if value="{{ st.notMedia }}"><dc-import name="AppFrame" s="{{ st.m }}" mobile="{{ true }}" hint-size="390px,844px"></dc-import></sc-if><sc-if value="{{ st.isMedia }}"><dc-import name="MediaFrame" s="{{ st.m }}" mobile="{{ true }}" hint-size="390px,844px"></dc-import></sc-if></div></div>
+</div>
+</div>
+</sc-for>
+</div>
+<sc-if value="{{ g.table }}"><div style="display:flex;flex-direction:column;gap:8px;max-width:1240px"><span style="font:600 16px/24px 'IBM Plex Sans',sans-serif;color:var(--ui-text-highlighted)">{{ g.tableTitle }}</span><div style="background:var(--ui-bg);border:1px solid var(--ui-border)"><div style="display:grid;grid-template-columns:90px 240px minmax(0,1fr);padding:8px 12px;background:var(--ui-bg-elevated);color:var(--ui-text-muted);font-weight:500"><span>Status</span><span>Where</span><span>Copy</span></div><sc-for list="{{ g.table }}" as="r" hint-placeholder-count="3"><div style="display:grid;grid-template-columns:90px 240px minmax(0,1fr);gap:0;padding:10px 12px;border-top:1px solid var(--ui-border);line-height:20px"><span style="font:500 13px 'IBM Plex Mono',monospace;color:var(--ui-text-highlighted)">{{ r.a }}</span><span style="color:var(--ui-text-toned);padding-right:16px">{{ r.b }}</span><span style="color:var(--ui-text-highlighted);text-wrap:pretty">{{ r.c }}</span></div></sc-for></div></div></sc-if>
+</section>
+</sc-for>
+
+</div>
+</x-dc>
+<script type="text/x-dc" data-dc-script data-props="{&quot;theme&quot;:{&quot;editor&quot;:&quot;enum&quot;,&quot;options&quot;:[&quot;system&quot;,&quot;light&quot;,&quot;dark&quot;],&quot;default&quot;:&quot;system&quot;,&quot;tsType&quot;:&quot;'system' | 'light' | 'dark'&quot;}}">
+class Component extends DCLogic {
+	state = { mode: this.props.theme ?? 'light' }
+	rootRef = React.createRef()
+	light = { '--ui-bg': '#ffffff', '--ui-bg-muted': '#fafafa', '--ui-bg-elevated': '#f3f2f0', '--ui-bg-accented': '#e6e4e0', '--ui-bg-inverted': '#111111', '--ui-text-dimmed': '#999999', '--ui-text-muted': '#666666', '--ui-text-toned': '#444444', '--ui-text': '#222222', '--ui-text-highlighted': '#111111', '--ui-text-inverted': '#ffffff', '--ui-border': '#e6e4e0', '--ui-border-muted': '#f3f2f0', '--ui-border-accented': '#8a8783', '--ui-primary': '#111111', '--ui-secondary': '#635643', '--ui-success': '#315b33', '--ui-info': '#34536d', '--ui-warning': '#6c4700', '--ui-error': '#882c21', '--rc-sand': '#e8dfd1', '--rc-success-soft': '#eaefea', '--rc-info-soft': '#ebeef0', '--rc-warning-soft': '#f0ede6', '--rc-error-soft': '#f3eae9', '--rc-overlay': 'rgb(10 10 10 / 0.4)', '--rc-shadow-pop': '0 4px 16px rgb(17 17 17 / 0.08), 0 1px 2px rgb(17 17 17 / 0.06)', '--rc-shadow-modal': '0 16px 48px rgb(17 17 17 / 0.18)', '--rc-canvas': '#ecebe8' }
+	dark = { '--ui-bg': '#111111', '--ui-bg-muted': '#0a0a0a', '--ui-bg-elevated': '#1a1a1a', '--ui-bg-accented': '#222222', '--ui-bg-inverted': '#fafafa', '--ui-text-dimmed': '#666666', '--ui-text-muted': '#999999', '--ui-text-toned': '#cfccc7', '--ui-text': '#e6e4e0', '--ui-text-highlighted': '#fafafa', '--ui-text-inverted': '#111111', '--ui-border': '#333333', '--ui-border-muted': '#222222', '--ui-border-accented': '#666666', '--ui-primary': '#fafafa', '--ui-secondary': '#d4c5b0', '--ui-success': '#a3caa3', '--ui-info': '#a5c2db', '--ui-warning': '#dfb67d', '--ui-error': '#fba394', '--rc-sand': '#d4c5b0', '--rc-success-soft': '#1f241f', '--rc-info-soft': '#202428', '--rc-warning-soft': '#2a251e', '--rc-error-soft': '#2c201f', '--rc-overlay': 'rgb(0 0 0 / 0.6)', '--rc-shadow-pop': '0 4px 16px rgb(0 0 0 / 0.5)', '--rc-shadow-modal': '0 16px 48px rgb(0 0 0 / 0.6)', '--rc-canvas': '#1c1c1c' }
+	resolved() {
+		if (this.state.mode === 'system') return window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light'
+		return this.state.mode
+	}
+	apply() {
+		const el = this.rootRef.current
+		if (!el) return
+		const vars = this.resolved() === 'dark' ? this.dark : this.light
+		for (const k in vars) el.style.setProperty(k, vars[k])
+		document.body.style.background = vars['--rc-canvas']
+	}
+	componentDidMount() { this.apply() }
+	componentDidUpdate(p) {
+		if (p.theme !== this.props.theme && this.props.theme) this.setState({ mode: this.props.theme })
+		this.apply()
+	}
+	groups() {
+		const withM = (st, mo = {}) => ({ ...st, m: { ...st, ...mo } })
+		return this.finish([
+			{ label: 'API keys', title: 'API keys', route: '/integration/api-keys', api: 'GET /v1/api-key · POST /v1/api-key · DELETE /v1/api-key/{id} (session only)', note: 'Recommendation: place it under Integration, as a sub-page linked from the Authentication section and from the sidebar item. Keys exist to call the API, so they belong next to the reference. Settings is owner-only today, but admins can also create keys. The screen is session only: an API key cannot manage keys. Key name: required, up to 60 characters. Expiry: optional, in the future. A key is shown in full once; afterwards only its prefix is visible.', states: [
+				withM({ kind: 'apikeys', nav: 'integration', crumbs: ['Integration','API keys'], mTitle: 'API keys', mLead: 'arrow-left', name: "Owner: list", trigger: "Owners see every user's keys and a \"Created by\" column. Expired keys keep their Revoke action.", ak: {"view":"owner"} }, { ak: {"view":"owner"} }),
+				withM({ kind: 'apikeys', nav: 'integration', crumbs: ['Integration','API keys'], mTitle: 'API keys', mLead: 'arrow-left', name: "Admin: own keys only", trigger: "Admins see only the keys they created, with no \"Created by\" column.", ak: {"view":"admin"} }, { ak: {"view":"admin"} }),
+				withM({ kind: 'apikeys', nav: 'integration', crumbs: ['Integration','API keys'], mTitle: 'API keys', mLead: 'arrow-left', name: "Loading", trigger: "The list request is in flight. Skeleton rows appear after 150 ms.", ak: {"state":"loading"} }, { ak: {"state":"loading"} }),
+				withM({ kind: 'apikeys', nav: 'integration', crumbs: ['Integration','API keys'], mTitle: 'API keys', mLead: 'arrow-left', name: "Empty", trigger: "No keys yet.", ak: {"state":"empty"} }, { ak: {"state":"empty"} }),
+				withM({ kind: 'apikeys', nav: 'integration', crumbs: ['Integration','API keys'], mTitle: 'API keys', mLead: 'arrow-left', name: "Error", trigger: "A 500 or network failure on the list request.", ak: {"state":"error"} }, { ak: {"state":"error"} }),
+				withM({ kind: 'apikeys', nav: 'integration', crumbs: ['Integration','API keys'], mTitle: 'API keys', mLead: 'arrow-left', name: "Create key", trigger: "\"Create key\" in the page header, or the bottom action on mobile. Name is required and limited to 60 characters; expiry is optional.", ak: {"modal":"create"} }, { ak: {"modal":"create"} }),
+				withM({ kind: 'apikeys', nav: 'integration', crumbs: ['Integration','API keys'], mTitle: 'API keys', mLead: 'arrow-left', name: "Create key: validation", trigger: "On submit or blur. Nothing is sent. The name is empty and the expiry is in the past.", ak: {"modal":"invalid"} }, { ak: {"modal":"invalid"} }),
+				withM({ kind: 'apikeys', nav: 'integration', crumbs: ['Integration','API keys'], mTitle: 'API keys', mLead: 'arrow-left', name: "Create key: name too long", trigger: "Over 60 characters. Checked as you type.", ak: {"modal":"toolong"} }, { ak: {"modal":"toolong"} }),
+				withM({ kind: 'apikeys', nav: 'integration', crumbs: ['Integration','API keys'], mTitle: 'API keys', mLead: 'arrow-left', name: "One-time reveal", trigger: "201: the full key is shown once. Closing the dialog discards it from the screen.", ak: {"modal":"reveal"} }, { ak: {"modal":"reveal"} }),
+				withM({ kind: 'apikeys', nav: 'integration', crumbs: ['Integration','API keys'], mTitle: 'API keys', mLead: 'arrow-left', name: "One-time reveal: copied", trigger: "Copy was pressed. The button reads \"Copied\" for 2 s and this is announced.", ak: {"modal":"copied"} }, { ak: {"modal":"copied"} }),
+				withM({ kind: 'apikeys', nav: 'integration', crumbs: ['Integration','API keys'], mTitle: 'API keys', mLead: 'arrow-left', name: "Revoke: confirm", trigger: "Revoke on an active or expired row.", ak: {"modal":"revoke"} }, { ak: {"modal":"revoke"} }),
+				withM({ kind: 'apikeys', nav: 'integration', crumbs: ['Integration','API keys'], mTitle: 'API keys', mLead: 'arrow-left', name: "Revoked", trigger: "204: the key stays in the list, greyed, with no Revoke action. A toast confirms.", ak: {"revoked":1,"toast":1} }, { ak: {"revoked":1,"toast":1} })
+			] }
+		])
+	}
+	finish(gs) { return gs.map(g => ({ ...g, states: g.states.map(st => ({ notMedia: !st.isMedia, ...st, m: { ...st.m } })) })) }
+	renderVals() {
+		const modes = [['system', 'System'], ['light', 'Light'], ['dark', 'Dark']].map(([k, label]) => {
+			const on = this.state.mode === k
+			return { label, on, bg: on ? 'var(--ui-primary)' : 'transparent', fg: on ? 'var(--ui-bg)' : 'var(--ui-text-toned)', pick: () => this.setState({ mode: k }) }
+		})
+		return { rootRef: this.rootRef, modes, groups: this.groups() }
+	}
+}
+</script>
+</body>
+</html>

docs/design/source/RenewCMS Screens Back-office.dc.html

@@ -13,12 +13,12 @@
 <link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Sans:wght@400;500;600&family=IBM+Plex+Mono:wght@400;500&family=Source+Serif+4:ital,opsz,wght@0,8..60,400;0,8..60,600;1,8..60,400&display=swap" rel="stylesheet">
 <style>body{margin:0;font-family:'IBM Plex Sans',sans-serif;font-size:13px;line-height:20px}*{box-sizing:border-box}a{color:inherit;text-underline-offset:3px}a:hover{opacity:.8}code{font-family:'IBM Plex Mono',monospace;font-size:12px}</style>
 </helmet>
-<div ref="{{ rootRef }}" data-screen-label="Back-office screens" style="--ui-bg:#ffffff;--ui-bg-muted:#fafafa;--ui-bg-elevated:#f3f2f0;--ui-bg-accented:#e6e4e0;--ui-bg-inverted:#111111;--ui-text-dimmed:#999999;--ui-text-muted:#666666;--ui-text-toned:#444444;--ui-text:#222222;--ui-text-highlighted:#111111;--ui-text-inverted:#ffffff;--ui-border:#e6e4e0;--ui-border-muted:#f3f2f0;--ui-border-accented:#8a8783;--ui-primary:#111111;--ui-secondary:#635643;--ui-success:#315b33;--ui-info:#34536d;--ui-warning:#6c4700;--ui-error:#882c21;--rc-sand:#e8dfd1;--rc-success-soft:#eaefea;--rc-info-soft:#ebeef0;--rc-warning-soft:#f0ede6;--rc-error-soft:#f3eae9;--rc-overlay:rgb(10 10 10 / 0.4);--rc-shadow-pop:0 4px 16px rgb(17 17 17 / 0.08), 0 1px 2px rgb(17 17 17 / 0.06);--rc-shadow-modal:0 16px 48px rgb(17 17 17 / 0.18);--rc-canvas:#ecebe8;background:var(--rc-canvas);color:var(--ui-text);padding:64px;display:flex;flex-direction:column;gap:72px;width:max-content;min-width:100%">
+<div ref="{{ rootRef }}" data-screen-label="Back-office screens" style="--ui-bg:#ffffff;--ui-bg-muted:#fafafa;--ui-bg-elevated:#f3f2f0;--ui-bg-accented:#e6e4e0;--ui-bg-inverted:#111111;--ui-text-dimmed:#999999;--ui-text-muted:#666666;--ui-text-toned:#444444;--ui-text:#222222;--ui-text-highlighted:#111111;--ui-text-inverted:#ffffff;--ui-border:#e6e4e0;--ui-border-muted:#f3f2f0;--ui-border-accented:#8a8783;--ui-primary:#111111;--ui-secondary:#635643;--ui-success:#315b33;--ui-info:#34536d;--ui-warning:#6c4700;--ui-error:#882c21;--rc-sand:#e8dfd1;--rc-on-sand:#111111;--rc-success-soft:#eaefea;--rc-info-soft:#ebeef0;--rc-warning-soft:#f0ede6;--rc-error-soft:#f3eae9;--rc-overlay:rgb(10 10 10 / 0.4);--rc-shadow-pop:0 4px 16px rgb(17 17 17 / 0.08), 0 1px 2px rgb(17 17 17 / 0.06);--rc-shadow-modal:0 16px 48px rgb(17 17 17 / 0.18);--rc-canvas:#ecebe8;background:var(--rc-canvas);color:var(--ui-text);padding:64px;display:flex;flex-direction:column;gap:72px;width:max-content;min-width:100%">
 
 <div style="display:flex;align-items:flex-end;gap:32px;max-width:1400px">
 <div style="flex:1;display:flex;flex-direction:column;gap:10px">
 <h1 style="margin:0;font:600 36px/44px 'IBM Plex Sans',sans-serif;letter-spacing:-0.02em;color:var(--ui-text-highlighted)">Screens: back-office and global</h1>
-<p style="margin:0;max-width:880px;font-size:16px;line-height:26px;color:var(--ui-text-toned);text-wrap:pretty">Every state of the verified-only routes, plus the global states, at 1440 px (shown at 50%) and 390 px (shown at 75%). The theme switch shows all of them in dark mode. Session expiry and unverified redirects end on screens from <a href="RenewCMS Screens Auth.dc.html">the auth board</a>.</p>
+<p style="margin:0;max-width:880px;font-size:16px;line-height:26px;color:var(--ui-text-toned);text-wrap:pretty">Every state of the verified-only routes, plus the global states, at 1440 px (shown at 50%) and 390 px (shown at 75%). Home, Settings and Media show every card in one page, so each card matches its neighbours. Activity, Media cleanup and the activity cards live here too. The theme switch shows all of them in dark mode. Session expiry and unverified redirects end on screens from <a href="RenewCMS Screens Auth.dc.html">the auth board</a>.</p>
 </div>
 <div role="radiogroup" aria-label="Theme" style="display:flex;border:1px solid var(--ui-border-accented);background:var(--ui-bg)">
 <sc-for list="{{ modes }}" as="m" hint-placeholder-count="3">
@@ -39,8 +39,8 @@
 <div style="display:flex;flex-direction:column;gap:12px">
 <div style="display:flex;flex-direction:column;gap:2px;max-width:1040px"><span style="font:600 16px/24px 'IBM Plex Sans',sans-serif;color:var(--ui-text-highlighted)">{{ st.name }}</span><span style="font-size:13px;color:var(--ui-text-muted)">{{ st.trigger }}</span></div>
 <div style="display:flex;gap:24px;align-items:flex-start">
-<div style="width:720px;height:450px;overflow:hidden;border:1px solid var(--ui-border);flex-shrink:0"><div style="width:1440px;height:900px;zoom:0.5"><sc-if value="{{ st.notMedia }}"><dc-import name="AppFrame" s="{{ st }}" mobile="{{ false }}" hint-size="1440px,900px"></dc-import></sc-if><sc-if value="{{ st.isMedia }}"><dc-import name="MediaFrame" s="{{ st }}" mobile="{{ false }}" hint-size="1440px,900px"></dc-import></sc-if></div></div>
-<div style="width:293px;height:633px;overflow:hidden;border:1px solid var(--ui-border);flex-shrink:0"><div style="width:390px;height:844px;zoom:0.75"><sc-if value="{{ st.notMedia }}"><dc-import name="AppFrame" s="{{ st.m }}" mobile="{{ true }}" hint-size="390px,844px"></dc-import></sc-if><sc-if value="{{ st.isMedia }}"><dc-import name="MediaFrame" s="{{ st.m }}" mobile="{{ true }}" hint-size="390px,844px"></dc-import></sc-if></div></div>
+<div style="width:720px;height:450px;overflow:hidden;border:1px solid var(--ui-border);flex-shrink:0"><div style="width:1440px;height:900px;zoom:0.5"><sc-if value="{{ st.notMedia }}"><dc-import name="AppFrame" s="{{ st }}" mobile="{{ false }}" hint-size="1440px,900px"></dc-import></sc-if><sc-if value="{{ st.isMedia }}"><dc-import name="MediaFrame" s="{{ st }}" mobile="{{ false }}" hint-size="1440px,900px"></dc-import></sc-if><sc-if value="{{ st.isAct }}"><dc-import name="ActivityFrame" s="{{ st }}" mobile="{{ false }}" hint-size="1440px,900px"></dc-import></sc-if></div></div>
+<div style="width:293px;height:633px;overflow:hidden;border:1px solid var(--ui-border);flex-shrink:0"><div style="width:390px;height:844px;zoom:0.75"><sc-if value="{{ st.notMedia }}"><dc-import name="AppFrame" s="{{ st.m }}" mobile="{{ true }}" hint-size="390px,844px"></dc-import></sc-if><sc-if value="{{ st.isMedia }}"><dc-import name="MediaFrame" s="{{ st.m }}" mobile="{{ true }}" hint-size="390px,844px"></dc-import></sc-if><sc-if value="{{ st.isAct }}"><dc-import name="ActivityFrame" s="{{ st.m }}" mobile="{{ true }}" hint-size="390px,844px"></dc-import></sc-if></div></div>
 </div>
 </div>
 </sc-for>
@@ -49,14 +49,17 @@
 </section>
 </sc-for>
 
+<section style="display:flex;flex-direction:column;gap:20px;max-width:1240px"><h2 style="margin:0;font:600 28px/36px 'IBM Plex Sans',sans-serif;color:var(--ui-text-highlighted)">Activity: copy per state</h2><div style="background:var(--ui-bg);border:1px solid var(--ui-border)"><sc-for list="{{ spCopy }}" as="r" hint-placeholder-count="5"><div style="display:grid;grid-template-columns:220px minmax(0,1fr);padding:10px 12px;border-top:1px solid var(--ui-border);line-height:20px"><span style="font:500 13px 'IBM Plex Mono',monospace;color:var(--ui-text-highlighted)">{{ r.a }}</span><span style="color:var(--ui-text-highlighted);text-wrap:pretty">{{ r.b }}</span></div></sc-for></div></section>
+<section style="display:flex;flex-direction:column;gap:20px;max-width:1240px"><h2 style="margin:0;font:600 28px/36px 'IBM Plex Sans',sans-serif;color:var(--ui-text-highlighted)">Activity: component inventory (Nuxt UI v4)</h2><div style="background:var(--ui-bg);border:1px solid var(--ui-border)"><sc-for list="{{ spComps }}" as="r" hint-placeholder-count="5"><div style="display:grid;grid-template-columns:220px minmax(0,1fr);padding:10px 12px;border-top:1px solid var(--ui-border);line-height:20px"><span style="font:500 13px 'IBM Plex Mono',monospace;color:var(--ui-text-highlighted)">{{ r.a }}</span><span style="color:var(--ui-text-highlighted);text-wrap:pretty">{{ r.b }}</span></div></sc-for></div></section>
+<section style="display:flex;flex-direction:column;gap:20px;max-width:1240px"><h2 style="margin:0;font:600 28px/36px 'IBM Plex Sans',sans-serif;color:var(--ui-text-highlighted)">Activity: API calls</h2><div style="background:var(--ui-bg);border:1px solid var(--ui-border)"><sc-for list="{{ spApi }}" as="r" hint-placeholder-count="5"><div style="display:grid;grid-template-columns:220px minmax(0,1fr);padding:10px 12px;border-top:1px solid var(--ui-border);line-height:20px"><span style="font:500 13px 'IBM Plex Mono',monospace;color:var(--ui-text-highlighted)">{{ r.a }}</span><span style="color:var(--ui-text-highlighted);text-wrap:pretty">{{ r.b }}</span></div></sc-for></div></section>
 </div>
 </x-dc>
-<script type="text/x-dc" data-dc-script data-props="{&quot;theme&quot;:{&quot;editor&quot;:&quot;enum&quot;,&quot;options&quot;:[&quot;system&quot;,&quot;light&quot;,&quot;dark&quot;],&quot;default&quot;:&quot;light&quot;,&quot;tsType&quot;:&quot;'system' | 'light' | 'dark'&quot;}}">
+<script type="text/x-dc" data-dc-script data-props="{&quot;theme&quot;:{&quot;editor&quot;:&quot;enum&quot;,&quot;options&quot;:[&quot;system&quot;,&quot;light&quot;,&quot;dark&quot;],&quot;default&quot;:&quot;system&quot;,&quot;tsType&quot;:&quot;'system' | 'light' | 'dark'&quot;}}">
 class Component extends DCLogic {
-	state = { mode: this.props.theme ?? 'light' }
+	state = { mode: this.props.theme ?? 'light', spec: { copy: [], comps: [], api: [] } }
 	rootRef = React.createRef()
-	light = { '--ui-bg': '#ffffff', '--ui-bg-muted': '#fafafa', '--ui-bg-elevated': '#f3f2f0', '--ui-bg-accented': '#e6e4e0', '--ui-bg-inverted': '#111111', '--ui-text-dimmed': '#999999', '--ui-text-muted': '#666666', '--ui-text-toned': '#444444', '--ui-text': '#222222', '--ui-text-highlighted': '#111111', '--ui-text-inverted': '#ffffff', '--ui-border': '#e6e4e0', '--ui-border-muted': '#f3f2f0', '--ui-border-accented': '#8a8783', '--ui-primary': '#111111', '--ui-secondary': '#635643', '--ui-success': '#315b33', '--ui-info': '#34536d', '--ui-warning': '#6c4700', '--ui-error': '#882c21', '--rc-sand': '#e8dfd1', '--rc-success-soft': '#eaefea', '--rc-info-soft': '#ebeef0', '--rc-warning-soft': '#f0ede6', '--rc-error-soft': '#f3eae9', '--rc-overlay': 'rgb(10 10 10 / 0.4)', '--rc-shadow-pop': '0 4px 16px rgb(17 17 17 / 0.08), 0 1px 2px rgb(17 17 17 / 0.06)', '--rc-shadow-modal': '0 16px 48px rgb(17 17 17 / 0.18)', '--rc-canvas': '#ecebe8' }
-	dark = { '--ui-bg': '#111111', '--ui-bg-muted': '#0a0a0a', '--ui-bg-elevated': '#1a1a1a', '--ui-bg-accented': '#222222', '--ui-bg-inverted': '#fafafa', '--ui-text-dimmed': '#666666', '--ui-text-muted': '#999999', '--ui-text-toned': '#cfccc7', '--ui-text': '#e6e4e0', '--ui-text-highlighted': '#fafafa', '--ui-text-inverted': '#111111', '--ui-border': '#333333', '--ui-border-muted': '#222222', '--ui-border-accented': '#666666', '--ui-primary': '#fafafa', '--ui-secondary': '#d4c5b0', '--ui-success': '#a3caa3', '--ui-info': '#a5c2db', '--ui-warning': '#dfb67d', '--ui-error': '#fba394', '--rc-sand': '#d4c5b0', '--rc-success-soft': '#1f241f', '--rc-info-soft': '#202428', '--rc-warning-soft': '#2a251e', '--rc-error-soft': '#2c201f', '--rc-overlay': 'rgb(0 0 0 / 0.6)', '--rc-shadow-pop': '0 4px 16px rgb(0 0 0 / 0.5)', '--rc-shadow-modal': '0 16px 48px rgb(0 0 0 / 0.6)', '--rc-canvas': '#1c1c1c' }
+	light = { '--ui-bg': '#ffffff', '--ui-bg-muted': '#fafafa', '--ui-bg-elevated': '#f3f2f0', '--ui-bg-accented': '#e6e4e0', '--ui-bg-inverted': '#111111', '--ui-text-dimmed': '#999999', '--ui-text-muted': '#666666', '--ui-text-toned': '#444444', '--ui-text': '#222222', '--ui-text-highlighted': '#111111', '--ui-text-inverted': '#ffffff', '--ui-border': '#e6e4e0', '--ui-border-muted': '#f3f2f0', '--ui-border-accented': '#8a8783', '--ui-primary': '#111111', '--ui-secondary': '#635643', '--ui-success': '#315b33', '--ui-info': '#34536d', '--ui-warning': '#6c4700', '--ui-error': '#882c21', '--rc-sand': '#e8dfd1', '--rc-on-sand': '#111111', '--rc-success-soft': '#eaefea', '--rc-info-soft': '#ebeef0', '--rc-warning-soft': '#f0ede6', '--rc-error-soft': '#f3eae9', '--rc-overlay': 'rgb(10 10 10 / 0.4)', '--rc-shadow-pop': '0 4px 16px rgb(17 17 17 / 0.08), 0 1px 2px rgb(17 17 17 / 0.06)', '--rc-shadow-modal': '0 16px 48px rgb(17 17 17 / 0.18)', '--rc-canvas': '#ecebe8' }
+	dark = { '--ui-bg': '#111111', '--ui-bg-muted': '#0a0a0a', '--ui-bg-elevated': '#1a1a1a', '--ui-bg-accented': '#222222', '--ui-bg-inverted': '#fafafa', '--ui-text-dimmed': '#666666', '--ui-text-muted': '#999999', '--ui-text-toned': '#cfccc7', '--ui-text': '#e6e4e0', '--ui-text-highlighted': '#fafafa', '--ui-text-inverted': '#111111', '--ui-border': '#333333', '--ui-border-muted': '#222222', '--ui-border-accented': '#666666', '--ui-primary': '#fafafa', '--ui-secondary': '#d4c5b0', '--ui-success': '#a3caa3', '--ui-info': '#a5c2db', '--ui-warning': '#dfb67d', '--ui-error': '#fba394', '--rc-sand': '#d4c5b0', '--rc-on-sand': '#111111', '--rc-success-soft': '#1f241f', '--rc-info-soft': '#202428', '--rc-warning-soft': '#2a251e', '--rc-error-soft': '#2c201f', '--rc-overlay': 'rgb(0 0 0 / 0.6)', '--rc-shadow-pop': '0 4px 16px rgb(0 0 0 / 0.5)', '--rc-shadow-modal': '0 16px 48px rgb(0 0 0 / 0.6)', '--rc-canvas': '#1c1c1c' }
 	resolved() {
 		if (this.state.mode === 'system') return window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light'
 		return this.state.mode
@@ -68,7 +71,10 @@ class Component extends DCLogic {
 		for (const k in vars) el.style.setProperty(k, vars[k])
 		document.body.style.background = vars['--rc-canvas']
 	}
-	componentDidMount() { this.apply() }
+	componentDidMount() {
+		this.apply()
+		import('./activity-spec.js').then(x => this.setState({ spec: { copy: x.copy, comps: x.comps, api: x.api } })).catch(() => {})
+	}
 	componentDidUpdate(p) {
 		if (p.theme !== this.props.theme && this.props.theme) this.setState({ mode: this.props.theme })
 		this.apply()
@@ -122,7 +128,7 @@ class Component extends DCLogic {
 		const B = (t, kind, icon, dis) => ({ t, icon, bg: kind === 'primary' ? 'var(--ui-primary)' : 'var(--ui-bg)', fg: kind === 'primary' ? 'var(--ui-bg)' : 'var(--ui-text-highlighted)', bd: kind === 'primary' ? 'var(--ui-primary)' : 'var(--ui-border-accented)', op: dis ? '0.4' : '1' })
 		const UPD = (o) => { const rdy = o.title === 'Version 2.3.0 is ready to install' && o.btns && o.btns.length; if (rdy) o = { ...o, tone: 'warning', icon: 'clock', pendingTag: true, inBtn: o.btns[0], btns: undefined }; const tone = o.tone || 'neutral'; return { v: 'v2.2.0-beta', focus: 'none', ...o, fg: tone === 'neutral' ? 'var(--ui-text-toned)' : 'var(--ui-' + tone + ')', bg: TB[tone], bar: o.pct !== undefined || !!o.indet, barW: o.indet ? '35%' : (o.pct || 0) + '%', barL: o.indet ? '30%' : '0', pct: o.indet ? undefined : o.pct } }
 		const NOTES = (open) => ({ open, chev: open ? 'chevron-down' : 'chevron-right', ver: '2.3.0', date: 'Released 24 Sep 2026', items: [{ t: 'Images upload faster, and large images no longer stall.' }, { t: 'Fixed a problem where a draft could show an old title after saving.' }, { t: 'Small improvements to the Users page.' }] })
-		const SU = (o, extra) => withM({ kind: 'settings', nav: 'settings', crumbs: ['Settings'], mTitle: 'Settings', ...extra, upd: UPD(o) })
+		const SU = (o, extra, mo) => withM({ kind: 'settings', nav: 'settings', crumbs: ['Settings'], mTitle: 'Settings', ...extra, upd: UPD(o) }, mo)
 		const LAST = 'Last checked today at 09:41'
 		const RESTART_FOOT = 'Restart takes about 10 seconds. Your site is unavailable while it restarts.'
 		const bn = (icon, title, text) => ({ icon, title, text, btn: 'Go to Settings', fg: 'var(--ui-info)', bg: 'var(--rc-info-soft)' })
@@ -130,17 +136,36 @@ class Component extends DCLogic {
 		const notPrep = (copied) => ({ icon: 'info', tone: 'info', title: 'Version 2.3.0 is available', text: 'This site can\'t update itself from the browser yet. Whoever manages your server can set it up once, or update RenewCMS for you.', meta: LAST, cmd: { line: cmdLine, t: copied ? 'Copied' : 'Copy', icon: copied ? 'check' : 'copy', fg: copied ? 'var(--ui-success)' : 'var(--ui-text-highlighted)', note: 'They run this once on the server. After that, Update and Restart appear here.' }, link: 'How to update' })
 		const restartModal = (o) => ({ title: 'Restart the site?', desc: 'Your site will be unavailable for about 10 seconds. This page reloads on its own when the site is back. Save anything you\'re editing first.', cancel: 'Cancel', confirm: 'Restart site', ...o })
 		const installModal = (o) => ({ title: 'Restart to finish the update?', desc: 'RenewCMS will install version 2.3.0 and restart. Your site will be unavailable for about 10 seconds. This page reloads on its own when the site is back. Save anything you\'re editing first.', cancel: 'Restart later', confirm: 'Restart now', ...o })
+		const Act = (name, trigger, o = {}, mo = {}) => ({ isAct: true, name, trigger, ...o, m: { isAct: true, name, trigger, ...o, ...mo } })
+		const UR = { role: 'user' }
+		const af1 = { cat: 'Authentication', out: 'Failed', range: '30 days' }
+		const UTD = { icon: 'circle-check', tone: 'success', title: 'You\'re up to date', text: 'You have the latest version of RenewCMS.', meta: LAST, btns: [B('Check for updates', 'sec', 'refresh-cw'), B('Restart', 'sec', 'power')], hint: RESTART_FOOT }
+		const SCR = { c: 300, cm: 480, r: 560, rm: 940 }
+		const cLast = { d: '14 Jun 2026', c: 3, a: 5 }, cOn = { on: true, days: '30', last: cLast, next: '14 Jul 2026' }
+		const SC = (kind, name, trigger, cu, extra = {}) => { const sy = kind === 'c' ? SCR.c : SCR.r, sm = kind === 'c' ? SCR.cm : SCR.rm; return withM({ kind: 'settings', nav: 'settings', crumbs: ['Settings'], mTitle: 'Settings', upd: UPD(UTD), scrollY: sy, name, trigger, ...cu, ...extra }, { scrollY: sm }) }
+		const CU = (name, trigger, cleanup, extra) => SC('c', name, trigger, { cleanup }, extra)
+		const RT = (name, trigger, ret, extra) => SC('r', name, trigger, { ret }, extra)
+		const PD = (k, name, trigger, dg = {}) => SC('c', name, trigger, { cleanup: { ...cOn, last: null, on: false }, purge: { k, ...dg } })
+		const pvMore = { groups: 8, copies: 15, arts: 24, list: [{ im: 12, n: 'floorboards.jpg', u: 4, c: 2 }, { im: 7, n: 'IMG_4471.jpg', u: 2, c: 1 }, { im: 2, n: 'kitchen-after.webp', u: 3, c: 3 }, { im: 4, n: 'logo-renew.svg', u: 5, c: 3 }, { im: 11, n: 'lime-plaster.jpg', u: 2, c: 1 }], more: 3 }
+		const pvOne = { groups: 1, copies: 1, arts: 2, list: [{ im: 7, n: 'IMG_4471.jpg', u: 2, c: 1 }], more: 0 }
+		const pv3 = { groups: 3, copies: 7, arts: 10, list: [{ im: 12, n: 'floorboards.jpg', u: 4, c: 2 }, { im: 2, n: 'kitchen-after.webp', u: 3, c: 3 }, { im: 4, n: 'logo-renew.svg', u: 5, c: 3 }], more: 0 }
+		const purged = TT('success', 'circle-check', 'Duplicates purged', '9 copies merged. 12 articles updated.')
+		const doneLast = { d: '5 Oct 2026', c: 9, a: 12 }
 		return this.finish([
 			{ label: 'Boot', title: 'App boot', route: 'any route, first load', api: 'GET /v1/auth/me (pending)', note: 'While the session is checked, the shell renders with skeletons, never a spinner. The possible outcomes are: 200 with a verified user, which renders the route; 200 with an unverified user, which goes to /register/pending; and 401, which goes to /login?redirect=<path>. Public routes skip this check.', states: [
 				withM({ ...home, name: 'Checking session', trigger: 'The first paint on any back-office URL, and usually visible for well under a second.', boot: true })
 			] },
-			{ label: 'Home', title: 'Home', route: '/home', api: 'GET /v1/article/', note: 'The counts come from the list, so there\'s no separate endpoint. The five most recently updated articles link to the editor.', states: [
-				withM({ ...home, name: 'Default', trigger: 'The articles loaded.', home: { sub: 'Here\'s where things stand on your site.', stats, recent } }),
-				withM({ ...home, name: 'Loading', trigger: 'The list request is in flight. Skeletons appear after 150 ms.', home: { sub: 'Here\'s where things stand on your site.', stats: stats.map(() => ({ skel: true })), recent: Array.from({ length: 5 }, () => ({ skel: true })) } }),
+			{ label: 'Home', title: 'Home', route: '/home', api: 'GET /v1/article/ · GET /v1/activity?size=5', note: 'The counts come from the list, so there\'s no separate endpoint. The five most recently updated articles link to the editor. Below them, a Recent activity section shows the last 5 events (owner and admin) or the user\'s own (regular users), and links to Activity.', states: [
+				withM({ ...home, name: 'Default', trigger: 'The articles loaded.', home: { sub: 'Here\'s where things stand on your site.', stats, recent, act: 'ok' } }),
+				withM({ ...home, name: 'Loading', trigger: 'The list request is in flight. Skeletons appear after 150 ms.', home: { sub: 'Here\'s where things stand on your site.', stats: stats.map(() => ({ skel: true })), recent: Array.from({ length: 5 }, () => ({ skel: true })), act: 'loading' } }),
 				withM({ ...home, name: 'Empty, first run', trigger: 'Zero articles: a single call to action, and no stats.', home: { sub: 'Welcome to RenewCMS.', empty: true } }),
 				withM({ ...home, name: 'Error', trigger: 'A 500 or network failure on the list request.', home: { sub: 'Here\'s where things stand on your site.', error: true } }),
-				withM({ ...home, navBadge: true, name: 'Update available (owner)', trigger: 'The owner only. A quiet banner above the content, and an "Update" pill on the Settings item (a dot on the menu icon on mobile, read as "Update available"). Dismissing hides the banner until the next version; the pill stays. Admins see neither.', home: { sub: 'Here\'s where things stand on your site.', stats, recent, banner: bn('circle-arrow-up', 'Version 2.3.0 is available', 'Update it from Settings. It takes about 2 minutes and the site stays online.') } }),
-				withM({ ...home, navBadge: true, name: 'Update ready to install (owner)', trigger: 'The download is checked. The same banner changes its copy, and a dismiss comes back on the next visit because the update is waiting.', home: { sub: 'Here\'s where things stand on your site.', stats, recent, banner: bn('circle-check', 'Version 2.3.0 is ready to install', 'Restart from Settings to finish. The site is unavailable for about 10 seconds.') } })
+				withM({ ...home, navBadge: true, name: 'Update available (owner)', trigger: 'The owner only. A quiet banner above the content, and an "Update" pill on the Settings item (a dot on the menu icon on mobile, read as "Update available"). Dismissing hides the banner until the next version; the pill stays. Admins see neither.', home: { sub: 'Here\'s where things stand on your site.', stats, recent, act: 'ok', banner: bn('circle-arrow-up', 'Version 2.3.0 is available', 'Update it from Settings. It takes about 2 minutes and the site stays online.') } }),
+				withM({ ...home, navBadge: true, name: 'Update ready to install (owner)', trigger: 'The download is checked. The same banner changes its copy, and a dismiss comes back on the next visit because the update is waiting.', home: { sub: 'Here\'s where things stand on your site.', stats, recent, act: 'ok', banner: bn('circle-check', 'Version 2.3.0 is ready to install', 'Restart from Settings to finish. The site is unavailable for about 10 seconds.') } }),
+				withM({ ...home, name: 'Recent activity: loading', trigger: 'The activity request is in flight. Five skeleton rows.', home: { sub: 'Here\'s where things stand on your site.', stats, recent, act: 'loading' } }),
+				withM({ ...home, name: 'Recent activity: error', trigger: 'A failed request shows an inline alert in the section only. The rest of Home is unaffected.', home: { sub: 'Here\'s where things stand on your site.', stats, recent, act: 'error' } }),
+				withM({ ...home, name: 'Recent activity: empty', trigger: 'No events yet.', home: { sub: 'Here\'s where things stand on your site.', stats, recent, act: 'empty' } }),
+				withM({ ...home, role: 'user', name: 'Regular user', trigger: 'Own events only, titled "Your recent activity". The sidebar has no Users, Integration or Settings.', home: { sub: 'Here\'s where things stand on your site.', stats, recent, act: 'ok' } })
 			] },
 			{ label: 'Articles', title: 'Articles', route: '/article', api: 'GET /v1/article/ · PATCH …/publish · PATCH …/unpublish · DELETE /v1/article/{id}', note: 'Rows update when the server responds, not optimistically. Search, tab and sort are stored in the query string.', states: [
 				withM({ ...L(), name: 'Default', trigger: 'The list loaded, sorted by last updated.' }),
@@ -223,6 +248,8 @@ class Component extends DCLogic {
 				Mp({ upload: upT([rowRej, { n: 'notes.pdf', sz: '210 KB', st: 'rej', title: 'notes.pdf isn\'t an image', msg: 'Images can be up to 10 MB. Use a PNG, JPEG, WEBP or SVG image.' }, { n: 'broken.png', sz: '3.0 MB', st: 'rej', title: 'broken.png couldn\'t be read', msg: 'The server couldn\'t read this image. Save it again as a PNG or JPEG, then try again.' }], { title: 'Nothing was uploaded', sub: '3 files were rejected', done: true }), name: 'Upload: rejected files (413, 400)', trigger: 'Type and size are checked in the browser first, so nothing is sent. A server 413 or 400 for a file that got through shows the same row with its own message.' }),
 				Mp({ limited: true, name: 'Upload: too many requests (429)', trigger: 'Rate limited. Retry-After is counted down in the button. It re-enables at zero. Already-added files are kept.' }),
 				Mp({ tab: 'dups', name: 'Duplicates: groups', trigger: 'The Duplicates tab. Groups of identical images side by side, each with its uploader, upload date and "Used in N articles". The suggested copy to keep is the most used, then the oldest.' }),
+				Mp({ tab: 'dups', modal: { k: 'purge' }, name: 'Purge duplicates: confirm', trigger: '"Purge duplicates" in the toolbar, next to the sort menu (in the stacked toolbar on mobile). Opens the same dialog as Settings; every other state is on the Media cleanup board.' }),
+				Mp({ tab: 'dups', member: true, name: 'Duplicates: no purge button (member)', trigger: 'Verified users who are not owner or admin. The "Purge duplicates" button is hidden. "Merge into this one" is unchanged.' }),
 				Mp({ tab: 'dups', dupEmpty: true, name: 'Duplicates: empty', trigger: 'No groups. The Duplicates tab loses its count badge.' }),
 				Mp({ tab: 'dups', modal: { k: 'merge' }, name: 'Merge: confirm', trigger: '"Merge into this one" on floorboards.jpg. The dialog says articles using the other copies will switch to this image and the other copies will be deleted, with the article count.' }),
 				Mp({ tab: 'dups', modal: { k: 'merge', loading: true }, name: 'Merge: in progress', trigger: 'Request in flight. The dialog can\'t be dismissed.' }),
@@ -265,9 +292,39 @@ class Component extends DCLogic {
 				MS({ kind: 'picker', inArticle: true, picker: false, modal: { k: 'remove' }, name: 'Remove image: confirm', trigger: 'Remove image on an image in the article. It now only removes it from this article, and the copy says the file stays in the library. The confirm button is neutral, not red, because nothing is deleted. Title: "Remove this image from the article?"' }),
 				MS({ kind: 'picker', name: 'Removed', trigger: 'Confirmed. The image leaves the article body, which now has unsaved changes.', toasts: [TT('success', 'circle-check', 'Image removed', 'It\'s still in your library.')] })
 			] },
-			{ label: 'Integration', title: 'Connect your website', route: '/integration', api: 'none (static)', note: 'Written for a developer. The base URL is window.location.origin.', states: [
-				withM({ kind: 'integration', nav: 'integration', crumbs: ['Integration'], mTitle: 'Integration', name: 'Default', trigger: 'Opened from the sidebar or the Home card.' }),
-				withM({ kind: 'integration', nav: 'integration', crumbs: ['Integration'], mTitle: 'Integration', copied: true, name: 'Copied', trigger: 'The base URL was copied. The button reads "Copied" for 2 s and this is announced.' })
+			{ label: 'Integration', title: 'Integration: API reference', route: '/integration', api: 'none (static). Replaces "Connect your website".', note: 'Navigation: a sticky section index on the right on desktop, and a "Jump to" select on mobile. A long reference is read in one scroll and searched with the browser, so tabs would hide content and break find-in-page; the index keeps every group on one page, links to anchors and shows where you are. Written for a developer. The base URL is window.location.origin. The API keys screen has its own board.', states: [
+				withM({ kind: 'integration', nav: 'integration', crumbs: ['Integration'], mTitle: 'Integration', name: "1. Default", trigger: "Opened from the sidebar or the Home card. Every endpoint card is collapsed. Desktop shows the sticky index on the right; mobile shows the \"Jump to\" select above the content.", int: {} }, { int: {} }),
+				withM({ kind: 'integration', nav: 'integration', crumbs: ['Integration'], mTitle: 'Integration', name: "2. Group scrolled, one card expanded", trigger: "POST /v1/media/ opened in the Media group: multipart body with 1 file field, curl tab shown. Only one example block is visible per card. Other cards stay collapsed.", int: {"scroll":"media","open":"med-up","tab":"curl"} }, { int: {"scroll":"ep-med-up","open":"med-up","tab":"curl"} }),
+				withM({ kind: 'integration', nav: 'integration', crumbs: ['Integration'], mTitle: 'Integration', name: "3a. Copied: base URL", trigger: "The base URL was copied. The button reads \"Copied\" for 2 s and this is announced.", int: {"copied":"base"} }, { int: {"copied":"base"} }),
+				withM({ kind: 'integration', nav: 'integration', crumbs: ['Integration'], mTitle: 'Integration', name: "3b. Copied: CodeBlock", trigger: "The Copy button in the API key example after a click. Back to \"Copy\" after 2 s.", int: {"scroll":"auth","copied":"auth"} }, { int: {"scroll":"auth","copied":"auth"} }),
+				withM({ kind: 'integration', nav: 'integration', crumbs: ['Integration'], mTitle: 'Integration', name: "4. Authentication", trigger: "The API key card with its example, the \"Manage API keys\" link (goes to the API keys board) and the two notes.", int: {"scroll":"auth"} }, { int: {"scroll":"auth"} }),
+				withM({ kind: 'integration', nav: 'integration', crumbs: ['Integration'], mTitle: 'Integration', name: "5. Session only", trigger: "Routes API keys cannot call. Dashed, muted and locked, so they read as unavailable and not as an error.", int: {"scroll":"session"} }, { int: {"scroll":"session"} }),
+				withM({ kind: 'integration', nav: 'integration', crumbs: ['Integration'], mTitle: 'Integration', name: "6. Errors", trigger: "Status table and the plain-text error response (status line plus a one-sentence body). Key-specific causes are in the 401, 403 and 429 rows.", int: {"scroll":"errors"} }, { int: {"scroll":"errors"} }),
+				withM({ kind: 'integration', nav: 'integration', crumbs: ['Integration'], mTitle: 'Integration', name: "7. Navigation", trigger: "Desktop: the sticky index with the active item (Media). Mobile: the \"Jump to\" select open. Keyboard: the index buttons and the select are in the tab order, Enter jumps, Escape closes the list.", int: {"scroll":"media"} }, { int: {"scroll":"media","jump":true} })
+			] },
+			{ label: 'Activity', title: 'Activity, owner and admin', route: '/activity', api: 'GET /v1/activity · GET /v1/activity/summary', note: 'New route in the sidebar after Users. Owner and admin see everything; regular users get "My activity". Copy, component mapping and API calls are at the bottom of this board.', states: [
+				Act('Default, large dataset', 'Newest first, day separators, a security row, 1,284 events across 52 pages. Hover on the first row shows the exact time.', { tip: 1 }),
+				Act('Loading', 'Skeleton strip and table while both requests are in flight.', { state: 'loading' }),
+				Act('Zero-value summary strip', 'Quiet period: Failed and Security show a calm 0.', { sum: 'zero' }),
+				Act('Filtered, card applied', 'Failed actions card clicked, chips and Clear all. Mobile shows the count on Filters.', { f: af1, card: 2, count: 6, total: '6', ids: [3], sum: 'default' }),
+				Act('Mobile filters sheet', 'Filters open as a bottom sheet (desktop uses the inline bar above).', { f: { ...af1, range: 'Custom' }, drawer: 1, count: 6, total: '6', ids: [3] }),
+				Act('Empty, no activity yet', 'New site. Export is disabled.', { state: 'none', sum: 'none' }),
+				Act('Empty, filters match nothing', 'Offers Clear filters.', { state: 'nomatch', f: { q: 'sitemap', cat: 'Media', out: 'Failed' }, total: '0' }),
+				Act('Error with retry', 'Request failed. The summary strip still shows if its call succeeded.', { state: 'error' }),
+				Act('Forbidden (403)', 'API returned 403 for this role or filter.', { state: 'forbidden', role: 'user' })
+			] },
+			{ label: 'Activity details', title: 'Activity: details slide-over and bottom sheet', route: 'Row click', api: 'Uses the item from GET /v1/activity', states: [
+				Act('Edit with a diff', 'Title change and "Body edited (+312 characters)". No body text.', { panel: 2 }),
+				Act('Settings diff, long text', 'Long values clamp to two lines with Show more.', { panel: 11 }),
+				Act('Failed action, very long target title', 'Failure reason shown, target title wraps.', { panel: 9 }),
+				Act('Deleted target, no diff', 'Struck-through target with a Deleted badge.', { panel: 8 }),
+				Act('System-initiated, no human actor', 'Scheduler with a System badge. IP and browser not applicable.', { panel: 5 }),
+				Act('Security event, failed login', 'Actor not signed in. Restrained shield marker.', { panel: 3 })
+			] },
+			{ label: 'My activity', title: 'My activity, regular user', route: '/activity', api: 'GET /v1/activity (server scoped to the user)', states: [
+				Act('Default', 'No summary strip, no actor filter, no Export. Title becomes My activity.', UR),
+				Act('Empty', 'The user has not done anything yet.', { ...UR, state: 'none' }),
+				Act('Details', 'Same slide-over, own event.', { ...UR, panel: 1 })
 			] },
 			{ label: 'Users', title: 'Users', route: '/users', api: 'GET /v1/user/ · POST /v1/user/invite · DELETE /v1/user/invite/:id (pending) · POST /v1/user/invite/:id/renew (pending)', note: 'One shared workspace: every user sees the same articles and this same list. Columns: email, display name, role (owner or admin), invite status and created date. A pending invite can be cancelled and an expired one renewed; accepted accounts have no row actions. An invite is Pending until its link is used, Expired after 3 days, and Accepted once the account is created.', states: [
 				withM({ ...U(), name: 'Default', trigger: 'The list loaded, newest first.' }),
@@ -288,7 +345,7 @@ class Component extends DCLogic {
 				withM({ ...U({ toasts: [T('error', 'circle-x', 'Couldn\'t renew the invite', 'Try again in a moment.')] }), name: 'Renew invite: failed', trigger: '500 or network failure. The row stays Expired and the button can be pressed again.' }),
 				withM({ ...U({ users: { rows: [{ email: 'lea.martin@renew.example', role: 'admin', st: 'pending', c: 'Today', hl: true }, ...people] } , toasts: [T('success', 'circle-check', 'Invite sent', 'lea.martin@renew.example has 3 days to accept.')] }), name: 'Invite sent', trigger: '201: the dialog closes, the new invite appears at the top as Pending, and a toast confirms.' })
 			] },
-			{ label: 'Settings', title: 'Settings: Updates', route: '/settings', api: 'GET /v1/system/update · POST …/check · POST …/download · POST …/restart (all pending)', note: 'New Updates card under Version, owner only. Update downloads and checks the new version and changes nothing. Restart installs it and restarts the site (about 10 seconds). "Restart later" is simply leaving the card or the dialog. A plain Restart shows only when no update is waiting. Admins see the version and a note. When the server isn\'t prepared, the card shows the notice and a "How to update" link with no buttons. Progress is a progressbar with a value, announced at 25% steps and when each step changes. The card is a polite live region. After the restart the page reloads, focus lands on the "Updates" heading, and a toast confirms. Buttons are disabled while any step runs, and any owner on any device sees the same state from the server. Cue elsewhere: see Home. Out of scope: choosing versions, downgrades, automatic updates, update history.', states: [
+			{ label: 'Settings', title: 'Settings: Updates', route: '/settings', api: 'GET /v1/system/update · POST …/check · POST …/download · POST …/update/restart (all pending)', note: 'The page is one column of cards, top to bottom: Version, Updates, Media cleanup, Retention (owner only). The screens below are scrolled to the card they show. New Updates card under Version, owner only. Update downloads and checks the new version and changes nothing. Restart installs it and restarts the site (about 10 seconds). "Restart later" is simply leaving the card or the dialog. A plain Restart shows only when no update is waiting. Admins see the version and a note. When the server isn\'t prepared, the card shows the notice and a "How to update" link with no buttons. Progress is a progressbar with a value, announced at 25% steps and when each step changes. The card is a polite live region. After the restart the page reloads, focus lands on the "Updates" heading, and a toast confirms. Buttons are disabled while any step runs, and any owner on any device sees the same state from the server. Cue elsewhere: see Home. Out of scope: choosing versions, downgrades, automatic updates, update history.', states: [
 				SU({ icon: 'circle-check', tone: 'success', title: 'You\'re up to date', text: 'You have the latest version of RenewCMS.', meta: LAST, btns: [B('Check for updates', 'sec', 'refresh-cw'), B('Restart', 'sec', 'power')], hint: RESTART_FOOT }, { name: 'Up to date', trigger: 'Opened with no newer version. Restart is available but not emphasised.' }),
 				SU({ icon: 'loader-circle', title: 'Checking for updates…', text: 'This usually takes a few seconds.', btns: [B('Checking…', 'sec', 'loader-circle', true)] }, { name: 'Checking', trigger: 'Check for updates pressed, or the first open after 24 hours. Announced as "Checking for updates". Buttons are disabled.' }),
 				SU({ icon: 'wifi-off', tone: 'warning', title: 'Couldn\'t check for updates', text: 'RenewCMS couldn\'t reach the update server. Check your connection and try again. Your site isn\'t affected.', meta: 'Last checked yesterday at 18:12', btns: [B('Try again', 'primary', 'rotate-cw'), B('Restart', 'sec', 'power')], hint: RESTART_FOOT }, { name: 'Check failed', trigger: 'Offline, or the update server didn\'t answer (500, network). The last known result is kept.' }),
@@ -311,8 +368,8 @@ class Component extends DCLogic {
 				SU({ icon: 'circle-check', tone: 'success', title: 'You\'re up to date', text: 'You have the latest version of RenewCMS.', meta: LAST, btns: [B('Check for updates', 'sec', 'refresh-cw'), B('Restart', 'sec', 'power')], hint: RESTART_FOOT }, { name: 'Plain restart: confirm', trigger: 'Restart with no update waiting. Nothing is installed.', modal: restartModal() }),
 				SU({ icon: 'circle-check', tone: 'success', title: '', text: '', btns: [] }, { name: 'Plain restart: restarting', trigger: 'Same overlay as the update restart with shorter copy.', overlay: { title: 'Restarting your site', text: 'This takes about 10 seconds. This page reloads on its own when the site is back.', meta: 'Started at 09:51', barL: '30%' } }),
 				SU({ icon: 'circle-check', tone: 'success', title: 'Your site is back', text: '', btns: [] }, { name: 'Plain restart: done', trigger: 'The page reloaded. Focus lands on the "Updates" heading.', toasts: [T('success', 'circle-check', 'Site restarted', 'Your site is running again.')] }),
-				SU({ icon: 'circle-arrow-up', tone: 'info', title: 'Version 2.3.0 is available', text: 'You have v2.2.0-beta. Only the owner can update RenewCMS. Ask the owner of this site.', meta: LAST }, { name: 'Admin view', trigger: 'Admins see the version and the note, with no buttons. Up to date: "You\'re up to date" and "Only the owner can update or restart the site." No Home banner or Settings pill.' }),
-				SU({ icon: 'circle-arrow-up', tone: 'info', title: 'Version 2.3.0 is available', text: 'You have v2.2.0-beta. Only the owner can update RenewCMS. Ask the owner of this site.', meta: LAST }, { name: 'Role changed (403)', trigger: 'An owner was changed to admin while the page was open and pressed a button. The card reloads in the admin view.', toasts: [T('error', 'circle-x', 'Only the owner can do this', 'Ask the owner of this site to update RenewCMS.')] }),
+				SU({ icon: 'circle-arrow-up', tone: 'info', title: 'Version 2.3.0 is available', text: 'You have v2.2.0-beta. Only the owner can update RenewCMS. Ask the owner of this site.', meta: LAST }, { noRet: true, name: 'Admin view', trigger: 'Admins see the version and the note, with no buttons. Up to date: "You\'re up to date" and "Only the owner can update or restart the site." No Home banner or Settings pill.' }),
+				SU({ icon: 'circle-arrow-up', tone: 'info', title: 'Version 2.3.0 is available', text: 'You have v2.2.0-beta. Only the owner can update RenewCMS. Ask the owner of this site.', meta: LAST }, { noRet: true, name: 'Role changed (403)', trigger: 'An owner was changed to admin while the page was open and pressed a button. The card reloads in the admin view.', toasts: [T('error', 'circle-x', 'Only the owner can do this', 'Ask the owner of this site to update RenewCMS.')] }),
 				SU({ icon: 'circle-arrow-up', tone: 'info', title: 'Version 2.3.0 is available', text: 'You have v2.2.0-beta. Update downloads the new version and checks it. Nothing changes until you restart.', meta: LAST, btns: [B('Update', 'primary', 'download', true)] }, { name: 'Update already running (409)', trigger: 'Another owner started it. The card switches to that run\'s progress.', navBadge: true, toasts: [T('info', 'info', 'An update is already running', 'Another owner started it. Progress shows here.')] })
 			], tableTitle: 'Status to copy', table: [
 				{ a: '200', b: 'Check, up to date', c: '"You\'re up to date" / "You have the latest version of RenewCMS." / "Last checked today at 09:41"' },
@@ -333,8 +390,52 @@ class Component extends DCLogic {
 				{ a: 'No answer, 60 s', b: 'Restart overlay', c: '"Still restarting" / "This is taking longer than usual. Keep this page open. It reloads on its own when the site is back, or you can reload it now."' },
 				{ a: 'Offline', b: 'Whole page', c: 'Existing banner. Check, Update and Restart are disabled. During a restart, the overlay keeps polling and ignores the offline state.' }
 			] },
+			{ label: 'Settings: Media cleanup', title: 'Settings: Media cleanup', route: '/settings', api: 'GET /v1/media/purge-settings · PATCH /v1/media/purge-settings (owner, admin)', note: 'A card below Updates, same card styling and 20 px gap. Automatic purge is off by default. Settings save immediately on toggle and on blur or Enter of the days field; there is no Save button. 401 and 403 are global (login redirect, /register/pending) and have no local copy.', states: [
+				CU('Default: off, never run', 'Owner or admin. Automatic purge is off, so the "Every" row and "Next purge" are hidden.', {}),
+				CU('On: 30 days, last run', 'Switch on. "Every" appears with the default of 30 days. The last-run line and the next run are shown.', cOn),
+				CU('Saving', 'Brief state after toggling or leaving the field. "Saving…" with loader-circle sits in the card header; controls stay usable.', { ...cOn, saving: true, focusDays: true }),
+				CU('Saved', 'The save succeeded. A small "Saved" confirmation shows in the card header and fades after 2 s. It is announced politely.', { ...cOn, saved: true }),
+				CU('Save failed', 'A 500 or network failure. The error sits under the field and the control reverts to its previous value (30).', { ...cOn, saveErr: true, days: '30', focusDays: true }),
+				CU('Validation error', 'Empty, 0, above 365 or not a whole number, checked on blur or Enter. Nothing is sent. The field keeps what was typed until corrected.', { ...cOn, days: '400', invalid: true, focusDays: true }),
+				CU('Read-only (non-admin)', 'Other verified users. Switch and input are disabled, "Purge now" is hidden, and an info alert explains why.', { ...cOn, ro: true }, { noRet: true }),
+				CU('Loading skeleton', 'The settings request is in flight. Skeleton shows only after 150 ms.', { loading: true }),
+				CU('Offline', 'navigator.onLine is false. The banner matches Media. Switch, input and button are disabled.', { ...cOn, offline: true }, { offline: true, offText: 'You\'re offline. Changing automatic purge and purging duplicates need a connection.' })
+			] },
+			{ label: 'Purge dialog', title: 'Purge duplicates: dialog', route: 'opens from "Purge now" (Settings) and "Purge duplicates" (Media, Duplicates tab)', api: 'GET /v1/media/purge-preview · POST /v1/media/purge', note: 'UModal, sm:max-w-md, bottom sheet on mobile. Cancel first, then the danger confirm. While the request runs, the confirm shows loader-circle and the dialog can\'t be dismissed. The preview is computed before confirming. A group is purged only if one of its copies is used in an article; the kept copy is the one used in the most articles (ties: oldest, then lowest id).', states: [
+				PD('loading', 'Loading preview', 'The preview request is in flight. Skeleton rows show after 150 ms and the confirm is disabled.'),
+				PD('confirm', 'Confirm', '"Purge now" pressed. Summary, up to 5 groups, a link to the Duplicates tab.'),
+				PD('confirm', 'Confirm: many groups', 'More than 5 groups. The list stops at 5 and says how many more.', { pv: pvMore }),
+				PD('progress', 'In progress', 'POST in flight. Confirm reads "Purging…" with loader-circle; Cancel is disabled and Esc, the overlay and swipe do nothing.'),
+				PD('nothing', 'Nothing to purge', 'The preview has no group with an image in use. No confirm; one Close button.'),
+				PD('error', 'Error', '500 or network failure. The dialog stays open, nothing changed. Confirm retries.'),
+				PD('partial', 'Partial failure', 'Some groups failed. The summary refreshes to what is left. Buttons: Close, Retry.', { pv: pvOne }),
+				PD('conflict', 'Conflict (409)', 'The library changed since the preview. Nothing was purged, the summary refreshes and the dialog stays open.', { pv: pv3 })
+			] },
+			{ label: 'Purge results', title: 'Purge: results and feedback', route: '/settings', api: 'after POST /v1/media/purge', note: 'An unattended run does not toast. The next visit to Settings shows the updated "Last purge" line.', states: [
+				CU('Success', 'The dialog closes, a toast shows for 5 s, and the "Last purge" line updates in place.', { on: false, last: doneLast }, { toasts: [T('success', 'circle-check', 'Duplicates purged', '9 copies merged. 12 articles updated.')] }),
+				CU('Success, automatic purge on', 'Same, with the next run moved forward by the interval.', { on: true, days: '30', last: doneLast, next: '4 Nov 2026' }, { toasts: [T('success', 'circle-check', 'Duplicates purged', '9 copies merged. 12 articles updated.')] })
+			], tableTitle: 'Status to copy', table: [
+				{ a: '200', b: 'Purge done', c: 'Toast "Duplicates purged" / "9 copies merged. 12 articles updated."' },
+				{ a: '409', b: 'Library changed', c: '"The library changed, so nothing was purged. Check the new summary and try again."' },
+				{ a: '207', b: 'Partial', c: '"Some groups couldn\'t be merged. 3 of 4 groups were purged. Try again to finish."' },
+				{ a: '500', b: 'Purge failed', c: '"Couldn\'t purge the duplicates. Nothing was changed. Try again in a moment."' },
+				{ a: '500', b: 'Setting not saved', c: '"Couldn\'t save. Try again in a moment."' },
+				{ a: '400', b: 'Days invalid', c: '"Enter a whole number of days between 1 and 365."' }
+			] },
+			{ label: 'Media duplicates entry', title: 'Media: Duplicates tab entry point', route: '/media?filter=duplicates', api: 'owner and admin only', note: 'A secondary "Purge duplicates" button (icon merge) in the toolbar next to the sort menu, and in the stacked toolbar on mobile. The dialog and the member state are listed with the Media states above. Per-group "Merge into this one" is unchanged.', states: [
+				Mp({ tab: 'dups', name: 'Duplicates tab with the button', trigger: 'Owner or admin.' }),
+				Mp({ tab: 'dups', offline: true, name: 'Duplicates tab: offline', trigger: 'The button is disabled with the existing banner.' })
+			] },
+			{ label: 'Settings: Retention', title: 'Settings: Retention (owner only)', route: '/settings', api: 'GET /v1/settings · PATCH /v1/settings', note: 'The last card on the page, same card styling as Version, Updates and Media cleanup. Saves on change.', states: [
+				RT('Default, 90 days or 5 GB', 'Saves on change. Whichever limit is reached first removes the oldest events.', { days: '90', size: '5', saved: true }),
+				RT('Age only (no size limit)', 'The size select reads "No size limit". Same as before this option.', { days: '90' }),
+				RT('Size only (forever)', 'Age is set to Forever, so only the size limit removes events.', { days: '0', size: '5' }),
+				RT('Shortening the period', 'Confirms before older events are removed.', { days: '90', size: '5', shorten: true }),
+				RT('Forever', 'No cleanup scheduled.', { days: '0' }),
+				RT('Save error', 'The previous setting is still in place.', { days: '90', err: true })
+			] },
 			{ label: 'Profile', title: 'Profile', route: '/profile', api: 'GET /v1/auth/me · PATCH /v1/user/me (pending) · POST /v1/auth/password-reset', note: 'Opened from the account menu at the bottom of the sidebar. Username, email and password are read-only. The display name is optional, trimmed, and up to 60 characters. Once saved it replaces the username everywhere a person is named: the sidebar, the account menu, the Home greeting, the Users list (with the username beside it) and the emails RenewCMS sends, such as "Marta Alves invited you to RenewCMS". Saving it empty goes back to the username. The reset link uses the same flow as "Forgot password" and ends on the auth board\'s "Choose a new password" screen.', states: [
-				withM({ ...home, home: { sub: 'Here\'s where things stand on your site.', stats, recent }, userMenu: true, name: 'Account menu', trigger: 'The account chip at the bottom of the sidebar. On mobile, the account row in the navigation drawer opens it as a sheet. Escape or a click outside closes it.' }),
+				withM({ ...home, home: { sub: 'Here\'s where things stand on your site.', stats, recent, act: 'ok' }, userMenu: true, name: 'Account menu', trigger: 'The account chip at the bottom of the sidebar. On mobile, the account row in the navigation drawer opens it as a sheet. Escape or a click outside closes it.' }),
 				P({ loading: true }, { name: 'Loading', trigger: 'Opened directly by URL before /auth/me has returned. From the menu, the cached user renders straight away.' }),
 				P({}, { name: 'Default, no display name', trigger: 'The usual first visit. The username is used everywhere.' }),
 				P({ value: dname, focus: true, dirty: true }, { name: 'Editing', trigger: 'Typing in the field. Save turns on, and leaving the page asks for confirmation.' }),
@@ -356,13 +457,14 @@ class Component extends DCLogic {
 			] }
 		])
 	}
-	finish(gs) { return gs.map(g => ({ ...g, states: g.states.map(st => ({ notMedia: !st.isMedia, ...st, m: { ...st.m } })) })) }
+	finish(gs) { return gs.map(g => ({ ...g, states: g.states.map(st => ({ notMedia: !st.isMedia && !st.isAct, ...st, m: { ...st.m } })) })) }
 	renderVals() {
 		const modes = [['system', 'System'], ['light', 'Light'], ['dark', 'Dark']].map(([k, label]) => {
 			const on = this.state.mode === k
 			return { label, on, bg: on ? 'var(--ui-primary)' : 'transparent', fg: on ? 'var(--ui-bg)' : 'var(--ui-text-toned)', pick: () => this.setState({ mode: k }) }
 		})
-		return { rootRef: this.rootRef, modes, groups: this.groups() }
+		const rows = a => a.map(r => ({ a: r[0], b: r[1] }))
+		return { rootRef: this.rootRef, modes, groups: this.groups(), spCopy: rows(this.state.spec.copy), spComps: rows(this.state.spec.comps), spApi: rows(this.state.spec.api) }
 	}
 }
 </script>

docs/design/source/RenewCMS Screens Image variants.dc.html

@@ -0,0 +1,347 @@
+<!DOCTYPE html>
+<html>
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<script src="./support.js"></script>
+</head>
+<body>
+<x-dc>
+<helmet>
+<meta name="design_doc_mode" content="canvas">
+<link rel="icon" href="brand/favicon.svg">
+<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Sans:wght@400;500;600&family=IBM+Plex+Mono:wght@400;500&family=Source+Serif+4:ital,opsz,wght@0,8..60,400;0,8..60,600;1,8..60,400&display=swap" rel="stylesheet">
+<style>body{margin:0;font-family:'IBM Plex Sans',sans-serif;font-size:13px;line-height:20px}*{box-sizing:border-box}a{color:inherit;text-underline-offset:3px}a:hover{opacity:.8}code{font-family:'IBM Plex Mono',monospace;font-size:12px}</style>
+</helmet>
+<div ref="{{ rootRef }}" data-screen-label="Image variants" style="background:var(--rc-canvas);color:var(--ui-text);padding:64px;display:flex;flex-direction:column;gap:72px;width:max-content;min-width:100%">
+
+<div style="display:flex;align-items:flex-end;gap:32px;max-width:1400px">
+<div style="flex:1;display:flex;flex-direction:column;gap:10px">
+<h1 style="margin:0;font:600 36px/44px 'IBM Plex Sans',sans-serif;letter-spacing:-0.02em;color:var(--ui-text-highlighted)">Feature: Image variants</h1>
+<p style="margin:0;max-width:900px;font-size:16px;line-height:26px;color:var(--ui-text-toned);text-wrap:pretty">Named variants of an original image, requested as <code>/media/photo.png?v=thumb</code>. The original is never changed. Six screens in the AppFrame back-office frame, plus the request contract, activity log copy, states matrix, API error copy and component inventory. 1440 px at 50%, 390 px at 75%. The theme switch shows every state in dark mode. Related: <a href="RenewCMS Screens Back-office.dc.html">Back-office screens</a>.</p>
+</div>
+<div role="radiogroup" aria-label="Theme" style="display:flex;border:1px solid var(--ui-border-accented);background:var(--ui-bg)">
+<sc-for list="{{ modes }}" as="m" hint-placeholder-count="3">
+<button role="radio" aria-checked="{{ m.on }}" onClick="{{ m.pick }}" style="all:unset;cursor:pointer;height:36px;padding:0 14px;display:flex;align-items:center;font-weight:500;font-size:14px;background:{{ m.bg }};color:{{ m.fg }}" style-focus-visible="outline:2px solid var(--ui-primary);outline-offset:2px">{{ m.label }}</button>
+</sc-for>
+</div>
+</div>
+
+<sc-for list="{{ groups }}" as="g" hint-placeholder-count="6">
+<section data-screen-label="{{ g.label }}" style="display:flex;flex-direction:column;gap:28px">
+<div style="display:flex;flex-direction:column;gap:6px;max-width:1100px">
+<h2 style="margin:0;font:600 28px/36px 'IBM Plex Sans',sans-serif;color:var(--ui-text-highlighted)">{{ g.title }}</h2>
+<div style="display:flex;gap:16px;flex-wrap:wrap;font:400 14px/22px 'IBM Plex Mono',monospace;color:var(--ui-text-toned)"><span>{{ g.route }}</span><span style="color:var(--ui-text-muted)">{{ g.api }}</span></div>
+<p style="margin:4px 0 0;font-size:15px;line-height:24px;color:var(--ui-text-toned);text-wrap:pretty">{{ g.note }}</p>
+</div>
+<div style="display:flex;flex-wrap:wrap;gap:40px;align-items:flex-start">
+<sc-for list="{{ g.states }}" as="st" hint-placeholder-count="4">
+<div style="display:flex;flex-direction:column;gap:12px">
+<div style="display:flex;flex-direction:column;gap:2px;max-width:1040px"><span style="font:600 16px/24px 'IBM Plex Sans',sans-serif;color:var(--ui-text-highlighted)">{{ st.id }} · {{ st.name }}</span><span style="font-size:13px;color:var(--ui-text-muted)">{{ st.trigger }}</span></div>
+<div style="display:flex;gap:24px;align-items:flex-start">
+<div style="width:720px;height:450px;overflow:hidden;border:1px solid var(--ui-border);flex-shrink:0"><div style="width:1440px;height:900px;zoom:0.5"><dc-import name="VariantsFrame" s="{{ st.s }}" mobile="{{ false }}" hint-size="1440px,900px"></dc-import></div></div>
+<div style="width:293px;height:633px;overflow:hidden;border:1px solid var(--ui-border);flex-shrink:0"><div style="width:390px;height:844px;zoom:0.75"><dc-import name="VariantsFrame" s="{{ st.m }}" mobile="{{ true }}" hint-size="390px,844px"></dc-import></div></div>
+</div>
+</div>
+</sc-for>
+</div>
+<sc-for list="{{ g.tables }}" as="t" hint-placeholder-count="1">
+<div style="display:flex;flex-direction:column;gap:8px;max-width:1240px"><span style="font:600 16px/24px 'IBM Plex Sans',sans-serif;color:var(--ui-text-highlighted)">{{ t.title }}</span><div style="background:var(--ui-bg);border:1px solid var(--ui-border)"><div style="display:grid;grid-template-columns:{{ t.tpl }};padding:8px 12px;gap:16px;background:var(--ui-bg-elevated);color:var(--ui-text-muted);font-weight:500"><sc-for list="{{ t.cols }}" as="c" hint-placeholder-count="3"><span>{{ c }}</span></sc-for></div><sc-for list="{{ t.rows }}" as="r" hint-placeholder-count="3"><div style="display:grid;grid-template-columns:{{ t.tpl }};gap:16px;padding:10px 12px;border-top:1px solid var(--ui-border);line-height:20px"><sc-for list="{{ r }}" as="cell" hint-placeholder-count="3"><span style="color:{{ cell.fg }};font-weight:{{ cell.fw }};font-family:{{ cell.ff }};font-size:{{ cell.fs }};text-wrap:pretty;min-width:0">{{ cell.t }}</span></sc-for></div></sc-for></div></div>
+</sc-for>
+</section>
+</sc-for>
+
+<sc-for list="{{ specs }}" as="sp" hint-placeholder-count="5">
+<section data-screen-label="{{ sp.label }}" style="display:flex;flex-direction:column;gap:16px;max-width:1240px">
+<h2 style="margin:0;font:600 28px/36px 'IBM Plex Sans',sans-serif;color:var(--ui-text-highlighted)">{{ sp.title }}</h2>
+<p style="margin:0;font-size:15px;line-height:24px;color:var(--ui-text-toned);text-wrap:pretty">{{ sp.note }}</p>
+<sc-for list="{{ sp.tables }}" as="t" hint-placeholder-count="1">
+<div style="background:var(--ui-bg);border:1px solid var(--ui-border)"><div style="display:grid;grid-template-columns:{{ t.tpl }};padding:8px 12px;gap:16px;background:var(--ui-bg-elevated);color:var(--ui-text-muted);font-weight:500"><sc-for list="{{ t.cols }}" as="c" hint-placeholder-count="3"><span>{{ c }}</span></sc-for></div><sc-for list="{{ t.rows }}" as="r" hint-placeholder-count="3"><div style="display:grid;grid-template-columns:{{ t.tpl }};gap:16px;padding:10px 12px;border-top:1px solid var(--ui-border);line-height:20px"><sc-for list="{{ r }}" as="cell" hint-placeholder-count="3"><span style="color:{{ cell.fg }};font-weight:{{ cell.fw }};font-family:{{ cell.ff }};font-size:{{ cell.fs }};text-wrap:pretty;min-width:0">{{ cell.t }}</span></sc-for></div></sc-for></div>
+</sc-for>
+</section>
+</sc-for>
+
+</div>
+</x-dc>
+<script type="text/x-dc" data-dc-script data-props="{&quot;theme&quot;:{&quot;editor&quot;:&quot;enum&quot;,&quot;options&quot;:[&quot;system&quot;,&quot;light&quot;,&quot;dark&quot;],&quot;default&quot;:&quot;system&quot;,&quot;tsType&quot;:&quot;'system' | 'light' | 'dark'&quot;}}">
+class Component extends DCLogic {
+	state = { mode: this.props.theme ?? 'light' }
+	rootRef = React.createRef()
+	light = { '--ui-bg': '#ffffff', '--ui-bg-muted': '#fafafa', '--ui-bg-elevated': '#f3f2f0', '--ui-bg-accented': '#e6e4e0', '--ui-bg-inverted': '#111111', '--ui-text-dimmed': '#999999', '--ui-text-muted': '#666666', '--ui-text-toned': '#444444', '--ui-text': '#222222', '--ui-text-highlighted': '#111111', '--ui-text-inverted': '#ffffff', '--ui-border': '#e6e4e0', '--ui-border-muted': '#f3f2f0', '--ui-border-accented': '#8a8783', '--ui-primary': '#111111', '--ui-secondary': '#635643', '--ui-success': '#315b33', '--ui-info': '#34536d', '--ui-warning': '#6c4700', '--ui-error': '#882c21', '--rc-sand': '#e8dfd1', '--rc-on-sand': '#111111', '--rc-success-soft': '#eaefea', '--rc-info-soft': '#ebeef0', '--rc-warning-soft': '#f0ede6', '--rc-error-soft': '#f3eae9', '--rc-overlay': 'rgb(10 10 10 / 0.4)', '--rc-shadow-pop': '0 4px 16px rgb(17 17 17 / 0.08), 0 1px 2px rgb(17 17 17 / 0.06)', '--rc-shadow-modal': '0 16px 48px rgb(17 17 17 / 0.18)', '--rc-canvas': '#ecebe8' }
+	dark = { '--ui-bg': '#111111', '--ui-bg-muted': '#0a0a0a', '--ui-bg-elevated': '#1a1a1a', '--ui-bg-accented': '#222222', '--ui-bg-inverted': '#fafafa', '--ui-text-dimmed': '#666666', '--ui-text-muted': '#999999', '--ui-text-toned': '#cfccc7', '--ui-text': '#e6e4e0', '--ui-text-highlighted': '#fafafa', '--ui-text-inverted': '#111111', '--ui-border': '#333333', '--ui-border-muted': '#222222', '--ui-border-accented': '#666666', '--ui-primary': '#fafafa', '--ui-secondary': '#d4c5b0', '--ui-success': '#a3caa3', '--ui-info': '#a5c2db', '--ui-warning': '#dfb67d', '--ui-error': '#fba394', '--rc-sand': '#d4c5b0', '--rc-on-sand': '#111111', '--rc-success-soft': '#1f241f', '--rc-info-soft': '#202428', '--rc-warning-soft': '#2a251e', '--rc-error-soft': '#2c201f', '--rc-overlay': 'rgb(0 0 0 / 0.6)', '--rc-shadow-pop': '0 4px 16px rgb(0 0 0 / 0.5)', '--rc-shadow-modal': '0 16px 48px rgb(0 0 0 / 0.6)', '--rc-canvas': '#1c1c1c' }
+	resolved() {
+		if (this.state.mode === 'system') return window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light'
+		return this.state.mode
+	}
+	apply() {
+		const el = this.rootRef.current
+		if (!el) return
+		const vars = this.resolved() === 'dark' ? this.dark : this.light
+		for (const k in vars) el.style.setProperty(k, vars[k])
+		document.body.style.background = vars['--rc-canvas']
+	}
+	componentDidMount() { this.apply() }
+	componentDidUpdate(p) {
+		if (p.theme !== this.props.theme && this.props.theme) this.setState({ mode: this.props.theme })
+		this.apply()
+	}
+	cell(t, i, o = {}) { return { t, fg: i === 0 && !o.plain ? 'var(--ui-text-highlighted)' : o.muted ? 'var(--ui-text-muted)' : 'var(--ui-text-toned)', fw: i === 0 && !o.plain ? 500 : 400, ff: o.mono ? "'IBM Plex Mono',monospace" : "'IBM Plex Sans',sans-serif", fs: o.mono ? '12px' : '13px' } }
+	tbl(title, cols, tpl, rows, o = {}) { return { title, cols, tpl, rows: rows.map(r => r.map((t, i) => this.cell(t, i, { mono: o.mono && o.mono.includes(i), muted: t === '–' }))) } }
+	groups() {
+		const st = (id, name, trigger, s, ms = {}) => ({ id, name, trigger, s, m: { ...s, ...ms } })
+		const LB = { nav: 'settings', crumbs: ['Settings', 'Media', 'Variants'], mTitle: 'Variants' }
+		const CB = { nav: 'settings', crumbs: ['Settings', 'Media', 'Cache'], mTitle: 'Cache' }
+		const MB = { nav: 'media', crumbs: ['Media'], mTitle: 'Media' }
+		const l = (list, o = {}) => ({ kind: 'list', ...LB, list, ...o })
+		const cr = { mode: 'create', fit: 'cover', pos: 50 }
+		const hero = { ...cr, name: 'hero', w: '1200', h: '630', fmt: 'WebP', q: 82, qv: 82, gen: true, en: true, out: '1200×630', est: '96 KB' }
+		const ed = (e, o = {}) => ({ kind: 'edit', ...LB, ed: e, ...o })
+		const ET = this.tbl.bind(this)
+		const C3 = ['State', 'Where', 'Copy']
+		const T3 = '210px 260px minmax(0,1fr)'
+		const tb = (title, rows) => ET(title, C3, T3, rows)
+		return [
+			{ label: 'Variants list', title: '1. Settings → Media → Variants', route: '/settings/media/variants', api: 'GET /v1/image-variants · PATCH /v1/image-variants/{name} · DELETE /v1/image-variants/{name} · POST /v1/image-variants/{name}/purge (proposed)', note: 'Admin-only page under Settings → Media, with two tabs: Variants and Cache. Desktop shows a table; mobile stacks each variant as a card. The status switch always pairs with an icon and the words Enabled or Disabled. The reference card "How requests are handled" sits under the table (section 7 of the brief).',
+				states: [
+					st('1a', 'Loaded', 'Six variants, one of them disabled (print).', l({})),
+					st('1b', 'Loading', 'Skeleton rows appear after 150 ms.', l({ state: 'loading' })),
+					st('1c', 'Empty', 'No variants. Two templates pre-fill the Add variant form.', l({ state: 'empty' })),
+					st('1d', 'Error loading', 'A 500 or network failure on the list request.', l({ state: 'error' })),
+					st('1e', 'Forbidden', 'A signed-in user who is not an admin opens the URL.', { kind: 'list', ...LB, nav: null, role: 'user', forbidden: true }),
+					st('1f', 'Row menu', 'The ellipsis button on a row.', l({ menu: 2 })),
+					st('1g', 'Row action in progress', 'Purge cache was confirmed on hero. The row is dimmed and its controls are disabled.', l({ busy: 2 })),
+					st('1h', 'Purge confirm', 'Purge cache in the row menu.', l({}, { modal: 'purgeVariant' })),
+					st('1i', 'Delete confirm', 'Delete in the row menu.', l({}, { modal: 'deleteVariant' })),
+					st('1j', 'Delete in progress', 'Delete was confirmed. The button shows a spinner.', l({}, { modal: 'deleteVariant', loadingModal: true })),
+					st('1l', 'Entry: sidebar', 'From any page, Settings expands in the sidebar to Media: Variants and Cache. Admin only. On mobile the menu button opens it as a drawer.', { kind: 'media', ...MB, sideOpen: true, ml: {}, drawer: true }),
+					st('1k', 'Request reference', 'Mobile scrolled to the reference card. On desktop it is visible below the table.', l({}), { scroll: 900 })
+				],
+				tables: [tb('Copy: Variants list', [
+					['Header', 'Title, description, button', 'Image variants · Named sizes and formats generated from your original images. Originals are never changed. · Add variant'],
+					['Table columns', 'Header row', 'Name · Dimensions · Fit · Format · Quality · Generated · Cache size · Status'],
+					['Dimensions', 'Cell', '400×300 · 800 × auto · auto × 2400'],
+					['Quality', 'Cell', '80 · — (PNG has no quality)'],
+					['Status', 'Switch + text', 'Enabled · Disabled (aria-label: "Enable variant hero")'],
+					['Row menu', 'Menu items', 'Edit · Purge cache · Delete'],
+					['Footer summary', 'Under the table', '6 variants · 1,284 generated files · 212 MB'],
+					['Footer summary (singular)', 'One variant', '1 variant · 1 generated file · 18 KB'],
+					['Loading', 'Skeleton', 'No text. Region announces "Loading variants".'],
+					['Empty', 'Title · text', 'No variants yet · A variant is a named size that an image can be requested in, like ?v=thumb. Start with one of these.'],
+					['Empty', 'Template cards', 'thumb · 400×300 · cover · WebP — hero · 1200×630 · cover · WebP — Use template'],
+					['Error', 'Alert', 'Couldn\'t load variants · Check your connection and try again. · Try again'],
+					['Forbidden', 'Title · text · button', 'You don\'t have access · Only admins can manage image variants. Ask an admin if you need one changed. · Back to Home'],
+					['Row in progress', 'Status cell', 'Purging…'],
+					['Purge success', 'Toast', 'Purged 244 files from “hero”'],
+					['Purge dialog', 'Title · text · buttons', 'Purge cache for “hero”? · This removes 244 generated files (84 MB). Files are generated again on the next request. · Cancel · Purge 244 files'],
+					['Delete dialog', 'Title · text · buttons', 'Delete variant “hero”? · This removes the variant and its 244 generated files (84 MB). Articles that use ?v=hero will start returning 400. This can\'t be undone. · Cancel · Delete variant'],
+					['Delete success', 'Toast', 'Variant “hero” deleted'],
+					['Request reference', 'Card', 'How requests are handled · Body of a 400 response · unsupported_parameter replaces unknown_variant when a raw parameter is sent. There is no arbitrary-size mode.']
+				])]
+			},
+			{ label: 'Add edit variant', title: '2. Add / edit variant', route: 'Slide-over on desktop · full page on mobile', api: 'POST /v1/image-variants · PUT /v1/image-variants/{name}', note: 'Form on the left, live preview on the right (stacked on mobile). The preview uses a sample image with a before/after divider. The divider is a slider: arrow keys move it by 1%, Shift+arrow by 10%, Home and End jump to the ends. Name is locked in edit mode. The edit warning is always visible in edit mode. Preview images are placeholders.',
+				states: [
+					st('2a', 'Create: pristine', 'Add variant just opened. Save is disabled.', ed({ ...cr, name: '', w: '', h: '', fmt: 'Original', q: 80, qv: 80, gen: false, en: true, disSave: true, focusName: true })),
+					st('2b', 'Create: dirty', 'Valid values. The divider has keyboard focus. Mobile is scrolled to the preview.', ed({ ...hero, dirty: true, focus: true }), { scroll: 560 }),
+					st('2c', 'Field errors', 'On blur and on submit. Name format, width above 8000, quality above 100.', ed({ ...cr, name: 'Hero banner', w: '9000', h: '630', fmt: 'WebP', q: 140, qv: 100, gen: false, en: true, dirty: true, err: { name: 'Use lowercase letters, numbers and dashes, 2 to 32 characters.', w: 'Enter a value from 1 to 8000.', q: 'Enter a value from 1 to 100.' } })),
+					st('2d', 'No dimension', 'Width and height are both empty on submit.', ed({ ...cr, name: 'banner', w: '', h: '', fmt: 'WebP', q: 80, qv: 80, gen: false, en: true, dirty: true, err: { dim: 'Set a width, a height, or both.' } })),
+					st('2e', 'Name already taken', 'POST returns 409.', ed({ ...hero, name: 'thumb', w: '400', h: '300', out: '400×300', est: '18 KB', dirty: true, err: { name: 'A variant named “thumb” already exists. Choose another name.' } })),
+					st('2f', 'Saving', 'Request in flight. Fields and buttons are disabled.', ed({ ...hero, dirty: true, saving: true })),
+					st('2g', 'Save error', 'A 500 or network failure. Values are kept.', ed({ ...hero, dirty: true, saveErr: true })),
+					st('2h', 'Edit: pristine', 'Opened from Edit. Name is locked. Save is disabled.', ed({ ...hero, mode: 'edit', files: 244, disSave: true })),
+					st('2i', 'Edit: dirty', 'Quality changed from 82 to 70.', ed({ ...hero, mode: 'edit', files: 244, q: 70, qv: 70, est: '71 KB', dirty: true })),
+					st('2j', 'Unsaved changes', 'Close, Cancel or Escape while dirty.', ed({ ...hero, mode: 'edit', files: 244, q: 70, qv: 70, est: '71 KB', dirty: true }, { modal: 'discard' })),
+					st('2k', 'PNG: no quality', 'Quality is hidden when the format is PNG.', ed({ ...hero, fmt: 'PNG', est: '310 KB', dirty: true }))
+				],
+				tables: [tb('Copy: Add / edit variant', [
+					['Titles', 'Slide-over header', 'Add variant · Edit variant: hero'],
+					['Name', 'Label · placeholder · help', 'Name · e.g. hero · Lowercase letters, numbers and dashes. Can\'t be changed later.'],
+					['Name (edit)', 'Help', 'The name can\'t be changed.'],
+					['Name error: format', 'Inline', 'Use lowercase letters, numbers and dashes, 2 to 32 characters.'],
+					['Name error: taken', 'Inline', 'A variant named “thumb” already exists. Choose another name.'],
+					['Width · Height', 'Label · suffix · placeholder · help', 'Width · Height · px · auto · Set a width, a height, or both. 1–8000 px. Images are never enlarged.'],
+					['Dimension error', 'Inline', 'Set a width, a height, or both.'],
+					['Dimension range error', 'Inline', 'Enter a value from 1 to 8000.'],
+					['Fit', 'Options · help', 'Cover: Fills the box and crops what overflows. · Contain: Whole image inside the box, padded to the box size. · Inside: Whole image inside the box, no padding.'],
+					['Format', 'Options · help', 'Original · JPEG · PNG · WebP · Keeps the format of each source image.'],
+					['Quality', 'Label · help · error', 'Quality · 1–100. Higher is sharper and larger. · Enter a value from 1 to 100.'],
+					['Toggles', 'Label · help', 'Generate on upload: Creates this variant when an image is uploaded. · Enabled: Disabled variants return 400 on the public site.'],
+					['Edit warning', 'Alert (edit only)', 'Changing dimensions, fit, format or quality purges 244 generated files; they will be regenerated on next request.'],
+					['Preview', 'Heading · labels · hint', 'Preview · Sample: north-wall.jpg · Original — 4032 × 3024 · 3.9 MB · hero — 1200×630 · about 96 KB · Drag the divider, or focus it and use the arrow keys. The estimate comes from a sample; output is never larger than the source.'],
+					['Preview (no size)', 'Over the image', 'Set a width or height to see a preview.'],
+					['Slider', 'aria-label · aria-valuetext', 'Compare original and hero · 50% hero'],
+					['URL', 'Label · button', 'URL · /media/north-wall.jpg?v=hero · Copy · Copied'],
+					['Footer', 'Status · buttons', 'Unsaved changes · Cancel · Add variant · Save changes · Saving…'],
+					['Save error', 'Alert', 'Couldn\'t save the variant · Check your connection and try again. · Try again'],
+					['Save success', 'Toast', 'Variant “hero” added · Variant “hero” saved. 244 files purged.'],
+					['Unsaved dialog', 'Title · text · buttons', 'Discard changes? · You have unsaved changes to “hero”. If you close now, they\'re lost. · Keep editing · Discard changes']
+				])]
+			},
+			{ label: 'Media library', title: '3. Media library', route: '/media', api: 'GET /v1/media?variants=with|without&sort=total_size (proposed)', note: 'The existing grid with three additions: a "N variants" badge on cards that have cached files, an All / With variants / Without filter, and the sort option "Largest total size (original + variants)". When sorted by total size, the meta line shows the total.',
+				states: [
+					st('3a', 'Grid with badges', 'Default view. Images with no cached variants have no badge.', { kind: 'media', ...MB, ml: { ann: 'New: badge' } }),
+					st('3b', 'Sort menu', 'The sort select is open. The new option is last.', { kind: 'media', ...MB, ml: { menu: true, sort: 'total', ann: 'New: sort option' } }),
+					st('3c', 'Filter: With variants, sorted by total size', 'The meta line becomes total · original + variants.', { kind: 'media', ...MB, ml: { filter: 'With variants', sort: 'total', ids: [1, 7, 9, 12, 5, 11, 2, 3, 10] } }),
+					st('3d', 'Filter: Without variants', 'Images no variant has been generated for.', { kind: 'media', ...MB, ml: { filter: 'Without', ids: [4, 6, 8] } }),
+					st('3e', 'Filter: nothing to show', 'With variants, and the cache is empty.', { kind: 'media', ...MB, ml: { filter: 'With variants', empty: true } }),
+					st('3f', 'Delete confirm', 'Delete on an image that has cached variants.', { kind: 'media', ...MB, ml: {}, modal: 'deleteImage' })
+				],
+				tables: [tb('Copy: Media library additions', [
+					['Badge', 'Card', '4 variants · 1 variant'],
+					['Filter', 'Segmented control', 'All · With variants · Without'],
+					['Sort', 'Select, new option', 'Largest total size (original + variants) · mobile label: Largest total size'],
+					['Meta line (sorted by total)', 'Card', '4.2 MB total · 3.9 MB + 260 KB'],
+					['Empty filter', 'Title · text · button', 'No images with variants · Variants are generated when an image is requested with ?v=<name>, or from its Variants tab. · Show all images'],
+					['Delete dialog', 'Title · text · note · buttons', 'Delete this image? · "north-wall.jpg" is used in 2 articles. If you delete it, they will show a broken image. This can\'t be undone. · Also removes 4 generated variants (260 KB) · Cancel · Delete image'],
+					['Bulk delete', 'Dialog line', 'Also removes 11 generated variants (1.1 MB)']
+				])]
+			},
+			{ label: 'Image detail', title: '4. Image detail: Variants tab', route: '/media (detail panel)', api: 'GET /v1/media/{id}/variants · POST /v1/media/{id}/variants/{name} · DELETE /v1/media/{id}/variants/{name} (proposed)', note: 'The detail panel gets a Variants tab with one row per enabled variant. On desktop the row actions are icon buttons with tooltips and accessible names; on mobile they are labeled buttons on their own line. Only actions that apply are shown: generated rows offer Copy URL, Preview and Purge; others offer Copy URL and Generate now. The tab shows output dimensions as they will be generated, capped at the source size.',
+				states: [
+					st('4a', 'Partly generated', 'Four of five generated. Saving is shown against the original.', { kind: 'detail', ...MB, dt: { rows: ['gen', 'gen', 'gen', 'gen', 'none'] } }),
+					st('4b', 'Nothing generated yet', 'No cached files for this image.', { kind: 'detail', ...MB, dt: {} }),
+					st('4c', 'Generating', 'Generate all or Generate now was pressed. Rows show a spinner.', { kind: 'detail', ...MB, dt: { rows: ['gen', 'busy', 'busy', 'none', 'none'] } }),
+					st('4d', 'Generation failed', 'The row shows the cause and Retry. Both causes are shown together for reference.', { kind: 'detail', ...MB, dt: { rows: ['gen', 'fail', 'fail', 'gen', 'gen'], cause: [0, 'Unsupported source format', 'Image too large'] } }),
+					st('4e', 'No variants defined', 'There are no enabled variants.', { kind: 'detail', ...MB, dt: { none: true } }),
+					st('4f', 'Source is an SVG', 'Variants aren\'t generated for vector images.', { kind: 'detail', ...MB, dt: { id: 4, nofmt: 'SVG images are served as they are.' } }),
+					st('4g', 'Source is an animated GIF', 'Same rule as SVG.', { kind: 'detail', ...MB, dt: { id: 4, nofmt: 'Animated GIFs are served as they are.' } }),
+					st('4h', 'Preview dialog', 'Preview on a generated row. Both at actual size.', { kind: 'detail', ...MB, dt: { rows: ['gen', 'gen', 'gen', 'gen', 'none'], preview: true } })
+				],
+				tables: [tb('Copy: Variants tab', [
+					['Tabs', 'Panel', 'Details · Variants'],
+					['Original', 'Header block', 'Original · kept untouched · north-wall.jpg · JPEG · 4032 × 3024 · 3.9 MB'],
+					['Summary', 'Above the list', '4 of 5 generated · Nothing generated yet. · Generating variants…'],
+					['Generate all', 'Button', 'Generate all · Generating…'],
+					['Row status', 'Badge', 'Generated · Not generated · Generating · Failed'],
+					['Row meta (generated)', 'Under the name', '400×300 · WebP · 18 KB · -99% vs original'],
+					['Row meta (not generated)', 'Under the name', '400×300 · WebP'],
+					['Row actions', 'Tooltip · aria-label', 'Copy URL · Preview · Generate now · Purge · Retry'],
+					['Failed: cause', 'Row line', 'Unsupported source format · Image too large'],
+					['No variants defined', 'Title · text · link', 'No variants defined · Define a variant in Settings to get resized copies of this image. · Settings → Media → Variants'],
+					['SVG / GIF', 'Alert', 'Variants aren\'t generated for this format. · SVG images are served as they are. · Animated GIFs are served as they are.'],
+					['Preview dialog', 'Title · panes · hint', 'Preview: thumb · thumb · 400×300 · WebP — 18 KB · saves 99% · Original · 4032×3024 · JPEG — 3.9 MB · Both images are shown at actual size. Scroll to pan. · Close'],
+					['Toasts', 'After actions', 'Generated 5 variants · Generated thumb · Purged 4 files (260 KB) · Couldn\'t generate hero. Image too large.']
+				])]
+			},
+			{ label: 'Cache panel', title: '5. Settings → Media → Cache', route: '/settings/media/cache', api: 'GET /v1/image-variants/cache · POST /v1/image-variants/cache/purge {scope: all|unused|variant|image} (proposed)', note: 'Stat tiles, a per-variant bar list (bar length is the disk size relative to the largest variant) and the ten images with the most variant disk usage. Purge all needs the word "purge" typed. Purge unused removes files of enabled variants not requested in 30 days.',
+				states: [
+					st('5a', 'Loaded', 'Default view.', { kind: 'cache', ...CB }),
+					st('5b', 'Loading', 'Tiles and lists show skeletons.', { kind: 'cache', ...CB, cache: { state: 'loading' } }),
+					st('5c', 'Empty cache', 'Nothing generated. Purge buttons are disabled.', { kind: 'cache', ...CB, cache: { state: 'empty' } }),
+					st('5d', 'Purging', 'Progress for a purge in progress. Content is dimmed.', { kind: 'cache', ...CB, cache: { state: 'purging' } }),
+					st('5e', 'Purge done', 'The cache is empty and a toast reports the result.', { kind: 'cache', ...CB, cache: { state: 'empty' }, toasts: [['success', 'circle-check', 'Purged 1,284 files, freed 212 MB', '']] }),
+					st('5f', 'Purge failed', 'Part of the purge did not complete.', { kind: 'cache', ...CB, toasts: [['error', 'circle-x', 'Purge didn\'t finish', '640 of 1,284 files were removed. Try again.', 'Try again']] }),
+					st('5g', 'Error loading', 'A 500 or network failure.', { kind: 'cache', ...CB, cache: { state: 'error' } }),
+					st('5h', 'Purge all: confirm', 'The word is not typed yet. The button is disabled.', { kind: 'cache', ...CB, modal: 'purgeAll' }),
+					st('5i', 'Purge all: confirm, typed', 'The input matches "purge".', { kind: 'cache', ...CB, modal: 'purgeAllOk' }),
+					st('5j', 'Purge unused: confirm', 'Variants of enabled variants not requested for 30 days.', { kind: 'cache', ...CB, modal: 'purgeUnused' })
+				],
+				tables: [tb('Copy: Cache panel', [
+					['Header', 'Title · text · buttons', 'Cache · Generated variant files. Purged files are generated again on the next request. · Purge unused · Purge all variants'],
+					['Tiles', 'Label · sub text', 'Generated files · Across 6 variants — Disk used · Originals not included — Variants defined · 5 enabled, 1 disabled — Rejected requests · Last 7 days'],
+					['Bar list', 'Heading · row', 'By variant · hero 244 files · 84 MB · Disabled (badge on disabled variants)'],
+					['Top 10', 'Heading · row · button', 'Top 10 images by variant disk usage · north-wall.jpg · 6 variants · 5.8 MB · Purge'],
+					['Empty cache', 'Title · text', 'Nothing generated yet · Variants are generated on the first request with ?v=<name>, or from an image\'s Variants tab.'],
+					['Purging', 'Banner', 'Purging 1,284 files · 640 of 1,284 · 106 MB freed'],
+					['Purge done', 'Toast', 'Purged 1,284 files, freed 212 MB'],
+					['Purge failed', 'Toast', 'Purge didn\'t finish · 640 of 1,284 files were removed. Try again. · Try again'],
+					['Error', 'Alert', 'Couldn\'t load cache stats · Check your connection and try again. · Try again'],
+					['Purge all dialog', 'Title · text · field · buttons', 'Purge all variants? · This removes 1,284 generated files (212 MB) for every variant. Originals aren\'t touched. Files are generated again on request. · Type purge to confirm · Cancel · Purge all variants'],
+					['Purge unused dialog', 'Title · text · buttons', 'Purge unused variants? · This removes 312 files (41 MB) from enabled variants that haven\'t been requested for 30 days. Files are generated again on request. · Cancel · Purge 312 files'],
+					['Purge image (row)', 'Toast', 'Purged 6 files (5.8 MB) for north-wall.jpg']
+				])]
+			},
+			{ label: 'Editor picker', title: '6. Editor image picker', route: '/articles/{id}/edit', api: 'Inserted URL: /media/{file}?v={name}', note: 'The Library tab of the picker gets a Variant select. Options are Original plus the enabled variants, each with its dimensions and format. Once inserted, a block whose variant was deleted or disabled shows an inline warning with a way to fix it. Disabled variants do not appear in the select.',
+				states: [
+					st('6a', 'Variant select', 'An image is selected. The URL line shows what will be inserted.', { kind: 'editor', nav: 'articles', crumbs: ['Articles', 'How we price a bathroom renovation'], mTitle: 'Edit article', back: true, edr: { picker: true, cur: 3 } }),
+					st('6b', 'Select open', 'Original plus five enabled variants.', { kind: 'editor', nav: 'articles', crumbs: ['Articles', 'How we price a bathroom renovation'], mTitle: 'Edit article', back: true, edr: { picker: true, cur: 3, open: true } }),
+					st('6c', 'No variants defined', 'Only Original is offered.', { kind: 'editor', nav: 'articles', crumbs: ['Articles', 'How we price a bathroom renovation'], mTitle: 'Edit article', back: true, edr: { picker: true, none: true } }),
+					st('6d', 'Variant deleted', 'The block keeps its URL. Pick another variant opens the select.', { kind: 'editor', nav: 'articles', crumbs: ['Articles', 'How we price a bathroom renovation'], mTitle: 'Edit article', back: true, edr: { block: true, msg: 'Variant \'hero\' no longer exists.' } }),
+					st('6e', 'Variant disabled', 'Same block, different cause. Proposed copy.', { kind: 'editor', nav: 'articles', crumbs: ['Articles', 'How we price a bathroom renovation'], mTitle: 'Edit article', back: true, edr: { block: true, msg: 'Variant \'hero\' is disabled.' } })
+				],
+				tables: [tb('Copy: Editor picker', [
+					['Select', 'Label', 'Variant'],
+					['Options', 'Option label', 'Original · 4032×3024 · JPEG — Thumb · 400×300 · WebP — Card · 800 × auto · WebP — Hero · 1200×630 · WebP — Square · 600×600 · JPEG — Og · 1200×630 · JPEG'],
+					['URL line', 'Under the select', '/media/north-wall.jpg?v=hero'],
+					['No variants', 'Help', 'No variants defined. Add one in Settings → Media → Variants.'],
+					['Block warning: deleted', 'Inline warning', 'Variant \'hero\' no longer exists. This image returns an error on the public site. · Pick another variant'],
+					['Block warning: disabled', 'Inline warning (proposed)', 'Variant \'hero\' is disabled. This image returns an error on the public site. · Pick another variant'],
+					['Block label', 'Chip on the image', 'hero · 1200×630']
+				])]
+			}
+		]
+	}
+	specs() {
+		const T = (cols, tpl, rows, o = {}) => ({ cols, tpl, rows: rows.map(r => r.map((t, i) => this.cell(t, i, { mono: o.mono && o.mono.includes(i), muted: t === '–' }))) })
+		return [
+			{ label: 'Request contract', title: '7. Public request contract', note: 'Shown as the "How requests are handled" card in section 1. Only variants that exist and are enabled are served. There is no arbitrary-size mode.', tables: [T(['Request', 'Status', 'Body or result'], '320px 80px minmax(0,1fr)', [
+				['/media/photo.png?v=thumb', '200', 'The cached image. Generated on first request.'],
+				['/media/photo.png?v=unknown', '400', 'Unknown variant'],
+				['/media/photo.png?v=hero (disabled)', '400', 'Unknown variant'],
+				['/media/photo.png?width=400', '400', 'Unsupported parameter'],
+				['height, format or quality parameters', '400', 'Unsupported parameter'],
+				['/media/missing.png?v=thumb', '404', 'Not found'],
+				['400 body shape', '', '{ "status": 400, "error": "unknown_variant" | "unsupported_parameter", "message": "Unknown variant", "detail": "banner" }']
+			], { mono: [0] })] },
+			{ label: 'Activity log', title: '8. Activity log entries', note: 'Row copy for the existing activity log. The actor name is bold, the quoted name is the variant name, and the detail line is secondary text.', tables: [T(['Event', 'Row copy', 'Detail line'], '220px minmax(0,1fr) minmax(0,1fr)', [
+				['Variant created', 'Marta Alves created variant “hero”', '1200×630 · cover · WebP · quality 82'],
+				['Variant updated', 'Marta Alves updated variant “hero”', 'Quality 82 → 70 · purged 244 files'],
+				['Variant deleted', 'Marta Alves deleted variant “hero”', 'Removed 244 generated files (84 MB)'],
+				['Variant enabled', 'Marta Alves enabled variant “hero”', 'Requests for ?v=hero are served'],
+				['Variant disabled', 'Marta Alves disabled variant “hero”', 'Requests for ?v=hero return 400'],
+				['Cache purged: all', 'Marta Alves purged all variants', 'Removed 1,284 files (212 MB)'],
+				['Cache purged: unused', 'Marta Alves purged unused variants', 'Removed 312 files (41 MB) not requested for 30 days'],
+				['Cache purged: by variant', 'Marta Alves purged the cache of variant “hero”', 'Removed 244 files (84 MB)'],
+				['Cache purged: by image', 'Marta Alves purged the variants of north-wall.jpg', 'Removed 4 files (260 KB)'],
+				['Generate all', 'Marta Alves generated all variants of north-wall.jpg', '5 variants generated'],
+				['Generate all, with a failure', 'Marta Alves generated all variants of north-wall.jpg', '4 generated · 1 failed (Image too large)'],
+				['Image deleted', 'Marta Alves deleted north-wall.jpg', 'Also removed 4 generated variants (260 KB)']
+			])] },
+			{ label: 'States matrix', title: 'States matrix', note: 'Frame: a numbered state above. Copy: covered by the copy tables, with no separate frame. Existing: unchanged behavior of the existing screen.', tables: [T(['Screen', 'Loaded', 'Empty', 'Loading', 'Error', 'Forbidden', 'In progress', 'Confirm', 'Validation', 'Success'], '190px repeat(9, minmax(0,1fr))', [
+				['1 Variants list', 'Frame 1a', 'Frame 1c', 'Frame 1b', 'Frame 1d', 'Frame 1e', 'Frame 1g, 1j', 'Frame 1h, 1i', '–', 'Copy'],
+				['2 Add / edit', 'Frame 2a, 2h', '–', '–', 'Frame 2g', 'Copy', 'Frame 2f', 'Frame 2j', 'Frame 2c, 2d, 2e', 'Copy'],
+				['3 Media library', 'Frame 3a', 'Frame 3e', 'Existing', 'Existing', '–', '–', 'Frame 3f', '–', '–'],
+				['4 Image detail', 'Frame 4a', 'Frame 4b, 4e, 4f, 4g', 'Existing', 'Frame 4d', '–', 'Frame 4c', '–', '–', 'Copy'],
+				['5 Cache', 'Frame 5a', 'Frame 5c', 'Frame 5b', 'Frame 5g, 5f', 'Copy', 'Frame 5d', 'Frame 5h, 5i, 5j', 'Frame 5h, 5i', 'Frame 5e'],
+				['6 Editor picker', 'Frame 6a, 6b', 'Frame 6c', 'Existing', 'Frame 6d, 6e', '–', '–', '–', '–', '–']
+			])] },
+			{ label: 'API errors', title: 'Back-office API errors', note: 'Shown as a toast, or inline where a field is named. The first line is the title, the second the text. The public media URL does not use these; see section 7.', tables: [T(['Status', 'Title', 'Text', 'Where it shows'], '70px 200px minmax(0,1fr) 260px', [
+				['400', 'Check the request', 'A value in the request isn\'t valid. Reload the page and try again.', 'Toast'],
+				['401', 'Session expired', 'Sign in again to continue.', 'Redirect to sign in, then a toast'],
+				['403', 'You don\'t have access', 'Only admins can manage image variants.', 'Toast, or the forbidden state on the list'],
+				['404', 'Not found', 'This variant or image no longer exists. Refresh the page.', 'Toast'],
+				['409', 'Name already taken', 'A variant named “thumb” already exists. Choose another name.', 'Inline under Name'],
+				['413', 'Image too large', 'The source image is too large to generate this variant.', 'Row cause in the Variants tab'],
+				['422', 'Check the fields', 'Width and height must be between 1 and 8000, and one of them is required.', 'Inline under each field'],
+				['500', 'Something went wrong', 'The server couldn\'t finish. Try again. If it keeps happening, check the server log.', 'Alert or toast with Try again']
+			], { mono: [0] })] },
+			{ label: 'Component inventory', title: 'Component inventory', note: 'Existing components are reused as they are. New components are built on Nuxt UI parts and use only existing tokens. Every icon-only button needs an aria-label and a UTooltip.', tables: [T(['Component', 'Status', 'Nuxt UI mapping', 'Notes'], '190px 80px 300px minmax(0,1fr)', [
+				['Variants table', 'New', 'UTable', 'Cell slots for the status switch and actions. Below 640 px it renders as a list of UCard.'],
+				['Variant row (settings, mobile)', 'New', 'UCard + USwitch + UDropdownMenu', 'Name, spec line, counts, status switch and menu.'],
+				['Variant row (image detail)', 'New', 'UBadge + UButton + UTooltip', 'Status badge, meta line, contextual actions, error line. Spinner uses UIcon.'],
+				['Variant form', 'New', 'UForm, UFormField, UInput, USelect, USlider, USwitch, URadioGroup', 'Fit is a URadioGroup, horizontal, 3 options. Quality hides when the format is PNG.'],
+				['Slide-over / full page', 'New', 'USlideover (desktop) · routed page (mobile)', 'Close with unsaved changes opens the discard UModal.'],
+				['Split comparison slider', 'New', 'No match. Custom ImageCompare on a native range input', 'Two stacked images, clip-path on the top one. role="slider", arrow keys 1%, Shift 10%, Home and End. Handle ≥ 44 px on touch.'],
+				['Stat tile', 'New', 'UCard (default slot)', 'Icon, label, value, sub text. Skeleton uses USkeleton.'],
+				['Bar list', 'New', 'UProgress per row', 'Row with name, stats and a bar. Value is disk size over the largest variant.'],
+				['Top-N list', 'New', 'UCard + list rows + UButton', 'Thumbnail, name, count, size, Purge.'],
+				['Type-to-confirm dialog', 'New', 'UModal + UInput', 'Confirm button disabled until the input equals "purge".'],
+				['Variant select', 'New', 'USelectMenu', 'Item slot shows name, dimensions, format. Only enabled variants.'],
+				['Variants badge', 'New', 'UBadge (outline, icon layers)', 'Shown on media cards when count > 0.'],
+				['Filter', 'New', 'UTabs (variant link) or UButtonGroup', 'All, With variants, Without.'],
+				['Request reference card', 'New', 'UCard + code block', 'Table of responses and a JSON body.'],
+				['Alerts, toasts, dialogs, empty states, skeletons', 'Existing', 'UAlert, useToast, UModal, UEmpty pattern, USkeleton', 'Same copy patterns as the Media and API keys screens.']
+			])] },
+			{ label: 'Vocabulary and accessibility', title: 'Vocabulary and accessibility', note: 'Use "variant", "generated" and "purge" everywhere. Never "thumbnail preset", "version" or "rendition". Delete removes a variant definition; purge removes only its generated files. Every status is an icon plus text: Generated (circle-check), Not generated (circle-dashed), Generating (loader), Failed (circle-x), Enabled (circle-check), Disabled (circle-off). The comparison slider has a visible focus ring and works from the keyboard. Dialogs trap focus and return it to the opener. Progress is announced with aria-live="polite". Touch targets on mobile are at least 44 px. The only token not already in the system is --rc-on-sand (dark ink on the sand selection color), used for the active nav item in both themes.', tables: [] }
+		]
+	}
+	renderVals() {
+		const modes = [['system', 'System'], ['light', 'Light'], ['dark', 'Dark']].map(([k, label]) => {
+			const on = this.state.mode === k
+			return { label, on, bg: on ? 'var(--ui-primary)' : 'transparent', fg: on ? 'var(--ui-bg)' : 'var(--ui-text-toned)', pick: () => this.setState({ mode: k }) }
+		})
+		return { rootRef: this.rootRef, modes, groups: this.groups(), specs: this.specs() }
+	}
+}
+</script>
+</body>
+</html>

docs/design/source/VariantsFrame.dc.html

@@ -0,0 +1,334 @@
+<!DOCTYPE html>
+<html>
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<script src="./support.js"></script>
+</head>
+<body>
+<x-dc>
+<div style="display:contents">{{ view }}</div>
+</x-dc>
+<script type="text/x-dc" data-dc-script>
+class Component extends DCLogic {
+	renderVals() {
+		const s = this.props.s || {}, m = !!this.props.mobile, h = React.createElement
+		const P = t => Object.fromEntries(t.split(';').filter(x => x.trim()).map(x => { const i = x.indexOf(':'); const k = x.slice(0, i).trim(); return [k.startsWith('--') ? k : k.replace(/-([a-z])/g, (_, c) => c.toUpperCase()), x.slice(i + 1).trim()] }))
+		const D = (t, ...c) => h('div', { style: P(t) }, ...c)
+		const S = (t, ...c) => h('span', { style: P(t) }, ...c)
+		const I = (n, z = 16, t = '') => h('span', { 'aria-hidden': 'true', style: { display: 'inline-block', flexShrink: 0, width: z, height: z, backgroundColor: 'currentColor', WebkitMask: 'url(https://api.iconify.design/lucide/' + n + '.svg) center / contain no-repeat', mask: 'url(https://api.iconify.design/lucide/' + n + '.svg) center / contain no-repeat', ...(t ? P(t) : {}) } })
+		const MONO = "font-family:'IBM Plex Mono',monospace"
+		const bh = m ? 44 : 32
+		const B = (label, o = {}) => {
+			const k = o.k || 'outline'
+			const bg = k === 'primary' ? 'var(--ui-primary)' : k === 'danger' ? 'var(--ui-error)' : k === 'ghost' ? 'transparent' : 'var(--ui-bg)'
+			const fg = k === 'primary' || k === 'danger' ? 'var(--ui-bg)' : k === 'del' ? 'var(--ui-error)' : 'var(--ui-text-highlighted)'
+			const bd = k === 'primary' || k === 'danger' ? bg : k === 'ghost' ? 'transparent' : k === 'del' ? 'var(--ui-error)' : 'var(--ui-border-accented)'
+			const ht = o.h || bh
+			return S('height:' + ht + 'px;' + (o.sq ? 'width:' + ht + 'px;' : 'padding:0 ' + (o.px || 12) + 'px;') + 'display:flex;align-items:center;justify-content:center;gap:6px;background:' + bg + ';color:' + fg + ';border:1px solid ' + bd + ';font-weight:500;font-size:' + (o.fs || 13) + 'px;white-space:nowrap;flex-shrink:0;opacity:' + (o.dis ? 0.4 : 1) + ';' + (o.full ? 'flex:1;' : '') + (o.ring ? 'outline:2px solid var(--ui-primary);outline-offset:2px;' : ''), o.icon && I(o.icon, o.z || 16), label)
+		}
+		const TONES = ['var(--rc-sand)', 'var(--ui-bg-accented)', 'color-mix(in srgb, var(--ui-border-accented) 35%, var(--ui-bg))', 'var(--ui-bg-elevated)']
+		const Th = (tone, t = '', z = 24, icon = 'image') => D('position:relative;overflow:hidden;display:flex;align-items:center;justify-content:center;color:var(--ui-text-muted);background:repeating-linear-gradient(135deg, rgb(128 128 128 / 0.12) 0 1px, transparent 1px 12px), ' + TONES[tone % 4] + ';' + t, I(icon, z, 'opacity:0.55'))
+		const BADGE = {
+			ok: ['background:var(--rc-success-soft);color:var(--ui-success)', 'circle-check'], none: ['border:1px solid var(--ui-border-accented);color:var(--ui-text-toned)', 'circle-dashed'],
+			busy: ['background:var(--rc-info-soft);color:var(--ui-info)', 'loader-circle'], fail: ['background:var(--rc-error-soft);color:var(--ui-error)', 'circle-x'],
+			used: ['border:1px solid var(--ui-border-accented);color:var(--ui-text-toned)'], unused: ['background:var(--rc-warning-soft);color:var(--ui-warning)', 'unlink'],
+			vars: ['background:var(--rc-info-soft);color:var(--ui-info)', 'layers'], off: ['border:1px solid var(--ui-border-accented);color:var(--ui-text-toned)', 'circle-off'], warn: ['background:var(--rc-warning-soft);color:var(--ui-warning)', 'triangle-alert']
+		}
+		const Bd = (t, k, sz = 20) => S('height:' + sz + 'px;padding:0 6px;display:inline-flex;align-items:center;gap:4px;font-size:12px;font-weight:500;white-space:nowrap;flex-shrink:0;' + BADGE[k][0], BADGE[k][1] && I(BADGE[k][1], 12), t)
+		const Sw = (on, dis) => S('width:32px;height:18px;padding:2px;flex-shrink:0;display:flex;justify-content:' + (on ? 'flex-end' : 'flex-start') + ';background:' + (on ? 'var(--ui-primary)' : 'var(--ui-border-accented)') + ';opacity:' + (dis ? 0.4 : 1), S('width:14px;height:14px;background:var(--ui-bg)'))
+		const Alert = (tone, icon, title, text, action, actionEl) => D('display:flex;gap:10px;padding:12px 14px;background:var(--rc-' + tone + '-soft);color:var(--ui-' + tone + ')', S('display:flex;padding-top:2px', I(icon)), D('flex:1;display:flex;flex-direction:column;gap:8px;min-width:0', D('display:flex;flex-direction:column;gap:2px', title && S('font-weight:600', title), text && S('color:var(--ui-text-toned)', text)), action && D('display:flex', B(action, { icon: 'rotate-cw', h: m ? 44 : 28, fs: 12, z: 14, ...(actionEl || {}) }))))
+		const Empty = (icon, title, text, pad = 56, ...extra) => D('background:var(--ui-bg);border:1px solid var(--ui-border);padding:' + pad + 'px 24px;display:flex;flex-direction:column;align-items:center;gap:12px;text-align:center', S('width:44px;height:44px;display:flex;align-items:center;justify-content:center;background:var(--ui-bg-elevated);color:var(--ui-text-toned)', I(icon, 20)), S('font-weight:600;font-size:15px;color:var(--ui-text-highlighted)', title), S('color:var(--ui-text-muted);max-width:380px;text-wrap:pretty', text), ...extra)
+		const Note = t => S('align-self:flex-start;height:20px;padding:0 6px;display:inline-flex;align-items:center;border:1px dashed var(--ui-border-accented);background:var(--ui-bg);color:var(--ui-text-toned);font:500 11px \'IBM Plex Mono\',monospace', t)
+		const Skl = (w, ht = 13) => S('display:block;width:' + w + ';height:' + ht + 'px;background:var(--ui-bg-accented)')
+		const Field = (lab, val, o = {}) => D('display:flex;flex-direction:column;gap:6px;min-width:0', D('display:flex;justify-content:space-between', S('font-weight:500;color:var(--ui-text-highlighted)', lab), o.count && S(MONO + ';font-size:12px;color:var(--ui-text-muted)', o.count)),
+			D('display:flex;align-items:center;min-height:' + (m ? 44 : 40) + 'px;border:1px solid ' + (o.err || o.eb ? 'var(--ui-error)' : o.focus ? 'var(--ui-primary)' : 'var(--ui-border-accented)') + ';' + (o.focus ? 'box-shadow:0 0 0 1px var(--ui-primary);' : '') + 'background:' + (o.dis || o.lock ? 'var(--ui-bg-elevated)' : 'var(--ui-bg)') + ';font-size:' + (m ? 16 : 13) + 'px;opacity:' + (o.dis ? 0.6 : 1),
+				S('flex:1;min-width:0;padding:0 12px;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;color:' + (val ? 'var(--ui-text-highlighted)' : 'var(--ui-text-muted)') + ';' + (o.mono ? MONO : ''), val || o.ph || ''),
+				o.suffix && S('padding:0 12px;color:var(--ui-text-muted);' + MONO + ';font-size:13px', o.suffix), o.lock && S('padding:0 12px;display:flex;color:var(--ui-text-muted)', I('lock', 14)), o.sel && S('padding:0 12px;display:flex;color:var(--ui-text-muted)', I('chevron-down', 16))),
+			o.err && S('display:flex;gap:6px;align-items:flex-start;color:var(--ui-error);font-size:12px', I('circle-alert', 14, 'margin-top:3px'), S('', o.err)), o.help && !o.err && S('color:var(--ui-text-muted);font-size:12px;text-wrap:pretty', o.help))
+		const SwRow = (lab, help, on, dis) => D('display:flex;align-items:flex-start;gap:12px;min-height:' + (m ? 44 : 32) + 'px', D('flex:1;display:flex;flex-direction:column;min-width:0', S('font-weight:500;color:var(--ui-text-highlighted)', lab), S('color:var(--ui-text-muted);font-size:12px', help)), D('padding-top:2px', Sw(on, dis)))
+		const Shell = (o, body) => D('position:absolute;inset:0;z-index:50;background:var(--rc-overlay);display:flex;align-items:' + (m ? 'flex-end' : 'flex-start') + ';justify-content:center;padding:' + (m ? 16 : o.top || 140) + 'px 16px 16px',
+			D('width:' + (m ? '100%' : (o.w || 460) + 'px') + ';max-height:100%;background:var(--ui-bg);box-shadow:var(--rc-shadow-modal);display:flex;flex-direction:column',
+				D('padding:20px 24px 0;display:flex;align-items:flex-start;gap:12px', D('flex:1;display:flex;flex-direction:column;gap:4px', S('font:600 16px/24px \'IBM Plex Sans\',sans-serif;color:var(--ui-text-highlighted)', o.title), o.desc && S('color:var(--ui-text-muted);text-wrap:pretty', o.desc)), o.close && S('width:28px;height:28px;display:flex;align-items:center;justify-content:center;color:var(--ui-text-muted)', I('x'))),
+				body,
+				D('padding:20px 24px;display:flex;flex-direction:' + (m ? 'column-reverse' : 'row') + ';justify-content:flex-end;gap:8px;flex-shrink:0', o.cancel && B(o.cancel, { dis: o.loading }), o.confirm && S('height:' + bh + 'px;padding:0 12px;display:flex;align-items:center;justify-content:center;gap:6px;background:' + (o.tone === 'danger' ? 'var(--ui-error)' : 'var(--ui-primary)') + ';color:var(--ui-bg);font-weight:500;opacity:' + (o.cdis ? 0.4 : 1), o.loading && I('loader-circle'), o.confirm))))
+		const Toasts = () => D('position:absolute;z-index:60;display:flex;flex-direction:column;gap:8px;' + (m ? 'left:16px;right:16px;bottom:16px' : 'right:24px;bottom:24px;width:372px'), ...s.toasts.map(t => D('display:flex;gap:10px;padding:12px 14px;background:var(--ui-bg);border:1px solid var(--ui-border);box-shadow:var(--rc-shadow-pop)', S('margin-top:2px;display:flex;color:var(--ui-' + t[0] + ')', I(t[1])), D('flex:1;display:flex;flex-direction:column;gap:6px', D('display:flex;flex-direction:column;gap:2px', S('font-weight:600;color:var(--ui-text-highlighted)', t[2]), t[3] && S('color:var(--ui-text-muted)', t[3])), t[4] && B(t[4], { icon: 'rotate-cw', z: 14, h: m ? 44 : 28, fs: 12, px: 10 })), I('x'))))
+
+		// ---------- data
+		const V = [
+			{ n: 'thumb', w: 400, h: 300, fit: 'cover', fmt: 'WebP', q: 80, files: 412, size: '21 MB', on: true, out: '400×300', kb: '18 KB', sv: '-99%' },
+			{ n: 'card', w: 800, h: 0, fit: 'inside', fmt: 'WebP', q: 80, files: 318, size: '58 MB', on: true, out: '800×600', kb: '64 KB', sv: '-98%' },
+			{ n: 'hero', w: 1200, h: 630, fit: 'cover', fmt: 'WebP', q: 82, files: 244, size: '84 MB', on: true, out: '1200×630', kb: '96 KB', sv: '-98%' },
+			{ n: 'square', w: 600, h: 600, fit: 'cover', fmt: 'JPEG', q: 85, files: 140, size: '19 MB', on: true, out: '600×600', kb: '82 KB', sv: '-98%' },
+			{ n: 'og', w: 1200, h: 630, fit: 'cover', fmt: 'JPEG', q: 80, files: 96, size: '9 MB', on: true, out: '1200×630', kb: '142 KB', sv: '-96%' },
+			{ n: 'print', w: 0, h: 2400, fit: 'inside', fmt: 'PNG', q: 0, files: 74, size: '21 MB', on: false, out: '3200×2400', kb: '3.1 MB', sv: '-21%' }
+		]
+		const dim = v => v.w && v.h ? v.w + '×' + v.h : v.w ? v.w + ' × auto' : 'auto × ' + v.h
+		const en = V.filter(v => v.on)
+		const IM = [
+			{ id: 1, n: 'north-wall.jpg', sz: '3.9 MB', dim: '4032 × 3024', ty: 'JPEG', used: 2, vc: 4, vs: '260 KB', tot: '4.2 MB', tone: 0 },
+			{ id: 2, n: 'kitchen-after.webp', sz: '1.2 MB', dim: '2400 × 1600', ty: 'WEBP', used: 3, vc: 5, vs: '410 KB', tot: '1.6 MB', tone: 1 },
+			{ id: 3, n: 'kitchen-before.webp', sz: '1.1 MB', dim: '2400 × 1600', ty: 'WEBP', used: 1, vc: 5, vs: '395 KB', tot: '1.5 MB', tone: 2 },
+			{ id: 4, n: 'logo-renew.svg', sz: '8 KB', dim: 'Vector', ty: 'SVG', used: 5, vc: 0, tot: '8 KB', tone: 3 },
+			{ id: 5, n: 'floorboards-copy.jpg', sz: '2.4 MB', dim: '3600 × 2400', ty: 'JPEG', used: 3, vc: 3, vs: '240 KB', tot: '2.6 MB', tone: 0 },
+			{ id: 6, n: 'IMG_2208.jpg', sz: '2.4 MB', dim: '3600 × 2400', ty: 'JPEG', used: 2, vc: 0, tot: '2.4 MB', tone: 0 },
+			{ id: 7, n: 'IMG_4471.jpg', sz: '3.1 MB', dim: '3600 × 2400', ty: 'JPEG', used: 2, vc: 2, vs: '150 KB', tot: '3.3 MB', tone: 2 },
+			{ id: 8, n: 'window-frame.jpg', sz: '1.8 MB', dim: '3000 × 2000', ty: 'JPEG', used: 0, vc: 0, tot: '1.8 MB', tone: 3 },
+			{ id: 9, n: 'stone-wall-detail.jpg', sz: '3.1 MB', dim: '3600 × 2400', ty: 'JPEG', used: 1, vc: 1, vs: '60 KB', tot: '3.2 MB', tone: 2 },
+			{ id: 10, n: 'bathroom-tiles.png', sz: '860 KB', dim: '1800 × 1200', ty: 'PNG', used: 0, vc: 3, vs: '190 KB', tot: '1.1 MB', tone: 1 },
+			{ id: 11, n: 'lime-plaster.jpg', sz: '2.1 MB', dim: '3200 × 2133', ty: 'JPEG', used: 2, vc: 4, vs: '280 KB', tot: '2.4 MB', tone: 1 },
+			{ id: 12, n: 'floorboards.jpg', sz: '2.4 MB', dim: '3600 × 2400', ty: 'JPEG', used: 4, vc: 5, vs: '430 KB', tot: '2.8 MB', tone: 0 }
+		]
+		const byId = id => IM.find(x => x.id === id)
+		const mark = k => h('svg', { width: k, height: k, viewBox: '0 0 16 16', shapeRendering: 'crispEdges' }, h('rect', { width: 16, height: 16, fill: 'var(--ui-primary)' }), h('path', { fill: 'var(--ui-bg)', fillRule: 'evenodd', d: 'M4 3h6v1h1v1h1v3h-1v1h-1v1h1v1h1v2h-2v-2h-1v-1H6v3H4zm2 2v3h4V5z' }))
+		const pad = m ? 16 : 24
+
+		// ---------- shell
+		const NAV = [['home', 'house', 'Home'], ['articles', 'file-text', 'Articles'], ['media', 'images', 'Media'], ['users', 'users', 'Users'], ['integration', 'plug', 'Integration'], ['settings', 'settings', 'Settings']]
+		const nav = s.role === 'user' ? NAV.filter(n => ['home', 'articles', 'media'].includes(n[0])) : NAV
+		const Side = dr => {
+			const open = s.nav === 'settings' || s.sideOpen, act = s.nav === 'settings' ? (s.crumbs || []).slice(-1)[0] : null, h = dr ? 44 : 32
+			const row = (ic, t, on, pl, tail, hi) => D('display:flex;align-items:center;gap:10px;height:' + h + 'px;padding:0 10px 0 ' + pl + 'px;background:' + (on ? 'var(--rc-sand)' : 'transparent') + ';color:' + (on ? 'var(--rc-on-sand)' : hi ? 'var(--ui-text-highlighted)' : 'var(--ui-text-toned)') + ';font-weight:' + (on || hi ? 500 : 400), I(ic, pl > 10 ? 14 : undefined), S('flex:1', t), tail)
+			return D('width:' + (dr ? '100%' : '224px') + ';height:' + (dr ? '100%' : 'auto') + ';flex-shrink:0;background:var(--ui-bg);' + (dr ? 'box-shadow:var(--rc-shadow-modal);' : 'border-right:1px solid var(--ui-border);') + 'display:flex;flex-direction:column;padding:12px;gap:2px',
+				D('display:flex;align-items:center;gap:10px;height:40px;padding:0 6px;margin-bottom:10px', mark(26), S('flex:1;font-weight:600;font-size:14px;color:var(--ui-text-highlighted)', 'RenewCMS'), dr && I('x', 20)),
+				...nav.flatMap(([k, ic, t]) => k !== 'settings' ? [row(ic, t, k === s.nav, 10)] : [row(ic, t, false, 10, I(open ? 'chevron-down' : 'chevron-right', 14), open), open && D('display:flex;flex-direction:column;gap:2px;margin-left:19px;border-left:1px solid var(--ui-border)', S('padding:6px 10px 2px 12px;font-size:11px;line-height:16px;font-weight:600;letter-spacing:.04em;text-transform:uppercase;color:var(--ui-text-muted)', 'Media'), row('layers', 'Variants', act === 'Variants', 12), row('database', 'Cache', act === 'Cache', 12))]),
+				D('flex:1'), D('display:flex;align-items:center;gap:10px;height:40px;padding:0 6px;color:var(--ui-text-highlighted)', S('width:26px;height:26px;flex-shrink:0;background:var(--rc-sand);color:var(--rc-on-sand);display:flex;align-items:center;justify-content:center;font:600 11px \'IBM Plex Sans\',sans-serif', 'MA'), S('flex:1;font-weight:500', 'Marta Alves'), I('chevrons-up-down', 14)))
+		}
+		const side = Side(false)
+		const crumbs = s.crumbs || []
+		const topbar = m
+			? D('height:56px;flex-shrink:0;border-bottom:1px solid var(--ui-border);background:var(--ui-bg);display:flex;align-items:center;padding:0 6px;gap:4px;color:var(--ui-text-highlighted)', S('width:44px;height:44px;display:flex;align-items:center;justify-content:center', I(s.back ? 'arrow-left' : 'menu', 20)), S('flex:1;font-weight:600;font-size:16px;overflow:hidden;text-overflow:ellipsis;white-space:nowrap', s.mTitle || crumbs[crumbs.length - 1]))
+			: D('height:48px;flex-shrink:0;border-bottom:1px solid var(--ui-border);background:var(--ui-bg);display:flex;align-items:center;padding:0 24px;gap:8px;color:var(--ui-text-muted)', I('panel-left-close'), S('width:1px;height:16px;background:var(--ui-border);margin:0 6px'), ...crumbs.flatMap((c, i) => [i > 0 && I('chevron-right', 14), S('color:' + (i === crumbs.length - 1 ? 'var(--ui-text-highlighted)' : 'var(--ui-text-muted)') + ';font-weight:' + (i === crumbs.length - 1 ? 500 : 400), c)]))
+		const PH = (title, desc, ...acts) => D('display:flex;flex-direction:' + (m ? 'column' : 'row') + ';align-items:' + (m ? 'stretch' : 'flex-start') + ';gap:' + (m ? 12 : 16) + 'px;flex-shrink:0', D('flex:1;display:flex;flex-direction:column;gap:4px;min-width:0', S('font:600 ' + (m ? 20 : 24) + 'px/32px \'IBM Plex Sans\',sans-serif;color:var(--ui-text-highlighted)', title), desc && S('color:var(--ui-text-muted);max-width:620px;text-wrap:pretty', desc)), acts.filter(Boolean).length > 0 && D('display:flex;gap:8px;flex-shrink:0;' + (m ? 'flex-direction:column' : ''), ...acts.filter(Boolean)))
+		const SetTabs = act => D('display:flex;gap:20px;border-bottom:1px solid var(--ui-border);flex-shrink:0', ...['Variants', 'Cache'].map(t => S('height:' + (m ? 44 : 36) + 'px;display:flex;align-items:center;gap:6px;border-bottom:2px solid ' + (t === act ? 'var(--ui-primary)' : 'transparent') + ';margin-bottom:-1px;font-weight:' + (t === act ? 500 : 400) + ';color:' + (t === act ? 'var(--ui-text-highlighted)' : 'var(--ui-text-toned)'), I(t === 'Variants' ? 'layers' : 'database', 14), t)))
+		const Pg = (...kids) => D('flex:1;min-height:0;overflow:hidden;padding:' + pad + 'px;display:flex;flex-direction:column;gap:16px;position:relative', D('display:flex;flex-direction:column;gap:16px;flex-shrink:0;margin-top:' + (-(s.scroll || 0)) + 'px', ...kids))
+		const Card = (title, right, ...kids) => D('background:var(--ui-bg);border:1px solid var(--ui-border);display:flex;flex-direction:column;min-width:0', D('display:flex;align-items:center;gap:8px;min-height:44px;padding:0 16px;border-bottom:1px solid var(--ui-border)', S('flex:1;font-weight:600;color:var(--ui-text-highlighted)', title), right), ...kids)
+
+		// ---------- 1. variants list
+		const L = s.list || {}
+		const Menu = () => D('position:absolute;z-index:20;right:0;top:' + (m ? 44 : 34) + 'px;width:176px;background:var(--ui-bg);border:1px solid var(--ui-border);box-shadow:var(--rc-shadow-pop);padding:4px;display:flex;flex-direction:column;font-size:13px', ...[['pencil', 'Edit', ''], ['eraser', 'Purge cache', ''], ['trash-2', 'Delete', 'color:var(--ui-error)']].map(([ic, t, c], i) => D('display:flex;align-items:center;gap:8px;height:' + (m ? 44 : 32) + 'px;padding:0 8px;color:var(--ui-text-highlighted);' + (i === 0 && L.menu !== undefined ? 'background:var(--ui-bg-elevated);' : '') + c, I(ic, 14), t)))
+		const stat = (v, i) => { const busy = L.busy === i, on = v.on; return D('display:flex;align-items:center;gap:8px;color:' + (busy ? 'var(--ui-info)' : on ? 'var(--ui-text-highlighted)' : 'var(--ui-text-muted)'), Sw(on, busy), S('display:flex;align-items:center;gap:4px;white-space:nowrap', I(busy ? 'loader-circle' : on ? 'circle-check' : 'circle-off', 14), busy ? 'Purging…' : on ? 'Enabled' : 'Disabled')) }
+		const act = (i) => S('position:relative;display:flex', B(null, { icon: 'ellipsis', sq: true, k: 'ghost', h: m ? 44 : 28, dis: L.busy === i, ring: L.menu === i }), L.menu === i && Menu())
+		const cols = 'minmax(0,1.1fr) 104px 76px 72px 68px 92px 92px 132px 44px'
+		const ListTable = () => {
+			const hd = D('display:grid;grid-template-columns:' + cols + ';height:36px;align-items:center;padding:0 8px 0 16px;background:var(--ui-bg-elevated);color:var(--ui-text-muted);font-weight:500', ...['Name', 'Dimensions', 'Fit', 'Format', 'Quality', 'Generated', 'Cache size', 'Status', ''].map(t => S('', t)))
+			const rows = V.map((v, i) => D('position:relative;display:grid;grid-template-columns:' + cols + ';min-height:48px;align-items:center;padding:0 8px 0 16px;border-top:1px solid var(--ui-border-muted);background:' + (L.busy === i ? 'var(--ui-bg-elevated)' : 'var(--ui-bg)') + ';color:' + (v.on ? 'var(--ui-text)' : 'var(--ui-text-muted)'),
+				S(MONO + ';font-weight:500;font-size:13px;color:' + (v.on ? 'var(--ui-text-highlighted)' : 'var(--ui-text-muted)'), v.n), S(MONO + ';font-size:12px', dim(v)), S('', v.fit), S('', v.fmt), S('', v.q ? v.q : '—'), S('', v.files.toLocaleString('en-US')), S('', v.size), stat(v, i), act(i)))
+			return D('background:var(--ui-bg);border:1px solid var(--ui-border)', hd, ...rows, D('padding:10px 16px;border-top:1px solid var(--ui-border);color:var(--ui-text-toned)', '6 variants · 1,284 generated files · 212 MB'))
+		}
+		const ListCards = () => D('display:flex;flex-direction:column;gap:8px', ...V.map((v, i) => D('position:relative;background:' + (L.busy === i ? 'var(--ui-bg-elevated)' : 'var(--ui-bg)') + ';border:1px solid var(--ui-border);padding:12px;display:flex;flex-direction:column;gap:6px', D('display:flex;align-items:center;gap:8px', S(MONO + ';font-weight:500;font-size:14px;flex:1;color:' + (v.on ? 'var(--ui-text-highlighted)' : 'var(--ui-text-muted)'), v.n), stat(v, i)),
+			S('color:var(--ui-text-toned);' + MONO + ';font-size:12px', dim(v) + ' · ' + v.fit + ' · ' + v.fmt + (v.q ? ' · q' + v.q : '')),
+			D('display:flex;align-items:center', S('flex:1;color:var(--ui-text-muted)', v.files.toLocaleString('en-US') + ' generated · ' + v.size), act(i)))), S('color:var(--ui-text-muted);padding:4px 0', '6 variants · 1,284 generated files · 212 MB'))
+		const RefCard = () => {
+			const rows = [['/media/photo.png?v=thumb', '200', 'Image', 'ok'], ['Unknown or disabled variant', '400', 'Unknown variant', 'err'], ['width, height, format or quality', '400', 'Unsupported parameter', 'err'], ['Missing source image', '404', 'Not found', 'err']]
+			const json = '{\n  "status": 400,\n  "error": "unknown_variant",\n  "message": "Unknown variant",\n  "detail": "banner"\n}'
+			return D('background:var(--ui-bg);border:1px solid var(--ui-border);padding:16px;display:flex;flex-direction:column;gap:12px', S('font-weight:600;color:var(--ui-text-highlighted)', 'How requests are handled'),
+				D('display:grid;grid-template-columns:' + (m ? 'minmax(0,1fr)' : 'minmax(0,1.3fr) minmax(0,1fr)') + ';gap:16px', D('display:flex;flex-direction:column;border:1px solid var(--ui-border)', ...rows.map(([a, b, c, k], i) => D('display:flex;align-items:center;gap:10px;min-height:' + (m ? 44 : 36) + 'px;padding:6px 12px;border-top:' + (i ? '1px solid var(--ui-border-muted)' : '0'), S('flex:1;min-width:0;' + (i === 0 ? MONO + ';font-size:12px' : '') + ';color:var(--ui-text-highlighted)', a), Bd(b, k === 'ok' ? 'ok' : 'fail'), S('width:' + (m ? 120 : 130) + 'px;color:var(--ui-text-toned)', c)))),
+					D('display:flex;flex-direction:column;gap:6px', S('color:var(--ui-text-muted);font-size:12px', 'Body of a 400 response'), h('pre', { style: { margin: 0, padding: 12, background: 'var(--ui-bg-elevated)', color: 'var(--ui-text-highlighted)', fontFamily: "'IBM Plex Mono',monospace", fontSize: 12, lineHeight: '18px', overflow: 'hidden' } }, json))), S('color:var(--ui-text-muted);font-size:12px', 'unsupported_parameter replaces unknown_variant when a raw parameter is sent. There is no arbitrary-size mode.'))
+		}
+		const TPL = [['thumb', '400×300 · cover · WebP'], ['hero', '1200×630 · cover · WebP']]
+		const ListPage = () => {
+			let body
+			if (s.forbidden) body = [Empty('lock', 'You don\'t have access', 'Only admins can manage image variants. Ask an admin if you need one changed.', 72, B('Back to Home', { icon: 'arrow-left' }))]
+			else {
+				const add = B('Add variant', { k: 'primary', icon: 'plus' })
+				body = [PH('Image variants', 'Named sizes and formats generated from your original images. Originals are never changed.', add), SetTabs('Variants')]
+				if (L.state === 'loading') body.push(m ? D('display:flex;flex-direction:column;gap:8px', ...Array.from({ length: 4 }, () => D('background:var(--ui-bg);border:1px solid var(--ui-border);padding:12px;display:flex;flex-direction:column;gap:10px', Skl('40%'), Skl('70%', 11), Skl('55%', 11)))) : D('background:var(--ui-bg);border:1px solid var(--ui-border)', D('height:36px;background:var(--ui-bg-elevated)'), ...Array.from({ length: 5 }, () => D('height:48px;border-top:1px solid var(--ui-border-muted);display:flex;align-items:center;gap:32px;padding:0 16px', Skl('120px'), Skl('90px'), Skl('60px'), Skl('60px'), Skl('80px'), Skl('160px')))))
+				else if (L.state === 'error') body.push(Alert('error', 'circle-x', 'Couldn\'t load variants', 'Check your connection and try again.', 'Try again'))
+				else if (L.state === 'empty') body.push(Empty('layers', 'No variants yet', 'A variant is a named size that an image can be requested in, like ?v=thumb. Start with one of these.', 40, D('display:flex;gap:12px;width:100%;max-width:520px;' + (m ? 'flex-direction:column' : ''), ...TPL.map(([n, d]) => D('flex:1;border:1px solid var(--ui-border-accented);padding:12px;display:flex;flex-direction:column;gap:2px;text-align:left;min-height:' + (m ? 64 : 0) + 'px', S(MONO + ';font-weight:500;color:var(--ui-text-highlighted)', n), S('font-size:12px;color:var(--ui-text-muted)', d), S('display:flex;align-items:center;gap:4px;margin-top:8px;font-weight:500;color:var(--ui-text-highlighted)', I('plus', 14), 'Use template')))), B('Add variant', { k: 'primary', icon: 'plus', px: 16 })))
+				else body.push(m ? ListCards() : ListTable(), RefCard())
+			}
+			return D('flex:1;min-width:0;min-height:0;display:flex;flex-direction:column', topbar, Pg(...body))
+		}
+
+		// ---------- 2. edit slide-over
+		const E = s.ed || {}, edit = E.mode === 'edit', er = E.err || {}, dis = !!E.saving
+		const Cmp = () => {
+			const pos = E.pos || 50, hasV = !!E.out
+			const chip = (t, side) => S('position:absolute;top:8px;' + side + ':8px;height:20px;padding:0 6px;display:flex;align-items:center;background:var(--ui-bg);border:1px solid var(--ui-border-accented);color:var(--ui-text-highlighted);font-weight:500;font-size:12px;' + (side === 'right' ? MONO : ''), t)
+			return D('position:relative;aspect-ratio:3/2;border:1px solid var(--ui-border);overflow:hidden;flex-shrink:0', Th(0, 'position:absolute;inset:0', 32),
+				hasV && D('position:absolute;inset:0;clip-path:inset(0 0 0 ' + pos + '%);background:repeating-linear-gradient(45deg, rgb(128 128 128 / 0.22) 0 2px, transparent 2px 6px), ' + TONES[1] + ';display:flex;align-items:center;justify-content:center;color:var(--ui-text-muted)'),
+				chip('Original', 'left'), hasV && chip(E.name || 'name', 'right'),
+				hasV && D('position:absolute;top:0;bottom:0;left:' + pos + '%;width:2px;margin-left:-1px;background:var(--ui-bg);box-shadow:0 0 0 1px var(--ui-border-accented)', S('position:absolute;top:50%;left:50%;width:' + (m ? 44 : 32) + 'px;height:' + (m ? 44 : 32) + 'px;margin:' + (m ? -22 : -16) + 'px 0 0 ' + (m ? -22 : -16) + 'px;display:flex;align-items:center;justify-content:center;background:var(--ui-bg);border:1px solid var(--ui-border-accented);color:var(--ui-text-highlighted);' + (E.focus ? 'outline:2px solid var(--ui-primary);outline-offset:2px;' : ''), I('chevrons-left-right', 16))),
+				!hasV && D('position:absolute;left:12px;right:12px;bottom:12px;padding:8px 12px;background:var(--ui-bg);border:1px solid var(--ui-border);color:var(--ui-text-toned)', 'Set a width or height to see a preview.'))
+		}
+		const Preview = () => D('display:flex;flex-direction:column;gap:12px;min-width:0', D('display:flex;align-items:baseline;gap:8px', S('font-weight:600;color:var(--ui-text-highlighted);flex:1', 'Preview'), S('font-size:12px;color:var(--ui-text-muted)', 'Sample: north-wall.jpg')), Cmp(),
+			D('display:grid;grid-template-columns:minmax(0,1fr) minmax(0,1fr);gap:12px', D('display:flex;flex-direction:column', S('font-weight:500;color:var(--ui-text-highlighted)', 'Original'), S('font-size:12px;color:var(--ui-text-muted)', '4032 × 3024 · 3.9 MB')), D('display:flex;flex-direction:column', S('font-weight:500;color:var(--ui-text-highlighted);' + MONO, E.name || 'name'), S('font-size:12px;color:var(--ui-text-muted)', E.out ? E.out + ' · about ' + E.est : 'No output yet'))),
+			S('font-size:12px;color:var(--ui-text-muted)', 'Drag the divider, or focus it and use the arrow keys. The estimate comes from a sample; output is never larger than the source.'),
+			D('display:flex;flex-direction:column;gap:6px', S('font-weight:500;color:var(--ui-text-highlighted)', 'URL'), D('display:flex;gap:8px', D('flex:1;min-width:0;display:flex;align-items:center;min-height:' + (m ? 44 : 32) + 'px;padding:0 12px;background:var(--ui-bg-elevated);border:1px solid var(--ui-border);' + MONO + ';font-size:12px;overflow:hidden;white-space:nowrap;text-overflow:ellipsis;color:' + (E.name ? 'var(--ui-text-highlighted)' : 'var(--ui-text-muted)'), '/media/north-wall.jpg?v=' + (E.name ? E.name : '<name>')), B(E.copied ? 'Copied' : 'Copy', { icon: E.copied ? 'check' : 'copy', dis: !E.name }))))
+		const FITS = [['cover', 'Cover', 'Fills the box and crops what overflows.'], ['contain', 'Contain', 'Whole image inside the box, padded to the box size.'], ['inside', 'Inside', 'Whole image inside the box, no padding.']]
+		const Form = () => {
+			const k = []
+			if (E.saveErr) k.push(Alert('error', 'circle-x', 'Couldn\'t save the variant', 'Check your connection and try again.', 'Try again'))
+			if (edit) k.push(Alert('warning', 'triangle-alert', null, 'Changing dimensions, fit, format or quality purges ' + (E.files || 244) + ' generated files; they will be regenerated on next request.'))
+			k.push(Field('Name', E.name, { mono: true, ph: 'e.g. hero', lock: edit, err: er.name, dis, focus: !edit && E.focusName, help: edit ? 'The name can\'t be changed.' : 'Lowercase letters, numbers and dashes. Can\'t be changed later.', count: !edit && E.name ? E.name.length + '/32' : '' }))
+			k.push(D('display:grid;grid-template-columns:minmax(0,1fr) minmax(0,1fr);gap:12px', Field('Width', E.w, { suffix: 'px', ph: 'auto', err: er.w || er.dim, dis }), Field('Height', E.h, { suffix: 'px', ph: 'auto', err: er.h, eb: !!er.dim, dis })), !er.w && !er.h && !er.dim && S('color:var(--ui-text-muted);font-size:12px;margin-top:-8px', 'Set a width, a height, or both. 1–8000 px. Images are never enlarged.'))
+			const fit = E.fit || 'cover'
+			k.push(D('display:flex;flex-direction:column;gap:6px', S('font-weight:500;color:var(--ui-text-highlighted)', 'Fit'), D('display:grid;grid-template-columns:repeat(3,minmax(0,1fr));gap:8px;opacity:' + (dis ? 0.6 : 1), ...FITS.map(([id, t]) => D('min-height:' + (m ? 44 : 36) + 'px;display:flex;align-items:center;justify-content:center;gap:6px;border:1px solid ' + (id === fit ? 'var(--ui-primary)' : 'var(--ui-border-accented)') + ';background:' + (id === fit ? 'var(--ui-bg-elevated)' : 'var(--ui-bg)') + ';font-weight:' + (id === fit ? 600 : 400) + ';color:var(--ui-text-highlighted)', id === fit && I('check', 14), t))), S('color:var(--ui-text-muted);font-size:12px', FITS.find(f => f[0] === fit)[2])))
+			const fmt = E.fmt || 'Original'
+			k.push(Field('Format', fmt, { sel: true, dis, help: fmt === 'Original' ? 'Keeps the format of each source image.' : null }))
+			if (fmt !== 'PNG') k.push(D('display:flex;flex-direction:column;gap:6px', S('font-weight:500;color:var(--ui-text-highlighted)', 'Quality'), D('display:flex;align-items:center;gap:16px;opacity:' + (dis ? 0.6 : 1), D('flex:1;position:relative;height:' + (m ? 44 : 24) + 'px;display:flex;align-items:center', S('position:absolute;left:0;right:0;height:4px;background:var(--ui-bg-accented)'), S('position:absolute;left:0;width:' + Math.min(100, Math.max(0, E.qv === undefined ? 80 : E.qv)) + '%;height:4px;background:var(--ui-primary)'), S('position:absolute;left:calc(' + Math.min(100, Math.max(0, E.qv === undefined ? 80 : E.qv)) + '% - 8px);width:16px;height:16px;background:var(--ui-primary);border:2px solid var(--ui-bg);box-shadow:0 0 0 1px var(--ui-primary)')), D('width:84px', Field('', String(E.q === undefined ? 80 : E.q), { mono: true, err: er.q ? ' ' : null, eb: !!er.q }))), er.q ? S('display:flex;gap:6px;color:var(--ui-error);font-size:12px', I('circle-alert', 14, 'margin-top:3px'), er.q) : S('color:var(--ui-text-muted);font-size:12px', '1–100. Higher is sharper and larger.')))
+			k.push(D('display:flex;flex-direction:column;gap:12px;padding-top:4px', SwRow('Generate on upload', 'Creates this variant when an image is uploaded.', !!E.gen, dis), SwRow('Enabled', 'Disabled variants return 400 on the public site.', E.en !== false, dis)))
+			return D('display:flex;flex-direction:column;gap:16px;min-width:0', ...k)
+		}
+		const EditPanel = () => {
+			const title = edit ? 'Edit variant: ' + E.name : 'Add variant'
+			const label = E.saving ? 'Saving…' : edit ? 'Save changes' : 'Add variant'
+			const hd = D('height:56px;flex-shrink:0;display:flex;align-items:center;gap:' + (m ? 4 : 12) + 'px;padding:0 ' + (m ? 6 : 20) + 'px;border-bottom:1px solid var(--ui-border);background:var(--ui-bg)', m && S('width:44px;height:44px;display:flex;align-items:center;justify-content:center', I('arrow-left', 20)), S('flex:1;min-width:0;font:600 16px/24px \'IBM Plex Sans\',sans-serif;color:var(--ui-text-highlighted);overflow:hidden;text-overflow:ellipsis;white-space:nowrap', title), !m && S('width:28px;height:28px;display:flex;align-items:center;justify-content:center;color:var(--ui-text-muted)', I('x')))
+			const ft = D('height:' + (m ? 72 : 64) + 'px;flex-shrink:0;display:flex;align-items:center;gap:' + (m ? 8 : 12) + 'px;padding:0 ' + (m ? 16 : 20) + 'px;border-top:1px solid var(--ui-border);background:var(--ui-bg)', !m && D('flex:1;display:flex;align-items:center;gap:6px;color:var(--ui-text-toned)', E.dirty && I('circle-dot', 14), E.dirty ? 'Unsaved changes' : ''), B('Cancel', { full: m, dis }), S('height:' + bh + 'px;padding:0 16px;display:flex;align-items:center;justify-content:center;gap:6px;background:var(--ui-primary);color:var(--ui-bg);font-weight:500;flex:' + (m ? 1 : '0 0 auto') + ';opacity:' + (E.disSave ? 0.4 : 1), E.saving && I('loader-circle'), label))
+			const body = m
+				? D('flex:1;min-height:0;overflow:hidden;background:var(--ui-bg)', D('padding:16px;display:flex;flex-direction:column;gap:24px;margin-top:' + (-(s.scroll || 0)) + 'px', Form(), D('border-top:1px solid var(--ui-border);padding-top:16px', Preview())))
+				: D('flex:1;min-height:0;overflow:hidden;display:grid;grid-template-columns:440px minmax(0,1fr);background:var(--ui-bg)', D('padding:20px;overflow:hidden', Form()), D('padding:20px;border-left:1px solid var(--ui-border);background:var(--ui-bg-muted);overflow:hidden', Preview()))
+			return D('width:' + (m ? '100%' : '960px') + ';height:100%;display:flex;flex-direction:column;background:var(--ui-bg);' + (m ? '' : 'box-shadow:var(--rc-shadow-modal)'), hd, body, ft)
+		}
+
+		// ---------- 3. media library
+		const ML = s.ml || {}
+		const Tb = () => {
+			const f = ML.filter || 'All'
+			const seg = D('display:flex;border:1px solid var(--ui-border-accented);background:var(--ui-bg);flex-shrink:0', ...['All', 'With variants', 'Without'].map(t => S('height:' + (m ? 44 : 30) + 'px;padding:0 ' + (m ? 10 : 12) + 'px;display:flex;align-items:center;font-weight:500;background:' + (t === f ? 'var(--ui-primary)' : 'transparent') + ';color:' + (t === f ? 'var(--ui-bg)' : 'var(--ui-text-toned)') + ';' + (m ? 'flex:1;justify-content:center;font-size:12px' : ''), t)))
+			const sortLbl = ML.sort === 'total' ? (m ? 'Largest total size' : 'Largest total size (original + variants)') : 'Newest first'
+			const sortBox = D('position:relative;' + (m ? 'flex:1' : ''), D('height:' + (m ? 44 : 30) + 'px;padding:0 10px;display:flex;align-items:center;gap:8px;border:1px solid var(--ui-border-accented);background:var(--ui-bg);color:var(--ui-text-highlighted);font-weight:500;', I('arrow-up-down', 14), S('flex:1', sortLbl), I('chevron-down', 14)),
+				ML.menu && D('position:absolute;z-index:20;top:' + (m ? 48 : 34) + 'px;right:0;width:' + (m ? '100%' : '340px') + ';background:var(--ui-bg);border:1px solid var(--ui-border);box-shadow:var(--rc-shadow-pop);padding:4px', ...['Newest first', 'Oldest first', 'Filename', 'Largest total size (original + variants)'].map((t, i) => D('display:flex;align-items:center;gap:8px;min-height:' + (m ? 44 : 32) + 'px;padding:0 8px;' + (i === 3 ? 'background:var(--ui-bg-elevated);font-weight:500;' : '') + 'color:var(--ui-text-highlighted)', S('width:16px;display:flex', i === 3 && I('check', 14)), t, i === 3 && S('margin-left:auto;font-size:11px;color:var(--ui-text-muted);' + MONO, 'new')))))
+			return D('display:flex;flex-direction:' + (m ? 'column' : 'row') + ';gap:8px;align-items:' + (m ? 'stretch' : 'center') + ';flex-shrink:0', D('height:' + (m ? 44 : 30) + 'px;padding:0 10px;display:flex;align-items:center;gap:8px;border:1px solid var(--ui-border-accented);background:var(--ui-bg);color:var(--ui-text-muted);' + (m ? '' : 'width:240px'), I('search', 14), 'Search by filename'), !m && D('flex:1'), m ? D('display:flex;gap:8px', seg) : seg, sortBox)
+		}
+		const MCard = im => {
+			const hover = ML.sort === 'total'
+			return D('display:flex;flex-direction:column;background:var(--ui-bg);border:1px solid var(--ui-border);min-width:0', Th(im.tone, 'aspect-ratio:4/3;border-bottom:1px solid var(--ui-border)'),
+				D('padding:10px 12px;display:flex;flex-direction:column;gap:6px;min-width:0', D('display:flex;flex-direction:column;gap:2px;min-width:0', S('font-weight:500;color:var(--ui-text-highlighted);overflow:hidden;text-overflow:ellipsis;white-space:nowrap', im.n), S('font-size:12px;color:var(--ui-text-muted);white-space:nowrap;overflow:hidden;text-overflow:ellipsis', hover ? im.tot + ' total' + (im.vc ? ' · ' + im.sz + ' + ' + im.vs : '') : im.sz + ' · ' + im.dim)),
+					D('display:flex;flex-wrap:wrap;gap:4px', im.used ? Bd('Used in ' + im.used, 'used') : Bd('Unused', 'unused'), im.vc > 0 && Bd(im.vc + (im.vc === 1 ? ' variant' : ' variants'), 'vars'))))
+		}
+		const MediaPage = () => {
+			let ids = ML.ids || IM.map(x => x.id)
+			const body = [PH('Media', 'Images you upload are kept as they are. Variants are generated from them.', B('Upload', { k: 'primary', icon: 'upload' })), Tb()]
+			if (ML.empty) body.push(Empty('layers', 'No images with variants', 'Variants are generated when an image is requested with ?v=<name>, or from its Variants tab.', 56, B('Show all images')))
+			else body.push(D('display:grid;grid-template-columns:repeat(' + (m ? 2 : 5) + ',minmax(0,1fr));gap:' + (m ? 10 : 16) + 'px', ...ids.map(byId).map(MCard)))
+			return D('flex:1;min-width:0;min-height:0;display:flex;flex-direction:column', topbar, Pg(...body), ML.ann && D('position:absolute;z-index:20;' + (m ? 'left:16px;bottom:16px' : 'left:248px;bottom:20px'), Note(ML.ann)))
+		}
+
+		// ---------- 4. detail panel
+		const DT = s.dt || {}
+		const stOf = (v, i) => (DT.rows && DT.rows[i]) || 'none'
+		const VR = (v, i) => {
+			const st = stOf(v, i), gen = st === 'gen', none = st === 'none', busy = st === 'busy', fail = st === 'fail'
+			const bk = { gen: ['Generated', 'ok'], none: ['Not generated', 'none'], busy: ['Generating', 'busy'], fail: ['Failed', 'fail'] }[st]
+			const meta = gen ? v.out + ' · ' + v.fmt + ' · ' + v.kb + ' · ' : v.out + ' · ' + v.fmt
+			const ib = (ic, lab) => m ? B(lab, { icon: ic, h: 44, px: 12 }) : B(null, { icon: ic, sq: true, h: 28 })
+			const acts = gen ? [ib('link', 'Copy URL'), ib('eye', 'Preview'), ib('eraser', 'Purge')] : none ? [ib('link', 'Copy URL'), ib('zap', 'Generate now')] : fail ? [B('Retry', { icon: 'rotate-cw', h: m ? 44 : 28, fs: 12, z: 14 })] : []
+			return D('display:flex;flex-direction:column;gap:' + (m ? 8 : 4) + 'px;padding:10px 12px;border-top:' + (i ? '1px solid var(--ui-border-muted)' : '0') + ';background:' + (busy ? 'var(--ui-bg-elevated)' : 'var(--ui-bg)'),
+				D('display:flex;align-items:center;gap:8px', S(MONO + ';font-weight:500;font-size:13px;color:var(--ui-text-highlighted)', v.n), Bd(bk[0], bk[1]), D('flex:1'), !m && D('display:flex;gap:4px', ...acts)),
+				D('color:var(--ui-text-toned);font-size:12px;display:flex;gap:4px;flex-wrap:wrap', S('', meta), gen && S('font-weight:500;color:var(--ui-success)', v.sv + ' vs original')),
+				fail && D('display:flex;align-items:center;gap:6px;color:var(--ui-error);font-size:12px', I('circle-alert', 14), DT.cause && DT.cause[i] || 'Image too large'),
+				m && acts.length > 0 && D('display:flex;gap:8px;flex-wrap:wrap', ...acts))
+		}
+		const DetailPanel = () => {
+			const im = byId(DT.id || 1), vlist = DT.none ? [] : en
+			const gens = vlist.filter((v, i) => stOf(v, i) === 'gen').length
+			const anyBusy = vlist.some((v, i) => stOf(v, i) === 'busy')
+			const noFmt = DT.nofmt
+			const tabs = D('display:flex;gap:20px;border-bottom:1px solid var(--ui-border);padding:0 ' + (m ? 16 : 20) + 'px;flex-shrink:0', ...['Details', 'Variants'].map(t => S('height:' + (m ? 44 : 40) + 'px;display:flex;align-items:center;border-bottom:2px solid ' + (t === 'Variants' ? 'var(--ui-primary)' : 'transparent') + ';margin-bottom:-1px;font-weight:' + (t === 'Variants' ? 500 : 400) + ';color:' + (t === 'Variants' ? 'var(--ui-text-highlighted)' : 'var(--ui-text-toned)'), t)))
+			const orig = D('display:flex;gap:12px;align-items:center;padding:12px;border:1px solid var(--ui-border);background:var(--ui-bg-muted)', Th(im.tone, 'width:72px;height:54px;flex-shrink:0;border:1px solid var(--ui-border)', 16), D('display:flex;flex-direction:column;min-width:0', S('font-size:12px;color:var(--ui-text-muted)', 'Original · kept untouched'), S('font-weight:600;color:var(--ui-text-highlighted);overflow:hidden;text-overflow:ellipsis;white-space:nowrap', im.n), S('font-size:12px;color:var(--ui-text-toned)', im.ty + ' · ' + im.dim + ' · ' + im.sz)))
+			const k = [orig]
+			if (noFmt) k.push(Alert('info', 'info', 'Variants aren\'t generated for this format.', noFmt))
+			else if (DT.none) k.push(Empty('layers', 'No variants defined', 'Define a variant in Settings to get resized copies of this image.', 28, S('display:inline-flex;align-items:center;gap:4px;font-weight:500;color:var(--ui-text-highlighted);text-decoration:underline;text-underline-offset:3px;min-height:' + (m ? 44 : 20) + 'px;align-items:center', 'Settings → Media → Variants', I('arrow-up-right', 14))))
+			else {
+				k.push(D('display:flex;align-items:center;gap:12px', D('flex:1;display:flex;flex-direction:column', S('font-weight:600;color:var(--ui-text-highlighted)', gens + ' of ' + vlist.length + ' generated'), gens === 0 && !anyBusy && S('font-size:12px;color:var(--ui-text-muted)', 'Nothing generated yet.'), anyBusy && S('font-size:12px;color:var(--ui-info)', 'Generating variants…')), B(anyBusy ? 'Generating…' : 'Generate all', { icon: anyBusy ? 'loader-circle' : 'zap', dis: anyBusy })))
+				k.push(D('border:1px solid var(--ui-border)', ...vlist.map(VR)))
+			}
+			return D('position:absolute;inset:0;z-index:40;display:flex;justify-content:flex-end;background:' + (m ? 'var(--ui-bg)' : 'var(--rc-overlay)'),
+				D('width:' + (m ? '100%' : '460px') + ';height:100%;background:var(--ui-bg);display:flex;flex-direction:column;' + (m ? '' : 'box-shadow:var(--rc-shadow-modal)'),
+					D('height:56px;flex-shrink:0;display:flex;align-items:center;gap:' + (m ? 4 : 12) + 'px;padding:0 ' + (m ? 6 : 20) + 'px;border-bottom:1px solid var(--ui-border)', m && S('width:44px;height:44px;display:flex;align-items:center;justify-content:center', I('arrow-left', 20)), S('flex:1;min-width:0;font:600 16px/24px \'IBM Plex Sans\',sans-serif;color:var(--ui-text-highlighted);overflow:hidden;text-overflow:ellipsis;white-space:nowrap', im.n), !m && S('width:28px;height:28px;display:flex;align-items:center;justify-content:center;color:var(--ui-text-muted)', I('x'))),
+					tabs, D('flex:1;min-height:0;overflow:hidden;padding:' + (m ? 16 : 20) + 'px;display:flex;flex-direction:column;gap:16px', ...k)))
+		}
+		const PrevDlg = () => {
+			const v = en[0], pane = (title, sub, inner) => D('display:flex;flex-direction:column;gap:8px;min-width:0', D('height:' + (m ? 180 : 300) + 'px;overflow:hidden;border:1px solid var(--ui-border);background:var(--ui-bg-muted);display:flex;align-items:' + (m ? 'flex-start' : 'center') + ';justify-content:' + (m ? 'flex-start' : 'center'), inner), D('display:flex;flex-direction:column', S('font-weight:600;color:var(--ui-text-highlighted)', title), S('font-size:12px;color:var(--ui-text-toned)', sub)))
+			const body = D('padding:20px 24px 0;display:flex;flex-direction:column;gap:12px;min-height:0;overflow:hidden', D('display:grid;grid-template-columns:' + (m ? 'minmax(0,1fr)' : 'minmax(0,1fr) minmax(0,1fr)') + ';gap:16px', pane(v.n + ' · ' + v.out + ' · ' + v.fmt, v.kb + ' · saves 99%', Th(1, 'width:400px;height:300px', 32)), pane('Original · 4032×3024 · JPEG', '3.9 MB · cropped to the preview area', Th(0, 'width:4032px;height:3024px;flex-shrink:0', 32))), S('font-size:12px;color:var(--ui-text-muted)', 'Both images are shown at actual size. Scroll to pan.'))
+			return Shell({ title: 'Preview: ' + v.n, w: 880, top: 80, close: true, cancel: 'Close' }, body)
+		}
+
+		// ---------- 5. cache
+		const C = s.cache || {}
+		const empty = C.state === 'empty'
+		const Tile = (ic, lab, val, sub) => D('background:var(--ui-bg);border:1px solid var(--ui-border);padding:' + (m ? 12 : 16) + 'px;display:flex;flex-direction:column;gap:4px;min-width:0', D('display:flex;align-items:center;gap:6px;color:var(--ui-text-muted)', I(ic, 14), S('', lab)), C.state === 'loading' ? Skl('60%', 28) : S('font:600 ' + (m ? 22 : 28) + 'px/36px \'IBM Plex Sans\',sans-serif;color:var(--ui-text-highlighted)', val), C.state === 'loading' ? Skl('40%', 11) : S('font-size:12px;color:var(--ui-text-muted)', sub))
+		const BL = () => {
+			const rows = [...V].sort((a, b) => parseInt(b.size) - parseInt(a.size))
+			const mx = 84
+			return Card('By variant', null, D('padding:8px 16px;display:flex;flex-direction:column;gap:' + (m ? 16 : 12) + 'px;margin:8px 0', ...rows.map(v => D('display:flex;flex-direction:column;gap:6px', D('display:flex;align-items:baseline;gap:8px', S(MONO + ';font-weight:500;color:var(--ui-text-highlighted)', v.n), !v.on && Bd('Disabled', 'off', 18), D('flex:1'), S('color:var(--ui-text-toned);font-size:12px', v.files.toLocaleString('en-US') + ' files · ' + v.size)), D('height:8px;background:var(--ui-bg-accented)', S('display:block;height:8px;width:' + (parseInt(v.size) / mx * 100) + '%;background:' + (v.on ? 'var(--ui-primary)' : 'var(--ui-border-accented)')))))))
+		}
+		const TOP = [['north-wall.jpg', 6, '5.8 MB', 0], ['lime-plaster.jpg', 6, '4.9 MB', 1], ['kitchen-after.webp', 5, '4.4 MB', 1], ['kitchen-before.webp', 5, '3.9 MB', 2], ['floorboards.jpg', 5, '3.6 MB', 0], ['IMG_4471.jpg', 4, '3.1 MB', 2], ['stone-wall-detail.jpg', 4, '2.8 MB', 2], ['bathroom-tiles.png', 4, '2.6 MB', 1], ['roof-lantern.jpg', 3, '2.3 MB', 3], ['chimney-stack.jpg', 3, '2.1 MB', 0]]
+		const TL = () => Card('Top 10 images by variant disk usage', null, ...TOP.map(([n, c, sz, t], i) => D('display:flex;align-items:center;gap:12px;min-height:' + (m ? 60 : 40) + 'px;padding:0 ' + (m ? 12 : 16) + 'px;border-top:' + (i ? '1px solid var(--ui-border-muted)' : '0'), S('width:20px;color:var(--ui-text-muted);font-size:12px;' + MONO, i + 1), Th(t, 'width:32px;height:24px;flex-shrink:0;border:1px solid var(--ui-border)', 12), D('flex:1;min-width:0;display:flex;flex-direction:' + (m ? 'column' : 'row') + ';gap:' + (m ? 0 : 12) + 'px', S('flex:1;min-width:0;font-weight:500;color:var(--ui-text-highlighted);overflow:hidden;text-overflow:ellipsis;white-space:nowrap', n), S('color:var(--ui-text-muted);font-size:12px;white-space:nowrap;' + (m ? '' : 'width:150px'), c + ' variants' + (m ? ' · ' + sz : ''))), !m && S('width:60px;text-align:right;color:var(--ui-text-toned)', sz), B(m ? null : 'Purge', { icon: 'eraser', h: m ? 44 : 26, fs: 12, z: 14, px: 10, sq: m }))))
+		const CachePage = () => {
+			const busy = C.state === 'purging'
+			const body = [PH('Cache', 'Generated variant files. Purged files are generated again on the next request.', B('Purge unused', { icon: 'clock', dis: busy || empty }), B('Purge all variants', { k: 'del', icon: 'trash-2', dis: busy || empty })), SetTabs('Cache')]
+			if (C.state === 'error') body.push(Alert('error', 'circle-x', 'Couldn\'t load cache stats', 'Check your connection and try again.', 'Try again'))
+			else {
+				if (busy) body.push(D('display:flex;flex-direction:column;gap:10px;padding:12px 14px;background:var(--rc-info-soft);color:var(--ui-info)', D('display:flex;gap:10px;align-items:center', I('loader-circle'), S('font-weight:600', 'Purging 1,284 files'), D('flex:1'), S('color:var(--ui-text-toned)', '640 of 1,284 · 106 MB freed')), D('height:6px;background:var(--ui-bg-accented)', S('display:block;height:6px;width:50%;background:var(--ui-info)'))))
+				const z = empty
+				body.push(D('display:grid;grid-template-columns:repeat(' + (m ? 2 : 4) + ',minmax(0,1fr));gap:' + (m ? 8 : 16) + 'px;opacity:' + (busy ? 0.6 : 1), Tile('files', 'Generated files', z ? '0' : '1,284', z ? 'Nothing cached' : 'Across 6 variants'), Tile('hard-drive', 'Disk used', z ? '0 MB' : '212 MB', z ? 'Nothing cached' : 'Originals not included'), Tile('layers', 'Variants defined', '6', '5 enabled, 1 disabled'), Tile('ban', 'Rejected requests', '37', 'Last 7 days')))
+				if (z) body.push(Empty('database', 'Nothing generated yet', 'Variants are generated on the first request with ?v=<name>, or from an image\'s Variants tab.', 48))
+				else if (C.state === 'loading') body.push(D('display:grid;grid-template-columns:' + (m ? 'minmax(0,1fr)' : '460px minmax(0,1fr)') + ';gap:16px', Card('By variant', null, D('padding:16px;display:flex;flex-direction:column;gap:20px', ...Array.from({ length: 5 }, () => D('display:flex;flex-direction:column;gap:8px', Skl('50%'), Skl('100%', 8))))), !m && Card('Top 10 images by variant disk usage', null, D('padding:16px;display:flex;flex-direction:column;gap:20px', ...Array.from({ length: 6 }, () => Skl('90%'))))))
+				else body.push(D('display:grid;grid-template-columns:' + (m ? 'minmax(0,1fr)' : '460px minmax(0,1fr)') + ';gap:16px;align-items:start;opacity:' + (busy ? 0.6 : 1), BL(), TL()))
+			}
+			return D('flex:1;min-width:0;min-height:0;display:flex;flex-direction:column', topbar, Pg(...body))
+		}
+		const cacheModal = () => {
+			const k = s.modal
+			if (k === 'purgeAll' || k === 'purgeAllOk') return { title: 'Purge all variants?', desc: 'This removes 1,284 generated files (212 MB) for every variant. Originals aren\'t touched. Files are generated again on request.', body: [Field('Type purge to confirm', k === 'purgeAllOk' ? 'purge' : 'pur', { mono: true, focus: true })], cancel: 'Cancel', confirm: 'Purge all variants', tone: 'danger', cdis: k === 'purgeAll' }
+			if (k === 'purgeUnused') return { title: 'Purge unused variants?', desc: 'This removes 312 files (41 MB) from enabled variants that haven\'t been requested for 30 days. Files are generated again on request.', cancel: 'Cancel', confirm: 'Purge 312 files' }
+			if (k === 'purgeVariant') return { title: 'Purge cache for “hero”?', desc: 'This removes 244 generated files (84 MB). Files are generated again on the next request.', cancel: 'Cancel', confirm: 'Purge 244 files' }
+			if (k === 'deleteVariant') return { title: 'Delete variant “hero”?', desc: 'This removes the variant and its 244 generated files (84 MB). Articles that use ?v=hero will start returning 400. This can\'t be undone.', cancel: 'Cancel', confirm: 'Delete variant', tone: 'danger', loading: !!s.loadingModal }
+			if (k === 'discard') return { title: 'Discard changes?', desc: 'You have unsaved changes to “hero”. If you close now, they\'re lost.', cancel: 'Keep editing', confirm: 'Discard changes', tone: 'danger' }
+			if (k === 'deleteImage') return { title: 'Delete this image?', desc: '"north-wall.jpg" is used in 2 articles. If you delete it, they will show a broken image. This can\'t be undone.', body: [D('display:flex;align-items:center;gap:8px;padding:10px 12px;background:var(--rc-warning-soft);color:var(--ui-warning)', I('layers'), S('font-weight:500;color:var(--ui-text-highlighted)', 'Also removes 4 generated variants (260 KB)'))], cancel: 'Cancel', confirm: 'Delete image', tone: 'danger' }
+		}
+		const Modal = () => { const c = cacheModal(); return Shell(c, D('padding:' + (c.body ? '20px 24px 0' : '0') + ';display:flex;flex-direction:column;gap:16px', ...(c.body || []))) }
+
+		// ---------- 6. editor + picker
+		const ED = s.edr || {}
+		const VOPT = [['Original', '4032×3024', 'JPEG'], ...en.map(v => [v.n[0].toUpperCase() + v.n.slice(1), dim(v), v.fmt === 'JPEG' ? 'JPEG' : v.fmt])]
+		const VSel = () => {
+			const cur = ED.cur ?? 0, open = ED.open, none = ED.none
+			const opts = none ? [VOPT[0]] : VOPT
+			const lab = o => o[0] + ' · ' + o[1] + ' · ' + o[2]
+			return D('display:flex;flex-direction:column;gap:6px', S('font-weight:500;color:var(--ui-text-highlighted)', 'Variant'),
+				D('display:flex;align-items:center;min-height:' + (m ? 44 : 40) + 'px;border:1px solid ' + (open ? 'var(--ui-primary)' : 'var(--ui-border-accented)') + ';background:var(--ui-bg);font-size:' + (m ? 16 : 13) + 'px;' + (open ? 'box-shadow:0 0 0 1px var(--ui-primary)' : ''), S('flex:1;min-width:0;padding:0 12px;color:var(--ui-text-highlighted);overflow:hidden;text-overflow:ellipsis;white-space:nowrap', lab(opts[cur])), S('padding:0 12px;display:flex;color:var(--ui-text-muted)', I('chevron-down', 16))),
+				open && D('border:1px solid var(--ui-border);box-shadow:var(--rc-shadow-pop);background:var(--ui-bg);padding:4px', ...opts.map((o, i) => D('display:flex;align-items:center;gap:8px;min-height:' + (m ? 44 : 36) + 'px;padding:0 8px;background:' + (i === cur ? 'var(--ui-bg-elevated)' : 'transparent') + ';color:var(--ui-text-highlighted)', S('width:16px;display:flex', i === cur && I('check', 14)), S('font-weight:' + (i === cur ? 600 : 400) + ';white-space:nowrap;overflow:hidden;text-overflow:ellipsis', lab(o))))),
+				none ? D('display:flex;align-items:center;gap:6px;color:var(--ui-text-muted);font-size:12px', I('info', 14), 'No variants defined. Add one in Settings → Media → Variants.') : D('color:var(--ui-text-muted);font-size:12px;' + MONO, '/media/north-wall.jpg' + (cur ? '?v=' + opts[cur][0].toLowerCase() : '')))
+		}
+		const pT = id => D('display:flex;flex-direction:column;gap:6px;min-width:0', D('position:relative;' + (id === 1 ? 'outline:2px solid var(--ui-primary);outline-offset:2px;' : ''), Th(byId(id).tone, 'aspect-ratio:1/1;border:1px solid var(--ui-border)', 20), id === 1 && S('position:absolute;top:4px;right:4px;width:20px;height:20px;display:flex;align-items:center;justify-content:center;background:var(--ui-primary);color:var(--ui-bg)', I('check', 14))), S('font-size:12px;color:var(--ui-text-toned);overflow:hidden;text-overflow:ellipsis;white-space:nowrap', byId(id).n))
+		const Picker = () => Shell({ title: 'Add an image', close: true, w: 640, top: 24, cancel: 'Cancel', confirm: 'Insert image' },
+			D('display:flex;flex-direction:column;min-height:0;flex:1;overflow:hidden', D('display:flex;gap:20px;border-bottom:1px solid var(--ui-border);padding:0 24px;margin-top:16px', ...['Upload', 'Library'].map(t => S('height:' + (m ? 44 : 36) + 'px;display:flex;align-items:center;gap:6px;border-bottom:2px solid ' + (t === 'Library' ? 'var(--ui-primary)' : 'transparent') + ';margin-bottom:-1px;font-weight:' + (t === 'Library' ? 500 : 400) + ';color:' + (t === 'Library' ? 'var(--ui-text-highlighted)' : 'var(--ui-text-toned)'), I(t === 'Upload' ? 'upload' : 'images', 14), t))),
+				D('padding:16px 24px 0;display:flex;flex-direction:column;gap:12px;overflow:hidden', D('display:grid;grid-template-columns:repeat(' + (m ? 3 : 4) + ',minmax(0,1fr));gap:12px ' + (m ? 8 : 12) + 'px', ...[1, 2, 3, 5].slice(0, m ? 3 : 4).map(pT)),
+					D('display:flex;flex-direction:column;gap:12px;padding-top:12px;border-top:1px solid var(--ui-border)', D('display:flex;gap:12px;align-items:center', Th(0, 'width:48px;height:48px;flex-shrink:0;border:1px solid var(--ui-border)', 16), D('display:flex;flex-direction:column;min-width:0', S('font-weight:500;color:var(--ui-text-highlighted)', 'north-wall.jpg'), S('font-size:12px;color:var(--ui-text-muted)', '4032 × 3024 · 3.9 MB'))), VSel()))))
+		const Editor = () => {
+			const bl = ED.block
+			const img = D('position:relative;aspect-ratio:16/9;border:1px solid var(--ui-border);overflow:hidden', Th(0, 'position:absolute;inset:0;opacity:' + (bl ? 0.5 : 1), 40, bl ? 'image-off' : 'image'), S('position:absolute;top:8px;left:8px;height:20px;padding:0 6px;display:flex;align-items:center;background:var(--ui-bg);border:1px solid var(--ui-border-accented);color:var(--ui-text-highlighted);font-size:12px;font-weight:500;' + MONO, 'hero · 1200×630'))
+			return D('flex:1;min-height:0;overflow:hidden;background:var(--ui-bg-muted);display:flex;flex-direction:column',
+				D('background:var(--ui-bg);border-bottom:1px solid var(--ui-border);padding:12px ' + pad + 'px;display:flex;align-items:center;gap:12px', S('flex:1;font:600 ' + (m ? 16 : 20) + 'px/28px \'IBM Plex Sans\',sans-serif;color:var(--ui-text-highlighted)', 'How we price a bathroom renovation'), !m && B('Save', { dis: true }), !m && B('Publish', { k: 'primary' })),
+				D('flex:1;overflow:hidden;padding:' + (m ? '20px 16px' : '32px 0') + ';display:flex;justify-content:center', D('width:100%;max-width:680px;display:flex;flex-direction:column;gap:16px;font-family:\'Source Serif 4\',serif;font-size:' + (m ? 16 : 18) + 'px;line-height:1.66;color:var(--ui-text-toned)',
+					S('display:block', 'A bathroom is priced by what has to happen behind the walls before anything gets tiled.'),
+					bl && D('display:flex;flex-direction:column;border:1px solid var(--ui-warning);font-family:\'IBM Plex Sans\',sans-serif;font-size:13px;line-height:20px', img, Alert('warning', 'triangle-alert', ED.msg, 'This image returns an error on the public site.', 'Pick another variant', { icon: 'layers' })),
+					S('display:block', 'We don\'t add a margin on materials you choose yourself.'))))
+		}
+		const EditorPage = () => D('flex:1;min-width:0;min-height:0;display:flex;flex-direction:column', topbar, Editor())
+
+		// ---------- compose
+		const k = s.kind
+		let main
+		if (k === 'list') main = ListPage()
+		else if (k === 'edit') main = m ? null : ListPage()
+		else if (k === 'media' || k === 'detail') main = MediaPage()
+		else if (k === 'cache') main = CachePage()
+		else main = EditorPage()
+		const root = D('width:' + (m ? 390 : 1440) + 'px;height:' + (m ? 844 : 900) + 'px;position:relative;display:flex;flex-direction:' + (m ? 'column' : 'row') + ';background:var(--ui-bg-muted);color:var(--ui-text);font-family:\'IBM Plex Sans\',sans-serif;font-size:13px;line-height:20px;overflow:hidden',
+			!m && side, main,
+			k === 'edit' && (m ? D('position:absolute;inset:0;z-index:40;display:flex', EditPanel()) : D('position:absolute;inset:0;z-index:40;display:flex;justify-content:flex-end;background:var(--rc-overlay)', EditPanel())),
+			k === 'detail' && (DT.preview ? [DetailPanel(), PrevDlg()] : DetailPanel()),
+			k === 'editor' && ED.picker && Picker(),
+			m && s.drawer && D('position:absolute;inset:0;z-index:60;display:flex;background:var(--rc-overlay)', D('width:300px;max-width:85%;height:100%', Side(true))),
+			s.modal && Modal(), s.toasts && Toasts())
+		return { view: root }
+	}
+}
+</script>
+</body>
+</html>

docs/design/source/activity-spec.js

@@ -0,0 +1,55 @@
+export const copy = [
+	['Page title', 'Activity. Regular users: My activity.'],
+	['Subtitle', 'Who did what, and when, across your site. Regular users: Everything you\'ve done on this site.'],
+	['Header action', 'Export CSV (owner and admin only). Preparing: Preparing file… Success toast: Export started. Your file will download shortly. Error toast: Couldn\'t export activity. Try again.'],
+	['Summary labels', 'Total actions · Active people · Failed actions · Security events'],
+	['Summary sub-lines', '12% vs previous 7 days · 7 people, 2 API keys · 0.5% of all actions · 5 failed logins'],
+	['Summary zero', 'Failed: Nothing failed. Security: Nothing to flag. No data at all: No data yet.'],
+	['Filter bar', 'Search activity · All people · All categories · All / Succeeded / Failed · Today / 7 days / 30 days / Custom'],
+	['Chips', 'Search: spring · Person: Marta Alves · Category: Authentication · Outcome: Failed · Dates: 1 – 30 Sep 2026 · Clear all'],
+	['Mobile filters', 'Filters (count badge) · sheet title Filters · Clear all · Show 23 results'],
+	['Day separators', 'Today · Yesterday · 3 Oct 2026'],
+	['Outcome badges', 'Succeeded · Failed. Row markers: Security (shield icon). Target badge: Deleted. Mobile card: Target deleted.'],
+	['Actor badges', 'API key · System. Not signed in: Not signed in.'],
+	['Empty, no activity', 'No activity yet. Actions on articles, media, users and API keys will appear here. Regular users: Your actions will appear here once you start working on the site.'],
+	['Empty, no match', 'No activity matches these filters. Try a different search or a wider date range. Action: Clear filters'],
+	['Error', 'Couldn\'t load activity. Check your connection and try again. Action: Try again'],
+	['Forbidden (403)', 'You can\'t view this activity. Your role doesn\'t include this page. Ask an owner or admin if you need access. Action: Back to home'],
+	['Pagination', 'Showing 1–25 of 1,284 · Rows per page 25 · mobile: Page 1 of 52'],
+	['Slide-over', 'Activity details · When (your time) + UTC line · Actor · Source (Web app, API key, System task) · IP address · Browser · Target · Changes · Before / After · Show more / Show less · Previous event · Next event · Event 2 of 1,284'],
+	['Slide-over, failed', 'Why it failed. Reason text comes from the API (plain language, no stack traces).'],
+	['Slide-over, deleted target', 'This item was deleted. Its name is kept for reference.'],
+	['Slide-over, system', 'Source: System task. IP address and Browser: Not applicable.'],
+	['Body edits', 'Body edited (+312 characters). No body text is shown.'],
+	['Home card', 'Recent activity (regular users: Your recent activity) · View all · Empty: No activity yet · Error: Couldn\'t load recent activity. Try again'],
+	['Retention', 'Retention · How long activity is kept. · Keep activity for: 30 days / 90 days / 365 days / Forever · Older events are removed automatically. · Forever: Nothing is removed automatically. The log grows over time.'],
+	['Retention notice', 'Activity logs are append-only. Events can\'t be edited or deleted from the app. Only the retention period removes them.'],
+	['Retention shorten', 'Events older than 30 days will be removed. This happens at the next cleanup on 7 Oct 2026, 03:00. It can\'t be undone. Actions: Apply 30 days · Cancel'],
+	['Retention status', 'Last cleanup 6 Oct 2026, 03:00 · 142 events removed · Next cleanup 7 Oct 2026, 03:00 · Never / Not scheduled for Forever. Save: Saved · Error: Couldn\'t save the retention period. Your previous setting is still in place.']
+]
+export const comps = [
+	['Page shell, sidebar entry', 'Existing dashboard shell. "Activity" (icon history) between Users and Settings, all verified users.'],
+	['Page header', 'Plain heading + UButton (outline, icon download) for Export CSV.'],
+	['Summary strip', 'Four UCard, each with a UButton-style click target (as="button"). Sparkline: seven div bars in the card (no chart library). Semantic emphasis via error and warning soft tokens.'],
+	['Search', 'UInput, icon search, clearable.'],
+	['Person and Category', 'USelectMenu. Person lists users, API keys and "System" in groups.'],
+	['Outcome and date presets', 'Groups of UButton (soft = selected, outline = other). Custom opens a date-range popover.'],
+	['Active filter chips', 'UBadge (variant subtle) with a trailing UButton (ghost, icon x). "Clear all" is UButton variant link.'],
+	['Timeline table', 'UTable with custom row slots for day separators (full-width row). Cells: UAvatar (initials, key or system icon), UBadge (API key, System, Succeeded, Failed, Deleted, Security).'],
+	['Row hover time', 'Native title attribute on the time cell (keeps to the allowed component list).'],
+	['Pagination', 'UPagination + USelectMenu for page size.'],
+	['Details panel', 'USlideover side="right" on desktop, side="bottom" on mobile. Body uses UCard sections. Prev and next are UButton.'],
+	['Mobile filters', 'USlideover side="bottom" with the same USelectMenu and UButton controls.'],
+	['Mobile list', 'UTable replaced below the md breakpoint by a stacked list of UCard rows.'],
+	['Empty, error, forbidden', 'UEmpty with icon, title, description and one UButton action. Error uses UEmpty in the table area.'],
+	['Loading', 'Skeleton blocks (bg-accented divs with animate-pulse) inside the same UCard and UTable layout.'],
+	['Home card', 'UCard with header, a list of UAvatar rows, and a link UButton.'],
+	['Retention', 'UCard in Settings with USelectMenu and read-only text lines.']
+]
+export const api = [
+	['GET /v1/activity', 'Query: q, actor (user:ID, key:ID, system), category (articles, media, users, api_keys, auth, system), outcome (all, success, failed), range (today, 7d, 30d, custom), from, to (ISO dates), page, size (25, 50, 100). Sorted newest first. Returns items (id, created_at, actor {type, id, name}, category, sentence parts, target {type, id, name, exists}, outcome, failure_reason, security, source, ip, user_agent, changes [{field, before, after, kind}]), total, page, size. Users who are not owner or admin are scoped to their own events by the server; requesting another actor returns 403. Body edits return a single change with kind "body" and a character delta, never the text. The same call powers the Home card (size=5) and the slide-over (items carry the detail fields).'],
+	['GET /v1/activity/summary', 'Query: the same range, from, to. Owner and admin only (403 otherwise). Returns total, previous_total, active_people {users, api_keys}, failed, security, and a 7-day series for each. Clicking a card applies outcome=failed or category in (auth, users role changes, api_keys) to the table, or clears filters for Total.'],
+	['GET /v1/activity/export', 'Query: the same filters, no page or size. Owner and admin only. Streams text/csv with columns when, actor, action, target, outcome, source, ip. No changes or secrets.'],
+	['GET /v1/settings', 'Existing endpoint. Adds activity_retention_days (30, 90, 365, 0 for forever), activity_last_cleanup_at, activity_last_cleanup_removed.'],
+	['PATCH /v1/settings', 'Existing endpoint. Body { activity_retention_days }. Owner only (403 otherwise). Shortening needs the confirm step in the UI first.']
+]

docs/design/states.md

@@ -134,8 +134,26 @@ Every state is drawn at desktop and mobile on the screen boards, with final copy
 | Media picker | `/article/:id/edit` | Inserted | Insert image from either tab | [media-picker](screens/media-picker.md) |
 | Media picker | `/article/:id/edit` | Remove image: confirm | Remove image on an image in the article | [media-picker](screens/media-picker.md) |
 | Media picker | `/article/:id/edit` | Removed | Confirmed | [media-picker](screens/media-picker.md) |
-| Integration | `/integration` | Default | Page load | [integration](screens/integration.md) |
-| Integration | `/integration` | Copied | Copy clicked (2 s) | [integration](screens/integration.md) |
+| Integration | `/integration` | Default | Page load, every endpoint card collapsed | [integration](screens/integration.md) |
+| Integration | `/integration` | Group scrolled, one card expanded | A card opened, one example visible | [integration](screens/integration.md) |
+| Integration | `/integration` | Copied: base URL | Copy clicked (2 s) | [integration](screens/integration.md) |
+| Integration | `/integration` | Copied: CodeBlock | Copy clicked in a code block (2 s) | [integration](screens/integration.md) |
+| Integration | `/integration` | Authentication | API key card, link and notes | [integration](screens/integration.md) |
+| Integration | `/integration` | Session only | Routes API keys cannot call | [integration](screens/integration.md) |
+| Integration | `/integration` | Errors | Status table and plain-text error shape | [integration](screens/integration.md) |
+| Integration | `/integration` | Navigation | Section index active item; mobile Jump to open | [integration](screens/integration.md) |
+| API keys | `/integration/api-keys` | Owner: list | Owner sees every key, with Created by | [integration-api-keys](screens/integration-api-keys.md) |
+| API keys | `/integration/api-keys` | Admin: own keys only | Admin sees only their own keys | [integration-api-keys](screens/integration-api-keys.md) |
+| API keys | `/integration/api-keys` | Loading | First load or retry | [integration-api-keys](screens/integration-api-keys.md) |
+| API keys | `/integration/api-keys` | Empty | No keys yet | [integration-api-keys](screens/integration-api-keys.md) |
+| API keys | `/integration/api-keys` | Error | 500 or network | [integration-api-keys](screens/integration-api-keys.md) |
+| API keys | `/integration/api-keys` | Create key | Modal opened | [integration-api-keys](screens/integration-api-keys.md) |
+| API keys | `/integration/api-keys` | Create key: validation | Name empty or expiry not in the future | [integration-api-keys](screens/integration-api-keys.md) |
+| API keys | `/integration/api-keys` | Create key: name too long | More than 60 characters | [integration-api-keys](screens/integration-api-keys.md) |
+| API keys | `/integration/api-keys` | One-time reveal | Key created, shown once | [integration-api-keys](screens/integration-api-keys.md) |
+| API keys | `/integration/api-keys` | One-time reveal: copied | Copy clicked (2 s) | [integration-api-keys](screens/integration-api-keys.md) |
+| API keys | `/integration/api-keys` | Revoke: confirm | Revoke pressed on a key | [integration-api-keys](screens/integration-api-keys.md) |
+| API keys | `/integration/api-keys` | Revoked | Confirmed, key stays listed as revoked | [integration-api-keys](screens/integration-api-keys.md) |
 | Users | `/users` | Default | List loaded, newest first | [users](screens/users.md) |
 | Users | `/users` | Loading | First load or retry | [users](screens/users.md) |
 | Users | `/users` | Only you | Nobody invited yet | [users](screens/users.md) |
@@ -263,3 +281,62 @@ Added by the Media screens, none of which exist yet:
 - `POST /v1/media/merge`: `{ keep_id, merge_ids }`. Rewrites article bodies from the merged copies' URLs to the kept image's URL, then deletes the copies. 200 with `{ articles_updated, merged }`, 404, 409 when a listed copy is gone or the group changed.
 - `GET /v1/media/{id}/usage`: `[{ id, title, published }]`, read from article bodies.
 - Images no longer belong to an article, and deleting an article no longer deletes images. `POST /v1/article/{id}/image` and `DELETE /v1/article/{id}/image/{imageId}` are replaced by the endpoints above.
+
+## Added with Media cleanup
+### Media cleanup
+| State | Surface | Behaviour |
+|---|---|---|
+| Default | Settings card | Off, "Never run", no "Every" row |
+| On | Settings card | "Every" 30 days, last and next run |
+| Saving / Saved | Settings card header | "Saving…" then "Saved" for 2 s, polite live region |
+| Save failed | Under the field | "Couldn't save. Try again in a moment." Control reverts |
+| Validation | Under the field | "Enter a whole number of days between 1 and 365." Nothing sent |
+| Read-only | Settings card | Controls disabled, button hidden, info alert |
+| Loading | Settings card | Skeleton after 150 ms |
+| Offline | Settings and Media | Banner as on Media. Controls and buttons disabled |
+| Preview loading | Dialog | Skeleton rows, confirm disabled |
+| Confirm | Dialog | Summary, up to 5 groups, link to Duplicates |
+| In progress | Dialog | "Purging…", loader-circle, not dismissible |
+| Nothing to purge | Dialog | Info state, "Close" only |
+| Error | Dialog | Notice, stays open, confirm retries |
+| Partial | Dialog | Warning, summary refreshes, "Close" and "Retry" |
+| Conflict (409) | Dialog | Warning, summary refreshes |
+| Success | Toast, 5 s | "Duplicates purged" / "9 copies merged. 12 articles updated." "Last purge" updates in place |
+| Unattended run | Settings | No toast. Updated on next visit |
+
+401 and 403 are global and have no local copy.
+
+## Added with Activity
+### Activity
+| State | Surface | Behaviour |
+|---|---|---|
+| Default | `/activity` | Strip, filters, day-grouped table, pagination |
+| Loading | `/activity` | Skeleton strip and rows after 150 ms |
+| Zero-value strip | `/activity` | Failed and Security show a calm 0 |
+| Filtered | `/activity` | Chips and "Clear all"; a strip card applies its filter |
+| Empty, no activity | `/activity` | "No activity yet"; Export disabled |
+| Empty, no match | `/activity` | "No activity matches these filters" with "Clear filters" |
+| Error | `/activity` | "Couldn't load activity" with "Try again"; the strip may still show |
+| Forbidden (403) | `/activity` | "You can't view this activity." with "Back to home" |
+| Details | Slide-over / bottom sheet | Sentence, time, actor, source, target, reason, changes, previous and next |
+| My activity | `/activity` | No strip, Person filter or Export; own events only |
+| Export | Header button, toasts | "Preparing file…", then "Export started. Your file will download shortly." or "Couldn't export activity. Try again." |
+| Home card | `/home` | Owner or admin, regular user, loading, error, empty |
+| Retention | `/settings` | Default (90 days or 5 GB), age only, size only (Forever), shortening (confirm), save error |
+
+401 is global. The 403 on `/activity` has local copy because the page itself is refused; the 403 on the summary or export of a non-admin is never shown, since the controls are hidden.
+
+## Added with Image variants
+
+Every state is drawn on `source/RenewCMS Screens Image variants.dc.html` and listed with its trigger and copy in [image-variants](screens/image-variants.md), which also holds the states matrix and the back-office error copy (400, 401, 403, 404, 409, 413, 422, 500).
+
+| Screen | Route | States |
+|---|---|---|
+| Variants list | `/settings/media/variants` | Loaded, loading, empty (two templates), error, forbidden, row menu, row action in progress, purge confirm, delete confirm, delete in progress, request reference |
+| Add / edit variant | slide-over (desktop), full page (mobile) | Create pristine and dirty, field errors, no dimension, name taken (409), saving, save error, edit pristine and dirty, unsaved changes, PNG without quality |
+| Media library | `/media` | Grid with badges, sort menu, filter With variants, filter Without, nothing to show, delete confirm with variants |
+| Image detail | `/media` (panel) | Partly generated, nothing generated, generating, generation failed, no variants defined, SVG source, animated GIF source, preview dialog |
+| Cache | `/settings/media/cache` | Loaded, loading, empty, purging, purge done, purge failed, error, purge all (confirm, typed), purge unused |
+| Editor picker | `/article/:id/edit` | Variant select, select open, no variants defined, variant deleted, variant disabled |
+
+The public request contract (200, 400 `unknown_variant` or `unsupported_parameter`, 404) is not a screen; it is section 7 of the same file.

docs/development.md

@@ -55,6 +55,8 @@ If your editor reports `pattern all:dist: no matching files found`, either run `
 ```sh
 task --list          # everything available
 task test            # Go tests; extra args pass through: task test -- -run TestCreateArticle -v
+task test:mysql      # MySQL tests against real servers in Docker (mysql:8.4, then mariadb:11)
+task test:postgres   # PostgreSQL tests against real servers in Docker (postgres:16, then postgres:17)
 task cover           # coverage of the use cases → tmp/coverage.out
 task mutate          # gremlins mutation testing → tmp/gremlins.json
 task test:web        # SPA component tests (Vitest)

docs/docker.md

@@ -0,0 +1,242 @@
+# Docker
+
+RenewCMS runs as a container. The image is published to the registry at `git.floriansylvain.fr/fsylvain/renewcms`, so site operators pull it and never build from source; it can also be built from this repository. The image holds only the single binary (SPA embedded) on Alpine, runs as a non-root user (uid 10001) and keeps all state on one volume mounted at `/data`. It reuses the configuration contract described in [configuration.md](configuration.md); there are no Docker-specific variables.
+
+Requirements: Docker with Compose v2. [task](https://taskfile.dev) is optional for operators and needed to build from source or to publish. Building needs no local Go or Bun. The image build bundles the SPA with `vite build` only; the `vue-tsc` type-check is not run inside the image (it does not work under the Bun-only build image), so keep running `bun run type-check` locally.
+
+## Quick start
+
+1. Copy the example env file and edit it:
+
+   ```sh
+   cp docker.env.example docker.env
+   ```
+
+   Set `PUBLIC_URL`, the `SMTP_*` values and a generated secret (`openssl rand -hex 32`) for `JWT_SECRET`. `docker.env` is git-ignored and excluded from the build context, so it never ends up in an image. Never commit it.
+
+2. Pull and start the published image:
+
+   ```sh
+   docker compose pull
+   docker compose up -d
+   ```
+
+   `docker-compose.yml` uses `image: ${RENEWCMS_IMAGE:-git.floriansylvain.fr/fsylvain/renewcms:beta}`. The default tag is `beta` because `latest` does not exist until the first stable release (the default changes to `latest` then). Set `RENEWCMS_IMAGE` in your shell or in a `.env` file next to the compose file to pin another tag, for example `RENEWCMS_IMAGE=git.floriansylvain.fr/fsylvain/renewcms:v2.9.0-beta`.
+
+   To build from the local sources instead, see [Building from source](#building-from-source).
+
+3. Check it: `curl http://localhost:8080/healthz` returns `ok`, and `http://localhost:8080/` serves the SPA.
+
+Other tasks: `task docker:pull`, `task docker:upgrade` (pull, then `docker compose up -d`), `task docker:up` (local build, see below), `task docker:build` (image only, tagged with the `git describe` version and `latest`), `task docker:run` (one-off foreground run on the volume `renewcms-data`, without Compose), `task docker:logs` and `task docker:down`.
+
+If a required variable is missing the container exits non-zero and the log names it, for example `Environment variable JWT_SECRET is not set`.
+
+### Local trial over plain HTTP
+
+`ENVIRONMENT` defaults to `production`, which makes the auth cookie `Secure`: browsers do not store it over `http://`, so login appears to fail. For a local trial on `http://localhost:8080`, set `ENVIRONMENT=development` and `PUBLIC_URL=http://localhost:8080` in `docker.env`. Use `production` only behind HTTPS.
+
+## Building from source
+
+`docker-compose.build.yml` adds the `build:` section and tags the result `renewcms:${VERSION:-dev}`. Use it as an override:
+
+```sh
+docker compose -f docker-compose.yml -f docker-compose.build.yml up -d --build
+```
+
+`task docker:up` does the same and passes the `git describe` version as `VERSION`. To check what Compose resolves, run `docker compose config`: without the override it shows the registry image and no `build` section, with it the `build` section is present.
+
+## Image tags
+
+| Release | Tags pushed |
+|---|---|
+| `vX.Y.Z` (stable) | `vX.Y.Z`, `X.Y.Z`, `X.Y`, `latest` |
+| `vX.Y.Z-<pre>` (for example `v2.9.0-beta`, `v2.9.0-rc.1`) | `vX.Y.Z-<pre>`, `X.Y.Z-<pre>`, and the moving tag `<pre-name>` (`beta`, `rc`) |
+
+A pre-release never moves `latest`. Images are published for `linux/amd64` and `linux/arm64`. `renewcms --version` in the image prints the exact release tag. Images are not signed; the Ed25519 key signs the release binaries only.
+
+## Environment
+
+Compose reads `docker.env` through `env_file` and sets `DB_FILE=/data/renewcms.db` and `UPLOAD_DIR=/data/uploads` itself. Everything in [configuration.md](configuration.md) can go in `docker.env`. To publish another host port, change the left side of `ports` in `docker-compose.yml`; keep `PORT` at 8080 unless you also change the healthcheck.
+
+The container receives SIGTERM on stop, and RenewCMS shuts down gracefully within 10 seconds. Compose uses `stop_grace_period: 15s`. The healthcheck calls `/healthz` inside the container.
+
+## Data volume
+
+State lives on the named volume `renewcms-data` (Compose prefixes it with the project name, usually `renewcms_renewcms-data`; check with `docker volume ls`). It holds the SQLite database (unless you use MySQL), uploads, and update records.
+
+- `docker compose down` removes the container and keeps the volume. The data survives and `docker compose up -d` brings it back.
+- **`docker compose down -v` deletes the volume and all data.** The next start is an empty instance.
+
+### Backup
+
+Replace `VOLUME` with the real volume name. The image has no `sqlite3`, so stop the service for a consistent copy:
+
+```sh
+docker compose stop
+docker run --rm -v VOLUME:/data -v "$PWD":/backup alpine tar czf /backup/renewcms-backup.tar.gz -C /data .
+docker compose start
+```
+
+### Restore into a fresh volume
+
+```sh
+docker compose down -v
+docker volume create VOLUME
+docker run --rm -v VOLUME:/data -v "$PWD":/backup alpine sh -c "tar xzf /backup/renewcms-backup.tar.gz -C /data && chown -R 10001:10001 /data"
+docker compose up -d
+```
+
+## MySQL or MariaDB
+
+SQLite on the `/data` volume is the default. [`docker-compose.mysql.yml`](../docker-compose.mysql.yml) runs RenewCMS next to a MySQL 8.4 container instead:
+
+```sh
+export MYSQL_ROOT_PASSWORD=<generated>
+export DB_PASSWORD=<generated>
+docker compose -f docker-compose.mysql.yml up -d
+```
+
+It starts the `mysql` service with a named volume `mysql-data` and a healthcheck, and starts `renewcms` only once the database is healthy (`depends_on` with `service_healthy`). RenewCMS gets `DB_DRIVER=mysql`, `DB_HOST=mysql`, `DB_NAME`, `DB_USER` and `DB_PASSWORD` from the compose file and the rest from `docker.env`. `DATA_DIR=/data` keeps update state and the `.sql` pre-update backups on the `renewcms-data` volume, which still holds the uploads. Replace the placeholders; never commit real passwords.
+
+To use MariaDB, change the `mysql` service image to `mariadb:11`, its `MYSQL_*` variables to `MARIADB_*` and its healthcheck to `healthcheck.sh --connect --innodb_initialized`. To use a server outside Compose, drop the `mysql` service and point `DB_HOST` at it. For a server on another machine set `DB_TLS=true`.
+
+Back the database up with `docker compose -f docker-compose.mysql.yml exec mysql mysqldump ...` (a `tar` copy of the volume is not consistent while it runs), and the `renewcms-data` volume as described above. Moving an existing SQLite volume is a manual procedure, see [deployment.md](deployment.md#moving-an-existing-sqlite-site-to-mysql).
+
+## PostgreSQL
+
+[`docker-compose.postgres.yml`](../docker-compose.postgres.yml) runs RenewCMS next to a PostgreSQL 17 container:
+
+```sh
+export DB_PASSWORD=<generated>
+docker compose -f docker-compose.postgres.yml up -d
+```
+
+It starts the `postgres` service with a named volume `postgres-data` and a `pg_isready` healthcheck, and starts `renewcms` only once the database is healthy (`depends_on` with `service_healthy`). RenewCMS gets `DB_DRIVER=postgres`, `DB_HOST=postgres`, `DB_PORT`, `DB_NAME`, `DB_USER`, `DB_PASSWORD` and `DB_SSLMODE=disable` (the traffic stays on the Compose network) from the compose file and the rest from `docker.env`. `DATA_DIR=/data` keeps update state and the `.sql` pre-update backups on the `renewcms-data` volume. For a server on another machine drop the `postgres` service, point `DB_HOST` at it and set `DB_SSLMODE=require`. Back the database up with `docker compose -f docker-compose.postgres.yml exec postgres pg_dump -U renewcms renewcms`. Replace the placeholders; never commit real passwords.
+
+## S3-compatible storage (SeaweedFS)
+
+[`docker-compose.s3.yml`](../docker-compose.s3.yml) runs RenewCMS with `STORAGE_DRIVER=s3` next to a [SeaweedFS](https://github.com/seaweedfs/seaweedfs) server (Apache 2.0, image `chrislusf/seaweedfs`, override with `SEAWEEDFS_IMAGE`) with its S3 gateway enabled, and a one-shot `seaweedfs-init` step that creates the bucket with `weed shell`:
+
+```sh
+export S3_SECRET_ACCESS_KEY=<generated>
+docker compose -f docker-compose.s3.yml up -d
+```
+
+RenewCMS gets `S3_ENDPOINT=http://seaweedfs:8333`, `S3_PATH_STYLE=true`, the bucket name and the access key (`S3_ACCESS_KEY_ID`, default `renewcms`, and `S3_SECRET_ACCESS_KEY`) from the compose file, and the rest from `docker.env`. SeaweedFS reads the same key pair as its admin identity. The `renewcms-data` volume then holds the SQLite database and update state but no uploads; the images live in the `seaweedfs-data` volume. The bucket is not published and the app serves the images. SeaweedFS is used because MinIO stopped publishing community images. To use AWS S3 or another provider, drop the `seaweedfs` services and set the `S3_*` variables in `docker.env` (see [configuration.md](configuration.md#image-storage)). The volume backup above covers the database only, so back the bucket up separately. To move existing uploads see [configuration.md](configuration.md#moving-existing-uploads-to-a-bucket).
+
+`task test:s3` starts a throwaway SeaweedFS and runs the storage integration test against it; it skips with a message when Docker is not available.
+
+## Reverse proxy and TLS
+
+With `ENVIRONMENT=production` the site must be served over HTTPS, so put a reverse proxy in front and set `PUBLIC_URL` to the public `https://` address. Bind the published port to the host only when the proxy runs on the same host, by changing `ports` to `"127.0.0.1:8080:8080"`.
+
+Caddy on the host:
+
+```caddyfile
+cms.example.com {
+	reverse_proxy 127.0.0.1:8080 {
+		header_up X-Real-IP {remote_host}
+	}
+}
+```
+
+nginx on the host:
+
+```nginx
+server {
+    listen 443 ssl;
+    server_name cms.example.com;
+    client_max_body_size 20m;
+
+    location / {
+        proxy_pass http://127.0.0.1:8080;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-Proto $scheme;
+    }
+}
+```
+
+Set `TRUSTED_PROXIES` to the proxy address as the container sees it, otherwise the login rate limiter ignores `X-Real-IP` and counts every client as the proxy. With a proxy on the host and the default bridge network, that is the bridge gateway (check with `docker network inspect`, often `172.17.0.1` or the Compose network gateway). With a proxy container on the same Compose network, it is that container's IP. The value is a semicolon-separated list of exact IPs, no CIDR. See [deployment.md](deployment.md#4-put-https-in-front).
+
+## SMTP
+
+RenewCMS sends registration and password-reset mail through the `SMTP_*` variables. Use your provider's host and port in `docker.env`.
+
+To use a mail server running on the Docker host, set `SMTP_HOST=host.docker.internal`. Docker Desktop resolves that name. On Linux add the mapping to the service in `docker-compose.yml`:
+
+```yaml
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+```
+
+The host MTA must listen on an address reachable from the container, not only on `127.0.0.1`.
+
+If SMTP is unreachable, the server still starts. Only the actions that send mail (registration, password reset, invitations) fail, and the error appears in `docker compose logs renewcms`.
+
+## Upgrading
+
+1. Back up the volume (see above).
+2. Pull the new image and recreate the container on the same volume:
+
+   ```sh
+   docker compose pull
+   docker compose up -d
+   ```
+
+   `task docker:upgrade` runs both. The schema is migrated at startup, and there is no down-migration.
+3. Check `docker compose logs renewcms` for the new version line, or `docker run --rm git.floriansylvain.fr/fsylvain/renewcms:beta --version`. The owner's Settings page also shows the running version.
+
+To roll back, set `RENEWCMS_IMAGE` to the previous tag, run `docker compose up -d`, and restore the backup if the schema changed.
+
+If you built from source, upgrade with `git pull` and `task docker:up` instead.
+
+## Maintainer: publishing
+
+Publishing is a manual, maintainer-run task, like `task release`. There is no CI pipeline.
+
+1. Tag the release and keep the work tree clean:
+
+   ```sh
+   git tag v2.9.0-beta
+   ```
+
+2. Log in once to the registry. The task never reads or stores credentials:
+
+   ```sh
+   docker login git.floriansylvain.fr
+   ```
+
+3. Make sure a buildx builder can build both platforms. Check with `docker buildx ls`. With the containerd image store (the Docker Desktop default) the default builder already works. Otherwise create one, and on a Linux host install the QEMU emulators:
+
+   ```sh
+   docker buildx create --use
+   docker run --privileged --rm tonistiigi/binfmt --install arm64
+   ```
+
+4. Publish:
+
+   ```sh
+   task docker:publish
+   ```
+
+   `REGISTRY_IMAGE` defaults to `git.floriansylvain.fr/fsylvain/renewcms` and `VERSION` to `git describe --tags`. The task refuses to run, before building anything, when `REGISTRY_IMAGE` is empty, when `VERSION` is not an exact tag `vX.Y.Z` or `vX.Y.Z-<pre>` on HEAD, when the work tree is dirty, or when the builder cannot build `linux/amd64` and `linux/arm64`. It prints the tags it pushes.
+
+### Dry run
+
+```sh
+task docker:publish -- --dry-run
+task docker:publish VERSION=v2.9.0-rc.1 -- --dry-run
+```
+
+The dry run builds for the host platform only, loads the image into the local Docker, pushes nothing and needs no login. It prints the tags a real run would push. A `VERSION` override is accepted only with `--dry-run`, and a dirty tree is allowed there. Remove the loaded images afterwards with `docker rmi`.
+
+### After pushing
+
+- `docker buildx imagetools inspect git.floriansylvain.fr/fsylvain/renewcms:<tag>` lists `linux/amd64` and `linux/arm64`.
+- The moving tag (`beta`) points at the new digest, and `latest` did not move for a pre-release.
+- On a clean machine, `docker compose pull && docker compose up -d` starts the new image and Settings shows the new version.
+
+## Limitations
+
+Browser updates are unsupported in Docker (they need Linux with systemd, and a binary replaced inside a container is lost when it is recreated). The image and `docker-compose.yml` set `RENEWCMS_CONTAINER=true`, so the owner's Settings page shows when a newer version exists and tells them to pull a new image: `docker compose pull && docker compose up -d`. There is no Update or Restart button. Upgrade by pulling the image as above, or by rebuilding it if you build from source.

docs/image-variants.md

@@ -0,0 +1,127 @@
+# Image variants
+
+An owner or admin defines named variants of the stored images. A request for
+`/static/uploadedImages/<storedName>?v=<name>` generates the variant on first use, caches it and
+serves the cached file afterwards. The original is never changed. Only a variant that exists and is
+enabled is served. The visual spec is `docs/design/screens/image-variants.md`; the management routes
+are in [api.md](api.md#image-variants); the layering is in [architecture.md](architecture.md#image-variants).
+
+## Public contract
+
+| Request | Result |
+| --- | --- |
+| `…/a1b2.png` | The stored file, exactly as before this feature. |
+| `…/a1b2.png?v=thumb` | 200, the cached variant. Other query parameters (`t=123`) are ignored. |
+| `?v=` with an unknown, disabled, deleted or badly written name | 400 `{"status":400,"error":"unknown_variant","message":"Unknown variant","detail":"<name>"}`. |
+| `width`, `height`, `format` or `quality` | 400 `unsupported_parameter` with the parameter as `detail`. It wins over `unknown_variant`. |
+| A missing source (also `..` and nested paths) | 404, after the parameter checks. |
+| A blob that has no image record (a generated variant file, an orphan) | 404 for `?v=`, after the parameter checks and before any storage read. Without `?v=` the blob is served as before. |
+| A source bigger than `IMAGE_VARIANT_MAX_SOURCE_BYTES` | 413 `The source image is too large to generate this variant.` (plain text). The original is never capped. |
+| A source whose header declares more than `IMAGE_VARIANT_MAX_SOURCE_PIXELS` (width x height) | The same 413 and body. The header is read before any pixel buffer is allocated, so a small file declaring 30000 x 30000 is refused without being decoded. |
+| A source that cannot be decoded, a header that cannot be read, or a failing render | 500, nothing is cached, the next request tries again. |
+
+The 400 body is JSON with `Content-Type: application/json`. Every other error is plain text.
+
+SVG sources and animated GIFs are served as they are, with the variant parameters validated but no
+generation, even above the size cap. A one-frame GIF is a normal raster source.
+
+The response carries an `ETag` derived from the variant settings (width, height, fit, format, quality)
+and the source stored name. It is an opaque quoted value. `If-None-Match` answers 304 before the cache
+is read. Changing `generate_on_upload` or `enabled` does not change it; changing any rendering
+setting does, so a client holding an old value gets a fresh 200. `Cache-Control` stays
+`public, no-cache`.
+
+## Cache
+
+Every generated file is a blob in `image.Storage` (local directory or S3) plus a row in
+`image_variant_files` (variant, source stored name, cached stored name, content type, size, settings
+fingerprint). The pair (variant, source) is unique. Concurrent first requests share one generation
+(`singleflight` keyed by variant, settings and source); different variants or different images are
+generated in parallel.
+
+Only a stored name that has an image record can be a variant source, so generated files and orphan blobs
+are never rendered. At most `IMAGE_VARIANT_MAX_CONCURRENT_RENDERS` (default 4) renders run at once:
+the slot is taken inside the shared generation, so identical concurrent requests use one slot, and a
+request waiting for a slot stops waiting when its client goes away, without rendering. A cached
+file never takes a slot. The pixel cap defaults to 50000000 pixels.
+
+- Editing a rendering setting (`width`, `height`, `fit`, `format`, `quality`) purges the variant's
+  files; the next request regenerates. Switching `generate_on_upload` or `enabled` keeps them, so
+  re-enabling a variant serves from its kept cache.
+- A row whose fingerprint differs from the variant (an edit raced a generation) or whose blob is gone
+  is regenerated and replaced, and the old blob is removed.
+- Deleting a variant, purging it, deleting a source image or merging copies removes the blobs first
+  and the rows second. A blob that cannot be deleted keeps its row, the call answers 500 and a retry
+  finishes the job. A blob that is already missing does not stop a purge.
+- `generate_on_upload` is stored and returned only. Generating at upload time is not part of this
+  release.
+
+### Request tracking and the Cache screen
+
+`/settings/media/cache` shows what the cache holds and purges it by scope (all, unused, one variant,
+one image). It reads `GET /v1/image-variants/cache` and writes `POST /v1/image-variants/cache/purge`
+([api.md](api.md)).
+
+Two things are tracked for it, without a database write per request. `usage.Tracker`
+(`internal/infrastructure/usage`) keeps in memory, behind the `image.VariantUsageTracker` port, the
+last time each (variant, source) file was requested and a counter of rejected requests per UTC day.
+`ServeVariantUseCase` records a hit when a cached file is served, when a file is generated by the
+request and on a 304; it counts a rejection when the request answers 400 (unknown or disabled
+variant, unsupported parameter). A missing source (404), a request without `?v=` and the admin
+generation routes record nothing. The tracker flushes one batch through `image.VariantUsageRepository`
+every 30 seconds, as soon as 500 distinct files are pending, before `GET /v1/image-variants/cache`
+reads, and on graceful shutdown; only `api/dependecyInjection.go` builds it and starts the loop. A
+failed flush keeps the pending hits and counts, so nothing is lost or counted twice. The stored
+`last_requested_at` of a file never moves back, a late update for a purged file changes nothing, and
+day rows older than 7 days are deleted by the flush.
+
+A file is unused when its reference time (`last_requested_at`, or `created_at` when never requested)
+is older than 30 days and its variant is enabled. A purge reads the rows in batches of 500 and keeps
+the rows whose blob cannot be deleted. Each scope records its own activity action
+(`media.variant_purge_all`, `media.variant_purge_unused`, `media.variant_purge`,
+`media.variant_purge_image`).
+
+## Geometry
+
+Images are never enlarged.
+
+- With one dimension, the image keeps its aspect ratio and the output is at most that size.
+- `inside` fits the whole image in the box, without padding.
+- `cover` fills the box and crops around the centre. A box larger than the source is first scaled
+  down, keeping its aspect ratio, until it fits inside the source (300 x 200 into 400 x 300 gives
+  267 x 200).
+- `contain` with both width and height scales the image to fit inside the box, never enlarging it, and
+  centres it on a canvas of exactly width x height: a 300 x 200 image in a 400 x 300 box stays
+  300 x 200 on a 400 x 300 canvas, and a 40 x 20 image in a 40 x 40 box is padded to 40 x 40. With a
+  single dimension there is no box, so no padding and no upscaling.
+
+### Padding colour of `contain`
+
+The design does not draw it, so it is decided here: the padding is transparent for `png` and `webp`
+outputs and white (`#FFFFFF`) for `jpeg` outputs, which have no alpha. A `jpeg` output also flattens
+any transparency of the source onto white (`#FFFFFF`).
+
+## Formats
+
+`original` keeps the source format (a GIF source becomes PNG). `jpeg` and `webp` use `quality`
+(default 82); `png` ignores it and the API returns `quality: null`. A WebP source always decodes. The
+renderer reports the formats it can encode; the API refuses a format it cannot encode with
+`Format must be original, jpeg or png.`.
+
+## Spike: a CGO-free lossy WebP encoder
+
+The standard library and `golang.org/x/image` can decode WebP but not encode it, and the build must
+stay `CGO_ENABLED=0` (six release targets, pure-Go SQLite).
+
+| Candidate | Lossy | `CGO_ENABLED=0` | Verdict |
+| --- | --- | --- | --- |
+| `golang.org/x/image/webp` | decode only | yes | Cannot encode. |
+| `github.com/gen2brain/webp` v0.6.4 (libwebp translated to Go with wasm2go; `purego` only for the optional dynamic library) | yes, with alpha | yes | Adopted. |
+
+The spike built `gen2brain/webp` for linux, darwin and windows on amd64 and arm64 with
+`CGO_ENABLED=0`, and `go list -deps` shows no package with cgo files. On a noisy 4032 x 3024 image
+a lossy encode took about 0.75 s at quality 20 and 1.5 s at quality 95 (a smaller, real photograph is
+faster). Output is `RIFF....WEBP`, and a lower quality gives a smaller file. Decision: `webp` is offered
+as an output format. Should the dependency ever be dropped, `NewVariantRendererEncoding` already
+builds a renderer without the WebP encoder: the API then refuses `webp` with 422, and a WebP source
+with format `original` is served as PNG.

docs/release-notes.md

@@ -30,3 +30,8 @@ Each body lives in `docs/releases/<tag>.md`. Publish with `tea releases create -
 | `v2.6.0-beta` | v2.6.0-beta - Signed updates and browser restart |
 | `v2.6.2-beta` | v2.6.2-beta - English and French interface |
 | `v2.7.0-beta` | v2.7.0-beta - Markdown and block article bodies |
+| `v2.8.0-beta` | v2.8.0-beta - API keys and API reference |
+| `v2.8.1-beta` | v2.8.1-beta - Docker deployment |
+| `v2.8.2-beta` | v2.8.2-beta - Security headers and clearer log in errors |
+| `v2.8.3-beta` | v2.8.3-beta - Security policy fixes for the web app |
+| `v3.1.0-beta` | v3.1.0-beta - Image variants |

docs/releases/v2.8.0-beta.md

@@ -0,0 +1,41 @@
+This release adds API keys, so a script or service can use the whole API without the web interface, and turns the Integration page into a complete API reference.
+
+## New
+
+**API keys**
+
+- Create named API keys from the new API keys screen under Integration, with an optional expiry date. The full key is shown once, when you create it, and only its prefix is visible afterwards.
+- Send a key as `Authorization: Bearer rcms_...` to manage articles, media, users and invites, and to read settings. A key acts with exactly the rights of the user who created it, so an admin's key cannot do owner-only things.
+- Revoke a key at any time. Active, expired and revoked keys all stay listed with their status, creation date and last use.
+- The owner sees every key and who created it. Admins see only their own.
+- Each key is limited to 120 requests per minute.
+- Resetting a user's password revokes all of that user's keys.
+
+**API reference**
+
+- The Integration page now documents every route a developer can call, grouped by area: articles, media, users and invites, and settings. Each endpoint lists who can call it, its request body, ready-to-copy fetch and curl examples, a sample response and its error statuses.
+- A new Authentication section explains public access and API keys, and a section index lets you jump between groups.
+- Routes that need a signed-in browser session are listed separately, and the page shows the real error messages the API returns.
+- The Integration page and the API keys screen are available in English and French.
+
+## API
+
+- `POST /v1/api-key` creates a key. It answers `201` with the key, shown once.
+- `GET /v1/api-key` lists keys, newest first, each with a `status` of `active`, `expired` or `revoked`. For the owner, each entry also carries `created_by_name`.
+- `DELETE /v1/api-key/{id}` revokes a key and answers `204`, also when the key is already revoked.
+- An invalid, unknown, expired or revoked key answers `401` on every route, including public ones, and is never treated as anonymous.
+- A key calling a session-only route answers `403` with "This action needs a real session." These routes are `/v1/api-key`, `POST /v1/auth/verify`, `DELETE /v1/auth/register` and everything under `/v1/system`.
+- `GET /v1/auth/me` accepts an API key, so a client can check who a key belongs to.
+- A key beyond 120 requests per minute gets `429` with a `Retry-After` header.
+- Cross-origin requests now allow the `PATCH` method.
+
+## Under the hood
+
+- Add the API key domain, use cases, SQLite repository and an authentication middleware that runs after each token verifier. Keys are generated by a new domain interface and stored as SHA-256 hashes, never in clear.
+- Add a typed API catalogue that drives the Integration page, with a test that every route has a description.
+- Add the API keys and Integration specifications and QA procedures to `features/`, and the API key reference to `docs/api/`.
+
+## Upgrading
+
+- Replace the binary. The new API keys table is created automatically at startup. No new environment variable is required.
+- Browsers calling the API from another origin can now use `PATCH`. Check your CORS configuration only if you restricted methods in a reverse proxy.

docs/releases/v2.8.1-beta.md

@@ -0,0 +1,36 @@
+This release adds an official Docker deployment, so RenewCMS can run in a container instead of as a binary under systemd, and teaches Settings to guide container installs through updates.
+
+## New
+
+**Docker deployment**
+
+- A container image holds the single RenewCMS binary on Alpine, runs as a non-root user and keeps the database and uploads on one volume. A Compose file starts it with an env file and a health check.
+- Images are published for amd64 and arm64 to the project registry at `git.floriansylvain.fr/fsylvain/renewcms`. Prereleases carry the version tag and a moving `beta` tag, and `latest` is only used for stable releases.
+- Upgrading is `docker compose pull && docker compose up -d`. Your data stays on the volume.
+- A new Docker guide covers the quick start, backups of the data volume, the reverse proxy and TLS, reaching an SMTP server from the container, and building the image from source.
+
+**Update guidance in containers**
+
+- In a container, Settings no longer shows the browser update flow, which cannot work there. It shows the new version, the command to run on the server with a Copy button, and a link to the Docker guide.
+- Download and restart are not offered in a container, and the API refuses them.
+
+## API
+
+- `GET /v1/system/update` has a new `container` boolean. It is `true` when the server runs in a container, and `can_apply` is then always `false`.
+- `POST /v1/system/update/download` and `POST /v1/system/update/restart` answer `409` in a container, as they already do when browser updates are not set up.
+
+## Under the hood
+
+- Add a multi-stage Dockerfile, a Compose file with a separate build override, and tasks to build, run, pull, upgrade and publish the image. Publishing is a maintainer task that refuses to run unless the version is an exact tag on a clean tree.
+- Add the container update guidance and the image publishing specifications and QA procedures to `features/`.
+
+## Upgrading
+
+- Replace the binary. No schema change and no required environment variable.
+- There is one new optional variable, `RENEWCMS_CONTAINER`, which defaults to `false`. The Docker image and the Compose file set it to `true`. Leave it unset on a binary install.
+- Docker users start from the Docker guide. To move an existing binary install to Docker, copy the database and uploads into the volume and keep the same environment variables.
+
+## Known limitations
+
+- Browser updates are not available in a container. Update by pulling a new image.
+- The new container wording in Settings has no design frame yet.

docs/releases/v2.8.2-beta.md

@@ -0,0 +1,18 @@
+This release hardens the server with browser security headers on every response and makes the log in form clearer when the username is wrong.
+
+## Improvements and fixes
+
+- RenewCMS now sends security headers on every response, including the web app and uploaded images: a Content Security Policy that forbids framing, `X-Content-Type-Options`, `X-Frame-Options`, `Referrer-Policy` and `Cross-Origin-Opener-Policy`. With `ENVIRONMENT=production` it also sends `Strict-Transport-Security`.
+- The log in form now tells you when you typed an email address instead of your username, and when the username is longer than 20 characters, instead of only asking for at least 3 characters. The messages are available in English and French.
+
+## Under the hood
+
+- Add a security headers middleware, mounted on the whole router, with tests.
+- Document the headers, the Google Fonts and `https:` image allowances in the policy, and the advice not to duplicate them in the reverse proxy in the deployment guide.
+
+## Upgrading
+
+- Replace the binary, or pull the new image. No schema change and no new environment variable.
+- If your reverse proxy already adds the same security headers, remove them there, or browsers will receive them twice.
+- The policy allows scripts from the same origin only. A custom script injected by your proxy will be blocked.
+- Serve the site over HTTPS only when `ENVIRONMENT=production`, because the server then asks browsers to remember HTTPS for a year.

docs/releases/v2.8.3-beta.md

@@ -0,0 +1,18 @@
+This release fixes the security headers added in v2.8.2-beta, which blocked parts of the web app in the browser.
+
+## Improvements and fixes
+
+- The web app's icons now display again. They are bundled into the app instead of being fetched from an external icon service, which the security policy blocked.
+- The light and dark mode script in the page is now allowed by the security policy, so the color mode no longer fails to apply on load.
+- The security policy now allows WebAssembly, which parts of the web app need.
+
+## Under the hood
+
+- Add a Vite plugin that bundles only the Lucide icons the app uses.
+- Compute a hash for each inline script in the served page and add it to the `script-src` directive, instead of allowing inline scripts in general.
+- Update the security headers tests.
+
+## Upgrading
+
+- Replace the binary, or pull the new image. No schema change and no new environment variable.
+- If you are on v2.8.2-beta, upgrade: that version's policy broke icons and color mode.

docs/releases/v2.9.0-beta.md

@@ -0,0 +1,34 @@
+This release adds a duplicate purge to the media library: owners and admins can merge identical images in one action, or let RenewCMS do it on a schedule.
+
+## New
+
+**Media duplicate purge**
+
+- Purge duplicates from the Duplicates tab of the media library with the new toolbar button, or from the new Media cleanup card in Settings. A summary shows how many copies would be merged and how many articles would be updated before you confirm.
+- For each group of identical images used in at least one article, the most used copy is kept, with ties going to the oldest. Every other copy is merged into it and the articles that used them are rewritten. Groups where no copy is used are left alone.
+- If the library changes between the summary and the confirmation, nothing is purged and you are asked to check the new summary.
+- Turn on automatic purge in Settings and choose an interval from 1 to 365 days, 30 by default. The first run happens one interval after you turn it on, then once per interval after each run.
+- The Media cleanup card shows the last run, with the number of copies merged and articles updated, and the date of the next one.
+- The purge is reserved for owners and admins. Editors get a clear message instead of the controls.
+- The new screens are available in English and French.
+
+## API
+
+- `GET /v1/media/purge-settings` returns the automatic purge settings: `auto_purge_enabled`, `auto_purge_interval_days`, `last_purge_at`, `last_purge_merged`, `last_purge_articles_updated` and `next_purge_at`, which is `null` while automatic purge is off.
+- `PATCH /v1/media/purge-settings` updates `auto_purge_enabled` and `auto_purge_interval_days`. An interval outside 1 to 365 answers `400`.
+- `GET /v1/media/purge-preview` returns what a purge would do, with a `fingerprint` of the plan. It changes nothing.
+- `POST /v1/media/purge` runs the purge. Send the preview's `fingerprint` to refuse a run if the library changed: a stale fingerprint answers `409`, and so does a purge that is already running.
+- All four routes answer `403` with "Only owners and admins can do this." for any other role, and accept a session only, like the rest of the media routes.
+
+## Under the hood
+
+- Add the purge domain, a SQLite repository for the single-row purge settings, and the use cases that build the plan, preview it, run it and decide when a scheduled run is due.
+- Add an hourly scheduler, started with the server after a one-minute delay and stopped on shutdown. It reads the settings on every tick, so changes apply without a restart, and a failed run is retried at the next tick.
+- Add the `RequireOwnerOrAdmin` middleware.
+- Add the media purge, scheduler and Settings card specifications and QA procedures to `features/`, the new screens to `docs/design/`, and Go and Vitest suites for each part.
+
+## Upgrading
+
+- Replace the binary, or pull the new image. The purge settings table is created automatically at startup. No new environment variable is required.
+- Automatic purge is off after the upgrade. Nothing is merged until an owner or admin runs a purge or turns it on.
+- A purge cannot be undone: merged copies are removed. Check the summary before confirming.

docs/releases/v3.0.0-beta.md

@@ -0,0 +1,47 @@
+This release adds an activity log that records who did what on your site, and lets RenewCMS run on MySQL, MariaDB or PostgreSQL and keep uploaded images in an S3-compatible bucket.
+
+## New
+
+**Activity log**
+
+- The new Activity page lists every important action as a plain sentence, newest first, grouped by day: articles created, edited, published or deleted, images uploaded, renamed, merged or purged, accounts and invitations, and the system tasks (scheduled purge, update checks and downloads, restarts).
+- Filter by search text, person, category, outcome and date range, with Today, 7 days, 30 days and a custom range. Click a summary card to apply its filter. Open any row to see its details, including what changed.
+- Failed actions are recorded with a plain reason, and failed logins and similar events are flagged as security events.
+- Owners and admins see everyone's activity, a summary strip (total, active people, failed actions, security events) and can export the filtered list as a CSV file. Any other role would only see its own activity.
+- Article bodies are never recorded, only the change in size. Passwords, codes, file contents and storage paths are never recorded either.
+- The Home page has a new Recent activity card with the last five events.
+- Owners choose how long events are kept in the new Retention card in Settings: 30 days, 90 days (the default), 365 days or forever. Shortening the period asks for confirmation first. Older events are removed automatically once a day, and Settings shows the last cleanup and the next one.
+- The new screens are available in English and French.
+
+**More ways to run RenewCMS**
+
+- Use MySQL 8, MariaDB 11 or PostgreSQL 16 and 17 instead of the local SQLite file by setting `DB_DRIVER` to `mysql` or `postgres` and the `DB_*` connection variables. SQLite stays the default.
+- Keep uploaded images in an S3-compatible bucket (AWS S3, MinIO, Ceph, Cloudflare R2, Backblaze B2 and similar) by setting `STORAGE_DRIVER=s3`. Image URLs do not change and the bucket stays private.
+- The update backup taken before a download now works with every database: SQLite as before, and a logical dump for MySQL, MariaDB and PostgreSQL. The newest 3 backups are kept.
+- Docker Compose files for each setup are included: `docker-compose.mysql.yml`, `docker-compose.postgres.yml` and `docker-compose.s3.yml`.
+
+## API
+
+- `GET /v1/activity` returns the filtered, paged events as `{ items, total, page, size }`, newest first. It accepts `q`, `actor`, `category`, `outcome`, `security`, `range`, `from`, `to`, `page` and `size`, and any invalid value answers `400`. Owners and admins see every event. Any other role only sees its own, and asking for another actor answers `403`.
+- `GET /v1/activity/summary` returns the counts for the range, the previous period, the active people and a seven-bucket series. Owners and admins only.
+- `GET /v1/activity/export` returns the same filters as a CSV attachment (`when,actor,action,target,outcome,source,ip`). Owners and admins only. Cells that start with `=`, `+`, `-` or `@` get a leading quote.
+- The three routes accept a session only: an API key answers `403` with "This action needs a real session."
+- There is no `POST`, `PUT`, `PATCH` or `DELETE` under `/v1/activity`. Events can only be removed by the retention period.
+- `GET /v1/settings` now also returns `activity_retention_days`, `activity_last_cleanup_at`, `activity_last_cleanup_removed` and `activity_next_cleanup_at`.
+- `PATCH /v1/settings` accepts `activity_retention_days` with `0` (forever), `30`, `90` or `365`. Session and owner only, with `403` "Only the owner can do this." for anyone else. Any other value answers `400`.
+
+## Under the hood
+
+- Decouple persistence and image storage behind driver registries: `persistence/database` for the SQL drivers and `internal/infrastructure/storage` for the image adapters, with the domain `image.Storage` port. Repositories no longer touch files.
+- Add the audit domain, an append-only repository, a recorder that never fails or blocks the caller, and the use cases that record events from inside each action.
+- Add a scheduler for the activity cleanup, which runs once a day at or after 03:00 server time, alongside the media purge scheduler.
+- Add the activity, Home card and Retention card specifications and QA procedures to `features/`, the new screens to `docs/design/`, and Go and Vitest suites for each part.
+- Document the new variables in `docs/configuration.md`, and the new setups in `docs/deployment.md` and `docs/docker.md`.
+
+## Upgrading
+
+- Replace the binary, or pull the new image. The activity tables are created automatically at startup.
+- New environment variables are all optional and default to the previous behaviour: `DB_DRIVER` (`sqlite`), `STORAGE_DRIVER` (`local`), `DATA_DIR` (the directory of `DB_FILE`), and the `DB_*` and `S3_*` variables listed in `docs/configuration.md`. An existing install needs no change.
+- Activity starts recording after the upgrade, and nothing earlier is added. The first cleanup applies the default retention of 90 days, so owners who want a longer history should change it in Settings.
+- There is no automatic migration between databases or from the upload directory to a bucket. To move, follow the steps in `docs/configuration.md` and `docs/deployment.md`.
+- Backups taken before an update cover the database only. With S3, back the bucket up with your provider.

docs/releases/v3.1.0-beta.md

@@ -0,0 +1,43 @@
+This release adds image variants: named sizes and formats of your images, generated on first use and cached, plus a size limit for the activity log.
+
+## New
+
+**Image variants**
+
+- Owners and admins define named variants (width, height, fit, format and quality) in the new variants screens under Settings. Variants can be created, edited, enabled, disabled, purged and deleted.
+- Add `?v=<name>` to any uploaded image URL to get the variant. It is generated on the first request, cached, and served from the cache afterwards. The original is never changed, and URLs without `?v=` behave as before.
+- Each image in the media library shows its variants, and lets you generate or purge them one by one or all at once.
+- The new Cache screen shows how many files are generated, the disk space used, how many requests were rejected and what has been unused for 30 days. Purge everything, unused files, one variant or one image.
+- Output can keep the original format or be converted to JPEG, PNG or lossy WebP. Images are never enlarged. SVG and animated GIF are served as they are.
+- Oversized sources are refused with a clear error instead of exhausting memory, and identical concurrent requests share one generation.
+- The new screens are available in English and French.
+
+**Activity log**
+
+- Retention can now also be capped by size, in GB, in addition to its age. Whichever limit is reached first removes the oldest events. No cap is set by default.
+
+## Improvements and fixes
+
+- Fix the missing routes of the integration pages.
+- Harmonize the design of the latest screens with the design spec.
+
+## API
+
+- `GET /v1/image-variants` and `POST /v1/image-variants` list and create variants. `PUT /v1/image-variants/{name}` replaces a definition, `PATCH` enables or disables it and `DELETE` removes it with its files. `POST /v1/image-variants/{name}/purge` removes the generated files only.
+- `GET /v1/image-variants/cache` returns the cache statistics, and `POST /v1/image-variants/cache/purge` purges by scope (`all`, `unused`, `variant` or `image`).
+- `GET /v1/media/{id}/variants` lists the variants of an image. `POST /v1/media/{id}/variants` generates all missing ones and `POST` or `DELETE /v1/media/{id}/variants/{name}` generates or purges one.
+- All of these routes are for owners and admins and accept a session only: an API key answers `403`.
+- `GET /static/uploadedImages/<storedName>?v=<name>` serves the variant. An unknown or disabled name, or a `width`, `height`, `format` or `quality` parameter, answers `400`. A source over the size or pixel limit answers `413`. The response carries an `ETag` and answers `304` to `If-None-Match`.
+- `PATCH /v1/settings` also accepts a maximum activity log size in GB, returned as `activity_retention_max_gb`.
+
+## Under the hood
+
+- Add the image variant domain, repositories, renderer, in-memory usage tracker flushed every 30 seconds, and use cases, behind the existing storage port so local and S3 storage both work.
+- Document the feature in `docs/image-variants.md`, `docs/api.md` and `docs/architecture.md`, and add the specifications, design screens and Go and Vitest suites.
+
+## Upgrading
+
+- Replace the binary, or pull the new image. The variant tables are created automatically at startup. No variant exists until you define one.
+- Three optional environment variables are new: `IMAGE_VARIANT_MAX_SOURCE_BYTES` (`10485760`), `IMAGE_VARIANT_MAX_SOURCE_PIXELS` (`50000000`) and `IMAGE_VARIANT_MAX_CONCURRENT_RENDERS` (`4`). An existing install needs no change.
+- Generated variants are stored next to your images, in the upload directory or the S3 bucket, and count toward the storage you use.
+- Generating a variant when an image is uploaded is not part of this release.

features/activity-log-backend.feature

@@ -0,0 +1,568 @@
+Feature: The back-office keeps an append-only activity log that owners can read and retention can prune
+
+  As the owner of a RenewCMS site
+  I want every important action recorded with who, what, when and from where
+  So that I can review activity, spot failed logins and keep the log from growing forever
+
+  Background:
+    Given the spec of record is docs/design/screens/activity.md ("Roles", "API contract", "What is recorded") and docs/design/screens/settings.md ("Activity retention")
+    And this slice is backend only: no SPA, no new env var, no change to the design
+    And error responses are plain text from http.Error and success responses are JSON with snake_case fields
+    And the layering rule holds: internal/domain/audit imports only the stdlib and other domain packages, use cases see only domain interfaces, handlers see only use cases, persistence owns GORM, and no comment is added anywhere
+    And validation of query and body goes through validate tags and validator.Validate.Struct where a struct exists
+    And the error text for a malformed query or body is "The request cannot be processed due to a mismatch in the format of the body."
+
+  Rule: The domain event is a complete snapshot and the repository is append-only
+
+    Scenario: An event carries everything the log needs
+      Given an event is built for the action "article.publish" in category "articles"
+      Then it holds an actor snapshot (type, id, name), the action code and its params, the category, a target snapshot (type, id, name), an outcome, a failure_reason, a security flag, a source, an ip, a user_agent, changes and a created_at
+
+    Scenario Outline: The vocabulary is closed
+      Then the allowed <field> values are exactly <values>
+
+      Examples:
+        | field       | values                                          |
+        | actor.type  | user, api_key, system, anonymous                |
+        | category    | articles, media, users, api_keys, auth, system  |
+        | outcome     | success, failed                                 |
+        | source      | web, api_key, system                            |
+        | change.kind | text, body                                      |
+
+    Scenario: The repository exposes no way to edit or delete one event
+      Then the audit Repository interface has exactly the methods Append, List, Summary, DeleteOlderThan, DeleteOldest and SizeBytes
+      And the persistence implementation exposes no other exported method than those and its constructor
+      And the HTTP surface has no POST, PUT, PATCH or DELETE under /v1/activity
+
+    Scenario: The sentinel errors are matchable
+      Then the audit package declares Err sentinels for an invalid filter and an invalid retention period
+      And each is asserted with errors.Is
+
+  Rule: The recorder never fails or blocks the caller
+
+    Scenario: A failing repository does not change the caller's result
+      Given the audit repository fails on Append with the error "disk full"
+      When a user logs in with valid credentials through POST /v1/auth/login
+      Then the response is 200 with a jwt cookie and the usual JSON message
+      And the process log contains a line naming the failed audit write and "disk full"
+
+    Scenario: A panicking repository does not crash the request
+      Given the audit repository panics on Append
+      When a user logs out through POST /v1/auth/logout
+      Then the response is 200 and the process continues serving
+
+    Scenario: The recorder fills the event from the audit context
+      Given a context holding actor user 3 "marta", source "web", ip "203.0.113.12" and user agent "Mozilla/5.0 test"
+      When the recorder records an event that has no actor, source, ip or user agent
+      Then the stored event has those values
+      And created_at is the injected clock's time in UTC
+
+    Scenario: Secrets never reach the log or the stored event
+      Given actions that handle a password, a raw API key, a reset code and a jwt
+      When they are recorded
+      Then no stored field, no params and no process log line contains any of those values or their hashes
+
+  Rule: The audit context is set by middleware from the credentials and the trusted-proxy IP
+
+    Scenario: A session sets a user actor with source web
+      Given a request with a valid jwt cookie for user 3 "marta"
+      When it passes the audit context middleware
+      Then the context holds actor type "user", id 3, name "marta" and source "web"
+
+    Scenario: An API key sets an api_key actor with source api_key
+      Given a request with "Authorization: Bearer <valid key>" for the key 7 named "Deploy bot"
+      When it passes the audit context middleware
+      Then the context holds actor type "api_key", id 7, name "Deploy bot" and source "api_key"
+
+    Scenario: No credentials sets an anonymous actor
+      Given a request without a cookie or key
+      Then the context holds actor type "anonymous" and source "web"
+
+    Scenario Outline: The ip comes from the trusted-proxy real IP only
+      Given the trusted proxies are "10.0.0.5"
+      And the request peer is "<peer>" and X-Real-IP is "<header>"
+      Then the context ip is "<ip>"
+
+      Examples:
+        | peer             | header       | ip           |
+        | 10.0.0.5:443     | 203.0.113.12 | 203.0.113.12 |
+        | 198.51.100.9:443 | 203.0.113.12 | 198.51.100.9 |
+        | 198.51.100.9:443 |              | 198.51.100.9 |
+
+    Scenario: The user agent is stored as sent and bounded
+      Given the User-Agent header is 400 characters long
+      Then the context user agent is its first 255 characters
+
+  Rule: Persistence stores events portably and indexed
+
+    Background:
+      Given the persistence tests run against a real in-memory SQLite database migrated with the model list of migrate.go
+      And the SQL stays portable across SQLite, MySQL/MariaDB and PostgreSQL
+
+    Scenario: The model is migrated with its indexes
+      Then the audit events table exists
+      And it has an index on created_at, an index on (actor_type, actor_id, created_at) and an index on (category, created_at)
+
+    Scenario: An appended event round-trips
+      When an event with params {"merged": 3}, changes and a null failure_reason is appended
+      Then listing returns it with every field equal, params and changes included
+
+    Scenario: List sorts by created_at descending then id descending
+      Given three events with the same created_at and one older
+      Then List returns the three by id descending, then the older one
+
+    Scenario Outline: Filters narrow the list and the total
+      Given events across actors, categories, outcomes and days
+      When List runs with <filter>
+      Then items and total contain exactly <expected>
+
+      Examples:
+        | filter                          | expected                                                              |
+        | actor user:3                    | events of user 3 only                                                 |
+        | actor key:7                     | events of api key 7 only                                              |
+        | actor system                    | events with actor type system only                                    |
+        | category auth                   | auth events only                                                      |
+        | outcome failed                  | failed events only                                                    |
+        | outcome success                 | succeeded events only                                                 |
+        | security true                   | events whose security flag is true                                    |
+        | q "SPRING"                      | events whose actor or target name contains "spring", case-insensitive |
+        | q "50%_"                        | only names containing the literal text 50%_                           |
+        | from 2026-10-01 to 2026-10-03   | events from 2026-10-01T00:00:00Z to the end of 2026-10-03             |
+
+    Scenario: Paging slices the sorted list and total is the unpaged count
+      Given 60 events
+      When List runs with page 2 and size 25
+      Then 25 items are returned, the 26th to 50th of the sorted list, and total is 60
+
+    Scenario: A page past the end is empty
+      When List runs with page 9 and size 25 over 60 events
+      Then items is empty and total is 60
+
+    Scenario: The summary counts the range and the previous period
+      Given events in the last 7 days and in the 7 days before
+      When Summary runs for range 7d
+      Then total, previous_total, failed and security are the counts of those periods
+      And active_people.users counts distinct user actors and active_people.api_keys counts distinct key actors, with anonymous and system excluded
+      And series holds seven daily counts for total, active, failed and security, oldest first
+
+    Scenario: DeleteOlderThan removes only events before the cutoff
+      Given events at 100, 40, 31, 29 and 1 days ago
+      When DeleteOlderThan runs with the cutoff 30 days ago
+      Then it returns 3 and only the 29-day and 1-day events remain
+
+  Rule: Reading the log is session only and scoped by role
+
+    Background:
+      Given the handler is mounted at /v1/activity behind jwtauth.Verifier, jwtauth.Authenticator, the current-token check and the verified-user check
+      And the routes sit behind RequireSession, so no API key reaches them
+
+    Scenario Outline: The credentials gate answers before any data
+      When GET <path> is sent <credentials>
+      Then the response is <status> with body "<body>"
+      And the audit repository was not read
+
+      Examples:
+        | path                    | credentials                       | status | body                                                     |
+        | /v1/activity            | without a jwt cookie              | 401    | You must be logged in to access this resource.           |
+        | /v1/activity/summary    | without a jwt cookie              | 401    | You must be logged in to access this resource.           |
+        | /v1/activity/export     | without a jwt cookie              | 401    | You must be logged in to access this resource.           |
+        | /v1/activity            | with a valid API key              | 403    | This action needs a real session.                        |
+        | /v1/activity/summary    | with a valid API key              | 403    | This action needs a real session.                        |
+        | /v1/activity/export     | with a valid API key              | 403    | This action needs a real session.                        |
+        | /v1/activity            | with an unverified user's cookie  | 403    | You must verify your account to access this resource.    |
+
+    Scenario Outline: Owner and admin see every event
+      Given events by users 1, 2 and 3, an api key and the system
+      When GET /v1/activity is sent with the cookie of the <role>
+      Then the response is 200 and total counts the events of every actor
+
+      Examples:
+        | role  |
+        | owner |
+        | admin |
+
+    Scenario: Another role is scoped to its own events
+      Given a verified user 3 whose role is neither owner nor admin
+      And events by users 1, 2 and 3
+      When GET /v1/activity is sent with user 3's cookie
+      Then every item has actor type "user" and id 3
+      And total counts only user 3's events
+
+    Scenario Outline: A scoped caller cannot ask for another actor
+      Given a verified user 3 whose role is neither owner nor admin
+      When GET /v1/activity?actor=<actor> is sent with user 3's cookie
+      Then the response is <status>
+
+      Examples:
+        | actor    | status |
+        | user:3   | 200    |
+        | user:2   | 403    |
+        | key:7    | 403    |
+        | system   | 403    |
+
+    Scenario Outline: A scoped caller cannot read the summary or the export
+      Given a verified user 3 whose role is neither owner nor admin
+      When GET <path> is sent with user 3's cookie
+      Then the response is 403 with body "Only owners and admins can do this."
+
+      Examples:
+        | path                 |
+        | /v1/activity/summary |
+        | /v1/activity/export  |
+
+  Rule: GET /v1/activity lists filtered, paged events
+
+    Scenario: The default request
+      Given 30 events over the last 3 days
+      When the owner sends GET /v1/activity
+      Then the response is 200 with {"items": [...], "total": 30, "page": 1, "size": 25}
+      And items has 25 entries, newest first
+
+    Scenario: An item has the documented shape
+      Given user 3 "Marta Alves" published the article 8 "Spring release" at 2026-10-06T10:42:18Z from 203.0.113.12 with "Chrome 129 on Windows"
+      When the owner sends GET /v1/activity
+      Then the first item is
+        """
+        {"id": 4821, "created_at": "2026-10-06T10:42:18Z", "action": "article.publish", "category": "articles", "actor": {"type": "user", "id": 3, "name": "Marta Alves"}, "target": {"type": "article", "id": "8", "name": "Spring release", "exists": true}, "outcome": "success", "failure_reason": null, "security": false, "source": "web", "ip": "203.0.113.12", "user_agent": "Chrome 129 on Windows", "params": {}, "changes": [{"field": "online", "kind": "text", "before": "false", "after": "true"}]}
+        """
+
+    Scenario: A system event has no ip or user agent
+      Given a system event "system.activity_cleanup"
+      When the owner sends GET /v1/activity
+      Then its item has actor {"type": "system", "id": null, "name": "System"}, source "system", ip null and user_agent null
+
+    Scenario: A renamed or deleted user still reads correctly
+      Given an event recorded when user 3 was named "Marta Alves"
+      And user 3 has since been renamed "M. Alves" and then deleted
+      When the owner sends GET /v1/activity
+      Then the item's actor.name is still "Marta Alves"
+
+    Scenario Outline: target.exists is resolved when the list is read
+      Given an event whose target is <type> "<id>" named "<name>"
+      And <state>
+      When the owner sends GET /v1/activity
+      Then the item's target.name is "<name>" and target.exists is <exists>
+
+      Examples:
+        | type    | id | name           | state                       | exists |
+        | article | 8  | Spring release | the article still exists    | true   |
+        | article | 8  | Spring release | the article was deleted     | false  |
+        | user    | 3  | Marta Alves    | the user was deleted        | false  |
+
+    Scenario: A body change carries a delta and never text
+      Given an event with a body change of +312 characters
+      Then its change is {"field": "body", "kind": "body", "delta": 312} with no before and no after
+
+    Scenario Outline: The filters are applied through the query
+      When the owner sends GET /v1/activity?<query>
+      Then the response is 200 and items match <expected>
+
+      Examples:
+        | query                                      | expected                                  |
+        | q=spring                                   | the actor or target name contains spring  |
+        | actor=user:3                               | events of user 3                          |
+        | actor=key:7                                | events of api key 7                       |
+        | actor=system                               | system events                             |
+        | category=auth                              | auth events                               |
+        | outcome=failed                             | failed events                             |
+        | outcome=success                            | succeeded events                          |
+        | outcome=all                                | both outcomes                             |
+        | security=true                              | events with the security flag             |
+        | range=today                                | events since 00:00 UTC today              |
+        | range=7d                                   | events of the last 7 days                 |
+        | range=30d                                  | events of the last 30 days                |
+        | range=custom&from=2026-09-01&to=2026-09-30 | events from 1 to 30 September 2026 UTC    |
+        | page=2&size=50                             | the second page of 50                     |
+        | size=5                                     | the first page of 5                       |
+
+    Scenario: Omitting range means 7 days
+      Given events 2 days old and 10 days old
+      When the owner sends GET /v1/activity
+      Then only the 2-day-old event is listed
+
+    Scenario Outline: Invalid values answer 400
+      When the owner sends GET /v1/activity?<query>
+      Then the response is 400 with body "The request cannot be processed due to a mismatch in the format of the body."
+      And the audit repository was not read
+
+      Examples:
+        | query                                      |
+        | actor=user:abc                             |
+        | actor=user:-1                              |
+        | actor=group:3                              |
+        | category=billing                           |
+        | outcome=maybe                              |
+        | security=false                             |
+        | range=year                                 |
+        | range=custom                               |
+        | range=custom&from=2026-09-30&to=2026-09-01 |
+        | range=custom&from=yesterday&to=today       |
+        | page=0                                     |
+        | page=abc                                   |
+        | size=10                                    |
+        | size=200                                   |
+
+  Rule: GET /v1/activity/summary answers the strip
+
+    Scenario: The summary of the last seven days
+      Given 12 events in the last 7 days, 3 failed, 2 with the security flag, by 2 users and 1 api key
+      And 10 events in the 7 days before
+      When the owner sends GET /v1/activity/summary?range=7d
+      Then the response is 200 and the body is
+        """
+        {"total": 12, "previous_total": 10, "active_people": {"users": 2, "api_keys": 1}, "failed": 3, "security": 2, "series": {"total": [...7 numbers], "active": [...7], "failed": [...7], "security": [...7]}}
+        """
+      And each series array has 7 entries, oldest first, and the total series sums to 12
+
+    Scenario: An empty log answers zeros
+      Given no events
+      When the owner sends GET /v1/activity/summary
+      Then every number is 0 and every series array is seven zeros
+
+    Scenario: The summary uses the same filters as the range
+      When the owner sends GET /v1/activity/summary?range=custom&from=2026-09-01&to=2026-09-07
+      Then the counts cover exactly that range and previous_total covers the 7 days immediately before 2026-09-01
+
+    Scenario: An invalid range answers 400
+      When the owner sends GET /v1/activity/summary?range=year
+      Then the response is 400 with the body-mismatch message
+
+  Rule: GET /v1/activity/export streams a safe CSV
+
+    Scenario: The response is a CSV attachment
+      Given 3 events
+      When the owner sends GET /v1/activity/export
+      Then the response is 200 with Content-Type "text/csv; charset=utf-8" and Content-Disposition starting with "attachment"
+      And the first row is "when,actor,action,target,outcome,source,ip"
+      And there are 3 data rows, newest first
+
+    Scenario: A row holds the documented columns only
+      Given user 3 "Marta Alves" published "Spring release" at 2026-10-06T10:42:18Z from 203.0.113.12 with changes and a user agent
+      Then the row is "2026-10-06T10:42:18Z,Marta Alves,article.publish,Spring release,success,web,203.0.113.12"
+      And the file contains no changes and no user agent
+
+    Scenario Outline: Cells that a spreadsheet would evaluate are neutralised
+      Given an event whose <column> is "<value>"
+      Then the cell is "<cell>"
+
+      Examples:
+        | column | value            | cell              |
+        | actor  | =cmd             | '=cmd             |
+        | target | +1+1             | '+1+1             |
+        | target | -2               | '-2               |
+        | actor  | @SUM(A1)         | '@SUM(A1)         |
+        | target | Spring release   | Spring release    |
+        | target | a=b              | a=b               |
+
+    Scenario: Commas, quotes and newlines are quoted
+      Given a target whose name contains a comma, double quotes and a newline
+      Then the cell is quoted with doubled inner quotes and the file still has one row for the event
+
+    Scenario: The export uses the list filters without paging
+      Given 60 events of which 8 failed
+      When the owner sends GET /v1/activity/export?outcome=failed&page=2&size=25
+      Then the file has the 8 failed rows and page and size are ignored
+
+    Scenario: A system event has an empty ip cell
+      Given a system event
+      Then its ip cell is empty
+
+    Scenario: An invalid filter answers 400 before any byte is streamed
+      When the owner sends GET /v1/activity/export?outcome=maybe
+      Then the response is 400 with the body-mismatch message and no CSV header
+
+    Scenario: A large export is read in batches
+      Given 1200 events
+      When the owner exports them
+      Then the file has 1200 rows and the repository was read through List in pages, not all at once
+
+  Rule: The retention period is a setting only the owner can change
+
+    Scenario: The default is 90 days
+      Given no retention row exists
+      When a verified user sends GET /v1/settings
+      Then the body has "activity_retention_days": 90, "activity_last_cleanup_at": null and "activity_last_cleanup_removed": 0
+      And the existing fields of the response are unchanged
+
+    Scenario: The last cleanup is reported
+      Given a cleanup ran at 2026-10-06T03:00:00Z and removed 142 events
+      When a verified user sends GET /v1/settings
+      Then "activity_last_cleanup_at" is "2026-10-06T03:00:00Z" and "activity_last_cleanup_removed" is 142
+
+    Scenario Outline: The owner sets a valid period
+      When the owner sends PATCH /v1/settings with body {"activity_retention_days": <days>}
+      Then the response is 200 and the body has "activity_retention_days": <days>
+      And a following GET /v1/settings returns <days>
+
+      Examples:
+        | days |
+        | 30   |
+        | 90   |
+        | 365  |
+        | 0    |
+
+    Scenario Outline: Any other value answers 400 and changes nothing
+      Given the stored retention is 90
+      When the owner sends PATCH /v1/settings with body <body>
+      Then the response is 400 with body "The request cannot be processed due to a mismatch in the format of the body."
+      And the stored retention is still 90
+
+      Examples:
+        | body                                |
+        | {"activity_retention_days": 7}      |
+        | {"activity_retention_days": -1}     |
+        | {"activity_retention_days": 366}    |
+        | {"activity_retention_days": 30.5}   |
+        | {"activity_retention_days": "30"}   |
+        | {"activity_retention_days": null}   |
+        | {}                                  |
+        | not json                            |
+
+    Scenario: An admin cannot change it
+      When an admin sends PATCH /v1/settings with body {"activity_retention_days": 30}
+      Then the response is 403 with body "Only the owner can do this."
+      And the stored retention is unchanged
+
+    Scenario Outline: The gate answers before the body is read
+      When PATCH /v1/settings is sent <credentials> with body {"activity_retention_days": 30}
+      Then the response is <status> with body "<body>"
+
+      Examples:
+        | credentials                  | status | body                                                  |
+        | without a jwt cookie         | 401    | You must be logged in to access this resource.        |
+        | with an owner's API key      | 403    | This action needs a real session.                     |
+        | with an unverified owner     | 403    | You must verify your account to access this resource. |
+
+    Scenario: A change is recorded as a system event by the owner
+      Given the stored retention is 90
+      When the owner sends PATCH /v1/settings with body {"activity_retention_days": 30}
+      Then one event exists with action "system.activity_retention_changed", category "system", actor the owner, source "web", outcome "success", security false and params {"from": 90, "to": 30}
+
+    Scenario: Setting the same value records nothing
+      Given the stored retention is 90
+      When the owner sends PATCH /v1/settings with body {"activity_retention_days": 90}
+      Then the response is 200 and no event is recorded
+
+  Rule: A daily cleanup removes events past the retention period
+
+    Background:
+      Given the cleanup is a use case with a Tick(now) like PurgeScheduler, driven by the scheduler runner with hand-fed channels and an injected clock
+      And the server time zone is the injected clock's location
+
+    Scenario Outline: The cleanup is due once a day at or after 03:00
+      Given the retention is 90 and the last cleanup was at <last>
+      When Tick runs at <now>
+      Then ran is <ran>
+
+      Examples:
+        | last                | now                 | ran   |
+        | never               | 2026-10-06T02:59:00 | false |
+        | never               | 2026-10-06T03:00:00 | true  |
+        | never               | 2026-10-06T14:00:00 | true  |
+        | 2026-10-05T03:00:00 | 2026-10-06T02:59:00 | false |
+        | 2026-10-05T03:00:00 | 2026-10-06T03:00:00 | true  |
+        | 2026-10-06T03:00:00 | 2026-10-06T04:00:00 | false |
+        | 2026-10-06T03:00:00 | 2026-10-07T03:00:00 | true  |
+
+    Scenario: Forever with no size limit never runs
+      Given the retention is 0
+      When Tick runs at 2026-10-06T03:00:00
+      Then ran is false and DeleteOlderThan is not called
+
+    Scenario: The cutoff is now minus the retention days
+      Given the retention is 30 and events at 40, 31, 29 and 1 days ago
+      When the cleanup runs at 2026-10-06T03:00:00
+      Then the events 31 and 40 days old are removed and the others remain
+      And the last cleanup time is the clock's time and the removed count is 2
+
+    Scenario: The last 24 hours are never removed
+      Given the cleanup is asked for a cutoff newer than 24 hours ago
+      Then the effective cutoff is 24 hours before now
+
+    Scenario: A cleanup that removes nothing still records the run
+      Given the retention is 90 and no event is older than 90 days
+      When the cleanup runs
+      Then the last cleanup time is the clock's time, the removed count is 0 and no system.activity_cleanup event is recorded
+
+    Scenario: A cleanup that removes events records a system event after deleting
+      Given 142 events older than the retention
+      When the cleanup runs
+      Then one event exists with action "system.activity_cleanup", category "system", actor type "system", source "system", ip null, user_agent null, outcome "success" and params {"removed": 142}
+      And that event is not among the removed ones
+
+    Scenario: A failing delete is retried at the next tick
+      Given DeleteOlderThan fails
+      When Tick runs
+      Then the error is returned and logged, the last cleanup fields are unchanged and the next tick runs the cleanup again
+
+    Scenario: A shortened period applies at the next cleanup
+      Given the retention was 90 and the owner sets 30
+      Then no event is removed by the change itself
+      And the next cleanup removes events older than 30 days
+
+    Scenario: The scheduler stops with the process
+      When the context is cancelled
+      Then the runner returns and no goroutine outlives it
+
+  Rule: The first producers record the right events
+
+    Scenario Outline: Authentication events
+      When <trigger>
+      Then one event exists with action "<action>", category "auth", <actor>, source "web", outcome "<outcome>", security <security>, failure_reason <reason> and the request ip and user agent
+
+      Examples:
+        | trigger                                                          | action                        | actor                                           | outcome | security | reason                        |
+        | POST /v1/auth/login with the right username and password         | auth.login                    | actor user with the account's name              | success | false    | null                          |
+        | POST /v1/auth/login with the right username and a wrong password | auth.login_failed             | actor anonymous named by the attempted username | failed  | true     | "Wrong username or password." |
+        | POST /v1/auth/login with an unknown username                     | auth.login_failed             | actor anonymous named by the attempted username | failed  | true     | "Wrong username or password." |
+        | POST /v1/auth/logout with a valid jwt cookie                     | auth.logout                   | actor user                                      | success | false    | null                          |
+        | POST /v1/auth/password-reset for an existing account             | auth.password_reset_requested | actor user                                      | success | true     | null                          |
+        | POST /v1/auth/password-reset/confirm with a valid code           | auth.password_reset_completed | actor user                                      | success | true     | null                          |
+
+    Scenario: A failed login reveals no more than the response does
+      Given a wrong password for an existing user and an unknown username
+      Then both events have the same failure_reason, actor type anonymous and no target
+      And neither event holds the password
+
+    Scenario Outline: Nothing is recorded when nothing happened
+      When <trigger>
+      Then no event is recorded and the response is unchanged
+
+      Examples:
+        | trigger                                                  |
+        | POST /v1/auth/logout without a jwt cookie                |
+        | POST /v1/auth/password-reset for an unknown email        |
+        | POST /v1/auth/password-reset/confirm with an invalid code |
+        | POST /v1/auth/login with a body that fails validation    |
+        | POST /v1/auth/login answered 429 by the rate limiter     |
+
+    Scenario: A reset event never holds the code
+      When a password reset is requested and completed
+      Then neither event nor the process log contains the raw code, its hash or the new password
+
+    Scenario: Creating an API key is recorded
+      When the owner sends POST /v1/api-key with a name "Deploy bot"
+      Then one event exists with action "api_key.create", category "api_keys", actor the owner, source "web", target {"type": "api_key", "id": "<new id>", "name": "Deploy bot"}, outcome "success" and security false
+      And no stored field and no response of the activity API contains the raw key or its hash
+
+    Scenario: Revoking an API key is recorded
+      Given the API key 7 named "Deploy bot"
+      When the owner sends DELETE /v1/api-key/7
+      Then one event exists with action "api_key.revoke", category "api_keys", actor the owner, target {"type": "api_key", "id": "7", "name": "Deploy bot"} and outcome "success"
+
+    Scenario: A revoke of an unknown key records nothing
+      When the owner sends DELETE /v1/api-key/99
+      Then the response is 404 and no event is recorded
+
+    Scenario: The recorded events are readable through the API
+      Given a failed login, an API key creation and a retention change were recorded
+      When the owner sends GET /v1/activity
+      Then the three events are listed newest first with their documented items
+      And GET /v1/activity?security=true lists only the failed login
+
+    Scenario: The size limit extension amends the retention rules
+      Given features/activity_home_card_and_retention.feature, rule "Retention size limit"
+      Then the settings default also has activity_retention_max_gb 0 and activity_log_size_bytes 0
+      And PATCH /v1/settings also accepts activity_retention_max_gb validated against audit.SizeOptions()
+      And the last 24 hours are never removed by DeleteOldest either
+      And a retention change is recorded with the max_gb_from and max_gb_to params when the size changes

features/activity-log-backend.qa.md

@@ -0,0 +1,72 @@
+# QA procedure: activity-log-backend
+
+Go only, no SPA. Package `test` (black-box), new files `test/activity_log_domain_test.go`, `test/activity_log_persistence_test.go`, `test/activity_log_http_test.go` and `test/activity_cleanup_test.go`. Fake and helper type names must be unique across the package. No live server, no real SMTP, no real SQLite file, no real sleeping, no `time.Ticker`. No env var is added. Never put a secret value in a test name or log assertion helper beyond the fixed test strings.
+
+## Setup shared by every case
+1. `validator.InitValidator()` once. `jwtauth.New("HS256", []byte("test-secret"), nil)` standing in for `JWT_SECRET`.
+2. Fakes: `fakeAuditClock` (mutable, `Now()` and `Set(t)`, UTC), `mockAuditRepo` (in-memory slice, `Append`, `List`, `Summary`, `DeleteOlderThan`, failure and panic switches, call counters per method), existing `mockUserRepo` extended with users: owner 1, admin 2, a verified user 3 with role `"editor"` (domain has only owner and admin, so the role is a plain string in the fake), an unverified user 4. Fake API key repo with key 7 "Deploy bot" and a raw key built with `apikey.RawKeyPrefix`.
+3. Router: a fresh `chi.NewRouter()` mirroring `api/router.go`. Mount `/activity` (RequireSession, `jwtauth.Verifier`, `jwtauth.Authenticator`, `RequireCurrentToken`, `RequireVerifiedUser`, then the audit context middleware), `/settings` with the new PATCH, `/api-key` and `/auth` over the real use cases and the fakes. `httptest.NewRecorder` per request. Cookies are real `jwt` cookies signed with the test token carrying `user_id` and `token_version`.
+4. Capture the standard log with `log.SetOutput(&buf)` and restore with `t.Cleanup`. No parallel tests except where `-race` is stated.
+5. Seed helper `seedEvents(repo, n, spec)` building events with explicit `created_at` from the clock.
+
+## A. Domain (no HTTP)
+6. Vocabulary table: for each of actor type, category, outcome, source and change kind, the exported constants equal the allowed set from the feature; an invalid value is rejected by the domain constructor or validator with the matching `Err` sentinel (`errors.Is`).
+7. Append-only guard: `reflect.TypeOf((*audit.Repository)(nil)).Elem()` has exactly `Append`, `List`, `Summary`, `DeleteOlderThan`. The persistence implementation's exported method set (via `reflect`) equals the same four. Router walk (`chi.Walk`) finds only GET under `/v1/activity`.
+8. Recorder: with `mockAuditRepo` failing (`errors.New("disk full")`), `Record` returns without error, and `buf` names the failed write and `disk full`. A panicking repo is recovered. A context holding actor, source, ip and user agent fills an event that lacks them; an event that already has an actor keeps it. `created_at` equals `fakeAuditClock.Now()` in UTC.
+
+## B. Persistence (real in-memory SQLite, same model list as `api/dependecyInjection.go` and `migrate.go`)
+9. Migrate, then query `sqlite_master` and assert the table and three indexes: `created_at`; `(actor_type, actor_id, created_at)`; `(category, created_at)`. Assert the audit model is in the `migrate.go` list (migrate the full list, not just the audit model).
+10. Round-trip: append an event with params, changes (text and body kinds) and a null failure_reason; `List` returns equal fields. A system event round-trips with null ip and user agent.
+11. Order: three events with identical `created_at` come back by id descending, older last.
+12. Filter table from the feature (actor user, key, system, category, outcome, security, `q` case-insensitive, `q` containing `%` and `_` matched literally, date range inclusive of the whole `to` day UTC). Assert items and total for each.
+13. Paging: 60 events, page 2 size 25 gives items 26-50 and total 60; page 9 gives empty items and total 60.
+14. Summary: events in the last 7 days and the 7 days before; assert total, previous_total, failed, security, distinct user and key counts (anonymous and system excluded) and the four seven-element series, oldest first.
+15. `DeleteOlderThan`: events at 100, 40, 31, 29, 1 days; cutoff 30 days; returns 3, remaining ids as expected.
+16. Portability: assert no raw dialect-specific SQL (`ILIKE`, `strftime`, `date_trunc`, backticks) appears in the repository source. Cross-database run is manual (see below).
+
+## C. Audit context middleware (probe handler echoing the context as JSON)
+17. Table: valid cookie for user 3 gives `{type user, id 3, name, source web}`; valid `Authorization: Bearer <key>` gives `{api_key, 7, "Deploy bot", source api_key}`; none gives anonymous and web.
+18. IP table with `TrustedProxyRealIP([]string{"10.0.0.5"})` in front: trusted peer plus `X-Real-IP` gives the header; untrusted peer ignores it; no header gives the peer. User agent of 400 characters is cut to 255.
+
+## D. Read endpoints (HTTP)
+19. Gate table: no cookie 401 `You must be logged in to access this resource.`; API key 403 `This action needs a real session.`; unverified cookie 403 `You must verify your account to access this resource.`, each for list, summary and export, with `mockAuditRepo` List/Summary counters at 0.
+20. Roles: owner and admin see all actors; user 3 sees only its own with `total` of its own count; `actor=user:3` is 200, `actor=user:2`, `actor=key:7`, `actor=system` are 403 (body `Only owners and admins can do this.`); summary and export for user 3 are 403 with the same body.
+21. Shape: decode the first item into a map and compare with the JSON in the feature, including `"failure_reason": null`, `"params": {}`, integer `actor.id`, string `target.id`, `exists`. System event has `actor.id` null, `ip` null, `user_agent` null. Renamed and deleted user keeps the snapshot name. `exists` table with fake article repo (present, deleted) and user repo (deleted). A `body` change has `delta` and no `before` or `after`.
+22. Query table: every row of the filter outline, asserted against the seeded set; default range 7d (2-day event in, 10-day event out); default `page` 1, `size` 25.
+23. 400 table: every invalid query row gives exactly `The request cannot be processed due to a mismatch in the format of the body.` with the repo read counter at 0.
+24. Summary: the 7d example (12 / 10 / 2 users + 1 key / 3 / 2 and seven-length series that sum to the total); empty log all zeros; custom range previous period is the 7 days immediately before; invalid range 400.
+25. Export: status 200, `Content-Type: text/csv; charset=utf-8`, `Content-Disposition` begins `attachment`. Parse with `encoding/csv`: header `when,actor,action,target,outcome,source,ip`, row values as in the feature, no changes and no user agent column, system ip cell empty. Formula table (`=cmd`, `+1+1`, `-2`, `@SUM(A1)` get a leading `'`; `Spring release` and `a=b` untouched). A name with comma, quotes and a newline is one parseable record. `outcome=failed&page=2&size=25` returns only failed rows. 1200 events yield 1200 rows and `mockAuditRepo` saw more than one `List` call with a bounded size. Invalid filter gives 400 with no `Content-Type: text/csv`.
+
+## E. Retention settings (HTTP)
+26. `GET /v1/settings` with no stored row: `activity_retention_days` 90, `activity_last_cleanup_at` null, `activity_last_cleanup_removed` 0, existing fields (`version`) unchanged. With a stored cleanup: values echoed (RFC3339 UTC).
+27. `PATCH` accepts 30, 90, 365, 0 (200, body echoes, a following GET agrees). 400 table: 7, -1, 366, 30.5, `"30"`, null, `{}`, non-JSON, each with the body-mismatch message and the stored value unchanged.
+28. Gate: admin 403 `Only the owner can do this.`; no cookie 401; owner API key 403 `This action needs a real session.`; unverified owner 403 verification text.
+29. Event: PATCH 90 to 30 records one `system.activity_retention_changed` event with actor owner, source web and params `{"from":90,"to":30}`; PATCH to the same value records none.
+
+## F. Cleanup scheduler (no HTTP, hand-fed channels, `fakeAuditClock`)
+30. Tick table from the feature (never/last cleanup versus now, boundary at exactly 03:00, same-day second tick not due, next-day tick due). Assert `ran` and the `DeleteOlderThan` call count. Retention 0 never calls it.
+31. Cutoff: retention 30, events at 40, 31, 29, 1 days; run at 03:00; 31 and 40 removed; `last_cleanup_at` equals the clock; removed count 2. A request for a cutoff inside 24 hours is clamped to now minus 24 hours.
+32. Zero removed: fields updated, no `system.activity_cleanup` event. 142 removed: one event with action `system.activity_cleanup`, actor type system, source system, ip and user agent null, params `{"removed":142}`, and it is not deleted by the run that created it.
+33. `DeleteOlderThan` failure: Tick returns the error, last-cleanup fields unchanged, the log buffer holds the error, the next Tick runs again after healing.
+34. Runner: one tick runs one Tick; cancelling the context returns `Run` within a timeout; a done channel proves no goroutine outlives it (`-race`).
+35. Shortening retention from 90 to 30 deletes nothing at PATCH time (repo `DeleteOlderThan` counter 0); the next due Tick deletes older than 30.
+
+## G. Producers (HTTP)
+36. Login: right credentials gives `auth.login` (actor user, source web, security false, failure_reason null, ip and user agent from the request); wrong password and unknown username give `auth.login_failed` with actor anonymous named by the attempted username, outcome failed, security true, failure_reason `Wrong username or password.`, identical for both; validation failure and a rate-limited 429 record nothing. No stored field or log line contains the password.
+37. Logout with a valid cookie gives `auth.logout`; without a cookie records nothing.
+38. Password reset: request for an existing account gives `auth.password_reset_requested` (security true); unknown email records nothing and the response is byte-identical to the existing account's response except `Date`; confirm with a valid code gives `auth.password_reset_completed`; invalid code records nothing. Neither the raw code, its hash nor the new password appears in any stored field or in `buf`.
+39. API key: `POST /v1/api-key` records `api_key.create` with the target `{api_key, <id>, name}`; `DELETE /v1/api-key/7` records `api_key.revoke`; `DELETE /v1/api-key/99` is 404 and records nothing. Marshal every stored event and every `/v1/activity` response and assert the raw key and its hash are absent.
+40. Recorder failure on each producer: the HTTP status and body equal those of the same request with a healthy repository.
+41. End to end: record a failed login, a key creation and a retention change, then `GET /v1/activity` lists them newest first, and `?security=true` returns only the failed login.
+
+## H. Layering and hygiene guards
+42. Grep-style test: `internal/domain/audit` imports only the stdlib and other `internal/domain/*`; the audit use cases import no `gorm`, `persistence`, `mailer`, `net/http`, chi or `api/...`; handlers import no `persistence`, `models` or `gorm`; the persistence repository asserts `var _ audit.Repository = &X{}`; the GORM model lives in `persistence/models` with a mapper.
+43. Grep the new and edited files, Go and docs, for comments: none; only tool directives.
+44. Docs read: `docs/api.md` lists the three activity routes, the query parameters, response shapes, the 400/401/403 answers and the PATCH `/v1/settings` contract with the three new GET fields; `docs/architecture.md` describes `domain/audit`, the recorder and context, the persistence model and indexes, and the retention scheduler; `docs/configuration.md` states that retention is stored in the database (default 90) and that no env var was added.
+
+## Manual (not automated)
+45. Real boot with `task dev:api`: log in with a wrong password, log in correctly, create and revoke an API key, PATCH retention as owner (with the session cookie), then read `/v1/activity` and `/v1/activity/export` and open the CSV in a spreadsheet to confirm injected cells show as text.
+46. Behind a reverse proxy with `TRUSTED_PROXIES` containing the proxy: the stored ip is the client's, not the proxy's. Without it: the proxy's.
+47. Backdate events in the SQLite file, set retention to 30 and either wait for 03:00 or move the system clock; confirm removed rows and the new Last cleanup values in `GET /v1/settings`.
+48. Run the persistence suite against a MySQL/MariaDB and a PostgreSQL instance through the documented database settings of `docs/configuration.md`: index creation, case-insensitive `q`, literal `%` and `_`, date-range boundaries, and `DeleteOlderThan` counts.
+49. SIGINT during a cleanup: the process exits after the run ends, with no database error on close.

features/activity-log-producers.feature

@@ -0,0 +1,506 @@
+Feature: Every real action of the back-office is recorded in the activity log from inside its use case
+
+  As the owner of a RenewCMS site
+  I want articles, media, users and invites, and system tasks to leave an activity event
+  So that the Activity screen shows who did what, and a failed attempt says why in plain words
+
+  Background:
+    Given the spec of record is docs/design/screens/activity.md ("What is recorded", "API contract") and the foundation slice features/activity-log-backend.feature
+    And this slice is backend only: no SPA, no new env var, no new table, no change to docs/design
+    And events are recorded by the use cases through audit.Recorder, never by handlers, middleware or GORM hooks
+    And every mutating use case method takes the request context as its first parameter and hands it to Recorder.Record, which fills actor, source, ip and user agent from the audit context
+    And system events set the system actor and source "system" themselves, with ip and user_agent null
+    And an event is recorded once, after the change was made (success) or after the use case decided to refuse or abort it (failed), never before
+    And no read is recorded: no GET, no list, no public article read, no status poll
+    And error responses are plain text from http.Error and success responses are JSON with snake_case fields, unchanged by this slice
+    And the layering rule holds: use cases see only domain interfaces, no comment is added anywhere
+
+  Rule: The audit context reaches every producing route
+
+    Scenario Outline: A producing route carries the origin of the request
+      When <request> is sent with <credentials>
+      Then the stored event has actor <actor>, source "<source>" and the request ip and user agent
+
+      Examples:
+        | request                      | credentials            | actor                            | source  |
+        | POST /v1/article             | the owner's jwt cookie | the owner, named by display name | web     |
+        | POST /v1/article             | an API key "Deploy bot"| api_key id 7 named "Deploy bot"  | api_key |
+        | POST /v1/media               | an API key "Deploy bot"| api_key id 7 named "Deploy bot"  | api_key |
+        | POST /v1/system/update/check | the owner's jwt cookie | the owner                        | web     |
+
+  Rule: A failed audit write never changes the user's action
+
+    Scenario Outline: A failing or panicking repository leaves the response untouched
+      Given the audit repository <fault> on Append
+      When <request> succeeds
+      Then the response status and body equal those of the same request with a healthy repository
+      And the change itself was applied
+      And the process log names the failed audit write
+
+      Examples:
+        | fault  | request                        |
+        | fails  | POST /v1/article               |
+        | fails  | DELETE /v1/article/8           |
+        | panics | PATCH /v1/article/8/publish    |
+        | fails  | POST /v1/media                 |
+        | fails  | POST /v1/media/merge           |
+        | fails  | POST /v1/user/invite           |
+        | fails  | POST /v1/system/update/restart |
+
+  Rule: Articles
+
+    Scenario: Creating an article is recorded
+      When the owner sends POST /v1/article with {"title": "Spring release", "body": "Hello"}
+      Then one event exists with action "article.create", category "articles", actor the owner, source "web", target {"type": "article", "id": "<new id>", "name": "Spring release"}, outcome "success", failure_reason null and no changes
+      And the stored event holds no article body
+
+    Scenario: Editing the body records a size delta and never the text
+      Given the article 8 "Spring release" has a body of 100 characters
+      When the owner sends PATCH /v1/article/8 with a body of 412 characters
+      Then one event exists with action "article.edit", target {"type": "article", "id": "8", "name": "Spring release"} and changes [{"field": "body", "kind": "body", "delta": 312}]
+      And no stored field and no /v1/activity response contains any text of either body
+
+    Scenario Outline: The delta is signed and counts characters
+      Given the article 8 has a body of <before> characters
+      When its body is replaced by one of <after> characters
+      Then the change delta is <delta>
+
+      Examples:
+        | before | after | delta |
+        | 100    | 412   | 312   |
+        | 412    | 100   | -312  |
+        | 5      | 5     | 0     |
+
+    Scenario: A body with multi-byte characters is counted in characters
+      Given the article 8 has the body "héllo"
+      When its body is replaced by "héllo wörld"
+      Then the change delta is 6
+
+    Scenario: Saving an identical body records nothing
+      Given the article 8 has the body "Same text"
+      When the owner sends PATCH /v1/article/8 with the body "Same text"
+      Then the response is 200 and no event is recorded
+
+    Scenario: A title change is recorded as a text diff when a title edit exists
+      Given a use case that changes an article's title from "Spring release" to "Spring release 2"
+      Then its event has action "article.edit" and changes [{"field": "title", "kind": "text", "before": "Spring release", "after": "Spring release 2"}]
+      And only the fields title, online and body can ever appear in an article event's changes
+
+    Scenario: Publishing is recorded with the publish state
+      Given the article 8 "Spring release" is offline
+      When the owner sends PATCH /v1/article/8/publish
+      Then one event exists with action "article.publish", category "articles" and changes [{"field": "online", "kind": "text", "before": "false", "after": "true"}]
+
+    Scenario: Unpublishing is recorded with the publish state
+      Given the article 8 is online
+      When the owner sends PATCH /v1/article/8/unpublish
+      Then one event exists with action "article.unpublish" and changes [{"field": "online", "kind": "text", "before": "true", "after": "false"}]
+
+    Scenario Outline: A publish state that does not change records nothing
+      Given the article 8 is <state>
+      When the owner sends PATCH /v1/article/8/<path>
+      Then the response is 200 and no event is recorded
+
+      Examples:
+        | state   | path      |
+        | online  | publish   |
+        | offline | unpublish |
+
+    Scenario: Deleting an article is recorded with its name snapshot
+      Given the article 8 "Spring release" exists
+      When the owner sends DELETE /v1/article/8
+      Then one event exists with action "article.delete", target {"type": "article", "id": "8", "name": "Spring release"} and outcome "success"
+      And GET /v1/activity shows that target with exists false
+
+    Scenario Outline: A refused article action is recorded as failed with a plain reason
+      Given <state>
+      When <request>
+      Then one event exists with action "<action>", outcome "failed" and failure_reason "<reason>"
+      And the response is unchanged
+
+      Examples:
+        | state                                    | request                                    | action          | reason                                              |
+        | no article has this title                | POST /v1/article with a 2 character title  | article.create  | The title must be between 3 and 200 characters.     |
+        | the repository fails with "db is locked" | POST /v1/article with a valid title        | article.create  | Something went wrong on our side. Please try again. |
+        | the repository fails with "db is locked" | PATCH /v1/article/8/publish                | article.publish | Something went wrong on our side. Please try again. |
+
+    Scenario: An article that does not exist records nothing
+      When the owner sends DELETE /v1/article/99, PATCH /v1/article/99, PATCH /v1/article/99/publish and PATCH /v1/article/99/unpublish
+      Then every response is 404 and no event is recorded
+
+    Scenario: A request that fails validation records nothing
+      When the owner sends POST /v1/article with an empty body or a malformed id such as /v1/article/abc
+      Then the response is 400 and no event is recorded
+
+    Scenario Outline: Reads are never recorded
+      When <request> is sent
+      Then no event is recorded
+
+      Examples:
+        | request                         |
+        | GET /v1/article                 |
+        | GET /v1/article/8               |
+        | GET /v1/article/8 as the public |
+
+  Rule: Media
+
+    Scenario: Uploading an image is recorded
+      When the owner sends POST /v1/media with the PNG "spring-banner.png"
+      Then one event exists with action "media.upload", category "media", actor the owner, target {"type": "image", "id": "<new id>", "name": "spring-banner.png"} and outcome "success"
+      And the stored event holds no file content and no storage path
+
+    Scenario Outline: A refused upload is recorded as failed
+      When the owner uploads <file>
+      Then one event exists with action "media.upload", outcome "failed" and failure_reason "<reason>"
+      And the target name is the file name as sent, normalised the way a stored upload would be named, or empty when it is unusable
+      And the response is unchanged
+
+      Examples:
+        | file                        | reason                                           |
+        | a GIF                       | The file must be a PNG, JPEG, WEBP or SVG image. |
+        | a PNG larger than the limit | The file is too large to upload.                 |
+        | a corrupt PNG               | The image could not be read.                     |
+
+    Scenario: Renaming an image records the filename diff
+      Given the image 5 "banner.png"
+      When the owner sends PATCH /v1/media/5 with {"filename": "spring-banner"}
+      Then one event exists with action "media.rename", target {"type": "image", "id": "5", "name": "spring-banner.png"} and changes [{"field": "filename", "kind": "text", "before": "banner.png", "after": "spring-banner.png"}]
+
+    Scenario: Renaming to the same name records nothing
+      Given the image 5 "banner.png"
+      When the owner renames it to "banner"
+      Then no event is recorded
+
+    Scenario: A refused rename is recorded as failed
+      Given the image 5 "banner.png"
+      When the owner sends PATCH /v1/media/5 with an invalid filename
+      Then one event exists with action "media.rename", outcome "failed", failure_reason "That file name is not valid." and target {"type": "image", "id": "5", "name": "banner.png"}
+
+    Scenario: Deleting an image is recorded with its name snapshot
+      Given the image 5 "banner.png"
+      When the owner sends DELETE /v1/media/5
+      Then one event exists with action "media.delete", target {"type": "image", "id": "5", "name": "banner.png"} and outcome "success"
+      And GET /v1/activity shows that target with exists false
+
+    Scenario: Merging images is recorded once with its counts
+      Given the images 5 "banner.png", 6 "banner-copy.png" and 7 "banner-copy-2.png" share one content hash
+      And two articles reference the copies
+      When the owner sends POST /v1/media/merge keeping 5 and merging [6, 7]
+      Then one event exists with action "media.merge", target {"type": "image", "id": "5", "name": "banner.png"} and params {"merged": 2, "articles_updated": 2}
+      And no event names a removed copy as a separate action
+
+    Scenario Outline: A refused merge is recorded as failed
+      When the owner sends POST /v1/media/merge that fails with <error>
+      Then one event exists with action "media.merge", outcome "failed" and failure_reason "<reason>"
+
+      Examples:
+        | error                  | reason                              |
+        | ErrInvalidMergeRequest | The merge request is not valid.     |
+        | ErrMergeCopyMissing    | One of the copies no longer exists. |
+        | ErrMergeHashMismatch   | The images are not identical copies.|
+
+    Scenario: A manual purge is recorded once and not as separate merges
+      Given a purge plan with 2 groups, 3 copies and 5 articles to update
+      When the owner sends POST /v1/media/purge
+      Then one event exists with action "media.purge", category "media", actor the owner, source "web", outcome "success" and params {"merged": 3, "articles_updated": 5}
+      And no "media.merge" event is recorded for its groups
+
+    Scenario: A partly failed manual purge is a success with the failed group count
+      Given a purge plan with 3 groups where 1 group fails
+      When the owner sends POST /v1/media/purge
+      Then one event exists with action "media.purge", outcome "success" and params that include "failed_groups": 1
+
+    Scenario Outline: A refused manual purge is recorded as failed
+      When the owner sends POST /v1/media/purge and the use case returns <error>
+      Then one event exists with action "media.purge", outcome "failed" and failure_reason "<reason>"
+
+      Examples:
+        | error            | reason                                                  |
+        | ErrPurgeConflict | The library changed since the preview. Review it again. |
+        | ErrPurgeBusy     | A purge is already running.                             |
+
+    Scenario: The scheduled purge is a system event
+      Given the purge is due and merges 3 copies and updates 5 articles
+      When PurgeSchedulerUseCase.Tick runs
+      Then one event exists with action "system.media_purge", category "system", actor type system named "System", source "system", ip null, user_agent null, outcome "success" and params {"merged": 3, "articles_updated": 5}
+
+    Scenario: A scheduled purge with a failed group records the failed group count
+      Given the purge is due and 1 group fails while others merge
+      When Tick runs
+      Then one event exists with action "system.media_purge", outcome "success" and params that include "failed_groups": 1
+
+    Scenario: A scheduled purge that is not due or merges nothing records nothing
+      Given the purge is not due, or is due and finds no duplicate
+      When Tick runs
+      Then no event is recorded
+
+    Scenario: A scheduled purge that cannot record its run is a failed system event
+      Given the purge is due and the run result cannot be saved
+      When Tick runs
+      Then one event exists with action "system.media_purge", outcome "failed" and failure_reason "Something went wrong on our side. Please try again."
+
+    Scenario: Browsing and the media usage lookup are never recorded
+      When the owner sends GET /v1/media, GET /v1/media/5/usage, GET /v1/media/purge-preview and GET /v1/media/purge-settings
+      Then no event is recorded
+
+  Rule: Users and invites
+
+    Scenario: Registering is recorded with the new account as actor
+      Given registration is open
+      When POST /v1/auth/register is sent with the username "marta"
+      Then one event exists with action "user.register", category "users", actor user "marta" with the new id, source "web", target {"type": "user", "id": "<new id>", "name": "marta"} and outcome "success"
+      And the stored event holds no password, no hash and no verification code
+
+    Scenario Outline: A refused registration is recorded as failed
+      When POST /v1/auth/register is sent and <cause>
+      Then one event exists with action "user.register", outcome "failed", failure_reason "<reason>", actor anonymous named by the attempted username and no target
+      And the response is unchanged
+
+      Examples:
+        | cause                                 | reason                                    |
+        | registration is closed                | Registration is closed on this site.      |
+        | the verification email cannot be sent | The verification email could not be sent. |
+
+    Scenario: Verifying an account is recorded
+      Given the unverified user 4 "lea" with a valid code
+      When user 4 sends POST /v1/auth/verify with that code
+      Then one event exists with action "user.verify", category "users", actor user 4, target {"type": "user", "id": "4", "name": "lea"} and outcome "success"
+      And the stored event does not hold the code or its hash
+
+    Scenario Outline: A refused verification is recorded as failed
+      Given the unverified user 4 "lea"
+      When user 4 sends POST /v1/auth/verify and the use case returns <error>
+      Then one event exists with action "user.verify", outcome "failed" and failure_reason "<reason>"
+
+      Examples:
+        | error                      | reason                              |
+        | ErrInvalidVerificationCode | The verification code is not valid. |
+        | ErrVerificationCodeExpired | The verification code has expired.  |
+
+    Scenario: Changing the display name records a before and after
+      Given user 3 has the display name "Marta"
+      When user 3 sends PATCH /v1/user/me with {"display_name": "Marta Alves"}
+      Then one event exists with action "user.update_profile", category "users", target {"type": "user", "id": "3", "name": "Marta Alves"} and changes [{"field": "display_name", "kind": "text", "before": "Marta", "after": "Marta Alves"}]
+      And the actor snapshot name is the name held when the request began
+
+    Scenario Outline: Setting a display name that does not change records nothing
+      Given user 3 has the display name "<current>"
+      When user 3 sends PATCH /v1/user/me with {"display_name": "<sent>"}
+      Then no event is recorded
+
+      Examples:
+        | current | sent    |
+        | Marta   | Marta   |
+        | Marta   |  Marta  |
+        |         |         |
+
+    Scenario: A display name that is too long is recorded as failed
+      When user 3 sends PATCH /v1/user/me with a 61 character name
+      Then one event exists with action "user.update_profile", outcome "failed" and failure_reason "That display name is too long."
+      And the stored event holds no changes
+
+    Scenario: Creating an invite is recorded
+      When the owner sends POST /v1/user/invite with {"email": "new@example.com"}
+      Then one event exists with action "invite.create", category "users", actor the owner, target {"type": "invite", "id": "<invite id>", "name": "new@example.com"} and outcome "success"
+      And the stored event holds no invite code and no hash
+
+    Scenario Outline: A refused invite action is recorded as failed
+      When the owner <request> and the use case returns <error>
+      Then one event exists with action "<action>", outcome "failed" and failure_reason "<reason>"
+
+      Examples:
+        | request                            | error                    | action        | reason                                           |
+        | sends POST /v1/user/invite         | ErrEmailHasAccount       | invite.create | That email already has an account.               |
+        | sends POST /v1/user/invite         | ErrPendingInvite         | invite.create | An invitation is already pending for that email. |
+        | sends POST /v1/user/invite         | ErrInviteEmailNotSent    | invite.create | The invitation email could not be sent.          |
+        | sends POST /v1/user/invite/4/renew | ErrInviteEmailNotSent    | invite.renew  | The invitation email could not be sent.          |
+        | sends POST /v1/user/invite/4/renew | ErrInviteAlreadyAccepted | invite.renew  | That invitation was already accepted.            |
+        | sends DELETE /v1/user/invite/4     | ErrInviteAlreadyAccepted | invite.cancel | That invitation was already accepted.            |
+
+    Scenario: Cancelling an invite is recorded
+      Given the pending invite 4 for "new@example.com"
+      When the owner sends DELETE /v1/user/invite/4
+      Then one event exists with action "invite.cancel", target {"type": "invite", "id": "4", "name": "new@example.com"} and outcome "success"
+
+    Scenario: Renewing an invite is recorded
+      Given the pending invite 4 for "new@example.com"
+      When the owner sends POST /v1/user/invite/4/renew
+      Then one event exists with action "invite.renew", target {"type": "invite", "id": "4", "name": "new@example.com"} and outcome "success"
+      And a renewal whose email fails is rolled back and recorded only as failed
+
+    Scenario: Accepting an invite is recorded with the new account as actor
+      Given the pending invite 4 for "new@example.com"
+      When POST /v1/auth/invite/accept is sent with a valid code and the username "sam"
+      Then one event exists with action "invite.accept", category "users", actor user "sam" with the new id, source "web", target {"type": "invite", "id": "4", "name": "new@example.com"} and outcome "success"
+      And the stored event holds no code, no hash and no password
+
+    Scenario Outline: A refused acceptance is recorded as failed
+      When POST /v1/auth/invite/accept is sent and the use case returns <error>
+      Then one event exists with action "invite.accept", outcome "failed", failure_reason "<reason>" and actor anonymous named by the attempted username
+      And the stored event has no target when the invite could not be identified
+
+      Examples:
+        | error                    | reason                                |
+        | ErrInviteInvalid         | That invitation is not valid.         |
+        | ErrInviteExpired         | That invitation has expired.          |
+        | ErrInviteAlreadyAccepted | That invitation was already accepted. |
+        | ErrUsernameTaken         | That username is already taken.       |
+        | ErrEmailHasAccount       | That email already has an account.    |
+
+    Scenario: An invite or user that does not exist records nothing
+      When the owner sends DELETE /v1/user/invite/99 or POST /v1/user/invite/99/renew
+      Then every response is 404 and no event is recorded
+
+    Scenario Outline: Reads and checks are never recorded
+      When <request> is sent
+      Then no event is recorded
+
+      Examples:
+        | request                         |
+        | GET /v1/user                    |
+        | GET /v1/auth/me                 |
+        | GET /v1/auth/invite?code=<code> |
+        | GET /v1/auth/registration       |
+
+  Rule: System tasks
+
+    Scenario: Checking for an update is recorded
+      Given the release feed answers v1.4.0 while the running version is v1.3.2
+      When the owner sends POST /v1/system/update/check
+      Then one event exists with action "system.update_checked", category "system", actor the owner, source "web", target {"type": "release", "id": "v1.4.0", "name": "v1.4.0"}, outcome "success" and params {"update_available": true}
+
+    Scenario Outline: A failed update check is recorded with a plain reason
+      When the owner sends POST /v1/system/update/check and the use case returns <error>
+      Then one event exists with action "system.update_checked", outcome "failed", failure_reason "<reason>" and no target
+
+      Examples:
+        | error              | reason                                 |
+        | ErrFeedUnavailable | The release feed could not be reached. |
+        | ErrNoRelease       | No release was found.                  |
+
+    Scenario: The status poll is never recorded
+      When the owner sends GET /v1/system/update
+      Then no event is recorded
+
+    Scenario: A download that completes is recorded when the job is ready
+      Given a newer release v1.4.0 is available and the update helper is installed
+      When the owner sends POST /v1/system/update/download
+      Then the response is returned before the job ends and no event exists yet
+      And when the job reaches the ready state one event exists with action "system.update_downloaded", actor the owner, source "web", target {"type": "release", "id": "v1.4.0", "name": "v1.4.0"} and outcome "success"
+      And the origin (actor, ip, user agent) is the one captured at request time
+
+    Scenario Outline: A download that fails is recorded with a reason that hides the cause
+      Given a newer release v1.4.0 is available and the job fails with the error kind "<kind>"
+      Then one event exists with action "system.update_downloaded", outcome "failed" and failure_reason "<reason>"
+      And the stored event holds no url, no path and no raw error text
+
+      Examples:
+        | kind         | reason                                            |
+        | download     | The update could not be downloaded.               |
+        | verification | The downloaded update failed its integrity check. |
+
+    Scenario Outline: A download refused at the start is recorded as failed
+      When the owner sends POST /v1/system/update/download and the use case returns <error>
+      Then one event exists with action "system.update_downloaded", outcome "failed" and failure_reason "<reason>"
+      And the response is unchanged
+
+      Examples:
+        | error               | reason                                 |
+        | ErrNotPrepared      | This server cannot apply updates.      |
+        | ErrJobInProgress    | An update is already being downloaded. |
+        | ErrRestartPending   | A restart is already pending.          |
+        | ErrNothingToUpdate  | There is nothing to update.            |
+        | ErrPreflightRefused | The update cannot be downloaded.       |
+
+    Scenario: A restart request is recorded
+      Given the update helper is installed and no job is running
+      When the owner sends POST /v1/system/update/restart
+      Then one event exists with action "system.restart_requested", category "system", actor the owner, source "web", outcome "success" and params {"kind": "restart"}
+
+    Scenario: A restart that applies a downloaded update records the kind and version
+      Given a downloaded update v1.4.0 is ready
+      When the owner sends POST /v1/system/update/restart
+      Then the event has params {"kind": "update", "tag": "v1.4.0"}
+
+    Scenario Outline: A refused restart is recorded as failed
+      When the owner sends POST /v1/system/update/restart and the use case returns <error>
+      Then one event exists with action "system.restart_requested", outcome "failed" and failure_reason "<reason>"
+
+      Examples:
+        | error                  | reason                                                 |
+        | ErrNotPrepared         | This server cannot apply updates.                      |
+        | ErrJobInProgress       | An update is still being downloaded.                   |
+        | ErrRestartPending      | A restart is already pending.                          |
+        | ErrRestartKindMismatch | The requested restart does not match the server state. |
+
+  Rule: A failed outcome never exposes more than the plain-language reason
+
+    Scenario: Failure reasons are mapped from domain sentinels
+      Given a table that maps each domain Err sentinel above to a fixed sentence
+      When a use case fails with an error that wraps one of them
+      Then failure_reason is that sentence, matched with errors.Is
+
+    Scenario Outline: Unmapped errors become the generic sentence
+      When a use case fails with <error>
+      Then failure_reason is "Something went wrong on our side. Please try again."
+      And neither the event, the activity API nor the CSV export holds the text of the error
+
+      Examples:
+        | error                                        |
+        | errors.New("db is locked")                   |
+        | an error carrying an SMTP host and password  |
+        | an error carrying a file system path        |
+        | an error wrapping a sentinel and a raw cause |
+
+    Scenario: Every failure reason fits the stored limit
+      Then every mapped sentence is at most 255 characters
+
+    Scenario: A failed event keeps its target when the target is known
+      Given the image 5 "banner.png" exists
+      When a rename of image 5 is refused
+      Then the failed event keeps the target snapshot of image 5
+
+  Rule: Secrets and bodies never reach the log
+
+    Scenario Outline: Sensitive values are absent everywhere
+      Given the action <action> handled <secret>
+      When it is recorded, listed through GET /v1/activity and exported through GET /v1/activity/export
+      Then no stored field, no params, no change, no response, no CSV cell and no process log line contains <secret>
+
+      Examples:
+        | action                   | secret                                           |
+        | user.register            | the password, its hash and the verification code |
+        | user.verify              | the verification code and its hash               |
+        | invite.create            | the invite code and its hash                     |
+        | invite.accept            | the invite code, its hash and the password       |
+        | article.edit             | the old and the new article body                 |
+        | media.upload             | the file bytes and the storage path              |
+        | system.update_downloaded | the asset url and the staging path               |
+
+    Scenario: Only allowlisted fields appear in changes
+      Then the only change fields any producer emits are title, online, body, filename and display_name
+      And the only change kinds are text and body
+
+  Rule: The recorded events read back through the existing API
+
+    Scenario: Producer events are listed with their documented shape
+      Given an article was created, edited, published and deleted by the owner
+      When the owner sends GET /v1/activity?category=articles
+      Then the four events are listed newest first, with category "articles", the documented item shape and the article target exists false after the delete
+
+    Scenario Outline: Categories filter the producers
+      Given one event of each producer was recorded
+      When the owner sends GET /v1/activity?category=<category>
+      Then the items are exactly the events listed in <actions>
+
+      Examples:
+        | category | actions                                                                                                    |
+        | articles | article.create, article.edit, article.publish, article.unpublish, article.delete                           |
+        | media    | media.upload, media.rename, media.delete, media.merge, media.purge                                         |
+        | users    | user.register, user.verify, user.update_profile, invite.create, invite.cancel, invite.renew, invite.accept |
+        | system   | system.media_purge, system.update_checked, system.update_downloaded, system.restart_requested              |
+
+    Scenario: A failed producer event is filterable
+      Given a refused merge and a successful rename were recorded
+      When the owner sends GET /v1/activity?outcome=failed
+      Then only the refused merge is listed with its failure_reason

features/activity-log-producers.qa.md

@@ -0,0 +1,67 @@
+# QA procedure: activity-log-producers
+
+Go only, no SPA. Package `test` (black-box). New files: `test/activity_producers_articles_test.go`, `test/activity_producers_media_test.go`, `test/activity_producers_users_test.go`, `test/activity_producers_system_test.go`, `test/activity_producers_reasons_test.go`. Reuse the foundation helpers in `test/activity_support_test.go` (`mockAuditRepo`, `fakeAuditClock`, `seedEvents`). Extend the existing hand-written fakes (`mockArticleRepo`, the image, user, invite, purge, update and status fakes) with failure switches and call counters. New fake type names must be unique across the package. No live server, no real SMTP, no real SQLite file, no real sleeping, no `time.Ticker`. Secrets in tests are fixed test strings only.
+
+## Setup shared by every case
+1. `validator.InitValidator()` once. `jwtauth.New("HS256", []byte("test-secret"), nil)` stands in for `JWT_SECRET`.
+2. One `auditing.NewRecorder(mockAuditRepo, fakeAuditClock.Now, logger)` shared by every use case. `logger` writes to a `bytes.Buffer` (restore with `t.Cleanup`).
+3. Users: owner 1, admin 2, verified user 3 "Marta", unverified user 4 "lea" (with a hashed code). API key 7 "Deploy bot" in the fake key repo.
+4. A fresh `chi.NewRouter()` per test that mirrors `api/router.go` for the article, user, media, system and auth routers, with `middleware.AuditContext(getUser, trustedProxies)` placed exactly where the router wires it (after `apiKeyAuth()` on the article, user and media routers). Cookies are real signed `jwt` cookies with `user_id` and `token_version`. `httptest.NewRecorder` per request.
+5. Helpers: `eventsOf(repo)`, `onlyEvent(t, repo)` (fails unless exactly one event), `assertNoEvent(t, repo)`.
+6. Each mutating use case method takes `ctx context.Context` first. A method called with a context holding no origin still works.
+
+## A. Origin and routing
+7. Table (feature rule 1): each request with the cookie or the API key yields the expected actor type, id, name and source, plus the request ip and user agent. Proves `AuditContext` is mounted on the article, user, media and system routers.
+8. A route without credentials, or answered 401/403/429, records nothing.
+
+## B. Articles
+9. Create: one `article.create` event, target id string, name as typed, no changes, no body anywhere (marshal the event and assert absence).
+10. Edit: table `(before, after, delta)`: 100 to 412 (312), 412 to 100 (-312), 5 to 5 with different content (0, still recorded), `héllo` to `héllo wörld` (6, characters not bytes). Identical body records nothing. Change kind `body`, `Delta` set, `Before` and `After` nil.
+11. Publish and unpublish: `online` text change (`"false"`/`"true"`). Repeating the same state records nothing and returns 200.
+12. Delete: event keeps the name snapshot. After it, `GET /v1/activity` shows `target.exists` false.
+13. Title diff: unit-test the change builder with title, online and body only; any other field name is rejected.
+14. Failure table: 2 character title, repository failing with `errors.New("db is locked")` (generic reason). 404 on delete, edit, publish, unpublish of id 99 and 400 on malformed id or body record nothing.
+15. Reads (list, get, public get) record nothing.
+
+## C. Media
+16. Upload: in-memory PNG, target name equals the normalised filename, no bytes and no path. Failed upload table: GIF, oversize, corrupt PNG, each with its mapped reason.
+17. Rename: `filename` text change `banner.png` to `spring-banner.png`. Same name records nothing. Invalid stem records a failed event keeping the target. Missing image records nothing (404).
+18. Delete: event with name snapshot. Missing image records nothing.
+19. Merge: three images with one hash, two articles referencing the copies. One `media.merge` event with `{"merged":2,"articles_updated":2}`, target the kept image. Failure table: `ErrInvalidMergeRequest`, `ErrMergeCopyMissing`, `ErrMergeHashMismatch`.
+20. Manual purge: plan with 2 groups, 3 copies, 5 articles. Exactly one `media.purge` event with `{"merged":3,"articles_updated":5}` and zero `media.merge` events. A plan with one failing group: outcome success with `failed_groups` 1. `ErrPurgeConflict` and `ErrPurgeBusy` give failed events. Preview, usage, list and settings GETs record nothing.
+21. Scheduled purge: drive `PurgeSchedulerUseCase.Tick(now)` with the fake purge repo and clock. Due and merging 3: one `system.media_purge` event with system actor, source system, ip nil, user agent nil. Due with a failed group: success with `failed_groups`. Not due, or no duplicates: none. A fake `SaveLastRun` failure: failed event with the generic reason.
+22. Manual purge after the scheduler in the same test yields two events with sources `web` and `system`.
+
+## D. Users and invites
+23. Register: open registration records `user.register` with the new account as actor and target. Closed registration and a failing mailer (error carrying a fake SMTP password) record failed events with the mapped reason, anonymous actor named by the attempted username, no raw text. Marshal the event and assert password, hash and code are absent.
+24. Verify: success, invalid code, expired code.
+25. Display name: before/after diff, trimmed no-op records nothing, empty to empty records nothing, 61 characters records a failed event with no changes. Actor snapshot name is the pre-change name.
+26. Invites: create, cancel, renew, accept each record the documented event with the invited email as target name. Failure table covers every error in the feature. A renew whose mail fails is rolled back and records one failed event only. Unknown ids (404) record nothing.
+27. Accept: actor is the new account, source `web`; failed accept actor is anonymous with the attempted username.
+28. Reads (`GET /v1/user`, `/v1/auth/me`, `/v1/auth/invite`, `/v1/auth/registration`) record nothing.
+
+## E. System tasks
+29. Check: success event with `{"update_available":true}` and a release target. `ErrFeedUnavailable` and `ErrNoRelease` give failed events without target. Status `GET` records nothing.
+30. Download: fakes complete the job through a hand-fed channel (no `time.Sleep`). No event before the job ends, one after `ready`; actor, ip and user agent are those captured at request time even though the request context was cancelled. Failure kinds `download` and `verification` give the two reasons, no URL or path. Start-time refusals give failed events. Run with `-race`.
+31. Restart: `{"kind":"restart"}` and `{"kind":"update","tag":"v1.4.0"}`. Refusals for `ErrNotPrepared`, `ErrJobInProgress`, `ErrRestartPending`, `ErrRestartKindMismatch`.
+
+## F. Reasons, secrets and recorder faults
+32. Reason table: wrap each sentinel with `fmt.Errorf("%w: %w", sentinel, errors.New("secret detail"))`, assert the sentence equals the table and the extra text is absent. Unmapped errors give the generic sentence. Every sentence is at most 255 characters.
+33. Recorder fault: for each producer row of the fault table, run with failing, panicking and healthy `mockAuditRepo`. Identical status and body, change applied, log line naming the failed write.
+34. Secret sweep: after exercising every producer, marshal every stored event, the `/v1/activity` response and the `/v1/activity/export` file; assert none contains the password, hash, verification code, invite code, raw API key, article body, file bytes, asset URL or staging path. The log buffer is free of them too.
+35. Allowlist: every `Change.Field` is in `{title, online, body, filename, display_name}` and every kind is `text` or `body`.
+36. Read-back: list by `category=articles|media|users|system` and `outcome=failed`; compare action sets with the feature tables.
+
+## G. Mutation guard (gremlins stays clean)
+37. `task mutate` scope is `./internal/infrastructure/useCases`. Each new branch needs a killing assertion: every no-op guard (body, online, filename, display name) with equal and differing values; delta sign and rune-versus-byte count; success versus failed outcome and recorded once after the change (event count and order against the repository call); every `errors.Is` row of the reason map plus the generic fallback; every `ctx` forwarding; the system-actor defaults. Bare-bool conditions produce no mutant, so cover both branches with tests regardless.
+
+## H. Layering and hygiene
+38. Touched use cases import no `gorm`, `persistence`, `mailer`, `net/http`, chi or `api/...`; handlers only pass `r.Context()`; `internal/domain/audit` imports only stdlib and domain packages.
+39. No comments in new or edited Go files, test files and docs, except tool directives.
+40. Docs (`docs/api.md`, `docs/architecture.md`) list the action catalogue, target types, reason sentences and the rule that no read is recorded.
+
+## Manual (not automated)
+41. Real boot with `task dev:api` and SMTP: register, verify, invite, renew, accept and cancel an invite, change display name, create/edit/publish/unpublish/delete an article, upload/rename/merge/delete images, manual purge; read `/v1/activity` and the CSV export and read every sentence.
+42. Real update helper on Linux systemd (or the Docker QA flow): check, download until `ready`, restart; one event each, real asset names absent. Skip in a container.
+43. Leave the scheduled purge due and wait for the hourly tick: a single `system.media_purge` event, source `system`, no ip or user agent.
+44. Remove the database file's write access during one article edit: edit result unchanged, process log names the audit write failure.

features/activity_home_card_and_retention.feature

@@ -0,0 +1,618 @@
+Feature: Recent activity card on Home and Retention card on Settings
+
+  As a RenewCMS user
+  I want Home to show my last five activity events and the owner to choose how long activity is kept on Settings
+  So that I see what happened without opening the Activity page, and the log does not grow without bound
+
+  Background:
+    Given the activity API (features/activity-log-backend.feature, activity-log-producers.feature, activity_screen.feature) and the settings retention fields already exist
+    And this slice adds one field to the settings API, activity_next_cleanup_at, and wires the SPA to the existing endpoints; there is no other Go change
+    And the Home card and the Settings "Retention" card are the two items activity_screen.feature left out of scope; the spec of record is docs/design/screens/home.md ("Recent activity") and docs/design/screens/settings.md ("Activity retention"), groups "Home" and "Settings: Retention" of RenewCMS Screens Back-office.dc.html
+    And both boards draw the existing cards as dashed placeholders, so neither card is pixel-compared and Vitest is the SPA coverage
+    And "owner" and "admin" are the full Home view; any other or absent session role is the regular-user view
+    And every new English string has a French entry in messages.ts
+    And GET /v1/settings (every verified user) and PATCH /v1/settings (owner only, behind RequireOwner) both answer with the JSON object {"version", "activity_retention_days", "activity_last_cleanup_at", "activity_last_cleanup_removed", "activity_next_cleanup_at"}, snake_case, nothing else
+    And this supersedes the statement of features/settings_page.feature that the body is exactly {"version": "<value>"}; the version field and the verified-user access of that feature are unchanged
+    And activity_next_cleanup_at is an RFC 3339 timestamp with the server's offset, or null when activity_retention_days is 0 (Forever)
+    And otherwise it is the next 03:00 (audit.CleanupHour) in the server's time zone strictly after the server's current time
+    And the value is computed in the domain (audit.Settings) from the clock the use cases are built with, never in the handler and never in the SPA
+    And the cleanup it announces is the existing daily job, which never touches the last 24 hours (audit.KeepRecentHours)
+    And GetActivityRetentionUseCase and UpdateActivityRetentionUseCase both return the value, so a PATCH response carries the next cleanup of the new period (null after switching to Forever, a timestamp after leaving Forever)
+    And the existing validation, 400 with the text of apperr.BodyErrorMessage for any value outside 0, 30, 90, 365 or a malformed body, and 403 for a non-owner are unchanged
+    And the domain package stays free of GORM, HTTP and the clock source (the clock is passed in)
+    And on /home a card "Recent activity" (RecentActivityCard) sits in a 420 px column to the right of the existing cards from the lg breakpoint up, with a 16 px gap, in a grid (minmax(0,1fr) 420px, items aligned to the start) that spans the full content width, with no max-width, as the board frame draws it
+    And the greeting header and the update banner stay above the grid at full width
+    And below lg the card is stacked above the stat tiles and the recent article list, below the banner, with a 16 px gap
+    And the card is --ui-bg with a 1 px --ui-border and a header row (12px 16px padding, 1 px bottom border) holding the title (14 px semibold, --ui-text-highlighted) and, at the right, the link "View all" with an arrow-right icon (14 px; 44 px touch height below lg) to /activity
+    And the title is "Recent activity", and "Your recent activity" in the regular-user view
+    And on mount the card sends exactly one GET /v1/activity?size=5 with no other parameter and never an actor parameter; it never calls /summary or /export; the server returns own events only for a regular user
+    And no range is sent, so the server's default of 7 days applies and a site quiet for more than a week reads "No activity yet"
+    And the card loads independently of GET /v1/article/: neither waits for or blocks the other, and an error or empty card leaves the stat tiles, the recent article list, the articles' own empty and error states and "Connect your website" as they are
+    And each row (up to 5, in API order) has a 24 px avatar, the sentence clamped to two lines with the target name in semibold (composed by ActivitySentence exactly as on /activity, never stored text), then a muted 12 px line: "{actor name} · {time}" in the full view and only "{time}" in the regular-user view
+    And the avatar is the same as the Actor cell of /activity (initials for a user, key-round for an API key, cog for the system, user-round-x for an anonymous actor)
+    And the time of an event of today is "{n} min ago" or "{n} h ago" (lib/activityTime), an event of yesterday reads "Yesterday, 14:20" and an older one "3 Oct 2026, 14:20" (French "Hier, 14:20", "3 oct. 2026, 14:20"); the full local time with seconds is its title attribute
+    And a failed event shows a "Failed" badge at the right of its row; a successful event with security true shows a small shield icon (14 px, --ui-warning) and no badge; a failed security event shows the badge only
+    And rows are not interactive; only "View all" navigates
+    And while the request is in flight for longer than 150 ms the card body shows five skeleton rows (24 px circle, two bars) and aria-busy="true"; nothing is drawn in the body for the first 150 ms
+    And on a 500, any other non-401 status or a network failure the body is an inline role="alert" error with icon circle-x, title "Couldn't load recent activity", no description, and a "Try again" button that sends the same GET /v1/activity?size=5 again; a 401 is handled globally by useApi
+    And when total is 0 the body is the empty state: icon history, "No activity yet" and "Actions on your site will appear here." (regular user: "Your actions will appear here.")
+    And on /settings, for the owner only, a third card (RetentionCard) follows UpdatesCard and MediaCleanupCard and has the same width as its sibling cards; for an admin, a regular user or an absent role it is not rendered at all
+    And the card reads GET /v1/settings, the single call SettingsView already makes, whose typed response is widened with the four activity_* fields; the page still sends exactly one GET /v1/settings per navigation
+    And the header is "Retention" (14 px semibold) over "How long activity is kept." (12 px muted) with a status area at the right, aria-live="polite": "Saving…" (loader-circle) while a PATCH is in flight, "Saved" (check, --ui-success) for 2 s after it succeeds
+    And the body has the label "Keep activity for" over a USelectMenu (at most 260 px wide) with the items "30 days", "90 days", "365 days", "Forever" (values 30, 90, 365, 0) and a 12 px muted helper: "Older events are removed automatically." or, for Forever, "Nothing is removed automatically. The log grows over time."
+    And an info UAlert with icon lock is always shown: "Activity logs are append-only" / "Events can't be edited or deleted from the app. Only the retention period removes them."
+    And after a divider two read-only lines (120 px label then value; stacked on mobile) are shown in the user's local time: "Last cleanup" reads "6 Oct 2026, 03:00 · 142 events removed" ("1 event removed" for 1), or "Never" when activity_last_cleanup_at is null; "Next cleanup" reads "7 Oct 2026, 03:00" from activity_next_cleanup_at, or "Not scheduled" when it is null
+    And for Forever the last-cleanup line still shows the real last cleanup when one exists, and "Never" otherwise
+    And the periods are ordered 30 < 90 < 365 < Forever, and "shorter" means a lower rank than the saved period
+    And choosing a longer period, including Forever, sends PATCH /v1/settings with {"activity_retention_days": <value>} at once
+    And choosing a shorter period sends nothing and shows a warning UAlert with icon triangle-alert, title "Events older than {n} days will be removed", text "This happens at the next cleanup on {date}. It can't be undone." (the date is the saved settings' activity_next_cleanup_at, formatted like the line above) and the buttons "Apply {n} days" and "Cancel"
+    And a PATCH 200 returns the full settings, which refresh the select and the last and next lines
+    And any non-401 PATCH failure (400, 403, 500, network) shows an error UAlert with icon circle-x, title "Couldn't save the retention period", text "Your previous setting is still in place." and a "Try again" button, reverts the select to the saved value and leaves the lines unchanged; a 403 additionally refreshes the session, after which the card is gone
+    And "Try again" re-sends the failed value without asking for the shortening confirmation again
+    And while GET /v1/settings is loading for longer than 150 ms the card shows skeleton lines with aria-busy="true"
+    And when GET /v1/settings fails the card shows the Media cleanup card's alert, "Couldn't reach RenewCMS. Check your connection and try again." with "Try again", which re-runs the shared load
+    And while the browser is offline the select, "Apply" and "Cancel" are disabled; the page's offline banner copy is unchanged
+
+  Scenario Outline: Settings API, GET returns the next cleanup of the saved period
+    Given the saved retention is <days> days and the server time is <now> in a server zone of +02:00
+    When a verified user sends GET /v1/settings
+    Then the status is 200
+    And the body has "activity_next_cleanup_at" <next> and the other four fields
+
+    Examples:
+      | days | now                       | next                        |
+      | 90   | 2026-10-06T10:00:00+02:00 | "2026-10-07T03:00:00+02:00" |
+      | 90   | 2026-10-06T02:59:59+02:00 | "2026-10-06T03:00:00+02:00" |
+      | 90   | 2026-10-06T03:00:00+02:00 | "2026-10-07T03:00:00+02:00" |
+      | 30   | 2026-12-31T23:30:00+02:00 | "2027-01-01T03:00:00+02:00" |
+      | 365  | 2026-10-06T10:00:00+02:00 | "2026-10-07T03:00:00+02:00" |
+      | 0    | 2026-10-06T10:00:00+02:00 | null                        |
+
+  Scenario: Settings API, GET keeps the existing fields and adds exactly one
+    Given the saved retention is 90 days, the last cleanup is 2026-10-06T01:00:00Z with 142 events removed
+    When a verified user sends GET /v1/settings
+    Then the body is a JSON object with exactly the keys version, activity_retention_days, activity_last_cleanup_at, activity_last_cleanup_removed and activity_next_cleanup_at
+
+  Scenario: Settings API, GET is open to every verified user
+    Given a verified admin or editor sends GET /v1/settings
+    Then the status is 200 and the body includes activity_next_cleanup_at
+
+  Scenario Outline: Settings API, PATCH returns the next cleanup of the new period
+    Given the saved retention is <from> days and the user is the owner
+    When the owner sends PATCH /v1/settings with {"activity_retention_days": <to>}
+    Then the status is 200 and activity_retention_days is <to>
+    And activity_next_cleanup_at is <next>
+
+    Examples:
+      | from | to  | next                          |
+      | 90   | 30  | the next 03:00 server time    |
+      | 90   | 0   | null                          |
+      | 0    | 365 | the next 03:00 server time    |
+      | 90   | 90  | the next 03:00 server time    |
+
+  Scenario: Settings API, PATCH with the saved value changes nothing
+    Given the saved retention is 90 days
+    When the owner sends PATCH /v1/settings with {"activity_retention_days": 90}
+    Then the status is 200, nothing is saved and no audit event is recorded
+
+  Scenario: Settings API, PATCH by a non-owner is refused and changes nothing
+    Given a verified admin
+    When the admin sends PATCH /v1/settings with {"activity_retention_days": 30}
+    Then the status is 403 with the text "Only the owner can do this." and the saved retention is unchanged
+
+  Scenario Outline: Settings API, PATCH rejects invalid input
+    When the owner sends PATCH /v1/settings with <body>
+    Then the status is 400 with the text of apperr.BodyErrorMessage and nothing is saved
+
+    Examples:
+      | body                              |
+      | {"activity_retention_days": 7}    |
+      | {"activity_retention_days": "30"} |
+      | {}                                |
+      | not json                          |
+
+  Scenario: Settings use cases compute the next cleanup from their clock
+    Given GetActivityRetentionUseCase and UpdateActivityRetentionUseCase are built with a fake settings repository and a fixed clock
+    Then GetActivityRetention returns Settings whose NextCleanupAt is the next 03:00 after the clock, or nil for Forever
+    And UpdateActivityRetention returns the new period with its own NextCleanupAt
+    And UpdateActivityRetention(7) returns an error satisfying errors.Is(err, audit.ErrInvalidRetention) and saves nothing
+
+  Scenario Outline: Home, owner or admin, the last five events with the actor name
+    Given the session role is "<role>" and GET /v1/activity?size=5 resolves 200 with 5 events, the first being Marta Alves publishing the article "Spring release" 2 minutes ago
+    When the user navigates to /home
+    Then the card title is "Recent activity" and "View all" links to /activity
+    And row 1 reads "Published the article Spring release" with "Spring release" in semibold, over "Marta Alves · 2 min ago", with a 24 px avatar "MA"
+    And exactly 5 rows are shown and GET /v1/activity was requested once with size=5 and no other parameter
+
+    Examples:
+      | role  |
+      | owner |
+      | admin |
+
+  Scenario Outline: Home, regular user, own events only and no actor name
+    Given the session role is "<role>" and GET /v1/activity?size=5 resolves 200 with 3 own events
+    When the user navigates to /home
+    Then the card title is "Your recent activity"
+    And each row's meta line is only the time, for example "2 min ago"
+    And no actor parameter was sent
+
+    Examples:
+      | role   |
+      | editor |
+      | absent |
+
+  Scenario Outline: Home rows, failure and security markers
+    Given an event with outcome "<outcome>" and security <security>
+    Then its row shows <marker>
+
+    Examples:
+      | outcome | security | marker                         |
+      | success | false    | no badge and no shield         |
+      | failed  | false    | a "Failed" badge               |
+      | success | true     | a shield icon and no badge     |
+      | failed  | true     | a "Failed" badge and no shield |
+
+  Scenario Outline: Home rows, the time label follows the day
+    Given the current time is 2026-10-06 15:00 local and an event created <when>
+    Then the meta time reads "<label>"
+
+    Examples:
+      | when             | label             |
+      | 2026-10-06 14:58 | 2 min ago         |
+      | 2026-10-06 12:00 | 3 h ago           |
+      | 2026-10-05 14:20 | Yesterday, 14:20  |
+      | 2026-10-03 14:20 | 3 Oct 2026, 14:20 |
+
+  Scenario: Home rows, a long sentence is clamped to two lines
+    Given an event on an article whose title has 150 characters
+    Then the sentence is clamped to two lines with the title in semibold and the meta line stays on one line
+
+  Scenario: Home rows, an unknown action and a failed login
+    Given an event with action "article.archive" and an "auth.login_failed" event for "alex@example.com"
+    Then the first row shows "article.archive", the second "Failed login attempt for alex@example.com" with a "Failed" badge and the user-round-x avatar, and nothing throws
+
+  Scenario: Home rows are not interactive
+    Then a click on a row navigates nowhere and opens nothing
+
+  Scenario: Home card, skeleton rows only after 150 ms
+    Given GET /v1/activity?size=5 has not resolved
+    When the user navigates to /home
+    Then nothing is drawn in the card body for the first 150 ms
+    And after 150 ms five skeleton rows are shown and the card is aria-busy="true"
+    When the request resolves 200 with 5 events
+    Then the skeletons are replaced by 5 rows
+    And a response in under 150 ms never shows a skeleton
+
+  Scenario Outline: Home card, error shows a retryable alert that leaves the page alone
+    Given GET /v1/activity?size=5 <failure> and GET /v1/article/ resolves 200 with 6 articles
+    When the user navigates to /home
+    Then the card shows an alert "Couldn't load recent activity" with a "Try again" button
+    And the stat tiles "6" "articles", "4" "online", "2" "drafts", the recent article list and "Connect your website" are shown as in home.feature's Default state
+    When the user activates "Try again"
+    Then GET /v1/activity?size=5 is sent again and, on 200 with events, the rows replace the alert
+
+    Examples:
+      | failure                      |
+      | resolves with a 500 response |
+      | resolves with a 403 response |
+      | never reaches the server     |
+
+  Scenario Outline: Home card, empty when there are no events yet
+    Given GET /v1/activity?size=5 resolves 200 with items [] and total 0 and the role is "<role>"
+    When the user navigates to /home
+    Then the card shows the history icon, "No activity yet" and "<text>"
+    And "View all" is still shown
+
+    Examples:
+      | role   | text                                   |
+      | owner  | Actions on your site will appear here. |
+      | editor | Your actions will appear here.         |
+
+  Scenario: Home card and article list are independent
+    Given GET /v1/article/ fails with a 500 and GET /v1/activity?size=5 resolves 200 with 5 events
+    Then the articles alert "Couldn't load your articles" and the 5 activity rows are both shown
+    And with GET /v1/article/ resolving [] and GET /v1/activity?size=5 failing, the articles' Empty state and the card's error are both shown
+
+  Scenario: Home layout is two columns from lg and stacked below
+    Given the viewport is lg or wider
+    Then the header and the update banner span the full content width and the grid below them spans the same full width with the article cards on the left and the activity card 420 px wide in the far-right column, 16 px apart, its top aligned with the top of the article cards
+    Given the viewport is below lg
+    Then the card sits above the stat tiles, below the banner, at full width
+
+  Scenario: Home card, "View all" opens the activity page
+    When the user activates "View all"
+    Then the router navigates to /activity
+
+  Scenario: Settings retention is hidden for everyone but the owner
+    Given GET /v1/settings resolves 200 with activity_retention_days 90
+    When an "admin" (or an "editor", or an absent role) navigates to /settings
+    Then no "Retention" card and no "Keep activity for" select is in the page
+    And the Version, Updates and Media cleanup cards are unchanged
+    And GET /v1/settings was requested once
+
+  Scenario: Settings retention, Default with 90 days
+    Given the role is "owner" and GET /v1/settings resolves 200 with activity_retention_days 90, activity_last_cleanup_at 6 Oct 2026 03:00 local, activity_last_cleanup_removed 142 and activity_next_cleanup_at 7 Oct 2026 03:00 local
+    When the owner navigates to /settings
+    Then the third card reads "Retention" and "How long activity is kept."
+    And the select shows "90 days" with the helper "Older events are removed automatically."
+    And the lock alert "Activity logs are append-only" is shown
+    And the lines read "Last cleanup" "6 Oct 2026, 03:00 · 142 events removed" and "Next cleanup" "7 Oct 2026, 03:00"
+    And no "Saved" is shown, no PATCH was sent and GET /v1/settings was requested once
+
+  Scenario: Settings retention, before the first cleanup
+    Given activity_last_cleanup_at is null and activity_next_cleanup_at is set
+    Then "Last cleanup" reads "Never" and "Next cleanup" shows the date
+
+  Scenario: Settings retention, skeleton lines after 150 ms
+    Given GET /v1/settings has not resolved and the role is "owner"
+    When the owner navigates to /settings
+    Then nothing is drawn in the card body for the first 150 ms, then skeleton lines with aria-busy="true"
+
+  Scenario: Settings retention, the settings request fails
+    Given GET /v1/settings fails with a 500
+    Then the card shows "Couldn't reach RenewCMS. Check your connection and try again." with a "Try again" button that re-runs the shared GET /v1/settings
+
+  Scenario Outline: Settings retention, a longer period saves at once
+    Given the saved period is <from> and the owner chooses "<to>"
+    When PATCH /v1/settings resolves 200 with activity_retention_days <value> and the matching activity_next_cleanup_at
+    Then PATCH was sent once with {"activity_retention_days": <value>} and no warning alert is shown
+    And the status reads "Saving…" while in flight and "Saved" with a check afterwards, fading after 2 s
+    And the select shows "<to>" and the "Next cleanup" line shows the returned value
+
+    Examples:
+      | from    | to       | value |
+      | 90 days | 365 days | 365   |
+      | 30 days | 90 days  | 90    |
+      | 90 days | Forever  | 0     |
+
+  Scenario: Settings retention, Forever changes the helper and the lines
+    Given the saved period is 90 days and the owner chooses "Forever" and PATCH resolves 200 with activity_retention_days 0, activity_next_cleanup_at null and a last cleanup of 6 Oct 2026 03:00 with 142 removed
+    Then the helper reads "Nothing is removed automatically. The log grows over time."
+    And "Next cleanup" reads "Not scheduled" and "Last cleanup" still reads "6 Oct 2026, 03:00 · 142 events removed"
+
+  Scenario: Settings retention, Forever and never cleaned
+    Given GET /v1/settings resolves 200 with activity_retention_days 0, activity_last_cleanup_at null and activity_next_cleanup_at null
+    Then "Last cleanup" reads "Never" and "Next cleanup" reads "Not scheduled"
+
+  Scenario: Settings retention, shortening asks first
+    Given the saved period is 90 days and activity_next_cleanup_at is 7 Oct 2026 03:00 local
+    When the owner chooses "30 days"
+    Then no PATCH is sent and the select shows "30 days"
+    And a warning alert shows "Events older than 30 days will be removed" and "This happens at the next cleanup on 7 Oct 2026, 03:00. It can't be undone." with "Apply 30 days" and "Cancel"
+    When the owner activates "Apply 30 days" and PATCH resolves 200 with activity_retention_days 30
+    Then PATCH was sent once with {"activity_retention_days": 30}, the alert is gone and "Saved" shows
+
+  Scenario: Settings retention, shortening cancelled
+    Given the warning for 30 days is shown on a saved 90
+    When the owner activates "Cancel"
+    Then the alert is gone, the select reads "90 days" again and no PATCH was ever sent
+
+  Scenario Outline: Settings retention, shortening is relative to the saved period
+    Given the saved period is <saved>
+    When the owner chooses "<chosen>"
+    Then <outcome>
+
+    Examples:
+      | saved    | chosen   | outcome                                                        |
+      | Forever  | 365 days | the warning "Events older than 365 days will be removed" shows |
+      | 365 days | 90 days  | the warning "Events older than 90 days will be removed" shows  |
+      | 90 days  | 90 days  | nothing happens and no request is sent                         |
+      | 30 days  | Forever  | PATCH is sent at once                                          |
+
+  Scenario: Settings retention, choosing a longer period while the warning is open drops it
+    Given the warning for 30 days is shown on a saved 90
+    When the owner chooses "365 days"
+    Then the warning disappears and PATCH is sent once with 365
+    When the owner then chooses "30 days" and again "365 days" before the first request settles or after it
+    Then no stale warning is ever left on screen
+
+  Scenario Outline: Settings retention, save error reverts the control and Try again retries
+    Given the saved period is 90 days and the owner chooses "365 days"
+    When PATCH /v1/settings <failure>
+    Then an error alert shows "Couldn't save the retention period" and "Your previous setting is still in place." with "Try again"
+    And the select shows "90 days" again, the lines are unchanged and no "Saved" appears
+    When the owner activates "Try again" and PATCH resolves 200 with 365
+    Then PATCH was sent a second time with 365 and "Saved" replaces the alert
+
+    Examples:
+      | failure                      |
+      | resolves with a 500 response |
+      | resolves with a 400 response |
+      | resolves with a 403 response |
+      | never reaches the server     |
+
+  Scenario: Settings retention, Try again after Apply does not ask again
+    Given the warning for 30 days is shown and the owner activates "Apply 30 days"
+    When PATCH resolves 500
+    Then the warning is gone, the error alert is shown and the select reads the saved period
+    When the owner activates "Try again" and PATCH resolves 200 with 30
+    Then PATCH was sent a second time with 30 and no warning reappears
+
+  Scenario: Settings retention, an owner demoted while the page is open
+    Given PATCH /v1/settings resolves 403 and GET /v1/auth/me then resolves with role "admin"
+    Then the error alert is shown and, after the session refresh, the Retention card is no longer rendered
+
+  Scenario: Settings retention, offline disables the controls
+    Given the owner is on /settings and the browser goes offline
+    Then the select, and "Apply" and "Cancel" when shown, are disabled and nothing is sent
+    And the page's offline banner keeps its existing copy
+
+  Scenario: Settings retention, a 401 is global
+    Given GET or PATCH /v1/settings resolves 401
+    Then useApi redirects to /login?redirect=/settings&reason=expired and no card alert is shown
+
+  Scenario: The French interface
+    Given the language is French
+    Then every string of both cards is French and the Home rows use the French sentence templates of activity_screen.feature
+
+  Scenario: Existing behaviour is unchanged
+    Then every scenario of home.feature, settings_page.feature (except its exact-body statement, superseded above) and the Media cleanup scenarios still holds with GET /v1/activity?size=5 mocked and the settings mock widened with the four activity_* fields
+
+  Rule: Retention size limit, an optional maximum size as an alternative to the age limit
+
+    Background:
+      Given this rule supersedes the statements above where they conflict: the settings body, the next-cleanup rule, the PATCH validation, the card copy and the shortening rule
+      And this extension changes Go code in the audit settings, the audit repositories, the settings and cleanup use cases and the settings handler
+      And GET /v1/settings and the PATCH response carry exactly {"version", "activity_retention_days", "activity_retention_max_gb", "activity_log_size_bytes", "activity_last_cleanup_at", "activity_last_cleanup_removed", "activity_next_cleanup_at"}, snake_case
+      And activity_next_cleanup_at is null only when activity_retention_days is 0 and activity_retention_max_gb is 0, otherwise it is the next 03:00 (audit.CleanupHour) in the server zone strictly after now, so Forever with a size limit has a schedule
+      And the PATCH body is a partial object with activity_retention_days in {0, 30, 90, 365} and/or activity_retention_max_gb in {0, 1, 5, 10, 25, 50}, absent keys are left unchanged, and an empty object, a null, a wrong type, any other value or malformed JSON answers 400 with apperr.BodyErrorMessage and saves nothing
+      And a non-owner PATCH answers 403 "Only the owner can do this."
+      And validation goes through validate tags and validator.Validate.Struct
+      And the size options are one list in the audit domain, audit.SizeOptions(), mirroring RetentionOptions()
+      And activity_log_size_bytes is the payload size of the activity events table, measured by audit.Repository.SizeBytes: the sum of the OCTET_LENGTH of the text columns action, actor_name, target_type, target_id, target_name, failure_reason, ip, user_agent, params and changes plus a fixed per-row overhead constant defined in the domain
+      And it is not the database file size and excludes indexes, free pages and other tables, and repositories never touch files
+      And the audit Repository gains SizeBytes() (int64, error) and DeleteOldest(limit int, before time.Time) (int, error); DeleteOldest removes the oldest events by created_at then id and only those older than before
+      And the cleanup runs the age step when days is greater than 0, then removes the oldest events in batches through DeleteOldest, calling SizeBytes between batches, until the log is at or under the limit or a batch removes 0
+      And the cutoff of every removal is the 24 hour guard (audit.KeepRecentHours); when the limit cannot be met because of the guard, the cleanup stops without error, records the run and tries again at the next 03:00
+      And Tick returns early only when days is 0 and max_gb is 0
+      And the removed count is the total of the age and size removals, in the last-cleanup fields and in the system.activity_cleanup params {"removed": n}
+      And system.activity_retention_changed is recorded once per PATCH that changes something, with params {"from","to"} when the age changes and "max_gb_from" and "max_gb_to" when the size changes, and no event when nothing changes
+      And lib/activitySentence.ts has an English and a French sentence for a size change
+      And GET /v1/settings computes the size on every call and a SizeBytes failure answers 500, like any use case error; every verified user receives the number, only the owner sees the card
+      And the SPA shows the size in GB (1 GB is 1024^3 bytes) with one decimal, or "Less than 0.1 GB" below 0.1 GB
+      And the header description is "How long activity is kept, and how much log data to keep. Whichever limit is reached first removes the oldest events. Only owners can change it."
+      And the append-only alert reads "Events can't be edited or deleted from the app. Only the retention limits remove them."
+      And below the age select an "or" divider is followed by the label "Keep at most" over a USelectMenu 160 px wide (full width on mobile) with the items "No size limit", "1 GB", "5 GB", "10 GB", "25 GB", "50 GB" (values 0, 1, 5, 10, 25, 50)
+      And the age helper is "Older events are removed automatically." without a size limit, "Events older than this are removed." with one, "Nothing is removed automatically. The log grows over time." for Forever without a size limit and "No age limit. Only the size limit applies." for Forever with one
+      And the size helper is "Optional. Logs can grow without a size cap." without a limit and "When logs pass 5 GB, the oldest events are removed. Currently 3.2 GB." with one, the figure being activity_log_size_bytes and never a hard-coded value
+      And the size rank is 1 < 5 < 10 < 25 < 50 < No size limit and a lower rank than the saved one is "smaller"
+      And choosing a smaller size, including a size when there was none, sends nothing and shows the warning "Events over {n} GB will be removed" with "This happens at the next cleanup on {date}. It can't be undone.", "Apply {n} GB" and "Cancel"; choosing a larger size or "No size limit" saves at once
+      And each select sends only its own key, both share one status area, one error alert and one pending warning, and a warning concerns one control at a time: a longer or larger choice on either control drops it and another shortening replaces it
+      And the visual states are "Default, 90 days or 5 GB", "Age only (no size limit)", "Size only (forever)", the shortening warning with a 5 GB limit, Forever and Save error
+
+    Scenario Outline: Settings API, GET reports the size limit and the measured size
+      Given the saved retention is <days> days with a size limit of <gb> GB and the activity table holds <bytes> bytes of payload
+      When a verified user sends GET /v1/settings at the server time 2026-10-06T10:00:00+02:00
+      Then the status is 200 and the body has exactly the seven keys
+      And "activity_retention_max_gb" is <gb> and "activity_log_size_bytes" is <bytes>
+      And "activity_next_cleanup_at" is <next>
+
+      Examples:
+        | days | gb | bytes      | next                        |
+        | 90   | 0  | 0          | "2026-10-07T03:00:00+02:00" |
+        | 90   | 5  | 3435973837 | "2026-10-07T03:00:00+02:00" |
+        | 0    | 5  | 3435973837 | "2026-10-07T03:00:00+02:00" |
+        | 0    | 0  | 1024       | null                        |
+
+    Scenario: Settings API, a fresh install defaults to no size limit
+      Given no settings row exists
+      When a verified user sends GET /v1/settings
+      Then activity_retention_days is 90, activity_retention_max_gb is 0 and activity_log_size_bytes is 0
+
+    Scenario Outline: Settings API, PATCH saves a size limit, an age, or both
+      Given the saved retention is 90 days and no size limit and the user is the owner
+      When the owner sends PATCH /v1/settings with <body>
+      Then the status is 200 and the body has activity_retention_days <days>, activity_retention_max_gb <gb> and activity_next_cleanup_at <next>
+      And the repository holds <days> and <gb>
+
+      Examples:
+        | body                                                           | days | gb | next                       |
+        | {"activity_retention_max_gb": 5}                               | 90   | 5  | the next 03:00 server time |
+        | {"activity_retention_days": 0, "activity_retention_max_gb": 5} | 0    | 5  | the next 03:00 server time |
+        | {"activity_retention_days": 30}                                | 30   | 0  | the next 03:00 server time |
+        | {"activity_retention_days": 0}                                 | 0    | 0  | null                       |
+
+    Scenario: Settings API, leaving the size limit while Forever clears the schedule
+      Given the saved retention is 0 days with a size limit of 5 GB
+      When the owner sends PATCH /v1/settings with {"activity_retention_max_gb": 0}
+      Then activity_next_cleanup_at is null
+
+    Scenario Outline: Settings API, PATCH rejects invalid size input
+      Given the saved retention is 90 days with a size limit of 5 GB
+      When the owner sends PATCH /v1/settings with <body>
+      Then the status is 400 with the text of apperr.BodyErrorMessage and nothing is saved
+
+      Examples:
+        | body                                                            |
+        | {"activity_retention_max_gb": 2}                                |
+        | {"activity_retention_max_gb": -1}                               |
+        | {"activity_retention_max_gb": 100}                              |
+        | {"activity_retention_max_gb": 5.5}                              |
+        | {"activity_retention_max_gb": "5"}                              |
+        | {"activity_retention_max_gb": null}                             |
+        | {"activity_retention_days": 30, "activity_retention_max_gb": 2} |
+        | {}                                                              |
+
+    Scenario: Settings API, a PATCH changing nothing is a no-op
+      Given the saved retention is 90 days and 5 GB
+      When the owner sends PATCH /v1/settings with {"activity_retention_days": 90, "activity_retention_max_gb": 5}
+      Then the status is 200, nothing is saved and no audit event is recorded
+
+    Scenario: Settings API, a non-owner cannot set the size limit
+      When an admin sends PATCH /v1/settings with {"activity_retention_max_gb": 5}
+      Then the status is 403 with "Only the owner can do this." and nothing is saved
+
+    Scenario: Settings API, a failing size measurement answers 500
+      Given SizeBytes fails
+      When a verified user sends GET /v1/settings
+      Then the status is 500 with the generic internal error text
+
+    Scenario Outline: Settings API, the change is audited
+      Given the saved retention is 90 days and no size limit
+      When the owner sends PATCH /v1/settings with <body>
+      Then one event "system.activity_retention_changed" exists with params <params>
+
+      Examples:
+        | body                                                            | params                                                   |
+        | {"activity_retention_days": 30}                                 | {"from": 90, "to": 30}                                   |
+        | {"activity_retention_max_gb": 5}                                | {"max_gb_from": 0, "max_gb_to": 5}                       |
+        | {"activity_retention_days": 30, "activity_retention_max_gb": 5} | {"from": 90, "to": 30, "max_gb_from": 0, "max_gb_to": 5} |
+
+    Scenario Outline: Cleanup, the size limit removes the oldest events
+      Given the retention is <days> days, the size limit is 5 GB and the log is 7 GB
+      And the oldest events are older than the guard
+      When the cleanup runs at 2026-10-06T03:00:00
+      Then events are removed oldest first, by created_at then id, until SizeBytes is at or under 5 GB
+      And the removed count is the total of the age removals and the size removals
+      And the last cleanup time is the clock's time
+
+      Examples:
+        | days |
+        | 90   |
+        | 0    |
+
+    Scenario: Cleanup, age first then size
+      Given the retention is 30 days, the size limit is 5 GB, 100 events are older than 30 days and the log still exceeds 5 GB after they go
+      When the cleanup runs
+      Then the 100 events go first, then the oldest remaining events until the log is at or under 5 GB
+
+    Scenario: Cleanup, the age limit alone is enough
+      Given the log is under the size limit after the age removal
+      When the cleanup runs
+      Then no size removal happens
+
+    Scenario: Cleanup, Forever with no size limit never runs
+      Given the retention is 0 days and no size limit
+      When Tick runs at 2026-10-06T03:00:00
+      Then ran is false and neither DeleteOlderThan nor DeleteOldest is called
+
+    Scenario: Cleanup, the last 24 hours are protected even when the size cannot be met
+      Given the size limit is 1 GB and the log is 4 GB, all of it from the last 24 hours
+      When the cleanup runs
+      Then nothing is removed, no error is returned, the last cleanup records 0 removed and the next tick tries again
+
+    Scenario: Cleanup, a failing size removal is retried
+      Given DeleteOldest fails
+      When Tick runs
+      Then the error is returned and logged, the last cleanup fields are unchanged and the next tick runs again
+
+    Scenario: Cleanup, a size removal records one system event
+      Given the age step removed 10 events and the size step removed 40
+      When the cleanup runs
+      Then one "system.activity_cleanup" event exists with params {"removed": 50}
+
+    Scenario: Persistence measures the table payload portably
+      Given a real in-memory SQLite database and events with known text lengths, one with a multi-byte name
+      Then SizeBytes equals the sum of the byte lengths of the text columns plus the fixed per-row overhead
+      And it is 0 for an empty table
+      And deleting events lowers it
+
+    Scenario: Persistence deletes the oldest events up to a limit and a guard
+      Given 10 events, 3 of them newer than the guard
+      When DeleteOldest runs with limit 5
+      Then the 5 oldest events are removed
+      When DeleteOldest runs with limit 20
+      Then only the 2 remaining events older than the guard are removed and the 3 newest stay
+
+    Scenario: Settings retention, Default with 90 days or 5 GB
+      Given the role is "owner" and GET /v1/settings resolves 200 with activity_retention_days 90, activity_retention_max_gb 5 and activity_log_size_bytes 3435973837
+      When the owner navigates to /settings
+      Then the age select shows "90 days" with the helper "Events older than this are removed."
+      And an "or" divider and "Keep at most" show "5 GB" with the helper "When logs pass 5 GB, the oldest events are removed. Currently 3.2 GB."
+      And the lock alert reads "Events can't be edited or deleted from the app. Only the retention limits remove them."
+      And "Next cleanup" shows the date from activity_next_cleanup_at
+
+    Scenario: Settings retention, Age only (no size limit)
+      Given activity_retention_max_gb is 0
+      When the owner navigates to /settings
+      Then the size select reads "No size limit" with the helper "Optional. Logs can grow without a size cap." and the age helper is "Older events are removed automatically."
+
+    Scenario: Settings retention, Size only (forever)
+      Given activity_retention_days is 0, activity_retention_max_gb is 5 and activity_next_cleanup_at is set
+      When the owner navigates to /settings
+      Then the age helper reads "No age limit. Only the size limit applies." and "Next cleanup" shows the date, not "Not scheduled"
+
+    Scenario: Settings retention, Forever with no size limit
+      Given activity_retention_days is 0, activity_retention_max_gb is 0 and activity_next_cleanup_at is null
+      When the owner navigates to /settings
+      Then the age helper reads "Nothing is removed automatically. The log grows over time." and "Next cleanup" reads "Not scheduled"
+
+    Scenario Outline: Settings retention, the measured size is formatted
+      Given the size limit is 5 GB and activity_log_size_bytes is <bytes>
+      When the owner navigates to /settings
+      Then the size helper ends with "<shown>"
+
+      Examples:
+        | bytes      | shown                       |
+        | 3435973837 | Currently 3.2 GB.           |
+        | 0          | Currently Less than 0.1 GB. |
+        | 53687091   | Currently Less than 0.1 GB. |
+        | 5368709120 | Currently 5.0 GB.           |
+
+    Scenario Outline: Settings retention, a larger size or no limit saves at once
+      Given the saved size is <from>
+      When the owner chooses "<to>"
+      Then PATCH is sent once with {"activity_retention_max_gb": <value>}, never the age key, and no warning shows
+      And the shared status reads "Saving…" then "Saved"
+
+      Examples:
+        | from | to            | value |
+        | 5 GB | 10 GB         | 10    |
+        | 5 GB | No size limit | 0     |
+        | 1 GB | 50 GB         | 50    |
+
+    Scenario Outline: Settings retention, a smaller size asks first
+      Given the saved size is <from>
+      When the owner chooses "<to>"
+      Then no PATCH is sent and the size select shows "<to>"
+      And a warning alert shows "Events over <n> GB will be removed" and "This happens at the next cleanup on 7 Oct 2026, 03:00. It can't be undone." with "Apply <n> GB" and "Cancel"
+
+      Examples:
+        | from          | to   | n |
+        | 10 GB         | 5 GB | 5 |
+        | No size limit | 5 GB | 5 |
+        | 50 GB         | 1 GB | 1 |
+
+    Scenario: Settings retention, Apply and Cancel for a smaller size
+      Given the warning for 5 GB is shown on a saved 10 GB
+      When the owner activates "Apply 5 GB" and PATCH resolves 200 with activity_retention_max_gb 5
+      Then PATCH was sent once with {"activity_retention_max_gb": 5} and "Saved" shows
+      Given the warning is shown again
+      When the owner activates "Cancel"
+      Then the size select reads the saved value and no PATCH was sent
+
+    Scenario: Settings retention, only one warning at a time
+      Given the age warning for 30 days is open
+      When the owner chooses "5 GB" as a smaller size
+      Then the age warning is replaced by the size warning and the age select reverts to the saved value
+      When the owner chooses a longer age or a larger size
+      Then the warning is dropped and PATCH is sent once for that control
+
+    Scenario: Settings retention, switching age to Forever with a size limit
+      Given the saved period is 90 days and 5 GB
+      When the owner chooses "Forever"
+      Then PATCH is sent with {"activity_retention_days": 0} and the age helper becomes "No age limit. Only the size limit applies."
+      And "Next cleanup" still shows the returned date
+
+    Scenario Outline: Settings retention, a size save error reverts only the size select
+      Given the saved size is 5 GB and the owner chooses "10 GB"
+      When PATCH /v1/settings <failure>
+      Then the error alert "Couldn't save the retention period" with "Your previous setting is still in place." and "Try again" shows
+      And the size select reads "5 GB" again and the age select is unchanged
+      When the owner activates "Try again" and PATCH resolves 200
+      Then PATCH was sent a second time with {"activity_retention_max_gb": 10} and "Saved" replaces the alert
+
+      Examples:
+        | failure                      |
+        | resolves with a 500 response |
+        | resolves with a 400 response |
+        | resolves with a 403 response |
+        | never reaches the server     |
+
+    Scenario: Settings retention, offline disables the size select too
+      Given the owner is on /settings and the browser goes offline
+      Then both selects, "Apply" and "Cancel" are disabled
+
+    Scenario: The French interface covers the size strings
+      Given the language is French
+      Then every new string has a French entry in messages.ts, and the Activity sentence for a size change is French

features/activity_home_card_and_retention.qa.md

@@ -0,0 +1,122 @@
+# QA: Recent activity card on Home and Retention card on Settings
+
+## Implementation note for coder (informational, not a QA assertion)
+
+- Backend: add NextCleanupAt (nullable time) to the audit settings entity with a domain method computing the next 03:00 (audit.CleanupHour) strictly after a given time, in that time's location; nil when RetentionDays is audit.ForeverRetentionDays. GetActivityRetentionUseCase and UpdateActivityRetentionUseCase get an injected `now func() time.Time` (wired in api/dependecyInjection.go) and populate it. settingsResponse in api/handlers/settings gains `activity_next_cleanup_at` (`*time.Time`, RFC 3339, null when nil). No logic in the handler, none in the SPA.
+- Home: HomeView mounts a RecentActivityCard calling GET /v1/activity?size=5 once, reusing ActivityActor, ActivitySentence and lib/activityTime.
+- Settings: widen WorkspaceSettings with the four activity_* fields, add a PATCH helper to useSettings, render RetentionCard after MediaCleanupCard for session.role === 'owner' only. No second GET /v1/settings.
+- features/settings_page.feature and its qa.md say the body is exactly {"version"}; this feature supersedes that statement, so update those tests to the new five-key body.
+
+## Automated, Go (httptest, in-memory fakes, `task test`)
+
+Build `settings.NewHandler(GetSettingsUseCase, GetActivityRetentionUseCase, UpdateActivityRetentionUseCase)` over a fake audit.SettingsRepository (records saved retention and last cleanup) and a fake audit.Recorder, with a fixed fake clock. Mount on a fresh chi.NewRouter mirroring NewSettingsRouter: GET "/" behind jwtauth.Verifier + Authenticator (test jwtauth.New("HS256", ...)); PATCH "/" additionally behind the owner check using a fake user repository holding an owner, an admin and an editor. Call validator.InitValidator() first. No live server, no SQLite file. Fake type names must be unique across test files.
+
+- G1. GET table (clock in a +02:00 zone): retention 90 at 10:00 gives next = next day 03:00+02:00; at 02:59:59 gives same day 03:00; at exactly 03:00:00 gives next day 03:00; 30 at 2026-12-31T23:30 gives 2027-01-01T03:00; 365 at 10:00 gives next day; retention 0 gives JSON null (assert the key is present with value null, not absent).
+- G2. GET body has exactly the five keys (decode into map[string]any, assert the key set); last cleanup 2026-10-06T01:00:00Z and 142 preserved.
+- G3. GET is 200 for owner, admin and editor tokens; 401 without a cookie.
+- G4. PATCH owner 90->30: 200, activity_retention_days 30, next cleanup non-null at the next 03:00; the fake repository holds 30; one audit event with params from 90, to 30.
+- G5. PATCH owner 90->0: 200, next null. PATCH 0->365: next non-null.
+- G6. PATCH owner 90->90: 200, next non-null, no repository save, no audit event.
+- G7. Ownership: PATCH as admin and as editor: 403 with "Only the owner can do this."; repository unchanged; no audit event. PATCH without a cookie: 401.
+- G8. Invalid: {"activity_retention_days": 7}, "30" (string), {}, malformed JSON: each 400 with the apperr.BodyErrorMessage text (plain text via http.Error), repository unchanged.
+- G9. Use-case level (no HTTP): GetActivityRetention returns NextCleanupAt per G1 rows; UpdateActivityRetention(7) returns an error satisfying errors.Is(err, audit.ErrInvalidRetention) and saves nothing; a repository Get error propagates and the handler answers 500 "Internal server error".
+- G10. Domain: NextCleanupAt table including a DST-change day in a named zone (for example Europe/Paris, 2026-10-25), asserting it is still 03:00 local on the right date.
+
+## Automated, SPA (Vitest + Vue Test Utils, `task test:web`)
+
+Suggested files: web/src/views/__tests__/HomeActivityCard.spec.ts and SettingsRetention.spec.ts. Mock useApi per case; no real backend. Freeze the clock with vi.setSystemTime only where a time label is asserted (these specs are not visual).
+
+Home (mount HomeView with a resolved session; GET /v1/article/ mocked with the 6-article fixture):
+
+1. Owner and admin: 5 events, title "Recent activity", "View all" links to /activity; row 1 text with semibold target, "Marta Alves · 2 min ago", avatar "MA"; the activity mock was called once with exactly size=5 and no other parameter; /summary and /export never called.
+2. Regular user (editor, absent role): "Your recent activity"; meta lines are time only; no actor parameter.
+3. Marker table over outcome x security (no badge and no shield, Failed badge, shield only, badge only).
+4. Time label table (2 min ago, 3 h ago, "Yesterday, 14:20", "3 Oct 2026, 14:20") with fixed time; the title attribute holds the full local time.
+5. Clamp class on a 150-character title; unknown action "article.archive" renders the code; auth.login_failed sentence with Failed badge and user-round-x avatar.
+6. Rows are inert: clicking one changes no route and opens nothing.
+7. Skeleton only after 150 ms (fake timers): none before, 5 skeleton rows and aria-busy after, replaced on resolve; a fast response never shows one.
+8. Error table (500, 403, network): role="alert", title "Couldn't load recent activity", no description, "Try again"; stat tiles, article list and "Connect your website" still rendered; retry sends a second GET and recovers.
+9. Empty: both copies by role; "View all" still present.
+10. Independence in both directions (articles 500 + activity 200; articles [] + activity 500).
+11. "View all" navigates to /activity (test router).
+12. Layout classes: grid with the lg two-column template and the 420 px column, and no max-width class on the Home wrapper or the grid (the grid spans the full content width); DOM order puts the card first below lg (real pixels are manual).
+13. Existing home specs (HomeView, HomeUpdateBanner, HomeUpdateReady) keep passing with the activity mock added to the shared mount helper.
+
+Settings (mount SettingsView, GET /v1/settings mocked with the five-key body):
+
+14. Hidden for admin, editor and absent role; GET /v1/settings called once.
+15. Owner Default: header, "90 days", helper, lock alert, "Last cleanup 6 Oct 2026, 03:00 · 142 events removed", "Next cleanup 7 Oct 2026, 03:00" (from activity_next_cleanup_at; the SPA computes nothing); no PATCH; "1 event removed" singular.
+16. last_cleanup_at null: "Never". Forever with null/null: "Never" and "Not scheduled". Forever with a past cleanup: the real last line and "Not scheduled".
+17. Skeleton after 150 ms with aria-busy; load error alert and "Try again" re-runs the shared GET.
+18. Longer periods (90->365, 30->90, 90->Forever): one PATCH with {"activity_retention_days": N}, "Saving…" then "Saved", gone after 2 s (fake timers), no warning; the returned next cleanup replaces the line; a Forever response with next null shows "Not scheduled".
+19. Shortening: no PATCH, warning copy with the date taken from the loaded activity_next_cleanup_at; Apply sends once; Cancel reverts the select with no PATCH; table Forever->365, 365->90, 90->90 (no-op), 30->Forever (immediate); a longer choice while the warning is open drops it and leaves no stale warning after 30 days then 365 days again.
+20. Save error x (500, 400, 403, network): alert copy, select reverts, lines unchanged; Try again re-sends the same value without re-confirming; success shows "Saved"; error after Apply also clears the warning; a 403 triggers a session refresh and the card disappears when the role is no longer owner.
+21. Offline (mock useOnline false): select, Apply and Cancel disabled; nothing sent; page offline banner text unchanged.
+22. 401 handled globally: no local alert.
+23. French key parity: every new string has a messages.ts entry.
+24. Keyboard: the select opens with Enter or Space, arrows and Enter choose, Escape closes; Apply then Cancel reachable in order after the select.
+25. Existing SettingsView, SettingsMediaCleanup and Settings update specs keep passing with the widened mock body.
+
+## Visual (task visual:check)
+
+- Neither card can be pixel-compared (dashed placeholders); no new visual state is added. The card sub-states are not `###` headings in home.md or settings.md, so the tool should not iterate them; confirm on the first run.
+- Existing Home states and owner-session Settings states must still pass at 10 % with the card present. Every Home setup in web/visual/states.ts needs GET /v1/activity?size=5 mocked (an unmocked /v1 call fails the gate), and every owner Settings setup needs the widened GET /v1/settings body. Layout changes may exceed the gate: measure first, then ask the user for a per-state `exception` (needs approvedBy). Do not add any exception beforehand.
+- Time-dependent states stay `skip: 'clock-sensitive'`; no Vitest spec freezes the date for a visual claim.
+
+## Manual verification
+
+- [ ] Real GET /v1/settings and PATCH /v1/settings against `task dev` with a live SQLite file: five keys, next cleanup at the next 03:00 server time, null after switching to Forever, a timestamp after leaving Forever; as an admin PATCH is 403, as the owner a bad value is 400.
+- [ ] Browser in a time zone different from the server's: the "Next cleanup" and "Last cleanup" lines both show the user's local time of the same instants; the warning date matches the "Next cleanup" line.
+- [ ] Real daily cleanup (or a forced run) updates "Last cleanup" and moves "Next cleanup" a day forward.
+- [ ] Real GET /v1/activity?size=5 as owner, admin and editor (server-side own-event scoping), including a site with only events older than 7 days (reads "No activity yet").
+- [ ] Home at 1440 and 390 px, light and dark: 420 px column in the far-right of the full content width, 16 px gap, row clamping, "View all" 44 px touch target; the article column fills the remaining width and still reads well.
+- [ ] Keyboard and focus: Home tab order "New article", article rows, "View all"; Settings select, Apply, Cancel in order and focus back on the select after Cancel.
+- [ ] Hover, focus rings, the 2 s "Saved" fade and reduced motion.
+
+## Retention size limit extension
+
+Spec: rule "Retention size limit" in activity_home_card_and_retention.feature. Items 14 to 25 above are updated for the widened mock body (activity_retention_max_gb, activity_log_size_bytes) and the new helper and alert copy.
+
+Implementation note for coder (informational, not a QA assertion):
+- audit.Settings gains RetentionMaxGB; the settings use case result carries LogSizeBytes from audit.Repository.SizeBytes.
+- audit.SizeOptions() is [0, 1, 5, 10, 25, 50]; invalid values return ErrInvalidRetention.
+- audit.Repository gains SizeBytes() (int64, error) and DeleteOldest(limit int, before time.Time) (int, error).
+- audit.SettingsRepository.SaveRetention takes days and max_gb; the model and mapper gain retention_max_gb.
+- The cleanup use case runs the age step when days > 0, then loops DeleteOldest batches with SizeBytes until the log fits or a batch removes 0; the cutoff is the 24 h guard.
+- The handler request struct is a partial with pointer fields and validate tags; an empty object is rejected.
+- settingsResponse gains activity_retention_max_gb and activity_log_size_bytes. Update the settings_page tests that count keys.
+
+### Go (httptest, fakes)
+- G11. GET key set is exactly the seven keys; max_gb and size_bytes carry the fake's values; a fresh fake gives 90, 0, 0.
+- G12. GET next-cleanup table: (90, 0), (90, 5), (0, 5) are non-null; (0, 0) is JSON null with the key present.
+- G13. PATCH table: size alone, age alone, both, Forever plus size, size 0 with Forever (next becomes null); the fake repository holds the pair.
+- G14. PATCH invalid: sizes 2, -1, 100, 5.5, "5", null, mixed with a valid age, {}, not JSON; each 400 with the BodyErrorMessage text and nothing saved. Non-owner 403, no cookie 401.
+- G15. No-op PATCH of both saved values: 200, no save, no event.
+- G16. Audit params table for the three bodies (age, size, both).
+- G17. Cleanup use case with a fake events repository that has a size model: age then size, Forever plus size, Forever with no size (ran=false, no calls), size already met (no DeleteOldest), the guard stops at 24 h with 0 removed and no error, DeleteOldest error propagates and leaves the last cleanup unchanged, total removed in the event params and in SaveLastCleanup, the batch loop terminates when a batch removes 0.
+- G18. CleanupDue table unchanged; Tick runs for Forever when a size limit is set.
+- G19. Domain: SizeOptions validation; next-cleanup is nil only when both are 0.
+- G20. Persistence on in-memory SQLite (extend test/activity_persistence_test.go): SizeBytes with multi-byte text, the empty table, after delete; DeleteOldest with the limit and the guard; the migrated model has retention_max_gb defaulting to 0.
+- G21. The interface-shape test is updated to the six methods.
+- G22. A SizeBytes error propagates and the handler answers 500 "Internal server error".
+
+### SPA (Vitest), extending web/src/views/__tests__/SettingsRetention.spec.ts
+- 26. Default 90 days or 5 GB; Age only; Size only (forever); Forever without a size: selects, helpers, "Currently 3.2 GB.", the "or" divider, the lines.
+- 27. Size formatting table (3.2, "Less than 0.1 GB", 5.0); 1024^3 base.
+- 28. Larger size or No size limit: one PATCH with only the size key, "Saving…" then "Saved" (fake timers).
+- 29. Smaller size, and a size when none was set: no PATCH, warning copy, Apply sends one PATCH, Cancel reverts.
+- 30. One warning at a time; a longer or larger choice drops it.
+- 31. Save errors (500, 400, 403, network): only the size select reverts; Try again re-sends the same body without re-confirming; 403 refreshes the session and the card disappears.
+- 32. Offline disables both selects and Apply and Cancel; 401 is global.
+- 33. French parity for the new strings; lib/activitySentence.spec.ts covers the size-change sentence in English and French.
+
+### Visual (task visual:check)
+The board draws the card in group "Settings: Retention" with the states 'Age only (no size limit)' and 'Size only (forever)'. In settings.md the states are bullets, not headings, so confirm on the first run whether the tool iterates them. Setups use the board's own sample data (5 GB, 3.2 GB) and the owner /v1/settings mock gets the widened body. Clock-sensitive states stay skip: 'clock-sensitive'. No exception beforehand.
+
+### Manual verification
+- [ ] Real SQLite file: activity_log_size_bytes grows as events are added and falls after a forced cleanup.
+- [ ] Forced cleanup with a small limit removes the oldest events and leaves the last 24 h.
+- [ ] Optional: SizeBytes on real MySQL and PostgreSQL.
+- [ ] Real PATCH as owner for each option, as admin 403, as owner with 2 GB 400.
+- [ ] Keyboard order: age select, size select, Apply, Cancel; focus returns to the triggering select after Cancel.
+- [ ] 1440 and 390 px, light and dark: the "or" divider and the 160 px or full-width size select as drawn in the board.

features/activity_screen.feature

@@ -0,0 +1,693 @@
+Feature: Activity screen, details slide-over and My activity
+
+  As a verified RenewCMS user
+  I want /activity to read as a plain-language timeline of who did what and when, with filters,
+    a summary strip, CSV export and a details panel for each event
+  So that an owner can audit the site without reading a log, and any other role sees its own history
+
+  Background:
+    Given /activity is a verified route (meta.auth "verified", meta.title "Activity") rendered as
+      ActivityView (views/ActivityView.vue, the "ActivityPage" of docs/design/components.md) inside
+      DashboardShell, per docs/design/routes.md and docs/design/screens/activity.md
+    And the activity API already exists (features/activity-log-backend.feature and
+      features/activity-log-producers.feature) and this slice wires the SPA to it unchanged, with
+      no Go change
+    And the Home card and the Settings "Retention" card of the same board are not in this slice
+    And where docs/design prose and the board frame ActivityFrame.dc.html differ, the frame is
+      followed
+    And the views read the session role from GET /v1/auth/me: "owner" and "admin" are the full
+      view; any other or absent value is the regular-user view ("My activity"), which no real
+      account can reach today and is covered by Vitest and one visual state only
+    And a full view loads, in parallel, GET /v1/activity?range=7d&page=1&size=25 and GET
+      /v1/activity/summary?range=7d; a regular-user view loads only GET /v1/activity with the same
+      query and never calls /summary or /export, and never sends an actor parameter
+    And the list query always sends range, page and size explicitly, and adds q, actor, category,
+      outcome, security, from and to only when set (outcome "all" is not sent, from and to only
+      with range=custom); the summary query sends only range, from and to; the export query sends
+      the list query without page and size
+    And filters and the page live in component state, not in the URL, and reset when the user
+      leaves /activity
+    And useApi's global handling covers 401 and the unverified 403
+      (features/api_client_global_error_handling.feature); this screen maps every other failure
+    And DashboardShell's navigation gains "Activity" (icon i-lucide-history, linking to /activity)
+      between "Users" and "Integration", in the sidebar and in the mobile drawer, so it lists Home,
+      Articles, Media, Users, Activity, Integration, Settings in that order, for every verified
+      user; "Activity" has aria-current="page" on /activity; the specs that list the destinations
+      are amended accordingly (named in the QA file)
+    And the PageHeader breadcrumb and the mobile title read the page title: "Activity", or
+      "My activity" for the regular-user view
+    And the page padding is 24 px on desktop and 16 px on mobile with a 16 px gap between the
+      header, the strip, the filter bar, the chips, the table and the pager
+    And the header is the title "Activity" (regular user: "My activity") with the subtitle "Who
+      did what, and when, across your site." (regular user: "Everything you've done on this
+      site."), and, in the full view except Forbidden, an outline button with icon download and
+      the label "Export CSV" at the right, aligned to the bottom of the title block
+    And sentences are composed in the SPA from the event's action code, its outcome, its params
+      and its target name through the existing i18n (English keys, French in messages.ts), never
+      stored as text; the target name is user content, is inserted untranslated as a semibold
+      segment, and is the last slot of every template, so a missing target name drops the slot
+      with its leading space and colon
+    And the success sentences are, in English and French (the actor sits in its own column, so
+      sentences start with the verb; {0} is the target name):
+      | action                                  | English                                                             | French                                                                  |
+      | article.create                          | Created the article {0}                                             | Article créé : {0}                                                      |
+      | article.edit                            | Edited the article {0}                                              | Article modifié : {0}                                                   |
+      | article.publish                         | Published the article {0}                                           | Article publié : {0}                                                    |
+      | article.unpublish                       | Unpublished the article {0}                                         | Article dépublié : {0}                                                  |
+      | article.delete                          | Deleted the article {0}                                             | Article supprimé : {0}                                                  |
+      | media.upload                            | Uploaded the image {0}                                              | Image téléversée : {0}                                                  |
+      | media.rename                            | Renamed the image {0}                                               | Image renommée : {0}                                                    |
+      | media.delete                            | Deleted the image {0}                                               | Image supprimée : {0}                                                   |
+      | media.merge                             | Merged duplicates into the image {0}                                | Doublons fusionnés dans l'image {0}                                     |
+      | media.purge                             | Purged duplicate images: {0} merged, {1} articles updated           | Doublons purgés : {0} fusionnés, {1} articles mis à jour                |
+      | system.media_purge                      | Ran the scheduled duplicate purge: {0} merged, {1} articles updated | Purge automatique des doublons : {0} fusionnés, {1} articles mis à jour |
+      | user.register                           | Registered the account {0}                                          | Compte créé : {0}                                                       |
+      | user.verify                             | Verified the account {0}                                            | Compte vérifié : {0}                                                    |
+      | user.update_profile                     | Updated the profile of {0}                                          | Profil mis à jour : {0}                                                 |
+      | invite.create                           | Invited {0}                                                         | Invitation envoyée à {0}                                                |
+      | invite.cancel                           | Cancelled the invite for {0}                                        | Invitation annulée : {0}                                                |
+      | invite.renew                            | Renewed the invite for {0}                                          | Invitation renouvelée : {0}                                             |
+      | invite.accept                           | Accepted the invite for {0}                                         | Invitation acceptée : {0}                                               |
+      | api_key.create                          | Created API key {0}                                                 | Clé d'API créée : {0}                                                   |
+      | api_key.revoke                          | Revoked API key {0}                                                 | Clé d'API révoquée : {0}                                                |
+      | auth.login                              | Logged in                                                           | Connexion                                                               |
+      | auth.logout                             | Logged out                                                          | Déconnexion                                                             |
+      | auth.password_reset_requested           | Requested a password reset                                          | Réinitialisation du mot de passe demandée                               |
+      | auth.password_reset_completed           | Reset the password                                                  | Mot de passe réinitialisé                                               |
+      | system.update_checked                   | Checked for updates                                                 | Recherche de mises à jour                                               |
+      | system.update_downloaded                | Downloaded the update {0}                                           | Mise à jour téléchargée : {0}                                           |
+      | system.restart_requested (kind restart) | Requested a restart                                                 | Redémarrage demandé                                                     |
+      | system.restart_requested (kind update)  | Restarted to apply the update {0}                                   | Redémarrage pour appliquer la mise à jour {0}                           |
+      | system.activity_retention_changed       | Changed the activity retention from {0} to {1}                      | Durée de conservation de l'activité modifiée : {0} → {1}                |
+      | system.activity_cleanup                 | Removed {0} old events from the activity log                        | {0} anciens événements supprimés du journal d'activité                  |
+    And the failed sentences, used when outcome is "failed", are:
+      | action                   | English                                       | French                                            |
+      | article.create           | Failed to create the article {0}              | Échec de la création de l'article {0}             |
+      | article.edit             | Failed to edit the article {0}                | Échec de la modification de l'article {0}         |
+      | article.publish          | Failed to publish the article {0}             | Échec de la publication de l'article {0}          |
+      | article.unpublish        | Failed to unpublish the article {0}           | Échec de la dépublication de l'article {0}        |
+      | article.delete           | Failed to delete the article {0}              | Échec de la suppression de l'article {0}          |
+      | media.upload             | Failed to upload the image {0}                | Échec du téléversement de l'image {0}             |
+      | media.rename             | Failed to rename the image {0}                | Échec du renommage de l'image {0}                 |
+      | media.delete             | Failed to delete the image {0}                | Échec de la suppression de l'image {0}            |
+      | media.merge              | Failed to merge duplicates into the image {0} | Échec de la fusion des doublons dans l'image {0}  |
+      | media.purge              | Failed to purge duplicate images              | Échec de la purge des doublons                    |
+      | system.media_purge       | Failed to run the scheduled duplicate purge   | Échec de la purge automatique des doublons        |
+      | user.register            | Failed to register the account {0}            | Échec de la création du compte {0}                |
+      | user.verify              | Failed to verify the account {0}              | Échec de la vérification du compte {0}            |
+      | user.update_profile      | Failed to update the profile of {0}           | Échec de la mise à jour du profil de {0}          |
+      | invite.create            | Failed to invite {0}                          | Échec de l'invitation de {0}                      |
+      | invite.cancel            | Failed to cancel the invite for {0}           | Échec de l'annulation de l'invitation de {0}      |
+      | invite.renew             | Failed to renew the invite for {0}            | Échec du renouvellement de l'invitation de {0}    |
+      | invite.accept            | Failed to accept the invite for {0}           | Échec de l'acceptation de l'invitation de {0}     |
+      | api_key.create           | Failed to create API key {0}                  | Échec de la création de la clé d'API {0}          |
+      | api_key.revoke           | Failed to revoke API key {0}                  | Échec de la révocation de la clé d'API {0}        |
+      | auth.login_failed        | Failed login attempt for {0}                  | Échec de connexion pour {0}                       |
+      | system.update_checked    | Failed to check for updates                   | Échec de la recherche de mises à jour             |
+      | system.update_downloaded | Failed to download the update {0}             | Échec du téléchargement de la mise à jour {0}     |
+      | system.restart_requested | Failed to restart                             | Échec du redémarrage                              |
+    And an action whose failed sentence is not listed (for example auth.login) renders its success
+      sentence with the Failed badge; an action code that is not in the catalogue renders the raw
+      code (for example "article.archive") and never throws
+    And for auth.login_failed the slot {0} is the actor's name (the attempted username, since the
+      event has no target), while the Actor column reads "Not signed in"
+    And counts in params are shown with the locale's number format; "{0} old events" and "{1}
+      articles updated" use the singular form for 1 ("1 old event", "1 article updated"); a
+      media.purge or system.media_purge event with params.failed_groups appends ", {2} groups
+      failed" ("1 group failed") in English and ", {2} groupes en échec" in French;
+      system.activity_retention_changed shows days as "{n} days" and 0 as "Forever" ("{n} jours",
+      "Toujours")
+    And the category icons are: articles file-text, media image, users users, api_keys key-round,
+      auth shield-check, system server-cog; the category labels are Articles, Media, Users and
+      invites, API keys, Authentication, System
+    And the Actor cell is the actor's name with: a UAvatar of initials (first letters of the first
+      two words, upper case) for type "user"; a key-round icon avatar and an "API key" badge for
+      "api_key"; a cog icon avatar and a "System" badge for "system"; a user-round-x icon avatar
+      and the text "Not signed in" for "anonymous"
+    And the Target cell is "—" (muted) when target is null; when target.exists it is the name as an
+      underlined link with an arrow-up-right icon, plus the target type as a muted second line
+      (Article, Image, User, Invite, API key, Release); when it does not exist the name is struck
+      through, muted, with a "Deleted" badge (icon trash-2) and the type line; the link goes to
+      /article/{id}/edit for article, /media for image, /users for user and invite,
+      /integration/api-keys for api_key, and a target type with no page (release) is plain text
+    And the Outcome cell is a badge with icon and word, never colour alone: "Succeeded" (check,
+      bordered) or "Failed" (circle-x, --rc-error-soft background, --ui-error text)
+    And a row whose event has security true shows a shield-alert icon in --ui-warning after the
+      sentence and a 2 px inset --ui-warning edge on its left side; on mobile it also shows a
+      "Security" badge (shield-alert, --rc-warning-soft, --ui-warning)
+    And the table (md and up) has the columns When, Actor, Action, Target, Outcome in a grid
+      96px 210px minmax(0,1fr) 230px 120px (regular user: When, Action, Target, Outcome in 96px
+      minmax(0,1fr) 230px 120px), a 36 px header on --ui-bg-elevated with an arrow-down icon on
+      When, day separator rows of 32 px on --ui-bg-muted with the label in 12 px semibold, and
+      rows at least 52 px high with a top border; a selected row (details open) and a hovered row
+      use --ui-bg-elevated
+    And rows are grouped by the user's local calendar day under a separator labelled "Today",
+      "Yesterday" or the date as "3 Oct 2026" (French "3 oct. 2026"), in the order the API
+      returns them (newest first); the When cell shows the time as drawn, relative within today
+      ("2 min ago", "29 min ago", "1 h ago") and the local clock time "HH:mm" on earlier days,
+      and carries the full local time "3 Oct 2026, 14:20:05" as its title attribute
+    And below md the table is replaced by a stacked list of cards (ActivityCardList) with the same
+      separators: a first line with the actor (avatar, name, badge; hidden for the regular user)
+      and the time at the right, the category icon and the sentence (15 px, up to 3 lines), then a
+      line of badges: the Outcome badge, "Security" when flagged, and "Target deleted" when the
+      target is gone; each card is at least 44 px high as a touch target
+    And rows and cards are focusable, open the details on click and on Enter, and a click on the
+      target link navigates to the target without opening the details
+    And the summary strip (ActivitySummaryStrip, full view only) has four cards that are real
+      buttons: "Total actions", "Active people", "Failed actions", "Security events", each with
+      the number (locale-formatted), a sub-line, and a seven-bar sparkline of seven div bars,
+      4 px wide, 2 px apart, oldest at the left, bar height round(value / max(series, 1) * H)
+      with a 2 px minimum and H of 20 px on desktop and 16 px on mobile, drawn from
+      series.total, series.active, series.failed and series.security
+    And on desktop the strip is a 4-column grid with a 12 px gap; below md it is, as drawn in
+      ActivityFrame.dc.html, a single row of 156 px cards with an 8 px gap that is clipped at the
+      page edge
+    And the Total sub-line is "{pct}% vs previous 7 days" with icon trending-up when total is at
+      least previous_total and trending-down otherwise, pct being the rounded absolute change
+      against previous_total; for the ranges Today, 30 days and Custom the words read "vs previous
+      day", "vs previous 30 days" and "vs previous period"; when previous_total is 0 the sub-line
+      is "No earlier data" and when the two totals are equal it is "No change", both without an
+      icon (French "Aucune donnée antérieure", "Aucun changement")
+    And the Active people number is active_people.users plus active_people.api_keys with the
+      sub-line "{users} people, {api_keys} API keys" ("1 person", "1 API key")
+    And the Failed sub-line is "{pct}% of all actions" (one decimal, "0.5%") with icon circle-x
+      and the --rc-error-soft background and --ui-error number
+    And the Security sub-line is "{n} flagged" (French "{n} signalés", "1 signalé"), n being
+      summary.security, with icon shield-alert and the --rc-warning-soft background and
+      --ui-warning number
+    And a Failed or Security count of 0 reads "0" with "Nothing failed" or "Nothing to flag" and
+      icon circle-check in --ui-success, drops the emphasis fill and draws its bars in
+      --ui-border-accented; with total 0 Total and Active people read "0" with "No data yet"
+    And the strip follows only the date range; q, person, category, outcome and security never
+      change it, and it is not requested again when they change
+    And when the summary request fails with any status or never reaches the server, the strip is
+      not rendered and nothing is shown in its place
+    And the filter bar (ActivityFilterBar) has: a UInput (icon search, clearable, placeholder
+      "Search activity", 240 px) that applies 300 ms after the last keystroke or at once on Enter;
+      a Person USelectMenu (icon user-round, "All people", 168 px, full view only) with the groups
+      users, API keys and "System"; a Category USelectMenu (icon layout-list, "All categories",
+      176 px); an Outcome button group "All / Succeeded / Failed" (soft is the selected one,
+      outline the others); and the date presets "Today / 7 days / 30 days / Custom" (Custom has
+      icon calendar and opens a date-range popover) at the right; controls are 32 px high
+    And the Person options come from GET /v1/user/ (accepted users, shown by display name or
+      username) and GET /v1/api-key/, requested once, the first time the Person menu opens, so a
+      page load makes no other call than the two above
+    And choosing a Person sends actor=user:{id}, actor=key:{id} or actor=system; a Category sends
+      category=articles|media|users|api_keys|auth|system; Outcome Succeeded sends outcome=success
+      and Failed outcome=failed; Today, 7 days and 30 days send range=today|7d|30d; Custom sends
+      range=custom&from=YYYY-MM-DD&to=YYYY-MM-DD once both dates are chosen; any filter change
+      resets the page to 1 and sends a new list request, and the page size is kept
+    And the active filter chips (UBadge subtle with a trailing ghost x button) read "Search:
+      spring", "Person: Marta Alves", "Category: Authentication", "Outcome: Failed", "Security
+      events", "Dates: 30 days" or "Dates: 1 – 30 Sep 2026" (same month "1 – 30 Sep 2026", across
+      months "28 Sep – 3 Oct 2026"), followed by a link button "Clear all"; the default range 7
+      days is never a chip; removing a chip resets that filter; "Clear all" resets every filter to
+      the default (range 7d)
+    And below md the bar is a search field and a "Filters" button (icon sliders-horizontal) with a
+      count badge (the number of chips, hidden at 0); it opens a bottom sheet titled "Filters"
+      with Person (full view only), Category, Outcome, Dates (two date fields when Custom is
+      chosen) and a footer "Clear all" (disabled at 0 filters) and "Show {total} results" ("Show 1
+      result"); the sheet applies each change at once, so the footer count is the current total,
+      and "Show … results" closes the sheet
+    And the pager (full width under the table) reads "Showing {from}–{to} of {total}" with
+      locale-formatted numbers, a UPagination (previous, 1, 2, 3, …, last, next; previous
+      disabled on page 1), and "Rows per page" with a select of 25, 50 and 100; changing the size
+      resets the page to 1; below md it reads "Page {page} of {pages}" above "{from}–{to} of
+      {total}", with previous and next buttons and the size select
+    And while a list request is in flight for longer than 150 ms, 9 skeleton rows (desktop) or 5
+      skeleton cards (below md) replace the rows and the pager is hidden; the strip shows 4
+      skeleton cards while the summary request is in flight for longer than 150 ms; nothing is
+      drawn in their place for the first 150 ms
+    And the list is "empty" when total is 0: with no chip it is "No activity yet" (icon history,
+      "Actions on articles, media, users and API keys will appear here.", regular user: "Your
+      actions will appear here once you start working on the site."), with at least one chip it is
+      "No activity matches these filters" (icon search-x, action "Clear filters")
+    And the error, empty and forbidden panels are drawn as in ActivityFrame.dc.html: "Couldn't
+      load activity" is an error alert with icon circle-x, the text and an outline "Try again"
+      button, and "You can't view this activity" (no trailing period) uses icon lock and the
+      action "Back to home"
+    And "Export CSV" is disabled in "No activity yet" and while the list is in the Error state,
+      and enabled otherwise
+    And ActivityDetailsPanel is a USlideover: 480 px wide from the right on desktop, an 88 %-high
+      bottom sheet with a 36×4 px handle below md; its header reads "Activity details" with a
+      close button (and "{position} of {total}" below md); it opens from a row or card, closes
+      with Escape, the close button or the scrim, and focus returns to the row that opened it
+    And the panel body has, in this order: the full sentence (18 px semibold, target in semibold)
+      with the Outcome badge, a "Security" badge when flagged and the category icon and label; an
+      error alert "Why it failed" with failure_reason, only when outcome is "failed" and the
+      reason is present; the grid When, Actor, Source, IP address, Browser; a Target section;
+      a Changes section
+    And When shows the local time as "6 Oct 2026, 10:42:18 (your time)" and under it, muted, the
+      UTC time as "6 Oct 2026, 10:42:18 UTC"; Actor is the avatar, the name and the same badges
+      as the table; Source is "Web app" for web, "API key" for api_key and "System task" for
+      system; IP address (IBM Plex Mono 12 px) and Browser read "Not applicable" (muted) when ip
+      or user_agent is null
+    And the Target section shows the name (a link with arrow-up-right when it exists, otherwise
+      struck through with a "Deleted" badge and the line "This item was deleted. Its name is kept
+      for reference."), and the line "{type} · {id}"; it is absent when target is null
+    And the Changes section (ActivityDiff) is absent when changes is empty; each change is a row
+      headed by its field label: a "text" change shows Before and After boxes (side by side with
+      an arrow-right on desktop, stacked with an arrow-down below md), a "body" change shows only
+      the line "Body edited (+312 characters)" with icon file-pen-line ("-48", "+1 character")
+      and never any text
+    And the field labels are title "Title", online "Publish state", body "Body", filename "File
+      name", display_name "Display name" (French "Titre", "État de publication", "Corps", "Nom du
+      fichier", "Nom d'affichage"), an unknown field shows its raw code, and for online the
+      values "false" and "true" read "Draft" and "Published" ("Brouillon", "Publié")
+    And a Before or After value taller than two lines is clamped to two lines and a "Show more"
+      link button appears under that row; it toggles to "Show less"; shorter values show no toggle
+    And the panel footer has "Previous event" (icon chevron-up) and "Next event" (icon
+      chevron-down) buttons that move through the current filtered list, and on desktop the
+      muted text "Event {position} of {total}" with position = (page − 1) × size + index + 1;
+      below md the two buttons are full width and there is no footer text
+    And when Previous or Next crosses a page boundary the list page follows, and a failed request
+      for the neighbour page keeps the panel on the current event with no message
+
+  Scenario: Navigation — "Activity" sits between Users and Integration
+    Given the user is on /activity
+    When DashboardShell mounts
+    Then the sidebar and the mobile drawer list Home, Articles, Media, Users, Activity,
+      Integration, Settings in that order
+    And "Activity" has the history icon, links to /activity and has aria-current="page"
+    And the breadcrumb reads "Activity" (mobile title "Activity")
+
+  Scenario: Default — an owner sees the strip, the filter bar and a day-grouped table
+    Given GET /v1/activity resolves 200 with 25 items and total 1284, and GET /v1/activity/summary
+      resolves 200 with total 1284, previous_total 1146, active_people {users 7, api_keys 2},
+      failed 6, security 11 and seven-day series, and the session role is "owner"
+    When the user navigates to /activity
+    Then the header shows "Activity", "Who did what, and when, across your site." and an enabled
+      "Export CSV"
+    And the strip reads "1,284" "12% vs previous 7 days" with trending-up; "9" "7 people, 2 API
+      keys"; "6" "0.5% of all actions"; "11" "11 flagged"
+    And the filter bar shows "Search activity", "All people", "All categories", All selected in
+      the Outcome group, and 7 days selected, with no chip
+    And the table rows follow the API order under day separators
+    And the pager reads "Showing 1–25 of 1,284" and "Rows per page" 25
+    And GET /v1/activity was requested once with range=7d, page=1, size=25 and no other
+      parameter, and GET /v1/activity/summary once with range=7d
+
+  Scenario Outline: Rows — the Actor cell and the sentence follow the event
+    Given a row for an event with actor type "<type>" named "<name>", action "<action>", outcome
+      "<outcome>" and security <security>
+    Then the Actor cell shows <actor>
+    And the Action cell shows "<sentence>" with the target name in semibold, and <marker>
+    And the Outcome cell shows "<badge>"
+
+    Examples:
+      | type      | name             | action             | outcome | security | actor                                 | sentence                                                        | marker                | badge     |
+      | user      | Marta Alves      | article.publish    | success | false    | an avatar "MA" and "Marta Alves"      | Published the article Spring release                            | no shield             | Succeeded |
+      | api_key   | Website sync     | media.upload       | success | false    | a key icon, "Website sync", "API key" | Uploaded the image north-wall.jpg                               | no shield             | Succeeded |
+      | system    | System           | system.media_purge | success | false    | a cog icon, "System", "System"        | Ran the scheduled duplicate purge: 3 merged, 5 articles updated | no shield            | Succeeded |
+      | anonymous | alex@example.com | auth.login_failed  | failed  | true     | a user-round-x icon, "Not signed in"  | Failed login attempt for alex@example.com                       | a shield-alert marker | Failed    |
+      | user      | Inès Duarte      | article.publish    | failed  | false    | an avatar "ID" and "Inès Duarte"      | Failed to publish the article Spring release                    | no shield             | Failed    |
+      | user      | Jonas Weber      | api_key.revoke     | success | true     | an avatar "JW" and "Jonas Weber"      | Revoked API key Mobile app                                      | a shield-alert marker | Succeeded |
+
+  Scenario: Rows — a deleted target is struck through, a living one is a link
+    Given an event of target {"type": "image", "id": "9", "name": "old-banner.png", "exists": false}
+      and an event of target {"type": "article", "id": "8", "name": "Spring release", "exists": true}
+    Then the first Target cell shows "old-banner.png" struck through with a "Deleted" badge and
+      "Image"
+    And the second Target cell shows "Spring release" as a link to /article/8/edit and "Article"
+    And clicking that link navigates to /article/8/edit and does not open the details
+
+  Scenario: Rows — an event with no target shows a dash
+    Given an event whose target is null
+    Then its Target cell shows a muted "—"
+
+  Scenario: Rows — an unknown action code renders the code
+    Given an event with action "article.archive"
+    Then its Action cell shows "article.archive" and the row still opens the details
+
+  Scenario Outline: Sentences — English and French come from the same code and params
+    Given an event with action "<action>", outcome "<outcome>", params <params> and target
+      "<target>"
+    When the language is <language>
+    Then the sentence reads "<sentence>" with "<target>" untranslated
+
+    Examples:
+      | action                            | outcome | params                                                   | target         | language | sentence                                                              |
+      | article.publish                   | success | {}                                                       | Spring release | English  | Published the article Spring release                                  |
+      | article.publish                   | success | {}                                                       | Spring release | French   | Article publié : Spring release                                       |
+      | article.publish                   | failed  | {}                                                       | Spring release | French   | Échec de la publication de l'article Spring release                   |
+      | media.purge                       | success | {"merged": 3, "articles_updated": 5}                     |                | English  | Purged duplicate images: 3 merged, 5 articles updated                 |
+      | media.purge                       | success | {"merged": 3, "articles_updated": 5, "failed_groups": 1} |                | English  | Purged duplicate images: 3 merged, 5 articles updated, 1 group failed |
+      | system.activity_cleanup           | success | {"removed": 1}                                           |                | English  | Removed 1 old event from the activity log                             |
+      | system.activity_retention_changed | success | {"from": 90, "to": 0}                                    |                | English  | Changed the activity retention from 90 days to Forever                |
+      | system.restart_requested          | success | {"kind": "update", "tag": "v1.4.0"}                      | v1.4.0         | English  | Restarted to apply the update v1.4.0                                  |
+      | media.upload                      | failed  | {}                                                       |                | English  | Failed to upload the image                                            |
+
+  Scenario: Loading — skeletons after 150 ms while both requests are in flight
+    Given GET /v1/activity and GET /v1/activity/summary have not resolved
+    When the user navigates to /activity
+    Then the header, the filter bar and an enabled "Export CSV" are drawn at once
+    And nothing is drawn in place of the strip and the table for the first 150 ms
+    And after 150 ms 4 skeleton cards replace the strip and 9 skeleton rows (5 cards below md)
+      replace the table, the pager is hidden and the table container is aria-busy="true"
+    When both requests resolve 200 with the Default data
+    Then the skeletons are replaced by the Default state's strip, rows and pager
+
+  Scenario: Zero-value summary strip — a quiet period shows a calm 0
+    Given GET /v1/activity/summary resolves 200 with total 214, previous_total 223, active_people
+      {users 4, api_keys 1}, failed 0, security 0 and series of zeros for failed and security
+    And GET /v1/activity resolves 200 with 25 items
+    When the user navigates to /activity
+    Then the Total card reads "214" "4% vs previous 7 days" with trending-down
+    And the Active people card reads "5" "4 people, 1 API key"
+    And the Failed card reads "0" "Nothing failed" with circle-check and no error fill
+    And the Security card reads "0" "Nothing to flag" with circle-check and no warning fill
+    And their bars are 2 px high
+
+  Scenario Outline: The Total sub-line when there is nothing to compare
+    Given GET /v1/activity/summary resolves 200 with total <total> and previous_total <previous>
+    When the user navigates to /activity
+    Then the Total card reads "<total>" and "<subline>" without a trend icon
+
+    Examples:
+      | total | previous | subline        |
+      | 40    | 0        | No earlier data |
+      | 40    | 40       | No change      |
+
+  Scenario: Empty, no activity yet — a new site
+    Given GET /v1/activity resolves 200 with items [] and total 0, and GET /v1/activity/summary
+      resolves 200 with every number 0
+    And no filter chip is shown
+    When the user navigates to /activity
+    Then the strip reads "0" "No data yet" for Total and Active people, "0" "Nothing failed" and
+      "0" "Nothing to flag"
+    And an empty panel with icon history shows "No activity yet" and "Actions on articles,
+      media, users and API keys will appear here."
+    And "Export CSV" is disabled and no table header or pager is shown
+
+  Scenario: Empty, filters match nothing — the panel offers Clear filters
+    Given the Default state has loaded
+    When the user types "sitemap" in Search, chooses Category "Media" and Outcome "Failed", and
+      GET /v1/activity resolves 200 with items [] and total 0
+    Then the chips read "Search: sitemap", "Category: Media", "Outcome: Failed" and "Clear all"
+    And an empty panel with icon search-x shows "No activity matches these filters" and "Try a
+      different search or a wider date range." with the action "Clear filters"
+    And "Export CSV" stays enabled and the strip is unchanged
+    When the user activates "Clear filters"
+    Then every filter is reset, GET /v1/activity is sent with range=7d, page=1, size=25 only and
+      the rows come back
+
+  Scenario Outline: Error with retry — a 500, a 400 or a network failure replaces the table
+    Given GET /v1/activity <failure> and GET /v1/activity/summary resolves 200
+    When the user navigates to /activity
+    Then the strip and the filter bar are shown
+    And an error alert shows "Couldn't load activity" and "Check your connection and try again."
+      with the action "Try again"
+    And "Export CSV" is disabled and no table or pager is shown
+    When the user activates "Try again"
+    Then the Loading state shows for the list and GET /v1/activity is sent again with the same
+      query
+    When it then resolves 200 with the Default data
+    Then the Default rows replace the alert
+
+    Examples:
+      | failure                      |
+      | resolves with a 500 response |
+      | resolves with a 400 response |
+      | never reaches the server     |
+
+  Scenario Outline: The summary alone fails — the strip is not drawn and the list still works
+    Given GET /v1/activity resolves 200 with the Default items and GET /v1/activity/summary
+      <failure>
+    When the user navigates to /activity
+    Then the strip is not rendered, with no error shown for it
+    And the filter bar, the rows and the pager are shown as in Default
+
+    Examples:
+      | failure                      |
+      | resolves with a 500 response |
+      | resolves with a 403 response |
+      | never reaches the server     |
+
+  Scenario: Forbidden (403) — the page itself is refused
+    Given GET /v1/activity resolves 403 and GET /v1/auth/me resolves 200 with a verified user
+    When the user navigates to /activity
+    Then the header shows "Activity" and no "Export CSV"
+    And no strip, filter bar, chips, table or pager is shown
+    And an empty panel with icon lock shows "You can't view this activity" and "Your role
+      doesn't include this page. Ask an owner or admin if you need access." with the action "Back
+      to home"
+    When the user activates "Back to home"
+    Then the router navigates to /home
+
+  Scenario: An unverified 403 and a 401 are handled globally
+    Given GET /v1/activity resolves 401 (or 403 for an unverified session)
+    When the user navigates to /activity
+    Then useApi redirects to /login?redirect=/activity&reason=expired (or to /register/pending)
+    And no Forbidden or Error panel is shown
+
+  Scenario Outline: Strip cards — each card applies its filter
+    Given the Default state has loaded with the 7 days range
+    When the user activates the "<card>" card
+    Then <effect>
+    And <state>
+
+    Examples:
+      | card            | effect                                                             | state                                                                                                              |
+      | Total actions   | every filter is cleared and GET /v1/activity is sent with range=7d | no card is marked active                                                                                           |
+      | Active people   | nothing changes and no request is sent                             | no card is marked active                                                                                           |
+      | Failed actions  | GET /v1/activity is sent with outcome=failed and the page 1        | the chip "Outcome: Failed" and "Clear all" appear and the card has aria-pressed="true" with a --ui-primary border |
+      | Security events | GET /v1/activity is sent with security=true and the page 1         | the chip "Security events" and "Clear all" appear and the card has aria-pressed="true" with a --ui-primary border |
+
+  Scenario: Filtered, card applied — the Failed card on top of other filters
+    Given the user has chosen Category "Authentication" and 30 days
+    When the user activates the "Failed actions" card and GET /v1/activity resolves 200 with 1
+      item and total 6
+    Then the chips read "Category: Authentication", "Outcome: Failed", "Dates: 30 days" and
+      "Clear all"
+    And GET /v1/activity/summary was requested for range=30d and is not requested again
+    And the pager reads "Showing 1–6 of 6"
+    And below md the "Filters" button shows the count badge "3"
+
+  Scenario Outline: Filter bar — each control sends its query parameter and resets the page
+    Given the user is on page 3 of the Default list
+    When <action>
+    Then GET /v1/activity is sent with <query>, page=1 and size=25
+
+    Examples:
+      | action                                             | query                       |
+      | the user types "spring" and waits 300 ms           | q=spring and range=7d       |
+      | the user types "spring" and presses Enter at once  | q=spring and range=7d       |
+      | the user chooses Person "Marta Alves" (user 3)     | actor=user:3 and range=7d   |
+      | the user chooses Person "Website sync" (API key 7) | actor=key:7 and range=7d    |
+      | the user chooses Person "System"                   | actor=system and range=7d   |
+      | the user chooses Category "Users and invites"      | category=users and range=7d |
+      | the user chooses Outcome "Succeeded"               | outcome=success and range=7d |
+      | the user chooses "Today"                           | range=today                 |
+      | the user chooses "30 days"                         | range=30d                   |
+
+  Scenario: Filter bar — Custom opens a date-range popover and applies on the second date
+    Given the Default state has loaded
+    When the user chooses "Custom" and picks 1 Sep 2026 then 30 Sep 2026 in the popover
+    Then GET /v1/activity and GET /v1/activity/summary are sent with range=custom, from=2026-09-01
+      and to=2026-09-30
+    And the chip reads "Dates: 1 – 30 Sep 2026"
+    And no request is sent after the first date alone
+
+  Scenario: Chips — removing one resets only that filter, Clear all resets everything
+    Given the chips "Search: spring", "Outcome: Failed" and "Dates: 30 days" are shown
+    When the user activates the x of "Outcome: Failed"
+    Then GET /v1/activity is sent with q=spring and range=30d and without outcome
+    When the user activates "Clear all"
+    Then GET /v1/activity is sent with range=7d only, and the summary is requested for range=7d
+    And no chip and no "Clear all" is shown
+
+  Scenario: The Person menu loads its options once, on first open
+    Given the Default state has loaded
+    Then GET /v1/user/ and GET /v1/api-key/ have not been requested
+    When the user opens the Person menu
+    Then both are requested once and the menu lists the users, then the API keys, then "System"
+    And opening it again does not request them again
+
+  Scenario: Pagination — next page, page size and totals
+    Given the Default state has loaded with total 1284
+    When the user activates page "2" of the pager
+    Then GET /v1/activity is sent with page=2 and size=25 and the pager reads "Showing 26–50 of
+      1,284"
+    When the user chooses "50" in "Rows per page"
+    Then GET /v1/activity is sent with page=1 and size=50 and the pager reads "Showing 1–50 of
+      1,284"
+    And on the last page 52 of size 25 the pager reads "Showing 1,276–1,284 of 1,284" and next is
+      disabled
+
+  Scenario: Mobile — the list is cards and the controls collapse into a sheet
+    Given the Default state has loaded below md with the filters Category "Authentication" and
+      Outcome "Failed" applied and GET /v1/activity resolves with total 6
+    Then the page shows the search field and "Filters" with the badge "2", and no Person,
+      Category, Outcome or date control
+    And the table is replaced by cards, each with its actor, time, sentence and badges
+    And the pager reads "Page 1 of 1" with "1–6 of 6"
+    When the user activates "Filters"
+    Then a bottom sheet titled "Filters" shows Person, Category, Outcome, Dates, "Clear all" and
+      "Show 6 results"
+    When the user chooses "Custom"
+    Then two date fields appear in the sheet
+    When the user activates "Show 6 results"
+    Then the sheet closes and the list stays filtered
+
+  Scenario: Export — the file is prepared, then downloads
+    Given the Default state has loaded with the filters Category "Authentication" and 30 days
+    When the user activates "Export CSV"
+    Then GET /v1/activity/export is sent with category=auth and range=30d and without page or size
+    And while it is in flight the button reads "Preparing file…" and is disabled
+    When it resolves 200 with a text/csv body
+    Then the file is downloaded as "activity.csv" and a toast appears: color success, icon
+      i-lucide-circle-check, title "Export started. Your file will download shortly."
+    And the button returns to "Export CSV", enabled
+
+  Scenario Outline: Export — a failure raises an error toast and re-enables the button
+    Given the Default state has loaded
+    When the user activates "Export CSV" and GET /v1/activity/export <failure>
+    Then a toast appears: color error, icon i-lucide-circle-x, title "Couldn't export activity.
+      Try again."
+    And nothing is downloaded and the button returns to "Export CSV", enabled
+
+    Examples:
+      | failure                      |
+      | resolves with a 500 response |
+      | resolves with a 403 response |
+      | never reaches the server     |
+
+  Scenario: Details — a row opens the slide-over and focus returns on close
+    Given the Default state has loaded
+    When the user activates the second row (click, or Enter with the row focused)
+    Then the slide-over opens with the title "Activity details", the row is marked selected and
+      the footer reads "Event 2 of 1,284"
+    When the user presses Escape (or activates the close button, or the scrim)
+    Then the slide-over closes and focus is on that row
+
+  Scenario: Details — the Edit with a diff event
+    Given the event "Why we reuse original floorboards" has action "article.edit" with changes
+      [{"field": "title", "kind": "text", "before": "Why we reuse floorboards", "after": "Why we
+      reuse original floorboards"}, {"field": "body", "kind": "body", "delta": 312}]
+    When its details open
+    Then the sentence reads "Edited the article Why we reuse original floorboards"
+    And the Changes section shows a "Title" row with Before "Why we reuse floorboards" and After
+      "Why we reuse original floorboards", then a "Body" row with "Body edited (+312 characters)"
+    And no body text appears anywhere in the panel
+
+  Scenario: Details — long values clamp to two lines with Show more
+    Given an event with a text change whose Before and After are 170-character values, and
+      another text change with short values
+    When its details open and the long values overflow two lines
+    Then the long row's values are clamped and "Show more" appears under that row only
+    When the user activates "Show more"
+    Then the values are fully shown and the link reads "Show less"
+
+  Scenario: Details — a failed action with a very long target title shows its reason
+    Given an event with action "article.publish", outcome "failed", failure_reason "The article
+      has no cover image. Add one, then publish again." and a 150-character target name
+    When its details open
+    Then the sentence wraps with the title in semibold, the "Failed" badge is shown and an error
+      alert "Why it failed" reads the reason
+    And the Target section wraps the long name
+
+  Scenario: Details — a deleted target has no diff
+    Given an event of action "media.delete" with target {"type": "image", "id": "9", "name":
+      "old-banner.png", "exists": false} and no changes
+    When its details open
+    Then the Target section shows "old-banner.png" struck through, a "Deleted" badge and "This
+      item was deleted. Its name is kept for reference."
+    And there is no Changes section
+
+  Scenario: Details — a system-initiated event has no human actor
+    Given an event with actor {"type": "system", "id": null, "name": "System"}, source "system",
+      ip null and user_agent null
+    When its details open
+    Then Actor shows the cog avatar, "System" and a "System" badge, Source reads "System task",
+      and IP address and Browser read "Not applicable"
+
+  Scenario: Details — a failed login shows the actor as not signed in
+    Given an event with action "auth.login_failed", actor {"type": "anonymous", "id": null,
+      "name": "alex@example.com"}, security true, outcome "failed", failure_reason "Wrong username
+      or password.", ip "198.51.100.77" and user_agent "Chrome 129 on Windows"
+    When its details open
+    Then the sentence reads "Failed login attempt for alex@example.com" with a "Security" badge
+      and a "Failed" badge
+    And Actor reads "Not signed in", the alert "Why it failed" shows the reason, and the IP
+      address and the Browser are shown
+
+  Scenario: Details — the times are shown in local time and in UTC
+    Given an event created_at "2026-10-06T10:42:18Z"
+    When its details open
+    Then the When line ends with "(your time)" and the muted line below reads "6 Oct 2026,
+      10:42:18 UTC"
+
+  Scenario Outline: Details — Source reads the event's source
+    Given an event with source "<source>"
+    When its details open
+    Then Source reads "<label>"
+
+    Examples:
+      | source  | label       |
+      | web     | Web app     |
+      | api_key | API key     |
+      | system  | System task |
+
+  Scenario: Details — Previous and Next move through the filtered list across pages
+    Given the list is on page 1 of size 25 with total 1284 and the first row's details are open
+    Then "Previous event" is disabled and the footer reads "Event 1 of 1,284"
+    When the user activates "Next event" 24 times
+    Then the footer reads "Event 25 of 1,284" with no extra request
+    When the user activates "Next event" once more
+    Then GET /v1/activity is sent with the same filters, page=2 and size=25
+    And the panel shows the first item of page 2, the footer reads "Event 26 of 1,284" and the
+      pager under the table reads "Showing 26–50 of 1,284"
+    When the user activates "Previous event"
+    Then GET /v1/activity is sent with page=1 and the panel shows the last item of page 1 as
+      "Event 25 of 1,284"
+    And on the last event "Next event" is disabled
+
+  Scenario: Details — a failed neighbour page keeps the panel on the current event
+    Given the last item of page 1 is open
+    When the user activates "Next event" and GET /v1/activity resolves 500
+    Then the panel still shows the same event, the button is enabled again and the list is
+      unchanged
+
+  Scenario: Details — below md the slide-over is a bottom sheet
+    Given the Default state has loaded below md
+    When the user activates the second card
+    Then a bottom sheet opens, 88 % high, with a handle, the title "Activity details", "2 of
+      1,284" in the header, and full-width "Previous event" and "Next event" buttons
+    And there is no "Event 2 of 1,284" footer text
+
+  Scenario: My activity — a role that is not owner or admin sees its own events
+    Given the session role is "editor" (or absent) and GET /v1/activity resolves 200 with 25
+      items and total 41
+    When the user navigates to /activity
+    Then the title reads "My activity", the subtitle "Everything you've done on this site." and
+      the breadcrumb "My activity"
+    And no summary strip, no Person filter and no "Export CSV" are rendered
+    And the table has the columns When, Action, Target, Outcome and no Actor column
+    And the cards show no actor line below md
+    And GET /v1/activity is sent with range=7d, page=1, size=25 and no actor parameter, and
+      GET /v1/activity/summary is never sent
+    And the pager reads "Showing 1–25 of 41"
+
+  Scenario: My activity, empty — the user has not done anything yet
+    Given the session role is "editor" and GET /v1/activity resolves 200 with items [] and total 0
+    When the user navigates to /activity
+    Then an empty panel with icon history shows "No activity yet" and "Your actions will appear
+      here once you start working on the site."
+
+  Scenario: My activity, details — the slide-over on one of the user's own events
+    Given the session role is "editor" and the Default list has loaded
+    When the first row's details open
+    Then the footer reads "Event 1 of 41", "Previous event" is disabled and the panel is the same
+      as for an owner, with the Actor row showing the user's own name
+
+  Scenario: The French interface composes sentences and chrome in French
+    Given the language is French and the Default state has loaded as owner
+    Then the title reads "Activité", the strip labels, filter placeholders, badges, pager and
+      "Exporter en CSV" are in French, the sentences use the French templates and day
+      separators read "Aujourd'hui", "Hier" or "3 oct. 2026"
+    And the Security sub-line reads "11 signalés"
+    And every new English string of this screen has a French entry in messages.ts
+
+  Scenario: Hover shows the exact time
+    Given the Default state has loaded
+    Then each When cell has a title attribute holding the full local time with seconds

features/activity_screen.qa.md

@@ -0,0 +1,257 @@
+# QA: Activity screen, details slide-over and My activity
+
+## Implementation note for coder (informational, not a QA assertion)
+
+The activity API is already built and covered by features/activity-log-backend.qa.md and
+features/activity-log-producers.qa.md: this slice has no Go change and no HTTP-level Go section.
+
+The shell specs that list the navigation are amended to seven destinations (Home, Articles, Media,
+Users, Activity, Integration, Settings): features/dashboard_shell_branding.feature,
+features/media_browse.feature, features/users_screen.feature and .qa.md,
+features/settings_page.feature and .qa.md, features/profile_page.feature. Their Vitest tests
+(DashboardShell.spec.ts, where Settings moves from index 5 to 6) must be updated in the same change.
+
+Export needs the response body as a file, which `useApi().request` does not return (it calls
+`response.json()`). Add a raw or blob read to `useApi` that keeps the global 401 handling, builds
+an object URL and clicks a temporary anchor with `download="activity.csv"`. The toasts use
+`useToast().add({ color, icon, title })` with the one sentence as the title.
+
+The page needs a date-range popover and a Custom date pair in the mobile sheet. The clamp ("Show
+more") is measured from the rendered element, so tests stub `scrollHeight` and `clientHeight`.
+
+Every new English string needs a French entry in `web/src/i18n/messages.ts`. Sentences are
+composed by a composable (`useActivitySentence`) that returns segments so the target name can be
+rendered semibold. The Security sub-line is "{n} flagged" with n = `summary.security`, French
+"{n} signalés".
+
+## Automated (Vitest + Vue Test Utils, `task test:web`)
+
+Mock `useApi`'s `request` (and the export transport) per case, matching on method, path and parsed
+query (`URLSearchParams`); no real backend. Mount ActivityView inside DashboardShell with a
+resolved verified session (id 2, username "ines", display_name "Inès Duarte", role "owner") and a
+test router at /activity; the regular-user cases use role "editor" (and one with no role). Run
+each layout case at a desktop and a below-md width (mock `matchMedia`, see
+`components/__tests__/viewport.ts`). Timers: use `vi.useFakeTimers({ toFake: ['setTimeout',
+'clearTimeout'] })` so the 150 ms skeleton delay and the 300 ms search debounce can be advanced
+while `Date` stays real. No test freezes or asserts the system date.
+
+Clock-independence rules for fixtures: every event in the Vitest fixtures is dated 3 Oct 2026 or
+earlier, created at 12:00 to 13:00 UTC so its local day is the same in any time zone from UTC-11
+to UTC+11; assert day separators with the absolute label "3 Oct 2026" and When cells only against
+the pattern `^\d{2}:\d{2}$` and a non-empty `title`; never assert "Today", "Yesterday" or a
+relative "N min ago". UTC lines can be asserted exactly; the local time line only with its
+"(your time)" suffix.
+
+Fixtures: `activityItems` (a 15-item list built from the board's events, mapped to the API shape
+with the action codes of the "Visual" section), `summaryDefault` (total 1284, previous_total
+1146, active_people {users 7, api_keys 2}, failed 6, security 11, series total [4,6,5,8,7,9,6],
+active [5,6,6,7,7,8,9], failed [0,1,0,2,1,0,2], security [1,0,2,1,3,2,2]), `summaryZero` (total
+214, previous_total 223, active_people {4, 1}, failed 0, security 0, series failed and security
+zeros) and `summaryNone` (all zeros). The list response is `{ items, total, page, size }`.
+
+1. **Navigation** — sidebar and drawer list Home, Articles, Media, Users, Activity, Integration,
+   Settings in order; "Activity" has the `i-lucide-history` icon, links to /activity, has
+   aria-current="page" on /activity and none elsewhere; breadcrumb and mobile title "Activity".
+2. **Default (owner)** — assert header texts, enabled "Export CSV", the four strip cards (labels,
+   "1,284", "9", "6", "11", sub-lines "12% vs previous 7 days" with the trending-up icon, "7
+   people, 2 API keys", "0.5% of all actions" with icon `circle-x`, "11 flagged" with icon
+   `shield-alert`), the filter bar (placeholder, "All people", "All categories", Outcome All
+   selected, 7 days selected), no chip, the pager text "Showing 1–25 of 1,284", and that `request`
+   was called exactly twice at mount with the expected queries (`range=7d&page=1&size=25` and
+   `range=7d`).
+3. **Rows, Examples-driven** — one fixture row per Examples row of the feature; assert the
+   Actor cell (initials, key or cog or user-round-x icon, badge, "Not signed in"), the sentence
+   text and that the target name is in a semibold element, the shield marker only on security
+   rows, and the Outcome badge word.
+4. **Target cell** — deleted (struck-through class, "Deleted" badge, type line), living (link
+   with `href` "/article/8/edit", "/media", "/users", "/integration/api-keys" per type, plain text
+   for "release"), and null ("—"); clicking the link navigates and does not open the details.
+5. **Day grouping and When cell** — fixture across 3 Oct and 2 Oct 2026; assert two separators
+   "3 Oct 2026" and "2 Oct 2026" in order, the When cell pattern and `title`.
+6. **Sentences, Examples-driven** — for each Examples row set the locale (`setLocale`), render
+   and assert the exact sentence, including plurals, `failed_groups`, "Forever", the dropped slot
+   for a missing target name, the unknown code `article.archive`, and the success sentence used
+   for an unlisted failed action (`auth.login` failed). Add a completeness test: every action in
+   the catalogue has an English and a French template, and every key used on the page exists in
+   `messages.ts`.
+7. **Loading** — unresolved requests; at 149 ms nothing in place of strip and table; at 150 ms 4
+   skeleton cards, 9 skeleton rows (5 cards below md), `aria-busy="true"`, no pager; resolve and
+   assert the Default content.
+8. **Zero-value strip** — `summaryZero`; assert "214" "4% vs previous 7 days" with the
+   trending-down icon, "5" "4 people, 1 API key", "0" "Nothing failed" and "0" "Nothing to flag"
+   with `circle-check`, no error or warning fill class, bars at 2 px.
+9. **Total sub-line without a comparison, Examples-driven** — previous_total 0 gives "No earlier
+   data" and equal totals give "No change", both without a trend icon; French "Aucune donnée
+   antérieure" and "Aucun changement"; ranges Today, 30 days and Custom give "vs previous day",
+   "vs previous 30 days" and "vs previous period".
+10. **Empty, no activity yet** — `summaryNone`, items []; assert "No data yet" on two cards, the
+    calm lines on the other two, the empty panel copy and icon, a disabled "Export CSV", no table
+    header and no pager.
+11. **Empty, filters match nothing** — type "sitemap", choose Category "Media" and Outcome
+    "Failed", resolve items []; assert chips, empty panel copy, "Clear filters", enabled export;
+    click "Clear filters" and assert a request with `range=7d&page=1&size=25` only.
+12. **Error, Examples-driven** — list rejects with `ApiError(500)`, `ApiError(400)`, then
+    `NetworkError`, summary resolves; assert the strip, the alert copy, "Try again", a disabled
+    export and no table; click "Try again"; assert the list request is repeated and the Default
+    rows replace the alert.
+13. **Summary alone fails** — summary rejects with `ApiError(500)`, `ApiError(403)`, then
+    `NetworkError`; assert the strip is absent, nothing is drawn in its place, and the list is
+    fully rendered.
+14. **Forbidden** — list rejects with `ApiError(403)` and a verified session; assert no export
+    button, no strip, no filter bar, the lock panel copy, and that "Back to home" navigates to
+    /home. Also `ApiError(401)` triggers the global redirect and no panel.
+15. **Strip cards, Examples-driven** — click each card; assert the effect and `aria-pressed`
+    (Failed: request with `outcome=failed&page=1`, chip "Outcome: Failed"; Security: request with
+    `security=true`, chip "Security events"; Total: filters cleared; Active people: no request)
+    and that the summary is not requested again.
+16. **Filtered, card applied** — Category "Authentication", 30 days, then the Failed card; assert
+    the chip texts and order, "Clear all", the summary requested only once for `range=30d`, the
+    pager "Showing 1–6 of 6", and below md the Filters badge "3".
+17. **Filter bar, Examples-driven** — for each Examples row assert the exact query, `page=1` after
+    starting on page 3, and the 300 ms debounce with fake timers (no request at 299 ms, one at
+    300 ms; Enter applies at once and the pending debounce does not send a second request).
+18. **Custom dates** — pick two dates in the popover (stub the calendar's model); assert no request
+    after the first date, then `range=custom&from=2026-09-01&to=2026-09-30` on the list and the
+    summary, and the chip "Dates: 1 – 30 Sep 2026"; also "28 Sep – 3 Oct 2026".
+19. **Chips** — remove one chip, then "Clear all"; assert the queries and that the summary is
+    requested again only when the range changes back.
+20. **Person options** — assert no `GET /v1/user/` or `GET /v1/api-key/` call at mount, both on
+    first open of the menu, none on the second; assert group order and the three query values.
+21. **Pagination** — next page, size 50, last page "Showing 1,276–1,284 of 1,284" with next
+    disabled; mobile "Page 1 of 52" and previous and next.
+22. **Mobile list and sheet** — below md assert cards (actor line, sentence, badges, "Target
+    deleted"), "Filters" with the badge count, the sheet content and footer ("Show 6 results", "Show
+    1 result"), two date fields for Custom, and that "Show … results" closes it.
+23. **Export success** — click "Export CSV" with filters applied; assert one request to
+    `/v1/activity/export` with the list filters and no `page` or `size`, "Preparing file…" and
+    disabled while pending, an object URL created and an anchor clicked with
+    `download="activity.csv"`, the success toast (color success, icon `i-lucide-circle-check`,
+    title "Export started. Your file will download shortly."), and the button back to "Export CSV".
+24. **Export failure, Examples-driven** — 500, 403 and `NetworkError`; assert the error toast
+    (color error, icon `i-lucide-circle-x`, title "Couldn't export activity. Try again."), no
+    download, button re-enabled.
+25. **Details open and close** — click, then Enter on a focused row; assert the title, the selected
+    row class, the footer "Event 2 of 1,284"; close with Escape, the close button and the scrim and
+    assert focus on the row.
+26. **Details content, Examples-driven** — the six board events: Edit with a diff (Title row with
+    both values and the "Body edited (+312 characters)" row, "(+1 character)", "(-48 characters)"),
+    long text (stub overflow; "Show more" on that row only, toggles to "Show less"), failed with a
+    long title (alert "Why it failed", wrapping), deleted target (struck-through name, "Deleted"
+    badge, explanation, no Changes), system event ("System" badge, "System task", two "Not
+    applicable"), failed login ("Not signed in", "Security" badge, reason, IP and Browser). Assert
+    the field labels and the Draft and Published values for `online`, the raw code for an unknown
+    field, and that no body text is ever rendered.
+27. **Details times** — `created_at` "2026-10-06T10:42:18Z": the UTC line is exactly "6 Oct 2026,
+    10:42:18 UTC" and the local line ends with "(your time)".
+28. **Previous and Next across pages** — first item: previous disabled, "Event 1 of 1,284"; 24
+    nexts without a request; the 25th next sends `page=2&size=25` with the same filters, shows
+    page 2's first item, "Event 26 of 1,284" and the pager "Showing 26–50 of 1,284"; previous
+    sends `page=1` and shows "Event 25 of 1,284"; the last event disables next; a 500 on the
+    neighbour page keeps the panel on the current event and re-enables the button; the position
+    also follows a non-default size (size 50, page 2, index 0 is "Event 51").
+29. **Details below md** — the bottom-sheet variant: header "2 of 1,284", full-width buttons, no
+    footer text.
+30. **My activity, Examples-driven** — role "editor" then no role: title, subtitle, breadcrumb "My
+    activity", no strip, no Person filter, no export, no Actor column or card actor line; assert no
+    request to `/summary` or `/export` and no `actor` parameter; pager "Showing 1–25 of 41"; empty
+    state copy; details "Event 1 of 41" with previous disabled.
+31. **French** — `setLocale('fr')`; assert the chrome strings (Activity "Activité", My activity
+    "Mon activité", Export CSV "Exporter en CSV", Preparing file… "Préparation du fichier…",
+    Total actions "Actions au total", Active people "Personnes actives", Failed actions "Actions
+    en échec", Security events "Événements de sécurité", Succeeded "Réussie", Failed "Échec", Not
+    signed in "Non connecté", Activity details "Détails de l'activité", Previous event and Next
+    event "Événement précédent" and "Événement suivant", "11 signalés"), the French sentences, the
+    plural and "Forever" ("Toujours") forms, and the day separator format.
+32. **Hover time** — each When cell has a `title` that is non-empty and contains seconds.
+
+## Visual (task visual:check -- activity, desktop and mobile, light and dark)
+
+Reference: `docs/design/screens/activity.md`, board `docs/design/source/RenewCMS Screens
+Activity.dc.html`, groups "Activity, owner and admin", "Details slide-over" and "My activity"
+(the last two are already declared as `extraSources` in `web/visual/check.ts`); exact values in
+`docs/design/source/ActivityFrame.dc.html`. Add each state to `visualStates.activity` in
+`web/visual/states.ts` with the board's own sample data. The gate is hard: every capture of every
+non-skipped state must be within 10 %, for both viewports and both themes (6 gated states, 24
+captures). No state uses the `now` option or a frozen clock. Mocks are keyed by method and path
+(`GET /v1/activity`, `GET /v1/activity/summary`, `GET /v1/auth/me`); use `bodyFor` to read the
+query. Do not mock or call `/v1/user/` or `/v1/api-key/` (Person options load only when the menu
+opens, which no state does), so there is no unmocked request.
+
+Sessions: add `activityOwnerSession` (id 2, display_name "Inès Duarte", role "owner") and
+`activityEditorSession` (id 3, display_name "Marta Alves", role "editor"), as the board draws them
+in its sidebar chip. The board draws a 4-item sidebar for the regular user as illustrative; the
+real shell keeps all 7 items, a known small difference in the My activity Empty capture.
+
+Fixtures (all taken from the frame's script): `activityBoardEvents`, the 15 events of the frame in
+its order, mapped to API items. Where the frame's sample has no real producer the nearest real
+code is used and the sentence differs from the board (accepted; those rows only appear in skipped
+states): 1 `article.publish`, 2 `article.edit` with title and body (+312) changes, 3
+`auth.login_failed` (anonymous, name "alex@example.com", reason from the frame), 4
+`api_key.revoke`, 5 `system.media_purge` (system, ip and user_agent null), 6 `invite.accept`
+(replaces "Changed the role"), 7 `media.upload` by the API key "Website sync", 8 `media.delete`
+(target not existing), 9 `article.publish` failed with the 150-character title, 10
+`system.activity_cleanup`, 11 `article.edit` with long title values (replaces the "Site
+description" setting diff), 12 `api_key.create`, 13 `user.update_profile`, 14 `media.upload`, 15
+`auth.password_reset_completed`; times are the frame's local times minus one hour as UTC
+(`created_at`), IPs and browsers as in the frame, security as in the frame. Summary fixtures are
+the three in the Automated section; the strip of the Default state is "1,284 / 9 / 6 / 11" with
+the sub-line "11 flagged". Total is 1284 with page size 25 for the owner and 41 for the editor.
+
+- [ ] Loading: both requests with `hang: true`; the setup waits 150 ms or more so the skeleton
+      strip and rows are drawn before the capture.
+- [ ] Empty, no activity yet: list `items: [], total: 0`, summary `summaryNone`; "Export CSV"
+      disabled.
+- [ ] Empty, filters match nothing: the board applies Search "sitemap", Category "Media", Outcome
+      "Failed" (steps type and select them, or the mock answers with the filtered query), list
+      `items: [], total: 0`, summary Default.
+- [ ] Error with retry: list 500, summary Default; the alert, disabled export, strip drawn.
+- [ ] Forbidden (403): list 403, summary 403; session with a non-admin role as the board does
+      (`role: 'user'`), so no "Export CSV".
+- [ ] My activity, Empty: `activityEditorSession`, list `items: [], total: 0`.
+- [ ] skip: clock-sensitive. Default, large dataset: `skip: 'clock-sensitive'` (day separators and
+      "2 min ago" depend on the real clock). Prints SKIP, never investigated or date-frozen.
+- [ ] skip: clock-sensitive. Zero-value summary strip, Filtered card applied and Mobile filters
+      sheet (all draw Today rows behind the strip or sheet).
+- [ ] skip: clock-sensitive. The six Details slide-over states (Edit with a diff, Settings diff
+      long text, Failed action very long target title, Deleted target no diff, System-initiated no
+      human actor, Security event failed login) and the My activity states Default and Details:
+      the rows behind the scrim show relative times and the panel shows the browser's local
+      time. Their Vitest coverage is cases 3, 5, 25 to 30.
+- [ ] Layout, from `ActivityFrame.dc.html`, not `components.md`: header row is the title block
+      (20 px/28 px title) on the left and the 32 px (44 px mobile) "Export CSV" button on the right,
+      aligned to the bottom; the strip is 4 columns with a 12 px gap on desktop and a clipped row
+      of 156 px cards with an 8 px gap on mobile; the table header is 36 px, day rows 32 px, rows at
+      least 52 px; the slide-over is 480 px wide on desktop, the bottom sheet 88 % high.
+- [ ] Error is drawn as the frame's alert (error soft background, circle-x, title, text, 28 px
+      outline "Try again"), the empty states as the frame's centred panel (44 px icon box, 15 px
+      semibold title, muted text up to 340 px).
+- [ ] Not covered by screenshots: keyboard and focus order (Tab reaches Export CSV, the strip
+      cards, the search, the selects, the groups, a row; Enter opens the details; focus is trapped
+      in the slide-over and returns to the row on close; Escape closes it); hover (the row, the
+      native `title` tooltip), the 240 ms slide-over and sheet motion and the skeleton pulse, all
+      stopped under reduced motion; the date-range popover.
+
+## Manual verification
+
+- **Real round trips against `task dev`** — Vitest only mocks `useApi`. As owner: perform an
+  article publish, an image upload and a failed login, then confirm they appear newest first with
+  the right sentences, the shield marker on the failed login, the Succeeded and Failed badges, the
+  summary numbers and the sparkline bars; apply each filter and each card; page through with size
+  25, 50 and 100; open the details across a page boundary.
+- **Real CSV** — click "Export CSV" with and without filters and open `activity.csv`: columns
+  `when,actor,action,target,outcome,source,ip`, the filtered rows only, no page or size applied,
+  neutralised cells that start with `=`, `+`, `-` or `@`; confirm the browser download prompt and
+  the two toasts.
+- **Admin session** — sign in as an admin: the same full view as the owner.
+- **Time zones** — set the OS time zone to UTC-8 and UTC+9, reload, and confirm the day
+  separators, the clock times, the "(your time)" line and the UTC line are consistent.
+- **Regular user** — no real account can reach "My activity" today; confirm by a mocked
+  `/v1/auth/me` in the browser (or a future role) that the view has no strip, no Person filter and
+  no export, and that the server answers 403 for `actor=user:2` and for the summary and export.
+- **API key** — calling `GET /v1/activity` with an API key answers 403 "This action needs a real
+  session." and the SPA never does it.
+- **"Today", "Yesterday" and relative times** — confirm them against the real clock, since
+  visual:check skips every state that shows them.
+- **French** — switch the language and read every state, the sentences and the toasts.
+- **Real screen readers and zoom** — row selection, the sparkline buttons (labelled by the card
+  text), the sheet focus trap.

features/api_keys.feature

@@ -0,0 +1,457 @@
+Feature: Developers authenticate against /v1 with named API keys instead of the jwt cookie
+
+  As a developer integrating with RenewCMS
+  I want to create named API keys and send them as a Bearer token
+  So that I can manage articles, media and users without the UI, with exactly the rights of the
+    user who created the key and never more
+
+  Background:
+    Given internal/domain/apikey defines the entity APIKey with ID uint32, UserID uint32, Name,
+      Prefix, HashedKey, ExpiresAt *time.Time, RevokedAt *time.Time, LastUsedAt *time.Time and
+      CreatedAt, with snake_case json tags
+    And internal/domain/apikey defines the sentinels apikey.ErrAPIKeyNotFound,
+      apikey.ErrAPIKeyInvalid and apikey.ErrExpiryNotInFuture
+    And apikey.ErrAPIKeyInvalid covers an unknown, malformed, expired or revoked key and a key
+      whose user is deleted or unverified
+    And internal/domain/apikey defines the interface Repository with Create, Get(id),
+      GetByHashedKey(hashedKey), ListByUser(userId), ListAll(), Revoke(id, at),
+      RevokeAllByUser(userId, at) and TouchLastUsed(id, at)
+    And RevokeAllByUser sets RevokedAt to at on every key of that user that is not yet revoked and
+      leaves the RevokedAt of already revoked keys and every other user's keys untouched
+    And internal/domain/apikey defines the interface KeyGenerator with Generate() returning the
+      raw key, its display prefix and its SHA-256 hash, and Hash(rawKey) returning the SHA-256 hash
+    And internal/infrastructure/hashing implements KeyGenerator, asserted with
+      var _ apikey.KeyGenerator = &SHA256KeyGenerator{}
+    And a generated raw key is "rcms_" followed by the base64url encoding, without padding, of 32
+      random bytes, so it matches ^rcms_[A-Za-z0-9_-]{43}$
+    And the display prefix is the first 12 characters of the raw key
+    And only the SHA-256 hash and the prefix are persisted, never the raw key
+    And the use cases CreateAPIKey, ListAPIKeys, RevokeAPIKey and AuthenticateAPIKey depend only
+      on apikey.Repository, apikey.KeyGenerator, user.Repository and an injected clock
+    And ResetPasswordUseCase additionally receives apikey.Repository and an injected clock, and
+      after a successful password reset calls RevokeAllByUser(userId, now); it never reaches
+      persistence directly
+    And persistence has a GORM model, a mapper and a repository for the entity, the model is
+      added to the AutoMigrate list in api/dependecyInjection.go, and wiring happens only in
+      api/dependecyInjection.go
+    And a new middleware resolves "Authorization: Bearer rcms_<...>" to a user and places a jwt in
+      the same jwtauth request context the cookie path fills, with the claims user_id and
+      token_version taken from the user's current record
+    And that middleware runs after jwtauth.Verifier and ahead of jwtauth.Authenticator on the
+      /article routes (public and protected), /user, /media, /settings and GET /auth/me
+    And jwtauth.Authenticator, RequireCurrentToken, RequireVerifiedUser, RequireOwner and every
+      handler stay unchanged
+    And a new middleware RequireSession, mounted ahead of jwtauth.Verifier, answers 403 with
+      apperr.SessionRequiredErrorMessage whenever the Authorization header is a Bearer token that
+      starts with "rcms_", whether that key is valid, expired, revoked, unknown or garbage
+    And RequireSession is mounted on the key management routes POST /v1/api-key, GET /v1/api-key
+      and DELETE /v1/api-key/{id}, on the session-only auth routes POST /v1/auth/verify and
+      DELETE /v1/auth/register, and on every /v1/system route (all under /v1/system/update)
+    And a request on those routes without a "Bearer rcms_" header passes through RequireSession
+      unchanged, so cookie-only and jwt-Bearer behaviour there does not change
+    And the public auth routes login, register, registration, logout, password-reset,
+      password-reset/confirm, invite and invite/accept do not use the key middleware or
+      RequireSession and behave exactly as they do without a key header
+    And the routes are mounted under /v1 inside the jwtauth.Verifier, jwtauth.Authenticator,
+      RequireCurrentToken and RequireVerifiedUser group:
+      POST /v1/api-key, GET /v1/api-key and DELETE /v1/api-key/{id}
+    And a Bearer key on a key-accepting route that cannot authenticate gets 401 with
+      apperr.UnauthorizedErrorMessage, and a request without an rcms_ key keeps the existing
+      jwtauth.Authenticator response, status 401, unchanged by this feature
+    And new apperr strings: APIKeyNotFoundErrorMessage = "API key not found",
+      APIKeyExpiryErrorMessage = "The expiry must be a date in the future." and
+      SessionRequiredErrorMessage = "This action needs a real session."
+    And the per-key rate limit is 120 requests per minute, as constants in api/router.go
+    And enableCorsIfConfigured allows the methods GET, POST, PUT, PATCH, DELETE and OPTIONS
+    And users: owner id 1 "marta" (verified), admin id 2 "dev" (verified), admin id 3 "pat"
+      (verified), unverified id 4 "quinn"
+
+  Scenario: Creating a key returns the full key exactly once
+    Given a valid jwt cookie for admin 2
+    When the client sends POST /v1/api-key with body {"name": "ci-deploy"}
+    Then the response status is 201
+    And the header Cache-Control is "no-store"
+    And the body has exactly the keys id, name, prefix, key, created_at, expires_at
+    And name is "ci-deploy", expires_at is null, and key matches ^rcms_[A-Za-z0-9_-]{43}$
+    And prefix equals the first 12 characters of key
+    And the stored record has user_id 2 and HashedKey equal to the SHA-256 of key
+    And neither the raw key nor the stored hash appears in any later response
+
+  Scenario: The key can't be retrieved afterwards
+    Given admin 2 created the key "ci-deploy" and holds its raw key
+    When the same jwt cookie sends GET /v1/api-key
+    Then the response status is 200
+    And the body is a JSON array with one entry whose keys are exactly id, user_id, name, prefix,
+      status, created_at, last_used_at, expires_at, revoked_at
+    And the entry has no "key" and no "hashed_key" field
+    And the raw key and its hash appear nowhere in the body
+    And the entry's prefix is the first 12 characters of the raw key
+
+  Scenario: Creating a key with an expiry
+    Given a valid jwt cookie for admin 2
+    When the client sends POST /v1/api-key with body
+      {"name": "temp", "expires_at": "<now + 30 days, RFC3339>"}
+    Then the response status is 201
+    And expires_at in the body equals the requested instant
+
+  Scenario Outline: Creating a key with an invalid body is refused and creates nothing
+    Given a valid jwt cookie for admin 2
+    When the client sends POST /v1/api-key with <body>
+    Then the response status is 400
+    And the response body is <message>
+    And no key exists in the repository
+
+    Examples:
+      | body                                           | message                               |
+      | body not-json                                  | apperr.BodyErrorMessage               |
+      | body {}                                        | text containing 'Name' and 'required' |
+      | body {"name": ""}                              | text containing 'Name' and 'required' |
+      | body {"name": "<61 characters>"}               | text containing 'Name' and 'max'      |
+      | body {"name": "x", "expires_at": "yesterday"}  | apperr.BodyErrorMessage               |
+      | body {"name": "x", "expires_at": "<now - 1h>"} | apperr.APIKeyExpiryErrorMessage       |
+
+  Scenario: A request body can't choose the owner or the role of a new key
+    Given a valid jwt cookie for admin 2
+    When the client sends POST /v1/api-key with body {"name": "sneaky", "user_id": 1, "role": "owner"}
+    Then the response status is 201
+    And the stored key belongs to user 2
+    And using that key on POST /v1/user/invite returns 403 with apperr.OwnerRequiredErrorMessage
+
+  Scenario Outline: Key management needs a verified real session
+    Given <caller>
+    When the client sends POST /v1/api-key with body {"name": "x"}
+    Then the response status is <status>
+    And the response body is <message>
+    And no key exists in the repository
+
+    Examples:
+      | caller                       | status | message                                 |
+      | no credentials               | 401    | the existing Authenticator response     |
+      | a jwt cookie for user 4      | 403    | apperr.VerificationRequiredErrorMessage |
+      | a stale token_version cookie | 401    | the existing Authenticator response     |
+
+  Scenario Outline: A valid key acts as its creator on every key-accepting route
+    Given an active key created by admin 2
+    When the client sends <method> <path> with "Authorization: Bearer <that key>" and no cookie <body>
+    Then the response status is <status>
+    And the effect is attributed to user 2
+
+    Examples:
+      | method | path                  | body                                             | status |
+      | GET    | /v1/settings          |                                                  | 200    |
+      | GET    | /v1/user              |                                                  | 200    |
+      | PATCH  | /v1/user/me           | and body {"display_name": "Dev"}                 | 200    |
+      | POST   | /v1/article           | and body {"title": "A valid title", "body": "x"} | 201    |
+      | PATCH  | /v1/article/1/publish |                                                  | 200    |
+      | DELETE | /v1/article/1         |                                                  | 204    |
+      | GET    | /v1/media             |                                                  | 200    |
+      | DELETE | /v1/media/1           |                                                  | 204    |
+
+  Scenario: A key can read its creator through GET /v1/auth/me
+    Given an active key created by admin 2
+    When the client sends GET /v1/auth/me with that key and no cookie
+    Then the response status is 200
+    And the body is the same JSON the jwt cookie of admin 2 gets on GET /v1/auth/me
+    And the body describes user 2 "dev"
+
+  Scenario: A key that can't authenticate gets 401 on GET /v1/auth/me
+    When the client sends GET /v1/auth/me with "Authorization: Bearer rcms_unknown"
+    Then the response status is 401
+    And the response body is apperr.UnauthorizedErrorMessage
+
+  Scenario: A key sees offline articles on the public article routes, an anonymous caller does not
+    Given an offline article 5 and an online article 6
+    And an active key created by admin 2
+    When the client sends GET /v1/article with that key
+    Then the body lists articles 5 and 6
+    When the client sends GET /v1/article with no credentials
+    Then the body lists only article 6
+    When the client sends GET /v1/article/5 with that key
+    Then the response status is 200
+    When the client sends GET /v1/article/5 with no credentials
+    Then the response status is 404
+
+  Scenario: An invalid key on a public article route is refused, not treated as anonymous
+    When the client sends GET /v1/article with "Authorization: Bearer rcms_unknown"
+    Then the response status is 401
+    And the response body is apperr.UnauthorizedErrorMessage
+
+  Scenario: An owner's key can do owner-only things
+    Given an active key created by owner 1
+    When the client sends POST /v1/user/invite with that key and body {"email": "new@example.com"}
+    Then the response status is 201
+    And the invite's invited_by is 1
+
+  Scenario: An admin's key can not do owner-only things
+    Given an active key created by admin 2
+    When the client sends POST /v1/user/invite with that key and body {"email": "new@example.com"}
+    Then the response status is 403
+    And the response body is apperr.OwnerRequiredErrorMessage
+    And no invite exists
+
+  Scenario Outline: A key that can't authenticate gets the same 401 as a bad jwt
+    Given <state>
+    When the client sends GET /v1/settings with "Authorization: Bearer <credential>"
+    Then the response status is 401
+    And the response body is apperr.UnauthorizedErrorMessage
+    And no handler or use case behind the route runs
+
+    Examples:
+      | state                                         | credential                                       |
+      | no key stored for it                          | rcms_unknownunknownunknownunknownunknownunknown1 |
+      | a key whose expires_at is one second ago      | that key                                         |
+      | a key that was revoked                        | that key                                         |
+      | a key of user 1 whose user record was deleted | that key                                         |
+      | a key of an unverified user                   | that key                                         |
+      | nothing after the prefix                      | rcms_                                            |
+      | a key with one character changed              | that key, last character changed                 |
+      | a key's hash passed instead of the key        | the stored HashedKey, status 401 only            |
+
+  Scenario: Key behaviour does not change the jwt cookie path
+    Given a valid jwt cookie for admin 2
+    When the client sends GET /v1/settings with only that cookie
+    Then the response status is 200
+    When the client sends GET /v1/settings with an Authorization header "Bearer <a valid jwt>" and no cookie
+    Then the response status is 200
+    When the client sends GET /v1/settings with a stale token_version cookie
+    Then the response status is 401
+
+  Scenario: A Bearer key wins over the cookie, and a bad key is not rescued by a good cookie
+    Given an active key created by admin 3 and a valid jwt cookie for owner 1
+    When the client sends POST /v1/user/invite with both the key and the cookie
+    Then the response status is 403
+    When the client sends GET /v1/settings with "Authorization: Bearer rcms_unknown" and the owner cookie
+    Then the response status is 401
+
+  Scenario Outline: Session-only routes refuse any rcms_ credential with 403
+    Given <state>
+    When the client sends <method> <path> with "Authorization: Bearer <credential>" <body>
+    Then the response status is 403
+    And the response body is apperr.SessionRequiredErrorMessage
+    And no use case behind the route runs
+    And no key was created, listed or revoked
+
+    Examples:
+      | state                       | credential                                       | method | path                       | body                       |
+      | an active key of owner 1    | that key                                         | POST   | /v1/api-key                | and body {"name": "child"} |
+      | an active key of owner 1    | that key                                         | GET    | /v1/api-key                |                            |
+      | an active key of owner 1    | that key                                         | DELETE | /v1/api-key/1              |                            |
+      | an active key of owner 1    | that key                                         | POST   | /v1/auth/verify            | and body {"code": "x"}     |
+      | an active key of owner 1    | that key                                         | DELETE | /v1/auth/register          |                            |
+      | an active key of owner 1    | that key                                         | GET    | /v1/system/update          |                            |
+      | an active key of owner 1    | that key                                         | POST   | /v1/system/update/check    |                            |
+      | an active key of owner 1    | that key                                         | POST   | /v1/system/update/download |                            |
+      | an active key of owner 1    | that key                                         | POST   | /v1/system/update/restart  |                            |
+      | a revoked key               | that key                                         | GET    | /v1/api-key                |                            |
+      | no key stored for it        | rcms_unknownunknownunknownunknownunknownunknown1 | POST   | /v1/system/update/check    |                            |
+      | nothing                     | rcms_                                            | DELETE | /v1/auth/register          |                            |
+
+  Scenario Outline: The session-only routes still work as before with a session
+    Given a valid jwt cookie for owner 1
+    When the client sends <method> <path> with only that cookie <body>
+    Then the response is the same as before this feature
+    And a request with no credentials still gets status 401 from the existing Authenticator
+
+    Examples:
+      | method | path                    | body                       |
+      | POST   | /v1/api-key             | and body {"name": "x"}     |
+      | GET    | /v1/api-key             |                            |
+      | GET    | /v1/system/update       |                            |
+      | POST   | /v1/system/update/check |                            |
+
+  Scenario Outline: A key never obtains a session through the public auth routes
+    Given an active key created by owner 1
+    When the client sends <method> <path> with that key and body <body>
+    Then the response is the same as without the key
+    And no jwt cookie is set unless the credentials in the body are valid
+    And the stored user and password are unchanged
+
+    Examples:
+      | method | path                            | body                                                                        |
+      | POST   | /v1/auth/login                  | {"username": "marta", "password": "wrong-pass-1"}                           |
+      | POST   | /v1/auth/password-reset/confirm | {"email": "marta@example.com", "code": "nope", "password": "newpassword1"} |
+
+  Scenario: A successful password reset revokes every key of that user
+    Given user 2 has active keys "a" and "b", and each works on GET /v1/settings
+    And user 2's stored PasswordResetCode is the hash of "reset-code-1" with an unexpired expiration
+    When the client sends POST /v1/auth/password-reset/confirm with body
+      {"email": "dev@example.com", "code": "reset-code-1", "password": "newpassword1"}
+    Then the response status is 200
+    And GET /v1/settings with key "a" returns 401 with apperr.UnauthorizedErrorMessage
+    And GET /v1/settings with key "b" returns 401 with apperr.UnauthorizedErrorMessage
+
+  Scenario: A password reset leaves other users' keys untouched
+    Given user 2 has an active key "a" and user 3 has an active key "c"
+    And user 2 has a valid password reset code "reset-code-1"
+    When user 2's password reset is confirmed with "reset-code-1"
+    Then GET /v1/settings with key "c" returns 200
+    And key "c" has no revoked_at
+
+  Scenario: Keys revoked by a password reset show as revoked
+    Given user 2 has active keys "a" and "b", and a clock at T
+    And user 2 has a valid password reset code "reset-code-1"
+    When user 2's password reset is confirmed with "reset-code-1"
+    And admin 2 logs in again with the new password and sends GET /v1/api-key with the new cookie
+    Then the entries "a" and "b" have status "revoked" and revoked_at T
+
+  Scenario: A password reset does not move the revoked_at of a key that was already revoked
+    Given user 2 has a key "old" revoked at T0 and an active key "a"
+    And user 2 has a valid password reset code "reset-code-1"
+    When user 2's password reset is confirmed with "reset-code-1" at a later time T
+    Then key "old" still has revoked_at T0
+    And key "a" has revoked_at T
+
+  Scenario Outline: A failed password reset confirmation revokes nothing
+    Given user 2 has an active key "a"
+    And user 2's stored PasswordResetCode is the hash of "reset-code-1" with <expiration>
+    When the client sends POST /v1/auth/password-reset/confirm with <body>
+    Then the response status is not 200
+    And key "a" has no revoked_at
+    And GET /v1/settings with key "a" returns 200
+
+    Examples:
+      | expiration                   | body                                                                         |
+      | an unexpired expiration      | {"email": "dev@example.com", "code": "wrong", "password": "newpassword1"}    |
+      | an expiration in the past    | {"email": "dev@example.com", "code": "reset-code-1", "password": "newpassword1"} |
+      | an unexpired expiration      | {"email": "nobody@example.com", "code": "reset-code-1", "password": "newpassword1"} |
+
+  Scenario: Listing as an admin shows only that admin's keys
+    Given keys "a" and "b" created by admin 2 and key "c" created by admin 3
+    When admin 2 sends GET /v1/api-key with a jwt cookie
+    Then the body lists exactly "a" and "b"
+
+  Scenario: Listing as the owner shows every user's keys, with the creator's id
+    Given the same three keys and key "d" created by owner 1
+    When owner 1 sends GET /v1/api-key with a jwt cookie
+    Then the body lists "a", "b", "c" and "d" newest first
+    And each entry has the user_id of its creator
+
+  Scenario Outline: The list reports each key's state
+    Given a key that is <state>
+    When its creator sends GET /v1/api-key with a jwt cookie
+    Then the entry's status is "<status>", revoked_at is <revoked_at>, and last_used_at is <last_used>
+
+    Examples:
+      | state                      | status  | revoked_at | last_used |
+      | active, never used         | active  | null       | null      |
+      | active, used 5 minutes ago | active  | null       | that time |
+      | expired one hour ago       | expired | null       | unchanged |
+      | revoked                    | revoked | a time     | unchanged |
+      | both expired and revoked   | revoked | a time     | unchanged |
+
+  Scenario: Revoking a key ends it immediately
+    Given an active key "ci-deploy" created by admin 2
+    And the key works on GET /v1/settings
+    When admin 2 sends DELETE /v1/api-key/<its id> with a jwt cookie
+    Then the response status is 204 and the body is empty
+    And GET /v1/settings with that key returns 401 with apperr.UnauthorizedErrorMessage
+    And GET /v1/api-key lists it with status "revoked"
+
+  Scenario: Revoking twice is idempotent
+    Given a key revoked at time T
+    When its creator sends DELETE /v1/api-key/<its id> again
+    Then the response status is 204
+    And revoked_at is still T
+
+  Scenario: An admin can't revoke someone else's key, and learns nothing about it
+    Given a key created by admin 3
+    When admin 2 sends DELETE /v1/api-key/<its id> with a jwt cookie
+    Then the response status is 404
+    And the response body is apperr.APIKeyNotFoundErrorMessage
+    And the key still works
+
+  Scenario: The owner can revoke any key
+    Given a key created by admin 3
+    When owner 1 sends DELETE /v1/api-key/<its id> with a jwt cookie
+    Then the response status is 204
+    And the key gets 401 on GET /v1/settings
+
+  Scenario Outline: Revoking with a bad id
+    Given a valid jwt cookie for admin 2
+    When the client sends DELETE /v1/api-key/<id>
+    Then the response status is <status>
+    And the response body is <message>
+
+    Examples:
+      | id         | status | message                           |
+      | abc        | 400    | apperr.IdUint32ErrorMessage       |
+      | -1         | 400    | apperr.IdUint32ErrorMessage       |
+      | 4294967296 | 400    | apperr.IdUint32ErrorMessage       |
+      | 999        | 404    | apperr.APIKeyNotFoundErrorMessage |
+
+  Scenario: Using a key records last_used_at, at most once per minute
+    Given an active key never used, and a fake clock at T
+    When the key authenticates a request at T
+    Then last_used_at is T
+    When it authenticates again at T + 30s
+    Then no write happened and last_used_at is still T
+    When it authenticates again at T + 61s
+    Then last_used_at is T + 61s
+
+  Scenario: A failure to record last_used_at doesn't fail the request
+    Given an active key and a repository whose TouchLastUsed returns an error
+    When the client sends GET /v1/settings with that key
+    Then the response status is 200
+
+  Scenario: A rejected key never records last_used_at
+    Given an expired key and a revoked key
+    When each is used on GET /v1/settings
+    Then each gets 401 and no last_used_at is written
+
+  Scenario: Each key has its own rate limit
+    Given two active keys "a" and "b" and a limit of N requests per minute per key
+    When key "a" sends N+1 requests to GET /v1/settings
+    Then request N+1 gets 429 with apperr.TooManyRequestsErrorMessage and a Retry-After header
+    And key "b" still gets 200
+    And a jwt cookie request still gets 200
+
+  Scenario: The rate limit does not apply to unauthenticated requests
+    When the client sends N+1 requests with "Authorization: Bearer rcms_unknown"
+    Then every response is 401, never 429
+
+  Scenario: The CORS preflight allows PATCH
+    Given settings with CorsAllowedOrigins ["https://app.example.com"]
+    When the client sends OPTIONS /v1/article/1 with Origin "https://app.example.com" and
+      Access-Control-Request-Method "PATCH"
+    Then the response is a successful preflight
+    And Access-Control-Allow-Methods includes PATCH
+    And a preflight for method "TRACE" is not allowed
+
+  Scenario: Use case: creating a key hashes it and stores no plaintext
+    Given a fake KeyGenerator returning raw "rcms_fake", prefix "rcms_fake", hash "hash:rcms_fake"
+    When CreateAPIKey is called with user 2 and name "ci"
+    Then the repository's Create receives HashedKey "hash:rcms_fake", Prefix "rcms_fake", UserID 2
+    And the result carries the raw key, which is not stored
+
+  Scenario: Use case: authenticating returns the user and rejects every invalid case with one sentinel
+    Given a fake KeyGenerator and keys that are unknown, expired, revoked, and owned by a missing or
+      unverified user
+    When AuthenticateAPIKey is called with each raw key
+    Then every call returns apikey.ErrAPIKeyInvalid, asserted with errors.Is
+    And a key expiring exactly at the clock's now is expired
+    And a valid key returns the user from user.Repository
+
+  Scenario: Use case: a failing repository is not reported as an invalid key
+    Given a repository whose GetByHashedKey returns an unexpected error
+    When AuthenticateAPIKey is called
+    Then the error is returned and errors.Is(err, apikey.ErrAPIKeyInvalid) is false
+    And the middleware answers 500 "Internal server error"
+
+  Scenario: Use case: ResetPassword revokes the user's keys through the domain repository
+    Given a fake apikey.Repository holding active keys of users 2 and 3, a fake clock at T, and a
+      user.Repository fake with a valid reset code for user 2
+    When ResetPasswordUseCase.ResetPassword succeeds for user 2
+    Then the fake apikey.Repository received exactly one RevokeAllByUser(2, T)
+    And user 3's keys are untouched
+
+  Scenario: Use case: ResetPassword does not call RevokeAllByUser when the reset fails
+    Given a fake apikey.Repository and a user.Repository fake with a wrong or expired reset code
+    When ResetPasswordUseCase.ResetPassword is called
+    Then it returns the existing invalid or expired sentinel
+    And RevokeAllByUser is never called
+
+  Scenario: Use case: a failure to revoke keys after a reset is reported
+    Given a valid reset code and an apikey.Repository whose RevokeAllByUser returns an error
+    When ResetPasswordUseCase.ResetPassword is called
+    Then the use case returns that error
+    And the password was already changed

features/api_keys.qa.md

@@ -0,0 +1,171 @@
+# QA procedure: API keys
+
+Package: `test` (black-box). No live server, no real SQLite file, no real SMTP.
+
+## Setup shared by every case
+1. Call `validator.InitValidator()` once per test.
+2. Add in-memory fakes with unique type names across the package: `mockAPIKeyRepo`
+   (implements `apikey.Repository` including `RevokeAllByUser`, with a `fail` switch per method such as
+   `failNext("TouchLastUsed")`, a `touchCalls` counter and a `revokeAllCalls` log of `(userId, at)`) and
+   `stubKeyGenerator` (deterministic raw/prefix/hash). Reuse `mockUserRepo`, `stubHasher` and the
+   article, media and invite fakes.
+3. HTTP tests use the real SHA-256 generator, so key format and hashing are real. Unit-level tests
+   use `stubKeyGenerator`.
+4. Build the handler stack from a `*api.UseCases` container holding fakes and mount
+   `api.InitBackendRoutes(container, settings)` on a test server (unused use cases stay nil). It is the
+   most faithful way to test the middleware order and the exclusions. If a nil use case breaks a
+   handler constructor, fall back to a fresh `chi.NewRouter()` that mirrors `api/router.go`:
+   `jwtauth.Verifier`, the key middleware, `jwtauth.Authenticator`, `RequireCurrentToken`,
+   `RequireVerifiedUser` (and `RequireOwner` on the invite group) for the key-accepting routes
+   (including `GET /auth/me`); `RequireSession` ahead of `jwtauth.Verifier` on `/api-key`,
+   `POST /auth/verify`, `DELETE /auth/register` and `/system`; and the public auth routes with neither.
+   The test token is `jwtauth.New("HS256", []byte("test-secret"), nil)`.
+5. Inject a fake clock (`now func() time.Time`) into the key use cases and `ResetPasswordUseCase`.
+6. Seed users: owner 1 "marta", admin 2 "dev", admin 3 "pat" (all verified), unverified 4 "quinn".
+7. Helpers: `cookieFor(userId, tokenVersion)` mints a jwt cookie with
+   `token.Encode(map[string]any{"user_id": id, "token_version": v})`; `bearer(raw)` sets the header.
+   Create real keys through `POST /v1/api-key` with the cookie so the shown-once value is genuine.
+
+## POST /v1/api-key
+8. Admin 2 cookie, `{"name":"ci-deploy"}` -> `201`, `Cache-Control: no-store`, key set is exactly `id`,
+   `name`, `prefix`, `key`, `created_at`, `expires_at`; `key` matches `^rcms_[A-Za-z0-9_-]{43}$`; prefix
+   is `key[:12]`; stored `HashedKey` equals the generator's `Hash(key)`; `UserID` 2; the raw key is
+   stored nowhere in the fake.
+9. Two creations give two different keys and ids.
+10. With `expires_at` 30 days ahead -> `201`, echoed instant.
+11. Invalid bodies (table): not-json -> `400` `apperr.BodyErrorMessage`; `{}`, `{"name":""}` -> `400`,
+    body contains `'Name'` and `required`; 61-char name -> `400`, contains `max`; `expires_at`
+    "yesterday" -> `400` `BodyErrorMessage`; past `expires_at` -> `400` `apperr.APIKeyExpiryErrorMessage`.
+    Each: repository still empty.
+12. Body `{"name":"sneaky","user_id":1,"role":"owner"}` with admin 2 -> `201`; stored `UserID` 2; that
+    key on `POST /v1/user/invite` -> `403` `apperr.OwnerRequiredErrorMessage`, no invite.
+13. Access table: no credentials -> `401`; user 4 cookie -> `403` `apperr.VerificationRequiredErrorMessage`;
+    stale `token_version` -> `401`. Each: repository empty.
+
+## Shown once
+14. After case 8, `GET /v1/api-key` -> entry keys exactly `id`, `user_id`, `name`, `prefix`, `status`,
+    `created_at`, `last_used_at`, `expires_at`, `revoked_at`; assert the response bytes contain neither
+    the raw key nor the stored hash. Also assert the raw key and hash are absent from the `DELETE`
+    response and from every error body in this file.
+15. There is no route that returns a key again: `GET /v1/api-key/{id}` -> `404` or `405` (whatever the
+    router yields; assert not `200`).
+
+## Authentication
+16. Table over `GET /v1/settings`, `GET /v1/user`, `PATCH /v1/user/me`, `POST /v1/article`,
+    `PATCH /v1/article/{id}/publish`, `DELETE /v1/article/{id}`, `GET /v1/media`, `DELETE /v1/media/{id}`
+    with only the Bearer key of admin 2 -> `200` each; the stored side effects (author, display name)
+    belong to user 2.
+17. Public article routes: seed offline article 5, online article 6. Key -> list has both, `GET /5` is
+    `200`. No credentials -> list has only 6, `GET /5` is `404`. `Bearer rcms_unknown` on `GET /v1/article`
+    -> `401` `apperr.UnauthorizedErrorMessage`.
+18. Owner key `POST /v1/user/invite` -> `201`, `invited_by` 1. Admin key -> `403`
+    `apperr.OwnerRequiredErrorMessage`, no invite and no mail.
+19. Table of 401 cases on `GET /v1/settings`, all with body `apperr.UnauthorizedErrorMessage` exactly (the
+    stored-hash case has no `rcms_` prefix, so it takes the jwt path: assert status `401` only):
+    unknown well-formed key; expired (clock one second past `expires_at`); revoked; creator deleted from
+    the user fake; creator unverified (set `IsVerified=false` in the fake); `Bearer rcms_`; one
+    character changed; the stored hash sent as the key. Assert each also leaves `touchCalls == 0`.
+    Without an `rcms_` key the existing `jwtauth.Authenticator` response is unchanged: assert status `401`.
+20. A key whose `ExpiresAt` equals the clock's now is rejected; one second later than now is accepted.
+21. Cookie path unchanged: valid cookie -> `200`; valid jwt in `Authorization: Bearer` with no cookie ->
+    `200`; stale `token_version` -> `401`; no credentials on a protected route -> `401`.
+22. Precedence: valid key of admin 3 plus an owner cookie on `POST /v1/user/invite` -> `403`
+    (acts as admin 3); `Bearer rcms_unknown` plus an owner cookie on `GET /v1/settings` -> `401`.
+23. Role is read live: change the stored role of user 2 from admin to owner in the fake (test-only) and
+    assert the key is now owner-capable, then back, and assert it is not. This pins "never more
+    rights than the creator's current rights".
+24. `GET /v1/auth/me` with only admin 2's key -> `200`, body byte-equal to the body admin 2's cookie gets
+    on the same route, describing user 2. `Bearer rcms_unknown` on `GET /v1/auth/me` -> `401`
+    `apperr.UnauthorizedErrorMessage`.
+
+## Session-only routes (RequireSession)
+25. Table, each with body `apperr.SessionRequiredErrorMessage`, status `403`, assert the underlying use
+    cases (key repository, verify, cancel registration, update status/check/download/restart) were
+    not invoked and the key repository is unchanged:
+    - owner 1's active key on `POST /v1/api-key`, `GET /v1/api-key`, `DELETE /v1/api-key/1`,
+      `POST /v1/auth/verify`, `DELETE /v1/auth/register`, `GET /v1/system/update`,
+      `POST /v1/system/update/check`, `POST /v1/system/update/download`, `POST /v1/system/update/restart`;
+    - a revoked key on `GET /v1/api-key`;
+    - an unknown well-formed `rcms_...` key on `POST /v1/system/update/check`;
+    - the bare string `rcms_` on `DELETE /v1/auth/register`.
+    The 403 comes before any authentication, so assert the same 403 for an owner key and a garbage key.
+26. Session routes unchanged for sessions: owner cookie on `POST /v1/api-key`, `GET /v1/api-key`,
+    `GET /v1/system/update`, `POST /v1/system/update/check` -> the same status and body as before this
+    feature; no credentials -> status `401` (existing Authenticator); a jwt in `Authorization: Bearer`
+    (not starting with `rcms_`) -> the same result as the cookie.
+27. Public auth routes with an owner key attached: `POST /v1/auth/login` with wrong credentials -> `403`
+    `apperr.LogsErrorMessage`, no `jwt` Set-Cookie; `POST /v1/auth/password-reset/confirm` with a wrong
+    code -> the same response as without the key, and the key is not rejected with
+    `SessionRequiredErrorMessage`. The user's stored password hash and `TokenVersion` are unchanged.
+
+## Password reset revokes keys
+28. Seed user 2 with active keys "a" and "b" (each `200` on `GET /v1/settings`), user 3 with key "c", and a
+    reset code for user 2 (hash of "reset-code-1", unexpired). `POST /v1/auth/password-reset/confirm`
+    `{"email":"dev@example.com","code":"reset-code-1","password":"newpassword1"}` -> `200`; then keys "a"
+    and "b" get `401` `apperr.UnauthorizedErrorMessage` on `GET /v1/settings`.
+29. Same seed: key "c" still gets `200` and has no `revoked_at`.
+30. Same seed with the fake clock at T: log in as user 2 with the new password, `GET /v1/api-key` with the
+    new cookie; "a" and "b" have status `revoked` and `revoked_at` equal to T.
+31. A key of user 2 already revoked at T0 keeps `revoked_at` T0 after a reset at a later T; the active
+    key gets T.
+32. Failed confirms (table: wrong code; expired code; unknown email) -> status not `200`; key "a" has no
+    `revoked_at`, still `200` on `GET /v1/settings`, and `revokeAllCalls` is empty.
+
+## Listing
+33. Admin 2 sees only own keys; owner 1 sees all, newest first, each with its `user_id`.
+34. Status table: active never used (`active`, nulls), active used (timestamp kept), expired
+    (`expired`), revoked (`revoked`, `revoked_at` set), expired-and-revoked (`revoked`).
+
+## Revoke
+35. Own key -> `204`, empty body; the key then gets `401` on `GET /v1/settings`; the list shows `revoked`.
+36. Second `DELETE` -> `204`, `revoked_at` unchanged.
+37. Admin 2 revoking admin 3's key -> `404` `apperr.APIKeyNotFoundErrorMessage`; the key still works.
+    Owner revoking it -> `204`; it then gets `401`.
+38. Ids `abc`, `-1`, `4294967296` -> `400` `apperr.IdUint32ErrorMessage`; unknown id -> `404`.
+39. Repository failure on `Revoke` -> `500` "Internal server error"; the key still works.
+
+## last_used_at
+40. Use-case level with the fake clock: first auth at T writes T; at T+30s no write
+    (`touchCalls` unchanged); at T+61s writes T+61s.
+41. `TouchLastUsed` failing -> the request still returns `200`.
+42. Rejected keys (case 19) never write.
+
+## Rate limit
+43. Mirror a group using the new per-key limiter with a limit of 2 (an exported constructor taking max
+    attempts and window): third request with key A -> `429`, body `apperr.TooManyRequestsErrorMessage`,
+    `Retry-After` header; key B and a cookie request still `200`; invalid keys stay `401`, never `429`.
+44. Through `api.InitBackendRoutes`, send 121 requests with one key to `GET /v1/settings` -> the 121st is
+    `429`, the first 120 are `200`.
+
+## CORS
+45. Through `api.InitRoutes` with `CorsAllowedOrigins` `["https://app.example.com"]`: `OPTIONS /v1/article/1`
+    with `Origin` and `Access-Control-Request-Method: PATCH` -> success, `Access-Control-Allow-Methods`
+    includes `PATCH`; with `TRACE` it is not allowed.
+
+## Use case level (no HTTP)
+46. `CreateAPIKey` with `stubKeyGenerator`: repository receives the hash and the prefix and the user id;
+    the raw key appears only in the return value; a generator error -> returned, nothing stored; past
+    expiry -> `errors.Is(err, apikey.ErrExpiryNotInFuture)`.
+47. `AuthenticateAPIKey`: each invalid case in 19 and 20 -> `errors.Is(err, apikey.ErrAPIKeyInvalid)`; a
+    valid key returns the user; an unexpected repository error is returned and is not `ErrAPIKeyInvalid`.
+48. `ListAPIKeys` for admin and owner; `RevokeAPIKey` own, other's (`ErrAPIKeyNotFound` for admin),
+    owner any, unknown (`ErrAPIKeyNotFound`).
+49. `ResetPasswordUseCase` built over `mockUserRepo`, `stubHasher`, `mockAPIKeyRepo` and a fake clock at T:
+    a successful reset for user 2 -> exactly one `RevokeAllByUser(2, T)` and user 3's keys untouched; a
+    wrong or expired code -> the existing sentinel and `revokeAllCalls` empty; `RevokeAllByUser`
+    failing -> that error is returned (the password was already changed).
+50. `mockAPIKeyRepo.RevokeAllByUser` semantics: sets `RevokedAt` only on that user's not-yet-revoked
+    keys.
+51. SHA-256 generator: raw matches the regex, `Hash(raw)` equals the generated hash, two generated keys
+    differ, prefix is the first 12 characters.
+
+## Manual verification (not exercised by the Go tests)
+- Real SQLite: start `task dev:api`, confirm `AutoMigrate` creates the api_keys table with a unique index
+  on the hashed key, create a key, restart, and check it still authenticates.
+- With `curl`, run `Authorization: Bearer <key>` against a running server for an article create, a media
+  upload, an owner invite and `GET /v1/auth/me`, and confirm `PATCH` works from a browser origin listed
+  in `CORS_ALLOWED_ORIGINS`.
+- Confirm the full key is shown only in the creation response and appears in no server log
+  (`ENVIRONMENT=development` enables httplog).
+- A real reverse proxy: confirm `Authorization` is forwarded and `Retry-After` reaches the client.
+- A real password reset by email: confirm the keys stop working after the link is used.

features/api_keys_screen.feature

@@ -0,0 +1,352 @@
+Feature: API keys screen
+
+  As a verified RenewCMS owner or admin
+  I want /integration/api-keys to list my API keys, create new ones and revoke them
+  So that a script or service can call the API with my rights, and I can cut it off at any time
+
+  Background:
+    Given /integration/api-keys is a verified route (meta.auth "verified") rendered as ApiKeysPage
+      with CreateApiKeyModal, ApiKeyReveal and a revoke confirmation dialog, inside
+      DashboardShell, per docs/design/routes.md
+    And the screen is a sub-page of Integration, per docs/design/screens/integration.md
+    And the screen calls, with relative URLs through useApi only, GET /v1/api-key,
+      POST /v1/api-key and DELETE /v1/api-key/{id}
+    And a GET /v1/api-key entry has the fields id, user_id, name, prefix (12 characters), status
+      ("active", "expired" or "revoked"), created_at, last_used_at, expires_at and revoked_at, and
+      never a key or a hash, per features/api_keys.feature
+    And an owner's entries also carry created_by_name, the creator's display name or username (see
+      the API scenarios below)
+    And the list arrives newest first; an owner receives every user's keys, an admin only their own
+    And the PageHeader shows breadcrumb "Integration › API keys" (Integration links to
+      /integration), title "API keys" and a primary "Create key" button on the right at desktop
+    And the description reads "Keys act as the user who created them. As an owner you see
+      everyone's keys." for an owner, and "Keys act as you, with your role. You only see your own
+      keys." for an admin; a session without a role gets the admin rendering
+    And the table, on desktop, has the columns Name, Key, Status, Created by (owner only), Created,
+      Last used, Expires and an action column, in a UTable with a 36 px header and 48 px rows
+    And below md, each key is a card: name and status badge, prefix in monospace, then
+      "Created {date}[ by {name}] · Last used {date} · Expires {date}", then a 44 px "Revoke" button
+    And the Key column and the card show the prefix cut to its first 9 characters followed by "…",
+      for example "rcms_Kf3x…", and the full key is never shown in the list
+    And the revoke text uses the same 9-character prefix plus "…"
+    And dates are absolute and formatted for the current locale, for example "12 Mar 2026" in
+      English; a null expires_at reads "None" and a null last_used_at reads "Never"
+    And a Created by cell with an empty created_by_name shows "—"
+    And the Status badge is a UBadge: active success soft, expired warning soft, revoked neutral
+      with a muted row
+    And "Revoke" is offered on active and expired keys, never on revoked keys
+    And a note with an info icon always closes the page: "Resetting a user's password revokes all of
+      their keys."
+    And the Integration page (/integration, features/integration.feature) gains a "Manage API
+      keys" link to /integration/api-keys (see the Integration link scenario)
+    And on /integration/api-keys the sidebar and drawer item "Integration" carries
+      aria-current="page"
+    And every visible string goes through t(...), with the English text as the key and its French
+      entry in web/src/i18n/messages.ts
+    And the screen uses Nuxt UI components and design tokens only, with no raw colors
+    And the owner fixture is, newest first as the board draws it:
+      | name                 | prefix     | status  | created by  | created     | last used   | expires     |
+      | Website build        | rcms_Kf3x… | active  | Marta Alves | 12 Mar 2026 | 3 Oct 2026  | None        |
+      | Nightly media import | rcms_Mq7b… | active  | Jonas       | 2 Apr 2026  | 3 Oct 2026  | 31 Dec 2026 |
+      | Staging preview      | rcms_Zt2d… | expired | Marta Alves | 14 Jun 2026 | 20 Aug 2026 | 30 Aug 2026 |
+      | Old migration script | rcms_Hn5w… | revoked | Inès Duarte | 3 Apr 2026  | 9 May 2026  | None        |
+    And the admin fixture (user "Jonas") is:
+      | name                 | prefix     | status  | created     | last used   | expires     |
+      | Nightly media import | rcms_Mq7b… | active  | 2 Apr 2026  | 3 Oct 2026  | 31 Dec 2026 |
+      | Old CI token         | rcms_Lp9c… | revoked | 18 Jan 2026 | 2 Feb 2026  | None        |
+
+  Scenario: Owner: list
+    Given the session role is "owner"
+    And GET /v1/api-key answers 200 with the owner fixture
+    When the user navigates to /integration/api-keys
+    Then the four rows show in fixture order with the columns Name, Key, Status, Created by,
+      Created, Last used, Expires
+    And "Staging preview" shows an "expired" badge and "Revoke"
+    And "Old migration script" shows a "revoked" badge, a muted row and no "Revoke"
+    And the description is the owner description
+
+  Scenario: Admin: own keys only
+    Given the session role is "admin"
+    And GET /v1/api-key answers 200 with the admin fixture
+    When the user navigates to /integration/api-keys
+    Then the two rows show with no "Created by" column
+    And on mobile the cards read "Created 2 Apr 2026 · Last used 3 Oct 2026 · Expires 31 Dec 2026"
+      without " by {name}"
+    And the description is the admin description
+
+  Scenario: Loading
+    Given GET /v1/api-key is pending
+    When the user navigates to /integration/api-keys
+    Then four skeleton rows are drawn in the table (two-bar cards below md) and the table has
+      aria-busy "true"
+    And the header "Create key" button is shown
+
+  Scenario: Empty
+    Given GET /v1/api-key answers 200 with []
+    When the user navigates to /integration/api-keys
+    Then a panel shows title "No API keys yet", text "Create a key to call the API from a script or
+      service." and a primary "Create key" button
+    And no table is drawn
+
+  Scenario Outline: Error on load
+    Given GET /v1/api-key fails with <failure>
+    When the user navigates to /integration/api-keys
+    Then an alert (role "alert") shows "Couldn't load your API keys" and "Check your connection and
+      try again." with a "Try again" action
+    And no table, no cards and no empty panel are drawn
+
+    Examples:
+      | failure         |
+      | status 500      |
+      | a network error |
+
+  Scenario: Try again after an error
+    Given the load failed and the error alert is shown
+    When the user activates "Try again"
+    Then GET /v1/api-key is requested again and, on 200, the list replaces the alert
+
+  Scenario Outline: Session problems use the app-wide handling
+    Given GET /v1/api-key answers <status>
+    When the user navigates to /integration/api-keys
+    Then <outcome>
+
+    Examples:
+      | status | outcome                                                                |
+      | 401    | the user lands on /login?redirect=/integration/api-keys&reason=expired |
+      | 403    | the user lands on /register/pending                                    |
+
+  Scenario: Create key: modal opened
+    Given the list is shown
+    When the user activates "Create key"
+    Then a modal titled "Create API key" opens with the text "The key acts as you, with your role. It
+      is shown in full once."
+    And it has a Name field with a "0 / 60" counter and help "Required. Up to 60 characters."
+    And it has an "Expiry date (optional)" date input with help "Optional. Must be in the future.
+      Leave it empty for a key that does not expire."
+    And it has the buttons "Cancel" and "Create key"
+    And Name has focus
+
+  Scenario Outline: Create key: validation
+    Given the Create API key modal is open
+    When the user submits with name "<name>" and expiry "<expiry>"
+    Then no request is sent
+    And <name_error>
+    And <expiry_error>
+
+    Examples:
+      | name   | expiry      | name_error                                  | expiry_error                                                 |
+      |        | 12 Mar 2026 | Name shows the error "Enter a name." in red | Expiry shows the error "Choose a date in the future." in red |
+      |        |             | Name shows the error "Enter a name." in red | Expiry shows no error                                        |
+      | Deploy | 12 Mar 2026 | Name shows no error                         | Expiry shows the error "Choose a date in the future." in red |
+
+  Scenario: Create key: name too long
+    Given the Create API key modal is open
+    When the user types a name of 75 characters
+    Then the counter reads "75 / 60" in the error color
+    And Name shows the error "Use 60 characters or fewer." in red
+    And submitting sends no request
+
+  Scenario: Create key: success reveals the key once
+    Given the Create API key modal is open
+    When the user submits name "Nightly media import" and an empty expiry
+    Then exactly one POST /v1/api-key is sent with body {"name": "Nightly media import"} and no
+      expires_at
+    And on 201 the form modal is replaced by a modal titled "Your new API key" with the text
+      "\"Nightly media import\" is ready. Copy the key and store it somewhere safe."
+    And a warning alert (UAlert, color warning, triangle-alert icon) reads "You won't be able to
+      see this key again."
+    And the full key from the response is shown in a monospace box with a "Copy" button (icon copy)
+    And the note "Closing this window discards the key from the screen. Copy it first." is shown
+    And the only button is a primary "Done"
+
+  Scenario: Create key: with an expiry
+    Given the Create API key modal is open
+    And the local date is D
+    When the user submits name "temp" and the expiry date D + 30 days
+    Then the POST body carries name "temp" and expires_at equal to 23:59:59 local time on D + 30
+      days, as an RFC3339 instant with the local offset
+
+  Scenario Outline: The expiry date is checked against the same instant the API checks
+    Given the Create API key modal is open and the current time is T
+    When the user submits a name and the expiry date <date>
+    Then <outcome>
+
+    Examples:
+      | date      | outcome                                                            |
+      | today     | the request is sent, because 23:59:59 today is after T             |
+      | yesterday | no request is sent and Expiry shows "Choose a date in the future." |
+      | tomorrow  | the request is sent                                                |
+
+  Scenario: One-time reveal: copied
+    Given the key reveal is open
+    When the user activates "Copy"
+    Then the full key is written to the clipboard
+    And the button shows icon check and text "Copied" in the success color, announced to assistive
+      technology
+    When 2 seconds elapse
+    Then the button reverts to icon copy and text "Copy"
+
+  Scenario: One-time reveal: Done discards the key
+    Given the key reveal is open
+    When the user activates "Done"
+    Then the modal closes
+    And the full key is no longer in the DOM, the component state, the URL or any storage
+    And the new key is listed first with its 9-character prefix and "…" only, status "active",
+      created by the current user (owner view), last used "Never", expires per the request, and no
+      second GET /v1/api-key is made
+    And reopening "Create key" shows an empty form
+
+  Scenario Outline: Dismissing the modals
+    Given <modal> is open
+    When the user <action>
+    Then <outcome>
+
+    Examples:
+      | modal               | action              | outcome                                                |
+      | the key reveal      | presses Escape      | the modal closes and the key is discarded, as for Done |
+      | the key reveal      | clicks the backdrop | the modal stays open                                   |
+      | the Create key form | presses Escape      | the modal closes with no request                       |
+      | the Create key form | clicks the backdrop | the modal stays open                                   |
+
+  Scenario: Create key: Cancel discards the form
+    Given the Create API key modal is open with typed values
+    When the user activates "Cancel"
+    Then the modal closes without a request, focus returns to the opening button, and reopening it
+      shows an empty form
+
+  Scenario: Revoke: confirm
+    Given the owner list is shown
+    When the user activates "Revoke" on "Nightly media import"
+    Then a dialog titled "Revoke this key?" opens with the text "\"Nightly media import\"
+      (rcms_Mq7b…) will stop working right away. Requests that use it answer 401. This can't be
+      undone."
+    And its buttons are "Keep key" and a destructive "Revoke key"
+    And "Keep key" closes the dialog with no request and the row unchanged
+
+  Scenario: Revoked
+    Given the revoke dialog is open for "Nightly media import" (id 2)
+    When the user activates "Revoke key"
+    Then exactly one DELETE /v1/api-key/2 is sent
+    And on 204 the dialog closes and the row stays listed with status "revoked", a muted row and no
+      "Revoke" button
+    And a success toast shows title "Key revoked" and text "\"Nightly media import\" can no longer
+      be used."
+    And no second GET /v1/api-key is made
+
+  Scenario: Mobile Create key button, not drawn on board
+    Given the viewport is below md
+    When the list, the loading skeleton or the error alert is shown
+    Then a primary full-width 48 px "Create key" button is pinned to the bottom of the screen
+    And it is hidden while any modal or dialog is open, and in the Empty state where the panel has
+      its own "Create key" button
+    And the header has no "Create key" button below md
+
+  Scenario: Integration page links to the keys screen
+    Given the user is on /integration
+    Then a "Manage API keys" link (UButton variant link, arrow-right trailing icon) is shown below
+      the three info notes
+    When the user activates it
+    Then the user lands on /integration/api-keys and the sidebar "Integration" item keeps
+      aria-current="page"
+
+  Scenario: Language: every string has a French entry
+    Given the language is "fr"
+    When the user opens each state of the screen
+    Then every visible string is the French message and none falls back to English
+    And dates are formatted for "fr"
+
+  Scenario: Create key: sending, not drawn on board, no visual state
+    Given the Create API key modal is open with a valid name
+    When the user submits and POST /v1/api-key is pending
+    Then the primary button reads "Creating…", Name, Expiry and "Cancel" are disabled
+    And Escape does not close the modal
+
+  Scenario Outline: Create key: failed, not drawn on board, no visual state
+    Given the Create API key modal is open with name "Nightly media import"
+    When POST /v1/api-key fails with <failure>
+    Then an alert in the modal reads "<copy>"
+    And the typed values are kept, the form is enabled again, no row is added, and no field error
+      is shown
+
+    Examples:
+      | failure         | copy                                                             |
+      | status 500      | Couldn't create the key. Try again in a moment.                  |
+      | a network error | Couldn't reach RenewCMS. Check your connection and try again.    |
+      | status 429      | Too many requests. Wait a moment, then try again.                |
+      | status 400      | Something in the form isn't valid. Check the highlighted fields. |
+
+  Scenario: Create key: retry after failure, not drawn on board, no visual state
+    Given a failed create left the modal open
+    When the user submits again and POST answers 201
+    Then the reveal opens and the row is added
+
+  Scenario: Revoke: sending, not drawn on board, no visual state
+    Given the revoke dialog is open
+    When the user activates "Revoke key" and DELETE is pending
+    Then "Revoke key" reads "Revoking…", both buttons are disabled, and Escape does not close the
+      dialog
+
+  Scenario Outline: Revoke: failed, not drawn on board, no visual state
+    Given the revoke dialog is open for "Nightly media import"
+    When DELETE fails with <failure>
+    Then a notice in the dialog reads "<copy>"
+    And the dialog stays open, the buttons are enabled again, and the row is unchanged
+
+    Examples:
+      | failure         | copy                                                          |
+      | status 500      | Couldn't revoke the key. Try again in a moment.               |
+      | a network error | Couldn't reach RenewCMS. Check your connection and try again. |
+
+  Scenario: Revoke: key already gone, 404, not drawn on board, no visual state
+    Given the revoke dialog is open for "Nightly media import" (id 2)
+    When DELETE /v1/api-key/2 answers 404
+    Then the dialog closes, the row is removed from the list, and an error toast reads "That key no
+      longer exists."
+
+  Scenario: Last used, never, not drawn on board, no visual state
+    Given an entry whose last_used_at is null
+    Then its Last used cell and its mobile card text read "Never"
+
+  Scenario: API: an owner's list carries the creator's name
+    Given owner 1 "marta" with display name "Marta Alves", admin 2 "dev" with display name "Dev Two"
+      and admin 3 "pat" with an empty display name
+    And keys "a" by user 1, "b" by user 2 and "c" by user 3
+    When owner 1 sends GET /v1/api-key with a jwt cookie
+    Then each entry has the key created_by_name
+    And entry "a" has "Marta Alves", "b" has "Dev Two" and "c" has "pat"
+    And the other nine fields are unchanged from features/api_keys.feature
+
+  Scenario: API: a whitespace-only display name falls back to the username
+    Given admin 3 "pat" with display name "   " and a key "c"
+    When owner 1 sends GET /v1/api-key
+    Then entry "c" has created_by_name "pat"
+
+  Scenario: API: an admin's list is unchanged
+    Given admin 2 with keys "a" and "b"
+    When admin 2 sends GET /v1/api-key with a jwt cookie
+    Then every entry has exactly the keys id, user_id, name, prefix, status, created_at,
+      last_used_at, expires_at, revoked_at
+    And no entry has created_by_name
+
+  Scenario: API: a key whose creator no longer exists
+    Given a key whose user record was deleted
+    When owner 1 sends GET /v1/api-key
+    Then its entry has created_by_name ""
+    And the response status is 200 and the other entries are unaffected
+
+  Scenario: API: a failing user lookup fails the list
+    Given the user repository fake returns an unexpected error on Get for a creator
+    When owner 1 sends GET /v1/api-key
+    Then the response status is 500 and the body is "Internal server error"
+
+  Scenario: API: the creator name is resolved once per user
+    Given owner 1 has 3 keys and admin 2 has 2 keys
+    When owner 1 sends GET /v1/api-key
+    Then the user repository received one Get per distinct creator, not one per key
+
+  Scenario: Use case: ListAPIKeys returns the creator name only to an owner
+    Given a fake apikey.Repository and a fake user.Repository
+    When ListAPIKeys is called for an owner
+    Then every APIKeyEntry carries the creator's name
+    When ListAPIKeys is called for an admin
+    Then every APIKeyEntry has an empty creator name and the handler omits the field

features/api_keys_screen.qa.md

@@ -0,0 +1,235 @@
+# QA: API keys screen
+
+Two parts: the Go API change (HTTP-level, in `test/`) and the SPA (Vitest and visual).
+
+## What changes in the backend
+
+Only `GET /v1/api-key` called by an owner changes: each entry gains `created_by_name`, the creator's
+display name (trimmed, non-empty) or else username, and `""` when the creator no longer exists.
+Admin entries keep exactly the nine existing fields and never carry `created_by_name`.
+`features/api_keys.feature` is not edited. Its exact-fields scenario is made as an admin and stays
+true. No domain or persistence change: `ListAPIKeysUseCase` already holds `user.Repository` and
+resolves each distinct creator once through `Get`.
+
+## Go: created_by_name on GET /v1/api-key
+
+Extend `test/api_keys_http_test.go`. Build the handler from `NewHandler(...)` over use cases wired
+to the existing in-memory fakes (apikey.Repository, user.Repository, KeyGenerator, fake clock).
+Mount it on a fresh `chi.NewRouter()` that mirrors `api/router.go`, wrapped in `jwtauth.Verifier`
+and `jwtauth.Authenticator` with a test `jwtauth.New("HS256", ...)`; call
+`validator.InitValidator()`; exercise it with `httptest`. No live server, no real SQLite, no real
+SMTP. Users: owner 1 "marta" (display name "Marta Alves"), admin 2 "dev" ("Dev Two"), admin 3
+"pat" (empty display name), all verified.
+
+1. **Owner sees names** - keys a (user 1), b (user 2), c (user 3); owner cookie GET /v1/api-key;
+   assert 200, every entry has `created_by_name`, a "Marta Alves", b "Dev Two", c "pat", and the
+   other nine fields as before (newest first).
+2. **Whitespace display name** - user 3 display name "   "; assert "pat".
+3. **Admin unchanged** - admin 2 cookie; assert every entry has exactly the nine existing fields
+   (use `apiKeyAssertExactFields`) and no `created_by_name`. Check that the existing exact-fields
+   test at line 341 is made as an admin; if it is made as an owner, update it and report it.
+4. **Deleted creator** - key whose user was removed from the fake; owner GET; assert 200 and
+   `created_by_name` "" for it.
+5. **User lookup fails** - the fake user repository returns an error on Get for a creator; assert
+   500 and body "Internal server error".
+6. **One lookup per creator** - the fake counts Get calls; owner with 3 + 2 keys over 2 creators;
+   assert the creator lookups equal the distinct creators (plus the requester's own Get).
+7. **Use case level** - ListAPIKeys for an owner returns entries with the creator name; for an
+   admin returns empty creator names; the other existing ListAPIKeys tests pass unchanged.
+8. **Regression** - the existing api_keys tests still pass; list order, statuses, 401 and 403
+   behaviour are unchanged.
+
+Run with `task test`; one test with `task test -- -run 'TestName'`.
+
+## Automated SPA (Vitest + Vue Test Utils, `task test:web`)
+
+Mock `useApi`'s `request` for GET /v1/api-key, POST /v1/api-key and DELETE /v1/api-key/{id} per
+case. Mount ApiKeysPage inside DashboardShell with a resolved verified session (id 1, "marta",
+display name "Marta Alves", role "owner") and a test router at /integration/api-keys; admin cases
+use role "admin", username "jonas". Mocked owner entries carry `created_by_name`. Stub
+`navigator.clipboard.writeText` per case. No test freezes the system date; specs assert on the
+fixtures' absolute dates only, and the expiry cases build their dates from the real clock. Run
+layout cases at desktop and below-md (mock `matchMedia`).
+
+1. **Owner: list** - breadcrumb (with the Integration link), title, owner description, header
+   labels, rows in fixture order with every cell (prefix cut to 9 characters plus "…", Created by
+   from `created_by_name`), badge words, "Revoke" on rows 1 to 3 and not row 4, row 4 muted, the
+   note; the below-md cards. An entry with an empty `created_by_name` shows "—".
+2. **Admin: own keys only** - no "Created by" header or cell, admin description, two rows, cards
+   without " by {name}"; a session with no role gets the same rendering.
+3. **Loading** - unresolved GET; 4 skeleton rows, aria-busy "true", header "Create key"; resolve
+   and assert rows.
+4. **Empty** - `[]`; the panel copy and its "Create key", no table.
+5. **Error, Examples-driven** - ApiError(500), then NetworkError; alert copy as drawn, "Try again",
+   no rows; click "Try again" and assert the second request and the rows.
+6. **401 and 403** - the app-wide redirects, no alert on the page.
+7. **Create key: opened** - title, text, "0 / 60", helps, buttons, focus on Name.
+8. **Create key: validation, Examples-driven** - the three Outline rows; error text, no request,
+   errors clear when fixed.
+9. **Create key: name too long** - 75 characters; counter, error class and text, no request.
+10. **Create key: success** - one POST with `{"name":"Nightly media import"}` and no expires_at
+    key; the reveal: title, text, warning alert, key equal to the mocked `key`, "Copy", note, only
+    "Done".
+11. **Create key: expiry** - date D + 30 days; assert expires_at is 23:59:59 local on that day
+    with the local offset. Examples today (sent), yesterday (blocked), tomorrow (sent); build the
+    dates from `new Date()` in the test.
+12. **Reveal: copied** - fake timers; click "Copy"; writeText with the full key, icon check,
+    "Copied", aria-live announcement; advance 2 s; "Copy" again.
+13. **Reveal: Done and Escape discard** - assert the modal is gone, the key string appears nowhere
+    in `wrapper.html()`, the router URL, localStorage or sessionStorage; the new row shows the
+    prefix only, status "active", "Never", created by the session user; no second GET; a reopened
+    form is empty. A backdrop click leaves the reveal open.
+14. **Create key: Cancel and Escape** - no request, empty on reopen, focus back on the opener;
+    a backdrop click does not close.
+15. **Revoke: confirm and Keep key** - dialog copy with the 9-character prefix, both buttons;
+    "Keep key" closes with no request.
+16. **Revoked** - confirm; one DELETE with the key's id; row "revoked", muted, no "Revoke"; toast
+    title and text; no second GET.
+17. **Not drawn: Create sending** - pending POST; "Creating…", disabled fields and Cancel, Escape
+    ignored.
+18. **Not drawn: Create failed, Examples-driven** - ApiError(500) "Couldn't create the key. Try
+    again in a moment.", NetworkError "Couldn't reach RenewCMS. Check your connection and try
+    again.", ApiError(429) "Too many requests. Wait a moment, then try again.", ApiError(400)
+    "Something in the form isn't valid. Check the highlighted fields."; values kept, form
+    re-enabled, no row added; submit again, resolve 201, assert the reveal.
+19. **Not drawn: Revoke sending** - "Revoking…", both buttons disabled, Escape ignored.
+20. **Not drawn: Revoke failed, Examples-driven** - ApiError(500) "Couldn't revoke the key. Try
+    again in a moment." and NetworkError "Couldn't reach RenewCMS. Check your connection and try
+    again."; the notice in the open dialog, row unchanged; retry succeeds.
+21. **Not drawn: Revoke 404** - the dialog closes, the row is removed, the error toast "That key no
+    longer exists.".
+22. **Not drawn: Last used "Never"** - null `last_used_at`, desktop cell and mobile card.
+23. **Mobile pinned button** - below md the pinned 48 px "Create key" exists in list, loading and
+    error; hidden while a modal is open and in Empty; no header button below md.
+24. **Integration link and navigation** - on /integration assert "Manage API keys" is a link to
+    /integration/api-keys below the three info notes; navigate; assert the sidebar and drawer
+    "Integration" item has aria-current="page" on /integration/api-keys. Update the existing
+    integration specs (features/integration.qa.md case 1) for the extra link.
+25. **French** - `setLocale('fr')`; walk cases 1, 4, 7, 10, 15, 16, 17, 21; no visible English
+    source string remains; dates use the French format.
+26. **Messages** - every new `t()` key has a French entry (extend the i18n spec pattern).
+
+Un-run web tests are reported as NOT RUN, never as passing.
+
+## Visual (`task visual:check -- integration-api-keys`, desktop and mobile, light and dark)
+
+Reference: docs/design/screens/integration.md, board `docs/design/source/RenewCMS Screens API
+keys.dc.html`, exact values in `docs/design/source/ApiKeysPage.dc.html`. Add each state's setup to
+`web/visual/states.ts` with the board's own sample data (mocked GET /v1/api-key responses include
+`created_by_name` and 12-character prefixes whose first 9 characters match the board). Hard gate:
+every capture of every state within 10 %.
+
+Sample data: the owner and admin fixtures from the feature's Background; Create modal name
+"Nightly media import" (20 / 60) and expiry 31 Dec 2026; validation: empty name (0 / 60) and
+expiry 12 Mar 2026; too long: "Nightly import of the new media library from the Brussels office
+file server" (75 / 60); reveal key rcms_Kf3x9QwL0aBcT7nV2uYdE5sHjR8mPz4WqXg6C1oIyNe for
+"Nightly media import"; revoke and toast for "Nightly media import" (rcms_Mq7b…).
+
+No state is clock-sensitive, since every date is fixed text. The Create sample expiry 31 Dec 2026
+becomes a past date after that day, but the state only displays it, so it gets no skip.
+
+States:
+- [ ] Owner: list
+- [ ] Admin: own keys only
+- [ ] Loading (the setup holds the request)
+- [ ] Empty
+- [ ] Error
+- [ ] Create key
+- [ ] Create key: validation
+- [ ] Create key: name too long
+- [ ] One-time reveal
+- [ ] One-time reveal: copied (timer-driven, so it is checked)
+- [ ] Revoke: confirm
+- [ ] Revoked (list with the revoked row and the toast)
+- [ ] Layout from the page component, not components.md: 36 px header, 48 px rows, 20 px status
+      badge; desktop modal 480 px wide 120 px from the top; mobile modal full width, bottom-aligned,
+      buttons stacked with Cancel under the primary; mobile card Revoke 44 px; toast 320 px wide
+      bottom-right on desktop and 16 px inset on mobile.
+- [ ] Not drawn on the board, no visual state, Vitest only: Create sending, Create failed (500,
+      network, 429, 400), Revoke sending, Revoke failed, Revoke 404, "Never", the dismissal rules,
+      and the Integration "Manage API keys" link.
+
+Risk: the mobile pinned "Create key" button is not on the board, and the Integration link is not
+on the board's frames for the current Integration page. Either may push a mobile or Integration
+capture over 10 %. Re-run `task visual:check -- integration` and the API keys screen. If either
+fails, the user must decide: an approved per-state exception needs `approvedBy`, or a design
+update.
+
+Manual checks screenshots cannot cover:
+- Keyboard and focus order: Tab reaches "Create key", then each "Revoke" in row order; modal focus
+  starts on Name, is trapped, and returns to the opener on close; the reveal's initial focus lands
+  on "Copy".
+- Hover and motion: outline and primary button hover; modal motion; skeleton pulse stopped under
+  reduced motion.
+
+## Manual verification
+
+- Real round trip against `task dev`: create a key, copy it, run
+  `curl -H "Authorization: Bearer <key>" <origin>/v1/auth/me` and get 200; revoke it from the
+  screen and get 401; confirm the key gets 403 "This action needs a real session." on
+  /v1/api-key.
+- Owner and admin: as owner confirm the Created by names (display name, else username); as admin
+  confirm only your own keys and no Created by column.
+- Reset-password revocation: reset a user's password and confirm their keys show "revoked" after
+  reload.
+- Clipboard on a real HTTPS or localhost origin.
+
+## French strings for web/src/i18n/messages.ts
+
+Keyed by the English text. `{0}` and `{1}` are the `t()` placeholders.
+
+- API keys = Clés d'API
+- Integration › API keys = Intégration › Clés d'API
+- Create key = Créer une clé
+- Name = Nom
+- Key = Clé
+- Status = Statut
+- Created by = Créée par
+- Created = Créée le
+- Last used = Dernière utilisation
+- Expires = Expire le
+- active = active
+- expired = expirée
+- revoked = révoquée
+- Revoke = Révoquer
+- None = Aucune
+- Never = Jamais
+- Keys act as the user who created them. As an owner you see everyone's keys. = Les clés agissent comme l'utilisateur qui les a créées. En tant que propriétaire, vous voyez les clés de tout le monde.
+- Keys act as you, with your role. You only see your own keys. = Les clés agissent en votre nom, avec votre rôle. Vous ne voyez que vos propres clés.
+- Resetting a user's password revokes all of their keys. = Réinitialiser le mot de passe d'un utilisateur révoque toutes ses clés.
+- No API keys yet = Aucune clé d'API pour l'instant
+- Create a key to call the API from a script or service. = Créez une clé pour appeler l'API depuis un script ou un service.
+- Couldn't load your API keys = Impossible de charger vos clés d'API
+- Check your connection and try again. = Vérifiez votre connexion et réessayez.
+- Try again = Réessayer
+- Create API key = Créer une clé d'API
+- The key acts as you, with your role. It is shown in full once. = La clé agit en votre nom, avec votre rôle. Elle n'est affichée en entier qu'une seule fois.
+- Required. Up to 60 characters. = Obligatoire. 60 caractères maximum.
+- Expiry date (optional) = Date d'expiration (facultative)
+- Optional. Must be in the future. Leave it empty for a key that does not expire. = Facultative. Doit être dans le futur. Laissez vide pour une clé qui n'expire pas.
+- Enter a name. = Saisissez un nom.
+- Use 60 characters or fewer. = Utilisez 60 caractères ou moins.
+- Choose a date in the future. = Choisissez une date dans le futur.
+- Cancel = Annuler
+- Your new API key = Votre nouvelle clé d'API
+- "{0}" is ready. Copy the key and store it somewhere safe. = « {0} » est prête. Copiez la clé et conservez-la en lieu sûr.
+- You won't be able to see this key again. = Vous ne pourrez plus revoir cette clé.
+- Copy = Copier
+- Copied = Copié
+- Closing this window discards the key from the screen. Copy it first. = Fermer cette fenêtre supprime la clé de l'écran. Copiez-la d'abord.
+- Done = Terminé
+- Revoke this key? = Révoquer cette clé ?
+- "{0}" ({1}) will stop working right away. Requests that use it answer 401. This can't be undone. = « {0} » ({1}) cessera de fonctionner immédiatement. Les requêtes qui l'utilisent recevront une réponse 401. Cette action est irréversible.
+- Keep key = Garder la clé
+- Revoke key = Révoquer la clé
+- Key revoked = Clé révoquée
+- "{0}" can no longer be used. = « {0} » ne peut plus être utilisée.
+- Creating… = Création…
+- Revoking… = Révocation…
+- Couldn't create the key. Try again in a moment. = Impossible de créer la clé. Réessayez dans un instant.
+- Couldn't reach RenewCMS. Check your connection and try again. = Impossible de joindre RenewCMS. Vérifiez votre connexion et réessayez.
+- Too many requests. Wait a moment, then try again. = Trop de requêtes. Patientez un instant, puis réessayez.
+- Something in the form isn't valid. Check the highlighted fields. = Un élément du formulaire n'est pas valide. Vérifiez les champs signalés.
+- Couldn't revoke the key. Try again in a moment. = Impossible de révoquer la clé. Réessayez dans un instant.
+- That key no longer exists. = Cette clé n'existe plus.
+- Manage API keys = Gérer les clés d'API

features/container_update_guidance.feature

@@ -0,0 +1,87 @@
+Feature: Container-aware update guidance
+
+  As the owner of a RenewCMS site running in Docker
+  I want Settings to say "update by pulling a new image" instead of "Not prepared"
+  So that I never see a browser-update flow that cannot work in a container
+
+  Background:
+    Given browser updates need Linux with systemd and the helper that "renewcms enable-browser-updates" configures
+    And a binary replaced inside a container is lost when the container is recreated,
+      so in a container the update is a new image: "docker compose pull && docker compose up -d"
+    And config.Settings gains Container bool, read from the env var RENEWCMS_CONTAINER (default "false", set to "true" by the Dockerfile and docker-compose.yml)
+    And RENEWCMS_CONTAINER is added to envDefaults in cmd/server/main.go, to .env.example and to docs/configuration.md; it is not in requiredEnvVars
+    And only "true" (case-insensitive) enables container mode; any other value means false
+    And the update status use case receives the bool through its constructor from api/dependecyInjection.go; internal/domain/update stays stdlib only
+    And the update check, update-status.json and the release feed work unchanged in container mode
+    And GET /v1/system/update gains a 13th key, container (bool), after started_at; the other 12 keys are unchanged
+    And in container mode can_apply is false for everyone, even if update-helper.json exists in the data directory
+    And POST /v1/system/update/download and /restart keep their guards and answer 409 because can_apply is false (existing behaviour, not re-specified)
+    And errors stay plain text from http.Error
+    And the user approved the copy below and the 13th key on 2026-10-05; docs/design is read-only for agents, so the design files are updated by the user, and the visual gate for container states stays PENDING until a board frame exists
+
+  Scenario Outline: The status carries the container flag
+    Given RENEWCMS_CONTAINER is "<value>"
+    When a verified user sends GET /v1/system/update
+    Then the JSON key container is <flag>
+
+    Examples:
+      | value | flag  |
+      | true  | true  |
+      | TRUE  | true  |
+      | false | false |
+      |       | false |
+      | yes   | false |
+
+  Scenario: Container mode disables apply even with a helper
+    Given RENEWCMS_CONTAINER is "true" and HelperDetector reports the helper installed
+    When the owner sends GET /v1/system/update
+    Then can_apply is false and container is true
+    And a newer stored result still reports available true, latest and notes
+
+  Scenario: The check still works in a container
+    Given container mode and a feed that reports "v2.9.0-beta" newer than the running "v2.8.0-beta"
+    When the owner sends POST /v1/system/update/check
+    Then the status is 200 and available is true and the result is stored in update-status.json
+
+  Scenario Outline: Download and restart are refused in a container
+    Given container mode and a stored newer release
+    When the owner sends POST <path>
+    Then the status is 409 and no job starts and the fetcher and the restart request writer are not called
+
+    Examples:
+      | path                        |
+      | /v1/system/update/download  |
+      | /v1/system/update/restart   |
+
+  Scenario: Host installs are unchanged
+    Given RENEWCMS_CONTAINER is unset
+    Then container is false and can_apply follows the helper as before
+    And "Not prepared" still shows its "renewcms enable-browser-updates" command
+
+  Scenario: Settings, owner, container, update available (route /settings)
+    Given GET /v1/system/update resolves available true, container true, can_apply false, latest "v2.9.0-beta"
+    Then the block uses the "Not prepared" frame's layout: icon info, tone info
+    And the title reads "Version 2.9.0-beta is available"
+    And the text reads "You have v2.8.0-beta. This site runs in Docker, so it updates by pulling a new image. Run the commands below on the server."
+    And a server-command block reads "docker compose pull && docker compose up -d" with the Copy button ("Copied" with a check for 2 s, announced)
+    And a link "How to update" with arrow-up-right points to docs/docker.md
+    And no Update, Restart or "Check for updates" button is rendered
+    And the "renewcms enable-browser-updates" command and its note are not rendered
+
+  Scenario: Settings, owner, container, up to date
+    Given container true and available false
+    Then "You're up to date" shows as in the existing Up to date state, the Restart button is not rendered and the container hint is not rendered
+    And "Check for updates" is still offered
+
+  Scenario: Settings, admin, container
+    Given the session role is "admin", container true and available true
+    Then the existing Admin view shows unchanged ("Only the owner can update RenewCMS.") with no command block
+
+  Scenario: Settings, non-container, no helper
+    Given container false and can_apply false
+    Then the existing "Not prepared" state shows unchanged
+
+  Scenario: The shipped Docker setup turns container mode on
+    Given the Dockerfile and docker-compose.yml
+    Then both set RENEWCMS_CONTAINER=true
+    And docs/docker.md and docs/configuration.md describe the variable

features/container_update_guidance.qa.md

@@ -0,0 +1,25 @@
+# QA: Container update guidance
+
+## Automated (Go, test/, httptest)
+1. Fakes: in-memory update status store, fake FeedClient, fake HelperDetector, fake JobStore and restart writer, validator.InitValidator(). Mount NewSystemRouter on a fresh chi.NewRouter() with jwtauth.Verifier + Authenticator and a test jwtauth.New("HS256", ...).
+2. Parse RENEWCMS_CONTAINER through config.NewSettingsFromEnv with t.Setenv over the table in the feature (true, TRUE, false, empty, yes).
+3. GET status: container key present and equal to the table; the other 12 keys are unchanged.
+4. Container true with a helper present: can_apply false for the owner.
+5. POST check in container mode: 200, available true, stored.
+6. POST download and restart in container mode: 409, no fake called.
+7. Container false: the existing updates_* tests still pass.
+8. An admin receives can_apply false and container true.
+
+## SPA (Vitest, mocked /v1)
+- Container + available: the block, command, Copy, "How to update", and no buttons. Reuse the "Not prepared" sample data from the board.
+- Container + up to date: no Restart.
+- Admin: the existing admin view.
+- Non-container "Not prepared": unchanged.
+- Visual: container states are PENDING until a board frame exists; report as PENDING, never as passing. Existing states must still pass `task visual:check -- settings`.
+
+## Manual (real Docker, ./docker-compose.yml)
+1. `docker compose up -d --build`; confirm RENEWCMS_CONTAINER=true with `docker compose exec renewcms env`.
+2. Point UPDATE_FEED_URL at a feed with a newer release; log in as owner; /settings shows the container block, no Update or Restart.
+3. The Copy button puts the exact command on the clipboard.
+4. Run the shown command on a host that has a newer image; Settings shows the new version afterwards.
+5. Run the binary on the host without the variable: "Not prepared" shows the old command.

features/docker-deployment.feature

@@ -0,0 +1,45 @@
+Feature: Docker deployment
+  RenewCMS can run in a container built from the repository. The container
+  reuses the existing configuration contract in cmd/server/main.go
+  (requiredEnvVars, envDefaults); no new variables are introduced.
+
+  Background:
+    Given the image is built with the default build, without the nofrontend tag
+    And the container runs the binary directly as PID 1 under a non-root user
+    And the environment sets DB_FILE and UPLOAD_DIR to paths on a named volume
+    And the required variables PUBLIC_URL, JWT_SECRET, SMTP_LOGIN, SMTP_SENDER, SMTP_PASSWORD, SMTP_HOST and SMTP_PORT come from an env file at runtime
+
+  Scenario: Healthy start
+    When the container starts with every required variable set
+    Then it logs "RenewCMS <version> (production) listening on :8080"
+    And GET /healthz on the published port returns 200 with the body "ok"
+
+  Scenario: Frontend and API are both served
+    When the container is running
+    Then GET / returns 200 with the SPA index.html
+    And GET /v1/auth/registration returns 200 with a JSON body
+
+  Scenario Outline: A missing required variable stops the container
+    When the container starts without <variable>
+    Then the process exits with a non-zero status
+    And the log contains "Environment variable <variable> is not set"
+
+    Examples:
+      | variable      |
+      | PUBLIC_URL    |
+      | JWT_SECRET    |
+      | SMTP_LOGIN    |
+      | SMTP_SENDER   |
+      | SMTP_PASSWORD |
+      | SMTP_HOST     |
+      | SMTP_PORT     |
+
+  Scenario: Data survives container recreation
+    Given an account was registered while the container was running
+    When the container is removed and recreated on the same named volume
+    Then the same account can log in
+
+  Scenario: Graceful shutdown on SIGTERM
+    When the container receives SIGTERM
+    Then the log contains "shutting down..."
+    And the container exits with status 0 within 10 seconds

features/docker-deployment.qa.md

@@ -0,0 +1,98 @@
+# QA: Docker deployment
+
+Packaging and docs only. There is no Go test in test/ and no Vitest spec for this slice. All steps are manual command steps run from a clean checkout on a machine with Docker and Compose v2. Record results in the Notes table. Anything not run is reported NOT RUN, never PASS.
+
+## Preconditions
+- Clean checkout, no bin/, tmp/, node_modules or internal/infrastructure/assets/dist present.
+- docker.env created from docker.env.example. JWT_SECRET is generated (openssl rand -hex 32) and SMTP values are real or placeholders. Nothing is committed.
+- For local HTTP trial, ENVIRONMENT=development (otherwise the Secure cookie is not stored over HTTP).
+
+## Static checks (no Docker daemon needed)
+1. Dockerfile, .dockerignore and docker-compose.yml contain no comment lines (no line starting with `#`, no trailing ` #`).
+2. .dockerignore lists tmp/, bin/, node_modules (also web/node_modules), .git, internal/infrastructure/assets/dist, .env and docker.env.
+3. Dockerfile: three stages (bun, go, final). The Go build sets CGO_ENABLED=0, has no `-tags nofrontend`, and uses `-ldflags` containing `-X main.version=` from a build arg. The final stage has USER non-root, exec-form ENTRYPOINT (no `sh -c`), and no ENV, ARG or COPY holding JWT_SECRET or any SMTP_* value.
+4. docker-compose.yml: one service, a named volume mounted at the data directory, a `ports` entry, `env_file`, a healthcheck on /healthz, `stop_grace_period` >= 15s.
+5. git diff --stat shows no change under api/, internal/, web/src/, cmd/ and test/. Only Dockerfile, .dockerignore, docker-compose.yml, docker.env.example, Taskfile.yml, .gitignore, README.md and docs/ changed. No new env var appears in cmd/server/main.go.
+6. docs/docker.md exists and is linked from README.md and docs/deployment.md.
+7. `task --list` shows docker:build, docker:run, docker:up, docker:down and docker:logs.
+
+## Build
+8. `task docker:build` succeeds from the clean checkout, with no pre-built SPA.
+9. `docker run --rm <image> --version` prints the version, which is not `dev`.
+10. `docker image ls` size recorded. Flag it if it is above roughly 40 MB.
+11. `docker image inspect` shows a non-root User, and `docker run --rm --entrypoint id <image>` shows uid not 0.
+12. `docker history --no-trunc <image>` contains none of the values in docker.env.
+
+## Run
+13. `task docker:up` starts the service. `docker compose ps` shows it healthy within the healthcheck start period.
+14. `curl -i http://localhost:8080/healthz` returns 200 and body `ok`.
+15. `curl -i http://localhost:8080/` returns 200 text/html, and the SPA loads in a browser.
+16. `curl -i http://localhost:8080/v1/auth/registration` returns 200 with JSON.
+17. Logs show the listening line, and no permission error creating DB_FILE or UPLOAD_DIR on the volume.
+18. Register an account in the SPA, then upload an image, to confirm both the DB and UPLOAD_DIR are writable by the container user.
+
+## Persistence
+19. `docker compose down` (no -v), then `task docker:up`. The account from step 18 can log in and the image is still served.
+20. `docker compose down -v` removes the volume, and the next start gives an empty instance. Documented in docs/docker.md.
+21. The backup procedure in docs/docker.md is followed once and restores into a fresh volume.
+
+## Failure and shutdown
+22. For each required variable in turn, remove it from the env file and run `docker compose up`. The container exits non-zero and the log contains `Environment variable <NAME> is not set`.
+23. `docker compose stop` (timed) completes in under 10 s, the log contains `shutting down...`, and the exit code is 0. This proves PID 1 receives SIGTERM.
+24. Break the healthcheck (stop the app inside the container, or point it at the wrong port): the service becomes unhealthy.
+
+## SMTP (manual, needs real SMTP)
+25. With an external SMTP host, trigger a registration or password-reset email and confirm delivery.
+26. With a host MTA via host.docker.internal, repeat. On Linux this needs the extra_hosts mapping documented.
+27. Confirm the failure mode is documented when SMTP is unreachable.
+
+## Reverse proxy and TLS (manual)
+28. Put Caddy or nginx in front, per docs/docker.md, with ENVIRONMENT=production over HTTPS. Log in and confirm the Secure cookie is accepted.
+29. Set TRUSTED_PROXIES to the proxy address as seen by the container and confirm the login rate limiter uses X-Real-IP.
+
+## Upgrade
+30. Follow docs/docker.md: back up, rebuild with `task docker:build`, `task docker:up`. Data is intact and `--version` shows the new version.
+31. Confirm docs state that browser-update Restart is unsupported in Docker (Settings shows "Not prepared").
+
+## Notes to record
+| Item | Value |
+| --- | --- |
+| Image size | |
+| Base images and tags used | |
+| Container uid | |
+| Build time (cold) | |
+| Docker and Compose versions | |
+| Steps 25-29 run? | |
+
+Not run in this slice: CI, registry publishing, Kubernetes or Helm, multi-arch. SPA tests and visual checks are out of scope.
+
+## Results
+Run on Windows 11, Docker 29.8.1, Compose 5.5.1, with a throwaway docker.env (fake secrets, ENVIRONMENT=development) that was deleted afterwards.
+
+| Steps | Result |
+| --- | --- |
+| 1-7, 31 | PASS |
+| 8 | PASS after a fix: `bun run build` failed in the image because vue-tsc cannot resolve .vue modules under the Bun-only node fallback; the Dockerfile now runs `bun run build-only`. vue-tsc passes on the host and under real node 22 |
+| 9, 11, 12 | PASS (version v2.8.0-beta-dirty, uid 10001, entrypoint exec form, no secret names in history) |
+| 10 | 54.5 MB, above the 40 MB flag (binary 29.9 MB on alpine 3.22) |
+| 13-17 | PASS (healthy, /healthz 200 ok, / 200 text/html, /v1/auth/registration 200 JSON, no permission errors) |
+| 18-19 | PASS (register, verify, login, image upload to /data/uploads as uid 10001; all survive `down` and recreate; uploaded image still served) |
+| 20 | PASS (`down -v` removed the volume) |
+| 21 | PASS (tar backup, `down -v`, restore, login and media list intact) |
+| 22 | PASS for all 7 vars (exit 2, `Environment variable X is not set`) |
+| 23 | PASS (stop 0.4 s, exit 0, `shutting down...` logged) |
+| 24 | PASS (wrong-port healthcheck reports unhealthy) |
+| 25 | PARTIAL: mail delivered over STARTTLS to a Mailpit container on the compose network with the CA trusted via SSL_CERT_FILE; no real external host |
+| 26-29 | NOT RUN (host MTA, Caddy/nginx TLS, TRUSTED_PROXIES) |
+| 30 | NOT RUN as a before/after upgrade |
+| `task docker:run` | PASS (healthz 200, graceful stop, separate volume renewcms-data) |
+
+Notes
+| Item | Value |
+| --- | --- |
+| Image size | 54.5 MB |
+| Base images and tags used | oven/bun:1-alpine, golang:1.27.1-alpine, alpine:3.22 |
+| Container uid | 10001 |
+| Build time (cold) | not measured, layers were partly cached; about 18 s warm |
+| Docker and Compose versions | 29.8.1, 5.5.1 |
+| Steps 25-29 run? | 25 partial, 26-29 no |

features/docker_image_publishing.feature

@@ -0,0 +1,71 @@
+Feature: Publish the RenewCMS image to a registry so an upgrade is "docker compose pull"
+
+  As a maintainer
+  I want one task that builds and pushes a versioned multi-arch image
+  So that site operators upgrade with "docker compose pull && docker compose up -d" and never build from source
+
+  Background:
+    Given there is no CI pipeline on purpose; publishing is a maintainer-run task, like "task release"
+    And the registry is the Gitea registry of git.floriansylvain.fr and REGISTRY_IMAGE defaults to "git.floriansylvain.fr/fsylvain/renewcms"
+    And the Dockerfile and docker-compose.yml from docker-deployment exist and are unchanged except where stated here
+    And Taskfile.yml gains "docker:publish", with variables REGISTRY_IMAGE and VERSION (default: git describe --tags)
+    And "docker:publish" refuses to run, before building anything, when REGISTRY_IMAGE is empty, when VERSION is not an exact tag "vX.Y.Z" or "vX.Y.Z-<pre>", or when the work tree is dirty
+    And the build is "docker buildx build --platform linux/amd64,linux/arm64 --build-arg VERSION=<tag>"; the tag is baked in through the existing version ldflags path, so the image's "renewcms --version" prints the tag
+    And tags pushed for vX.Y.Z-<pre>: "vX.Y.Z-<pre>" and "X.Y.Z-<pre>" and the moving tag "<pre-name>" (for example "beta"); "latest" is NOT moved
+    And tags pushed for vX.Y.Z: "vX.Y.Z", "X.Y.Z", "X.Y", and "latest"
+    And the maintainer authenticates beforehand with "docker login git.floriansylvain.fr"; the task never reads, stores or echoes a password or token, and never passes credentials on a command line
+    And no secret, .env, signing key or JWT_SECRET is copied into the image (already enforced by .dockerignore; checked again here)
+    And no image signing or attestation is part of this slice; the Ed25519 key signs release binaries only
+    And "task docker:publish -- --dry-run" builds for the host platform only with "--load", pushes nothing, needs no login and prints the tags it would push
+    And docker-compose.yml uses "image: ${RENEWCMS_IMAGE:-git.floriansylvain.fr/fsylvain/renewcms:beta}" (the default tag is "beta" because "latest" does not exist until the first stable release; it is changed to "latest" then) and its "build:" block moves to docker-compose.build.yml, used as "docker compose -f docker-compose.yml -f docker-compose.build.yml up -d --build"
+    And docs/docker.md, docs/deployment.md and README.md document pull-based upgrade, the build override, the tag scheme and the maintainer publish steps; no comments in any file
+    And the real push is a manual item: it needs a registry account and network
+
+  Scenario Outline: Tags for a version
+    Given VERSION is "<version>"
+    When "task docker:publish -- --dry-run" runs
+    Then it prints exactly these tags: <tags>
+
+    Examples:
+      | version      | tags                                  |
+      | v2.9.0       | v2.9.0, 2.9.0, 2.9, latest            |
+      | v2.9.0-beta  | v2.9.0-beta, 2.9.0-beta, beta         |
+      | v2.9.0-rc.1  | v2.9.0-rc.1, 2.9.0-rc.1, rc           |
+
+  Scenario Outline: Refusals before any build
+    Given <condition>
+    When "task docker:publish" runs
+    Then it exits non-zero with a message naming the problem and docker is not invoked
+
+    Examples:
+      | condition                             |
+      | REGISTRY_IMAGE is empty               |
+      | VERSION is "dev"                      |
+      | VERSION is "2.9.0" (no leading v)     |
+      | the work tree has uncommitted changes |
+
+  Scenario: Dry run builds and loads a working image
+    When "task docker:publish -- --dry-run" runs with VERSION "v2.9.0-beta"
+    Then an image is loaded locally for the host platform and no registry is contacted
+    And running it prints "v2.9.0-beta" for --version
+    And it serves GET /healthz as ok with the env from docker.env.example
+    And it runs as the non-root user with the data volume as in docker-deployment
+
+  Scenario: No secrets in the image
+    Given the dry-run image
+    Then "docker history" and a file listing show no .env, no release.key, no JWT_SECRET value and no SMTP password
+
+  Scenario: Compose pulls by default
+    Given docker-compose.yml with RENEWCMS_IMAGE unset
+    Then "docker compose config" shows the image "git.floriansylvain.fr/fsylvain/renewcms:beta" and no build section
+    And with RENEWCMS_IMAGE set to a tag, that tag is used
+    And with docker-compose.build.yml added, the build section is present and the image builds from the local Dockerfile
+
+  Scenario: Upgrade is a pull
+    Given a running stack on tag "v2.8.0-beta" with data in the volume
+    When the operator runs "docker compose pull && docker compose up -d" after a newer tag is pushed
+    Then the container is recreated on the new image and the articles, uploads and database in the volume are intact
+    And GET /v1/settings reports the new version
+
+  Scenario: Docs say the same thing
+    Then docs/docker.md, docs/deployment.md and README.md each show the pull upgrade, the tag scheme and the maintainer flow, and none claims CI exists

features/docker_image_publishing.qa.md

@@ -0,0 +1,29 @@
+# QA: Docker image publishing
+
+Everything runs on the real local Docker daemon, with no registry push. On Windows use MSYS_NO_PATHCONV=1 under Git Bash and put the Docker bin on PATH (memory: docker-windows-gotchas).
+
+## Automated / scripted
+1. Refusals: run "task docker:publish" with REGISTRY_IMAGE empty, VERSION=dev, VERSION=2.9.0, and a dirty tree; assert non-zero exit and that no docker build started (compare "docker buildx ls" and the image list before and after).
+2. Tag table: run "task docker:publish -- --dry-run" with VERSION=v2.9.0, v2.9.0-beta and v2.9.0-rc.1 (the VERSION override is accepted only with --dry-run); compare the printed tags with the feature.
+3. Dry run: the image is loaded; "docker run --rm <image> --version" prints the tag; start the stack from docker.env.example and check GET /healthz is ok, and "docker exec <ctr> id -u" is not 0.
+4. Secrets: "docker history --no-trunc" and a file search for .env and release.key inside the image are clean; grep the layers for the sample JWT_SECRET value.
+5. Compose: "docker compose config" with and without RENEWCMS_IMAGE, and with the build override.
+6. Upgrade simulation: tag two local images v-old and v-new, run the stack on v-old, write an article, switch RENEWCMS_IMAGE to v-new, "docker compose up -d", and verify the article and the new version.
+7. Docs: grep the three docs for "docker compose pull", the tag scheme, and the absence of CI claims.
+8. No credentials: grep Taskfile.yml and docs for token or password literals; the task must not call "docker login".
+
+## Manual (user performs; needs the registry)
+- `docker login git.floriansylvain.fr`; "task docker:publish" with a real tag; confirm "docker buildx imagetools inspect <image>:<tag>" lists linux/amd64 and linux/arm64.
+- On a clean machine, "docker compose pull && docker compose up -d" against the pushed image; confirm /settings shows the new version and the container guidance from container_update_guidance.
+- Confirm the moving "beta" tag points at the intended digest and that "latest" did not move for a prerelease.
+
+## Results
+- 1 Refusals: PASS (coder and hardener runs).
+- 2 Tag table: PASS (v2.9.0, v2.9.0-beta, v2.9.0-rc.1; re-seen with v2.9.0-beta and v2.9.1-beta, tags "vX, X, beta").
+- 3 Dry run: PASS (--version prints the tag, /healthz ok, uid 10001).
+- 4 Secrets: PASS.
+- 5 Compose: PASS.
+- 6 Upgrade simulation: PASS. Local images v2.9.0-beta and v2.9.1-beta, stack on the old tag, register + verify (mail captured over TLS by Mailpit) + login, article created (201), RENEWCMS_IMAGE switched, "docker compose up -d" recreated the container on the same volume. Old cookie still accepted, login 200, article 1 intact, GET /v1/settings reports v2.9.1-beta (was v2.9.0-beta).
+- 7 Docs: PASS.
+- 8 No credentials: PASS.
+- Manual items: NOT RUN (need the registry): docker login, real multi-arch push and imagetools inspect, "docker compose pull" against the pushed image, moving beta/latest tag checks, builder failure paths of a real run.

features/image-variants.feature

@@ -0,0 +1,778 @@
+Feature: Image variants are generated on first request, cached, and managed by admins
+
+  As an admin or owner of a RenewCMS site
+  I want to define named variants of the original images and have them generated and cached on demand
+  So that articles can ask for /static/uploadedImages/<storedName>?v=<name> and get a right-sized file,
+    the original is never changed, and nothing but a defined, enabled variant can be requested
+
+  Background:
+    Given the spec of record is docs/design/screens/image-variants.md sections 1, 2 and 7, its "Back-office API errors" table and section 8 for the activity rows
+    And this slice is API only: no SPA code, no change to docs/design
+    And it excludes the design's cache screen routes (GET /v1/image-variants/cache, POST /v1/image-variants/cache/purge), the per-image routes (/v1/media/{id}/variants...) and the media library variants filter and sort
+    And internal/domain/image gains the entity Variant with the JSON fields name, width, height, fit, format, quality, generate_on_upload, enabled, created_at and updated_at in snake_case
+    And Variant.Name is a slug of 2 to 32 characters among a-z, 0-9 and "-", unique and immutable after creation
+    And Variant.Width and Variant.Height are 1 to 8000 pixels or absent (JSON null, "auto" in the design), and at least one is present
+    And Variant.Fit is one of cover, contain, inside, and defaults to cover
+    And Variant.Format is one of original, jpeg, png, webp, and defaults to original
+    And Variant.Quality is 1 to 100 and defaults to 82; for format png it is not stored and is returned as null, and a quality sent with png is ignored
+    And generate_on_upload defaults to false and enabled defaults to true
+    And internal/domain/image defines the sentinels ErrVariantNotFound, ErrVariantExists, ErrVariantInvalid, ErrUnknownVariant, ErrUnsupportedParameter and ErrSourceTooLarge, asserted with errors.Is
+    And internal/domain/image defines the port VariantRepository (variants CRUD) and the port VariantFileRepository, an index of generated files holding variant name, source stored name, cached stored name, content type, size in bytes and the settings fingerprint, because Storage.Put chooses the stored name itself
+    And internal/domain/image defines the port VariantRenderer, implemented in internal/infrastructure and kept free of GORM and HTTP, which decodes a source and encodes a variant, and reports which output formats it can encode
+    And generated bytes are stored only through image.Storage, are named by Storage.Put like any stored image, and are never reachable as library images
+    And the use cases (create, update, set enabled, delete, purge, list variants, serve variant) depend only on domain interfaces
+    And the variant routes are mounted at /v1/image-variants behind jwtauth.Verifier, middleware.AuditContext, jwtauth.Authenticator, middleware.RequireCurrentToken, middleware.RequireVerifiedUser and middleware.RequireOwnerOrAdmin, with no API key authentication
+    And request bodies are validated with validate tags and validator.Validate.Struct, never by hand
+    And successful responses are JSON with snake_case fields, and error responses on /v1 are plain text from http.Error, except the public 400 described below
+    And a variant is returned as {"name", "width", "height", "fit", "format", "quality", "generate_on_upload", "enabled", "generated_files", "cache_size", "created_at", "updated_at"}, with cache_size in bytes
+    And the variant list is ordered by name ascending
+    And the contain padding colour is decided here: transparent for png and webp outputs, and white (#FFFFFF) for jpeg outputs, which carry no alpha
+    And a jpeg output flattens any transparency of the source onto white (#FFFFFF)
+    And a new env var IMAGE_VARIANT_MAX_SOURCE_BYTES, default 10485760, is listed in envDefaults in cmd/server/main.go (not in requiredEnvVars), in .env.example and in docs/configuration.md
+    And a new env var IMAGE_VARIANT_MAX_SOURCE_PIXELS, default 50000000, caps the declared width x height of a source, read from the image header before any pixel buffer is allocated, and is listed in the same three places
+    And a new env var IMAGE_VARIANT_MAX_CONCURRENT_RENDERS, default 4, bounds the renders running at once, with waiting requests queued until a slot frees or their context ends, and is listed in the same three places
+    And contain always pads to the box when both width and height are given: the image is scaled to fit inside the box, never enlarged, and centred on a canvas of exactly width x height; with a single dimension there is no box and no padding
+    And the first implementation task is a spike of a CGO-free lossy WebP encoder with CGO_ENABLED=0
+    And the public serving path stays /static/uploadedImages/<storedName>, mounted in api/router.go, and is outside /v1 and outside any auth
+
+  Rule: Only owners and admins reach the variant routes
+
+    Scenario Outline: Every variant route is guarded
+      When the client sends <method> <path> with <credentials>
+      Then the response status is <status>
+      And the plain text body is <body>
+      And no variant, generated file or activity event is read or changed
+
+      Examples:
+        | method | path                        | credentials                    | status | body                                         |
+        | GET    | /v1/image-variants          | no cookie                      | 401    | apperr.UnauthorizedErrorMessage              |
+        | GET    | /v1/image-variants          | a stale token_version cookie   | 401    | apperr.UnauthorizedErrorMessage              |
+        | GET    | /v1/image-variants          | the cookie of an unverified user| 403   | apperr.VerificationRequiredErrorMessage      |
+        | GET    | /v1/image-variants          | the cookie of a plain user     | 403    | apperr.OwnerOrAdminRequiredErrorMessage      |
+        | POST   | /v1/image-variants          | the cookie of a plain user     | 403    | apperr.OwnerOrAdminRequiredErrorMessage      |
+        | PUT    | /v1/image-variants/hero     | the cookie of a plain user     | 403    | apperr.OwnerOrAdminRequiredErrorMessage      |
+        | PATCH  | /v1/image-variants/hero     | the cookie of a plain user     | 403    | apperr.OwnerOrAdminRequiredErrorMessage      |
+        | DELETE | /v1/image-variants/hero     | the cookie of a plain user     | 403    | apperr.OwnerOrAdminRequiredErrorMessage      |
+        | POST   | /v1/image-variants/hero/purge | the cookie of a plain user   | 403    | apperr.OwnerOrAdminRequiredErrorMessage      |
+        | GET    | /v1/image-variants          | a valid API key                | 401    | apperr.UnauthorizedErrorMessage              |
+
+    Scenario Outline: Owners and admins are both allowed
+      When <role> sends GET /v1/image-variants with a valid cookie
+      Then the response status is 200
+
+      Examples:
+        | role         |
+        | the owner    |
+        | an admin     |
+
+  Rule: Listing
+
+    Scenario: An empty list is an empty array
+      Given no variant exists
+      When an admin sends GET /v1/image-variants
+      Then the response status is 200
+      And the body is {"items": []}, with items an empty array and not null in the raw JSON
+
+    Scenario: The list carries the generated count and cache size per variant
+      Given the variants "hero" (cover 1200x630 webp 82, enabled) and "card" (inside 800 x auto jpeg 80, disabled)
+      And the cache index holds 3 generated files of 1000, 2000 and 3000 bytes for "hero" and none for "card"
+      When an admin sends GET /v1/image-variants
+      Then "items" is ordered "card", "hero"
+      And "card" has width 800, height null, fit "inside", format "jpeg", quality 80, enabled false, generated_files 0 and cache_size 0
+      And "hero" has width 1200, height 630, fit "cover", format "webp", quality 82, enabled true, generated_files 3 and cache_size 6000
+
+    Scenario: A png variant lists a null quality
+      Given the variant "logo" with format png
+      When an admin sends GET /v1/image-variants
+      Then "logo" has quality null
+
+  Rule: Creating a variant
+
+    Scenario: Creating a variant with every field
+      When an admin sends POST /v1/image-variants with {"name": "hero", "width": 1200, "height": 630, "fit": "cover", "format": "webp", "quality": 82, "generate_on_upload": true, "enabled": true}
+      Then the response status is 201
+      And the body is the variant with generated_files 0 and cache_size 0
+      And exactly one variant "hero" is stored
+
+    Scenario: Omitted optional fields take their defaults
+      When an admin sends POST /v1/image-variants with {"name": "thumb", "width": 400}
+      Then the response status is 201
+      And the body has width 400, height null, fit "cover", format "original", quality 82, generate_on_upload false and enabled true
+
+    Scenario Outline: A valid boundary value is accepted
+      When an admin sends POST /v1/image-variants with <body>
+      Then the response status is 201
+
+      Examples:
+        | body                                                    |
+        | {"name": "ab", "width": 1}                              |
+        | {"name": "a-b-c", "height": 8000}                       |
+        | {"name": "<32 characters a-z0-9->", "width": 8000, "height": 8000} |
+        | {"name": "q1", "width": 10, "quality": 1}               |
+        | {"name": "q100", "width": 10, "quality": 100}           |
+
+    Scenario Outline: An invalid field answers 422 with the field's sentence and stores nothing
+      When an admin sends POST /v1/image-variants with <body>
+      Then the response status is 422
+      And the plain text body is "<message>"
+      And no variant is stored and no activity event is recorded
+
+      Examples:
+        | body                                         | message                                                               |
+        | {"name": "a", "width": 10}                   | Use lowercase letters, numbers and dashes, 2 to 32 characters.        |
+        | {"name": "<33 characters>", "width": 10}     | Use lowercase letters, numbers and dashes, 2 to 32 characters.        |
+        | {"name": "Hero", "width": 10}                | Use lowercase letters, numbers and dashes, 2 to 32 characters.        |
+        | {"name": "he ro", "width": 10}               | Use lowercase letters, numbers and dashes, 2 to 32 characters.        |
+        | {"name": "hero"}                             | Width and height must be between 1 and 8000, and one of them is required. |
+        | {"name": "hero", "width": 0}                 | Width and height must be between 1 and 8000, and one of them is required. |
+        | {"name": "hero", "width": 8001}              | Width and height must be between 1 and 8000, and one of them is required. |
+        | {"name": "hero", "height": -1}               | Width and height must be between 1 and 8000, and one of them is required. |
+        | {"name": "hero", "width": 10, "fit": "stretch"}  | Fit must be cover, contain or inside.                             |
+        | {"name": "hero", "width": 10, "format": "avif"}  | Format must be original, jpeg, png or webp.                       |
+        | {"name": "hero", "width": 10, "quality": 0}      | Quality must be between 1 and 100.                                |
+        | {"name": "hero", "width": 10, "quality": 101}    | Quality must be between 1 and 100.                                |
+
+    Scenario Outline: A malformed request answers 400
+      When an admin sends POST /v1/image-variants with <body>
+      Then the response status is 400
+      And the plain text body is apperr.BodyErrorMessage
+
+      Examples:
+        | body                       |
+        | not json                   |
+        | {"name": "hero", "width": "wide"} |
+        | an empty body              |
+
+    Scenario: A duplicate name answers 409 and keeps the existing variant
+      Given the variant "thumb" 400 x 300 cover jpeg quality 80
+      When an admin sends POST /v1/image-variants with {"name": "thumb", "width": 800, "format": "png"}
+      Then the response status is 409
+      And the plain text body is "A variant named “thumb” already exists. Choose another name."
+      And the stored variant "thumb" is unchanged
+
+  Rule: Updating a variant
+
+    Background:
+      Given the variant "hero" is 1200x630 cover webp quality 82, enabled, with generate_on_upload false
+      And the cache index holds 244 generated files for "hero" (84 MB) and 3 generated files for "thumb"
+
+    Scenario: Changing quality updates the variant and purges its generated files
+      When an admin sends PUT /v1/image-variants/hero with {"width": 1200, "height": 630, "fit": "cover", "format": "webp", "quality": 70, "generate_on_upload": false, "enabled": true}
+      Then the response status is 200
+      And the body is the variant with quality 70, generated_files 0, cache_size 0 and "purged_files": 244
+      And the 244 cached blobs of "hero" are deleted from image.Storage and their index rows are gone
+      And the files of "thumb" are untouched
+
+    Scenario Outline: A change to a rendering setting purges
+      When an admin sends PUT /v1/image-variants/hero changing <setting> to <value>, everything else as stored
+      Then the response status is 200
+      And "purged_files" is 244
+
+      Examples:
+        | setting | value   |
+        | width   | 1000    |
+        | height  | null    |
+        | fit     | inside  |
+        | format  | jpeg    |
+        | quality | 60      |
+
+    Scenario Outline: A change to a switch does not purge
+      When an admin sends PUT /v1/image-variants/hero changing <setting> to <value>, everything else as stored
+      Then the response status is 200
+      And "purged_files" is 0 and generated_files is still 244
+      And no blob is deleted
+
+      Examples:
+        | setting            | value |
+        | generate_on_upload | true  |
+        | enabled            | false |
+
+    Scenario: A PUT identical to the stored variant changes nothing
+      When an admin sends PUT /v1/image-variants/hero with the stored values
+      Then the response status is 200 and "purged_files" is 0
+      And updated_at is unchanged and no activity event is recorded
+
+    Scenario: Switching the format to png drops the quality and purges
+      When an admin sends PUT /v1/image-variants/hero with format "png" and quality 40
+      Then the response status is 200 and quality is null and "purged_files" is 244
+
+    Scenario: Changing the quality of a png variant is a no-op
+      Given the variant "logo" with format png
+      When an admin sends PUT /v1/image-variants/logo with the same values and quality 30
+      Then "purged_files" is 0 and quality is still null
+
+    Scenario: The name is immutable
+      When an admin sends PUT /v1/image-variants/hero with {"name": "banner", "width": 1200, "height": 630}
+      Then the stored variant is still named "hero" and no variant "banner" exists
+
+    Scenario Outline: An invalid PUT answers like a create and changes nothing
+      When an admin sends PUT /v1/image-variants/hero with <body>
+      Then the response status is 422 and the stored variant and its 244 generated files are unchanged
+
+      Examples:
+        | body                                       |
+        | {"quality": 101}                           |
+        | {"width": null, "height": null}            |
+        | {"width": 9000}                            |
+        | {"fit": "stretch"}                         |
+
+    Scenario: An unknown variant answers 404
+      When an admin sends PUT /v1/image-variants/missing with a valid body
+      Then the response status is 404 and the plain text body is "Variant not found"
+
+  Rule: Enabling and disabling
+
+    Scenario Outline: PATCH toggles enabled and keeps the cache
+      Given the variant "hero" has enabled <before> and 244 generated files
+      When an admin sends PATCH /v1/image-variants/hero with {"enabled": <after>}
+      Then the response status is 200 and the body has enabled <after> and generated_files 244
+      And no blob is deleted
+
+      Examples:
+        | before | after |
+        | true   | false |
+        | false  | true  |
+
+    Scenario Outline: A PATCH that is not valid or not found
+      When an admin sends PATCH /v1/image-variants/<name> with <body>
+      Then the response status is <status>
+
+      Examples:
+        | name    | body              | status |
+        | hero    | not json          | 400    |
+        | hero    | {}                | 422    |
+        | hero    | {"enabled": "no"} | 400    |
+        | missing | {"enabled": true} | 404    |
+
+  Rule: Deleting a variant and purging its cache
+
+    Scenario: Deleting removes the definition and its generated files
+      Given the variant "hero" with 244 generated files and the variant "thumb" with 3
+      When an admin sends DELETE /v1/image-variants/hero
+      Then the response status is 204 with an empty body
+      And "hero" is gone, its 244 blobs are deleted from image.Storage and its index rows are gone
+      And "thumb" and its 3 files are untouched
+
+    Scenario: Purging removes only the generated files
+      Given the variant "hero" with 244 generated files of 84 MB in total
+      When an admin sends POST /v1/image-variants/hero/purge
+      Then the response status is 200 and the body is {"purged_files": 244, "purged_bytes": <total bytes>}
+      And the variant "hero" still exists unchanged and GET /v1/image-variants shows generated_files 0 and cache_size 0
+
+    Scenario: Purging an empty cache answers zero
+      When an admin sends POST /v1/image-variants/hero/purge and "hero" has no generated file
+      Then the response status is 200 and the body is {"purged_files": 0, "purged_bytes": 0}
+
+    Scenario Outline: An unknown variant answers 404
+      When an admin sends <method> /v1/image-variants/missing<suffix>
+      Then the response status is 404 and the plain text body is "Variant not found"
+
+      Examples:
+        | method | suffix |
+        | DELETE |        |
+        | POST   | /purge |
+
+    Scenario: A blob that cannot be deleted keeps its index row and the call fails
+      Given the variant "hero" with 3 generated files and image.Storage failing to delete the second one
+      When an admin sends POST /v1/image-variants/hero/purge
+      Then the response status is 500 with the body "Internal server error"
+      And the 2 other files are deleted and the failing file keeps its index row so that a retry can finish
+
+    Scenario: A blob already missing from storage does not stop a purge
+      Given the variant "hero" with an index row whose blob no longer exists
+      When an admin sends POST /v1/image-variants/hero/purge
+      Then the response status is 200 and the row is removed
+
+    Scenario: Deleting a source image purges its generated files
+      Given the image "north-wall.jpg" with generated files for "hero" and "thumb"
+      When an admin sends DELETE /v1/media/<its id>
+      Then the response status is 204 and the generated blobs and index rows of that image are gone
+      And the generated files of other images are untouched
+
+    Scenario: Merging copies purges the generated files of the removed copies
+      Given the images 5, 6 and 7 share one hash and 6 and 7 each have generated files
+      When an admin sends POST /v1/media/merge keeping 5 and merging [6, 7]
+      Then the generated blobs and rows of images 6 and 7 are gone
+
+  Rule: Public serving of ?v=<name>
+
+    Background:
+      Given the variant "thumb" is cover 400x300 jpeg quality 80 and enabled
+      And the image "photo.png" is stored as "a1b2.png", a 1000 x 800 PNG
+      And no generated file exists yet
+
+    Scenario: The first request generates and caches
+      When the public client sends GET /static/uploadedImages/a1b2.png?v=thumb
+      Then the response status is 200 with the content type "image/jpeg"
+      And the body decodes to a 400 x 300 JPEG
+      And exactly one blob was put in image.Storage for the variant and one index row exists with the same size as the body
+      And the original blob "a1b2.png" is unchanged
+
+    Scenario: The second request serves the cached file without rendering
+      Given GET /static/uploadedImages/a1b2.png?v=thumb was served once
+      When the public client sends the same request again
+      Then the body is byte-identical to the first one
+      And the renderer was called once in total and image.Storage Put was called once in total
+
+    Scenario: A request without ?v= is the unchanged original
+      When the public client sends GET /static/uploadedImages/a1b2.png
+      Then the response is the stored PNG with the same headers as before this slice
+      And the renderer is not called
+
+    Scenario: The ETag derives from the variant settings
+      When the public client sends GET /static/uploadedImages/a1b2.png?v=thumb
+      Then the response has an ETag that is a quoted opaque value
+      And requesting it again returns the same ETag
+      And sending If-None-Match with that ETag answers 304 with an empty body
+
+    Scenario Outline: The ETag changes when a setting changes and stays when a switch changes
+      Given the ETag E1 of GET /static/uploadedImages/a1b2.png?v=thumb
+      When an admin changes <setting> of "thumb" to <value>
+      And the public client requests the same URL again
+      Then the new ETag is different from E1: <changes>
+
+      Examples:
+        | setting            | value  | changes |
+        | quality            | 70     | yes     |
+        | width              | 500    | yes     |
+        | height             | 200    | yes     |
+        | fit                | inside | yes     |
+        | format             | png    | yes     |
+        | generate_on_upload | true   | no      |
+
+    Scenario: A stale If-None-Match after an edit gets a fresh 200
+      Given the client holds E1 and the admin changed the quality of "thumb"
+      When the client sends If-None-Match E1
+      Then the response is 200 with the regenerated file and a new ETag
+
+    Scenario: Editing a variant regenerates on the next request
+      Given GET ...?v=thumb was served once
+      When an admin changes the quality of "thumb" from 80 to 70
+      And the public client requests the same URL
+      Then a new blob is generated and the previous blob was deleted from image.Storage
+
+    Scenario: A cached file that vanished from storage is generated again
+      Given the index row for "thumb" and "a1b2.png" exists but image.Storage reports ErrBlobNotFound for it
+      When the public client requests GET ...?v=thumb
+      Then the response is 200 with a freshly generated file and the index row points to the new blob
+
+    Scenario: Concurrent first requests generate once
+      When 20 concurrent clients send GET /static/uploadedImages/a1b2.png?v=thumb
+      Then every response is 200 with identical bytes
+      And the renderer was called once and image.Storage Put was called once (singleflight keyed by variant and image)
+
+    Scenario: Different variants and different images are not serialised together
+      Given the variant "card" and the image "c3d4.png"
+      When the four (variant, image) pairs are requested concurrently while each render blocks
+      Then all four renders are in flight at the same time
+
+    Scenario: A failed generation is not cached and is retried
+      Given the renderer fails for the first call
+      When the public client requests GET ...?v=thumb twice
+      Then the first response is 500 and no blob or row exists
+      And the second response is 200
+
+    Rule: Unknown, disabled and raw parameters
+
+      Scenario Outline: A request outside the contract answers 400 with the JSON error body
+        When the public client sends GET <url>
+        Then the response status is 400 with the content type "application/json"
+        And the body is {"status": 400, "error": "<error>", "message": "<message>", "detail": "<detail>"}
+        And the renderer is not called and nothing is stored
+
+        Examples:
+          | url                                                     | error                 | message               | detail  |
+          | /static/uploadedImages/a1b2.png?v=banner                | unknown_variant       | Unknown variant       | banner  |
+          | /static/uploadedImages/a1b2.png?v=Thumb                 | unknown_variant       | Unknown variant       | Thumb   |
+          | /static/uploadedImages/a1b2.png?v=                      | unknown_variant       | Unknown variant       |         |
+          | /static/uploadedImages/a1b2.png?v=hero (disabled)       | unknown_variant       | Unknown variant       | hero    |
+          | /static/uploadedImages/a1b2.png?width=400               | unsupported_parameter | Unsupported parameter | width   |
+          | /static/uploadedImages/a1b2.png?height=300              | unsupported_parameter | Unsupported parameter | height  |
+          | /static/uploadedImages/a1b2.png?format=webp             | unsupported_parameter | Unsupported parameter | format  |
+          | /static/uploadedImages/a1b2.png?quality=50              | unsupported_parameter | Unsupported parameter | quality |
+          | /static/uploadedImages/a1b2.png?v=thumb&width=400       | unsupported_parameter | Unsupported parameter | width   |
+          | /static/uploadedImages/a1b2.png?v=banner&quality=50     | unsupported_parameter | Unsupported parameter | quality |
+
+      Scenario: Other query parameters are ignored
+        When the public client sends GET /static/uploadedImages/a1b2.png?v=thumb&t=123
+        Then the response status is 200 with the thumb variant
+
+      Scenario: A disabled variant serves again once enabled, from its kept cache
+        Given the variant "thumb" was served once, then disabled
+        When the public client requests ?v=thumb
+        Then the response is 400 unknown_variant
+        When an admin enables "thumb" and the client requests again
+        Then the response is 200 and image.Storage Put was called once in total
+
+      Scenario: A deleted variant answers 400
+        Given the variant "thumb" is deleted
+        When the public client requests ?v=thumb
+        Then the response is 400 unknown_variant
+
+    Rule: Missing and unreadable sources
+
+      Scenario Outline: A missing source answers 404
+        When the public client sends GET <url>
+        Then the response status is 404 and nothing is generated
+
+        Examples:
+          | url                                           |
+          | /static/uploadedImages/missing.png?v=thumb    |
+          | /static/uploadedImages/../secret.png?v=thumb  |
+          | /static/uploadedImages/nested/a1b2.png?v=thumb|
+
+      Scenario: Parameter errors come before the missing source
+        When the public client sends GET /static/uploadedImages/missing.png?v=banner
+        Then the response status is 400 unknown_variant
+
+      Scenario: A source that cannot be decoded answers 500 and caches nothing
+        Given the stored blob "bad.png" holds bytes that are not an image
+        When the public client requests /static/uploadedImages/bad.png?v=thumb
+        Then the response status is 500 and nothing is stored
+
+      Scenario Outline: Only a source that is a known image record can be a variant source
+        Given the blob "<name>" exists in image.Storage
+        And <record>
+        When the public client requests /static/uploadedImages/<name>?v=thumb
+        Then the response status is <status>
+        And nothing is generated and nothing is stored
+
+        Examples:
+          | name         | record                                            | status |
+          | a1b2.png     | an image record with that stored name exists      | 200    |
+          | gen-1.jpg    | the blob is a generated variant file, with no image record | 404 |
+          | orphan.png   | the blob has no image record                      | 404 |
+
+      Scenario: The record lookup comes after the parameter checks and before any storage read
+        When the public client requests /static/uploadedImages/orphan.png?v=banner
+        Then the response status is 400 unknown_variant
+        And when requested with ?v=thumb the response is 404 and image.Storage Open is not called
+
+      Scenario: The original of any stored blob is still served without ?v=
+        When the public client requests /static/uploadedImages/gen-1.jpg
+        Then the response is the stored bytes as before this slice
+
+    Rule: Source size cap
+
+      Scenario Outline: A source beyond IMAGE_VARIANT_MAX_SOURCE_BYTES answers 413
+        Given IMAGE_VARIANT_MAX_SOURCE_BYTES is 1000
+        And the stored source "big.png" is <size> bytes
+        When the public client requests /static/uploadedImages/big.png?v=thumb
+        Then the response status is <status>
+
+        Examples:
+          | size | status |
+          | 1000 | 200    |
+          | 1001 | 413    |
+
+      Scenario: The 413 body is plain text and nothing is generated
+        Given a source of 1001 bytes with the cap at 1000
+        Then the body is "The source image is too large to generate this variant." and the renderer is not called
+
+      Scenario: The cap never affects the original
+        Given a source of 1001 bytes with the cap at 1000
+        When the public client requests it without ?v=
+        Then the response is 200 with the stored bytes
+
+      Scenario Outline: The env var rejects invalid values at boot
+        When the settings are loaded with IMAGE_VARIANT_MAX_SOURCE_BYTES=<value>
+        Then the result is <result>
+
+        Examples:
+          | value    | result                                              |
+          | (unset)  | 10485760                                            |
+          | 2048     | 2048                                                |
+          | 0        | an error naming IMAGE_VARIANT_MAX_SOURCE_BYTES      |
+          | -5       | an error naming IMAGE_VARIANT_MAX_SOURCE_BYTES      |
+          | many     | an error naming IMAGE_VARIANT_MAX_SOURCE_BYTES      |
+
+    Rule: Source pixel cap, checked before decoding
+
+      Scenario Outline: A source beyond IMAGE_VARIANT_MAX_SOURCE_PIXELS answers 413 without decoding it
+        Given IMAGE_VARIANT_MAX_SOURCE_PIXELS is 10000
+        And the stored source "wide.png" is a small file whose header declares <w> x <h> pixels
+        When the public client requests /static/uploadedImages/wide.png?v=thumb
+        Then the response status is <status>
+        And the renderer never allocates the pixel buffer for a refused source
+
+        Examples:
+          | w     | h     | status |
+          | 100   | 100   | 200    |
+          | 101   | 100   | 413    |
+          | 30000 | 30000 | 413    |
+
+      Scenario: The pixel 413 body is plain text and nothing is generated
+        Given a source declaring more pixels than the cap
+        Then the body is "The source image is too large to generate this variant." and the renderer is not called and nothing is stored
+
+      Scenario: The pixel cap never affects the original or SVG
+        Given a source declaring more pixels than the cap
+        When the public client requests it without ?v=
+        Then the response is 200 with the stored bytes
+
+      Scenario: A header that cannot be read answers 500 and caches nothing
+        Given the stored blob "bad.png" holds bytes that are not an image
+        When the public client requests /static/uploadedImages/bad.png?v=thumb
+        Then the response status is 500 and nothing is stored
+
+      Scenario Outline: The pixel cap env var
+        When the settings are loaded with IMAGE_VARIANT_MAX_SOURCE_PIXELS=<value>
+        Then the result is <result>
+
+        Examples:
+          | value    | result                                              |
+          | (unset)  | 50000000                                            |
+          | 2048     | 2048                                                |
+          | 0        | an error naming IMAGE_VARIANT_MAX_SOURCE_PIXELS     |
+          | -5       | an error naming IMAGE_VARIANT_MAX_SOURCE_PIXELS     |
+          | many     | an error naming IMAGE_VARIANT_MAX_SOURCE_PIXELS     |
+
+    Rule: Concurrent renders are bounded
+
+      Scenario: At most IMAGE_VARIANT_MAX_CONCURRENT_RENDERS renders run at once
+        Given IMAGE_VARIANT_MAX_CONCURRENT_RENDERS is 2 and the renderer blocks
+        When 5 requests for 5 distinct uncached (variant, image) pairs arrive
+        Then exactly 2 renders are in flight and the other 3 wait for a slot
+        And once a render is released, a waiting one starts, and every request ends with 200
+
+      Scenario: A cached file never takes a render slot
+        Given every render slot is held
+        When the public client requests a variant file that is already cached
+        Then the response is 200 immediately
+
+      Scenario: A waiting request whose client has gone does not render
+        Given every render slot is held and a request waits for a slot
+        When its context is cancelled
+        Then it stops waiting, no render starts for it and nothing is stored
+
+      Scenario: Identical concurrent requests still share one render and one slot
+        When 20 concurrent clients request the same uncached (variant, image) pair
+        Then the renderer is called once and only one slot is taken
+
+      Scenario Outline: The concurrency env var
+        When the settings are loaded with IMAGE_VARIANT_MAX_CONCURRENT_RENDERS=<value>
+        Then the result is <result>
+
+        Examples:
+          | value    | result                                                   |
+          | (unset)  | 4                                                        |
+          | 1        | 1                                                        |
+          | 0        | an error naming IMAGE_VARIANT_MAX_CONCURRENT_RENDERS     |
+          | -1       | an error naming IMAGE_VARIANT_MAX_CONCURRENT_RENDERS     |
+          | many     | an error naming IMAGE_VARIANT_MAX_CONCURRENT_RENDERS     |
+
+    Rule: SVG and animated GIF are served as they are
+
+      Scenario: An SVG with a valid variant is served unchanged
+        Given the image "logo.svg" is stored as "e5f6.svg"
+        When the public client requests /static/uploadedImages/e5f6.svg?v=thumb
+        Then the response is 200 with the stored bytes, the content type "image/svg+xml" and the existing Content-Security-Policy
+        And the renderer is not called and no blob or row is created
+
+      Scenario: An SVG with an unknown variant is still a 400
+        When the public client requests /static/uploadedImages/e5f6.svg?v=banner
+        Then the response is 400 unknown_variant
+
+      Scenario: An SVG larger than the cap is still served
+        Given the cap is lower than the SVG size
+        Then the response is 200 with the stored bytes
+
+      Scenario: An animated GIF is served unchanged
+        Given a stored blob "anim.gif" holding an animated GIF
+        When the public client requests /static/uploadedImages/anim.gif?v=thumb
+        Then the response is 200 with the stored bytes, the content type "image/gif" and no generated file
+
+      Scenario: A single-frame GIF is treated like any raster source
+        Given a stored blob "still.gif" holding a one-frame GIF
+        When the public client requests it with ?v=thumb
+        Then the response is a generated variant
+
+    Rule: Output geometry never upscales
+
+      Scenario Outline: The output size follows the fit and never exceeds the source
+        Given a variant with width <w>, height <h>, fit <fit> and format png
+        And a source of <sw> x <sh> pixels
+        When the variant is requested
+        Then the decoded output is <ow> x <oh>
+
+        Examples:
+          | sw   | sh   | w    | h    | fit     | ow   | oh   |
+          | 4032 | 3024 | 400  | 300  | cover   | 400  | 300  |
+          | 4032 | 3024 | 800  |      | cover   | 800  | 600  |
+          | 4032 | 3024 |      | 600  | contain | 800  | 600  |
+          | 4032 | 3024 | 1000 | 1000 | inside  | 1000 | 750  |
+          | 4032 | 3024 | 1000 | 1000 | cover   | 1000 | 1000 |
+          | 4032 | 3024 | 1000 | 1000 | contain | 1000 | 1000 |
+          | 300  | 200  | 800  |      | cover   | 300  | 200  |
+          | 300  | 200  |      | 800  | inside  | 300  | 200  |
+          | 300  | 200  | 400  | 300  | cover   | 267  | 200  |
+          | 300  | 200  | 400  | 300  | contain | 400  | 300  |
+          | 300  | 200  | 1200 | 1200 | contain | 1200 | 1200 |
+          | 300  | 200  | 1200 | 1200 | inside  | 300  | 200  |
+
+      Scenario: Cover crops around the centre
+        Given a 40 x 20 source whose columns 0 to 9 are red, 10 to 29 are green and 30 to 39 are blue
+        When the variant cover 20 x 20 png is requested
+        Then the output is 20 x 20 and every pixel is green
+
+      Scenario: Contain pads transparent on png and webp
+        Given a 40 x 20 opaque red source and the variant contain 40 x 40 png
+        When it is requested
+        Then the output is 40 x 40, the top 10 rows and bottom 10 rows are fully transparent, and the middle 20 rows are red
+
+      Scenario: Contain pads white on jpeg
+        Given the same source and the variant contain 40 x 40 jpeg
+        Then the top 10 rows and bottom 10 rows are white (#FFFFFF) within JPEG tolerance
+
+      Scenario: Inside adds no padding
+        Given the same source and the variant inside 40 x 40 png
+        Then the output is 40 x 20 with no transparent pixel
+
+      Scenario: A transparent PNG source flattened to JPEG becomes white
+        Given a fully transparent 10 x 10 PNG and the variant 10 x 10 jpeg
+        Then every pixel of the output is white within JPEG tolerance
+
+    Rule: Output format
+
+      Scenario Outline: The output format and content type
+        Given the source "<source>" and the variant format <format>
+        Then the response content type is <type> and the body signature is <signature>
+
+        Examples:
+          | source | format   | type       | signature |
+          | png    | original | image/png  | PNG       |
+          | jpeg   | original | image/jpeg | JPEG      |
+          | png    | jpeg     | image/jpeg | JPEG      |
+          | jpeg   | png      | image/png  | PNG       |
+
+      Scenario: Quality changes the size of a lossy output
+        Given a photographic 600 x 600 source and the variants "lo" quality 20 and "hi" quality 95, both jpeg
+        Then the "lo" output is smaller than the "hi" output
+
+      Scenario: A png output ignores quality
+        Given two png variants stored with quality 30 and 95 submitted at creation
+        Then both outputs are byte-identical
+
+    Rule: WebP is conditional on the spike
+
+      Scenario: When a CGO-free lossy WebP encoder exists, webp is offered
+        Given the spike found an encoder that builds with CGO_ENABLED=0
+        When an admin creates a variant with format "webp"
+        Then the response is 201
+        And requesting it returns "image/webp" with a RIFF/WEBP signature, the right dimensions, and a lower quality giving a smaller file
+        And a webp source with format "original" is served as webp
+
+      Scenario: When no encoder is viable, webp is refused
+        Given the spike found no usable encoder and the renderer reports png, jpeg as encodable
+        When an admin sends POST /v1/image-variants with {"name": "wp", "width": 10, "format": "webp"}
+        Then the response status is 422 and the plain text body is "Format must be original, jpeg or png."
+        And creating with original, jpeg and png still works
+
+      Scenario: A stored GIF is served with the image/gif content type
+        Given a stored blob "anim.gif"
+        When the public client requests /static/uploadedImages/anim.gif
+        Then the response content type is "image/gif"
+
+      Scenario: A webp source still decodes without an encoder
+        Given a webp source and a jpeg variant
+        Then the response is 200 with a JPEG
+
+      Scenario: Without an encoder, a webp source with format original falls back to png
+        Given no webp encoder and a webp source with a variant of format original
+        Then the response content type is image/png
+
+      Scenario: The build stays CGO-free
+        When the module is built with CGO_ENABLED=0 and -tags nofrontend
+        Then it succeeds and go list -deps ./... lists no package that imports "C"
+
+  Rule: Every variant change is recorded in the activity log
+
+    Background:
+      Given recording follows features/activity-log-producers.feature: once, from the use case, after the change, with the request origin
+      And the category is "media" and the target is {"type": "image_variant", "id": "<name>", "name": "<name>"}
+      And the actions are media.variant_create, media.variant_update, media.variant_delete, media.variant_enable, media.variant_disable and media.variant_purge
+      And the change fields allowed in the log are extended with width, height, fit, format and quality, all of kind "text"
+
+    Scenario: Creating a variant is recorded
+      When the owner creates "hero" 1200x630 cover webp quality 82
+      Then one event exists with action "media.variant_create", target {"type": "image_variant", "id": "hero", "name": "hero"}, outcome "success" and params {"width": 1200, "height": 630, "fit": "cover", "format": "webp", "quality": 82}
+
+    Scenario: Updating a variant is recorded with the diff and the purge count
+      Given "hero" has quality 82 and 244 generated files
+      When the owner changes its quality to 70
+      Then one event exists with action "media.variant_update", changes [{"field": "quality", "kind": "text", "before": "82", "after": "70"}] and params {"purged_files": 244}
+
+    Scenario: A switch-only update does not claim a purge
+      When the owner sets generate_on_upload to true on "hero"
+      Then no "media.variant_update" event with a rendering change is recorded, and no event exists for that switch
+
+    Scenario: Deleting a variant is recorded with the removed files
+      Given "hero" has 244 generated files totalling 84 MB
+      When the owner deletes it
+      Then one event exists with action "media.variant_delete", target "hero" and params {"purged_files": 244, "purged_bytes": <total>}
+
+    Scenario Outline: Enabling and disabling are recorded
+      Given "hero" has enabled <before>
+      When the owner sends PATCH /v1/image-variants/hero with {"enabled": <after>}
+      Then one event exists with action "<action>" and target "hero"
+
+      Examples:
+        | before | after | action                |
+        | false  | true  | media.variant_enable  |
+        | true   | false | media.variant_disable |
+
+    Scenario: A PATCH to the current value records nothing
+      When the owner sets enabled to its current value
+      Then the response is 200 and no event is recorded
+
+    Scenario: A refused create is recorded as failed
+      Given "thumb" exists
+      When the owner creates "thumb" again
+      Then one event exists with action "media.variant_create", outcome "failed", failure_reason "A variant with that name already exists." and target "thumb"
+
+    Scenario Outline: Requests that fail validation or find nothing record nothing
+      When <request>
+      Then no event is recorded
+
+      Examples:
+        | request                                              |
+        | POST /v1/image-variants with width 9000              |
+        | PUT /v1/image-variants/missing with a valid body     |
+        | DELETE /v1/image-variants/missing                    |
+        | PATCH /v1/image-variants/missing with {"enabled": true} |
+        | POST /v1/image-variants/missing/purge                |
+        | GET /v1/image-variants                               |
+        | a public GET ...?v=thumb that generates a file       |
+
+    Scenario: Purging a variant's cache is recorded
+      Given "hero" has 244 generated files totalling 84 MB
+      When the owner sends POST /v1/image-variants/hero/purge
+      Then one event exists with action "media.variant_purge", target {"type": "image_variant", "id": "hero", "name": "hero"}, outcome "success" and params {"purged_files": 244, "purged_bytes": <total>}
+
+    Scenario: Purging an empty cache records nothing
+      Given "hero" has no generated file
+      When the owner sends POST /v1/image-variants/hero/purge
+      Then the response is 200 with {"purged_files": 0, "purged_bytes": 0} and no event is recorded
+
+    Scenario: A purge that fails on storage is recorded as failed
+      Given "hero" has 3 generated files and image.Storage fails to delete the second
+      When the owner sends POST /v1/image-variants/hero/purge
+      Then the response is 500 and one event exists with action "media.variant_purge", outcome "failed" and failure_reason "Something went wrong on our side. Please try again."
+
+    Scenario: A failing audit write never changes the response
+      Given the audit repository fails on Append
+      When the owner creates "hero"
+      Then the response is 201 and the variant exists
+
+    Scenario: The existing allowlist scenario is updated
+      Then the only change fields any producer emits are title, online, body, filename, display_name, width, height, fit, format and quality
+
+  Rule: Layering and hygiene
+
+    Scenario: The dependency rule holds
+      Then internal/domain/image imports only the stdlib and other internal/domain packages
+      And the variant use cases import no persistence, mailer, models, gorm, net/http, chi or api package
+      And the handler for /v1/image-variants and the public handler import no persistence, mailer, models or gorm package
+      And only api/dependecyInjection.go constructs the variant repositories, the renderer and the use cases
+      And the new GORM models are registered in internal/infrastructure/persistence/database/migrate.go
+      And no comment is added to any Go file, test or doc, except tool directives

features/image-variants.qa.md

@@ -0,0 +1,74 @@
+# QA procedure: image-variants
+
+Go only, no SPA. Package `test` (black-box). New files: `test/image_variants_admin_http_test.go`, `test/image_variants_serving_http_test.go`, `test/image_variants_geometry_test.go`, `test/image_variants_audit_test.go`, `test/image_variants_config_test.go`. Fake type names must be unique across the package. No live server, no real SMTP, no real SQLite file, no `time.Sleep`.
+
+## Setup shared by every case
+1. `validator.InitValidator()` once. `jwtauth.New("HS256", []byte("test-secret"), nil)` stands in for `JWT_SECRET`.
+2. New hand-written in-memory fakes: `mockVariantRepo` (CRUD, stores creation order, unique-name check returning `image.ErrVariantExists`), `mockVariantFileRepo` (index rows with variant, source stored name, cached stored name, content type, size, fingerprint, with `Delete` calls recorded and a per-row failure switch), `mockVariantStorage` (an in-memory `image.Storage` that names blobs `gen-<n>.<ext>`, counts `Put`, `Open` and `Delete` calls, can fail `Delete` for one name, and can block `Put`/render on a channel), `countingRenderer` (wraps the real stdlib-based renderer, counts calls, can fail the first call, can block on a channel, `EncodableFormats()` configurable for the webp-on or webp-off cases). Reuse `mockImageRepo`, the user fake, the audit fakes from `test/activity_support_test.go` (`mockAuditRepo`, `fakeAuditClock`).
+3. Users: owner 1, admin 2, verified plain user 3, unverified user 4. Real signed `jwt` cookies with `user_id` and `token_version`; a stale cookie with a lower `token_version`. A valid API key in the key fake for the "API key refused" row.
+4. Admin router: a fresh `chi.NewRouter()` mirroring `api/router.go`: `jwtauth.Verifier`, `middleware.AuditContext(getUser, nil)`, `jwtauth.Authenticator`, `RequireCurrentToken`, `RequireVerifiedUser`, `RequireOwnerOrAdmin`, mounted at `/v1/image-variants`, with no `apiKeyAuth`.
+5. Public router: mount the real `staticimages.NewHandler(...)` (with the new variant dependency) at `/static/uploadedImages` on the same kind of router, over `mockVariantStorage` holding the originals. The router wraps `chimiddleware.GetHead` like `InitRoutes`.
+6. Images are generated in the test with `image/png`, `image/jpeg` and `image/draw` (solid or half-and-half colours so crops and padding can be asserted pixel by pixel). Decode responses with `image.Decode`. An animated GIF is built with `image/gif` and two frames. A real SVG string is stored as `e5f6.svg`. Use `x/image/webp` to decode webp fixtures.
+7. Set the cap by constructing the use case with the value; do not touch the process environment except in the config test.
+
+## A. Guards (feature "Only owners and admins")
+8. Table: each method, path and credential gives the status and the exact body constant; assert no variant, index, storage or audit fake was touched. API key gets 401. Owner and admin both get 200.
+
+## B. List and create
+9. Empty list: raw JSON has `"items":[]`. Seeded list: order by name, `width`/`height` as JSON `null` when absent (assert on the raw body), `quality` null for png, counts and sizes from the file index.
+10. Create: full body, defaults body, boundary table (name 2 and 32 chars, `width` 1 and 8000, quality 1 and 100). Invalid table gives 422 with each exact sentence and verifies nothing stored and no audit event. Malformed JSON rows give 400 with `apperr.BodyErrorMessage`. Duplicate gives 409 with the exact sentence and leaves the stored variant unchanged.
+11. When `EncodableFormats()` lacks webp, the format rejection sentence is `Format must be original, jpeg or png.` and `webp` is refused with 422; run the format rows in both configurations.
+
+## C. Update, toggle, delete, purge
+12. PUT table over `width`, `height`, `fit`, `format`, `quality` (purges 244 seeded index rows: assert the blob `Delete` calls equal the row set, the index is empty for the variant, the other variant's rows untouched, `purged_files` equals 244). `generate_on_upload` and `enabled` rows purge nothing. Identical PUT leaves `updated_at` as it was and records no event. A png variant ignores a quality edit. The body `name` is ignored.
+13. Invalid PUT rows leave variant and rows unchanged. Unknown name gives 404 with `Variant not found`.
+14. PATCH: both directions keep the index rows and call no storage `Delete`; 400/422/404 rows.
+15. DELETE: 204 with empty body, variant gone, its blobs and rows gone, others untouched. 404 row.
+16. Purge: 200 with `purged_files` and `purged_bytes`, variant intact, list shows zero. Empty cache returns zeros. Storage `Delete` failing on the second of three blobs gives 500, two rows removed, one row kept. A blob already absent (storage `Delete` returns nil per `LocalStorage` contract) removes the row.
+17. Source delete and merge: through the real delete and merge media use cases, assert the generated blobs and rows of the removed image(s) are deleted and those of other images are kept. Assert the 204 status and the existing library behaviour are unchanged.
+
+## D. Public serving
+18. First request: 200, content type, decoded size, exactly one `Put` and one index row equal to the body size, original blob untouched. Second request: byte-identical body, renderer count 1, `Put` count 1.
+19. No `?v=`: the response equals the pre-slice response (headers and bytes) and the renderer count is 0. Other parameters such as `t=123` are ignored.
+20. ETag: present, stable, `If-None-Match` gives 304 with an empty body and no renderer call on a cached file. Edit table (quality, width, height, fit, format change the ETag; `generate_on_upload` does not). A stale `If-None-Match` after an edit gets 200 with a new ETag. After an edit, the next request puts one new blob and the old blob was deleted.
+21. Vanished blob: index row present, storage `Open` returns `ErrBlobNotFound`: regenerated, row repointed.
+22. Concurrency (run with `-race`): 20 goroutines released by a barrier channel against a renderer blocking on a channel; all 200 with identical bytes, renderer count 1, `Put` count 1. Four distinct (variant, image) pairs with blocking renderers: assert all four renders start before any is released (use a `sync.WaitGroup` rendezvous in the fake, no sleeping). A failing first render gives 500 with no row and a successful retry.
+23. 400 table: every URL of the outline, with the exact JSON body (decode and compare `status`, `error`, `message`, `detail`), `Content-Type` starting with `application/json`, renderer count 0, storage `Put` count 0. Precedence: `unsupported_parameter` beats `unknown_variant`; 400 beats 404 for a missing source.
+24. Disabled then enabled: 400, then 200 served from the kept row (`Put` count unchanged). Deleted variant: 400.
+25. 404 table: missing name, `..` traversal, nested path. 500 for undecodable bytes with nothing stored.
+26. Cap: boundary table 1000 bytes (200) and 1001 bytes (413), the 413 plain text body, the renderer count 0, the original served without `?v=`.
+27. SVG and GIF: unchanged bytes, content types `image/svg+xml` (with the existing CSP header) and `image/gif`, renderer count 0, nothing stored, unknown variant still 400, SVG larger than the cap still 200. A one-frame GIF is rendered.
+
+## E. Geometry and format (unit-level, no HTTP, same files)
+28. Table (feature "Output geometry"): decode each output and assert width and height. Build the source with a solid colour for the size rows.
+29. Pixel assertions: cover crops around the centre of a 40 x 20 source with red columns 0-9, green 10-29, blue 30-39 and every pixel of the 20 x 20 output is green; contain pads transparent on png (alpha 0 on the padded rows, assert RGBA) and white on jpeg (within a tolerance of 8 per channel); inside has no transparent pixel; a fully transparent PNG source flattened to jpeg is white.
+30. Format table: signature bytes (`\x89PNG`, `\xff\xd8`, `RIFF....WEBP`) and content types for original, jpeg, png. Lossy size: quality 20 smaller than quality 95 on a noisy fixture. PNG variants stored with quality 30 and 95 give byte-identical outputs.
+31. WebP, conditional: with an encoder, assert `RIFF/WEBP`, dimensions via `webp.DecodeConfig`, lower quality gives a smaller file, and a webp source with `original` stays webp. Without one, a webp source rendered to jpeg works and `original` falls back to png. Record in the test name which build is under test.
+
+## F. Config
+32. Settings load: unset gives 10485760, `2048` gives 2048, `0`, `-5` and `many` give an error naming `IMAGE_VARIANT_MAX_SOURCE_BYTES`. Assert the var is present in `envDefaults` (and absent from `requiredEnvVars`), in `.env.example` and in `docs/configuration.md` (grep-style test on the files).
+
+## G. Audit
+33. Create, update (diff plus `purged_files`), delete (`purged_files`, `purged_bytes`), enable, disable and purge events (purge: counts on success, nothing for an empty cache or an unknown name, a failed event with the generic reason when storage fails) with the exact action, category `media`, target `image_variant`, actor and source from the origin. No-op PUT and PATCH record nothing; switch-only PUT records nothing for the rendering diff. Duplicate create records a failed event with its reason; validation errors, 404s, list and public generation record nothing. A failing audit repository leaves the response and the change untouched. Update the allowlist assertion of `test/activity_log_producers*_test.go` to the new field set.
+
+## H. Mutation guard
+34. `task mutate` scope is `./internal/infrastructure/useCases`, scoped with `MUTATE_FILES` to the new use case files and `MUTATE_RUN` to the new test names. Each new branch needs a killing assertion: the 1 and 8000 and 2 and 32 boundaries (just inside and just outside), the "at least one dimension" rule, every rendering-setting equality in the purge decision with equal and differing values, the cap comparison (`>` not `>=`, at 1000 and 1001), the never-upscale `min`, the singleflight key (variant and image both), the ETag input set, the check order (parameters, variant, source, as-is types, cap, ETag, cache), and the audit no-op guards. Bare-bool conditions produce no mutant, so cover both branches anyway.
+
+## I. Layering and hygiene
+35. Guard test (`go list -deps` or grep): `internal/domain/image` imports no GORM, chi, http or infrastructure; the variant use cases import no `persistence`, `mailer`, `models`, `gorm`, `net/http`, chi or `api`; the handlers import no `persistence`, `mailer`, `models` or `gorm`.
+36. `CGO_ENABLED=0 go build -tags nofrontend ./...` succeeds, and `go list -deps` shows no package importing `"C"`.
+37. No comments in new or edited Go files, tests and docs (the hook enforces it). Docs: `docs/api.md` lists the routes and response shapes, `docs/architecture.md` the ports and the cache, `docs/configuration.md` the env var.
+
+## J. Hardening follow-up
+44. Pixel cap: a PNG whose IHDR declares 30000 x 30000 (a few hundred bytes of real data) answers 413 with the plain text body and the renderer fake records zero calls; boundary 100 x 100 passes and 101 x 100 fails at a cap of 10000; the original is still served without `?v=`; an unreadable header gives 500. Settings tests for IMAGE_VARIANT_MAX_SOURCE_PIXELS (unset 50000000, 2048, 0, -5, many) and presence in envDefaults, `.env.example`, `docs/configuration.md`.
+45. Render slots: a renderer fake that blocks on a channel proves at most N renders run at once, the rest wait and then complete with 200; a cached hit does not wait; a cancelled request context stops waiting and renders nothing; identical concurrent requests share one slot. Settings tests for IMAGE_VARIANT_MAX_CONCURRENT_RENDERS (unset 4, 1, 0, -1, many) and the three-place documentation check. Run with `-race`.
+46. Known source: a blob without an image record (generated cache file or orphan) answers 404 for `?v=` with no storage `Open` call; parameter checks (400) still come first; the original of that blob is still served without `?v=`.
+47. Contain geometry: 300 x 200 in 400 x 300 gives a 400 x 300 canvas with the image centred and unscaled (transparent padding on png); 300 x 200 in 1200 x 1200 gives 1200 x 1200; single-dimension contain keeps no padding.
+
+## Manual (not automated)
+38. Real boot with `task dev:api` over a scratch SQLite file and `UPLOAD_DIR`: create `thumb`, request `/static/uploadedImages/<name>?v=thumb` in a browser, check the file lands in `UPLOAD_DIR`, a second request is served without re-rendering, edit the quality and check the old file disappears. Check `AutoMigrate` created the new tables.
+39. S3 driver (`STORAGE_DRIVER=s3`, MinIO): generated blobs land in the bucket, purge removes them, serving works without Range or seek support.
+40. Visual quality of a real photograph in jpeg and, if the spike succeeded, webp; check the contain padding looks right against a white and a dark page.
+41. WebP spike: record the evaluated encoders, the build result with `CGO_ENABLED=0`, speed and size on a 4032x3024 photo, and the decision. Report to the user if none works.
+42. Memory and time on a source near `IMAGE_VARIANT_MAX_SOURCE_BYTES` with very large pixel dimensions.
+43. Read the activity rows in the real Activity screen against section 8 copy.

features/image_variants_cache.feature

@@ -0,0 +1,627 @@
+Feature: Image variants cache panel: cache statistics, purge by scope, request tracking and the Cache screen
+
+  As an owner or admin of a RenewCMS site
+  I want to see what the variant cache holds and to purge all of it, the unused part, one variant or one image
+  So that I can reclaim disk without deleting a variant, and the activity log records every purge
+
+  Background:
+    Given the spec of record is docs/design/screens/image-variants.md sections 5 and 8, its "Back-office API errors" table, the cache frames of docs/design/source/VariantsFrame.dc.html and docs/design/routes.md
+    And the routes the design marks "proposed" are fixed here: GET /v1/image-variants/cache and POST /v1/image-variants/cache/purge, mounted in NewImageVariantRouter in api/router.go behind the existing owner or admin middleware chain, so a request with an API key has no user_id claim and answers 401
+    And features/image-variants.feature and features/image_variants_per_image_api.feature are the contract for variants, index rows and per-image purge, and are unchanged
+    And a cached file is one VariantFile index row, a row counts whatever the state of its fingerprint, and sizes are in bytes (1 MB = 1048576)
+    And the page is /settings/media/cache, a verified route rendered as CachePage inside DashboardShell, and it supersedes the aria-disabled "Cache" tab of features/image_variants_screens.feature, which becomes a link to this route
+    And request validation goes through validate tags and validator.Validate.Struct, an unreadable JSON body answers 400 with apperr.BodyErrorMessage, a failed validation answers 422, and error responses are plain text from http.Error
+    And new apperr constants are CachePurgeScopeErrorMessage = "Scope must be all, unused, variant or image." and CachePurgeTargetErrorMessage = "A variant name or an image id is required for this scope."
+    And request tracking has two parts: the last time each generated file was requested, and a counter of rejected requests per UTC day
+    And tracking never writes to the database on a request: hits are kept in memory by a thread-safe tracker behind a domain port, merged per (variant, source) key, and flushed in one batch by a background loop every 30 seconds, when 500 distinct keys are pending, on GET /v1/image-variants/cache before it reads, and on graceful shutdown
+    And the flush reaches the database through a domain repository port, the models are added to internal/infrastructure/persistence/database/migrate.go: a nullable last_requested_at column on ImageVariantFile and a new model ImageVariantRejectionDay with a unique day and a count
+    And the SQL stays portable across SQLite, MySQL/MariaDB and PostgreSQL: plain GROUP BY, ORDER BY, LIMIT and comparisons, no dialect function and no upsert syntax outside GORM's portable clauses
+    And the cache body is JSON with snake_case fields, arrays are never null, and the Default fixture below is used by the scenarios
+    And the Default fixture holds six variants, the enabled ones are card, hero, og, square and thumb, the disabled one is print, and the index holds:
+      | variant | files | bytes     |
+      | hero    | 244   | 88080384  |
+      | card    | 318   | 60817408  |
+      | thumb   | 412   | 22020096  |
+      | print   | 74    | 22020096  |
+      | square  | 140   | 19922944  |
+      | og      | 96    | 9437184   |
+    And 312 files (42991616 bytes) of enabled variants have a reference time older than 30 days, the reference time of a row being last_requested_at when set and created_at otherwise
+    And the ten images using the most variant bytes are, in order: north-wall.jpg (id 1, 6 files, 6082765 bytes), lime-plaster.jpg (6, 5138022), kitchen-after.webp (5, 4613734), kitchen-before.webp (5, 4089446), floorboards.jpg (5, 3774873), IMG_4471.jpg (4, 3250585), stone-wall-detail.jpg (4, 2936012), bathroom-tiles.png (4, 2726297), roof-lantern.jpg (3, 2411724) and chimney-stack.jpg (3, 2202009)
+    And 37 rejected requests were counted over the last 7 UTC days
+
+  Rule: Only owners and admins reach the cache routes
+
+    Scenario Outline: Every cache route is guarded
+      When the client sends <method> <path> with <credentials>
+      Then the response status is <status>
+      And the plain text body is <body>
+      And no index row, blob, counter or activity event is read or changed
+
+      Examples:
+        | method | path                            | credentials                       | status | body                                    |
+        | GET    | /v1/image-variants/cache        | no cookie                         | 401    | apperr.UnauthorizedErrorMessage         |
+        | GET    | /v1/image-variants/cache        | a stale token_version cookie      | 401    | apperr.UnauthorizedErrorMessage         |
+        | GET    | /v1/image-variants/cache        | the cookie of an unverified user  | 403    | apperr.VerificationRequiredErrorMessage |
+        | GET    | /v1/image-variants/cache        | the cookie of a plain user        | 403    | apperr.OwnerOrAdminRequiredErrorMessage |
+        | POST   | /v1/image-variants/cache/purge  | the cookie of a plain user        | 403    | apperr.OwnerOrAdminRequiredErrorMessage |
+        | GET    | /v1/image-variants/cache        | a valid API key                   | 401    | apperr.UnauthorizedErrorMessage         |
+        | POST   | /v1/image-variants/cache/purge  | a valid API key                   | 401    | apperr.UnauthorizedErrorMessage         |
+
+    Scenario Outline: Owners and admins are both allowed
+      When <role> sends GET /v1/image-variants/cache with a valid cookie
+      Then the response status is 200
+
+      Examples:
+        | role      |
+        | the owner |
+        | an admin  |
+
+  Rule: The cache statistics
+
+    Scenario: The Default fixture
+      When an admin sends GET /v1/image-variants/cache
+      Then the response status is 200
+      And the body holds "generated_files" 1284 and "disk_used" 222298112
+      And it holds "variants_defined" 6, "variants_enabled" 5 and "variants_disabled" 1
+      And it holds "rejected_requests" 37 and "rejected_window_days" 7
+      And it holds "unused" {"files": 312, "bytes": 42991616, "days": 30}
+      And "by_variant" lists every defined variant sorted by bytes descending then name ascending: hero, card, print, thumb, square, og, each as {"name", "enabled", "files", "bytes"}
+      And "top_images" lists the ten images above in that order, each as {"id", "filename", "url", "files", "bytes"} where url is "/static/uploadedImages/<storedName>"
+
+    Scenario: Counts are the sum of the index rows
+      Then "generated_files" equals the sum of the "files" of "by_variant" and "disk_used" equals the sum of their "bytes"
+
+    Scenario: A variant without a file is listed with zero
+      Given the variant "banner" is defined and enabled and has no file
+      When an admin sends GET /v1/image-variants/cache
+      Then "by_variant" holds {"name": "banner", "enabled": true, "files": 0, "bytes": 0} and "variants_defined" is 7
+
+    Scenario: A disabled variant keeps its files in the totals
+      Then "by_variant" holds print with "enabled" false, "files" 74 and "bytes" 22020096
+      And print is counted in "generated_files" and "disk_used" but not in "unused"
+
+    Scenario: An image deleted behind the index is not a top image
+      Given index rows exist for a stored name that no image record has
+      When an admin sends GET /v1/image-variants/cache
+      Then the rows count in "generated_files", "disk_used" and "by_variant" and no entry of "top_images" names that stored name
+
+    Scenario: Top images are capped at ten and tie-break by id
+      Given eleven images have variant files and images 7 and 8 have equal bytes
+      When an admin sends GET /v1/image-variants/cache
+      Then "top_images" has ten entries and image 7 comes before image 8
+
+    Scenario: An empty cache
+      Given the index holds no row
+      When an admin sends GET /v1/image-variants/cache
+      Then the response status is 200
+      And "generated_files" is 0, "disk_used" is 0, "unused" is {"files": 0, "bytes": 0, "days": 30}
+      And the raw body holds "top_images":[] and every "by_variant" entry has files 0
+      And "variants_defined" and "rejected_requests" are unchanged
+
+    Scenario: No variant defined
+      Given no variant exists
+      When an admin sends GET /v1/image-variants/cache
+      Then the raw body holds "by_variant":[] and "variants_defined":0
+
+    Scenario: Unused counts only enabled variants older than the cutoff
+      Given a row of "hero" with last_requested_at 29 days ago and a row of "hero" with last_requested_at 31 days ago
+      And a row of "print", a disabled variant, with last_requested_at 90 days ago
+      And a row of "card" with no last_requested_at and a created_at 45 days ago
+      Then the rows of "hero" 31 days ago and of "card" are counted in "unused", and the other two are not
+
+    Scenario: A row requested exactly 30 days ago is still in use
+      Given a row whose reference time is exactly the cutoff
+      Then it is not counted in "unused"
+
+    Scenario: The statistics are aggregated, not read per image
+      When an admin sends GET /v1/image-variants/cache
+      Then the file repository answered the totals, the unused totals and the top images in one aggregated call each, never one query per image or per file
+
+    Scenario: The read flushes pending tracking first
+      Given 12 hits and 3 rejections are pending in memory
+      When an admin sends GET /v1/image-variants/cache
+      Then one batch write happens before the read and "rejected_requests" includes the 3 pending
+
+    Scenario: The statistics change nothing else
+      When an admin sends GET /v1/image-variants/cache
+      Then no blob is opened, no render happens, no row is deleted and no activity event is recorded
+
+    Scenario: A failing repository answers 500
+      Given the file repository fails to total
+      When an admin sends GET /v1/image-variants/cache
+      Then the response status is 500 and the plain text body is "Internal server error"
+
+  Rule: The last time each generated file was requested is tracked without a write per hit
+
+    Scenario Outline: What counts as a request for a file
+      When <request>
+      Then <effect> for the pair (variant, stored name) in memory and no database write happens
+
+      Examples:
+        | request                                                                   | effect                              |
+        | the public client gets /static/uploadedImages/a1b2.jpg?v=thumb, cached    | the last requested time is set      |
+        | the public client gets it and the file is generated by that request       | the last requested time is set      |
+        | the public client gets it with a matching If-None-Match and receives 304  | the last requested time is set      |
+        | the public client gets /static/uploadedImages/a1b2.jpg with no variant     | nothing is recorded                 |
+        | the public client gets it with ?v=unknown                                 | nothing is recorded                 |
+        | the public client gets it with ?v=print, a disabled variant               | nothing is recorded                 |
+        | the public client gets /static/uploadedImages/missing.jpg?v=thumb         | nothing is recorded                 |
+        | an admin sends POST /v1/media/1/variants/thumb                            | nothing is recorded                 |
+        | an admin sends GET /v1/image-variants/cache                               | nothing is recorded                 |
+
+    Scenario: A thousand hits on one file are one pending key
+      When the public client requests the same cached file 1000 times
+      Then the database received zero writes during the requests
+      And after a flush exactly one batch write holds one update for that file with the time of the last hit
+
+    Scenario: The flush writes one batch for many files
+      Given 40 distinct files were requested
+      When the tracker flushes
+      Then the repository received one batch of 40 updates in one call
+
+    Scenario: Nothing pending means no write
+      When the tracker flushes and nothing was recorded since the last flush
+      Then the repository is not called
+
+    Scenario: The flush loop and the size trigger
+      Given 500 distinct keys are pending
+      Then a flush is started without waiting for the interval
+      And a flush also happens at each 30 second tick and on graceful shutdown
+
+    Scenario: A failed flush keeps the pending hits
+      Given the repository fails on the batch
+      When the tracker flushes, then the repository recovers and the tracker flushes again
+      Then the second batch holds the hits of both flushes with the latest time per file and nothing is lost or counted twice
+
+    Scenario: A request is never blocked by or failed by the tracker
+      Given the repository fails on every batch
+      When the public client requests a cached file
+      Then the response is 200 with the file bytes
+
+    Scenario: A stored time never moves back
+      Given a row with last_requested_at 10:05
+      When a batch carries the time 10:01 for that file
+      Then last_requested_at is still 10:05
+
+    Scenario: A purged file ignores a late update
+      Given the batch carries a time for a file that was purged since
+      When the tracker flushes
+      Then no row is created and the call succeeds
+
+    Scenario: Concurrent requests are race free
+      When 50 goroutines record hits and rejections while another flushes
+      Then the totals written equal the recorded ones, with the race detector enabled
+
+  Rule: Rejected public requests are counted per day
+
+    Scenario Outline: What counts as rejected
+      When the public client sends GET <url>
+      Then <effect>
+
+      Examples:
+        | url                                          | effect                                  | status |
+        | /static/uploadedImages/a1b2.jpg?v=unknown    | the rejected counter of today is +1     | 400    |
+        | /static/uploadedImages/a1b2.jpg?v=print      | the rejected counter of today is +1     | 400    |
+        | /static/uploadedImages/a1b2.jpg?width=400    | the rejected counter of today is +1     | 400    |
+        | /static/uploadedImages/a1b2.jpg?v=Thumb      | the rejected counter of today is +1     | 400    |
+        | /static/uploadedImages/missing.jpg?v=thumb   | the counter is unchanged                | 404    |
+        | /static/uploadedImages/a1b2.jpg?v=thumb      | the counter is unchanged                | 200    |
+        | /static/uploadedImages/a1b2.jpg              | the counter is unchanged                | 200    |
+
+    Scenario: A rejection is an in-memory increment
+      When the public client sends 1000 rejected requests
+      Then the database received zero writes during the requests
+      And after a flush one batch adds 1000 to today's day row
+
+    Scenario: The window is today and the six previous UTC days
+      Given the tracker clock reads 2026-10-08 23:59 UTC and day rows of 2026-10-02 (5) and 2026-10-01 (9)
+      When an admin sends GET /v1/image-variants/cache
+      Then "rejected_requests" counts the row of 2026-10-02 and not the row of 2026-10-01
+
+    Scenario: A day boundary starts a new bucket
+      Given a rejection at 2026-10-08 23:59:59 UTC and another at 2026-10-09 00:00:00 UTC
+      Then they are counted in two different day rows
+
+    Scenario: Old day rows are pruned by the flush
+      Given a day row older than 7 days
+      When the tracker flushes
+      Then that row is deleted and the rows of the window are kept
+
+    Scenario: A failed flush keeps the pending rejections
+      Given the repository fails on the batch
+      When the tracker flushes, then the repository recovers and flushes again
+      Then the rejections are written once
+
+  Rule: Purging the cache by scope
+
+    Background:
+      Given the Default fixture with blobs in image.Storage for every row
+      And images 1 "north-wall.jpg" and 2 "lime-plaster.jpg" hold index rows
+
+    Scenario: Purge all removes every generated file of every variant
+      When an admin sends POST /v1/image-variants/cache/purge with {"scope": "all"}
+      Then the response status is 200
+      And the body is {"scope": "all", "purged_files": 1284, "purged_bytes": 222298112, "failed_files": 0}
+      And every generated blob is deleted from image.Storage and the index holds no row
+      And the original blobs and every variant definition are unchanged
+
+    Scenario: Purge all includes the files of disabled variants
+      Then the 74 files of "print" are among the 1284 purged
+
+    Scenario: Purge unused removes the unused files of enabled variants only
+      When an admin sends POST /v1/image-variants/cache/purge with {"scope": "unused"}
+      Then the response status is 200
+      And the body is {"scope": "unused", "purged_files": 312, "purged_bytes": 42991616, "failed_files": 0}
+      And the remaining 972 rows are untouched, including any row of "print" and every row requested within 30 days
+
+    Scenario: Purge by variant removes the files of that variant only
+      When an admin sends POST /v1/image-variants/cache/purge with {"scope": "variant", "variant": "hero"}
+      Then the body is {"scope": "variant", "purged_files": 244, "purged_bytes": 88080384, "failed_files": 0}
+      And the files of the other variants are untouched
+
+    Scenario: Purge by variant works for a disabled variant
+      When an admin sends POST /v1/image-variants/cache/purge with {"scope": "variant", "variant": "print"}
+      Then "purged_files" is 74
+
+    Scenario: Purge by image removes every variant file of that image
+      Given image 1 holds 6 rows of 6082765 bytes
+      When an admin sends POST /v1/image-variants/cache/purge with {"scope": "image", "image_id": 1}
+      Then the body is {"scope": "image", "purged_files": 6, "purged_bytes": 6082765, "failed_files": 0}
+      And the files of image 2 are untouched and the original of image 1 is unchanged
+
+    Scenario: The next public request generates a purged file again
+      Given a purge with {"scope": "all"} answered 200
+      When the public client sends GET /static/uploadedImages/a1b2.jpg?v=thumb
+      Then the response is 200 and a new blob was put
+
+    Scenario: Purging an empty cache answers zero
+      Given the index holds no row
+      When an admin sends POST /v1/image-variants/cache/purge with {"scope": "all"}
+      Then the response status is 200 and the body is {"scope": "all", "purged_files": 0, "purged_bytes": 0, "failed_files": 0}
+
+    Scenario: A blob already missing from storage does not stop a purge
+      Given image.Storage reports a missing blob for one row
+      When an admin sends POST /v1/image-variants/cache/purge with {"scope": "all"}
+      Then its row is removed and counted as purged and the others are purged
+
+    Scenario Outline: A request that cannot be served
+      When an admin sends POST /v1/image-variants/cache/purge with <body>
+      Then the response status is <status> and the plain text body is <message>
+      And no blob is deleted and no row is deleted and no activity event is recorded
+
+      Examples:
+        | body                                          | status | message                                  |
+        | {"scope": "everything"}                       | 422    | apperr.CachePurgeScopeErrorMessage       |
+        | {"scope": "ALL"}                              | 422    | apperr.CachePurgeScopeErrorMessage       |
+        | {}                                            | 422    | apperr.CachePurgeScopeErrorMessage       |
+        | {"scope": "variant"}                          | 422    | apperr.CachePurgeTargetErrorMessage      |
+        | {"scope": "variant", "variant": ""}           | 422    | apperr.CachePurgeTargetErrorMessage      |
+        | {"scope": "image"}                            | 422    | apperr.CachePurgeTargetErrorMessage      |
+        | {"scope": "image", "image_id": 0}             | 422    | apperr.CachePurgeTargetErrorMessage      |
+        | {"scope": "image", "image_id": -1}            | 422    | apperr.CachePurgeTargetErrorMessage      |
+        | {"scope": "variant", "variant": "missing"}    | 404    | apperr.VariantNotFoundErrorMessage       |
+        | {"scope": "image", "image_id": 9999}          | 404    | Image not found                          |
+        | not json                                      | 400    | apperr.BodyErrorMessage                  |
+
+    Scenario Outline: A target given for a scope that ignores it is ignored
+      When an admin sends POST /v1/image-variants/cache/purge with {"scope": "<scope>", "variant": "hero", "image_id": 1}
+      Then the response status is 200 and the purged files are those of the scope "<scope>" alone
+
+      Examples:
+        | scope  |
+        | all    |
+        | unused |
+
+  Rule: A purge that does not complete reports what it did
+
+    Background:
+      Given the Default fixture and image.Storage fails to delete the blobs of 644 rows
+
+    Scenario: A partial purge answers 200 with the failed count
+      When an admin sends POST /v1/image-variants/cache/purge with {"scope": "all"}
+      Then the response status is 200
+      And the body is {"scope": "all", "purged_files": 640, "purged_bytes": <bytes of those 640>, "failed_files": 644}
+      And the 644 rows are kept, so a second call can retry them
+
+    Scenario: Retrying removes the rest
+      Given a partial purge answered 200
+      When image.Storage recovers and the admin sends the same request again
+      Then "purged_files" is 644 and "failed_files" is 0
+
+    Scenario: A failure to list the rows answers 500
+      Given the file repository fails to list the rows to purge
+      When an admin sends POST /v1/image-variants/cache/purge with {"scope": "all"}
+      Then the response status is 500 and the plain text body is "Internal server error"
+
+    Scenario: Rows are processed in bounded batches
+      When an admin sends POST /v1/image-variants/cache/purge with {"scope": "all"} over 5000 rows
+      Then the rows were read in batches of at most 500 and never all loaded at once
+
+  Rule: Each purge scope is recorded in the activity log
+
+    Background:
+      Given recording follows features/activity-log-producers.feature: once, from the use case, after the change, with the request origin
+      And the category is "media"
+      And the domain audit gains the actions media.variant_purge_all and media.variant_purge_unused, and reuses media.variant_purge and media.variant_purge_image
+
+    Scenario Outline: A purge that removes files is recorded
+      When the owner sends POST /v1/image-variants/cache/purge with <body>
+      Then one event exists with action "<action>", target <target>, outcome "success" and params <params>
+
+      Examples:
+        | body                                   | action                     | target                                                                 | params                                                             |
+        | {"scope": "all"}                       | media.variant_purge_all    | none                                                                   | {"purged_files": 1284, "purged_bytes": 222298112}                  |
+        | {"scope": "unused"}                    | media.variant_purge_unused | none                                                                   | {"purged_files": 312, "purged_bytes": 42991616, "older_than_days": 30} |
+        | {"scope": "variant", "variant": "hero"}| media.variant_purge        | {"type": "image_variant", "id": "hero", "name": "hero"}                | {"purged_files": 244, "purged_bytes": 88080384}                    |
+        | {"scope": "image", "image_id": 1}      | media.variant_purge_image  | {"type": "image", "id": "1", "name": "north-wall.jpg"}                 | {"purged_files": 6, "purged_bytes": 6082765}                       |
+
+    Scenario: A partial failure is a success that names the failed count
+      Given a purge removes 640 files and fails on 644
+      When the owner sends POST /v1/image-variants/cache/purge with {"scope": "all"}
+      Then one event exists with action "media.variant_purge_all", outcome "success" and params {"purged_files": 640, "purged_bytes": <bytes>, "failed_files": 644}
+
+    Scenario: Every file failing is a failed event with a plain reason
+      Given image.Storage fails to delete every blob
+      When the owner sends POST /v1/image-variants/cache/purge with {"scope": "all"}
+      Then the response is 200 with "purged_files" 0 and "failed_files" 1284
+      And one event exists with action "media.variant_purge_all", outcome "failed" and failure_reason "Something went wrong on our side. Please try again."
+
+    Scenario Outline: Nothing removed, nothing recorded
+      When <request>
+      Then no event is recorded
+
+      Examples:
+        | request                                                         |
+        | the owner purges all on an empty cache                          |
+        | the owner purges unused when nothing is unused                  |
+        | the owner purges the variant "hero" and it has no file          |
+        | the owner purges image 1 and it has no file                     |
+        | the owner sends an unknown scope                                |
+        | the owner purges an unknown variant                             |
+        | the owner purges an unknown image                               |
+        | the owner sends GET /v1/image-variants/cache                    |
+
+    Scenario: A failing audit write never changes the response
+      Given the audit repository fails on Append
+      When the owner sends POST /v1/image-variants/cache/purge with {"scope": "all"}
+      Then the response is 200 with the same body and the files are gone
+
+    Scenario: The events read back through the existing activity API
+      Given one event of each of the four scopes was recorded
+      When the owner sends GET /v1/activity?category=media
+      Then the four events are listed with their action, target and params
+
+    Scenario Outline: The Activity screen words each scope
+      Given an activity item with action "<action>", outcome "<outcome>" and the params above
+      Then the sentence reads "<sentence>" and the detail line reads "<detail>"
+
+      Examples:
+        | action                     | outcome | sentence                                  | detail                                                   |
+        | media.variant_purge_all    | success | Purged all variants                       | Removed 1,284 files (212 MB)                             |
+        | media.variant_purge_all    | failed  | Failed to purge all variants              |                                                          |
+        | media.variant_purge_unused | success | Purged unused variants                    | Removed 312 files (41 MB) not requested for 30 days      |
+        | media.variant_purge_unused | failed  | Failed to purge unused variants           |                                                          |
+        | media.variant_purge        | success | Purged the cache of variant “hero”        | Removed 244 files (84 MB)                                |
+        | media.variant_purge        | failed  | Failed to purge the cache of variant “hero” |                                                        |
+        | media.variant_purge_image  | success | Purged the variants of north-wall.jpg     | Removed 6 files (5.8 MB)                                 |
+
+    Scenario: A partial purge adds the failed count to the detail line
+      Given an item "media.variant_purge_all" with params {"purged_files": 640, "purged_bytes": 111149056, "failed_files": 644}
+      Then the detail line reads "Removed 640 files (106 MB) · 644 failed"
+
+  Rule: Cache screen, access and header
+
+    Background:
+      Given the session user has role "owner" or "admin" from GET /v1/auth/me unless a scenario says otherwise
+      And the page uses Nuxt UI components only and design tokens, with no raw hex value and no arbitrary Tailwind colour
+      And every new English string has a French entry in web/src/i18n/messages.ts
+      And the stats come from GET /v1/image-variants/cache once per navigation, and every size is shown with the formatter of the Variants page (1 MB = 1048576), numbers with thousands separators
+      And plain-text API errors are mapped by status, never shown raw
+      And the desktop breadcrumb is "Settings › Media › Cache", the mobile top bar title is "Cache", and the sidebar item "Settings" is current
+
+    Scenario Outline: A session whose role is not owner or admin gets the Forbidden state
+      Given the session has <session>
+      When the user opens /settings/media/cache
+      Then the page shows the empty block with a lock icon, the title "You don't have access" and the text "Only admins can manage image variants. Ask an admin if you need one changed."
+      And it offers one button "Back to Home" with an arrow-left icon, which routes to /home
+      And no header, no tabs, no tile and no list is drawn
+      And <request>
+
+      Examples:
+        | session                           | request                                         |
+        | no role                           | no request to GET /v1/image-variants/cache is sent |
+        | role "owner" but the API answers 403 | the request was sent and its 403 is handled here |
+
+    Scenario: The header and the tabs
+      When the Default fixture is loaded
+      Then the title is "Cache" and the description is "Generated variant files. Purged files are generated again on the next request."
+      And two buttons are shown: "Purge unused" with a clock icon and "Purge all variants" with a trash-2 icon in the danger tone
+      And two tabs follow: "Variants" (icon layers, a link to /settings/media/variants) and "Cache" (icon database, active, medium weight, 2 px primary underline)
+      And activating "Variants" routes to /settings/media/variants, where its own "Cache" tab routes back here
+
+  Rule: Cache screen, loaded
+
+    Scenario: The four stat tiles
+      When the Default fixture is loaded
+      Then four tiles show, as label, value and sub text:
+        | label              | value   | sub text               |
+        | Generated files    | 1,284   | Across 6 variants      |
+        | Disk used          | 212 MB  | Originals not included |
+        | Variants defined   | 6       | 5 enabled, 1 disabled  |
+        | Rejected requests  | 37      | Last 7 days            |
+      And the tiles form four columns on desktop and two on mobile
+
+    Scenario: The By variant list
+      When the Default fixture is loaded
+      Then the card "By variant" lists in the API order:
+        | name   | stats                 | badge    | bar width of the largest |
+        | hero   | 244 files · 84 MB     |          | 100 %                    |
+        | card   | 318 files · 58 MB     |          | 69 %                     |
+        | print  | 74 files · 21 MB      | Disabled | 25 %                     |
+        | thumb  | 412 files · 21 MB     |          | 25 %                     |
+        | square | 140 files · 19 MB     |          | 23 %                     |
+        | og     | 96 files · 9 MB       |          | 11 %                     |
+      And the bar width is the bytes of the row over the largest bytes, 0 when the largest is 0
+      And a disabled variant draws its bar in the border-accented colour and the others in the primary colour
+      And the names are IBM Plex Mono medium and the singular reads "1 file"
+
+    Scenario: The Top 10 list on desktop
+      When the Default fixture is loaded
+      Then the card "Top 10 images by variant disk usage" lists ten rows numbered 1 to 10, each with a 32 x 24 thumbnail of the original, the filename, "N variants", the size and a "Purge" button with an eraser icon
+      And the first row reads north-wall.jpg, 6 variants, 5.8 MB and the last chimney-stack.jpg, 3 variants, 2.1 MB
+      And the singular reads "1 variant"
+
+    Scenario: The Top 10 list on mobile
+      Given the viewport is below 640 px
+      When the Default fixture is loaded
+      Then the tiles are two columns, the two cards stack, each Top 10 row is 60 px high with the size after the count ("6 variants · 5.8 MB") and the Purge button is icon only, 44 px square, with aria-label "Purge north-wall.jpg" and a tooltip
+
+    Scenario: The layout is two columns on desktop
+      Given the viewport is 640 px wide or more
+      Then By variant is 460 px wide and Top 10 takes the rest
+
+  Rule: Cache screen, loading, empty and error
+
+    Scenario: Loading
+      Given GET /v1/image-variants/cache is unresolved
+      Then at 149 ms nothing is drawn and at 150 ms the region has aria-busy and the label "Loading cache"
+      And the four tiles show skeletons for the value and the sub text, By variant shows 5 skeleton rows, Top 10 shows 6 skeleton rows on desktop and is hidden on mobile
+      And a response at 100 ms never draws skeletons
+
+    Scenario: Empty cache
+      Given the stats hold zero files and variants_defined 6
+      Then the tiles read "0 · Nothing cached" for Generated files, "0 MB · Nothing cached" for Disk used, "6 · 5 enabled, 1 disabled" and "37 · Last 7 days"
+      And an empty block with a database icon shows the title "Nothing generated yet" and the text "Variants are generated on the first request with ?v=<name>, or from an image's Variants tab."
+      And "Purge unused" and "Purge all variants" are disabled and no By variant or Top 10 card is drawn
+
+    Scenario Outline: Error loading
+      Given the GET answers <failure>
+      Then an error alert shows the icon circle-x, the title "Couldn't load cache stats", the text "Check your connection and try again." and the button "Try again"
+      And no tile, list or table is drawn and the alert has no close button
+      When the user activates "Try again"
+      Then GET /v1/image-variants/cache is sent again and the Default fixture renders
+
+      Examples:
+        | failure          |
+        | a 500            |
+        | a network error  |
+
+    Scenario: Purge unused is disabled when nothing is unused
+      Given the stats hold "unused" {"files": 0, "bytes": 0, "days": 30} and 1284 files
+      Then "Purge unused" is disabled and "Purge all variants" is enabled
+
+  Rule: Cache screen, purge all with a typed word
+
+    Scenario: The dialog opens with the button disabled
+      When the user activates "Purge all variants"
+      Then a dialog titled "Purge all variants?" shows "This removes 1,284 generated files (212 MB) for every variant. Originals aren't touched. Files are generated again on request."
+      And a field labelled "Type purge to confirm" in IBM Plex Mono is focused, "Cancel" is offered and "Purge all variants" in the danger tone is disabled
+      And no request is sent
+
+    Scenario Outline: The word unlocks the button
+      Given the dialog is open
+      When the user types "<typed>"
+      Then the confirm button is <state>
+
+      Examples:
+        | typed  | state    |
+        | pur    | disabled |
+        | Purge  | disabled |
+        | purge  | enabled  |
+        | purge  | enabled  |
+        | purged | disabled |
+
+    Scenario: Cancel and Escape send nothing
+      When the user activates Cancel, or presses Escape
+      Then the dialog closes, focus returns to "Purge all variants" and no request is sent
+
+    Scenario: Confirming sends the purge
+      Given the typed word is "purge"
+      When the user activates "Purge all variants"
+      Then POST /v1/image-variants/cache/purge is sent once with {"scope": "all"} and the dialog closes
+
+  Rule: Cache screen, purge unused
+
+    Scenario: The dialog states the count from the stats
+      When the user activates "Purge unused"
+      Then a dialog titled "Purge unused variants?" shows "This removes 312 files (41 MB) from enabled variants that haven't been requested for 30 days. Files are generated again on request."
+      And it offers "Cancel" and "Purge 312 files", with no typed word
+
+    Scenario: Confirming sends the purge
+      When the user activates "Purge 312 files"
+      Then POST /v1/image-variants/cache/purge is sent once with {"scope": "unused"}
+
+  Rule: Cache screen, purging, done and failed
+
+    Scenario: Purging
+      Given a purge request is in flight and the stats hold 1284 files
+      Then the page shows an info banner with a loader icon and "Purging 1,284 files" with an indeterminate bar, announced with aria-live="polite"
+      And the tiles and lists are dimmed to 60 % opacity, "Purge unused", "Purge all variants" and every row Purge button are disabled, and the tabs stay active
+
+    Scenario: Purge done after purge all
+      Given the purge answered {"scope": "all", "purged_files": 1284, "purged_bytes": 222298112, "failed_files": 0}
+      Then a success toast reads "Purged 1,284 files, freed 212 MB"
+      And the stats are fetched again once and the empty cache state shows
+
+    Scenario: Purge done after purge unused
+      Given the purge answered {"scope": "unused", "purged_files": 312, "purged_bytes": 42991616, "failed_files": 0}
+      Then a success toast reads "Purged 312 files, freed 41 MB" and the stats are fetched again once
+
+    Scenario: Purge failed
+      Given the purge answered {"scope": "all", "purged_files": 640, "purged_bytes": 111149056, "failed_files": 644}
+      Then an error toast shows the title "Purge didn't finish", the text "640 of 1,284 files were removed. Try again." and the button "Try again"
+      And the stats are fetched again once
+      When the user activates "Try again"
+      Then the same request is sent again, without asking for the word again
+
+    Scenario Outline: A purge request that errors
+      Given the POST answers <failure>
+      Then the banner is removed, the content is restored and a toast shows <title> and <text>
+
+      Examples:
+        | failure         | title                | text                                                                              |
+        | a 400           | Check the request    | A value in the request isn't valid. Reload the page and try again.                |
+        | a 403           | You don't have access| Only admins can manage image variants.                                            |
+        | a 500           | Something went wrong | The server couldn't finish. Try again. If it keeps happening, check the server log. |
+        | a network error | Something went wrong | The server couldn't finish. Try again. If it keeps happening, check the server log. |
+
+    Scenario: A 401 sends the user to sign in
+      Given the POST answers 401
+      Then the user is redirected to sign in and a toast reads "Session expired" with "Sign in again to continue."
+
+  Rule: Cache screen, purging the variants of one image
+
+    Scenario: A row Purge sends the image scope
+      When the user activates "Purge" on the north-wall.jpg row
+      Then POST /v1/image-variants/cache/purge is sent once with {"scope": "image", "image_id": 1} and no confirm dialog is shown
+      And while it runs the row shows a loader on its button and the other Purge buttons stay enabled
+
+    Scenario: Done
+      Given the purge answered {"scope": "image", "purged_files": 6, "purged_bytes": 6082765, "failed_files": 0}
+      Then a success toast reads "Purged 6 files (5.8 MB) for north-wall.jpg" and the stats are fetched again once
+
+    Scenario: The image no longer exists
+      Given the POST answers 404
+      Then a toast shows "Not found" and "This variant or image no longer exists. Refresh the page." and the stats are fetched again
+
+    Scenario: Failed
+      Given the purge answered {"scope": "image", "purged_files": 4, "purged_bytes": 1000, "failed_files": 2}
+      Then the "Purge didn't finish" toast reads "4 of 6 files were removed. Try again." with "Try again"
+
+  Rule: Accessibility and vocabulary
+
+    Scenario: Roles and announcements
+      Then the tabs have role tablist and tab, the dialog traps focus and returns it to its opener, the icon-only buttons have an aria-label and a tooltip, touch targets on mobile are at least 44 px, and every status is an icon plus text
+      And no rendered text contains "thumbnail preset", "version" or "rendition"
+
+  Rule: Layering and hygiene
+
+    Scenario: The dependency rule holds
+      Then internal/domain/image and internal/domain/audit import only the stdlib and other internal/domain packages
+      And the tracker port, the usage repository port and the cache port are declared in internal/domain/image
+      And the new use cases (cache stats, purge cache) and the tracker import no persistence, mailer, models, gorm, net/http, chi or api package
+      And the handler imports no persistence, mailer, models or gorm package
+      And only api/dependecyInjection.go constructs the tracker, starts its flush loop, flushes it on shutdown and wires the use cases into imagevariant.NewHandler and the serve path of the public handler
+      And a repository method with a single-row Find or Save keeps its current signature
+      And the models are listed in internal/infrastructure/persistence/database/migrate.go
+      And no comment is added to any file, except tool directives

features/image_variants_cache.qa.md

@@ -0,0 +1,100 @@
+# QA procedure: image_variants_cache
+
+Two parts: Go for the API and tracking, Vitest for the Cache screen. No live server, no real SQLite file, no real SMTP, no `time.Sleep` (use an injected clock and manual flushes).
+
+## Go (package `test`, black-box)
+
+New files: `test/image_variants_cache_http_test.go`, `test/image_variants_cache_tracking_test.go`, `test/image_variants_cache_purge_test.go`, `test/image_variants_cache_audit_test.go`. Extend `test/image_variants_support_test.go`. Fake type names must stay unique in the package.
+
+### Setup shared by every case
+1. `validator.InitValidator()` once. `jwtauth.New("HS256", []byte("test-secret"), nil)` stands in for `JWT_SECRET`.
+2. Reuse `mockVariantRepo`, `mockVariantFileRepo`, `mockVariantStorage`, `countingRenderer`, `mockImageRepo`, the user fake, the API-key fake and the audit fakes of `test/activity_support_test.go`. Add to `mockVariantFileRepo`: `last_requested_at` per row, the aggregated totals, unused totals (cutoff, enabled variants only), top-images query (limit 10, bytes desc, id asc), batched listing for purge (batch size recorded), the batch update of requested times, with a call counter per method. Add fakes for the usage repository (`mockVariantUsageRepo`: day rows, batch writes counted, switchable failure) and a controllable clock.
+3. Users: owner 1, admin 2, verified plain user 3, unverified user 4. Real signed `jwt` cookies with `user_id` and `token_version`; a stale cookie; a valid API key.
+4. Router: a fresh `chi.NewRouter()` mirroring `NewImageVariantRouter` in `api/router.go` (`jwtauth.Verifier`, `AuditContext`, `RequireSignedIn`, `Authenticator`, `RequireCurrentToken`, `RequireVerifiedUser`, `RequireOwnerOrAdmin`) with `Get("/cache")` and `Post("/cache/purge")` beside the existing variant routes, mounted at `/v1/image-variants`. Mount the real public handler `staticimages.NewHandler(...)` at `/static/uploadedImages` over the same storage, variant use cases and the real tracker.
+5. Seed the Default fixture of the feature (six variants, the per-variant bytes, 312 unused files with the 29/31/30 day boundary rows, the ten top images, 37 rejections over the window). Images are generated in the test with `image/png`, `image/jpeg`, `image/draw`.
+
+### A. Guards
+6. Table of the feature: each method, path and credential gives the status and exact body constant; assert no file, storage, usage or audit fake was touched. API key gets 401. Owner and admin get 200.
+
+### B. Statistics
+7. Default fixture: decode the body and assert every field and value, `by_variant` order and content, `top_images` order, `url`. Sum invariants. Zero-file variant listed; disabled variant in totals but not in `unused`; orphan index rows counted but absent from `top_images`; tie at the tenth place; empty cache raw body `"top_images":[]`; no variant raw `"by_variant":[]`.
+8. `unused` boundaries: 29 days (in use), exactly the cutoff (in use), 31 days (unused), `created_at` fallback, disabled variant excluded.
+9. Aggregation: the file fake saw one totals call, one unused call and one top-images call, regardless of the number of images. A pending-tracking fixture asserts one batch write before the read, and that the 3 pending rejections are in `rejected_requests`. A failing totals call gives 500 `Internal server error`. GET records no audit event and opens no blob.
+
+### C. Tracking
+10. Hits: for each row of the "what counts" table drive the real public handler and assert the pending key set and zero usage writes. 1000 hits on one file: zero writes, then one flush gives one update with the last time. 40 files: one batch of 40. Nothing pending: repository not called. 500 distinct keys trigger a flush without the tick (use the injected trigger, not a timer). Failed batch then recovery: nothing lost, nothing counted twice, latest time wins. A failing repository never fails or slows the public response. The stored time never moves back. A late update for a purged file creates no row.
+11. Rejections: for each row of the table drive the public handler and assert the counter and the status. 1000 rejections: zero writes, one batch adds 1000. Window: clock at 2026-10-08 23:59 UTC, rows of 2026-10-02 counted, 2026-10-01 not. Day boundary at 23:59:59 and 00:00:00 UTC gives two rows. The flush prunes rows older than 7 days. Failed flush keeps the pending counts.
+12. Race (run with `-race`): 50 goroutines record hits and rejections while another flushes; totals written equal totals recorded. Shutdown: closing the container flushes once.
+
+### D. Purge
+13. One case per scope with the numbers of the feature (all 1284 and 222298112, unused 312 and 42991616, variant hero 244 and 88080384, image 1 6 and 6082765): assert the body, each deleted blob name, each deleted row, and that originals and definitions are unchanged. Disabled variant: scope all and scope variant include it; scope unused excludes it. A following public GET renders again.
+14. Empty cache returns zeros. A blob missing from storage still removes its row and counts as purged.
+15. Refusals table: unknown scope, case change, empty body, missing or empty variant, missing, zero and negative `image_id`, unknown variant (404 `Variant not found`), unknown image (404 `Image not found`), invalid JSON (400 `apperr.BodyErrorMessage`). Assert no storage or row change and no audit event. Extra target fields for `all` and `unused` are ignored.
+16. Partial failure: storage fails on 644 rows; 200 with `purged_files` 640, `failed_files` 644, failing rows kept; retry after recovery purges the rest. Listing failure gives 500. Batch size at most 500 over 5000 rows (assert the largest batch the fake returned).
+
+### E. Audit
+17. One case per scope row: action, target (none for all and unused, `image_variant` for variant, `image` for image), outcome, params including `older_than_days` 30 for unused. Partial failure is a success carrying `failed_files`. All-failed is a `failed` event with the generic reason. The no-op rows record nothing. A failing audit repository leaves the response and files unchanged. `GET /v1/activity?category=media` lists the four events. Extend the `failureReasons` mapping test for the two new actions.
+
+### F. Mutation guard
+18. `task mutate` scope is `./internal/infrastructure/useCases`, scoped with `MUTATE_FILES` to the new use case files and `MUTATE_RUN` to the new test names. Each new branch needs a killing assertion: the unused cutoff comparison (below, at and above), the enabled filter of unused, the `purged_files > 0` guard, the success versus failed outcome (`purged > 0` versus `failed > 0`), the top-10 limit and its id tie-break, the window start (7 days) and the never-moving-back time guard. Bare-bool conditions produce no mutant, so cover both branches anyway.
+
+### G. Layering and hygiene
+19. Guard test (`go list -deps` or grep): the domain imports only the stdlib and domain packages; the new use cases and the tracker import no `persistence`, `mailer`, `models`, `gorm`, `net/http`, chi or `api`; the handler imports no `persistence`, `mailer`, `models` or `gorm`. Check `migrate.go` lists `ImageVariantRejectionDay`. `CGO_ENABLED=0 go build -tags nofrontend ./...` succeeds. No comment in new or edited files. `docs/api.md` lists the two routes, the shapes, the scopes and the errors, and `docs/architecture.md` or the variants doc describes the tracker and its 30 second flush.
+
+## Automated (Vitest + Vue Test Utils, `task test:web`)
+
+Mock `useApi`'s `request` per case (GET `/v1/image-variants/cache`, POST `/v1/image-variants/cache/purge`); no backend. Mount `CachePage` inside `DashboardShell` with a resolved verified session (id 1, username "marta", role "owner") and a test router at `/settings/media/cache`. Mock `matchMedia` for the 640 px breakpoint; run layout cases at desktop and below-640. Use fake timers for the 150 ms skeleton delay. No test freezes the system date (this screen shows no date).
+
+Default fixture = the Background of the feature, with the six variants, the ten top images and the numbers above.
+
+1. **Access, Examples-driven**: no role, role "owner", role "admin", 403 on the list. Forbidden copy and "Back to Home"; no request when the role is missing.
+2. **Header and tabs**: title, description, the two buttons with icons, the two tabs; "Variants" routes to `/settings/media/variants`; the Variants page's "Cache" tab now routes here (update the existing VariantsPage spec that asserted aria-disabled); breadcrumb and mobile title.
+3. **Tiles**: the four rows of the table; two columns on mobile, four on desktop.
+4. **By variant**: order, stats text, the Disabled badge, bar width percentages (100, 69, 25, 25, 23, 11), the colour classes for enabled and disabled, `1 file` singular, 0 width when the largest is 0.
+5. **Top 10**: ten rows, numbering, thumbnails, `6 variants`, `1 variant`, sizes; mobile 60 px rows with the size after the count and an icon-only 44 px Purge with aria-label and tooltip.
+6. **Loading**: nothing at 149 ms; at 150 ms `aria-busy`, label "Loading cache", skeleton counts (5 and 6; Top 10 hidden on mobile); a response at 100 ms never draws skeletons.
+7. **Empty**: tile subs "Nothing cached", empty block copy, both purge buttons disabled, no lists. **Purge unused** disabled when unused is 0.
+8. **Error, Examples-driven**: 500 and network error, alert copy, no close button, Try again re-sends and renders.
+9. **Purge all dialog**: copy, focus on the field, confirm disabled; the typed-word table (`pur`, `Purge`, `purge`, `purged`); Cancel and Escape send nothing and return focus; confirm sends `{"scope": "all"}` once.
+10. **Purge unused dialog**: copy with 312 and 41 MB, "Purge 312 files", sends `{"scope": "unused"}`.
+11. **Purging**: banner copy "Purging 1,284 files", `aria-live="polite"`, dimmed content, all purge controls disabled, tabs active.
+12. **Done**: toasts "Purged 1,284 files, freed 212 MB" and "Purged 312 files, freed 41 MB"; one refetch; the empty state after purge all.
+13. **Failed**: toast "Purge didn't finish", "640 of 1,284 files were removed. Try again.", one refetch, Try again re-sends the same body without the typed word.
+14. **Errors, Examples-driven**: 400, 403, 500, network, 401 (redirect then toast), each with the copy of the table; banner removed and content restored.
+15. **Row purge**: sends `{"scope": "image", "image_id": 1}` with no dialog; button loader; other rows enabled; toast "Purged 6 files (5.8 MB) for north-wall.jpg"; 404 toast and refetch; partial failure "4 of 6 files were removed. Try again.".
+16. **Activity sentences** (extend `activitySentence.spec.ts` and `ActivityVariants.spec.ts`): the seven rows of the sentence table, the partial detail line, and `SENTENCE_ACTIONS` including the three actions.
+17. **French**: `setLocale('fr')`; a catalogue test that every key used on the page and in the new sentences exists in `messages.ts`; the page renders without missing keys.
+18. **Vocabulary and accessibility**: no rendered text contains "thumbnail preset", "version" or "rendition"; tabs, labels, focus return.
+
+## Visual (task visual:check -- image-variants, desktop and mobile, light and dark)
+
+NOT RUN: the user forbade running task visual:check for this slice, so every item below is reported NOT RUN.
+
+Reference: `docs/design/screens/image-variants.md` section 5 and the cache frame in `docs/design/source/VariantsFrame.dc.html` (lines 250-278, with `AppFrame.dc.html` for the shell). Add each state to `web/visual/states.ts` with the board's data. The gate: every non-skipped capture within 10 %, both viewports, both themes. None of these states depends on the date or time, so none is skipped.
+
+Board sample data the mocks must reuse: variants thumb 412 files 21 MB, card 318 and 58 MB, hero 244 and 84 MB, square 140 and 19 MB, og 96 and 9 MB, print 74 and 21 MB (disabled); totals 1,284 files and 212 MB; 6 variants, 5 enabled and 1 disabled; 37 rejected requests; unused 312 files and 41 MB; the Top 10 of the frame (north-wall.jpg 6 variants 5.8 MB, lime-plaster.jpg 6 and 4.9 MB, kitchen-after.webp 5 and 4.4 MB, kitchen-before.webp 5 and 3.9 MB, floorboards.jpg 5 and 3.6 MB, IMG_4471.jpg 4 and 3.1 MB, stone-wall-detail.jpg 4 and 2.8 MB, bathroom-tiles.png 4 and 2.6 MB, roof-lantern.jpg 3 and 2.3 MB, chimney-stack.jpg 3 and 2.1 MB); session name "Marta Alves". The mock returns the By variant rows in the board's order (hero, card, then the ties).
+
+- [ ] 5a Loaded
+- [ ] 5b Loading
+- [ ] 5c Empty cache
+- [ ] 5d Purging (the frame draws "640 of 1,284 · 106 MB freed" with a 50 % bar; the draft shows an indeterminate bar and no progress line, so this state is the one at risk against the budget; see open question 1)
+- [ ] 5e Purge done (empty cache; the toast)
+- [ ] 5f Purge failed (toast "Purge didn't finish")
+- [ ] 5g Error loading
+- [ ] 5h Purge all: confirm (typed "pur", button disabled)
+- [ ] 5i Purge all: confirm, typed (typed "purge")
+- [ ] 5j Purge unused: confirm
+- [ ] Layout from the frame, not `components.md`: tiles 4 columns and 16 px gap on desktop, 2 columns and 8 px on mobile; tile padding 16 px (12 px mobile), value 28 px (22 px mobile); two columns 460 px / rest; bars 8 px high; Top 10 rows 40 px (60 px mobile) with the Purge button 26 px high (44 px square icon-only on mobile).
+- [ ] Not drawn, no visual state: the error toasts for 400, 403, 500 and 404, the row-purge toast, the row loader, the disabled Purge unused with a non-empty cache; Vitest only.
+- [ ] Not covered by screenshots: keyboard and focus order (Tab reaches the buttons, the tabs, each Purge; the dialog traps focus and Escape returns it), hover and active states, motion (dialog, skeleton pulse stopped under reduced motion).
+
+## Manual verification
+
+- **Real flush loop**: `task dev:api` over a scratch SQLite file. Request `/static/uploadedImages/<storedName>?v=thumb` repeatedly, wait 30 s, then open the Cache page and check "Rejected requests" after a few `?v=unknown` requests. Check in the file that `last_requested_at` is set once per file and the day row holds the count.
+- **Graceful shutdown**: record hits, stop the server with Ctrl+C within 30 s, restart and check the counts survived.
+- **Real purge**: generate real variants, then purge all, unused (age a row in the file), one image, and check the files disappear from `UPLOAD_DIR` and reappear on request.
+- **S3 driver** (`STORAGE_DRIVER=s3`, MinIO): purge all and by image.
+- **Large cache**: 20,000 index rows; check the Cache page loads in a reasonable time and the purge keeps memory flat.
+- **Other databases**: run the stats and purge against MariaDB and PostgreSQL if available (portable SQL).
+- **Activity screen**: read the four new events against section 8 of the design.
+- **French**: switch the language and read every state, the dialogs and the toasts.