feat(stats): add counter-backed usage and trending stats

Add DB-backed usage counters for users, tokens, and server-wide stats, including current and lifetime upload/file/size totals, feature usage, TTL distributions, download counters, and daily download rollups.

Expose the new stats through user, token, admin, metrics, and trending APIs, update the Vue admin/home/download views, and add sorting by stats-backed size/download fields.

Keep stats safe for multi-instance deployments with atomic metadata mutations, import/export coverage, bounded daily rollup cleanup, and best-effort download stat writes that do not block valid downloads.

Document the stats architecture, cleanup semantics, download counting policy, Prometheus metrics, API fields, and agent review expectations.

Author: ca.mathieu

.agents/workflows/review-changes.md

@@ -54,6 +54,8 @@ For every modified file, evaluate against ALL of the following checklist:
 - [ ] Does the change follow existing patterns in the codebase?
 - [ ] Are naming conventions consistent (variables, functions, types)?
 - [ ] Does it match the code style of surrounding files?
+- [ ] Are non-obvious policy helpers commented? Check public API validators, persistent-state mutations, complex SQL/GORM queries, stats/business policy, security/privacy behavior, and concurrency assumptions.
+- [ ] Do comments explain intent, accepted inputs, defaults, return meaning, or invariants where those are not obvious from nearby code?
 
 #### Completeness
 - [ ] Are all necessary files modified (tests, docs, config)?
@@ -75,6 +77,8 @@ For every modified file, evaluate against ALL of the following checklist:
 - [ ] Are new behaviors covered by tests?
 - [ ] Do existing tests still pass with these changes?
 - [ ] Are test assertions meaningful (not just "no error")?
+- [ ] For large backend changes, compare package coverage before/after and identify new uncovered functions.
+- [ ] Are complex SQL/GORM queries, migrations/backfills, counter mutations, concurrency paths, and public API validation covered by focused backend tests? E2E coverage is useful but not a substitute for these.
 
 #### Documentation (`docs/`, README, `--help`)
 - [ ] Do user-facing docs reflect the new/changed behavior?
@@ -89,6 +93,7 @@ For every modified file, evaluate against ALL of the following checklist:
 - [ ] Are new/changed request/response fields documented with examples?
 - [ ] Are removed or renamed fields noted for backward compatibility?
 - [ ] Are new query parameters listed in the relevant filter table?
+- [ ] Treat HTTP API documentation drift as a critical review finding.
 
 #### CSS / Theming (if webapp styles were changed)
 - [ ] Do changes use design tokens (`surface-*`, `accent-*`) instead of hardcoded colors?
@@ -114,6 +119,7 @@ For every modified file, evaluate against ALL of the following checklist:
 - Verify the change aligns with documented patterns
 - Check if AGENTS.md needs updating
 - **If any HTTP handler, route, or API response struct was modified**: check `docs/reference/api.md` and flag any drift as a 🔴 Critical issue
+- **If stats, counters, migrations, or SQL/GORM queries changed**: verify direct backend tests exist for the new logic and flag E2E-only coverage as a review issue
 
 ### 4. Lint and build
 
@@ -207,4 +213,4 @@ Do NOT auto-fix without asking. Present the findings first, let the user decide.
 - Don't just rubber-stamp changes with "LGTM" unless they're truly clean
 - Pay special attention to subtle issues: off-by-one, missing error handling, stdout/stderr confusion, goroutine leaks
 - If a change seems incomplete (e.g., missing tests for new behavior), flag it
-- Compare against ARCHITECTURE.md and project conventions
+- Compare against ARCHITECTURE.md and project conventions

AGENTS.md

@@ -43,7 +43,7 @@ plik/
 ├── README.md               ← project README (concise)
 ├── Makefile                ← build orchestration
 ├── Dockerfile
-├── .agent/                 ← agentic workflows (/review-changes, /prepare-pr, /cut-release)
+├── .agents/                ← agentic workflows (/review-changes, /prepare-pr, /cut-release)
 ├── server/                 ← Go server (see server/ARCHITECTURE.md)
 │   ├── main.go             ← entry point
 │   ├── plikd.cfg           ← default config
@@ -139,8 +139,24 @@ make vuln                   # govulncheck (report only)
 - **Helm persistence**: the chart has two independent PVCs — `persistence` for uploaded files (`/home/plik/server/files`) and `dbPersistence` for the SQLite database (`/home/plik/server/db`). Both default to `emptyDir` when disabled. The default `MetadataBackendConfig.ConnectionString` is `/home/plik/server/db/plik.db`.
 - **Run tests before committing**: `make lint && make test`
 - **Keep ARCHITECTURE.md files in sync**: Each root folder has its own — update the one closest to your change
