feat: redesign notifications settings with per-category in-app/push table

- Add notify_new_chapters_push field to AppUser, PATCH /api/profile, and profile loader
- Fix bell panel to reload notifications on every open (not just once on mount)
- Replace flat in-app + push toggles with structured category table (Category | In-app | Push)
- Add browser push master subscribe/unsubscribe row above the table
- Push column toggle disabled until browser is subscribed; shows — when unsupported/denied
- Update Notifications row hint to summarise active channels (In-app · Push / Off)

.gitea/workflows/ci.yaml

@@ -2,11 +2,8 @@ name: CI
 
 on:
   push:
-    paths:
-      - "backend/**"
-      - "ui/**"
-      - ".gitea/workflows/ci.yaml"
-  pull_request:
+    tags-ignore:
+      - "v*"
     paths:
       - "backend/**"
       - "ui/**"
@@ -66,6 +63,9 @@ jobs:
       - name: Install dependencies
         run: npm ci
 
+      - name: Check Paraglide codegen is up to date
+        run: npm run paraglide && git diff --exit-code src/lib/paraglide/
+
       - name: Type check
         run: npm run check
 

.gitea/workflows/release.yaml

@@ -55,24 +55,122 @@ jobs:
       - name: Build
         run: npm run build
 
-  # ── docker: backend ───────────────────────────────────────────────────────────
-  docker-backend:
-    name: Docker / backend
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v3
+        with:
+          name: ui-build
+          path: ui/build
+          retention-days: 1
+
+  # ── ui: source map upload ─────────────────────────────────────────────────────
+  # Commented out — re-enable when GlitchTip source map uploads are needed again.
+  #
+  # upload-sourcemaps:
+  #   name: Upload source maps
+  #   runs-on: ubuntu-latest
+  #   needs: [check-ui]
+  #   steps:
+  #     - name: Compute release version (strip leading v)
+  #       id: ver
+  #       run: |
+  #         V="${{ gitea.ref_name }}"
+  #         echo "version=${V#v}" >> "$GITHUB_OUTPUT"
+  #
+  #     - name: Download build artifacts
+  #       uses: actions/download-artifact@v3
+  #       with:
+  #         name: ui-build
+  #         path: build
+  #
+  #     - name: Install sentry-cli
+  #       run: npm install -g @sentry/cli
+  #
+  #     - name: Inject debug IDs into build artifacts
+  #       run: sentry-cli sourcemaps inject ./build
+  #       env:
+  #         SENTRY_URL: https://errors.libnovel.cc/
+  #         SENTRY_AUTH_TOKEN: ${{ secrets.GLITCHTIP_AUTH_TOKEN }}
+  #         SENTRY_ORG: libnovel
+  #         SENTRY_PROJECT: ui
+  #
+  #     - name: Upload injected build (for docker-ui)
+  #       uses: actions/upload-artifact@v3
+  #       with:
+  #         name: ui-build-injected
+  #         path: build
+  #         retention-days: 1
+  #
+  #     - name: Create GlitchTip release
+  #       run: sentry-cli releases new ${{ steps.ver.outputs.version }}
+  #       env:
+  #         SENTRY_URL: https://errors.libnovel.cc/
+  #         SENTRY_AUTH_TOKEN: ${{ secrets.GLITCHTIP_AUTH_TOKEN }}
+  #         SENTRY_ORG: libnovel
+  #         SENTRY_PROJECT: ui
+  #
+  #     - name: Upload source maps to GlitchTip
+  #       run: sentry-cli sourcemaps upload ./build --release ${{ steps.ver.outputs.version }}
+  #       env:
+  #         SENTRY_URL: https://errors.libnovel.cc/
+  #         SENTRY_AUTH_TOKEN: ${{ secrets.GLITCHTIP_AUTH_TOKEN }}
+  #         SENTRY_ORG: libnovel
+  #         SENTRY_PROJECT: ui
+  #
+  #     - name: Finalize GlitchTip release
+  #       run: sentry-cli releases finalize ${{ steps.ver.outputs.version }}
+  #       env:
+  #         SENTRY_URL: https://errors.libnovel.cc/
+  #         SENTRY_AUTH_TOKEN: ${{ secrets.GLITCHTIP_AUTH_TOKEN }}
+  #         SENTRY_ORG: libnovel
+  #         SENTRY_PROJECT: ui
+  #
+  #     - name: Prune old GlitchTip releases (keep latest 10)
+  #       run: |
+  #         set -euo pipefail
+  #         KEEP=10
+  #         OLD=$(curl -sf \
+  #           -H "Authorization: Bearer $SENTRY_AUTH_TOKEN" \
+  #           "$SENTRY_URL/api/0/organizations/$SENTRY_ORG/releases/?project=$SENTRY_PROJECT&per_page=100" \
+  #           | python3 -c "
+  #         import sys, json
+  #         releases = json.load(sys.stdin)
+  #         for r in releases[$KEEP:]:
+  #             print(r['version'])
+  #         " KEEP=$KEEP)
+  #         for ver in $OLD; do
+  #           echo "Deleting old release: $ver"
+  #           sentry-cli releases delete "$ver" || true
+  #         done
+  #       env:
+  #         SENTRY_URL: https://errors.libnovel.cc
+  #         SENTRY_AUTH_TOKEN: ${{ secrets.GLITCHTIP_AUTH_TOKEN }}
+  #         SENTRY_ORG: libnovel
+  #         SENTRY_PROJECT: ui
+
+  # ── docker: all images in one job (single login) ──────────────────────────────
+  # backend, runner, ui, and caddy are built sequentially in one job so Docker
+  # Hub only needs to be authenticated once. This also eliminates 3 redundant
+  # checkout + setup-buildx + scheduler round-trips compared to separate jobs.
+  docker:
+    name: Docker
     runs-on: ubuntu-latest
