chore(deps): pin foliate-js f622841 — manual touch scrolling in scrolled layouts

Completes the reader-chrome UX batch (handoff item 7): the gitea
mirror now carries fork 0.5.4, so the pin replaces the temporary
node_modules patch the verification build used. Rebuilt and re-verified
live (chrome starts hidden; flick-down reveals).

.dockerignore

@@ -20,6 +20,9 @@ logs/
 
 # Dependencies (install fresh in container)
 node_modules/
+# Local-only lockfile: a stale one pins old foliate-js commits into builds
+# (npm reuses name@version without re-resolving the git pin)
+package-lock.json
 
 # Environment
 .env

.gitea/workflows/release.yml

@@ -56,6 +56,9 @@ jobs:
           context: .
           file: ./Dockerfile
           push: true
+          # Bake the version into the binary (Admin → Settings → About).
+          build-args: |
+            APP_VERSION=${{ env.TAG }}
           # Publishes both the exact version (e.g. v0.2.0) and the movable "latest" tag.
           # Deployments default to "latest" via ${IMAGE_TAG:-latest} in docker-compose.yml;
           # pin or roll back by setting IMAGE_TAG in .env.

.gitignore

@@ -79,3 +79,6 @@ web/static/vendor/
 VALID_TOKEN
 fresh_token.txt
 session-*.md
+
+# Local prod-export scratch: personal annotation/reading data, never commit
+/export/

AGENTS.md

@@ -0,0 +1,123 @@
+# AGENTS.md — Bookhoard server
+
+Standing rules for any agent or developer working in this repo.
+Project-wide context lives in the sibling repos' AGENTS.md files
+(../bookhoard-app/AGENTS.md is the Android client's).
+
+## Library visibility (family-lens rule) — ALWAYS apply
+
+Per-user library visibility (`library_visibility` table, default-ALLOW:
+every user sees every library unless an admin hides one) must be
+enforced on **every endpoint that returns media metadata or content**.
+It is NOT automatic — enforcement is per-handler.
+
+- **New endpoints that list/filter media or series** MUST filter by the
+  requesting user's visible-library set, and MUST reject an explicit
+  `library_id` outside that set with 403 (never silently pass).
+- Helpers (do not hand-roll):
+  - `handlers`: `(*MediaHandler).visibleLibrarySet` /
+    `(*SeriesHandler).visibleLibrarySet` — membership map + id slice.
+  - `router`: `visibleLibraryIDsFor` — same for SSR routes.
+  - `resolveLibrary` (helpers.go) only honors requested library ids
+    inside the visible set.
+- SQL pattern: `AND (sqlc.narg('visible_library_ids')::uuid[] IS NULL OR
+  library_id = ANY(sqlc.narg('visible_library_ids')::uuid[]))` — see
+  `ListMediaItems`, `GetDistinctSeries`, `SearchMediaItems`.
+- Content endpoints (file bytes, page images) additionally gate per item
+  like `ReaderHandler.ensureItemVisible` / the download endpoint.
+- Tests must pin visibility: hidden library → 403 on the endpoint, and
+  absent from unscoped aggregates.
+
+History: 2026-10-13 (`431fec0`) the series/media listing surfaces
+leaked hidden libraries to any authenticated account — series endpoints
+were name-only across ALL libraries. Fixed; do not regress.
+
+## Tests
+
+- Use `setupTestServer()` from `cmd/server/tests/test_helpers_test.go`
+  (see the Conventions section below for the pool/cleanup rules).
+- Integration tests run against the SHARED dev database: never write
+  destructive SQL without preserving the dev rows (libraries Manga/
+  Comics/Ebooks, testuser's annotations and progress are real data).
+- Test-created users must use `@tests.bookhoard.internal` or
+  `@example.com` emails and "test"-named collections/libraries so the
+  harness cleanup can find them.
+- **NEVER rename or edit the shared admin (`testuser`) in tests** — a
+  renamed admin escapes the cleanup preserve-list and cascades real
+  data (this wiped the dev annotations once; see user_test.go
+  TestUpdateProfileSelfEdit for the dedicated-user pattern).
+- **`testuser` is a LIVE reader**: the dev account genuinely reads in
+  the web reader while the suite runs, so `reading_history` /
+  `reading_progress` rows accrue on it mid-test. Exact-total
+  assertions against that account flap (three stats/analytics tests
+  broke on 2026-10-14 within hours of session capture shipping).
+  Tests that need deterministic data use `setup.RegularToken` +
+  `getRegularUserID` (the fresh per-test user), or assert ranges
+  instead of equals. Related: **no table-wide DELETEs in test
+  cleanups** — sync_integration's `DELETE FROM reading_history WHERE
+  true` destroyed the live reader's stats data on every suite run
+  until scoped to the test-sync users (cascade via user delete).
+
+## Timezones
+
+- The server owns display conversion: clients send instants (RFC3339),
+  the server renders in the requesting user's timezone.
+- Use `utils.FormatTimeInTimezone` / `utils.UserLocation` — never
+  `time.Now().Format(...)` bare (that is server-UTC).
+- Analytics day-buckets must bucket in the user's timezone
+  (`CreatedAt.In(loc)`), and date-range end bounds must be end-of-day.
+
+## Known gotchas (do not relearn)
+
+1. **templ does NOT interpolate `{ expr }` inside quoted attribute
+   values** — it emits the literal text. `x-init="f('{ col.ID }')"`
+   shipped a request to `/api/collections/{ collection.ID }` found by
+   the request logs; the whole attribute value must BE an expression:
+   `x-init={ "f('" + col.ID + "')" }`. Note
+   `class="theme-{ user.Theme }"` has always been literal (harmlessly
+   masked by the JS theme engine).
+2. **SettingsRegistry caches**: writes must go through the settings
+   API (Reload on save). Direct SQL writes to system_settings leave
+   the cache stale until the next API-path write — never "preview"
+   rule changes via psql and expect them applied (2026-10-14: a live
+   curl test flip looked ignored until the API path was used).
+3. **User collections are not dashboard sections**: nothing sets
+   collection show_on_dashboard for user rows, and GetDashboardSections
+   skips empty user sections. Collection detail (JSON + SSR) must NOT
+   route user rows through the dashboard-section path — a 7ce7321
+   regression did exactly that (static detail without library_id
+   returned zero books until 0a7fbd6). Only real system query types
+   (continue-reading etc.) route there; `query_type='filter'` is the
+   schema DEFAULT on every user row, not a query type.
+4. **End-of-day arithmetic**: anchor the END bound to the START of the
+   day, never to NOW(). `now.AddDate(0,0,1) − 1ns` carries this
+   instant's clock time into tomorrow — a range "ending today"
+   resolves tomorrow's calendar date and today's rows land in
+   yesterday's bucket (found twice now: analytics 1601548 and stats
+   2026-10-14). Same trap, two deaths.
+5. **Test binaries run against the LIVE dev DB**: hand-probes made in
+   psql during debugging (seed rows, fake sessions) will silently
+   pollute the next integration run — DELETE them when done (this
+   burned the first stats suite run: a stray 30-min probe row shipped
+   a phantom "185 minutes" failure).
+6. **SaveProgressRequest.DeviceID is NOT always a device**: the
+   web/app progress paths have historically stuffed the USER id into
+   it (it only fed a broadcast label before stats). Anything that
+   dereferences it (reading_history device_id FK, device joins) must
+   probe DeviceExistsForUser first — stats capture does.
+
+## Conventions (absorbed from the retired PROJECT_GUIDELINES.md —
+## only the rules that still matched reality)
+
+- **Runtime is Docker** (Makefile auto-detects docker, falls back to
+  podman). The old "podman only" rule is dead.
+- **The server binary is only built inside the Docker build**
+  (`make rebuild-app`); host-side Go builds are for tests/vet only.
+- **Schema changes go in place** — edit `database/schema/schema.sql`,
+  never create migration files, until a release splits them.
+- **Business logic lives in services**, not handlers; handlers parse
+  requests and call services (all DB access goes through services).
+- **Integration tests**: one `setupTestServer()` per test function;
+  test pools use `max_conns=1`; never create a `pgxpool` per subtest
+  (connection exhaustion); use `t.Cleanup()`-based helpers; table-driven
+  subtests over duplicate functions.

DOCS_SEARCH_IMPLEMENTATION.md

@@ -1065,7 +1065,7 @@ If there's a section about documentation features, mention the new search functi
 
 ## Git Commit Strategy
 
-Follow PROJECT_GUIDELINES.md - make multiple logical commits:
+Follow AGENTS.md conventions - make multiple logical commits:
 
 1. **Backend implementation** (search.go, http_handler.go, router changes)
 2. **Unit tests** (search_test.go)

Dockerfile

@@ -37,10 +37,23 @@ RUN cd templates && templ generate
 RUN npm run build:css:prod
 RUN npm run build:ts
 
+# App version baked into the binary (shown in Admin → Settings → About).
+# Declared after `COPY . .` so a version bump only invalidates this layer.
+# The release workflow passes the git tag, e.g. APP_VERSION=v1.5.
+ARG APP_VERSION=dev
+
 # Build Go binary (cached unless Go files or generated code changes)
 RUN --mount=type=cache,target=/root/go/pkg/mod \
   --mount=type=cache,target=/root/.cache/go-build \
-  CGO_ENABLED=0 GOOS=linux go build -installsuffix cgo -o main ./cmd/server
+  CGO_ENABLED=0 GOOS=linux go build -installsuffix cgo \
+  -ldflags "-X bookhoard/internal/version.Version=${APP_VERSION}" \
+  -o main ./cmd/server
+
+# Materialize the Go module cache into an image layer so the test-runner
+# stage can restore it. GOMODCACHE is /go/pkg/mod; cache mounts elsewhere are
+# ignored by the go tool, and without this copy `go test` in the tests
+# container re-downloads every dependency on each invocation.
+RUN cp -r /go/pkg/mod /app/go-module-cache
 
 # Test runner stage - includes Go runtime and test dependencies
 # This stage is ONLY used for running tests, never deployed to production
@@ -53,6 +66,9 @@ WORKDIR /app
 # Copy everything from builder (includes compiled binary, source code, and dependencies)
 COPY --from=builder /app ./
 
+# Restore the materialized Go module cache so `go test` works offline.
+RUN mkdir -p /go/pkg/mod && cp -r /app/go-module-cache/. /go/pkg/mod/ && rm -rf /app/go-module-cache
+
 # Install kepubify for conversion tests
 RUN wget -O /usr/bin/kepubify https://github.com/pgaskin/kepubify/releases/latest/download/kepubify-linux-64bit \
   && chmod +x /usr/bin/kepubify

Makefile

@@ -1,4 +1,4 @@
-.PHONY: help test test-integration test-all rebuild rebuild-force rebuild-app rebuild-app-force rebuild-force-db clean restart up down logs ps test-env-up test-env-down verify-guidelines verify-quick release
+.PHONY: help test test-integration test-all rebuild-app rebuild-app-force rebuild rebuild-force rebuild-force-db clean restart up down logs ps test-env-up test-env-down release
 
 # Include .env file for environment variables (single source of truth)
 # Ignore if .env doesn't exist yet
@@ -42,8 +42,6 @@ help:
 	@echo "  make test-env-down     - Stop test environment"
 	@echo ""
 	@echo "Verification:"
-	@echo "  make verify-guidelines - Run comprehensive guidelines check"
-	@echo "  make verify-quick      - Run quick guidelines check"
 	@echo ""
 	@echo "Release:"
 	@echo "  ./release v0.3.0            - Tag, push, and release (notes auto-generated from commits)"
@@ -153,14 +151,7 @@ test-env-up:
 test-env-down:
 	$(COMPOSE) down -v
 
-# Verify project guidelines compliance
-verify-guidelines:
-	@echo "Running comprehensive project guidelines verification..."
-	@./scripts/verify-guidelines.sh
 
-verify-quick:
-	@echo "Running quick project guidelines verification..."
-	@./scripts/verify-quick.sh
 
 # Create an annotated version tag carrying auto-generated release notes (git-cliff)
 # and push it. The tag push triggers .gitea/workflows/release.yml, which builds the

PROJECT_GUIDELINES.md

@@ -1,480 +0,0 @@
-# Combined Project Guidelines for Bookhoard
-
-## 🚨 CRITICAL PROHIBITIONS (Never violate these)
-
-### Backend & Database
-
-- ❌ **NEVER modify backend code when working on frontend-only tasks*
-- ❌ **NEVER modify database schema** unless explicitly instructed for full-stack changes
-- ❌ **NEVER use Docker** - use Podman only
-- ❌ **NEVER build server binaries locally** - all builds through Dockerfile/docker-compose
-- ❌ **NEVER create new migration files** - merge changes into current one until release
-- ❌ **NEVER use `git checkout` on schema files** without checking what will be lost
-- ❌ **NEVER break existing functionality** unless explicitly instructed
-- ❌ **NEVER duplicate business logic** - keep logic in services, not handlers
-- ❌ **NEVER bypass service layer** - all database operations must go through services
-
-### Testing
-
-- ✅ **ALWAYS use `setupTestServer()` helper from `cmd/server/tests/test_helpers_test.go`*
-- ✅ **Share one test setup across all subtests** - call `setupTestServer()` once at test function level, not per subtest
-- ✅ **Prefer table-driven tests** - use `t.Run()` with test cases instead of duplicate test functions
-- ✅ **Configure database pools efficiently** - use `max_conns=1` for test pools (via `pgxpool.ParseConfig()`) to prevent connection exhaustion
-- ❌ **NEVER create separate `pgxpool` per test** - each pool creates 4 connections by default; 78 tests = 312 potential connections > PostgreSQL's 100 limit
-- ❌ **NEVER call `setupTestServer()` in loops or within subtests** - creates unnecessary database pools and exhausts connections
-- ✅ **DO verify tests pass** - run full test suite before completing work
-- ✅ **Use `t.Cleanup()` properly** - the `TestServerSetup` pattern automatically handles cleanup via `t.Cleanup()`
-
-### Frontend & Styling
-
-- ❌ **NEVER modify backend/API for frontend features without user confirmation*
-- ❌ **NEVER use custom CSS** - TailwindCSS classes only
-  - **⚠️ EXCEPTION**: `templates/error.templ` may have inline CSS because error pages must work when main app fails (404, server errors, CSS fails to load)
-- ❌ **NEVER use JavaScript** - convert all to TypeScript
-  - **⚠️ EXCEPTION**: Inline JS function calls in HTML attributes (e.g., `onclick="myFunction()"`) are acceptable for simple interactions
-- ❌ **NEVER use Object-Oriented Programming** (no classes, inheritance, or this-capture)
-- ✅ **DO use procedural/imperative style** as your default
-- ✅ **DO borrow functional techniques** when they simplify code
-- ✅ **DO avoid ideological purity** - the best paradigm is the one that fits the problem
-- ❌ **NEVER add new Dockerfiles without user confirmation*
-- ❌ **NEVER fetch initial data via AJAX on page load** - use server-side rendering instead
-- ❌ **NEVER break progressive enhancement** - pages must work without JavaScript
-
-**Note:** Go methods in the backend are fine and encouraged. This guideline applies to TypeScript/JavaScript frontend code only.
-
-### General
-
-- ❌ **NEVER skip pre-commit hooks** unless explicitly requested
-- ❌ **NEVER force push to main/master** branches
-- ❌ **NEVER commit files with secrets** (.env, credentials.json, etc.)
-- ❌ **NEVER make assumptions** - ask clarifying questions when uncertain
-- ❌ **NEVER delete code without reading full context first** (minimum 20 lines before/after)
-- ❌ **NEVER make cascading fix-up edits without git diff review*
-  - After compilation error: STOP, review `git diff`, understand full impact
-  - Use revert/reapply pattern instead of blind fixes
-- ❌ **NEVER skip post-edit verification** - must compile after each file edit
-- ❌ **NEVER run git commands concurrently** - always run sequentially:
-  - Run `git add <files>` and wait for completion
-  - Run `git commit -m "<message>"` and wait for completion
-  - Run `git push` and wait for completion
-  - Never use `&&` to chain git commands together
-- ✅ **Make good organized git commits for the entire project (not just what you changed) and push - run git add, commit, push sequentially as separate commands, no need to repeatedly check status*
-- ✅ **Indentation is always 2 spaces unless the language prohibits it*
-
-### Cascading Fix-up Pattern (PROHIBITED)
-
-**WHAT NOT TO DO** - This caused critical bugs:
-
-```go
-// ❌ WRONG: Blindly making fixes after compilation error
-
-Edit 1: Delete deprecated code
-[Compilation error: undefined Register]
-
-Edit 2: Try to fix error (over-broad deletion)
-[More errors: undefined Login, GetProfile, etc.]
-
-Edit 3: Try to fix again (worse damage)
-[Even more errors: major functionality broken]
-```
-
-**CORRECT APPROACH**:
-
-```go
-// ✅ CORRECT: Stop, understand, then fix deliberately
-
-Edit 1: Delete deprecated code
-[Compilation error: undefined Register]
-
-STOP → Review git diff → Understand Register was accidentally deleted
-RESTORE → Get exact Register function from git history
-VERIFY → Compile successfully
-```
-
-**Key Principle**: When compilation errors occur after edits:
-
-1. STOP - Don't make more edits
-2. ANALYZE - Use `git diff` to understand what was changed
-3. RECOVER - Restore what was accidentally deleted/broken
-4. VERIFY - Compile and test before proceeding
-
----
-
-## 🎯 CONTEXT-SPECIFIC RULES
-
-### When Working on Frontend-Only Tasks
-
-- **DO NOT touch backend code** - handlers, services, database layer
-- **DO NOT modify API routes** - use existing endpoints only
-- **DO NOT change database schema** - work with existing structure
-- **If backend change seems necessary**:
-  1. Identify the required change
-  2. Explain why you need it
-  3. Provide impact analysis
-  4. **ASK FOR USER CONFIRMATION before proceeding*
-
-### When Working on Full-Stack Tasks
-
-- Backend changes are allowed when explicitly part of the task
-- Still follow all database protocols (atomic changes, validation, etc.)
-- **If modifying database schema:** Update local database after schema.sql changes (see Database Operations section)
-- Still use Podman for all builds
-- Still include Bruno requests for API changes
-
----
-
-## ✅ MANDATORY REQUIREMENTS
-
-### Database Operations (Full-Stack Tasks Only)
-
-- ✅ Follow **pgx v5 standards** for all database operations
-- ✅ Treat schema changes as **ATOMIC** - complete success or complete rejection
-- ✅ **⚠️ CRITICAL: This is a pre-production application (NO production deployments exist)*
-  - When `database/schema/schema.sql` is updated, local databases must be updated
-  - **Option 1 (Recommended):** Recreate database with fresh schema:
-    ```bash
-    podman compose down -v  # Delete volumes (WARNING: loses all data)
-    podman compose up -d    # Start fresh with new schema
-    ```
-  - **Option 2:** Manually apply schema changes to existing database using psql
-  - **DO NOT create migration files** - no legacy schema support needed
-- ✅ Use **pre-change checklist**: read schema → identify columns → plan changes → verify → read back
-- ✅ **Post-change validation**: ensure schema.sql, models.go, and queries.sql are in sync
-
-### Build & Deployment
-
-- ✅ Use **Podman** exclusively (not Docker)
-- ✅ All builds through existing **Dockerfile** and **docker-compose.yml*
-- ✅ Stop building server binaries - everything goes through containers
-
-### API Changes (Full-Stack Tasks Only)
-
-- ✅ Include **Bruno OpenCollection YAML requests** with all API documentation
-- ✅ Integration Tests (cmd/server/tests) must be **comprehensive and cover three contexts**: no user, user, and admin
-- ✅ Maintain backward compatibility for mobile apps and external consumers
-
-### Frontend & Styling
-
-- ✅ Always use **TailwindCSS classes** for all styling
-- ✅ Convert all JavaScript to **TypeScript**
-- ✅ **Never use Object-Oriented Programming** (no classes, inheritance, or this-capture)
-- ✅ **Use procedural/imperative style** as your default
-- ✅ **Borrow functional techniques** when they simplify code
-- ✅ **Avoid ideological purity** - the best paradigm is the one that fits the problem
-- ✅ **Extract domain concepts/types only when clearly beneficial** - apply YAGNI, avoid over-engineering
-- ✅ **Render initial data server-side** in Go templates for fast page loads
-- ✅ **Use JavaScript/HTMX for CRUD operations** (create, update, delete)
-- ✅ **Ensure progressive enhancement** - pages work without JavaScript
-
-### Service Layer Architecture
-
-- ✅ **All business logic in services** - never in handlers
-- ✅ **Services must be reusable** by both SSR handlers and API endpoints
-- ✅ **Database operations through services only** - never direct from handlers
-- ✅ **When adding features**: Add service logic → Create API endpoint → Use SSR for initial render → Use JS for updates
-
-### Code Organization
-
-- ✅ Minimize project structure changes
-- ✅ Place new files in **contextually appropriate directories*
-- ✅ Follow **KISS**, **DRY**, and **YAGNI** principles
-- ✅ Use **multiple, logical git commits** with clear messages
-- ❌ **NEVER duplicate types between handlers and templates** - define data types in handlers, reuse directly in templates
-- ✅ **DO share handler types with templates** - templates should use handlers.CollectionData, handlers.BookInfo, etc. directly
-- ❌ **NEVER create parallel type systems** - no templates.XxxData types for data that originates from handlers
-- ✅ **DO enhance handler types with template-specific fields** when needed (e.g., add Icon, FormattedDate fields to handlers structs)
-- ✅ **DO keep template-only types in templates package** - PageData, UnsafeHTML, and template-specific utilities are appropriate
-- ❌ **NEVER create conversion helper functions** to map between handler and template types - use handler types directly
-
-### Configuration & Environment
-
-- ✅ If **.env is missing**, auto-generate secure values
-- ✅ Never commit secrets to repository
-
-### Code Modification Safety
-
-- ✅ **Post-Edit Verification (MANDATORY for ALL file modifications)**:
-  - Run `go build` for affected packages immediately after each edit
-  - Review `git diff filename` to verify only intended changes
-  - Validate functionality still works as expected
-  - Never proceed to next file until current edit is verified
-- ✅ **Backup Before Large Changes**:
-  - Create a stash: `git stash push -m "Pre-cleanup snapshot"` before removing >50 lines
-  - Or create a backup branch: `git branch backup-before-cleanup`
-  - This allows instant recovery if mistakes occur
-- ✅ **Large Deletion Safety Pattern**:
-  - Read at least 20 lines before/after deletion target
-  - Include unique identifiers in match (function signatures, specific comments)
-  - Use narrow matches - avoid generic patterns
-  - Verify line numbers match intended section
-
-### Documentation
-
-**Documentation Structure** (updated with full docs system):
-
-- ✅ **README.md** - Project overview, quick start, and setup instructions only
-- ✅ **docs/** - Comprehensive documentation system with search
-- ✅ **docs/developer/api/** - API reference documentation (split by endpoint/category)
-- ✅ **docs/user/** - User-facing features, guides, and workflows
-- ✅ **docs/user/devices/** - Device setup guides (KOBO, KOReader, etc.)
-- ✅ **docs/contributing/** - Development and contribution guides
-
-**Where to document changes**:
-
-| Change Type                         | Location                                                      | Examples                                                  |
-| ----------------------------------- | ------------------------------------------------------------- | --------------------------------------------------------- |
-| **User-facing features**            | `docs/user/`                                                  | New features, UI changes, workflows                       |
-| **API endpoints**                   | `docs/developer/api/<category>/<endpoint>.md`                 | New endpoints, modified responses, authentication changes |
-| **API behavior**                    | Update existing `docs/developer/api/` files                   | Parameter changes, error codes, rate limits               |
-| **Device setup**                    | `docs/user/devices/`                                          | New device support, setup instructions                    |
-| **Development**                     | `docs/contributing/`                                          | Build changes, architecture decisions                     |
-| **Quick start/setup**               | `README.md`                                                   | Installation, environment setup, first-run                |
-| **Breaking changes**                | Both `README.md` and relevant `docs/`                         | Migration guides, deprecation notices                     |
-| **Bug fixes**                       | Update relevant `docs/` only if user-visible                  | Clarifications, troubleshooting additions                 |
-| **Bruno OpenCollection YAML requests** | `.yml` files in bruno folder in appropriate folder/sub-folder | API contract testing, examples                            |
-
-**Documentation Update Workflow**:
-
-1. **Identify the audience** (end users, developers, API consumers)
-2. **Choose appropriate location** based on table above
-3. **Update documentation** before or with code changes
-4. **Verify documentation renders** at `/docs` endpoint
-5. **Test search** finds new/updated content
-6. **For API changes**: Update both `docs/developer/api/` files, integration test files (cmd/server/tests) AND Bruno OpenCollection YAML `.yml` files
-7. **Commit separately** with clear message: `docs: <description>`
-
-**When in doubt**:
-
-- End-user visible → `docs/user/`
-- API reference → `docs/developer/api/`
-- Setup/onboarding → `README.md`
-- Development related → `docs/contributing/`
-
-### Process & Continuity
-
-- ✅ If mid-task and receive "no response", **continue the task*
-- ✅ Verify no regressions before modifying/removing code
-
----
-
-## 🔧 TECHNICAL STANDARDS
-
-### Backend Stack
-
-- **Language**: Go 1.25+
-- **Database**: PostgreSQL 15+ with **pgx v5 driver** only
-- **Authentication**: JWT tokens with bcrypt password hashing
-- **Architecture**: Service layer pattern (handlers → services → database)
-
-### Frontend Stack
-
-- **Rendering**: SSR-first - Go templates render initial page with all data
-- **Interactivity**: Alpine.js for UI state (modals, dropdowns, transitions)
-- **Dynamic Updates**: HTMX for CRUD operations (no full page reloads)
-- **Styling**: TailwindCSS (no custom CSS)
-- **Language**: TypeScript (no JavaScript)
-- **Patterns**: Procedural/imperative with functional techniques where helpful (no OOP)
-
-### SSR-First Principles
-
-- ❌ **NEVER fetch initial data via AJAX** - server renders complete page
-- ❌ **NEVER fetch data in Alpine x-init** - data already SSR'd
-- ✅ **Use Alpine.js only for UI state** - modal visibility, dropdown toggles
-- ✅ **Use HTMX for dynamic operations** - form submissions, partial page updates
-- ✅ **x-init is for setup only** - event listeners, not data fetching
-- ✅ **Data fetching happens after user actions** - not on page load
-
-### Page Type Classifications
-
-1. **Type 1: 80% SSR (most pages)**
-   - Backend provides all initial data
-   - Alpine handles modals/dropdowns only
-   - x-init NEVER fetches data
-
-2. **Type 2: SSR + Interactive (dashboard, bookshelf)**
-   - Backend provides initial data
-   - Alpine handles interactivity (drag-drop, filtering)
-   - x-init ONLY sets up event listeners
-
-3. **Type 3: 80% TypeScript (analytics, complex dashboards)**
-   - Some client-side data fetching acceptable
-   - Still prefer SSR when possible
-
-### Containerization
-
-- **Runtime**: Podman (not Docker)
-- **Build**: Existing Dockerfile and docker-compose.yml only
-- **No local builds** allowed
-
----
-
-## 🔄 ERROR RECOVERY PROTOCOL
-
-When code modification mistakes occur (deleted wrong code, broke compilation, etc.):
-
-### Immediate Actions
-
-1. **STOP** - Don't make more edits
-2. **ASSESS** - What was deleted? Is it critical?
-3. **REVIEW** - Run `git diff` to see exact changes
-4. **RESTORE** - Choose appropriate recovery method:
-   - **Recent mistake**: `git checkout -- filename`
-   - **Complex restoration**: Use `git show HEAD:filename` to recover deleted code
-   - **Multiple files**: `git reset HEAD~1` (if safe)
-5. **VERIFY** - Compile and test restored code
-6. **DOCUMENT** - Note what went wrong for future reference
-
-### Recovery Examples
-
-```bash
-# Recover a deleted function from original file
-git show HEAD:internal/handlers/auth.go | sed -n '70,275p' > recovery.txt
-
-# Revert entire file to original state
-git checkout HEAD -- internal/handlers/auth.go
-
-# Use git stash to save current state before rollback
-git stash push -m "Broken state before fix"
-git checkout -- internal/handlers/auth.go
-```
-
-### Prevention (Learn From Mistakes)
-
-- Why did the mistake happen?
-- Was it too-broad matching?
-- Was it insufficient context reading?
-- Was it cascading fix-up attempts?
-- Update guidelines to prevent recurrence
-
----
-
-## 📋 WORKFLOW CHECKLISTS
-
-### Before Making Frontend-Only Changes
-
-- [ ] Identify if backend modification could make implementation simpler
-- [ ] Plan to use existing API endpoints only
-- [ ] If backend change seems necessary, prepare confirmation request:
-  - Required change description
-  - Why it would help
-  - Impact analysis
-  - Alternative approaches considered
-- [ ] Plan git commit structure (multiple logical commits)
-- [ ] **Identify documentation location** (see Documentation section):
-  - [ ] User-facing feature → `docs/user/`
-  - [ ] UI/workflow changes → `docs/user/`
-  - [ ] Setup instructions → `README.md`
-
-### Before Making Full-Stack Changes
-
-- [ ] Read current schema completely (if database changes)
-- [ ] Identify all columns that must be preserved
-- [ ] Plan exact changes needed
-- [ ] Verify Podman will be used for builds
-- [ ] Plan git commit structure (multiple logical commits)
-- [ ] **Identify documentation location**:
-  - [ ] API changes → `docs/developer/api/<category>/`
-  - [ ] New endpoints → Create new `.md` file in `docs/developer/api/`
-  - [ ] API behavior → Update existing `docs/developer/api/` files
-  - [ ] Breaking changes → Both `README.md` + relevant `docs/`
-  - [ ] Bruno OpenCollection YAML `.yml` files → Update/create alongside API changes
-  - [ ] Integration tests (cmd/server/tests) → Update/create alongside API changes
-
-### During Schema Changes (Full-Stack Only)
-
-- [ ] Read current schema completely
-- [ ] Identify all columns that must be preserved
-- [ ] Plan exact changes needed
-- [ ] Set up verification step
-- [ ] Make intended changes
-- [ ] Immediately verify by reading back modified sections
-- [ ] Confirm ALL expected columns are present
-- [ ] Verify schema.sql, models.go, and queries.sql are in sync
-- [ ] **Update local database** (choose ONE):
-  - [ ] **Option 1 - Recreate database** (recommended, loses data):
-    ```bash
-    podman compose down -v  # Delete all volumes
-    podman compose up -d    # Start with fresh schema
-    ```
-  - [ ] **Option 2 - Manual SQL migration** (preserves data):
-    ```bash
-    podman exec bookhoard_db psql -U postgres -d bookhoard -c "YOUR SQL HERE"
-    ```
-- [ ] Verify database has new schema (check column types, indexes, etc.)
-
-### After API Changes
-
-- [ ] Create/update Bruno OpenCollection YAML requests
-- [ ] Create/update Integration tests (cmd/server/tests) 
-- [ ] Test with no user context
-- [ ] Test with regular user context
-- [ ] Test with admin context
-- [ ] Verify backward compatibility
-
-### Before Committing
-
-- [ ] **Run verification script**: `bash scripts/verify-guidelines.sh`
-- [ ] **Fix any errors** - verification must pass (0 errors) to commit
-- [ ] **Note warnings** - informational only, do not auto-fix
-- [ ] Run tests: `go test ./... -v`
-- [ ] Run lint/typecheck if available
-- [ ] Ensure no secrets in changes
-- [ ] Verify logical commit structure
-- [ ] **Update documentation** (see Documentation section):
-  - [ ] User-facing changes → `docs/user/`
-  - [ ] API changes → `docs/developer/api/` + Integration tests + Bruno OpenCollection YAML `.yml` files
-  - [ ] Setup/onboarding → `README.md`
-  - [ ] Development changes → `docs/contributing/`
-- [ ] **Verify docs render** at `/docs` endpoint
-- [ ] **Test docs search** finds new content
-
-### Error Recovery Protocol (If Code Mistakes Occur)
-
-- [ ] **Stop immediately** - don't make more edits
-- [ ] **Assess impact**: What was deleted? Is it critical?
-- [ ] **Review git diff**: See exact changes made
-- [ ] **Restore strategy**:
-  - If recent mistake: `git checkout -- filename`
-  - If complex: Reconstruct from git diff using `git show HEAD:filename`
-- [ ] **Verify recovery**: Compile and test restored code
-- [ ] **Document mistake**: Note what went wrong for future reference
-
-### Phase Completion Verification (Before Declaring "Complete")
-
-- [ ] All target code is removed/intact as intended
-- [ ] No unintended code was deleted
-- [ ] All affected files compile successfully
-- [ ] Run `go build ./...` for entire project
-- [ ] **Run verification script**: `bash scripts/verify-guidelines.sh` - must pass (0 errors)
-- [ ] No critical functionality was broken
-- [ ] Git diff shows only intended changes
-- [ ] Review all modified files with `git diff --stat`
-
----
-
-## 🏗 ARCHITECTURAL PATTERNS
-
-### Current: SSR-First with Alpine.js + HTMX
-
-```
-Browser → Go template (SSR with all data) → Display instantly
-                      ↓
-        Alpine.js for UI state (modals, dropdowns)
-                      ↓
-                 HTMX for CRUD (forms, updates)
-                      ↓
-           Shared service layer (Go)
-```
-
-**Layer Responsibilities:**
-
-| Layer | Responsibility |
-|-------|---------------|
-| **Go Template** | SSR initial page with real data |
-| **Alpine.js** | UI state only (x-data, x-show, transitions) |
-| **HTMX** | Dynamic updates without page reload |
-| **TypeScript** | Pure business logic (API calls, data processing) |
-
-**See also:** `SSR_FIRST_ALPINE_GUIDE.md` and `ALPINE_COMPLETION_GUIDE.md`
-
-Ultimately, whenever you are unsure just ask for confirmation.

README.md

@@ -127,6 +127,32 @@ The first user to register automatically becomes an admin.
 
 ---
 
+## 💾 Network Storage (NAS / NFS / SMB)
+
+Libraries on network mounts are supported for everyday use — serving,
+reading, progress, and annotation sync all work over the mount — with a
+few behaviors worth knowing:
+
+- **Outage hysteresis.** When the mount drops, files miss one scan
+  (marked missing, hidden) then a second (archived, still recoverable).
+  When the mount returns — by path or by identical content elsewhere —
+  everything is restored automatically: annotations, progress, and
+  covers included.
+- **Retention purge.** Archived items older than `ARCHIVE_RETENTION_DAYS`
+  (default **90**, `0` = never auto-purge) are deleted for good by
+  library scans, annotations included. A NAS offline longer than the
+  retention window loses those books' metadata on return.
+- **Deleting while the storage is down is refused.** Deleting a book
+  cascades its annotations, so deletes are rejected with a clear error
+  while the item's library storage is unreachable. Archive the item
+  instead, or retry when the mount is back.
+- **Watch mode does not fire on network mounts** (inotify doesn't work
+  over NFS/SMB). The periodic scan is the change detector.
+- **Latency** — folder reachability checks are cached ~30s; large
+  libraries on slow mounts will still feel slower than local disk.
+
+---
+
 ## 🛠 Tech Stack
 
 - **Backend**: Go 1.25+ with Echo framework

bruno/notes/Create Media Note.yml

@@ -27,7 +27,7 @@ docs: |-
     - `id` (string): Media item ID
     
     **Request Body:**
-    - `content` (string): Note content (required, 1-10000 chars)
+    - `content` (string): Note content (required, 1-100000 chars)
     - `position` (string): Optional position reference (max 100 chars)
     
     **Response:**

bruno/notes/Update Media Note.yml

@@ -28,7 +28,7 @@ docs: |-
     - `noteId` (string): Note ID
     
     **Request Body:**
-    - `content` (string): Updated note content (required, 1-10000 chars)
+    - `content` (string): Updated note content (required, 1-100000 chars)
     - `position` (string): Updated position reference (optional, max 100 chars)
     
     **Response:**

cmd/server/main.go

@@ -10,6 +10,7 @@ import (
 	"bookhoard/internal/router"
 	"bookhoard/internal/services"
 	"bookhoard/internal/sync"
+	"bookhoard/templates"
 	"context"
 	"log"
 	"time"
@@ -56,6 +57,20 @@ func main() {
 	if err := registry.Load(ctx); err != nil {
 		log.Printf("⚠️ Could not load system settings (using defaults): %v", err)
 	}
+
+	// Public signup surfaces follow the registration_enabled flag, with the
+	// first-user exception: an unconfigured server (zero admins) keeps its
+	// signup links and registration route reachable for bootstrapping.
+	templates.SetSignupVisibility(func() bool {
+		if registry.RegistrationEnabled() {
+			return true
+		}
+		count, err := queries.CountAdmins(context.Background())
+		if err != nil {
+			return true // fail open, matching setupstatus
+		}
+		return count == 0
+	})
 	// Wire the registry into the package-level password validator so live
 	// rule changes apply to the echo struct-tag validator and ValidatePassword.
 	middleware.SetDefaultPasswordSettings(registry)
@@ -121,6 +136,9 @@ func main() {
 
 	// Create library service
 	libraryService := services.NewLibraryService(queries)
+	// The progress service verifies submitted anchors against the book
+	// itself — it needs to resolve library-relative file paths.
+	progressService.SetMediaPathResolver(libraryService)
 
 	// Sync Go AllowedExtensions into DB so API clients see correct extensions
 	libraryService.SyncAllowedExtensions(context.Background())
@@ -137,6 +155,8 @@ func main() {
 	wsHandler := handlers.NewWSHandler(queries, connManager, cfg.JWTSecret, deviceAuthMiddleware)
 	conflictHandler := handlers.NewConflictHandler(queries, connManager)
 	analyticsHandler := handlers.NewAnalyticsHandler(queries)
+	statisticsService := services.NewStatisticsService(queries)
+	statsHandler := handlers.NewStatsHandler(statisticsService)
 	queueHandler := handlers.NewQueueHandler(queries, queueProcessor)
 
 	conversionService := services.NewConversionService(queries, "/var/bookhoard/cache/kepub")
@@ -208,6 +228,8 @@ func main() {
 		WSHandler:               wsHandler,
 		ConflictHandler:         conflictHandler,
 		AnalyticsHandler:        analyticsHandler,
+		StatsHandler:            statsHandler,
+		StatisticsService:       statisticsService,
 		QueueHandler:            queueHandler,
 		CollectionHandler:       collectionHandler,
 		FiltersHandler:          filtersHandler,

cmd/server/tests/analytics_test.go

@@ -93,8 +93,12 @@ func TestAnalyticsReadingStats(t *testing.T) {
 	})
 
 	t.Run("GetReadingStats_EmptyHistory", func(t *testing.T) {
+		// The REGULAR user, deliberately: the shared dev DB carries a
+		// live reader on `testuser` whose real sessions accrue even
+		// while the suite runs, so "empty history" only holds for a
+		// freshly-created account.
 		req, _ := http.NewRequest("GET", setup.Server.URL+"/api/analytics/reading-stats", nil)
-		req.Header.Set("Authorization", "Bearer "+setup.Token)
+		req.Header.Set("Authorization", "Bearer "+setup.RegularToken)
 
 		resp, err := client.Do(req)
 		require.NoError(t, err)
@@ -351,8 +355,11 @@ func TestAnalyticsPopularBooks(t *testing.T) {
 	})
 
 	t.Run("GetPopularBooks_NoReadingHistory", func(t *testing.T) {
+		// The REGULAR user, deliberately: the live dev-reader's sessions
+		// accrue on `testuser` while the suite runs, so an empty-history
+		// assertion only holds for a fresh account.
 		req, _ := http.NewRequest("GET", setup.Server.URL+"/api/analytics/popular-books", nil)
-		req.Header.Set("Authorization", "Bearer "+setup.Token)
+		req.Header.Set("Authorization", "Bearer "+setup.RegularToken)
 
 		resp, err := client.Do(req)
 		require.NoError(t, err)

cmd/server/tests/collections_smart_test.go

@@ -0,0 +1,353 @@
+package main
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"testing"
+	"time"
+
+	"github.com/google/uuid"
+	"github.com/jackc/pgx/v5/pgtype"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"bookhoard/internal/database"
+)
+
+// HTTP helpers -----------------------------------------------------------
+
+func smartCreateCollection(t *testing.T, setup *TestServerSetup, token, name string, collectionType string) string {
+	t.Helper()
+	payload := map[string]interface{}{
+		"name":            name,
+		"description":     "smart collections test",
+		"color":           "blue",
+		"icon":            "📚",
+		"collection_type": collectionType,
+	}
+	body, _ := json.Marshal(payload)
+	req, _ := http.NewRequest("POST", setup.Server.URL+"/api/collections", bytes.NewBuffer(body))
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("Authorization", "Bearer "+token)
+	resp, err := http.DefaultClient.Do(req)
+	require.NoError(t, err)
+	defer func(Body io.ReadCloser) { _ = Body.Close() }(resp.Body)
+	require.Equal(t, http.StatusCreated, resp.StatusCode, "collection creation should succeed")
+
+	var result map[string]interface{}
+	require.NoError(t, json.NewDecoder(resp.Body).Decode(&result))
+	return result["id"].(string)
+}
+
+func smartGetCollection(t *testing.T, setup *TestServerSetup, token, collectionID string) map[string]interface{} {
+	t.Helper()
+	req, _ := http.NewRequest("GET", setup.Server.URL+"/api/collections/"+collectionID, nil)
+	req.Header.Set("Authorization", "Bearer "+token)
+	resp, err := http.DefaultClient.Do(req)
+	require.NoError(t, err)
+	defer func(Body io.ReadCloser) { _ = Body.Close() }(resp.Body)
+	require.Equal(t, http.StatusOK, resp.StatusCode)
+	var result map[string]interface{}
+	require.NoError(t, json.NewDecoder(resp.Body).Decode(&result))
+	return result
+}
+
+func smartPostRule(t *testing.T, setup *TestServerSetup, token, collectionID, field, operator, value string, enabled *bool) *http.Response {
+	t.Helper()
+	payload := map[string]interface{}{
+		"field":    field,
+		"operator": operator,
+		"value":    value,
+	}
+	if enabled != nil {
+		payload["enabled"] = *enabled
+	}
+	body, _ := json.Marshal(payload)
+	req, _ := http.NewRequest("POST", setup.Server.URL+"/api/collections/"+collectionID+"/rules", bytes.NewBuffer(body))
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("Authorization", "Bearer "+token)
+	resp, err := http.DefaultClient.Do(req)
+	require.NoError(t, err)
+	return resp
+}
+
+func smartDecodeRuleID(t *testing.T, resp *http.Response) string {
+	t.Helper()
+	defer func(Body io.ReadCloser) { _ = Body.Close() }(resp.Body)
+	var result map[string]interface{}
+	require.NoError(t, json.NewDecoder(resp.Body).Decode(&result))
+	rule := result["rule"].(map[string]interface{})
+	return rule["id"].(string)
+}
+
+// Data helpers -----------------------------------------------------------
+
+func smartCreateLibraryAndBooks(t *testing.T, setup *TestServerSetup, userID uuid.UUID, titlesByGenre map[string]string) (libraryID string, bookIDs []string) {
+	t.Helper()
+	ctx := context.Background()
+
+	libType, err := setup.DB.GetLibraryTypeByName(ctx, "ebooks")
+	require.NoError(t, err)
+	uniqueName := fmt.Sprintf("Test Smart Rules Library %d", time.Now().UnixNano())
+	library, err := setup.DB.CreateLibrary(ctx, database.CreateLibraryParams{
+		Name:             uniqueName,
+		Description:      pgtype.Text{String: "smart collections test library", Valid: true},
+		LibraryTypeID:    libType.ID,
+		CreatedByAdminID: pgtype.UUID{Bytes: [16]byte(userID), Valid: true},
+	})
+	require.NoError(t, err, "should create test library")
+	libUUID, err := uuid.FromBytes(library.ID.Bytes[0:16])
+	require.NoError(t, err)
+
+	t.Cleanup(func() {
+		_ = setup.DB.DeleteLibrary(ctx, library.ID)
+	})
+
+	for title, genre := range titlesByGenre {
+		media, err := setup.DB.CreateMediaItem(ctx, database.CreateMediaItemParams{
+			LibraryID: pgtype.UUID{Bytes: libUUID, Valid: true},
+			Title:     title,
+			Author:    pgtype.Text{String: "Smart Rule Author", Valid: true},
+			Genre:     pgtype.Text{String: genre, Valid: true},
+			FilePath:  fmt.Sprintf("/tmp/%s-%d.epub", title, time.Now().UnixNano()),
+			FileSize:  pgtype.Int8{Int64: 1024, Valid: true},
+			MimeType:  pgtype.Text{String: "application/epub+zip", Valid: true},
+		})
+		require.NoError(t, err, "should create test media item")
+		mediaUUID, err := uuid.FromBytes(media.ID.Bytes[0:16])
+		require.NoError(t, err)
+		bookIDs = append(bookIDs, mediaUUID.String())
+	}
+	return libUUID.String(), bookIDs
+}
+
+func smartLibraryTitleSet(t *testing.T, coll map[string]interface{}) map[string]bool {
+	t.Helper()
+	books, _ := coll["books"].([]interface{})
+	set := make(map[string]bool, len(books))
+	for _, b := range books {
+		if m, ok := b.(map[string]interface{}); ok {
+			if title, ok := m["title"].(string); ok {
+				set[title] = true
+			}
+		}
+	}
+	return set
+}
+
+// Tests ------------------------------------------------------------------
+
+func TestSmartCollections(t *testing.T) {
+	setup := setupTestServer(t)
+	adminID := getTestUserID(t, setup.DB)
+
+	t.Run("FirstRuleConvertsCollectionToSmart_LiveMembership", func(t *testing.T) {
+		_, bookIDs := smartCreateLibraryAndBooks(t, setup, adminID, map[string]string{
+			"Smart SF Book One": "Science Fiction",
+			"Smart SF Book Two": "Science Fiction",
+			"Smart FANT Book":   "Fantasy",
+		})
+
+		// Rule evaluation ignores stored links: a static collection's own
+		// added item must NOT show up once the collection is smart.
+		collID := smartCreateCollection(t, setup, setup.Token, "Test Smart Live "+uuid.NewString()[:8], "static")
+
+		// Add one hand-picked book (a Fantasy one that the smart rule
+		// will not match — so it must vanish from the render).
+		addBody, _ := json.Marshal(map[string]interface{}{"book_ids": []string{bookIDs[2]}})
+		addReq, _ := http.NewRequest("POST", setup.Server.URL+"/api/collections/"+collID+"/books", bytes.NewBuffer(addBody))
+		addReq.Header.Set("Content-Type", "application/json")
+		addReq.Header.Set("Authorization", "Bearer "+setup.Token)
+		addResp, err := http.DefaultClient.Do(addReq)
+		require.NoError(t, err)
+		require.Equal(t, http.StatusNoContent, addResp.StatusCode)
+		_ = addResp.Body.Close()
+
+		staticDetail := smartGetCollection(t, setup, setup.Token, collID)
+		assert.Equal(t, false, staticDetail["is_smart"])
+		assert.Equal(t, float64(1), staticDetail["book_count"], "static collection shows its stored link")
+
+		resp := smartPostRule(t, setup, setup.Token, collID, "genre", "equals", "Science Fiction", nil)
+		require.Equal(t, http.StatusCreated, resp.StatusCode)
+		_ = resp.Body.Close()
+
+		smartDetail := smartGetCollection(t, setup, setup.Token, collID)
+		assert.Equal(t, true, smartDetail["is_smart"], "rules presence derives the type")
+		assert.Equal(t, float64(2), smartDetail["book_count"], "live rule matches only")
+
+		memberTitles := smartLibraryTitleSet(t, smartDetail)
+		assert.True(t, memberTitles["Smart SF Book One"])
+		assert.True(t, memberTitles["Smart SF Book Two"])
+		assert.False(t, memberTitles["Smart FANT Book"], "hand-picked link is ignored under smart evaluation (v1 no hybrid)")
+	})
+
+	t.Run("DisabledRuleExcludedFromLiveSet", func(t *testing.T) {
+		smartCreateLibraryAndBooks(t, setup, adminID, map[string]string{
+			"Smart Diss Book": "Science Fiction",
+		})
+		collID := smartCreateCollection(t, setup, setup.Token, "Test Smart Disabled "+uuid.NewString()[:8], "smart")
+
+		resp := smartPostRule(t, setup, setup.Token, collID, "genre", "equals", "Science Fiction", nil)
+		require.Equal(t, http.StatusCreated, resp.StatusCode)
+		ruleID := smartDecodeRuleID(t, resp)
+
+		assert.Equal(t, float64(1), smartGetCollection(t, setup, setup.Token, collID)["book_count"])
+
+		// Disable: membership drops to zero at once.
+		falseFlag := false
+		dBody, _ := json.Marshal(map[string]interface{}{"enabled": falseFlag})
+		dReq, _ := http.NewRequest("PUT", setup.Server.URL+"/api/collections/"+collID+"/rules/"+ruleID, bytes.NewBuffer(dBody))
+		dReq.Header.Set("Content-Type", "application/json")
+		dReq.Header.Set("Authorization", "Bearer "+setup.Token)
+		dResp, err := http.DefaultClient.Do(dReq)
+		require.NoError(t, err)
+		require.Equal(t, http.StatusOK, dResp.StatusCode)
+		_ = dResp.Body.Close()
+
+		assert.Equal(t, float64(0), smartGetCollection(t, setup, setup.Token, collID)["book_count"], "disabled rules never match")
+	})
+
+	t.Run("SmartCollectionsRejectMembershipMutations", func(t *testing.T) {
+		smartCreateLibraryAndBooks(t, setup, adminID, map[string]string{
+			"Smart Guard Book": "Science Fiction",
+		})
+		collID := smartCreateCollection(t, setup, setup.Token, "Test Smart Guard "+uuid.NewString()[:8], "smart")
+
+		resp := smartPostRule(t, setup, setup.Token, collID, "genre", "equals", "Science Fiction", nil)
+		require.Equal(t, http.StatusCreated, resp.StatusCode)
+		_ = resp.Body.Close()
+
+		addBody, _ := json.Marshal(map[string]interface{}{"book_ids": []string{uuid.NewString()}})
+		addReq, _ := http.NewRequest("POST", setup.Server.URL+"/api/collections/"+collID+"/books", bytes.NewBuffer(addBody))
+		addReq.Header.Set("Content-Type", "application/json")
+		addReq.Header.Set("Authorization", "Bearer "+setup.Token)
+		addResp, err := http.DefaultClient.Do(addReq)
+		require.NoError(t, err)
+		require.Equal(t, http.StatusBadRequest, addResp.StatusCode)
+		_ = addResp.Body.Close()
+
+		removeReq, _ := http.NewRequest("DELETE", setup.Server.URL+"/api/collections/"+collID+"/books/"+uuid.NewString(), nil)
+		removeReq.Header.Set("Authorization", "Bearer "+setup.Token)
+		removeResp, err := http.DefaultClient.Do(removeReq)
+		require.NoError(t, err)
+		require.Equal(t, http.StatusBadRequest, removeResp.StatusCode)
+		_ = removeResp.Body.Close()
+	})
+
+	t.Run("RemoveLastRuleRevertsToStatic", func(t *testing.T) {
+		smartCreateLibraryAndBooks(t, setup, adminID, map[string]string{
+			"Smart Back Book": "Science Fiction",
+		})
+		collID := smartCreateCollection(t, setup, setup.Token, "Test Smart Revert "+uuid.NewString()[:8], "smart")
+
+		resp := smartPostRule(t, setup, setup.Token, collID, "tags", "contains", "no-such-tag", nil)
+		require.Equal(t, http.StatusCreated, resp.StatusCode)
+		ruleID := smartDecodeRuleID(t, resp)
+
+		smartDetail := smartGetCollection(t, setup, setup.Token, collID)
+		assert.Equal(t, true, smartDetail["is_smart"])
+
+		delReq, _ := http.NewRequest("DELETE", setup.Server.URL+"/api/collections/"+collID+"/rules/"+ruleID, nil)
+		delReq.Header.Set("Authorization", "Bearer "+setup.Token)
+		delResp, err := http.DefaultClient.Do(delReq)
+		require.NoError(t, err)
+		require.Equal(t, http.StatusOK, delResp.StatusCode)
+		_ = delResp.Body.Close()
+
+		staticDetail := smartGetCollection(t, setup, setup.Token, collID)
+		assert.Equal(t, false, staticDetail["is_smart"], "removing the last rule reverts to static")
+
+		// Membership mutations work again on the reverted static.
+		addBody, _ := json.Marshal(map[string]interface{}{"book_ids": []string{uuid.NewString()}})
+		addReq, _ := http.NewRequest("POST", setup.Server.URL+"/api/collections/"+collID+"/books", bytes.NewBuffer(addBody))
+		addReq.Header.Set("Content-Type", "application/json")
+		addReq.Header.Set("Authorization", "Bearer "+setup.Token)
+		addResp, err := http.DefaultClient.Do(addReq)
+		require.NoError(t, err)
+		assert.Equal(t, http.StatusNoContent, addResp.StatusCode)
+		_ = addResp.Body.Close()
+	})
+
+	t.Run("RuleValidationAndSystemCollections", func(t *testing.T) {
+		collID := smartCreateCollection(t, setup, setup.Token, "Test Smart Valid "+uuid.NewString()[:8], "static")
+
+		resp := smartPostRule(t, setup, setup.Token, collID, "not_a_field", "equals", "x", nil)
+		require.Equal(t, http.StatusBadRequest, resp.StatusCode)
+		_ = resp.Body.Close()
+
+		resp = smartPostRule(t, setup, setup.Token, collID, "genre", "equals", "Science Fiction", nil)
+		require.Equal(t, http.StatusCreated, resp.StatusCode)
+		_ = resp.Body.Close()
+
+		// System collections may never carry rules.
+		colls, err := setup.DB.GetCollectionsByUser(context.Background(), pgtype.UUID{Bytes: [16]byte(adminID), Valid: true})
+		require.NoError(t, err)
+		var systemID string
+		for _, c := range colls {
+			if c.IsSystemCollection.Bool {
+				systemID = uuid.UUID(c.ID.Bytes).String()
+				break
+			}
+		}
+		require.NotEmpty(t, systemID, "admin user should have system collections")
+
+		sysResp := smartPostRule(t, setup, setup.Token, systemID, "genre", "equals", "x", nil)
+		require.Equal(t, http.StatusBadRequest, sysResp.StatusCode)
+		_ = sysResp.Body.Close()
+	})
+
+	t.Run("CollectionsListRespectsIncludeAutoWithLiveCounts", func(t *testing.T) {
+		_, _ = smartCreateLibraryAndBooks(t, setup, adminID, map[string]string{
+			"Smart List Book": "Science Fiction",
+		})
+		collID := smartCreateCollection(t, setup, setup.Token, "Test Smart List "+uuid.NewString()[:8], "smart")
+
+		resp := smartPostRule(t, setup, setup.Token, collID, "genre", "equals", "Science Fiction", nil)
+		require.Equal(t, http.StatusCreated, resp.StatusCode)
+		_ = resp.Body.Close()
+
+		// Default list (the Android app's read): smart collections hidden.
+		req, _ := http.NewRequest("GET", setup.Server.URL+"/api/collections", nil)
+		req.Header.Set("Authorization", "Bearer "+setup.Token)
+		defaultResp, err := http.DefaultClient.Do(req)
+		require.NoError(t, err)
+		defer func(Body io.ReadCloser) { _ = Body.Close() }(defaultResp.Body)
+		var defaultData struct {
+			Collections []struct {
+				ID string `json:"id"`
+			} `json:"collections"`
+		}
+		require.NoError(t, json.NewDecoder(defaultResp.Body).Decode(&defaultData))
+		for _, c := range defaultData.Collections {
+			assert.NotEqual(t, collID, c.ID, "default listing excludes rule-driven collections (app compat)")
+		}
+
+		// Opt-in listing includes them with LIVE counts.
+		scopeReq, _ := http.NewRequest("GET", setup.Server.URL+"/api/collections?include_auto=true", nil)
+		scopeReq.Header.Set("Authorization", "Bearer "+setup.Token)
+		scopeResp, err := http.DefaultClient.Do(scopeReq)
+		require.NoError(t, err)
+		defer func(Body io.ReadCloser) { _ = Body.Close() }(scopeResp.Body)
+		var scopeData struct {
+			Collections []struct {
+				ID        string `json:"id"`
+				BookCount int    `json:"book_count"`
+				IsSmart   bool   `json:"is_smart"`
+			} `json:"collections"`
+		}
+		require.NoError(t, json.NewDecoder(scopeResp.Body).Decode(&scopeData))
+		found := false
+		for _, c := range scopeData.Collections {
+			if c.ID == collID {
+				found = true
+				assert.True(t, c.IsSmart)
+				assert.Equal(t, 1, c.BookCount, "smart card counts rule matches live")
+			}
+		}
+		assert.True(t, found, "include_auto=true must surface smart collections")
+	})
+}

cmd/server/tests/comic_metadata_display_test.go

@@ -140,7 +140,6 @@ func TestComicMetadataDisplay_ComicDetailPage(t *testing.T) {
 		body := readBody(resp)
 
 		// Verify reading direction badge is displayed
-		assert.Contains(t, body, "📖", "Should display reading direction icon")
 		assert.Contains(t, body, "RTL", "Should display RTL reading direction")
 	})
 
@@ -263,7 +262,8 @@ func TestComicMetadataDisplay_ComicDetailPage(t *testing.T) {
 		assert.Equal(t, http.StatusOK, resp.StatusCode)
 		body := readBody(resp)
 
-		assert.Contains(t, body, "📚", "Should display story arc icon")
+		// The redesigned badge renders the arc NAME in a text badge
+		// (no 📚 icon) — assert the name.
 		assert.Contains(t, body, "The Dark Phoenix Saga", "Should display story arc name")
 	})
 
@@ -508,7 +508,8 @@ func TestComicMetadataDisplay_ComicDetailPage(t *testing.T) {
 		assert.Equal(t, http.StatusOK, resp.StatusCode)
 		body := readBody(resp)
 
-		// Verify all manga-specific fields are displayed
+		// The redesigned badge (07578e0) renders the direction text chip
+		// without the 📖 emoji — assert the chip text.
 		assert.Contains(t, body, "RTL", "Should display RTL reading direction")
 		assert.Contains(t, body, "Teen", "Should display age rating")
 		assert.Contains(t, body, "8.5 / 10", "Should display community rating")
@@ -619,9 +620,11 @@ func TestComicMetadataDisplay_ComicDetailPage(t *testing.T) {
 		assert.Contains(t, body, "Everyone", "Should display age rating")
 		assert.Contains(t, body, "goodreads.com", "Should display web URL")
 
-		// Verify comic-specific fields are NOT displayed
-		assert.NotContains(t, body, "Manga Type", "Should not display manga type for ebook")
-		assert.NotContains(t, body, "Scan Info", "Should not display scan info for ebook")
+		// Verify comic-specific fields are NOT displayed. The page body
+		// always contains the admin edit modal's "Manga Type"/"Scan Info"
+		// LABELS — assert the metadata VALUES (what the display block
+		// renders) are absent instead.
+		assert.NotContains(t, body, "yes and right to left", "Should not display manga type value for ebook")
 		assert.NotContains(t, body, "B&W", "Should not display B&W badge for ebook")
 	})
 
@@ -682,9 +685,11 @@ func TestComicMetadataDisplay_ComicDetailPage(t *testing.T) {
 
 		// Page should still render successfully
 		assert.Contains(t, body, "Minimal Comic", "Should display title")
-		// Use "Community Rating:" with colon to avoid matching the HTML comment
+		// The admin edit modal always carries "Manga Type" as a form
+		// LABEL — the display block would render the capitalized VALUE,
+		// which is absent here.
 		assert.NotContains(t, body, "Community Rating:", "Should not show community rating when not set")
-		assert.NotContains(t, body, "Manga Type", "Should not show manga type when unknown")
+		assert.NotContains(t, body, "yes and right to left", "Should not show a manga type value when unknown")
 	})
 }
 

cmd/server/tests/cross_library_move_test.go

@@ -0,0 +1,639 @@
+package main
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"net/http"
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"bookhoard/internal/database"
+	"bookhoard/internal/services"
+
+	"github.com/google/uuid"
+	"github.com/jackc/pgx/v5/pgtype"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// Cross-library SHA move detection + archived-twin merge integration tests.
+// These cover the scenario where identical book content moves between
+// libraries of the same type: the row must be repointed (history follows)
+// instead of duplicated, deliberate copies stay independent, type rules are
+// enforced, and archived twins can be merged into their active copy.
+
+const (
+	moveTestAdminEmail = "testuser@tests.bookhoard.internal"
+	moveTestFileName   = "Test Book.epub"
+)
+
+// createEbooksTestLibrary creates a library of the given type via the API and
+// swaps its default folder for a fresh temp directory the test controls.
+func createTypedTestLibrary(t *testing.T, setup *TestServerSetup, name, libType string) (pgtype.UUID, string) {
+	t.Helper()
+	ctx := context.Background()
+
+	libBody, _ := json.Marshal(map[string]interface{}{"name": name, "type": libType})
+	req, _ := http.NewRequest("POST", setup.Server.URL+"/api/libraries", bytes.NewBuffer(libBody))
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("Authorization", "Bearer "+setup.Token)
+	resp, err := http.DefaultClient.Do(req)
+	require.NoError(t, err)
+	defer func() { _ = resp.Body.Close() }()
+	require.Equal(t, http.StatusCreated, resp.StatusCode, "library creation should succeed")
+
+	var libResp map[string]interface{}
+	require.NoError(t, json.NewDecoder(resp.Body).Decode(&libResp))
+	libID, err := uuid.Parse(libResp["id"].(string))
+	require.NoError(t, err)
+	pgLib := pgtype.UUID{Bytes: libID, Valid: true}
+
+	folders, err := setup.DB.GetLibraryFolders(ctx, pgLib)
+	require.NoError(t, err)
+	for _, f := range folders {
+		_, err = setup.DB.DeleteLibraryFolder(ctx, database.DeleteLibraryFolderParams{
+			LibraryID:  pgLib,
+			FolderPath: f.FolderPath,
+		})
+		require.NoError(t, err)
+	}
+
+	tmpDir := t.TempDir()
+	_, err = setup.DB.AddLibraryFolder(ctx, database.AddLibraryFolderParams{
+		LibraryID:  pgLib,
+		FolderPath: tmpDir,
+	})
+	require.NoError(t, err)
+	return pgLib, tmpDir
+}
+
+// deleteLibraries removes libraries (cascading to media items, progress,
+// annotations, and processing issues) so reruns never see leftovers from a
+// previous run — stale rows with identical content hashes would otherwise be
+// picked up as move candidates. Call via defer AFTER the setup.Close defer so
+// it executes while the pool is still open (defers run LIFO).
+func deleteLibraries(t *testing.T, setup *TestServerSetup, libs ...pgtype.UUID) {
+	t.Helper()
+	for _, lib := range libs {
+		_ = setup.DB.DeleteLibrary(context.Background(), lib)
+	}
+}
+
+// scanTestFolder runs a synchronous scan over one folder.
+func scanTestFolder(t *testing.T, setup *TestServerSetup, adminID pgtype.UUID, folder string) {
+	t.Helper()
+	scanner := services.NewMediaScanner(setup.DB)
+	defer func() { _ = scanner.Close() }()
+	scanner.SetAdminID(adminID)
+	require.NoError(t, scanner.SetFolders([]string{folder}, false))
+	require.NoError(t, scanner.ScanFolders(context.Background()))
+}
+
+// waitForCond polls cond until true or the timeout elapses.
+func waitForCond(t *testing.T, timeout time.Duration, msg string, cond func() bool) {
+	t.Helper()
+	deadline := time.Now().Add(timeout)
+	for time.Now().Before(deadline) {
+		if cond() {
+			return
+		}
+		time.Sleep(100 * time.Millisecond)
+	}
+	t.Fatalf("condition not met within %v: %s", timeout, msg)
+}
+
+func moveTestAdminID(t *testing.T, setup *TestServerSetup) (pgtype.UUID, pgtype.UUID) {
+	t.Helper()
+	admin, err := setup.DB.GetUserByEmail(context.Background(), moveTestAdminEmail)
+	require.NoError(t, err)
+	pgAdmin := pgtype.UUID{Bytes: admin.ID.Bytes, Valid: true}
+	return pgAdmin, pgAdmin
+}
+
+// writeTestEbook places an identical dummy epub under folder/Author/.
+func writeTestEbook(t *testing.T, folder string, content []byte) string {
+	t.Helper()
+	authorDir := filepath.Join(folder, "Author")
+	require.NoError(t, os.MkdirAll(authorDir, 0755))
+	bookPath := filepath.Join(authorDir, moveTestFileName)
+	require.NoError(t, os.WriteFile(bookPath, content, 0644))
+	return bookPath
+}
+
+// TestCrossLibraryMovePreservesHistory is the core scenario: a book moves
+// from library A to library B (same type). The existing row must be repointed
+// to library B keeping its ID so progress and annotations survive, instead of
+// creating a duplicate while the old row goes missing.
+func TestCrossLibraryMovePreservesHistory(t *testing.T) {
+	setup := setupTestServer(t)
+	defer func() { _ = setup.Close() }()
+
+	ctx := context.Background()
+	adminID, adminPgID := moveTestAdminID(t, setup)
+	libA, folderA := createTypedTestLibrary(t, setup, "Move Src Library", "ebooks")
+	libB, folderB := createTypedTestLibrary(t, setup, "Move Dst Library", "ebooks")
+	defer deleteLibraries(t, setup, libA, libB)
+
+	content := []byte("cross library move test epub content")
+	writeTestEbook(t, folderA, content)
+
+	scanTestFolder(t, setup, adminID, folderA)
+
+	var original database.ListMediaItemsByLibraryRow
+	waitForCond(t, 5*time.Second, "book should be imported into library A", func() bool {
+		books, err := setup.DB.ListMediaItemsByLibrary(ctx, libA)
+		if err != nil || len(books) != 1 {
+			return false
+		}
+		original = books[0]
+		return true
+	})
+
+	// Give the book real user data at its original location.
+	_, err := setup.DB.UpdateReadingProgress(ctx, database.UpdateReadingProgressParams{
+		MediaItemID: original.ID,
+		UserID:      adminPgID,
+		CurrentPage: pgtype.Int4{Int32: 12, Valid: true},
+		TotalPages:  pgtype.Int4{Int32: 300, Valid: true},
+	})
+	require.NoError(t, err)
+	_, err = setup.DB.CreateMediaHighlight(ctx, database.CreateMediaHighlightParams{
+		MediaItemID:   original.ID,
+		UserID:        adminPgID,
+		SelectionText: "a line worth keeping",
+		Color:         pgtype.Text{String: "#ffff00", Valid: true},
+	})
+	require.NoError(t, err)
+
+	// Move the file: same bytes, new library folder, old copy deleted.
+	writeTestEbook(t, folderB, content)
+	require.NoError(t, os.Remove(filepath.Join(folderA, "Author", moveTestFileName)))
+
+	scanTestFolder(t, setup, adminID, folderB)
+
+	var moved database.ListMediaItemsByLibraryRow
+	waitForCond(t, 5*time.Second, "book should be repointed into library B", func() bool {
+		books, err := setup.DB.ListMediaItemsByLibrary(ctx, libB)
+		if err != nil || len(books) != 1 {
+			return false
+		}
+		moved = books[0]
+		return true
+	})
+
+	assert.Equal(t, original.ID, moved.ID, "row ID must be preserved so history follows the book")
+	assert.Equal(t, libB, moved.LibraryID, "row must now belong to library B")
+	assert.Equal(t, filepath.ToSlash(filepath.Join("Author", moveTestFileName)), moved.FilePath, "path must be repointed relative to library B")
+	assert.False(t, moved.ArchivedAt.Valid, "moved row must not be archived")
+	assert.Equal(t, int32(0), moved.MissingScanCount, "moved row must not be marked missing")
+	assert.True(t, moved.LibraryTypeName.Valid && moved.LibraryTypeName.String == "ebooks", "library_type_name must stay truthful after library change")
+
+	// History followed the row.
+	progress, err := setup.DB.GetReadingProgress(ctx, database.GetReadingProgressParams{MediaItemID: original.ID, UserID: adminPgID})
+	require.NoError(t, err)
+	assert.Equal(t, int32(12), progress.CurrentPage.Int32, "reading progress must survive the move")
+
+	highlights, err := setup.DB.GetMediaHighlights(ctx, database.GetMediaHighlightsParams{MediaItemID: original.ID, UserID: adminPgID})
+	require.NoError(t, err)
+	assert.Len(t, highlights, 1, "annotation must survive the move")
+
+	// Library A no longer holds the row: no duplicate, no archived ghost.
+	booksA, err := setup.DB.ListMediaItemsByLibrary(ctx, libA)
+	require.NoError(t, err)
+	assert.Empty(t, booksA, "library A must not keep a duplicate row after the move")
+}
+
+// TestCrossLibraryCopyStaysIndependent verifies that placing identical
+// content in two libraries on purpose creates two independent rows: the
+// second import is NOT blocked, and neither row is repointed or archived.
+func TestCrossLibraryCopyStaysIndependent(t *testing.T) {
+	setup := setupTestServer(t)
+	defer func() { _ = setup.Close() }()
+
+	ctx := context.Background()
+	adminID, adminPgID := moveTestAdminID(t, setup)
+	libA, folderA := createTypedTestLibrary(t, setup, "Copy Lib A", "ebooks")
+	libB, folderB := createTypedTestLibrary(t, setup, "Copy Lib B", "ebooks")
+	defer deleteLibraries(t, setup, libA, libB)
+
+	content := []byte("deliberate duplicate content")
+	writeTestEbook(t, folderA, content)
+	writeTestEbook(t, folderB, content)
+
+	scanTestFolder(t, setup, adminID, folderA)
+	scanTestFolder(t, setup, adminID, folderB)
+
+	var itemA, itemB database.ListMediaItemsByLibraryRow
+	waitForCond(t, 5*time.Second, "both libraries should hold their own copy", func() bool {
+		booksA, errA := setup.DB.ListMediaItemsByLibrary(ctx, libA)
+		booksB, errB := setup.DB.ListMediaItemsByLibrary(ctx, libB)
+		if errA != nil || errB != nil || len(booksA) != 1 || len(booksB) != 1 {
+			return false
+		}
+		itemA, itemB = booksA[0], booksB[0]
+		return true
+	})
+
+	assert.NotEqual(t, itemA.ID, itemB.ID, "deliberate copies must stay independent rows")
+	assert.False(t, itemA.ArchivedAt.Valid && itemB.ArchivedAt.Valid, "no copy should be archived")
+
+	// History on one copy does not leak into the other.
+	_, err := setup.DB.UpdateReadingProgress(ctx, database.UpdateReadingProgressParams{
+		MediaItemID: itemA.ID,
+		UserID:      adminPgID,
+		CurrentPage: pgtype.Int4{Int32: 7, Valid: true},
+		TotalPages:  pgtype.Int4{Int32: 100, Valid: true},
+	})
+	require.NoError(t, err)
+
+	_, err = setup.DB.GetReadingProgress(ctx, database.GetReadingProgressParams{MediaItemID: itemB.ID, UserID: adminPgID})
+	assert.Error(t, err, "copy B must not inherit copy A's progress")
+}
+
+// TestCrossLibraryMoveRejectedForTypeMismatch verifies the type guard: the
+// cross-library lookup only matches same-type libraries, so a reflowable EPUB
+// registered in a manga library whose file moves to ANOTHER manga library is
+// detected as a move but must be rejected by the type rules (manga libraries
+// only accept fixed-layout/image content). The move is rejected, a processing
+// issue is recorded, and the file stays untracked rather than being
+// force-imported.
+func TestCrossLibraryMoveRejectedForTypeMismatch(t *testing.T) {
+	setup := setupTestServer(t)
+	defer func() { _ = setup.Close() }()
+
+	ctx := context.Background()
+	adminID, _ := moveTestAdminID(t, setup)
+	libA, folderA := createTypedTestLibrary(t, setup, "Type Src Manga", "manga")
+	libM, folderM := createTypedTestLibrary(t, setup, "Type Dst Manga", "manga")
+	defer deleteLibraries(t, setup, libA, libM)
+
+	content := []byte("reflowable epub that manga libraries must not adopt via move")
+	writeTestEbook(t, folderA, content)
+	scanTestFolder(t, setup, adminID, folderA)
+
+	var original database.ListMediaItemsByLibraryRow
+	waitForCond(t, 5*time.Second, "book should be imported into the first manga library", func() bool {
+		books, err := setup.DB.ListMediaItemsByLibrary(ctx, libA)
+		if err != nil || len(books) != 1 {
+			return false
+		}
+		original = books[0]
+		return true
+	})
+	require.Equal(t, "reflowable", original.FormatGroup, "dummy epub must scan as reflowable for this test")
+
+	// Move into the second manga library: same hash, same type, but the
+	// reflowable format violates manga library rules.
+	writeTestEbook(t, folderM, content)
+	require.NoError(t, os.Remove(filepath.Join(folderA, "Author", moveTestFileName)))
+
+	scanTestFolder(t, setup, adminID, folderM)
+
+	// The second manga library must not adopt the item.
+	booksM, err := setup.DB.ListMediaItemsByLibrary(ctx, libM)
+	require.NoError(t, err)
+	assert.Empty(t, booksM, "reflowable epub must not be repointed between manga libraries")
+
+	// The original row is untouched in the first manga library.
+	after, err := setup.DB.GetMediaItem(ctx, original.ID)
+	require.NoError(t, err)
+	assert.Equal(t, libA, after.LibraryID, "original row must stay in its library")
+
+	// A processing issue explains the rejection.
+	waitForCond(t, 5*time.Second, "processing issue should be recorded", func() bool {
+		issues, err := setup.DB.ListProcessingIssuesByLibrary(ctx, libM)
+		if err != nil {
+			return false
+		}
+		for _, issue := range issues {
+			if issue.IssueType == "library_type_mismatch" {
+				return true
+			}
+		}
+		return false
+	})
+}
+
+// TestListHiddenMediaItemsMatchesActiveTwin verifies the archived-page query:
+// an archived row with an active same-hash twin reports it in match_* columns;
+// an archived row without a twin reports no match.
+func TestListHiddenMediaItemsMatchesActiveTwin(t *testing.T) {
+	setup := setupTestServer(t)
+	defer func() { _ = setup.Close() }()
+
+	ctx := context.Background()
+	adminID, _ := moveTestAdminID(t, setup)
+	libA, folderA := createTypedTestLibrary(t, setup, "Twin Lib A", "ebooks")
+	libB, folderB := createTypedTestLibrary(t, setup, "Twin Lib B", "ebooks")
+	libC, folderC := createTypedTestLibrary(t, setup, "Twin Lib C", "ebooks")
+	defer deleteLibraries(t, setup, libA, libB, libC)
+
+	twinContent := []byte("twin content shared by two libraries")
+	writeTestEbook(t, folderA, twinContent)
+	writeTestEbook(t, folderB, twinContent)
+	lonelyContent := []byte("unique content with no twin anywhere")
+	writeTestEbook(t, folderC, lonelyContent)
+
+	scanTestFolder(t, setup, adminID, folderA)
+	scanTestFolder(t, setup, adminID, folderB)
+	scanTestFolder(t, setup, adminID, folderC)
+
+	booksA, err := setup.DB.ListMediaItemsByLibrary(ctx, libA)
+	require.NoError(t, err)
+	require.Len(t, booksA, 1)
+	twin := booksA[0]
+
+	booksC, err := setup.DB.ListMediaItemsByLibrary(ctx, libC)
+	require.NoError(t, err)
+	require.Len(t, booksC, 1)
+	lonely := booksC[0]
+
+	// Archive both: the A row now has an active twin in B, the C row has none.
+	require.NoError(t, setup.DB.ArchiveMediaItem(ctx, twin.ID))
+	require.NoError(t, setup.DB.ArchiveMediaItem(ctx, lonely.ID))
+
+	rows, err := setup.DB.ListHiddenMediaItems(ctx)
+	require.NoError(t, err)
+
+	foundTwin, foundLonely := false, false
+	for _, row := range rows {
+		if row.ID == twin.ID {
+			foundTwin = true
+			assert.True(t, row.MatchID.Valid, "twin row must report its active match")
+			if row.MatchID.Valid {
+				assert.Equal(t, findTwinTargetID(t, setup, libB), uuid.UUID(row.MatchID.Bytes).String())
+			}
+			assert.Equal(t, "Test Book", row.MatchTitle)
+		}
+		if row.ID == lonely.ID {
+			foundLonely = true
+			assert.False(t, row.MatchID.Valid, "row without a twin must report no match")
+		}
+	}
+	require.True(t, foundTwin, "twin row should be listed")
+	require.True(t, foundLonely, "lonely row should be listed")
+}
+
+// findTwinTargetID returns the single active item in the given library.
+func findTwinTargetID(t *testing.T, setup *TestServerSetup, libID pgtype.UUID) string {
+	t.Helper()
+	books, err := setup.DB.ListMediaItemsByLibrary(context.Background(), libID)
+	require.NoError(t, err)
+	require.Len(t, books, 1)
+	return uuid.UUID(books[0].ID.Bytes).String()
+}
+
+// mergeRequest issues POST /api/media-items/{source}/merge.
+func mergeRequest(t *testing.T, setup *TestServerSetup, token, sourceID string, body map[string]interface{}) *http.Response {
+	t.Helper()
+	payload, _ := json.Marshal(body)
+	req, _ := http.NewRequest("POST", setup.Server.URL+"/api/media-items/"+sourceID+"/merge", bytes.NewBuffer(payload))
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("Authorization", "Bearer "+token)
+	resp, err := http.DefaultClient.Do(req)
+	require.NoError(t, err)
+	return resp
+}
+
+// archiveAndIsolate imports one book into the library and archives it,
+// simulating a file that was copied elsewhere then deleted from here.
+func archiveAndIsolate(t *testing.T, setup *TestServerSetup, adminID, adminPgID pgtype.UUID, libID pgtype.UUID, folder, content string) database.ListMediaItemsByLibraryRow {
+	t.Helper()
+	ctx := context.Background()
+	writeTestEbook(t, folder, []byte(content))
+	scanTestFolder(t, setup, adminID, folder)
+
+	books, err := setup.DB.ListMediaItemsByLibrary(ctx, libID)
+	require.NoError(t, err)
+	require.Len(t, books, 1)
+	item := books[0]
+
+	// Reading history that must survive the merge.
+	_, err = setup.DB.UpdateReadingProgress(ctx, database.UpdateReadingProgressParams{
+		MediaItemID: item.ID,
+		UserID:      adminPgID,
+		CurrentPage: pgtype.Int4{Int32: 42, Valid: true},
+		TotalPages:  pgtype.Int4{Int32: 200, Valid: true},
+	})
+	require.NoError(t, err)
+	_, err = setup.DB.CreateMediaHighlight(ctx, database.CreateMediaHighlightParams{
+		MediaItemID:   item.ID,
+		UserID:        adminPgID,
+		SelectionText: "annotation on the old copy",
+		Color:         pgtype.Text{String: "#00ff00", Valid: true},
+	})
+	require.NoError(t, err)
+
+	require.NoError(t, setup.DB.ArchiveMediaItem(ctx, item.ID))
+	return item
+}
+
+// TestMergeArchivedItemIntoActiveTwin covers the copy-then-delete-later
+// workflow: the active copy exists in another library, the archived twin
+// holds the real reading history. Merging moves progress + annotations onto
+// the active row and removes the archived row.
+func TestMergeArchivedItemIntoActiveTwin(t *testing.T) {
+	setup := setupTestServer(t)
+	defer func() { _ = setup.Close() }()
+
+	ctx := context.Background()
+	adminID, adminPgID := moveTestAdminID(t, setup)
+	libOld, folderOld := createTypedTestLibrary(t, setup, "Merge Old Lib", "ebooks")
+	libNew, folderNew := createTypedTestLibrary(t, setup, "Merge New Lib", "ebooks")
+	defer deleteLibraries(t, setup, libOld, libNew)
+
+	content := "merge workflow epub content"
+
+	// Old library: book + history, then archived (file "deleted").
+	oldItem := archiveAndIsolate(t, setup, adminID, adminPgID, libOld, folderOld, content)
+
+	// New library: the surviving active copy, no history of its own.
+	writeTestEbook(t, folderNew, []byte(content))
+	scanTestFolder(t, setup, adminID, folderNew)
+	booksNew, err := setup.DB.ListMediaItemsByLibrary(ctx, libNew)
+	require.NoError(t, err)
+	require.Len(t, booksNew, 1)
+	active := booksNew[0]
+
+	oldID := uuid.UUID(oldItem.ID.Bytes).String()
+	activeID := uuid.UUID(active.ID.Bytes).String()
+	resp := mergeRequest(t, setup, setup.Token, oldID, map[string]interface{}{"target_id": activeID})
+	defer func() { _ = resp.Body.Close() }()
+	require.Equal(t, http.StatusOK, resp.StatusCode, "merge should succeed")
+
+	var mergeResp map[string]interface{}
+	require.NoError(t, json.NewDecoder(resp.Body).Decode(&mergeResp))
+
+	// Archived row is gone.
+	_, err = setup.DB.GetMediaItem(ctx, oldItem.ID)
+	assert.Error(t, err, "archived row must be removed after merge")
+
+	// History landed on the active row.
+	progress, err := setup.DB.GetReadingProgress(ctx, database.GetReadingProgressParams{MediaItemID: active.ID, UserID: adminPgID})
+	require.NoError(t, err)
+	assert.Equal(t, int32(42), progress.CurrentPage.Int32, "progress must merge into the active copy")
+
+	highlights, err := setup.DB.GetMediaHighlights(ctx, database.GetMediaHighlightsParams{MediaItemID: active.ID, UserID: adminPgID})
+	require.NoError(t, err)
+	assert.Len(t, highlights, 1, "annotations must merge into the active copy")
+
+	booksOld, err := setup.DB.ListMediaItemsByLibrary(ctx, libOld)
+	require.NoError(t, err)
+	assert.Empty(t, booksOld, "old library must be empty after merge")
+}
+
+func TestMergeArchivedItemRejections(t *testing.T) {
+	setup := setupTestServer(t)
+	defer func() { _ = setup.Close() }()
+
+	ctx := context.Background()
+	adminID, adminPgID := moveTestAdminID(t, setup)
+	libA, folderA := createTypedTestLibrary(t, setup, "Reject Lib A", "ebooks")
+	libB, folderB := createTypedTestLibrary(t, setup, "Reject Lib B", "ebooks")
+	defer deleteLibraries(t, setup, libA, libB)
+
+	t.Run("requires admin", func(t *testing.T) {
+		writeTestEbook(t, folderA, []byte("admin check content"))
+		scanTestFolder(t, setup, adminID, folderA)
+		booksA, err := setup.DB.ListMediaItemsByLibrary(ctx, libA)
+		require.NoError(t, err)
+		require.Len(t, booksA, 1)
+		itemID := uuid.UUID(booksA[0].ID.Bytes).String()
+
+		resp := mergeRequest(t, setup, setup.RegularToken, itemID, map[string]interface{}{"target_id": itemID})
+		defer func() { _ = resp.Body.Close() }()
+		assert.Equal(t, http.StatusForbidden, resp.StatusCode)
+	})
+
+	t.Run("rejects active source", func(t *testing.T) {
+		writeTestEbook(t, folderA, []byte("active source content"))
+		scanTestFolder(t, setup, adminID, folderA)
+		booksA, err := setup.DB.ListMediaItemsByLibrary(ctx, libA)
+		require.NoError(t, err)
+		require.Len(t, booksA, 1)
+		sourceID := uuid.UUID(booksA[0].ID.Bytes).String()
+
+		writeTestEbook(t, folderB, []byte("active source content"))
+		scanTestFolder(t, setup, adminID, folderB)
+		targetID := findTwinTargetID(t, setup, libB)
+
+		resp := mergeRequest(t, setup, setup.Token, sourceID, map[string]interface{}{"target_id": targetID})
+		defer func() { _ = resp.Body.Close() }()
+		assert.Equal(t, http.StatusBadRequest, resp.StatusCode, "source is not archived/missing")
+	})
+
+	t.Run("rejects hash mismatch", func(t *testing.T) {
+		writeTestEbook(t, folderA, []byte("hash mismatch content A"))
+		scanTestFolder(t, setup, adminID, folderA)
+		booksA, err := setup.DB.ListMediaItemsByLibrary(ctx, libA)
+		require.NoError(t, err)
+		require.Len(t, booksA, 1)
+		source := booksA[0]
+		require.NoError(t, setup.DB.ArchiveMediaItem(ctx, source.ID))
+		sourceID := uuid.UUID(source.ID.Bytes).String()
+
+		writeTestEbook(t, folderB, []byte("hash mismatch content B - different bytes"))
+		scanTestFolder(t, setup, adminID, folderB)
+		targetID := findTwinTargetID(t, setup, libB)
+
+		resp := mergeRequest(t, setup, setup.Token, sourceID, map[string]interface{}{"target_id": targetID})
+		defer func() { _ = resp.Body.Close() }()
+		assert.Equal(t, http.StatusBadRequest, resp.StatusCode, "different content must not merge")
+
+		// Both rows still exist.
+		_, err = setup.DB.GetMediaItem(ctx, source.ID)
+		assert.NoError(t, err, "source must survive a rejected merge")
+	})
+
+	t.Run("requires target_id", func(t *testing.T) {
+		writeTestEbook(t, folderA, []byte("missing target content"))
+		scanTestFolder(t, setup, adminID, folderA)
+		booksA, err := setup.DB.ListMediaItemsByLibrary(ctx, libA)
+		require.NoError(t, err)
+		require.Len(t, booksA, 1)
+		require.NoError(t, setup.DB.ArchiveMediaItem(ctx, booksA[0].ID))
+		sourceID := uuid.UUID(booksA[0].ID.Bytes).String()
+
+		resp := mergeRequest(t, setup, setup.Token, sourceID, map[string]interface{}{})
+		defer func() { _ = resp.Body.Close() }()
+		assert.Equal(t, http.StatusBadRequest, resp.StatusCode)
+	})
+
+	t.Run("rejects self merge", func(t *testing.T) {
+		writeTestEbook(t, folderA, []byte("self merge content"))
+		scanTestFolder(t, setup, adminID, folderA)
+		booksA, err := setup.DB.ListMediaItemsByLibrary(ctx, libA)
+		require.NoError(t, err)
+		require.Len(t, booksA, 1)
+		require.NoError(t, setup.DB.ArchiveMediaItem(ctx, booksA[0].ID))
+		sourceID := uuid.UUID(booksA[0].ID.Bytes).String()
+
+		resp := mergeRequest(t, setup, setup.Token, sourceID, map[string]interface{}{"target_id": sourceID})
+		defer func() { _ = resp.Body.Close() }()
+		assert.Equal(t, http.StatusBadRequest, resp.StatusCode)
+	})
+
+	t.Run("rejects archived target", func(t *testing.T) {
+		content := []byte("archived target content")
+		writeTestEbook(t, folderA, content)
+		scanTestFolder(t, setup, adminID, folderA)
+		booksA, err := setup.DB.ListMediaItemsByLibrary(ctx, libA)
+		require.NoError(t, err)
+		require.Len(t, booksA, 1)
+		require.NoError(t, setup.DB.ArchiveMediaItem(ctx, booksA[0].ID))
+		sourceID := uuid.UUID(booksA[0].ID.Bytes).String()
+
+		writeTestEbook(t, folderB, content)
+		scanTestFolder(t, setup, adminID, folderB)
+		booksB, err := setup.DB.ListMediaItemsByLibrary(ctx, libB)
+		require.NoError(t, err)
+		require.Len(t, booksB, 1)
+		require.NoError(t, setup.DB.ArchiveMediaItem(ctx, booksB[0].ID))
+		targetID := uuid.UUID(booksB[0].ID.Bytes).String()
+
+		resp := mergeRequest(t, setup, setup.Token, sourceID, map[string]interface{}{"target_id": targetID})
+		defer func() { _ = resp.Body.Close() }()
+		assert.Equal(t, http.StatusBadRequest, resp.StatusCode, "target must be active")
+	})
+
+	_ = adminPgID
+}
+
+// TestLibraryTypeNameTriggerOnLibraryChange proves the schema trigger keeps
+// media_items.library_type_name in sync when a row is repointed to a library
+// of a different type (the INSERT-only trigger previously left it stale).
+func TestLibraryTypeNameTriggerOnLibraryChange(t *testing.T) {
+	setup := setupTestServer(t)
+	defer func() { _ = setup.Close() }()
+
+	ctx := context.Background()
+	adminID, _ := moveTestAdminID(t, setup)
+	libE, folderE := createTypedTestLibrary(t, setup, "Trigger Ebooks", "ebooks")
+	libC, _ := createTypedTestLibrary(t, setup, "Trigger Comics", "comics")
+	defer deleteLibraries(t, setup, libE, libC)
+
+	writeTestEbook(t, folderE, []byte("trigger check content"))
+	scanTestFolder(t, setup, adminID, folderE)
+
+	books, err := setup.DB.ListMediaItemsByLibrary(ctx, libE)
+	require.NoError(t, err)
+	require.Len(t, books, 1)
+	item := books[0]
+	require.True(t, item.LibraryTypeName.Valid && item.LibraryTypeName.String == "ebooks")
+
+	require.NoError(t, setup.DB.MoveMediaItemToLibrary(ctx, database.MoveMediaItemToLibraryParams{
+		ID:        item.ID,
+		LibraryID: libC,
+		FilePath:  "Author/Test Book.epub",
+		FileSize:  pgtype.Int8{Int64: 27, Valid: true},
+	}))
+
+	after, err := setup.DB.GetMediaItem(ctx, item.ID)
+	require.NoError(t, err)
+	assert.Equal(t, libC, after.LibraryID)
+	assert.True(t, after.LibraryTypeName.Valid && after.LibraryTypeName.String == "comics",
+		"trigger must refresh library_type_name when library_id changes")
+}

cmd/server/tests/dashboard_integration_test.go

@@ -69,15 +69,16 @@ func (s *DashboardIntegrationTestSuite) TestGetSections_EndToEndFlow() {
 		assert.IsType(s.T(), float64(0), section["priority"], "priority should be number")
 	}
 
-	// Verify all system collections exist
-	assert.Contains(s.T(), sectionMap, "continue-reading")
-	assert.Contains(s.T(), sectionMap, "recently-added")
-	assert.Contains(s.T(), sectionMap, "recently-read")
-	assert.Contains(s.T(), sectionMap, "not-started")
-	assert.Contains(s.T(), sectionMap, "continue-series")
+	// Verify all system collections exist (names are the section ids;
+	// the canonical seed names are Title-case).
+	assert.Contains(s.T(), sectionMap, "Continue Reading")
+	assert.Contains(s.T(), sectionMap, "Recently Added")
+	assert.Contains(s.T(), sectionMap, "Recently Read")
+	assert.Contains(s.T(), sectionMap, "Not Started")
+	assert.Contains(s.T(), sectionMap, "Continue Series")
 
 	// Verify continue-reading is a system collection
-	continueReading := sectionMap["continue-reading"]
+	continueReading := sectionMap["Continue Reading"]
 	assert.True(s.T(), continueReading["is_system"].(bool), "continue-reading should be system collection")
 	assert.Equal(s.T(), "📖", continueReading["icon"], "icon should match")
 }
@@ -85,6 +86,8 @@ func (s *DashboardIntegrationTestSuite) TestGetSections_EndToEndFlow() {
 func (s *DashboardIntegrationTestSuite) TestGetSections_MissingLibraryID() {
 	token := s.setup.Token
 
+	// No library_id = the All Libraries view: the endpoint aggregates
+	// sections across every library (200), it does not 400.
 	req, _ := http.NewRequest("GET", s.setup.Server.URL+"/api/dashboard/sections", nil)
 	req.Header.Set("Authorization", "Bearer "+token)
 
@@ -95,7 +98,14 @@ func (s *DashboardIntegrationTestSuite) TestGetSections_MissingLibraryID() {
 		_ = Body.Close()
 	}(resp.Body)
 
-	assert.Equal(s.T(), http.StatusBadRequest, resp.StatusCode)
+	assert.Equal(s.T(), http.StatusOK, resp.StatusCode)
+
+	var response map[string]interface{}
+	err = json.NewDecoder(resp.Body).Decode(&response)
+	require.NoError(s.T(), err)
+	sections, ok := response["sections"].([]interface{})
+	require.True(s.T(), ok, "sections should be an array")
+	assert.NotEmpty(s.T(), sections, "All Libraries view should aggregate sections")
 }
 
 func (s *DashboardIntegrationTestSuite) TestGetSections_InvalidLibraryID() {
@@ -258,6 +268,263 @@ func (s *DashboardIntegrationTestSuite) TestRestoreSystemCollection_ValidNames()
 	}
 }
 
+func (s *DashboardIntegrationTestSuite) TestUpdatePreferences_GlobalScope() {
+	token := s.setup.Token
+
+	// Absent library_id (JSON null after omit) = the global All Libraries
+	// scope: stored in user_dashboard_preferences_global, one row per user.
+	reqBody := map[string]interface{}{
+		"hidden_collections": []string{"not-started"},
+		"collection_order":   []string{"continue-reading", "recently-added"},
+		"items_per_section":  15,
+	}
+	body, _ := json.Marshal(reqBody)
+	req, _ := http.NewRequest("PUT", s.setup.Server.URL+"/api/dashboard/preferences", bytes.NewBuffer(body))
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("Authorization", "Bearer "+token)
+
+	client := &http.Client{}
+	resp, err := client.Do(req)
+	require.NoError(s.T(), err)
+	defer func(Body io.ReadCloser) {
+		_ = Body.Close()
+	}(resp.Body)
+
+	assert.Equal(s.T(), http.StatusOK, resp.StatusCode)
+
+	// Second global save with different values: must UPDATE the same row
+	// (the old ON CONFLICT (user_id, library_id) never fired for NULLs and
+	// would have minted a duplicate per save).
+	reqBody["items_per_section"] = 25
+	body, _ = json.Marshal(reqBody)
+	req, _ = http.NewRequest("PUT", s.setup.Server.URL+"/api/dashboard/preferences", bytes.NewBuffer(body))
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("Authorization", "Bearer "+token)
+	resp, err = client.Do(req)
+	require.NoError(s.T(), err)
+	defer func(Body io.ReadCloser) {
+		_ = Body.Close()
+	}(resp.Body)
+	assert.Equal(s.T(), http.StatusOK, resp.StatusCode)
+
+	// Reading prefs without library_id returns the global row (not some
+	// arbitrary library's).
+	req, _ = http.NewRequest("GET", s.setup.Server.URL+"/api/dashboard/preferences", nil)
+	req.Header.Set("Authorization", "Bearer "+token)
+	resp, err = client.Do(req)
+	require.NoError(s.T(), err)
+	defer func(Body io.ReadCloser) {
+		_ = Body.Close()
+	}(resp.Body)
+	assert.Equal(s.T(), http.StatusOK, resp.StatusCode)
+
+	var prefs map[string]interface{}
+	err = json.NewDecoder(resp.Body).Decode(&prefs)
+	require.NoError(s.T(), err)
+	assert.Equal(s.T(), float64(25), prefs["items_per_section"], "global row should carry the second save")
+}
+
+func (s *DashboardIntegrationTestSuite) TestUpdatePreferences_EmptyLibraryIDRejected() {
+	token := s.setup.Token
+
+	// Empty string is a LOST value (a client bug), never a scope — must
+	// stay a loud 400 rather than silently writing the global scope.
+	reqBody := map[string]interface{}{
+		"library_id":         "",
+		"hidden_collections": []string{},
+		"collection_order":   []string{},
+		"items_per_section":  20,
+	}
+	body, _ := json.Marshal(reqBody)
+	req, _ := http.NewRequest("PUT", s.setup.Server.URL+"/api/dashboard/preferences", bytes.NewBuffer(body))
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("Authorization", "Bearer "+token)
+
+	client := &http.Client{}
+	resp, err := client.Do(req)
+	require.NoError(s.T(), err)
+	defer func(Body io.ReadCloser) {
+		_ = Body.Close()
+	}(resp.Body)
+
+	assert.Equal(s.T(), http.StatusBadRequest, resp.StatusCode)
+}
+
+func (s *DashboardIntegrationTestSuite) TestGetPreferences_GlobalAndPerLibraryIndependent() {
+	token := s.setup.Token
+	libraryID := createTestLibraryWithFolder(s.T(), s.setup.Server, token, "Prefs Scope Test Library", false)
+
+	// Global scope: 15.
+	globalBody, _ := json.Marshal(map[string]interface{}{
+		"hidden_collections": []string{},
+		"collection_order":   []string{},
+		"items_per_section":  15,
+	})
+	req, _ := http.NewRequest("PUT", s.setup.Server.URL+"/api/dashboard/preferences", bytes.NewBuffer(globalBody))
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("Authorization", "Bearer "+token)
+	client := &http.Client{}
+	resp, err := client.Do(req)
+	require.NoError(s.T(), err)
+	resp.Body.Close()
+	require.Equal(s.T(), http.StatusOK, resp.StatusCode)
+
+	// Per-library scope: 30. Must not bleed into global or vice versa.
+	libBody, _ := json.Marshal(map[string]interface{}{
+		"library_id":         libraryID,
+		"hidden_collections": []string{},
+		"collection_order":   []string{},
+		"items_per_section":  30,
+	})
+	req, _ = http.NewRequest("PUT", s.setup.Server.URL+"/api/dashboard/preferences", bytes.NewBuffer(libBody))
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("Authorization", "Bearer "+token)
+	resp, err = client.Do(req)
+	require.NoError(s.T(), err)
+	resp.Body.Close()
+	require.Equal(s.T(), http.StatusOK, resp.StatusCode)
+
+	// Per-library read.
+	req, _ = http.NewRequest("GET", s.setup.Server.URL+"/api/dashboard/preferences?library_id="+libraryID, nil)
+	req.Header.Set("Authorization", "Bearer "+token)
+	resp, err = client.Do(req)
+	require.NoError(s.T(), err)
+	defer func(Body io.ReadCloser) {
+		_ = Body.Close()
+	}(resp.Body)
+	require.Equal(s.T(), http.StatusOK, resp.StatusCode)
+	var libPrefs map[string]interface{}
+	err = json.NewDecoder(resp.Body).Decode(&libPrefs)
+	require.NoError(s.T(), err)
+	assert.Equal(s.T(), float64(30), libPrefs["items_per_section"], "per-library scope should read its own row")
+
+	// Global read.
+	req, _ = http.NewRequest("GET", s.setup.Server.URL+"/api/dashboard/preferences", nil)
+	req.Header.Set("Authorization", "Bearer "+token)
+	resp, err = client.Do(req)
+	require.NoError(s.T(), err)
+	defer func(Body io.ReadCloser) {
+		_ = Body.Close()
+	}(resp.Body)
+	require.Equal(s.T(), http.StatusOK, resp.StatusCode)
+	var globalPrefs map[string]interface{}
+	err = json.NewDecoder(resp.Body).Decode(&globalPrefs)
+	require.NoError(s.T(), err)
+	assert.Equal(s.T(), float64(15), globalPrefs["items_per_section"], "global scope should stay independent")
+}
+
+// TestDeleteSystemCollection_TombstonesAndRestores pins the system-
+// collection permanence contract: DELETE hides the section everywhere
+// (tombstone) and restore brings back the EXACT SAME row (id stable),
+// never a fresh one.
+func newHTTPClient() *http.Client { return &http.Client{} }
+func (s *DashboardIntegrationTestSuite) TestDeleteSystemCollection_TombstonesAndRestores() {
+	token := s.setup.Token
+	libraryID := createTestLibraryWithFolder(s.T(), s.setup.Server, token, "Test Library", false)
+
+	collectionID := func(sectionID string) string {
+		url := fmt.Sprintf("%s/api/dashboard/sections?library_id=%s", s.setup.Server.URL, libraryID)
+		req, _ := http.NewRequest("GET", url, nil)
+		req.Header.Set("Authorization", "Bearer "+token)
+		resp, err := newHTTPClient().Do(req)
+		require.NoError(s.T(), err)
+		defer func(Body io.ReadCloser) { _ = Body.Close() }(resp.Body)
+		require.Equal(s.T(), http.StatusOK, resp.StatusCode)
+		var response map[string]interface{}
+		require.NoError(s.T(), json.NewDecoder(resp.Body).Decode(&response))
+		for _, sec := range response["sections"].([]interface{}) {
+			section := sec.(map[string]interface{})
+			if section["id"] == sectionID {
+				return section["collection_id"].(string)
+			}
+		}
+		return ""
+	}
+	hasSection := func(sectionID string) bool {
+		url := fmt.Sprintf("%s/api/dashboard/sections?library_id=%s", s.setup.Server.URL, libraryID)
+		req, _ := http.NewRequest("GET", url, nil)
+		req.Header.Set("Authorization", "Bearer "+token)
+		resp, err := newHTTPClient().Do(req)
+		require.NoError(s.T(), err)
+		defer func(Body io.ReadCloser) { _ = Body.Close() }(resp.Body)
+		var response map[string]interface{}
+		require.NoError(s.T(), json.NewDecoder(resp.Body).Decode(&response))
+		for _, sec := range response["sections"].([]interface{}) {
+			if sec.(map[string]interface{})["id"] == sectionID {
+				return true
+			}
+		}
+		return false
+	}
+
+	idBefore := collectionID("Continue Reading")
+	require.NotEmpty(s.T(), idBefore, "Continue Reading should exist")
+
+	// DELETE a system collection = tombstone (204, behaves like a delete).
+	delReq, _ := http.NewRequest("DELETE", s.setup.Server.URL+"/api/collections/"+idBefore, nil)
+	delReq.Header.Set("Authorization", "Bearer "+token)
+	delResp, err := newHTTPClient().Do(delReq)
+	require.NoError(s.T(), err)
+	defer func(Body io.ReadCloser) { _ = Body.Close() }(delResp.Body)
+	assert.Equal(s.T(), http.StatusNoContent, delResp.StatusCode)
+
+	// Invisible on the dashboard.
+	assert.False(s.T(), hasSection("Continue Reading"), "tombstoned section must vanish")
+
+	// Restore brings back the EXACT SAME row.
+	restoreBody, _ := json.Marshal(map[string]string{"collection_name": "Continue Reading"})
+	req, _ := http.NewRequest("POST", s.setup.Server.URL+"/api/dashboard/restore-system-collection", bytes.NewBuffer(restoreBody))
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("Authorization", "Bearer "+token)
+	restoreResp, err := newHTTPClient().Do(req)
+	require.NoError(s.T(), err)
+	defer func(Body io.ReadCloser) { _ = Body.Close() }(restoreResp.Body)
+	require.Equal(s.T(), http.StatusOK, restoreResp.StatusCode)
+
+	idAfter := collectionID("Continue Reading")
+	assert.Equal(s.T(), idBefore, idAfter, "restore must resurrect the SAME row id")
+	assert.True(s.T(), hasSection("Continue Reading"))
+}
+
+// TestDeleteUserCollection_HardDelete pins the user-collection contract:
+// user collections hard-delete exactly as before (no tombstone, no restore).
+func (s *DashboardIntegrationTestSuite) TestDeleteUserCollection_HardDelete() {
+	token := s.setup.Token
+
+	createBody, _ := json.Marshal(map[string]interface{}{"name": "Test User Shelf", "type": "ebooks"})
+	req, _ := http.NewRequest("POST", s.setup.Server.URL+"/api/collections", bytes.NewBuffer(createBody))
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("Authorization", "Bearer "+token)
+	createResp, err := newHTTPClient().Do(req)
+	require.NoError(s.T(), err)
+	defer func(Body io.ReadCloser) { _ = Body.Close() }(createResp.Body)
+	require.Equal(s.T(), http.StatusCreated, createResp.StatusCode)
+
+	var created map[string]interface{}
+	require.NoError(s.T(), json.NewDecoder(createResp.Body).Decode(&created))
+	collectionID := created["id"].(string)
+
+	delReq, _ := http.NewRequest("DELETE", s.setup.Server.URL+"/api/collections/"+collectionID, nil)
+	delReq.Header.Set("Authorization", "Bearer "+token)
+	delResp, err := newHTTPClient().Do(delReq)
+	require.NoError(s.T(), err)
+	defer func(Body io.ReadCloser) { _ = Body.Close() }(delResp.Body)
+	assert.Equal(s.T(), http.StatusNoContent, delResp.StatusCode)
+
+	listReq, _ := http.NewRequest("GET", s.setup.Server.URL+"/api/collections", nil)
+	listReq.Header.Set("Authorization", "Bearer "+token)
+	listResp, err := newHTTPClient().Do(listReq)
+	require.NoError(s.T(), err)
+	defer func(Body io.ReadCloser) { _ = Body.Close() }(listResp.Body)
+	var list struct {
+		Collections []map[string]interface{} `json:"collections"`
+	}
+	require.NoError(s.T(), json.NewDecoder(listResp.Body).Decode(&list))
+	for _, c := range list.Collections {
+		assert.NotEqual(s.T(), collectionID, c["id"], "hard-deleted user collection must be gone")
+	}
+}
+
 func TestDashboardIntegrationTestSuite(t *testing.T) {
 	suite.Run(t, new(DashboardIntegrationTestSuite))
 }

cmd/server/tests/device_cap_test.go

@@ -336,7 +336,7 @@ func createTestUserForMaxDevices(t *testing.T, ts *httptest.Server, adminToken s
 	}
 
 	jsonData, _ := json.Marshal(createUserPayload)
-	req, _ := http.NewRequest("POST", ts.URL+"/api/auth/register", bytes.NewBuffer(jsonData))
+	req, _ := http.NewRequest("POST", ts.URL+"/api/auth/users", bytes.NewBuffer(jsonData))
 	req.Header.Set("Content-Type", "application/json")
 	req.Header.Set("Authorization", "Bearer "+adminToken)
 
@@ -416,14 +416,19 @@ func createTestUserForMaxDevices(t *testing.T, ts *httptest.Server, adminToken s
 	err = json.NewDecoder(resp.Body).Decode(&result)
 	require.NoError(t, err)
 
-	// Check if user creation was successful
-	if result["user"] == nil {
+	// Admin create returns the user object at the top level; the legacy
+	// register endpoint nested it under "user". Accept both.
+	userObj, ok := result["user"].(map[string]interface{})
+	if !ok {
+		userObj = result
+	}
+	if userObj["id"] == nil {
 		// User creation failed for another reason
 		t.Logf("User creation failed, response: %+v", result)
 		return uuid.UUID{}
 	}
 
-	userIDStr := result["user"].(map[string]interface{})["id"].(string)
+	userIDStr, _ := userObj["id"].(string)
 	userID, _ := uuid.Parse(userIDStr)
 
 	return userID

cmd/server/tests/device_test.go

@@ -252,6 +252,88 @@ func TestListPendingRegistrations(t *testing.T) {
 	assert.NotNil(t, pending, "Pending registrations should not be nil")
 }
 
+// Regression test for the "approve returns 500 after app reinstall" bug:
+// an app reinstall that preserves data (e.g. Android Studio installDebug
+// over an existing install) re-registers with the SAME device_identifier,
+// and the blind INSERT in ApproveDevice hit the UNIQUE(device_identifier)
+// constraint. Re-approval must be idempotent: same row (id unchanged),
+// rotated token, old token invalidated.
+func TestApproveDeviceReapprovalRotatesToken(t *testing.T) {
+	setup := setupTestServer(t)
+	userID := getTestUserID(t, setup.DB)
+
+	identifier := fmt.Sprintf("repro-reinstall-%s", uuid.New().String())
+
+	registerAndApprove := func() string {
+		regRequest := map[string]interface{}{
+			"device_name":       "Reinstall Device",
+			"device_type":       "mobile",
+			"device_identifier": identifier,
+		}
+		regBody, _ := json.Marshal(regRequest)
+
+		req := httptest.NewRequest("POST", "/api/devices/register", bytes.NewReader(regBody))
+		req.Header.Set("Content-Type", "application/json")
+		rec := httptest.NewRecorder()
+		setup.Server.Config.Handler.ServeHTTP(rec, req)
+		require.Equal(t, http.StatusCreated, rec.Code, "Should initiate registration")
+
+		var regResponse map[string]interface{}
+		json.Unmarshal(rec.Body.Bytes(), &regResponse)
+		registrationID, ok := regResponse["registration_id"].(string)
+		require.True(t, ok, "Should have registration_id")
+
+		req = httptest.NewRequest("GET", fmt.Sprintf("/api/devices/approve/%s", registrationID), nil)
+		req.Header.Set("Authorization", "Bearer "+setup.Token)
+		rec = httptest.NewRecorder()
+		setup.Server.Config.Handler.ServeHTTP(rec, req)
+		require.Equal(t, http.StatusOK, rec.Code,
+			"Approve must succeed even when the identifier already exists (was the reinstall 500)")
+
+		// The status response is single-use and carries the credentials.
+		statusBody, _ := json.Marshal(map[string]string{"registration_id": registrationID})
+		req = httptest.NewRequest("POST", "/api/devices/register/status", bytes.NewReader(statusBody))
+		req.Header.Set("Content-Type", "application/json")
+		rec = httptest.NewRecorder()
+		setup.Server.Config.Handler.ServeHTTP(rec, req)
+		require.Equal(t, http.StatusOK, rec.Code)
+
+		var statusResponse map[string]interface{}
+		json.Unmarshal(rec.Body.Bytes(), &statusResponse)
+		require.Equal(t, "approved", statusResponse["status"])
+		token, ok := statusResponse["auth_token"].(string)
+		require.True(t, ok, "Should have auth_token")
+		require.NotEmpty(t, token)
+		return token
+	}
+
+	token1 := registerAndApprove()
+	token2 := registerAndApprove()
+
+	assert.NotEqual(t, token1, token2, "Re-approval must rotate the auth token (fresh install = fresh credentials)")
+
+	devices, err := setup.DB.ListDevicesByUser(context.Background(),
+		pgtype.UUID{Bytes: [16]byte(userID), Valid: true})
+	require.NoError(t, err)
+	rows := 0
+	for _, d := range devices {
+		if d.DeviceIdentifier == identifier {
+			rows++
+		}
+	}
+	assert.Equal(t, 1, rows, "Re-approval must reuse the existing devices row, not duplicate it")
+
+	// The rotated-in token must be the live one.
+	var live *database.Devices
+	for i := range devices {
+		if devices[i].DeviceIdentifier == identifier {
+			live = &devices[i]
+		}
+	}
+	require.NotNil(t, live)
+	assert.Equal(t, token2, live.AuthToken, "The devices row must carry the newly rotated token")
+}
+
 func TestApproveDeviceRegistration(t *testing.T) {
 	setup := setupTestServer(t)
 
@@ -430,7 +512,7 @@ func TestRegenerateDeviceToken_Forbidden(t *testing.T) {
 	defer setup.Server.Close()
 
 	// Create device for user 1
-	device1 := setup.CreateDevice(t, "User1 Device", "koreader", "user1-device")
+	device1 := setup.CreateDevice(t, "User1 Device", "koreader", "user1-test-device")
 
 	// Create a second user with different credentials
 	ctx := context.Background()
@@ -442,6 +524,7 @@ func TestRegenerateDeviceToken_Forbidden(t *testing.T) {
 		FirstName:    pgtype.Text{String: "Different", Valid: true},
 		LastName:     pgtype.Text{String: "User", Valid: true},
 		Role:         "user",
+		Timezone:     pgtype.Text{String: "UTC", Valid: true},
 	})
 	assert.NoError(t, err)
 

cmd/server/tests/filters_test.go

@@ -47,7 +47,7 @@ func TestSavedFilters(t *testing.T) {
 
 	t.Run("POST /api/saved-filters creates filter", func(t *testing.T) {
 		reqBody := map[string]interface{}{
-			"name":          "My Sci-Fi Books",
+			"name":          "My Sci-Fi Test Books",
 			"resource_type": "media-items",
 			"filters": map[string]string{
 				"genre_filter": "Science Fiction",
@@ -71,7 +71,7 @@ func TestSavedFilters(t *testing.T) {
 		var filter map[string]interface{}
 		err = json.NewDecoder(resp.Body).Decode(&filter)
 		require.NoError(t, err)
-		assert.Equal(t, "My Sci-Fi Books", filter["name"])
+		assert.Equal(t, "My Sci-Fi Test Books", filter["name"])
 		assert.Equal(t, "media-items", filter["resource_type"])
 		assert.NotEmpty(t, filter["id"])
 		// Filters field will be JSON object (JSONB as raw bytes)
@@ -113,7 +113,7 @@ func TestSavedFilters(t *testing.T) {
 	t.Run("PUT /api/saved-filters/:id updates filter", func(t *testing.T) {
 		// Create filter first
 		createReq := map[string]interface{}{
-			"name":          "Original Name",
+			"name":          "Original Test Name",
 			"resource_type": "media-items",
 			"filters":       map[string]string{"search": "original"},
 		}
@@ -134,11 +134,13 @@ func TestSavedFilters(t *testing.T) {
 		var createdFilter map[string]interface{}
 		err = json.NewDecoder(createResp.Body).Decode(&createdFilter)
 		require.NoError(t, err)
-		filterID := createdFilter["id"].(string)
+		filterIDRaw, ok := createdFilter["id"]
+		require.True(t, ok, "create filter response should carry id: %v", createdFilter)
+		filterID := filterIDRaw.(string)
 
 		// Update filter
 		updateReq := map[string]interface{}{
-			"name":          "Updated Name",
+			"name":          "Updated Test Name",
 			"resource_type": "media-items",
 			"filters":       map[string]string{"search": "updated"},
 		}
@@ -159,7 +161,7 @@ func TestSavedFilters(t *testing.T) {
 		var updatedFilter map[string]interface{}
 		err = json.NewDecoder(updateResp.Body).Decode(&updatedFilter)
 		require.NoError(t, err)
-		assert.Equal(t, "Updated Name", updatedFilter["name"])
+		assert.Equal(t, "Updated Test Name", updatedFilter["name"])
 	})
 
 	t.Run("DELETE /api/saved-filters/:id deletes filter", func(t *testing.T) {
@@ -184,7 +186,9 @@ func TestSavedFilters(t *testing.T) {
 		var createdFilter map[string]interface{}
 		err = json.NewDecoder(createResp.Body).Decode(&createdFilter)
 		require.NoError(t, err)
-		filterID := createdFilter["id"].(string)
+		filterIDRaw, ok := createdFilter["id"]
+		require.True(t, ok, "create filter response should carry id: %v", createdFilter)
+		filterID := filterIDRaw.(string)
 
 		// Delete filter
 		deleteHTTP, _ := http.NewRequest("DELETE", setup.Server.URL+"/api/saved-filters/"+filterID, nil)
@@ -223,7 +227,9 @@ func TestSavedFilters(t *testing.T) {
 		var createdFilter map[string]interface{}
 		err = json.NewDecoder(createResp.Body).Decode(&createdFilter)
 		require.NoError(t, err)
-		filterID := createdFilter["id"].(string)
+		filterIDRaw, ok := createdFilter["id"]
+		require.True(t, ok, "create filter response should carry id: %v", createdFilter)
+		filterID := filterIDRaw.(string)
 
 		// Admin user tries to delete regular user's filter
 		deleteHTTP, _ := http.NewRequest("DELETE", setup.Server.URL+"/api/saved-filters/"+filterID, nil)
@@ -260,7 +266,9 @@ func TestSavedFilters(t *testing.T) {
 		var createdFilter map[string]interface{}
 		err = json.NewDecoder(createResp.Body).Decode(&createdFilter)
 		require.NoError(t, err)
-		filterID := createdFilter["id"].(string)
+		filterIDRaw, ok := createdFilter["id"]
+		require.True(t, ok, "create filter response should carry id: %v", createdFilter)
+		filterID := filterIDRaw.(string)
 
 		// Now retrieve the filter by ID
 		getReq, _ := http.NewRequest("GET", setup.Server.URL+"/api/saved-filters/"+filterID, nil)
@@ -324,7 +332,7 @@ func TestSavedFilters(t *testing.T) {
 	t.Run("GET /api/saved-filters/:id from different user returns 404", func(t *testing.T) {
 		// Create filter with admin user (setup.Token)
 		reqBody := map[string]interface{}{
-			"name":          "Admin Filter",
+			"name":          "Admin Test Filter",
 			"resource_type": "media-items",
 			"filters":       map[string]string{"search": "test"},
 		}
@@ -340,7 +348,9 @@ func TestSavedFilters(t *testing.T) {
 		var createdFilter map[string]interface{}
 		err = json.NewDecoder(createResp.Body).Decode(&createdFilter)
 		require.NoError(t, err)
-		filterID := createdFilter["id"].(string)
+		filterIDRaw, ok := createdFilter["id"]
+		require.True(t, ok, "create filter response should carry id: %v", createdFilter)
+		filterID := filterIDRaw.(string)
 		// Try to access with regular user (setup.RegularToken)
 		httpReq, _ := http.NewRequest("GET", setup.Server.URL+"/api/saved-filters/"+filterID, nil)
 		httpReq.Header.Set("Authorization", "Bearer "+setup.RegularToken)

cmd/server/tests/library_browse_test.go

@@ -4,6 +4,8 @@ import (
 	"encoding/json"
 	"net/http"
 	"net/http/httptest"
+	"os"
+	"path/filepath"
 	"testing"
 
 	"github.com/stretchr/testify/assert"
@@ -28,7 +30,21 @@ func TestBrowseLibraryFoldersEndpoint(t *testing.T) {
 	})
 
 	t.Run("GET /api/libraries/browse - admin can browse directories", func(t *testing.T) {
-		req := httptest.NewRequest("GET", "/api/libraries/browse?path=/tmp", nil)
+		// Self-created fixture dir: the container's /tmp may be empty, and
+		// the endpoint lists DIRECTORIES only — seed two so the listing is
+		// deterministic regardless of environment.
+		root := t.TempDir()
+		for _, name := range []string{"alpha", "beta"} {
+			if err := os.Mkdir(filepath.Join(root, name), 0o755); err != nil {
+				t.Fatal(err)
+			}
+		}
+		// A decoy file must NOT appear in the directory listing.
+		if err := os.WriteFile(filepath.Join(root, "stray.txt"), []byte("x"), 0o644); err != nil {
+			t.Fatal(err)
+		}
+
+		req := httptest.NewRequest("GET", "/api/libraries/browse?path="+root, nil)
 		req.Header.Set("Authorization", "Bearer "+setup.Token)
 		rec := httptest.NewRecorder()
 		setup.Server.Config.Handler.ServeHTTP(rec, req)
@@ -41,8 +57,8 @@ func TestBrowseLibraryFoldersEndpoint(t *testing.T) {
 		}
 		err := json.Unmarshal(rec.Body.Bytes(), &data)
 		assert.NoError(t, err)
-		assert.Equal(t, "/tmp", data.CurrentPath)
-		assert.NotEmpty(t, data.Directories)
+		assert.Equal(t, filepath.Clean(root), data.CurrentPath)
+		assert.ElementsMatch(t, []string{"alpha", "beta"}, data.Directories)
 	})
 
 	t.Run("GET /api/libraries/browse - blocks path traversal attempts", func(t *testing.T) {

cmd/server/tests/media_item_isbn_test.go

@@ -7,6 +7,7 @@ import (
 	"io"
 	"net/http"
 	"net/http/httptest"
+	"strings"
 	"testing"
 	"time"
 
@@ -151,11 +152,15 @@ func TestMediaItemISBNNormalization(t *testing.T) {
 
 	for _, tc := range testCases {
 		t.Run(tc.name, func(t *testing.T) {
+			// Unique file_path per case: CreateMediaItem upserts ON
+			// CONFLICT (library_id, file_path), so a constant path would
+			// return the FIRST row's ISBN for every later case.
+			slug := strings.ReplaceAll(strings.ToLower(tc.name), " ", "-")
 			payload := map[string]interface{}{
 				"title":      fmt.Sprintf("Test Book %s", tc.name),
 				"isbn":       tc.input,
 				"library_id": libID,
-				"file_path":  "/test/path.epub",
+				"file_path":  "/test/" + slug + ".epub",
 				"file_size":  1024,
 				"mime_type":  "application/epub+zip",
 			}
@@ -203,7 +208,7 @@ func TestMediaItemISBNEdgeCases(t *testing.T) {
 		payload := map[string]interface{}{
 			"title":      "Book without ISBN",
 			"library_id": libID,
-			"file_path":  "/test/path.epub",
+			"file_path":  "/test/book-without-isbn.epub",
 			"file_size":  1024,
 			"mime_type":  "application/epub+zip",
 		}
@@ -228,7 +233,7 @@ func TestMediaItemISBNEdgeCases(t *testing.T) {
 			"title":      "Multi-Hyphen ISBN",
 			"isbn":       "978-0-306-40615-7",
 			"library_id": libID,
-			"file_path":  "/test/path.epub",
+			"file_path":  "/test/multi-hyphen-isbn.epub",
 			"file_size":  1024,
 			"mime_type":  "application/epub+zip",
 		}
@@ -258,7 +263,7 @@ func TestMediaItemISBNEdgeCases(t *testing.T) {
 			"title":      "Trailing Hyphen ISBN",
 			"isbn":       "978-0-596-00965-2",
 			"library_id": libID,
-			"file_path":  "/test/path.epub",
+			"file_path":  "/test/trailing-hyphen-isbn.epub",
 			"file_size":  1024,
 			"mime_type":  "application/epub+zip",
 		}
@@ -292,13 +297,15 @@ func TestMediaItemsPagination(t *testing.T) {
 	libID := createTestLibrary(t, setup.Server, token, "test-pagination-lib")
 	addFolderToLibrary(t, setup, libID, "/app/uploads")
 
-	// Create some test media items
+	// Create some test media items. Unique file_path per item: the create
+	// endpoint upserts ON CONFLICT (library_id, file_path), so a constant
+	// path would collapse all five creates onto one row.
 	for i := 1; i <= 5; i++ {
 		payload := map[string]interface{}{
 			"title":      fmt.Sprintf("Book %d", i),
 			"isbn":       fmt.Sprintf("978030640615%d", i),
 			"library_id": libID,
-			"file_path":  "/test/path.epub",
+			"file_path":  fmt.Sprintf("/test/book-%d.epub", i),
 			"file_size":  1024,
 			"mime_type":  "application/epub+zip",
 		}
@@ -408,6 +415,62 @@ func TestMediaItemsPagination(t *testing.T) {
 	})
 }
 
+// TestMediaItemCreateDuplicatePath pins the create endpoint's duplicate
+// behavior: a POST with a (library_id, file_path) that already exists
+// answers 200 OK with the EXISTING item and duplicate=true — never a
+// 201 with the old row pretending to be new, and nothing overwritten.
+func TestMediaItemCreateDuplicatePath(t *testing.T) {
+	setup := setupTestServer(t)
+
+	token := setup.Token
+	libID := createTestLibrary(t, setup.Server, token, "test-dup-create-lib")
+	addFolderToLibrary(t, setup, libID, "/app/uploads")
+
+	createPayload := func(title string) []byte {
+		body, _ := json.Marshal(map[string]interface{}{
+			"title":      title,
+			"author":     "First Author",
+			"isbn":       "9780306406157",
+			"library_id": libID,
+			"file_path":  "/test/dup-target.epub",
+			"file_size":  1024,
+			"mime_type":  "application/epub+zip",
+		})
+		return body
+	}
+
+	post := func(body []byte) (*http.Response, []byte) {
+		req, _ := http.NewRequest("POST", setup.Server.URL+"/api/media-items", bytes.NewBuffer(body))
+		req.Header.Set("Content-Type", "application/json")
+		req.Header.Set("Authorization", "Bearer "+token)
+		resp, err := (&http.Client{}).Do(req)
+		require.NoError(t, err)
+		defer func(Body io.ReadCloser) {
+			_ = Body.Close()
+		}(resp.Body)
+		raw, err := io.ReadAll(resp.Body)
+		require.NoError(t, err)
+		return resp, raw
+	}
+
+	resp, raw := post(createPayload("Original Title"))
+	require.Equal(t, http.StatusCreated, resp.StatusCode, "first create should be 201")
+	var created map[string]interface{}
+	require.NoError(t, json.Unmarshal(raw, &created))
+	originalID := created["id"].(string)
+
+	resp, raw = post(createPayload("Different Title"))
+	require.Equal(t, http.StatusOK, resp.StatusCode, "duplicate create should be 200, not a 201 lie")
+
+	var dup map[string]interface{}
+	require.NoError(t, json.Unmarshal(raw, &dup))
+	assert.Equal(t, true, dup["duplicate"], "response must flag the duplicate")
+	assert.Equal(t, originalID, dup["item"].(map[string]interface{})["id"].(string),
+		"duplicate response carries the existing item")
+	assert.Equal(t, "Original Title", dup["item"].(map[string]interface{})["title"],
+		"the second create's payload must NOT overwrite the existing row")
+}
+
 // TestMediaItemLibraryRequirement tests that media items require a library
 func TestMediaItemLibraryRequirement(t *testing.T) {
 	setup := setupTestServer(t)

cmd/server/tests/media_note_length_test.go

@@ -0,0 +1,54 @@
+package main
+
+import (
+	"bytes"
+	"encoding/json"
+	"io"
+	"net/http"
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// TestMediaNoteLengthLimits verifies the note content validator cap
+// (internal/handlers/media.go): content up to 100,000 chars is accepted,
+// longer content is rejected with 400.
+func TestMediaNoteLengthLimits(t *testing.T) {
+	setup := setupTestServer(t)
+
+	token := setup.Token
+	mediaItemID := createTestMediaItemID(t, setup)
+
+	postNote := func(content string) int {
+		payload := map[string]interface{}{
+			"content":  content,
+			"position": "page:1",
+		}
+		body, _ := json.Marshal(payload)
+		req, _ := http.NewRequest("POST", setup.Server.URL+"/api/media-items/"+mediaItemID+"/notes", bytes.NewBuffer(body))
+		req.Header.Set("Content-Type", "application/json")
+		req.Header.Set("Authorization", "Bearer "+token)
+
+		client := &http.Client{}
+		resp, err := client.Do(req)
+		require.NoError(t, err)
+		defer func(Body io.ReadCloser) {
+			_ = Body.Close()
+		}(resp.Body)
+		return resp.StatusCode
+	}
+
+	t.Run("50k-char note accepted", func(t *testing.T) {
+		assert.Equal(t, http.StatusCreated, postNote(strings.Repeat("a", 50000)))
+	})
+
+	t.Run("100k-char note accepted at boundary", func(t *testing.T) {
+		assert.Equal(t, http.StatusCreated, postNote(strings.Repeat("b", 100000)))
+	})
+
+	t.Run("over-limit note rejected", func(t *testing.T) {
+		assert.Equal(t, http.StatusBadRequest, postNote(strings.Repeat("c", 100001)))
+	})
+}

cmd/server/tests/opds_test.go

@@ -6,6 +6,7 @@ import (
 	"testing"
 
 	"github.com/google/uuid"
+	"github.com/jackc/pgx/v5/pgtype"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 )
@@ -435,3 +436,119 @@ func TestOPDSSearchAcrossLibraries(t *testing.T) {
 		t.Logf("❌ FAILED - OPDS returned %d", resp.StatusCode)
 	}
 }
+
+// TestOPDSLibraryFolders covers the library-folder navigation feed: the root
+// catalog is a navigation feed with an "All Books" entry plus one folder per
+// visible library, the scoped catalog only lists that library's books, and
+// the library-scoped search parameter restricts results to that library.
+// TestOPDSLibraryFolders covers the library-folder navigation feed: the root
+// catalog is a navigation feed with an "All Books" entry plus one folder per
+// visible library, the scoped catalog only lists that library's books, and
+// the library-scoped search parameter restricts results to that library.
+// NOTE: library names deliberately avoid the word "test" — setupTestServer's
+// setup-time cleanup deletes every library whose name contains it (and
+// setupDeviceTest re-runs that cleanup mid-test).
+func TestOPDSLibraryFolders(t *testing.T) {
+	setup := setupTestServer(t)
+	client := &http.Client{}
+
+	// Two libraries, one distinct book each.
+	lib1Resp := createLibrary(t, client, setup, "OPDS Folder Lib Alpha")
+	lib2Resp := createLibrary(t, client, setup, "OPDS Folder Lib Beta")
+	lib1ID := lib1Resp["id"].(string)
+	lib2ID := lib2Resp["id"].(string)
+	// Real directories: the folder API validates that the path exists on the
+	// host running the server (container path /app/uploads won't exist when
+	// tests run on the host).
+	addFolderToLibrary(t, setup, lib1ID, t.TempDir())
+	addFolderToLibrary(t, setup, lib2ID, t.TempDir())
+	createTestMediaItemIDInLibrary(t, client, setup, lib1ID, "OPDS Folder Book 1")
+	createTestMediaItemIDInLibrary(t, client, setup, lib2ID, "OPDS Folder Book 2")
+
+	deviceSetup := setupDeviceTest(t)
+	device := deviceSetup.CreateDevice(t, "OPDS Folders Device", "koreader", "opds-folders-"+uuid.NewString())
+	base := setup.Server.URL + "/opds/devices/" + device.ID.String()
+
+	// Explicit cleanup: these names don't contain "test", so the harness
+	// cleanup skips them; remove them ourselves. Registered as a defer AFTER
+	// the setup.Close defer so LIFO ordering runs it while the pool is open.
+	defer deleteLibraries(t, setup,
+		pgtype.UUID{Bytes: uuid.MustParse(lib1ID), Valid: true},
+		pgtype.UUID{Bytes: uuid.MustParse(lib2ID), Valid: true})
+
+	getFeed := func(t *testing.T, url string) (int, string, string) {
+		t.Helper()
+		req, _ := http.NewRequest("GET", url, nil)
+		req.Header.Set("Authorization", "Bearer "+device.AuthToken)
+		resp, err := client.Do(req)
+		require.NoError(t, err)
+		defer func(Body io.ReadCloser) {
+			_ = Body.Close()
+		}(resp.Body)
+		contentType := resp.Header.Get("Content-Type")
+		bodyBytes, err := io.ReadAll(resp.Body)
+		require.NoError(t, err)
+		return resp.StatusCode, contentType, string(bodyBytes)
+	}
+
+	t.Run("root catalog is a navigation feed with All Books and library folders", func(t *testing.T) {
+		status, contentType, body := getFeed(t, base+"/catalog")
+		require.Equal(t, http.StatusOK, status)
+		assert.Contains(t, contentType, "kind=navigation")
+		assert.Contains(t, body, "All Books")
+		assert.Contains(t, body, "OPDS Folder Lib Alpha")
+		assert.Contains(t, body, "OPDS Folder Lib Beta")
+		assert.Contains(t, body, "/library/"+lib1ID+"/catalog")
+		assert.Contains(t, body, "/library/"+lib2ID+"/catalog")
+		// The nav feed itself must not inline book entries.
+		assert.NotContains(t, body, "OPDS Folder Book 1")
+	})
+
+	t.Run("all=1 keeps the flat cross-library catalog", func(t *testing.T) {
+		// Explicit large page: the shared test DB accumulates items, and
+		// the freshly created books sort last — without a generous
+		// per_page they fall onto a later page and the assertion reads
+		// tea leaves instead of the contract.
+		status, contentType, body := getFeed(t, base+"/catalog?all=1&per_page=200")
+		require.Equal(t, http.StatusOK, status)
+		assert.Contains(t, contentType, "kind=acquisition")
+		assert.Contains(t, body, "OPDS Folder Book 1")
+		assert.Contains(t, body, "OPDS Folder Book 2")
+	})
+
+	t.Run("scoped catalog lists only its own library's books", func(t *testing.T) {
+		status, contentType, body := getFeed(t, base+"/library/"+lib1ID+"/catalog")
+		require.Equal(t, http.StatusOK, status)
+		assert.Contains(t, contentType, "kind=acquisition")
+		assert.Contains(t, body, "OPDS Folder Book 1")
+		assert.NotContains(t, body, "OPDS Folder Book 2")
+		// Scoped search discovery: template pins the library.
+		assert.Contains(t, body, "library_id="+lib1ID)
+	})
+
+	t.Run("scoped catalog rejects libraries outside device visibility", func(t *testing.T) {
+		status, _, _ := getFeed(t, base+"/library/11111111-2222-3333-4444-555555555555/catalog")
+		assert.Equal(t, http.StatusForbidden, status)
+	})
+
+	t.Run("scoped search restricts results to the library", func(t *testing.T) {
+		status, _, body := getFeed(t, base+"/search?q=OPDS+Folder&library_id="+lib2ID)
+		require.Equal(t, http.StatusOK, status)
+		assert.Contains(t, body, "OPDS Folder Book 2")
+		assert.NotContains(t, body, "OPDS Folder Book 1")
+	})
+
+	t.Run("scoped search rejects inaccessible library", func(t *testing.T) {
+		status, _, _ := getFeed(t, base+"/search?q=OPDS&library_id=11111111-2222-3333-4444-555555555555")
+		assert.Equal(t, http.StatusForbidden, status)
+	})
+
+	t.Run("global search labels entries with their library", func(t *testing.T) {
+		status, _, body := getFeed(t, base+"/search?q=OPDS+Folder")
+		require.Equal(t, http.StatusOK, status)
+		assert.Contains(t, body, "OPDS Folder Book 1")
+		assert.Contains(t, body, "OPDS Folder Book 2")
+		assert.Contains(t, body, "OPDS Folder Lib Alpha")
+		assert.Contains(t, body, "OPDS Folder Lib Beta")
+	})
+}

cmd/server/tests/ownership_and_admin_test.go

@@ -0,0 +1,315 @@
+package main
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"bookhoard/internal/database"
+
+	"github.com/google/uuid"
+	"github.com/jackc/pgx/v5/pgtype"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"github.com/stretchr/testify/suite"
+)
+
+// OwnershipAndAdminTestSuite pins the 2026-10-13 hardening: per-user
+// annotation mutations are ownership-scoped (no cross-user delete/update by
+// bare row id), and admins can create users even with self-service
+// registration disabled.
+type OwnershipAndAdminTestSuite struct {
+	suite.Suite
+	setup     *TestServerSetup
+	token     string
+	itemID    string
+	libraryID string
+	absFile   string
+}
+
+func (s *OwnershipAndAdminTestSuite) SetupSuite() {
+	s.setup = setupTestServer(s.T())
+	s.token = s.setup.Token
+	var libID string
+	s.itemID, libID, s.absFile = s.createItemViaDB(true)
+	s.libraryID = libID
+	// createTestMediaItemID's t.Cleanup path can't be used at suite level
+	// (it fires after TearDownSuite has closed the server), so the item is
+	// created directly through the DB handle; suite cleanup relies on the
+	// standard "@tests.bookhoard.internal / test-named rows" passes of the
+	// next run's setupTestServer.
+}
+
+// createItemViaDB makes a throwaway library + media item directly through
+// the test DB handle — no HTTP, no t.Cleanup entanglement.
+// With withFolder=true the library gets a REAL temp folder row and the
+// file is created on disk inside it, so deletes exercise real file
+// removal; the folder path is returned alongside the item id.
+func (s *OwnershipAndAdminTestSuite) createItemViaDB(withFolder bool) (itemID, libraryID, absFile string) {
+	ctx := s.setup.QueueCtx
+	db := s.setup.DB
+
+	libraryTypeRow, err := db.GetLibraryTypeByName(ctx, "ebooks")
+	require.NoError(s.T(), err, "should find ebooks library type")
+
+	admin, err := db.GetUserByEmail(ctx, "testuser@tests.bookhoard.internal")
+	require.NoError(s.T(), err, "dev admin user should exist")
+
+	library, err := db.CreateLibrary(ctx, database.CreateLibraryParams{
+		Name:             fmt.Sprintf("Ownership Suite Test Library %d", time.Now().UnixNano()),
+		Description:      pgtype.Text{String: "annotation ownership suite", Valid: true},
+		LibraryTypeID:    libraryTypeRow.ID,
+		CreatedByAdminID: admin.ID,
+	})
+	require.NoError(s.T(), err)
+
+	relPath := fmt.Sprintf("ownership-suite-%d.epub", time.Now().UnixNano())
+	absFile = ""
+	if withFolder {
+		dir, dirErr := os.MkdirTemp("", "ownership-suite-*")
+		require.NoError(s.T(), dirErr)
+		_, ferr := db.AddLibraryFolder(ctx, database.AddLibraryFolderParams{
+			LibraryID:  library.ID,
+			FolderPath: dir,
+		})
+		require.NoError(s.T(), ferr)
+		absFile = filepath.Join(dir, relPath)
+		if werr := os.WriteFile(absFile, []byte("restored book"), 0o644); werr != nil {
+			require.NoError(s.T(), werr)
+		}
+	}
+
+	item, err := db.CreateMediaItem(ctx, database.CreateMediaItemParams{
+		LibraryID: library.ID,
+		Title:     "Ownership Suite Item",
+		Author:    pgtype.Text{String: "Suite Author", Valid: true},
+		FilePath:  relPath,
+		MimeType:  pgtype.Text{String: "application/epub+zip", Valid: true},
+	})
+	require.NoError(s.T(), err)
+
+	return uuid.UUID(item.ID.Bytes).String(), uuid.UUID(library.ID.Bytes).String(), absFile
+}
+
+func (s *OwnershipAndAdminTestSuite) TearDownSuite() {
+	s.setup.Close()
+}
+
+func (s *OwnershipAndAdminTestSuite) getItem(itemID string) map[string]interface{} {
+	req, _ := http.NewRequest("GET", s.setup.Server.URL+"/api/media-items/"+itemID, nil)
+	req.Header.Set("Authorization", "Bearer "+s.token)
+	resp, err := (&http.Client{}).Do(req)
+	require.NoError(s.T(), err)
+	defer resp.Body.Close()
+	require.Equal(s.T(), http.StatusOK, resp.StatusCode)
+	var body map[string]interface{}
+	require.NoError(s.T(), json.NewDecoder(resp.Body).Decode(&body))
+	return body
+}
+
+func (s *OwnershipAndAdminTestSuite) createHighlight(token string) map[string]interface{} {
+	payload, _ := json.Marshal(map[string]interface{}{
+		"selection_text": "owned annotation text",
+		"start_position": "p1",
+		"end_position":   "p1",
+		"color":          "#ffff00",
+	})
+	req, _ := http.NewRequest("POST", s.setup.Server.URL+"/api/media-items/"+s.itemID+"/highlights", bytes.NewBuffer(payload))
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("Authorization", "Bearer "+token)
+	resp, err := (&http.Client{}).Do(req)
+	require.NoError(s.T(), err)
+	defer resp.Body.Close()
+	require.Equal(s.T(), http.StatusCreated, resp.StatusCode, "highlight create should succeed")
+	var body map[string]interface{}
+	require.NoError(s.T(), json.NewDecoder(resp.Body).Decode(&body))
+	return body
+}
+
+func (s *OwnershipAndAdminTestSuite) highlightExists(token, highlightID string) bool {
+	req, _ := http.NewRequest("GET", s.setup.Server.URL+"/api/media-items/"+s.itemID+"/highlights", nil)
+	req.Header.Set("Authorization", "Bearer "+token)
+	resp, err := (&http.Client{}).Do(req)
+	require.NoError(s.T(), err)
+	defer resp.Body.Close()
+	var body []map[string]interface{}
+	require.NoError(s.T(), json.NewDecoder(resp.Body).Decode(&body))
+	for _, h := range body {
+		if h["id"] == highlightID {
+			return true
+		}
+	}
+	return false
+}
+
+// TestHighlightDelete_CrossUserNoOp pins the ownership predicate: user B's
+// DELETE of user A's highlight by bare id must not remove A's row.
+func (s *OwnershipAndAdminTestSuite) TestHighlightDelete_CrossUserNoOp() {
+	regular := s.setup.RegularToken
+
+	created := s.createHighlight(regular)
+	highlightID, ok := created["id"].(string)
+	require.True(s.T(), ok, "create response carries the highlight id")
+
+	// The ADMIN (a different user) tries to delete it by id.
+	req, _ := http.NewRequest("DELETE", s.setup.Server.URL+"/api/media-items/"+s.itemID+"/highlights/"+highlightID, nil)
+	req.Header.Set("Authorization", "Bearer "+s.token)
+	resp, err := (&http.Client{}).Do(req)
+	require.NoError(s.T(), err)
+	io.Copy(io.Discard, resp.Body)
+	resp.Body.Close()
+
+	assert.True(s.T(), s.highlightExists(regular, highlightID),
+		"another user's delete-by-id must not remove the owner's highlight")
+
+	// The owner deletes their own highlight — gone.
+	req, _ = http.NewRequest("DELETE", s.setup.Server.URL+"/api/media-items/"+s.itemID+"/highlights/"+highlightID, nil)
+	req.Header.Set("Authorization", "Bearer "+regular)
+	resp, err = (&http.Client{}).Do(req)
+	require.NoError(s.T(), err)
+	io.Copy(io.Discard, resp.Body)
+	resp.Body.Close()
+
+	assert.False(s.T(), s.highlightExists(regular, highlightID), "owner delete removes the row")
+}
+
+// TestAdminCreateUser pins the admin counterpart to registration: admins
+// create accounts even with self-service registration disabled, regular
+// users cannot, and duplicates conflict.
+func (s *OwnershipAndAdminTestSuite) TestAdminCreateUser() {
+	suffix := fmt.Sprintf("%d", s.setup.DBPool.Config().MaxConns) // stable-ish uniquifier
+	unique := fmt.Sprintf("admincreated%s", suffix)
+
+	// Regular user token → 403 (AdminMiddleware).
+	payload, _ := json.Marshal(map[string]interface{}{
+		"email":    unique + "@tests.bookhoard.internal",
+		"username": unique,
+		"password": "Test@Pass123!",
+	})
+	req, _ := http.NewRequest("POST", s.setup.Server.URL+"/api/auth/users", bytes.NewBuffer(payload))
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("Authorization", "Bearer "+s.setup.RegularToken)
+	resp, err := (&http.Client{}).Do(req)
+	require.NoError(s.T(), err)
+	io.Copy(io.Discard, resp.Body)
+	resp.Body.Close()
+	require.Equal(s.T(), http.StatusForbidden, resp.StatusCode)
+
+	// Admin → 201, and the account is immediately usable (login works)
+	// even though self-service registration is off for new servers.
+	req, _ = http.NewRequest("POST", s.setup.Server.URL+"/api/auth/users", bytes.NewBuffer(payload))
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("Authorization", "Bearer "+s.token)
+	resp, err = (&http.Client{}).Do(req)
+	require.NoError(s.T(), err)
+	defer resp.Body.Close()
+	require.Equal(s.T(), http.StatusCreated, resp.StatusCode)
+	var created map[string]interface{}
+	require.NoError(s.T(), json.NewDecoder(resp.Body).Decode(&created))
+	assert.Equal(s.T(), unique, created["username"])
+	assert.Equal(s.T(), "user", created["role"])
+
+	// New users inherit the system-wide default timezone (this was the
+	// point of the setting; before 2026-10-13 every new user got UTC
+	// regardless of it).
+	expectedTZ := "UTC"
+	var settingTZ string
+	err = s.setup.DBPool.QueryRow(s.setup.QueueCtx,
+		"SELECT setting_value FROM system_settings WHERE setting_key = 'default_timezone'").Scan(&settingTZ)
+	if err == nil {
+		if _, locErr := time.LoadLocation(settingTZ); locErr == nil && settingTZ != "" {
+			expectedTZ = settingTZ
+		}
+	}
+	assert.Equal(s.T(), expectedTZ, created["timezone"],
+		"created user must carry the system default timezone")
+
+	// Duplicate username → 409.
+	req, _ = http.NewRequest("POST", s.setup.Server.URL+"/api/auth/users", bytes.NewBuffer(payload))
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("Authorization", "Bearer "+s.token)
+	resp, err = (&http.Client{}).Do(req)
+	require.NoError(s.T(), err)
+	defer resp.Body.Close()
+	assert.Equal(s.T(), http.StatusConflict, resp.StatusCode)
+
+	// The created user can log in.
+	loginPayload, _ := json.Marshal(map[string]interface{}{
+		"login":    unique + "@tests.bookhoard.internal",
+		"password": "Test@Pass123!",
+	})
+	req, _ = http.NewRequest("POST", s.setup.Server.URL+"/api/auth/login", bytes.NewBuffer(loginPayload))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err = (&http.Client{}).Do(req)
+	require.NoError(s.T(), err)
+	defer resp.Body.Close()
+	assert.Equal(s.T(), http.StatusOK, resp.StatusCode)
+}
+
+// TestDelete_StorageDownRefused pins the NAS guard: deleting a media item
+// while its library storage is unreachable is REFUSED (row + annotations
+// survive) instead of cascading annotations for a file that will re-import
+// bare on the next scan.
+func (s *OwnershipAndAdminTestSuite) TestDelete_StorageDownRefused() {
+	ctx := s.setup.QueueCtx
+	db := s.setup.DB
+
+	libraryTypeRow, err := db.GetLibraryTypeByName(ctx, "ebooks")
+	require.NoError(s.T(), err)
+	admin, err := db.GetUserByEmail(ctx, "testuser@tests.bookhoard.internal")
+	require.NoError(s.T(), err)
+
+	library, err := db.CreateLibrary(ctx, database.CreateLibraryParams{
+		Name:             fmt.Sprintf("Ownership Suite Test Offline %d", time.Now().UnixNano()),
+		Description:      pgtype.Text{String: "storage-down suite", Valid: true},
+		LibraryTypeID:    libraryTypeRow.ID,
+		CreatedByAdminID: admin.ID,
+	})
+	require.NoError(s.T(), err)
+	// Folder row pointing at a mount that does not exist.
+	_, err = db.AddLibraryFolder(ctx, database.AddLibraryFolderParams{
+		LibraryID:  library.ID,
+		FolderPath: "/nonexistent-mount-xyz",
+	})
+	require.NoError(s.T(), err)
+
+	item, err := db.CreateMediaItem(ctx, database.CreateMediaItemParams{
+		LibraryID: library.ID,
+		Title:     "Offline Storage Item",
+		FilePath:  "offline.epub",
+		MimeType:  pgtype.Text{String: "application/epub+zip", Valid: true},
+	})
+	require.NoError(s.T(), err)
+	itemID := uuid.UUID(item.ID.Bytes).String()
+
+	payload, _ := json.Marshal(map[string]interface{}{"media_item_ids": []string{itemID}})
+	req, _ := http.NewRequest("POST", s.setup.Server.URL+"/api/media-items/bulk-delete", bytes.NewBuffer(payload))
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("Authorization", "Bearer "+s.token)
+	resp, err := (&http.Client{}).Do(req)
+	require.NoError(s.T(), err)
+	defer resp.Body.Close()
+	require.Equal(s.T(), http.StatusOK, resp.StatusCode, "bulk endpoint answers 200 with per-item errors")
+
+	var body map[string]interface{}
+	require.NoError(s.T(), json.NewDecoder(resp.Body).Decode(&body))
+	results := body["results"].([]interface{})
+	require.Len(s.T(), results, 1)
+	first := results[0].(map[string]interface{})
+	assert.Contains(s.T(), first["error"], "storage unreachable")
+
+	// The row survived the refused delete.
+	check, err := db.GetMediaItem(ctx, item.ID)
+	require.NoError(s.T(), err)
+	assert.Equal(s.T(), "Offline Storage Item", check.Title)
+}
+
+func TestOwnershipAndAdminTestSuite(t *testing.T) {
+	suite.Run(t, new(OwnershipAndAdminTestSuite))
+}

cmd/server/tests/processing_issues_test.go

@@ -16,8 +16,7 @@ func TestProcessingIssuesListAuthentication(t *testing.T) {
 	setup := setupTestServer(t)
 
 	// Create a test library
-	deviceSetup := setupDeviceTest(t)
-	libraryID := deviceSetup.CreateLibrary(t, "Test Auth Library", "manga")
+	libraryID := createLibraryDirect(t, setup.DB, getTestUserID(t, setup.DB), "Test Auth Library", "manga")
 
 	t.Run("GET /api/libraries/:id/issues/list - No authentication", func(t *testing.T) {
 		req := httptest.NewRequest("GET", "/api/libraries/"+libraryID+"/issues/list", nil)
@@ -55,8 +54,7 @@ func TestProcessingIssuesListResponseStructure(t *testing.T) {
 	setup := setupTestServer(t)
 
 	// Create a test library
-	deviceSetup := setupDeviceTest(t)
-	libraryID := deviceSetup.CreateLibrary(t, "Test Structure Library", "comics")
+	libraryID := createLibraryDirect(t, setup.DB, getTestUserID(t, setup.DB), "Test Structure Library", "comics")
 
 	t.Run("Returns JSON array for empty library", func(t *testing.T) {
 		token := setup.Token
@@ -163,8 +161,7 @@ func TestProcessingIssueStatsAuthentication(t *testing.T) {
 	setup := setupTestServer(t)
 
 	// Create a test library
-	deviceSetup := setupDeviceTest(t)
-	libraryID := deviceSetup.CreateLibrary(t, "Test Stats Auth Library", "manga")
+	libraryID := createLibraryDirect(t, setup.DB, getTestUserID(t, setup.DB), "Test Stats Auth Library", "manga")
 
 	t.Run("GET /api/libraries/:id/issues/stats - No authentication", func(t *testing.T) {
 		req := httptest.NewRequest("GET", "/api/libraries/"+libraryID+"/issues/stats", nil)
@@ -202,8 +199,7 @@ func TestProcessingIssueStatsResponseStructure(t *testing.T) {
 	setup := setupTestServer(t)
 
 	// Create a test library
-	deviceSetup := setupDeviceTest(t)
-	libraryID := deviceSetup.CreateLibrary(t, "Test Stats Structure Library", "comics")
+	libraryID := createLibraryDirect(t, setup.DB, getTestUserID(t, setup.DB), "Test Stats Structure Library", "comics")
 
 	t.Run("Returns correct structure for empty library", func(t *testing.T) {
 		token := setup.Token
@@ -343,11 +339,9 @@ func TestProcessingIssuesCrossLibraryIsolation(t *testing.T) {
 	setup := setupTestServer(t)
 
 	// Create two different libraries with different types
-	deviceSetup1 := setupDeviceTest(t)
-	library1ID := deviceSetup1.CreateLibrary(t, "Isolation Test Library 1", "manga")
+	library1ID := createLibraryDirect(t, setup.DB, getTestUserID(t, setup.DB), "Isolation Test Library 1", "manga")
 
-	deviceSetup2 := setupDeviceTest(t)
-	library2ID := deviceSetup2.CreateLibrary(t, "Isolation Test Library 2", "comics")
+	library2ID := createLibraryDirect(t, setup.DB, getTestUserID(t, setup.DB), "Isolation Test Library 2", "comics")
 
 	token := setup.Token
 
@@ -431,8 +425,7 @@ func TestProcessingIssuesDifferentLibraryTypes(t *testing.T) {
 
 	for _, lt := range libraryTypes {
 		t.Run(lt.name+" - list endpoint works", func(t *testing.T) {
-			deviceSetup := setupDeviceTest(t)
-			libraryID := deviceSetup.CreateLibrary(t, "Test "+lt.name, lt.libraryType)
+			libraryID := createLibraryDirect(t, setup.DB, getTestUserID(t, setup.DB), "Test "+lt.name, lt.libraryType)
 
 			req := httptest.NewRequest("GET", "/api/libraries/"+libraryID+"/issues/list", nil)
 			req.Header.Set("Authorization", "Bearer "+token)
@@ -448,8 +441,7 @@ func TestProcessingIssuesDifferentLibraryTypes(t *testing.T) {
 		})
 
 		t.Run(lt.name+" - stats endpoint works", func(t *testing.T) {
-			deviceSetup := setupDeviceTest(t)
-			libraryID := deviceSetup.CreateLibrary(t, "Test "+lt.name, lt.libraryType)
+			libraryID := createLibraryDirect(t, setup.DB, getTestUserID(t, setup.DB), "Test "+lt.name, lt.libraryType)
 
 			req := httptest.NewRequest("GET", "/api/libraries/"+libraryID+"/issues/stats", nil)
 			req.Header.Set("Authorization", "Bearer "+token)
@@ -474,8 +466,7 @@ func TestProcessingIssuesInvalidTokens(t *testing.T) {
 	setup := setupTestServer(t)
 
 	// Create a test library
-	deviceSetup := setupDeviceTest(t)
-	libraryID := deviceSetup.CreateLibrary(t, "Test Token Library", "ebooks")
+	libraryID := createLibraryDirect(t, setup.DB, getTestUserID(t, setup.DB), "Test Token Library", "ebooks")
 
 	t.Run("List endpoint rejects invalid token", func(t *testing.T) {
 		req := httptest.NewRequest("GET", "/api/libraries/"+libraryID+"/issues/list", nil)

cmd/server/tests/progress_service_test.go

@@ -656,3 +656,182 @@ func TestProgressWeb_EdgeCases(t *testing.T) {
 		assert.InDelta(t, 1.5, progress.ZoomLevel.Float64, 0.01)
 	})
 }
+
+// TestDeletedUserTokenRejected pins the ghost-session guard: a
+// signature-valid JWT for a user that has been DELETED must stop
+// authenticating (401 user_not_found), not serve a phantom session.
+// Before the guard, deleted users kept full API access until token
+// expiry (observed live on hardware 2026-10-09).
+func TestDeletedUserTokenRejected(t *testing.T) {
+	setup := setupTestServer(t)
+	ctx := context.Background()
+
+	// Create a dedicated user, then log in as it to get a fresh token.
+	// Admin-created (not self-registered) so the test stays deterministic
+	// regardless of the registration_enabled setting.
+	createResp := doReq(t, "POST", setup.Server.URL+"/api/auth/users", map[string]interface{}{
+		"email":    "ghost-test@tests.bookhoard.internal",
+		"username": "ghosttest",
+		"password": "Ghost@Pass123!",
+	}, setup.Token)
+	defer createResp.Body.Close()
+	if createResp.StatusCode != http.StatusCreated {
+		t.Skipf("admin user creation unavailable (status %d)", createResp.StatusCode)
+	}
+
+	loginResp := doReq(t, "POST", setup.Server.URL+"/api/auth/login", map[string]interface{}{
+		"login":    "ghost-test@tests.bookhoard.internal",
+		"password": "Ghost@Pass123!",
+	}, "")
+	defer loginResp.Body.Close()
+	require.Equal(t, http.StatusOK, loginResp.StatusCode)
+	var loginBody struct {
+		AccessToken string `json:"access_token"`
+	}
+	require.NoError(t, json.NewDecoder(loginResp.Body).Decode(&loginBody))
+	require.NotEmpty(t, loginBody.AccessToken)
+
+	ghostToken := loginBody.AccessToken
+
+	// Sanity: the token works while the user exists (user-scoped endpoint
+	// a freshly-registered regular user can access).
+	okResp := doReq(t, "GET", setup.Server.URL+"/api/collections", nil, ghostToken)
+	defer okResp.Body.Close()
+	require.Equal(t, http.StatusOK, okResp.StatusCode, "token must work while the user exists")
+
+	// Delete the user directly via the DB for determinism (same query the
+	// suite's own cleanup uses).
+	ghostID := ""
+	users, err := setup.DB.ListUsers(ctx)
+	require.NoError(t, err)
+	for _, u := range users {
+		if u.Email == "ghost-test@tests.bookhoard.internal" {
+			ghostID = uuid.UUID(u.ID.Bytes).String()
+			require.NoError(t, setup.DB.DeleteUser(ctx, u.ID))
+		}
+	}
+	require.NotEmpty(t, ghostID, "ghost user row must exist before deletion")
+
+	// The same token must now be rejected with 401 user_not_found.
+	resp := doReq(t, "GET", setup.Server.URL+"/api/collections", nil, ghostToken)
+	defer resp.Body.Close()
+	assert.Equal(t, http.StatusUnauthorized, resp.StatusCode, "ghost token must be rejected")
+
+	var errBody map[string]string
+	require.NoError(t, json.NewDecoder(resp.Body).Decode(&errBody))
+	assert.Contains(t, errBody["message"], "user_not_found")
+}
+
+// TestProgressWeb_LocatorCoherence pins the locator coherence rule: a
+// percentage-only write that DECLARES no locator (ClearLocator) must clear
+// any inherited stale anchor instead of re-pairing the new percentage with
+// the previous writer's CFI/context — the incoherent row shape that fed the
+// client-side far-anchor restore floor. Request-carried fields always win.
+func TestProgressWeb_LocatorCoherence(t *testing.T) {
+	setup := setupTestServer(t)
+	ctx := context.Background()
+	userID := getTestUserID(t, setup.DB)
+	pgUserID := pgtype.UUID{Bytes: userID, Valid: true}
+
+	seedAnchor := func(t *testing.T, mediaItemID string) uuid.UUID {
+		mediaUUID, _ := uuid.Parse(mediaItemID)
+		_, err := setup.ProgressService.SaveProgress(ctx, wsync.SaveProgressRequest{
+			MediaItemID: pgtype.UUID{Bytes: mediaUUID, Valid: true},
+			UserID:      pgUserID,
+			Source:      "web",
+			Percentage:  pFloat64(0.3),
+			Epubcfi:     pStr("epubcfi(/6/4/2:first)"),
+			ContextText: pStr("some anchor context sentence"),
+			DeviceType:  "web",
+			Broadcast:   false,
+		})
+		require.NoError(t, err)
+		progress, err := setup.DB.GetReadingProgress(ctx, database.GetReadingProgressParams{
+			MediaItemID: pgtype.UUID{Bytes: mediaUUID, Valid: true},
+			UserID:      pgUserID,
+		})
+		require.NoError(t, err)
+		require.True(t, progress.Epubcfi.Valid, "seed: anchor stored")
+		return mediaUUID
+	}
+
+	t.Run("percentage-only kobo write clears the inherited anchor", func(t *testing.T) {
+		mediaItemID := createTestMediaItemID(t, setup)
+		mediaUUID := seedAnchor(t, mediaItemID)
+
+		_, err := setup.ProgressService.SaveProgress(ctx, wsync.SaveProgressRequest{
+			MediaItemID:  pgtype.UUID{Bytes: mediaUUID, Valid: true},
+			UserID:       pgUserID,
+			Source:       "kobo",
+			Percentage:   pFloat64(0.6),
+			DeviceType:   "kobo",
+			ClearLocator: true,
+			Broadcast:    false,
+		})
+		require.NoError(t, err)
+
+		progress, err := setup.DB.GetReadingProgress(ctx, database.GetReadingProgressParams{
+			MediaItemID: pgtype.UUID{Bytes: mediaUUID, Valid: true},
+			UserID:      pgUserID,
+		})
+		require.NoError(t, err)
+		assert.InDelta(t, 0.6, progress.Percentage.Float64, 0.001, "percentage updated")
+		assert.False(t, progress.Epubcfi.Valid, "stale anchor cleared, not re-paired")
+		assert.False(t, progress.ContextText.Valid, "stale context cleared")
+		assert.Equal(t, "kobo", progress.LastSyncSource.String)
+	})
+
+	t.Run("request-carried context survives the clear", func(t *testing.T) {
+		mediaItemID := createTestMediaItemID(t, setup)
+		mediaUUID := seedAnchor(t, mediaItemID)
+
+		_, err := setup.ProgressService.SaveProgress(ctx, wsync.SaveProgressRequest{
+			MediaItemID:  pgtype.UUID{Bytes: mediaUUID, Valid: true},
+			UserID:       pgUserID,
+			Source:       "koreader",
+			Percentage:   pFloat64(0.7),
+			ContextText:  pStr("a brand new context sentence"),
+			DeviceType:   "koreader",
+			ClearLocator: true,
+			Broadcast:    false,
+		})
+		require.NoError(t, err)
+
+		progress, err := setup.DB.GetReadingProgress(ctx, database.GetReadingProgressParams{
+			MediaItemID: pgtype.UUID{Bytes: mediaUUID, Valid: true},
+			UserID:      pgUserID,
+		})
+		require.NoError(t, err)
+		assert.InDelta(t, 0.7, progress.Percentage.Float64, 0.001)
+		assert.True(t, progress.ContextText.Valid, "request-carried context kept")
+		assert.Equal(t, "a brand new context sentence", progress.ContextText.String)
+		// The verify gate is inert in the test harness (no media path
+		// resolver wired), so no anchor can be minted here; the rule
+		// under test is that the STALE one is gone.
+		assert.False(t, progress.Epubcfi.Valid, "stale anchor cleared")
+	})
+
+	t.Run("HTTP merge semantics untouched: key-absent PUT preserves fields", func(t *testing.T) {
+		mediaItemID := createTestMediaItemID(t, setup)
+		mediaUUID := seedAnchor(t, mediaItemID)
+
+		// Service-level save WITHOUT ClearLocator mimics the HTTP merge
+		// path (field absent = inherit): the anchor must survive.
+		_, err := setup.ProgressService.SaveProgress(ctx, wsync.SaveProgressRequest{
+			MediaItemID: pgtype.UUID{Bytes: mediaUUID, Valid: true},
+			UserID:      pgUserID,
+			Source:      "queue",
+			Percentage:  pFloat64(0.4),
+			Broadcast:   false,
+		})
+		require.NoError(t, err)
+
+		progress, err := setup.DB.GetReadingProgress(ctx, database.GetReadingProgressParams{
+			MediaItemID: pgtype.UUID{Bytes: mediaUUID, Valid: true},
+			UserID:      pgUserID,
+		})
+		require.NoError(t, err)
+		assert.True(t, progress.Epubcfi.Valid, "merge path preserves the anchor")
+		assert.Equal(t, "epubcfi(/6/4/2:first)", progress.Epubcfi.String)
+	})
+}

cmd/server/tests/schema_idempotency_test.go

@@ -0,0 +1,53 @@
+package main
+
+import (
+	"context"
+	"testing"
+
+	"bookhoard/internal/config"
+	"bookhoard/internal/database"
+
+	"github.com/jackc/pgx/v5/pgxpool"
+	"github.com/stretchr/testify/require"
+)
+
+// TestSchemaInitializationIsIdempotent replays the application's production
+// schema initializer twice against the same database. schema.sql runs on
+// EVERY app startup, so it must apply cleanly to a database where a previous
+// startup already applied it. A regression here crash-loops the production
+// container on its second boot (e.g. SQLSTATE 2BP01: DROP FUNCTION refused
+// while a trigger created by the previous run still references it).
+//
+// Uses a dedicated pool: production Initialize holds the advisory lock on one
+// connection while executing the schema on another, but the shared test pool
+// is capped at MaxConns=1 and would deadlock.
+func TestSchemaInitializationIsIdempotent(t *testing.T) {
+	if testing.Short() {
+		t.Skip("skipping schema re-initialization in -short mode")
+	}
+
+	// Bring up the standard test environment (seeds users, starts server).
+	setup := setupTestServer(t)
+	defer func() { _ = setup.Close() }()
+
+	// Dedicated pool with default connection limits for the initializer.
+	poolCfg, err := pgxpool.ParseConfig(config.LoadConfig().DatabaseURL())
+	require.NoError(t, err, "failed to parse database URL")
+	pool, err := pgxpool.NewWithConfig(context.Background(), poolCfg)
+	require.NoError(t, err, "failed to connect for schema initialization test")
+	defer func() { pool.Close() }()
+
+	ctx := context.Background()
+
+	// First boot: applies the schema to the (possibly fresh) database.
+	if err := database.Initialize(ctx, pool); err != nil {
+		t.Fatalf("first schema initialization failed: %v", err)
+	}
+
+	// Second boot against the now-initialized database: this is exactly
+	// where non-idempotent statements (bare CREATE TRIGGER, DROP FUNCTION
+	// with dependent objects, etc.) blow up.
+	if err := database.Initialize(ctx, pool); err != nil {
+		t.Fatalf("second schema initialization failed: %v — schema.sql must stay idempotent across restarts", err)
+	}
+}

cmd/server/tests/search_test.go

@@ -384,12 +384,12 @@ func TestCollectionSearchLibraryFilter(t *testing.T) {
 	book2ID := createTestMediaItemIDInLibrary(t, client, setup, lib2Resp["id"].(string), "Harry Potter 2")
 
 	tests := []struct {
-		name          string
-		query         string
-		libraryID     string
-		expectedCount int
+		name           string
+		query          string
+		libraryID      string
+		expectedCount  int
 		expectedStatus int
-		shouldContain string // Comma-separated list of book IDs to check
+		shouldContain  string // Comma-separated list of book IDs to check
 	}{
 		{
 			name:          "no filter - both test books present",

cmd/server/tests/search_unified_test.go

@@ -6,6 +6,7 @@ import (
 	"io"
 	"net/http"
 	"net/http/httptest"
+	"strings"
 	"testing"
 
 	"github.com/stretchr/testify/assert"
@@ -34,15 +35,19 @@ func TestUnifiedSearch(t *testing.T) {
 	_ = folderResp.Body.Close()
 	require.Equal(t, http.StatusCreated, folderResp.StatusCode)
 
-	// Helper to create book with fields
+	// Helper to create book with fields. Unique file_path per book: the
+	// create endpoint answers 200/duplicate for a repeated
+	// (library_id, file_path), and the old shared constant made the 2nd/3rd
+	// creates no-ops anyway.
 	createBook := func(title, author, genre string, year int, hasCover bool) {
+		slug := strings.ReplaceAll(strings.ToLower(title), " ", "-")
 		bookReq := map[string]interface{}{
 			"library_id":     libraryID,
 			"title":          title,
 			"author":         author,
 			"genre":          genre,
 			"copyright_year": year,
-			"file_path":      "/tmp/test.epub",
+			"file_path":      "/tmp/" + slug + ".epub",
 			"file_size":      1024,
 			"mime_type":      "application/epub+zip",
 		}

cmd/server/tests/series_integration_test.go

@@ -32,6 +32,11 @@ func (s *SeriesIntegrationTestSuite) TearDownSuite() {
 }
 
 func (s *SeriesIntegrationTestSuite) TestGetSeries_RequiresLibraryID() {
+	// Ground truth (2026-10-13 visibility hardening): library_id stays
+	// optional, but the unscoped aggregate now covers only the requester's
+	// VISIBLE libraries — hidden libraries contribute nothing. Series are
+	// grouped per library (same name in two libraries = two entries), so
+	// every row carries a library_id.
 	req, _ := http.NewRequest("GET", s.setup.Server.URL+"/api/series", nil)
 	req.Header.Set("Authorization", "Bearer "+s.token)
 
@@ -42,12 +47,20 @@ func (s *SeriesIntegrationTestSuite) TestGetSeries_RequiresLibraryID() {
 		_ = Body.Close()
 	}(resp.Body)
 
-	assert.Equal(s.T(), http.StatusBadRequest, resp.StatusCode)
+	assert.Equal(s.T(), http.StatusOK, resp.StatusCode)
 
-	var body map[string]string
+	var body map[string]interface{}
 	err = json.NewDecoder(resp.Body).Decode(&body)
 	require.NoError(s.T(), err)
-	assert.Equal(s.T(), "library_id required", body["error"])
+	assert.Contains(s.T(), body, "series", "response carries the series array")
+	assert.Contains(s.T(), body, "total")
+	if rows, ok := body["series"].([]interface{}); ok {
+		for _, r := range rows {
+			row, ok := r.(map[string]interface{})
+			require.True(s.T(), ok)
+			assert.NotEmpty(s.T(), row["library_id"], "series rows carry their library scope")
+		}
+	}
 }
 
 func (s *SeriesIntegrationTestSuite) TestGetSeries_InvalidLibraryID() {
@@ -159,7 +172,13 @@ func (s *SeriesIntegrationTestSuite) TestGetSeries_LimitClampedTo100() {
 	assert.Equal(s.T(), float64(100), limit, "limit should be clamped to 100")
 }
 
-func (s *SeriesIntegrationTestSuite) TestGetSeriesBooks_RequiresLibraryID() {
+func (s *SeriesIntegrationTestSuite) TestGetSeriesBooks_LibraryIDRequired() {
+	// Ground truth (2026-10-13 visibility hardening): /api/series/books is
+	// per-library now — library_id is REQUIRED, validated, and must be
+	// visible to the requester. The former name-only contract let any
+	// authenticated account pull series books across ALL libraries
+	// (including hidden ones), and merged same-name series across
+	// libraries (manga adaptations / LN splits).
 	req, _ := http.NewRequest("GET", s.setup.Server.URL+"/api/series/books?name=Test+Series", nil)
 	req.Header.Set("Authorization", "Bearer "+s.token)
 
@@ -199,6 +218,7 @@ func (s *SeriesIntegrationTestSuite) TestGetSeriesBooks_RequiresName() {
 }
 
 func (s *SeriesIntegrationTestSuite) TestGetSeriesBooks_InvalidLibraryID() {
+	// library_id is now validated: an unparseable uuid is a 400.
 	req, _ := http.NewRequest("GET", s.setup.Server.URL+"/api/series/books?library_id=bad-uuid&name=Test", nil)
 	req.Header.Set("Authorization", "Bearer "+s.token)
 
@@ -296,6 +316,83 @@ func (s *SeriesIntegrationTestSuite) TestGetSeries_ResponseStructure() {
 	assert.True(s.T(), ok, "'series' should be an array")
 }
 
+func (s *SeriesIntegrationTestSuite) setLibraryVisibility(token, libraryID string, visible bool) *http.Response {
+	payload, _ := json.Marshal(map[string]interface{}{
+		"library_id": libraryID,
+		"is_visible": visible,
+	})
+	req, _ := http.NewRequest("POST", s.setup.Server.URL+"/api/libraries/visibility", bytes.NewBuffer(payload))
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("Authorization", "Bearer "+token)
+	resp, err := (&http.Client{}).Do(req)
+	require.NoError(s.T(), err)
+	return resp
+}
+
+// TestGetSeries_HiddenLibraryScopedOut pins the family-lens contract: a
+// library hidden from a user contributes NOTHING to that user's series
+// views, and naming it explicitly is a 403, not a silent pass — across
+// /api/series, /api/series/books, and /api/media-items.
+func (s *SeriesIntegrationTestSuite) TestGetSeries_HiddenLibraryScopedOut() {
+	regular := s.setup.RegularToken
+
+	// Baseline: the regular user can see the suite library.
+	resp := s.setLibraryVisibility(regular, s.libraryID, true)
+	defer resp.Body.Close()
+	require.Equal(s.T(), http.StatusOK, resp.StatusCode)
+
+	// Hide it from the regular user.
+	resp = s.setLibraryVisibility(regular, s.libraryID, false)
+	require.Equal(s.T(), http.StatusOK, resp.StatusCode)
+	defer func() {
+		r := s.setLibraryVisibility(regular, s.libraryID, true)
+		_ = r.Body.Close()
+	}()
+
+	client := &http.Client{}
+
+	// Explicit hidden library → 403.
+	for _, path := range []string{
+		"/api/series?library_id=" + s.libraryID,
+		"/api/series/books?library_id=" + s.libraryID + "&name=Test",
+		"/api/media-items?library_id=" + s.libraryID,
+	} {
+		req, _ := http.NewRequest("GET", s.setup.Server.URL+path, nil)
+		req.Header.Set("Authorization", "Bearer "+regular)
+		r, err := client.Do(req)
+		require.NoError(s.T(), err)
+		body, _ := io.ReadAll(r.Body)
+		r.Body.Close()
+		require.Equalf(s.T(), http.StatusForbidden, r.StatusCode, "%s must be 403 for a hidden library (body: %s)", path, body)
+	}
+
+	// Unscoped aggregate: the hidden library's series never appear.
+	req, _ := http.NewRequest("GET", s.setup.Server.URL+"/api/series", nil)
+	req.Header.Set("Authorization", "Bearer "+regular)
+	r, err := client.Do(req)
+	require.NoError(s.T(), err)
+	defer r.Body.Close()
+	require.Equal(s.T(), http.StatusOK, r.StatusCode)
+	var body map[string]interface{}
+	require.NoError(s.T(), json.NewDecoder(r.Body).Decode(&body))
+	if rows, ok := body["series"].([]interface{}); ok {
+		for _, row := range rows {
+			m, ok := row.(map[string]interface{})
+			require.True(s.T(), ok)
+			assert.NotEqual(s.T(), s.libraryID, m["library_id"], "hidden library must not appear in the aggregate")
+		}
+	}
+
+	// The admin still sees the library (default-allow; visibility rows are
+	// per-user).
+	req, _ = http.NewRequest("GET", s.setup.Server.URL+"/api/series?library_id="+s.libraryID, nil)
+	req.Header.Set("Authorization", "Bearer "+s.token)
+	r, err = client.Do(req)
+	require.NoError(s.T(), err)
+	defer r.Body.Close()
+	assert.Equal(s.T(), http.StatusOK, r.StatusCode)
+}
+
 func (s *SeriesIntegrationTestSuite) TestRestoreSystemCollection_ContinueSeries() {
 	reqBody := map[string]interface{}{
 		"collection_name": "Continue Series",
@@ -349,11 +446,17 @@ func (s *SeriesIntegrationTestSuite) TestGetSections_IncludesContinueSeries() {
 		sectionIDs[section["id"].(string)] = true
 	}
 
-	assert.Contains(s.T(), sectionIDs, "continue-series", "dashboard should include continue-series section")
-	assert.Contains(s.T(), sectionIDs, "continue-reading")
-	assert.Contains(s.T(), sectionIDs, "recently-added")
-	assert.Contains(s.T(), sectionIDs, "recently-read")
-	assert.Contains(s.T(), sectionIDs, "not-started")
+	// Ground truth: the /sections contract keys a section's identity on
+	// the collection NAME — BuildSections sets ID = CollectionName, and
+	// the web/app reorder + hidden-collection preferences persist those
+	// same strings (data-collection-id). The kebab "query_type"
+	// ("continue-series" etc.) is the STORAGE key for system collections
+	// and is not exposed on this endpoint.
+	assert.Contains(s.T(), sectionIDs, "Continue Series", "dashboard should include Continue Series")
+	assert.Contains(s.T(), sectionIDs, "Continue Reading")
+	assert.Contains(s.T(), sectionIDs, "Recently Added")
+	assert.Contains(s.T(), sectionIDs, "Recently Read")
+	assert.Contains(s.T(), sectionIDs, "Not Started")
 }
 
 func TestSeriesIntegrationTestSuite(t *testing.T) {

cmd/server/tests/statistics_test.go

@@ -0,0 +1,519 @@
+package main
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"testing"
+	"time"
+
+	"github.com/google/uuid"
+	"github.com/jackc/pgx/v5/pgtype"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"bookhoard/internal/database"
+)
+
+// Reading-statistics coverage: session CAPTURE at the sync chokepoint,
+// the summary aggregation (tz buckets, streaks, finished detection),
+// range validation, the widget, and the per-book card.
+//
+// All seeded instants anchor to USER-TZ midnights (the test user is UTC)
+// so day buckets are deterministic regardless of when the suite runs.
+
+func pgUser(id uuid.UUID) pgtype.UUID { return pgtype.UUID{Bytes: [16]byte(id), Valid: true} }
+func pgFloat(v float64) pgtype.Float8 { return pgtype.Float8{Float64: v, Valid: true} }
+func pgInt4(v int32) pgtype.Int4      { return pgtype.Int4{Int32: v, Valid: true} }
+func pgTS(v time.Time) pgtype.Timestamptz {
+	return pgtype.Timestamptz{Time: v, Valid: !v.IsZero()}
+}
+
+// middayDaysAgo returns noon UTC N calendar days before today — a
+// bucket-stable instant for any wall-clock time the suite runs at.
+func middayDaysAgo(daysAgo int) time.Time {
+	midnight := time.Now().UTC()
+	midnight = time.Date(midnight.Year(), midnight.Month(), midnight.Day(), 0, 0, 0, 0, time.UTC)
+	return midnight.AddDate(0, 0, -daysAgo).Add(12 * time.Hour)
+}
+
+func statsLogin(t *testing.T, setup *TestServerSetup, token, path string) (*http.Response, []byte) {
+	t.Helper()
+	req, _ := http.NewRequest("GET", setup.Server.URL+path, nil)
+	req.Header.Set("Authorization", "Bearer "+token)
+	resp, err := http.DefaultClient.Do(req)
+	require.NoError(t, err)
+	defer func() {
+		_ = resp.Body.Close()
+		t.Setenv("STATS_LAST_BODY_PATH", path) // no-op; keeps body-close ordering explicit
+	}()
+	body, err := io.ReadAll(resp.Body)
+	require.NoError(t, err)
+	return resp, body
+}
+
+func TestReadingStatsCapture(t *testing.T) {
+	setup := setupTestServer(t)
+	userID := getTestUserID(t, setup.DB)
+	ctx := context.Background()
+
+	bookID := createTestMediaItemID(t, setup)
+
+	push := func(body map[string]interface{}) int {
+		payload, _ := json.Marshal(body)
+		req, _ := http.NewRequest("PUT", setup.Server.URL+"/api/media-items/"+bookID+"/progress", bytes.NewBuffer(payload))
+		req.Header.Set("Content-Type", "application/json")
+		req.Header.Set("Authorization", "Bearer "+setup.Token)
+		resp, err := http.DefaultClient.Do(req)
+		require.NoError(t, err)
+		defer func() { _ = resp.Body.Close() }()
+		return resp.StatusCode
+	}
+
+	require.Equal(t, http.StatusOK, push(map[string]interface{}{
+		"percentage": 0.10, "current_page": 10, "total_pages": 100,
+	}))
+
+	time.Sleep(1100 * time.Millisecond) // the second push derives a ~1s span
+
+	require.Equal(t, http.StatusOK, push(map[string]interface{}{
+		"percentage": 0.15, "current_page": 15, "total_pages": 100,
+	}))
+
+	rows, err := setup.DB.GetBookReadingSessions(ctx, database.GetBookReadingSessionsParams{
+		UserID:      pgUser(userID),
+		MediaItemID: uuidToPGType(uuid.MustParse(bookID)),
+	})
+	require.NoError(t, err)
+	require.Len(t, rows, 2, "each push records one session row")
+
+	first := rows[0]
+	assert.Equal(t, int32(0), first.TimeSpentSeconds.Int32, "first contact: marker with zero time")
+	assert.InEpsilon(t, 0.10, first.ProgressPercentage.Float64, 0.001)
+
+	second := rows[1]
+	assert.GreaterOrEqual(t, second.TimeSpentSeconds.Int32, int32(1), "the ~1.1s gap is attributed")
+	assert.LessOrEqual(t, second.TimeSpentSeconds.Int32, int32(10), "and bounded by the slept interval")
+	require.True(t, second.PagesRead.Valid, "page info was carried on both pushes")
+	assert.Equal(t, int32(5), second.PagesRead.Int32, "pages: 15 − 10")
+
+	progress, err := setup.DB.GetReadingProgress(ctx, database.GetReadingProgressParams{
+		MediaItemID: uuidToPGType(uuid.MustParse(bookID)),
+		UserID:      pgUser(userID),
+	})
+	require.NoError(t, err)
+	assert.InEpsilon(t, 0.15, progress.Percentage.Float64, 0.001, "capture never disturbs stored position")
+}
+
+func TestReadingStatsDeviceAttribution(t *testing.T) {
+	setup := setupTestServer(t)
+	userID := getTestUserID(t, setup.DB)
+	ctx := context.Background()
+
+	bookID := createTestMediaItemID(t, setup)
+
+	// A registered device owned by the test user, plus one owned by a
+	// DIFFERENT user (the foreign token must be ignored, never sent).
+	device, err := setup.DB.CreateDevice(ctx, database.CreateDeviceParams{
+		UserID:               pgUser(userID),
+		DeviceName:           "Pixel 9 Test",
+		DeviceType:           "mobile",
+		DeviceIdentifier:     "stats-test-android-" + uuid.NewString(),
+		AuthToken:            "dev_test_token_" + uuid.NewString(),
+		SyncEnabled:          pgtype.Bool{Bool: true, Valid: true},
+		AutoSync:             pgtype.Bool{Bool: true, Valid: true},
+		SyncFrequencyMinutes: pgtype.Int4{Int32: 5, Valid: true},
+		DeviceMetadata:       []byte("{}"),
+	})
+	require.NoError(t, err)
+	t.Cleanup(func() { _ = setup.DB.DeleteDevice(ctx, device.ID) })
+
+	otherUser := getRegularUserID(t, setup.DB)
+	foreign, err := setup.DB.CreateDevice(ctx, database.CreateDeviceParams{
+		UserID:               pgUser(otherUser),
+		DeviceName:           "Foreign Device",
+		DeviceType:           "mobile",
+		DeviceIdentifier:     "stats-test-foreign-" + uuid.NewString(),
+		AuthToken:            "dev_foreign_token_" + uuid.NewString(),
+		SyncEnabled:          pgtype.Bool{Bool: true, Valid: true},
+		AutoSync:             pgtype.Bool{Bool: true, Valid: true},
+		SyncFrequencyMinutes: pgtype.Int4{Int32: 5, Valid: true},
+		DeviceMetadata:       []byte("{}"),
+	})
+	require.NoError(t, err)
+	t.Cleanup(func() { _ = setup.DB.DeleteDevice(ctx, foreign.ID) })
+
+	push := func(body map[string]interface{}, deviceToken string) int {
+		payload, _ := json.Marshal(body)
+		req, _ := http.NewRequest("PUT", setup.Server.URL+"/api/media-items/"+bookID+"/progress", bytes.NewBuffer(payload))
+		req.Header.Set("Content-Type", "application/json")
+		req.Header.Set("Authorization", "Bearer "+setup.Token)
+		if deviceToken != "" {
+			req.Header.Set("X-Device-Token", deviceToken)
+		}
+		resp, err := http.DefaultClient.Do(req)
+		require.NoError(t, err)
+		defer func() { _ = resp.Body.Close() }()
+		return resp.StatusCode
+	}
+
+	// Registered device push → attributed to the device with its name.
+	require.Equal(t, http.StatusOK, push(map[string]interface{}{
+		"percentage": 0.10, "current_page": 10, "total_pages": 100,
+	}, device.AuthToken))
+
+	rows, err := setup.DB.GetBookReadingSessions(ctx, database.GetBookReadingSessionsParams{
+		UserID:      pgUser(userID),
+		MediaItemID: uuidToPGType(uuid.MustParse(bookID)),
+	})
+	require.NoError(t, err)
+	require.Len(t, rows, 1)
+	require.True(t, rows[0].DeviceID.Valid)
+	assert.Equal(t, uuid.UUID(device.ID.Bytes).String(), uuid.UUID(rows[0].DeviceID.Bytes).String())
+	var meta struct {
+		Source string `json:"source"`
+	}
+	require.NoError(t, json.Unmarshal(rows[0].DeviceMetadata, &meta))
+	assert.Equal(t, "Pixel 9 Test", meta.Source, "capture metadata carries the registered device name")
+
+	progress, err := setup.DB.GetReadingProgress(ctx, database.GetReadingProgressParams{
+		MediaItemID: uuidToPGType(uuid.MustParse(bookID)),
+		UserID:      pgUser(userID),
+	})
+	require.NoError(t, err)
+	assert.Equal(t, "Pixel 9 Test", progress.LastSyncSource.String, "last-sync surface shows the device name")
+
+	// Foreign device token → soft-fails: unattributed, plain web source.
+	require.Equal(t, http.StatusOK, push(map[string]interface{}{
+		"percentage": 0.20, "current_page": 20, "total_pages": 100,
+	}, "dev_foreign_token_"+uuid.NewString() /* nonexistent token */))
+
+	// A REAL foreign token must also be ignored, not adopted.
+	require.Equal(t, http.StatusOK, push(map[string]interface{}{
+		"percentage": 0.25, "current_page": 25, "total_pages": 100,
+	}, foreign.AuthToken))
+
+	rows, err = setup.DB.GetBookReadingSessions(ctx, database.GetBookReadingSessionsParams{
+		UserID:      pgUser(userID),
+		MediaItemID: uuidToPGType(uuid.MustParse(bookID)),
+	})
+	require.NoError(t, err)
+	require.Len(t, rows, 3)
+	for _, row := range rows[1:] {
+		assert.False(t, row.DeviceID.Valid, "invalid/foreign tokens never attribute a device")
+		require.NoError(t, json.Unmarshal(row.DeviceMetadata, &meta))
+		assert.Equal(t, "web", meta.Source)
+	}
+	progress, err = setup.DB.GetReadingProgress(ctx, database.GetReadingProgressParams{
+		MediaItemID: uuidToPGType(uuid.MustParse(bookID)),
+		UserID:      pgUser(userID),
+	})
+	require.NoError(t, err)
+	assert.Equal(t, "web", progress.LastSyncSource.String)
+}
+
+func TestReadingStatsSummary(t *testing.T) {
+
+	setup := setupTestServer(t)
+	// The REGULAR test user, deliberately: the shared dev DB carries a
+	// live reader on `testuser` (the dev account genuinely reads while
+	// the suite runs), and exact-total assertions cannot share an
+	// account with reality. The fresh regular user has no live pushes.
+	userID := getRegularUserID(t, setup.DB)
+	ctx := context.Context(context.Background())
+
+	libIDStr := createLibraryDirect(t, setup.DB, userID, fmt.Sprintf("Test Stats Library %d", time.Now().UnixNano()), "ebooks")
+	libUUID := uuid.MustParse(libIDStr)
+
+	var finishedBookID, offRangeBookID string
+	// A real registered device: attributed sessions carry its id (the
+	// rest fall into the "Web / unsynced" bucket).
+	seedDevice, err := setup.DB.CreateDevice(ctx, database.CreateDeviceParams{
+		UserID:               pgUser(userID),
+		DeviceName:           "Kindle Papered Test",
+		DeviceType:           "koreader",
+		DeviceIdentifier:     "stats-test-kindle-" + uuid.NewString(),
+		AuthToken:            "dev_kindle_token_" + uuid.NewString(),
+		SyncEnabled:          pgtype.Bool{Bool: true, Valid: true},
+		AutoSync:             pgtype.Bool{Bool: true, Valid: true},
+		SyncFrequencyMinutes: pgtype.Int4{Int32: 5, Valid: true},
+		DeviceMetadata:       []byte("{}"),
+	})
+	require.NoError(t, err)
+	t.Cleanup(func() { _ = setup.DB.DeleteDevice(ctx, seedDevice.ID) })
+	deviceID := seedDevice.ID
+
+	insertSession := func(daysAgo int, minutes int32, pages int32, pct float64, title string, attributed bool, reuseMediaID ...string) string {
+		var media database.MediaItems
+		var err error
+		if len(reuseMediaID) > 0 && reuseMediaID[0] != "" {
+			media, err = setup.DB.GetMediaItem(ctx, uuidToPGType(uuid.MustParse(reuseMediaID[0])))
+			require.NoError(t, err, "reuse seeded media item")
+		} else {
+			media, err = setup.DB.CreateMediaItem(ctx, database.CreateMediaItemParams{
+				LibraryID: pgtype.UUID{Bytes: [16]byte(libUUID), Valid: true},
+				Title:     title,
+				FilePath:  fmt.Sprintf("/tmp/stats-%s-%d.epub", title, time.Now().UnixNano()),
+				FileSize:  pgtype.Int8{Int64: 1024, Valid: true},
+				MimeType:  pgtype.Text{String: "application/epub+zip", Valid: true},
+			})
+			require.NoError(t, err, "seed media item")
+		}
+
+		deviceIDArg := pgtype.UUID{}
+		if attributed {
+			deviceIDArg = deviceID
+		}
+
+		pushAt := middayDaysAgo(daysAgo)
+		_, err = setup.DB.CreateReadingHistory(ctx, database.CreateReadingHistoryParams{
+			UserID:              pgUser(userID),
+			MediaItemID:         media.ID,
+			DeviceID:            deviceIDArg,
+			ProgressPercentage:  pgFloat(pct),
+			ReadingSessionStart: pgTS(pushAt.Add(-time.Duration(minutes) * time.Minute)),
+			ReadingSessionEnd:   pgTS(pushAt),
+			PagesRead:           pgInt4(pages),
+			TimeSpentSeconds:    pgInt4(minutes * 60),
+			DeviceMetadata:      []byte(`{"source":"test"}`),
+		})
+		require.NoError(t, err, "seed session")
+
+		id, _ := uuid.FromBytes(media.ID.Bytes[0:16])
+		return id.String()
+	}
+
+	// Device-split scenario: attributed (80 min) + unattributed (75 min).
+	finishedBookID = insertSession(0, 30, 12, 1.0, "Stats Finished Book", false)
+	insertSession(1, 45, 20, 0.5, "Stats Streak Book", false)
+	insertSession(2, 60, 25, 0.42, "Stats Back Book", true)
+	insertSession(2, 20, 8, 0.9, "Stats Finished Book (same book, second session)", true, finishedBookID)
+	offRangeBookID = insertSession(400, 120, 40, 0.2, "Stats OffRange Book", false)
+
+	// Summary -----------------------------------------------------------
+	resp, body := statsLogin(t, setup, setup.RegularToken, "/api/stats/summary?range=7")
+	require.Equal(t, http.StatusOK, resp.StatusCode)
+
+	var summary struct {
+		Range          string  `json:"range"`
+		TotalMinutes   int     `json:"total_minutes"`
+		TotalPages     int     `json:"total_pages"`
+		SessionCount   int     `json:"session_count"`
+		BooksActive    int     `json:"books_with_activity"`
+		BooksFinished  int     `json:"books_finished"`
+		CompletionRate float64 `json:"completion_rate"`
+		Daily          []struct {
+			Date    string `json:"date"`
+			Minutes int    `json:"minutes"`
+			Pages   int    `json:"pages"`
+		} `json:"daily"`
+		Streak struct {
+			Current     int  `json:"current"`
+			Longest     int  `json:"longest"`
+			ActiveToday bool `json:"active_today"`
+		} `json:"streak"`
+		TopBooks []struct {
+			MediaItemID string `json:"media_item_id"`
+			Minutes     int    `json:"minutes"`
+		} `json:"top_books"`
+		LibraryBreakdown []struct {
+			Name    string `json:"name"`
+			Minutes int    `json:"minutes"`
+		} `json:"library_breakdown"`
+		DeviceBreakdown []struct {
+			DeviceID string `json:"device_id"`
+			Name     string `json:"name"`
+			Type     string `json:"type"`
+			Minutes  int    `json:"minutes"`
+			Sessions int    `json:"sessions"`
+		} `json:"device_breakdown"`
+	}
+	require.NoError(t, json.Unmarshal(body, &summary))
+
+	assert.Equal(t, "7", summary.Range)
+	require.Len(t, summary.Daily, 7, "zero-filled inclusive calendar")
+	assert.Equal(t, 155, summary.TotalMinutes, "30+45+60+20 (the 400-day-day session is out of range)")
+	assert.Equal(t, 65, summary.TotalPages, "12+20+25+8")
+	assert.Equal(t, 4, summary.SessionCount)
+	assert.Equal(t, 3, summary.BooksActive, "distinct books with sessions")
+	assert.Equal(t, 1, summary.BooksFinished, "finished := any push ≥ 99.5%")
+	assert.InEpsilon(t, float64(1)/float64(3), summary.CompletionRate, 0.001)
+
+	// Streaks: today, −1d, −2d are consecutive; the lone −400d day isn't.
+	t.Logf("STREAK DUMP: %+v (values %#v)", summary.Streak, summary.Streak)
+	t.Logf("DAILY DUMP: %+v", summary.Daily)
+	assert.Equal(t, 3, summary.Streak.Current)
+	assert.Equal(t, 3, summary.Streak.Longest)
+	assert.True(t, summary.Streak.ActiveToday)
+
+	// Top books: minutes-ordered — the seeded 60-minute back book tops.
+	require.NotEmpty(t, summary.TopBooks)
+	assert.Equal(t, 60, summary.TopBooks[0].Minutes)
+	for i := 1; i < len(summary.TopBooks); i++ {
+		assert.GreaterOrEqual(t, summary.TopBooks[i-1].Minutes, summary.TopBooks[i].Minutes, "top books sorted by minutes")
+	}
+
+	// Library breakdown carries the seeded library.
+	found := false
+	for _, lib := range summary.LibraryBreakdown {
+		if lib.Minutes >= 155 {
+			found = true
+		}
+	}
+	assert.True(t, found, "library breakdown aggregates the seeded library")
+
+	// Device breakdown: attributed (80) + unattributed (75) reconcile
+	// against the headline total; both buckets present.
+	require.Len(t, summary.DeviceBreakdown, 2, "one device bucket + one unattributed bucket")
+	var kindleFound, unattributedFound bool
+	for _, dev := range summary.DeviceBreakdown {
+		if dev.Name == "Kindle Papered Test" {
+			kindleFound = true
+			assert.Equal(t, 80, dev.Minutes, "60 + 20 attributed sessions")
+			assert.Equal(t, 2, dev.Sessions)
+			assert.NotEqual(t, "", dev.DeviceID, "device bucket carries its id")
+			assert.Equal(t, "koreader", dev.Type)
+		}
+		if dev.Name == "Web" {
+			unattributedFound = true
+			assert.Equal(t, 75, dev.Minutes, "30 + 45 unattributed sessions")
+			assert.Equal(t, 2, dev.Sessions)
+			assert.Equal(t, "", dev.DeviceID)
+		}
+	}
+	assert.True(t, kindleFound, "the registered device has its own bucket")
+	assert.True(t, unattributedFound, "device-less pushes aggregate into the Web bucket")
+	deviceMinutes := 0
+	for _, dev := range summary.DeviceBreakdown {
+		deviceMinutes += dev.Minutes
+	}
+	assert.Equal(t, 155, deviceMinutes, "device buckets reconcile with the total")
+
+	// Range validation ---------------------------------------------------
+	badResp, badBody := statsLogin(t, setup, setup.RegularToken, "/api/stats/summary?range=fortnight")
+	assert.Equal(t, http.StatusBadRequest, badResp.StatusCode)
+	assert.Contains(t, string(badBody), "invalid range")
+
+	// Auth gate ----------------------------------------------------------
+	anonym, err := http.Get(setup.Server.URL + "/api/stats/summary")
+	require.NoError(t, err)
+	assert.Equal(t, http.StatusUnauthorized, anonym.StatusCode)
+	_ = anonym.Body.Close()
+
+	// Widget -------------------------------------------------------------
+	resp, body = statsLogin(t, setup, setup.RegularToken, "/api/stats/this-week")
+	require.Equal(t, http.StatusOK, resp.StatusCode)
+	var week struct {
+		WeekMinutes   int  `json:"week_minutes"`
+		WeekBooks     int  `json:"week_books"`
+		ActiveToday   bool `json:"active_today"`
+		CurrentStreak int  `json:"current_streak"`
+		PrevMinutes   int  `json:"prev_week_minutes"`
+	}
+	require.NoError(t, json.Unmarshal(body, &week))
+	assert.Equal(t, 155, week.WeekMinutes)
+	assert.Equal(t, 3, week.WeekBooks)
+	assert.True(t, week.ActiveToday)
+	assert.Equal(t, 3, week.CurrentStreak)
+	assert.Equal(t, 0, week.PrevMinutes)
+
+	// Per-book card (lifetime, so the 400-day book still totals) -----------
+	resp, body = statsLogin(t, setup, setup.RegularToken, "/api/stats/books/"+offRangeBookID)
+	require.Equal(t, http.StatusOK, resp.StatusCode)
+	var bookStats struct {
+		TotalMinutes int     `json:"total_minutes"`
+		SessionCount int     `json:"session_count"`
+		MaxProgress  float64 `json:"max_progress"`
+	}
+	require.NoError(t, json.Unmarshal(body, &bookStats))
+	assert.Equal(t, 120, bookStats.TotalMinutes)
+	assert.Equal(t, 1, bookStats.SessionCount)
+	assert.InEpsilon(t, 0.2, bookStats.MaxProgress, 0.001)
+
+	_ = finishedBookID
+}
+
+// TestReadingStatsWeekLibraryScope: the dashboard widget tracks the
+// switched library — this-week totals and streaks scope to the
+// requested library (and stay global without one).
+func TestReadingStatsWeekLibraryScope(t *testing.T) {
+	setup := setupTestServer(t)
+	userID := getRegularUserID(t, setup.DB) // isolated from the live dev-reader account
+	ctx := context.Context(context.Background())
+
+	libA := uuid.MustParse(createLibraryDirect(t, setup.DB, userID, fmt.Sprintf("Test Scope LibA %d", time.Now().UnixNano()), "ebooks"))
+	libB := uuid.MustParse(createLibraryDirect(t, setup.DB, userID, fmt.Sprintf("Test Scope LibB %d", time.Now().UnixNano()), "ebooks"))
+
+	seed := func(lib uuid.UUID, title string, daysAgo int, minutes int32) {
+		media, err := setup.DB.CreateMediaItem(ctx, database.CreateMediaItemParams{
+			LibraryID: pgtype.UUID{Bytes: [16]byte(lib), Valid: true},
+			Title:     title,
+			FilePath:  fmt.Sprintf("/tmp/%s-%d.epub", title, time.Now().UnixNano()),
+			FileSize:  pgtype.Int8{Int64: 1024, Valid: true},
+			MimeType:  pgtype.Text{String: "application/epub+zip", Valid: true},
+		})
+		require.NoError(t, err)
+		pushAt := middayDaysAgo(daysAgo)
+		_, err = setup.DB.CreateReadingHistory(ctx, database.CreateReadingHistoryParams{
+			UserID:              pgUser(userID),
+			MediaItemID:         media.ID,
+			ProgressPercentage:  pgFloat(0.3),
+			ReadingSessionStart: pgTS(pushAt.Add(-time.Duration(minutes) * time.Minute)),
+			ReadingSessionEnd:   pgTS(pushAt),
+			PagesRead:           pgInt4(5),
+			TimeSpentSeconds:    pgInt4(minutes * 60),
+			DeviceMetadata:      []byte(`{"source":"test"}`),
+		})
+		require.NoError(t, err)
+	}
+
+	seed(libA, "Scope A Today", 0, 30)
+	seed(libA, "Scope A Yesterday", 1, 20)
+	seed(libB, "Scope B Today", 0, 45)
+
+	week := func(libraryID string) map[string]interface{} {
+		url := setup.Server.URL + "/api/stats/this-week"
+		if libraryID != "" {
+			url += "?library_id=" + libraryID
+		}
+		req, _ := http.NewRequest("GET", url, nil)
+		req.Header.Set("Authorization", "Bearer "+setup.RegularToken)
+		resp, err := http.DefaultClient.Do(req)
+		require.NoError(t, err)
+		defer func() { _ = resp.Body.Close() }()
+		require.Equal(t, http.StatusOK, resp.StatusCode)
+		var out map[string]interface{}
+		require.NoError(t, json.NewDecoder(resp.Body).Decode(&out))
+		return out
+	}
+
+	num := func(m map[string]interface{}, key string) int { return int(m[key].(float64)) }
+
+	all := week("")
+	assert.Equal(t, 95, num(all, "week_minutes"), "no library filter = all visible libraries")
+	assert.Equal(t, 2, num(all, "current_streak"), "today + yesterday (libA)")
+
+	onlyA := week(libA.String())
+	assert.Equal(t, 50, num(onlyA, "week_minutes"))
+	assert.Equal(t, 2, num(onlyA, "current_streak"))
+	assert.True(t, onlyA["active_today"].(bool))
+
+	onlyB := week(libB.String())
+	assert.Equal(t, 45, num(onlyB, "week_minutes"))
+	assert.Equal(t, 1, num(onlyB, "current_streak"), "libB only has today")
+
+	// A library owned by someone else (invisible to this user) leaks nothing.
+	hidden := uuid.MustParse(createLibraryDirect(t, setup.DB, getTestUserID(t, setup.DB), fmt.Sprintf("Test Scope Hidden %d", time.Now().UnixNano()), "ebooks"))
+	assert.Equal(t, 0, num(week(hidden.String()), "week_minutes"), "invisible library contributes nothing")
+
+	// Malformed scope is a clean 400.
+	req, _ := http.NewRequest("GET", setup.Server.URL+"/api/stats/this-week?library_id=nope", nil)
+	req.Header.Set("Authorization", "Bearer "+setup.RegularToken)
+	resp, err := http.DefaultClient.Do(req)
+	require.NoError(t, err)
+	defer func() { _ = resp.Body.Close() }()
+	assert.Equal(t, http.StatusBadRequest, resp.StatusCode)
+}

cmd/server/tests/sync_integration_test.go

@@ -32,12 +32,16 @@ func setupSyncTestDB(t *testing.T) *database.Queries {
 
 	db := database.New(dbPool)
 	t.Cleanup(func() {
+		// Scoped wipes ONLY: reading_history now carries real captured
+		// sessions for the shared dev accounts, so a table-wide DELETE
+		// here silently destroyed a live reader's stats data on every
+		// suite run (2026-10-14). Sync-test sessions belong to the
+		// test-sync users; deleting those users cascades their rows.
 		_, _ = dbPool.Exec(ctx, "DELETE FROM sync_queue WHERE true")
-		_, _ = dbPool.Exec(ctx, "DELETE FROM reading_history WHERE true")
+		_, _ = dbPool.Exec(ctx, "DELETE FROM users WHERE email LIKE 'test-sync%'")
 		_, _ = dbPool.Exec(ctx, "DELETE FROM media_items WHERE title LIKE 'Test %'")
 		_, _ = dbPool.Exec(ctx, "DELETE FROM libraries WHERE name LIKE 'Test %'")
 		_, _ = dbPool.Exec(ctx, "DELETE FROM devices WHERE device_name LIKE 'Test %'")
-		_, _ = dbPool.Exec(ctx, "DELETE FROM users WHERE email LIKE 'test-sync%'")
 		dbPool.Close()
 	})
 
@@ -55,6 +59,7 @@ func createSyncTestUser(t *testing.T, db *database.Queries) pgtype.UUID {
 		FirstName:    pgtype.Text{String: "Test", Valid: true},
 		LastName:     pgtype.Text{String: "Sync", Valid: true},
 		Role:         "user",
+		Timezone:     pgtype.Text{String: "UTC", Valid: true},
 	})
 	require.NoError(t, err)
 

cmd/server/tests/tags_filter_test.go

@@ -6,6 +6,7 @@ import (
 	"io"
 	"net/http"
 	"net/http/httptest"
+	"strings"
 	"testing"
 
 	"github.com/stretchr/testify/assert"
@@ -34,14 +35,18 @@ func TestTagsFilter(t *testing.T) {
 	_ = folderResp.Body.Close()
 	require.Equal(t, http.StatusCreated, folderResp.StatusCode, "Should add folder to library")
 
-	// Helper to create book with tags
+	// Helper to create book with tags. The file_path must be UNIQUE per
+	// book: CreateMediaItem upserts ON CONFLICT (library_id, file_path),
+	// so a constant path collapses every create onto the first row and
+	// the later books' tags never land.
 	createBook := func(title, author string, tags []string) {
+		slug := strings.ReplaceAll(strings.ToLower(title), " ", "-")
 		bookReq := map[string]interface{}{
 			"library_id": libraryID,
 			"title":      title,
 			"author":     author,
 			"tags":       tags,
-			"file_path":  "/tmp/test.epub",
+			"file_path":  "/tmp/" + slug + ".epub",
 			"file_size":  1024,
 			"mime_type":  "application/epub+zip",
 		}

cmd/server/tests/test_helpers_db_test.go

@@ -109,6 +109,18 @@ func createTestLibraryWithFolder(t *testing.T, ts *httptest.Server, token, name
 	require.NoError(t, err)
 	libraryID := libResponse["id"].(string)
 
+	// Every library a test creates must not outlive that test — delete
+	// it on cleanup so runs leave no residue in the dev database.
+	t.Cleanup(func() {
+		delHTTP, _ := http.NewRequest("DELETE", fmt.Sprintf("%s/api/libraries/%s", ts.URL, libraryID), nil)
+		delHTTP.Header.Set("Authorization", "Bearer "+token)
+		delResp, err := client.Do(delHTTP)
+		if err == nil {
+			_, _ = io.Copy(io.Discard, delResp.Body)
+			_ = delResp.Body.Close()
+		}
+	})
+
 	if withFolder {
 		folderReq := map[string]interface{}{
 			"folder_path": "/app/uploads",

cmd/server/tests/test_helpers_test.go

@@ -77,21 +77,21 @@ type DeviceTestData struct {
 
 // TestServerSetup manages the lifecycle of a test server with proper resource cleanup
 type TestServerSetup struct {
-	Server          *httptest.Server
-	DB              *database.Queries
-	DBPool          *pgxpool.Pool
-	Config          *config.Config
-	ConnManager     *wsync.ConnectionManager
-	QueueProcessor  *wsync.SyncQueueProcessor
-	ProgressService *wsync.ProgressService
+	Server            *httptest.Server
+	DB                *database.Queries
+	DBPool            *pgxpool.Pool
+	Config            *config.Config
+	ConnManager       *wsync.ConnectionManager
+	QueueProcessor    *wsync.SyncQueueProcessor
+	ProgressService   *wsync.ProgressService
 	AnnotationService *wsync.AnnotationService
-	CleanupCancel   context.CancelFunc
-	QueueCtx        context.Context
-	QueueCancel     context.CancelFunc
-	Token           string
-	RegularToken    string
-	mu              sync.Mutex
-	closed          bool
+	CleanupCancel     context.CancelFunc
+	QueueCtx          context.Context
+	QueueCancel       context.CancelFunc
+	Token             string
+	RegularToken      string
+	mu                sync.Mutex
+	closed            bool
 }
 
 // Close cleans up all resources in the correct order
@@ -246,6 +246,7 @@ func createRegularUserOnce(t *testing.T, db *database.Queries) UserTestData {
 		FirstName:    pgtype.Text{String: "Regular", Valid: true},
 		LastName:     pgtype.Text{String: "User", Valid: true},
 		Role:         "user",
+		Timezone:     pgtype.Text{String: "UTC", Valid: true},
 	})
 	require.NoError(t, err, "Should create regular test user")
 
@@ -275,6 +276,10 @@ func uuidToPGType(u uuid.UUID) pgtype.UUID {
 // createDefaultCollectionsForUser creates the 4 default system collections for a user
 func createDefaultCollectionsForUser(t *testing.T, db *database.Queries, userID pgtype.UUID) {
 	ctx := context.Background()
+	// Canonical Title-case names — the same list the registration seed
+	// (CreateDefaultCollectionsForUser) and RestoreSystemCollection use.
+	// A stale kebab-case copy lived here once and duplicated every
+	// system collection in the shared dev DB.
 	defaultCollections := []struct {
 		Name        string
 		Description string
@@ -283,14 +288,34 @@ func createDefaultCollectionsForUser(t *testing.T, db *database.Queries, userID
 		QueryType   string
 		Priority    int32
 	}{
-		{"continue-reading", "Books you're currently reading (0 < progress < 1)", "📖", "#7aa2f7", "continue-reading", 1},
-		{"recently-added", "Newly added items to this library", "🆕", "#9ece6a", "recently-added", 2},
-		{"recently-read", "Books you've finished (progress >= 1)", "✅", "#e0af68", "recently-read", 3},
-		{"not-started", "Books you haven't read yet (progress = 0 or no record)", "📕", "#f7768e", "not-started", 4},
-		{"continue-series", "Next book in series you're reading", "📚", "#bb9af7", "continue-series", 5},
+		{"Continue Reading", "Books you're currently reading (0 < progress < 1)", "📖", "#7aa2f7", "continue-reading", 1},
+		{"Recently Added", "Newly added items to this library", "🆕", "#9ece6a", "recently-added", 2},
+		{"Recently Read", "Books you've finished (progress >= 1)", "✅", "#e0af68", "recently-read", 3},
+		{"Not Started", "Books you haven't read yet (progress = 0 or no record)", "📕", "#f7768e", "not-started", 4},
+		{"Continue Series", "Next book in series you're reading", "📚", "#bb9af7", "continue-series", 5},
 	}
 
 	for _, col := range defaultCollections {
+		// Idempotent by the STABLE identity (user + query_type): existing
+		// rows (renamed, tombstoned) heal to canonical metadata in place;
+		// insert only when the query type has no row. A blind insert here
+		// hit UNIQUE(user_id, name) on every preserved-admin rerun.
+		existing, gerr := db.GetSystemCollectionByQueryType(ctx, database.GetSystemCollectionByQueryTypeParams{
+			UserID:    userID,
+			QueryType: pgtype.Text{String: col.QueryType, Valid: true},
+		})
+		if gerr == nil {
+			_, uerr := db.RestoreSystemCollectionRow(ctx, database.RestoreSystemCollectionRowParams{
+				ID:          existing.ID,
+				Name:        col.Name,
+				Description: pgtype.Text{String: col.Description, Valid: true},
+				Icon:        pgtype.Text{String: col.Icon, Valid: true},
+				Color:       pgtype.Text{String: col.Color, Valid: true},
+				Priority:    pgtype.Int4{Int32: col.Priority, Valid: true},
+			})
+			require.NoError(t, uerr, "Should restore default collection: "+col.Name)
+			continue
+		}
 		_, err := db.CreateSystemCollection(ctx, database.CreateSystemCollectionParams{
 			UserID:          userID,
 			Name:            col.Name,
@@ -482,6 +507,8 @@ func setupTestServer(t *testing.T) *TestServerSetup {
 	filtersHandler := handlers.NewFiltersHandler(queries)
 	dashboardService := services.NewDashboardService(queries)
 	dashboardHandler := handlers.NewDashboardHandler(queries)
+	statisticsService := services.NewStatisticsService(queries)
+	statsHandler := handlers.NewStatsHandler(statisticsService)
 	seriesHandler := handlers.NewSeriesHandler(queries)
 	mediaHandler := handlers.NewMediaHandler(queries, libraryService, worker)
 	mediaHandler.SetProgressService(progressService)
@@ -515,35 +542,45 @@ func setupTestServer(t *testing.T) *TestServerSetup {
 
 	// Setup routes using router package
 	routerConfig := &router.Config{
-		Echo:                  e,
-		Queries:               queries,
-		Cfg:                   cfg,
-		DBPool:                dbPool,
-		AuthHandler:           authHandler,
-		LibraryHandler:        libraryHandler,
-		DeviceHandler:         deviceHandler,
-		MediaHandler:          mediaHandler,
-		MatchingHandler:       matchingHandler,
-		KOReaderHandler:       koreaderHandler,
-		WSHandler:             wsHandler,
-		ConflictHandler:       conflictHandler,
-		AnalyticsHandler:      analyticsHandler,
-		QueueHandler:          queueHandler,
-		SystemSettingsHandler: systemSettingsHandler,
+		Echo:                    e,
+		Queries:                 queries,
+		Cfg:                     cfg,
+		DBPool:                  dbPool,
+		AuthHandler:             authHandler,
+		LibraryHandler:          libraryHandler,
+		DeviceHandler:           deviceHandler,
+		MediaHandler:            mediaHandler,
+		MatchingHandler:         matchingHandler,
+		KOReaderHandler:         koreaderHandler,
+		WSHandler:               wsHandler,
+		ConflictHandler:         conflictHandler,
+		AnalyticsHandler:        analyticsHandler,
+		StatsHandler:            statsHandler,
+		StatisticsService:       statisticsService,
+		QueueHandler:            queueHandler,
+		SystemSettingsHandler:   systemSettingsHandler,
 		ProcessingIssuesHandler: processingIssuesHandler,
-		CollectionHandler:     collectionHandler,
-		FiltersHandler:        filtersHandler,
-		DashboardHandler:      dashboardHandler,
-		DashboardService:      dashboardService,
-		SeriesHandler:         seriesHandler,
-		OPDSHandler:           opdsHandler,
-		JobsHandler:           jobsHandler,
-		ConnManager:           connManager,
-		QueueProcessor:        queueProcessor,
-		ProgressService:       progressService,
-		AnnotationService:     annotationService,
-		DeviceAuthMiddleware:  deviceAuthMiddleware,
-		LoginTracker:          loginAttemptTracker,
+		CollectionHandler:       collectionHandler,
+		FiltersHandler:          filtersHandler,
+		DashboardHandler:        dashboardHandler,
+		DashboardService:        dashboardService,
+		SeriesHandler:           seriesHandler,
+		OPDSHandler:             opdsHandler,
+		JobsHandler:             jobsHandler,
+		ConnManager:             connManager,
+		QueueProcessor:          queueProcessor,
+		ProgressService:         progressService,
+		AnnotationService:       annotationService,
+		DeviceAuthMiddleware:    deviceAuthMiddleware,
+		LoginTracker:            loginAttemptTracker,
+		// RegisterRoutes dereferences Settings for the auth rate limit;
+		// the main binary wires database.NewSettingsRegistry(queries) —
+		// the test harness must too or route registration nil-panics.
+		Settings: database.NewSettingsRegistry(queries),
+		// main.go:246 passes the shared LibraryService here; omitting it
+		// hands the kobo/kepub CFI converter a typed-nil (kobo markup
+		// panic-recovered as 500s in TestProgressWeb_KoboIntegration).
+		LibraryService: libraryService,
 	}
 
 	router.RegisterRoutes(routerConfig)
@@ -588,22 +625,74 @@ func setupTestServer(t *testing.T) *TestServerSetup {
 		}
 	}
 
-	// Create fresh admin test user
+	// The admin test user doubles as the shared dev admin and is
+	// deliberately PRESERVED by the cleanup above — reuse it when it
+	// already exists instead of re-creating (a blind INSERT hits
+	// users_email_key on every run after the first).
 	passwordHash := "$2a$10$JjAtK7PPa1WexQC3AUGe8OXLeuseZ/haN1Mz7emMo6CfOvMiTVXWq"
-	adminUser, err := queries.CreateUser(ctx, database.CreateUserParams{
-		Email:        "testuser@tests.bookhoard.internal",
-		Username:     "testuser",
-		PasswordHash: passwordHash,
-		FirstName:    pgtype.Text{String: "Test", Valid: true},
-		LastName:     pgtype.Text{String: "User", Valid: true},
-		Role:         "admin",
-	})
-	require.NoError(t, err, "Failed to create admin test user")
-
-	adminUUID, err := uuid.FromBytes(adminUser.ID.Bytes[:])
-	require.NoError(t, err, "Failed to parse admin user UUID")
+	var adminUUID uuid.UUID
+	if existing, gerr := queries.GetUserByEmail(ctx, "testuser@tests.bookhoard.internal"); gerr == nil {
+		adminUUID, err = uuid.FromBytes(existing.ID.Bytes[:])
+		require.NoError(t, err, "Failed to parse admin user UUID")
+		// Reset the password to the known test constant: other tests (e.g.
+		// password-change tests) mutate the shared admin's password, which
+		// would otherwise lock every later test out with login 401s until
+		// the database is wiped.
+		if updErr := queries.UpdatePassword(ctx, database.UpdatePasswordParams{
+			ID:           existing.ID,
+			PasswordHash: passwordHash,
+		}); updErr != nil {
+			require.NoError(t, updErr, "Failed to reset shared admin test password")
+		}
+	} else {
+		adminUser, cerr := queries.CreateUser(ctx, database.CreateUserParams{
+			Email:        "testuser@tests.bookhoard.internal",
+			Username:     "testuser",
+			PasswordHash: passwordHash,
+			FirstName:    pgtype.Text{String: "Test", Valid: true},
+			LastName:     pgtype.Text{String: "User", Valid: true},
+			Role:         "admin",
+		})
+		require.NoError(t, cerr, "Failed to create admin test user")
+		adminUUID, err = uuid.FromBytes(adminUser.ID.Bytes[:])
+		require.NoError(t, err, "Failed to parse admin user UUID")
+	}
+	// The canonical system-collection set is ensured on EVERY run: the
+	// helper is idempotent by (user, query_type) and heals tombstoned or
+	// renamed rows, so suite runs can't accumulate naming-drift copies.
 	createDefaultCollectionsForUser(t, queries, pgtype.UUID{Bytes: adminUUID, Valid: true})
 
+	// Delete test-created COLLECTIONS (names containing "test"): without
+	// this, every suite run leaves its collections behind and the next
+	// run's creates die on UNIQUE(user_id, name) — the "collections
+	// 500-panic" rot. System collections are skipped (permanent rows).
+	// Same convention as the library pass: names containing "test".
+	adminColls, cerr := queries.GetCollectionsByUser(ctx, pgtype.UUID{Bytes: adminUUID, Valid: true})
+	if cerr == nil {
+		for _, coll := range adminColls {
+			if !coll.IsSystemCollection.Bool && strings.Contains(strings.ToLower(coll.Name), "test") {
+				queries.DeleteCollection(ctx, coll.ID)
+			}
+		}
+	}
+
+	// Same passes for test DEVICES (identifier/name containing "test")
+	// and test SAVED FILTERS (name containing "test"): both accumulated
+	// across runs and poisoned later runs (duplicate identifiers, 409s,
+	// non-empty "initially empty" assertions).
+	_, derr := dbPool.Exec(ctx,
+		"DELETE FROM devices WHERE user_id = $1 AND (device_identifier ILIKE '%test%' OR device_name ILIKE '%test%')",
+		adminUUID)
+	if derr != nil {
+		t.Logf("device cleanup failed: %v", derr)
+	}
+	_, ferr := dbPool.Exec(ctx,
+		"DELETE FROM saved_filters WHERE user_id = $1 AND name ILIKE '%test%'",
+		adminUUID)
+	if ferr != nil {
+		t.Logf("saved-filter cleanup failed: %v", ferr)
+	}
+
 	// Create fresh regular test user
 	regularUser, err := queries.CreateUser(ctx, database.CreateUserParams{
 		Email:        "testregularuser@tests.bookhoard.internal",
@@ -612,6 +701,7 @@ func setupTestServer(t *testing.T) *TestServerSetup {
 		FirstName:    pgtype.Text{String: "Regular", Valid: true},
 		LastName:     pgtype.Text{String: "User", Valid: true},
 		Role:         "user",
+		Timezone:     pgtype.Text{String: "UTC", Valid: true},
 	})
 	require.NoError(t, err, "Failed to create regular test user")
 
@@ -652,6 +742,17 @@ func setupTestServer(t *testing.T) *TestServerSetup {
 			}
 		}
 
+		// Same pass for test-created COLLECTIONS (the "collections
+		// 500-panic" rot: they lingered forever and poisoned later runs).
+		adminColls, cerr := queries.GetCollectionsByUser(ctx, pgtype.UUID{Bytes: adminUUID, Valid: true})
+		if cerr == nil {
+			for _, coll := range adminColls {
+				if !coll.IsSystemCollection.Bool && strings.Contains(strings.ToLower(coll.Name), "test") {
+					queries.DeleteCollection(ctx, coll.ID)
+				}
+			}
+		}
+
 		if err := setup.Close(); err != nil {
 			t.Errorf("Failed to cleanup test server: %v", err)
 		}
@@ -699,6 +800,26 @@ func getTestUserID(t *testing.T, db *database.Queries) uuid.UUID {
 	return userUUID
 }
 
+// createLibraryDirect inserts a library owned by the given user WITHOUT a
+// nested test-server setup: a second setupTestServer bootstraps away the
+// first setup's users, and the ghost-session guard rightly rejects the
+// outer test's tokens from then on.
+func createLibraryDirect(t *testing.T, db *database.Queries, ownerID uuid.UUID, name, libraryType string) string {
+	ctx := context.Background()
+	libraryTypeRow, err := db.GetLibraryTypeByName(ctx, libraryType)
+	require.NoError(t, err, "Should find library type")
+	library, err := db.CreateLibrary(ctx, database.CreateLibraryParams{
+		Name:             name,
+		Description:      pgtype.Text{String: "Test library description", Valid: true},
+		LibraryTypeID:    libraryTypeRow.ID,
+		CreatedByAdminID: pgtype.UUID{Bytes: [16]byte(ownerID), Valid: true},
+	})
+	require.NoError(t, err, "Should create library")
+	libraryUUID, err := uuid.FromBytes(library.ID.Bytes[0:16])
+	require.NoError(t, err, "Should parse library ID")
+	return libraryUUID.String()
+}
+
 func getRegularUserID(t *testing.T, db *database.Queries) uuid.UUID {
 	ctx := context.Background()
 	user, err := db.GetUserByEmail(ctx, "testregularuser@tests.bookhoard.internal")

cmd/server/tests/user_test.go

@@ -8,22 +8,65 @@ import (
 	"net/http/httptest"
 	"testing"
 
+	"bookhoard/internal/database"
+
 	"github.com/google/uuid"
+	"github.com/jackc/pgx/v5/pgtype"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 	"golang.org/x/crypto/bcrypt"
 )
 
+// ensureSingleAdmin makes the "last admin" precondition deterministic in
+// the shared test DB: only the preserved testuser admin remains. Other
+// suites may have promoted or renamed users; the last-admin semantics
+// under test require a true singleton.
+func ensureSingleAdmin(t *testing.T, setup *TestServerSetup) {
+	ctx := context.Background()
+	_, err := setup.DBPool.Exec(ctx,
+		"DELETE FROM users WHERE role = 'admin' AND email != 'testuser@tests.bookhoard.internal'")
+	require.NoError(t, err, "Failed to prune extra admins")
+
+	if _, err := setup.DB.GetUserByEmail(ctx, "testuser@tests.bookhoard.internal"); err != nil {
+		passwordHash := "$2a$10$JjAtK7PPa1WexQC3AUGe8OXLeuseZ/haN1Mz7emMo6CfOvMiTVXWq"
+		_, cerr := setup.DB.CreateUser(ctx, database.CreateUserParams{
+			Email:        "testuser@tests.bookhoard.internal",
+			Username:     "testuser",
+			PasswordHash: passwordHash,
+			Role:         "admin",
+			Timezone:     pgtype.Text{String: "UTC", Valid: true},
+		})
+		require.NoError(t, cerr, "Failed to restore the shared admin")
+	}
+
+	users, _ := setup.DB.ListUsers(ctx)
+	adminCount := 0
+	for _, u := range users {
+		if u.Role == "admin" {
+			adminCount++
+		}
+	}
+	require.Equal(t, 1, adminCount, "precondition: exactly one admin")
+}
+
 func TestUpdateProfileSelfEdit(t *testing.T) {
 	t.Run("PUT /api/auth/profile - Update all fields successfully", func(t *testing.T) {
 		setup := setupTestServer(t)
 
-		_ = createTestUserOnce(t, setup.DB)
-		token := setup.Token
+		// Self-edit a DEDICATED user, never the shared admin: renaming
+		// testuser here leaked a second admin row into the shared DB (the
+		// renamed email escapes the harness's preserve-list cleanup) and
+		// broke the last-admin tests downstream.
+		selfUser := createRegularUserOnce(t, setup.DB)
+		token := loginUserWithCredentials(t, setup.Server, selfUser.Email, selfUser.Password)
 
+		// Unique rename target: a fixed name collides with stale rows from
+		// earlier runs of this very test (409 username conflict).
+		suffix := uuid.New().String()[:8]
+		newUsername := "updateduser-" + suffix
 		updateData := map[string]interface{}{
-			"username":   "updateduser",
-			"email":      "updated@tests.bookhoard.internal",
+			"username":   newUsername,
+			"email":      "updated-" + suffix + "@tests.bookhoard.internal",
 			"first_name": "Updated",
 			"last_name":  "Name",
 			"theme":      "dracula",
@@ -39,9 +82,9 @@ func TestUpdateProfileSelfEdit(t *testing.T) {
 
 		assert.Equal(t, http.StatusOK, rec.Code)
 
-		user, err := setup.DB.GetUserByUsername(context.Background(), "updateduser")
+		user, err := setup.DB.GetUserByUsername(context.Background(), newUsername)
 		require.NoError(t, err)
-		assert.Equal(t, "updated@tests.bookhoard.internal", user.Email)
+		assert.Equal(t, "updated-"+suffix+"@tests.bookhoard.internal", user.Email)
 		assert.Equal(t, "Updated", user.FirstName.String)
 		assert.Equal(t, "Name", user.LastName.String)
 		assert.Equal(t, "dracula", user.Theme.String)
@@ -215,6 +258,10 @@ func TestUpdateProfileAdminMode(t *testing.T) {
 	t.Run("PUT /api/auth/profile/:id - Try to demote last admin", func(t *testing.T) {
 		setup := setupTestServer(t)
 
+		// Deterministic singleton-admin precondition (shared DB may carry
+		// promoted/renamed admin rows from other suites).
+		ensureSingleAdmin(t, setup)
+
 		// Delete the regular user so we have only 1 admin (testuser)
 		regularUser := createRegularUserOnce(t, setup.DB)
 		err := setup.DB.DeleteUser(context.Background(), uuidToPGType(regularUser.ID))
@@ -435,6 +482,7 @@ func TestDeleteUserConsolidated(t *testing.T) {
 	t.Run("DELETE /api/auth/profile - Last admin tries self-delete", func(t *testing.T) {
 		setup := setupTestServer(t)
 
+		ensureSingleAdmin(t, setup)
 		_ = createTestUserOnce(t, setup.DB)
 		token := setup.Token
 
@@ -471,6 +519,7 @@ func TestDeleteUserConsolidated(t *testing.T) {
 	t.Run("DELETE /api/auth/profile/:id - Admin tries delete last admin", func(t *testing.T) {
 		setup := setupTestServer(t)
 
+		ensureSingleAdmin(t, setup)
 		_ = createTestUserOnce(t, setup.DB)
 		token := setup.Token
 

cmd/server/tests/websocket_test.go

@@ -240,9 +240,11 @@ func TestWebSocketUserScopedBroadcast(t *testing.T) {
 	// Use pre-created admin user (setup.Token) and regular user (setup.RegularToken)
 	// Both users already created by setupTestServer()
 
-	// Create a collection for admin user
+	// Create a collection for admin user. Unique name: the shared DB keeps
+	// non-"test"-named collections across runs, and UNIQUE(user_id, name)
+	// turns a fixed name into a 409 on the second run.
 	collectionReq := map[string]interface{}{
-		"name":        "Admin Collection",
+		"name":        "Admin Collection " + uuid.New().String()[:8],
 		"description": "Test collection for WebSocket test",
 	}
 	collectionBody, _ := json.Marshal(collectionReq)

database/schema/schema.sql

@@ -68,6 +68,7 @@ INSERT INTO system_settings (setting_key, setting_value, description, setting_ty
 ('password_require_lower', 'true', 'Require at least one lowercase letter (a-z)', 'bool', NULL, NULL, FALSE, 'security'),
 ('password_require_number', 'true', 'Require at least one number (0-9)', 'bool', NULL, NULL, FALSE, 'security'),
 ('password_require_special', 'true', 'Require at least one special character', 'bool', NULL, NULL, FALSE, 'security'),
+('registration_enabled', 'false', 'Allow users to create their own accounts (admins can always create accounts)', 'bool', NULL, NULL, FALSE, 'security'),
 -- security / auth (restart required)
 ('auth_rate_limit_per_min', '10', 'Global auth API rate limit (requests per minute)', 'int', '1', '10000', TRUE, 'security'),
 ('login_max_attempts', '5', 'Failed login attempts before lockout', 'int', '1', '100', TRUE, 'security'),
@@ -259,8 +260,11 @@ CREATE INDEX IF NOT EXISTS idx_media_items_archived ON media_items (archived_at)
 CREATE INDEX IF NOT EXISTS idx_media_items_tags_search ON media_items USING GIN (tags_search);
 CREATE INDEX IF NOT EXISTS idx_media_items_contributors_search ON media_items USING GIN (contributors_search);
 
--- Drop existing trigger if exists
+-- Drop existing triggers if exists. Both must be dropped BEFORE the function:
+-- dropping a function that triggers still reference fails (SQLSTATE 2BP01),
+-- which would abort the schema transaction on every startup after the first.
 DROP TRIGGER IF EXISTS set_library_type_name_on_insert ON media_items;
+DROP TRIGGER IF EXISTS set_library_type_name_on_library_change ON media_items;
 -- Drop existing function if exists
 DROP FUNCTION IF EXISTS set_library_type_name();
 
@@ -279,6 +283,14 @@ CREATE TRIGGER set_library_type_name_on_insert
   FOR EACH ROW
   EXECUTE FUNCTION set_library_type_name();
 
+-- Keep library_type_name truthful when an item is repointed to another
+-- library (cross-library move detection reuses the same function; the row
+-- keeps its ID while its library changes).
+CREATE TRIGGER set_library_type_name_on_library_change
+  BEFORE UPDATE OF library_id ON media_items
+  FOR EACH ROW
+  EXECUTE FUNCTION set_library_type_name();
+
 -- Add GIN indexes for pg_trgm fuzzy search performance
 CREATE INDEX IF NOT EXISTS idx_media_items_author_trgm
   ON media_items USING GIN (author gin_trgm_ops);
@@ -333,6 +345,20 @@ CREATE TABLE IF NOT EXISTS media_ratings (
     UNIQUE(media_item_id, user_id)
 );
 
+-- Create media_reviews table: the user's markdown book review. Sibling of
+-- media_ratings (same uniqueness + cascade shape) but standalone — a review
+-- without a rating (and vice versa) must work. Stored as RAW markdown and
+-- rendered only at display sites (same doctrine as notes).
+CREATE TABLE IF NOT EXISTS media_reviews (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    media_item_id UUID NOT NULL REFERENCES media_items(id) ON DELETE CASCADE,
+    user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    review TEXT NOT NULL,
+    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+    updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+    UNIQUE(media_item_id, user_id)
+);
+
 -- Create media_notes table for user notes on media items
 CREATE TABLE IF NOT EXISTS media_notes (
     id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
@@ -590,6 +616,10 @@ CREATE INDEX IF NOT EXISTS idx_reading_progress_user_id ON reading_progress(user
 CREATE INDEX IF NOT EXISTS idx_media_ratings_media_item_id ON media_ratings(media_item_id);
 CREATE INDEX IF NOT EXISTS idx_media_ratings_user_id ON media_ratings(user_id);
 
+-- Reviews indexes
+CREATE INDEX IF NOT EXISTS idx_media_reviews_media_item_id ON media_reviews(media_item_id);
+CREATE INDEX IF NOT EXISTS idx_media_reviews_user_id ON media_reviews(user_id);
+
 -- Notes and highlights indexes
 CREATE INDEX IF NOT EXISTS idx_media_notes_media_item_id ON media_notes(media_item_id);
 CREATE INDEX IF NOT EXISTS idx_media_notes_user_id ON media_notes(user_id);
@@ -1123,9 +1153,15 @@ CREATE TABLE IF NOT EXISTS collections (
     priority INT DEFAULT 100,
     is_system_collection BOOLEAN DEFAULT false,
     created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+    deleted_at TIMESTAMP WITH TIME ZONE,
     UNIQUE(user_id, name)
 );
 
+-- System collections (the 5 dashboard sections) are permanent: "delete"
+-- tombstones the row (deleted_at) and restore un-tombstones it in place —
+-- the row id (and everything referencing it) never churn.
+ALTER TABLE collections ADD COLUMN IF NOT EXISTS deleted_at TIMESTAMPTZ;
+
 CREATE INDEX IF NOT EXISTS idx_collections_user_id ON collections(user_id);
 
 -- Index for dashboard queries
@@ -1148,6 +1184,20 @@ CREATE TABLE IF NOT EXISTS user_dashboard_preferences (
 -- Index for fast lookups
 CREATE INDEX IF NOT EXISTS idx_dashboard_prefs_user_library ON user_dashboard_preferences(user_id, library_id);
 
+-- Global (all-libraries) dashboard preferences: exactly one row per user.
+-- Backs the dashboard's "All Libraries" view (library_id NULL convention
+-- rejected: the upsert's ON CONFLICT cannot dedupe NULLs and intent would
+-- be invisible — a dedicated table makes the scope structural). System
+-- and user collections are user-scoped, so collection_order/
+-- hidden_collections IDs are library-independent and valid in this scope.
+CREATE TABLE IF NOT EXISTS user_dashboard_preferences_global (
+    user_id UUID PRIMARY KEY REFERENCES users(id) ON DELETE CASCADE,
+    hidden_collections TEXT[] DEFAULT '{}',
+    collection_order TEXT[] DEFAULT '{}',
+    items_per_section INT DEFAULT 20,
+    updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
+);
+
 -- Create collection_items table (which books belong to each collection)
 CREATE TABLE IF NOT EXISTS collection_items (
     id UUID PRIMARY KEY DEFAULT gen_random_uuid(),

docker-compose.yml

@@ -15,7 +15,8 @@ services:
       # Make other volumes as needed
       - ./uploads:/app/uploads
     ports:
-      - "${DB_PORT:-5432}:${DB_PORT:-5432}"
+      - "127.0.0.1:${DB_PORT:-5432}:${DB_PORT:-5432}"
+      - "[::1]:${DB_PORT:-5432}:${DB_PORT:-5432}"
     healthcheck:
       test: ["CMD-SHELL", "pg_isready -U postgres"]
       interval: 30s

docs/contributing/contributing.md

@@ -14,7 +14,7 @@ Welcome to the Bookhoard contributing documentation. This section contains guide
 
 ## 📋 Project Guidelines
 
-- **[PROJECT_GUIDELINES.md](../PROJECT_GUIDELINES.md)** - Development rules and standards
+- **[AGENTS.md](../../AGENTS.md)** - Agent/development rules
   - Critical prohibitions
   - Mandatory requirements
   - Error recovery protocol

docs/contributing/development.md

@@ -445,7 +445,7 @@ DEBUG=true
 
 ## 📚 Additional Resources
 
-- [Project Guidelines](../../PROJECT_GUIDELINES.md) - Development rules and standards
+- [AGENTS.md](../../AGENTS.md) - Agent/development rules
 - [API Reference](../API_REFERENCE.md) - Complete API documentation
 - [Troubleshooting](../TROUBLESHOOTING.md) - Deployment issues
 - [Go Documentation](https://go.dev/doc/)

docs/developer/api-reference.md

@@ -394,6 +394,11 @@ Authorization: Bearer <token>
 
 ## Reading Progress
 
+Full field reference: [api/progress/](api/progress/) — and read the
+[Position Contract](api/progress/position-contract.md) (verification,
+healing, the OPF spine numbering hazard, offset currencies) before
+writing a client.
+
 ### Get Reading Progress
 
 ```http
@@ -405,57 +410,56 @@ Authorization: Bearer <token>
 
 ```json
 {
+  "id": "uuid",
   "media_item_id": "uuid",
   "user_id": "uuid",
-  "current_page": 45,
-  "total_pages": 200,
-  "percentage": 0.225,
-  "character_offset": 15432,
-  "epubcfi": "epubcfi(/6/4/2:15)",
-  "chapter": 3,
-  "chapter_progress": 0.5,
-  "last_read_at": "2026-01-31T10:00:00Z",
+  "percentage": 0.045,
+  "epubcfi": "epubcfi(/6/4!/4/8[_idContainer003]/58/1:598)",
+  "context_text": "from day to day, but there was none in which ...",
+  "character_offset": 16375,
+  "current_page": null,
+  "total_pages": null,
+  "chapter": null,
+  "chapter_progress": null,
   "format_group": "reflowable",
-  "viewport_y": 0.12,
-  "zoom_level": 1.0
+  "total_characters": 592216,
+  "chapter_count": 1,
+  "last_read_at": "2026-09-26T14:52:34Z",
+  "last_sync_source": "koreader",
+  "css_selector": "body>div:nth-child(4)>p:nth-child(29)",
+  "anchor_href": "1984.xhtml",
+  "char_offset": 598
 }
 ```
 
+`css_selector`, `anchor_href` and `char_offset` are server-derived
+restore handles, served for convertible reflowable books with a
+resolvable anchor. `char_offset` is UTF-16 code units within the anchor
+block's text; `character_offset` is a book-wide rune count. Resolve the
+document by `anchor_href`, never by the CFI's spine step (OPF numbering
+includes `linear="no"` items).
+
 ### Update Reading Progress
 
 ```http
 PUT /api/media-items/{media_id}/progress
 Authorization: Bearer <token>
 Content-Type: application/json
-
-{
-  "source": "web",
-  "location": {
-    "percentage": 0.45678,
-    "epubcfi": "epubcfi(/6/4/2:15)",
-    "character": 15432,
-    "chapter": 3,
-    "page": 89,
-    "total_pages": 200
-  },
-  "device_metadata": {
-    "device_type": "web",
-    "user_agent": "Mozilla/5.0..."
-  }
-}
 ```
 
-**Response** (200):
-
 ```json
 {
-  "sync_status": "success",
-  "progress_updated": true,
-  "devices_notified": ["device-1", "device-2"],
-  "broadcast": true
+  "percentage": 0.0415,
+  "context_text": "was at war with one of these Powers it was generally a",
+  "epubcfi": "epubcfi(/6/4!/4/8[_idContainer003]/62/1:456)"
 }
 ```
 
+All fields are optional. The server verifies the submission against the
+book and heals it on mismatch; the response is the stored row after
+verification. A `percentage` below 0.005 is ignored while stored
+progress exceeds 0.01 (first-page anti-clobber).
+
 ### Delete Reading Progress
 
 ```http
@@ -1297,82 +1301,10 @@ Authorization: Bearer <device_token>
 
 ## Universal Progress
 
-### Get Universal Progress
-
-```http
-GET /api/progress/{book_uuid}
-Authorization: Bearer <token>
-```
-
-**Response** (200):
-
-```json
-{
-  "book_id": "book-uuid",
-  "format_group": "reflowable",
-  "universal_progress": 0.45678,
-  "location_references": {
-    "percentage": 0.45678,
-    "epubcfi": "epubcfi(/6/4/2:15)",
-    "character": 15432,
-    "chapter": 3,
-    "chapter_progress": 0.234,
-    "viewport_y": 0.12
-  },
-  "device_progress": {
-    "koreader": {
-      "percentage": 0.45678,
-      "last_sync": "2026-01-30T20:00:00Z"
-    },
-    "kobo": {
-      "percentage": 45.6,
-      "last_sync": "2026-01-30T19:55:00Z"
-    },
-    "web": {
-      "display_page": 89,
-      "total_pages": 200,
-      "last_sync": "2026-01-30T20:05:00Z"
-    }
-  },
-  "annotations": {
-    "highlights": [...],
-    "notes": [...],
-    "bookmarks": [...]
-  },
-  "conflicts": [
-    {
-      "id": "conflict-uuid",
-      "type": "progress",
-      "resolved": false,
-      "sources": ["koreader", "kobo"]
-    }
-  ]
-}
-```
-
-### Update Universal Progress
-
-```http
-POST /api/progress/{book_uuid}
-Authorization: Bearer <token>
-Content-Type: application/json
-
-{
-  "source": "web|koreader|kobo|mobile",
-  "location": {
-    "percentage": 0.45678,
-    "epubcfi": "epubcfi(/6/4/2:15)",
-    "character": 15432,
-    "chapter": 3,
-    "page": 89,
-    "total_pages": 200
-  },
-  "device_metadata": {
-    "device_type": "web",
-    "user_agent": "..."
-  }
-}
-```
+Universal progress is the media-item progress — one row per (user,
+media item) shared by every device. See [Reading Progress](#reading-progress)
+and the [Position Contract](api/progress/position-contract.md). There
+are no separate `/api/progress/:id` GET/POST endpoints.
 
 ## Conflicts
 

docs/developer/api/api-reference.md

@@ -117,10 +117,14 @@ See [Media Item Operations](media-items/)
 
 ## Reading Progress
 
-See [Progress Tracking](progress/)
+See [Progress Tracking](progress/) — in particular the
+[Position Contract](progress/position-contract.md) (verification,
+healing, the OPF spine numbering hazard, and offset currencies) before
+writing a client.
 
-- GET /api/progress/:id - Get universal progress
-- POST /api/progress/:id - Update universal progress
+- GET /api/media-items/:id/progress - Get reading progress + restore handles
+- PUT /api/media-items/:id/progress - Submit reading progress (verified/healed server-side)
+- DELETE /api/media-items/:id/progress - Delete reading progress
 - GET /api/progress/:id/history - Get progress history
 
 ## Notes & Highlights

docs/developer/api/koreader/get_metadata.md

@@ -1,9 +1,12 @@
 # Get Metadata
 
-Get metadata for a book from KOReader device.
+Get a book's stored progress and annotations for a KOReader device —
+the pull half of the device sync. The reference client calls this after
+linking a book via [Resolve Book](resolve_book.md) and navigates to the
+returned position.
 
 **Endpoint**: `GET /api/sync/koreader/metadata/:uuid`
-**Auth**: Required (Device authentication)
+**Auth**: Required (Device authentication — `Authorization: Bearer {device_token}`)
 
 ## Path Parameters
 
@@ -11,41 +14,55 @@ Get metadata for a book from KOReader device.
 | --------- | ------------- | -------- | ----------- |
 | uuid      | string (UUID) | Yes      | Book UUID   |
 
-## Device Authentication
-
-This endpoint requires device authentication (not user JWT). Devices authenticate using their device credentials.
-
-## Request Headers
-
-| Header       | Type   | Required | Description               |
-| ------------ | ------ | -------- | ------------------------- |
-| X-Device-ID  | string | Yes      | Device UUID               |
-| X-Device-Key | string | Yes      | Device authentication key |
-
 ### Example Request
 
 ```http
-GET /api/sync/koreader/metadata/550e8400-e29b-41d4-a716-446655440000
-X-Device-ID: 550e8400-e29b-41d4-a716-446655440000
-X-Device-Key: device-auth-key
+GET /api/sync/koreader/metadata/774641f9-317b-4087-8e04-53bb4392ae56
+Authorization: Bearer {device_token}
 ```
 
 ## Response (200 OK)
 
 ```json
 {
-  "id": "uuid",
-  "title": "Book Title",
-  "authors": ["Author Name"],
-  "path": "/path/to/book.epub",
-  "file_size": 1234567,
-  "modified_at": "2026-02-08T10:00:00Z"
+  "uuid": "774641f9-317b-4087-8e04-53bb4392ae56",
+  "title": "1984",
+  "author": "George Orwell",
+  "progress": {
+    "percentage": 0.045,
+    "koreader_xpointer": "/body/DocFragment[1]/body/p[29]/text().598",
+    "chapter": null,
+    "chapter_progress": null,
+    "page": null,
+    "total_pages": null
+  },
+  "annotations": {
+    "highlights": []
+  }
 }
 ```
 
+### Progress Object
+
+| Field | Type | Description |
+| ----- | ---- | ----------- |
+| `percentage` | float | Stored position as a book fraction. |
+| `koreader_xpointer` | string | The stored canonical position converted back to a CRE xpointer (UTF-16 `text().N` offset). **The device should navigate to this.** Reflowable books only. |
+| `epubcfi` | string | The stored canonical CFI, when the conversion to a CRE xpointer is unavailable. Fallback after `koreader_xpointer`. |
+| `character` | int | Book-wide rune offset (internal currency). |
+| `chapter`, `chapter_progress` | int, float | Chapter position when known. |
+| `page`, `total_pages` | int | Fixed-layout page position — the canonical locator for image-based books (CFI/xpointer are omitted for them). |
+
+`progress` is `null` when the book has no stored progress.
+
+The `annotations` object carries device-format highlights/bookmarks/notes
+synced from other clients; its presence depends on annotation sync being
+enabled.
+
 ## Error Responses
 
-| Code | Description                  |
-| ---- | ---------------------------- |
+| Code | Description |
+| ---- | ----------- |
+| 400  | Invalid book UUID |
 | 401  | Device authentication failed |
-| 404  | Book or device not found     |
+| 404  | Book not found |

docs/developer/api/koreader/sync_progress.md

@@ -1,63 +1,87 @@
 # Sync Progress
 
-Sync reading progress from KOReader device.
+Push reading progress from a KOReader device.
 
 **Endpoint**: `POST /api/sync/koreader/progress`
-**Auth**: Required (Device authentication)
+**Auth**: Required (Device authentication — `Authorization: Bearer {device_token}`)
 
-## Device Authentication
-
-This endpoint requires device authentication (not user JWT). Devices authenticate using their device credentials.
+This is the device-native tier of the [Position
+Contract](../progress/position-contract.md): the KOReader payload carries
+a CRE xpointer and the server converts it to the canonical standard CFI,
+verifies it against the submitted `context_text`, and heals it on
+mismatch — exactly like every other client.
 
 ## Request Body
 
-| Field     | Type          | Required | Description               |
-| --------- | ------------- | -------- | ------------------------- |
-| device_id | string (UUID) | Yes      | Device UUID               |
-| progress  | array         | Yes      | Array of progress objects |
+| Field     | Type   | Required | Description |
+| --------- | ------ | -------- | ----------- |
+| `books`    | array  | Yes      | One book object (the reference client sends a single-element array). |
+| `sync_mode`| string | No       | `immediate` (default) or `manual`. |
 
-### Progress Object
+### Book Object
 
-| Field       | Type    | Required | Description                        |
-| ----------- | ------- | -------- | ---------------------------------- |
-| book        | string  | Yes      | Book identifier (filename or UUID) |
-| percent     | float   | Yes      | Progress percentage (0-100)        |
-| page        | integer | No       | Current page number                |
-| total_pages | integer | No       | Total pages in document            |
-| date_read   | string  | No       | ISO 8601 timestamp of last read    |
-| updated_at  | string  | Yes      | ISO 8601 timestamp                 |
+| Field | Type | Required | Description |
+| ----- | ---- | -------- | ----------- |
+| `uuid` | string (UUID) | No | Bookhoard UUID, once the device has linked the book via [Resolve Book](resolve_book.md). |
+| `sha256` | string | Yes | File content hash (64 hex chars) — the primary book identity. |
+| `title` | string | No | Document title. |
+| `authors` | array | No | Author names. |
+| `percentage` | float | Yes | Position as a fraction of the book (0..1). |
+| `context_text` | string | No | Up to 100 whitespace-normalized chars from the current position — enables the server's verification/healing. Strongly recommended. |
+| `page` | int | No | Current page (fixed-layout books). |
+| `total_pages` | int | No | Page count (fixed-layout books). |
+| `epubcfi` | string | Reflowable only | **A CRE xpointer** (`/body/DocFragment[N]/body/...`), not a CFI — the field name is historical. Fixed-layout books must omit it and carry their position in `page`/`total_pages`. |
+| `file_path` | string | No | Device-local file path (informational). |
+| `device_info` | object | No | `{ koreader_version, device_model }`. |
 
 ### Example Request
 
+```http
+POST /api/sync/koreader/progress
+Authorization: Bearer {device_token}
+Content-Type: application/json
+```
+
 ```json
 {
-  "device_id": "550e8400-e29b-41d4-a716-446655440000",
-  "progress": [
+  "books": [
     {
-      "book": "book.epub",
-      "percent": 75.5,
-      "page": 150,
-      "total_pages": 200,
-      "date_read": "2026-02-08T10:00:00Z",
-      "updated_at": "2026-02-08T10:00:00Z"
+      "uuid": "774641f9-317b-4087-8e04-53bb4392ae56",
+      "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
+      "title": "1984",
+      "authors": ["George Orwell"],
+      "percentage": 0.045,
+      "context_text": "from day to day, but there was none in which Goldstein was not the principal figure. He was the prim",
+      "page": 14,
+      "total_pages": 311,
+      "epubcfi": "/body/DocFragment[1]/body/p[29]/text().598",
+      "device_info": {
+        "koreader_version": "v2026.07.1",
+        "device_model": "emulator"
+      }
     }
-  ]
+  ],
+  "sync_mode": "immediate"
 }
 ```
 
-## Response (200 OK)
+## Response (202 Accepted)
 
 ```json
 {
-  "message": "Progress synced successfully",
-  "synced_count": 1
+  "sync_status": "ok",
+  "books_synced": 1,
+  "timestamp": "2026-09-26T21:25:09Z"
 }
 ```
 
+Per-book results and any detected sync conflicts are carried in
+`book_results` and `conflicts` when present.
+
 ## Error Responses
 
-| Code | Description                  |
-| ---- | ---------------------------- |
+| Code | Description |
+| ---- | ----------- |
+| 400  | Invalid request format |
 | 401  | Device authentication failed |
-| 400  | Invalid request data         |
-| 404  | Device not found             |
+| 500  | Database error |

docs/developer/api/progress/delete_media_progress.md

@@ -0,0 +1,35 @@
+# Delete Media Item Progress
+
+Delete the stored reading progress for a media item.
+
+**Endpoint**: `DELETE /api/media-items/:id/progress`
+**Auth**: Required (Bearer token)
+
+## Path Parameters
+
+| Parameter | Type          | Required | Description     |
+| --------- | ------------- | -------- | ---------------- |
+| id        | string (UUID) | Yes      | Media item UUID |
+
+### Example Request
+
+```http
+DELETE /api/media-items/774641f9-317b-4087-8e04-53bb4392ae56/progress
+Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
+```
+
+## Response (200 OK)
+
+```json
+{
+  "message": "reading progress deleted"
+}
+```
+
+## Error Responses
+
+| Code | Description |
+| ---- | ----------- |
+| 400  | Invalid media item id |
+| 401  | Invalid or expired token |
+| 500  | Database error |

docs/developer/api/progress/delete_progress.md

@@ -1,36 +0,0 @@
-# Delete Reading Progress
-
-Delete reading progress for a media item.
-
-**Endpoint**: `DELETE /api/media-items/{media_id}/progress`
-**Auth**: Required
-
-## Path Parameters
-
-| Parameter | Type   | Required | Description     |
-| --------- | ------ | -------- | --------------- |
-| media_id  | string | Yes      | Media item UUID |
-
-## Request Headers
-
-| Header        | Type   | Required | Description  |
-| ------------- | ------ | -------- | ------------ |
-| Authorization | string | Yes      | Bearer token |
-
-### Example Request
-
-```http
-DELETE /api/media-items/uuid/progress
-Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
-```
-
-## Response (204 No Content)
-
-Progress deleted successfully.
-
-## Error Responses
-
-| Code | Description              |
-| ---- | ------------------------ |
-| 401  | Invalid or expired token |
-| 404  | Media item not found     |

docs/developer/api/progress/get_media_progress.md

@@ -0,0 +1,98 @@
+# Get Media Item Progress
+
+Get the stored reading progress for a media item, plus the
+server-derived restore handles for reflowable books.
+
+**Endpoint**: `GET /api/media-items/:id/progress`
+**Auth**: Required (Bearer token)
+
+See [Position Contract](position-contract.md) for the semantics of every
+field — what is verified, what the currencies are, and how clients
+should restore.
+
+## Path Parameters
+
+| Parameter | Type          | Required | Description     |
+| --------- | ------------- | -------- | --------------- |
+| id        | string (UUID) | Yes      | Media item UUID |
+
+### Example Request
+
+```http
+GET /api/media-items/774641f9-317b-4087-8e04-53bb4392ae56/progress
+Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
+```
+
+## Response (200 OK) — no progress stored
+
+When the item has no progress row, an empty fixed-layout-style stub is
+returned (not 404):
+
+```json
+{
+  "current_page": 0,
+  "total_pages": null
+}
+```
+
+## Response (200 OK) — progress stored
+
+```json
+{
+  "id": "e8239659-0ed6-42ae-a946-8440d7655b42",
+  "media_item_id": "774641f9-317b-4087-8e04-53bb4392ae56",
+  "user_id": "1b64992e-3408-4d84-9e03-e2dc4950e1dd",
+  "current_page": null,
+  "total_pages": null,
+  "last_read_at": "2026-09-26T14:52:34.806446Z",
+  "percentage": 0.045,
+  "character_offset": 16375,
+  "epubcfi": "epubcfi(/6/4!/4/8[_idContainer003]/58/1:598)",
+  "chapter": null,
+  "chapter_progress": null,
+  "format_group": "reflowable",
+  "total_characters": 592216,
+  "chapter_count": 1,
+  "last_sync_device": "web",
+  "last_sync_source": "koreader",
+  "last_sync_timestamp": "2026-09-26T14:52:34.806446Z",
+  "css_selector": "body>div:nth-child(4)>p:nth-child(29)",
+  "anchor_href": "1984.xhtml",
+  "char_offset": 598,
+  "context_text": "from day to day, but there was none in which Goldstein was not the principal figure. He was the prim"
+}
+```
+
+### Field Reference
+
+Base fields (always present when a row exists):
+
+| Field | Type | Description |
+| ----- | ---- | ----------- |
+| `percentage` | float | Position as a fraction of the whole book (0..1). |
+| `epubcfi` | string | The stored canonical standard CFI. **Spine steps index the OPF spine as written, including `linear="no"` items — do not resolve them against a readium reading order.** See the [Position Contract](position-contract.md#spine-numbering-hazard--read-this-before-parsing-a-stored-cfi). |
+| `context_text` | string | The stored verification context (≤100 whitespace-normalized chars from the anchor). |
+| `character_offset` | int | Book-wide rune offset. Internal currency — consistent with `total_characters`. |
+| `current_page`, `total_pages` | int | Fixed-layout page position (null for reflowable). |
+| `chapter`, `chapter_progress` | int, float | Chapter index and within-chapter fraction, when known. |
+| `format_group` | string | `reflowable`, `fixed_layout`, `comic_archive`, … Gates the restore handles. |
+| `total_characters`, `chapter_count` | int | Book metrics, for client-side fraction math. |
+| `last_sync_device`, `last_sync_source`, `last_sync_timestamp` | — | Which client last wrote the row. |
+
+Restore handles (conditional — served only for convertible reflowable
+books whose stored anchor re-resolves at GET time):
+
+| Field | Type | Description |
+| ----- | ---- | ----------- |
+| `anchor_href` | string | The spine document containing the anchor (e.g. `1984.xhtml`). **Resolve your resource by this**, never by the CFI's spine step. |
+| `css_selector` | string | Body-relative chain to the anchor's block element. |
+| `char_offset` | int | Anchor offset within the block's concatenated text, in UTF-16 code units. |
+| `epubcfi` | string | Re-served (possibly healed) canonical CFI — present whenever re-verification produced one. |
+
+## Error Responses
+
+| Code | Description |
+| ---- | ----------- |
+| 400  | Invalid media item id |
+| 401  | Invalid or expired token |
+| 500  | Database error |

docs/developer/api/progress/get_progress.md

@@ -1,52 +0,0 @@
-# Get Reading Progress
-
-Retrieve reading progress for a specific media item.
-
-**Endpoint**: `GET /api/media-items/{media_id}/progress`
-**Auth**: Required
-
-## Path Parameters
-
-| Parameter | Type   | Required | Description     |
-| --------- | ------ | -------- | --------------- |
-| media_id  | string | Yes      | Media item UUID |
-
-## Request Headers
-
-| Header        | Type   | Required | Description  |
-| ------------- | ------ | -------- | ------------ |
-| Authorization | string | Yes      | Bearer token |
-
-### Example Request
-
-```http
-GET /api/media-items/uuid/progress
-Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
-```
-
-## Response (200 OK)
-
-```json
-{
-  "media_item_id": "uuid",
-  "user_id": "uuid",
-  "current_page": 45,
-  "total_pages": 200,
-  "percentage": 0.225,
-  "character_offset": 15432,
-  "epubcfi": "epubcfi(/6/4/2:15)",
-  "chapter": 3,
-  "chapter_progress": 0.5,
-  "last_read_at": "2026-01-31T10:00:00Z",
-  "format_group": "reflowable",
-  "viewport_y": 0.12,
-  "zoom_level": 1.0
-}
-```
-
-## Error Responses
-
-| Code | Description              |
-| ---- | ------------------------ |
-| 401  | Invalid or expired token |
-| 404  | Media item not found     |

docs/developer/api/progress/get_universal_progress.md

@@ -1,50 +0,0 @@
-# Get Universal Progress
-
-Get universal (device-agnostic) reading progress for a media item.
-
-**Endpoint**: `GET /api/progress/:id`
-**Auth**: Required
-
-## Path Parameters
-
-| Parameter | Type          | Required | Description     |
-| --------- | ------------- | -------- | --------------- |
-| id        | string (UUID) | Yes      | Media item UUID |
-
-## Request Headers
-
-| Header        | Type   | Required | Description  |
-| ------------- | ------ | -------- | ------------ |
-| Authorization | string | Yes      | Bearer token |
-
-### Example Request
-
-```http
-GET /api/progress/550e8400-e29b-41d4-a716-446655440000
-Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
-```
-
-## Response (200 OK)
-
-```json
-{
-  "media_item_id": "uuid",
-  "percentage": 75.5,
-  "position": 1234,
-  "page": 150,
-  "total_pages": 200,
-  "finished": false,
-  "updated_at": "2026-02-08T10:00:00Z",
-  "device": {
-    "id": "device-uuid",
-    "name": "My Kobo"
-  }
-}
-```
-
-## Error Responses
-
-| Code | Description              |
-| ---- | ------------------------ |
-| 401  | Invalid or expired token |
-| 404  | Media item not found     |

docs/developer/api/progress/position-contract.md

@@ -0,0 +1,135 @@
+# Position Contract
+
+How reading positions are represented, submitted, verified, and restored
+across clients. This is the contract every client speaks — readium-based
+apps, web (foliate), KOReader, and Kobo devices alike.
+
+**The server is the position authority.** Every submission is
+independently verified against the book itself before it is stored; a
+client whose locator math is wrong cannot poison the stored position.
+In exchange, the server hands back handles clients can apply directly,
+so they never have to parse or trust CFIs themselves.
+
+## The three-tier submission
+
+Clients submit what their renderer can reliably observe. All three tiers
+are accepted on `PUT /api/media-items/:id/progress` (and on the KOReader
+device endpoints):
+
+| Tier   | Field          | Currency                                              | Notes |
+| ------ | -------------- | ----------------------------------------------------- | ----- |
+| 1      | `percentage`   | Float 0..1 of the whole book                          | Universal. The only field every client can supply. |
+| 2      | `context_text` | Up to 100 chars, whitespace-normalized, starting at the anchor | The verification anchor. The server extracts the text at the submitted structural anchor and compares. |
+| 3      | `epubcfi`      | Standard wrapped CFI, terminals in UTF-16 code units  | Optional structural anchor. KOReader submits a CRE xpointer and the server converts it. |
+
+Tier 2 is what makes the system self-correcting: percentages alone
+cannot distinguish "the reader's locator is right" from "the reader
+silently reported wherever it is currently scrolled".
+
+## Verification and healing (ingest side)
+
+On every progress save for a convertible reflowable book that carries a
+`context_text`, the server:
+
+1. Parses the submitted `epubcfi` (if any) and resolves it against the
+   book's own XHTML.
+2. Extracts the text at the resolved anchor and cross-checks it with the
+   submitted `context_text`.
+3. On a mismatch — or an unresolvable anchor, or no anchor at all —
+   heals the position by text search, using the submitted `percentage`
+   to disambiguate repeated phrases. The healed CFI and a recomputed
+   percentage are stored in place of the submitted ones.
+4. Refreshes the book-wide `character_offset` column from the verified
+   anchor on every verified save, so it never goes stale behind the
+   anchor.
+
+If verification fails outright (book file unreadable, context not found
+and percentage cannot disambiguate), the error is logged and the
+submission is stored as-is — verification never rejects a save, it only
+corrects.
+
+## The restore handles
+
+`GET /api/media-items/:id/progress` serves, alongside the raw stored
+fields, the server-derived handles for reflowable books with a
+resolvable anchor:
+
+| Field         | Currency                | Meaning |
+| ------------- | ----------------------- | ------- |
+| `anchor_href` | —                       | The spine document the anchor lives in (e.g. `1984.xhtml`). **This is how a client finds the right resource.** |
+| `css_selector`| —                       | Body-relative `tag:nth-child(k)` chain of the anchor's block element (e.g. `body>div:nth-child(4)>p:nth-child(29)`). |
+| `char_offset` | UTF-16 code units       | Offset of the anchor within the concatenated text of that block. |
+| `epubcfi`     | UTF-16 terminals        | The stored canonical CFI — re-served healed if the GET-time re-verification improved it. |
+| `context_text`| —                       | The stored verification context (≤100 normalized chars from the anchor). |
+
+**Recommended restore sequence for a client:**
+
+1. Open the book and jump to the stored `percentage` (coarse floor).
+2. Resolve `anchor_href` against your own spine (an ends-with match on
+   document hrefs) and open that document if you are not already there.
+3. Query `css_selector` in that document, walk its text nodes counting
+   UTF-16 units to `char_offset`, and scroll that position into view.
+4. If the anchor cannot be measured (renderer-specific laziness), the
+   percentage floor stands.
+
+## SPINE NUMBERING HAZARD — read this before parsing a stored CFI
+
+**`epubcfi` spine steps index the OPF spine AS WRITTEN, including
+`linear="no"` items.** Several rendering engines (notably readium)
+number their reading order EXCLUDING `linear="no"` items. When a book's
+cover (or any other item) is `linear="no"`, the two numberings differ by
+a constant offset from that item onward — a client resolving a stored
+CFI's spine step against its own numbering lands in the WRONG DOCUMENT.
+
+This is not hypothetical: "1984" epubs commonly have a `linear="no"`
+cover, which makes readium spine 0 = OPF spine 1. The server heals such
+numbering mismatches at ingest (that is what the context check is for),
+but the durable rule for client authors is:
+
+> **Never resolve a stored CFI's spine step yourself.** Resolve the
+> document by `anchor_href`, then land with `css_selector` +
+> `char_offset`. Treat the CFI as opaque server currency.
+
+## Offset currencies
+
+Two counting systems are in play, and they are deliberately kept apart:
+
+| Quantity | Currency | Why |
+| -------- | -------- | --- |
+| CFI terminal offsets (`…/1:456`) | UTF-16 code units | The EPUB CFI spec, and what every client observes (JavaScript `.length`). |
+| `char_offset` (block-relative handle) | UTF-16 code units | Same reason — clients walk DOM text with JS semantics. |
+| KOReader CRE `text().N` offsets | UTF-16 code units | crengine is UCS-16 internally. |
+| `character_offset` (book-wide column) | Unicode runes | Internal, consistent with `total_characters` and the percentage derivations. |
+
+For all-BMP text the two currencies are identical. They diverge on
+astral-plane characters (emoji, rare CJK ideographs): one rune, two
+UTF-16 units. The server converts at every wire boundary; internal
+arithmetic never crosses.
+
+## `context_text` rules
+
+- Starts at the anchor position (it may begin mid-word).
+- Whitespace-normalized (all runs of whitespace collapse to single
+  spaces).
+- At most 100 characters.
+- Comparison is containment-based (client and server suffixes of the
+  same block verify in either direction); contexts shorter than 12
+  chars never match.
+
+## Engine-specific notes
+
+- **readium-based clients** (the Android app): submit
+  percentage + `context_text` + a CFI generated from the laid-out
+  WebView. Their locally-generated CFI spine steps use readium
+  numbering — the server heals the difference; nothing to do.
+- **Web (foliate)**: submit all three tiers; foliate CFIs are the same
+  currency the server stores.
+- **KOReader**: submits a CRE xpointer in the `epubcfi` field of the
+  device payload (historical field name; it is a CRE xpointer, not a
+  CFI). The server converts CRE → canonical at ingest and canonical →
+  CRE on pull (`koreader_xpointer` in the metadata response).
+- **Kobo**: submits kepub CFI locators, converted server-side the same
+  way.
+- **Fixed-layout content** (PDF/CBZ): the page index is the canonical
+  locator; CFI/xpointer are meaningless and neither submitted nor
+  served.

docs/developer/api/progress/update_media_progress.md

@@ -0,0 +1,91 @@
+# Update Media Item Progress
+
+Submit reading progress for a media item. This is the position-authority
+ingest point: the server independently verifies the submission against
+the book and heals it when the client's projection is wrong.
+
+**Endpoint**: `PUT /api/media-items/:id/progress`
+**Auth**: Required (Bearer token)
+**Content-Type**: `application/json`
+
+See the [Position Contract](position-contract.md) for the three-tier
+submission model, the verification/healing semantics, and the offset
+currencies.
+
+## Path Parameters
+
+| Parameter | Type          | Required | Description     |
+| --------- | ------------- | -------- | ---------------- |
+| id        | string (UUID) | Yes      | Media item UUID |
+
+## Request Body
+
+All fields are optional; submit what your renderer can observe.
+
+| Field | Type | Description |
+| ----- | ---- | ----------- |
+| `percentage` | float | Position as a fraction of the whole book (0..1). Tier 1 — the universal field. |
+| `context_text` | string | Up to 100 whitespace-normalized chars starting at the anchor. Tier 2 — enables verification and healing. |
+| `epubcfi` | string | Standard wrapped CFI (UTF-16 terminals). Tier 3 — the structural anchor. Note: the server re-derives the stored canonical CFI; a client's own spine numbering is healed if it disagrees with the OPF spine. |
+| `character_offset` | int | Book-wide rune offset. Accepted but recomputed server-side from the verified anchor on every verified save. |
+| `current_page`, `total_pages` | int | Fixed-layout position. For fixed-layout formats the page index is the canonical locator. |
+| `chapter`, `chapter_progress` | int, float | Chapter index and within-chapter fraction. |
+| `reading_mode` | string | `paged` or `scrolled` (fixed-layout reader state). |
+| `zoom_level`, `scroll_position_x`, `scroll_position_y` | float | Fixed-layout viewport state. |
+
+### Example Request (reflowable, all three tiers)
+
+```http
+PUT /api/media-items/774641f9-317b-4087-8e04-53bb4392ae56/progress
+Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
+Content-Type: application/json
+```
+
+```json
+{
+  "percentage": 0.0415,
+  "context_text": "was at war with one of these Powers it was generally at peace with the other. But what was strange w",
+  "epubcfi": "epubcfi(/6/4!/4/8[_idContainer003]/62/1:456)"
+}
+```
+
+### Example Request (fixed-layout)
+
+```json
+{
+  "percentage": 0.15,
+  "current_page": 30,
+  "total_pages": 194,
+  "reading_mode": "paged"
+}
+```
+
+## Behavior
+
+- The submission is verified against the book's XHTML when
+  `context_text` is present and the book is convertible reflowable: the
+  CFI is resolved, the text at the anchor is compared with
+  `context_text`, and mismatches heal by text search (percentage
+  disambiguates repeats). See [Position Contract](position-contract.md).
+- **Anti-clobber guard**: a submission with `percentage < 0.005` is
+  ignored with `{"status": "ignored"}` when the stored row already holds
+  a percentage above `0.01` — re-opening a book at its first page does
+  not wipe real progress.
+- The response is the stored row after verification, including the
+  healed `epubcfi` and the refreshed `character_offset` when
+  verification ran.
+
+## Response (200 OK)
+
+The saved progress row (same shape as
+[GET](get_media_progress.md), minus the GET-time handles). The
+`epubcfi` and `percentage` in the response are the server-verified
+values, which may differ from the submitted ones when healing occurred.
+
+## Error Responses
+
+| Code | Description |
+| ---- | ----------- |
+| 400  | Invalid request data |
+| 401  | Invalid or expired token |
+| 500  | Database error |

docs/developer/api/progress/update_progress.md

@@ -1,68 +0,0 @@
-# Update Reading Progress
-
-Update reading progress for a media item. This will sync across all devices via WebSocket.
-
-**Endpoint**: `PUT /api/media-items/{media_id}/progress`
-**Auth**: Required
-**Content-Type**: `application/json`
-
-## Path Parameters
-
-| Parameter | Type   | Required | Description     |
-| --------- | ------ | -------- | --------------- |
-| media_id  | string | Yes      | Media item UUID |
-
-## Request Body
-
-| Field                       | Type    | Required | Description                                       |
-| --------------------------- | ------- | -------- | ------------------------------------------------- |
-| source                      | string  | Yes      | Progress source (e.g., "web", "koreader", "kobo") |
-| location                    | object  | Yes      | Location information                              |
-| location.percentage         | float   | No       | Progress percentage (0-1)                         |
-| location.epubcfi            | string  | No       | EPUB CFI location                                 |
-| location.character          | integer | No       | Character offset                                  |
-| location.chapter            | integer | No       | Chapter number                                    |
-| location.page               | integer | No       | Current page                                      |
-| location.total_pages        | integer | No       | Total pages                                       |
-| device_metadata             | object  | No       | Device metadata                                   |
-| device_metadata.device_type | string  | No       | Device type                                       |
-| device_metadata.user_agent  | string  | No       | User agent string                                 |
-
-### Example Request
-
-```json
-{
-  "source": "web",
-  "location": {
-    "percentage": 0.45678,
-    "epubcfi": "epubcfi(/6/4/2:15)",
-    "character": 15432,
-    "chapter": 3,
-    "page": 89,
-    "total_pages": 200
-  },
-  "device_metadata": {
-    "device_type": "web",
-    "user_agent": "Mozilla/5.0..."
-  }
-}
-```
-
-## Response (200 OK)
-
-```json
-{
-  "sync_status": "success",
-  "progress_updated": true,
-  "devices_notified": ["device-1", "device-2"],
-  "broadcast": true
-}
-```
-
-## Error Responses
-
-| Code | Description              |
-| ---- | ------------------------ |
-| 400  | Invalid location data    |
-| 401  | Invalid or expired token |
-| 404  | Media item not found     |

docs/developer/api/progress/update_universal_progress.md

@@ -1,56 +0,0 @@
-# Update Universal Progress
-
-Update universal reading progress for a media item.
-
-**Endpoint**: `POST /api/progress/:id`
-**Auth**: Required
-**Content-Type**: `application/json`
-
-## Path Parameters
-
-| Parameter | Type          | Required | Description     |
-| --------- | ------------- | -------- | --------------- |
-| id        | string (UUID) | Yes      | Media item UUID |
-
-## Request Body
-
-| Field      | Type          | Required | Description                                 |
-| ---------- | ------------- | -------- | ------------------------------------------- |
-| percentage | float         | No       | Progress percentage (0-100)                 |
-| position   | integer       | No       | Current position in bytes                   |
-| page       | integer       | No       | Current page number                         |
-| finished   | boolean       | No       | Whether the book is finished                |
-| device_id  | string (UUID) | No       | Device UUID (optional, for tracking source) |
-
-### Example Request
-
-```json
-{
-  "percentage": 75.5,
-  "position": 1234,
-  "page": 150,
-  "finished": false,
-  "device_id": "device-uuid"
-}
-```
-
-## Response (200 OK)
-
-```json
-{
-  "media_item_id": "uuid",
-  "percentage": 75.5,
-  "position": 1234,
-  "page": 150,
-  "finished": false,
-  "updated_at": "2026-02-08T10:00:00Z"
-}
-```
-
-## Error Responses
-
-| Code | Description              |
-| ---- | ------------------------ |
-| 400  | Invalid request data     |
-| 401  | Invalid or expired token |
-| 404  | Media item not found     |

docs/developer/api/scanner/overview.md

@@ -30,10 +30,15 @@ The Bookhoard scanner provides comprehensive library management for ebooks, comi
 | -------- | ------------------------ |
 | EPUB     | `.epub`                  |
 | PDF      | `.pdf`                   |
-| Kindle   | `.mobi`, `.azw`, `.azw3` |
+| Kindle   | `.mobi`                  |
 | Text     | `.txt`, `.rtf`           |
-| Document | `.doc`, `.docx`          |
-| Other    | `.lit`, `.fb2`, `.pdb`   |
+| Document | `.docx`                  |
+| Other    | `.fb2`, `.pdb`           |
+
+DOC (Word 97-2003 binary) and LIT (Microsoft Reader) are deliberately
+unsupported: no credible JavaScript parser exists for either, and
+compromising on fidelity is against the project's format goals. Files
+with these extensions are not scanned.
 
 ### Comics
 

docs/developer/api/scanner/scan_library.md

@@ -18,7 +18,7 @@ Initiate a one-time scan of a library for ebooks, manga, or comics.
 
 The scanner automatically detects and processes files based on the library type:
 
-**Ebooks:** .epub, .pdf, .mobi, .azw, .azw3, .txt, .rtf, .doc, .docx, .lit, .fb2, .pdb
+**Ebooks:** .epub, .pdf, .mobi, .txt, .rtf, .docx, .fb2, .pdb
 
 **Comics:** .cbz, .cbr, .cb7, .cbt, .pdf
 

docs/developer/development.md

@@ -73,6 +73,12 @@ Browse individual endpoint documentation with interactive API Explorer:
 
 ## 🛠 Implementation Guides
 
+### Library Visibility
+
+- **[Library Visibility](library-visibility.md)** - Per-user library
+  visibility: the family-lens rule. New media endpoints MUST thread the
+  visible-library set (helpers, SQL pattern, series per-library).
+
 ### Calibre Integration
 
 - **[Calibre OPF Implementation](../development/calibre-opf-implementation.md)** - Technical implementation details

docs/developer/library-visibility.md

@@ -0,0 +1,54 @@
+# Library Visibility (family-lens rule)
+
+Every endpoint that returns media metadata or content must respect
+per-user **library visibility**: the `library_visibility` table maps
+`(user_id, library_id, is_visible)` and defaults to **ALLOW** — every
+user sees every library unless an admin explicitly hides one from them.
+The point of the system is the family case: an admin hides the adult
+library from a child's account, and no trace of that library (titles,
+covers, series, page images) may reach the child's account.
+
+## The rule for new endpoints
+
+Any endpoint that lists, filters, or details media/series/books:
+
+1. Filter by the requesting user's visible-library set.
+2. Reject an explicit `library_id` outside that set with **403** —
+   never silently ignore or fall back.
+3. Content endpoints (file bytes, page images) gate per item, like
+   `ReaderHandler.ensureItemVisible`.
+
+If you forget, hidden libraries leak. This exact leak shipped: the
+series endpoints were name-only across ALL libraries and the PDF
+thumbnail endpoint served page images of hidden books (fixed 2026-10-13,
+bookhoard `431fec0`).
+
+## Helpers — do not hand-roll
+
+- `(*MediaHandler).visibleLibrarySet` /
+  `(*SeriesHandler).visibleLibrarySet` — returns a membership map plus
+  the id slice (map for param checks, slice for SQL `ANY()`).
+- `router.visibleLibraryIDsFor` — same for SSR routes.
+- `resolveLibrary` (router/helpers.go) only honors a requested
+  `library_id` that is inside the caller's visible set.
+- SQL pattern (see `ListMediaItems`, `GetDistinctSeries`,
+  `SearchMediaItems`):
+
+```sql
+AND (sqlc.narg('visible_library_ids')::uuid[] IS NULL
+     OR library_id = ANY(sqlc.narg('visible_library_ids')::uuid[]))
+```
+
+## Known-safe surfaces
+
+- OPDS device catalogs filter by the device owner's visible libraries.
+- Search (`SearchMediaItems`) is visibility-scoped.
+- File download, reader page render, and page content gate per item.
+
+## Series are per-library
+
+Series are grouped by `(library_id, series)` — the same series name in
+two libraries is two entries (manga adaptations, LN splits). Do not
+re-merge them cross-library. `/api/series/books` REQUIRES a visible
+`library_id`; `/api/series` without one aggregates only the caller's
+visible libraries.

docs/index.md

@@ -63,7 +63,7 @@ Complete guide to Bookhoard documentation. Find what you need quickly.
 **[Contributing Portal](contributing/contributing.md)** - Development workflow
 
 - [Development Guide](contributing/development.md) - Architecture, setup, testing
-- [../PROJECT_GUIDELINES.md](../PROJECT_GUIDELINES.md) - Development rules and standards
+- [../../AGENTS.md](../../AGENTS.md) - Development rules and standards
 
 ---
 
@@ -77,6 +77,7 @@ Complete guide to Bookhoard documentation. Find what you need quickly.
 | **Deploy Bookhoard** | [Operations Portal → Troubleshooting](operations/troubleshooting.md)   |
 | **Contribute code**  | [Contributing Portal → Development Guide](contributing/development.md) |
 | **Understand sync**  | [User Portal → Sync Guide](user/sync-guide.md)                         |
+| **Read in the browser** | [User Portal → Web Reader Guide](user/reader-guide.md)              |
 
 ---
 
@@ -90,6 +91,7 @@ Complete guide to Bookhoard documentation. Find what you need quickly.
 | ...set up KOReader?         | [KOReader Setup Guide](user/devices/koreader-setup.md) |
 | ...use a Kobo?              | [Kobo Setup Guide](user/devices/kobo-setup.md) - native sync coming soon; KOReader works today |
 | ...understand sync?         | [Sync Guide](user/sync-guide.md)                       |
+| ...read in the browser?     | [Web Reader Guide](user/reader-guide.md) - reading, highlights, notes |
 | ...resolve conflicts?       | [Sync Guide](user/sync-guide.md) - Managing Conflicts  |
 | ...troubleshoot deployment? | [Troubleshooting Guide](operations/troubleshooting.md) |
 | ...use the API?             | [API Reference](developer/api-reference.md)            |
@@ -141,7 +143,7 @@ When adding new features:
 3. **Backend changes** → Update [Development Guide](contributing/development.md)
 4. **Deployment changes** → Update [Operations Portal](operations/operations.md)
 
-Keep [../PROJECT_GUIDELINES.md](../PROJECT_GUIDELINES.md) in mind for documentation standards.
+Keep [../../AGENTS.md](../../AGENTS.md) in mind for documentation standards.
 
 ---
 

docs/user/calibre-integration.md

@@ -124,7 +124,7 @@ The following Calibre metadata is **not** imported (by design):
 
 Bookhoard imports Calibre metadata for **all file types**:
 
-- 📚 **Ebooks**: EPUB, MOBI, AZW3, PDF, TXT, etc.
+- 📚 **Ebooks**: EPUB, MOBI, PDF, TXT, etc.
 - 🎧 **Audiobooks**: MP3, M4B, M4A, etc.
 - 📰 **Comics**: CBZ, CBR, CB7, CBT, etc.
 - 📄 **Documents**: PDF, DOCX, etc.

docs/user/devices/android-app.md

@@ -0,0 +1,43 @@
+# Android App Setup Guide
+
+The Bookhoard Android app is the native mobile client: browse your libraries, read EPUBs, PDFs, comics and manga, and sync progress, highlights, bookmarks and notes with the server.
+
+## Prerequisites
+
+- ✅ A Bookhoard instance running and reachable from your phone's network
+- ✅ The Bookhoard APK installed on your phone (Android 8.0+ / API 26+)
+- ✅ Your phone connected to the same network as the server (for a self-hosted LAN setup)
+
+## Installing the app
+
+The app is distributed as a sideloaded APK:
+
+1. Copy the APK to your phone (USB, or any file-sync you trust)
+2. Tap the APK to install — approve the "install unknown apps" prompt for the app you installed from (file manager, browser, etc.)
+3. Upgrades install straight over the existing app and keep your data (login, downloads, reading state)
+
+## First run
+
+1. **Server URL** — enter your server's address. For a self-hosted LAN setup that is `http://<desktop-LAN-IP>:8765` (plain HTTP is expected here and fully supported; check the server machine's firewall allows port 8765 from your LAN)
+2. **Log in** with your Bookhoard account
+3. **Device registration** happens automatically — the app registers itself as a synced device so progress and annotations sync under your account
+
+## Android 16+: the local-network permission
+
+On Android 16 and newer, apps need explicit permission to talk to devices on your local network (and to non-HTTPS local addresses in general). **If the permission is missing, the app's logins to a LAN server time out with no visible cause** — the phone silently drops the traffic.
+
+- The app **asks for the permission by itself** during setup, as soon as you enter a local server address — grant it when prompted
+- If it was denied (or you missed the prompt): **Settings → Apps → Bookhoard → Permissions → "Access local network devices" → Allow**, then try again
+- Servers reached over the public internet (HTTPS) are not affected by this permission
+
+## Troubleshooting login failures
+
+The login screen prints the underlying error after "Could not reach server: …" — read it to narrow the cause:
+
+| Error | Meaning | What to check |
+|---|---|---|
+| `SocketTimeoutException` | The phone sent nothing that reached the server | On Android 16+ this is most often the **local-network permission** (above). Otherwise: wrong IP, phone on a different network/VLAN, or server down |
+| `ConnectException` (connection refused/blocked) | The phone reached the machine but nothing answered | Server container down, or a firewall rejecting port 8765 |
+| `UnknownHostException` | The hostname didn't resolve | Typo in the server URL, or a DNS/name issue (raw IPs avoid this) |
+
+To verify the server is reachable from the phone at all, open the same URL in the phone's browser — the browser is not subject to the per-app local-network permission, so if the browser works but the app times out on Android 16+, it is the permission.

docs/user/reader-guide.md

@@ -0,0 +1,81 @@
+# Web Reader Guide
+
+Bookhoard's built-in web reader works in any modern browser — desktop or
+mobile — and keeps your position, highlights, bookmarks, and notes in sync
+with the Android app and KOReader.
+
+## Opening a Book
+
+From your library or book page, click **Read**. The reader opens in an
+immersive view with the book's cover, title, and chapter in the top bar
+(EPUB) or page number (PDF/comics).
+
+## Navigation
+
+### On a phone or tablet (touch)
+
+| Gesture | Action |
+|---|---|
+| **Swipe** left / right | Turn the page |
+| **Tap** once | Toggle the reader menu (headers, settings, drawers) |
+| **Tap** in a corner zone | With the menu open: jump back / forward by chapter |
+
+Paging is swipe-only by design: taps are reserved for the menu so a page
+turn can never fire while you're trying to select text.
+
+### On desktop
+
+- Scroll wheel, trackpad, arrow keys, or **Page Up / Page Down** to page
+- Click the progress bar (bottom, with the menu open) to jump
+- Contents drawer for the table of contents; Pages grid for PDF/comics
+
+## Text Selection & Highlights
+
+### Selecting text (touch)
+
+1. **Press and hold** a word (~half a second) until it highlights
+2. **Drag** to extend the selection word by word — it stays on the
+   visible page
+3. **Drag the round handles** (EPUB) to fine-tune the start and end
+   points
+4. Lift your finger and pause — the highlight menu appears **below** the
+   selection, underneath the browser's own copy menu
+
+The browser's address bar hides while a selection is active to give the
+page room; it returns as soon as the selection is cleared.
+
+### Creating a highlight or note
+
+With the selection menu open:
+
+- **Color dots** — tap one to highlight immediately in that color
+- **Pencil** — opens a note; write it and tap **Highlight with note**
+  to save the highlight and its note together
+- **Copy** — copies the selected text (works even over plain HTTP on
+  your LAN)
+- While the note editor is open, you can still change the color — the
+  popover stays put until you save or cancel
+
+### Editing or removing a highlight
+
+Tap anywhere on a painted highlight to reopen it in the menu. From there
+you can change its color, edit the note (pencil → **Save note**), or
+delete it (trash icon). Tapping anywhere else closes the menu.
+
+### PDFs and comics
+
+Text selection works the same way on PDFs. Highlights are stored as
+page-anchored rectangles and sync to the Android app. Comics/manga
+libraries disable annotation (bookmarks still work).
+
+## Notes & Bookmarks
+
+The **annotations drawer** (right side, from the open menu) lists your
+highlights, standalone notes, and bookmarks for the book — tap any entry
+to jump to it.
+
+## Where Reading Position Is Stored
+
+Position, highlights, bookmarks, and notes sync automatically through the
+server (see the [Sync Guide](sync-guide.md)). Close the tab whenever you
+like — the reader resumes exactly where you left off on any device.

docs/user/user-guide.md

@@ -6,6 +6,12 @@ Welcome to the Bookhoard user documentation. This section contains guides for us
 
 Learn how to configure your e-reader devices to sync with Bookhoard:
 
+- **[Android App Guide](devices/android-app.md)** - The native Android client
+  - Installing and upgrading the APK
+  - Connecting to a self-hosted server over LAN
+  - The Android 16+ local-network permission
+  - Troubleshooting login failures
+
 - **[KOReader Setup Guide](devices/koreader-setup.md)** - Complete guide for KOReader
   - Installation on Kindle/Kobo/PocketBook
   - Plugin setup with server-side device approval
@@ -36,6 +42,14 @@ Learn how to configure your e-reader devices to sync with Bookhoard:
   - Troubleshooting
   - Best practices
 
+## 📖 Reading
+
+- **[Web Reader Guide](reader-guide.md)** - Reading and annotating in the browser
+  - Touch navigation (swipe to page, tap for menu)
+  - Selecting text: long-press, drag, handles
+  - Highlights, notes, copy, and editing
+  - PDFs and comics
+
 ## 🎨 Frontend Guide
 
 **[Frontend Guide](frontend-guide.md)** - Learn how to use the Bookhoard web interface

go.sum

@@ -1,5 +1,7 @@
 github.com/ArcadiaLin/go-epub v0.1.1 h1:13roe62tarrZ1Y1QTxE+Bzd/NKlChhRzegLVmU5Hgws=
 github.com/ArcadiaLin/go-epub v0.1.1/go.mod h1:GY09AG6jnEbsYytkw6VeICLOt25F1GQDGXjYS7cxNhU=
+github.com/a-h/parse v0.0.0-20250122154542-74294addb73e h1:HjVbSQHy+dnlS6C3XajZ69NYAb5jbGNfHanvm1+iYlo=
+github.com/a-h/parse v0.0.0-20250122154542-74294addb73e/go.mod h1:3mnrkvGpurZ4ZrTDbYU84xhwXW2TjTKShSwjRi2ihfQ=
 github.com/a-h/templ v0.3.1020 h1:ypAT/L5ySWEnZ6Zft/5yfoWXYYkhFNvEFOeeqecg4tw=
 github.com/a-h/templ v0.3.1020/go.mod h1:A2DlK61v+K+NRoGnhmYbNYVmtYHcFO5/AisMvBdDxTM=
 github.com/alecthomas/chroma v0.10.0 h1:7XDcGkCQopCNKjZHfYrNLraA+M7e0fMiJ/Mfikbfjek=
@@ -12,8 +14,13 @@ github.com/bodgit/plumbing v1.3.0 h1:pf9Itz1JOQgn7vEOE7v7nlEfBykYqvUYioC61TwWCFU
 github.com/bodgit/plumbing v1.3.0/go.mod h1:JOTb4XiRu5xfnmdnDJo6GmSbSbtSyufrsyZFByMtKEs=
 github.com/bodgit/windows v1.0.1 h1:tF7K6KOluPYygXa3Z2594zxlkbKPAOvqr97etrGNIz4=
 github.com/bodgit/windows v1.0.1/go.mod h1:a6JLwrB4KrTR5hBpp8FI9/9W9jJfeQ2h4XDXU74ZCdM=
+github.com/cenkalti/backoff/v4 v4.3.0 h1:MyRJ/UdXutAwSAT+s3wNd7MfTIcy71VQueUuFK343L8=
+github.com/cenkalti/backoff/v4 v4.3.0/go.mod h1:Y3VNntkOUPxTVeUxJ/G5vcM//AlwfmyYozVcomhLiZE=
+github.com/cli/browser v1.3.0 h1:LejqCrpWr+1pRqmEPDGnTZOjsMe7sehifLynZJuqJpo=
+github.com/cli/browser v1.3.0/go.mod h1:HH8s+fOAxjhQoBUAsKuPCbqUuxZDhQ2/aD+SzsEfBTk=
 github.com/clipperhouse/uax29/v2 v2.7.0 h1:+gs4oBZ2gPfVrKPthwbMzWZDaAFPGYK72F0NJv2v7Vk=
 github.com/clipperhouse/uax29/v2 v2.7.0/go.mod h1:EFJ2TJMRUaplDxHKj1qAEhCtQPW2tJSwu5BF98AuoVM=
+github.com/creack/pty v1.1.9 h1:uDmaGzcdjhF4i/plgjmEsriH11Y0o7RKapEf/LDaM3w=
 github.com/creack/pty v1.1.9/go.mod h1:oKZEueFk5CKHvIhNR5MUki03XCEU+Q6VDXinZuGJ33E=
 github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
@@ -22,6 +29,8 @@ github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc/go.mod h1:J7Y8Yc
 github.com/dlclark/regexp2 v1.4.0/go.mod h1:2pZnwuY/m+8K6iRw6wQdMtk+rH5tNGR1i55kozfMjCc=
 github.com/dlclark/regexp2 v1.12.0 h1:0j4c5qQmnC6XOWNjP3PIXURXN2gWx76rd3KvgdPkCz8=
 github.com/dlclark/regexp2 v1.12.0/go.mod h1:DHkYz0B9wPfa6wondMfaivmHpzrQ3v9q8cnmRbL6yW8=
+github.com/fatih/color v1.16.0 h1:zmkK9Ngbjj+K0yRhTVONQh1p/HknKYSlNT+vZCzyokM=
+github.com/fatih/color v1.16.0/go.mod h1:fL2Sau1YI5c0pdGEVCbKQbLXB6edEj1ZgiY4NijnWvE=
 github.com/fsnotify/fsnotify v1.9.0 h1:2Ml+OJNzbYCTzsxtv8vKSFD9PbJjmhYF14k/jKC7S9k=
 github.com/fsnotify/fsnotify v1.9.0/go.mod h1:8jBTzvmWwFyi3Pb8djgCCO5IBqzKJ/Jwo8TRcHyHii0=
 github.com/gabriel-vasile/mimetype v1.4.13 h1:46nXokslUBsAJE/wMsp5gtO500a4F3Nkz9Ufpk2AcUM=
@@ -72,16 +81,23 @@ github.com/labstack/echo/v5 v5.1.0 h1:MvIRydoN+p9cx/zq8Lff6YXqUW2ZaEsOMISzEGSMrB
 github.com/labstack/echo/v5 v5.1.0/go.mod h1:SyvlSdObGjRXeQfCCXW/sybkZdOOQZBmpKF0bvALaeo=
 github.com/leodido/go-urn v1.4.0 h1:WT9HwE9SGECu3lg4d/dIA+jxlljEa1/ffXKmRjqdmIQ=
 github.com/leodido/go-urn v1.4.0/go.mod h1:bvxc+MVxLKB4z00jd1z+Dvzr47oO32F/QSNjSBOlFxI=
+github.com/mattn/go-colorable v0.1.13 h1:fFA4WZxdEF4tXPZVKMLwD8oUnCTTo08duU7wxecdEvA=
+github.com/mattn/go-colorable v0.1.13/go.mod h1:7S9/ev0klgBDR4GtXTXX8a3vIGJpMovkB8vQcUbaXHg=
+github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWEY=
+github.com/mattn/go-isatty v0.0.20/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y=
 github.com/mattn/go-runewidth v0.0.23 h1:7ykA0T0jkPpzSvMS5i9uoNn2Xy3R383f9HDx3RybWcw=
 github.com/mattn/go-runewidth v0.0.23/go.mod h1:XBkDxAl56ILZc9knddidhrOlY5R/pDhgLpndooCuJAs=
 github.com/microcosm-cc/bluemonday v1.0.27 h1:MpEUotklkwCSLeH+Qdx1VJgNqLlpY2KXwXFM08ygZfk=
 github.com/microcosm-cc/bluemonday v1.0.27/go.mod h1:jFi9vgW+H7c3V0lb6nR74Ib/DIB5OBs92Dimizgw2cA=
+github.com/natefinch/atomic v1.0.1 h1:ZPYKxkqQOx3KZ+RsbnP/YsgvxWQPGxjC0oBt2AhwV0A=
+github.com/natefinch/atomic v1.0.1/go.mod h1:N/D/ELrljoqDyT3rZrsUmtsuzvHkeB/wWjHV22AZRbM=
 github.com/nwaples/rardecode v1.1.3 h1:cWCaZwfM5H7nAD6PyEdcVnczzV8i/JtotnyW/dD9lEc=
 github.com/nwaples/rardecode v1.1.3/go.mod h1:5DzqNKiOdpKKBH87u8VlvAnPZMXcGRhxWkRpHbbfGS0=
 github.com/pdfcpu/pdfcpu v0.11.1 h1:htHBSkGH5jMKWC6e0sihBFbcKZ8vG1M67c8/dJxhjas=
 github.com/pdfcpu/pdfcpu v0.11.1/go.mod h1:pP3aGga7pRvwFWAm9WwFvo+V68DfANi9kxSQYioNYcw=
 github.com/pierrec/lz4/v4 v4.1.26 h1:GrpZw1gZttORinvzBdXPUXATeqlJjqUG/D87TKMnhjY=
 github.com/pierrec/lz4/v4 v4.1.26/go.mod h1:EoQMVJgeeEOMsCqCzqFm2O0cJvljX2nGZjcRIPL34O4=
+github.com/pkg/diff v0.0.0-20210226163009-20ebb0f2a09e h1:aoZm08cpOy4WuID//EZDgcC4zIxODThtZNPirFr42+A=
 github.com/pkg/diff v0.0.0-20210226163009-20ebb0f2a09e/go.mod h1:pJLUxLENpZxwdsKMEsNbx1VGcRFpLqf3715MtcvvzbA=
 github.com/pkg/errors v0.9.1 h1:FEBLx1zS214owpjy7qsBeixbURkuhQAwrK5UwLGTwt4=
 github.com/pkg/errors v0.9.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
@@ -91,6 +107,8 @@ github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2/go.mod h1:iKH
 github.com/rogpeppe/go-internal v1.9.0/go.mod h1:WtVeX8xhTBvf0smdhujwtBcq4Qrzq/fJaraNFVN+nFs=
 github.com/rogpeppe/go-internal v1.14.1 h1:UQB4HGPB6osV0SQTLymcB4TgvyWu6ZyliaW0tI/otEQ=
 github.com/rogpeppe/go-internal v1.14.1/go.mod h1:MaRKkUm5W0goXpeCfT7UZI6fk/L7L7so1lCWt35ZSgc=
+github.com/rs/cors v1.11.0 h1:0B9GE/r9Bc2UxRMMtymBkHTenPkHDv0CW4Y98GBY+po=
+github.com/rs/cors v1.11.0/go.mod h1:XyqrcTp5zjWr1wsJ8PIRZssZ8b/WMcMf71DJnit4EMU=
 github.com/skip2/go-qrcode v0.0.0-20200617195104-da1b6568686e h1:MRM5ITcdelLK2j1vwZ3Je0FKVCfqOLp5zO6trqMLYs0=
 github.com/skip2/go-qrcode v0.0.0-20200617195104-da1b6568686e/go.mod h1:XV66xRDqSt+GTGFMVlhk3ULuV0y9ZmzeVGR4mloJI3M=
 github.com/spf13/afero v1.15.0 h1:b/YBCLWAJdFWJTN9cLhiXXcD7mzKn9Dm86dNnfyQw1I=
@@ -98,6 +116,8 @@ github.com/spf13/afero v1.15.0/go.mod h1:NC2ByUVxtQs4b3sIUphxK0NioZnmxgyCrfzeuq8
 github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
 github.com/stretchr/objx v0.4.0/go.mod h1:YvHI0jy2hoMjB+UWwv71VJQ9isScKT/TqJzVSSt89Yw=
 github.com/stretchr/objx v0.5.0/go.mod h1:Yh+to48EsGEfYuaHDzXPcE3xhTkx73EhmCGUpEOglKo=
+github.com/stretchr/objx v0.5.2 h1:xuMeJ0Sdp5ZMRXx/aWO6RZxdr3beISkG5/G/aIRr3pY=
+github.com/stretchr/objx v0.5.2/go.mod h1:FRsXN1f5AsAjCGJKqEizvkpNtU+EGNCLh3NxZ/8L+MA=
 github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI=
 github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
 github.com/stretchr/testify v1.7.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
@@ -118,16 +138,22 @@ golang.org/x/crypto v0.50.0 h1:zO47/JPrL6vsNkINmLoo/PH1gcxpls50DNogFvB5ZGI=
 golang.org/x/crypto v0.50.0/go.mod h1:3muZ7vA7PBCE6xgPX7nkzzjiUq87kRItoJQM1Yo8S+Q=
 golang.org/x/image v0.39.0 h1:skVYidAEVKgn8lZ602XO75asgXBgLj9G/FE3RbuPFww=
 golang.org/x/image v0.39.0/go.mod h1:sIbmppfU+xFLPIG0FoVUTvyBMmgng1/XAMhQ2ft0hpA=
+golang.org/x/mod v0.34.0 h1:xIHgNUUnW6sYkcM5Jleh05DvLOtwc6RitGHbDk4akRI=
+golang.org/x/mod v0.34.0/go.mod h1:ykgH52iCZe79kzLLMhyCUzhMci+nQj+0XkbXpNYtVjY=
 golang.org/x/net v0.53.0 h1:d+qAbo5L0orcWAr0a9JweQpjXF19LMXJE8Ey7hwOdUA=
 golang.org/x/net v0.53.0/go.mod h1:JvMuJH7rrdiCfbeHoo3fCQU24Lf5JJwT9W3sJFulfgs=
 golang.org/x/sync v0.20.0 h1:e0PTpb7pjO8GAtTs2dQ6jYa5BWYlMuX047Dco/pItO4=
 golang.org/x/sync v0.20.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
 golang.org/x/sys v0.43.0 h1:Rlag2XtaFTxp19wS8MXlJwTvoh8ArU6ezoyFsMyCTNI=
 golang.org/x/sys v0.43.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
+golang.org/x/term v0.42.0 h1:UiKe+zDFmJobeJ5ggPwOshJIVt6/Ft0rcfrXZDLWAWY=
+golang.org/x/term v0.42.0/go.mod h1:Dq/D+snpsbazcBG5+F9Q1n2rXV8Ma+71xEjTRufARgY=
 golang.org/x/text v0.36.0 h1:JfKh3XmcRPqZPKevfXVpI1wXPTqbkE5f7JA92a55Yxg=
 golang.org/x/text v0.36.0/go.mod h1:NIdBknypM8iqVmPiuco0Dh6P5Jcdk8lJL0CUebqK164=
 golang.org/x/time v0.15.0 h1:bbrp8t3bGUeFOx08pvsMYRTCVSMk89u4tKbNOZbp88U=
 golang.org/x/time v0.15.0/go.mod h1:Y4YMaQmXwGQZoFaVFk4YpCt4FLQMYKZe9oeV/f4MSno=
+golang.org/x/tools v0.43.0 h1:12BdW9CeB3Z+J/I/wj34VMl8X+fEXBxVR90JeMX5E7s=
+golang.org/x/tools v0.43.0/go.mod h1:uHkMso649BX2cZK6+RpuIPXS3ho2hZo4FVwfoy1vIk0=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
 gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
 gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q=

internal/database/models.go

@@ -31,6 +31,7 @@ type Collections struct {
 	Priority           pgtype.Int4        `db:"priority" json:"priority"`
 	IsSystemCollection pgtype.Bool        `db:"is_system_collection" json:"is_system_collection"`
 	CreatedAt          pgtype.Timestamptz `db:"created_at" json:"created_at"`
+	DeletedAt          pgtype.Timestamptz `db:"deleted_at" json:"deleted_at"`
 }
 
 type DeviceCatalogs struct {
@@ -351,6 +352,15 @@ type MediaRatings struct {
 	UpdatedAt pgtype.Timestamptz `db:"updated_at" json:"updated_at"`
 }
 
+type MediaReviews struct {
+	ID          pgtype.UUID        `db:"id" json:"id"`
+	MediaItemID pgtype.UUID        `db:"media_item_id" json:"media_item_id"`
+	UserID      pgtype.UUID        `db:"user_id" json:"user_id"`
+	Review      string             `db:"review" json:"review"`
+	CreatedAt   pgtype.Timestamptz `db:"created_at" json:"created_at"`
+	UpdatedAt   pgtype.Timestamptz `db:"updated_at" json:"updated_at"`
+}
+
 type OpdsTokens struct {
 	ID        pgtype.UUID        `db:"id" json:"id"`
 	DeviceID  pgtype.UUID        `db:"device_id" json:"device_id"`
@@ -538,6 +548,14 @@ type UserDashboardPreferences struct {
 	UpdatedAt         pgtype.Timestamptz `db:"updated_at" json:"updated_at"`
 }
 
+type UserDashboardPreferencesGlobal struct {
+	UserID            pgtype.UUID        `db:"user_id" json:"user_id"`
+	HiddenCollections []string           `db:"hidden_collections" json:"hidden_collections"`
+	CollectionOrder   []string           `db:"collection_order" json:"collection_order"`
+	ItemsPerSection   pgtype.Int4        `db:"items_per_section" json:"items_per_section"`
+	UpdatedAt         pgtype.Timestamptz `db:"updated_at" json:"updated_at"`
+}
+
 type Users struct {
 	ID           pgtype.UUID        `db:"id" json:"id"`
 	Email        string             `db:"email" json:"email"`

internal/database/querier.go

@@ -30,6 +30,7 @@ type Querier interface {
 	// Cleanup expired OPDS tokens
 	CleanupExpiredOpdsTokens(ctx context.Context) error
 	CleanupExpiredRefreshTokens(ctx context.Context, dollar_1 float64) error
+	ClearCollectionItems(ctx context.Context, collectionID pgtype.UUID) error
 	ClearDeviceSyncQueue(ctx context.Context, deviceID pgtype.UUID) error
 	ClearKoboShelf(ctx context.Context, deviceID pgtype.UUID) error
 	ClearKoboShelfByName(ctx context.Context, arg ClearKoboShelfByNameParams) error
@@ -41,6 +42,10 @@ type Querier interface {
 	ClearMediaItemMetadataOverrides(ctx context.Context, id pgtype.UUID) error
 	CountAdmins(ctx context.Context) (int64, error)
 	CountArchivedMediaItems(ctx context.Context) (int64, error)
+	// Live item count for a STATIC collection (rule-free cards on the
+	// collections page); same live filter as GetCollectionItems, plus the
+	// future-hybrid excluded exclusion and an optional library scope.
+	CountCollectionLiveItems(ctx context.Context, arg CountCollectionLiveItemsParams) (int32, error)
 	// Count unlinked books for a device
 	CountUnlinkedBooks(ctx context.Context, deviceID pgtype.UUID) (int64, error)
 	CountUserDevices(ctx context.Context, userID pgtype.UUID) (int64, error)
@@ -79,6 +84,11 @@ type Querier interface {
 	// MEDIA ITEM FORMATS QUERIES
 	// Create media item format
 	CreateMediaItemFormat(ctx context.Context, arg CreateMediaItemFormatParams) (MediaItemFormats, error)
+	// API create path: race-safe create-or-detect. On a duplicate
+	// (library_id, file_path) this inserts NOTHING and returns no row
+	// (pgx.ErrNoRows) — the handler then answers 200 with the existing row
+	// and a duplicate flag instead of pretending it created something.
+	CreateMediaItemIfNew(ctx context.Context, arg CreateMediaItemIfNewParams) (MediaItems, error)
 	// Media Notes queries
 	CreateMediaNote(ctx context.Context, arg CreateMediaNoteParams) (MediaNotes, error)
 	CreateMediaNoteFull(ctx context.Context, arg CreateMediaNoteFullParams) (MediaNotes, error)
@@ -125,13 +135,14 @@ type Querier interface {
 	DeleteKoboEntitlement(ctx context.Context, arg DeleteKoboEntitlementParams) error
 	DeleteLibrary(ctx context.Context, id pgtype.UUID) error
 	DeleteLibraryFolder(ctx context.Context, arg DeleteLibraryFolderParams) (LibraryFolders, error)
-	DeleteMediaBookmark(ctx context.Context, id pgtype.UUID) error
-	DeleteMediaHighlight(ctx context.Context, id pgtype.UUID) error
+	DeleteMediaBookmark(ctx context.Context, arg DeleteMediaBookmarkParams) error
+	DeleteMediaHighlight(ctx context.Context, arg DeleteMediaHighlightParams) error
 	DeleteMediaItem(ctx context.Context, id pgtype.UUID) error
 	// Delete media item format
 	DeleteMediaItemFormat(ctx context.Context, id pgtype.UUID) error
-	DeleteMediaNote(ctx context.Context, id pgtype.UUID) error
+	DeleteMediaNote(ctx context.Context, arg DeleteMediaNoteParams) error
 	DeleteMediaRating(ctx context.Context, arg DeleteMediaRatingParams) error
+	DeleteMediaReview(ctx context.Context, arg DeleteMediaReviewParams) error
 	DeleteProcessingIssue(ctx context.Context, id pgtype.UUID) (ProcessingIssues, error)
 	DeleteReadingProgress(ctx context.Context, arg DeleteReadingProgressParams) error
 	DeleteSavedFilter(ctx context.Context, arg DeleteSavedFilterParams) (SavedFilters, error)
@@ -143,6 +154,10 @@ type Querier interface {
 	DeleteUnlinkedBook(ctx context.Context, id pgtype.UUID) error
 	DeleteUser(ctx context.Context, id pgtype.UUID) error
 	DeleteUserSystemCollection(ctx context.Context, arg DeleteUserSystemCollectionParams) error
+	// Device existence probe for capture: the web/app progress paths
+	// historically stuff the user id into DeviceID (it only fed a broadcast
+	// label before stats); a capture row must only reference a REAL device.
+	DeviceExistsForUser(ctx context.Context, arg DeviceExistsForUserParams) (bool, error)
 	// Find content-duplicate groups (same library + SHA-256, more than one row)
 	FindHashConflictGroups(ctx context.Context) ([]FindHashConflictGroupsRow, error)
 	GenerateKoboEntitlementId(ctx context.Context) (interface{}, error)
@@ -155,6 +170,8 @@ type Querier interface {
 	GetAllSystemSettings(ctx context.Context) ([]GetAllSystemSettingsRow, error)
 	GetAllSystemSettingsFull(ctx context.Context) ([]SystemSettings, error)
 	GetAnnotationsForBook(ctx context.Context, arg GetAnnotationsForBookParams) ([]GetAnnotationsForBookRow, error)
+	// Lifetime session rows for ONE book (the book-detail stats card).
+	GetBookReadingSessions(ctx context.Context, arg GetBookReadingSessionsParams) ([]GetBookReadingSessionsRow, error)
 	GetBooksByTag(ctx context.Context, arg GetBooksByTagParams) ([]MediaItems, error)
 	// Get collection
 	GetCollection(ctx context.Context, id pgtype.UUID) (Collections, error)
@@ -174,6 +191,10 @@ type Querier interface {
 	// CAROUSEL-STYLE DASHBOARD
 	// ============================================
 	// Dashboard preferences queries
+	// The handler routes by scope: a Valid library_id targets the per-library
+	// table below; an absent one targets user_dashboard_preferences_global
+	// (the "All Libraries" view). Never pass NULL here — the loose NULL match
+	// was removed because it returned an arbitrary library's row.
 	GetDashboardPreferences(ctx context.Context, arg GetDashboardPreferencesParams) (UserDashboardPreferences, error)
 	GetDevice(ctx context.Context, id pgtype.UUID) (Devices, error)
 	GetDeviceByAuthToken(ctx context.Context, authToken string) (Devices, error)
@@ -195,11 +216,16 @@ type Querier interface {
 	// Get device shelf mappings
 	GetDeviceShelfMappings(ctx context.Context, deviceID pgtype.UUID) ([]GetDeviceShelfMappingsRow, error)
 	GetDictionaryEntry(ctx context.Context, word string) (DictionaryCache, error)
+	// Series are grouped PER LIBRARY: the same series name in two libraries
+	// (novels vs manga adaptations, LN splits) stays two entries. Visible
+	// filter enforces per-user library visibility at the source.
 	GetDistinctSeries(ctx context.Context, arg GetDistinctSeriesParams) ([]GetDistinctSeriesRow, error)
-	GetDistinctSeriesCount(ctx context.Context, libraryID pgtype.UUID) (int32, error)
+	GetDistinctSeriesCount(ctx context.Context, arg GetDistinctSeriesCountParams) (int32, error)
 	GetFailedSyncQueueItems(ctx context.Context, limit int32) ([]SyncQueue, error)
 	GetFirstAdmin(ctx context.Context) (pgtype.UUID, error)
 	GetFirstAdminExclude(ctx context.Context, id pgtype.UUID) (GetFirstAdminExcludeRow, error)
+	// Global (all-libraries) scope: exactly one row per user.
+	GetGlobalDashboardPreferences(ctx context.Context, userID pgtype.UUID) (UserDashboardPreferencesGlobal, error)
 	GetHashConflict(ctx context.Context, id pgtype.UUID) (HashConflicts, error)
 	GetKoboEntitlementByContentId(ctx context.Context, arg GetKoboEntitlementByContentIdParams) (GetKoboEntitlementByContentIdRow, error)
 	GetKoboEntitlementByEntitlementId(ctx context.Context, arg GetKoboEntitlementByEntitlementIdParams) (GetKoboEntitlementByEntitlementIdRow, error)
@@ -209,6 +235,12 @@ type Querier interface {
 	GetKoboShelfBooksByShelfName(ctx context.Context, arg GetKoboShelfBooksByShelfNameParams) ([]GetKoboShelfBooksByShelfNameRow, error)
 	// Get Kobo shelves by collection
 	GetKoboShelvesByCollection(ctx context.Context, arg GetKoboShelvesByCollectionParams) ([]GetKoboShelvesByCollectionRow, error)
+	// KOReader stats conversion: the device pushes its CUMULATIVE total reading
+	// seconds for a book; the watermark is the highest total already converted,
+	// read from the koreader sessions' own device_metadata. Delta-only insertion
+	// means a reinstall of the device cannot double-count, and sub-threshold
+	// deltas are never lost (they stay folded into the next push's delta).
+	GetKoreaderStatWatermark(ctx context.Context, arg GetKoreaderStatWatermarkParams) (interface{}, error)
 	GetLibrary(ctx context.Context, id pgtype.UUID) (GetLibraryRow, error)
 	GetLibraryByFolder(ctx context.Context, folderPath string) (GetLibraryByFolderRow, error)
 	GetLibraryByFolderPathPrefix(ctx context.Context, folderPath string) (GetLibraryByFolderPathPrefixRow, error)
@@ -243,6 +275,7 @@ type Querier interface {
 	// ============================================
 	GetMediaItemByFilePathForSync(ctx context.Context, filePath string) (MediaItems, error)
 	GetMediaItemByKoboContentId(ctx context.Context, koboContentID pgtype.Text) (MediaItems, error)
+	GetMediaItemByLibraryAndPath(ctx context.Context, arg GetMediaItemByLibraryAndPathParams) (MediaItems, error)
 	// Get media item by OPF identifier
 	GetMediaItemByOPFIdentifier(ctx context.Context, opfIdentifier pgtype.Text) (MediaItems, error)
 	// Get media item by OPF UUID
@@ -259,6 +292,12 @@ type Querier interface {
 	GetMediaItemFormats(ctx context.Context, mediaItemID pgtype.UUID) ([]MediaItemFormats, error)
 	// Per-item user-data counts, used when choosing which duplicate copy to keep
 	GetMediaItemUsageCounts(ctx context.Context, mediaItemID pgtype.UUID) (GetMediaItemUsageCountsRow, error)
+	// Cross-library move detection: identical content registered in a different
+	// library of the same type (ebooks stay with ebooks, comics with comics).
+	// Candidates may be active copies (deliberate duplicates - leave alone) or
+	// hidden/archived rows whose file vanished (move candidates - the scanner
+	// verifies disk state before repointing).
+	GetMediaItemsBySHA256AndSameLibraryType(ctx context.Context, arg GetMediaItemsBySHA256AndSameLibraryTypeParams) ([]GetMediaItemsBySHA256AndSameLibraryTypeRow, error)
 	GetMediaNote(ctx context.Context, id pgtype.UUID) (MediaNotes, error)
 	// ============================================
 	// ANNOTATION SYNC QUERIES (notes)
@@ -267,6 +306,7 @@ type Querier interface {
 	GetMediaNotes(ctx context.Context, arg GetMediaNotesParams) ([]MediaNotes, error)
 	GetMediaRating(ctx context.Context, arg GetMediaRatingParams) (MediaRatings, error)
 	GetMediaRatings(ctx context.Context, mediaItemID pgtype.UUID) ([]GetMediaRatingsRow, error)
+	GetMediaReview(ctx context.Context, arg GetMediaReviewParams) (MediaReviews, error)
 	GetNextRetryTime(ctx context.Context) (interface{}, error)
 	GetNotStartedItems(ctx context.Context, arg GetNotStartedItemsParams) ([]MediaItems, error)
 	// Get OPDS token
@@ -287,12 +327,21 @@ type Querier interface {
 	GetRefreshToken(ctx context.Context, token pgtype.UUID) (GetRefreshTokenRow, error)
 	GetSavedFilterByID(ctx context.Context, arg GetSavedFilterByIDParams) (SavedFilters, error)
 	GetSavedFilters(ctx context.Context, arg GetSavedFiltersParams) ([]SavedFilters, error)
-	GetSeriesBooks(ctx context.Context, series pgtype.Text) ([]MediaItems, error)
+	// Scoped to ONE library: same-name series in different libraries are
+	// different stories (manga adaptations, LN splits). Callers must pass a
+	// library_id and verify the requester can see that library.
+	GetSeriesBooks(ctx context.Context, arg GetSeriesBooksParams) ([]MediaItems, error)
 	GetSeriesCovers(ctx context.Context, arg GetSeriesCoversParams) ([]GetSeriesCoversRow, error)
 	GetStuckSyncQueueItems(ctx context.Context) ([]SyncQueue, error)
 	GetSyncConflict(ctx context.Context, id pgtype.UUID) (SyncConflicts, error)
 	GetSyncQueueItem(ctx context.Context, id pgtype.UUID) (SyncQueue, error)
 	GetSyncQueueStats(ctx context.Context, deviceID pgtype.UUID) (GetSyncQueueStatsRow, error)
+	// System collections are permanent: identity is (user_id, query_type).
+	// Restore/reset operate IN PLACE (the row id — and everything referencing
+	// it: shelf mappings, prefs order, links — never churns). Deleted sections
+	// are TOMBSTONED (deleted_at) and stay invisible until restored.
+	// Unfiltered by design: restore/seed must resolve tombstoned rows too.
+	GetSystemCollectionByQueryType(ctx context.Context, arg GetSystemCollectionByQueryTypeParams) (Collections, error)
 	// Dashboard collections queries
 	GetSystemCollectionsForDashboard(ctx context.Context, userID pgtype.UUID) ([]Collections, error)
 	// SYSTEM CONFIG QUERIES
@@ -303,6 +352,8 @@ type Querier interface {
 	GetSystemSettingFull(ctx context.Context, settingKey string) (SystemSettings, error)
 	GetSystemTimezone(ctx context.Context) (string, error)
 	GetTombstonedAnnotationsForBook(ctx context.Context, arg GetTombstonedAnnotationsForBookParams) ([]GetTombstonedAnnotationsForBookRow, error)
+	// Most-read books for a range (minutes), for the top list.
+	GetTopBooksByMinutes(ctx context.Context, arg GetTopBooksByMinutesParams) ([]GetTopBooksByMinutesRow, error)
 	// Get universal progress for a book
 	GetUniversalProgress(ctx context.Context, arg GetUniversalProgressParams) (GetUniversalProgressRow, error)
 	// Get unlinked book by ContentId
@@ -316,17 +367,42 @@ type Querier interface {
 	GetUserByEmailOrUsername(ctx context.Context, email string) (GetUserByEmailOrUsernameRow, error)
 	GetUserByUsername(ctx context.Context, username string) (GetUserByUsernameRow, error)
 	GetUserCollectionsForDashboard(ctx context.Context, userID pgtype.UUID) ([]Collections, error)
+	// Per-device reading breakdown for a range. LEFT JOIN so pushes that
+	// carry no device (web reader until it identifies) still appear as one
+	// "unattributed" bucket — device minutes must reconcile with the totals.
+	GetUserDeviceBreakdown(ctx context.Context, arg GetUserDeviceBreakdownParams) ([]GetUserDeviceBreakdownRow, error)
 	// Get user device usage statistics
 	GetUserDeviceUsage(ctx context.Context, userID pgtype.UUID) ([]GetUserDeviceUsageRow, error)
 	GetUserForLogin(ctx context.Context, email string) (GetUserForLoginRow, error)
+	// Per-library aggregation for the same range.
+	GetUserLibraryBreakdown(ctx context.Context, arg GetUserLibraryBreakdownParams) ([]GetUserLibraryBreakdownRow, error)
 	GetUserMediaItemsForSync(ctx context.Context, userID pgtype.UUID) ([]GetUserMediaItemsForSyncRow, error)
 	GetUserPasswordHash(ctx context.Context, id pgtype.UUID) (string, error)
 	GetUserProgressForBooks(ctx context.Context, arg GetUserProgressForBooksParams) ([]GetUserProgressForBooksRow, error)
+	// Distinct ACTIVE days (any captured session) bucketed in the user's
+	// timezone — the streak calendar. Scoped to a long look-back so the
+	// "longest streak" and a current streak longer than the selected range
+	// are both real.
+	GetUserReadingActiveDays(ctx context.Context, arg GetUserReadingActiveDaysParams) ([]string, error)
 	// Analytics queries
 	// Get user reading history for analytics
 	GetUserReadingHistory(ctx context.Context, arg GetUserReadingHistoryParams) ([]GetUserReadingHistoryRow, error)
+	// STATISTICS (reading sessions) — time spent, pages, streaks, breakdowns.
+	// Every stats query scopes to the requesting user's VISIBLE libraries
+	// (family lens at the source) and single scan of reading_history.
+	// Full session rows for a range (summary math runs in Go: tz buckets,
+	// streaks, finished-book detection). The bucket/range key is the session
+	// END instant (the push time; NULL falls back to created_at) — the same
+	// value the capture stamps every write with.
+	GetUserReadingSessionsRange(ctx context.Context, arg GetUserReadingSessionsRangeParams) ([]GetUserReadingSessionsRangeRow, error)
 	GetUserVisibleLibraries(ctx context.Context, userID pgtype.UUID) ([]GetUserVisibleLibrariesRow, error)
 	GetVisibleLibraryMediaCounts(ctx context.Context, userID pgtype.UUID) ([]GetVisibleLibraryMediaCountsRow, error)
+	// Smart ("dynamic") collections: rules are evaluated LIVE at render, so
+	// membership comes from the candidate book set instead of collection_items.
+	// The set is scoped to the requesting user's visible libraries (family
+	// lens enforced at the source) and live items only — the same filters the
+	// static collection paths apply.
+	GetVisibleLiveMediaForRules(ctx context.Context, arg GetVisibleLiveMediaForRulesParams) ([]MediaItems, error)
 	HasRecentConflictResolution(ctx context.Context, arg HasRecentConflictResolutionParams) (bool, error)
 	IncrementSyncQueueAttempts(ctx context.Context, arg IncrementSyncQueueAttemptsParams) (SyncQueue, error)
 	// Check if book is in collection
@@ -349,7 +425,10 @@ type Querier interface {
 	ListDevicesByUser(ctx context.Context, userID pgtype.UUID) ([]Devices, error)
 	// Items hidden from libraries: either missing from disk (waiting on the
 	// second scan that archives them) or already archived and pending purge.
-	// Feeds the admin archived-items page.
+	// Feeds the admin archived-items page. match_* columns identify an active
+	// item with identical content (same SHA-256) so the UI can offer merging the
+	// archived row's reading data into its active twin instead of waiting for a
+	// file that will never return.
 	ListHiddenMediaItems(ctx context.Context) ([]ListHiddenMediaItemsRow, error)
 	ListLibraries(ctx context.Context) ([]ListLibrariesRow, error)
 	ListMediaItems(ctx context.Context, arg ListMediaItemsParams) ([]ListMediaItemsRow, error)
@@ -374,6 +453,11 @@ type Querier interface {
 	// a move. Repoints the row (and refreshes file-level fields) so reading
 	// history follows the book; archive/missing state is cleared separately.
 	MoveMediaItemFilePath(ctx context.Context, arg MoveMediaItemFilePathParams) error
+	// Cross-library move: identical content reappeared in a different library of
+	// the same type while the old file vanished. Repoints the row so reading
+	// history, annotations and collections follow the book; archive/missing
+	// state is cleared. library_type_name is refreshed by trigger.
+	MoveMediaItemToLibrary(ctx context.Context, arg MoveMediaItemToLibraryParams) error
 	// Manual bulk purge from the library admin page.
 	PurgeAllArchivedMediaItems(ctx context.Context) ([]PurgeAllArchivedMediaItemsRow, error)
 	// Retention sweep at library-scan time: hard-delete archived items older
@@ -405,6 +489,9 @@ type Querier interface {
 	RestoreMediaBookmarkByID(ctx context.Context, arg RestoreMediaBookmarkByIDParams) (int64, error)
 	RestoreMediaHighlightByID(ctx context.Context, arg RestoreMediaHighlightByIDParams) (int64, error)
 	RestoreMediaNoteByID(ctx context.Context, arg RestoreMediaNoteByIDParams) (int64, error)
+	// Full reset, in place: canonical metadata, back on the dashboard,
+	// un-tombstoned. Item assignments are cleared by the caller ("full").
+	RestoreSystemCollectionRow(ctx context.Context, arg RestoreSystemCollectionRowParams) (Collections, error)
 	RevokeAllUserRefreshTokens(ctx context.Context, userID pgtype.UUID) error
 	RevokeDevice(ctx context.Context, id pgtype.UUID) error
 	// Revoke OPDS token
@@ -424,13 +511,17 @@ type Querier interface {
 	SetSystemConfig(ctx context.Context, arg SetSystemConfigParams) (SystemConfig, error)
 	SyncLibraryTypeExtensions(ctx context.Context, arg SyncLibraryTypeExtensionsParams) error
 	TombstoneMediaBookmarkByDedupKey(ctx context.Context, arg TombstoneMediaBookmarkByDedupKeyParams) error
-	TombstoneMediaBookmarkByID(ctx context.Context, id pgtype.UUID) error
+	TombstoneMediaBookmarkByID(ctx context.Context, arg TombstoneMediaBookmarkByIDParams) error
 	TombstoneMediaHighlightByDedupKey(ctx context.Context, arg TombstoneMediaHighlightByDedupKeyParams) error
-	TombstoneMediaHighlightByID(ctx context.Context, id pgtype.UUID) error
+	TombstoneMediaHighlightByID(ctx context.Context, arg TombstoneMediaHighlightByIDParams) error
 	TombstoneMediaNoteByDedupKey(ctx context.Context, arg TombstoneMediaNoteByDedupKeyParams) error
-	TombstoneMediaNoteByID(ctx context.Context, id pgtype.UUID) error
+	TombstoneMediaNoteByID(ctx context.Context, arg TombstoneMediaNoteByIDParams) error
+	TombstoneSystemCollection(ctx context.Context, id pgtype.UUID) error
 	// Update collection
 	UpdateCollection(ctx context.Context, arg UpdateCollectionParams) (Collections, error)
+	// Replace ONLY the auto_assign_rules document (rule CRUD: read-modify-write
+	// of the JSONB without touching metadata stale clients did not send).
+	UpdateCollectionRulesJSON(ctx context.Context, arg UpdateCollectionRulesJSONParams) (Collections, error)
 	UpdateDashboardPreferences(ctx context.Context, arg UpdateDashboardPreferencesParams) (UserDashboardPreferences, error)
 	UpdateDevice(ctx context.Context, arg UpdateDeviceParams) (Devices, error)
 	UpdateDeviceAuthToken(ctx context.Context, arg UpdateDeviceAuthTokenParams) (Devices, error)
@@ -489,6 +580,8 @@ type Querier interface {
 	UpdateUserTimezone(ctx context.Context, arg UpdateUserTimezoneParams) error
 	UpdateUsername(ctx context.Context, arg UpdateUsernameParams) error
 	UpsertDashboardPreferences(ctx context.Context, arg UpsertDashboardPreferencesParams) (UserDashboardPreferences, error)
+	UpsertGlobalDashboardPreferences(ctx context.Context, arg UpsertGlobalDashboardPreferencesParams) (UserDashboardPreferencesGlobal, error)
+	UpsertMediaReview(ctx context.Context, arg UpsertMediaReviewParams) (MediaReviews, error)
 	UpsertPanelData(ctx context.Context, arg UpsertPanelDataParams) (PanelData, error)
 	UpsertReaderSettings(ctx context.Context, arg UpsertReaderSettingsParams) (ReaderSettings, error)
 	UpsertSystemSetting(ctx context.Context, arg UpsertSystemSettingParams) (SystemSettings, error)

internal/database/queries/queries.sql

@@ -1,7 +1,7 @@
 -- name: CreateUser :one
-INSERT INTO users (email, username, password_hash, first_name, last_name, theme, role)
-VALUES ($1, $2, $3, $4, $5, $6, $7)
-RETURNING id, email, username, theme, first_name, last_name, role, created_at, updated_at;
+INSERT INTO users (email, username, password_hash, first_name, last_name, theme, role, timezone)
+VALUES ($1, $2, $3, $4, $5, $6, $7, $8)
+RETURNING id, email, username, theme, first_name, last_name, role, timezone, created_at, updated_at;
 
 -- name: GetUserByEmail :one
 SELECT id, email, username, theme, first_name, last_name, role, created_at, updated_at FROM users WHERE email = $1;
@@ -154,6 +154,19 @@ VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15, $16, $
 ON CONFLICT (library_id, file_path) DO UPDATE SET updated_at = NOW()
 RETURNING *;
 
+-- name: CreateMediaItemIfNew :one
+-- API create path: race-safe create-or-detect. On a duplicate
+-- (library_id, file_path) this inserts NOTHING and returns no row
+-- (pgx.ErrNoRows) — the handler then answers 200 with the existing row
+-- and a duplicate flag instead of pretending it created something.
+INSERT INTO media_items (library_id, title, author, isbn, description, file_path, file_size, mime_type, cover_image_path, series, series_number, tags, tags_search, asin, date_published, publisher, contributors, contributors_search, language, edition, page_count, genre, copyright_year, goodreads_id, openlibrary_id, google_books_id, added_by_admin_id, created_at, imported_at, manga_type, reading_direction, series_count, volume, imprint, age_rating, web_url, story_arc, is_black_and_white, metadata_notes, community_rating, alternate_info, scan_information, summary, library_type_name)
+VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15, $16, $17, $18, $19, $20, $21, $22, $23, $24, $25, $26, $27, $28, $29, $30, $31, $32, $33, $34, $35, $36, $37, $38, $39, $40, $41, $42, $43, $44)
+ON CONFLICT (library_id, file_path) DO NOTHING
+RETURNING *;
+
+-- name: GetMediaItemByLibraryAndPath :one
+SELECT * FROM media_items WHERE library_id = $1 AND file_path = $2;
+
 -- name: GetMediaItem :one
 SELECT * FROM media_items WHERE id = $1;
 
@@ -164,6 +177,7 @@ JOIN libraries l ON mi.library_id = l.id
 JOIN library_types lt ON l.library_type_id = lt.id
 WHERE mi.archived_at IS NULL
   AND mi.missing_scan_count = 0
+  AND (sqlc.narg('visible_library_ids')::uuid[] IS NULL OR mi.library_id = ANY(sqlc.narg('visible_library_ids')::uuid[]))
 ORDER BY mi.created_at DESC LIMIT $1 OFFSET $2;
 
 -- name: ListMediaItemsByLibrary :many
@@ -328,6 +342,20 @@ WHERE id = $1;
 UPDATE media_items SET archived_at = NOW(), updated_at = NOW()
 WHERE id = $1;
 
+-- name: MoveMediaItemToLibrary :exec
+-- Cross-library move: identical content reappeared in a different library of
+-- the same type while the old file vanished. Repoints the row so reading
+-- history, annotations and collections follow the book; archive/missing
+-- state is cleared. library_type_name is refreshed by trigger.
+UPDATE media_items
+SET library_id = $2,
+    file_path = $3,
+    file_size = $4,
+    archived_at = NULL,
+    missing_scan_count = 0,
+    updated_at = NOW()
+WHERE id = $1;
+
 -- name: ClearMediaItemArchive :exec
 -- File is back on disk (by path or content hash): restore visibility and
 -- reset the missing-scan counter. No-op for items that were never archived.
@@ -353,11 +381,32 @@ SELECT COUNT(*) FROM media_items WHERE archived_at IS NOT NULL;
 -- name: ListHiddenMediaItems :many
 -- Items hidden from libraries: either missing from disk (waiting on the
 -- second scan that archives them) or already archived and pending purge.
--- Feeds the admin archived-items page.
-SELECT mi.*, l.name as library_name, lt.name as library_type_name
+-- Feeds the admin archived-items page. match_* columns identify an active
+-- item with identical content (same SHA-256) so the UI can offer merging the
+-- archived row's reading data into its active twin instead of waiting for a
+-- file that will never return.
+SELECT mi.*, l.name as library_name, lt.name as library_type_name,
+       twin.id AS match_id, COALESCE(twin.title, '') AS match_title,
+       twin_library.name AS match_library_name
 FROM media_items mi
 JOIN libraries l ON mi.library_id = l.id
 JOIN library_types lt ON l.library_type_id = lt.id
+LEFT JOIN LATERAL (
+    SELECT t.id, t.title, t.library_id
+    FROM media_items t
+    JOIN libraries tl ON t.library_id = tl.id
+    JOIN library_types tlt ON tl.library_type_id = tlt.id
+    WHERE t.file_sha256 = mi.file_sha256
+      AND t.id <> mi.id
+      AND t.archived_at IS NULL
+      AND t.missing_scan_count = 0
+    ORDER BY (tlt.id = lt.id) DESC,
+             (tl.id = l.id) DESC,
+             (SELECT COUNT(*) FROM reading_progress rp WHERE rp.media_item_id = t.id) DESC,
+             t.created_at ASC
+    LIMIT 1
+) twin ON true
+LEFT JOIN libraries twin_library ON twin_library.id = twin.library_id
 WHERE mi.archived_at IS NOT NULL OR mi.missing_scan_count > 0
 ORDER BY mi.archived_at NULLS LAST, mi.updated_at DESC;
 
@@ -501,6 +550,33 @@ RETURNING *;
 -- name: DeleteMediaRating :exec
 DELETE FROM media_ratings WHERE media_item_id = $1 AND user_id = $2;
 
+-- name: UpsertMediaReview :one
+INSERT INTO media_reviews (media_item_id, user_id, review)
+VALUES ($1, $2, $3)
+ON CONFLICT (media_item_id, user_id)
+DO UPDATE SET
+    review = EXCLUDED.review,
+    updated_at = NOW()
+RETURNING *;
+
+-- name: GetMediaReview :one
+SELECT * FROM media_reviews WHERE media_item_id = $1 AND user_id = $2;
+
+-- name: DeleteMediaReview :exec
+DELETE FROM media_reviews WHERE media_item_id = $1 AND user_id = $2;
+
+-- KOReader stats conversion: the device pushes its CUMULATIVE total reading
+-- seconds for a book; the watermark is the highest total already converted,
+-- read from the koreader sessions' own device_metadata. Delta-only insertion
+-- means a reinstall of the device cannot double-count, and sub-threshold
+-- deltas are never lost (they stay folded into the next push's delta).
+-- name: GetKoreaderStatWatermark :one
+SELECT COALESCE(MAX((device_metadata->>'total_seconds')::bigint), 0) AS total_seconds
+FROM reading_history
+WHERE user_id = $1
+  AND media_item_id = $2
+  AND device_metadata->>'source' = 'koreader';
+
 -- Search Media Items queries
 -- name: SearchMediaItems :many
 SELECT mi.*, l.name as library_name, lt.name as library_type_name
@@ -593,6 +669,8 @@ WHERE COALESCE(lv.is_visible, true) = true
   AND (sqlc.narg('series_filter') = '' OR word_similarity(sqlc.narg('series_filter'), COALESCE(mi.series, '')) > 0.3)
   -- Fuzzy genre filter
   AND (sqlc.narg('genre_filter') = '' OR word_similarity(sqlc.narg('genre_filter'), COALESCE(mi.genre, '')) > 0.3)
+  -- Fuzzy publisher filter
+  AND (sqlc.narg('publisher_filter') = '' OR word_similarity(sqlc.narg('publisher_filter'), COALESCE(mi.publisher, '')) > 0.3)
   -- Fuzzy language filter
   AND (sqlc.narg('language_filter') = '' OR word_similarity(sqlc.narg('language_filter'), COALESCE(mi.language, '')) > 0.3)
   -- Tags filter (NEW - fuzzy match against tags array)
@@ -667,6 +745,7 @@ ORDER BY
         ELSE 0 END,
         word_similarity(sqlc.narg('author_filter'), COALESCE(mi.author, '')),
         word_similarity(sqlc.narg('genre_filter'), COALESCE(mi.genre, '')),
+        word_similarity(sqlc.narg('publisher_filter'), COALESCE(mi.publisher, '')),
         (SELECT MAX(word_similarity(sqlc.narg('tags_filter'), tag))
          FROM unnest(mi.tags_search) AS tag)
       )
@@ -819,11 +898,11 @@ UPDATE media_notes SET
     content = $2,
     position = $3,
     updated_at = NOW()
-WHERE id = $1
+WHERE id = $1 AND user_id = $4
 RETURNING *;
 
 -- name: DeleteMediaNote :exec
-DELETE FROM media_notes WHERE id = $1;
+DELETE FROM media_notes WHERE id = $1 AND user_id = $2;
 
 -- Media Highlights queries
 -- name: CreateMediaHighlight :one
@@ -845,11 +924,11 @@ UPDATE media_highlights SET
     color = $5,
     note_id = $6,
     updated_at = NOW()
-WHERE id = $1
+WHERE id = $1 AND user_id = $7
 RETURNING *;
 
 -- name: DeleteMediaHighlight :exec
-DELETE FROM media_highlights WHERE id = $1;
+DELETE FROM media_highlights WHERE id = $1 AND user_id = $2;
 
 -- ============================================
 -- ANNOTATION SYNC QUERIES (highlights)
@@ -892,7 +971,7 @@ UPDATE media_highlights SET
     updated_at = NOW(),
     deleted = FALSE,
     deleted_at = NULL
-WHERE id = $1
+WHERE id = $1 AND user_id = $15
 RETURNING *;
 
 -- name: TombstoneMediaHighlightByDedupKey :exec
@@ -907,7 +986,7 @@ UPDATE media_highlights SET
     deleted = TRUE,
     deleted_at = NOW(),
     last_modified_at = NOW()
-WHERE id = $1;
+WHERE id = $1 AND user_id = $2;
 
 -- name: PurgeExpiredHighlightTombstones :exec
 DELETE FROM media_highlights WHERE deleted = TRUE AND deleted_at < $1;
@@ -949,7 +1028,7 @@ UPDATE media_notes SET
     updated_at = NOW(),
     deleted = FALSE,
     deleted_at = NULL
-WHERE id = $1
+WHERE id = $1 AND user_id = $13
 RETURNING *;
 
 -- name: TombstoneMediaNoteByDedupKey :exec
@@ -964,7 +1043,7 @@ UPDATE media_notes SET
     deleted = TRUE,
     deleted_at = NOW(),
     last_modified_at = NOW()
-WHERE id = $1;
+WHERE id = $1 AND user_id = $2;
 
 -- name: PurgeExpiredNoteTombstones :exec
 DELETE FROM media_notes WHERE deleted = TRUE AND deleted_at < $1;
@@ -1007,7 +1086,7 @@ UPDATE media_bookmarks SET
     created_at = created_at,
     deleted = FALSE,
     deleted_at = NULL
-WHERE id = $1
+WHERE id = $1 AND user_id = $14
 RETURNING *;
 
 -- name: TombstoneMediaBookmarkByDedupKey :exec
@@ -1022,7 +1101,7 @@ UPDATE media_bookmarks SET
     deleted = TRUE,
     deleted_at = NOW(),
     last_modified_at = NOW()
-WHERE id = $1;
+WHERE id = $1 AND user_id = $2;
 
 -- name: PurgeExpiredBookmarkTombstones :exec
 DELETE FROM media_bookmarks WHERE deleted = TRUE AND deleted_at < $1;
@@ -1415,6 +1494,128 @@ SELECT
  ORDER BY read_count DESC
  LIMIT $2;
 
+-- STATISTICS (reading sessions) — time spent, pages, streaks, breakdowns.
+-- Every stats query scopes to the requesting user's VISIBLE libraries
+-- (family lens at the source) and single scan of reading_history.
+
+-- Full session rows for a range (summary math runs in Go: tz buckets,
+-- streaks, finished-book detection). The bucket/range key is the session
+-- END instant (the push time; NULL falls back to created_at) — the same
+-- value the capture stamps every write with.
+-- name: GetUserReadingSessionsRange :many
+SELECT
+    rh.id, rh.media_item_id, rh.device_id, rh.progress_percentage,
+    rh.reading_session_start, rh.reading_session_end,
+    rh.pages_read, rh.time_spent_seconds, rh.device_metadata, rh.created_at,
+    mi.title, mi.author, mi.library_id, mi.cover_image_path
+FROM reading_history rh
+JOIN media_items mi ON mi.id = rh.media_item_id
+WHERE rh.user_id = sqlc.arg('user_id')
+  AND COALESCE(rh.reading_session_end, rh.created_at) >= sqlc.arg('start_time')
+  AND COALESCE(rh.reading_session_end, rh.created_at) <= sqlc.arg('end_time')
+  AND (sqlc.narg('library_id')::uuid IS NULL OR mi.library_id = sqlc.narg('library_id')::uuid)
+  AND (sqlc.narg('visible_library_ids')::uuid[] IS NULL OR mi.library_id = ANY(sqlc.narg('visible_library_ids')::uuid[]))
+ORDER BY rh.created_at ASC;
+
+-- Per-library aggregation for the same range.
+-- name: GetUserLibraryBreakdown :many
+SELECT
+    l.id::uuid AS library_id,
+    l.name,
+    COUNT(*)::int AS session_count,
+    SUM(COALESCE(rh.time_spent_seconds, 0))::int AS total_seconds,
+    SUM(COALESCE(rh.pages_read, 0))::int AS total_pages,
+    COUNT(DISTINCT rh.media_item_id)::int AS book_count
+FROM reading_history rh
+JOIN media_items mi ON mi.id = rh.media_item_id
+JOIN libraries l ON l.id = mi.library_id
+WHERE rh.user_id = sqlc.arg('user_id')
+  AND COALESCE(rh.reading_session_end, rh.created_at) >= sqlc.arg('start_time')
+  AND COALESCE(rh.reading_session_end, rh.created_at) <= sqlc.arg('end_time')
+  AND (sqlc.narg('visible_library_ids')::uuid[] IS NULL OR mi.library_id = ANY(sqlc.narg('visible_library_ids')::uuid[]))
+GROUP BY l.id, l.name
+ORDER BY total_seconds DESC;
+
+-- Most-read books for a range (minutes), for the top list.
+-- name: GetTopBooksByMinutes :many
+SELECT
+    mi.id::uuid AS media_item_id,
+    mi.title,
+    mi.author,
+    mi.library_id,
+    mi.cover_image_path,
+    SUM(COALESCE(rh.time_spent_seconds, 0))::int AS total_seconds,
+    SUM(COALESCE(rh.pages_read, 0))::int AS total_pages,
+    COUNT(*)::int AS session_count,
+    MAX(rh.created_at) AS last_read
+FROM reading_history rh
+JOIN media_items mi ON mi.id = rh.media_item_id
+WHERE rh.user_id = sqlc.arg('user_id')
+  AND COALESCE(rh.reading_session_end, rh.created_at) >= sqlc.arg('start_time')
+  AND COALESCE(rh.reading_session_end, rh.created_at) <= sqlc.arg('end_time')
+  AND (sqlc.narg('visible_library_ids')::uuid[] IS NULL OR mi.library_id = ANY(sqlc.narg('visible_library_ids')::uuid[]))
+GROUP BY mi.id, mi.title, mi.author, mi.library_id, mi.cover_image_path
+ORDER BY total_seconds DESC
+LIMIT sqlc.arg('limit');
+
+-- Lifetime session rows for ONE book (the book-detail stats card).
+-- name: GetBookReadingSessions :many
+SELECT
+    rh.id, rh.device_id, rh.progress_percentage,
+    rh.reading_session_start, rh.reading_session_end,
+    rh.pages_read, rh.time_spent_seconds, rh.device_metadata, rh.created_at
+FROM reading_history rh
+WHERE rh.user_id = sqlc.arg('user_id')
+  AND rh.media_item_id = sqlc.arg('media_item_id')
+ORDER BY rh.created_at ASC;
+
+-- Distinct ACTIVE days (any captured session) bucketed in the user's
+-- timezone — the streak calendar. Scoped to a long look-back so the
+-- "longest streak" and a current streak longer than the selected range
+-- are both real.
+-- name: GetUserReadingActiveDays :many
+SELECT DISTINCT (COALESCE(rh.reading_session_end, rh.created_at) AT TIME ZONE sqlc.arg('tz')::text)::date::text AS day
+FROM reading_history rh
+JOIN media_items mi ON mi.id = rh.media_item_id
+WHERE rh.user_id = sqlc.arg('user_id')
+  AND COALESCE(rh.reading_session_end, rh.created_at) >= sqlc.arg('start_time')
+  AND (sqlc.narg('library_id')::uuid IS NULL OR mi.library_id = sqlc.narg('library_id')::uuid)
+  AND (sqlc.narg('visible_library_ids')::uuid[] IS NULL OR mi.library_id = ANY(sqlc.narg('visible_library_ids')::uuid[]))
+ORDER BY day ASC;
+
+-- Device existence probe for capture: the web/app progress paths
+-- historically stuff the user id into DeviceID (it only fed a broadcast
+-- label before stats); a capture row must only reference a REAL device.
+-- name: DeviceExistsForUser :one
+SELECT EXISTS(
+    SELECT 1 FROM devices
+    WHERE id = sqlc.arg('device_id') AND user_id = sqlc.arg('user_id')
+) AS has_device;
+
+-- Per-device reading breakdown for a range. LEFT JOIN so pushes that
+-- carry no device (web reader until it identifies) still appear as one
+-- "unattributed" bucket — device minutes must reconcile with the totals.
+-- name: GetUserDeviceBreakdown :many
+SELECT
+    d.id,
+    d.device_name,
+    d.device_type,
+    COUNT(*)::int AS session_count,
+    SUM(COALESCE(rh.time_spent_seconds, 0))::int AS total_seconds,
+    SUM(COALESCE(rh.pages_read, 0))::int AS total_pages,
+    COUNT(DISTINCT rh.media_item_id)::int AS book_count
+FROM reading_history rh
+JOIN media_items mi ON mi.id = rh.media_item_id
+LEFT JOIN devices d ON d.id = rh.device_id
+WHERE rh.user_id = sqlc.arg('user_id')
+  AND COALESCE(rh.reading_session_end, rh.created_at) >= sqlc.arg('start_time')
+  AND COALESCE(rh.reading_session_end, rh.created_at) <= sqlc.arg('end_time')
+  AND (sqlc.narg('visible_library_ids')::uuid[] IS NULL OR mi.library_id = ANY(sqlc.narg('visible_library_ids')::uuid[]))
+GROUP BY d.id, d.device_name, d.device_type
+ORDER BY total_seconds DESC;
+
+
+
  -- ============================================
 -- DEVICE MANAGEMENT & AUTH
 -- ============================================
@@ -1898,6 +2099,24 @@ SELECT * FROM media_items WHERE file_sha256 = $1;
 -- name: GetMediaItemBySHA256AndLibrary :one
 SELECT * FROM media_items WHERE file_sha256 = $1 AND library_id = $2;
 
+-- name: GetMediaItemsBySHA256AndSameLibraryType :many
+-- Cross-library move detection: identical content registered in a different
+-- library of the same type (ebooks stay with ebooks, comics with comics).
+-- Candidates may be active copies (deliberate duplicates - leave alone) or
+-- hidden/archived rows whose file vanished (move candidates - the scanner
+-- verifies disk state before repointing).
+SELECT mi.*, lt.name AS library_type_name
+FROM media_items mi
+JOIN libraries l ON mi.library_id = l.id
+JOIN library_types lt ON l.library_type_id = lt.id
+JOIN libraries target_lib ON target_lib.id = sqlc.arg('library_id')
+WHERE mi.file_sha256 = sqlc.arg('file_sha256')
+  AND mi.library_id <> sqlc.arg('library_id')
+  AND lt.id = target_lib.library_type_id
+ORDER BY (mi.archived_at IS NOT NULL) DESC,
+         mi.missing_scan_count DESC,
+         mi.created_at ASC;
+
 -- List all media items sharing a SHA-256 hash within a library (hash conflict group)
 -- name: ListMediaItemsBySHA256AndLibrary :many
 SELECT * FROM media_items WHERE file_sha256 = $1 AND library_id = $2 ORDER BY file_path;
@@ -2095,7 +2314,7 @@ SELECT * FROM collections WHERE id = $1;
 
 -- Get collections by user
 -- name: GetCollectionsByUser :many
-SELECT * FROM collections WHERE user_id = $1 ORDER BY created_at DESC;
+SELECT * FROM collections WHERE user_id = $1 AND deleted_at IS NULL ORDER BY created_at DESC;
 
 -- Get collection with book count
 -- name: GetCollectionWithBookCount :one
@@ -2120,6 +2339,11 @@ SET
 WHERE id = $1
 RETURNING *;
 
+-- Replace ONLY the auto_assign_rules document (rule CRUD: read-modify-write
+-- of the JSONB without touching metadata stale clients did not send).
+-- name: UpdateCollectionRulesJSON :one
+UPDATE collections SET auto_assign_rules = $2 WHERE id = $1 RETURNING *;
+
 -- Delete collection
 -- name: DeleteCollection :exec
 DELETE FROM collections WHERE id = $1;
@@ -2143,6 +2367,8 @@ SELECT ci.*, mi.title, mi.author, mi.cover_image_path, mi.library_id
 FROM collection_items ci
 JOIN media_items mi ON ci.media_item_id = mi.id
 WHERE ci.collection_id = $1
+  AND mi.archived_at IS NULL
+  AND mi.missing_scan_count = 0
 ORDER BY ci.added_at DESC;
 
 -- Get collections for book
@@ -2150,7 +2376,8 @@ ORDER BY ci.added_at DESC;
 SELECT c.*
 FROM collections c
 JOIN collection_items ci ON c.id = ci.collection_id
-WHERE ci.media_item_id = $1;
+WHERE ci.media_item_id = $1
+  AND c.deleted_at IS NULL;
 
 -- Check if book is in collection
 -- name: IsBookInCollection :one
@@ -2377,9 +2604,13 @@ LIMIT $1 OFFSET $2;
 -- ============================================
 
 -- Dashboard preferences queries
+-- The handler routes by scope: a Valid library_id targets the per-library
+-- table below; an absent one targets user_dashboard_preferences_global
+-- (the "All Libraries" view). Never pass NULL here — the loose NULL match
+-- was removed because it returned an arbitrary library's row.
 -- name: GetDashboardPreferences :one
 SELECT * FROM user_dashboard_preferences
-WHERE user_id = sqlc.narg('user_id') AND (sqlc.narg('library_id')::uuid IS NULL OR library_id = sqlc.narg('library_id')::uuid);
+WHERE user_id = sqlc.narg('user_id') AND library_id = sqlc.narg('library_id')::uuid;
 
 -- name: UpsertDashboardPreferences :one
 INSERT INTO user_dashboard_preferences (user_id, library_id, hidden_collections, collection_order, items_per_section)
@@ -2401,12 +2632,29 @@ SET hidden_collections = $2,
 WHERE user_id = $1 AND library_id = $5
 RETURNING *;
 
+-- Global (all-libraries) scope: exactly one row per user.
+-- name: GetGlobalDashboardPreferences :one
+SELECT user_id, hidden_collections, collection_order, items_per_section, updated_at FROM user_dashboard_preferences_global
+WHERE user_id = $1;
+
+-- name: UpsertGlobalDashboardPreferences :one
+INSERT INTO user_dashboard_preferences_global (user_id, hidden_collections, collection_order, items_per_section)
+VALUES ($1, $2, $3, $4)
+ON CONFLICT (user_id)
+DO UPDATE SET
+    hidden_collections = EXCLUDED.hidden_collections,
+    collection_order = EXCLUDED.collection_order,
+    items_per_section = EXCLUDED.items_per_section,
+    updated_at = NOW()
+RETURNING user_id, hidden_collections, collection_order, items_per_section, updated_at;
+
 -- Dashboard collections queries
 -- name: GetSystemCollectionsForDashboard :many
 SELECT * FROM collections
 WHERE user_id = $1
   AND is_system_collection = true
   AND show_on_dashboard = true
+  AND deleted_at IS NULL
 ORDER BY priority ASC;
 
 -- name: GetUserCollectionsForDashboard :many
@@ -2414,6 +2662,7 @@ SELECT c.* FROM collections c
 WHERE c.user_id = $1
   AND c.show_on_dashboard = true
   AND c.is_system_collection = false
+  AND c.deleted_at IS NULL
 ORDER BY priority ASC;
 
 -- name: DeleteUserSystemCollection :exec
@@ -2422,6 +2671,38 @@ WHERE user_id = $1
   AND name = $2
   AND is_system_collection = true;
 
+-- System collections are permanent: identity is (user_id, query_type).
+-- Restore/reset operate IN PLACE (the row id — and everything referencing
+-- it: shelf mappings, prefs order, links — never churns). Deleted sections
+-- are TOMBSTONED (deleted_at) and stay invisible until restored.
+
+-- name: GetSystemCollectionByQueryType :one
+-- Unfiltered by design: restore/seed must resolve tombstoned rows too.
+SELECT * FROM collections
+WHERE user_id = $1
+  AND query_type = $2
+  AND is_system_collection = true;
+
+-- name: TombstoneSystemCollection :exec
+UPDATE collections SET deleted_at = NOW() WHERE id = $1;
+
+-- name: RestoreSystemCollectionRow :one
+-- Full reset, in place: canonical metadata, back on the dashboard,
+-- un-tombstoned. Item assignments are cleared by the caller ("full").
+UPDATE collections
+SET name = $2,
+    description = $3,
+    icon = $4,
+    color = $5,
+    priority = $6,
+    show_on_dashboard = true,
+    deleted_at = NULL
+WHERE id = $1
+RETURNING *;
+
+-- name: ClearCollectionItems :exec
+DELETE FROM collection_items WHERE collection_id = $1;
+
 -- name: CreateSystemCollection :one
 INSERT INTO collections (user_id, name, description, icon, color, show_on_dashboard, query_type, priority, is_system_collection, auto_assign_rules)
 VALUES ($1, $2, $3, $4, $5, $6, $7, $8, true, 'null'::jsonb)
@@ -2449,12 +2730,16 @@ INNER JOIN (
     ORDER BY media_item_id, last_read_at DESC
 ) rp ON rp.media_item_id = mi.id
 WHERE (sqlc.narg('library_id')::uuid IS NULL OR mi.library_id = sqlc.narg('library_id')::uuid)
+  AND mi.archived_at IS NULL
+  AND mi.missing_scan_count = 0
 ORDER BY rp.last_read_at DESC
 LIMIT sqlc.narg('limit');
 
 -- name: GetRecentlyAddedItems :many
 SELECT mi.* FROM media_items mi
 WHERE (sqlc.narg('library_id')::uuid IS NULL OR mi.library_id = sqlc.narg('library_id')::uuid)
+  AND mi.archived_at IS NULL
+  AND mi.missing_scan_count = 0
 ORDER BY mi.imported_at DESC NULLS LAST, mi.created_at DESC
 LIMIT sqlc.narg('limit');
 
@@ -2468,12 +2753,16 @@ INNER JOIN (
     ORDER BY media_item_id, last_read_at DESC
 ) rp ON rp.media_item_id = mi.id
 WHERE (sqlc.narg('library_id')::uuid IS NULL OR mi.library_id = sqlc.narg('library_id')::uuid)
+  AND mi.archived_at IS NULL
+  AND mi.missing_scan_count = 0
 ORDER BY rp.last_read_at DESC
 LIMIT sqlc.narg('limit');
 
 -- name: GetNotStartedItems :many
 SELECT mi.* FROM media_items mi
 WHERE (sqlc.narg('library_id')::uuid IS NULL OR mi.library_id = sqlc.narg('library_id')::uuid)
+  AND mi.archived_at IS NULL
+  AND mi.missing_scan_count = 0
   AND NOT EXISTS (
     SELECT 1 FROM reading_progress rp
     WHERE rp.media_item_id = mi.id
@@ -2488,39 +2777,89 @@ SELECT mi.*, ci.excluded FROM media_items mi
 INNER JOIN collection_items ci ON ci.media_item_id = mi.id
 WHERE ci.collection_id = sqlc.narg('collection_id')
   AND (sqlc.narg('library_id')::uuid IS NULL OR mi.library_id = sqlc.narg('library_id')::uuid)
+  AND mi.archived_at IS NULL
+  AND mi.missing_scan_count = 0
 ORDER BY ci.added_at DESC
 LIMIT sqlc.narg('limit');
 
+-- Smart ("dynamic") collections: rules are evaluated LIVE at render, so
+-- membership comes from the candidate book set instead of collection_items.
+-- The set is scoped to the requesting user's visible libraries (family
+-- lens enforced at the source) and live items only — the same filters the
+-- static collection paths apply.
+-- name: GetVisibleLiveMediaForRules :many
+SELECT mi.* FROM media_items mi
+WHERE (sqlc.narg('library_id')::uuid IS NULL OR mi.library_id = sqlc.narg('library_id')::uuid)
+  AND (sqlc.narg('visible_library_ids')::uuid[] IS NULL OR mi.library_id = ANY(sqlc.narg('visible_library_ids')::uuid[]))
+  AND mi.archived_at IS NULL
+  AND mi.missing_scan_count = 0
+ORDER BY mi.title ASC;
+
+-- Live item count for a STATIC collection (rule-free cards on the
+-- collections page); same live filter as GetCollectionItems, plus the
+-- future-hybrid excluded exclusion and an optional library scope.
+-- name: CountCollectionLiveItems :one
+SELECT COUNT(*)::int FROM collection_items ci
+JOIN media_items mi ON ci.media_item_id = mi.id
+WHERE ci.collection_id = $1
+  AND NOT COALESCE(ci.excluded, false)
+  AND (sqlc.narg('library_id')::uuid IS NULL OR mi.library_id = sqlc.narg('library_id')::uuid)
+  AND mi.archived_at IS NULL
+  AND mi.missing_scan_count = 0;
+
 -- name: GetLibraryItems :many
 SELECT mi.* FROM media_items mi
 WHERE (sqlc.narg('library_id')::uuid IS NULL OR mi.library_id = sqlc.narg('library_id')::uuid)
+  AND mi.archived_at IS NULL
+  AND mi.missing_scan_count = 0
 ORDER BY mi.created_at DESC;
 
 -- name: GetDistinctSeries :many
-SELECT series, COUNT(*) as book_count,
+-- Series are grouped PER LIBRARY: the same series name in two libraries
+-- (novels vs manga adaptations, LN splits) stays two entries. Visible
+-- filter enforces per-user library visibility at the source.
+SELECT library_id, series, COUNT(*) as book_count,
        MAX(series_count) as total_in_series,
        MAX(created_at) as last_entry_at
 FROM media_items
-WHERE (sqlc.narg('library_id')::uuid IS NULL OR library_id = sqlc.narg('library_id')::uuid) AND series IS NOT NULL AND series != ''
-GROUP BY series
+WHERE (sqlc.narg('library_id')::uuid IS NULL OR library_id = sqlc.narg('library_id')::uuid)
+  AND (sqlc.narg('visible_library_ids')::uuid[] IS NULL OR library_id = ANY(sqlc.narg('visible_library_ids')::uuid[]))
+  AND archived_at IS NULL
+  AND missing_scan_count = 0
+  AND series IS NOT NULL AND series != ''
+GROUP BY library_id, series
 ORDER BY MAX(created_at) DESC
 LIMIT sqlc.narg('limit') OFFSET sqlc.narg('offset');
 
 -- name: GetDistinctSeriesCount :one
-SELECT COUNT(DISTINCT series)::int
+SELECT COUNT(DISTINCT (library_id, series))::int
 FROM media_items
-WHERE (sqlc.narg('library_id')::uuid IS NULL OR library_id = sqlc.narg('library_id')::uuid) AND series IS NOT NULL AND series != '';
+WHERE (sqlc.narg('library_id')::uuid IS NULL OR library_id = sqlc.narg('library_id')::uuid)
+  AND (sqlc.narg('visible_library_ids')::uuid[] IS NULL OR library_id = ANY(sqlc.narg('visible_library_ids')::uuid[]))
+  AND archived_at IS NULL
+  AND missing_scan_count = 0
+  AND series IS NOT NULL AND series != '';
 
 -- name: GetSeriesCovers :many
 SELECT cover_image_path, library_id
 FROM media_items
-WHERE (sqlc.narg('library_id')::uuid IS NULL OR library_id = sqlc.narg('library_id')::uuid) AND series = sqlc.narg('series') AND cover_image_path IS NOT NULL AND cover_image_path != ''
+WHERE (sqlc.narg('library_id')::uuid IS NULL OR library_id = sqlc.narg('library_id')::uuid)
+  AND (sqlc.narg('visible_library_ids')::uuid[] IS NULL OR library_id = ANY(sqlc.narg('visible_library_ids')::uuid[]))
+  AND archived_at IS NULL
+  AND missing_scan_count = 0
+  AND series = sqlc.narg('series') AND cover_image_path IS NOT NULL AND cover_image_path != ''
 ORDER BY series_number ASC NULLS LAST
 LIMIT sqlc.narg('limit');
 
 -- name: GetSeriesBooks :many
+-- Scoped to ONE library: same-name series in different libraries are
+-- different stories (manga adaptations, LN splits). Callers must pass a
+-- library_id and verify the requester can see that library.
 SELECT * FROM media_items
 WHERE series = sqlc.narg('series')
+  AND library_id = sqlc.narg('library_id')
+  AND archived_at IS NULL
+  AND missing_scan_count = 0
 ORDER BY series_number ASC NULLS LAST;
 
 -- name: GetContinueSeriesItems :many
@@ -2661,7 +3000,7 @@ RETURNING *;
 
 -- name: DeleteMediaBookmark :exec
 DELETE FROM media_bookmarks
-WHERE id = $1;
+WHERE id = $1 AND user_id = $2;
 
 -- name: UpdateMediaBookmark :one
 UPDATE media_bookmarks

internal/database/settings_registry.go

@@ -65,6 +65,7 @@ var SettingDefaults = []SettingDefault{
 	{Key: "password_require_lower", Value: "true", Type: SettingTypeBool, Category: "security", Group: "Password Quality", Description: "Require at least one lowercase letter (a-z)"},
 	{Key: "password_require_number", Value: "true", Type: SettingTypeBool, Category: "security", Group: "Password Quality", Description: "Require at least one number (0-9)"},
 	{Key: "password_require_special", Value: "true", Type: SettingTypeBool, Category: "security", Group: "Password Quality", Description: "Require at least one special character"},
+	{Key: "registration_enabled", Value: "true", Type: SettingTypeBool, Category: "security", Group: "Public Registration", Description: "Allow users to create their own accounts (admins can always create accounts)"},
 	{Key: "opds_default_page_size", Value: "50", Type: SettingTypeInt, Min: "1", Max: "500", Category: "api", Group: "OPDS Catalog", Description: "Default OPDS page size"},
 	{Key: "opds_max_page_size", Value: "200", Type: SettingTypeInt, Min: "1", Max: "1000", Category: "api", Group: "OPDS Catalog", Description: "Maximum OPDS page size"},
 	{Key: "device_rate_sync_per_min", Value: "60", Type: SettingTypeInt, Min: "1", Max: "10000", Category: "api", Group: "Device Rate Limits", Description: "Device sync requests per minute"},
@@ -188,6 +189,12 @@ func (r *SettingsRegistry) ScanPollInterval() time.Duration {
 // AutoScanEnabled reports whether auto-scanning is on.
 func (r *SettingsRegistry) AutoScanEnabled() bool { return r.getBool("auto_scan_enabled") }
 
+// RegistrationEnabled reports whether public signup is allowed. Admin user
+// creation is never affected — only self-service registration rides this
+// flag; handlers additionally grant the first-user exception (see
+// handlers/auth.go Register).
+func (r *SettingsRegistry) RegistrationEnabled() bool { return r.getBool("registration_enabled") }
+
 // DefaultTimezone returns the configured default timezone name.
 func (r *SettingsRegistry) DefaultTimezone() string { return r.raw("default_timezone") }
 

internal/handlers/analytics.go

@@ -2,6 +2,7 @@ package handlers
 
 import (
 	"bookhoard/internal/database"
+	"bookhoard/internal/utils"
 	"context"
 	"errors"
 	"fmt"
@@ -74,22 +75,32 @@ func (h *AnalyticsHandler) GetReadingStats(c *echo.Context) error {
 	startDate := c.QueryParam("start_date")
 	endDate := c.QueryParam("end_date")
 
+	// All range boundaries and day buckets are computed in the REQUESTING
+	// USER'S timezone: "today" and "which day did this session land on" are
+	// per-user calendar concepts, not UTC ones.
+	loc := utils.UserLocation(user.Timezone.String)
+	now := time.Now().In(loc)
+
 	if startDate == "" {
-		startDate = time.Now().AddDate(0, -1, 0).Format("01-02-2006")
+		startDate = now.AddDate(0, -1, 0).Format("01-02-2006")
 	}
 	if endDate == "" {
-		endDate = time.Now().Format("01-02-2006")
+		endDate = now.Format("01-02-2006")
 	}
 
-	startTime, err := time.Parse("01-02-2006", startDate)
+	startTime, err := time.ParseInLocation("01-02-2006", startDate, loc)
 	if err != nil {
 		return echo.NewHTTPError(http.StatusBadRequest, "invalid start_date format")
 	}
 
-	endTime, err := time.Parse("01-02-2006", endDate)
+	endTime, err := time.ParseInLocation("01-02-2006", endDate, loc)
 	if err != nil {
 		return echo.NewHTTPError(http.StatusBadRequest, "invalid end_date format")
 	}
+	// The query bounds with <=, so the end bound must be the last instant
+	// OF the end date — otherwise the end date's own sessions (including
+	// "today") never appear.
+	endTime = endTime.AddDate(0, 0, 1).Add(-time.Nanosecond)
 
 	ctx := context.Background()
 
@@ -103,12 +114,12 @@ func (h *AnalyticsHandler) GetReadingStats(c *echo.Context) error {
 		return echo.NewHTTPError(http.StatusInternalServerError, "failed to get reading history")
 	}
 
-	stats := h.calculateReadingStats(history)
+	stats := h.calculateReadingStats(history, loc)
 
 	return c.JSON(http.StatusOK, stats)
 }
 
-func (h *AnalyticsHandler) calculateReadingStats(history []database.GetUserReadingHistoryRow) ReadingStatsResponse {
+func (h *AnalyticsHandler) calculateReadingStats(history []database.GetUserReadingHistoryRow, loc *time.Location) ReadingStatsResponse {
 	stats := ReadingStatsResponse{
 		DailyReadingMinutes: make([]DailyReading, 0),
 	}
@@ -130,7 +141,7 @@ func (h *AnalyticsHandler) calculateReadingStats(history []database.GetUserReadi
 				longestSession = int(minutes)
 			}
 
-			dateKey := entry.CreatedAt.Time.Format("01-02-2006")
+			dateKey := entry.CreatedAt.Time.In(loc).Format("01-02-2006")
 			if dailyMap[dateKey] == nil {
 				dailyMap[dateKey] = &DailyReading{
 					Date: dateKey,
@@ -141,7 +152,7 @@ func (h *AnalyticsHandler) calculateReadingStats(history []database.GetUserReadi
 
 		if entry.PagesRead.Valid {
 			totalPages += int(entry.PagesRead.Int32)
-			dateKey := entry.CreatedAt.Time.Format("01-02-2006")
+			dateKey := entry.CreatedAt.Time.In(loc).Format("01-02-2006")
 			if dailyMap[dateKey] != nil {
 				dailyMap[dateKey].Pages += int(entry.PagesRead.Int32)
 			}
@@ -174,7 +185,7 @@ func (h *AnalyticsHandler) calculateReadingStats(history []database.GetUserReadi
 		stats.CompletionRate = float64(booksCompleted) / float64(totalBooks)
 	}
 
-	stats.MostActiveDay = h.calculateMostActiveDay(history)
+	stats.MostActiveDay = h.calculateMostActiveDay(history, loc)
 
 	for _, data := range dailyMap {
 		stats.DailyReadingMinutes = append(stats.DailyReadingMinutes, *data)
@@ -183,13 +194,13 @@ func (h *AnalyticsHandler) calculateReadingStats(history []database.GetUserReadi
 	return stats
 }
 
-func (h *AnalyticsHandler) calculateMostActiveDay(history []database.GetUserReadingHistoryRow) string {
+func (h *AnalyticsHandler) calculateMostActiveDay(history []database.GetUserReadingHistoryRow, loc *time.Location) string {
 	dayCount := make(map[string]int)
 
 	days := []string{"Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"}
 
 	for _, entry := range history {
-		day := days[entry.CreatedAt.Time.Weekday()]
+		day := days[entry.CreatedAt.Time.In(loc).Weekday()]
 		dayCount[day]++
 	}
 
@@ -222,7 +233,7 @@ func (h *AnalyticsHandler) GetDeviceUsage(c *echo.Context) error {
 		lastSync := ""
 		if u.LastSync != nil {
 			if t, ok := u.LastSync.(time.Time); ok {
-				lastSync = t.Format("01-02-2006 03:04:05 PM")
+				lastSync = utils.FormatTimeInTimezone(t, user.Timezone.String)
 			}
 		}
 
@@ -274,7 +285,7 @@ func (h *AnalyticsHandler) GetPopularBooks(c *echo.Context) error {
 		lastRead := ""
 		if book.LastRead != nil {
 			if t, ok := book.LastRead.(time.Time); ok {
-				lastRead = t.Format("01-02-2006 03:04:05 PM")
+				lastRead = utils.FormatTimeInTimezone(t, user.Timezone.String)
 			}
 		}
 

internal/handlers/auth.go

@@ -10,6 +10,7 @@ import (
 	"context"
 	"errors"
 	"fmt"
+	"html/template"
 	"net/http"
 	"os"
 	"path/filepath"
@@ -38,6 +39,23 @@ var SessionDurationSec = int(DefaultSessionDuration.Seconds())
 // SetSettings wires the tunable settings registry (optional).
 func (h *AuthHandler) SetSettings(s *database.SettingsRegistry) { h.settings = s }
 
+// defaultTimezone returns the system-wide default timezone for new users.
+// Falls back to UTC when no registry is wired, the setting is empty, or
+// the value is not a valid IANA location.
+func (h *AuthHandler) defaultTimezone() string {
+	if h.settings == nil {
+		return "UTC"
+	}
+	tz := h.settings.DefaultTimezone()
+	if tz == "" {
+		return "UTC"
+	}
+	if _, err := time.LoadLocation(tz); err != nil {
+		return "UTC"
+	}
+	return tz
+}
+
 // sessionDuration returns the active session duration from the registry.
 func (h *AuthHandler) sessionDuration() time.Duration {
 	if h.settings != nil {
@@ -101,6 +119,7 @@ type UserProfile struct {
 	FirstName string `json:"first_name"`
 	LastName  string `json:"last_name"`
 	Role      string `json:"role"`
+	Theme     string `json:"theme,omitempty"`
 }
 
 type UpdateProfileRequest struct {
@@ -173,6 +192,21 @@ func (h *AuthHandler) Register(c *echo.Context) error {
 		req.Role = strings.ToLower(req.Role)
 	}
 
+	// Public registration can be disabled by admins. The giveaway exception
+	// is an unconfigured server: with zero admins the first-user-becomes-
+	// admin bootstrap path must stay reachable (mirrors setupRedirect-
+	// Middleware's "users exist" reasoning). Admin account creation via the
+	// admin API never rides this route, so it is unaffected regardless.
+	if h.settings != nil && !h.settings.RegistrationEnabled() {
+		count, countErr := h.db.CountAdmins(c.Request().Context())
+		if countErr != nil || count > 0 {
+			if c.Request().Header.Get("HX-Request") == "true" {
+				return c.HTML(http.StatusForbidden, `<div class="text-red-500">Registration is disabled on this server</div>`)
+			}
+			return c.JSON(http.StatusForbidden, map[string]string{"error": "registration is disabled on this server"})
+		}
+	}
+
 	if _, err := h.db.GetUserByEmail(c.Request().Context(), req.Email); err == nil {
 		if c.Request().Header.Get("HX-Request") == "true" {
 			return c.HTML(http.StatusConflict, `<div class="text-red-500">Email already exists</div>`)
@@ -246,6 +280,7 @@ func (h *AuthHandler) Register(c *echo.Context) error {
 		LastName:     pgtype.Text{String: req.LastName, Valid: req.LastName != ""},
 		Theme:        pgtype.Text{String: "tokyo-night", Valid: true},
 		Role:         userRole,
+		Timezone:     pgtype.Text{String: h.defaultTimezone(), Valid: true},
 	})
 	if err != nil {
 		if c.Request().Header.Get("HX-Request") == "true" {
@@ -485,7 +520,14 @@ window.location.href = '%s';
 
 // GetProfile handles GET /api/auth/profile
 func (h *AuthHandler) GetProfile(c *echo.Context) error {
-	user := MustGetAuthenticatedUser(c)
+	ctxUser := MustGetAuthenticatedUser(c)
+	// The context user is a JWT-claims stub (id/email/username/role) —
+	// it carries no theme. Read the full row: clients (the Android app)
+	// sync their app-chrome theme from this field.
+	user, err := h.db.GetUser(c.Request().Context(), ctxUser.ID)
+	if err != nil {
+		return c.JSON(http.StatusInternalServerError, map[string]string{"error": "failed to load profile"})
+	}
 
 	firstName := ""
 	if user.FirstName.Valid {
@@ -502,6 +544,7 @@ func (h *AuthHandler) GetProfile(c *echo.Context) error {
 		FirstName: firstName,
 		LastName:  lastName,
 		Role:      user.Role,
+		Theme:     user.Theme.String,
 	})
 }
 
@@ -650,6 +693,15 @@ func (h *AuthHandler) UpdateProfile(c *echo.Context) error {
 		}
 	}
 
+	// Browser path (htmx modal + profile page): refresh so every rendered
+	// value (timezone select, table rows, header) reflects the save and the
+	// modal closes. A bare JSON body swapped into #profile-result read as
+	// "nothing happened" — the save DID land, invisibly.
+	if c.Request().Header.Get("HX-Request") == "true" {
+		c.Response().Header().Set("HX-Refresh", "true")
+		return c.HTML(http.StatusOK, `<div class="text-green-500">Profile updated.</div>`)
+	}
+
 	return c.JSON(http.StatusOK, map[string]string{"message": "profile updated successfully"})
 }
 
@@ -662,6 +714,104 @@ func (h *AuthHandler) ListUsers(c *echo.Context) error {
 	return c.JSON(http.StatusOK, users)
 }
 
+// GetPasswordRules handles GET /api/auth/password-rules (public — the
+// register page is pre-auth). Exposes the ACTIVE complexity configuration
+// so the UI requirement checkers mirror the real rules instead of
+// hardcoding defaults. The server remains the enforcer.
+func (h *AuthHandler) GetPasswordRules(c *echo.Context) error {
+	minLength, upper, lower, number, special := 8, true, true, true, true
+	if h.settings != nil {
+		r := h.settings.PasswordRules()
+		minLength, upper, lower, number, special =
+			r.MinLength, r.Upper, r.Lower, r.Number, r.Special
+	}
+	if minLength < 1 {
+		minLength = 8
+	}
+	return c.JSON(http.StatusOK, map[string]interface{}{
+		"min_length":      minLength,
+		"require_upper":   upper,
+		"require_lower":   lower,
+		"require_number":  number,
+		"require_special": special,
+	})
+}
+
+// AdminCreateUser handles POST /api/auth/users (AdminMiddleware-gated).
+// The admin's counterpart to public registration: creating an account for
+// someone else must work even when self-service registration is disabled
+// (the family/self-hosted default). The requester's admin role comes from
+// the route group, and the new account NEVER auto-logins — no tokens are
+// issued here, unlike Register.
+func (h *AuthHandler) AdminCreateUser(c *echo.Context) error {
+	var req RegisterRequest
+	if err := c.Bind(&req); err != nil {
+		return c.JSON(http.StatusBadRequest, map[string]string{"error": "invalid request"})
+	}
+	if err := c.Validate(&req); err != nil {
+		return c.JSON(http.StatusBadRequest, map[string]string{"error": err.Error()})
+	}
+
+	req.Username = strings.TrimSpace(req.Username)
+	if req.Username == "" {
+		return c.JSON(http.StatusBadRequest, map[string]string{"error": "username cannot be empty or whitespace"})
+	}
+
+	role := strings.ToLower(req.Role)
+	if role == "" {
+		role = "user"
+	}
+	if role != "user" && role != "admin" {
+		return c.JSON(http.StatusBadRequest, map[string]string{"error": "invalid role. must be 'user' or 'admin'"})
+	}
+
+	if _, err := h.db.GetUserByEmail(c.Request().Context(), req.Email); err == nil {
+		return c.JSON(http.StatusConflict, map[string]string{"error": "email already exists"})
+	}
+	if _, err := h.db.GetUserByUsername(c.Request().Context(), req.Username); err == nil {
+		return c.JSON(http.StatusConflict, map[string]string{"error": "username already exists"})
+	}
+
+	hashedPassword, err := bcrypt.GenerateFromPassword([]byte(req.Password), bcrypt.DefaultCost)
+	if err != nil {
+		return c.JSON(http.StatusInternalServerError, map[string]string{"error": "failed to hash password"})
+	}
+
+	user, err := h.db.CreateUser(c.Request().Context(), database.CreateUserParams{
+		Email:        req.Email,
+		Username:     req.Username,
+		PasswordHash: string(hashedPassword),
+		FirstName:    pgtype.Text{String: req.FirstName, Valid: req.FirstName != ""},
+		LastName:     pgtype.Text{String: req.LastName, Valid: req.LastName != ""},
+		Theme:        pgtype.Text{String: "tokyo-night", Valid: true},
+		Role:         role,
+		Timezone:     pgtype.Text{String: h.defaultTimezone(), Valid: true},
+	})
+	if err != nil {
+		return c.JSON(http.StatusInternalServerError, map[string]string{"error": err.Error()})
+	}
+
+	if err := h.CreateDefaultCollectionsForUser(c.Request().Context(), user.ID); err != nil {
+		return c.JSON(http.StatusInternalServerError, map[string]string{"error": "failed to create default collections"})
+	}
+
+	// The admin UI posts this via HTMX: refresh the page so the new user
+	// appears in the table, and confirm inline.
+	if c.Request().Header.Get("HX-Request") == "true" {
+		c.Response().Header().Set("HX-Refresh", "true")
+		return c.HTML(http.StatusCreated, `<div class="text-green-500">User "`+template.HTMLEscapeString(user.Username)+`" created.</div>`)
+	}
+
+	return c.JSON(http.StatusCreated, map[string]interface{}{
+		"id":         uuid.UUID(user.ID.Bytes).String(),
+		"email":      user.Email,
+		"username":   user.Username,
+		"role":       user.Role,
+		"timezone":   user.Timezone,
+		"created_at": user.CreatedAt,
+	})
+}
+
 // normalizePath cleans and normalizes folder paths for consistent storage and comparison
 func normalizePath(path string) string {
 	fmt.Printf("normalizePath input: '%s'\n", path)
@@ -1067,7 +1217,27 @@ func (h *AuthHandler) CreateDefaultCollectionsForUser(ctx context.Context, userI
 	}
 
 	for _, col := range defaultCollections {
-		_, err := h.db.CreateSystemCollection(ctx, database.CreateSystemCollectionParams{
+		// Idempotent by the STABLE identity (user + query_type): a
+		// preserved or renamed row heals to canonical metadata instead of
+		// duplicating (the naming-drift bug). Insert only when absent.
+		existing, err := h.db.GetSystemCollectionByQueryType(ctx, database.GetSystemCollectionByQueryTypeParams{
+			UserID:    userID,
+			QueryType: pgtype.Text{String: col.QueryType, Valid: true},
+		})
+		if err == nil {
+			if _, uerr := h.db.RestoreSystemCollectionRow(ctx, database.RestoreSystemCollectionRowParams{
+				ID:          existing.ID,
+				Name:        col.Name,
+				Description: pgtype.Text{String: col.Description, Valid: true},
+				Icon:        pgtype.Text{String: col.Icon, Valid: true},
+				Color:       pgtype.Text{String: col.Color, Valid: true},
+				Priority:    pgtype.Int4{Int32: col.Priority, Valid: true},
+			}); uerr != nil {
+				return uerr
+			}
+			continue
+		}
+		_, err = h.db.CreateSystemCollection(ctx, database.CreateSystemCollectionParams{
 			UserID:          userID,
 			Name:            col.Name,
 			Description:     pgtype.Text{String: col.Description, Valid: true},

internal/handlers/collections.go

@@ -40,6 +40,7 @@ type CreateCollectionRequest struct {
 	Description     string                 `form:"description" json:"description"`
 	Color           string                 `form:"color" json:"color"`
 	Icon            string                 `form:"icon" json:"icon"`
+	CollectionType  string                 `form:"collection_type" json:"collection_type"` // "static" (default) or "smart" (rule-based)
 	AutoAssignRules []services.Rule        `form:"auto_assign_rules" json:"auto_assign_rules"`
 	ViewSettings    map[string]interface{} `form:"view_settings" json:"view_settings"`
 }
@@ -111,10 +112,14 @@ func (h *CollectionHandler) CreateCollection(c *echo.Context) error {
 		req.ViewSettings,
 	)
 	if err != nil {
+		if errors.Is(err, services.ErrCollectionNameTaken) {
+			return c.JSON(http.StatusConflict, map[string]string{"error": "a collection with this name already exists"})
+		}
 		return c.JSON(http.StatusInternalServerError, map[string]string{"error": err.Error()})
 	}
 
 	bookCount := int32(0)
+	isSmart := req.CollectionType == "smart" || len(req.AutoAssignRules) > 0
 	response := map[string]interface{}{
 		"id":                uuid.UUID(collection.ID.Bytes).String(),
 		"user_id":           uuid.UUID(collection.UserID.Bytes).String(),
@@ -122,6 +127,7 @@ func (h *CollectionHandler) CreateCollection(c *echo.Context) error {
 		"description":       textToString(collection.Description),
 		"color":             textToString(collection.Color),
 		"icon":              textToString(collection.Icon),
+		"collection_type":   map[bool]string{true: "smart", false: "static"}[isSmart],
 		"auto_assign_rules": collection.AutoAssignRules,
 		"view_settings":     collection.ViewSettings,
 		"book_count":        bookCount,
@@ -130,7 +136,13 @@ func (h *CollectionHandler) CreateCollection(c *echo.Context) error {
 
 	// Add redirect header for HTMX requests
 	if c.Request().Header.Get("HX-Request") == "true" {
-		c.Response().Header().Set("HX-Redirect", "/collections")
+		// A smart collection starts with an empty ruleset; the builder is
+		// where it becomes real. Static collections head back to the grid.
+		if isSmart {
+			c.Response().Header().Set("HX-Redirect", "/collections/"+uuid.UUID(collection.ID.Bytes).String()+"/rules")
+		} else {
+			c.Response().Header().Set("HX-Redirect", "/collections")
+		}
 	}
 
 	return c.JSON(http.StatusCreated, response)
@@ -155,31 +167,46 @@ func (h *CollectionHandler) GetCollections(c *echo.Context) error {
 		AutoAssignRules json.RawMessage `json:"auto_assign_rules"`
 		CreatedAt       string          `json:"created_at"`
 		BookCount       int             `json:"book_count"`
+		IsSmart         bool            `json:"is_smart"`
 	}
 
 	response := make([]CollectionResponse, 0, len(collections))
 	for _, col := range collections {
-		if !includeAuto && len(col.AutoAssignRules) > 0 {
+		isSmart := h.collectionService.IsSmartCollection(col.AutoAssignRules)
+		if !includeAuto && isSmart {
+			// Legacy default for API clients (the Android app pre-dates
+			// smart collections): rule-driven collections stay opt-in so
+			// their membership could never be stale for old readers.
 			continue
 		}
 
 		bookCount := 0
+		var libUUID pgtype.UUID
 		if libraryID != "" {
-			libUUID, libErr := uuid.Parse(libraryID)
-			if libErr == nil {
-				items, countErr := h.db.GetCollectionItemsForDashboard(c.Request().Context(), database.GetCollectionItemsForDashboardParams{
-					CollectionID: pgtype.UUID{Bytes: col.ID.Bytes, Valid: true},
-					LibraryID:    pgtype.UUID{Bytes: libUUID, Valid: true},
-					Limit:        pgtype.Int4{Int32: 10000, Valid: true},
+			if libParsed, libErr := uuid.Parse(libraryID); libErr == nil {
+				libUUID = pgtype.UUID{Bytes: libParsed, Valid: true}
+			}
+		}
+		if isSmart {
+			rules := h.collectionService.ParseRules(col.AutoAssignRules)
+			visibleIDs, visErr := h.userVisibleLibraryIDs(c)
+			if visErr == nil {
+				matches, evalErr := h.collectionService.EvaluateSmartCollection(c.Request().Context(), rules, services.SmartEvalOptions{
+					LibraryID:  libUUID,
+					VisibleIDs: visibleIDs,
 				})
-				if countErr == nil {
-					for _, item := range items {
-						if !item.Excluded.Valid || !item.Excluded.Bool {
-							bookCount++
-						}
-					}
+				if evalErr == nil {
+					bookCount = len(matches)
 				}
 			}
+		} else {
+			count, countErr := h.db.CountCollectionLiveItems(c.Request().Context(), database.CountCollectionLiveItemsParams{
+				CollectionID: pgtype.UUID{Bytes: col.ID.Bytes, Valid: true},
+				LibraryID:    libUUID,
+			})
+			if countErr == nil {
+				bookCount = int(count)
+			}
 		}
 
 		response = append(response, CollectionResponse{
@@ -191,6 +218,7 @@ func (h *CollectionHandler) GetCollections(c *echo.Context) error {
 			AutoAssignRules: col.AutoAssignRules,
 			CreatedAt:       col.CreatedAt.Time.String(),
 			BookCount:       bookCount,
+			IsSmart:         isSmart,
 		})
 	}
 
@@ -233,7 +261,31 @@ func (h *CollectionHandler) GetCollection(c *echo.Context) error {
 		libUUID = pgtype.UUID{Bytes: parsed, Valid: true}
 	}
 
-	if collection.QueryType.Valid && collection.QueryType.String != "" {
+	isSmart := h.collectionService.IsSmartCollection(collection.AutoAssignRules)
+	if isSmart {
+		rules := h.collectionService.ParseRules(collection.AutoAssignRules)
+		visibleIDs, err := h.userVisibleLibraryIDs(c)
+		if err != nil {
+			return c.JSON(http.StatusInternalServerError, map[string]string{"error": err.Error()})
+		}
+		matches, evalErr := h.collectionService.EvaluateSmartCollection(c.Request().Context(), rules, services.SmartEvalOptions{
+			LibraryID:  libUUID,
+			VisibleIDs: visibleIDs,
+		})
+		if evalErr != nil {
+			return c.JSON(http.StatusInternalServerError, map[string]string{"error": evalErr.Error()})
+		}
+		bookList = make([]BookInfo, 0, len(matches))
+		for _, item := range matches {
+			itemUUID, _ := uuid.FromBytes(item.ID.Bytes[0:16])
+			bookList = append(bookList, BookInfo{
+				MediaItemID:    itemUUID.String(),
+				Title:          item.Title,
+				Author:         textToString(item.Author),
+				CoverImagePath: utils.ResolveMediaURL(item.LibraryID, item.CoverImagePath),
+			})
+		}
+	} else if collection.IsSystemCollection.Bool && collection.QueryType.Valid && collection.QueryType.String != "" && collection.QueryType.String != "filter" {
 		user := c.Get("user").(database.Users)
 		userUUID := uuid.UUID(user.ID.Bytes)
 		dashboardSvc := services.NewDashboardService(h.db)
@@ -320,6 +372,7 @@ func (h *CollectionHandler) GetCollection(c *echo.Context) error {
 		"view_settings":     viewSettings,
 		"books":             bookList,
 		"book_count":        len(bookList),
+		"is_smart":          isSmart,
 		"created_at":        collection.CreatedAt.Time.String(),
 	})
 }
@@ -397,6 +450,10 @@ func (h *CollectionHandler) AddBooks(c *echo.Context) error {
 		return c.JSON(http.StatusBadRequest, map[string]string{"error": "invalid collection id"})
 	}
 
+	if guardErr := h.rejectSmartMutation(c, collectionID); guardErr != nil {
+		return guardErr
+	}
+
 	user := c.Get("user").(database.Users)
 	userUUID := uuid.UUID(user.ID.Bytes)
 
@@ -444,6 +501,10 @@ func (h *CollectionHandler) RemoveBook(c *echo.Context) error {
 		return c.JSON(http.StatusBadRequest, map[string]string{"error": "invalid collection id"})
 	}
 
+	if guardErr := h.rejectSmartMutation(c, collectionID); guardErr != nil {
+		return guardErr
+	}
+
 	bookID, err := uuid.Parse(c.Param("bookId"))
 	if err != nil {
 		return c.JSON(http.StatusBadRequest, map[string]string{"error": "invalid book id"})
@@ -484,6 +545,10 @@ func (h *CollectionHandler) BulkRemoveBooks(c *echo.Context) error {
 		return c.JSON(http.StatusBadRequest, map[string]string{"error": "invalid collection id"})
 	}
 
+	if guardErr := h.rejectSmartMutation(c, collectionID); guardErr != nil {
+		return guardErr
+	}
+
 	user := c.Get("user").(database.Users)
 	userUUID := uuid.UUID(user.ID.Bytes)
 
@@ -724,6 +789,170 @@ func (h *CollectionHandler) GetUserCollectionsList(c *echo.Context) ([]database.
 	return h.collectionService.GetUserCollections(c.Request().Context(), userUUID)
 }
 
+// userVisibleLibraryIDs loads the requester's visible-library set (the
+// family lens). Smart-collection evaluation funnels every book candidate
+// through it so hidden libraries contribute nothing.
+func (h *CollectionHandler) userVisibleLibraryIDs(c *echo.Context) ([]pgtype.UUID, error) {
+	user, ok := c.Get("user").(database.Users)
+	if !ok {
+		return nil, echo.NewHTTPError(http.StatusUnauthorized, "invalid user")
+	}
+	rows, err := h.libraryService.GetUserVisibleLibraries(c.Request().Context(), user.ID)
+	if err != nil {
+		return nil, fmt.Errorf("failed to check library access: %w", err)
+	}
+	ids := make([]pgtype.UUID, 0, len(rows))
+	for _, lib := range rows {
+		if lib.ID.Valid {
+			ids = append(ids, lib.ID)
+		}
+	}
+	return ids, nil
+}
+
+// UserVisibleLibraryIDs is the exported entry point for the router's
+// frontend page handlers, which resolve the visible-library set before
+// evaluating smart-collection rule matches.
+func (h *CollectionHandler) UserVisibleLibraryIDs(c *echo.Context) ([]pgtype.UUID, error) {
+	return h.userVisibleLibraryIDs(c)
+}
+
+// CollectionService returns the underlying service so the router's
+// frontend handlers can share the exact same evaluation the API uses.
+func (h *CollectionHandler) CollectionService() *services.CollectionService {
+	return h.collectionService
+}
+
+// rejectSmartMutation returns a 400 for smart collections: membership is
+// derived live from rules, so stored link mutations have nothing to act
+// on. v1 has no hybrid mode — add/remove with both rules and hand-picked
+// books is deliberately unsupported (collection_items.excluded awaits it).
+func (h *CollectionHandler) rejectSmartMutation(c *echo.Context, collectionID uuid.UUID) *echo.HTTPError {
+	collection, err := h.GetCollectionData(c, collectionID)
+	if err != nil {
+		return echo.NewHTTPError(http.StatusNotFound, "collection not found")
+	}
+	if h.collectionService.IsSmartCollection(collection.AutoAssignRules) {
+		return echo.NewHTTPError(http.StatusBadRequest, "smart collections are rule-based — membership is managed by the collection's rules, not by hand")
+	}
+	return nil
+}
+
+type AddRuleRequest struct {
+	Field    string `json:"field" validate:"required"`
+	Operator string `json:"operator" validate:"required"`
+	Value    string `json:"value" validate:"required"`
+	Enabled  *bool  `json:"enabled"`
+	Priority int    `json:"priority"`
+}
+
+// AddRule handles POST /api/collections/:id/rules — appends one rule to
+// the ruleset. The first rule converts a static collection to smart.
+func (h *CollectionHandler) AddRule(c *echo.Context) error {
+	collectionID, err := uuid.Parse(c.Param("id"))
+	if err != nil {
+		return c.JSON(http.StatusBadRequest, map[string]string{"error": "invalid collection id"})
+	}
+
+	collection, err := h.GetCollectionData(c, collectionID)
+	if err != nil {
+		return c.JSON(http.StatusNotFound, map[string]string{"error": "collection not found"})
+	}
+	if collection.IsSystemCollection.Bool {
+		return c.JSON(http.StatusBadRequest, map[string]string{"error": "system collections cannot have rules"})
+	}
+
+	var req AddRuleRequest
+	if err := c.Bind(&req); err != nil {
+		return c.JSON(http.StatusBadRequest, map[string]string{"error": "invalid request"})
+	}
+	if err := c.Validate(&req); err != nil {
+		return c.JSON(http.StatusBadRequest, map[string]string{"error": err.Error()})
+	}
+
+	updated, rule, err := h.collectionService.AddRule(c.Request().Context(), collectionID, services.Rule{
+		Field:    req.Field,
+		Operator: req.Operator,
+		Value:    req.Value,
+		Enabled:  req.Enabled,
+		Priority: req.Priority,
+	})
+	if err != nil {
+		var ruleErr *services.RuleValidationError
+		if errors.As(err, &ruleErr) {
+			return c.JSON(http.StatusBadRequest, map[string]string{"error": err.Error()})
+		}
+		return c.JSON(http.StatusInternalServerError, map[string]string{"error": err.Error()})
+	}
+
+	return c.JSON(http.StatusCreated, map[string]interface{}{
+		"collection_id": uuid.UUID(updated.ID.Bytes).String(),
+		"rule":          rule,
+		"is_smart":      h.collectionService.IsSmartCollection(updated.AutoAssignRules),
+	})
+}
+
+// UpdateRule handles PUT /api/collections/:id/rules/:ruleId — currently
+// the enabled toggle; the payload may only carry {"enabled": bool}.
+func (h *CollectionHandler) UpdateRule(c *echo.Context) error {
+	collectionID, err := uuid.Parse(c.Param("id"))
+	if err != nil {
+		return c.JSON(http.StatusBadRequest, map[string]string{"error": "invalid collection id"})
+	}
+	ruleID := c.Param("ruleId")
+	if ruleID == "" {
+		return c.JSON(http.StatusBadRequest, map[string]string{"error": "rule id required"})
+	}
+
+	var req struct {
+		Enabled *bool `json:"enabled" validate:"required"`
+	}
+	if err := c.Bind(&req); err != nil {
+		return c.JSON(http.StatusBadRequest, map[string]string{"error": "invalid request"})
+	}
+	if err := c.Validate(&req); err != nil {
+		return c.JSON(http.StatusBadRequest, map[string]string{"error": err.Error()})
+	}
+
+	updated, err := h.collectionService.SetRuleEnabled(c.Request().Context(), collectionID, ruleID, *req.Enabled)
+	if err != nil {
+		if strings.Contains(err.Error(), "rule not found") {
+			return c.JSON(http.StatusNotFound, map[string]string{"error": err.Error()})
+		}
+		return c.JSON(http.StatusInternalServerError, map[string]string{"error": err.Error()})
+	}
+
+	return c.JSON(http.StatusOK, map[string]interface{}{
+		"collection_id": uuid.UUID(updated.ID.Bytes).String(),
+		"is_smart":      h.collectionService.IsSmartCollection(updated.AutoAssignRules),
+	})
+}
+
+// RemoveRule handles DELETE /api/collections/:id/rules/:ruleId.
+func (h *CollectionHandler) RemoveRule(c *echo.Context) error {
+	collectionID, err := uuid.Parse(c.Param("id"))
+	if err != nil {
+		return c.JSON(http.StatusBadRequest, map[string]string{"error": "invalid collection id"})
+	}
+	ruleID := c.Param("ruleId")
+	if ruleID == "" {
+		return c.JSON(http.StatusBadRequest, map[string]string{"error": "rule id required"})
+	}
+
+	updated, err := h.collectionService.RemoveRule(c.Request().Context(), collectionID, ruleID)
+	if err != nil {
+		if strings.Contains(err.Error(), "rule not found") {
+			return c.JSON(http.StatusNotFound, map[string]string{"error": err.Error()})
+		}
+		return c.JSON(http.StatusInternalServerError, map[string]string{"error": err.Error()})
+	}
+
+	return c.JSON(http.StatusOK, map[string]interface{}{
+		"collection_id": uuid.UUID(updated.ID.Bytes).String(),
+		"is_smart":      h.collectionService.IsSmartCollection(updated.AutoAssignRules),
+	})
+}
+
 type TestRulesRequest struct {
 	Rules []map[string]interface{} `json:"rules" validate:"required"`
 }
@@ -745,16 +974,32 @@ func (h *CollectionHandler) TestRules(c *echo.Context) error {
 		return c.JSON(http.StatusBadRequest, map[string]string{"error": err.Error()})
 	}
 
-	mediaItems, err := h.db.ListMediaItems(c.Request().Context(), database.ListMediaItemsParams{
-		Limit:  1000,
-		Offset: 0,
+	// Candidates mirror what smart collections actually evaluate against:
+	// the requester's visible libraries and live items only — the preview
+	// must not promise matches the live render will never produce.
+	visibleIDs, err := h.userVisibleLibraryIDs(c)
+	if err != nil {
+		return c.JSON(http.StatusInternalServerError, map[string]string{"error": err.Error()})
+	}
+	var visibleArg []pgtype.UUID
+	if len(visibleIDs) > 0 {
+		visibleArg = visibleIDs
+	}
+	mediaItems, err := h.db.GetVisibleLiveMediaForRules(c.Request().Context(), database.GetVisibleLiveMediaForRulesParams{
+		LibraryID:         pgtype.UUID{},
+		VisibleLibraryIds: visibleArg,
 	})
 	if err != nil {
 		return c.JSON(http.StatusInternalServerError, map[string]string{"error": "failed to load media items"})
 	}
 
+	listRows := make([]database.ListMediaItemsRow, len(mediaItems))
+	for i, item := range mediaItems {
+		listRows[i] = mediaItemsToListMediaItemsRow(item)
+	}
+
 	var matches []BookMatch
-	for _, item := range mediaItems {
+	for _, item := range listRows {
 		matchReason := h.checkRulesAgainstBook(item, req.Rules)
 		if matchReason != "" {
 			author := ""
@@ -883,6 +1128,16 @@ func (h *CollectionHandler) HandleBulkAddBooks(c *echo.Context) error {
 		return c.JSON(http.StatusBadRequest, map[string]string{"error": "operations required"})
 	}
 
+	// Smart collections are rejected up front per operation so the
+	// caller sees a clean, actionable error instead of silent no-ops.
+	for _, op := range req.Operations {
+		if colUUID, err := uuid.Parse(op.CollectionID); err == nil {
+			if guardErr := h.rejectSmartMutation(c, colUUID); guardErr != nil {
+				return guardErr
+			}
+		}
+	}
+
 	results := make([]map[string]interface{}, 0)
 	successCount := 0
 	failedCount := 0

internal/handlers/conflicts.go

@@ -406,6 +406,7 @@ func (h *ConflictHandler) applyHighlightResolution(ctx context.Context, mediaIte
 		LastModifiedAt:    pgtype.Timestamptz{Time: time.Now(), Valid: true},
 		LastModifiedSource: pgtype.Text{String: "conflict_resolution", Valid: true},
 		DeviceSyncData:     existing.DeviceSyncData,
+		UserID:             userID,
 	}
 
 	if v, ok := data["selection_text"].(string); ok {
@@ -451,6 +452,7 @@ func (h *ConflictHandler) applyBookmarkResolution(ctx context.Context, mediaItem
 		LastModifiedAt:    pgtype.Timestamptz{Time: time.Now(), Valid: true},
 		LastModifiedSource: pgtype.Text{String: "conflict_resolution", Valid: true},
 		DeviceSyncData:     existing.DeviceSyncData,
+		UserID:             userID,
 	}
 
 	if v, ok := data["title"].(string); ok {
@@ -486,6 +488,7 @@ func (h *ConflictHandler) applyNoteResolution(ctx context.Context, mediaItemID p
 		LastModifiedAt:     pgtype.Timestamptz{Time: time.Now(), Valid: true},
 		LastModifiedSource: pgtype.Text{String: "conflict_resolution", Valid: true},
 		DeviceSyncData:     existing.DeviceSyncData,
+		UserID:             userID,
 	}
 
 	if v, ok := data["content"].(string); ok {

internal/handlers/dashboard.go

@@ -75,7 +75,9 @@ func (h *DashboardHandler) UpdatePreferences(c *echo.Context) error {
 	userUUID := uuid.UUID(user.ID.Bytes)
 
 	var req struct {
-		LibraryID         string   `json:"library_id"`
+		// nil (JSON null/absent) = the global All Libraries scope;
+		// empty string is a LOST value, not a scope — rejected loudly.
+		LibraryID         *string  `json:"library_id"`
 		HiddenCollections []string `json:"hidden_collections"`
 		CollectionOrder   []string `json:"collection_order"`
 		ItemsPerSection   int      `json:"items_per_section"`
@@ -85,9 +87,16 @@ func (h *DashboardHandler) UpdatePreferences(c *echo.Context) error {
 		return c.JSON(http.StatusBadRequest, map[string]string{"error": "Invalid request"})
 	}
 
-	libUUID, err := uuid.Parse(req.LibraryID)
-	if err != nil {
-		return c.JSON(http.StatusBadRequest, map[string]string{"error": "invalid library_id"})
+	var libUUID pgtype.UUID
+	if req.LibraryID != nil {
+		if *req.LibraryID == "" {
+			return c.JSON(http.StatusBadRequest, map[string]string{"error": "invalid library_id"})
+		}
+		parsed, err := uuid.Parse(*req.LibraryID)
+		if err != nil {
+			return c.JSON(http.StatusBadRequest, map[string]string{"error": "invalid library_id"})
+		}
+		libUUID = pgtype.UUID{Bytes: parsed, Valid: true}
 	}
 
 	// Sanitize preferences (remove duplicates)
@@ -97,7 +106,7 @@ func (h *DashboardHandler) UpdatePreferences(c *echo.Context) error {
 
 	prefs, err := h.dashboardService.UpsertDashboardPreferences(c.Request().Context(), database.UpsertDashboardPreferencesParams{
 		UserID:            pgtype.UUID{Bytes: userUUID, Valid: true},
-		LibraryID:         pgtype.UUID{Bytes: libUUID, Valid: true},
+		LibraryID:         libUUID,
 		HiddenCollections: req.HiddenCollections,
 		CollectionOrder:   req.CollectionOrder,
 		ItemsPerSection:   pgtype.Int4{Int32: int32(req.ItemsPerSection), Valid: true},

internal/handlers/devices.go

@@ -6,11 +6,16 @@ import (
 	"crypto/rand"
 	"encoding/base64"
 	"encoding/json"
+	"errors"
 	"fmt"
+	"log/slog"
 	"net/http"
+	"sync"
 	"time"
 
 	"github.com/google/uuid"
+	"github.com/jackc/pgx/v5"
+	"github.com/jackc/pgx/v5/pgconn"
 	"github.com/jackc/pgx/v5/pgtype"
 	"github.com/labstack/echo/v5"
 	"github.com/skip2/go-qrcode"
@@ -106,7 +111,14 @@ type PendingRegistration struct {
 	SyncEndpoints    map[string]string
 }
 
-var pendingRegistrations = make(map[string]*PendingRegistration)
+// pendingRegistrations holds in-flight (unapproved) device registrations.
+// HTTP handlers touch it from multiple goroutines — every access must hold
+// pendingMu (Go maps are not safe for concurrent use; a racing write is a
+// runtime fatal, not an error).
+var (
+	pendingRegistrations = make(map[string]*PendingRegistration)
+	pendingMu            sync.Mutex
+)
 
 func (h *DeviceHandler) InitiateRegistration(c *echo.Context) error {
 	req := DeviceRegistrationRequest{}
@@ -130,7 +142,9 @@ func (h *DeviceHandler) InitiateRegistration(c *echo.Context) error {
 		CreatedAt:        time.Now(),
 	}
 
+	pendingMu.Lock()
 	pendingRegistrations[registrationID] = registration
+	pendingMu.Unlock()
 
 	authURL := fmt.Sprintf("%s/devices/approve/%s", h.cfg.BaseURL, registrationID)
 
@@ -167,26 +181,34 @@ func (h *DeviceHandler) CheckRegistrationStatus(c *echo.Context) error {
 		return c.JSON(http.StatusBadRequest, map[string]string{"error": "invalid request format"})
 	}
 
+	pendingMu.Lock()
 	registration, exists := pendingRegistrations[req.RegistrationID]
 	if !exists {
+		pendingMu.Unlock()
 		return c.JSON(http.StatusNotFound, map[string]string{"error": "registration not found"})
 	}
 
 	if time.Now().After(registration.ExpiresAt) {
 		delete(pendingRegistrations, req.RegistrationID)
+		pendingMu.Unlock()
 		return c.JSON(http.StatusGone, map[string]string{"error": "registration expired"})
 	}
 
 	if registration.Approved {
 		delete(pendingRegistrations, req.RegistrationID)
-
-		return c.JSON(http.StatusOK, DeviceAuthStatusResponse{
+		// Snapshot under the lock: the approver wrote these fields, and
+		// the row is gone from the map — no other reader/writer remains.
+		resp := DeviceAuthStatusResponse{
 			Status:        "approved",
 			AuthToken:     registration.AuthToken,
 			DeviceID:      registration.DeviceID,
 			SyncEndpoints: registration.SyncEndpoints,
-		})
+		}
+		pendingMu.Unlock()
+
+		return c.JSON(http.StatusOK, resp)
 	}
+	pendingMu.Unlock()
 
 	return c.JSON(http.StatusOK, DeviceAuthStatusResponse{
 		Status:    "pending",
@@ -552,17 +574,21 @@ func (h *DeviceHandler) ApproveDevice(c *echo.Context) error {
 
 	registrationID := c.Param("registration_id")
 
+	pendingMu.Lock()
 	registration, exists := pendingRegistrations[registrationID]
 	if !exists {
+		pendingMu.Unlock()
 		return c.JSON(http.StatusNotFound, map[string]string{"error": "registration not found"})
 	}
 
 	if time.Now().After(registration.ExpiresAt) {
 		delete(pendingRegistrations, registrationID)
+		pendingMu.Unlock()
 		return c.JSON(http.StatusGone, map[string]string{"error": "registration expired"})
 	}
 
 	if registration.Approved {
+		pendingMu.Unlock()
 		return c.JSON(http.StatusOK, map[string]interface{}{
 			"message":     "device already approved",
 			"device_name": registration.DeviceName,
@@ -570,6 +596,7 @@ func (h *DeviceHandler) ApproveDevice(c *echo.Context) error {
 			"approved":    true,
 		})
 	}
+	pendingMu.Unlock()
 
 	authToken, err := generateDeviceToken()
 	if err != nil {
@@ -577,23 +604,87 @@ func (h *DeviceHandler) ApproveDevice(c *echo.Context) error {
 	}
 
 	pgUserID := pgtype.UUID{Bytes: [16]byte(userUUID), Valid: true}
-	syncEnabled := pgtype.Bool{Bool: true, Valid: true}
-	autoSync := pgtype.Bool{Bool: true, Valid: true}
-	syncFreq := pgtype.Int4{Int32: 5, Valid: true}
 
-	device, err := h.db.CreateDevice(c.Request().Context(), database.CreateDeviceParams{
-		UserID:               pgUserID,
-		DeviceName:           registration.DeviceName,
-		DeviceType:           registration.DeviceType,
-		DeviceIdentifier:     registration.DeviceIdentifier,
-		AuthToken:            authToken,
-		SyncEnabled:          syncEnabled,
-		AutoSync:             autoSync,
-		SyncFrequencyMinutes: syncFreq,
-		DeviceMetadata:       []byte("{}"),
-	})
-	if err != nil {
-		return c.JSON(http.StatusInternalServerError, map[string]string{"error": "failed to create device"})
+	// Re-approval: app reinstalls that preserve data (e.g. Android Studio
+	// installDebug over an existing install) re-register with the SAME
+	// device_identifier, but the devices row from the previous install
+	// still exists — device_identifier is UNIQUE, so a blind INSERT fails
+	// with a unique violation (the historical "approve returns 500 after
+	// reinstall" bug). Look the device up first and rotate its token
+	// instead; a fresh install MUST get fresh credentials, so the old
+	// token is invalidated either way.
+	rotateExisting := func(existing database.Devices) (database.Devices, bool, error) {
+		// The identifier is globally unique; a row owned by another user
+		// means cross-account identifier reuse — refuse it.
+		if !existing.UserID.Valid || existing.UserID.Bytes != pgUserID.Bytes {
+			return existing, false, nil
+		}
+		updated, err := h.db.UpdateDeviceAuthToken(c.Request().Context(),
+			database.UpdateDeviceAuthTokenParams{
+				ID:        pgtype.UUID{Bytes: existing.ID.Bytes, Valid: true},
+				AuthToken: authToken,
+			})
+		return updated, true, err
+	}
+
+	existing, err := h.db.GetDeviceByIdentifier(c.Request().Context(),
+		registration.DeviceIdentifier)
+	var device database.Devices
+	switch {
+	case err == nil:
+		// Known device: rotate the token, keep the row (id unchanged —
+		// highlights/bookmarks/progress anchored to it stay valid).
+		var ok bool
+		device, ok, err = rotateExisting(existing)
+		if err != nil {
+			slog.Error("device re-approval failed",
+				"registration_id", registrationID, "error", err)
+			return c.JSON(http.StatusInternalServerError,
+				map[string]string{"error": "failed to approve device"})
+		}
+		if !ok {
+			return c.JSON(http.StatusConflict,
+				map[string]string{"error": "device identifier already registered to another user"})
+		}
+	case errors.Is(err, pgx.ErrNoRows):
+		device, err = h.db.CreateDevice(c.Request().Context(), database.CreateDeviceParams{
+			UserID:               pgUserID,
+			DeviceName:           registration.DeviceName,
+			DeviceType:           registration.DeviceType,
+			DeviceIdentifier:     registration.DeviceIdentifier,
+			AuthToken:            authToken,
+			SyncEnabled:          pgtype.Bool{Bool: true, Valid: true},
+			AutoSync:             pgtype.Bool{Bool: true, Valid: true},
+			SyncFrequencyMinutes: pgtype.Int4{Int32: 5, Valid: true},
+			DeviceMetadata:       []byte("{}"),
+		})
+		if err != nil {
+			// Concurrent approve racing us onto the unique index: fall
+			// through to the rotate path for the winner's row.
+			var pgErr *pgconn.PgError
+			if asErr := errors.As(err, &pgErr); asErr && pgErr.Code == "23505" {
+				if winner, lerr := h.db.GetDeviceByIdentifier(
+					c.Request().Context(), registration.DeviceIdentifier); lerr == nil {
+					var ok bool
+					device, ok, err = rotateExisting(winner)
+					if err == nil && !ok {
+						return c.JSON(http.StatusConflict,
+							map[string]string{"error": "device identifier already registered to another user"})
+					}
+				}
+			}
+		}
+		if err != nil {
+			slog.Error("device creation failed",
+				"registration_id", registrationID, "error", err)
+			return c.JSON(http.StatusInternalServerError,
+				map[string]string{"error": "failed to create device"})
+		}
+	default:
+		slog.Error("device lookup failed",
+			"registration_id", registrationID, "error", err)
+		return c.JSON(http.StatusInternalServerError,
+			map[string]string{"error": "failed to look up device"})
 	}
 
 	syncEndpoints := map[string]string{}
@@ -607,11 +698,16 @@ func (h *DeviceHandler) ApproveDevice(c *echo.Context) error {
 		syncEndpoints["library"] = fmt.Sprintf("%s/api/sync/kobo/library", h.cfg.BaseURL)
 	}
 
+	// Publish the credentials under the map lock: the status poller
+	// snapshots these fields only after Approved flips, so the token can
+	// never be read half-written.
+	pendingMu.Lock()
 	registration.UserID = userUUID
 	registration.Approved = true
 	registration.AuthToken = authToken
 	registration.DeviceID = device.ID.Bytes
 	registration.SyncEndpoints = syncEndpoints
+	pendingMu.Unlock()
 
 	return c.JSON(http.StatusOK, map[string]interface{}{
 		"message":         "device approved successfully",
@@ -625,12 +721,15 @@ func (h *DeviceHandler) ApproveDevice(c *echo.Context) error {
 func (h *DeviceHandler) RejectDevice(c *echo.Context) error {
 	registrationID := c.Param("registration_id")
 
+	pendingMu.Lock()
 	_, exists := pendingRegistrations[registrationID]
 	if !exists {
+		pendingMu.Unlock()
 		return c.JSON(http.StatusNotFound, map[string]string{"error": "registration not found"})
 	}
 
 	delete(pendingRegistrations, registrationID)
+	pendingMu.Unlock()
 
 	return c.JSON(http.StatusOK, map[string]string{
 		"message": "device registration rejected",
@@ -639,6 +738,7 @@ func (h *DeviceHandler) RejectDevice(c *echo.Context) error {
 
 func (h *DeviceHandler) GetPendingRegistrationsData(c *echo.Context) ([]map[string]interface{}, error) {
 	registrations := []map[string]interface{}{}
+	pendingMu.Lock()
 	for _, reg := range pendingRegistrations {
 		if reg.UserID == (uuid.UUID{}) {
 			registrations = append(registrations, map[string]interface{}{
@@ -652,6 +752,7 @@ func (h *DeviceHandler) GetPendingRegistrationsData(c *echo.Context) ([]map[stri
 			})
 		}
 	}
+	pendingMu.Unlock()
 
 	return registrations, nil
 }
@@ -664,6 +765,7 @@ func (h *DeviceHandler) ListPendingRegistrations(c *echo.Context) error {
 	}
 
 	registrations := []map[string]interface{}{}
+	pendingMu.Lock()
 	for _, reg := range pendingRegistrations {
 		if reg.UserID == userUUID || reg.UserID == (uuid.UUID{}) {
 			registrations = append(registrations, map[string]interface{}{
@@ -677,6 +779,7 @@ func (h *DeviceHandler) ListPendingRegistrations(c *echo.Context) error {
 			})
 		}
 	}
+	pendingMu.Unlock()
 
 	return c.JSON(http.StatusOK, map[string]interface{}{
 		"registrations":         registrations,

internal/handlers/kobo.go

@@ -254,9 +254,9 @@ type KoboInitResponse struct {
 }
 
 type KoboSyncStatus struct {
-	Status            string                 `json:"Status"`
-	MarkupsSynced     int                    `json:"MarkupsSynced"`
-	BookmarksSynced   int                    `json:"BookmarksSynced"`
+	Status             string                  `json:"Status"`
+	MarkupsSynced      int                     `json:"MarkupsSynced"`
+	BookmarksSynced    int                     `json:"BookmarksSynced"`
 	DeletedAnnotations []KoboDeletedAnnotation `json:"DeletedAnnotations,omitempty"`
 }
 
@@ -448,16 +448,17 @@ func (h *KoboHandler) Markup(c *echo.Context) error {
 
 		if h.progressSvc != nil {
 			_, err = h.progressSvc.SaveProgress(c.Request().Context(), wsync.SaveProgressRequest{
-				MediaItemID: pgMediaUUID,
-				UserID:      pgUserID,
-				Source:      "kobo",
-				DeviceID:    pgtype.UUID{Bytes: deviceID, Valid: true},
-				Percentage:  &percentage,
-				CurrentPage: currentPage,
-				TotalPages:  totalPages,
-				DeviceType:  "kobo",
-				DeviceName:  device.DeviceName,
-				Broadcast:   true,
+				MediaItemID:  pgMediaUUID,
+				UserID:       pgUserID,
+				Source:       "kobo",
+				DeviceID:     pgtype.UUID{Bytes: deviceID, Valid: true},
+				Percentage:   &percentage,
+				CurrentPage:  currentPage,
+				TotalPages:   totalPages,
+				DeviceType:   "kobo",
+				DeviceName:   device.DeviceName,
+				Broadcast:    true,
+				ClearLocator: true,
 			})
 		} else {
 			_, err = h.db.UpdateUniversalProgress(c.Request().Context(), database.UpdateUniversalProgressParams{
@@ -798,14 +799,15 @@ func (h *KoboHandler) AnalyticsGettests(c *echo.Context) error {
 
 		if h.progressSvc != nil {
 			_, err = h.progressSvc.SaveProgress(c.Request().Context(), wsync.SaveProgressRequest{
-				MediaItemID: pgMediaUUID,
-				UserID:      pgUserID,
-				Source:      "kobo",
-				DeviceID:    pgtype.UUID{Bytes: deviceID, Valid: true},
-				Percentage:  &percentage,
-				DeviceType:  "kobo",
-				DeviceName:  device.DeviceName,
-				Broadcast:   true,
+				MediaItemID:  pgMediaUUID,
+				UserID:       pgUserID,
+				Source:       "kobo",
+				DeviceID:     pgtype.UUID{Bytes: deviceID, Valid: true},
+				Percentage:   &percentage,
+				DeviceType:   "kobo",
+				DeviceName:   device.DeviceName,
+				Broadcast:    true,
+				ClearLocator: true,
 			})
 		} else {
 			_, err = h.db.UpdateUniversalProgress(c.Request().Context(), database.UpdateUniversalProgressParams{
@@ -860,14 +862,15 @@ func (h *KoboHandler) SyncFromServer(c *echo.Context) error {
 
 		if h.progressSvc != nil {
 			_, err = h.progressSvc.SaveProgress(c.Request().Context(), wsync.SaveProgressRequest{
-				MediaItemID: pgMediaUUID,
-				UserID:      pgUserID,
-				Source:      "bookhoard",
-				DeviceID:    pgtype.UUID{Bytes: deviceID, Valid: true},
-				Percentage:  &percentage,
-				DeviceType:  "kobo",
-				DeviceName:  device.DeviceName,
-				Broadcast:   false,
+				MediaItemID:  pgMediaUUID,
+				UserID:       pgUserID,
+				Source:       "bookhoard",
+				DeviceID:     pgtype.UUID{Bytes: deviceID, Valid: true},
+				Percentage:   &percentage,
+				DeviceType:   "kobo",
+				DeviceName:   device.DeviceName,
+				Broadcast:    false,
+				ClearLocator: true,
 			})
 		} else {
 			_, err = h.db.UpdateUniversalProgress(c.Request().Context(), database.UpdateUniversalProgressParams{

internal/handlers/koreader.go

@@ -6,6 +6,7 @@ import (
 	wsync "bookhoard/internal/sync"
 	"context"
 	"encoding/json"
+	"errors"
 	"fmt"
 	"log"
 	"net/http"
@@ -14,6 +15,8 @@ import (
 	"time"
 	"unicode/utf8"
 
+	"github.com/jackc/pgx/v5"
+
 	"github.com/google/uuid"
 	"github.com/jackc/pgx/v5/pgtype"
 	"github.com/labstack/echo/v5"
@@ -93,7 +96,22 @@ func (h *KOReaderHandler) convertHighlightPositions(ec annotationEpub, pos0, pos
 	if pos0 == "" || !ec.convertible() {
 		return "", ""
 	}
-	startLoc := wsync.ConvertToCanonical(wsync.LocatorSourceKOReader, pos0, percentage, contextText, ec.mediaItem.FormatGroup, ec.epubPath, "")
+	// Primary: anchor both endpoints by the selection text itself. One
+	// document match yields a same-spine ordered pair — the invariant the
+	// web reader's range-CFI builder needs. Independent per-endpoint
+	// conversion mis-anchors any selection past a block's first text node
+	// (crengine text-node indices don't survive to the raw XHTML).
+	startLoc := wsync.ConvertHighlightRangeToCanonical(ec.epubPath, ec.mediaItem.FormatGroup, pos0, pos1, contextText, percentage)
+	if startLoc.Precision == "exact" || startLoc.Precision == "structural" {
+		startCFI := webUsableCFI(startLoc)
+		endCFI := ""
+		if startCFI != "" && startLoc.EndCFI != "" {
+			endCFI = webUsableCFI(wsync.CanonicalLocator{CFI: startLoc.EndCFI, Precision: startLoc.Precision})
+		}
+		return startCFI, endCFI
+	}
+	// Fallback: legacy independent per-endpoint conversion.
+	startLoc = wsync.ConvertToCanonical(wsync.LocatorSourceKOReader, pos0, percentage, contextText, ec.mediaItem.FormatGroup, ec.epubPath, "")
 	startCFI := webUsableCFI(startLoc)
 	endCFI := ""
 	// A text-search start matched the selection text itself: its extent
@@ -219,24 +237,24 @@ type KOReaderProgressRequest struct {
 }
 
 type KOReaderBookProgress struct {
-	UUID        string                   `json:"uuid,omitempty"`
-	SHA256      string                   `json:"sha256,omitempty"`
-	Title       string                   `json:"title,omitempty"`
-	Authors     []string                 `json:"authors,omitempty"`
-	Progress    float64                  `json:"progress"`
-	Percentage  float64                  `json:"percentage"`
-	LastRead    string                   `json:"last_read,omitempty"`
-	FilePath    string                   `json:"file_path,omitempty"`
-	DeviceInfo  KOReaderDeviceInfo       `json:"device_info,omitempty"`
-	Bookmarks   []KOReaderBookmark       `json:"bookmarks,omitempty"`
-	Highlights  []KOReaderHighlight      `json:"highlights,omitempty"`
-	Notes       []KOReaderNote           `json:"notes,omitempty"`
-	Chapter     *int                     `json:"chapter,omitempty"`
-	Character   *int64                   `json:"character,omitempty"`
-	Epubcfi     *string                  `json:"epubcfi,omitempty"`
-	ContextText *string                  `json:"context_text,omitempty"`
-	Page        *int                     `json:"page,omitempty"`
-	TotalPages  *int                     `json:"total_pages,omitempty"`
+	UUID        string              `json:"uuid,omitempty"`
+	SHA256      string              `json:"sha256,omitempty"`
+	Title       string              `json:"title,omitempty"`
+	Authors     []string            `json:"authors,omitempty"`
+	Progress    float64             `json:"progress"`
+	Percentage  float64             `json:"percentage"`
+	LastRead    string              `json:"last_read,omitempty"`
+	FilePath    string              `json:"file_path,omitempty"`
+	DeviceInfo  KOReaderDeviceInfo  `json:"device_info,omitempty"`
+	Bookmarks   []KOReaderBookmark  `json:"bookmarks,omitempty"`
+	Highlights  []KOReaderHighlight `json:"highlights,omitempty"`
+	Notes       []KOReaderNote      `json:"notes,omitempty"`
+	Chapter     *int                `json:"chapter,omitempty"`
+	Character   *int64              `json:"character,omitempty"`
+	Epubcfi     *string             `json:"epubcfi,omitempty"`
+	ContextText *string             `json:"context_text,omitempty"`
+	Page        *int                `json:"page,omitempty"`
+	TotalPages  *int                `json:"total_pages,omitempty"`
 	// Device-side deletions, reported by dedup key. Keys refer to annotations
 	// the device previously received from the server (or echoes of its own
 	// pushes); the device only flags a deletion after observing the key in a
@@ -862,6 +880,11 @@ func (h *KOReaderHandler) updateProgressForBook(c *echo.Context, deviceID pgtype
 
 	if h.progressSvc != nil {
 		epubcfi := book.Epubcfi
+		// No position pointer from the device, or a conversion that
+		// declined below: the write is percentage-only by intent. The
+		// service then clears any inherited stale anchor instead of
+		// re-pairing it with the new percentage.
+		clearLocator := epubcfi == nil
 		if epubcfi != nil && wsync.IsCREXPointer(*epubcfi) {
 			// Same facade every annotation uses: cached converter,
 			// structural-first resolution, guarded fallbacks. The facade
@@ -897,6 +920,7 @@ func (h *KOReaderHandler) updateProgressForBook(c *echo.Context, deviceID pgtype
 					// and the device keeps its own native position.
 					log.Printf("Bookhoard: CRE→CFI conversion low-confidence (%s) for %s; storing percentage only", loc.Precision, *epubcfi)
 					epubcfi = nil
+					clearLocator = true
 				}
 			}
 		}
@@ -916,6 +940,7 @@ func (h *KOReaderHandler) updateProgressForBook(c *echo.Context, deviceID pgtype
 			DeviceType:      "koreader",
 			DeviceName:      deviceModel,
 			Broadcast:       true,
+			ClearLocator:    clearLocator,
 		}
 
 		_, err := h.progressSvc.SaveProgress(ctx, saveReq)
@@ -1707,3 +1732,260 @@ func (h *KOReaderHandler) SyncBookmarks(c *echo.Context) error {
 		"timestamp":         time.Now().Format(time.RFC3339),
 	})
 }
+
+// ---------------------------------------------------------------------------
+// Ratings / review / reading-time bridge (handoff item 4 Batch B)
+//
+// The plugin mirrors the book's .sdr summary (summary.rating 5-star,
+// summary.note = the Book Status "Review" box) against the server's
+// 1-10 rating and raw-markdown review, and pushes its cumulative
+// reading time from statistics.sqlite3. Stats are PUSH-ONLY and
+// watermark-converted: the device sends its TOTAL seconds for the
+// book and the server inserts only the delta as a reading_history
+// session attributed to this device, so totals unify in the one
+// stats pipeline while the By Device panel keeps the per-client
+// split. A device reinstall cannot double-count (the watermark is
+// server-side), and sub-threshold deltas simply ride forward.
+// ---------------------------------------------------------------------------
+
+// koreaderBookRef is the minimal book identity the bridge endpoints
+// accept; it resolves through the same priority chain as progress.
+type koreaderBookRef struct {
+	UUID    string   `json:"uuid,omitempty" query:"uuid"`
+	SHA256  string   `json:"sha256,omitempty" query:"sha256"`
+	Title   string   `json:"title,omitempty" query:"title"`
+	Authors []string `json:"authors,omitempty"`
+}
+
+func (r koreaderBookRef) toProgress() KOReaderBookProgress {
+	return KOReaderBookProgress{
+		UUID:    r.UUID,
+		SHA256:  r.SHA256,
+		Title:   r.Title,
+		Authors: r.Authors,
+	}
+}
+
+// resolveParsedRef resolves an already-bound book identity to a media
+// item. Endpoints bind ONCE — a resolve helper that re-bound the body
+// would drain it and break the payload bind that follows.
+func (h *KOReaderHandler) resolveParsedRef(c *echo.Context, device database.Devices, ref koreaderBookRef) (pgtype.UUID, error) {
+	mediaItemID, _ := h.resolveBookToMediaItem(c, device.ID, device.UserID, ref.toProgress())
+	if !mediaItemID.Valid {
+		return pgtype.UUID{}, fmt.Errorf("book not found on server")
+	}
+	return mediaItemID, nil
+}
+
+// GetKOReaderRating handles GET /api/sync/koreader/rating?uuid=&sha256=
+func (h *KOReaderHandler) GetKOReaderRating(c *echo.Context) error {
+	device := c.Get("device").(database.Devices)
+	var ref koreaderBookRef
+	if err := c.Bind(&ref); err != nil {
+		return c.JSON(http.StatusBadRequest, map[string]string{"error": "invalid request"})
+	}
+	mediaItemID, err := h.resolveParsedRef(c, device, ref)
+	if err != nil {
+		return c.JSON(http.StatusNotFound, map[string]string{"error": err.Error()})
+	}
+	rating, err := h.db.GetMediaRating(c.Request().Context(), database.GetMediaRatingParams{
+		MediaItemID: mediaItemID,
+		UserID:      device.UserID,
+	})
+	if err != nil {
+		if errors.Is(err, pgx.ErrNoRows) {
+			return c.JSON(http.StatusOK, map[string]interface{}{"rating": nil})
+		}
+		return c.JSON(http.StatusInternalServerError, map[string]string{"error": err.Error()})
+	}
+	return c.JSON(http.StatusOK, map[string]interface{}{"rating": rating.Rating})
+}
+
+// SetKOReaderRating handles POST /api/sync/koreader/rating. Rating 0
+// (koreader's "unrated") clears the server rating.
+func (h *KOReaderHandler) SetKOReaderRating(c *echo.Context) error {
+	device := c.Get("device").(database.Devices)
+
+	var req struct {
+		koreaderBookRef
+		Rating int `json:"rating" validate:"min=0,max=10"`
+	}
+	if err := c.Bind(&req); err != nil {
+		return c.JSON(http.StatusBadRequest, map[string]string{"error": "invalid request"})
+	}
+	if err := c.Validate(&req); err != nil {
+		return c.JSON(http.StatusBadRequest, map[string]string{"error": err.Error()})
+	}
+
+	mediaItemID, err := h.resolveParsedRef(c, device, req.koreaderBookRef)
+	if err != nil {
+		return c.JSON(http.StatusNotFound, map[string]string{"error": err.Error()})
+	}
+
+	if req.Rating <= 0 {
+		if err := h.db.DeleteMediaRating(c.Request().Context(), database.DeleteMediaRatingParams{
+			MediaItemID: mediaItemID,
+			UserID:      device.UserID,
+		}); err != nil {
+			return c.JSON(http.StatusInternalServerError, map[string]string{"error": err.Error()})
+		}
+		return c.JSON(http.StatusOK, map[string]interface{}{"rating": nil})
+	}
+
+	rating, err := h.db.CreateMediaRating(c.Request().Context(), database.CreateMediaRatingParams{
+		MediaItemID: mediaItemID,
+		UserID:      device.UserID,
+		Rating:      int32(req.Rating),
+	})
+	if err != nil {
+		return c.JSON(http.StatusInternalServerError, map[string]string{"error": err.Error()})
+	}
+	return c.JSON(http.StatusOK, map[string]interface{}{"rating": rating.Rating})
+}
+
+// GetKOReaderReview handles GET /api/sync/koreader/review. Returns the
+// RAW MARKDOWN source (koreader's review box shows it literally, the
+// same accepted tradeoff as notes).
+func (h *KOReaderHandler) GetKOReaderReview(c *echo.Context) error {
+	device := c.Get("device").(database.Devices)
+	var ref koreaderBookRef
+	if err := c.Bind(&ref); err != nil {
+		return c.JSON(http.StatusBadRequest, map[string]string{"error": "invalid request"})
+	}
+	mediaItemID, err := h.resolveParsedRef(c, device, ref)
+	if err != nil {
+		return c.JSON(http.StatusNotFound, map[string]string{"error": err.Error()})
+	}
+	review, err := h.db.GetMediaReview(c.Request().Context(), database.GetMediaReviewParams{
+		MediaItemID: mediaItemID,
+		UserID:      device.UserID,
+	})
+	if err != nil {
+		if errors.Is(err, pgx.ErrNoRows) {
+			return c.JSON(http.StatusOK, map[string]interface{}{"review": nil})
+		}
+		return c.JSON(http.StatusInternalServerError, map[string]string{"error": err.Error()})
+	}
+	return c.JSON(http.StatusOK, map[string]interface{}{"review": review.Review})
+}
+
+// SetKOReaderReview handles POST /api/sync/koreader/review. An empty
+// body clears the review (mirrors the first-party PUT contract).
+func (h *KOReaderHandler) SetKOReaderReview(c *echo.Context) error {
+	device := c.Get("device").(database.Devices)
+
+	var req struct {
+		koreaderBookRef
+		Review string `json:"review" validate:"max=50000"`
+	}
+	if err := c.Bind(&req); err != nil {
+		return c.JSON(http.StatusBadRequest, map[string]string{"error": "invalid request"})
+	}
+	if err := c.Validate(&req); err != nil {
+		return c.JSON(http.StatusBadRequest, map[string]string{"error": err.Error()})
+	}
+
+	mediaItemID, err := h.resolveParsedRef(c, device, req.koreaderBookRef)
+	if err != nil {
+		return c.JSON(http.StatusNotFound, map[string]string{"error": err.Error()})
+	}
+
+	if strings.TrimSpace(req.Review) == "" {
+		if err := h.db.DeleteMediaReview(c.Request().Context(), database.DeleteMediaReviewParams{
+			MediaItemID: mediaItemID,
+			UserID:      device.UserID,
+		}); err != nil {
+			return c.JSON(http.StatusInternalServerError, map[string]string{"error": err.Error()})
+		}
+		return c.JSON(http.StatusOK, map[string]interface{}{"review": nil})
+	}
+
+	review, err := h.db.UpsertMediaReview(c.Request().Context(), database.UpsertMediaReviewParams{
+		MediaItemID: mediaItemID,
+		UserID:      device.UserID,
+		Review:      req.Review,
+	})
+	if err != nil {
+		return c.JSON(http.StatusInternalServerError, map[string]string{"error": err.Error()})
+	}
+	return c.JSON(http.StatusOK, map[string]interface{}{"review": review.Review})
+}
+
+// PushKOReaderStats handles POST /api/sync/koreader/stats. The device
+// sends its cumulative total reading seconds for the book; only the
+// delta above the stored watermark becomes a reading_history session
+// (attributed to the koreader device, metadata carrying the new
+// cumulative marker). Sub-minute deltas ride forward: no session, no
+// watermark movement, nothing lost.
+func (h *KOReaderHandler) PushKOReaderStats(c *echo.Context) error {
+	device := c.Get("device").(database.Devices)
+
+	var req struct {
+		koreaderBookRef
+		TotalSeconds int64 `json:"total_seconds" validate:"min=0,max=2000000000"`
+	}
+	if err := c.Bind(&req); err != nil {
+		return c.JSON(http.StatusBadRequest, map[string]string{"error": "invalid request"})
+	}
+	if err := c.Validate(&req); err != nil {
+		return c.JSON(http.StatusBadRequest, map[string]string{"error": err.Error()})
+	}
+
+	mediaItemID, err := h.resolveParsedRef(c, device, req.koreaderBookRef)
+	if err != nil {
+		return c.JSON(http.StatusNotFound, map[string]string{"error": err.Error()})
+	}
+
+	// sqlc scans COALESCE(MAX(...)) as interface{}; pgx hands bigint
+	// back as int64.
+	watermarkAny, err := h.db.GetKoreaderStatWatermark(c.Request().Context(), database.GetKoreaderStatWatermarkParams{
+		UserID:      device.UserID,
+		MediaItemID: mediaItemID,
+	})
+	if err != nil {
+		return c.JSON(http.StatusInternalServerError, map[string]string{"error": err.Error()})
+	}
+	watermark, _ := watermarkAny.(int64)
+
+	// Delta against the stored watermark (the highest total ever
+	// converted for this user+book across ALL koreader devices). When
+	// another device is ahead, the delta clamps to zero so a lagging
+	// device can never drag the total backwards.
+	delta := req.TotalSeconds - watermark
+	if delta < 0 {
+		delta = 0
+	}
+
+	result := map[string]interface{}{
+		"total_seconds":    req.TotalSeconds,
+		"watermark":        watermark,
+		"delta_seconds":    delta,
+		"session_recorded": false,
+	}
+
+	if delta >= 60 {
+		now := time.Now()
+		start := now.Add(-time.Duration(delta) * time.Second)
+		metadata, _ := json.Marshal(map[string]interface{}{
+			"source":        "koreader",
+			"total_seconds": req.TotalSeconds,
+		})
+		if _, err := h.db.CreateReadingHistory(c.Request().Context(), database.CreateReadingHistoryParams{
+			UserID:              device.UserID,
+			MediaItemID:         mediaItemID,
+			DeviceID:            device.ID,
+			ProgressPercentage:  pgtype.Float8{Float64: 0, Valid: false},
+			ReadingSessionStart: pgtype.Timestamptz{Time: start, Valid: true},
+			ReadingSessionEnd:   pgtype.Timestamptz{Time: now, Valid: true},
+			PagesRead:           pgtype.Int4{Int32: 0, Valid: false},
+			TimeSpentSeconds:    pgtype.Int4{Int32: int32(delta), Valid: true},
+			DeviceMetadata:      metadata,
+		}); err != nil {
+			return c.JSON(http.StatusInternalServerError, map[string]string{"error": err.Error()})
+		}
+		result["session_recorded"] = true
+		result["session_seconds"] = delta
+	}
+
+	return c.JSON(http.StatusOK, result)
+}

internal/handlers/media.go

@@ -102,13 +102,13 @@ type UpdateMediaItemRequest struct {
 
 // CreateMediaNoteRequest represents the request for creating a media note
 type CreateMediaNoteRequest struct {
-	Content  string `json:"content" validate:"required,min=1,max=10000"`
+	Content  string `json:"content" validate:"required,min=1,max=100000"`
 	Position string `json:"position"`
 }
 
 // UpdateMediaNoteRequest represents the request for updating a media note
 type UpdateMediaNoteRequest struct {
-	Content  string `json:"content" validate:"required,min=1,max=10000"`
+	Content  string `json:"content" validate:"required,min=1,max=100000"`
 	Position string `json:"position"`
 }
 
@@ -120,7 +120,7 @@ type CreateMediaHighlightRequest struct {
 	EpubcfiStart     string  `json:"epubcfi_start" validate:"max=2000"`
 	EpubcfiEnd       string  `json:"epubcfi_end" validate:"max=2000"`
 	Color            string  `json:"color" validate:"omitempty,len=7"`
-	NoteText         string  `json:"note_text" validate:"max=10000"`
+	NoteText         string  `json:"note_text" validate:"max=100000"`
 	NoteID           string  `json:"note_id"`
 	PercentageStart  float64 `json:"percentage_start"`
 	PercentageEnd    float64 `json:"percentage_end"`
@@ -135,7 +135,7 @@ type UpdateMediaHighlightRequest struct {
 	EpubcfiStart     string  `json:"epubcfi_start" validate:"max=2000"`
 	EpubcfiEnd       string  `json:"epubcfi_end" validate:"max=2000"`
 	Color            string  `json:"color" validate:"omitempty,len=7"`
-	NoteText         string  `json:"note_text" validate:"max=10000"`
+	NoteText         string  `json:"note_text" validate:"max=100000"`
 	NoteID           string  `json:"note_id"`
 	PercentageStart  float64 `json:"percentage_start"`
 	PercentageEnd    float64 `json:"percentage_end"`
@@ -146,7 +146,7 @@ type UpdateMediaHighlightRequest struct {
 type CreateMediaBookmarkRequest struct {
 	Title            string  `json:"title" validate:"required,min=1,max=255"`
 	Position         string  `json:"position" validate:"max=100"`
-	Notes            string  `json:"notes" validate:"max=10000"`
+	Notes            string  `json:"notes" validate:"max=100000"`
 	CfiPosition      string  `json:"cfi_position" validate:"max=255"`
 	PageNumber       int32   `json:"page_number"`
 	ChapterNumber    int32   `json:"chapter_number"`
@@ -160,7 +160,7 @@ type CreateMediaBookmarkRequest struct {
 // UpdateMediaBookmarkRequest represents the request for updating a media bookmark
 type UpdateMediaBookmarkRequest struct {
 	Title    string `json:"title" validate:"required,min=1,max=255"`
-	Notes    string `json:"notes" validate:"max=10000"`
+	Notes    string `json:"notes" validate:"max=100000"`
 	Position string `json:"position" validate:"max=100"`
 }
 
@@ -439,6 +439,20 @@ func (h *MediaHandler) HandleBulkDelete(c *echo.Context) error {
 			continue
 		}
 
+		// Storage-down guard: deleting cascades the item's annotations, so
+		// refuse while the library storage is unreachable — the file would
+		// survive as an orphan and re-import bare on the next scan.
+		storage := h.resolveMediaStorage(c.Request().Context(), uuid.UUID(media.LibraryID.Bytes).String(), media.FilePath)
+		if !storage.Reachable {
+			results = append(results, map[string]interface{}{
+				"media_item_id": mediaIDStr,
+				"status":        "error",
+				"error":         "storage unreachable — archive the item instead, or retry when the storage is mounted",
+			})
+			failedCount++
+			continue
+		}
+
 		err = h.db.DeleteMediaItem(c.Request().Context(), mediaUUID)
 		if err != nil {
 			results = append(results, map[string]interface{}{
@@ -450,11 +464,11 @@ func (h *MediaHandler) HandleBulkDelete(c *echo.Context) error {
 			continue
 		}
 
-		if media.FilePath != "" {
-			if err := os.Remove(media.FilePath); err != nil {
+		if storage.AbsolutePath != "" {
+			if err := os.Remove(storage.AbsolutePath); err != nil {
 				// Log file removal failure but don't fail the request
 				// DB record is already deleted, which is the primary concern
-				log.Printf("Warning: failed to remove file %s: %v", media.FilePath, err)
+				log.Printf("Warning: failed to remove file %s: %v", storage.AbsolutePath, err)
 			}
 		}
 
@@ -626,6 +640,77 @@ func (h *MediaHandler) HandleBulkUpdate(c *echo.Context) error {
 	})
 }
 
+// visibleLibrarySet loads the requester's visible libraries — membership
+// map for param checks, id slice for SQL ANY() filters.
+func (mh *MediaHandler) visibleLibrarySet(c *echo.Context) (map[string]bool, []pgtype.UUID, error) {
+	user, ok := c.Get("user").(database.Users)
+	if !ok {
+		return nil, nil, echo.NewHTTPError(http.StatusUnauthorized, "invalid user")
+	}
+	libraries, err := mh.libraryService.GetUserVisibleLibraries(c.Request().Context(), user.ID)
+	if err != nil {
+		return nil, nil, echo.NewHTTPError(http.StatusInternalServerError, "failed to check library access")
+	}
+	set := make(map[string]bool, len(libraries))
+	ids := make([]pgtype.UUID, 0, len(libraries))
+	for _, lib := range libraries {
+		if !lib.ID.Valid {
+			continue
+		}
+		set[uuid.UUID(lib.ID.Bytes).String()] = true
+		ids = append(ids, lib.ID)
+	}
+	return set, ids, nil
+}
+
+// mediaStorageState reports whether the library storage holding a media
+// item's file is currently reachable, and resolves the file's absolute
+// path when it can be located.
+//
+// Why this exists: deleting a media item cascades its annotations, so the
+// delete must never proceed while the storage is unreachable — otherwise
+// a NAS outage turns an admin cleanup into permanent annotation loss
+// (the DB row dies, the orphaned file re-imports bare on the next scan).
+type mediaStorageState struct {
+	// Absolute path of the file when located on reachable storage;
+	// empty when the file is missing or reachability is undeterminable.
+	AbsolutePath string
+	// Reachable is false ONLY when the library has folders and every one
+	// of them fails to stat — positive evidence the mount is down. When
+	// no folders are configured reachability is undeterminable and this
+	// is true (delete proceeds; behavior unchanged from before this check).
+	Reachable bool
+}
+
+func (mh *MediaHandler) resolveMediaStorage(ctx context.Context, libraryID string, relativePath string) mediaStorageState {
+	libUUID, err := uuid.Parse(libraryID)
+	if err != nil {
+		return mediaStorageState{Reachable: true}
+	}
+	folders, err := mh.libraryService.GetLibraryFolders(ctx, pgtype.UUID{Bytes: libUUID, Valid: true})
+	if err != nil || len(folders) == 0 {
+		return mediaStorageState{Reachable: true}
+	}
+
+	anyFolderUp := false
+	for _, f := range folders {
+		if _, err := os.Stat(f.FolderPath); err != nil {
+			continue // folder root unreachable
+		}
+		anyFolderUp = true
+		candidate := filepath.Join(f.FolderPath, filepath.FromSlash(relativePath))
+		if _, err := os.Stat(candidate); err == nil {
+			return mediaStorageState{AbsolutePath: candidate, Reachable: true}
+		}
+	}
+	if !anyFolderUp {
+		return mediaStorageState{Reachable: false}
+	}
+	// Storage is up but the file is genuinely gone: a stale row is safe
+	// to delete.
+	return mediaStorageState{Reachable: true}
+}
+
 // ListMediaItems handles GET /api/media-items
 func (mh *MediaHandler) ListMediaItems(c *echo.Context) error {
 	libraryID := c.QueryParam("library_id")
@@ -678,6 +763,14 @@ func (mh *MediaHandler) ListMediaItems(c *echo.Context) error {
 			return c.JSON(http.StatusBadRequest, map[string]string{"error": "invalid library id"})
 		}
 
+		visibleSet, _, err := mh.visibleLibrarySet(c)
+		if err != nil {
+			return err
+		}
+		if !visibleSet[libraryID] {
+			return c.JSON(http.StatusForbidden, map[string]string{"error": "library not accessible"})
+		}
+
 		items, err := mh.db.ListMediaItemsSorted(c.Request().Context(), database.ListMediaItemsSortedParams{
 			LibraryID: pgtype.UUID{Bytes: libUUID, Valid: true},
 			Sort:      pgtype.Text{String: sort, Valid: true},
@@ -691,9 +784,14 @@ func (mh *MediaHandler) ListMediaItems(c *echo.Context) error {
 		return c.JSON(http.StatusOK, map[string]interface{}{"data": items})
 	}
 
+	_, visibleIDs, err := mh.visibleLibrarySet(c)
+	if err != nil {
+		return err
+	}
 	items, err := mh.db.ListMediaItems(c.Request().Context(), database.ListMediaItemsParams{
-		Limit:  int32(limit),
-		Offset: int32(offset),
+		Limit:             int32(limit),
+		Offset:            int32(offset),
+		VisibleLibraryIds: visibleIDs,
 	})
 	if err != nil {
 		return c.JSON(http.StatusInternalServerError, map[string]string{"error": err.Error()})
@@ -764,6 +862,15 @@ func (mh *MediaHandler) GetMediaItem(c *echo.Context) error {
 		return c.JSON(http.StatusInternalServerError, map[string]string{"error": err.Error()})
 	}
 
+	// Visibility gate: hidden libraries don't leak row detail by id.
+	visibleSet, _, err := mh.visibleLibrarySet(c)
+	if err != nil {
+		return err
+	}
+	if !visibleSet[uuid.UUID(item.LibraryID.Bytes).String()] {
+		return c.JSON(http.StatusForbidden, map[string]string{"error": "library not accessible"})
+	}
+
 	return c.JSON(http.StatusOK, map[string]interface{}{
 		"id":               uuid.UUID(item.ID.Bytes).String(),
 		"library_id":       uuid.UUID(item.LibraryID.Bytes).String(),
@@ -905,6 +1012,111 @@ func (mh *MediaHandler) DeleteMediaRating(c *echo.Context) error {
 	return c.JSON(http.StatusOK, map[string]string{"message": "rating deleted"})
 }
 
+// UpsertMediaReview handles POST and PUT /api/media-items/:id/review.
+// The review body is RAW MARKDOWN (same doctrine as notes): storage and
+// every sync payload carry the source string; rendering happens only at
+// display sites. An empty body deletes the review — clearing via the
+// editor is a delete, not an empty row.
+func (mh *MediaHandler) UpsertMediaReview(c *echo.Context) error {
+	userID := c.Get("user_id").(string)
+	userUUID, err := uuid.Parse(userID)
+	if err != nil {
+		return c.JSON(http.StatusBadRequest, map[string]string{"error": "invalid user"})
+	}
+
+	mediaID := c.Param("id")
+	mediaUUID, err := uuid.Parse(mediaID)
+	if err != nil {
+		return c.JSON(http.StatusBadRequest, map[string]string{"error": "invalid media item id"})
+	}
+
+	var req struct {
+		Review string `json:"review" validate:"max=50000"`
+	}
+	if err := c.Bind(&req); err != nil {
+		return c.JSON(http.StatusBadRequest, map[string]string{"error": "invalid request"})
+	}
+	if err := c.Validate(&req); err != nil {
+		return c.JSON(http.StatusBadRequest, map[string]string{"error": err.Error()})
+	}
+
+	trimmed := strings.TrimSpace(req.Review)
+	if trimmed == "" {
+		err := mh.db.DeleteMediaReview(c.Request().Context(), database.DeleteMediaReviewParams{
+			MediaItemID: pgtype.UUID{Bytes: mediaUUID, Valid: true},
+			UserID:      pgtype.UUID{Bytes: userUUID, Valid: true},
+		})
+		if err != nil {
+			return c.JSON(http.StatusInternalServerError, map[string]string{"error": err.Error()})
+		}
+		return c.JSON(http.StatusOK, map[string]interface{}{"review": nil})
+	}
+
+	review, err := mh.db.UpsertMediaReview(c.Request().Context(), database.UpsertMediaReviewParams{
+		MediaItemID: pgtype.UUID{Bytes: mediaUUID, Valid: true},
+		UserID:      pgtype.UUID{Bytes: userUUID, Valid: true},
+		Review:      req.Review,
+	})
+	if err != nil {
+		return c.JSON(http.StatusInternalServerError, map[string]string{"error": err.Error()})
+	}
+
+	return c.JSON(http.StatusOK, review)
+}
+
+// GetMediaReview handles GET /api/media-items/:id/review
+func (mh *MediaHandler) GetMediaReview(c *echo.Context) error {
+	userID := c.Get("user_id").(string)
+	userUUID, err := uuid.Parse(userID)
+	if err != nil {
+		return c.JSON(http.StatusBadRequest, map[string]string{"error": "invalid user"})
+	}
+
+	mediaID := c.Param("id")
+	mediaUUID, err := uuid.Parse(mediaID)
+	if err != nil {
+		return c.JSON(http.StatusBadRequest, map[string]string{"error": "invalid media item id"})
+	}
+
+	review, err := mh.db.GetMediaReview(c.Request().Context(), database.GetMediaReviewParams{
+		MediaItemID: pgtype.UUID{Bytes: mediaUUID, Valid: true},
+		UserID:      pgtype.UUID{Bytes: userUUID, Valid: true},
+	})
+	if err != nil {
+		if errors.Is(err, pgx.ErrNoRows) {
+			return c.JSON(http.StatusOK, map[string]interface{}{"review": nil})
+		}
+		return c.JSON(http.StatusInternalServerError, map[string]string{"error": err.Error()})
+	}
+
+	return c.JSON(http.StatusOK, review)
+}
+
+// DeleteMediaReview handles DELETE /api/media-items/:id/review
+func (mh *MediaHandler) DeleteMediaReview(c *echo.Context) error {
+	userID := c.Get("user_id").(string)
+	userUUID, err := uuid.Parse(userID)
+	if err != nil {
+		return c.JSON(http.StatusBadRequest, map[string]string{"error": "invalid user"})
+	}
+
+	mediaID := c.Param("id")
+	mediaUUID, err := uuid.Parse(mediaID)
+	if err != nil {
+		return c.JSON(http.StatusBadRequest, map[string]string{"error": "invalid media item id"})
+	}
+
+	err = mh.db.DeleteMediaReview(c.Request().Context(), database.DeleteMediaReviewParams{
+		MediaItemID: pgtype.UUID{Bytes: mediaUUID, Valid: true},
+		UserID:      pgtype.UUID{Bytes: userUUID, Valid: true},
+	})
+	if err != nil {
+		return c.JSON(http.StatusInternalServerError, map[string]string{"error": err.Error()})
+	}
+
+	return c.JSON(http.StatusOK, map[string]string{"message": "review deleted"})
+}
+
 // GetMediaReadingProgress handles GET /api/media-items/:id/progress
 func (mh *MediaHandler) GetMediaReadingProgress(c *echo.Context) error {
 	userID := c.Get("user_id").(string)
@@ -953,6 +1165,37 @@ func (mh *MediaHandler) GetMediaReadingProgress(c *echo.Context) error {
 		"last_sync_timestamp": progress.LastSyncTimestamp,
 	}
 
+	// Position authority: re-verify the stored anchor and derive the
+	// client-facing handles (cssSelector + anchor document href) server-
+	// side, so clients scroll to an address instead of parsing CFIs.
+	if progress.Epubcfi.Valid && wsync.IsConvertibleFormat(progress.FormatGroup) && mh.libraryService != nil {
+		contextText := ""
+		if progress.ContextText.Valid {
+			contextText = progress.ContextText.String
+		}
+		pct := 0.0
+		if progress.Percentage.Valid {
+			pct = progress.Percentage.Float64
+		}
+		if mediaItem, err := mh.db.GetMediaItem(c.Request().Context(), pgtype.UUID{Bytes: mediaUUID, Valid: true}); err == nil {
+			if path, perr := mh.libraryService.ResolveMediaPath(c.Request().Context(), mediaItem.LibraryID, mediaItem.FilePath); perr == nil && path != "" {
+				if finalCFI, sel, href, charOff, _, _, _, verr := wsync.VerifyProgressAnchor(path, progress.Epubcfi.String, contextText, pct); verr == nil && sel != "" {
+					resp["css_selector"] = sel
+					resp["anchor_href"] = href
+					if charOff != nil {
+						resp["char_offset"] = *charOff
+					}
+					if finalCFI != "" {
+						resp["epubcfi"] = finalCFI
+					}
+				}
+			}
+		}
+	}
+	if progress.ContextText.Valid {
+		resp["context_text"] = progress.ContextText.String
+	}
+
 	return c.JSON(http.StatusOK, resp)
 }
 
@@ -970,6 +1213,31 @@ func (mh *MediaHandler) UpdateMediaReadingProgress(c *echo.Context) error {
 		return c.JSON(http.StatusBadRequest, map[string]string{"error": "invalid media item id"})
 	}
 
+	// Reading-stats attribution: registered clients may send their device
+	// token in X-Device-Token (the user JWT stays the primary auth). A
+	// token that maps to a device owned by THIS user attaches the push —
+	// and everything the reading history records about it — to that
+	// device's registered name/type ("Pixel 9" · mobile, "Kindle… " ·
+	// koreader). Absent/invalid/foreign tokens soft-fail to the plain
+	// web attribution; a stats decoration must never fail a sync.
+	deviceID := pgtype.UUID{}
+	deviceSource := "web"
+	deviceLabel := ""
+	deviceType := ""
+	if token := c.Request().Header.Get("X-Device-Token"); token != "" {
+		device, devErr := mh.db.GetDeviceByAuthToken(c.Request().Context(), token)
+		if devErr == nil && device.UserID.Valid && uuid.UUID(device.UserID.Bytes) == userUUID {
+			deviceID = device.ID
+			deviceLabel = device.DeviceName
+			deviceType = device.DeviceType
+			deviceSource = device.DeviceName
+			if strings.TrimSpace(deviceSource) == "" {
+				deviceSource = device.DeviceType
+			}
+		}
+	}
+
+
 	var req struct {
 		CurrentPage     *int32   `json:"current_page"`
 		TotalPages      *int32   `json:"total_pages"`
@@ -992,8 +1260,10 @@ func (mh *MediaHandler) UpdateMediaReadingProgress(c *echo.Context) error {
 		saveReq := wsync.SaveProgressRequest{
 			MediaItemID:     pgtype.UUID{Bytes: mediaUUID, Valid: true},
 			UserID:          pgtype.UUID{Bytes: userUUID, Valid: true},
-			Source:          "web",
-			DeviceID:        pgtype.UUID{Bytes: userUUID, Valid: true},
+			Source:          deviceSource,
+			DeviceID:        deviceID,
+			DeviceType:      deviceType,
+			DeviceName:      deviceLabel,
 			Percentage:      req.Percentage,
 			Epubcfi:         req.Epubcfi,
 			ContextText:     req.ContextText,
@@ -1006,8 +1276,6 @@ func (mh *MediaHandler) UpdateMediaReadingProgress(c *echo.Context) error {
 			ScrollX:         req.ScrollX,
 			ScrollY:         req.ScrollY,
 			ReadingMode:     req.ReadingMode,
-			DeviceType:      "web",
-			DeviceName:      "Web",
 			Broadcast:       true,
 		}
 		if req.CurrentPage != nil {
@@ -1163,7 +1431,10 @@ func (mh *MediaHandler) CreateMediaItem(c *echo.Context) error {
 		})
 	}
 
-	mediaItemID, err := mh.db.CreateMediaItem(c.Request().Context(), database.CreateMediaItemParams{
+	// Race-safe create-or-detect: on a duplicate (library_id, file_path)
+	// the insert writes nothing and returns no row — answer with the
+	// EXISTING item, a duplicate flag, and 200 OK (not a 201 lie).
+	created, err := mh.db.CreateMediaItemIfNew(c.Request().Context(), database.CreateMediaItemIfNewParams{
 		LibraryID:          pgtype.UUID{Bytes: req.LibraryID, Valid: true},
 		Title:              req.Title,
 		Author:             pgtype.Text{String: req.Author, Valid: req.Author != ""},
@@ -1184,11 +1455,25 @@ func (mh *MediaHandler) CreateMediaItem(c *echo.Context) error {
 		ContributorsSearch: contributorsSearch,
 		AddedByAdminID:     user.ID,
 	})
+	if errors.Is(err, pgx.ErrNoRows) {
+		existing, gerr := mh.db.GetMediaItemByLibraryAndPath(c.Request().Context(), database.GetMediaItemByLibraryAndPathParams{
+			LibraryID: pgtype.UUID{Bytes: req.LibraryID, Valid: true},
+			FilePath:  req.FilePath,
+		})
+		if gerr != nil {
+			return c.JSON(http.StatusInternalServerError, map[string]string{"error": gerr.Error()})
+		}
+		return c.JSON(http.StatusOK, map[string]interface{}{
+			"duplicate": true,
+			"message":   "A media item already exists for this file_path in this library",
+			"item":      existing,
+		})
+	}
 	if err != nil {
 		return c.JSON(http.StatusInternalServerError, map[string]string{"error": err.Error()})
 	}
 
-	item, err := mh.db.GetMediaItem(c.Request().Context(), pgtype.UUID{Bytes: mediaItemID.ID.Bytes, Valid: true})
+	item, err := mh.db.GetMediaItem(c.Request().Context(), pgtype.UUID{Bytes: created.ID.Bytes, Valid: true})
 	if err != nil {
 		return c.JSON(http.StatusInternalServerError, map[string]string{"error": err.Error()})
 	}
@@ -1354,6 +1639,83 @@ func (mh *MediaHandler) UnarchiveMediaItem(c *echo.Context) error {
 	return c.NoContent(http.StatusNoContent)
 }
 
+// MergeArchivedMediaItem handles POST /api/media-items/:id/merge (admin
+// only). Merges an archived/missing item's reading data (progress,
+// annotations, highlights, notes, bookmarks, ratings, collections, kobo
+// shelves) into an active item with identical content (same SHA-256), then
+// deletes the archived row. Covers the copy-then-delete-later workflow: the
+// active copy exists, the archived twin holds the real reading history.
+// Per-user collisions keep the active copy's data, mirroring hash-conflict
+// resolution.
+func (mh *MediaHandler) MergeArchivedMediaItem(c *echo.Context) error {
+	user := MustGetAuthenticatedUser(c)
+
+	if user.Role != "admin" {
+		return c.JSON(http.StatusForbidden, map[string]string{"error": "admin access required"})
+	}
+
+	sourceUUID, err := uuid.Parse(c.Param("id"))
+	if err != nil {
+		return c.JSON(http.StatusBadRequest, map[string]string{"error": "invalid media item id"})
+	}
+
+	var req struct {
+		TargetID string `json:"target_id"`
+	}
+	if err := c.Bind(&req); err != nil || req.TargetID == "" {
+		return c.JSON(http.StatusBadRequest, map[string]string{"error": "target_id is required"})
+	}
+	targetUUID, err := uuid.Parse(req.TargetID)
+	if err != nil {
+		return c.JSON(http.StatusBadRequest, map[string]string{"error": "invalid target_id"})
+	}
+	if sourceUUID == targetUUID {
+		return c.JSON(http.StatusBadRequest, map[string]string{"error": "cannot merge an item into itself"})
+	}
+
+	ctx := c.Request().Context()
+	source, err := mh.db.GetMediaItem(ctx, pgtype.UUID{Bytes: sourceUUID, Valid: true})
+	if err != nil {
+		if errors.Is(err, pgx.ErrNoRows) {
+			return c.JSON(http.StatusNotFound, map[string]string{"error": "archived item not found"})
+		}
+		return c.JSON(http.StatusInternalServerError, map[string]string{"error": err.Error()})
+	}
+	if !source.ArchivedAt.Valid && source.MissingScanCount == 0 {
+		return c.JSON(http.StatusBadRequest, map[string]string{"error": "source item is not archived or missing"})
+	}
+
+	target, err := mh.db.GetMediaItem(ctx, pgtype.UUID{Bytes: targetUUID, Valid: true})
+	if err != nil {
+		if errors.Is(err, pgx.ErrNoRows) {
+			return c.JSON(http.StatusNotFound, map[string]string{"error": "target item not found"})
+		}
+		return c.JSON(http.StatusInternalServerError, map[string]string{"error": err.Error()})
+	}
+	if target.ArchivedAt.Valid || target.MissingScanCount > 0 {
+		return c.JSON(http.StatusBadRequest, map[string]string{"error": "target item is not active"})
+	}
+
+	if !source.FileSha256.Valid || source.FileSha256.String == "" ||
+		source.FileSha256.String != target.FileSha256.String {
+		return c.JSON(http.StatusBadRequest, map[string]string{"error": "items do not share the same content hash"})
+	}
+
+	if err := mh.db.ReparentMediaItemChildren(ctx, database.ReparentMediaItemChildrenParams{
+		Column1: pgtype.UUID{Bytes: targetUUID, Valid: true},
+		Column2: pgtype.UUID{Bytes: sourceUUID, Valid: true},
+	}); err != nil {
+		return c.JSON(http.StatusInternalServerError, map[string]string{"error": "failed to merge reading data: " + err.Error()})
+	}
+	if err := mh.db.DeleteMediaItem(ctx, pgtype.UUID{Bytes: sourceUUID, Valid: true}); err != nil {
+		return c.JSON(http.StatusInternalServerError, map[string]string{"error": "failed to remove archived item: " + err.Error()})
+	}
+
+	return c.JSON(http.StatusOK, map[string]string{
+		"message": "Merged reading progress, annotations, and collections into the active item",
+	})
+}
+
 // PurgeArchivedMediaItems handles POST /api/media-items/purge-archived
 // (admin only). Hard-deletes every archived item (files missing from disk for
 // 2+ scans) together with its reading history. The archive retention window
@@ -1429,11 +1791,35 @@ func (mh *MediaHandler) DeleteMediaItem(c *echo.Context) error {
 		return c.JSON(http.StatusBadRequest, map[string]string{"error": "invalid media item id"})
 	}
 
+	media, err := mh.db.GetMediaItem(c.Request().Context(), pgtype.UUID{Bytes: mediaUUID, Valid: true})
+	if err != nil {
+		if errors.Is(err, pgx.ErrNoRows) {
+			return c.JSON(http.StatusNotFound, map[string]string{"error": "media item not found"})
+		}
+		return c.JSON(http.StatusInternalServerError, map[string]string{"error": err.Error()})
+	}
+
+	// Storage-down guard (see HandleBulkDelete): refuse while the library
+	// storage is unreachable so the cascade can't destroy annotations for
+	// a file that will re-import on the next scan.
+	storage := mh.resolveMediaStorage(c.Request().Context(), uuid.UUID(media.LibraryID.Bytes).String(), media.FilePath)
+	if !storage.Reachable {
+		return c.JSON(http.StatusConflict, map[string]string{
+			"error": "storage unreachable — archive the item instead, or retry when the storage is mounted",
+		})
+	}
+
 	err = mh.db.DeleteMediaItem(c.Request().Context(), pgtype.UUID{Bytes: mediaUUID, Valid: true})
 	if err != nil {
 		return c.JSON(http.StatusInternalServerError, map[string]string{"error": err.Error()})
 	}
 
+	if storage.AbsolutePath != "" {
+		if err := os.Remove(storage.AbsolutePath); err != nil {
+			log.Printf("Warning: failed to remove file %s: %v", storage.AbsolutePath, err)
+		}
+	}
+
 	return c.NoContent(http.StatusNoContent)
 }
 
@@ -1541,6 +1927,12 @@ func (mh *MediaHandler) UpdateMediaNote(c *echo.Context) error {
 		return c.JSON(http.StatusBadRequest, map[string]string{"error": "invalid note id"})
 	}
 
+	userID := c.Get("user_id").(string)
+	userUUID, err := uuid.Parse(userID)
+	if err != nil {
+		return c.JSON(http.StatusBadRequest, map[string]string{"error": "invalid user"})
+	}
+
 	var req UpdateMediaNoteRequest
 	if err := c.Bind(&req); err != nil {
 		return c.JSON(http.StatusBadRequest, map[string]string{"error": "invalid request"})
@@ -1553,6 +1945,7 @@ func (mh *MediaHandler) UpdateMediaNote(c *echo.Context) error {
 		ID:       pgtype.UUID{Bytes: noteUUID, Valid: true},
 		Content:  req.Content,
 		Position: pgtype.Text{String: req.Position, Valid: req.Position != ""},
+		UserID:   pgtype.UUID{Bytes: userUUID, Valid: true},
 	})
 	if err != nil {
 		return c.JSON(http.StatusInternalServerError, map[string]string{"error": err.Error()})
@@ -1569,10 +1962,19 @@ func (mh *MediaHandler) DeleteMediaNote(c *echo.Context) error {
 		return c.JSON(http.StatusBadRequest, map[string]string{"error": "invalid note id"})
 	}
 
+	userID := c.Get("user_id").(string)
+	userUUID, err := uuid.Parse(userID)
+	if err != nil {
+		return c.JSON(http.StatusBadRequest, map[string]string{"error": "invalid user"})
+	}
+
 	if mh.annotationSvc != nil {
-		err = mh.annotationSvc.TombstoneNoteByID(c.Request().Context(), pgtype.UUID{Bytes: noteUUID, Valid: true})
+		err = mh.annotationSvc.TombstoneNoteByID(c.Request().Context(), pgtype.UUID{Bytes: noteUUID, Valid: true}, pgtype.UUID{Bytes: userUUID, Valid: true})
 	} else {
-		err = mh.db.DeleteMediaNote(c.Request().Context(), pgtype.UUID{Bytes: noteUUID, Valid: true})
+		err = mh.db.DeleteMediaNote(c.Request().Context(), database.DeleteMediaNoteParams{
+			ID:     pgtype.UUID{Bytes: noteUUID, Valid: true},
+			UserID: pgtype.UUID{Bytes: userUUID, Valid: true},
+		})
 	}
 	if err != nil {
 		return c.JSON(http.StatusInternalServerError, map[string]string{"error": err.Error()})
@@ -1774,6 +2176,12 @@ func (mh *MediaHandler) UpdateMediaHighlight(c *echo.Context) error {
 		return c.JSON(http.StatusOK, result.Highlight)
 	}
 
+	userID := c.Get("user_id").(string)
+	userUUID, err := uuid.Parse(userID)
+	if err != nil {
+		return c.JSON(http.StatusBadRequest, map[string]string{"error": "invalid user"})
+	}
+
 	highlight, err := mh.db.UpdateMediaHighlight(c.Request().Context(), database.UpdateMediaHighlightParams{
 		ID:            pgtype.UUID{Bytes: highlightUUID, Valid: true},
 		SelectionText: req.SelectionText,
@@ -1781,6 +2189,7 @@ func (mh *MediaHandler) UpdateMediaHighlight(c *echo.Context) error {
 		EndPosition:   pgtype.Text{String: req.EndPosition, Valid: true},
 		Color:         pgtype.Text{String: color, Valid: true},
 		NoteID:        noteUUID,
+		UserID:        pgtype.UUID{Bytes: userUUID, Valid: true},
 	})
 	if err != nil {
 		return c.JSON(http.StatusInternalServerError, map[string]string{"error": err.Error()})
@@ -1799,14 +2208,27 @@ func (mh *MediaHandler) DeleteMediaHighlight(c *echo.Context) error {
 
 	pgHighlightID := pgtype.UUID{Bytes: highlightUUID, Valid: true}
 
+	userID := c.Get("user_id").(string)
+	userUUID, err := uuid.Parse(userID)
+	if err != nil {
+		return c.JSON(http.StatusBadRequest, map[string]string{"error": "invalid user"})
+	}
+	pgUserID := pgtype.UUID{Bytes: userUUID, Valid: true}
+
 	if mh.annotationSvc != nil {
-		if err := mh.annotationSvc.TombstoneHighlightByID(c.Request().Context(), pgHighlightID, "web"); err != nil {
+		if err := mh.annotationSvc.TombstoneHighlightByID(c.Request().Context(), pgUserID, pgHighlightID, "web"); err != nil {
+			if errors.Is(err, pgx.ErrNoRows) {
+				return c.JSON(http.StatusNotFound, map[string]string{"error": "highlight not found"})
+			}
 			return c.JSON(http.StatusInternalServerError, map[string]string{"error": err.Error()})
 		}
 		return c.NoContent(http.StatusNoContent)
 	}
 
-	err = mh.db.DeleteMediaHighlight(c.Request().Context(), pgHighlightID)
+	err = mh.db.DeleteMediaHighlight(c.Request().Context(), database.DeleteMediaHighlightParams{
+		ID:     pgHighlightID,
+		UserID: pgUserID,
+	})
 	if err != nil {
 		return c.JSON(http.StatusInternalServerError, map[string]string{"error": err.Error()})
 	}
@@ -1951,14 +2373,27 @@ func (mh *MediaHandler) DeleteMediaBookmark(c *echo.Context) error {
 
 	pgBookmarkID := pgtype.UUID{Bytes: bookmarkUUID, Valid: true}
 
+	userID := c.Get("user_id").(string)
+	userUUID, err := uuid.Parse(userID)
+	if err != nil {
+		return c.JSON(http.StatusBadRequest, map[string]string{"error": "invalid user"})
+	}
+	pgUserID := pgtype.UUID{Bytes: userUUID, Valid: true}
+
 	if mh.annotationSvc != nil {
-		if err := mh.annotationSvc.TombstoneBookmarkByID(c.Request().Context(), pgBookmarkID, "web"); err != nil {
+		if err := mh.annotationSvc.TombstoneBookmarkByID(c.Request().Context(), pgUserID, pgBookmarkID, "web"); err != nil {
+			if errors.Is(err, pgx.ErrNoRows) {
+				return c.JSON(http.StatusNotFound, map[string]string{"error": "bookmark not found"})
+			}
 			return c.JSON(http.StatusInternalServerError, map[string]string{"error": err.Error()})
 		}
 		return c.NoContent(http.StatusNoContent)
 	}
 
-	if err := mh.db.DeleteMediaBookmark(c.Request().Context(), pgBookmarkID); err != nil {
+	if err := mh.db.DeleteMediaBookmark(c.Request().Context(), database.DeleteMediaBookmarkParams{
+		ID:     pgBookmarkID,
+		UserID: pgUserID,
+	}); err != nil {
 		return c.JSON(http.StatusInternalServerError, map[string]string{"error": err.Error()})
 	}
 
@@ -2025,6 +2460,7 @@ func (mh *MediaHandler) SearchMediaItems(c *echo.Context) error {
 	authorFilter := c.QueryParam("author_filter")
 	seriesFilter := c.QueryParam("series_filter")
 	genreFilter := c.QueryParam("genre_filter")
+	publisherFilter := c.QueryParam("publisher_filter")
 	tagsFilter := c.QueryParam("tags_filter")
 	languageFilter := c.QueryParam("language_filter")
 	yearMin, _ := strconv.Atoi(c.QueryParam("year_min"))
@@ -2044,20 +2480,21 @@ func (mh *MediaHandler) SearchMediaItems(c *echo.Context) error {
 
 	// Build search params
 	params := services.SearchParams{
-		UserID:         userID.ID,
-		LibraryID:      libUUID,
-		SearchQuery:    query,
-		AuthorFilter:   authorFilter,
-		SeriesFilter:   seriesFilter,
-		GenreFilter:    genreFilter,
-		TagsFilter:     tagsFilter,
-		LanguageFilter: languageFilter,
-		YearMin:        yearMin,
-		YearMax:        yearMax,
-		HasCover:       pgtype.Bool{Bool: hasCover, Valid: hasCoverValid},
-		Sort:           sortParam,
-		Limit:          limit,
-		Offset:         offset,
+		UserID:          userID.ID,
+		LibraryID:       libUUID,
+		SearchQuery:     query,
+		AuthorFilter:    authorFilter,
+		SeriesFilter:    seriesFilter,
+		GenreFilter:     genreFilter,
+		PublisherFilter: publisherFilter,
+		TagsFilter:      tagsFilter,
+		LanguageFilter:  languageFilter,
+		YearMin:         yearMin,
+		YearMax:         yearMax,
+		HasCover:        pgtype.Bool{Bool: hasCover, Valid: hasCoverValid},
+		Sort:            sortParam,
+		Limit:           limit,
+		Offset:          offset,
 	}
 
 	c.Logger().Info("SearchMediaItems called",

internal/handlers/media_detail.go

@@ -13,9 +13,15 @@ type MediaDetail struct {
 
 	// User-specific data
 	Rating          *database.MediaRatings    `json:"rating,omitempty"`
+	Review          *database.MediaReviews    `json:"review,omitempty"` // raw markdown
 	Collections     []database.Collections    `json:"collections"`
 	ReadingProgress *database.ReadingProgress `json:"reading_progress,omitempty"`
 
+	// The viewer's own reading-history card for this book (nil when the
+	// user has no sessions here); rendered as the "Your Reading Stats"
+	// section of the book page.
+	BookStats *BookStatsData `json:"book_stats,omitempty"`
+
 	// Conflict data (if exists)
 	ActiveConflict *ConflictDetailResponse `json:"active_conflict,omitempty"`
 
@@ -27,3 +33,14 @@ type MediaDetail struct {
 	// page's "recently deleted" list with restore/permanent-delete actions.
 	DeletedAnnotations []DeletedAnnotationResponse `json:"deleted_annotations"`
 }
+
+// BookStatsData is the per-book reading-stats card payload.
+type BookStatsData struct {
+	TotalMinutes int
+	TotalPages   int
+	SessionCount int
+	MaxProgress  float64 // 0..1
+	Finished     bool
+	LastSession  string
+	FirstSession string
+}

internal/handlers/opds.go

@@ -90,6 +90,9 @@ func appendToken(url, token string) string {
 // catalogMediaType is the OPDS media type for an acquisition catalog feed.
 const catalogMediaType = "application/atom+xml;profile=opds-catalog;kind=acquisition"
 
+// navFeedMediaType is the OPDS media type for a navigation catalog feed.
+const navFeedMediaType = "application/atom+xml;profile=opds-catalog;kind=navigation"
+
 // addCatalogPaginationLinks adds OPDS pagination links (self, start, first,
 // previous, next, last) and OpenSearch paging metadata (totalResults,
 // itemsPerPage, startIndex) to a feed based on the current page position.
@@ -172,8 +175,109 @@ func formatLabelFromPath(path string) string {
 	}
 }
 
-// GetDeviceCatalog returns the OPDS catalog feed for a device
+// GetDeviceCatalog serves the OPDS root feed for a device.
+//
+// By default it returns a navigation feed: an "All Books" entry (the flat
+// cross-library catalog) followed by one folder entry per visible library.
+// OPDS clients render navigation entries as folders, so each library's
+// books — and its library-scoped search — live under their own node instead
+// of interleaving duplicate copies of the same book in one flat list.
+// Passing ?all=1 serves the flat cross-library acquisition feed directly,
+// preserving the pre-folders behavior.
 func (h *OPDSHandler) GetDeviceCatalog(c *echo.Context) error {
+	if c.QueryParam("all") == "1" {
+		return h.serveAllBooksCatalog(c)
+	}
+
+	deviceID := c.Param("deviceId")
+
+	// Get base URLs
+	_, opdsBaseURL, err := h.getBaseURLs(c)
+	if err != nil {
+		return c.XML(http.StatusInternalServerError, opds.NewErrorFeed("Failed to get config"))
+	}
+
+	// Parse device ID
+	deviceUUID, err := uuid.Parse(deviceID)
+	if err != nil {
+		return c.XML(http.StatusBadRequest, opds.NewErrorFeed("Invalid device ID"))
+	}
+
+	// Verify device exists
+	device, err := h.db.GetDevice(c.Request().Context(), pgtype.UUID{Bytes: deviceUUID, Valid: true})
+	if err != nil {
+		return c.XML(http.StatusNotFound, opds.NewErrorFeed("Device not found"))
+	}
+
+	// Get user's visible libraries
+	userID := device.UserID.Bytes
+	libraries, err := h.db.GetUserVisibleLibraries(c.Request().Context(), pgtype.UUID{Bytes: userID, Valid: true})
+	if err != nil {
+		return c.XML(http.StatusInternalServerError, opds.NewErrorFeed("Failed to get libraries"))
+	}
+
+	token := h.getAuthToken(c)
+
+	feed := opds.NewFeed(
+		fmt.Sprintf("urn:uuid:%s", deviceID),
+		"Bookhoard Library",
+	)
+
+	// OpenSearch discovery: the root search stays global (all libraries).
+	searchURL := appendToken(fmt.Sprintf("%s/devices/%s/search?q={searchTerms}", opdsBaseURL, deviceID), token)
+	feed.AddLink(searchURL, "application/opensearchdescription+xml", "search")
+
+	updated := time.Now().UTC().Format("2006-01-02T15:04:05Z")
+
+	// "All Books" first: the flat cross-library catalog (?all=1).
+	allBooks := opds.NewEntry(
+		fmt.Sprintf("urn:uuid:%s-all-books", deviceID),
+		"All Books",
+		"",
+		updated,
+	)
+	allBooks.AddLink(appendToken(fmt.Sprintf("%s/devices/%s/catalog?all=1", opdsBaseURL, deviceID), token), catalogMediaType, "subsection")
+	allBooks.SetSummary("Browse every book across all your libraries")
+	feed.AddEntry(allBooks)
+
+	// One folder per visible library, with live book counts.
+	counts := make(map[pgtype.UUID]int64)
+	if countRows, cerr := h.db.GetVisibleLibraryMediaCounts(c.Request().Context(), pgtype.UUID{Bytes: userID, Valid: true}); cerr == nil {
+		for _, row := range countRows {
+			counts[row.ID] = row.MediaCount
+		}
+	}
+
+	for _, lib := range libraries {
+		libUUID := uuid.UUID(lib.ID.Bytes).String()
+		title := lib.Name
+		if n, ok := counts[lib.ID]; ok {
+			title = fmt.Sprintf("%s (%d)", lib.Name, n)
+		}
+		entry := opds.NewEntry(
+			fmt.Sprintf("urn:uuid:%s-library-%s", deviceID, libUUID),
+			title,
+			"",
+			updated,
+		)
+		entry.AddLink(appendToken(fmt.Sprintf("%s/devices/%s/library/%s/catalog", opdsBaseURL, deviceID, libUUID), token), catalogMediaType, "subsection")
+		entry.SetSummary("Browse books in the " + lib.Name + " library")
+		feed.AddEntry(entry)
+	}
+
+	// Generate XML
+	xmlString, err := feed.GenerateXMLString()
+	if err != nil {
+		return c.XML(http.StatusInternalServerError, opds.NewErrorFeed("Failed to generate feed"))
+	}
+
+	c.Response().Header().Set("Content-Type", navFeedMediaType)
+	return c.String(http.StatusOK, xmlString)
+}
+
+// serveAllBooksCatalog is the original flat cross-library acquisition feed:
+// every book from every visible library, paginated as one list.
+func (h *OPDSHandler) serveAllBooksCatalog(c *echo.Context) error {
 	deviceID := c.Param("deviceId")
 
 	page := c.QueryParam("page")
@@ -216,8 +320,6 @@ func (h *OPDSHandler) GetDeviceCatalog(c *echo.Context) error {
 
 	// Get user's visible libraries
 	userID := device.UserID.Bytes
-	userUUID := uuid.UUID(userID)
-
 	libraries, err := h.db.GetUserVisibleLibraries(c.Request().Context(), pgtype.UUID{Bytes: userID, Valid: true})
 	if err != nil {
 		return c.XML(http.StatusInternalServerError, opds.NewErrorFeed("Failed to get libraries"))
@@ -276,7 +378,23 @@ func (h *OPDSHandler) GetDeviceCatalog(c *echo.Context) error {
 	feed.AddLink(searchURL, "application/opensearchdescription+xml", "search")
 
 	// Add entries
-	for _, item := range allItems {
+	h.addAcquisitionEntries(c.Request().Context(), feed, device, deviceID, allItems, baseURL, opdsBaseURL, token)
+
+	// Generate XML
+	xmlString, err := feed.GenerateXMLString()
+	if err != nil {
+		return c.XML(http.StatusInternalServerError, opds.NewErrorFeed("Failed to generate feed"))
+	}
+
+	c.Response().Header().Set("Content-Type", catalogMediaType)
+	return c.String(http.StatusOK, xmlString)
+}
+
+// addAcquisitionEntries fills an acquisition feed with book entries for the
+// given items. Shared body of the all-books and per-library catalogs.
+func (h *OPDSHandler) addAcquisitionEntries(ctx context.Context, feed *opds.Feed, device database.Devices, deviceID string, items []database.ListMediaItemsByLibraryRow, baseURL, opdsBaseURL, token string) {
+	userUUID := uuid.UUID(device.UserID.Bytes)
+	for _, item := range items {
 		bookUUID := uuid.UUID(item.ID.Bytes).String()
 		title := item.Title
 		author := ""
@@ -284,7 +402,7 @@ func (h *OPDSHandler) GetDeviceCatalog(c *echo.Context) error {
 			author = item.Author.String
 		}
 
-		updated := item.UpdatedAt.Time.Format("2006-01-02T15:04:05Z")
+		updated := item.UpdatedAt.Time.UTC().Format("2006-01-02T15:04:05Z")
 
 		entry := opds.NewEntry(
 			fmt.Sprintf("urn:uuid:%s", bookUUID),
@@ -323,7 +441,7 @@ func (h *OPDSHandler) GetDeviceCatalog(c *echo.Context) error {
 		}
 
 		// Add collections as categories
-		collections, err := h.db.GetCollectionsForBook(c.Request().Context(), pgtype.UUID{Bytes: item.ID.Bytes, Valid: true})
+		collections, err := h.db.GetCollectionsForBook(ctx, pgtype.UUID{Bytes: item.ID.Bytes, Valid: true})
 		if err == nil {
 			collectionScheme := fmt.Sprintf("%s/collections", baseURL)
 			for _, col := range collections {
@@ -335,6 +453,125 @@ func (h *OPDSHandler) GetDeviceCatalog(c *echo.Context) error {
 
 		feed.AddEntry(entry)
 	}
+}
+
+// GetLibraryCatalog serves an acquisition feed scoped to one of the device
+// owner's visible libraries. Its search link is library-scoped: OPDS clients
+// only substitute {searchTerms}, so opening search from inside this folder
+// searches within this library only.
+func (h *OPDSHandler) GetLibraryCatalog(c *echo.Context) error {
+	deviceID := c.Param("deviceId")
+	libraryID := c.Param("libraryId")
+
+	page := c.QueryParam("page")
+	perPage := c.QueryParam("per_page")
+	includeFormat := c.QueryParam("include_format")
+
+	// Parse pagination parameters
+	pageNum := 1
+	if page != "" {
+		if num, err := strconv.Atoi(page); err == nil && num > 0 {
+			pageNum = num
+		}
+	}
+
+	perPageNum := h.opdsDefaultPageSize()
+	maxPerPage := h.opdsMaxPageSize()
+	if perPage != "" {
+		if num, err := strconv.Atoi(perPage); err == nil && num > 0 && num <= maxPerPage {
+			perPageNum = num
+		}
+	}
+
+	// Get base URLs
+	baseURL, opdsBaseURL, err := h.getBaseURLs(c)
+	if err != nil {
+		return c.XML(http.StatusInternalServerError, opds.NewErrorFeed("Failed to get config"))
+	}
+
+	// Parse IDs
+	deviceUUID, err := uuid.Parse(deviceID)
+	if err != nil {
+		return c.XML(http.StatusBadRequest, opds.NewErrorFeed("Invalid device ID"))
+	}
+	libUUID, err := uuid.Parse(libraryID)
+	if err != nil {
+		return c.XML(http.StatusBadRequest, opds.NewErrorFeed("Invalid library ID"))
+	}
+
+	// Verify device exists
+	device, err := h.db.GetDevice(c.Request().Context(), pgtype.UUID{Bytes: deviceUUID, Valid: true})
+	if err != nil {
+		return c.XML(http.StatusNotFound, opds.NewErrorFeed("Device not found"))
+	}
+
+	// The library must be visible to the device owner.
+	userID := device.UserID.Bytes
+	libraries, err := h.db.GetUserVisibleLibraries(c.Request().Context(), pgtype.UUID{Bytes: userID, Valid: true})
+	if err != nil {
+		return c.XML(http.StatusInternalServerError, opds.NewErrorFeed("Failed to get libraries"))
+	}
+	var library *database.GetUserVisibleLibrariesRow
+	for i := range libraries {
+		if libraries[i].ID.Bytes == libUUID {
+			library = &libraries[i]
+			break
+		}
+	}
+	if library == nil {
+		return c.XML(http.StatusForbidden, opds.NewErrorFeed("Library not accessible"))
+	}
+
+	// Get media items
+	items, err := h.db.ListMediaItemsByLibrary(c.Request().Context(), library.ID)
+	if err != nil {
+		items = []database.ListMediaItemsByLibraryRow{}
+	}
+
+	// Filter by format if specified
+	if includeFormat != "" {
+		filteredItems := []database.ListMediaItemsByLibraryRow{}
+		for _, item := range items {
+			if strings.EqualFold(item.FormatGroup, includeFormat) {
+				filteredItems = append(filteredItems, item)
+			}
+		}
+		items = filteredItems
+	}
+
+	// Pagination
+	totalItems := len(items)
+	startIdx := (pageNum - 1) * perPageNum
+	endIdx := startIdx + perPageNum
+
+	if startIdx >= totalItems {
+		items = []database.ListMediaItemsByLibraryRow{}
+	} else if endIdx > totalItems {
+		items = items[startIdx:]
+	} else {
+		items = items[startIdx:endIdx]
+	}
+
+	// Create OPDS feed
+	feed := opds.NewFeed(
+		fmt.Sprintf("urn:uuid:%s-library-%s", deviceID, libUUID),
+		library.Name,
+	)
+
+	token := h.getAuthToken(c)
+	catalogBase := fmt.Sprintf("%s/devices/%s/library/%s/catalog", opdsBaseURL, deviceID, libUUID)
+	addCatalogPaginationLinks(feed, catalogBase, pageNum, perPageNum, totalItems, token)
+
+	// Library-scoped search discovery: the template pins this library.
+	searchURL := appendToken(fmt.Sprintf("%s/devices/%s/search?q={searchTerms}&library_id=%s", opdsBaseURL, deviceID, libUUID), token)
+	feed.AddLink(searchURL, "application/opensearchdescription+xml", "search")
+
+	// Up-link back to the root navigation feed.
+	rootURL := appendToken(fmt.Sprintf("%s/devices/%s/catalog", opdsBaseURL, deviceID), token)
+	feed.AddLink(rootURL, navFeedMediaType, "up")
+
+	// Add entries
+	h.addAcquisitionEntries(c.Request().Context(), feed, device, deviceID, items, baseURL, opdsBaseURL, token)
 
 	// Generate XML
 	xmlString, err := feed.GenerateXMLString()
@@ -342,7 +579,7 @@ func (h *OPDSHandler) GetDeviceCatalog(c *echo.Context) error {
 		return c.XML(http.StatusInternalServerError, opds.NewErrorFeed("Failed to generate feed"))
 	}
 
-	c.Response().Header().Set("Content-Type", "application/atom+xml;profile=opds-catalog;kind=acquisition")
+	c.Response().Header().Set("Content-Type", catalogMediaType)
 	return c.String(http.StatusOK, xmlString)
 }
 
@@ -377,20 +614,50 @@ func (h *OPDSHandler) SearchDeviceCatalog(c *echo.Context) error {
 
 	// Get user's visible libraries
 	userID := device.UserID.Bytes
-	_, err = h.db.GetUserVisibleLibraries(c.Request().Context(), pgtype.UUID{Bytes: userID, Valid: true})
+	libraries, err := h.db.GetUserVisibleLibraries(c.Request().Context(), pgtype.UUID{Bytes: userID, Valid: true})
 	if err != nil {
 		return c.XML(http.StatusInternalServerError, opds.NewErrorFeed("Failed to get libraries"))
 	}
 
+	// Optional library scope: library folder feeds advertise their own search
+	// link with this parameter, so opening search from inside a library
+	// folder searches within that library only.
+	var scopedLibraryID pgtype.UUID
+	scopedLibraryName := ""
+	if libParam := c.QueryParam("library_id"); libParam != "" {
+		parsed, perr := uuid.Parse(libParam)
+		if perr != nil {
+			return c.XML(http.StatusBadRequest, opds.NewErrorFeed("Invalid library ID"))
+		}
+		for i := range libraries {
+			if libraries[i].ID.Bytes == parsed {
+				scopedLibraryID = libraries[i].ID
+				scopedLibraryName = libraries[i].Name
+				break
+			}
+		}
+		if !scopedLibraryID.Valid {
+			return c.XML(http.StatusForbidden, opds.NewErrorFeed("Library not accessible"))
+		}
+	}
+
 	token := h.getAuthToken(c)
 
 	// No query: serve the OpenSearch description document so clients can learn
-	// the search template (contains the {searchTerms} placeholder).
+	// the search URL template (contains the {searchTerms} placeholder).
 	if query == "" {
-		searchURL := appendToken(fmt.Sprintf("%s/devices/%s/search?q={searchTerms}", opdsBaseURL, deviceID), token)
+		template := fmt.Sprintf("%s/devices/%s/search?q={searchTerms}", opdsBaseURL, deviceID)
+		shortName := "Bookhoard"
+		description := "Search the Bookhoard library"
+		if scopedLibraryID.Valid {
+			template += "&library_id=" + scopedLibraryID.String()
+			shortName = "Bookhoard: " + scopedLibraryName
+			description = "Search the " + scopedLibraryName + " library"
+		}
+		searchURL := appendToken(template, token)
 		desc := opds.NewSearchDescription(
-			"Bookhoard",
-			"Search the Bookhoard library",
+			shortName,
+			description,
 			searchURL,
 		)
 		xmlString, err := desc.GenerateXMLString()
@@ -404,6 +671,7 @@ func (h *OPDSHandler) SearchDeviceCatalog(c *echo.Context) error {
 	// Search media items
 	allItems, err := h.db.SearchMediaItems(c.Request().Context(), database.SearchMediaItemsParams{
 		UserID:        pgtype.UUID{Bytes: userID, Valid: true},
+		LibraryID:     scopedLibraryID,
 		SearchPattern: pgtype.Text{String: "%" + query + "%", Valid: true},
 		Offset:        pgtype.Int4{Int32: 0, Valid: true},
 		Limit:         pgtype.Int4{Int32: 1000, Valid: true},
@@ -438,7 +706,7 @@ func (h *OPDSHandler) SearchDeviceCatalog(c *echo.Context) error {
 			author = item.Author.String
 		}
 
-		updated := item.UpdatedAt.Time.Format("2006-01-02T15:04:05Z")
+		updated := item.UpdatedAt.Time.UTC().Format("2006-01-02T15:04:05Z")
 
 		entry := opds.NewEntry(
 			fmt.Sprintf("urn:uuid:%s", bookUUID),
@@ -451,6 +719,15 @@ func (h *OPDSHandler) SearchDeviceCatalog(c *echo.Context) error {
 			entry.SetSummary(item.Description.String)
 		}
 
+		// Global (unscoped) search: label which library each copy lives in so
+		// duplicate copies of the same book are distinguishable.
+		if !scopedLibraryID.Valid && item.LibraryName != "" {
+			entry.AddCategory(baseURL+"/libraries", item.LibraryName)
+			if !item.Description.Valid || item.Description.String == "" {
+				entry.SetSummary("Library: " + item.LibraryName)
+			}
+		}
+
 		downloadURL := appendToken(fmt.Sprintf("%s/devices/%s/download/%s", opdsBaseURL, deviceID, bookUUID), token)
 		entry.AddAcquisitionLink(downloadURL, resolveMimeType(item.MimeType, item.FormatMimetype))
 

internal/handlers/progress.go

@@ -97,121 +97,6 @@ func (h *Handler) GetUniversalProgress(c *echo.Context) error {
 }
 
 // UpdateUniversalProgress updates progress with automatic conversion
-func (h *Handler) UpdateUniversalProgress(c *echo.Context) error {
-	user := MustGetAuthenticatedUser(c)
-
-	mediaItemID, err := uuid.Parse(c.Param("id"))
-	if err != nil {
-		return echo.NewHTTPError(http.StatusBadRequest, "invalid media item ID")
-	}
-
-	var req struct {
-		Source   string `json:"source"`
-		Location struct {
-			Percentage *float64 `json:"percentage"`
-			Page       *int     `json:"page"`
-			TotalPages *int     `json:"total_pages"`
-			Epubcfi    *string  `json:"epubcfi"`
-			Character  *int64   `json:"character"`
-			Chapter    *int     `json:"chapter"`
-			ViewportY  *float64 `json:"viewport_y"`
-		} `json:"location"`
-		DeviceMetadata struct {
-			DeviceType string `json:"device_type"`
-			UserAgent  string `json:"user_agent"`
-		} `json:"device_metadata"`
-	}
-
-	if err := c.Bind(&req); err != nil {
-		return echo.NewHTTPError(http.StatusBadRequest, "invalid request body")
-	}
-
-	mediaItem, err := h.db.GetMediaItem(context.Background(), pgtype.UUID{Bytes: mediaItemID, Valid: true})
-	if err != nil {
-		return echo.NewHTTPError(http.StatusNotFound, "media item not found")
-	}
-
-	percentage := 0.0
-	if req.Location.Percentage != nil {
-		percentage = *req.Location.Percentage
-	} else if req.Location.Page != nil && req.Location.TotalPages != nil {
-		percentage = wsync.PageToPercentage(*req.Location.Page, *req.Location.TotalPages)
-	}
-
-	currentPage := 0
-	totalPages := 0
-	if req.Location.Page != nil {
-		currentPage = *req.Location.Page
-	}
-	if req.Location.TotalPages != nil {
-		totalPages = *req.Location.TotalPages
-	}
-	if mediaItem.PageCount.Valid && mediaItem.PageCount.Int32 > 0 {
-		totalPages = int(mediaItem.PageCount.Int32)
-	}
-
-	var epubcfi pgtype.Text
-	if req.Location.Epubcfi != nil {
-		epubcfi = pgtype.Text{String: *req.Location.Epubcfi, Valid: true}
-	}
-
-	var chapter pgtype.Int4
-	if req.Location.Chapter != nil {
-		chapter = pgtype.Int4{Int32: int32(*req.Location.Chapter), Valid: true}
-	}
-
-	var viewportY pgtype.Float8
-	if req.Location.ViewportY != nil {
-		viewportY = pgtype.Float8{Float64: *req.Location.ViewportY, Valid: true}
-	}
-
-	var lastSyncDevice, lastSyncSource pgtype.Text
-	if req.DeviceMetadata.DeviceType != "" {
-		lastSyncDevice = pgtype.Text{String: req.DeviceMetadata.DeviceType, Valid: true}
-		lastSyncSource = pgtype.Text{String: req.Source, Valid: true}
-	}
-
-	updated, err := h.db.UpdateUniversalProgress(context.Background(), database.UpdateUniversalProgressParams{
-		MediaItemID:     pgtype.UUID{Bytes: mediaItemID, Valid: true},
-		UserID:          pgtype.UUID{Bytes: user.ID.Bytes, Valid: true},
-		Percentage:      pgtype.Float8{Float64: percentage, Valid: true},
-		Epubcfi:         epubcfi,
-		Chapter:         chapter,
-		ChapterProgress: pgtype.Float8{Float64: percentage, Valid: true},
-		ViewportY:       viewportY,
-		LastSyncDevice:  lastSyncDevice,
-		LastSyncSource:  lastSyncSource,
-		CurrentPage:     pgtype.Int4{Int32: int32(currentPage), Valid: true},
-		TotalPages:      pgtype.Int4{Int32: int32(totalPages), Valid: true},
-	})
-	if err != nil {
-		return echo.NewHTTPError(http.StatusInternalServerError, "failed to update progress")
-	}
-
-	// Broadcast progress update to all connected WebSocket clients
-	deviceName := "Web"
-	deviceType := "web"
-	if req.DeviceMetadata.DeviceType != "" {
-		deviceType = req.DeviceMetadata.DeviceType
-		deviceName = req.DeviceMetadata.DeviceType
-	}
-
-	h.connManager.BroadcastProgressUpdate(mediaItemID, percentage, wsync.SourceDevice{
-		ID:   uuid.UUID(user.ID.Bytes).String(),
-		Name: deviceName,
-		Type: deviceType,
-	})
-
-	return c.JSON(http.StatusOK, map[string]interface{}{
-		"sync_status":      "success",
-		"progress_updated": true,
-		"percentage":       percentage,
-		"current_page":     currentPage,
-		"total_pages":      totalPages,
-		"last_read_at":     updated.LastReadAt.Time,
-	})
-}
-
 // GetProgressHistory retrieves reading session history
 func (h *Handler) GetProgressHistory(c *echo.Context) error {
 	user := MustGetAuthenticatedUser(c)
@@ -306,7 +191,7 @@ func (h *Handler) GetAllProgress(c *echo.Context) error {
 
 		lastUpdated := ""
 		if progress.LastReadAt.Valid {
-			lastUpdated = progress.LastReadAt.Time.Format("01-02-2006 03:04 PM")
+			lastUpdated = utils.FormatTimeInTimezone(progress.LastReadAt.Time, user.Timezone.String)
 		}
 
 		progressList = append(progressList, ProgressWithMedia{
@@ -376,7 +261,7 @@ func (h *Handler) GetAllProgressData(c *echo.Context) ([]ProgressWithMedia, erro
 
 		lastUpdated := ""
 		if progress.LastReadAt.Valid {
-			lastUpdated = progress.LastReadAt.Time.Format("01-02-2006 03:04 PM")
+			lastUpdated = utils.FormatTimeInTimezone(progress.LastReadAt.Time, user.Timezone.String)
 		}
 
 		progressList = append(progressList, ProgressWithMedia{

internal/handlers/queue.go

@@ -2,6 +2,7 @@ package handlers
 
 import (
 	"bookhoard/internal/database"
+	"bookhoard/internal/utils"
 	"context"
 	"net/http"
 	"strconv"
@@ -47,7 +48,11 @@ type QueueItemResponse struct {
 	Status       string  `json:"status"`
 	ErrorMessage *string `json:"error_message,omitempty"`
 	CreatedAt    string  `json:"created_at"`
-	ProcessedAt  *string `json:"processed_at,omitempty"`
+	// CreatedAtDisplay is the server-rendered wall-clock string in the
+	// requesting admin's timezone (templates render this; created_at stays
+	// machine-readable RFC3339 for API consumers).
+	CreatedAtDisplay string  `json:"created_at_display,omitempty"`
+	ProcessedAt      *string `json:"processed_at,omitempty"`
 }
 
 func (h *QueueHandler) GetDeviceQueueStats(c *echo.Context) error {
@@ -136,7 +141,9 @@ func (h *QueueHandler) ListDeviceQueueItems(c *echo.Context) error {
 			Status:       item.Status.String,
 			ErrorMessage: textPtrToString(item.ErrorMessage),
 			CreatedAt:    item.CreatedAt.Time.Format("2006-01-02T15:04:05Z07:00"),
-			ProcessedAt:  timestamptzPtrToString(item.ProcessedAt),
+			CreatedAtDisplay: utils.FormatTimeInTimezone(
+				item.CreatedAt.Time, user.Timezone.String),
+			ProcessedAt: timestamptzPtrToString(item.ProcessedAt),
 		})
 	}
 
@@ -189,7 +196,9 @@ func (h *QueueHandler) GetQueueData(c *echo.Context) ([]QueueItemResponse, error
 			Status:       item.Status.String,
 			ErrorMessage: textPtrToString(item.ErrorMessage),
 			CreatedAt:    item.CreatedAt.Time.Format("2006-01-02T15:04:05Z07:00"),
-			ProcessedAt:  timestamptzPtrToString(item.ProcessedAt),
+			CreatedAtDisplay: utils.FormatTimeInTimezone(
+				item.CreatedAt.Time, user.Timezone.String),
+			ProcessedAt: timestamptzPtrToString(item.ProcessedAt),
 		})
 	}
 

internal/handlers/reader.go

@@ -213,6 +213,27 @@ func (h *ReaderHandler) GetPage(c *echo.Context) error {
 }
 
 // GetChapters returns chapter metadata
+// ensureItemVisible enforces the library-visibility gate for reader
+// content and layout endpoints (same rule GetPage applies): a hidden
+// library leaks nothing by item id.
+func (h *ReaderHandler) ensureItemVisible(c *echo.Context, mediaItem *database.MediaItems) error {
+	user := c.Get("user")
+	if user == nil {
+		return c.JSON(http.StatusUnauthorized, map[string]string{"error": "User not authenticated"})
+	}
+	userData := user.(database.Users)
+	libraries, err := h.libraryService.GetUserVisibleLibraries(c.Request().Context(), userData.ID)
+	if err != nil {
+		return c.JSON(http.StatusInternalServerError, map[string]string{"error": "Failed to check library access"})
+	}
+	for _, lib := range libraries {
+		if lib.ID == mediaItem.LibraryID {
+			return nil
+		}
+	}
+	return c.JSON(http.StatusForbidden, map[string]string{"error": "Access denied to this library"})
+}
+
 func (h *ReaderHandler) GetChapters(c *echo.Context) error {
 	mediaItemID := c.Param("mediaItemId")
 	parsedUUID, err := uuid.Parse(mediaItemID)
@@ -220,6 +241,14 @@ func (h *ReaderHandler) GetChapters(c *echo.Context) error {
 		return c.JSON(http.StatusBadRequest, map[string]string{"error": "Invalid media item ID"})
 	}
 
+	mediaItem, err := h.db.GetMediaItem(c.Request().Context(), pgtype.UUID{Bytes: parsedUUID, Valid: true})
+	if err != nil {
+		return c.JSON(http.StatusNotFound, map[string]string{"error": "Media item not found"})
+	}
+	if err := h.ensureItemVisible(c, &mediaItem); err != nil {
+		return err
+	}
+
 	// Use reader service to detect chapters
 	chapters, err := h.readerService.DetectChapters(c.Request().Context(), parsedUUID)
 	if err != nil {
@@ -246,6 +275,14 @@ func (h *ReaderHandler) GetPanels(c *echo.Context) error {
 		return c.JSON(http.StatusBadRequest, map[string]string{"error": "Invalid page number"})
 	}
 
+	mediaItem, err := h.db.GetMediaItem(c.Request().Context(), pgtype.UUID{Bytes: parsedUUID, Valid: true})
+	if err != nil {
+		return c.JSON(http.StatusNotFound, map[string]string{"error": "Media item not found"})
+	}
+	if err := h.ensureItemVisible(c, &mediaItem); err != nil {
+		return err
+	}
+
 	// Get detection method from query
 	method := c.QueryParam("method")
 	if method == "" {
@@ -398,6 +435,9 @@ func (h *ReaderHandler) GetPDFOutline(c *echo.Context) error {
 	if err != nil {
 		return c.JSON(http.StatusNotFound, map[string]string{"error": "Media item not found"})
 	}
+	if err := h.ensureItemVisible(c, &mediaItem); err != nil {
+		return err
+	}
 
 	// Only PDFs have outlines
 	if mediaItem.FormatGroup != "pdf" {
@@ -438,6 +478,9 @@ func (h *ReaderHandler) GetPDFThumbnail(c *echo.Context) error {
 	if err != nil {
 		return c.JSON(http.StatusNotFound, map[string]string{"error": "Media item not found"})
 	}
+	if err := h.ensureItemVisible(c, &mediaItem); err != nil {
+		return err
+	}
 
 	// Get thumbnail size from query
 	width := c.QueryParam("width")
@@ -590,57 +633,6 @@ func (h *ReaderHandler) generatePDFThumbnail(fullPath string, page int, width, h
 	return []byte{}, nil
 }
 
-func (h *ReaderHandler) ParseEbook(c *echo.Context) error {
-	mediaItemID := c.Param("mediaItemId")
-	parsedUUID, err := uuid.Parse(mediaItemID)
-	if err != nil {
-		return c.JSON(400, map[string]string{"error": "Invalid media item ID"})
-	}
-
-	// Fetch media item
-	mediaItem, err := h.db.GetMediaItem(c.Request().Context(), pgtype.UUID{Bytes: parsedUUID, Valid: true})
-	if err != nil {
-		if errors.Is(err, pgx.ErrNoRows) {
-			return c.JSON(404, map[string]string{"error": "Media item not found"})
-		}
-		return c.JSON(500, map[string]string{"error": "Failed to fetch media item"})
-	}
-
-	// Check if format requires server-side parsing
-	requiresServerParsing := false
-	formatName := ""
-	switch mediaItem.MimeType.String {
-	case "application/x-mobipocket-ebook":
-		requiresServerParsing = true
-		formatName = "MOBI"
-	case "application/vnd.amazon.mobi8-ebook":
-		requiresServerParsing = true
-		formatName = "AZW3/KF8"
-	case "application/vnd.openxmlformats-officedocument.wordprocessingml.document":
-		requiresServerParsing = true
-		formatName = "DOCX"
-	case "application/rtf":
-		requiresServerParsing = true
-		formatName = "RTF"
-	}
-
-	if requiresServerParsing {
-		// Phase 1: Return 501 for server-side formats
-		return c.JSON(501, map[string]interface{}{
-			"error":      fmt.Sprintf("Server-side %s parsing is not yet implemented", formatName),
-			"message":    fmt.Sprintf("%s format support is planned for Phase 2.5", formatName),
-			"suggestion": "Please convert your ebook to EPUB format for now",
-			"format":     formatName,
-			"phase":      "2.5",
-		})
-	}
-
-	// Client-side format - should not call this endpoint
-	return c.JSON(400, map[string]string{
-		"error": "This format should be parsed client-side, not on the server",
-	})
-}
-
 // ShouldTreatAsComic reports whether a fixed-layout item that lives in a
 // comics or manga library should get comic reader treatment: bookmarks
 // only — no text-selection highlights, no annotations, no in-book search.

internal/handlers/scanner.go

@@ -177,6 +177,38 @@ func (h *Handler) GetScanStatus(c *echo.Context) error {
 	})
 }
 
+// GetActiveScans handles GET /api/scanner/active (admin): every
+// pending/running job. Lets the admin page re-attach to in-flight
+// scans after a page refresh instead of only tracking scans it
+// started itself in this page load.
+func (h *Handler) GetActiveScans(c *echo.Context) error {
+	jobs := h.worker.GetActiveScanJobs()
+	return c.JSON(http.StatusOK, map[string]interface{}{
+		"scanning": len(jobs) > 0,
+		"jobs":     jobs,
+	})
+}
+
+// GetScanSummary handles GET /api/scanner/active-summary (any
+// authenticated user): whether a scan is running and its average
+// progress (0-1). Powers the sitewide sidebar indicator, which must
+// survive page refreshes — websocket events alone only reach pages
+// that were already open when the scan started.
+func (h *Handler) GetScanSummary(c *echo.Context) error {
+	jobs := h.worker.GetActiveScanJobs()
+	progress := 0.0
+	if len(jobs) > 0 {
+		for _, job := range jobs {
+			progress += job.Progress
+		}
+		progress /= float64(len(jobs))
+	}
+	return c.JSON(http.StatusOK, map[string]interface{}{
+		"scanning": len(jobs) > 0,
+		"progress": progress,
+	})
+}
+
 // StartWatchModeForLibrary starts watching a specific library's folders
 func (h *Handler) StartWatchModeForLibrary(ctx context.Context, libraryID pgtype.UUID, adminID pgtype.UUID) error {
 	h.mu.Lock()

internal/handlers/series.go

@@ -50,13 +50,25 @@ func (h *SeriesHandler) GetSeries(c *echo.Context) error {
 		}
 	}
 
-	seriesList, total, err := h.seriesService.GetSeriesPage(c.Request().Context(), libUUID, limit, offset)
+	// Visibility scoping: an explicit library_id must be visible to the
+	// requester (403 otherwise); the unscoped aggregate covers only the
+	// requester's visible libraries.
+	visibleSet, visibleIDs, err := h.visibleLibrarySet(c)
+	if err != nil {
+		return err
+	}
+	if libraryID != "" && !visibleSet[libraryID] {
+		return c.JSON(http.StatusForbidden, map[string]string{"error": "library not accessible"})
+	}
+
+	seriesList, total, err := h.seriesService.GetSeriesPage(c.Request().Context(), libUUID, visibleIDs, limit, offset)
 	if err != nil {
 		return c.JSON(http.StatusInternalServerError, map[string]string{"error": "Failed to load series"})
 	}
 
 	type SeriesResponse struct {
 		Name          string   `json:"name"`
+		LibraryID     string   `json:"library_id"`
 		BookCount     int64    `json:"book_count"`
 		TotalInSeries int      `json:"total_in_series"`
 		CoverPaths    []string `json:"cover_paths"`
@@ -67,6 +79,7 @@ func (h *SeriesHandler) GetSeries(c *echo.Context) error {
 	for _, s := range seriesList {
 		response = append(response, SeriesResponse{
 			Name:          s.Name,
+			LibraryID:     s.LibraryID,
 			BookCount:     s.BookCount,
 			TotalInSeries: s.TotalInSeries,
 			CoverPaths:    s.CoverPaths,
@@ -82,13 +95,58 @@ func (h *SeriesHandler) GetSeries(c *echo.Context) error {
 	})
 }
 
+// visibleLibrarySet loads the requester's visible libraries. Every series
+// path funnels through this: hidden libraries contribute nothing, and an
+// explicit library_id outside the set is a 403, not a silent pass.
+func (h *SeriesHandler) visibleLibrarySet(c *echo.Context) (map[string]bool, []pgtype.UUID, error) {
+	user, ok := c.Get("user").(database.Users)
+	if !ok {
+		return nil, nil, echo.NewHTTPError(http.StatusUnauthorized, "invalid user")
+	}
+	libraries, err := h.seriesService.VisibleLibraries(c.Request().Context(), user.ID)
+	if err != nil {
+		return nil, nil, echo.NewHTTPError(http.StatusInternalServerError, "failed to check library access")
+	}
+	set := make(map[string]bool, len(libraries))
+	ids := make([]pgtype.UUID, 0, len(libraries))
+	for _, lib := range libraries {
+		if !lib.ID.Valid {
+			continue
+		}
+		libUUID, err := uuid.FromBytes(lib.ID.Bytes[0:16])
+		if err != nil {
+			continue
+		}
+		set[libUUID.String()] = true
+		ids = append(ids, lib.ID)
+	}
+	return set, ids, nil
+}
+
 func (h *SeriesHandler) GetSeriesBooks(c *echo.Context) error {
 	seriesName := c.QueryParam("name")
 	if seriesName == "" {
 		return c.JSON(http.StatusBadRequest, map[string]string{"error": "name required"})
 	}
 
-	books, err := h.seriesService.GetSeriesBooks(c.Request().Context(), seriesName)
+	libraryID := c.QueryParam("library_id")
+	if libraryID == "" {
+		return c.JSON(http.StatusBadRequest, map[string]string{"error": "library_id required"})
+	}
+	libUUID, err := uuid.Parse(libraryID)
+	if err != nil {
+		return c.JSON(http.StatusBadRequest, map[string]string{"error": "invalid library_id"})
+	}
+
+	visibleSet, _, err := h.visibleLibrarySet(c)
+	if err != nil {
+		return err
+	}
+	if !visibleSet[libraryID] {
+		return c.JSON(http.StatusForbidden, map[string]string{"error": "library not accessible"})
+	}
+
+	books, err := h.seriesService.GetSeriesBooks(c.Request().Context(), pgtype.UUID{Bytes: libUUID, Valid: true}, seriesName)
 	if err != nil {
 		return c.JSON(http.StatusInternalServerError, map[string]string{"error": "Failed to load series books"})
 	}
@@ -105,13 +163,14 @@ func (h *SeriesHandler) GetSeriesBooks(c *echo.Context) error {
 	}
 
 	return c.JSON(http.StatusOK, map[string]interface{}{
-		"name":  seriesName,
-		"books": bookCards,
-		"total": len(bookCards),
+		"name":       seriesName,
+		"library_id": libraryID,
+		"books":      bookCards,
+		"total":      len(bookCards),
 	})
 }
 
-func GetSeriesCardsData(ctx context.Context, db *database.Queries, libraryID pgtype.UUID, limit, offset int) ([]services.SeriesInfo, int, error) {
+func GetSeriesCardsData(ctx context.Context, db *database.Queries, libraryID pgtype.UUID, visibleLibraryIDs []pgtype.UUID, limit, offset int) ([]services.SeriesInfo, int, error) {
 	svc := services.NewSeriesService(db)
-	return svc.GetSeriesPage(ctx, libraryID, limit, offset)
+	return svc.GetSeriesPage(ctx, libraryID, visibleLibraryIDs, limit, offset)
 }

internal/handlers/stats.go

@@ -0,0 +1,99 @@
+package handlers
+
+import (
+	"bookhoard/internal/database"
+	"bookhoard/internal/services"
+	"net/http"
+
+	"github.com/google/uuid"
+	"github.com/jackc/pgx/v5/pgtype"
+	"github.com/labstack/echo/v5"
+)
+
+// StatsHandler serves the reading-statistics API (/api/stats/*) backed
+// by the StatisticsService. The server owns every conversion: clients
+// receive user-timezone-rendered strings plus raw minute/page counts.
+type StatsHandler struct {
+	statsService *services.StatisticsService
+}
+
+func NewStatsHandler(statsService *services.StatisticsService) *StatsHandler {
+	return &StatsHandler{statsService: statsService}
+}
+
+func mustUser(c *echo.Context) (database.Users, bool) {
+	user, ok := c.Get("user").(database.Users)
+	return user, ok
+}
+
+// Summary handles GET /api/stats/summary?range=7|30|90|year — the /stats
+// page's complete payload: totals, daily arrays, streaks, most-active
+// day, top books, per-library breakdown.
+func (h *StatsHandler) Summary(c *echo.Context) error {
+	user, ok := mustUser(c)
+	if !ok {
+		return echo.NewHTTPError(http.StatusUnauthorized, "invalid user")
+	}
+	summary, err := h.statsService.UserSummary(c.Request().Context(),
+		pgtype.UUID{Bytes: user.ID.Bytes, Valid: true},
+		user.Timezone.String,
+		c.QueryParam("range"),
+	)
+	if err != nil {
+		if err.Error()[:7] == "invalid" {
+			return echo.NewHTTPError(http.StatusBadRequest, err.Error())
+		}
+		return echo.NewHTTPError(http.StatusInternalServerError, err.Error())
+	}
+	return c.JSON(http.StatusOK, summary)
+}
+
+// ThisWeek handles GET /api/stats/this-week — the dashboard widget's
+// data: rolling 7-day totals vs the previous seven days, plus streak.
+// An optional ?library_id scopes the week to one library (the
+// dashboard's library switcher drives it).
+func (h *StatsHandler) ThisWeek(c *echo.Context) error {
+	user, ok := mustUser(c)
+	if !ok {
+		return echo.NewHTTPError(http.StatusUnauthorized, "invalid user")
+	}
+	var libraryID pgtype.UUID
+	if raw := c.QueryParam("library_id"); raw != "" {
+		parsed, err := uuid.Parse(raw)
+		if err != nil {
+			return echo.NewHTTPError(http.StatusBadRequest, "invalid library id")
+		}
+		libraryID = pgtype.UUID{Bytes: parsed, Valid: true}
+	}
+	week, err := h.statsService.ThisWeek(c.Request().Context(),
+		pgtype.UUID{Bytes: user.ID.Bytes, Valid: true},
+		user.Timezone.String,
+		libraryID,
+	)
+	if err != nil {
+		return echo.NewHTTPError(http.StatusInternalServerError, err.Error())
+	}
+	return c.JSON(http.StatusOK, week)
+}
+
+// BookStats handles GET /api/stats/books/:id — the per-book card on the
+// book detail page (lifetime totals + recent sessions).
+func (h *StatsHandler) BookStats(c *echo.Context) error {
+	user, ok := mustUser(c)
+	if !ok {
+		return echo.NewHTTPError(http.StatusUnauthorized, "invalid user")
+	}
+	mediaItemID, err := uuid.Parse(c.Param("id"))
+	if err != nil {
+		return echo.NewHTTPError(http.StatusBadRequest, "invalid media item id")
+	}
+	stats, err := h.statsService.BookStats(c.Request().Context(),
+		pgtype.UUID{Bytes: user.ID.Bytes, Valid: true},
+		mediaItemID,
+		user.Timezone.String,
+	)
+	if err != nil {
+		return echo.NewHTTPError(http.StatusInternalServerError, err.Error())
+	}
+	return c.JSON(http.StatusOK, stats)
+}

internal/router/analytics.go

@@ -8,9 +8,18 @@ func registerAnalyticsRoutes(cfg *Config) {
 
 	protected := e.Group("/api", jwtMiddleware)
 
-	// Analytics routes
+	// Analytics routes (legacy shape; kept for existing API consumers —
+	// the web UI moved to /stats)
 	analytics := protected.Group("/analytics")
 	analytics.GET("/reading-stats", cfg.AnalyticsHandler.GetReadingStats)
 	analytics.GET("/device-usage", cfg.AnalyticsHandler.GetDeviceUsage)
 	analytics.GET("/popular-books", cfg.AnalyticsHandler.GetPopularBooks)
+
+	// Reading-statistics API (/stats page + dashboard widget + per-book
+	// card). Same session seed, service-backed aggregates, user-timezone
+	// bucketing. The legacy /analytics page redirects to /stats.
+	stats := protected.Group("/stats")
+	stats.GET("/summary", cfg.StatsHandler.Summary)
+	stats.GET("/this-week", cfg.StatsHandler.ThisWeek)
+	stats.GET("/books/:id", cfg.StatsHandler.BookStats)
 }

internal/router/auth.go

@@ -12,6 +12,7 @@ func registerAuthRoutes(cfg *Config, rateLimitMiddleware echo.MiddlewareFunc) {
 	// Auth routes (no auth required, but rate limited)
 	e.POST("/api/auth/register", rateLimitMiddleware(cfg.AuthHandler.Register))
 	e.POST("/api/auth/login", rateLimitMiddleware(cfg.AuthHandler.Login))
+	e.GET("/api/auth/password-rules", cfg.AuthHandler.GetPasswordRules)
 
 	// JWT middleware for protected routes
 	jwtMiddleware := createJWTMiddleware(cfg)
@@ -40,6 +41,7 @@ func registerAuthRoutes(cfg *Config, rateLimitMiddleware echo.MiddlewareFunc) {
 	// Admin-only routes (same handlers with URL param)
 	admin := protected.Group("/auth", handlers.AdminMiddleware)
 	admin.GET("/users", cfg.AuthHandler.ListUsers)
+	admin.POST("/users", cfg.AuthHandler.AdminCreateUser)
 	admin.PUT("/users/:id/max-devices", cfg.AuthHandler.UpdateUserMaxDevices)
 	admin.PUT("/profile/:id", cfg.AuthHandler.UpdateProfile)
 	admin.PUT("/password/:id", cfg.AuthHandler.UpdatePassword)

internal/router/collections.go

@@ -22,6 +22,12 @@ func registerCollectionsRoutes(cfg *Config) {
 	collections.POST("/test-rules", cfg.CollectionHandler.TestRules)
 	collections.POST("/preview", cfg.CollectionHandler.PreviewCollection)
 
+	// Smart collection rule CRUD (the rules builder persists through
+	// these; type follows rules presence — first rule = smart).
+	collections.POST("/:id/rules", cfg.CollectionHandler.AddRule)
+	collections.PUT("/:id/rules/:ruleId", cfg.CollectionHandler.UpdateRule)
+	collections.DELETE("/:id/rules/:ruleId", cfg.CollectionHandler.RemoveRule)
+
 	// Device shelf mapping routes
 	deviceCollections := protected.Group("/devices/:id/collections")
 	deviceCollections.GET("", cfg.CollectionHandler.GetDeviceMappings)

internal/router/frontend.go

@@ -17,9 +17,12 @@ import (
 	"bookhoard/internal/handlers"
 	"bookhoard/internal/services"
 	"bookhoard/internal/utils"
+	"bookhoard/internal/version"
 	"bookhoard/templates"
+	"errors"
 
 	"github.com/golang-jwt/jwt/v5"
+	"github.com/jackc/pgx/v5"
 	"github.com/jackc/pgx/v5/pgtype"
 	"github.com/labstack/echo/v5"
 
@@ -61,7 +64,7 @@ func registerFrontendRoutes(cfg *Config) {
 		var buf bytes.Buffer
 		sessionExpired := c.QueryParam("session") == "expired"
 		deleted := c.QueryParam("deleted") == "true"
-		err := templates.Login(sessionExpired, deleted).Render(c.Request().Context(), &buf)
+		err := templates.Login(sessionExpired, deleted, templates.SignupVisible()).Render(c.Request().Context(), &buf)
 		if err != nil {
 			return err
 		}
@@ -69,6 +72,13 @@ func registerFrontendRoutes(cfg *Config) {
 	})
 
 	e.GET("/register", func(c *echo.Context) error {
+		// Registration can be disabled by admins. The first-user exception
+		// keeps the page reachable on an unconfigured server (zero admins) —
+		// see templates.SignupVisible for the shared reasoning. Redirect
+		// (not 404) so stale links and bookmarks land somewhere sensible.
+		if !templates.SignupVisible() {
+			return c.Redirect(http.StatusFound, "/login")
+		}
 		var buf bytes.Buffer
 		err := templates.Register().Render(c.Request().Context(), &buf)
 		if err != nil {
@@ -100,7 +110,7 @@ func registerFrontendRoutes(cfg *Config) {
 			loggedIn = err == nil && token.Valid
 		}
 
-		err = templates.Index(loggedIn).Render(c.Request().Context(), &buf)
+		err = templates.Index(loggedIn, templates.SignupVisible()).Render(c.Request().Context(), &buf)
 		if err != nil {
 			return err
 		}
@@ -112,7 +122,7 @@ func registerFrontendRoutes(cfg *Config) {
 	// ============================================================================
 
 	// Protected frontend routes (no /api prefix)
-	frontendProtected := e.Group("", jwtMiddleware, ensureUserExistsMiddleware(cfg))
+	frontendProtected := e.Group("", jwtMiddleware)
 
 	// Series browse page
 	frontendProtected.GET("/series", func(c *echo.Context) error {
@@ -143,27 +153,38 @@ func registerFrontendRoutes(cfg *Config) {
 		totalPages := 1
 
 		if errorMsg == "" {
-			seriesList, total, err := handlers.GetSeriesCardsData(c.Request().Context(), cfg.Queries, libRes.LibUUID, perSeriesPage, offset)
-			if err != nil {
-				log.Printf("GetSeriesCardsData failed: %v", err)
+			// Visible-library scoping: cards are grouped per library, and a
+			// specific library selection only renders if it's in the set.
+			visibleSet, visibleIDs, visErr := visibleLibraryIDsFor(c, cfg)
+			if visErr != nil {
+				log.Printf("visibleLibraryIDsFor failed: %v", visErr)
 				errorMsg = "Error loading series"
+			} else if libRes.LibUUID.Valid && !visibleSet[libRes.LibraryID] {
+				errorMsg = "Library not accessible"
 			} else {
-				totalPages = (total + perSeriesPage - 1) / perSeriesPage
-				if totalPages < 1 {
-					totalPages = 1
-				}
-				seriesCards = make([]templates.SeriesCardData, 0, len(seriesList))
-				for _, s := range seriesList {
-					covers := s.CoverPaths
-					if covers == nil {
-						covers = []string{}
+				seriesList, total, err := handlers.GetSeriesCardsData(c.Request().Context(), cfg.Queries, libRes.LibUUID, visibleIDs, perSeriesPage, offset)
+				if err != nil {
+					log.Printf("GetSeriesCardsData failed: %v", err)
+					errorMsg = "Error loading series"
+				} else {
+					totalPages = (total + perSeriesPage - 1) / perSeriesPage
+					if totalPages < 1 {
+						totalPages = 1
+					}
+					seriesCards = make([]templates.SeriesCardData, 0, len(seriesList))
+					for _, s := range seriesList {
+						covers := s.CoverPaths
+						if covers == nil {
+							covers = []string{}
+						}
+						seriesCards = append(seriesCards, templates.SeriesCardData{
+							Name:          s.Name,
+							LibraryID:     s.LibraryID,
+							BookCount:     s.BookCount,
+							TotalInSeries: s.TotalInSeries,
+							CoverPaths:    covers,
+						})
 					}
-					seriesCards = append(seriesCards, templates.SeriesCardData{
-						Name:          s.Name,
-						BookCount:     s.BookCount,
-						TotalInSeries: s.TotalInSeries,
-						CoverPaths:    covers,
-					})
 				}
 			}
 		}
@@ -194,10 +215,28 @@ func registerFrontendRoutes(cfg *Config) {
 			return renderErrorPage(c, "Series name required", "bad_request")
 		}
 
+		// Series are per-library now: the detail page must say WHICH library's
+		// series it is showing, and the requester must be able to see it.
+		libraryIDParam := c.QueryParam("library_id")
+		if libraryIDParam == "" {
+			return renderErrorPage(c, "Library required", "bad_request")
+		}
+		libUUIDParam, err := uuid.Parse(libraryIDParam)
+		if err != nil {
+			return renderErrorPage(c, "Invalid library", "bad_request")
+		}
+		visibleSet, _, visErr := visibleLibraryIDsFor(c, cfg)
+		if visErr != nil {
+			return renderErrorPage(c, "Error checking access", "access_error")
+		}
+		if !visibleSet[libraryIDParam] {
+			return renderErrorPage(c, "Access denied", "access_denied")
+		}
+
 		var bookInfoList []handlers.BookInfo
 
 		svc := services.NewSeriesService(cfg.Queries)
-		books, err := svc.GetSeriesBooks(c.Request().Context(), seriesName)
+		books, err := svc.GetSeriesBooks(c.Request().Context(), pgtype.UUID{Bytes: libUUIDParam, Valid: true}, seriesName)
 		if err != nil {
 			log.Printf("GetSeriesBooks failed: %v", err)
 			errorMsg = "Error loading series books"
@@ -434,8 +473,36 @@ func registerFrontendRoutes(cfg *Config) {
 		sectionData := handlers.MarkActiveConflictsSections(c.Request().Context(), cfg.Queries, userPgID, handlers.BuildSections(visibleSections, libraryID))
 		allSectionsData := handlers.BuildSections(allSections, libraryID)
 
+		// "This week" widget: the user's rolling 7-day reading pulse for
+		// the CURRENTLY SELECTED library (the same resolution the sections
+		// use), from the same session seed the /stats page serves.
+		// Suppressed when the service fails (dashboard always renders).
+		var week *templates.WeekStatsData
+		if cfg.StatisticsService != nil {
+			weekScope := pgtype.UUID{}
+			if !libRes.IsAll {
+				weekScope = libRes.LibUUID
+			}
+			weekSvc, weekErr := cfg.StatisticsService.ThisWeek(c.Request().Context(),
+				pgtype.UUID{Bytes: userUUID, Valid: true}, user.Timezone, weekScope)
+			if weekErr == nil {
+				week = &templates.WeekStatsData{
+					WeekMinutes:   weekSvc.WeekMinutes,
+					WeekPages:     weekSvc.WeekPages,
+					WeekSessions:  weekSvc.WeekSessions,
+					WeekBooks:     weekSvc.WeekBooks,
+					PrevMinutes:   weekSvc.PrevMinutes,
+					ActiveToday:   weekSvc.ActiveToday,
+					CurrentStreak: weekSvc.CurrentStreak,
+					LibraryID:     libRes.LibraryID,
+				}
+			} else {
+				log.Printf("ThisWeek widget failed: %v", weekErr)
+			}
+		}
+
 		var buf bytes.Buffer
-		err = templates.Dashboard(user, sectionData, allSectionsData, libRes.Libraries, libraryID, prefs.HiddenCollections, limit, errorMsg).Render(c.Request().Context(), &buf)
+		err = templates.Dashboard(user, sectionData, allSectionsData, libRes.Libraries, libraryID, prefs.HiddenCollections, limit, week, errorMsg).Render(c.Request().Context(), &buf)
 		if err != nil {
 			return err
 		}
@@ -459,14 +526,56 @@ func registerFrontendRoutes(cfg *Config) {
 			errorMsg = "Error loading collections"
 		}
 
+		// Live per-card counts: smart collections are rule-matched at
+		// render against the requesting user's visible libraries; static
+		// ones count their stored links. Library filter applies when a
+		// specific library is selected.
+		libRes := resolveLibrary(c, cfg, user.ID)
+		var libScope pgtype.UUID
+		if !libRes.IsAll {
+			if parsed, parseErr := uuid.Parse(libRes.LibraryID); parseErr == nil {
+				libScope = pgtype.UUID{Bytes: parsed, Valid: true}
+			}
+		}
+		visibleIDs, visErr := cfg.CollectionHandler.UserVisibleLibraryIDs(c)
+		if visErr != nil {
+			log.Printf("UserVisibleLibraryIDs failed: %v", visErr)
+			visibleIDs = nil
+		}
+
 		colData := make([]templates.CollectionData, len(collections))
+		colService := cfg.CollectionHandler.CollectionService()
 		for i, col := range collections {
+			isSmart := colService.IsSmartCollection(col.AutoAssignRules)
+			bookCount := 0
+			if isSmart {
+				matches, evalErr := colService.EvaluateSmartCollection(c.Request().Context(),
+					colService.ParseRules(col.AutoAssignRules), services.SmartEvalOptions{
+						LibraryID:  libScope,
+						VisibleIDs: visibleIDs,
+					})
+				if evalErr == nil {
+					bookCount = len(matches)
+				}
+			} else {
+				count, countErr := cfg.Queries.CountCollectionLiveItems(c.Request().Context(), database.CountCollectionLiveItemsParams{
+					CollectionID: pgtype.UUID{Bytes: col.ID.Bytes, Valid: true},
+					LibraryID:    libScope,
+				})
+				if countErr == nil {
+					bookCount = int(count)
+				}
+			}
+
 			colData[i] = templates.CollectionData{
 				ID:          uuid.UUID(col.ID.Bytes).String(),
 				Name:        col.Name,
 				Description: getText(col.Description),
 				Color:       getText(col.Color),
 				Icon:        getText(col.Icon),
+				IsSystem:    col.IsSystemCollection.Bool,
+				IsSmart:     isSmart,
+				BookCount:   bookCount,
 			}
 		}
 
@@ -535,6 +644,47 @@ func registerFrontendRoutes(cfg *Config) {
 		return c.HTML(http.StatusOK, buf.String())
 	})
 
+	// Smart collection rules builder page (the smart editor). User
+	// collections only: system sections keep their hardwired queries.
+	frontendProtected.GET("/collections/:id/rules", func(c *echo.Context) error {
+		user, err := getTemplateUserWithTheme(c, cfg)
+		if err != nil {
+			return renderErrorPage(c, "Error loading user", "user_load_error")
+		}
+		collectionID := c.Param("id")
+		collUUID, err := uuid.Parse(collectionID)
+		if err != nil {
+			return renderErrorPage(c, "Invalid collection ID", "invalid_id")
+		}
+		collection, err := cfg.Queries.GetCollection(c.Request().Context(), pgtype.UUID{Bytes: collUUID, Valid: true})
+		if err != nil {
+			if errors.Is(err, pgx.ErrNoRows) {
+				return renderErrorPage(c, "Collection not found", "not_found")
+			}
+			return renderErrorPage(c, "Error loading collection", "collection_load_error")
+		}
+		if collection.IsSystemCollection.Bool {
+			return renderErrorPage(c, "System collections cannot have rules", "not_allowed")
+		}
+
+		colData := templates.CollectionData{
+			ID:          collectionID,
+			Name:        collection.Name,
+			Description: getText(collection.Description),
+			Color:       getText(collection.Color),
+			Icon:        getText(collection.Icon),
+			IsSystem:    collection.IsSystemCollection.Bool,
+			IsSmart:     cfg.CollectionHandler.CollectionService().IsSmartCollection(collection.AutoAssignRules),
+		}
+
+		var buf bytes.Buffer
+		err = templates.CollectionRules(user, colData).Render(c.Request().Context(), &buf)
+		if err != nil {
+			return err
+		}
+		return c.HTML(http.StatusOK, buf.String())
+	})
+
 	// Collection detail page (works for both system and user collections)
 	frontendProtected.GET("/collections/:id", func(c *echo.Context) error {
 		user, err := getTemplateUserWithTheme(c, cfg)
@@ -562,7 +712,44 @@ func registerFrontendRoutes(cfg *Config) {
 		libRes := resolveLibrary(c, cfg, user.ID)
 		libraryID := libRes.LibraryID
 
-		if collection.QueryType.Valid && collection.QueryType.String != "" {
+		var libScope pgtype.UUID
+		if !libRes.IsAll {
+			if parsed, parseErr := uuid.Parse(libraryID); parseErr == nil {
+				libScope = pgtype.UUID{Bytes: parsed, Valid: true}
+			}
+		}
+		colService := cfg.CollectionHandler.CollectionService()
+		isSmart := colService.IsSmartCollection(collection.AutoAssignRules)
+
+		visibleIDs, visErr := cfg.CollectionHandler.UserVisibleLibraryIDs(c)
+		if visErr != nil {
+			log.Printf("UserVisibleLibraryIDs failed: %v", visErr)
+			visibleIDs = nil
+		}
+
+		if isSmart {
+			// Smart (dynamic) collection: membership is evaluated live —
+			// visible libraries, live items only, any enabled rule matches.
+			matches, evalErr := colService.EvaluateSmartCollection(c.Request().Context(),
+				colService.ParseRules(collection.AutoAssignRules), services.SmartEvalOptions{
+					LibraryID:  libScope,
+					VisibleIDs: visibleIDs,
+				})
+			if evalErr != nil {
+				return renderErrorPage(c, "Error loading books", "books_load_error")
+			}
+			bookCards := make([]handlers.BookInfo, 0, len(matches))
+			for _, item := range matches {
+				itemUUID, _ := uuid.FromBytes(item.ID.Bytes[0:16])
+				bookCards = append(bookCards, handlers.BookInfo{
+					MediaItemID:    itemUUID.String(),
+					Title:          item.Title,
+					Author:         getText(item.Author),
+					CoverImagePath: utils.ResolveMediaURL(item.LibraryID, item.CoverImagePath),
+				})
+			}
+			books = bookCards
+		} else if collection.IsSystemCollection.Bool && collection.QueryType.Valid && collection.QueryType.String != "" && collection.QueryType.String != "filter" {
 			dashboardSvc := services.NewDashboardService(cfg.Queries)
 			sections, secErr := dashboardSvc.GetDashboardSections(c.Request().Context(), userUUID, libRes.LibUUID, 1000, []string{}, []string{})
 			if secErr != nil {
@@ -647,6 +834,8 @@ func registerFrontendRoutes(cfg *Config) {
 			Color:       collection.Color.String,
 			Icon:        collection.Icon.String,
 			IsSystem:    collection.IsSystemCollection.Bool,
+			IsSmart:     isSmart,
+			BookCount:   len(books),
 		}
 
 		var buf bytes.Buffer
@@ -657,6 +846,46 @@ func registerFrontendRoutes(cfg *Config) {
 		return c.HTML(http.StatusOK, buf.String())
 	})
 
+	// Week-widget fragment: the collapsible "This Week" strip re-fetches
+	// itself here (htmx) whenever the library switcher dispatches
+	// week-refresh, carrying the current #library-select value. Same
+	// resolution rules as the dashboard page (family-lens safe).
+	frontendProtected.GET("/dashboard/week-widget", func(c *echo.Context) error {
+		user, err := getTemplateUserWithTheme(c, cfg)
+		if err != nil {
+			return echo.NewHTTPError(http.StatusUnauthorized, "invalid user")
+		}
+		if cfg.StatisticsService == nil {
+			return echo.NewHTTPError(http.StatusServiceUnavailable, "stats unavailable")
+		}
+		libRes := resolveLibrary(c, cfg, user.ID)
+		weekScope := pgtype.UUID{}
+		if !libRes.IsAll {
+			weekScope = libRes.LibUUID
+		}
+		userUUID, _ := uuid.Parse(user.ID)
+		weekSvc, weekErr := cfg.StatisticsService.ThisWeek(c.Request().Context(),
+			uuidToPGType(userUUID), user.Timezone, weekScope)
+		if weekErr != nil {
+			return echo.NewHTTPError(http.StatusInternalServerError, weekErr.Error())
+		}
+		var buf bytes.Buffer
+		err = templates.DashboardWeekWidget(templates.WeekStatsData{
+			WeekMinutes:   weekSvc.WeekMinutes,
+			WeekPages:     weekSvc.WeekPages,
+			WeekSessions:  weekSvc.WeekSessions,
+			WeekBooks:     weekSvc.WeekBooks,
+			PrevMinutes:   weekSvc.PrevMinutes,
+			ActiveToday:   weekSvc.ActiveToday,
+			CurrentStreak: weekSvc.CurrentStreak,
+			LibraryID:     libRes.LibraryID,
+		}).Render(c.Request().Context(), &buf)
+		if err != nil {
+			return err
+		}
+		return c.HTML(http.StatusOK, buf.String())
+	})
+
 	// Custom Section Builder page
 	frontendProtected.GET("/custom-section", func(c *echo.Context) error {
 		user, err := getTemplateUserWithTheme(c, cfg)
@@ -787,14 +1016,22 @@ func registerFrontendRoutes(cfg *Config) {
 		return c.HTML(http.StatusOK, buf.String())
 	})
 
-	// Analytics page
+	// Analytics page → /stats (the rebuilt reading-statistics page;
+	// nobody bookmarks orphan pages twice).
 	frontendProtected.GET("/analytics", func(c *echo.Context) error {
+		return c.Redirect(http.StatusMovedPermanently, "/stats")
+	})
+
+	// Reading statistics page — per-user by default, with library
+	// breakdown; the per-book tier lives on the book detail page and the
+	// dashboard carries the "this week" widget.
+	frontendProtected.GET("/stats", func(c *echo.Context) error {
 		user, err := getTemplateUserWithTheme(c, cfg)
 		if err != nil {
 			return renderErrorPage(c, "Error loading user", "user_load_error")
 		}
 		var buf bytes.Buffer
-		err = templates.Analytics(user).Render(c.Request().Context(), &buf)
+		err = templates.Stats(user).Render(c.Request().Context(), &buf)
 		if err != nil {
 			return err
 		}
@@ -873,6 +1110,11 @@ func registerFrontendRoutes(cfg *Config) {
 				FilePath:     row.FilePath,
 				MissingScans: row.MissingScanCount,
 			}
+			if row.MatchID.Valid {
+				item.MatchID = uuid.UUID(row.MatchID.Bytes).String()
+				item.MatchTitle = row.MatchTitle
+				item.MatchLibraryName = getText(row.MatchLibraryName)
+			}
 			if row.ArchivedAt.Valid {
 				archived := row.ArchivedAt.Time
 				item.ArchivedAt = &archived
@@ -1029,7 +1271,7 @@ func registerFrontendRoutes(cfg *Config) {
 				LibraryName: p.LibraryName,
 				SHA256:      p.FileSha256,
 				SHAShort:    p.FileSha256[:16] + "…",
-				CreatedAt:   p.CreatedAt.Time.Format("Jan 2, 2006"),
+				CreatedAt: p.CreatedAt.Time.In(utils.UserLocation(user.Timezone)).Format("Jan 2, 2006"),
 				Items:       []templates.HashConflictItemData{},
 			}
 
@@ -1212,6 +1454,9 @@ func registerFrontendRoutes(cfg *Config) {
 			FirstName: getText(targetUser.FirstName),
 			LastName:  getText(targetUser.LastName),
 			CreatedAt: targetUser.CreatedAt.Time,
+			// Without this the timezone select rendered UTC selected for
+			// EVERY user — saves landed, the modal just never showed them.
+			Timezone: getText(targetUser.Timezone),
 		}
 
 		// Render modal
@@ -1358,6 +1603,17 @@ func registerFrontendRoutes(cfg *Config) {
 			rating = &userRating
 		}
 
+		// Fetch the user's review (raw markdown; rendered client-side
+		// through the notes pipeline).
+		var review *database.MediaReviews
+		userReview, err := cfg.Queries.GetMediaReview(c.Request().Context(), database.GetMediaReviewParams{
+			MediaItemID: pgMediaUUID,
+			UserID:      pgUserID,
+		})
+		if err == nil {
+			review = &userReview
+		}
+
 		// Fetch collections
 		collections, _ := cfg.Queries.GetCollectionsForBook(c.Request().Context(), pgMediaUUID)
 
@@ -1408,13 +1664,33 @@ func registerFrontendRoutes(cfg *Config) {
 			UserID:      pgUserID,
 		})
 
+		// Per-book reading stats (the viewer's own history card) — nil
+		// keeps the card off the page for untouched books / other users.
+		var bookStats *handlers.BookStatsData
+		if cfg.StatisticsService != nil {
+			if svcStats, serr := cfg.StatisticsService.BookStats(c.Request().Context(),
+				pgUserID, mediaUUID, user.Timezone); serr == nil && svcStats.SessionCount > 0 {
+				bookStats = &handlers.BookStatsData{
+					TotalMinutes: svcStats.TotalMinutes,
+					TotalPages:   svcStats.TotalPages,
+					SessionCount: svcStats.SessionCount,
+					MaxProgress:  svcStats.MaxProgress,
+					Finished:     svcStats.Finished,
+					FirstSession: svcStats.FirstSession,
+					LastSession:  svcStats.LastSession,
+				}
+			}
+		}
+
 		// Assemble response (no field duplication!)
 		detail := handlers.MediaDetail{
 			MediaItems:         mediaItem, // Embedded - ALL fields available
 			FileLocation:       fileLocation,
 			Rating:             rating,
+			Review:             review,
 			Collections:        collections,
 			ReadingProgress:    progress,
+			BookStats:          bookStats,
 			ActiveConflict:     activeConflict,
 			NotesCount:         len(notes),
 			HighlightsCount:    len(highlights),
@@ -1423,7 +1699,10 @@ func registerFrontendRoutes(cfg *Config) {
 
 		// Render template
 		var buf bytes.Buffer
-		err = templates.BookDetail(user, detail, "").Render(c.Request().Context(), &buf)
+		// The deleted-annotations modal states the retention in plain days
+		// (the tunable's user-facing value), never as a settings name.
+		tombstoneDays := cfg.Settings.TombstoneTTL() / (24 * time.Hour)
+		err = templates.BookDetail(user, detail, "", int(tombstoneDays)).Render(c.Request().Context(), &buf)
 		if err != nil {
 			return err
 		}
@@ -1450,6 +1729,7 @@ func (cfg *Config) GetHealth(c *echo.Context) error {
 
 	return c.JSON(http.StatusOK, map[string]interface{}{
 		"status":   "healthy",
+		"version":  version.Version,
 		"database": "connected",
 		"scan": map[string]interface{}{
 			"scan_in_progress": cfg.Worker.HasActiveScans(),

internal/router/helpers.go

@@ -3,8 +3,10 @@ package router
 import (
 	"context"
 	"log"
+	"net/http"
 	"net/url"
 	"os"
+	"sync"
 	"time"
 
 	"bookhoard/internal/database"
@@ -51,13 +53,16 @@ func getTemplateUserWithTheme(c *echo.Context, cfg *Config) (templates.User, err
 	}
 
 	return templates.User{
-		ID:       userID,
-		Email:    userEmail,
-		Username: userUsername,
-		Role:     userRole,
-		Theme:    userTheme,
-		Token:    token,
-		Timezone: userTimezone,
+		ID:        userID,
+		Email:     userEmail,
+		Username:  userUsername,
+		Role:      userRole,
+		Theme:     userTheme,
+		Token:     token,
+		Timezone:  userTimezone,
+		FirstName: getText(userDB.FirstName),
+		LastName:  getText(userDB.LastName),
+		CreatedAt: userDB.CreatedAt.Time,
 	}, nil
 }
 
@@ -102,6 +107,34 @@ type LibraryResolution struct {
 	FirstID   string
 }
 
+// folderStatEntry caches one folder-reachability result.
+type folderStatEntry struct {
+	exists bool
+	at     time.Time
+}
+
+const folderStatTTL = 30 * time.Second
+
+var folderStatCache sync.Map
+
+// folderReachableCached stats a library folder with a short TTL cache:
+// resolveLibrary runs on every SSR render, and a stat per library folder
+// over a network mount adds real latency to each page. The cache trades
+// ~30s of stale online/offline state for snappy renders.
+func folderReachableCached(path string) bool {
+	if v, ok := folderStatCache.Load(path); ok {
+		if e, ok := v.(folderStatEntry); ok && time.Since(e.at) < folderStatTTL {
+			return e.exists
+		}
+	}
+	exists := false
+	if _, err := os.Stat(path); err == nil {
+		exists = true
+	}
+	folderStatCache.Store(path, folderStatEntry{exists: exists, at: time.Now()})
+	return exists
+}
+
 func getText(t pgtype.Text) string {
 	if t.Valid {
 		return t.String
@@ -118,6 +151,15 @@ func resolveLibrary(c *echo.Context, cfg *Config, userUUID string) LibraryResolu
 		log.Printf("GetUserVisibleLibraries failed: %v", err)
 		libraries = []database.GetUserVisibleLibrariesRow{}
 	}
+	visibleSet := make(map[string]bool, len(libraries))
+	for _, lib := range libraries {
+		if !lib.ID.Valid {
+			continue
+		}
+		if id, err := uuid.FromBytes(lib.ID.Bytes[0:16]); err == nil {
+			visibleSet[id.String()] = true
+		}
+	}
 
 	counts, countErr := cfg.Queries.GetVisibleLibraryMediaCounts(c.Request().Context(), uuidToPGType(userU))
 	if countErr != nil {
@@ -143,7 +185,7 @@ func resolveLibrary(c *echo.Context, cfg *Config, userUUID string) LibraryResolu
 		} else {
 			anyFolderExists := false
 			for _, folder := range folders {
-				if _, statErr := os.Stat(folder.FolderPath); statErr == nil {
+				if folderReachableCached(folder.FolderPath) {
 					anyFolderExists = true
 					break
 				}
@@ -189,8 +231,46 @@ func resolveLibrary(c *echo.Context, cfg *Config, userUUID string) LibraryResolu
 		return res
 	}
 
+	// A requested library outside the requester's visible set is not
+	// honored — fall back to the first visible library instead of leaking
+	// hidden-library contents through a hand-typed query param or cookie.
+	if !visibleSet[libraryID] {
+		res.LibraryID = res.FirstID
+		if res.LibraryID != "" {
+			parsed, _ := uuid.Parse(res.LibraryID)
+			res.LibUUID = pgtype.UUID{Bytes: parsed, Valid: true}
+		}
+		return res
+	}
+
 	res.LibraryID = libraryID
 	parsed, _ := uuid.Parse(libraryID)
 	res.LibUUID = pgtype.UUID{Bytes: parsed, Valid: true}
 	return res
 }
+
+// visibleLibraryIDsFor returns the requester's visible-library id set (for
+// membership checks) plus the ids themselves (for SQL ANY() filters).
+func visibleLibraryIDsFor(c *echo.Context, cfg *Config) (map[string]bool, []pgtype.UUID, error) {	userUUIDStr, ok := c.Get("user_id").(string)
+	if !ok {
+		return nil, nil, echo.NewHTTPError(http.StatusUnauthorized, "invalid user")
+	}
+	userU, err := uuid.Parse(userUUIDStr)
+	if err != nil {
+		return nil, nil, echo.NewHTTPError(http.StatusUnauthorized, "invalid user")
+	}
+	libraries, err := cfg.Queries.GetUserVisibleLibraries(c.Request().Context(), uuidToPGType(userU))
+	if err != nil {
+		return nil, nil, err
+	}
+	set := make(map[string]bool, len(libraries))
+	ids := make([]pgtype.UUID, 0, len(libraries))
+	for _, lib := range libraries {
+		if !lib.ID.Valid {
+			continue
+		}
+		set[lib.ID.String()] = true
+		ids = append(ids, lib.ID)
+	}
+	return set, ids, nil
+}

internal/router/media.go

@@ -25,6 +25,13 @@ func registerMediaRoutes(cfg *Config) {
 	protected.PUT("/media-items/:id/rating", cfg.MediaHandler.UpdateMediaRating)
 	protected.DELETE("/media-items/:id/rating", cfg.MediaHandler.DeleteMediaRating)
 
+	// Media review routes (all authenticated users). Raw markdown in,
+	// raw markdown out — rendered only at display sites.
+	protected.POST("/media-items/:id/review", cfg.MediaHandler.UpsertMediaReview)
+	protected.GET("/media-items/:id/review", cfg.MediaHandler.GetMediaReview)
+	protected.PUT("/media-items/:id/review", cfg.MediaHandler.UpsertMediaReview)
+	protected.DELETE("/media-items/:id/review", cfg.MediaHandler.DeleteMediaReview)
+
 	// Progress routes (all authenticated users)
 	protected.GET("/media-items/:id/progress", cfg.MediaHandler.GetMediaReadingProgress)
 	protected.PUT("/media-items/:id/progress", cfg.MediaHandler.UpdateMediaReadingProgress)
@@ -64,6 +71,7 @@ func registerMediaRoutes(cfg *Config) {
 	admin.DELETE("/media-items/:id", cfg.MediaHandler.DeleteMediaItem)
 	admin.POST("/media-items/purge-archived", cfg.MediaHandler.PurgeArchivedMediaItems)
 	admin.POST("/media-items/:id/unarchive", cfg.MediaHandler.UnarchiveMediaItem)
+	admin.POST("/media-items/:id/merge", cfg.MediaHandler.MergeArchivedMediaItem)
 
 	// Shelf management (protected)
 	protected.POST("/devices/:id/shelves", cfg.MediaHandler.AddToShelf)

internal/router/opds.go

@@ -19,6 +19,7 @@ func registerOPDSRoutes(cfg *Config) {
 	opds := e.Group("/opds/devices")
 	opds.Use(cfg.DeviceAuthMiddleware.Authenticate)
 	opds.GET("/:deviceId/catalog", cfg.OPDSHandler.GetDeviceCatalog)
+	opds.GET("/:deviceId/library/:libraryId/catalog", cfg.OPDSHandler.GetLibraryCatalog)
 	opds.GET("/:deviceId/search", cfg.OPDSHandler.SearchDeviceCatalog)
 	opds.GET("/:deviceId/nav", cfg.OPDSHandler.GetDeviceNavigation)
 	opds.GET("/:deviceId/download/:bookId", cfg.OPDSHandler.DownloadBook)

internal/router/router.go

@@ -52,6 +52,8 @@ type Config struct {
 	WSHandler               *handlers.WSHandler
 	ConflictHandler         *handlers.ConflictHandler
 	AnalyticsHandler        *handlers.AnalyticsHandler
+	StatsHandler            *handlers.StatsHandler
+	StatisticsService       *services.StatisticsService
 	QueueHandler            *handlers.QueueHandler
 	CollectionHandler       *handlers.CollectionHandler
 	Worker                  *services.Worker
@@ -69,7 +71,7 @@ type Config struct {
 	LoginTracker            *ratelimit.LoginAttemptTracker
 	ScannerHandler          *handlers.Handler
 	JobsHandler             *handlers.JobsHandler
-	SidecarHandler           *handlers.SidecarHandler
+	SidecarHandler          *handlers.SidecarHandler
 	ReaderHandler           *handlers.ReaderHandler
 	LibraryService          *services.LibraryService
 }
@@ -113,11 +115,41 @@ func createJWTMiddleware(cfg *Config) echo.MiddlewareFunc {
 				return echo.NewHTTPError(http.StatusBadRequest, "invalid user ID in token")
 			}
 
+			// Ghost-session guard: a signature-valid token for a user that
+			// no longer exists must not authenticate (deleted users kept
+			// full access until token expiry before this check). A
+			// primary-key lookup per request — instant revocation, no TTL
+			// semantics; the guard also covers the SSR groups that used to
+			// chain ensureUserExistsMiddleware. The fetched row also feeds
+			// the context stub: the user's timezone must travel with every
+			// request so server-side time rendering converts per-user.
+			liveUser, exists := fetchLiveUser(cfg, userUUID)
+			if !exists {
+				log.Printf("Ghost session rejected: user %s no longer exists", userIDStr)
+				c.SetCookie(&http.Cookie{
+					Name:     "token",
+					Value:    "",
+					Expires:  time.Now().Add(-24 * time.Hour),
+					Path:     "/",
+					HttpOnly: true,
+					SameSite: http.SameSiteLaxMode,
+				})
+				if wantsHTML(c.Request().Header) {
+					return c.Redirect(http.StatusFound, "/login?session=invalid")
+				}
+				// Non-nil error is REQUIRED: returning c.JSON's nil would
+				// let the chain continue into handlers whose c.Get("user")
+				// assertion panics on the never-set user.
+				return echo.NewHTTPError(http.StatusUnauthorized,
+					"user_not_found: this account no longer exists; please log in again")
+			}
+
 			c.Set("user", database.Users{
 				ID:       pgtype.UUID{Bytes: userUUID, Valid: true},
 				Email:    claims["user_email"].(string),
 				Username: claims["user_username"].(string),
 				Role:     claims["user_role"].(string),
+				Timezone: liveUser.Timezone,
 			})
 			return nil
 		},
@@ -138,43 +170,19 @@ func createJWTMiddleware(cfg *Config) echo.MiddlewareFunc {
 	})
 }
 
-// ensureUserExistsMiddleware checks if the authenticated user still exists in the database
-func ensureUserExistsMiddleware(cfg *Config) echo.MiddlewareFunc {
-	return func(next echo.HandlerFunc) echo.HandlerFunc {
-		return func(c *echo.Context) error {
-			userIDStr, ok := c.Get("user_id").(string)
-			if !ok {
-				return next(c)
-			}
+// userExists checks the users table for the token's claimed user. Runs on
+// every authenticated request: a primary-key lookup, cheap at this scale,
+// and it makes deletion revocable the moment it happens.
+func userExists(cfg *Config, id uuid.UUID) bool {
+	_, err := cfg.Queries.GetUser(context.Background(), uuidToPGType(id))
+	return err == nil
+}
 
-			userUUID, err := uuid.Parse(userIDStr)
-			if err != nil {
-				log.Printf("Invalid UUID in user existence check: %v", err)
-				return next(c)
-			}
-
-			// Check if user exists in database
-			_, err = cfg.Queries.GetUser(c.Request().Context(), uuidToPGType(userUUID))
-			if err != nil {
-				log.Printf("User not found in database: %s", userIDStr)
-
-				// Clear invalid cookie
-				c.SetCookie(&http.Cookie{
-					Name:     "token",
-					Value:    "",
-					Expires:  time.Now().Add(-24 * time.Hour),
-					Path:     "/",
-					HttpOnly: true,
-					SameSite: http.SameSiteLaxMode,
-				})
-
-				// Redirect to login with session=invalid
-				return c.Redirect(http.StatusFound, "/login?session=invalid")
-			}
-
-			return next(c)
-		}
-	}
+// fetchLiveUser loads the full user row for the JWT stub — the ghost-session
+// guard and the timezone travel together on this one per-request lookup.
+func fetchLiveUser(cfg *Config, id uuid.UUID) (database.GetUserRow, bool) {
+	u, err := cfg.Queries.GetUser(context.Background(), uuidToPGType(id))
+	return u, err == nil
 }
 
 // wantsHTML determines if the request expects HTML response
@@ -255,6 +263,21 @@ func RegisterRoutes(cfg *Config) *handlers.Handler {
 	registerWebSocketRoutes(cfg)
 	registerFrontendRoutes(cfg)
 	registerDocumentationRoutes(cfg)
+
+	// Static bundles are served unhashed (reader.js, index.js), so the
+	// browser must revalidate on every load — with no Cache-Control it
+	// fell back to heuristic caching and served stale bundles for hours
+	// after a deploy (user-visible: fixed web bugs "not fixed"). no-cache
+	// still allows cheap If-Modified-Since 304 revalidation.
+	e.Pre(func(next echo.HandlerFunc) echo.HandlerFunc {
+		return func(c *echo.Context) error {
+			if strings.HasPrefix(c.Request().URL.Path, "/static/") {
+				c.Response().Header().Set(echo.HeaderCacheControl, "no-cache")
+			}
+			return next(c)
+		}
+	})
+
 	e.Static("/static", "web/static")
 
 	// Catch-all 404 handler - must be last
@@ -309,9 +332,9 @@ func RegisterRoutes(cfg *Config) *handlers.Handler {
 	// Register progress routes with actual handler
 	registerProgressRoutes(cfg, scannerHandler)
 
-	// Register scanner routes (admin only)
+	// Register scanner routes (admin only, plus the sitewide summary)
 	admin := protected.Group("", handlers.AdminMiddleware)
-	registerScannerRoutes(admin, scannerHandler)
+	registerScannerRoutes(protected, admin, scannerHandler)
 
 	// Hash conflict routes (admin only)
 	admin.GET("/api/admin/hash-conflicts", cfg.HashConflictsHandler.ListHashConflicts)

internal/router/scanner.go

@@ -7,12 +7,18 @@ import (
 )
 
 // registerScannerRoutes registers all scanner-related endpoints
-func registerScannerRoutes(admin *echo.Group, h *handlers.Handler) {
+func registerScannerRoutes(protected, admin *echo.Group, h *handlers.Handler) {
+	// Any authenticated user: the sitewide sidebar indicator needs to
+	// know a scan is running after a page refresh (websocket events
+	// only reach pages that were already open).
+	protected.GET("/scanner/active-summary", h.GetScanSummary)
+
 	// Scanner routes (admin only)
 	admin.POST("/scanner/scan", h.ScanLibrary)
 	admin.POST("/scanner/start", h.StartScanner)
 	admin.POST("/scanner/stop", h.StopScanner)
 	admin.GET("/scanner/status/:jobId", h.GetScanStatus)
+	admin.GET("/scanner/active", h.GetActiveScans)
 
 	// Watch mode routes (admin only)
 	admin.POST("/scanner/watch/start", h.StartWatchMode)

internal/router/sync.go

@@ -28,6 +28,11 @@ func registerSyncRoutes(cfg *Config) {
 	koreaderSync.GET("/metadata/:uuid", cfg.DeviceAuthMiddleware.Authenticate(cfg.KOReaderHandler.GetMetadata))
 	koreaderSync.GET("/library", cfg.DeviceAuthMiddleware.Authenticate(cfg.KOReaderHandler.GetLibrary))
 	koreaderSync.POST("/bookmarks", cfg.DeviceAuthMiddleware.Authenticate(cfg.KOReaderHandler.SyncBookmarks))
+	koreaderSync.GET("/rating", cfg.DeviceAuthMiddleware.Authenticate(cfg.KOReaderHandler.GetKOReaderRating))
+	koreaderSync.POST("/rating", cfg.DeviceAuthMiddleware.Authenticate(cfg.KOReaderHandler.SetKOReaderRating))
+	koreaderSync.GET("/review", cfg.DeviceAuthMiddleware.Authenticate(cfg.KOReaderHandler.GetKOReaderReview))
+	koreaderSync.POST("/review", cfg.DeviceAuthMiddleware.Authenticate(cfg.KOReaderHandler.SetKOReaderReview))
+	koreaderSync.POST("/stats", cfg.DeviceAuthMiddleware.Authenticate(cfg.KOReaderHandler.PushKOReaderStats))
 
 	// Kobo sync routes (device authentication required)
 	// Kobo devices use URL path: /api/sync/kobo/{token}/markup

internal/services/collection_service.go

@@ -4,13 +4,19 @@ import (
 	"bookhoard/internal/database"
 	"context"
 	"encoding/json"
+	"errors"
 	"fmt"
 	"strings"
 
 	"github.com/google/uuid"
+	"github.com/jackc/pgx/v5"
+	"github.com/jackc/pgx/v5/pgconn"
 	"github.com/jackc/pgx/v5/pgtype"
 )
 
+// ErrCollectionNameTaken: the user already has a collection with this name.
+var ErrCollectionNameTaken = errors.New("collection name already exists")
+
 // Rule represents an auto-assign rule for collections
 type Rule struct {
 	ID       string `json:"id"`
@@ -18,8 +24,30 @@ type Rule struct {
 	Operator string `json:"operator"` // "equals", "contains", "starts_with", "ends_with", "greater_than", "less_than"
 	Value    string `json:"value"`
 	Priority int    `json:"priority"` // 1-10, higher values take precedence
+	// Enabled gates the rule in the LIVE evaluation used by smart
+	// collections; absent (JSON omitempty) means enabled — rules written
+	// before the field existed keep matching.
+	Enabled *bool `json:"enabled,omitempty"`
 }
 
+// Known rule fields and operators — the rules builder UI and the
+// persisted JSONB documents must agree with this vocabulary.
+var ruleFields = map[string]bool{
+	"genre": true, "series": true, "author": true, "language": true,
+	"publisher": true, "copyright_year": true, "tags": true,
+}
+
+var ruleOperators = map[string]bool{
+	"equals": true, "not_equals": true, "contains": true, "not_contains": true,
+	"starts_with": true, "ends_with": true, "greater_than": true, "less_than": true,
+}
+
+// RuleValidationError reports a rule payload the evaluator could never
+// honor (unknown field/operator, empty value).
+type RuleValidationError struct{ Msg string }
+
+func (e *RuleValidationError) Error() string { return e.Msg }
+
 // RuleEvaluation represents the result of evaluating a rule
 type RuleEvaluation struct {
 	RuleID     string  `json:"rule_id"`
@@ -72,7 +100,13 @@ func (s *CollectionService) CreateCollection(ctx context.Context, userID uuid.UU
 	})
 
 	if err != nil {
-		return database.Collections{}, fmt.Errorf("failed to create collection: %v", err)
+		// Duplicate name (UNIQUE(user_id, name)) is a client error, not a
+		// server failure: surface it as 409 so callers can recover.
+		var pgErr *pgconn.PgError
+		if errors.As(err, &pgErr) && pgErr.Code == "23505" {
+			return database.Collections{}, ErrCollectionNameTaken
+		}
+		return database.Collections{}, fmt.Errorf("failed to create collection: %w", err)
 	}
 
 	return collection, nil
@@ -160,9 +194,24 @@ func (s *CollectionService) UpdateCollection(ctx context.Context, collectionID u
 
 // DeleteCollection deletes a collection
 func (s *CollectionService) DeleteCollection(ctx context.Context, collectionID uuid.UUID) error {
-	err := s.db.DeleteCollection(ctx, pgtype.UUID{Bytes: collectionID, Valid: true})
+	// System collections (the 5 dashboard sections) are PERMANENT: a
+	// delete tombstones the row (invisible everywhere, restorable with
+	// the same id) instead of destroying it and every reference to it.
+	row, err := s.db.GetCollection(ctx, pgtype.UUID{Bytes: collectionID, Valid: true})
 	if err != nil {
-		return fmt.Errorf("failed to delete collection: %v", err)
+		if errors.Is(err, pgx.ErrNoRows) {
+			return nil // already gone: keep delete idempotent
+		}
+		return fmt.Errorf("failed to fetch collection: %w", err)
+	}
+
+	if row.IsSystemCollection.Bool {
+		return s.db.TombstoneSystemCollection(ctx, pgtype.UUID{Bytes: collectionID, Valid: true})
+	}
+
+	err = s.db.DeleteCollection(ctx, pgtype.UUID{Bytes: collectionID, Valid: true})
+	if err != nil {
+		return fmt.Errorf("failed to delete collection: %w", err)
 	}
 
 	return nil
@@ -217,6 +266,248 @@ func (s *CollectionService) GetBookCollections(ctx context.Context, mediaItemID
 	return collections, nil
 }
 
+// ParseRules decodes a collection's auto_assign_rules JSONB into typed
+// rules. "null", empty, and malformed docs mean "no rules".
+func (s *CollectionService) ParseRules(raw []byte) []Rule {
+	if len(raw) == 0 {
+		return nil
+	}
+	var rules []Rule
+	if err := json.Unmarshal(raw, &rules); err != nil {
+		return nil
+	}
+	return rules
+}
+
+// IsSmartCollection derives the collection type: a non-empty ruleset
+// makes it SMART (live-matched), an empty/absent ruleset makes it STATIC
+// (stored collection_items links).
+func (s *CollectionService) IsSmartCollection(raw []byte) bool {
+	return len(s.ParseRules(raw)) > 0
+}
+
+// EnabledRules filters a ruleset down to the rules that participate in
+// live evaluation (absent enabled = enabled for backward compatibility).
+func (s *CollectionService) EnabledRules(rules []Rule) []Rule {
+	enabled := make([]Rule, 0, len(rules))
+	for _, rule := range rules {
+		if rule.Enabled == nil || *rule.Enabled {
+			enabled = append(enabled, rule)
+		}
+	}
+	return enabled
+}
+
+// validateRule checks a rule payload the evaluator will have to honor.
+func (s *CollectionService) validateRule(rule Rule) error {
+	if !ruleFields[rule.Field] {
+		return &RuleValidationError{Msg: "unknown rule field: " + rule.Field}
+	}
+	if !ruleOperators[rule.Operator] {
+		return &RuleValidationError{Msg: "unknown rule operator: " + rule.Operator}
+	}
+	if strings.TrimSpace(rule.Value) == "" {
+		return &RuleValidationError{Msg: "rule value is required"}
+	}
+	if rule.Priority < 0 || rule.Priority > 10 {
+		return &RuleValidationError{Msg: "priority must be between 0 and 10"}
+	}
+	return nil
+}
+
+// AddRule appends a rule to the collection's ruleset, generating an id
+// when the caller did not supply one. Adding the first rule CONVERTS a
+// static collection to smart (type is derived from rules presence).
+func (s *CollectionService) AddRule(ctx context.Context, collectionID uuid.UUID, rule Rule) (database.Collections, Rule, error) {
+	if err := s.validateRule(rule); err != nil {
+		return database.Collections{}, Rule{}, err
+	}
+
+	collection, err := s.GetCollection(ctx, collectionID)
+	if err != nil {
+		return database.Collections{}, Rule{}, err
+	}
+
+	rules := s.ParseRules(collection.AutoAssignRules)
+	if rule.ID == "" {
+		rule.ID = uuid.NewString()
+	}
+	rules = append(rules, rule)
+
+	rulesJSON, marshalErr := json.Marshal(rules)
+	if marshalErr != nil {
+		return database.Collections{}, Rule{}, fmt.Errorf("failed to marshal rules: %w", marshalErr)
+	}
+
+	updated, err := s.db.UpdateCollectionRulesJSON(ctx, database.UpdateCollectionRulesJSONParams{
+		ID:              pgtype.UUID{Bytes: collectionID, Valid: true},
+		AutoAssignRules: rulesJSON,
+	})
+	if err != nil {
+		return database.Collections{}, Rule{}, fmt.Errorf("failed to save rules: %w", err)
+	}
+	return updated, rule, nil
+}
+
+// SetRuleEnabled flips a single rule's enabled flag in place.
+func (s *CollectionService) SetRuleEnabled(ctx context.Context, collectionID uuid.UUID, ruleID string, enabled bool) (database.Collections, error) {
+	collection, err := s.GetCollection(ctx, collectionID)
+	if err != nil {
+		return database.Collections{}, err
+	}
+	rules := s.ParseRules(collection.AutoAssignRules)
+	found := false
+	for i := range rules {
+		if rules[i].ID == ruleID {
+			rules[i].Enabled = &enabled
+			found = true
+			break
+		}
+	}
+	if !found {
+		return database.Collections{}, fmt.Errorf("rule not found: %s", ruleID)
+	}
+
+	rulesJSON, marshalErr := json.Marshal(rules)
+	if marshalErr != nil {
+		return database.Collections{}, fmt.Errorf("failed to marshal rules: %w", marshalErr)
+	}
+
+	updated, err := s.db.UpdateCollectionRulesJSON(ctx, database.UpdateCollectionRulesJSONParams{
+		ID:              pgtype.UUID{Bytes: collectionID, Valid: true},
+		AutoAssignRules: rulesJSON,
+	})
+	if err != nil {
+		return database.Collections{}, fmt.Errorf("failed to save rules: %w", err)
+	}
+	return updated, nil
+}
+
+// RemoveRule deletes a single rule from the ruleset. Removing the LAST
+// rule converts the collection back to static (type is derived).
+func (s *CollectionService) RemoveRule(ctx context.Context, collectionID uuid.UUID, ruleID string) (database.Collections, error) {
+	collection, err := s.GetCollection(ctx, collectionID)
+	if err != nil {
+		return database.Collections{}, err
+	}
+	rules := s.ParseRules(collection.AutoAssignRules)
+	kept := make([]Rule, 0, len(rules))
+	found := false
+	for _, rule := range rules {
+		if rule.ID == ruleID {
+			found = true
+			continue
+		}
+		kept = append(kept, rule)
+	}
+	if !found {
+		return database.Collections{}, fmt.Errorf("rule not found: %s", ruleID)
+	}
+
+	rulesJSON, marshalErr := json.Marshal(kept)
+	if marshalErr != nil {
+		return database.Collections{}, fmt.Errorf("failed to marshal rules: %w", marshalErr)
+	}
+
+	updated, err := s.db.UpdateCollectionRulesJSON(ctx, database.UpdateCollectionRulesJSONParams{
+		ID:              pgtype.UUID{Bytes: collectionID, Valid: true},
+		AutoAssignRules: rulesJSON,
+	})
+	if err != nil {
+		return database.Collections{}, fmt.Errorf("failed to save rules: %w", err)
+	}
+	return updated, nil
+}
+
+// SmartEvalOptions scopes a smart collection's live evaluation.
+type SmartEvalOptions struct {
+	// LibraryID, when valid, restricts matching to one library (the
+	// detail page's library switcher).
+	LibraryID pgtype.UUID
+	// VisibleIDs is the requesting user's visible-library set (family
+	// lens). Empty means no visible-library filter.
+	VisibleIDs []pgtype.UUID
+}
+
+// EvaluateSmartCollection resolves a smart collection's membership LIVE:
+// every visible live book matched by at least one enabled rule is in.
+// No stored links are consulted — "truly dynamic," always current.
+func (s *CollectionService) EvaluateSmartCollection(ctx context.Context, rules []Rule, opts SmartEvalOptions) ([]database.MediaItems, error) {
+	enabled := s.EnabledRules(rules)
+	if len(enabled) == 0 {
+		return []database.MediaItems{}, nil
+	}
+
+	var visibleArg []pgtype.UUID
+	if len(opts.VisibleIDs) > 0 {
+		visibleArg = opts.VisibleIDs
+	}
+	items, err := s.db.GetVisibleLiveMediaForRules(ctx, database.GetVisibleLiveMediaForRulesParams{
+		LibraryID:         opts.LibraryID,
+		VisibleLibraryIds: visibleArg,
+	})
+	if err != nil {
+		return nil, fmt.Errorf("failed to load candidate books: %w", err)
+	}
+
+	matches := make([]database.MediaItems, 0, len(items))
+	for _, item := range items {
+		if s.mediaItemMatchesAnyRule(item, enabled) {
+			matches = append(matches, item)
+		}
+	}
+	return matches, nil
+}
+
+func (s *CollectionService) mediaItemMatchesAnyRule(item database.MediaItems, rules []Rule) bool {
+	for _, rule := range rules {
+		if s.mediaItemMatchesRule(item, rule) {
+			return true
+		}
+	}
+	return false
+}
+
+func (s *CollectionService) mediaItemMatchesRule(item database.MediaItems, rule Rule) bool {
+	if rule.Enabled != nil && !*rule.Enabled {
+		return false
+	}
+
+	var fieldValue string
+	switch rule.Field {
+	case "genre":
+		if item.Genre.Valid {
+			fieldValue = item.Genre.String
+		}
+	case "series":
+		if item.Series.Valid {
+			fieldValue = item.Series.String
+		}
+	case "author":
+		if item.Author.Valid {
+			fieldValue = item.Author.String
+		}
+	case "language":
+		if item.Language.Valid {
+			fieldValue = item.Language.String
+		}
+	case "publisher":
+		if item.Publisher.Valid {
+			fieldValue = item.Publisher.String
+		}
+	case "copyright_year":
+		if item.CopyrightYear.Valid {
+			fieldValue = fmt.Sprintf("%d", item.CopyrightYear.Int32)
+		}
+	case "tags":
+		if len(item.Tags) > 0 {
+			fieldValue = strings.Join(item.Tags, ", ")
+		}
+	}
+
+	return s.evaluateRule(fieldValue, rule.Operator, rule.Value)
+}
+
 // EvaluateRules evaluates auto-assign rules for a media item
 func (s *CollectionService) EvaluateRules(mediaItem database.ListMediaItemsRow, rules []Rule) []RuleEvaluation {
 	var evaluations []RuleEvaluation
@@ -233,6 +524,11 @@ func (s *CollectionService) EvaluateRules(mediaItem database.ListMediaItemsRow,
 	}
 
 	for _, rule := range sortedRules {
+		// Disabled rules never match (kept for context in the UI only).
+		if rule.Enabled != nil && !*rule.Enabled {
+			evaluations = append(evaluations, RuleEvaluation{RuleID: rule.ID, Matches: false})
+			continue
+		}
 		eval := RuleEvaluation{
 			RuleID:  rule.ID,
 			Matches: false,

internal/services/dashboard_service.go

@@ -5,9 +5,11 @@ import (
 	"bookhoard/internal/utils"
 	"context"
 	"encoding/json"
+	"errors"
 	"fmt"
 
 	"github.com/google/uuid"
+	"github.com/jackc/pgx/v5"
 	"github.com/jackc/pgx/v5/pgtype"
 )
 
@@ -376,6 +378,22 @@ func (s *DashboardService) getUserCollectionItems(ctx context.Context, coll data
 }
 
 func (s *DashboardService) GetDashboardPreferences(ctx context.Context, userID uuid.UUID, libraryID pgtype.UUID) (database.UserDashboardPreferences, error) {
+	// Absent library = the global (All Libraries) scope: a separate
+	// one-row-per-user table, so an accidental per-library write can never
+	// masquerade as global.
+	if !libraryID.Valid {
+		g, err := s.db.GetGlobalDashboardPreferences(ctx, pgtype.UUID{Bytes: userID, Valid: true})
+		if err != nil {
+			return database.UserDashboardPreferences{}, err
+		}
+		return database.UserDashboardPreferences{
+			UserID:            g.UserID,
+			HiddenCollections: g.HiddenCollections,
+			CollectionOrder:   g.CollectionOrder,
+			ItemsPerSection:   g.ItemsPerSection,
+			UpdatedAt:         g.UpdatedAt,
+		}, nil
+	}
 	return s.db.GetDashboardPreferences(ctx, database.GetDashboardPreferencesParams{
 		UserID:    pgtype.UUID{Bytes: userID, Valid: true},
 		LibraryID: libraryID,
@@ -383,6 +401,24 @@ func (s *DashboardService) GetDashboardPreferences(ctx context.Context, userID u
 }
 
 func (s *DashboardService) UpsertDashboardPreferences(ctx context.Context, params database.UpsertDashboardPreferencesParams) (database.UserDashboardPreferences, error) {
+	if !params.LibraryID.Valid {
+		g, err := s.db.UpsertGlobalDashboardPreferences(ctx, database.UpsertGlobalDashboardPreferencesParams{
+			UserID:            params.UserID,
+			HiddenCollections: params.HiddenCollections,
+			CollectionOrder:   params.CollectionOrder,
+			ItemsPerSection:   params.ItemsPerSection,
+		})
+		if err != nil {
+			return database.UserDashboardPreferences{}, err
+		}
+		return database.UserDashboardPreferences{
+			UserID:            g.UserID,
+			HiddenCollections: g.HiddenCollections,
+			CollectionOrder:   g.CollectionOrder,
+			ItemsPerSection:   g.ItemsPerSection,
+			UpdatedAt:         g.UpdatedAt,
+		}, nil
+	}
 	return s.db.UpsertDashboardPreferences(ctx, params)
 }
 
@@ -430,34 +466,50 @@ func (s *DashboardService) RestoreSystemCollection(ctx context.Context, userID u
 		return fmt.Errorf("unknown collection: %s", collectionName)
 	}
 
-	if resetType == "keep_books" {
-		return s.db.ResetSystemCollectionMetadata(ctx, database.ResetSystemCollectionMetadataParams{
-			UserID:      pgtype.UUID{Bytes: userID, Valid: true},
-			Name:        collectionName,
-			Description: pgtype.Text{String: meta.Description, Valid: true},
-			Icon:        pgtype.Text{String: meta.Icon, Valid: true},
-			Color:       pgtype.Text{String: meta.Color, Valid: true},
-			Priority:    pgtype.Int4{Int32: meta.Priority, Valid: true},
-		})
-	}
-
-	err := s.db.DeleteUserSystemCollection(ctx, database.DeleteUserSystemCollectionParams{
-		UserID: pgtype.UUID{Bytes: userID, Valid: true},
-		Name:   collectionName,
+	// System collections are PERMANENT rows identified by the stable
+	// (user_id, query_type) pair — restore never deletes or re-creates,
+	// so the row id (and every reference to it: device shelf mappings,
+	// dashboard order/hidden prefs, /collections/{id} links) never churns.
+	// Resolution includes tombstoned rows: restoring a deleted section
+	// un-deletes the exact same row.
+	row, err := s.db.GetSystemCollectionByQueryType(ctx, database.GetSystemCollectionByQueryTypeParams{
+		UserID:    pgtype.UUID{Bytes: userID, Valid: true},
+		QueryType: pgtype.Text{String: meta.QueryType, Valid: true},
 	})
-	if err != nil {
+	if err != nil && !errors.Is(err, pgx.ErrNoRows) {
 		return err
 	}
 
-	_, err = s.db.CreateSystemCollection(ctx, database.CreateSystemCollectionParams{
-		UserID:          pgtype.UUID{Bytes: userID, Valid: true},
-		Name:            collectionName,
-		Description:     pgtype.Text{String: meta.Description, Valid: true},
-		Icon:            pgtype.Text{String: meta.Icon, Valid: true},
-		Color:           pgtype.Text{String: meta.Color, Valid: true},
-		ShowOnDashboard: pgtype.Bool{Bool: true, Valid: true},
-		QueryType:       pgtype.Text{String: meta.QueryType, Valid: true},
-		Priority:        pgtype.Int4{Int32: meta.Priority, Valid: true},
+	if errors.Is(err, pgx.ErrNoRows) {
+		// Provision: the only path that mints a system-collection row.
+		_, cerr := s.db.CreateSystemCollection(ctx, database.CreateSystemCollectionParams{
+			UserID:          pgtype.UUID{Bytes: userID, Valid: true},
+			Name:            collectionName,
+			Description:     pgtype.Text{String: meta.Description, Valid: true},
+			Icon:            pgtype.Text{String: meta.Icon, Valid: true},
+			Color:           pgtype.Text{String: meta.Color, Valid: true},
+			ShowOnDashboard: pgtype.Bool{Bool: true, Valid: true},
+			QueryType:       pgtype.Text{String: meta.QueryType, Valid: true},
+			Priority:        pgtype.Int4{Int32: meta.Priority, Valid: true},
+		})
+		return cerr
+	}
+
+	// "full": clear item assignments (a fresh section has none) and reset
+	// everything, IN PLACE. "keep_books": metadata-only, in place. Both
+	// un-tombstone, so a deleted section comes back as the same row.
+	if resetType != "keep_books" {
+		if err := s.db.ClearCollectionItems(ctx, row.ID); err != nil {
+			return err
+		}
+	}
+	_, err = s.db.RestoreSystemCollectionRow(ctx, database.RestoreSystemCollectionRowParams{
+		ID:          row.ID,
+		Name:        collectionName,
+		Description: pgtype.Text{String: meta.Description, Valid: true},
+		Icon:        pgtype.Text{String: meta.Icon, Valid: true},
+		Color:       pgtype.Text{String: meta.Color, Valid: true},
+		Priority:    pgtype.Int4{Int32: meta.Priority, Valid: true},
 	})
 	return err
 }

internal/services/library_service.go

@@ -30,7 +30,7 @@ const (
 )
 
 var AllowedExtensions = map[string][]string{
-	LibraryTypeEbooks: {".epub", ".pdf", ".mobi", ".azw", ".azw3", ".txt", ".rtf", ".doc", ".docx", ".lit", ".fb2", ".pdb"},
+	LibraryTypeEbooks: {".epub", ".pdf", ".mobi", ".azw", ".azw3", ".txt", ".rtf", ".docx", ".fb2", ".pdb"},
 	LibraryTypeComics: {".cbz", ".cbr", ".cb7", ".cbt", ".epub", ".pdf"},
 	LibraryTypeManga:  {".cbz", ".cbr", ".epub", ".pdf", ".png", ".jpg", ".jpeg", ".gif", ".bmp", ".webp", ".avif", ".tiff", ".tif"},
 }
@@ -59,9 +59,7 @@ var MimeTypes = map[string]string{
 	".azw3": "application/vnd.amazon.ebook",
 	".txt":  "text/plain",
 	".rtf":  "application/rtf",
-	".doc":  "application/msword",
 	".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
-	".lit":  "application/x-msreader",
 	".fb2":  "application/x-fictionbook+xml",
 	".pdb":  "application/vnd.palm",
 }
@@ -301,6 +299,13 @@ func (s *LibraryService) SyncAllowedExtensions(ctx context.Context) {
 }
 
 func (s *LibraryService) ResolveMediaPath(ctx context.Context, libraryID pgtype.UUID, relativePath string) (string, error) {
+	// Typed-nil interface guard: a nil *LibraryService held in an
+	// interface passes `!= nil` checks at call sites; degrade instead
+	// of panicking (kobo markup 500s were exactly this path).
+	if s == nil || s.db == nil {
+		return "", fmt.Errorf("library service not configured")
+	}
+
 	// Get library folders for this library
 	folders, err := s.db.GetLibraryFolders(ctx, libraryID)
 	if err != nil || len(folders) == 0 {