+- **Comment non-obvious policy and invariants**: Add concise comments for helpers that validate public API input, mutate persistent state, build complex SQL/GORM queries, encode security/privacy behavior, rely on concurrency assumptions, or implement statistics/business policy. Comments should explain accepted input domains, default behavior, return meaning, and why the rule exists when those details are not obvious from the name and surrounding call site. Prefer comments that explain why the rule exists over comments that restate the code.
+- **Test at the right layer**: E2E tests complement, but do not replace, focused backend tests for SQL/GORM queries, migrations/backfills, counter mutations, concurrency, and public API validation.
 - **Release process**: Before creating a GitHub release, update the version in `README.md` and move `charts/plik/CHANGELOG.md` entries from `[Unreleased]` to the new version heading
 
+## Agent Workflows
+
+Project workflows live in `.agents/workflows/`. Use them when the matching task comes up:
+
+| Workflow | Purpose |
+|----------|---------|
+| `plan.md` | Create an implementation plan before non-trivial features or refactors |
+| `review-changes.md` | Critically review local diffs before committing or preparing a PR |
+| `commit.md` | Commit or push changes with the mandatory user approval gate |
+| `prepare-pr.md` | Run review/pre-flight checks, commit, push, and draft a PR |
+| `cut-release.md` | Walk through the release checklist |
+| `add-language.md` | Add a new webapp locale end to end |
+| `review-language.md` | Review locale quality, placeholders, plurals, and semantic distinctions |
+
 ## Documentation
 
 The documentation lives in two places:
@@ -171,4 +187,3 @@ make docs                    # Build docs (builds client, injects help+plikrc, b
 | [releaser/ARCHITECTURE.md](releaser/ARCHITECTURE.md) | Release tooling: build pipeline, Docker stages, client/server compilation |
 | [charts/plik/ARCHITECTURE.md](charts/plik/ARCHITECTURE.md) | Helm chart: structure, config/secrets separation, persistence, versioning |
 | [.github/ARCHITECTURE.md](.github/ARCHITECTURE.md) | GitHub Actions workflows, CI/CD, Helm chart release flow |
-

ARCHITECTURE.md

@@ -253,9 +253,9 @@ When processing a request, limits are resolved via the custom `Context`:
 | GET | `/me/token` | `GetUserTokens` | List tokens (paginated) |
 | POST | `/me/token` | `CreateToken` | Create upload token |
 | DELETE | `/me/token/{token}` | `RevokeToken` | Revoke token |
-| GET | `/me/uploads` | `GetUserUploads` | List uploads (paginated, sortable by `sort` (`date`/`size`) and `order` (`desc`/`asc`), filterable by `token` and badge settings: `oneShot`, `removable`, `stream`, `extendTTL`, `password`, `e2ee`) |
+| GET | `/me/uploads` | `GetUserUploads` | List uploads (paginated, sortable by `sort` (`date`/`size`/`downloads`) and `order` (`desc`/`asc`), filterable by `token` and badge settings: `oneShot`, `removable`, `stream`, `extendTTL`, `password`, `e2ee`) |
 | DELETE | `/me/uploads` | `RemoveUserUploads` | Remove all uploads |
-| GET | `/me/stats` | `GetUserStatistics` | User stats |
+| GET | `/me/stats` | `GetUserStatistics` | Counter-backed user current + lifetime stats, including stats tracking start timestamp; `token` filters to current API token stats |
 
 ### User Management Endpoints (authenticated — session cookie required)
 
@@ -270,10 +270,12 @@ When processing a request, limits are resolved via the custom `Context`:
 | Method | Path | Handler | Description |
 |--------|------|---------|-------------|
 | POST | `/user` | `CreateUser` | Create user |
-| GET | `/stats` | `GetServerStatistics` | Server stats |
-| GET | `/users` | `GetUsers` | List users (paginated, filterable by `provider` and `admin` status) |
+| GET | `/stats` | `GetServerStatistics` | Counter-backed server current + lifetime stats, downloads, and feature usage counters |
+| GET | `/stats/trending/uploads` | `GetTrendingUploads` | Trending uploads (`window=all\|1d\|7d\|30d`, `limit`) |
+| GET | `/stats/trending/files` | `GetTrendingFiles` | Trending files (`window=all\|1d\|7d\|30d`, `limit`) |
+| GET | `/users` | `GetUsers` | List users (paginated, sortable by `sort` (`date`/`size`/`everSize`), filterable by `provider` and `admin` status) |
 | GET | `/users/search` | `SearchUsers` | Search users by login/name/email (LIKE query, `q`, `limit`, `provider`, `admin`) |