-    needs: [test-backend]
+    needs: [test-backend, check-ui]
     steps:
       - uses: actions/checkout@v4
 
       - uses: docker/setup-buildx-action@v3
 
+      # Single login — credential is written to ~/.docker/config.json and
+      # reused by all subsequent build-push-action steps in this job.
       - name: Log in to Docker Hub
         uses: docker/login-action@v3
         with:
           username: ${{ secrets.DOCKER_USER }}
           password: ${{ secrets.DOCKER_TOKEN }}
 
-      - name: Docker meta
-        id: meta
+      # ── backend ──────────────────────────────────────────────────────────────
+      - name: Docker meta / backend
+        id: meta-backend
         uses: docker/metadata-action@v5
         with:
           images: ${{ secrets.DOCKER_USER }}/libnovel-backend
@@ -81,38 +179,23 @@ jobs:
             type=semver,pattern={{major}}.{{minor}}
             type=raw,value=latest
 
-      - name: Build and push
+      - name: Build and push / backend
         uses: docker/build-push-action@v6
         with:
           context: backend
           target: backend
           push: true
-          tags: ${{ steps.meta.outputs.tags }}
-          labels: ${{ steps.meta.outputs.labels }}
+          tags: ${{ steps.meta-backend.outputs.tags }}
+          labels: ${{ steps.meta-backend.outputs.labels }}
           build-args: |
-            VERSION=${{ steps.meta.outputs.version }}
+            VERSION=${{ steps.meta-backend.outputs.version }}
             COMMIT=${{ gitea.sha }}
           cache-from: type=registry,ref=${{ secrets.DOCKER_USER }}/libnovel-backend:latest
           cache-to: type=inline
 
-  # ── docker: runner ────────────────────────────────────────────────────────────
-  docker-runner:
-    name: Docker / runner
-    runs-on: ubuntu-latest
-    needs: [test-backend]
-    steps:
-      - uses: actions/checkout@v4
-
-      - uses: docker/setup-buildx-action@v3
-
-      - name: Log in to Docker Hub
-        uses: docker/login-action@v3
-        with:
-          username: ${{ secrets.DOCKER_USER }}
-          password: ${{ secrets.DOCKER_TOKEN }}
-
-      - name: Docker meta
-        id: meta
+      # ── runner ───────────────────────────────────────────────────────────────
+      - name: Docker meta / runner
+        id: meta-runner
         uses: docker/metadata-action@v5
         with:
           images: ${{ secrets.DOCKER_USER }}/libnovel-runner
@@ -121,96 +204,34 @@ jobs:
             type=semver,pattern={{major}}.{{minor}}
             type=raw,value=latest
 
-      - name: Build and push
+      - name: Build and push / runner
         uses: docker/build-push-action@v6
         with:
           context: backend
           target: runner
           push: true
-          tags: ${{ steps.meta.outputs.tags }}
-          labels: ${{ steps.meta.outputs.labels }}
+          tags: ${{ steps.meta-runner.outputs.tags }}
+          labels: ${{ steps.meta-runner.outputs.labels }}
           build-args: |
-            VERSION=${{ steps.meta.outputs.version }}
+            VERSION=${{ steps.meta-runner.outputs.version }}
             COMMIT=${{ gitea.sha }}
           cache-from: type=registry,ref=${{ secrets.DOCKER_USER }}/libnovel-runner:latest
           cache-to: type=inline
 
-  # ── ui: source map upload ─────────────────────────────────────────────────────
-  # Commented out: GlitchTip project/auth token needs to be recreated after
-  # the GlitchTip DB wipe. Re-enable once GLITCHTIP_AUTH_TOKEN is updated.
-  # upload-sourcemaps:
-  #   name: Upload source maps
-  #   runs-on: ubuntu-latest
-  #   needs: [check-ui]
-  #   defaults:
-  #     run:
-  #       working-directory: ui
-  #   steps:
-  #     - uses: actions/checkout@v4
-  #
-  #     - uses: actions/setup-node@v4
-  #       with:
-  #         node-version: "22"
-  #         cache: npm
-  #         cache-dependency-path: ui/package-lock.json
-  #
-  #     - name: Install dependencies
-  #       run: npm ci
-  #
-  #     - name: Build with source maps
-  #       run: npm run build
-  #
-  #     - name: Download glitchtip-cli
-  #       run: |
-  #         curl -L "https://gitlab.com/glitchtip/glitchtip-cli/-/jobs/artifacts/v0.1.0/raw/artifacts/glitchtip-cli-linux-x86_64?job=build-linux-x86_64" \
-  #           -o /usr/local/bin/glitchtip-cli
-  #         chmod +x /usr/local/bin/glitchtip-cli
-  #
-  #     - name: Inject debug IDs into build artifacts
-  #       run: glitchtip-cli sourcemaps inject ./build
-  #       env:
-  #         SENTRY_URL: https://errors.libnovel.cc/
-  #         SENTRY_AUTH_TOKEN: ${{ secrets.GLITCHTIP_AUTH_TOKEN }}
-  #         SENTRY_ORG: libnovel
-  #         SENTRY_PROJECT: libnovel-ui
-  #
-  #     - name: Upload source maps to GlitchTip
-  #       run: glitchtip-cli sourcemaps upload ./build --release ${{ gitea.ref_name }}
-  #       env:
-  #         SENTRY_URL: https://errors.libnovel.cc/
-  #         SENTRY_AUTH_TOKEN: ${{ secrets.GLITCHTIP_AUTH_TOKEN }}
-  #         SENTRY_ORG: libnovel
-  #         SENTRY_PROJECT: libnovel-ui
-
-  # ── docker: ui ────────────────────────────────────────────────────────────────
-  docker-ui:
-    name: Docker / ui
-    runs-on: ubuntu-latest
-    needs: [check-ui]
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Fetch releases from Gitea API
-        run: |
-          set -euo pipefail
-          RESPONSE=$(curl -sfL \
-            -H "Accept: application/json" \
-            "http://gitea.kalekber.cc/api/v1/repos/kamil/libnovel/releases?limit=50&page=1")
-          # Validate JSON before writing — fails hard if response is not a JSON array
-          COUNT=$(echo "$RESPONSE" | jq 'if type == "array" then length else error("expected array, got \(type)") end')
-          echo "$RESPONSE" > ui/static/releases.json
-          echo "Fetched $COUNT releases"
-
-      - uses: docker/setup-buildx-action@v3
-
-      - name: Log in to Docker Hub
-        uses: docker/login-action@v3
+      # ── ui ───────────────────────────────────────────────────────────────────
+      - name: Download ui build artifacts
+        uses: actions/download-artifact@v3
         with:
-          username: ${{ secrets.DOCKER_USER }}
-          password: ${{ secrets.DOCKER_TOKEN }}
+          name: ui-build
+          path: ui/build
 
-      - name: Docker meta
-        id: meta
+      - name: Allow build/ into Docker context (override .dockerignore)
+        run: |
+          grep -v '^build$' ui/.dockerignore > ui/.dockerignore.tmp
+          mv ui/.dockerignore.tmp ui/.dockerignore
+
+      - name: Docker meta / ui
+        id: meta-ui
         uses: docker/metadata-action@v5
         with:
           images: ${{ secrets.DOCKER_USER }}/libnovel-ui
@@ -219,37 +240,24 @@ jobs:
             type=semver,pattern={{major}}.{{minor}}
             type=raw,value=latest
 
-      - name: Build and push
+      - name: Build and push / ui
         uses: docker/build-push-action@v6
         with:
           context: ui
           push: true
-          tags: ${{ steps.meta.outputs.tags }}
-          labels: ${{ steps.meta.outputs.labels }}
+          tags: ${{ steps.meta-ui.outputs.tags }}
+          labels: ${{ steps.meta-ui.outputs.labels }}
           build-args: |