-| GET | `/uploads` | `GetUploads` | List all uploads (paginated, filterable by `user`, `token`, `sort`, badge settings: `oneShot`, `removable`, `stream`, `extendTTL`, `password`, `e2ee`) |
+| GET | `/uploads` | `GetUploads` | List all uploads (paginated, sortable by `sort` (`date`/`size`/`downloads`), filterable by `user`, `token`, and badge settings: `oneShot`, `removable`, `stream`, `extendTTL`, `password`, `e2ee`) |
 
 ---
 
@@ -421,8 +423,23 @@ GORM-based with auto-migrations via gormigrate.
 | `tokens` | `Token` | Upload tokens, FK to users |
 | `settings` | `Setting` | Server settings (e.g., auth signing key) |
 | `cli_auth_sessions` | `CLIAuthSession` | Ephemeral CLI device auth sessions (auto-cleaned) |
+| `user_usage_stats` | `UserUsageStats` | Current/lifetime upload, file, and size counters keyed by user ID, with a stats tracking start timestamp; anonymous usage uses the `__anonymous__` sentinel |
+| `server_usage_stats` | `ServerUsageStats` | Single-row server current/lifetime counters, download totals, upload feature counters, TTL buckets, and file-size buckets |
+| `token_usage_stats` | `TokenUsageStats` | Current/lifetime upload, file, and size counters for current API tokens |
+| `download_stats_daily` | `DownloadStatsDaily` | Daily download rollups keyed by day/entity type/entity ID for trending windows; cleanup keeps today plus 30 previous UTC-day buckets |
 | `migrations` | (gormigrate) | Schema migration history |
 
+### Stats Model
+
+Plik's stats system is database-backed so several server instances can safely share one metadata database. Counters are updated in the same metadata transactions that create uploads, complete files, remove retained data, and record counted downloads. The detailed implementation contract lives in [server/ARCHITECTURE.md](server/ARCHITECTURE.md#stats-architecture); the system-level invariants are:
+
+- **Current stats** describe retained state now: active uploads, uploaded files, retained size, current feature usage, current TTL distribution, and current file-size distribution.
+- **Lifetime stats** describe events since tracking started: ever uploads, ever files, ever size, lifetime feature usage, lifetime TTL distribution, and lifetime file-size distribution.
+- **StartedAt** is the "Stats since ..." timestamp. Migration-created rows start at migration/backfill time because already purged metadata cannot be reconstructed.
+- **Anonymous usage** is tracked through a synthetic `__anonymous__` usage row instead of a real user.
+- **Downloads** are logical intent events, not bytes. Full-file `GET` requests count, start-range `GET` requests count, non-start ranges and malformed ranges do not. Direct file download stats are recorded after auth/status/backend-open/range-policy checks and before streaming completes; archive download stats are recorded after a successful archive close.
+- **Trending and server download windows** use upload/file download counts and daily rollups for `1d`, `7d`, and `30d` UTC-day windows. Trending is admin-only. Cleanup keeps today plus 30 previous UTC-day rollup buckets, one extra bucket beyond the 30-day display window.
+
 ---
 
 ## Documentation

docs/operations/server-cli.md

@@ -146,7 +146,7 @@ plikd file delete --all
 
 ## Cleanup
 