-            BUILD_VERSION=${{ steps.meta.outputs.version }}
+            BUILD_VERSION=${{ steps.meta-ui.outputs.version }}
             BUILD_COMMIT=${{ gitea.sha }}
             BUILD_TIME=${{ gitea.event.head_commit.timestamp }}
+            PREBUILT=1
           cache-from: type=registry,ref=${{ secrets.DOCKER_USER }}/libnovel-ui:latest
           cache-to: type=inline
 
-  # ── docker: caddy ─────────────────────────────────────────────────────────────
-  docker-caddy:
-    name: Docker / caddy
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - uses: docker/setup-buildx-action@v3
-
-      - name: Log in to Docker Hub
-        uses: docker/login-action@v3
-        with:
-          username: ${{ secrets.DOCKER_USER }}
-          password: ${{ secrets.DOCKER_TOKEN }}
-
-      - name: Docker meta
-        id: meta
+      # ── caddy ────────────────────────────────────────────────────────────────
+      - name: Docker meta / caddy
+        id: meta-caddy
         uses: docker/metadata-action@v5
         with:
           images: ${{ secrets.DOCKER_USER }}/libnovel-caddy
@@ -258,13 +266,13 @@ jobs:
             type=semver,pattern={{major}}.{{minor}}
             type=raw,value=latest
 
-      - name: Build and push
+      - name: Build and push / caddy
         uses: docker/build-push-action@v6
         with:
           context: caddy
           push: true
-          tags: ${{ steps.meta.outputs.tags }}
-          labels: ${{ steps.meta.outputs.labels }}
+          tags: ${{ steps.meta-caddy.outputs.tags }}
+          labels: ${{ steps.meta-caddy.outputs.labels }}
           cache-from: type=registry,ref=${{ secrets.DOCKER_USER }}/libnovel-caddy:latest
           cache-to: type=inline
 
@@ -272,14 +280,31 @@ jobs:
   release:
     name: Gitea Release
     runs-on: ubuntu-latest
-    needs: [docker-backend, docker-runner, docker-ui, docker-caddy]
+    needs: [docker]
     steps:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
 
+      - name: Extract release notes from tag commit
+        id: notes
+        run: |
+          set -euo pipefail
+          # Subject line (first line of commit message) → release title
+          SUBJECT=$(git log -1 --format="%s" "${{ gitea.sha }}")
+          # Body (everything after the blank line) → release body
+          BODY=$(git log -1 --format="%b" "${{ gitea.sha }}" | sed '/^Co-Authored-By:/d' | sed '/^[[:space:]]*$/{ N; /^\n$/d }' | sed 's/^[[:space:]]*$//' | awk 'NF || !p; {p = !NF}')
+          echo "title=${SUBJECT}" >> "$GITHUB_OUTPUT"
+          # Use a heredoc delimiter to safely handle multi-line body
+          {
+            echo "body<<RELEASE_BODY_EOF"
+            echo "${BODY}"
+            echo "RELEASE_BODY_EOF"
+          } >> "$GITHUB_OUTPUT"
+
       - name: Create release
         uses: https://gitea.com/actions/gitea-release-action@v1
         with:
           token: ${{ secrets.GITEA_TOKEN }}
-          generate_release_notes: true
+          title: ${{ steps.notes.outputs.title }}
+          body: ${{ steps.notes.outputs.body }}

.githooks/pre-commit

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+# Auto-recompile paraglide messages when ui/messages/*.json files are staged.
+# Prevents svelte-check / CI failures caused by stale generated JS files.
+
+set -euo pipefail
+
+STAGED=$(git diff --cached --name-only)
+
+if echo "$STAGED" | grep -q '^ui/messages/'; then
+  echo "[pre-commit] ui/messages/*.json changed — recompiling paraglide..."
+  (cd ui && npm run paraglide --silent)
+  git add -f ui/src/lib/paraglide/messages/
+  echo "[pre-commit] paraglide output re-staged."
+fi

.gitignore

@@ -6,6 +6,8 @@
 
 # ── Compiled binaries ──────────────────────────────────────────────────────────
 backend/bin/
+backend/backend
+backend/runner
 
 # ── Environment & secrets ──────────────────────────────────────────────────────
 # Secrets are managed by Doppler — never commit .env files.

.opencode/skills/ios-ux/SKILL.md

@@ -1,156 +0,0 @@
----
-name: ios-ux
-description: iOS/SwiftUI UI & UX review and implementation guidelines for LibNovel. Enforces Apple HIG, iOS 17+ APIs, spring animations, haptics, accessibility, performance, and offline handling. Load this skill for any iOS view work.
-compatibility: opencode
----
-
-# iOS UI/UX Skill — LibNovel
-
-Load this skill whenever working on SwiftUI views in `ios/`. It defines design standards, review process for screenshots, and implementation rules.
-
----
-
-## Screenshot Review Process
-
-When the user provides a screenshot of the app:
-
-1. **Analyze first** — identify specific UI/UX issues across these categories:
-   - Visual hierarchy and spacing
-   - Typography (size, weight, contrast)
-   - Color and material usage
-   - Animation and interactivity gaps
-   - Accessibility problems
-   - Deprecated or non-native patterns
-2. **Present a numbered list** of suggested improvements with brief rationale for each.
-3. **Ask for confirmation** before writing any code: "Should I apply all of these, or only specific ones?"
-4. Apply only what the user confirms.
-
----
-
-## Design System
-
-### Colors & Materials
-- **Accent**: `Color.amber` (project-defined). Use for active state, selection indicators, progress fills, and CTAs.
-- **Backgrounds**: Prefer `.regularMaterial`, `.ultraThinMaterial`, or `.thinMaterial` over hard-coded `Color.black.opacity(x)` or `Color(.systemBackground)`.
-- **Dark overlays** (e.g. full-screen players): Use `KFImage` blurred background + `Color.black.opacity(0.5–0.6)` overlay. Never use a flat solid black background.
-- **Semantic colors**: Use `.primary`, `.secondary`, `.tertiary` foreground styles. Avoid hard-coded `Color.white` except on dark material contexts (full-screen player).
-- **No hardcoded color literals** — use `Color+App.swift` extensions or system semantic colors.
-
-### Typography
-- Use the SF Pro system font via `.font(.title)`, `.font(.body)`, etc. — never hardcode font names except for intentional stylistic accents (e.g. "Snell Roundhand" for voice watermark).
-- Apply `.fontWeight()` and `.fontDesign()` modifiers rather than custom font families.
-- Support Dynamic Type — never hardcode a fixed font size as the sole option without a `.minimumScaleFactor` or system font size modifier.
-- Hierarchy: title3.bold for primary labels, subheadline for secondary, caption/caption2 for metadata.
-
-### Spacing & Layout
-- Minimum touch target: **44×44 pt**. Use `.frame(minWidth: 44, minHeight: 44)` or `.contentShape(Rectangle())` on small icons.
-- Prefer 16–20 pt horizontal padding on full-width containers; 12 pt for compact inner elements.
-- Use `VStack(spacing:)` and `HStack(spacing:)` explicitly — never rely on default spacing for production UI.
-- Corner radii: 12–14 pt for cards/chips, 10 pt for small badges, 20–24 pt for large cover art.
-
----
-
-## Animation Rules
-
-### Spring Animations (default for all interactive transitions)
-- Use `.spring(response:dampingFraction:)` for state-driven layout changes, selection feedback, and appear/disappear transitions.
-- Recommended defaults:
-  - Interactive elements: `response: 0.3, dampingFraction: 0.7`
-  - Entrance animations: `response: 0.45–0.5, dampingFraction: 0.7`
-  - Quick snappy feedback: `response: 0.2, dampingFraction: 0.6`
-- Reserve `.easeInOut` only for non-interactive, ambient animations (e.g. opacity pulses, generating overlays).
-
-### SF Symbol Transitions
-- Always use `contentTransition(.symbolEffect(.replace.downUp))` when a symbol name changes based on state (play/pause, checkmark/circle, etc.).
-- Use `.symbolEffect(.variableColor.cumulative)` for continuous animations (waveform, loading indicators).
-- Use `.symbolEffect(.bounce)` for one-shot entrance emphasis (e.g. completion checkmark appearing).
-- Use `.symbolEffect(.pulse)` for error/warning states that need attention.
-
-### Repeating Animations
-- Use `phaseAnimator` for any looping animation that previously used manual `@State` + `withAnimation` chains.
-- Do not use `Timer` publishers for UI animation — prefer `phaseAnimator` or `TimelineView`.
-
----
-
-## Haptic Feedback
-
-Add `UIImpactFeedbackGenerator` to every user-initiated interactive control:
-- `.light` — toggle switches, selection chips, secondary actions, slider drag start.
-- `.medium` — primary transport buttons (play/pause, chapter skip), significant confirmations.
-- `.heavy` — destructive actions (only if no confirmation dialog).
-
-Pattern:
-```swift
-Button {
-    UIImpactFeedbackGenerator(style: .light).impactOccurred()
-    // action
-} label: { ... }
-```
-
-Do **not** add haptics to:
-- Programmatic state changes not directly triggered by a tap.
-- Buttons inside `List` rows that already use swipe actions.
-- Scroll events.
-
----
-
-## iOS 17+ API Usage
-
-Flag and replace any of the following deprecated patterns:
-
-| Deprecated | Replace with |
-|---|---|
-| `NavigationView` | `NavigationStack` |
-| `@StateObject` / `ObservableObject` (new types only) | `@Observable` macro |
-| `DispatchQueue.main.async` | `await MainActor.run` or `@MainActor` |
-| Manual `@State` animation chains for repeating loops | `phaseAnimator` |
-| `.animation(_:)` without `value:` | `.animation(_:value:)` |
-| `AnyView` wrapping for conditional content | `@ViewBuilder` + `Group` |
-
-Do **not** refactor existing `ObservableObject` types to `@Observable` unless explicitly asked — only apply `@Observable` to new types.
-
----
-
-## Accessibility
-
-Every view must:
-- Support VoiceOver: add `.accessibilityLabel()` to icon-only buttons and image views.
-- Support Dynamic Type: test that text doesn't truncate at xxxLarge without a layout adjustment.
-- Meet contrast ratio: text on tinted backgrounds must be legible — avoid `.opacity(0.25)` or lower for any user-readable text.
-- Touch targets ≥ 44pt (see Spacing above).
-- Interactive controls must have `.accessibilityAddTraits(.isButton)` if not using `Button`.
-- Do not rely solely on color to convey state — pair color with icon or label.
-
----
-
-## Performance
-
-- **Isolate high-frequency observers**: Any view that observes a `PlaybackProgress` (timer-tick updates) must be a separate sub-view that `@ObservedObject`-observes only the progress object — not the parent view. This prevents the entire parent from re-rendering every 0.5 seconds.
-- **Avoid `id()` overuse**: Only use `.id()` to force view recreation when necessary (e.g. background image on track change). Prefer `onChange(of:)` for side effects.
-- **Lazy containers**: Use `LazyVStack` / `LazyHStack` inside `ScrollView` for lists of 20+ items. `List` is inherently lazy and does not need this.
-- **Image loading**: Always use `KFImage` (Kingfisher) with `.placeholder` for remote images. Never use `AsyncImage` for cover art — it has no disk cache.
-- **Avoid `AnyView`**: It breaks structural identity and hurts diffing. Use `@ViewBuilder` or `Group { }` instead.
-
----
-
-## Offline & Error States
-
-Every view that makes network calls must:
-1. Wrap the body in a `VStack` with `OfflineBanner` at the top, gated on `networkMonitor.isConnected`.
-2. Suppress network errors silently when offline via `ErrorAlertModifier` — do not show an alert when the device is offline.
-3. Gate `.task` / `.onAppear` network calls: `guard networkMonitor.isConnected else { return }`.
-4. Show a non-blocking inline empty state (not a full-screen error) for failed loads when online.
-
----
-
-## Component Checklist (before submitting any view change)
-
-- [ ] All interactive elements ≥ 44pt touch target
-- [ ] SF Symbol state changes use `contentTransition(.symbolEffect(...))`
-- [ ] State-driven layout transitions use `.spring(response:dampingFraction:)`
-- [ ] Tappable controls have haptic feedback
-- [ ] No `NavigationView`, no `DispatchQueue.main.async`, no `.animation(_:)` without `value:`
-- [ ] High-frequency observers are isolated sub-views
-- [ ] Offline state handled with `OfflineBanner` + `NetworkMonitor`
-- [ ] VoiceOver labels on icon-only buttons
-- [ ] No hardcoded `Color.black` / `Color.white` / `Color(.systemBackground)` where a material applies