-Remove expired uploads and purge deleted files from the data backend:
+Remove expired uploads, purge deleted files from the data backend, and prune old download statistics used for trends:
 
 ```bash
 plikd clean

docs/reference/api.md

@@ -129,12 +129,13 @@ Requires authenticated session cookie.
 | `GET` | `/me` | Current user info |
 | `PATCH` | `/me` | Update self-editable profile fields (`name`, `email`, `theme`, `language`) |
 | `DELETE` | `/me` | Delete own account |
-| `GET` | `/me/token` | List tokens (paginated) |
+| `GET` | `/me/token` | List tokens (paginated, sortable by `date`, `size`, `everSize`) |
 | `POST` | `/me/token` | Create upload token `{ "comment": "..." }` |
 | `DELETE` | `/me/token/{token}` | Revoke token |
-| `GET` | `/me/uploads` | List uploads (paginated, filterable) |
+| `GET` | `/me/uploads` | List uploads (paginated, filterable, sortable by `date`, `size`, `downloads`) |
 | `DELETE` | `/me/uploads` | Remove all uploads |
-| `GET` | `/me/stats` | User statistics |
+| `GET` | `/me/stats` | User current/lifetime statistics |
+| `GET` | `/me/stats?token=...` | Statistics for one API token |
 
 ## Admin Endpoints
 
@@ -146,10 +147,46 @@ Requires admin session cookie.
 | `GET` | `/user/{userID}` | Get user info |
 | `POST` | `/user/{userID}` | Update user |
 | `DELETE` | `/user/{userID}` | Delete user |
-| `GET` | `/stats` | Server statistics |
-| `GET` | `/users` | List all users (paginated, filterable) |
+| `GET` | `/stats` | Server current/lifetime statistics and feature usage counters |
+| `GET` | `/stats/trending/uploads?window=7d&limit=20` | Trending uploads (`window`: `all`, `1d`, `7d`, `30d`) |
+| `GET` | `/stats/trending/files?window=7d&limit=20` | Trending files (`window`: `all`, `1d`, `7d`, `30d`) |
+| `GET` | `/users` | List all users (paginated, filterable, sortable by `date`, `size`, `everSize`) |
 | `GET` | `/users/search?q=...` | Search users (optional: `provider`, `admin`, `limit`) |
-| `GET` | `/uploads` | List all uploads (paginated, filterable) |
+| `GET` | `/uploads` | List all uploads (paginated, filterable, sortable by `date`, `size`, `downloads`) |
+
+### GET /me/stats
+
+Returns current and lifetime usage for the authenticated user. The optional `token` query parameter returns stats for an API token owned by the user; revoked tokens do not retain historical token stats.
+
+Selected response fields: `uploads`, `files`, `totalSize`, `everUploads`, `everFiles`, `everTotalSize`, `startedAt`.
+
+### GET /me/token
+
+Each token returned by `GET /me/token` includes a `stats` object with current and lifetime token usage (`uploads`, `files`, `totalSize`, `everUploads`, `everFiles`, `everTotalSize`, `startedAt`) plus `lastUploadAt` when the token has created uploads. Supported sort fields are `date` (token creation), `size` (current retained size), and `everSize` (lifetime uploaded size).
+
+### GET /stats
+
+Returns server-wide usage statistics. Current usage fields describe retained data at the time of the request: `users`, `uploads`, `anonymousUploads`, `files`, `totalSize`, `anonymousTotalSize`. Lifetime fields describe activity since `startedAt`: `everUsers`, `everUploads`, `everFiles`, `everTotalSize`, `everAnonymousUploads`, `everAnonymousTotalSize`.
+
+Download fields count logical download events, not transferred bytes: `downloads`, `downloads1d`, `downloads7d`, `downloads30d`.
+
+Download windows are based on UTC calendar days: `downloads1d` is the current UTC day, `downloads7d` is today plus the previous 6 UTC days, and `downloads30d` is today plus the previous 29 UTC days. `downloads` remains all-time.
+
+Feature usage counters are individual upload counters, not combinations: `passwordUploads`, `removableUploads`, `oneShotUploads`, `streamUploads`, `extendTTLUploads`, `e2eeUploads`, `commentUploads`, plus matching `ever*` fields.
+
+TTL distribution counters track creation-time TTL choices for current and lifetime uploads: `ttlNoneUploads`, `ttlLt1hUploads`, `ttl1h1dUploads`, `ttl1d7dUploads`, `ttl7d30dUploads`, `ttlGt30dUploads`, plus matching `everTTL*` fields.
+
+File size distribution counters count files, not bytes, with binary MiB/GiB thresholds: `fileSizeLt1mFiles`, `fileSize1m10mFiles`, `fileSize10m100mFiles`, `fileSize100m1gFiles`, `fileSize1g10gFiles`, `fileSize10g100gFiles`, `fileSizeGt100gFiles`, plus matching `everFileSize*` fields.
+
+### GET /users
+
+Each user returned by `GET /users` includes a `stats` object with current and lifetime usage. Supported sort fields are `date` (user creation), `size` (current retained size), and `everSize` (lifetime uploaded size).
+
+### Trending Stats
+
+Admin-only trending endpoints return current uploads/files ordered by download count. If omitted, `window` defaults to `all`; accepted values are `all`, `1d`, `7d`, and `30d`. `limit` defaults to `20` and is capped at `100`.
+
+Trending items include IDs, display name/comment, user ID, size or file count, `downloadCount`, and `lastDownloadedAt`.
 
 ## Pagination