AGENTS.md

@@ -0,0 +1,193 @@
+# LibNovel v2 — Agent Context
+
+This file is the root-level knowledge base for LLM coding agents (OpenCode, Claude, Cursor, Copilot, etc.).
+Sub-directories have their own `AGENTS.md` with deeper context (e.g. `ios/AGENTS.md`).
+
+---
+
+## Stack
+
+| Layer | Technology |
+|---|---|
+| UI | SvelteKit 2 + Svelte 5, TypeScript, TailwindCSS |
+| Backend / Runner | Go (single repo, two binaries: `backend`, `runner`) |
+| iOS app | SwiftUI, iOS 17+, Swift 5.9+ |
+| Database | PocketBase (SQLite) + MinIO (object storage) |
+| Search | Meilisearch |
+| Queue | Asynq over Redis (local) / Valkey (prod) |
+| Scraping | Novelfire scraper in `backend/novelfire/` |
+
+---
+
+## Repository Layout
+
+```
+.
+├── .gitea/workflows/     # CI/CD — Gitea Actions (NOT .github/)
+├── .opencode/            # OpenCode agent config (memory, skills)
+├── backend/              # Go backend + runner (single module)
+├── caddy/                # Caddy reverse proxy Dockerfile
+├── homelab/              # Homelab docker-compose + observability stack
+├── ios/                  # SwiftUI iOS app (see ios/AGENTS.md)
+├── scripts/              # Utility scripts
+├── ui/                   # SvelteKit UI
+├── docker-compose.yml    # Prod compose (all services)
+├── AGENTS.md             # This file
+└── opencode.json         # OpenCode config
+```
+
+---
+
+## CI/CD — Gitea Actions
+
+- Workflows live in `.gitea/workflows/` — **not** `.github/workflows/`
+- Self-hosted Gitea instance; use `gitea.ref_name` / `gitea.sha` (not `github.*`)
+- Two workflows:
+  - `ci.yaml` — runs on every push to `main` (test + type-check)
+  - `release.yaml` — runs on `v*` tags (build Docker images, upload source maps, create Gitea release)
+- Secrets: `DOCKER_USER`, `DOCKER_TOKEN`, `GITEA_TOKEN`, `GLITCHTIP_AUTH_TOKEN`
+
+### Git credentials
+
+Credentials are embedded in the remote URL — no `HOME=/root` or credential helper needed for push:
+
+```
+https://kamil:95782641Apple%24@gitea.kalekber.cc/kamil/libnovel.git
+```
+
+All git commands still use `HOME=/root` prefix for consistency (picks up `/root/.gitconfig` for user name/email), but push auth works without it.
+
+### Releasing a new version
+
+```bash
+HOME=/root git tag v2.6.X -m "Short title"
+HOME=/root git push origin v3-cleanup --tags
+```
+
+CI will build all Docker images, upload source maps to GlitchTip, and create a Gitea release automatically.
+
+---
+
+## GlitchTip Error Tracking
+
+- Instance: `https://errors.libnovel.cc/`
+- Org: `libnovel`
+- Projects: `ui` (id/1), `backend` (id/2), `runner` (id/3)
+- Tool: `glitchtip-cli` v0.1.0
+
+### Per-service DSNs (stored in Doppler)
+
+| Service | Doppler key | GlitchTip project |
+|---|---|---|
+| UI (SvelteKit) | `PUBLIC_GLITCHTIP_DSN` | ui (1) |
+| Backend (Go) | `GLITCHTIP_DSN_BACKEND` | backend (2) |
+| Runner (Go) | `GLITCHTIP_DSN_RUNNER` | runner (3) |
+
+### Source map upload flow (release.yaml)
+
+The correct order is **critical** — uploading before `releases new` results in 0 files shown in GlitchTip UI:
+
+```
+glitchtip-cli sourcemaps inject ./build          # inject debug IDs
+glitchtip-cli releases new <version>             # MUST come before upload
+glitchtip-cli sourcemaps upload ./build \
+  --release <version>                            # associate files with release
+glitchtip-cli releases finalize <version>        # mark release complete
+```
+
+---
+
+## Infrastructure
+
+| Environment | Host | Path | Doppler config |
+|---|---|---|---|
+| Prod | `165.22.70.138` | `/opt/libnovel/` | `prd` |
+| Homelab runner | `192.168.0.109` | `/opt/libnovel-runner/` | `prd_homelab` |
+
+### Docker Compose — always use Doppler
+
+```bash
+# Prod
+doppler run --project libnovel --config prd -- docker compose <cmd>
+
+# Homelab full-stack (runs from .bak file on server)
+doppler run --project libnovel --config prd_homelab -- docker compose -f homelab/docker-compose.yml.bak <cmd>
+
+# Homelab runner only
+doppler run --project libnovel --config prd_homelab -- docker compose -f homelab/runner/docker-compose.yml <cmd>
+```
+
+- Prod runner has `profiles: [runner]` — `docker compose up -d` will NOT accidentally start it
+- When deploying, always sync `docker-compose.yml` to the server before running `up -d`
+- **Caddyfile is NOT in git** — lives at `/opt/libnovel/Caddyfile` on prod server only. Edit directly on the server and restart the `caddy` container.
+
+---
+
+## Observability
+
+| Tool | Purpose |
+|---|---|
+| GlitchTip | Error tracking (UI + backend + runner) |
+| Grafana Faro | RUM / Web Vitals (collector at `faro.libnovel.cc/collect`) → Alloy (port 12347) |
+| OpenTelemetry | Distributed tracing (OTLP → cloudflared → OTel collector → Tempo) |
+| Grafana | Dashboards at `https://grafana.libnovel.cc` |
+
+### Grafana dashboards: `homelab/otel/grafana/provisioning/dashboards/`
+
+Key dashboards:
+- `backend.json` — Backend logs (Loki: `{service_name="backend"}`, plain text)
+- `runner.json` — Runner logs (Loki: `{service_name="runner"}`) + Asynq Prometheus metrics
+- `web-vitals.json` — Web Vitals (Loki: `{service_name="unknown_service"} kind=measurement` + pattern parser)
+- `catalogue.json` — Scrape progress (Loki: `{service_name="runner"} | json | body="..."`)
+
+### Data pipeline (2026-04-07 working state)
+
+**Browser → Grafana Faro:**
+Browser sends RUM data → `https://faro.libnovel.cc/collect` → **Alloy** `faro.receiver` (port 12347) → Loki (logs/exceptions) + OTel collector → **Tempo** (traces)
+
+**Backend/Runner → OTel:**
+Backend/Runner Go SDK → `https://otel.libnovel.cc` (cloudflared tunnel) → **OTel collector** (port 4318) → Tempo (traces) + Loki (logs via `otlphttp/loki` exporter)
+Runner also sends to **Alloy** `otelcol.receiver.otlp` (port 4318) → `otelcol.exporter.loki` → Loki
+
+### Loki log format per service
+
+- `service_name="backend"`: Plain text (e.g. `backend: asynq task dispatch enabled`)
+- `service_name="runner"`: JSON with `body`, `attributes{slug,chapters,page}`, `severity`
+- `service_name="unknown_service"`: Faro RUM text format (e.g. `kind=measurement lcp=5428.0 ...`)
+
+### OTel Collector ports (homelab)
+
+- gRPC: `4317` — receives from cloudflared (`otel.libnovel.cc`)
+- HTTP: `4318` — receives from cloudflared + Alloy
+- Metrics: `8888`
+
+### Known issues / pending fixes
+
+- Web Vitals use `service_name="unknown_service"` (Faro SDK doesn't set service.name in browser) — works with `unknown_service` label
+- Runner logs go to both Alloy→Loki AND OTel collector→Loki (dual pipeline — intentional for resilience)
+
+---
+
+## Go Backend
+
+- Primary files: `orchestrator.go`, `server/handlers_*.go`, `novelfire/scraper.go`, `storage/hybrid.go`, `storage/pocketbase.go`
+- Store interface: `store.go` — never touch MinIO/PocketBase clients directly outside `storage/`
+- Two binaries built from the same module: `backend` (HTTP API) and `runner` (Asynq worker)
+
+---
+
+## SvelteKit UI
+
+- Source: `ui/src/`
+- i18n: Paraglide — translation files in `ui/messages/*.json` (5 locales)
+- Auth debug bypass: `GET /api/auth/debug-login?token=<DEBUG_LOGIN_TOKEN>&username=<username>&next=<path>`
+
+---
+
+## iOS App
+
+Full context in `ios/AGENTS.md`. Quick notes:
+- SwiftUI, iOS 17+, `@Observable` for new types
+- Download key separator: `::` (not `-`)
+- Voice fallback: book override → global default → `"af_bella"`
+- Offline pattern: `NetworkMonitor` env object + `OfflineBanner` + `ErrorAlertModifier`

Caddyfile

@@ -58,9 +58,9 @@
 
 	# ── Redis TCP proxy via layer4 ────────────────────────────────────────────
 	# Exposes prod Redis over TLS for Asynq job enqueueing from the homelab runner.
-	# Listens on :6380 (all interfaces). TLS is terminated here using the cert
+	# Listens on :6380 (all interfaces). TLS is terminated here using the cert
 	# for redis.libnovel.cc; traffic is proxied to the local Redis sidecar.
-	# Requires the caddy-l4 module in the custom Caddy build.
+	# Requires the caddy-l4 module in the custom Caddy build.
 	layer4 {
 		:6380 {
 			route {
@@ -73,7 +73,7 @@
 				}
 				proxy {
 					upstream redis:6379
-				}
+				}
 			}
 		}
 	}