feat(router): cookie-aware SSR library resolution with resolveLibrary helper

- helpers.go: Promote getText() from a local closure in frontend.go
  to a package-level function so it can be used by resolveLibrary.
  Add resolveLibrary(c, cfg, user.ID) helper that:
    1. Reads library_id query param (explicit navigation wins)
    2. Falls back to selectedLibrary cookie — validates __all__
       sentinel or real UUID, rejects garbage values silently
    3. Falls back to user's first visible library
  Returns LibraryResolution struct with LibraryID, IsAll, LibUUID,
  Libraries, and FirstID — eliminating repeated boilerplate across
  all SSR routes.

- frontend.go: Replace manual library resolution boilerplate in 5
  SSR route handlers (series, tags/detail, bookshelf, dashboard,
  collections/:id) with resolveLibrary(). Each route now gets cookie-
  aware library selection for free. Collection detail correctly
  handles All Libraries mode for both system and user collections.
  Dashboard no longer makes a redundant second GetUserVisibleLibraries
  call.

.dockerignore

@@ -20,9 +20,6 @@ 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

.env.example

@@ -10,21 +10,6 @@ JWT_SECRET=your-secure-jwt-secret-key-here
 # Generate with: openssl rand -hex 16
 DBPASS=your-secure-database-password-here
 
-# Networking: change a port if it conflicts on your host
-# Postgres port, host + container (e.g. another local DB already uses 5432)
-# DB_PORT=15432
-# App web port, host + container
-# SERVER_PORT=8765
-
-# Deployment
-# External URL for device sync (must include protocol; defaults to http://localhost:8765)
-# Examples: https://bookhoard.example.com | http://192.168.1.10:8765
-# BASE_URL=https://bookhoard.example.com
-# Mark session cookies Secure — set true behind a TLS-terminating reverse proxy (Caddy/nginx/traefik)
-# COOKIE_SECURE=true
-# Pin or rollback a specific published image version (defaults to "latest")
-# IMAGE_TAG=1.0.0
-
 # Optional: Override Defaults (defaults are set in docker-compose.yml)
 # Test Mode: WARNING - Only set to true for integration testing
 # TEST_MODE=true
@@ -35,9 +20,5 @@ DBPASS=your-secure-database-password-here
 # BOOKHOARD_CONVERSION_TOOL=/usr/bin/ebook-convert
 # Conversion Cache TTL: Override default 24h
 # BOOKHOARD_CONVERSION_CACHE_TTL=48h
-# Archive Retention: days to keep archived items (files missing from disk for
-# 2+ scans) before they are purged, deleting their reading history with them.
-# Set 0 to keep archived items until purged manually on the library admin page.
-# ARCHIVE_RETENTION_DAYS=90
 # System timezone (fallback for server-side time operations, defaults to UTC)
 # TZ=America/New_York

.gitea/workflows/release.yml

@@ -1,115 +0,0 @@
-name: Release
-
-# Overrides the default run name (the tagged commit's message) so the Actions
-# runs list shows "Release v0.3.0" instead.
-run-name: "Release ${{ gitea.event.inputs.tag || gitea.ref_name }}"
-
-# Publishes the Bookhoard container image to the Gitea container registry AND
-# creates a Gitea Release whose body is the annotated tag's message (generated
-# locally by `make release VERSION=...` via git-cliff). Triggered by a version
-# tag push, or manually via workflow_dispatch with a tag. Pushing to main does
-# nothing, so work-in-progress commits never ship. Each release publishes two
-# image tags: the version (e.g. v0.3.0) and "latest".
-on:
-  push:
-    tags:
-      - 'v*'
-  workflow_dispatch:
-    inputs:
-      tag:
-        description: 'Tag to release (e.g. v0.3.0)'
-        required: true
-        type: string
-
-jobs:
-  build-and-push:
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-      packages: write
-    env:
-      # Resolve the target tag for both triggers: explicit input on manual
-      # dispatch, otherwise the pushed tag ref.
-      TAG: ${{ gitea.event.inputs.tag || gitea.ref_name }}
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-        with:
-          # Full history ensures the tag annotation (the release notes) is present.
-          fetch-depth: 0
-          ref: ${{ gitea.event.inputs.tag || gitea.ref }}
-
-      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v3
-
-      - name: Login to Gitea Container Registry
-        uses: docker/login-action@v3
-        with:
-          registry: git.linuxhg.com
-          username: ${{ gitea.actor }}
-          # PAT stored as a repo Actions secret (auto GITHUB_TOKEN lacks package scope in Gitea)
-          password: ${{ secrets.REGISTRY_TOKEN }}
-
-      - name: Build and push image
-        uses: docker/build-push-action@v5
-        with:
-          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.
-          tags: |
-            git.linuxhg.com/bookhoard/bookhoard:${{ env.TAG }}
-            git.linuxhg.com/bookhoard/bookhoard:latest
-
-      - name: Create Gitea Release
-        env:
-          # REGISTRY_TOKEN is reused for release creation because Gitea's auto
-          # GITHUB_TOKEN cannot create releases on this instance. The PAT must
-          # carry write:repository scope. Idempotent: re-runs update an existing
-          # release for this tag instead of failing with 409. On any HTTP error
-          # the API response body is printed so a 403 names the missing scope.
-          TOKEN: ${{ secrets.REGISTRY_TOKEN }}
-          REPO: ${{ gitea.repository }}
-        run: |
-          set -euo pipefail
-          : "${TAG:?TAG is required}"
-          API="https://git.linuxhg.com/api/v1/repos/${REPO}/releases"
-          AUTH="Authorization: token ${TOKEN}"
-          # Release body = the annotated tag's message (the git-cliff notes).
-          BODY="$(git tag -l --format='%(contents)' "${TAG}")"
-
-          # Tags containing a '-' (e.g. v0.3.0-rc1) are published as pre-releases.
-          PRE="false"; case "${TAG}" in *-*) PRE="true";; esac
-
-          PAYLOAD=$(jq -n \
-            --arg t "${TAG}" --arg n "${TAG}" --arg b "${BODY}" --argjson p "${PRE}" \
-            '{tag_name:$t, name:$n, body:$b, draft:false, prerelease:$p}')
-
-          # POST/PATCH the release, surfacing Gitea's error message on failure
-          # (e.g. "token does not have write scope") instead of failing silently.
-          api_call() {
-            local method="$1" url="$2" resp code rbody
-            resp="$(curl -sS -w '\n%{http_code}' -X "${method}" \
-              -H "${AUTH}" -H "Content-Type: application/json" \
-              -d "${PAYLOAD}" "${url}")"
-            code="$(printf '%s' "${resp}" | tail -n1)"
-            rbody="$(printf '%s' "${resp}" | sed '$d')"
-            if [ "${code}" -ge 400 ]; then
-              echo "::error::Release API ${code} (${method} ${url}): ${rbody}" >&2
-              return 1
-            fi
-          }
-
-          EXISTING_ID="$(curl -sS -H "${AUTH}" "${API}/tags/${TAG}" | jq -r '.id // empty' 2>/dev/null || true)"
-          if [ -n "${EXISTING_ID}" ]; then
-            api_call PATCH "${API}/${EXISTING_ID}"
-            echo "Updated existing release id=${EXISTING_ID} for ${TAG}"
-          else
-            api_call POST "${API}"
-            echo "Created new release for ${TAG}"
-          fi

.gitignore

@@ -79,10 +79,3 @@ web/static/vendor/
 VALID_TOKEN
 fresh_token.txt
 session-*.md
-
-# Local prod-export scratch: personal annotation/reading data, never commit
-/export/
-
-# Binary media fixtures: never commit (generate with ffmpeg at test time,
-# see docs/contributing/development.md → Media fixtures)
-internal/services/testdata/

AGENTS.md

@@ -1,257 +0,0 @@
-# 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).
-
-## Rendering ownership (templ vs TypeScript) — ALWAYS apply
-
-The point of templ + htmx + Alpine is: the server renders the UI, and
-JavaScript is kept minimal. The rule that keeps it that way:
-
-> **JavaScript decides what shows. templ decides what it looks like.**
-
-- Content derived from **server data** (DB rows, search results, match
-  lists, conflict cards, any list/card/badge/table) is rendered by
-  templ. When it changes client-side, fetch a **templ partial** from an
-  SSR route and swap it in (`htmx.ajax(...)`), never rebuild it from a
-  JSON payload with `innerHTML` string templates.
-- **Pure functions of client-local state** (open/closed panels, tabs,
-  password strength from a typed value, toasts) may render in
-  TS/Alpine — no server round trip needed.
-- `web/src` is **TypeScript only** — no new `.js` source files.
-  Vendored third-party and vite build output under `web/static` are
-  exempt.
-- Inline `<script>` in a `.templ` file needs a reason a bundled module
-  cannot do the job (pre-paint execution). Currently sanctioned:
-  `theme_flash_guard.templ` only.
-
-Sanctioned JS islands (engines, not UI renderers — exempt from the
-above): the reader (foliate-js + `web/src/reader/`), Chart.js graphs in
-stats, toasts, password validation. Anything else that renders app UI
-in TypeScript is a defect; if a templ twin of it exists, one of the two
-must be deleted.
-
-**Documented exception — dashboard sections**: `renderDashboardCollections`
-/ `renderSectionHTML` in `web/src/dashboard.ts` re-render dashboard
-sections from `/api/dashboard/sections` JSON (library switch, settings
-save, refresh button) to preserve the switch fade/transition on a page
-with heavy interactivity. First-paint section markup is still templ
-(Dashboard handler in `internal/router/frontend.go`). This exception is
-deliberate; do not clone it to new pages, and do not "fix" the dashboard
-without restoring a templ-partial fade path first.
-
-## 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
-
-- **THE DOCTRINE — tests are never run against a real/production
-  server.** The dev DB is the test environment, and the invariant every
-  test must uphold is: **leave the testuser experience alone** — its
-  settings, scans, and reading data must be exactly as the suite found
-  them. The helpers exist to enforce this; if a test needs protection
-  the helpers don't provide, EXPAND THE HELPERS rather than hand-rolling
-  (2026-10-21: `setSystemSettingRestored` — snapshot-and-restore for
-  system_settings — exists because a hardcoded ev restore could clobber
-  a deliberate dev bump, and the live dev server obeys that setting on
-  its next poll).
-- 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).
-- **RUN ONLY YOUR OWN TESTS while iterating**: integration tests
-  require the containerized dev DB — a bare host `go test
-  ./cmd/server/tests` fails on auth on every machine not running the
-  compose stack. Use the filtered container runner
-  (`docker compose -f docker-compose.yml -f
-  docker-compose.dev.yml --profile tests run --rm tests go test
-  ./cmd/server/tests -run 'TestYourPrefix' -v`) and save full-suite
-  runs for pre-commit validation; several tests read live shared
-  state (system_settings, real library folders, the periodic backup
-  scan's websocket broadcasts) and flap on data/timing your change
-  never touched. Full recipes: docs/contributing/development.md
-  → Testing.
-- **NEVER COMMIT BINARY MEDIA** (mp3/m4b/flac/... fixtures): 
-  `internal/services/testdata/` is gitignored by policy; generate
-  media at test runtime with ffmpeg instead (test images ship it).
-  ffmpeg cannot write Audible freeform atoms — those paths are unit-
-  tested with synthetic ffprobeReport values. Recipes:
-  docs/contributing/development.md → Media fixtures.
-
-## Web (TypeScript) tests
-
-- `npm run test` (vp test) runs the vitest suite: colocated `web/src/*.test.ts`
-  files, jsdom environment (configured in vite.config.ts `test`). Do NOT switch
-  to happy-dom — DOMPurify's sanitizer output is mangled under it, which makes
-  the markdown security suite test nothing (verified empirically; jsdom is the
-  documented fallback for exactly this reason).
-- Static gates: `npx tsc --noEmit`, `npx vp check web/src` (format + lint),
-  `npx vp fmt web/src` to apply formatting.
-- Tests are never bundled (build entries are main.ts/reader.ts only). When
-  touching build config, re-prove it: back-to-back `npm run build:ts` runs must
-  produce byte-identical hashes, and no test-only strings may appear in
-  web/static.
-- markdown.test.ts pins the notes XSS defenses (FORBID_TAGS, scheme checks,
-  parser-level html escaping). Loosening any assertion there is a security
-  decision, not cleanup.
-
-## 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.
-
-## Debug discipline (test-failure triage) — 2026-10-17
-
-When a test or bruno request fails, suspect the TEST FIRST — most
-failures in this repo are harness/schema/environment drift, not server
-bugs (2026-10-17 bruno sweep: drifted body keys, bodies pre-truncated
-at their first `{{var}}`, missing `/api` prefixes; host runs hitting
-container-only paths/hostnames). Triage order: (1) read the
-test/fixture/payload schema and diff against a known-good sibling
-(bruno: the `NewDevDBSetup` files are the reference for `body.data`
-form); (2) check environment assumptions (host vs container,
-harness cleanup, live-DB traffic); (3) cheap probe (curl, one SQL
-query) before any deep dive.
-
-But test changes are ASYMMETRIC with code changes: server code may be
-fixed freely when it is the bug; test/contract edits may only
-(a) fix harness plumbing, (b) WIDEN pins additively with a
-`docs/contract_pins.md` changelog entry, (c) delete tests of deleted
-behavior — never narrow an assertion or flip an expectation to match
-observed behavior. Contract pins were green at a known commit, so git
-history arbitrates "test stale vs code changed." If a test looks right
-but fails and no harness bug explains it, that is prima facie evidence
-of a server bug: stop and flag the user.
-
-## 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 + "')" }`. (Every occurrence of this bug —
-   including `class="theme-{ user.Theme }"` on 22 page bodies and 26
-   attribute interpolations — was swept and fixed in 2026-10; when
-   adding attributes with dynamic values, the whole value is an
-   expression, and free text goes through `templates.JSONArg`.)
-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 query types** (amended 2026-10-19,
-   A2c): user collections ARE dashboard sections by default now —
-   GetUserCollectionsForDashboard no longer gates on show_on_dashboard
-   (which remains system-section provisioning state; hiding is
-   dashboard-prefs `hidden_collections` territory). GetDashboardSections
-   still skips genuinely empty user sections, but hide_finished
-   collections emit a Complete section instead of vanishing. Collection
-   detail (JSON + SSR) must still 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.
-7. **Scanner re-extraction is write-after-success** — a failed/empty
-   extraction must NEVER clear scan-derived columns. `updateMediaItem`
-   (generic full-row path) preserves `existing.AudioMetadata` when the
-   new extraction carries no audio payload, and `updateAudioBookItem`
-   refuses empty payloads over populated rows (both guarded 2026-10-21
-   after an ev-gated re-extract NULLed every multi-file audiobook's
-   audio_metadata — books displayed as 1 second long and lost their
-   track manifests). New scan-owned column writes need the same guard.
-8. **templ double-escapes style attribute values** — the codegen wraps
-   style exprs in a sanitizer AND `templ.EscapeString`, so ANY quote
-   character (even inside `templ.SafeCSS`) reaches the DOM as literal
-   `&#39;` text and the CSS never parses (2026-10-21: every book-detail
-   hero backdrop broken + Firefox fetched `/media/&` → 500 spam).
-   Emit quote-free CSS: unquoted `url(...)` tokens via `SafeCSS` +
-   `cssURL()` in book_detail.templ.
-9. **`vp test` runs the vite config** — plugins with build hooks fire
-   in the test context too. `cleanStaleChunks` guards on
-   `produced.size === 0` precisely because a bare sweep deleted every
-   hashed chunk in `web/static` when run under vitest (2026-10-21:
-   `npm run test` gutted the build; every page 404'd its imports).
-   Any future outDir-mutating plugin needs the same "am I a build?"
-   guard.

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 AGENTS.md conventions - make multiple logical commits:
+Follow PROJECT_GUIDELINES.md - make multiple logical commits:
 
 1. **Backend implementation** (search.go, http_handler.go, router changes)
 2. **Unit tests** (search_test.go)

Dockerfile

@@ -8,18 +8,15 @@ RUN apk add --no-cache nodejs npm curl git
 
 # Install Go tools (cached well)
 RUN wget -O /tmp/sqlc.tar.gz https://github.com/sqlc-dev/sqlc/releases/download/v1.31.0/sqlc_1.31.0_linux_amd64.tar.gz && \
-  tar -xzf /tmp/sqlc.tar.gz -C /usr/local/bin sqlc && \
-  rm /tmp/sqlc.tar.gz
+    tar -xzf /tmp/sqlc.tar.gz -C /usr/local/bin sqlc && \
+    rm /tmp/sqlc.tar.gz
 RUN --mount=type=cache,target=/root/go/pkg/mod \
   go install github.com/a-h/templ/cmd/templ@v0.3.1020
 
 # Copy package files and install npm dependencies (cached unless package.json changes)
 COPY package*.json ./
-# npm cache mount renamed from /root/.npm: the old volume held a stale
-# foliate-js tarball (name@version reuse) that --no-cache and builder prune
-# could not evict; a new mount id guarantees a clean fetch.
-RUN --mount=type=cache,target=/root/.npm-cache2 \
-  npm install 
+RUN --mount=type=cache,target=/root/.npm \
+  npm ci
 
 # Copy Go mod files (cached unless go.mod changes)
 COPY go.mod go.sum ./
@@ -37,41 +34,21 @@ 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 \
-  -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
+  CGO_ENABLED=0 GOOS=linux go build -a -installsuffix cgo -o main ./cmd/server
 
 # Test runner stage - includes Go runtime and test dependencies
 # This stage is ONLY used for running tests, never deployed to production
 FROM golang:1.26-alpine AS test-runner
 
-# ffmpeg/ffprobe match the runtime stage: the audio ingestion (tag
-# fallbacks, embedded covers, cue probing) must be exercised in tests
-# exactly as it runs in production.
-RUN apk --no-cache add ca-certificates curl poppler-utils ffmpeg
+RUN apk --no-cache add ca-certificates curl
 
 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
@@ -87,7 +64,7 @@ CMD ["go", "test", "./cmd/server/tests", "-v", "-timeout", "5m", "-parallel=1",
 # Final stage
 FROM alpine:latest
 
-RUN apk --no-cache add ca-certificates curl poppler-utils ffmpeg
+RUN apk --no-cache add ca-certificates curl
 
 # Install kepubify for EPUB→KEPUB conversion
 RUN wget -O /usr/bin/kepubify https://github.com/pgaskin/kepubify/releases/latest/download/kepubify-linux-64bit \

LICENSE

@@ -1,661 +1,232 @@
-                    GNU AFFERO GENERAL PUBLIC LICENSE
-                       Version 3, 19 November 2007
-
- Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
- Everyone is permitted to copy and distribute verbatim copies
- of this license document, but changing it is not allowed.
-
-                            Preamble
-
-  The GNU Affero General Public License is a free, copyleft license for
-software and other kinds of works, specifically designed to ensure
-cooperation with the community in the case of network server software.
-
-  The licenses for most software and other practical works are designed
-to take away your freedom to share and change the works.  By contrast,
-our General Public Licenses are intended to guarantee your freedom to
-share and change all versions of a program--to make sure it remains free
-software for all its users.
-
-  When we speak of free software, we are referring to freedom, not
-price.  Our General Public Licenses are designed to make sure that you
-have the freedom to distribute copies of free software (and charge for
-them if you wish), that you receive source code or can get it if you
-want it, that you can change the software or use pieces of it in new
-free programs, and that you know you can do these things.
-
-  Developers that use our General Public Licenses protect your rights
-with two steps: (1) assert copyright on the software, and (2) offer
-you this License which gives you legal permission to copy, distribute
-and/or modify the software.
-
-  A secondary benefit of defending all users' freedom is that
-improvements made in alternate versions of the program, if they
-receive widespread use, become available for other developers to
-incorporate.  Many developers of free software are heartened and
-encouraged by the resulting cooperation.  However, in the case of
-software used on network servers, this result may fail to come about.
-The GNU General Public License permits making a modified version and
-letting the public access it on a server without ever releasing its
-source code to the public.
-
-  The GNU Affero General Public License is designed specifically to
-ensure that, in such cases, the modified source code becomes available
-to the community.  It requires the operator of a network server to
-provide the source code of the modified version running there to the
-users of that server.  Therefore, public use of a modified version, on
-a publicly accessible server, gives the public access to the source
-code of the modified version.
-
-  An older license, called the Affero General Public License and
-published by Affero, was designed to accomplish similar goals.  This is
-a different license, not a version of the Affero GPL, but Affero has
-released a new version of the Affero GPL which permits relicensing under
-this license.
-
-  The precise terms and conditions for copying, distribution and
-modification follow.
-
-                       TERMS AND CONDITIONS
-
-  0. Definitions.
-
-  "This License" refers to version 3 of the GNU Affero General Public License.
-
-  "Copyright" also means copyright-like laws that apply to other kinds of
-works, such as semiconductor masks.
-
-  "The Program" refers to any copyrightable work licensed under this
-License.  Each licensee is addressed as "you".  "Licensees" and
-"recipients" may be individuals or organizations.
-
-  To "modify" a work means to copy from or adapt all or part of the work
-in a fashion requiring copyright permission, other than the making of an
-exact copy.  The resulting work is called a "modified version" of the
-earlier work or a work "based on" the earlier work.
-
-  A "covered work" means either the unmodified Program or a work based
-on the Program.
-
-  To "propagate" a work means to do anything with it that, without
-permission, would make you directly or secondarily liable for
-infringement under applicable copyright law, except executing it on a
-computer or modifying a private copy.  Propagation includes copying,
-distribution (with or without modification), making available to the
-public, and in some countries other activities as well.
-
-  To "convey" a work means any kind of propagation that enables other
-parties to make or receive copies.  Mere interaction with a user through
-a computer network, with no transfer of a copy, is not conveying.
-
-  An interactive user interface displays "Appropriate Legal Notices"
-to the extent that it includes a convenient and prominently visible
-feature that (1) displays an appropriate copyright notice, and (2)
-tells the user that there is no warranty for the work (except to the
-extent that warranties are provided), that licensees may convey the
-work under this License, and how to view a copy of this License.  If
-the interface presents a list of user commands or options, such as a
-menu, a prominent item in the list meets this criterion.
-
-  1. Source Code.
-
-  The "source code" for a work means the preferred form of the work
-for making modifications to it.  "Object code" means any non-source
-form of a work.
-
-  A "Standard Interface" means an interface that either is an official
-standard defined by a recognized standards body, or, in the case of
-interfaces specified for a particular programming language, one that
-is widely used among developers working in that language.
-
-  The "System Libraries" of an executable work include anything, other
-than the work as a whole, that (a) is included in the normal form of
-packaging a Major Component, but which is not part of that Major
-Component, and (b) serves only to enable use of the work with that
-Major Component, or to implement a Standard Interface for which an
-implementation is available to the public in source code form.  A
-"Major Component", in this context, means a major essential component
-(kernel, window system, and so on) of the specific operating system
-(if any) on which the executable work runs, or a compiler used to
-produce the work, or an object code interpreter used to run it.
-
-  The "Corresponding Source" for a work in object code form means all
-the source code needed to generate, install, and (for an executable
-work) run the object code and to modify the work, including scripts to
-control those activities.  However, it does not include the work's
-System Libraries, or general-purpose tools or generally available free
-programs which are used unmodified in performing those activities but
-which are not part of the work.  For example, Corresponding Source
-includes interface definition files associated with source files for
-the work, and the source code for shared libraries and dynamically
-linked subprograms that the work is specifically designed to require,
-such as by intimate data communication or control flow between those
-subprograms and other parts of the work.
-
-  The Corresponding Source need not include anything that users
-can regenerate automatically from other parts of the Corresponding
-Source.
-
-  The Corresponding Source for a work in source code form is that
-same work.
-
-  2. Basic Permissions.
-
-  All rights granted under this License are granted for the term of
-copyright on the Program, and are irrevocable provided the stated
-conditions are met.  This License explicitly affirms your unlimited
-permission to run the unmodified Program.  The output from running a
-covered work is covered by this License only if the output, given its
-content, constitutes a covered work.  This License acknowledges your
-rights of fair use or other equivalent, as provided by copyright law.
-
-  You may make, run and propagate covered works that you do not
-convey, without conditions so long as your license otherwise remains
-in force.  You may convey covered works to others for the sole purpose
-of having them make modifications exclusively for you, or provide you
-with facilities for running those works, provided that you comply with
-the terms of this License in conveying all material for which you do
-not control copyright.  Those thus making or running the covered works
-for you must do so exclusively on your behalf, under your direction
-and control, on terms that prohibit them from making any copies of
-your copyrighted material outside their relationship with you.
-
-  Conveying under any other circumstances is permitted solely under
-the conditions stated below.  Sublicensing is not allowed; section 10
-makes it unnecessary.
-
-  3. Protecting Users' Legal Rights From Anti-Circumvention Law.
-
-  No covered work shall be deemed part of an effective technological
-measure under any applicable law fulfilling obligations under article
-11 of the WIPO copyright treaty adopted on 20 December 1996, or
-similar laws prohibiting or restricting circumvention of such
-measures.
-
-  When you convey a covered work, you waive any legal power to forbid
-circumvention of technological measures to the extent such circumvention
-is effected by exercising rights under this License with respect to
-the covered work, and you disclaim any intention to limit operation or
-modification of the work as a means of enforcing, against the work's
-users, your or third parties' legal rights to forbid circumvention of
-technological measures.
-
-  4. Conveying Verbatim Copies.
-
-  You may convey verbatim copies of the Program's source code as you
-receive it, in any medium, provided that you conspicuously and
-appropriately publish on each copy an appropriate copyright notice;
-keep intact all notices stating that this License and any
-non-permissive terms added in accord with section 7 apply to the code;
-keep intact all notices of the absence of any warranty; and give all
-recipients a copy of this License along with the Program.
-
-  You may charge any price or no price for each copy that you convey,
-and you may offer support or warranty protection for a fee.
-
-  5. Conveying Modified Source Versions.
-
-  You may convey a work based on the Program, or the modifications to
-produce it from the Program, in the form of source code under the
-terms of section 4, provided that you also meet all of these conditions:
-
-    a) The work must carry prominent notices stating that you modified
-    it, and giving a relevant date.
-
-    b) The work must carry prominent notices stating that it is
-    released under this License and any conditions added under section
-    7.  This requirement modifies the requirement in section 4 to
-    "keep intact all notices".
-
-    c) You must license the entire work, as a whole, under this
-    License to anyone who comes into possession of a copy.  This
-    License will therefore apply, along with any applicable section 7
-    additional terms, to the whole of the work, and all its parts,
-    regardless of how they are packaged.  This License gives no
-    permission to license the work in any other way, but it does not
-    invalidate such permission if you have separately received it.
-
-    d) If the work has interactive user interfaces, each must display
-    Appropriate Legal Notices; however, if the Program has interactive
-    interfaces that do not display Appropriate Legal Notices, your
-    work need not make them do so.
-
-  A compilation of a covered work with other separate and independent
-works, which are not by their nature extensions of the covered work,
-and which are not combined with it such as to form a larger program,
-in or on a volume of a storage or distribution medium, is called an
-"aggregate" if the compilation and its resulting copyright are not
-used to limit the access or legal rights of the compilation's users
-beyond what the individual works permit.  Inclusion of a covered work
-in an aggregate does not cause this License to apply to the other
-parts of the aggregate.
-
-  6. Conveying Non-Source Forms.
-
-  You may convey a covered work in object code form under the terms
-of sections 4 and 5, provided that you also convey the
-machine-readable Corresponding Source under the terms of this License,
-in one of these ways:
-
-    a) Convey the object code in, or embodied in, a physical product
-    (including a physical distribution medium), accompanied by the
-    Corresponding Source fixed on a durable physical medium
-    customarily used for software interchange.
-
-    b) Convey the object code in, or embodied in, a physical product
-    (including a physical distribution medium), accompanied by a
-    written offer, valid for at least three years and valid for as
-    long as you offer spare parts or customer support for that product
-    model, to give anyone who possesses the object code either (1) a
-    copy of the Corresponding Source for all the software in the
-    product that is covered by this License, on a durable physical
-    medium customarily used for software interchange, for a price no
-    more than your reasonable cost of physically performing this
-    conveying of source, or (2) access to copy the
-    Corresponding Source from a network server at no charge.
-
-    c) Convey individual copies of the object code with a copy of the
-    written offer to provide the Corresponding Source.  This
-    alternative is allowed only occasionally and noncommercially, and
-    only if you received the object code with such an offer, in accord
-    with subsection 6b.
-
-    d) Convey the object code by offering access from a designated
-    place (gratis or for a charge), and offer equivalent access to the
-    Corresponding Source in the same way through the same place at no
-    further charge.  You need not require recipients to copy the
-    Corresponding Source along with the object code.  If the place to
-    copy the object code is a network server, the Corresponding Source
-    may be on a different server (operated by you or a third party)
-    that supports equivalent copying facilities, provided you maintain
-    clear directions next to the object code saying where to find the
-    Corresponding Source.  Regardless of what server hosts the
-    Corresponding Source, you remain obligated to ensure that it is
-    available for as long as needed to satisfy these requirements.
-
-    e) Convey the object code using peer-to-peer transmission, provided
-    you inform other peers where the object code and Corresponding
-    Source of the work are being offered to the general public at no
-    charge under subsection 6d.
-
-  A separable portion of the object code, whose source code is excluded
-from the Corresponding Source as a System Library, need not be
-included in conveying the object code work.
-
-  A "User Product" is either (1) a "consumer product", which means any
-tangible personal property which is normally used for personal, family,
-or household purposes, or (2) anything designed or sold for incorporation
-into a dwelling.  In determining whether a product is a consumer product,
-doubtful cases shall be resolved in favor of coverage.  For a particular
-product received by a particular user, "normally used" refers to a
-typical or common use of that class of product, regardless of the status
-of the particular user or of the way in which the particular user
-actually uses, or expects or is expected to use, the product.  A product
-is a consumer product regardless of whether the product has substantial
-commercial, industrial or non-consumer uses, unless such uses represent
-the only significant mode of use of the product.
-
-  "Installation Information" for a User Product means any methods,
-procedures, authorization keys, or other information required to install
-and execute modified versions of a covered work in that User Product from
-a modified version of its Corresponding Source.  The information must
-suffice to ensure that the continued functioning of the modified object
-code is in no case prevented or interfered with solely because
-modification has been made.
-
-  If you convey an object code work under this section in, or with, or
-specifically for use in, a User Product, and the conveying occurs as
-part of a transaction in which the right of possession and use of the
-User Product is transferred to the recipient in perpetuity or for a
-fixed term (regardless of how the transaction is characterized), the
-Corresponding Source conveyed under this section must be accompanied
-by the Installation Information.  But this requirement does not apply
-if neither you nor any third party retains the ability to install
-modified object code on the User Product (for example, the work has
-been installed in ROM).
-
-  The requirement to provide Installation Information does not include a
-requirement to continue to provide support service, warranty, or updates
-for a work that has been modified or installed by the recipient, or for
-the User Product in which it has been modified or installed.  Access to a
-network may be denied when the modification itself materially and
-adversely affects the operation of the network or violates the rules and
-protocols for communication across the network.
-
-  Corresponding Source conveyed, and Installation Information provided,
-in accord with this section must be in a format that is publicly
-documented (and with an implementation available to the public in
-source code form), and must require no special password or key for
-unpacking, reading or copying.
-
-  7. Additional Terms.
-
-  "Additional permissions" are terms that supplement the terms of this
-License by making exceptions from one or more of its conditions.
-Additional permissions that are applicable to the entire Program shall
-be treated as though they were included in this License, to the extent
-that they are valid under applicable law.  If additional permissions
-apply only to part of the Program, that part may be used separately
-under those permissions, but the entire Program remains governed by
-this License without regard to the additional permissions.
-
-  When you convey a copy of a covered work, you may at your option
-remove any additional permissions from that copy, or from any part of
-it.  (Additional permissions may be written to require their own
-removal in certain cases when you modify the work.)  You may place
-additional permissions on material, added by you to a covered work,
-for which you have or can give appropriate copyright permission.
-
-  Notwithstanding any other provision of this License, for material you
-add to a covered work, you may (if authorized by the copyright holders of
-that material) supplement the terms of this License with terms:
-
-    a) Disclaiming warranty or limiting liability differently from the
-    terms of sections 15 and 16 of this License; or
-
-    b) Requiring preservation of specified reasonable legal notices or
-    author attributions in that material or in the Appropriate Legal
-    Notices displayed by works containing it; or
-
-    c) Prohibiting misrepresentation of the origin of that material, or
-    requiring that modified versions of such material be marked in
-    reasonable ways as different from the original version; or
-
-    d) Limiting the use for publicity purposes of names of licensors or
-    authors of the material; or
-
-    e) Declining to grant rights under trademark law for use of some
-    trade names, trademarks, or service marks; or
-
-    f) Requiring indemnification of licensors and authors of that
-    material by anyone who conveys the material (or modified versions of
-    it) with contractual assumptions of liability to the recipient, for
-    any liability that these contractual assumptions directly impose on
-    those licensors and authors.
-
-  All other non-permissive additional terms are considered "further
-restrictions" within the meaning of section 10.  If the Program as you
-received it, or any part of it, contains a notice stating that it is
-governed by this License along with a term that is a further
-restriction, you may remove that term.  If a license document contains
-a further restriction but permits relicensing or conveying under this
-License, you may add to a covered work material governed by the terms
-of that license document, provided that the further restriction does
-not survive such relicensing or conveying.
-
-  If you add terms to a covered work in accord with this section, you
-must place, in the relevant source files, a statement of the
-additional terms that apply to those files, or a notice indicating
-where to find the applicable terms.
-
-  Additional terms, permissive or non-permissive, may be stated in the
-form of a separately written license, or stated as exceptions;
-the above requirements apply either way.
-
-  8. Termination.
-
-  You may not propagate or modify a covered work except as expressly
-provided under this License.  Any attempt otherwise to propagate or
-modify it is void, and will automatically terminate your rights under
-this License (including any patent licenses granted under the third
-paragraph of section 11).
-
-  However, if you cease all violation of this License, then your
-license from a particular copyright holder is reinstated (a)
-provisionally, unless and until the copyright holder explicitly and
-finally terminates your license, and (b) permanently, if the copyright
-holder fails to notify you of the violation by some reasonable means
-prior to 60 days after the cessation.
-
-  Moreover, your license from a particular copyright holder is
-reinstated permanently if the copyright holder notifies you of the
-violation by some reasonable means, this is the first time you have
-received notice of violation of this License (for any work) from that
-copyright holder, and you cure the violation prior to 30 days after
-your receipt of the notice.
-
-  Termination of your rights under this section does not terminate the
-licenses of parties who have received copies or rights from you under
-this License.  If your rights have been terminated and not permanently
-reinstated, you do not qualify to receive new licenses for the same
-material under section 10.
-
-  9. Acceptance Not Required for Having Copies.
-
-  You are not required to accept this License in order to receive or
-run a copy of the Program.  Ancillary propagation of a covered work
-occurring solely as a consequence of using peer-to-peer transmission
-to receive a copy likewise does not require acceptance.  However,
-nothing other than this License grants you permission to propagate or
-modify any covered work.  These actions infringe copyright if you do
-not accept this License.  Therefore, by modifying or propagating a
-covered work, you indicate your acceptance of this License to do so.
-
-  10. Automatic Licensing of Downstream Recipients.
-
-  Each time you convey a covered work, the recipient automatically
-receives a license from the original licensors, to run, modify and
-propagate that work, subject to this License.  You are not responsible
-for enforcing compliance by third parties with this License.
-
-  An "entity transaction" is a transaction transferring control of an
-organization, or substantially all assets of one, or subdividing an
-organization, or merging organizations.  If propagation of a covered
-work results from an entity transaction, each party to that
-transaction who receives a copy of the work also receives whatever
-licenses to the work the party's predecessor in interest had or could
-give under the previous paragraph, plus a right to possession of the
-Corresponding Source of the work from the predecessor in interest, if
-the predecessor has it or can get it with reasonable efforts.
-
-  You may not impose any further restrictions on the exercise of the
-rights granted or affirmed under this License.  For example, you may
-not impose a license fee, royalty, or other charge for exercise of
-rights granted under this License, and you may not initiate litigation
-(including a cross-claim or counterclaim in a lawsuit) alleging that
-any patent claim is infringed by making, using, selling, offering for
-sale, or importing the Program or any portion of it.
-
-  11. Patents.
-
-  A "contributor" is a copyright holder who authorizes use under this
-License of the Program or a work on which the Program is based.  The
-work thus licensed is called the contributor's "contributor version".
-
-  A contributor's "essential patent claims" are all patent claims
-owned or controlled by the contributor, whether already acquired or
-hereafter acquired, that would be infringed by some manner, permitted
-by this License, of making, using, or selling its contributor version,
-but do not include claims that would be infringed only as a
-consequence of further modification of the contributor version.  For
-purposes of this definition, "control" includes the right to grant
-patent sublicenses in a manner consistent with the requirements of
-this License.
-
-  Each contributor grants you a non-exclusive, worldwide, royalty-free
-patent license under the contributor's essential patent claims, to
-make, use, sell, offer for sale, import and otherwise run, modify and
-propagate the contents of its contributor version.
-
-  In the following three paragraphs, a "patent license" is any express
-agreement or commitment, however denominated, not to enforce a patent
-(such as an express permission to practice a patent or covenant not to
-sue for patent infringement).  To "grant" such a patent license to a
-party means to make such an agreement or commitment not to enforce a
-patent against the party.
-
-  If you convey a covered work, knowingly relying on a patent license,
-and the Corresponding Source of the work is not available for anyone
-to copy, free of charge and under the terms of this License, through a
-publicly available network server or other readily accessible means,
-then you must either (1) cause the Corresponding Source to be so
-available, or (2) arrange to deprive yourself of the benefit of the
-patent license for this particular work, or (3) arrange, in a manner
-consistent with the requirements of this License, to extend the patent
-license to downstream recipients.  "Knowingly relying" means you have
-actual knowledge that, but for the patent license, your conveying the
-covered work in a country, or your recipient's use of the covered work
-in a country, would infringe one or more identifiable patents in that
-country that you have reason to believe are valid.
-
-  If, pursuant to or in connection with a single transaction or
-arrangement, you convey, or propagate by procuring conveyance of, a
-covered work, and grant a patent license to some of the parties
-receiving the covered work authorizing them to use, propagate, modify
-or convey a specific copy of the covered work, then the patent license
-you grant is automatically extended to all recipients of the covered
-work and works based on it.
-
-  A patent license is "discriminatory" if it does not include within
-the scope of its coverage, prohibits the exercise of, or is
-conditioned on the non-exercise of one or more of the rights that are
-specifically granted under this License.  You may not convey a covered
-work if you are a party to an arrangement with a third party that is
-in the business of distributing software, under which you make payment
-to the third party based on the extent of your activity of conveying
-the work, and under which the third party grants, to any of the
-parties who would receive the covered work from you, a discriminatory
-patent license (a) in connection with copies of the covered work
-conveyed by you (or copies made from those copies), or (b) primarily
-for and in connection with specific products or compilations that
-contain the covered work, unless you entered into that arrangement,
-or that patent license was granted, prior to 28 March 2007.
-
-  Nothing in this License shall be construed as excluding or limiting
-any implied license or other defenses to infringement that may
-otherwise be available to you under applicable patent law.
-
-  12. No Surrender of Others' Freedom.
-
-  If conditions are imposed on you (whether by court order, agreement or
-otherwise) that contradict the conditions of this License, they do not
-excuse you from the conditions of this License.  If you cannot convey a
-covered work so as to satisfy simultaneously your obligations under this
-License and any other pertinent obligations, then as a consequence you may
-not convey it at all.  For example, if you agree to terms that obligate you
-to collect a royalty for further conveying from those to whom you convey
-the Program, the only way you could satisfy both those terms and this
-License would be to refrain entirely from conveying the Program.
-
-  13. Remote Network Interaction; Use with the GNU General Public License.
-
-  Notwithstanding any other provision of this License, if you modify the
-Program, your modified version must prominently offer all users
-interacting with it remotely through a computer network (if your version
-supports such interaction) an opportunity to receive the Corresponding
-Source of your version by providing access to the Corresponding Source
-from a network server at no charge, through some standard or customary
-means of facilitating copying of software.  This Corresponding Source
-shall include the Corresponding Source for any work covered by version 3
-of the GNU General Public License that is incorporated pursuant to the
-following paragraph.
-
-  Notwithstanding any other provision of this License, you have
-permission to link or combine any covered work with a work licensed
-under version 3 of the GNU General Public License into a single
-combined work, and to convey the resulting work.  The terms of this
-License will continue to apply to the part which is the covered work,
-but the work with which it is combined will remain governed by version
-3 of the GNU General Public License.
-
-  14. Revised Versions of this License.
-
-  The Free Software Foundation may publish revised and/or new versions of
-the GNU Affero General Public License from time to time.  Such new versions
-will be similar in spirit to the present version, but may differ in detail to
-address new problems or concerns.
-
-  Each version is given a distinguishing version number.  If the
-Program specifies that a certain numbered version of the GNU Affero General
-Public License "or any later version" applies to it, you have the
-option of following the terms and conditions either of that numbered
-version or of any later version published by the Free Software
-Foundation.  If the Program does not specify a version number of the
-GNU Affero General Public License, you may choose any version ever published
-by the Free Software Foundation.
-
-  If the Program specifies that a proxy can decide which future
-versions of the GNU Affero General Public License can be used, that proxy's
-public statement of acceptance of a version permanently authorizes you
-to choose that version for the Program.
-
-  Later license versions may give you additional or different
-permissions.  However, no additional obligations are imposed on any
-author or copyright holder as a result of your choosing to follow a
-later version.
-
-  15. Disclaimer of Warranty.
-
-  THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
-APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
-HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
-OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
-THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
-PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
-IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
-ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
-
-  16. Limitation of Liability.
-
-  IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
-WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
-THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
-GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
-USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
-DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
-PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
-EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
-SUCH DAMAGES.
-
-  17. Interpretation of Sections 15 and 16.
-
-  If the disclaimer of warranty and limitation of liability provided
-above cannot be given local legal effect according to their terms,
-reviewing courts shall apply local law that most closely approximates
-an absolute waiver of all civil liability in connection with the
-Program, unless a warranty or assumption of liability accompanies a
-copy of the Program in return for a fee.
-
-                     END OF TERMS AND CONDITIONS
-
-            How to Apply These Terms to Your New Programs
-
-  If you develop a new program, and you want it to be of the greatest
-possible use to the public, the best way to achieve this is to make it
-free software which everyone can redistribute and change under these terms.
-
-  To do so, attach the following notices to the program.  It is safest
-to attach them to the start of each source file to most effectively
-state the exclusion of warranty; and each file should have at least
-the "copyright" line and a pointer to where the full notice is found.
-
-    <one line to give the program's name and a brief idea of what it does.>
-    Copyright (C) <year>  <name of author>
-
-    This program is free software: you can redistribute it and/or modify
-    it under the terms of the GNU Affero General Public License as published by
-    the Free Software Foundation, either version 3 of the License, or
-    (at your option) any later version.
-
-    This program is distributed in the hope that it will be useful,
-    but WITHOUT ANY WARRANTY; without even the implied warranty of
-    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-    GNU Affero General Public License for more details.
-
-    You should have received a copy of the GNU Affero General Public License
-    along with this program.  If not, see <https://www.gnu.org/licenses/>.
+GNU GENERAL PUBLIC LICENSE
+Version 3, 29 June 2007
+
+Copyright © 2007 Free Software Foundation, Inc. <https://fsf.org/>
+
+Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.
+
+Preamble
+
+The GNU General Public License is a free, copyleft license for software and other kinds of works.
+
+The licenses for most software and other practical works are designed to take away your freedom to share and change the works. By contrast, the GNU General Public License is intended to guarantee your freedom to share and change all versions of a program--to make sure it remains free software for all its users. We, the Free Software Foundation, use the GNU General Public License for most of our software; it applies also to any other work released this way by its authors. You can apply it to your programs, too.
+
+When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for them if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs, and that you know you can do these things.
+
+To protect your rights, we need to prevent others from denying you these rights or asking you to surrender the rights. Therefore, you have certain responsibilities if you distribute copies of the software, or if you modify it: responsibilities to respect the freedom of others.
+
+For example, if you distribute copies of such a program, whether gratis or for a fee, you must pass on to the recipients the same freedoms that you received. You must make sure that they, too, receive or can get the source code. And you must show them these terms so they know their rights.
+
+Developers that use the GNU GPL protect your rights with two steps: (1) assert copyright on the software, and (2) offer you this License giving you legal permission to copy, distribute and/or modify it.
+
+For the developers' and authors' protection, the GPL clearly explains that there is no warranty for this free software. For both users' and authors' sake, the GPL requires that modified versions be marked as changed, so that their problems will not be attributed erroneously to authors of previous versions.
+
+Some devices are designed to deny users access to install or run modified versions of the software inside them, although the manufacturer can do so. This is fundamentally incompatible with the aim of protecting users' freedom to change the software. The systematic pattern of such abuse occurs in the area of products for individuals to use, which is precisely where it is most unacceptable. Therefore, we have designed this version of the GPL to prohibit the practice for those products. If such problems arise substantially in other domains, we stand ready to extend this provision to those domains in future versions of the GPL, as needed to protect the freedom of users.
+
+Finally, every program is threatened constantly by software patents. States should not allow patents to restrict development and use of software on general-purpose computers, but in those that do, we wish to avoid the special danger that patents applied to a free program could make it effectively proprietary. To prevent this, the GPL assures that patents cannot be used to render the program non-free.
+
+The precise terms and conditions for copying, distribution and modification follow.
+
+TERMS AND CONDITIONS
+
+0. Definitions.
+
+“This License” refers to version 3 of the GNU General Public License.
+
+“Copyright” also means copyright-like laws that apply to other kinds of works, such as semiconductor masks.
+
+“The Program” refers to any copyrightable work licensed under this License. Each licensee is addressed as “you”. “Licensees” and “recipients” may be individuals or organizations.
+
+To “modify” a work means to copy from or adapt all or part of the work in a fashion requiring copyright permission, other than the making of an exact copy. The resulting work is called a “modified version” of the earlier work or a work “based on” the earlier work.
+
+A “covered work” means either the unmodified Program or a work based on the Program.
+
+To “propagate” a work means to do anything with it that, without permission, would make you directly or secondarily liable for infringement under applicable copyright law, except executing it on a computer or modifying a private copy. Propagation includes copying, distribution (with or without modification), making available to the public, and in some countries other activities as well.
+
+To “convey” a work means any kind of propagation that enables other parties to make or receive copies. Mere interaction with a user through a computer network, with no transfer of a copy, is not conveying.
+
+An interactive user interface displays “Appropriate Legal Notices” to the extent that it includes a convenient and prominently visible feature that (1) displays an appropriate copyright notice, and (2) tells the user that there is no warranty for the work (except to the extent that warranties are provided), that licensees may convey the work under this License, and how to view a copy of this License. If the interface presents a list of user commands or options, such as a menu, a prominent item in the list meets this criterion.
+
+1. Source Code.
+The “source code” for a work means the preferred form of the work for making modifications to it. “Object code” means any non-source form of a work.
+
+A “Standard Interface” means an interface that either is an official standard defined by a recognized standards body, or, in the case of interfaces specified for a particular programming language, one that is widely used among developers working in that language.
+
+The “System Libraries” of an executable work include anything, other than the work as a whole, that (a) is included in the normal form of packaging a Major Component, but which is not part of that Major Component, and (b) serves only to enable use of the work with that Major Component, or to implement a Standard Interface for which an implementation is available to the public in source code form. A “Major Component”, in this context, means a major essential component (kernel, window system, and so on) of the specific operating system (if any) on which the executable work runs, or a compiler used to produce the work, or an object code interpreter used to run it.
+
+The “Corresponding Source” for a work in object code form means all the source code needed to generate, install, and (for an executable work) run the object code and to modify the work, including scripts to control those activities. However, it does not include the work's System Libraries, or general-purpose tools or generally available free programs which are used unmodified in performing those activities but which are not part of the work. For example, Corresponding Source includes interface definition files associated with source files for the work, and the source code for shared libraries and dynamically linked subprograms that the work is specifically designed to require, such as by intimate data communication or control flow between those subprograms and other parts of the work.
+
+The Corresponding Source need not include anything that users can regenerate automatically from other parts of the Corresponding Source.
+
+The Corresponding Source for a work in source code form is that same work.
+
+2. Basic Permissions.
+All rights granted under this License are granted for the term of copyright on the Program, and are irrevocable provided the stated conditions are met. This License explicitly affirms your unlimited permission to run the unmodified Program. The output from running a covered work is covered by this License only if the output, given its content, constitutes a covered work. This License acknowledges your rights of fair use or other equivalent, as provided by copyright law.
+
+You may make, run and propagate covered works that you do not convey, without conditions so long as your license otherwise remains in force. You may convey covered works to others for the sole purpose of having them make modifications exclusively for you, or provide you with facilities for running those works, provided that you comply with the terms of this License in conveying all material for which you do not control copyright. Those thus making or running the covered works for you must do so exclusively on your behalf, under your direction and control, on terms that prohibit them from making any copies of your copyrighted material outside their relationship with you.
+
+Conveying under any other circumstances is permitted solely under the conditions stated below. Sublicensing is not allowed; section 10 makes it unnecessary.
+
+3. Protecting Users' Legal Rights From Anti-Circumvention Law.
+No covered work shall be deemed part of an effective technological measure under any applicable law fulfilling obligations under article 11 of the WIPO copyright treaty adopted on 20 December 1996, or similar laws prohibiting or restricting circumvention of such measures.
+
+When you convey a covered work, you waive any legal power to forbid circumvention of technological measures to the extent such circumvention is effected by exercising rights under this License with respect to the covered work, and you disclaim any intention to limit operation or modification of the work as a means of enforcing, against the work's users, your or third parties' legal rights to forbid circumvention of technological measures.
+
+4. Conveying Verbatim Copies.
+You may convey verbatim copies of the Program's source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice; keep intact all notices stating that this License and any non-permissive terms added in accord with section 7 apply to the code; keep intact all notices of the absence of any warranty; and give all recipients a copy of this License along with the Program.
+
+You may charge any price or no price for each copy that you convey, and you may offer support or warranty protection for a fee.
+
+5. Conveying Modified Source Versions.
+You may convey a work based on the Program, or the modifications to produce it from the Program, in the form of source code under the terms of section 4, provided that you also meet all of these conditions:
+
+     a) The work must carry prominent notices stating that you modified it, and giving a relevant date.
+
+     b) The work must carry prominent notices stating that it is released under this License and any conditions added under section 7. This requirement modifies the requirement in section 4 to “keep intact all notices”.
+
+     c) You must license the entire work, as a whole, under this License to anyone who comes into possession of a copy. This License will therefore apply, along with any applicable section 7 additional terms, to the whole of the work, and all its parts, regardless of how they are packaged. This License gives no permission to license the work in any other way, but it does not invalidate such permission if you have separately received it.
+
+     d) If the work has interactive user interfaces, each must display Appropriate Legal Notices; however, if the Program has interactive interfaces that do not display Appropriate Legal Notices, your work need not make them do so.
+
+A compilation of a covered work with other separate and independent works, which are not by their nature extensions of the covered work, and which are not combined with it such as to form a larger program, in or on a volume of a storage or distribution medium, is called an “aggregate” if the compilation and its resulting copyright are not used to limit the access or legal rights of the compilation's users beyond what the individual works permit. Inclusion of a covered work in an aggregate does not cause this License to apply to the other parts of the aggregate.
+
+6. Conveying Non-Source Forms.
+You may convey a covered work in object code form under the terms of sections 4 and 5, provided that you also convey the machine-readable Corresponding Source under the terms of this License, in one of these ways:
+
+     a) Convey the object code in, or embodied in, a physical product (including a physical distribution medium), accompanied by the Corresponding Source fixed on a durable physical medium customarily used for software interchange.
+
+     b) Convey the object code in, or embodied in, a physical product (including a physical distribution medium), accompanied by a written offer, valid for at least three years and valid for as long as you offer spare parts or customer support for that product model, to give anyone who possesses the object code either (1) a copy of the Corresponding Source for all the software in the product that is covered by this License, on a durable physical medium customarily used for software interchange, for a price no more than your reasonable cost of physically performing this conveying of source, or (2) access to copy the Corresponding Source from a network server at no charge.
+
+     c) Convey individual copies of the object code with a copy of the written offer to provide the Corresponding Source. This alternative is allowed only occasionally and noncommercially, and only if you received the object code with such an offer, in accord with subsection 6b.
+
+     d) Convey the object code by offering access from a designated place (gratis or for a charge), and offer equivalent access to the Corresponding Source in the same way through the same place at no further charge. You need not require recipients to copy the Corresponding Source along with the object code. If the place to copy the object code is a network server, the Corresponding Source may be on a different server (operated by you or a third party) that supports equivalent copying facilities, provided you maintain clear directions next to the object code saying where to find the Corresponding Source. Regardless of what server hosts the Corresponding Source, you remain obligated to ensure that it is available for as long as needed to satisfy these requirements.
+
+     e) Convey the object code using peer-to-peer transmission, provided you inform other peers where the object code and Corresponding Source of the work are being offered to the general public at no charge under subsection 6d.
+
+A separable portion of the object code, whose source code is excluded from the Corresponding Source as a System Library, need not be included in conveying the object code work.
+
+A “User Product” is either (1) a “consumer product”, which means any tangible personal property which is normally used for personal, family, or household purposes, or (2) anything designed or sold for incorporation into a dwelling. In determining whether a product is a consumer product, doubtful cases shall be resolved in favor of coverage. For a particular product received by a particular user, “normally used” refers to a typical or common use of that class of product, regardless of the status of the particular user or of the way in which the particular user actually uses, or expects or is expected to use, the product. A product is a consumer product regardless of whether the product has substantial commercial, industrial or non-consumer uses, unless such uses represent the only significant mode of use of the product.
+
+“Installation Information” for a User Product means any methods, procedures, authorization keys, or other information required to install and execute modified versions of a covered work in that User Product from a modified version of its Corresponding Source. The information must suffice to ensure that the continued functioning of the modified object code is in no case prevented or interfered with solely because modification has been made.
+
+If you convey an object code work under this section in, or with, or specifically for use in, a User Product, and the conveying occurs as part of a transaction in which the right of possession and use of the User Product is transferred to the recipient in perpetuity or for a fixed term (regardless of how the transaction is characterized), the Corresponding Source conveyed under this section must be accompanied by the Installation Information. But this requirement does not apply if neither you nor any third party retains the ability to install modified object code on the User Product (for example, the work has been installed in ROM).
+
+The requirement to provide Installation Information does not include a requirement to continue to provide support service, warranty, or updates for a work that has been modified or installed by the recipient, or for the User Product in which it has been modified or installed. Access to a network may be denied when the modification itself materially and adversely affects the operation of the network or violates the rules and protocols for communication across the network.
+
+Corresponding Source conveyed, and Installation Information provided, in accord with this section must be in a format that is publicly documented (and with an implementation available to the public in source code form), and must require no special password or key for unpacking, reading or copying.
+
+7. Additional Terms.
+“Additional permissions” are terms that supplement the terms of this License by making exceptions from one or more of its conditions. Additional permissions that are applicable to the entire Program shall be treated as though they were included in this License, to the extent that they are valid under applicable law. If additional permissions apply only to part of the Program, that part may be used separately under those permissions, but the entire Program remains governed by this License without regard to the additional permissions.
+
+When you convey a copy of a covered work, you may at your option remove any additional permissions from that copy, or from any part of it. (Additional permissions may be written to require their own removal in certain cases when you modify the work.) You may place additional permissions on material, added by you to a covered work, for which you have or can give appropriate copyright permission.
+
+Notwithstanding any other provision of this License, for material you add to a covered work, you may (if authorized by the copyright holders of that material) supplement the terms of this License with terms:
+
+     a) Disclaiming warranty or limiting liability differently from the terms of sections 15 and 16 of this License; or
+
+     b) Requiring preservation of specified reasonable legal notices or author attributions in that material or in the Appropriate Legal Notices displayed by works containing it; or
+
+     c) Prohibiting misrepresentation of the origin of that material, or requiring that modified versions of such material be marked in reasonable ways as different from the original version; or
+
+     d) Limiting the use for publicity purposes of names of licensors or authors of the material; or
+
+     e) Declining to grant rights under trademark law for use of some trade names, trademarks, or service marks; or
+
+     f) Requiring indemnification of licensors and authors of that material by anyone who conveys the material (or modified versions of it) with contractual assumptions of liability to the recipient, for any liability that these contractual assumptions directly impose on those licensors and authors.
+
+All other non-permissive additional terms are considered “further restrictions” within the meaning of section 10. If the Program as you received it, or any part of it, contains a notice stating that it is governed by this License along with a term that is a further restriction, you may remove that term. If a license document contains a further restriction but permits relicensing or conveying under this License, you may add to a covered work material governed by the terms of that license document, provided that the further restriction does not survive such relicensing or conveying.
+
+If you add terms to a covered work in accord with this section, you must place, in the relevant source files, a statement of the additional terms that apply to those files, or a notice indicating where to find the applicable terms.
+
+Additional terms, permissive or non-permissive, may be stated in the form of a separately written license, or stated as exceptions; the above requirements apply either way.
+
+8. Termination.
+You may not propagate or modify a covered work except as expressly provided under this License. Any attempt otherwise to propagate or modify it is void, and will automatically terminate your rights under this License (including any patent licenses granted under the third paragraph of section 11).
+
+However, if you cease all violation of this License, then your license from a particular copyright holder is reinstated (a) provisionally, unless and until the copyright holder explicitly and finally terminates your license, and (b) permanently, if the copyright holder fails to notify you of the violation by some reasonable means prior to 60 days after the cessation.
+
+Moreover, your license from a particular copyright holder is reinstated permanently if the copyright holder notifies you of the violation by some reasonable means, this is the first time you have received notice of violation of this License (for any work) from that copyright holder, and you cure the violation prior to 30 days after your receipt of the notice.
+
+Termination of your rights under this section does not terminate the licenses of parties who have received copies or rights from you under this License. If your rights have been terminated and not permanently reinstated, you do not qualify to receive new licenses for the same material under section 10.
+
+9. Acceptance Not Required for Having Copies.
+You are not required to accept this License in order to receive or run a copy of the Program. Ancillary propagation of a covered work occurring solely as a consequence of using peer-to-peer transmission to receive a copy likewise does not require acceptance. However, nothing other than this License grants you permission to propagate or modify any covered work. These actions infringe copyright if you do not accept this License. Therefore, by modifying or propagating a covered work, you indicate your acceptance of this License to do so.
+
+10. Automatic Licensing of Downstream Recipients.
+Each time you convey a covered work, the recipient automatically receives a license from the original licensors, to run, modify and propagate that work, subject to this License. You are not responsible for enforcing compliance by third parties with this License.
+
+An “entity transaction” is a transaction transferring control of an organization, or substantially all assets of one, or subdividing an organization, or merging organizations. If propagation of a covered work results from an entity transaction, each party to that transaction who receives a copy of the work also receives whatever licenses to the work the party's predecessor in interest had or could give under the previous paragraph, plus a right to possession of the Corresponding Source of the work from the predecessor in interest, if the predecessor has it or can get it with reasonable efforts.
+
+You may not impose any further restrictions on the exercise of the rights granted or affirmed under this License. For example, you may not impose a license fee, royalty, or other charge for exercise of rights granted under this License, and you may not initiate litigation (including a cross-claim or counterclaim in a lawsuit) alleging that any patent claim is infringed by making, using, selling, offering for sale, or importing the Program or any portion of it.
+
+11. Patents.
+A “contributor” is a copyright holder who authorizes use under this License of the Program or a work on which the Program is based. The work thus licensed is called the contributor's “contributor version”.
+
+A contributor's “essential patent claims” are all patent claims owned or controlled by the contributor, whether already acquired or hereafter acquired, that would be infringed by some manner, permitted by this License, of making, using, or selling its contributor version, but do not include claims that would be infringed only as a consequence of further modification of the contributor version. For purposes of this definition, “control” includes the right to grant patent sublicenses in a manner consistent with the requirements of this License.
+
+Each contributor grants you a non-exclusive, worldwide, royalty-free patent license under the contributor's essential patent claims, to make, use, sell, offer for sale, import and otherwise run, modify and propagate the contents of its contributor version.
+
+In the following three paragraphs, a “patent license” is any express agreement or commitment, however denominated, not to enforce a patent (such as an express permission to practice a patent or covenant not to sue for patent infringement). To “grant” such a patent license to a party means to make such an agreement or commitment not to enforce a patent against the party.
+
+If you convey a covered work, knowingly relying on a patent license, and the Corresponding Source of the work is not available for anyone to copy, free of charge and under the terms of this License, through a publicly available network server or other readily accessible means, then you must either (1) cause the Corresponding Source to be so available, or (2) arrange to deprive yourself of the benefit of the patent license for this particular work, or (3) arrange, in a manner consistent with the requirements of this License, to extend the patent license to downstream recipients. “Knowingly relying” means you have actual knowledge that, but for the patent license, your conveying the covered work in a country, or your recipient's use of the covered work in a country, would infringe one or more identifiable patents in that country that you have reason to believe are valid.
+
+If, pursuant to or in connection with a single transaction or arrangement, you convey, or propagate by procuring conveyance of, a covered work, and grant a patent license to some of the parties receiving the covered work authorizing them to use, propagate, modify or convey a specific copy of the covered work, then the patent license you grant is automatically extended to all recipients of the covered work and works based on it.
+
+A patent license is “discriminatory” if it does not include within the scope of its coverage, prohibits the exercise of, or is conditioned on the non-exercise of one or more of the rights that are specifically granted under this License. You may not convey a covered work if you are a party to an arrangement with a third party that is in the business of distributing software, under which you make payment to the third party based on the extent of your activity of conveying the work, and under which the third party grants, to any of the parties who would receive the covered work from you, a discriminatory patent license (a) in connection with copies of the covered work conveyed by you (or copies made from those copies), or (b) primarily for and in connection with specific products or compilations that contain the covered work, unless you entered into that arrangement, or that patent license was granted, prior to 28 March 2007.
+
+Nothing in this License shall be construed as excluding or limiting any implied license or other defenses to infringement that may otherwise be available to you under applicable patent law.
+
+12. No Surrender of Others' Freedom.
+If conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot convey a covered work so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not convey it at all. For example, if you agree to terms that obligate you to collect a royalty for further conveying from those to whom you convey the Program, the only way you could satisfy both those terms and this License would be to refrain entirely from conveying the Program.
+
+13. Use with the GNU Affero General Public License.
+Notwithstanding any other provision of this License, you have permission to link or combine any covered work with a work licensed under version 3 of the GNU Affero General Public License into a single combined work, and to convey the resulting work. The terms of this License will continue to apply to the part which is the covered work, but the special requirements of the GNU Affero General Public License, section 13, concerning interaction through a network will apply to the combination as such.
+
+14. Revised Versions of this License.
+The Free Software Foundation may publish revised and/or new versions of the GNU General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns.
+
+Each version is given a distinguishing version number. If the Program specifies that a certain numbered version of the GNU General Public License “or any later version” applies to it, you have the option of following the terms and conditions either of that numbered version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of the GNU General Public License, you may choose any version ever published by the Free Software Foundation.
+
+If the Program specifies that a proxy can decide which future versions of the GNU General Public License can be used, that proxy's public statement of acceptance of a version permanently authorizes you to choose that version for the Program.
+
+Later license versions may give you additional or different permissions. However, no additional obligations are imposed on any author or copyright holder as a result of your choosing to follow a later version.
+
+15. Disclaimer of Warranty.
+THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+16. Limitation of Liability.
+IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+
+17. Interpretation of Sections 15 and 16.
+If the disclaimer of warranty and limitation of liability provided above cannot be given local legal effect according to their terms, reviewing courts shall apply local law that most closely approximates an absolute waiver of all civil liability in connection with the Program, unless a warranty or assumption of liability accompanies a copy of the Program in return for a fee.
+
+END OF TERMS AND CONDITIONS
+
+How to Apply These Terms to Your New Programs
+
+If you develop a new program, and you want it to be of the greatest possible use to the public, the best way to achieve this is to make it free software which everyone can redistribute and change under these terms.
+
+To do so, attach the following notices to the program. It is safest to attach them to the start of each source file to most effectively state the exclusion of warranty; and each file should have at least the “copyright” line and a pointer to where the full notice is found.
+
+     bookhoard
+      Copyright (C) 2026  john-okeefe
+
+     This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
+
+     This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
+
+     You should have received a copy of the GNU General Public License along with this program.  If not, see <https://www.gnu.org/licenses/>.
 
 Also add information on how to contact you by electronic and paper mail.
 
-  If your software can interact with users remotely through a computer
-network, you should also make sure that it provides a way for users to
-get its source.  For example, if your program is a web application, its
-interface could display a "Source" link that leads users to an archive
-of the code.  There are many ways you could offer source, and different
-solutions will be better for different programs; see section 13 for the
-specific requirements.
+If the program does terminal interaction, make it output a short notice like this when it starts in an interactive mode:
 
-  You should also get your employer (if you work as a programmer) or school,
-if any, to sign a "copyright disclaimer" for the program, if necessary.
-For more information on this, and how to apply and follow the GNU AGPL, see
-<https://www.gnu.org/licenses/>.
+     bookhoard  Copyright (C) 2026  john-okeefe
+     This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
+     This is free software, and you are welcome to redistribute it under certain conditions; type `show c' for details.
+
+The hypothetical commands `show w' and `show c' should show the appropriate parts of the General Public License. Of course, your program's commands might be different; for a GUI interface, you would use an “about box”.
+
+You should also get your employer (if you work as a programmer) or school, if any, to sign a “copyright disclaimer” for the program, if necessary. For more information on this, and how to apply and follow the GNU GPL, see <https://www.gnu.org/licenses/>.
+
+The GNU General Public License does not permit incorporating your program into proprietary programs. If your program is a subroutine library, you may consider it more useful to permit linking proprietary applications with the library. If this is what you want to do, use the GNU Lesser General Public License instead of this License. But first, please read <https://www.gnu.org/philosophy/why-not-lgpl.html>.

Makefile

@@ -1,4 +1,4 @@
-.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
+.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
 
 # Include .env file for environment variables (single source of truth)
 # Ignore if .env doesn't exist yet
@@ -7,14 +7,6 @@ ifneq (,$(wildcard ./.env))
     export
 endif
 
-# Auto-detect container runtime: prefer docker, fall back to podman
-# Override with: CONTAINER_RUNTIME=podman make rebuild-app
-CONTAINER_RUNTIME ?= $(shell command -v docker 2>/dev/null || command -v podman 2>/dev/null)
-
-# Dev compose stack: base prod file merged with the dev override (local build + tests).
-# Prod deploy does NOT use this — it runs plain `docker compose` against the base file only.
-COMPOSE := $(CONTAINER_RUNTIME) compose -f docker-compose.yml -f docker-compose.dev.yml
-
 # Default target
 help:
 	@echo "Available targets:"
@@ -42,59 +34,33 @@ help:
 	@echo "  make test-env-down     - Stop test environment"
 	@echo ""
 	@echo "Verification:"
-	@echo ""
-	@echo "Release:"
-	@echo "  ./release v0.3.0            - Tag, push, and release (notes auto-generated from commits)"
+	@echo "  make verify-guidelines - Run comprehensive guidelines check"
+	@echo "  make verify-quick      - Run quick guidelines check"
 
 # Run unit tests locally (fast, no containers)
-test: lint-rendering
+test:
 	go test ./internal/... -v -short
 
-# Rendering-ownership guard (AGENTS.md → Rendering ownership): templ renders
-# UI markup, JS orchestrates. Fails when a web/src file builds more HTML
-# template literals than its recorded baseline (web/src/rendering-allowlist.txt),
-# or when a .templ file gains an inline <script> block (theme_flash_guard.templ
-# is the only sanctioned one). Shrink baselines as fragments move to templ
-# partials; grow one only with a written reason.
-lint-rendering:
-	@violations=""; \
-	for f in $$(grep -rlE 'innerHTML[[:space:]]*=[[:space:]]*' web/src --include='*.ts' | grep -v 'web/src/reader/'); do \
-		count=$$(grep -E 'innerHTML[[:space:]]*=[[:space:]]*' $$f | grep -cvE 'innerHTML[[:space:]]*=[[:space:]]*""[[:space:]]*$$'); \
-		allowed=$$(grep -F "$$f:" web/src/rendering-allowlist.txt | cut -d: -f2); \
-		allowed=$${allowed:-0}; \
-		if [ $$count -gt $$allowed ]; then \
-			violations="$$violations $$f ($$count > $$allowed)"; \
-		fi; \
-	done; \
-	for f in $$(grep -rln '<script>' templates --include='*.templ'); do \
-		case $$f in *theme_flash_guard*) continue;; esac; \
-		violations="$$violations $$f (inline script)"; \
-	done; \
-	if [ -n "$$violations" ]; then \
-		echo "rendering-ownership violations:$$violations"; exit 1; \
-	fi; \
-	echo "rendering ownership OK"
-
 # Run integration tests in containers (matches production environment)
 test-integration:
 	@echo "Building test containers..."
-	$(COMPOSE) --profile tests build
+	podman compose --profile tests build
 	@echo "Starting application containers..."
-	$(COMPOSE) up -d db app
+	podman compose up -d db app
 	@echo "Waiting for services to be healthy..."
-	@until $(CONTAINER_RUNTIME) exec bookhoard_db pg_isready -U postgres > /dev/null 2>&1; do \
+	@until podman exec bookhoard_db pg_isready -U postgres > /dev/null 2>&1; do \
 		echo "  Database not ready yet..."; \
 		sleep 2; \
 	done; \
 	echo "  ✓ Database is ready"
-	@until $(CONTAINER_RUNTIME) exec bookhoard curl -sf http://localhost:8765/health > /dev/null 2>&1; do \
+	@until podman exec bookhoard curl -sf http://localhost:8765/health > /dev/null 2>&1; do \
 		echo "  Application not ready yet..."; \
 		sleep 2; \
 	done; \
 	echo "  ✓ Application is ready"
 	@echo ""
 	@echo "Running integration tests in container..."
-	$(COMPOSE) --profile tests run --rm tests
+	podman compose --profile tests run --rm tests
 	@echo ""
 	@echo "✅ Integration tests completed!"
 	@echo "📝 Containers are still running. Use 'make logs' to view logs or 'make clean' to stop."
@@ -105,99 +71,82 @@ test-all: test test-integration
 # Rebuild app container only (preserve DB, with cache)
 rebuild-app:
 	@echo "Rebuilding app container (database stays running)..."
-	$(COMPOSE) up --build --force-recreate -d app
+	podman compose up --build --force-recreate -d app
 	@echo "✓ App container rebuilt and restarted"
 
 # Rebuild app container only (preserve DB, no cache)
 rebuild-app-force:
 	@echo "Force rebuilding app container (database stays running, no cache)..."
-	$(COMPOSE) build --no-cache app
-	$(COMPOSE) up --force-recreate -d app
+	podman compose build --no-cache app
+	podman compose up --force-recreate -d app
 	@echo "✓ App container rebuilt and restarted"
 
 # Rebuild all containers (preserve DB, with cache)
 rebuild:
 	@echo "Rebuilding all containers (database preserved)..."
-	$(COMPOSE) up --build --force-recreate -d
+	podman compose up --build --force-recreate -d
 	@echo "✓ All containers rebuilt and restarted"
 
 # Rebuild all containers (preserve DB, no cache)
 rebuild-force:
 	@echo "Force rebuilding all containers (database preserved, no cache)..."
-	$(COMPOSE) build --no-cache
-	$(COMPOSE) up --force-recreate -d
+	podman compose build --no-cache
+	podman compose up --force-recreate -d
 	@echo "✓ All containers rebuilt and restarted"
 
 # Rebuild all containers (remove DB, no cache)
 rebuild-force-db:
 	@echo "Force rebuilding all containers (database will be DELETED, no cache)..."
-	$(COMPOSE) down -v
-	$(COMPOSE) build --no-cache
-	$(COMPOSE) up --force-recreate -d
+	podman compose down -v
+	podman compose build --no-cache
+	podman compose up --force-recreate -d
 	@echo "✓ All containers rebuilt and restarted"
 
 # Stop and remove containers
 clean:
-	$(COMPOSE) down -v
+	podman compose down -v
 
 # Quick start (if already built)
 up:
-	$(COMPOSE) up -d
+	podman compose up -d
 
 # Stop all containers (alias for clean)
 down:
-	$(COMPOSE) down
+	podman compose down
 
 # Restart app container (preserves database)
 restart:
 	@echo "Restarting app container (database stays running)..."
-	$(COMPOSE) restart app
+	podman compose restart app
 	@echo "✓ App container restarted"
 
 # Show container status
 ps:
-	$(COMPOSE) ps
+	podman compose ps
 
 # Show container logs
 logs:
-	$(COMPOSE) logs -f
+	podman compose logs -f
 
 # Start containers with test mode enabled for manual testing
 test-env-up:
 	@echo "Starting containers with test mode enabled..."
-	TEST_MODE=true RATE_LIMIT_ENABLED=false REQUESTS_PER_MINUTE=1000 $(COMPOSE) up --build --force-recreate -d
+	TEST_MODE=true RATE_LIMIT_ENABLED=false REQUESTS_PER_MINUTE=1000 podman compose up --build --force-recreate -d
 	@echo "Waiting for services to be ready..."
-	@until $(CONTAINER_RUNTIME) exec bookhoard_db pg_isready -U postgres > /dev/null 2>&1; do sleep 1; done
-	@until $(CONTAINER_RUNTIME) exec bookhoard curl -sf http://localhost:8765/health > /dev/null 2>&1; do sleep 1; done
+	@until podman exec bookhoard_db pg_isready -U postgres > /dev/null 2>&1; do sleep 1; done
+	@until podman exec bookhoard curl -sf http://localhost:8765/health > /dev/null 2>&1; do sleep 1; done
 	@echo "✓ Test environment is ready!"
 	@echo "Application available at http://localhost:8765"
 
 # Stop test environment
 test-env-down:
-	$(COMPOSE) down -v
+	podman compose down -v
 
+# Verify project guidelines compliance
+verify-guidelines:
+	@echo "Running comprehensive project guidelines verification..."
+	@./scripts/verify-guidelines.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
-# image and publishes a Gitea Release whose body is this tag's message. Notes come
-# entirely from Conventional Commits — no hand-written message required.
-#
-# git-cliff's --latest needs the tag to exist to scope the notes, so we create a
-# throwaway lightweight tag, generate the notes, replace it with an annotated tag,
-# then push. --cleanup=verbatim keeps the markdown "###" group headers (git's
-# default cleanup would strip lines starting with "#").
-#
-# Requires git-cliff: https://git-cliff.org/install
-# Usage: make release VERSION=v0.3.0
-release:
-	@test -n "$(VERSION)" || { echo "Usage: make release VERSION=v0.3.0"; exit 1; }
-	@command -v git-cliff >/dev/null 2>&1 || { echo "git-cliff not found — install: https://git-cliff.org/install"; exit 1; }
-	@if git rev-parse "$(VERSION)" >/dev/null 2>&1; then echo "Tag $(VERSION) already exists locally — delete it first: git tag -d $(VERSION)"; exit 1; fi
-	@echo "Generating release notes for $(VERSION)..."
-	@git tag "$(VERSION)" HEAD && \
-		(git cliff --latest --config cliff.toml > .release-notes.tmp && git tag -d "$(VERSION)" >/dev/null) || \
-		{ git tag -d "$(VERSION)" >/dev/null 2>&1; rm -f .release-notes.tmp; echo "git-cliff failed"; exit 1; }
-	@git tag -a --cleanup=verbatim -F .release-notes.tmp "$(VERSION)" HEAD && rm -f .release-notes.tmp
-	@git push origin "$(VERSION)"
-	@echo "Pushed $(VERSION) — Gitea Actions will build the image and publish the Release."
+verify-quick:
+	@echo "Running quick project guidelines verification..."
+	@./scripts/verify-quick.sh

PROJECT_GUIDELINES.md

@@ -0,0 +1,480 @@
+# 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

@@ -1,10 +1,10 @@
-# <img src="web/static/favicon.svg" width="32" alt="Bookhoard logo"> Bookhoard
+# 📚 Bookhoard
 
 A modern self-hosted media library system built with Go, PostgreSQL, HTMX, and Tailwind CSS featuring **universal cross-device sync**, beautiful dark themes, and comprehensive media management.
 
 ## ✨ Why Bookhoard?
 
-**🔄 Universal Sync**: Your reading position, bookmarks, highlights, and notes sync automatically between KOReader and the web - with native Kobo sync and mobile apps coming later.
+**🔄 Universal Sync**: Your reading progress, highlights, and notes sync automatically across all your devices - KOReader, Kobo, web, and mobile.
 
 **📱 Multi-Library**: Organize your ebooks, comics, and manga with per-library folders and smart collections.
 
@@ -25,7 +25,7 @@ A modern self-hosted media library system built with Go, PostgreSQL, HTMX, and T
 
 ```bash
 # 1. Clone the repository
-git clone https://git.linuxhg.com/Bookhoard/bookhoard.git
+git clone https://github.com/yourusername/bookhoard.git
 cd bookhoard
 
 # 2. Set up environment
@@ -35,10 +35,8 @@ cp .env.example .env
 #   DBPASS: openssl rand -hex 16
 # Edit .env with your generated values
 
-# 3. Pull images and start the server
-docker compose pull
-docker compose up -d
-# Optionally pin a specific version: set IMAGE_TAG in .env (defaults to "latest")
+# 3. Start the server
+podman-compose up --build -d  # or: docker-compose up --build -d
 
 # 4. Open your browser
 open http://localhost:8765
@@ -52,13 +50,13 @@ The first user to register automatically becomes an admin.
 
 ### Universal Cross-Platform Sync
 
-- **Real-Time Progress**: Turn a page on your e-reader, see it in your browser
+- **Real-Time Progress**: Turn a page on your Kindle, see it on your phone
 - **Format-Aware**: EPUB CFI, page numbers, percentages - all handled correctly
 - **Offline Queue**: Changes sync when you reconnect, priority-processed
 - **Conflict Resolution**: Smart handling when same book read on multiple devices
 - **Book Matching**: Automatic matching using SHA-256, ISBN, UUID
 - **OPDS Catalog**: Wireless book delivery to e-readers over Wi-Fi
-- **Format Conversion**: On-the-fly EPUB→KEPUB conversion (for upcoming native Kobo support)
+- **Format Conversion**: On-the-fly EPUB→KEPUB for Kobo devices
 
 ### Media Management
 
@@ -74,7 +72,7 @@ The first user to register automatically becomes an admin.
 ### Smart Collections
 
 - **Auto-Assign Rules**: Automatically add books based on genre, author, series, tags, language, publisher, year
-- **Device Shelf Mappings**: Map collections to device shelves (used by native Kobo sync, coming soon)
+- **Device Shelf Mappings**: Sync collections to Kobo shelves and KOReader categories
 - **Test Before Creating**: Preview which books match your rules
 
 ### Library Organization
@@ -102,8 +100,8 @@ The first user to register automatically becomes an admin.
 
 - **[docs/user/calibre-integration.md](docs/user/calibre-integration.md)** - Calibre library integration
 - **[docs/user/sync-guide.md](docs/user/sync-guide.md)** - Understanding and using universal sync
+- **[docs/user/devices/kobo-setup.md](docs/user/devices/kobo-setup.md)** - Kobo e-reader configuration
 - **[docs/user/devices/koreader-setup.md](docs/user/devices/koreader-setup.md)** - KOReader configuration
-- **[docs/user/devices/kobo-setup.md](docs/user/devices/kobo-setup.md)** - Kobo e-reader configuration (coming soon)
 - **[docs/user/user-guide.md](docs/user/user-guide.md)** - General user guide
 - **[docs/user/admin-guide.md](docs/user/admin-guide.md)** - Admin features and configuration
 - **[docs/user/settings-guide.md](docs/user/settings-guide.md)** - Settings and preferences
@@ -111,45 +109,18 @@ The first user to register automatically becomes an admin.
 ### For Developers
 
 - **[docs/developer/api/api-reference.md](docs/developer/api/api-reference.md)** - Complete API documentation
-- **[docs/developer/android-app.md](docs/developer/android-app.md)** - Android app design & roadmap
-- **[docs/contributing/development.md](docs/contributing/development.md)** - Development workflow
+- **[docs/contributing/DEVELOPMENT.md](docs/contributing/DEVELOPMENT.md)** - Development workflow
 
 ---
 
 ## 🎯 Supported Devices
 
-| Platform         | Sync | OPDS | Status                                                        |
-| ---------------- | ---- | ---- | ------------------------------------------------------------- |
-| **Web Browser**  | ✅   | ✅   | Full support                                                  |
-| **KOReader**     | ✅   | ✅   | Runs on Kindle, Kobo, PocketBook hardware                     |
-| **Kobo Devices** | 🚧   | 🚧   | Native Kobo sync coming soon (use KOReader on Kobo today)     |
-| **Mobile Apps**  | 🚧   | 🚧   | Native Android app in design ([docs](docs/developer/android-app.md)); iOS later |
-
----
-
-## 💾 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.
+| Platform         | Sync | OPDS | Status                   |
+| ---------------- | ---- | ---- | ------------------------ |
+| **Web Browser**  | ✅   | ✅   | Full support             |
+| **KOReader**     | ✅   | ✅   | Kindle, Kobo, PocketBook |
+| **Kobo Devices** | ✅   | ✅   | Clara, Libra, Sage, etc. |
+| **Mobile Apps**  | 🚧   | 🚧   | Coming Q2 2026           |
 
 ---
 
@@ -182,20 +153,20 @@ bruno run
 ## 📊 Project Status
 
 **Version**: 1.0  
-**License**: AGPL-3.0  
+**License**: GPL-3.0  
 **Status**: Production-ready ✅
 
 ---
 
 ## 🤝 Contributing
 
-We welcome contributions! Please see [docs/developer/development.md](docs/developer/development.md) for guidelines.
+We welcome contributions! Please see [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) for guidelines.
 
 ---
 
 ## 📄 License
 
-AGPL-3.0 - See [LICENSE](LICENSE) file for details.
+GPL-3.0 - See [LICENSE](LICENSE) file for details.
 
 ---
 

TIMEZONE_PLAN.md

@@ -0,0 +1,379 @@
+# Timezone Implementation Plan
+
+## Overview
+
+Add per-user timezone support with system-wide fallback (set via docker-compose), defaulting to UTC. The database already stores all timestamps as UTC via `TIMESTAMPTZ` columns, so this is primarily a display-layer feature.
+
+**Display format:** MM-DD-YYYY HH:MM (US convention, no timezone abbreviation shown)
+
+**Timezone selection:** Manual dropdown only (no browser auto-detect)
+
+---
+
+## Phase 1: Database Schema
+
+**File:** `database/schema/schema.sql`
+
+1. Add `timezone` column directly to the `users` table definition (line ~36):
+
+```sql
+CREATE TABLE IF NOT EXISTS users (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    email VARCHAR(255) UNIQUE NOT NULL,
+    username VARCHAR(255) UNIQUE NOT NULL,
+    password_hash VARCHAR(255) NOT NULL,
+    first_name VARCHAR(255),
+    last_name VARCHAR(255),
+    role VARCHAR(20) NOT NULL DEFAULT 'user' CHECK (role IN ('admin', 'user')),
+    theme VARCHAR(50) DEFAULT 'tokyo-night',
+    max_devices INTEGER DEFAULT 10,
+    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+    updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+    timezone VARCHAR(50) DEFAULT 'UTC'
+);
+```
+
+> Note: The `timezone` column is already present at line 36 in the current schema. No change needed for this step.
+
+1. Add `default_timezone` to the `system_settings` INSERT block (line ~49-52):
+
+```sql
+INSERT INTO system_settings (setting_key, setting_value, description) VALUES
+('scan_poll_interval_seconds', '60', 'How often to scan all libraries in minutes'),
+('auto_scan_enabled', 'true', 'Whether auto-scanning is enabled system-wide'),
+('default_timezone', 'UTC', 'System default timezone')
+ON CONFLICT (setting_key) DO NOTHING;
+```
+
+1. Add index in the indexes section (after line ~460, with other user indexes):
+
+```sql
+CREATE INDEX IF NOT EXISTS idx_users_timezone ON users(timezone);
+```
+
+1. Regenerate sqlc code:
+
+```bash
+cd internal/database && sqlc generate
+```
+
+---
+
+## Phase 2: Database Queries
+
+**File:** `internal/database/queries/queries.sql`
+
+Add new queries:
+
+```sql
+-- name: UpdateUserTimezone :exec
+UPDATE users SET timezone = $2, updated_at = NOW() WHERE id = $1;
+
+-- name: GetSystemTimezone :one
+SELECT setting_value FROM system_settings WHERE setting_key = 'default_timezone';
+```
+
+> Note: `UpdateSystemTimezone` is omitted because the existing `UpdateSystemSetting` query handles it by passing `'default_timezone'` as the key parameter.
+
+Regenerate after adding queries:
+
+```bash
+cd internal/database && sqlc generate
+```
+
+---
+
+## Phase 3: Template Utilities
+
+**File:** `templates/utils.go`
+
+Add timezone-aware time formatting helpers:
+
+```go
+package templates
+
+import (
+    "time"
+
+    "github.com/jackc/pgx/v5/pgtype"
+)
+
+// FormatInTimezone formats a time.Time in the specified timezone as MM-DD-YYYY HH:MM
+func FormatInTimezone(t time.Time, timezone string) string {
+    if t.IsZero() {
+        return ""
+    }
+
+    loc, err := time.LoadLocation(timezone)
+    if err != nil {
+        loc = time.UTC
+    }
+
+    return t.In(loc).Format("01-02-2006 03:04 PM")
+}
+
+// FormatTimestamptzInTimezone formats a pgtype.Timestamptz in the specified timezone
+func FormatTimestamptzInTimezone(t pgtype.Timestamptz, timezone string) string {
+    if !t.Valid {
+        return ""
+    }
+    return FormatInTimezone(t.Time, timezone)
+}
+```
+
+---
+
+## Phase 4: User Context Update
+
+**File:** `templates/types.go`
+
+Add `Timezone` field to the `User` struct:
+
+```go
+type User struct {
+    ID        string
+    Email     string
+    Username  string
+    Role      string
+    Theme     string
+    FirstName string
+    LastName  string
+    CreatedAt time.Time
+    Token     string
+    Timezone  string
+}
+```
+
+**File:** `internal/router/helpers.go`
+
+Update `getTemplateUserWithTheme()` to include timezone:
+
+```go
+userTimezone := "UTC"
+if userDB.Timezone.Valid {
+    userTimezone = userDB.Timezone.String
+}
+
+return templates.User{
+    // ... existing fields ...
+    Timezone: userTimezone,
+}
+```
+
+---
+
+## Phase 5: Handlers
+
+**File:** `internal/handlers/auth.go`
+
+Update `UpdateProfileRequest` struct:
+
+```go
+type UpdateProfileRequest struct {
+    Username  string `json:"username,omitempty" validate:"omitempty,min=3,max=50"`
+    Email     string `json:"email,omitempty" validate:"omitempty,email"`
+    FirstName string `json:"first_name,omitempty" validate:"omitempty,max=100"`
+    LastName  string `json:"last_name,omitempty" validate:"omitempty,max=100"`
+    Theme     string `json:"theme,omitempty" validate:"omitempty"`
+    Timezone  string `json:"timezone,omitempty" validate:"omitempty"`
+}
+```
+
+Add timezone update logic in `UpdateProfile()`:
+
+```go
+if req.Timezone != "" {
+    if _, err := time.LoadLocation(req.Timezone); err != nil {
+        return c.JSON(http.StatusBadRequest, map[string]string{
+            "error": "Invalid timezone",
+        })
+    }
+    err := h.db.UpdateUserTimezone(ctx, database.UpdateUserTimezoneParams{
+        ID:       pgtype.UUID{Bytes: userUUID, Valid: true},
+        Timezone: pgtype.Text{String: req.Timezone, Valid: true},
+    })
+    if err != nil {
+        return err
+    }
+}
+```
+
+**File:** `internal/handlers/system_settings.go`
+
+Add timezone settings handler:
+
+```go
+type UpdateTimezoneSettingsRequest struct {
+    DefaultTimezone string `json:"default_timezone" validate:"required"`
+}
+
+func (h *SystemSettingsHandler) UpdateTimezoneSettings(c *echo.Context) error {
+    var req UpdateTimezoneSettingsRequest
+    if err := c.Bind(&req); err != nil {
+        return c.JSON(http.StatusBadRequest, map[string]string{"error": "Invalid request"})
+    }
+    if _, err := time.LoadLocation(req.DefaultTimezone); err != nil {
+        return c.JSON(http.StatusBadRequest, map[string]string{"error": "Invalid timezone"})
+    }
+    err := h.db.UpdateSystemSetting(c.Request().Context(), database.UpdateSystemSettingParams{
+        SettingKey:   "default_timezone",
+        SettingValue: req.DefaultTimezone,
+    })
+    if err != nil {
+        return err
+    }
+    return c.JSON(http.StatusOK, map[string]string{"message": "Timezone updated"})
+}
+```
+
+---
+
+## Phase 6: User Profile UI
+
+**File:** `templates/profile_form.templ`
+
+Add timezone dropdown after the theme field:
+
+```templ
+<div class="form-group">
+    <label for="timezone">Timezone</label>
+    <select name="timezone" id="timezone" class="form-select">
+        <option value="UTC" selected?={ user.Timezone == "UTC" }>UTC (Coordinated Universal Time)</option>
+        <option value="America/New_York" selected?={ user.Timezone == "America/New_York" }>Eastern Time</option>
+        <option value="America/Chicago" selected?={ user.Timezone == "America/Chicago" }>Central Time</option>
+        <option value="America/Denver" selected?={ user.Timezone == "America/Denver" }>Mountain Time</option>
+        <option value="America/Los_Angeles" selected?={ user.Timezone == "America/Los_Angeles" }>Pacific Time</option>
+        <option value="America/Phoenix" selected?={ user.Timezone == "America/Phoenix" }>Mountain Time (no DST)</option>
+        <option value="America/Anchorage" selected?={ user.Timezone == "America/Anchorage" }>Alaska Time</option>
+        <option value="Pacific/Honolulu" selected?={ user.Timezone == "Pacific/Honolulu" }>Hawaii Time</option>
+    </select>
+</div>
+```
+
+Include timezone in the HTMX form submission payload.
+
+---
+
+## Phase 7: Admin Settings UI
+
+**File:** `templates/admin_settings.templ`
+
+Add system default timezone setting:
+
+```templ
+<div class="setting-group">
+    <h3>System Defaults</h3>
+    <label for="default_timezone">Default Timezone</label>
+    <select name="default_timezone" id="default_timezone">
+        <option value="UTC">UTC (Coordinated Universal Time)</option>
+        <option value="America/New_York">Eastern Time</option>
+        <option value="America/Chicago">Central Time</option>
+        <option value="America/Denver">Mountain Time</option>
+        <option value="America/Los_Angeles">Pacific Time</option>
+        <option value="America/Phoenix">Mountain Time (no DST)</option>
+        <option value="America/Anchorage">Alaska Time</option>
+        <option value="Pacific/Honolulu">Hawaii Time</option>
+    </select>
+</div>
+```
+
+---
+
+## Phase 8: Template Time Display Updates
+
+### Files to update
+
+| Template                             | Line(s)        | Field(s)                            |
+| ------------------------------------ | -------------- | ----------------------------------- |
+| `templates/book_detail.templ`        | ~253, ~282     | `LastReadAt`, `DatePublished`       |
+| `templates/book_detail_modals.templ` | ~68, ~113      | `Timestamp`, `LastReadAt`           |
+| `templates/devices.templ`            | ~83, ~91, ~174 | `LastSync`, `LastSeen`, `ExpiresAt` |
+| `templates/conflicts.templ`          | ~114           | `CreatedAt`                         |
+| `templates/admin_users.templ`        | ~89            | `CreatedAt`                         |
+| `templates/queue.templ`              | ~138           | `CreatedAt`                         |
+
+### Change pattern
+
+```templ
+<!-- Before -->
+{ book.ReadingProgress.LastReadAt.Time.Format("01-02-2006 03:04 PM") }
+
+<!-- After -->
+{ templates.FormatTimestamptzInTimezone(book.ReadingProgress.LastReadAt, user.Timezone) }
+```
+
+For `time.Time` fields:
+
+```templ
+<!-- Before -->
+{ device.LastSync.Format("01-02-2006 03:04 PM") }
+
+<!-- After -->
+{ templates.FormatInTimezone(device.LastSync, user.Timezone) }
+```
+
+---
+
+## Phase 9: Docker Configuration
+
+**File:** `docker-compose.yml`
+
+```yaml
+services:
+  server:
+    environment:
+      - TZ=UTC
+```
+
+**File:** `.env.example`
+
+```
+# System default timezone (fallback if not set in DB)
+TZ=UTC
+```
+
+---
+
+## Files Modified Summary
+
+| File                                    | Change                                                                          |
+| --------------------------------------- | ------------------------------------------------------------------------------- |
+| `database/schema/schema.sql`            | Add timezone column to users, system_setting row                                |
+| `internal/database/queries/queries.sql` | Add UpdateUserTimezone, GetSystemTimezone (reuses existing UpdateSystemSetting) |
+| `templates/utils.go`                    | Add FormatInTimezone, FormatTimestamptzInTimezone                               |
+| `templates/types.go`                    | Add Timezone field to User struct                                               |
+| `internal/router/helpers.go`            | Pass timezone to template User                                                  |
+| `internal/handlers/auth.go`             | Handle timezone updates in UpdateProfile                                        |
+| `internal/handlers/system_settings.go`  | Add timezone settings handler                                                   |
+| `templates/profile_form.templ`          | Add timezone dropdown                                                           |
+| `templates/admin_settings.templ`        | Add default timezone setting                                                    |
+| `templates/book_detail.templ`           | Update time displays                                                            |
+| `templates/book_detail_modals.templ`    | Update time displays                                                            |
+| `templates/devices.templ`               | Update time displays                                                            |
+| `templates/conflicts.templ`             | Update time displays                                                            |
+| `templates/admin_users.templ`           | Update time displays                                                            |
+| `templates/queue.templ`                 | Update time displays                                                            |
+| `docker-compose.yml`                    | Add TZ env var                                                                  |
+| `.env.example`                          | Add TZ example                                                                  |
+
+---
+
+## Testing Checklist
+
+- [ ] Create user, set timezone to Eastern, verify times display in MM-DD-YYYY HH:MM format
+- [ ] Create user, set timezone to Pacific, verify different offset
+- [ ] Test system default timezone fallback for users with no timezone set
+- [ ] Verify invalid timezone values are rejected by the API
+- [ ] Verify existing users (no timezone set) fall back to system default
+- [ ] Verify all templates show consistent MM-DD-YYYY HH:MM format
+- [ ] Run `make test-integration` to verify no regressions
+
+---
+
+## Deployment Steps
+
+1. Update `database/schema/schema.sql` with new column and settings
+2. Regenerate sqlc: `cd internal/database && sqlc generate`
+3. Apply schema changes (restart database container with `make rebuild-force-db`)
+4. Deploy backend code changes
+5. Verify with existing data

bruno/NewDB.sh

@@ -1,3 +1,3 @@
 #!/bin/bash
 
-bru run --env Bookhoard --delay 500 "NewDevDBSetup/RegisterUser.yml" "NewDevDBSetup/SetBaseUrl.yml" "NewDevDBSetup/CreateEbookLibrary.yml" "NewDevDBSetup/CreateComicLibrary.yml" "NewDevDBSetup/CreateMangaLibrary.yml" "NewDevDBSetup/AddEbookLibraryFolder.yml" "NewDevDBSetup/AddComicLibraryFolder.yml" "NewDevDBSetup/AddMangaLibraryFolder.yml" "NewDevDBSetup/ScanAllLibraries.yml"
+bru run --env Bookhoard --delay 500 "NewDevDBSetup/RegisterUser.yml" "NewDevDBSetup/CreateEbookLibrary.yml" "NewDevDBSetup/CreateComicLibrary.yml" "NewDevDBSetup/CreateMangaLibrary.yml" "NewDevDBSetup/AddEbookLibraryFolder.yml" "NewDevDBSetup/AddComicLibraryFolder.yml" "NewDevDBSetup/AddMangaLibraryFolder.yml" "NewDevDBSetup/ScanAllLibraries.yml"

bruno/NewDevDBSetup/SetBaseUrl.yml

@@ -1,37 +0,0 @@
-info:
-  name: SetBaseUrl
-  type: http
-  seq: 3
-http:
-  method: PUT
-  url: '{{base_url}}/api/system/config'
-  auth: inherit
-  body:
-    type: json
-    data: "{\n  \"base_url\": \"http://localhost:8765\"\n}"
-  headers:
-  - key: Authorization
-    value: Bearer {{token}}
-  - key: Content-Type
-    value: application/json
-settings:
-  encodeUrl: true
-  timeout: 0
-  followRedirects: true
-  maxRedirects: 5
-docs: '## Set Base URL
-
-
-  Configures the server''s base_url during initial dev database setup.
-
-
-  Must be run after RegisterUser (which provides the auth token) and before
-
-  any library/device creation (which require setup to be complete).
-
-
-  **Method:** PUT
-
-  **Endpoint:** /api/system/config
-
-  **Auth:** Bearer token (from RegisterUser)'

bruno/admin/Get Admin Profile.yml

@@ -0,0 +1,39 @@
+info:
+  name: Get Admin Profile
+  type: http
+  seq: 4
+http:
+  method: GET
+  url: '{{base_url}}/admin/profile'
+  auth: inherit
+  body:
+    type: none
+
+docs: |-
+  ## Get Admin Profile
+    
+    Retrieves the admin profile information for administrative access.
+    
+    **Method:** GET
+    
+    **Endpoint:** /admin/profile
+    
+    **Authentication:** Required (Bearer token)
+    
+    **Response:**
+    - JSON object containing admin profile details
+      - `id` (string): Admin user ID
+      - `email` (string): Admin email
+      - `username` (string): Admin username
+      - `theme` (string): Theme preference
+      - `first_name` (string): First name
+      - `last_name` (string): Last name
+      - `is_admin` (boolean): Admin status
+      - `created_at` (string): Account creation timestamp
+      - `updated_at` (string): Last update timestamp
+    
+    **Status Codes:**
+    - 200: Success
+    - 401: Unauthorized
+    - 403: Forbidden (non-admin users)
+    - 404: Profile not found

bruno/books/Bulk Delete Books.yml

@@ -8,8 +8,43 @@ http:
   auth: inherit
   body:
     type: json
-    data: "{\n    \"media_item_ids\": [\n      \"{{bookId1"
+    jsonBody: "{\n    \"media_item_ids\": [\n      \"{{bookId1"
   headers:
   - key: Content-Type
     value: application/json
-docs: "## Bulk Delete Media Items\n\n  Deletes multiple media items in a single request.\n\n  **Method:** POST\n\n  **Endpoint:** /api/media-items/bulk-delete\n\n  **Authentication:** Required (Bearer token)\n\n  **Request Body:**\n  - `media_item_ids` (array of strings): Array of media item UUIDs to delete\n\n  **Response:**\n  - `results` (array): Results for each deletion attempt\n  - `total` (number): Total number of media items processed\n  - `deleted` (number): Number of successfully deleted media items\n  - `failed` (number): Number of failed deletions\n\n  **Status Codes:**\n  - 200: Success (with partial results if some failed)\n  - 400: Invalid request data\n  - 401: Unauthorized\n  - 403: Forbidden\n  - 500: Internal server error\n\n  **Example:**\n  ```json\n  {\n    \"media_item_ids\": [\n      \"uuid-1\",\n      \"uuid-2\",\n      \"uuid-3\"\n    ]"
+
+docs: |-
+  ## Bulk Delete Media Items
+  
+    Deletes multiple media items in a single request.
+  
+    **Method:** POST
+  
+    **Endpoint:** /api/media-items/bulk-delete
+  
+    **Authentication:** Required (Bearer token)
+  
+    **Request Body:**
+    - `media_item_ids` (array of strings): Array of media item UUIDs to delete
+  
+    **Response:**
+    - `results` (array): Results for each deletion attempt
+    - `total` (number): Total number of media items processed
+    - `deleted` (number): Number of successfully deleted media items
+    - `failed` (number): Number of failed deletions
+  
+    **Status Codes:**
+    - 200: Success (with partial results if some failed)
+    - 400: Invalid request data
+    - 401: Unauthorized
+    - 403: Forbidden
+    - 500: Internal server error
+  
+    **Example:**
+    ```json
+    {
+      "media_item_ids": [
+        "uuid-1",
+        "uuid-2",
+        "uuid-3"
+      ]

bruno/books/Bulk Update Books.yml

@@ -8,9 +8,48 @@ http:
   auth: inherit
   body:
     type: json
-    data: "{\n    \"media_item_updates\": [\n      {\n        \"media_item_id\": \"{{bookId1"
+    jsonBody: "{\n    \"media_item_updates\": [\n      {\n        \"media_item_id\"\
+      : \"{{bookId1"
   headers:
   - key: Content-Type
     value: application/json
-docs: "## Bulk Update Media Items\n\n  Updates multiple media items in a single request with different fields for each item.\n\n  **Method:** POST\n\n  **Endpoint:** /api/media-items/bulk-update\n\n  **Authentication:** Required (Bearer token)\n\n  **Request Body:**\n  - `media_item_updates` (array): Array of update objects\n    - `media_item_id` (string): Media item UUID to update\n    - `updates` (object): Fields to update (can include title, author, genre, tags, contributors, etc.)\n\n  **Response:**\n  - `results` (array): Results for each update attempt\n  - `total` (number): Total number of media items processed\n  - `updated` (number): Number of successfully updated media items\n  - `failed` (number): Number of failed updates\n\n  **Status Codes:**\n  - 200: Success (with partial results if some failed)\n  - 400: Invalid request data\n  - 401: Unauthorized\n  - 403: Forbidden\n  - 500: Internal server error\n\n  **Example:**\n  ```json\n  {\n    \"media_item_updates\": [\n      {\n\
-  \        \"media_item_id\": \"uuid-1\",\n        \"updates\": {\n          \"title\": \"New Title\",\n          \"genre\": \"Fiction\",\n          \"tags\": [\"fiction\", \"adventure\"]"
+
+docs: |-
+  ## Bulk Update Media Items
+  
+    Updates multiple media items in a single request with different fields for each item.
+  
+    **Method:** POST
+  
+    **Endpoint:** /api/media-items/bulk-update
+  
+    **Authentication:** Required (Bearer token)
+  
+    **Request Body:**
+    - `media_item_updates` (array): Array of update objects
+      - `media_item_id` (string): Media item UUID to update
+      - `updates` (object): Fields to update (can include title, author, genre, tags, contributors, etc.)
+  
+    **Response:**
+    - `results` (array): Results for each update attempt
+    - `total` (number): Total number of media items processed
+    - `updated` (number): Number of successfully updated media items
+    - `failed` (number): Number of failed updates
+  
+    **Status Codes:**
+    - 200: Success (with partial results if some failed)
+    - 400: Invalid request data
+    - 401: Unauthorized
+    - 403: Forbidden
+    - 500: Internal server error
+  
+    **Example:**
+    ```json
+    {
+      "media_item_updates": [
+        {
+          "media_item_id": "uuid-1",
+          "updates": {
+            "title": "New Title",
+            "genre": "Fiction",
+            "tags": ["fiction", "adventure"]

bruno/collections/Add Books to Collection.yml

@@ -8,5 +8,31 @@ http:
   auth: inherit
   body:
     type: json
-    data: "{\n    \"book_ids\": [\n      \"{{book_id_1}}"
-docs: "## Add Books to Collection\n\n  Adds multiple books to an existing collection.\n  \n  **Method:** POST\n  \n  **Endpoint:** /api/collections/{collection_id}/books\n  \n  **Authentication:** Required (Bearer token)\n  \n  **Path Parameters:**\n  - `collection_id` (string): Collection ID\n  \n  **Request Body:**\n  - `book_ids` (array of strings, required): List of book IDs to add\n  \n  **Response:**\n  - `message` (string): Success message\n  - `added_count` (integer): Number of books added\n  \n  **Status Codes:**\n  - 200: Success\n  - 400: Invalid request\n  - 401: Unauthorized\n  - 404: Collection not found"
+    jsonBody: "{\n    \"book_ids\": [\n      \"{{book_id_1}}"
+
+docs: |-
+  ## Add Books to Collection
+  
+    Adds multiple books to an existing collection.
+    
+    **Method:** POST
+    
+    **Endpoint:** /api/collections/{collection_id}/books
+    
+    **Authentication:** Required (Bearer token)
+    
+    **Path Parameters:**
+    - `collection_id` (string): Collection ID
+    
+    **Request Body:**
+    - `book_ids` (array of strings, required): List of book IDs to add
+    
+    **Response:**
+    - `message` (string): Success message
+    - `added_count` (integer): Number of books added
+    
+    **Status Codes:**
+    - 200: Success
+    - 400: Invalid request
+    - 401: Unauthorized
+    - 404: Collection not found

bruno/collections/Create Collection.yml

@@ -8,6 +8,40 @@ http:
   auth: inherit
   body:
     type: json
-    data: "{\n    \"name\": \"Science Fiction\",\n    \"description\": \"My favorite sci-fi books\",\n    \"color\": \"#ff0000\",\n    \"icon\": \"\U0001F680\",\n    \"auto_assign_rules\": [\n      {\n        \"id\": \"rule-1\",\n        \"field\": \"genre\",\n        \"operator\": \"equals\",\n        \"value\": \"Science Fiction\",\n        \"priority\": 8"
-docs: "## Create Collection\n\n  Creates a new collection for organizing books.\n  \n  **Method:** POST\n  \n  **Endpoint:** /api/collections\n  \n  **Authentication:** Required (Bearer token)\n  \n  **Request Body:**\n  - `name` (string, required): Collection name (max 100 chars)\n  - `description` (string, optional): Collection description (max 500 chars)\n  - `color` (string, optional): Hex color code (default #3498db)\n  - `icon` (string, optional): Emoji icon (default \U0001F4DA)\n  - `auto_assign_rules` (array, optional): Auto-assignment rules\n    - `id` (string): Rule ID\n    - `field` (string): Field to match (genre, author, series, etc.)\n    - `operator` (string): Comparison operator (equals, contains, startsWith)\n    - `value` (string): Value to match\n    - `priority` (integer): Rule priority (1-10)\n  \n  **Response:**\n  - Collection object with generated ID\n  \n  **Status Codes:**\n  - 201: Created\n  - 400: Invalid request\n  - 401: Unauthorized\n  - 409: Collection name\
-  \ already exists"
+    jsonBody: "{\n    \"name\": \"Science Fiction\",\n    \"description\": \"My favorite\
+      \ sci-fi books\",\n    \"color\": \"#ff0000\",\n    \"icon\": \"\U0001F680\"\
+      ,\n    \"auto_assign_rules\": [\n      {\n        \"id\": \"rule-1\",\n    \
+      \    \"field\": \"genre\",\n        \"operator\": \"equals\",\n        \"value\"\
+      : \"Science Fiction\",\n        \"priority\": 8"
+
+docs: |-
+  ## Create Collection
+  
+    Creates a new collection for organizing books.
+    
+    **Method:** POST
+    
+    **Endpoint:** /api/collections
+    
+    **Authentication:** Required (Bearer token)
+    
+    **Request Body:**
+    - `name` (string, required): Collection name (max 100 chars)
+    - `description` (string, optional): Collection description (max 500 chars)
+    - `color` (string, optional): Hex color code (default #3498db)
+    - `icon` (string, optional): Emoji icon (default 📚)
+    - `auto_assign_rules` (array, optional): Auto-assignment rules
+      - `id` (string): Rule ID
+      - `field` (string): Field to match (genre, author, series, etc.)
+      - `operator` (string): Comparison operator (equals, contains, startsWith)
+      - `value` (string): Value to match
+      - `priority` (integer): Rule priority (1-10)
+    
+    **Response:**
+    - Collection object with generated ID
+    
+    **Status Codes:**
+    - 201: Created
+    - 400: Invalid request
+    - 401: Unauthorized
+    - 409: Collection name already exists

bruno/collections/Create Device Mapping.yml

@@ -8,5 +8,32 @@ http:
   auth: inherit
   body:
     type: json
-    data: "{\n    \"collection_id\": \"{{collection_id}}"
-docs: "## Create Device Mapping\n\n  Maps a collection to a device shelf for synchronization.\n  \n  **Method:** POST\n  \n  **Endpoint:** /api/devices/{device_id}/collections\n  \n  **Authentication:** Required (Bearer token)\n  \n  **Path Parameters:**\n  - `device_id` (string): Device ID\n  \n  **Request Body:**\n  - `collection_id` (string, required): Collection ID to map\n  - `device_shelf_name` (string, optional): Custom shelf name on device\n  - `sync_direction` (string, optional): sync direction (book_to_device, device_to_book, bidirectional)\n  \n  **Response:**\n  - Mapping object with generated ID\n  \n  **Status Codes:**\n  - 201: Created\n  - 400: Invalid request\n  - 401: Unauthorized\n  - 404: Device or collection not found"
+    jsonBody: "{\n    \"collection_id\": \"{{collection_id}}"
+
+docs: |-
+  ## Create Device Mapping
+  
+    Maps a collection to a device shelf for synchronization.
+    
+    **Method:** POST
+    
+    **Endpoint:** /api/devices/{device_id}/collections
+    
+    **Authentication:** Required (Bearer token)
+    
+    **Path Parameters:**
+    - `device_id` (string): Device ID
+    
+    **Request Body:**
+    - `collection_id` (string, required): Collection ID to map
+    - `device_shelf_name` (string, optional): Custom shelf name on device
+    - `sync_direction` (string, optional): sync direction (book_to_device, device_to_book, bidirectional)
+    
+    **Response:**
+    - Mapping object with generated ID
+    
+    **Status Codes:**
+    - 201: Created
+    - 400: Invalid request
+    - 401: Unauthorized
+    - 404: Device or collection not found

bruno/collections/Update Collection.yml

@@ -8,5 +8,39 @@ http:
   auth: inherit
   body:
     type: json
-    data: "{\n    \"name\": \"Sci-Fi Favorites\",\n    \"description\": \"Updated description\",\n    \"color\": \"#00ff00\",\n    \"icon\": \"⭐\",\n    \"auto_assign_rules\": [\n      {\n        \"id\": \"rule-2\",\n        \"field\": \"series\",\n        \"operator\": \"equals\",\n        \"value\": \"Foundation\",\n        \"priority\": 9"
-docs: "## Update Collection\n\n  Updates an existing collection's properties.\n  \n  **Method:** PUT\n  \n  **Endpoint:** /api/collections/{collection_id}\n  \n  **Authentication:** Required (Bearer token)\n  \n  **Path Parameters:**\n  - `collection_id` (string): Collection ID\n  \n  **Request Body:**\n  - `name` (string, optional): New collection name\n  - `description` (string, optional): New description\n  - `color` (string, optional): New hex color code\n  - `icon` (string, optional): New emoji icon\n  - `auto_assign_rules` (array, optional): Updated auto-assignment rules\n  \n  **Response:**\n  - Updated collection object\n  \n  **Status Codes:**\n  - 200: Success\n  - 400: Invalid request\n  - 401: Unauthorized\n  - 404: Collection not found\n  - 409: Collection name already exists"
+    jsonBody: "{\n    \"name\": \"Sci-Fi Favorites\",\n    \"description\": \"Updated\
+      \ description\",\n    \"color\": \"#00ff00\",\n    \"icon\": \"⭐\",\n    \"\
+      auto_assign_rules\": [\n      {\n        \"id\": \"rule-2\",\n        \"field\"\
+      : \"series\",\n        \"operator\": \"equals\",\n        \"value\": \"Foundation\"\
+      ,\n        \"priority\": 9"
+
+docs: |-
+  ## Update Collection
+  
+    Updates an existing collection's properties.
+    
+    **Method:** PUT
+    
+    **Endpoint:** /api/collections/{collection_id}
+    
+    **Authentication:** Required (Bearer token)
+    
+    **Path Parameters:**
+    - `collection_id` (string): Collection ID
+    
+    **Request Body:**
+    - `name` (string, optional): New collection name
+    - `description` (string, optional): New description
+    - `color` (string, optional): New hex color code
+    - `icon` (string, optional): New emoji icon
+    - `auto_assign_rules` (array, optional): Updated auto-assignment rules
+    
+    **Response:**
+    - Updated collection object
+    
+    **Status Codes:**
+    - 200: Success
+    - 400: Invalid request
+    - 401: Unauthorized
+    - 404: Collection not found
+    - 409: Collection name already exists

bruno/collections/Update Device Mapping.yml

@@ -8,5 +8,33 @@ http:
   auth: inherit
   body:
     type: json
-    data: "{\n    \"device_shelf_name\": \"Science Fiction\",\n    \"sync_direction\": \"book_to_device\""
-docs: "## Update Device Mapping\n\n  Updates settings for a collection-to-device mapping.\n  \n  **Method:** PUT\n  \n  **Endpoint:** /api/devices/{device_id}/collections/{mapping_id}\n  \n  **Authentication:** Required (Bearer token)\n  \n  **Path Parameters:**\n  - `device_id` (string): Device ID\n  - `mapping_id` (string): Mapping ID\n  \n  **Request Body:**\n  - `device_shelf_name` (string, optional): Custom shelf name on device\n  - `sync_direction` (string, optional): Sync direction (book_to_device, device_to_book, bidirectional)\n  \n  **Response:**\n  - Updated mapping object\n  \n  **Status Codes:**\n  - 200: Success\n  - 400: Invalid request\n  - 401: Unauthorized\n  - 404: Device or mapping not found"
+    jsonBody: "{\n    \"device_shelf_name\": \"Science Fiction\",\n    \"sync_direction\"\
+      : \"book_to_device\""
+
+docs: |-
+  ## Update Device Mapping
+  
+    Updates settings for a collection-to-device mapping.
+    
+    **Method:** PUT
+    
+    **Endpoint:** /api/devices/{device_id}/collections/{mapping_id}
+    
+    **Authentication:** Required (Bearer token)
+    
+    **Path Parameters:**
+    - `device_id` (string): Device ID
+    - `mapping_id` (string): Mapping ID
+    
+    **Request Body:**
+    - `device_shelf_name` (string, optional): Custom shelf name on device
+    - `sync_direction` (string, optional): Sync direction (book_to_device, device_to_book, bidirectional)
+    
+    **Response:**
+    - Updated mapping object
+    
+    **Status Codes:**
+    - 200: Success
+    - 400: Invalid request
+    - 401: Unauthorized
+    - 404: Device or mapping not found

bruno/collections/create-custom-section-manual.yml

@@ -8,9 +8,40 @@ http:
   auth: inherit
   body:
     type: json
-    data: "{\n  \"library_id\": \"{{library_id}}\",\n  \"name\": \"My Favorites\",\n  \"icon\": \"⭐\",\n  \"description\": \"My favorite books\",\n  \"show_on_dashboard\": true,\n  \"auto_assign_rules\": \"\",\n  \"manual_book_ids\": [\"{{media_item_id}}\"],\n  \"match_type\": \"all\"\n}"
+    jsonBody: "{\n  \"library_id\": \"{{library_id}}\",\n  \"name\": \"My Favorites\"\
+      ,\n  \"icon\": \"⭐\",\n  \"description\": \"My favorite books\",\n  \"show_on_dashboard\"\
+      : true,\n  \"auto_assign_rules\": \"\",\n  \"manual_book_ids\": [\"{{media_item_id}}\"\
+      ],\n  \"match_type\": \"all\"\n}"
 runtime:
   scripts:
-  - type: after-response
-    code: "function onResponse(res) {\ntest(\"status must be 201 with valid request\", function() {\n    expect(res.status).to.eql(201);\n});\n\ntest(\"response contains collection id\", function() {\n    expect(res.body.id).to.exist;\nexpect(res.body.id).to.be.a('string');\n  });\n\ntest(\"response contains collection name\", function() {\n    expect(res.body.name).to.eql(\"My Favorites\");\n  });\n}"
-docs: "Create a custom collection with manually selected books.\n\n**Endpoint**: POST /api/collections\n**Auth**: Required (Bearer token)\n\n## Example Request\n\n```json\n{\n  \"library_id\": \"cc23c3a7-f8fb-451a-a78d-2a16df1b725a\",\n  \"name\": \"My Favorites\",\n  \"icon\": \"⭐\",\n  \"description\": \"My favorite books\",\n  \"show_on_dashboard\": true,\n  \"auto_assign_rules\": \"\",\n  \"manual_book_ids\": [\"book-id-1\", \"book-id-2\"],\n  \"match_type\": \"all\"\n}\n```\n\n## Response\n\nReturns the created collection with generated ID."
+  - type: tests
+    code: "test(\"status must be 201 with valid request\", function() {\n    expect(res.status).to.eql(201);\n\
+      });\n\ntest(\"response contains collection id\", function() {\n    expect(res.body.id).to.exist;\n\
+            expect(res.body.id).to.be.a('string');\n  });\n\ntest(\"response contains\
+      \ collection name\", function() {\n    expect(res.body.name).to.eql(\"My Favorites\"\
+      );\n  });"
+
+docs: |-
+  Create a custom collection with manually selected books.
+
+  **Endpoint**: POST /api/collections
+  **Auth**: Required (Bearer token)
+
+  ## Example Request
+
+  ```json
+  {
+    "library_id": "cc23c3a7-f8fb-451a-a78d-2a16df1b725a",
+    "name": "My Favorites",
+    "icon": "⭐",
+    "description": "My favorite books",
+    "show_on_dashboard": true,
+    "auto_assign_rules": "",
+    "manual_book_ids": ["book-id-1", "book-id-2"],
+    "match_type": "all"
+  }
+  ```
+
+  ## Response
+
+  Returns the created collection with generated ID.

bruno/collections/create-custom-section-missing-fields.yml

@@ -8,12 +8,16 @@ http:
   auth: inherit
   body:
     type: json
-    data: "{\n  \"library_id\": \"{{library_id}}\",\n  \"icon\": \"\U0001F4DA\"\n}"
+    jsonBody: "{\n  \"library_id\": \"{{library_id}}\",\n  \"icon\": \"📚\"\
+      \n}"
 runtime:
   scripts:
-  - type: after-response
-    code: "function onResponse(res) {\ntest(\"status must be 400 with missing name\", function() {\n    expect(res.status).to.eql(400);\n});\n\ntest(\"response contains error message\", function() {\n    expect(res.body.error).to.exist;\n  });\n}"
-docs: 'Test error handling when creating a collection without required fields.
+  - type: tests
+    code: "test(\"status must be 400 with missing name\", function() {\n    expect(res.status).to.eql(400);\n\
+      });\n\ntest(\"response contains error message\", function() {\n    expect(res.body.error).to.exist;\n\
+      \  });"
 
+docs: |-
+  Test error handling when creating a collection without required fields.
 
-  **Expected Response**: 400 Bad Request with error message.'
+  **Expected Response**: 400 Bad Request with error message.

bruno/collections/create-custom-section-rules.yml

@@ -8,10 +8,57 @@ http:
   auth: inherit
   body:
     type: json
-    data: "{\n  \"library_id\": \"{{library_id}}\",\n  \"name\": \"Science Fiction Books\",\n  \"icon\": \"\U0001F680\",\n  \"description\": \"All my sci-fi books\",\n  \"show_on_dashboard\": true,\n  \"auto_assign_rules\": \"{\\\"rules\\\":[{\\\"id\\\":\\\"rule1\\\",\\\"field\\\":\\\"genre\\\",\\\"operator\\\":\\\"equals\\\",\\\"value\\\":\\\"Sci-Fi\\\",\\\"priority\\\":1}]}\",\n  \"manual_book_ids\": [],\n  \"match_type\": \"all\"\n}"
+    jsonBody: "{\n  \"library_id\": \"{{library_id}}\",\n  \"name\": \"Science Fiction\
+      \ Books\",\n  \"icon\": \"🚀\",\n  \"description\": \"All my sci-fi books\",\n\
+      \  \"show_on_dashboard\": true,\n  \"auto_assign_rules\": \"{\\\"rules\\\":[{\\\
+      \"id\\\":\\\"rule1\\\",\\\"field\\\":\\\"genre\\\",\\\"operator\\\":\\\"equals\\\"\
+      ,\\\"value\\\":\\\"Sci-Fi\\\",\\\"priority\\\":1}]}\",\n  \"manual_book_ids\"\
+      : [],\n  \"match_type\": \"all\"\n}"
 runtime:
   scripts:
-  - type: after-response
-    code: "function onResponse(res) {\ntest(\"status must be 201 with valid request\", function() {\n    expect(res.status).to.eql(201);\n});\n\ntest(\"response contains collection id\", function() {\n    expect(res.body.id).to.exist;\nexpect(res.body.id).to.be.a('string');\n  });\n\ntest(\"response contains collection name\", function() {\n    expect(res.body.name).to.eql(\"Science Fiction Books\");\n  });\n\ntest(\"response contains is_system false\", function() {\n    expect(res.body.is_system).to.exist;\n    expect(res.body.is_system).to.eql(false);\n  });\n}"
-docs: "Create a custom collection with filter rules.\n\n**Endpoint**: POST /api/collections\n**Auth**: Required (Bearer token)\n\n## Request Body\n\n| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n| library_id | string | Yes | Library UUID |\n| name | string | Yes | Collection name |\n| icon | string | No | Emoji icon |\n| description | string | No | Collection description |\n| show_on_dashboard | boolean | No | Show on dashboard (default: true) |\n| auto_assign_rules | string | No | JSON string of filter rules |\n| manual_book_ids | array | No | Array of book IDs |\n| match_type | string | No | \"all\" (AND) or \"any\" (OR) |\n\n## Example Request\n\n```json\n{\n  \"library_id\": \"cc23c3a7-f8fb-451a-a78d-2a16df1b725a\",\n  \"name\": \"Science Fiction Books\",\n  \"icon\": \"\U0001F680\",\n  \"description\": \"All my sci-fi books\",\n  \"show_on_dashboard\": true,\n  \"auto_assign_rules\": \"{\\\"rules\\\":[{\\\"id\\\":\\\"rule1\\\",\\\"field\\\":\\\
-  \"genre\\\",\\\"operator\\\":\\\"equals\\\",\\\"value\\\":\\\"Sci-Fi\\\",\\\"priority\\\":1}]}\",\n  \"manual_book_ids\": [],\n  \"match_type\": \"all\"\n}\n```\n\n## Response\n\nReturns the created collection with generated ID."
+  - type: tests
+    code: "test(\"status must be 201 with valid request\", function() {\n    expect(res.status).to.eql(201);\n\
+      });\n\ntest(\"response contains collection id\", function() {\n    expect(res.body.id).to.exist;\n\
+            expect(res.body.id).to.be.a('string');\n  });\n\ntest(\"response contains\
+      \ collection name\", function() {\n    expect(res.body.name).to.eql(\"Science\
+      \ Fiction Books\");\n  });\n\ntest(\"response contains is_system false\", function()\
+      \ {\n    expect(res.body.is_system).to.exist;\n    expect(res.body.is_system).to.eql(false);\n\
+      \  });"
+
+docs: |-
+  Create a custom collection with filter rules.
+
+  **Endpoint**: POST /api/collections
+  **Auth**: Required (Bearer token)
+
+  ## Request Body
+
+  | Field | Type | Required | Description |
+  |-------|------|----------|-------------|
+  | library_id | string | Yes | Library UUID |
+  | name | string | Yes | Collection name |
+  | icon | string | No | Emoji icon |
+  | description | string | No | Collection description |
+  | show_on_dashboard | boolean | No | Show on dashboard (default: true) |
+  | auto_assign_rules | string | No | JSON string of filter rules |
+  | manual_book_ids | array | No | Array of book IDs |
+  | match_type | string | No | "all" (AND) or "any" (OR) |
+
+  ## Example Request
+
+  ```json
+  {
+    "library_id": "cc23c3a7-f8fb-451a-a78d-2a16df1b725a",
+    "name": "Science Fiction Books",
+    "icon": "🚀",
+    "description": "All my sci-fi books",
+    "show_on_dashboard": true,
+    "auto_assign_rules": "{\"rules\":[{\"id\":\"rule1\",\"field\":\"genre\",\"operator\":\"equals\",\"value\":\"Sci-Fi\",\"priority\":1}]}",
+    "manual_book_ids": [],
+    "match_type": "all"
+  }
+  ```
+
+  ## Response
+
+  Returns the created collection with generated ID.

bruno/collections/preview-collection.yml

@@ -8,9 +8,53 @@ http:
   auth: inherit
   body:
     type: json
-    data: "{\n  \"library_id\": \"{{library_id}}\",\n  \"rules\": [\n{\n      \"id\": \"rule1\",\n      \"field\": \"genre\",\n\"operator\": \"equals\",\n      \"value\": \"Fiction\",\n\"priority\": 1\n    }\n  ],\n  \"manual_book_ids\": [],\n  \"limit\": 20\n}"
+    jsonBody: "{\n  \"library_id\": \"{{library_id}}\",\n  \"rules\": [\n\
+      {\n      \"id\": \"rule1\",\n      \"field\": \"genre\",\n\
+      \"operator\": \"equals\",\n      \"value\": \"Fiction\",\n\
+      \"priority\": 1\n    }\n  ],\n  \"manual_book_ids\": [],\n  \"limit\": 20\n}"
 runtime:
   scripts:
-  - type: after-response
-    code: "function onResponse(res) {\ntest(\"status must be 200 with valid request\", function() {\n    expect(res.status).to.eql(200);\n});\n\ntest(\"response contains items array\", function() {\n    expect(res.body.items).to.exist;\nexpect(res.body.items).to.be.an('array');\n  });\n}"
-docs: "Preview collection with filter rules before saving.\n\n**Endpoint**: POST /api/collections/preview\n**Auth**: Required (Bearer token)\n\n## Request Body\n\n| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n| library_id | string | Yes | Library UUID |\n| rules | array | No | Filter rules to evaluate |\n| manual_book_ids | array | No | Manually selected book IDs |\n| limit | int | No | Max items to return (default: 20, max: 100) |\n\n## Example Request\n\n```json\n{\n  \"library_id\": \"cc23c3a7-f8fb-451a-a78d-2a16df1b725a\",\n  \"rules\": [\n    {\n      \"id\": \"rule1\",\n      \"field\": \"genre\",\n      \"operator\": \"equals\",\n      \"value\": \"Fiction\",\n      \"priority\": 1\n    }\n  ],\n  \"manual_book_ids\": [],\n  \"limit\": 20\n}\n```\n\n## Response\n\nReturns array of matching book items.\n\nThis endpoint is used by the Custom Section Builder to show users what books will match their filter rules before they save the collection."
+  - type: tests
+    code: "test(\"status must be 200 with valid request\", function() {\n    expect(res.status).to.eql(200);\n\
+      });\n\ntest(\"response contains items array\", function() {\n    expect(res.body.items).to.exist;\n\
+         expect(res.body.items).to.be.an('array');\n  });"
+
+docs: |-
+  Preview collection with filter rules before saving.
+
+  **Endpoint**: POST /api/collections/preview
+  **Auth**: Required (Bearer token)
+
+  ## Request Body
+
+  | Field | Type | Required | Description |
+  |-------|------|----------|-------------|
+  | library_id | string | Yes | Library UUID |
+  | rules | array | No | Filter rules to evaluate |
+  | manual_book_ids | array | No | Manually selected book IDs |
+  | limit | int | No | Max items to return (default: 20, max: 100) |
+
+  ## Example Request
+
+  ```json
+  {
+    "library_id": "cc23c3a7-f8fb-451a-a78d-2a16df1b725a",
+    "rules": [
+      {
+        "id": "rule1",
+        "field": "genre",
+        "operator": "equals",
+        "value": "Fiction",
+        "priority": 1
+      }
+    ],
+    "manual_book_ids": [],
+    "limit": 20
+  }
+  ```
+
+  ## Response
+
+  Returns array of matching book items.
+
+  This endpoint is used by the Custom Section Builder to show users what books will match their filter rules before they save the collection.

bruno/collections/scenarios/Bulk Add Books to Collections.yml

@@ -8,11 +8,46 @@ http:
   auth: inherit
   body:
     type: json
-    data: "{\n    \"operations\": [\n      {\n        \"collection_id\": \"{{collectionId1"
+    jsonBody: "{\n    \"operations\": [\n      {\n        \"collection_id\": \"{{collectionId1"
   headers:
   - key: Content-Type
     value: application/json
   - key: Authorization
     value: Bearer {{authToken
-docs: "## Bulk Add Books to Collections\n\n  Adds multiple books to multiple collections in a single request. Each operation specifies a collection and a list of books to add.\n\n  **Method:** POST\n\n  **Endpoint:** /api/collections/bulk-add-books\n\n  **Authentication:** Bearer token\n\n  **Request Body:**\n  - `operations` (array): Array of collection-book operations\n    - `collection_id` (string): Collection UUID\n    - `book_ids` (array): Array of book UUIDs to add to the collection\n\n  **Response:**\n  - `results` (array): Results for each operation\n  - `total` (number): Total number of operations\n  - `success` (number): Number of successful operations\n  - `failed` (number): Number of failed operations\n\n  **Status Codes:**\n  - 200: Success (with partial results if some failed)\n  - 400: Invalid request data\n  - 401: Unauthorized\n  - 403: Forbidden\n  - 500: Internal server error\n\n  **Example:**\n  ```json\n  {\n    \"operations\": [\n      {\n        \"collection_id\":\
-  \ \"collection-uuid-1\",\n        \"book_ids\": [\"book-1\", \"book-2\"]"
+
+docs: |-
+  ## Bulk Add Books to Collections
+  
+    Adds multiple books to multiple collections in a single request. Each operation specifies a collection and a list of books to add.
+  
+    **Method:** POST
+  
+    **Endpoint:** /api/collections/bulk-add-books
+  
+    **Authentication:** Bearer token
+  
+    **Request Body:**
+    - `operations` (array): Array of collection-book operations
+      - `collection_id` (string): Collection UUID
+      - `book_ids` (array): Array of book UUIDs to add to the collection
+  
+    **Response:**
+    - `results` (array): Results for each operation
+    - `total` (number): Total number of operations
+    - `success` (number): Number of successful operations
+    - `failed` (number): Number of failed operations
+  
+    **Status Codes:**
+    - 200: Success (with partial results if some failed)
+    - 400: Invalid request data
+    - 401: Unauthorized
+    - 403: Forbidden
+    - 500: Internal server error
+  
+    **Example:**
+    ```json
+    {
+      "operations": [
+        {
+          "collection_id": "collection-uuid-1",
+          "book_ids": ["book-1", "book-2"]

bruno/collections/scenarios/Bulk Remove Books - All Books.yml

@@ -8,8 +8,16 @@ http:
   auth: inherit
   body:
     type: json
-    data: "{\n    \"book_ids\": [\n      \"{{bookId1"
+    jsonBody: "{\n    \"book_ids\": [\n      \"{{bookId1"
   headers:
   - key: Content-Type
     value: application/json
-docs: "## Bulk Remove Books from Collection\n\n  Removes multiple books from a collection in a single request.\n\n  **Method:** POST\n\n  **Endpoint:** /api/collections/{collection_id"
+
+docs: |-
+  ## Bulk Remove Books from Collection
+  
+    Removes multiple books from a collection in a single request.
+  
+    **Method:** POST
+  
+    **Endpoint:** /api/collections/{collection_id

bruno/collections/scenarios/Bulk Remove Books - Empty List.yml

@@ -8,10 +8,20 @@ http:
   auth: inherit
   body:
     type: json
-    data: "{\n    \"book_ids\": []"
+    jsonBody: "{\n    \"book_ids\": []"
   headers:
   - key: Content-Type
     value: application/json
   - key: Authorization
     value: Bearer {{authToken
-docs: "## Bulk Remove Books - Empty List Validation\n\n  Tests validation behavior when providing an empty book_ids array.\n\n  **Expected Result:** 400 Bad Request\n\n  **Validation Rule:** book_ids array must contain at least one book UUID.\n\n  **Purpose:** Ensures the API properly validates input and rejects empty removal requests."
+
+docs: |-
+  ## Bulk Remove Books - Empty List Validation
+  
+    Tests validation behavior when providing an empty book_ids array.
+  
+    **Expected Result:** 400 Bad Request
+  
+    **Validation Rule:** book_ids array must contain at least one book UUID.
+  
+    **Purpose:** Ensures the API properly validates input and rejects empty removal requests.

bruno/collections/scenarios/Bulk Remove Books - Invalid IDs.yml

@@ -8,10 +8,24 @@ http:
   auth: inherit
   body:
     type: json
-    data: "{\n    \"book_ids\": [\n      \"{{bookId1"
+    jsonBody: "{\n    \"book_ids\": [\n      \"{{bookId1"
   headers:
   - key: Content-Type
     value: application/json
   - key: Authorization
     value: Bearer {{authToken
-docs: "## Bulk Remove Books - Invalid IDs\n\n  Tests behavior when the book_ids array contains invalid UUID formats or non-existent books.\n\n  **Expected Result:** 200 OK with partial success\n\n  **Purpose:** Verifies that:\n  - Invalid UUID formats don't crash the endpoint\n  - Non-existent book IDs are handled gracefully\n  - Valid IDs in the same request are still processed\n  - Response includes detailed results showing which succeeded/failed\n\n  **Note:** The endpoint should process all valid IDs and report failures for invalid ones, allowing clients to handle partial failures appropriately."
+
+docs: |-
+  ## Bulk Remove Books - Invalid IDs
+  
+    Tests behavior when the book_ids array contains invalid UUID formats or non-existent books.
+  
+    **Expected Result:** 200 OK with partial success
+  
+    **Purpose:** Verifies that:
+    - Invalid UUID formats don't crash the endpoint
+    - Non-existent book IDs are handled gracefully
+    - Valid IDs in the same request are still processed
+    - Response includes detailed results showing which succeeded/failed
+  
+    **Note:** The endpoint should process all valid IDs and report failures for invalid ones, allowing clients to handle partial failures appropriately.

bruno/collections/scenarios/Bulk Remove Books - Single Book.yml

@@ -8,10 +8,20 @@ http:
   auth: inherit
   body:
     type: json
-    data: "{\n    \"book_ids\": [\n      \"{{bookId1"
+    jsonBody: "{\n    \"book_ids\": [\n      \"{{bookId1"
   headers:
   - key: Content-Type
     value: application/json
   - key: Authorization
     value: Bearer {{authToken
-docs: "## Bulk Remove Books - Single Book\n\n  Tests that bulk remove endpoint works correctly with a single book.\n\n  **Expected Result:** 200 OK with removed: 1, total: 1\n\n  **Purpose:** Verifies the bulk remove endpoint handles single-item arrays correctly, providing flexibility for clients to use the same endpoint for both single and multiple removals.\n\n  **Note:** Using bulk remove for a single book is functionally equivalent to the single remove endpoint but allows for consistent error handling and response format."
+
+docs: |-
+  ## Bulk Remove Books - Single Book
+  
+    Tests that bulk remove endpoint works correctly with a single book.
+  
+    **Expected Result:** 200 OK with removed: 1, total: 1
+  
+    **Purpose:** Verifies the bulk remove endpoint handles single-item arrays correctly, providing flexibility for clients to use the same endpoint for both single and multiple removals.
+  
+    **Note:** Using bulk remove for a single book is functionally equivalent to the single remove endpoint but allows for consistent error handling and response format.

bruno/collections/scenarios/Test Collection Rules - Author Contains.yml

@@ -8,10 +8,23 @@ http:
   auth: inherit
   body:
     type: json
-    data: "{\n    \"rules\": [\n      {\n        \"field\": \"author\",\n        \"operator\": \"contains\",\n        \"value\": \"Asimov\""
+    jsonBody: "{\n    \"rules\": [\n      {\n        \"field\": \"author\",\n    \
+      \    \"operator\": \"contains\",\n        \"value\": \"Asimov\""
   headers:
   - key: Content-Type
     value: application/json
   - key: Authorization
     value: Bearer {{authToken
-docs: "## Test Collection Rules - Author Contains\n\n  Tests the \"contains\" operator on the author field to find books by a specific author (partial match).\n\n  **Example Use Case:** Finding all books by an author whose name contains \"Asimov\" (e.g., \"Isaac Asimov\").\n\n  **Operator:** `contains` - Matches if the field contains the specified value as a substring (case-insensitive typically).\n\n  **Expected Result:** Returns all books where the author field contains \"Asimov\".\n\n  **Purpose:** Demonstrates text-based partial matching for author searches, useful when you don't need the exact author name or want to find books by authors with similar names."
+
+docs: |-
+  ## Test Collection Rules - Author Contains
+  
+    Tests the "contains" operator on the author field to find books by a specific author (partial match).
+  
+    **Example Use Case:** Finding all books by an author whose name contains "Asimov" (e.g., "Isaac Asimov").
+  
+    **Operator:** `contains` - Matches if the field contains the specified value as a substring (case-insensitive typically).
+  
+    **Expected Result:** Returns all books where the author field contains "Asimov".
+  
+    **Purpose:** Demonstrates text-based partial matching for author searches, useful when you don't need the exact author name or want to find books by authors with similar names.

bruno/collections/scenarios/Test Collection Rules - Copyright Year Greater Than.yml

@@ -8,10 +8,25 @@ http:
   auth: inherit
   body:
     type: json
-    data: "{\n    \"rules\": [\n      {\n        \"field\": \"copyright_year\",\n        \"operator\": \"greater_than\",\n        \"value\": \"2000\""
+    jsonBody: "{\n    \"rules\": [\n      {\n        \"field\": \"copyright_year\"\
+      ,\n        \"operator\": \"greater_than\",\n        \"value\": \"2000\""
   headers:
   - key: Content-Type
     value: application/json
   - key: Authorization
     value: Bearer {{authToken
-docs: "## Test Collection Rules - Copyright Year Greater Than\n\n  Tests the \"greater_than\" operator on the copyright_year field to find books published after a specific year.\n\n  **Example Use Case:** Creating a \"Modern Books\" collection with books published after 2000.\n\n  **Operator:** `greater_than` - Matches if the field value is greater than the specified value (numeric comparison).\n\n  **Field:** `copyright_year` - The year the book was copyrighted/published.\n\n  **Expected Result:** Returns all books with copyright_year greater than 2000 (i.e., published in 2001 or later).\n\n  **Purpose:** Demonstrates numeric comparison operators for creating date-based collections, useful for organizing books by publication era."
+
+docs: |-
+  ## Test Collection Rules - Copyright Year Greater Than
+  
+    Tests the "greater_than" operator on the copyright_year field to find books published after a specific year.
+  
+    **Example Use Case:** Creating a "Modern Books" collection with books published after 2000.
+  
+    **Operator:** `greater_than` - Matches if the field value is greater than the specified value (numeric comparison).
+  
+    **Field:** `copyright_year` - The year the book was copyrighted/published.
+  
+    **Expected Result:** Returns all books with copyright_year greater than 2000 (i.e., published in 2001 or later).
+  
+    **Purpose:** Demonstrates numeric comparison operators for creating date-based collections, useful for organizing books by publication era.

bruno/collections/scenarios/Test Collection Rules - Empty Rules Array.yml

@@ -8,10 +8,22 @@ http:
   auth: inherit
   body:
     type: json
-    data: "{\n    \"rules\": []"
+    jsonBody: "{\n    \"rules\": []"
   headers:
   - key: Content-Type
     value: application/json
   - key: Authorization
     value: Bearer {{authToken
-docs: "## Test Collection Rules - Empty Rules Array\n\n  Tests validation behavior when providing an empty rules array.\n\n  **Expected Result:** 400 Bad Request\n\n  **Validation Rule:** rules array must contain at least one rule object.\n\n  **Purpose:** Ensures the API properly validates input and rejects empty rule sets, preventing accidental queries that would return all books or cause performance issues.\n\n  **Use Case:** Client-side validation should prevent sending empty rules, but the API should also validate to catch malformed requests."
+
+docs: |-
+  ## Test Collection Rules - Empty Rules Array
+  
+    Tests validation behavior when providing an empty rules array.
+  
+    **Expected Result:** 400 Bad Request
+  
+    **Validation Rule:** rules array must contain at least one rule object.
+  
+    **Purpose:** Ensures the API properly validates input and rejects empty rule sets, preventing accidental queries that would return all books or cause performance issues.
+  
+    **Use Case:** Client-side validation should prevent sending empty rules, but the API should also validate to catch malformed requests.

bruno/collections/scenarios/Test Collection Rules - No Matches.yml

@@ -8,10 +8,27 @@ http:
   auth: inherit
   body:
     type: json
-    data: "{\n    \"rules\": [\n      {\n        \"field\": \"genre\",\n        \"operator\": \"equals\",\n        \"value\": \"NonExistentGenre123456\""
+    jsonBody: "{\n    \"rules\": [\n      {\n        \"field\": \"genre\",\n     \
+      \   \"operator\": \"equals\",\n        \"value\": \"NonExistentGenre123456\""
   headers:
   - key: Content-Type
     value: application/json
   - key: Authorization
     value: Bearer {{authToken
-docs: "## Test Collection Rules - No Matches\n\n  Tests behavior when collection rules don't match any books in the library.\n\n  **Example Use Case:** Validating that a new genre name doesn't exist before creating a collection for it, or testing edge cases.\n\n  **Expected Result:** 200 OK with empty matches array and total: 0\n\n  **Purpose:** Verifies that the API handles zero-match scenarios gracefully:\n  - Returns 200 (success) not 404\n  - Returns empty array, not null\n  - Returns total: 0 for clarity\n  - No errors thrown for no results\n\n  **Note:** An empty result set is a valid response and doesn't indicate an error. This allows users to test rules confidently before creating collections."
+
+docs: |-
+  ## Test Collection Rules - No Matches
+  
+    Tests behavior when collection rules don't match any books in the library.
+  
+    **Example Use Case:** Validating that a new genre name doesn't exist before creating a collection for it, or testing edge cases.
+  
+    **Expected Result:** 200 OK with empty matches array and total: 0
+  
+    **Purpose:** Verifies that the API handles zero-match scenarios gracefully:
+    - Returns 200 (success) not 404
+    - Returns empty array, not null
+    - Returns total: 0 for clarity
+    - No errors thrown for no results
+  
+    **Note:** An empty result set is a valid response and doesn't indicate an error. This allows users to test rules confidently before creating collections.

bruno/collections/scenarios/Test Collection Rules.yml

@@ -8,11 +8,60 @@ http:
   auth: inherit
   body:
     type: json
-    data: "{\n    \"rules\": [\n      {\n        \"field\": \"genre\",\n        \"operator\": \"equals\",\n        \"value\": \"Science Fiction\""
+    jsonBody: "{\n    \"rules\": [\n      {\n        \"field\": \"genre\",\n     \
+      \   \"operator\": \"equals\",\n        \"value\": \"Science Fiction\""
   headers:
   - key: Content-Type
     value: application/json
   - key: Authorization
     value: Bearer {{authToken
-docs: "## Test Collection Rules\n\n  Tests collection rules against the library to see which books match, without creating a collection. Useful for previewing what books would be included in a collection with specific rules.\n\n  **Method:** POST\n\n  **Endpoint:** /api/collections/test-rules\n\n  **Authentication:** Bearer token\n\n  **Request Body:**\n  - `rules` (array): Array of rule objects to test\n    - `field` (string): Field to test (genre, author, copyright_year, tags, etc.)\n    - `operator` (string): Comparison operator\n      - `equals`: Exact match\n      - `contains`: Contains substring (for text fields)\n      - `greater_than`: Greater than (for numeric fields)\n      - `less_than`: Less than (for numeric fields)\n      - `not_equals`: Not equal to\n      - `starts_with`: Starts with\n      - `ends_with`: Ends with\n      - `is_empty`: Field is empty or null\n      - `is_not_empty`: Field is not empty and not null\n    - `value` (string): Value to compare against (not required\
-  \ for is_empty/is_not_empty)\n\n  **Response:**\n  - `matches` (array): Array of matching books\n    - `id` (string): Book UUID\n    - `title` (string): Book title\n    - `author` (string): Book author\n    - `genre` (string): Book genre\n    - Additional book metadata\n  - `total` (number): Total number of matching books\n\n  **Status Codes:**\n  - 200: Success - returns matching books\n  - 400: Invalid request (empty rules array, invalid field/operator)\n  - 401: Unauthorized\n  - 500: Internal server error\n\n  **Example Request:**\n  ```json\n  {\n    \"rules\": [\n      {\n        \"field\": \"genre\",\n        \"operator\": \"equals\",\n        \"value\": \"Science Fiction\""
+
+docs: |-
+  ## Test Collection Rules
+  
+    Tests collection rules against the library to see which books match, without creating a collection. Useful for previewing what books would be included in a collection with specific rules.
+  
+    **Method:** POST
+  
+    **Endpoint:** /api/collections/test-rules
+  
+    **Authentication:** Bearer token
+  
+    **Request Body:**
+    - `rules` (array): Array of rule objects to test
+      - `field` (string): Field to test (genre, author, copyright_year, tags, etc.)
+      - `operator` (string): Comparison operator
+        - `equals`: Exact match
+        - `contains`: Contains substring (for text fields)
+        - `greater_than`: Greater than (for numeric fields)
+        - `less_than`: Less than (for numeric fields)
+        - `not_equals`: Not equal to
+        - `starts_with`: Starts with
+        - `ends_with`: Ends with
+        - `is_empty`: Field is empty or null
+        - `is_not_empty`: Field is not empty and not null
+      - `value` (string): Value to compare against (not required for is_empty/is_not_empty)
+  
+    **Response:**
+    - `matches` (array): Array of matching books
+      - `id` (string): Book UUID
+      - `title` (string): Book title
+      - `author` (string): Book author
+      - `genre` (string): Book genre
+      - Additional book metadata
+    - `total` (number): Total number of matching books
+  
+    **Status Codes:**
+    - 200: Success - returns matching books
+    - 400: Invalid request (empty rules array, invalid field/operator)
+    - 401: Unauthorized
+    - 500: Internal server error
+  
+    **Example Request:**
+    ```json
+    {
+      "rules": [
+        {
+          "field": "genre",
+          "operator": "equals",
+          "value": "Science Fiction"

bruno/conflicts/Resolve Conflict.yml

@@ -8,8 +8,18 @@ http:
   auth: inherit
   body:
     type: json
-    data: "{\n    \"winner\": \"koreader\",\n    \"manual_data\": null,\n    \"apply_to_all_future_conflicts\": false,\n    \"reason\": \"User chose more recent progress\""
+    jsonBody: "{\n    \"winner\": \"koreader\",\n    \"manual_data\": null,\n    \"\
+      apply_to_all_future_conflicts\": false,\n    \"reason\": \"User chose more recent\
+      \ progress\""
   headers:
   - key: Authorization
     value: Bearer {{token
-docs: "## Resolve Conflict\n\n  Resolves a sync conflict by choosing which source to use for the conflicting data.\n\n  **Method:** POST\n\n  **Endpoint:** /api/conflicts/{conflict_id"
+
+docs: |-
+  ## Resolve Conflict
+  
+    Resolves a sync conflict by choosing which source to use for the conflicting data.
+  
+    **Method:** POST
+  
+    **Endpoint:** /api/conflicts/{conflict_id

bruno/conflicts/scenarios/Bulk Dismiss Conflicts.yml

@@ -8,10 +8,42 @@ http:
   auth: inherit
   body:
     type: json
-    data: "{\n    \"conflict_ids\": [\n      \"{{conflictId1"
+    jsonBody: "{\n    \"conflict_ids\": [\n      \"{{conflictId1"
   headers:
   - key: Content-Type
     value: application/json
   - key: Authorization
     value: Bearer {{authToken
-docs: "## Bulk Dismiss Conflicts\n\n  Dismisses multiple sync conflicts without resolving them. This removes them from the conflict list while leaving the data unchanged.\n\n  **Method:** POST\n\n  **Endpoint:** /api/conflicts/bulk-dismiss\n\n  **Authentication:** Bearer token\n\n  **Request Body:**\n  - `conflict_ids` (array): Array of conflict UUIDs to dismiss\n\n  **Response:**\n  - `results` (array): Results for each dismissal\n  - `total` (number): Total number of conflicts processed\n  - `success` (number): Number of successfully dismissed conflicts\n  - `failed` (number): Number of failed dismissals\n\n  **Status Codes:**\n  - 200: Success\n  - 400: Invalid request data\n  - 401: Unauthorized\n  - 403: Forbidden\n  - 404: One or more conflicts not found\n  - 500: Internal server error\n\n  **Example:**\n  ```json\n  {\n    \"conflict_ids\": [\"uuid-1\", \"uuid-2\"]"
+
+docs: |-
+  ## Bulk Dismiss Conflicts
+  
+    Dismisses multiple sync conflicts without resolving them. This removes them from the conflict list while leaving the data unchanged.
+  
+    **Method:** POST
+  
+    **Endpoint:** /api/conflicts/bulk-dismiss
+  
+    **Authentication:** Bearer token
+  
+    **Request Body:**
+    - `conflict_ids` (array): Array of conflict UUIDs to dismiss
+  
+    **Response:**
+    - `results` (array): Results for each dismissal
+    - `total` (number): Total number of conflicts processed
+    - `success` (number): Number of successfully dismissed conflicts
+    - `failed` (number): Number of failed dismissals
+  
+    **Status Codes:**
+    - 200: Success
+    - 400: Invalid request data
+    - 401: Unauthorized
+    - 403: Forbidden
+    - 404: One or more conflicts not found
+    - 500: Internal server error
+  
+    **Example:**
+    ```json
+    {
+      "conflict_ids": ["uuid-1", "uuid-2"]

bruno/conflicts/scenarios/Bulk Resolve Conflicts.yml

@@ -8,11 +8,48 @@ http:
   auth: inherit
   body:
     type: json
-    data: "{\n    \"conflict_ids\": [\n      \"{{conflictId1"
+    jsonBody: "{\n    \"conflict_ids\": [\n      \"{{conflictId1"
   headers:
   - key: Content-Type
     value: application/json
   - key: Authorization
     value: Bearer {{authToken
-docs: "## Bulk Resolve Conflicts\n\n  Resolves multiple sync conflicts in a single request using a specified resolution strategy.\n\n  **Method:** POST\n\n  **Endpoint:** /api/conflicts/bulk-resolve\n\n  **Authentication:** Bearer token\n\n  **Request Body:**\n  - `conflict_ids` (array): Array of conflict UUIDs to resolve\n  - `strategy` (string): Resolution strategy\n    - `most_recent`: Use the most recently updated progress\n    - `highest_progress`: Use the reading progress with the highest percent read\n    - `server`: Always prefer server-side data\n    - `device`: Always prefer device-side data\n\n  **Response:**\n  - `results` (array): Results for each conflict resolution\n  - `total` (number): Total number of conflicts processed\n  - `success` (number): Number of successfully resolved conflicts\n  - `failed` (number): Number of failed resolutions\n\n  **Status Codes:**\n  - 200: Success (with partial results if some failed)\n  - 400: Invalid request data\n  - 401: Unauthorized\n\
-  \  - 403: Forbidden\n  - 404: One or more conflicts not found\n  - 500: Internal server error\n\n  **Example:**\n  ```json\n  {\n    \"conflict_ids\": [\"uuid-1\", \"uuid-2\", \"uuid-3\"],\n    \"strategy\": \"most_recent\""
+
+docs: |-
+  ## Bulk Resolve Conflicts
+  
+    Resolves multiple sync conflicts in a single request using a specified resolution strategy.
+  
+    **Method:** POST
+  
+    **Endpoint:** /api/conflicts/bulk-resolve
+  
+    **Authentication:** Bearer token
+  
+    **Request Body:**
+    - `conflict_ids` (array): Array of conflict UUIDs to resolve
+    - `strategy` (string): Resolution strategy
+      - `most_recent`: Use the most recently updated progress
+      - `highest_progress`: Use the reading progress with the highest percent read
+      - `server`: Always prefer server-side data
+      - `device`: Always prefer device-side data
+  
+    **Response:**
+    - `results` (array): Results for each conflict resolution
+    - `total` (number): Total number of conflicts processed
+    - `success` (number): Number of successfully resolved conflicts
+    - `failed` (number): Number of failed resolutions
+  
+    **Status Codes:**
+    - 200: Success (with partial results if some failed)
+    - 400: Invalid request data
+    - 401: Unauthorized
+    - 403: Forbidden
+    - 404: One or more conflicts not found
+    - 500: Internal server error
+  
+    **Example:**
+    ```json
+    {
+      "conflict_ids": ["uuid-1", "uuid-2", "uuid-3"],
+      "strategy": "most_recent"

bruno/conflicts/scenarios/Bulk Resolve Highest Progress.yml

@@ -8,11 +8,39 @@ http:
   auth: inherit
   body:
     type: json
-    data: "{\n    \"conflict_ids\": [\n      \"{{conflictId1"
+    jsonBody: "{\n    \"conflict_ids\": [\n      \"{{conflictId1"
   headers:
   - key: Content-Type
     value: application/json
   - key: Authorization
     value: Bearer {{authToken
-docs: "## Bulk Resolve with Highest Progress Strategy\n\n  Resolves multiple sync conflicts using the \"highest_progress\" strategy, which keeps the reading progress with the highest percentage read.\n\n  **Method:** POST\n\n  **Endpoint:** /api/conflicts/bulk-resolve\n\n  **Authentication:** Bearer token\n\n  **Request Body:**\n  - `conflict_ids` (array): Array of conflict UUIDs to resolve\n  - `strategy` (string): Must be \"highest_progress\"\n\n  **Response:**\n  - `results` (array): Results for each conflict resolution\n  - `total` (number): Total number of conflicts processed\n  - `success` (number): Number of successfully resolved conflicts\n  - `failed` (number): Number of failed resolutions\n\n  **Status Codes:**\n  - 200: Success\n  - 400: Invalid request data\n  - 401: Unauthorized\n  - 403: Forbidden\n  - 500: Internal server error\n\n  **Note:** The highest progress strategy is ideal when you want to preserve the most reading progress across devices. Use this when you've been\
-  \ reading on multiple devices and want to keep the furthest position."
+
+docs: |-
+  ## Bulk Resolve with Highest Progress Strategy
+  
+    Resolves multiple sync conflicts using the "highest_progress" strategy, which keeps the reading progress with the highest percentage read.
+  
+    **Method:** POST
+  
+    **Endpoint:** /api/conflicts/bulk-resolve
+  
+    **Authentication:** Bearer token
+  
+    **Request Body:**
+    - `conflict_ids` (array): Array of conflict UUIDs to resolve
+    - `strategy` (string): Must be "highest_progress"
+  
+    **Response:**
+    - `results` (array): Results for each conflict resolution
+    - `total` (number): Total number of conflicts processed
+    - `success` (number): Number of successfully resolved conflicts
+    - `failed` (number): Number of failed resolutions
+  
+    **Status Codes:**
+    - 200: Success
+    - 400: Invalid request data
+    - 401: Unauthorized
+    - 403: Forbidden
+    - 500: Internal server error
+  
+    **Note:** The highest progress strategy is ideal when you want to preserve the most reading progress across devices. Use this when you've been reading on multiple devices and want to keep the furthest position.

bruno/dashboard/restore-system-collection.yml

@@ -8,9 +8,40 @@ http:
   auth: inherit
   body:
     type: json
-    data: "{\n  \"collection_name\": \"continue-reading\"\n}"
+    jsonBody: "{\n  \"collection_name\": \"continue-reading\"\n}"
 runtime:
   scripts:
   - type: tests
-    code: "test(\"status must be 200 with valid collection\", function() {\n    expect(res.status).to.eql(200);\n});\n\ntest(\"response has success message\", function() {\n    expect(res.body.message).to.exist;\n});"
-docs: "Restore a system collection to its default state.\n\n**Endpoint**: POST /api/dashboard/restore-system-collection\n**Auth**: Required (Bearer token)\n\n## Request Body\n\n| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n| collection_name | string | Yes | Name of system collection to restore |\n\nValid collection names:\n- `continue-reading`: Books you're currently reading (0 < progress < 1)\n- `recently-added`: Newly added items to this library\n- `recently-read`: Books you've finished (progress >= 1)\n- `not-started`: Books you haven't read yet (progress = 0 or no record)\n\n## Example Request\n\n```json\n{\n  \"collection_name\": \"continue-reading\"\n}\n```\n\n## Response\n\nReturns success message on restore."
+    code: "test(\"status must be 200 with valid collection\", function() {\n    expect(res.status).to.eql(200);\n\
+      });\n\ntest(\"response has success message\", function() {\n    expect(res.body.message).to.exist;\n\
+      });"
+
+docs: |-
+  Restore a system collection to its default state.
+
+  **Endpoint**: POST /api/dashboard/restore-system-collection
+  **Auth**: Required (Bearer token)
+
+  ## Request Body
+
+  | Field | Type | Required | Description |
+  |-------|------|----------|-------------|
+  | collection_name | string | Yes | Name of system collection to restore |
+
+  Valid collection names:
+  - `continue-reading`: Books you're currently reading (0 < progress < 1)
+  - `recently-added`: Newly added items to this library
+  - `recently-read`: Books you've finished (progress >= 1)
+  - `not-started`: Books you haven't read yet (progress = 0 or no record)
+
+  ## Example Request
+
+  ```json
+  {
+    "collection_name": "continue-reading"
+  }
+  ```
+
+  ## Response
+
+  Returns success message on restore.

bruno/dashboard/update-preferences.yml

@@ -8,9 +8,41 @@ http:
   auth: inherit
   body:
     type: json
-    data: "{\n  \"library_id\": \"{{library_id}}\",\n  \"hidden_collections\": [\"not-started\"],\n  \"collection_order\": [\"recently-added\", \"continue-reading\", \"recently-read\"],\n  \"items_per_section\": 20\n}"
+    jsonBody: "{\n  \"library_id\": \"{{library_id}}\",\n  \"hidden_collections\"\
+      : [\"not-started\"],\n  \"collection_order\": [\"recently-added\", \"continue-reading\"\
+      , \"recently-read\"],\n  \"items_per_section\": 20\n}"
 runtime:
   scripts:
   - type: tests
-    code: "test(\"status must be 200 with valid request\", function() {\n    expect(res.status).to.eql(200);\n});"
-docs: "Update dashboard preferences for the authenticated user.\n\n**Endpoint**: PUT /api/dashboard/preferences\n**Auth**: Required (Bearer token)\n\n## Request Body\n\n| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n| library_id | string | Yes | Library UUID |\n| hidden_collections | array | No | Collection names to hide from dashboard |\n| collection_order | array | No | Collection names in custom display order |\n| items_per_section | int | No | Items to show per section (default: 20) |\n\n## Example Request\n\n```json\n{\n  \"library_id\": \"cc23c3a7-f8fb-451a-a78d-2a16df1b725a\",\n  \"hidden_collections\": [\"not-started\"],\n  \"collection_order\": [\"recently-added\", \"continue-reading\", \"recently-read\"],\n  \"items_per_section\": 20\n}\n```\n\n## Response\n\nReturns updated preferences object on success."
+    code: "test(\"status must be 200 with valid request\", function() {\n    expect(res.status).to.eql(200);\n\
+      });"
+
+docs: |-
+  Update dashboard preferences for the authenticated user.
+
+  **Endpoint**: PUT /api/dashboard/preferences
+  **Auth**: Required (Bearer token)
+
+  ## Request Body
+
+  | Field | Type | Required | Description |
+  |-------|------|----------|-------------|
+  | library_id | string | Yes | Library UUID |
+  | hidden_collections | array | No | Collection names to hide from dashboard |
+  | collection_order | array | No | Collection names in custom display order |
+  | items_per_section | int | No | Items to show per section (default: 20) |
+
+  ## Example Request
+
+  ```json
+  {
+    "library_id": "cc23c3a7-f8fb-451a-a78d-2a16df1b725a",
+    "hidden_collections": ["not-started"],
+    "collection_order": ["recently-added", "continue-reading", "recently-read"],
+    "items_per_section": 20
+  }
+  ```
+
+  ## Response
+
+  Returns updated preferences object on success.

bruno/devices/api.yml

@@ -0,0 +1,22 @@
+info:
+  name: Bookhoard Device Management API
+  type: collection
+  seq: 1
+http:
+  method: POST
+  url: '"http://localhost:8765/api"'
+
+docs: |-
+  ## Bookhoard Device Management API
+  
+    Collection of endpoints for managing e-reader devices and their synchronization settings.
+  
+    **Base URL:** http://localhost:8765/api
+  
+    **Authentication:** Most endpoints require Bearer token authentication
+  
+    **Endpoints:**
+    - Device registration and management
+    - Device authentication tokens
+    - Sync configuration
+    - Device-to-collection mappings

bruno/devices/folder.yml

@@ -1,7 +0,0 @@
-info:
-  name: Bookhoard Device Management API
-  type: folder
-  seq: 1
-request:
-  auth: inherit
-docs: "## Bookhoard Device Management API\n\n  Collection of endpoints for managing e-reader devices and their synchronization settings.\n\n  **Base URL:** http://localhost:8765/api\n\n  **Authentication:** Most endpoints require Bearer token authentication\n\n  **Endpoints:**\n  - Device registration and management\n  - Device authentication tokens\n  - Sync configuration\n  - Device-to-collection mappings"

bruno/devices/kobo/Get Analytics Tests.yml

@@ -2,16 +2,95 @@ info:
   name: Get Analytics Tests
   type: http
   seq: 7
+
 http:
   method: POST
-  url: '{{base_url}}/api/sync/kobo/{{kobo_device_token}}/v1/analytics/gettests'
+  url: '{{base_url}}/api/sync/kobo/v1/analytics/gettests'
   auth: inherit
   headers:
-  - key: Content-Type
-    value: application/json
+    - key: Content-Type
+      value: application/json
   body:
     type: json
-    data: "{\n  \"platform\": \"android\",\n  \"firmware_version\": \"4.30.19023\"\n}"
-docs: "## Get Kobo Analytics Tests\n\nRetrieves A/B testing configuration and feature flags for Kobo device.\n\n**Method:** POST\n\n**Endpoint:** /api/sync/kobo/v1/analytics/gettests\n\n**Authentication:** Bearer token\n\n**Request Body:**\n- `platform` (string): Device platform\n  - `android`: Kobo Android app\n  - `kobo`: Native Kobo firmware\n- `firmware_version` (string): Firmware version (e.g., \"4.30.19023\")\n- `device_model` (string, optional): Device model identifier\n- `locale` (string, optional): Device locale (e.g., \"en_US\")\n\n**Response:**\n- `tests` (array): Active A/B tests\n  - `test_name` (string): Test identifier\n  - `variant` (string): Assigned variant (A, B, C, etc.)\n  - `enabled` (boolean): Whether test is active\n  - `parameters` (object): Test-specific parameters\n- `features` (object): Feature flags\n  - `feature_name` (boolean/string): Feature state\n- `configuration` (object): Device configuration\n  - `sync_interval_minutes` (integer): Recommended sync frequency\n\
-  \  - `batch_size` (integer): Max items per batch sync\n  - `timeout_seconds` (integer): Request timeout\n- `version` (string): Configuration version\n\n**Status Codes:**\n- 200: Success\n- 401: Unauthorized\n- 400: Invalid request parameters\n\n**Analytics Testing Purpose:**\n- Kobo uses A/B testing for UX features\n- Feature flags for gradual rollout\n- Performance monitoring configuration\n- Sync behavior optimization\n- Device-specific tuning\n\n**Common Tests:**\n- Sync frequency optimization\n- UI/UX variations\n- Network usage patterns\n- Battery life improvements\n- Feature set variations by model\n\n**Feature Flags:**\n- New sync features\n- Beta functionality\n- Platform-specific capabilities\n- Experimental features\n\n**Configuration Parameters:**\n- Optimal sync intervals for device\n- Batch size limits based on device capabilities\n- Timeout values for network conditions\n- Retry logic configuration\n- Cache policy settings\n\n**Usage:**\n- Called during device initialization\n\
-  - Refreshed daily or weekly\n- Cached on device\n- Affects sync behavior\n- Can be overridden by server\n\n**Use Cases:**\n- Device initialization\n- Feature rollout testing\n- Performance optimization\n- UX experiment participation\n- Configuration management"
+    json:
+      platform: android
+      firmware_version: 4.30.19023
+
+docs: |-
+  ## Get Kobo Analytics Tests
+
+  Retrieves A/B testing configuration and feature flags for Kobo device.
+
+  **Method:** POST
+
+  **Endpoint:** /api/sync/kobo/v1/analytics/gettests
+
+  **Authentication:** Bearer token
+
+  **Request Body:**
+  - `platform` (string): Device platform
+    - `android`: Kobo Android app
+    - `kobo`: Native Kobo firmware
+  - `firmware_version` (string): Firmware version (e.g., "4.30.19023")
+  - `device_model` (string, optional): Device model identifier
+  - `locale` (string, optional): Device locale (e.g., "en_US")
+
+  **Response:**
+  - `tests` (array): Active A/B tests
+    - `test_name` (string): Test identifier
+    - `variant` (string): Assigned variant (A, B, C, etc.)
+    - `enabled` (boolean): Whether test is active
+    - `parameters` (object): Test-specific parameters
+  - `features` (object): Feature flags
+    - `feature_name` (boolean/string): Feature state
+  - `configuration` (object): Device configuration
+    - `sync_interval_minutes` (integer): Recommended sync frequency
+    - `batch_size` (integer): Max items per batch sync
+    - `timeout_seconds` (integer): Request timeout
+  - `version` (string): Configuration version
+
+  **Status Codes:**
+  - 200: Success
+  - 401: Unauthorized
+  - 400: Invalid request parameters
+
+  **Analytics Testing Purpose:**
+  - Kobo uses A/B testing for UX features
+  - Feature flags for gradual rollout
+  - Performance monitoring configuration
+  - Sync behavior optimization
+  - Device-specific tuning
+
+  **Common Tests:**
+  - Sync frequency optimization
+  - UI/UX variations
+  - Network usage patterns
+  - Battery life improvements
+  - Feature set variations by model
+
+  **Feature Flags:**
+  - New sync features
+  - Beta functionality
+  - Platform-specific capabilities
+  - Experimental features
+
+  **Configuration Parameters:**
+  - Optimal sync intervals for device
+  - Batch size limits based on device capabilities
+  - Timeout values for network conditions
+  - Retry logic configuration
+  - Cache policy settings
+
+  **Usage:**
+  - Called during device initialization
+  - Refreshed daily or weekly
+  - Cached on device
+  - Affects sync behavior
+  - Can be overridden by server
+
+  **Use Cases:**
+  - Device initialization
+  - Feature rollout testing
+  - Performance optimization
+  - UX experiment participation
+  - Configuration management

bruno/devices/kobo/Get Kobo Library.yml

@@ -5,7 +5,7 @@ info:
 
 http:
   method: GET
-  url: '{{base_url}}/api/sync/kobo/{{kobo_device_token}}/v1/initialization'
+  url: '{{base_url}}/api/sync/kobo/library'
   auth: inherit
 
 docs: |-

bruno/devices/kobo/Get Unlinked Book Suggestions.yml

@@ -4,7 +4,7 @@ info:
   seq: 1
 http:
   method: GET
-  url: '{{base_url}}/api/sync/unlinked-books/{{unlinkedBookId}}/suggestions'
+  url: '{{base_url}}/sync/unlinked-books/{{unlinkedBookId}}/suggestions'
   auth: inherit
   body:
     type: none

bruno/devices/kobo/api.yml

@@ -0,0 +1,22 @@
+info:
+  name: Bookhoard Kobo Sync API
+  type: collection
+  seq: 1
+http:
+  method: POST
+  url: '"http://localhost:8765/api"'
+
+docs: |-
+  ## Bookhoard Kobo Sync API
+  
+    Collection of endpoints specifically for Kobo e-reader device synchronization.
+  
+    **Base URL:** http://localhost:8765/api
+  
+    **Authentication:** Device token or Bearer token required
+  
+    **Endpoints:**
+    - Kobo-specific sync protocols
+    - Kobo store integration
+    - Metadata synchronization
+    - Reading progress sync

bruno/devices/kobo/folder.yml

@@ -1,7 +0,0 @@
-info:
-  name: Bookhoard Kobo Sync API
-  type: folder
-  seq: 1
-request:
-  auth: inherit
-docs: "## Bookhoard Kobo Sync API\n\n  Collection of endpoints specifically for Kobo e-reader device synchronization.\n\n  **Base URL:** http://localhost:8765/api\n\n  **Authentication:** Device token or Bearer token required\n\n  **Endpoints:**\n  - Kobo-specific sync protocols\n  - Kobo store integration\n  - Metadata synchronization\n  - Reading progress sync"

bruno/devices/kobo/scenarios/Auto Link Books.yml

@@ -4,14 +4,42 @@ info:
   seq: 1
 http:
   method: POST
-  url: '{{base_url}}/api/sync/auto-link-books'
+  url: '{{base_url}}/sync/auto-link-books'
   auth: inherit
   body:
     type: json
-    data: "{\n    \"confidence_threshold\": 0.8,\n    \"limit\": 50"
+    jsonBody: "{\n    \"confidence_threshold\": 0.8,\n    \"limit\": 50"
   headers:
   - key: Content-Type
     value: application/json
   - key: Authorization
     value: Bearer {{authToken
-docs: "## Auto-Link Unlinked Books\n\n  Automatically links unlinked books to media items based on title and author matching with a configurable confidence threshold.\n\n  **Method:** POST\n\n  **Endpoint:** /sync/auto-link-books\n\n  **Authentication:** Bearer token\n\n  **Request Body:**\n  - `confidence_threshold` (number, optional): Minimum confidence score for auto-linking (0-1, default: 0.8)\n  - `limit` (number, optional): Maximum number of books to auto-link (default: 50)\n\n  **Response:**\n  - `results` (array): Results for each auto-link attempt\n  - `total` (number): Total number of books processed\n  - `success` (number): Number of successful links\n  - `failed` (number): Number of failed links\n\n  **Status Codes:**\n  - 200: Success\n  - 400: Invalid request data\n  - 401: Unauthorized\n  - 500: Internal server error\n\n  **Note:** Higher confidence thresholds produce fewer but more accurate matches. Consider the tradeoff between automation and accuracy."
+
+docs: |-
+  ## Auto-Link Unlinked Books
+  
+    Automatically links unlinked books to media items based on title and author matching with a configurable confidence threshold.
+  
+    **Method:** POST
+  
+    **Endpoint:** /sync/auto-link-books
+  
+    **Authentication:** Bearer token
+  
+    **Request Body:**
+    - `confidence_threshold` (number, optional): Minimum confidence score for auto-linking (0-1, default: 0.8)
+    - `limit` (number, optional): Maximum number of books to auto-link (default: 50)
+  
+    **Response:**
+    - `results` (array): Results for each auto-link attempt
+    - `total` (number): Total number of books processed
+    - `success` (number): Number of successful links
+    - `failed` (number): Number of failed links
+  
+    **Status Codes:**
+    - 200: Success
+    - 400: Invalid request data
+    - 401: Unauthorized
+    - 500: Internal server error
+  
+    **Note:** Higher confidence thresholds produce fewer but more accurate matches. Consider the tradeoff between automation and accuracy.

bruno/devices/kobo/scenarios/Bulk Link Books.yml

@@ -4,14 +4,44 @@ info:
   seq: 1
 http:
   method: POST
-  url: '{{base_url}}/api/sync/bulk-link-books'
+  url: '{{base_url}}/sync/bulk-link-books'
   auth: inherit
   body:
     type: json
-    data: "{\n    \"links\": [\n      {\n        \"unlinked_book_id\": \"{{unlinkedBookId1"
+    jsonBody: "{\n    \"links\": [\n      {\n        \"unlinked_book_id\": \"{{unlinkedBookId1"
   headers:
   - key: Content-Type
     value: application/json
   - key: Authorization
     value: Bearer {{authToken
-docs: "## Bulk Link Unlinked Books\n\n  Links multiple unlinked books to media items in a single request.\n\n  **Method:** POST\n\n  **Endpoint:** /sync/bulk-link-books\n\n  **Authentication:** Bearer token\n\n  **Request Body:**\n  - `links` (array): Array of link objects\n    - `unlinked_book_id` (string): Unlinked book UUID\n    - `media_item_id` (string): Media item UUID to link to\n    - `confidence_score` (number): Match confidence (0-1)\n\n  **Response:**\n  - `results` (array): Results for each link attempt\n  - `total` (number): Total number of links processed\n  - `success` (number): Number of successful links\n  - `failed` (number): Number of failed links\n\n  **Status Codes:**\n  - 200: Success\n  - 400: Invalid request data\n  - 401: Unauthorized\n  - 500: Internal server error\n\n  **Note:** Use this endpoint after reviewing suggestions from the Get Unlinked Book Suggestions endpoint."
+
+docs: |-
+  ## Bulk Link Unlinked Books
+  
+    Links multiple unlinked books to media items in a single request.
+  
+    **Method:** POST
+  
+    **Endpoint:** /sync/bulk-link-books
+  
+    **Authentication:** Bearer token
+  
+    **Request Body:**
+    - `links` (array): Array of link objects
+      - `unlinked_book_id` (string): Unlinked book UUID
+      - `media_item_id` (string): Media item UUID to link to
+      - `confidence_score` (number): Match confidence (0-1)
+  
+    **Response:**
+    - `results` (array): Results for each link attempt
+    - `total` (number): Total number of links processed
+    - `success` (number): Number of successful links
+    - `failed` (number): Number of failed links
+  
+    **Status Codes:**
+    - 200: Success
+    - 400: Invalid request data
+    - 401: Unauthorized
+    - 500: Internal server error
+  
+    **Note:** Use this endpoint after reviewing suggestions from the Get Unlinked Book Suggestions endpoint.

bruno/devices/kobo/scenarios/Kobo Initialization.yml

@@ -5,7 +5,7 @@ info:
 
 http:
   method: GET
-  url: '{{base_url}}/api/sync/kobo/{{kobo_device_token}}/v1/initialization'
+  url: '{{base_url}}/api/sync/kobo/v1/initialization'
   auth: inherit
 
 docs: |-

bruno/devices/kobo/scenarios/Server Sync to Kobo.yml

@@ -4,13 +4,50 @@ info:
   seq: 1
 http:
   method: POST
-  url: '{{base_url}}/api/sync/kobo/{{kobo_device_token}}/sync-from-server'
+  url: '{{baseURL}}/api/sync/kobo/sync-from-server'
   auth: inherit
   body:
     type: json
-    data: "[\n    {\n      \"ContentId\": \"{{bookUUID"
+    jsonBody: "[\n    {\n      \"ContentId\": \"{{bookUUID"
   headers:
   - key: Authorization
     value: Bearer {{koboToken
-docs: "## Sync from Bookhoard to Kobo\n\n  Server-initiated sync pushing progress, bookmarks, and highlights from Bookhoard to Kobo device. Two-way sync endpoint.\n\n  **Method:** POST\n\n  **Endpoint:** /api/sync/kobo/sync-from-server\n\n  **Authentication:** Bearer token with Kobo device identification\n\n  **Headers:**\n  - `x-kobo-device` (string): JSON string containing Kobo device info\n    - `DeviceId`: Kobo device ID\n    - `Model`: Kobo device model\n    - `SerialNumber`: Kobo device serial number\n\n  **Request Body:** Array of sync data objects\n  - `ContentId` (string): Book UUID\n  - `PercentRead` (number): Reading progress percentage (0-100)\n  - `LastModified` (string): ISO 8601 timestamp\n  - `Bookmarks` (array, optional): Array of bookmark objects\n    - `BookmarkId`: Unique bookmark ID\n    - `ContentId`: Book UUID\n    - `BookmarkText`: Bookmark text/note\n    - `BookmarkType`: Type (bookmark, annotation, etc.)\n    - `BookmarkTitle`: Bookmark title\n  - `Highlights` (array,\
-  \ optional): Array of highlight objects (same structure as bookmarks)\n\n  **Response:**\n  - Sync result confirmation\n\n  **Status Codes:**\n  - 200: Success\n  - 401: Unauthorized\n  - 500: Internal server error\n\n  **Note:** Allows Bookhoard server to push updates to Kobo device, including reading progress, bookmarks, and highlights."
+
+docs: |-
+  ## Sync from Bookhoard to Kobo
+  
+    Server-initiated sync pushing progress, bookmarks, and highlights from Bookhoard to Kobo device. Two-way sync endpoint.
+  
+    **Method:** POST
+  
+    **Endpoint:** /api/sync/kobo/sync-from-server
+  
+    **Authentication:** Bearer token with Kobo device identification
+  
+    **Headers:**
+    - `x-kobo-device` (string): JSON string containing Kobo device info
+      - `DeviceId`: Kobo device ID
+      - `Model`: Kobo device model
+      - `SerialNumber`: Kobo device serial number
+  
+    **Request Body:** Array of sync data objects
+    - `ContentId` (string): Book UUID
+    - `PercentRead` (number): Reading progress percentage (0-100)
+    - `LastModified` (string): ISO 8601 timestamp
+    - `Bookmarks` (array, optional): Array of bookmark objects
+      - `BookmarkId`: Unique bookmark ID
+      - `ContentId`: Book UUID
+      - `BookmarkText`: Bookmark text/note
+      - `BookmarkType`: Type (bookmark, annotation, etc.)
+      - `BookmarkTitle`: Bookmark title
+    - `Highlights` (array, optional): Array of highlight objects (same structure as bookmarks)
+  
+    **Response:**
+    - Sync result confirmation
+  
+    **Status Codes:**
+    - 200: Success
+    - 401: Unauthorized
+    - 500: Internal server error
+  
+    **Note:** Allows Bookhoard server to push updates to Kobo device, including reading progress, bookmarks, and highlights.

bruno/devices/kobo/scenarios/Sync Books from Server to Kobo.yml

@@ -2,16 +2,105 @@ info:
   name: Sync Books from Server to Kobo
   type: http
   seq: 9
+
 http:
   method: POST
-  url: '{{base_url}}/api/sync/kobo/{{kobo_device_token}}/sync-from-server'
+  url: '{{base_url}}/api/sync/kobo/sync-from-server'
   auth: inherit
   headers:
-  - key: Content-Type
-    value: application/json
+    - key: Content-Type
+      value: application/json
   body:
     type: json
-    data: "{\n  \"force_sync\": true,\n  \"books\": [\n    \"book-uuid-1\",\n    \"book-uuid-2\"\n  ]\n}"
-docs: "## Sync Books from Server to Kobo\n\nPulls reading progress, annotations, and bookmarks from server to Kobo device.\n\n**Method:** POST\n\n**Endpoint:** /api/sync/kobo/sync-from-server\n\n**Authentication:** Bearer token\n\n**Request Body:**\n- `force_sync` (boolean): Force full sync (ignore last sync time)\n- `books` (array, optional): List of book UUIDs to sync\n  - If empty, syncs all books with server data\n  - If specified, only syncs listed books\n- `sync_options` (object, optional):\n  - `since_date` (string): ISO 8601 timestamp for incremental sync\n  - `include_annotations` (boolean): Include highlights/notes\n  - `include_progress` (boolean): Include reading progress\n  - `conflict_resolution` (string): `most_recent`, `server_wins`, `client_wins`\n\n**Response:**\n- `synced` (integer): Number of books synced\n- `skipped` (integer): Books with no server changes\n- `failed` (integer): Books that failed to sync\n- `results` (array): Per-book sync results\n  - `book_id` (string):\
-  \ Book UUID\n  - `status` (string): `synced`, `skipped`, `failed`\n  - `progress_pulled` (boolean): Whether progress was downloaded\n  - `annotations_pulled` (integer): Number of annotations downloaded\n  - `error` (string, optional): Error message if failed\n- `server_timestamp` (string): Server timestamp of sync\n\n**Status Codes:**\n- 200: Sync completed\n- 207: Multi-status (some succeeded, some failed)\n- 401: Unauthorized\n- 400: Invalid request\n\n**Sync Direction:**\n- **Server → Device** (this endpoint)\n- Device → Server: Use `/sync/kobo/markup` endpoint\n- Bidirectional sync achieved by calling both\n\n**Pull Sync Use Cases:**\n- New device setup (download all progress)\n- Device replacement (restore from server)\n- Multi-device sync (pull changes from other devices)\n- Conflict resolution (server wins)\n- Manual \"Download from server\" operation\n\n**Conflict Resolution:**\n- `most_recent`: Latest timestamp wins (default)\n- `server_wins`: Server data always used\n- `client_wins`:\
-  \ Device data preserved\n- Applied per-book, per-item\n\n**Sync Optimization:**\n- Incremental sync by default (since last sync)\n- Force sync does full comparison\n- Book-level batching (10 books per batch)\n- Delta transfer (only changed items)\n- Compression for large annotation sets\n\n**Kobo Device Behavior:**\n- Device updates local database\n- Progress reflected in reading view\n- Annotations appear in Notebook\n- Bookmarks updated in navigation\n- Conflict warnings shown to user\n- Sync progress displayed on screen\n\n**Performance:**\n- Small sync (1-10 books): 2-5 seconds\n- Medium sync (10-50 books): 5-15 seconds\n- Large sync (50-200 books): 15-45 seconds\n- Timeout: 120 seconds\n\n**Use Cases:**\n- Initial device sync\n- After firmware update\n- From another device's changes\n- Manual sync request\n- Conflict recovery\n- Data restoration"
+    json:
+      force_sync: true
+      books:
+        - book-uuid-1
+        - book-uuid-2
+
+docs: |-
+  ## Sync Books from Server to Kobo
+
+  Pulls reading progress, annotations, and bookmarks from server to Kobo device.
+
+  **Method:** POST
+
+  **Endpoint:** /api/sync/kobo/sync-from-server
+
+  **Authentication:** Bearer token
+
+  **Request Body:**
+  - `force_sync` (boolean): Force full sync (ignore last sync time)
+  - `books` (array, optional): List of book UUIDs to sync
+    - If empty, syncs all books with server data
+    - If specified, only syncs listed books
+  - `sync_options` (object, optional):
+    - `since_date` (string): ISO 8601 timestamp for incremental sync
+    - `include_annotations` (boolean): Include highlights/notes
+    - `include_progress` (boolean): Include reading progress
+    - `conflict_resolution` (string): `most_recent`, `server_wins`, `client_wins`
+
+  **Response:**
+  - `synced` (integer): Number of books synced
+  - `skipped` (integer): Books with no server changes
+  - `failed` (integer): Books that failed to sync
+  - `results` (array): Per-book sync results
+    - `book_id` (string): Book UUID
+    - `status` (string): `synced`, `skipped`, `failed`
+    - `progress_pulled` (boolean): Whether progress was downloaded
+    - `annotations_pulled` (integer): Number of annotations downloaded
+    - `error` (string, optional): Error message if failed
+  - `server_timestamp` (string): Server timestamp of sync
+
+  **Status Codes:**
+  - 200: Sync completed
+  - 207: Multi-status (some succeeded, some failed)
+  - 401: Unauthorized
+  - 400: Invalid request
+
+  **Sync Direction:**
+  - **Server → Device** (this endpoint)
+  - Device → Server: Use `/sync/kobo/markup` endpoint
+  - Bidirectional sync achieved by calling both
+
+  **Pull Sync Use Cases:**
+  - New device setup (download all progress)
+  - Device replacement (restore from server)
+  - Multi-device sync (pull changes from other devices)
+  - Conflict resolution (server wins)
+  - Manual "Download from server" operation
+
+  **Conflict Resolution:**
+  - `most_recent`: Latest timestamp wins (default)
+  - `server_wins`: Server data always used
+  - `client_wins`: Device data preserved
+  - Applied per-book, per-item
+
+  **Sync Optimization:**
+  - Incremental sync by default (since last sync)
+  - Force sync does full comparison
+  - Book-level batching (10 books per batch)
+  - Delta transfer (only changed items)
+  - Compression for large annotation sets
+
+  **Kobo Device Behavior:**
+  - Device updates local database
+  - Progress reflected in reading view
+  - Annotations appear in Notebook
+  - Bookmarks updated in navigation
+  - Conflict warnings shown to user
+  - Sync progress displayed on screen
+
+  **Performance:**
+  - Small sync (1-10 books): 2-5 seconds
+  - Medium sync (10-50 books): 5-15 seconds
+  - Large sync (50-200 books): 15-45 seconds
+  - Timeout: 120 seconds
+
+  **Use Cases:**
+  - Initial device sync
+  - After firmware update
+  - From another device's changes
+  - Manual sync request
+  - Conflict recovery
+  - Data restoration

bruno/devices/kobo/scenarios/Sync Multiple Books Progress.yml

@@ -2,17 +2,90 @@ info:
   name: Sync Multiple Books Progress
   type: http
   seq: 3
+
 http:
   method: POST
-  url: '{{base_url}}/api/sync/kobo/{{kobo_device_token}}/markup'
+  url: '{{base_url}}/api/sync/kobo/markup'
   auth: inherit
   headers:
-  - key: Content-Type
-    value: application/json
-  - key: x-kobo-device
-    value: '{"DeviceId":"{{kobo_device_id}}","Model":"Kobo Aura"}'
+    - key: Content-Type
+      value: application/json
+    - key: x-kobo-device
+      value: '{"DeviceId":"{{kobo_device_id}}","Model":"Kobo Aura"}'
   body:
     type: json
-    data: "{\n  \"ReadingSync\": [\n    {\n      \"ContentId\": \"book-1-uuid\",\n      \"PercentRead\": 25.0,\n      \"EntitlementId\": \"entitlement-1\",\n      \"RemainingTimeMinutes\": 240,\n      \"FirstReadTime\": \"2026-01-25T10:00:00Z\",\n      \"LastModified\": \"2026-01-30T18:00:00Z\"\n    },\n    {\n      \"ContentId\": \"book-2-uuid\",\n      \"PercentRead\": 78.5,\n      \"EntitlementId\": \"entitlement-2\",\n      \"RemainingTimeMinutes\": 45,\n      \"FirstReadTime\": \"2026-01-25T14:00:00Z\",\n      \"LastModified\": \"2026-01-30T20:00:00Z\"\n    }\n  ],\n  \"BookmarkSync\": []\n}"
-docs: "## Sync Multiple Books Progress\n\nSynchronizes reading progress for multiple books in a single request.\n\n**Method:** POST\n\n**Endpoint:** /api/sync/kobo/markup\n\n**Authentication:** Bearer token\n\n**Headers:**\n- `Authorization`: Bearer {{kobo_device_token}}\n- `x-kobo-device`: Device information (Model: \"Kobo Aura\")\n\n**Request Body:**\n- `ReadingSync` (array): Multiple progress items\n  - Each item contains: ContentId, PercentRead, EntitlementId, etc.\n- `BookmarkSync` (array): Empty for progress-only batch\n\n**Response:**\n- `total` (integer): Total items in request\n- `synced` (integer): Successfully synced\n- `failed` (integer): Failed items\n- `results` (array): Per-item results\n  - `ContentId` (string): Book UUID\n  - `status` (string): `synced`, `failed`, `skipped`\n  - `error` (string, optional): Error message if failed\n\n**Status Codes:**\n- 200: Batch sync completed\n- 207: Multi-status (some succeeded, some failed)\n- 401: Unauthorized\n- 413: Payload too large\
-  \ (>1MB)\n\n**Batch Sync Advantages:**\n- Efficient sync of entire library\n- Reduces HTTP overhead\n- Faster for devices with many books\n- Atomic operation (all or nothing by default)\n\n**Kobo Batch Sync Behavior:**\n- Triggered when device connects after being offline\n- Occurs during manual \"Sync now\" operation\n- Limited to 100 books per request\n- Progress updates shown on device\n- Failed items retried individually\n\n**Performance:**\n- Typical batch: 10-50 books in 1-3 seconds\n- Large batch: 50-100 books in 3-8 seconds\n- Timeout: 30 seconds\n- Rate limit: 10 batches per minute per device\n\n**Use Cases:**\n- Initial device sync after registration\n- Catch-up sync after extended offline period\n- Library-wide progress update\n- Pre-sync before device firmware update"
+    json:
+      ReadingSync:
+        - ContentId: book-1-uuid
+          PercentRead: 25.0
+          EntitlementId: entitlement-1
+          RemainingTimeMinutes: 240
+          FirstReadTime: '2026-01-25T10:00:00Z'
+          LastModified: '2026-01-30T18:00:00Z'
+        - ContentId: book-2-uuid
+          PercentRead: 78.5
+          EntitlementId: entitlement-2
+          RemainingTimeMinutes: 45
+          FirstReadTime: '2026-01-25T14:00:00Z'
+          LastModified: '2026-01-30T20:00:00Z'
+      BookmarkSync: []
+
+docs: |-
+  ## Sync Multiple Books Progress
+
+  Synchronizes reading progress for multiple books in a single request.
+
+  **Method:** POST
+
+  **Endpoint:** /api/sync/kobo/markup
+
+  **Authentication:** Bearer token
+
+  **Headers:**
+  - `Authorization`: Bearer {{kobo_device_token}}
+  - `x-kobo-device`: Device information (Model: "Kobo Aura")
+
+  **Request Body:**
+  - `ReadingSync` (array): Multiple progress items
+    - Each item contains: ContentId, PercentRead, EntitlementId, etc.
+  - `BookmarkSync` (array): Empty for progress-only batch
+
+  **Response:**
+  - `total` (integer): Total items in request
+  - `synced` (integer): Successfully synced
+  - `failed` (integer): Failed items
+  - `results` (array): Per-item results
+    - `ContentId` (string): Book UUID
+    - `status` (string): `synced`, `failed`, `skipped`
+    - `error` (string, optional): Error message if failed
+
+  **Status Codes:**
+  - 200: Batch sync completed
+  - 207: Multi-status (some succeeded, some failed)
+  - 401: Unauthorized
+  - 413: Payload too large (>1MB)
+
+  **Batch Sync Advantages:**
+  - Efficient sync of entire library
+  - Reduces HTTP overhead
+  - Faster for devices with many books
+  - Atomic operation (all or nothing by default)
+
+  **Kobo Batch Sync Behavior:**
+  - Triggered when device connects after being offline
+  - Occurs during manual "Sync now" operation
+  - Limited to 100 books per request
+  - Progress updates shown on device
+  - Failed items retried individually
+
+  **Performance:**
+  - Typical batch: 10-50 books in 1-3 seconds
+  - Large batch: 50-100 books in 3-8 seconds
+  - Timeout: 30 seconds
+  - Rate limit: 10 batches per minute per device
+
+  **Use Cases:**
+  - Initial device sync after registration
+  - Catch-up sync after extended offline period
+  - Library-wide progress update
+  - Pre-sync before device firmware update

bruno/devices/kobo/scenarios/Sync Progress with Bookmarks.yml

@@ -2,17 +2,83 @@ info:
   name: Sync Progress with Bookmarks
   type: http
   seq: 2
+
 http:
   method: POST
-  url: '{{base_url}}/api/sync/kobo/{{kobo_device_token}}/markup'
+  url: '{{base_url}}/api/sync/kobo/markup'
   auth: inherit
   headers:
-  - key: Content-Type
-    value: application/json
-  - key: x-kobo-device
-    value: '{"DeviceId":"{{kobo_device_id}}","Model":"Kobo Clara"}'
+    - key: Content-Type
+      value: application/json
+    - key: x-kobo-device
+      value: '{"DeviceId":"{{kobo_device_id}}","Model":"Kobo Clara"}'
   body:
     type: json
-    data: "{\n  \"ReadingSync\": [\n    {\n      \"ContentId\": \"book-uuid\",\n      \"PercentRead\": 42.3,\n      \"EntitlementId\": \"entitlement-id\",\n      \"RemainingTimeMinutes\": 138,\n      \"FirstReadTime\": \"2026-01-25T10:00:00Z\",\n      \"LastModified\": \"2026-01-30T20:00:00Z\"\n    }\n  ],\n  \"BookmarkSync\": [\n    {\n      \"ContentId\": \"book-uuid\",\n      \"BookmarkText\": \"highlighted text passage\",\n      \"BookmarkType\": \"annotation\",\n      \"BookmarkTitle\": \"Chapter 3\"\n    }\n  ]\n}"
-docs: "## Sync Progress with Bookmarks\n\nSynchronizes reading progress and highlights/annotations from Kobo device.\n\n**Method:** POST\n\n**Endpoint:** /api/sync/kobo/markup\n\n**Authentication:** Bearer token\n\n**Headers:**\n- `Authorization`: Bearer {{kobo_device_token}}\n- `x-kobo-device`: Device information JSON\n\n**Request Body:**\n- `ReadingSync` (array): Progress items (see Sync Reading Progress)\n- `BookmarkSync` (array): Highlights and annotations\n  - `ContentId` (string): Book UUID\n  - `BookmarkText` (string): Highlighted text or note content\n  - `BookmarkType` (string): Type of bookmark\n    - `annotation`: Highlighted text\n    - `note`: Personal note\n    - `bookmark`: Location bookmark\n  - `BookmarkTitle` (string): Reference (e.g., chapter name)\n  - `ChapterID` (string, optional): Chapter identifier\n  - `DateCreated` (string, optional): Creation timestamp\n\n**Response:**\n- `progress_synced` (integer): Progress items synced\n- `bookmarks_synced` (integer): Bookmark\
-  \ items synced\n- `conflicts_resolved` (integer): Number of conflicts auto-resolved\n- `timestamp` (string): Sync timestamp\n- `details` (object): Sync breakdown by type\n\n**Status Codes:**\n- 200: Successful sync\n- 401: Unauthorized\n- 400: Invalid data\n\n**Kobo Highlight Features:**\n- 5 highlight colors (yellow, green, blue, pink, orange)\n- Chapter-based organization\n- Linked to reading progress\n- Appears in Kobo \"Notebook\" view\n- Can be exported from device\n- Syncs across all user devices\n\n**Annotation Sync:**\n- Highlight text preserved exactly\n- Color mapped to system colors\n- Chapter reference maintained\n- Location data converted to standard format\n- Notes attached to highlights synced separately"
+    json:
+      ReadingSync:
+        - ContentId: book-uuid
+          PercentRead: 42.3
+          EntitlementId: entitlement-id
+          RemainingTimeMinutes: 138
+          FirstReadTime: '2026-01-25T10:00:00Z'
+          LastModified: '2026-01-30T20:00:00Z'
+      BookmarkSync:
+        - ContentId: book-uuid
+          BookmarkText: highlighted text passage
+          BookmarkType: annotation
+          BookmarkTitle: Chapter 3
+
+docs: |-
+  ## Sync Progress with Bookmarks
+
+  Synchronizes reading progress and highlights/annotations from Kobo device.
+
+  **Method:** POST
+
+  **Endpoint:** /api/sync/kobo/markup
+
+  **Authentication:** Bearer token
+
+  **Headers:**
+  - `Authorization`: Bearer {{kobo_device_token}}
+  - `x-kobo-device`: Device information JSON
+
+  **Request Body:**
+  - `ReadingSync` (array): Progress items (see Sync Reading Progress)
+  - `BookmarkSync` (array): Highlights and annotations
+    - `ContentId` (string): Book UUID
+    - `BookmarkText` (string): Highlighted text or note content
+    - `BookmarkType` (string): Type of bookmark
+      - `annotation`: Highlighted text
+      - `note`: Personal note
+      - `bookmark`: Location bookmark
+    - `BookmarkTitle` (string): Reference (e.g., chapter name)
+    - `ChapterID` (string, optional): Chapter identifier
+    - `DateCreated` (string, optional): Creation timestamp
+
+  **Response:**
+  - `progress_synced` (integer): Progress items synced
+  - `bookmarks_synced` (integer): Bookmark items synced
+  - `conflicts_resolved` (integer): Number of conflicts auto-resolved
+  - `timestamp` (string): Sync timestamp
+  - `details` (object): Sync breakdown by type
+
+  **Status Codes:**
+  - 200: Successful sync
+  - 401: Unauthorized
+  - 400: Invalid data
+
+  **Kobo Highlight Features:**
+  - 5 highlight colors (yellow, green, blue, pink, orange)
+  - Chapter-based organization
+  - Linked to reading progress
+  - Appears in Kobo "Notebook" view
+  - Can be exported from device
+  - Syncs across all user devices
+
+  **Annotation Sync:**
+  - Highlight text preserved exactly
+  - Color mapped to system colors
+  - Chapter reference maintained
+  - Location data converted to standard format
+  - Notes attached to highlights synced separately

bruno/devices/kobo/scenarios/Sync Reading Progress.yml

@@ -2,18 +2,83 @@ info:
   name: Sync Reading Progress
   type: http
   seq: 1
+
 http:
   method: POST
-  url: '{{base_url}}/api/sync/kobo/{{kobo_device_token}}/markup'
+  url: '{{base_url}}/api/sync/kobo/markup'
   auth: inherit
   headers:
-  - key: Content-Type
-    value: application/json
-  - key: x-kobo-device
-    value: '{"DeviceId":"{{kobo_device_id}}","Model":"Kobo Clara"}'
+    - key: Content-Type
+      value: application/json
+    - key: x-kobo-device
+      value: '{"DeviceId":"{{kobo_device_id}}","Model":"Kobo Clara"}'
   body:
     type: json
-    data: "{\n  \"ReadingSync\": [\n    {\n      \"ContentId\": \"book-uuid-here\",\n      \"PercentRead\": 45.6,\n      \"EntitlementId\": \"entitlement-id-here\",\n      \"RemainingTimeMinutes\": 120,\n      \"FirstReadTime\": \"2026-01-25T10:00:00Z\",\n      \"LastModified\": \"2026-01-30T20:00:00Z\"\n    }\n  ],\n  \"BookmarkSync\": []\n}"
-docs: "## Sync Kobo Reading Progress\n\nSynchronizes reading progress from a Kobo device to the server using Bearer token authentication.\n\n**Method:** POST\n\n**Endpoint:** /api/sync/kobo/markup\n\n**Authentication:** Bearer token (in Authorization header)\n\n**Headers:**\n- `Authorization`: Bearer {{kobo_device_token}}\n- `x-kobo-device`: JSON-encoded device info\n  - `DeviceId`: Kobo device identifier\n  - `Model`: Device model (e.g., \"Kobo Clara\", \"Kobo Libra\", \"Kobo Aura\")\n\n**Request Body:**\n- `ReadingSync` (array): Reading progress items\n  - `ContentId` (string): Book/Content UUID\n  - `PercentRead` (number): Reading progress 0-100\n  - `EntitlementId` (string): Kobo entitlement ID\n  - `RemainingTimeMinutes` (integer): Estimated reading time remaining\n  - `FirstReadTime` (string): ISO 8601 timestamp when first opened\n  - `LastModified` (string): ISO 8601 timestamp of last progress update\n- `BookmarkSync` (array): Empty array for progress-only sync\n\n**Response:**\n\
-  - `synced` (integer): Number of items synced\n- `failed` (integer): Number of items that failed to sync\n- `timestamp` (string): Server timestamp of sync\n- `books` (array): Synced book data\n  - `ContentId` (string): Book UUID\n  - `status` (string): `synced`, `failed`, `skipped`\n  - `server_percent` (number): Server-side progress (for conflict detection)\n\n**Status Codes:**\n- 200: Sync successful\n- 401: Invalid device token\n- 403: Device not approved\n- 400: Invalid request format\n\n**Authentication Methods:**\nThis endpoint uses **Bearer token authentication** (token in Authorization header).\nAlternative: Use `/sync/kobo/{token}/markup` with token in URL path.\n\n**Kobo Sync Features:**\n- Native Kobo sync protocol\n- Supports Kobo Clara, Libra, Aura, Forma, Sage, Elipsa\n- Progress percentage tracking\n- Reading time estimation\n- Cross-device synchronization\n- Automatic conflict resolution (most recent wins)\n\n**Sync Frequency:**\n- Kobo devices auto-sync every 15-30 minutes\
-  \ when connected to WiFi\n- Manual sync available from device settings\n- Sync triggers on: device wake, book close, WiFi connection"
+    json:
+      ReadingSync:
+        - ContentId: book-uuid-here
+          PercentRead: 45.6
+          EntitlementId: entitlement-id-here
+          RemainingTimeMinutes: 120
+          FirstReadTime: '2026-01-25T10:00:00Z'
+          LastModified: '2026-01-30T20:00:00Z'
+      BookmarkSync: []
+
+docs: |-
+  ## Sync Kobo Reading Progress
+
+  Synchronizes reading progress from a Kobo device to the server using Bearer token authentication.
+
+  **Method:** POST
+
+  **Endpoint:** /api/sync/kobo/markup
+
+  **Authentication:** Bearer token (in Authorization header)
+
+  **Headers:**
+  - `Authorization`: Bearer {{kobo_device_token}}
+  - `x-kobo-device`: JSON-encoded device info
+    - `DeviceId`: Kobo device identifier
+    - `Model`: Device model (e.g., "Kobo Clara", "Kobo Libra", "Kobo Aura")
+
+  **Request Body:**
+  - `ReadingSync` (array): Reading progress items
+    - `ContentId` (string): Book/Content UUID
+    - `PercentRead` (number): Reading progress 0-100
+    - `EntitlementId` (string): Kobo entitlement ID
+    - `RemainingTimeMinutes` (integer): Estimated reading time remaining
+    - `FirstReadTime` (string): ISO 8601 timestamp when first opened
+    - `LastModified` (string): ISO 8601 timestamp of last progress update
+  - `BookmarkSync` (array): Empty array for progress-only sync
+
+  **Response:**
+  - `synced` (integer): Number of items synced
+  - `failed` (integer): Number of items that failed to sync
+  - `timestamp` (string): Server timestamp of sync
+  - `books` (array): Synced book data
+    - `ContentId` (string): Book UUID
+    - `status` (string): `synced`, `failed`, `skipped`
+    - `server_percent` (number): Server-side progress (for conflict detection)
+
+  **Status Codes:**
+  - 200: Sync successful
+  - 401: Invalid device token
+  - 403: Device not approved
+  - 400: Invalid request format
+
+  **Authentication Methods:**
+  This endpoint uses **Bearer token authentication** (token in Authorization header).
+  Alternative: Use `/sync/kobo/{token}/markup` with token in URL path.
+
+  **Kobo Sync Features:**
+  - Native Kobo sync protocol
+  - Supports Kobo Clara, Libra, Aura, Forma, Sage, Elipsa
+  - Progress percentage tracking
+  - Reading time estimation
+  - Cross-device synchronization
+  - Automatic conflict resolution (most recent wins)
+
+  **Sync Frequency:**
+  - Kobo devices auto-sync every 15-30 minutes when connected to WiFi
+  - Manual sync available from device settings
+  - Sync triggers on: device wake, book close, WiFi connection

bruno/devices/kobo/scenarios/Sync Single Bookmark.yml

@@ -2,18 +2,91 @@ info:
   name: Sync Single Bookmark
   type: http
   seq: 5
+
 http:
   method: POST
-  url: '{{base_url}}/api/sync/kobo/{{kobo_device_token}}/bookmark'
+  url: '{{base_url}}/api/sync/kobo/bookmark'
   auth: inherit
   headers:
-  - key: Content-Type
-    value: application/json
-  - key: x-kobo-device
-    value: '{"DeviceId":"{{kobo_device_id}}","Model":"Kobo Clara"}'
+    - key: Content-Type
+      value: application/json
+    - key: x-kobo-device
+      value: '{"DeviceId":"{{kobo_device_id}}","Model":"Kobo Clara"}'
   body:
     type: json
-    data: "{\n  \"ContentId\": \"book-uuid\",\n  \"BookmarkText\": \"Bookmarked passage\",\n  \"BookmarkType\": \"annotation\",\n  \"BookmarkTitle\": \"Chapter 3\"\n}"
-docs: "## Sync Single Bookmark\n\nSynchronizes an individual bookmark/highlight from Kobo device.\n\n**Method:** POST\n\n**Endpoint:** /api/sync/kobo/bookmark\n\n**Authentication:** Bearer token\n\n**Headers:**\n- `Authorization`: Bearer {{kobo_device_token}}\n- `x-kobo-device`: Device information JSON\n\n**Request Body:**\n- `ContentId` (string): Book UUID\n- `BookmarkText` (string): Highlighted text or bookmark description\n- `BookmarkType` (string): Type of bookmark\n  - `annotation`: Highlighted text passage\n  - `note`: Personal note\n  - `bookmark`: Location marker\n- `BookmarkTitle` (string): Reference title (e.g., chapter name)\n- `ChapterID` (string, optional): Chapter identifier\n- `DateCreated` (string, optional): ISO 8601 timestamp\n- `highlight_color` (string, optional): Color name (yellow, green, blue, pink, orange)\n\n**Response:**\n- `id` (string): Server bookmark ID\n- `ContentId` (string): Associated book UUID\n- `status` (string): `created`, `updated`, `skipped` (duplicate)\n\
-  - `timestamp` (string): Server timestamp\n- `url` (string): API URL to retrieve bookmark\n\n**Status Codes:**\n- 201: Bookmark created\n- 200: Bookmark updated (duplicate found)\n- 409: Duplicate bookmark (unchanged)\n- 401: Unauthorized\n- 400: Invalid bookmark data\n\n**Single Bookmark Sync vs Batch:**\n- **Single bookmark endpoint:** Real-time, immediate sync\n- **Batch markup endpoint:** Deferred, periodic sync\n- Use single when user explicitly creates highlight\n- Use batch for periodic background sync\n\n**Kobo Trigger:**\n- User highlights text → immediate single sync\n- User adds note → immediate single sync\n- Device goes online → batch sync of all changes\n\n**Duplicate Detection:**\n- Same ContentId + similar BookmarkText + same location\n- Updates existing if text modified\n- Skips if identical bookmark exists\n- Preserves creation date of original\n\n**Use Cases:**\n- Real-time highlight sync\n- Instant note backup\n- Immediate annotation sharing\n- Quick single annotation\
-  \ update\n- Testing annotation sync\n\n**Notes:**\n- Much faster than full markup sync\n- Lower bandwidth usage\n- Ideal for intermittent connectivity\n- Can be called multiple times safely"
+    json:
+      ContentId: book-uuid
+      BookmarkText: Bookmarked passage
+      BookmarkType: annotation
+      BookmarkTitle: Chapter 3
+
+docs: |-
+  ## Sync Single Bookmark
+
+  Synchronizes an individual bookmark/highlight from Kobo device.
+
+  **Method:** POST
+
+  **Endpoint:** /api/sync/kobo/bookmark
+
+  **Authentication:** Bearer token
+
+  **Headers:**
+  - `Authorization`: Bearer {{kobo_device_token}}
+  - `x-kobo-device`: Device information JSON
+
+  **Request Body:**
+  - `ContentId` (string): Book UUID
+  - `BookmarkText` (string): Highlighted text or bookmark description
+  - `BookmarkType` (string): Type of bookmark
+    - `annotation`: Highlighted text passage
+    - `note`: Personal note
+    - `bookmark`: Location marker
+  - `BookmarkTitle` (string): Reference title (e.g., chapter name)
+  - `ChapterID` (string, optional): Chapter identifier
+  - `DateCreated` (string, optional): ISO 8601 timestamp
+  - `highlight_color` (string, optional): Color name (yellow, green, blue, pink, orange)
+
+  **Response:**
+  - `id` (string): Server bookmark ID
+  - `ContentId` (string): Associated book UUID
+  - `status` (string): `created`, `updated`, `skipped` (duplicate)
+  - `timestamp` (string): Server timestamp
+  - `url` (string): API URL to retrieve bookmark
+
+  **Status Codes:**
+  - 201: Bookmark created
+  - 200: Bookmark updated (duplicate found)
+  - 409: Duplicate bookmark (unchanged)
+  - 401: Unauthorized
+  - 400: Invalid bookmark data
+
+  **Single Bookmark Sync vs Batch:**
+  - **Single bookmark endpoint:** Real-time, immediate sync
+  - **Batch markup endpoint:** Deferred, periodic sync
+  - Use single when user explicitly creates highlight
+  - Use batch for periodic background sync
+
+  **Kobo Trigger:**
+  - User highlights text → immediate single sync
+  - User adds note → immediate single sync
+  - Device goes online → batch sync of all changes
+
+  **Duplicate Detection:**
+  - Same ContentId + similar BookmarkText + same location
+  - Updates existing if text modified
+  - Skips if identical bookmark exists
+  - Preserves creation date of original
+
+  **Use Cases:**
+  - Real-time highlight sync
+  - Instant note backup
+  - Immediate annotation sharing
+  - Quick single annotation update
+  - Testing annotation sync
+
+  **Notes:**
+  - Much faster than full markup sync
+  - Lower bandwidth usage
+  - Ideal for intermittent connectivity
+  - Can be called multiple times safely

bruno/devices/kobo/scenarios/Sync with Annotations.yml

@@ -2,17 +2,105 @@ info:
   name: Sync with Annotations
   type: http
   seq: 4
+
 http:
   method: POST
-  url: '{{base_url}}/api/sync/kobo/{{kobo_device_token}}/markup'
+  url: '{{base_url}}/api/sync/kobo/markup'
   auth: inherit
   headers:
-  - key: Content-Type
-    value: application/json
-  - key: x-kobo-device
-    value: '{"DeviceId":"{{kobo_device_id}}","Model":"Kobo Libra"}'
+    - key: Content-Type
+      value: application/json
+    - key: x-kobo-device
+      value: '{"DeviceId":"{{kobo_device_id}}","Model":"Kobo Libra"}'
   body:
     type: json
-    data: "{\n  \"ReadingSync\": [\n    {\n      \"ContentId\": \"book-uuid\",\n      \"PercentRead\": 55.0,\n      \"EntitlementId\": \"entitlement-id\",\n      \"RemainingTimeMinutes\": 120,\n      \"FirstReadTime\": \"2026-01-25T10:00:00Z\",\n      \"LastModified\": \"2026-01-30T20:00:00Z\"\n    }\n  ],\n  \"BookmarkSync\": [\n    {\n      \"ContentId\": \"book-uuid\",\n      \"BookmarkText\": \"Important quote\",\n      \"BookmarkType\": \"annotation\",\n      \"BookmarkTitle\": \"Chapter 4 - The Truth\"\n    },\n    {\n      \"ContentId\": \"book-uuid\",\n      \"BookmarkText\": \"Another quote\",\n      \"BookmarkType\": \"annotation\",\n      \"BookmarkTitle\": \"Chapter 5\"\n    },\n    {\n      \"ContentId\": \"book-uuid\",\n      \"BookmarkText\": \"Note to myself\",\n      \"BookmarkType\": \"note\",\n      \"BookmarkTitle\": \"Personal note\"\n    }\n  ]\n}"
-docs: "## Sync with Multiple Annotations\n\nSynchronizes reading progress with multiple highlights and notes.\n\n**Method:** POST\n\n**Endpoint:** /api/sync/kobo/markup\n\n**Authentication:** Bearer token\n\n**Headers:**\n- `Authorization`: Bearer {{kobo_device_token}}\n- `x-kobo-device`: Device info (Model: \"Kobo Libra\")\n\n**Request Body:**\n- `ReadingSync` (array): Single book progress\n- `BookmarkSync` (array): Multiple annotations\n  - Can include highlights (annotation type)\n  - Can include notes (note type)\n  - Each has: ContentId, BookmarkText, BookmarkType, BookmarkTitle\n\n**Response:**\n- `progress_synced` (boolean): Progress update status\n- `annotations_synced` (integer): Number of annotations synced\n- `highlights_count` (integer): Highlights synced\n- `notes_count` (integer): Notes synced\n- `conflicts` (array): Any annotation conflicts resolved\n- `timestamp` (string): Sync completion time\n\n**Status Codes:**\n- 200: Successful sync\n- 401: Unauthorized\n- 400: Invalid\
-  \ annotation data\n\n**Kobo Annotation Types:**\n- **Highlights:** Selected text passages\n  - 5 preset colors available\n  - Can have chapter titles\n  - Exportable to PDF/Mobile\n- **Notes:** Personal annotations\n  - Free-form text\n  - Can be attached to highlights\n  - Separate from highlights\n- **Bookmarks:** Location markers\n  - Chapter positions\n  - Quick navigation\n\n**Sync Behavior:**\n- Duplicates detected by content matching\n- Most recent edit wins conflicts\n- Annotations linked to book content\n- Chapter references preserved\n- Order maintained from device\n\n**Kobo Notebook Export:**\n- All annotations appear in Kobo \"Notebook\"\n- Can be exported to PDF\n- Can be exported to Mobile (text)\n- Organized by book\n- Shows highlight context\n\n**Use Cases:**\n- Study and research\n- Book club discussion prep\n- Content review\n- Sharing insights\n- Personal learning archive"
+    json:
+      ReadingSync:
+        - ContentId: book-uuid
+          PercentRead: 55.0
+          EntitlementId: entitlement-id
+          RemainingTimeMinutes: 120
+          FirstReadTime: '2026-01-25T10:00:00Z'
+          LastModified: '2026-01-30T20:00:00Z'
+      BookmarkSync:
+        - ContentId: book-uuid
+          BookmarkText: Important quote
+          BookmarkType: annotation
+          BookmarkTitle: Chapter 4 - The Truth
+        - ContentId: book-uuid
+          BookmarkText: Another quote
+          BookmarkType: annotation
+          BookmarkTitle: Chapter 5
+        - ContentId: book-uuid
+          BookmarkText: Note to myself
+          BookmarkType: note
+          BookmarkTitle: Personal note
+
+docs: |-
+  ## Sync with Multiple Annotations
+
+  Synchronizes reading progress with multiple highlights and notes.
+
+  **Method:** POST
+
+  **Endpoint:** /api/sync/kobo/markup
+
+  **Authentication:** Bearer token
+
+  **Headers:**
+  - `Authorization`: Bearer {{kobo_device_token}}
+  - `x-kobo-device`: Device info (Model: "Kobo Libra")
+
+  **Request Body:**
+  - `ReadingSync` (array): Single book progress
+  - `BookmarkSync` (array): Multiple annotations
+    - Can include highlights (annotation type)
+    - Can include notes (note type)
+    - Each has: ContentId, BookmarkText, BookmarkType, BookmarkTitle
+
+  **Response:**
+  - `progress_synced` (boolean): Progress update status
+  - `annotations_synced` (integer): Number of annotations synced
+  - `highlights_count` (integer): Highlights synced
+  - `notes_count` (integer): Notes synced
+  - `conflicts` (array): Any annotation conflicts resolved
+  - `timestamp` (string): Sync completion time
+
+  **Status Codes:**
+  - 200: Successful sync
+  - 401: Unauthorized
+  - 400: Invalid annotation data
+
+  **Kobo Annotation Types:**
+  - **Highlights:** Selected text passages
+    - 5 preset colors available
+    - Can have chapter titles
+    - Exportable to PDF/Mobile
+  - **Notes:** Personal annotations
+    - Free-form text
+    - Can be attached to highlights
+    - Separate from highlights
+  - **Bookmarks:** Location markers
+    - Chapter positions
+    - Quick navigation
+
+  **Sync Behavior:**
+  - Duplicates detected by content matching
+  - Most recent edit wins conflicts
+  - Annotations linked to book content
+  - Chapter references preserved
+  - Order maintained from device
+
+  **Kobo Notebook Export:**
+  - All annotations appear in Kobo "Notebook"
+  - Can be exported to PDF
+  - Can be exported to Mobile (text)
+  - Organized by book
+  - Shows highlight context
+
+  **Use Cases:**
+  - Study and research
+  - Book club discussion prep
+  - Content review
+  - Sharing insights
+  - Personal learning archive

bruno/devices/kobo/scenarios/bookmark-sync.yml

@@ -4,12 +4,42 @@ info:
   seq: 3
 http:
   method: POST
-  url: '{{base_url}}/api/sync/kobo/{{kobo_device_token}}/bookmark'
+  url: '{{base_url}}/api/v1/kobo/bookmark'
   auth: inherit
   body:
     type: json
-    data: "{\n    \"BookmarkSync\": [\n      {\n        \"BookmarkId\": \"bookmark_2\",\n        \"ContentId\": \"kobo_xyz789\",\n        \"BookmarkText\": \"Important note\",\n        \"BookmarkType\": \"bookmark\",\n        \"DateCreated\": \"2026-01-31T12:00:00Z\""
+    jsonBody: "{\n    \"BookmarkSync\": [\n      {\n        \"BookmarkId\": \"bookmark_2\"\
+      ,\n        \"ContentId\": \"kobo_xyz789\",\n        \"BookmarkText\": \"Important\
+      \ note\",\n        \"BookmarkType\": \"bookmark\",\n        \"DateCreated\"\
+      : \"2026-01-31T12:00:00Z\""
   headers:
   - key: Authorization
     value: Bearer {{device_token
-docs: "## Kobo Bookmark Sync\n\n  Synchronizes bookmarks from a Kobo device to the Bookhoard server.\n\n  **Method:** POST\n\n  **Endpoint:** /api/v1/kobo/bookmark\n\n  **Authentication:** Bearer token (device token)\n\n  **Request Body:**\n  - `BookmarkSync` (array): Array of bookmark objects\n    - `BookmarkId` (string): Unique bookmark ID\n    - `ContentId` (string): Book/content ID\n    - `BookmarkText` (string): Bookmark text or note\n    - `BookmarkType` (string): Type (bookmark, highlight, note)\n    - `DateCreated` (string): ISO 8601 timestamp\n\n  **Response:**\n  - `Status` (string): Sync status (Success, Partial)\n  - `BookmarksSynced` (number): Number of bookmarks synced\n\n  **Status Codes:**\n  - 200: Success\n  - 401: Unauthorized\n  - 500: Internal server error"
+
+docs: |-
+  ## Kobo Bookmark Sync
+  
+    Synchronizes bookmarks from a Kobo device to the Bookhoard server.
+  
+    **Method:** POST
+  
+    **Endpoint:** /api/v1/kobo/bookmark
+  
+    **Authentication:** Bearer token (device token)
+  
+    **Request Body:**
+    - `BookmarkSync` (array): Array of bookmark objects
+      - `BookmarkId` (string): Unique bookmark ID
+      - `ContentId` (string): Book/content ID
+      - `BookmarkText` (string): Bookmark text or note
+      - `BookmarkType` (string): Type (bookmark, highlight, note)
+      - `DateCreated` (string): ISO 8601 timestamp
+  
+    **Response:**
+    - `Status` (string): Sync status (Success, Partial)
+    - `BookmarksSynced` (number): Number of bookmarks synced
+  
+    **Status Codes:**
+    - 200: Success
+    - 401: Unauthorized
+    - 500: Internal server error

bruno/devices/kobo/scenarios/get-initialization-url-token.yml

@@ -4,7 +4,7 @@ info:
   seq: 4
 http:
   method: GET
-  url: '{{base_url}}/api/sync/kobo/{{kobo_device_token}}/v1/initialization'
+  url: '{{base_url}}/sync/kobo/{{kobo_device_token}}/v1/initialization'
   auth: none
   body:
     type: none

bruno/devices/kobo/scenarios/get-library-url-token.yml

@@ -4,7 +4,7 @@ info:
   seq: 3
 http:
   method: GET
-  url: '{{base_url}}/api/sync/kobo/{{kobo_device_token}}/v1/initialization'
+  url: '{{base_url}}/sync/kobo/{{kobo_device_token}}/library'
   auth: none
   body:
     type: none

bruno/devices/kobo/scenarios/get-unlinked-books.yml

@@ -4,7 +4,7 @@ info:
   seq: 4
 http:
   method: GET
-  url: '{{base_url}}/api/devices/{{device_id}}/sync/unlinked-books'
+  url: '{{base_url}}/api/sync/unlinked-books'
   auth: inherit
   body:
     type: none

bruno/devices/kobo/scenarios/initialization.yml

@@ -0,0 +1,34 @@
+info:
+  name: Kobo Initialization
+  type: http
+  seq: 1
+http:
+  method: GET
+  url: '{{base_url}}/api/v1/kobo/initialization'
+  auth: inherit
+  body:
+    type: none
+  headers:
+  - key: Authorization
+    value: Bearer {{device_token
+
+docs: |-
+  ## Kobo Initialization
+  
+    Initializes Kobo device sync, returning device resources and account information.
+  
+    **Method:** GET
+  
+    **Endpoint:** /api/v1/kobo/initialization
+  
+    **Authentication:** Bearer token (device token)
+  
+    **Response:**
+    - `ContentId` (string): Device content ID
+    - `Categories` (array): Available categories/collections
+    - `BookhoardUUID` (string): Bookhoard instance UUID
+  
+    **Status Codes:**
+    - 200: Success
+    - 401: Unauthorized
+    - 500: Internal server error

bruno/devices/kobo/scenarios/link-book.yml

@@ -4,12 +4,40 @@ info:
   seq: 5
 http:
   method: POST
-  url: '{{base_url}}/api/devices/{{device_id}}/sync/link-book'
+  url: '{{base_url}}/api/sync/link-book'
   auth: inherit
   body:
     type: json
-    data: "{\n    \"unlinked_book_id\": \"{{unlinked_book_id"
+    jsonBody: "{\n    \"unlinked_book_id\": \"{{unlinked_book_id"
   headers:
   - key: Authorization
     value: Bearer {{user_token
-docs: "## Link Unlinked Book - Manual Resolution\n\n  Manually links an unlinked book to a media item in the library.\n\n  **Method:** POST\n\n  **Endpoint:** /api/sync/link-book\n\n  **Authentication:** Bearer token\n\n  **Request Body:**\n  - `unlinked_book_id` (string): Unlinked book UUID\n  - `media_item_id` (string): Media item UUID to link to\n  - `confidence_score` (number): Match confidence (0-1, 1.0 for manual)\n\n  **Response:**\n  - `status` (string): Link status (linked)\n  - `unlinked_book_id` (string): Unlinked book UUID\n  - `media_item_id` (string): Media item UUID\n  - `message` (string): Success message\n\n  **Status Codes:**\n  - 200: Success - book linked\n  - 400: Invalid request\n  - 401: Unauthorized\n  - 404: Book or media item not found\n  - 500: Internal server error"
+
+docs: |-
+  ## Link Unlinked Book - Manual Resolution
+  
+    Manually links an unlinked book to a media item in the library.
+  
+    **Method:** POST
+  
+    **Endpoint:** /api/sync/link-book
+  
+    **Authentication:** Bearer token
+  
+    **Request Body:**
+    - `unlinked_book_id` (string): Unlinked book UUID
+    - `media_item_id` (string): Media item UUID to link to
+    - `confidence_score` (number): Match confidence (0-1, 1.0 for manual)
+  
+    **Response:**
+    - `status` (string): Link status (linked)
+    - `unlinked_book_id` (string): Unlinked book UUID
+    - `media_item_id` (string): Media item UUID
+    - `message` (string): Success message
+  
+    **Status Codes:**
+    - 200: Success - book linked
+    - 400: Invalid request
+    - 401: Unauthorized
+    - 404: Book or media item not found
+    - 500: Internal server error

bruno/devices/kobo/scenarios/markup-sync.yml

@@ -0,0 +1,52 @@
+info:
+  name: Kobo Markup Sync
+  type: http
+  seq: 2
+http:
+  method: POST
+  url: '{{base_url}}/api/v1/kobo/markup'
+  auth: inherit
+  body:
+    type: json
+    jsonBody: "{\n    \"ReadingSync\": [\n      {\n        \"ContentId\": \"kobo_abc123def456\"\
+      ,\n        \"PercentRead\": 60.0,\n        \"RemainingTimeMin\": 120,\n    \
+      \    \"ReadingEvent\": \"BookRead\",\n        \"LastModified\": \"2026-01-31T12:00:00Z\""
+  headers:
+  - key: Authorization
+    value: Bearer {{device_token
+
+docs: |-
+  ## Kobo Markup Sync
+  
+    Synchronizes reading progress and markup (highlights, bookmarks) from a Kobo device.
+  
+    **Method:** POST
+  
+    **Endpoint:** /api/v1/kobo/markup
+  
+    **Authentication:** Bearer token (device token)
+  
+    **Request Body:**
+    - `ReadingSync` (array, optional): Reading progress data
+      - `ContentId` (string): Book/content ID
+      - `PercentRead` (number): Percentage read (0-100)
+      - `RemainingTimeMin` (number): Remaining time in minutes
+      - `ReadingEvent` (string): Event type (BookRead, etc.)
+      - `LastModified` (string): ISO 8601 timestamp
+    - `BookmarkSync` (array, optional): Bookmark/highlight data
+      - `BookmarkId` (string): Unique bookmark ID
+      - `ContentId` (string): Book/content ID
+      - `BookmarkText` (string): Highlighted/bookmarked text
+      - `BookmarkType` (string): Type (annotation, bookmark)
+      - `DateCreated` (string): ISO 8601 timestamp
+    - `Metadata` (boolean): Whether to include metadata
+  
+    **Response:**
+    - `Status` (string): Sync status (Success, Partial)
+    - `MarkupsSynced` (number): Number of markups synced
+    - `BookmarksSynced` (number): Number of bookmarks synced
+  
+    **Status Codes:**
+    - 200: Success
+    - 401: Unauthorized
+    - 500: Internal server error

bruno/devices/kobo/scenarios/sync-bookmark-url-token.yml

@@ -4,12 +4,22 @@ info:
   seq: 2
 http:
   method: POST
-  url: '{{base_url}}/api/sync/kobo/{{kobo_device_token}}/bookmark'
+  url: '{{base_url}}/sync/kobo/{{kobo_device_token}}/bookmark'
   auth: none
   body:
     type: json
-    data: "{\n    \"ContentId\": \"book-uuid\",\n    \"BookmarkText\": \"Highlighted text\",\n    \"BookmarkType\": \"annotation\",\n    \"BookmarkTitle\": \"Chapter 3\""
+    jsonBody: "{\n    \"ContentId\": \"book-uuid\",\n    \"BookmarkText\": \"Highlighted\
+      \ text\",\n    \"BookmarkType\": \"annotation\",\n    \"BookmarkTitle\": \"\
+      Chapter 3\""
   headers:
   - key: Content-Type
     value: application/json
-docs: "## Sync Bookmark - URL Path Token\n\n  Synchronizes bookmarks and annotations from Kobo device using token in URL path.\n\n  **Method:** POST\n\n  **Endpoint:** /sync/kobo/{kobo_device_token"
+
+docs: |-
+  ## Sync Bookmark - URL Path Token
+  
+    Synchronizes bookmarks and annotations from Kobo device using token in URL path.
+  
+    **Method:** POST
+  
+    **Endpoint:** /sync/kobo/{kobo_device_token

bruno/devices/kobo/scenarios/sync-markup-url-token.yml

@@ -4,12 +4,23 @@ info:
   seq: 1
 http:
   method: POST
-  url: '{{base_url}}/api/sync/kobo/{{kobo_device_token}}/markup'
+  url: '{{base_url}}/sync/kobo/{{kobo_device_token}}/markup'
   auth: none
   body:
     type: json
-    data: "{\n    \"ReadingSync\": [\n      {\n        \"ContentId\": \"book-uuid\",\n        \"PercentRead\": 45.6,\n        \"EntitlementId\": \"entitlement-id\",\n        \"RemainingTimeMinutes\": 120,\n        \"FirstReadTime\": \"2026-01-25T10:00:00Z\",\n        \"LastModified\": \"2026-01-30T20:00:00Z\""
+    jsonBody: "{\n    \"ReadingSync\": [\n      {\n        \"ContentId\": \"book-uuid\"\
+      ,\n        \"PercentRead\": 45.6,\n        \"EntitlementId\": \"entitlement-id\"\
+      ,\n        \"RemainingTimeMinutes\": 120,\n        \"FirstReadTime\": \"2026-01-25T10:00:00Z\"\
+      ,\n        \"LastModified\": \"2026-01-30T20:00:00Z\""
   headers:
   - key: Content-Type
     value: application/json
-docs: "## Sync Reading Progress - URL Path Token\n\n  Synchronizes reading progress from Kobo device using token in URL path.\n\n  **Method:** POST\n\n  **Endpoint:** /sync/kobo/{kobo_device_token"
+
+docs: |-
+  ## Sync Reading Progress - URL Path Token
+  
+    Synchronizes reading progress from Kobo device using token in URL path.
+  
+    **Method:** POST
+  
+    **Endpoint:** /sync/kobo/{kobo_device_token

bruno/devices/koreader/Get Book Metadata.yml

@@ -1,14 +1,92 @@
-docs: "## Get KOReader Book Metadata\n\nRetrieves metadata for a specific book from the server.\n\n**Method:** GET\n\n**Endpoint:** /api/sync/koreader/metadata/:book_uuid\n\n**Authentication:** Bearer token\n\n**Path Parameters:**\n- `book_uuid` (string): SHA-256 based book identifier\n\n**Response:**\n- `uuid` (string): Book UUID (SHA-256)\n- `title` (string): Book title\n- `authors` (array): Author names\n- `series` (string, optional): Series name\n- `series_index` (number, optional): Position in series\n- `publisher` (string, optional): Publisher name\n- `publication_date` (string, optional): Release date\n- `language` (string, optional): ISO 639-1 language code\n- `description` (string, optional): Book description\n- `cover_url` (string, optional): Cover image URL\n- `cover_thumbnail_url` (string, optional): Thumbnail URL\n- `identifiers` (object): Various identifiers\n  - `isbn` (string, optional): ISBN-13\n  - `asin` (string, optional): Amazon ASIN\n  - `goodreads` (string, optional):\
-  \ Goodreads ID\n  - `google_books` (string, optional): Google Books ID\n- `metadata_sources` (array): Sources metadata was pulled from\n- `last_synced` (string): Last metadata sync timestamp\n- `file_metadata` (object):\n  - `file_size` (integer): File size in bytes\n  - `format` (string): File format (epub, pdf, mobi, etc.)\n  - `pages` (integer, optional): Page count\n  - `word_count` (integer, optional): Estimated words\n\n**Status Codes:**\n- 200: Success\n- 401: Unauthorized\n- 404: Book not found\n\n**Metadata Purpose:**\n- Enrich book information on device\n- Improve book organization\n- Enable better search\n- Support series sorting\n- Provide cover images\n- Link to external sources\n\n**KOReader Usage:**\n- Display in book info dialog\n- Used for library sorting\n- Shown in file browser\n- Series grouping\n- Cover display\n- Search optimization\n\n**SHA-256 Book ID:**\n- Primary identifier in KOReader\n- Universal across devices\n- Format-independent\n- Generated from file content\n\
-  - Survives metadata changes\n\n**Metadata Sources:**\n- Google Books API\n- Open Library\n- Goodreads API\n- ISBN database lookup\n- Publisher metadata\n- User-provided metadata\n\n**Use Cases:**\n- Initial book import\n- Metadata refresh\n- Cover image download\n- Series organization\n- Duplicate detection\n- Library management"
-http:
-  headers: []
-  method: GET
-  url: '{{base_url}}/api/sync/koreader/metadata/{{book_uuid}}'
-  auth:
-    type: bearer
-    token: '{{koreader_device_token}}'
 info:
   name: Get Book Metadata
-  seq: 8
   type: http
+  seq: 8
+
+http:
+  method: GET
+  url: '{{base_url}}/api/sync/koreader/metadata/{{book_uuid}}'
+  auth: inherit
+
+docs: |-
+  ## Get KOReader Book Metadata
+
+  Retrieves metadata for a specific book from the server.
+
+  **Method:** GET
+
+  **Endpoint:** /api/sync/koreader/metadata/:book_uuid
+
+  **Authentication:** Bearer token
+
+  **Path Parameters:**
+  - `book_uuid` (string): SHA-256 based book identifier
+
+  **Response:**
+  - `uuid` (string): Book UUID (SHA-256)
+  - `title` (string): Book title
+  - `authors` (array): Author names
+  - `series` (string, optional): Series name
+  - `series_index` (number, optional): Position in series
+  - `publisher` (string, optional): Publisher name
+  - `publication_date` (string, optional): Release date
+  - `language` (string, optional): ISO 639-1 language code
+  - `description` (string, optional): Book description
+  - `cover_url` (string, optional): Cover image URL
+  - `cover_thumbnail_url` (string, optional): Thumbnail URL
+  - `identifiers` (object): Various identifiers
+    - `isbn` (string, optional): ISBN-13
+    - `asin` (string, optional): Amazon ASIN
+    - `goodreads` (string, optional): Goodreads ID
+    - `google_books` (string, optional): Google Books ID
+  - `metadata_sources` (array): Sources metadata was pulled from
+  - `last_synced` (string): Last metadata sync timestamp
+  - `file_metadata` (object):
+    - `file_size` (integer): File size in bytes
+    - `format` (string): File format (epub, pdf, mobi, etc.)
+    - `pages` (integer, optional): Page count
+    - `word_count` (integer, optional): Estimated words
+
+  **Status Codes:**
+  - 200: Success
+  - 401: Unauthorized
+  - 404: Book not found
+
+  **Metadata Purpose:**
+  - Enrich book information on device
+  - Improve book organization
+  - Enable better search
+  - Support series sorting
+  - Provide cover images
+  - Link to external sources
+
+  **KOReader Usage:**
+  - Display in book info dialog
+  - Used for library sorting
+  - Shown in file browser
+  - Series grouping
+  - Cover display
+  - Search optimization
+
+  **SHA-256 Book ID:**
+  - Primary identifier in KOReader
+  - Universal across devices
+  - Format-independent
+  - Generated from file content
+  - Survives metadata changes
+
+  **Metadata Sources:**
+  - Google Books API
+  - Open Library
+  - Goodreads API
+  - ISBN database lookup
+  - Publisher metadata
+  - User-provided metadata
+
+  **Use Cases:**
+  - Initial book import
+  - Metadata refresh
+  - Cover image download
+  - Series organization
+  - Duplicate detection
+  - Library management

bruno/devices/koreader/Get Library.yml

@@ -1,14 +1,34 @@
-docs: "## KOReader Get Library\n\n  Retrieves the user's library for KOReader sync operations.\n\n  **Method:** GET\n\n  **Endpoint:** /api/sync/koreader/library\n\n  **Authentication:** Bearer token (device token)\n\n  **Response:**\n  - `library_sync` (object): Library sync data\n  - `total_books` (number): Total number of books\n  - `books` (array): Array of book objects\n\n  **Status Codes:**\n  - 200: Success\n  - 401: Unauthorized\n  - 500: Internal server error"
-http:
-  body:
-    type: none
-  headers: []
-  method: GET
-  url: '{{base_url}}/api/sync/koreader/library'
-  auth:
-    type: bearer
-    token: '{{koreader_device_token}}'
 info:
   name: KOReader Get Library
-  seq: 3
   type: http
+  seq: 3
+http:
+  method: GET
+  url: '{{base_url}}/api/sync/koreader/library'
+  auth: inherit
+  body:
+    type: none
+  headers:
+  - key: Authorization
+    value: Bearer {{device_token
+
+docs: |-
+  ## KOReader Get Library
+  
+    Retrieves the user's library for KOReader sync operations.
+  
+    **Method:** GET
+  
+    **Endpoint:** /api/sync/koreader/library
+  
+    **Authentication:** Bearer token (device token)
+  
+    **Response:**
+    - `library_sync` (object): Library sync data
+    - `total_books` (number): Total number of books
+    - `books` (array): Array of book objects
+  
+    **Status Codes:**
+    - 200: Success
+    - 401: Unauthorized
+    - 500: Internal server error

bruno/devices/koreader/Get User Library for KOReader.yml

@@ -1,15 +1,103 @@
-docs: "## Get KOReader User Library\n\nRetrieves the user's book library for KOReader device sync.\n\n**Method:** GET\n\n**Endpoint:** /api/sync/koreader/library\n\n**Authentication:** Bearer token (koreader_device_token)\n\n**Query Parameters:**\nNone (returns entire library)\n\n**Response:**\n- `books` (array): Library items\n  - `uuid` (string): SHA-256 based book identifier\n  - `title` (string): Book title\n  - `authors` (array): Author names\n  - `series` (string, optional): Series name\n  - `series_index` (number, optional): Series position\n  - `publisher` (string, optional): Publisher\n  - `publication_date` (string, optional): Release date\n  - `language` (string, optional): Language code\n  - `description` (string, optional): Description\n  - `cover_url` (string, optional): Cover image URL\n  - `cover_thumbnail_url` (string, optional): Thumbnail URL\n  - `file_metadata` (object):\n    - `format` (string): File format\n    - `file_size` (integer): Size in bytes\n    - `pages` (integer,\
-  \ optional): Page count\n  - `progress` (object, optional): Reading progress\n    - `percentage` (number): Progress 0-100\n    - `last_read` (string): Last read timestamp\n    - `epubcfi` (string): Current position\n  - `annotations_count` (object, optional): Annotation stats\n    - `highlights` (integer): Highlight count\n    - `notes` (integer): Note count\n    - `bookmarks` (integer): Bookmark count\n- `library_info` (object):\n  - `total_books` (integer): Total book count\n  - `last_sync` (string): Last library sync timestamp\n  - `has_updates` (boolean): Updates available\n- `user_info` (object):\n  - `user_id` (string): User identifier\n  - `email` (string): Email (masked)\n  - `libraries` (array): Available library IDs\n\n**Status Codes:**\n- 200: Success\n- 401: Unauthorized\n- 403: Device not approved\n\n**Library Purpose for KOReader:**\n- Discover books available for download\n- Browse catalog on device\n- Sync reading progress across books\n- Download covers/metadata\n- Series-based\
-  \ organization\n- Cloud library access\n\n**KOReader Device Features:**\n- **OPDS catalog**: Native OPDS client\n- **File browser**: See server books\n- **Cloud download**: Download books on-demand\n- **Metadata sync**: Automatic metadata fetching\n- **Cover images**: Display in library view\n- **Progress sync**: See progress across all books\n- **Search**: Search library by title/author\n\n**KOReader-Specific Features:**\n- SHA-256 based book IDs\n- Multi-format support (EPUB, FB2, PDF, DJVU, MOBI, etc.)\n- Series sorting and grouping\n- Language filtering\n- Cover image caching\n- Metadata for file browser enhancement\n- Integration with KOReader's OPDS client\n\n**Performance:**\n- Typical response: 100-500KB for 100 books\n- Processing time: 300ms-1s\n- Cache duration: 5 minutes\n- Pagination support for libraries >500 books\n\n**Use Cases:**\n- Initial device setup\n- Library browsing on device\n- Book download\n- Metadata refresh\n- Cover image sync\n- Progress overview\n- Series-based\
-  \ reading"
-http:
-  headers: []
-  method: GET
-  url: '{{base_url}}/api/sync/koreader/library'
-  auth:
-    type: bearer
-    token: '{{koreader_device_token}}'
 info:
   name: Get User Library for KOReader
-  seq: 9
   type: http
+  seq: 9
+
+http:
+  method: GET
+  url: '{{base_url}}/api/sync/koreader/library'
+  auth: inherit
+
+docs: |-
+  ## Get KOReader User Library
+
+  Retrieves the user's book library for KOReader device sync.
+
+  **Method:** GET
+
+  **Endpoint:** /api/sync/koreader/library
+
+  **Authentication:** Bearer token (koreader_device_token)
+
+  **Query Parameters:**
+  None (returns entire library)
+
+  **Response:**
+  - `books` (array): Library items
+    - `uuid` (string): SHA-256 based book identifier
+    - `title` (string): Book title
+    - `authors` (array): Author names
+    - `series` (string, optional): Series name
+    - `series_index` (number, optional): Series position
+    - `publisher` (string, optional): Publisher
+    - `publication_date` (string, optional): Release date
+    - `language` (string, optional): Language code
+    - `description` (string, optional): Description
+    - `cover_url` (string, optional): Cover image URL
+    - `cover_thumbnail_url` (string, optional): Thumbnail URL
+    - `file_metadata` (object):
+      - `format` (string): File format
+      - `file_size` (integer): Size in bytes
+      - `pages` (integer, optional): Page count
+    - `progress` (object, optional): Reading progress
+      - `percentage` (number): Progress 0-100
+      - `last_read` (string): Last read timestamp
+      - `epubcfi` (string): Current position
+    - `annotations_count` (object, optional): Annotation stats
+      - `highlights` (integer): Highlight count
+      - `notes` (integer): Note count
+      - `bookmarks` (integer): Bookmark count
+  - `library_info` (object):
+    - `total_books` (integer): Total book count
+    - `last_sync` (string): Last library sync timestamp
+    - `has_updates` (boolean): Updates available
+  - `user_info` (object):
+    - `user_id` (string): User identifier
+    - `email` (string): Email (masked)
+    - `libraries` (array): Available library IDs
+
+  **Status Codes:**
+  - 200: Success
+  - 401: Unauthorized
+  - 403: Device not approved
+
+  **Library Purpose for KOReader:**
+  - Discover books available for download
+  - Browse catalog on device
+  - Sync reading progress across books
+  - Download covers/metadata
+  - Series-based organization
+  - Cloud library access
+
+  **KOReader Device Features:**
+  - **OPDS catalog**: Native OPDS client
+  - **File browser**: See server books
+  - **Cloud download**: Download books on-demand
+  - **Metadata sync**: Automatic metadata fetching
+  - **Cover images**: Display in library view
+  - **Progress sync**: See progress across all books
+  - **Search**: Search library by title/author
+
+  **KOReader-Specific Features:**
+  - SHA-256 based book IDs
+  - Multi-format support (EPUB, FB2, PDF, DJVU, MOBI, etc.)
+  - Series sorting and grouping
+  - Language filtering
+  - Cover image caching
+  - Metadata for file browser enhancement
+  - Integration with KOReader's OPDS client
+
+  **Performance:**
+  - Typical response: 100-500KB for 100 books
+  - Processing time: 300ms-1s
+  - Cache duration: 5 minutes
+  - Pagination support for libraries >500 books
+
+  **Use Cases:**
+  - Initial device setup
+  - Library browsing on device
+  - Book download
+  - Metadata refresh
+  - Cover image sync
+  - Progress overview
+  - Series-based reading

bruno/devices/koreader/api.yml

@@ -0,0 +1,22 @@
+info:
+  name: Bookhoard KOReader Sync API
+  type: collection
+  seq: 1
+http:
+  method: POST
+  url: '"http://localhost:8765/api"'
+
+docs: |-
+  ## Bookhoard KOReader Sync API
+  
+    Collection of endpoints specifically for KOReader e-reader device synchronization.
+  
+    **Base URL:** http://localhost:8765/api
+  
+    **Authentication:** Device token or Bearer token required
+  
+    **Endpoints:**
+    - KOReader-specific sync protocols
+    - Metadata synchronization
+    - Reading progress sync
+    - Highlights and notes sync

bruno/devices/koreader/folder.yml

@@ -1,7 +0,0 @@
-info:
-  name: Bookhoard KOReader Sync API
-  type: folder
-  seq: 1
-request:
-  auth: inherit
-docs: "## Bookhoard KOReader Sync API\n\n  Collection of endpoints specifically for KOReader e-reader device synchronization.\n\n  **Base URL:** http://localhost:8765/api\n\n  **Authentication:** Device token or Bearer token required\n\n  **Endpoints:**\n  - KOReader-specific sync protocols\n  - Metadata synchronization\n  - Reading progress sync\n  - Highlights and notes sync"

bruno/devices/koreader/scenarios/Checkpoint Sync.yml

@@ -1,19 +1,123 @@
-docs: "## Checkpoint Sync\n\nIncremental sync using checkpoint-based change tracking.\n\n**Method:** POST\n\n**Endpoint:** /api/sync/koreader/progress\n\n**Authentication:** Bearer token\n\n**Request Body:**\n- `sync_mode` (string): Must be `checkpoint`\n- `checkpoint_id` (string): Unique checkpoint identifier\n- `since_timestamp` (string): ISO 8601 timestamp for incremental sync\n- `books` (array): Book progress items\n  - `uuid` (string): Book UUID\n  - `percentage` (number): Progress 0.0-1.0\n  - `chapter` (integer): Current chapter\n  - `epubcfi` (string, optional): Current position\n  - `modified_since` (boolean, optional): Whether modified since checkpoint\n\n**Response:**\n- `checkpoint_id` (string): Server checkpoint ID\n- `checkpoint_timestamp` (string): Checkpoint creation time\n- `processed` (integer): Books processed\n- `changes_only` (boolean): Whether only changed items synced\n- `next_checkpoint_id` (string): ID for next checkpoint sync\n- `results` (array): Per-book results\n\
-  \n**Status Codes:**\n- 200: Checkpoint sync completed\n- 401: Unauthorized\n- 400: Invalid checkpoint or timestamp\n\n**Checkpoint Sync Benefits:**\n- **Incremental**: Only sync changed items\n- **Efficient**: Smaller payloads\n- **Fast**: Reduced processing time\n- **Reliable**: Checkpoint-based tracking\n- **Resumable**: Can continue from last checkpoint\n\n**Checkpoint Mechanism:**\n- Server tracks changes since checkpoint\n- Client provides checkpoint ID or timestamp\n- Only modified books returned/processed\n- Checkpoint ID advances on each sync\n- Supports large libraries efficiently\n\n**Use Cases:**\n- Large libraries (100+ books)\n- Intermittent connectivity\n- Bandwidth optimization\n- Battery conservation\n- Background sync\n- Periodic sync (every 5-15 minutes)\n\n**Checkpoint Lifecycle:**\n1. Initial sync: No checkpoint (full sync)\n2. Server returns checkpoint_id\n3. Next sync: Client sends checkpoint_id\n4. Server processes only changes\n5. New checkpoint_id returned\n6.\
-  \ Repeat from step 3\n\n**Sync Optimization:**\n- Only books with progress changes\n- Skips unmodified books\n- Delta transfer\n- Compression for large payloads\n- Batch processing\n\n**Failure Handling:**\n- Checkpoint ID preserved on failure\n- Retry with same checkpoint\n- Full sync if checkpoint expired\n- Checkpoint validity: 24 hours\n- Auto-fallback to full sync\n\n**Performance:**\n- Small changes (1-10 books): 100-300ms\n- Medium changes (10-50 books): 300ms-1s\n- Large changes (50-100 books): 1-3s\n- Typical: 5-10x faster than full sync\n\n**When to Use:**\n- Default sync mode for most users\n- Periodic background sync\n- Large library management\n- Mobile/network-constrained environments\n- Battery-powered devices\n\n**Configuration:**\n- Checkpoint expiration: 24 hours\n- Max history: 100 checkpoints\n- Auto-cleanup of old checkpoints\n- Configurable sync interval"
-http:
-  body:
-    type: json
-    data: "{\n  \"books\": [\n    {\n      \"chapter\": 3,\n      \"percentage\": 0.45,\n      \"uuid\": \"{{media_item_id}}\"\n    },\n    {\n      \"chapter\": 8,\n      \"percentage\": 0.75,\n      \"uuid\": \"{{media_item_id}}\"\n    }\n  ],\n  \"checkpoint_id\": \"checkpoint-uuid\",\n  \"since_timestamp\": \"2026-01-30T19:00:00Z\",\n  \"sync_mode\": \"checkpoint\"\n}"
-  headers:
-  - key: Content-Type
-    value: application/json
-  method: POST
-  url: '{{base_url}}/api/sync/koreader/progress'
-  auth:
-    type: bearer
-    token: '{{koreader_device_token}}'
 info:
   name: Checkpoint Sync
-  seq: 11
   type: http
+  seq: 11
+
+http:
+  method: POST
+  url: '{{base_url}}/api/sync/koreader/progress'
+  auth: inherit
+  headers:
+    - key: Content-Type
+      value: application/json
+  body:
+    type: json
+    json:
+      sync_mode: checkpoint
+      checkpoint_id: checkpoint-uuid
+      since_timestamp: '2026-01-30T19:00:00Z'
+      books:
+        - uuid: book-uuid-1
+          percentage: 0.45
+          chapter: 3
+        - uuid: book-uuid-2
+          percentage: 0.75
+          chapter: 8
+
+docs: |-
+  ## Checkpoint Sync
+
+  Incremental sync using checkpoint-based change tracking.
+
+  **Method:** POST
+
+  **Endpoint:** /api/sync/koreader/progress
+
+  **Authentication:** Bearer token
+
+  **Request Body:**
+  - `sync_mode` (string): Must be `checkpoint`
+  - `checkpoint_id` (string): Unique checkpoint identifier
+  - `since_timestamp` (string): ISO 8601 timestamp for incremental sync
+  - `books` (array): Book progress items
+    - `uuid` (string): Book UUID
+    - `percentage` (number): Progress 0.0-1.0
+    - `chapter` (integer): Current chapter
+    - `epubcfi` (string, optional): Current position
+    - `modified_since` (boolean, optional): Whether modified since checkpoint
+
+  **Response:**
+  - `checkpoint_id` (string): Server checkpoint ID
+  - `checkpoint_timestamp` (string): Checkpoint creation time
+  - `processed` (integer): Books processed
+  - `changes_only` (boolean): Whether only changed items synced
+  - `next_checkpoint_id` (string): ID for next checkpoint sync
+  - `results` (array): Per-book results
+
+  **Status Codes:**
+  - 200: Checkpoint sync completed
+  - 401: Unauthorized
+  - 400: Invalid checkpoint or timestamp
+
+  **Checkpoint Sync Benefits:**
+  - **Incremental**: Only sync changed items
+  - **Efficient**: Smaller payloads
+  - **Fast**: Reduced processing time
+  - **Reliable**: Checkpoint-based tracking
+  - **Resumable**: Can continue from last checkpoint
+
+  **Checkpoint Mechanism:**
+  - Server tracks changes since checkpoint
+  - Client provides checkpoint ID or timestamp
+  - Only modified books returned/processed
+  - Checkpoint ID advances on each sync
+  - Supports large libraries efficiently
+
+  **Use Cases:**
+  - Large libraries (100+ books)
+  - Intermittent connectivity
+  - Bandwidth optimization
+  - Battery conservation
+  - Background sync
+  - Periodic sync (every 5-15 minutes)
+
+  **Checkpoint Lifecycle:**
+  1. Initial sync: No checkpoint (full sync)
+  2. Server returns checkpoint_id
+  3. Next sync: Client sends checkpoint_id
+  4. Server processes only changes
+  5. New checkpoint_id returned
+  6. Repeat from step 3
+
+  **Sync Optimization:**
+  - Only books with progress changes
+  - Skips unmodified books
+  - Delta transfer
+  - Compression for large payloads
+  - Batch processing
+
+  **Failure Handling:**
+  - Checkpoint ID preserved on failure
+  - Retry with same checkpoint
+  - Full sync if checkpoint expired
+  - Checkpoint validity: 24 hours
+  - Auto-fallback to full sync
+
+  **Performance:**
+  - Small changes (1-10 books): 100-300ms
+  - Medium changes (10-50 books): 300ms-1s
+  - Large changes (50-100 books): 1-3s
+  - Typical: 5-10x faster than full sync
+
+  **When to Use:**
+  - Default sync mode for most users
+  - Periodic background sync
+  - Large library management
+  - Mobile/network-constrained environments
+  - Battery-powered devices
+
+  **Configuration:**
+  - Checkpoint expiration: 24 hours
+  - Max history: 100 checkpoints
+  - Auto-cleanup of old checkpoints
+  - Configurable sync interval

bruno/devices/koreader/scenarios/Immediate Sync - Page Turn.yml

@@ -1,19 +1,105 @@
-docs: "## Immediate Sync - Page Turn\n\nReal-time progress sync triggered immediately on page turn.\n\n**Method:** POST\n\n**Endpoint:** /api/sync/koreader/progress\n\n**Authentication:** Bearer token\n\n**Request Body:**\n- `sync_mode` (string): Must be `immediate`\n- `books` (array): Current book progress\n  - `uuid` (string): Book UUID\n  - `percentage` (number): Precise progress (0.45678 = 45.678%)\n  - `chapter` (integer): Current chapter\n  - `timestamp` (string): ISO 8601 timestamp\n  - `epubcfi` (string, optional): Current position\n  - `page` (integer, optional): Current page\n\n**Response:**\n- `synced` (boolean): Immediate sync status\n- `timestamp` (string): Server timestamp\n- `next_sync_suggested` (string): Suggested next sync time\n\n**Status Codes:**\n- 200: Sync queued\n- 202: Accepted for processing\n- 401: Unauthorized\n- 429: Too many immediate sync requests (rate limited)\n\n**Immediate Sync Mode:**\n- **Purpose**: Real-time progress updates\n- **Trigger**: Every page\
-  \ turn (configurable)\n- **Priority**: High priority processing\n- **Latency**: <100ms typical\n- **Best effort**: May be queued under load\n\n**Rate Limiting:**\n- Max 60 requests per minute per device\n- Throttled after limit reached\n- Suggests switching to periodic sync\n- Prevents server overload\n\n**Use Cases:**\n- Real-time multi-device reading\n- Live progress sharing\n- Instant position backup\n- Critical reading points\n- Test/profiling mode\n\n**Performance:**\n- Ultra-fast sync\n- Minimal payload\n- Optimized for speed\n- Async processing\n- No confirmation wait\n\n**Battery Considerations:**\n- More frequent network use\n- Higher battery consumption\n- WiFi recommended\n- Can reduce sync frequency in settings\n\n**Configuration:**\n- Can enable/disable per device\n- Adjustable frequency (every page, every N pages)\n- Automatic fallback to periodic sync on error\n- Respects device power-save mode\n\n**When to Use:**\n- Critical reading sessions\n- Multi-device concurrent reading\n\
-  - Research and study\n- Testing sync functionality\n- When power source available\n\n**When NOT to Use:**\n- Battery conservation needed\n- Unstable network\n- Extended reading sessions\n- Background sync preferred"
-http:
-  body:
-    type: json
-    data: "{\n  \"books\": [\n    {\n      \"chapter\": 3,\n      \"percentage\": 0.45678,\n      \"timestamp\": \"2026-01-30T20:00:00Z\",\n      \"uuid\": \"{{media_item_id}}\"\n    }\n  ],\n  \"sync_mode\": \"immediate\"\n}"
-  headers:
-  - key: Content-Type
-    value: application/json
-  method: POST
-  url: '{{base_url}}/api/sync/koreader/progress'
-  auth:
-    type: bearer
-    token: '{{koreader_device_token}}'
 info:
   name: Immediate Sync - Page Turn
-  seq: 10
   type: http
+  seq: 10
+
+http:
+  method: POST
+  url: '{{base_url}}/api/sync/koreader/progress'
+  auth: inherit
+  headers:
+    - key: Content-Type
+      value: application/json
+  body:
+    type: json
+    json:
+      sync_mode: immediate
+      books:
+        - uuid: book-uuid
+          percentage: 0.45678
+          chapter: 3
+          timestamp: '2026-01-30T20:00:00Z'
+
+docs: |-
+  ## Immediate Sync - Page Turn
+
+  Real-time progress sync triggered immediately on page turn.
+
+  **Method:** POST
+
+  **Endpoint:** /api/sync/koreader/progress
+
+  **Authentication:** Bearer token
+
+  **Request Body:**
+  - `sync_mode` (string): Must be `immediate`
+  - `books` (array): Current book progress
+    - `uuid` (string): Book UUID
+    - `percentage` (number): Precise progress (0.45678 = 45.678%)
+    - `chapter` (integer): Current chapter
+    - `timestamp` (string): ISO 8601 timestamp
+    - `epubcfi` (string, optional): Current position
+    - `page` (integer, optional): Current page
+
+  **Response:**
+  - `synced` (boolean): Immediate sync status
+  - `timestamp` (string): Server timestamp
+  - `next_sync_suggested` (string): Suggested next sync time
+
+  **Status Codes:**
+  - 200: Sync queued
+  - 202: Accepted for processing
+  - 401: Unauthorized
+  - 429: Too many immediate sync requests (rate limited)
+
+  **Immediate Sync Mode:**
+  - **Purpose**: Real-time progress updates
+  - **Trigger**: Every page turn (configurable)
+  - **Priority**: High priority processing
+  - **Latency**: <100ms typical
+  - **Best effort**: May be queued under load
+
+  **Rate Limiting:**
+  - Max 60 requests per minute per device
+  - Throttled after limit reached
+  - Suggests switching to periodic sync
+  - Prevents server overload
+
+  **Use Cases:**
+  - Real-time multi-device reading
+  - Live progress sharing
+  - Instant position backup
+  - Critical reading points
+  - Test/profiling mode
+
+  **Performance:**
+  - Ultra-fast sync
+  - Minimal payload
+  - Optimized for speed
+  - Async processing
+  - No confirmation wait
+
+  **Battery Considerations:**
+  - More frequent network use
+  - Higher battery consumption
+  - WiFi recommended
+  - Can reduce sync frequency in settings
+
+  **Configuration:**
+  - Can enable/disable per device
+  - Adjustable frequency (every page, every N pages)
+  - Automatic fallback to periodic sync on error
+  - Respects device power-save mode
+
+  **When to Use:**
+  - Critical reading sessions
+  - Multi-device concurrent reading
+  - Research and study
+  - Testing sync functionality
+  - When power source available
+
+  **When NOT to Use:**
+  - Battery conservation needed
+  - Unstable network
+  - Extended reading sessions
+  - Background sync preferred

bruno/devices/koreader/scenarios/Sync Annotations (Per-Book SHA-256).yml

@@ -1,15 +1,44 @@
-docs: "## KOReader Sync Annotations - Per-Book SHA-256\n\n  Synchronizes annotations (highlights) from KOReader with per-annotation SHA-256 hashes for multi-book sync.\n\n  **Method:** POST\n\n  **Endpoint:** /api/v1/koreader/sync/bookmarks\n\n  **Authentication:** Bearer token (KOReader device token)\n\n  **Request Body:**\n  - `book_uuid` (string): Primary book UUID\n  - `highlights` (array): Array of highlight objects\n    - `text` (string): Highlighted text\n    - `pos0`, `pos1` (string): EPUB CFI positions\n    - `color` (string): Highlight color (hex)\n    - `page` (number): Page number\n    - `book_sha256` (string): SHA-256 hash for this specific book\n\n  **Response:**\n  - `highlights_synced` (number): Number of highlights synced\n\n  **Status Codes:**\n  - 200: Success\n  - 401: Unauthorized\n  - 500: Internal server error\n\n  **Note:** Each highlight can include its own book_sha256, allowing annotations from multiple books in a single request."
-http:
-  body:
-    type: json
-    data: "{\n  \"book_sha256\": \"{{book_sha256}}\",\n  \"bookmarks\": [\n    {\n      \"chapter\": 3,\n      \"datetime\": \"2026-01-30T19:55:00Z\",\n      \"page\": 45,\n      \"pos0\": \"p1\",\n      \"text\": \"Per-book annotation\",\n      \"type\": \"bookmark\"\n    }\n  ]\n}"
-  headers: []
-  method: POST
-  url: '{{base_url}}/api/sync/koreader/bookmarks'
-  auth:
-    type: bearer
-    token: '{{koreader_device_token}}'
 info:
   name: KOReader Sync Annotations - Per-Book SHA-256
-  seq: 4
   type: http
+  seq: 4
+http:
+  method: POST
+  url: '{{base_url}}/api/v1/koreader/sync/bookmarks'
+  auth: inherit
+  body:
+    type: json
+    jsonBody: "{\n    \"book_uuid\": \"{{book_uuid"
+  headers:
+  - key: Authorization
+    value: Bearer {{koreader_device_token
+
+docs: |-
+  ## KOReader Sync Annotations - Per-Book SHA-256
+  
+    Synchronizes annotations (highlights) from KOReader with per-annotation SHA-256 hashes for multi-book sync.
+  
+    **Method:** POST
+  
+    **Endpoint:** /api/v1/koreader/sync/bookmarks
+  
+    **Authentication:** Bearer token (KOReader device token)
+  
+    **Request Body:**
+    - `book_uuid` (string): Primary book UUID
+    - `highlights` (array): Array of highlight objects
+      - `text` (string): Highlighted text
+      - `pos0`, `pos1` (string): EPUB CFI positions
+      - `color` (string): Highlight color (hex)
+      - `page` (number): Page number
+      - `book_sha256` (string): SHA-256 hash for this specific book
+  
+    **Response:**
+    - `highlights_synced` (number): Number of highlights synced
+  
+    **Status Codes:**
+    - 200: Success
+    - 401: Unauthorized
+    - 500: Internal server error
+  
+    **Note:** Each highlight can include its own book_sha256, allowing annotations from multiple books in a single request.

bruno/devices/koreader/scenarios/Sync Bookmarks (SHA-256).yml

@@ -1,15 +1,40 @@
-docs: "## KOReader Sync Bookmarks - SHA-256\n\n  Synchronizes bookmarks, notes, and highlights from KOReader using SHA-256 hash for book identification.\n\n  **Method:** POST\n\n  **Endpoint:** /api/v1/koreader/sync/bookmarks\n\n  **Authentication:** Bearer token (KOReader device token)\n\n  **Request Body:**\n  - `book_sha256` (string): SHA-256 hash of book file\n  - `bookmarks` (array): Array of bookmarks\n  - `notes` (array): Array of notes\n  - `highlights` (array): Array of highlights\n\n  **Response:**\n  - `sync_status` (string): Sync status\n  - `total_synced` (number): Total items synced\n\n  **Status Codes:**\n  - 200: Success\n  - 401: Unauthorized\n  - 500: Internal server error"
-http:
-  body:
-    type: json
-    data: "{\n  \"book_sha256\": \"{{book_sha256}}\",\n  \"bookmarks\": [\n    {\n      \"chapter\": 3,\n      \"datetime\": \"2026-01-30T19:55:00Z\",\n      \"page\": 45,\n      \"pos0\": \"p1\",\n      \"text\": \"SHA-256 bookmark\",\n      \"type\": \"bookmark\"\n    }\n  ]\n}"
-  headers: []
-  method: POST
-  url: '{{base_url}}/api/sync/koreader/bookmarks'
-  auth:
-    type: bearer
-    token: '{{koreader_device_token}}'
 info:
   name: KOReader Sync Bookmarks - SHA-256
-  seq: 3
   type: http
+  seq: 3
+http:
+  method: POST
+  url: '{{base_url}}/api/v1/koreader/sync/bookmarks'
+  auth: inherit
+  body:
+    type: json
+    jsonBody: "{\n    \"book_sha256\": \"{{book_sha256"
+  headers:
+  - key: Authorization
+    value: Bearer {{koreader_device_token
+
+docs: |-
+  ## KOReader Sync Bookmarks - SHA-256
+  
+    Synchronizes bookmarks, notes, and highlights from KOReader using SHA-256 hash for book identification.
+  
+    **Method:** POST
+  
+    **Endpoint:** /api/v1/koreader/sync/bookmarks
+  
+    **Authentication:** Bearer token (KOReader device token)
+  
+    **Request Body:**
+    - `book_sha256` (string): SHA-256 hash of book file
+    - `bookmarks` (array): Array of bookmarks
+    - `notes` (array): Array of notes
+    - `highlights` (array): Array of highlights
+  
+    **Response:**
+    - `sync_status` (string): Sync status
+    - `total_synced` (number): Total items synced
+  
+    **Status Codes:**
+    - 200: Success
+    - 401: Unauthorized
+    - 500: Internal server error

bruno/devices/koreader/scenarios/Sync Bookmarks.yml

@@ -1,19 +1,105 @@
-docs: "## Sync KOReader Bookmarks\n\nSynchronizes bookmarks separately from progress for KOReader.\n\n**Method:** POST\n\n**Endpoint:** /api/sync/koreader/bookmarks\n\n**Authentication:** Bearer token\n\n**Request Body:**\n- `library_id` (string, optional): Library UUID\n- `books` (array): Books with bookmarks\n  - `uuid` (string): Book UUID\n  - `bookmarks` (array): Bookmark items\n    - `chapter` (integer): Chapter number\n    - `datetime` (string): ISO 8601 timestamp\n    - `notes` (string): Bookmark description\n    - `pos0` (string): EPUB CFI start position\n    - `pos1` (string): EPUB CFI end position\n    - `page` (integer): Page number\n    - `text` (string): Displayed text\n    - `type` (string): `bookmark`, `highlight`, or `note`\n\n**Response:**\n- `synced` (integer): Number of bookmarks synced\n- `duplicates_skipped` (integer): Duplicate bookmarks skipped\n- `results` (array): Per-bookmark results\n- `timestamp` (string): Sync timestamp\n\n**Status Codes:**\n- 200: Success\n\
-  - 401: Unauthorized\n- 400: Invalid data\n\n**Dedicated Bookmark Endpoint:**\n- **Purpose**: Sync bookmarks independently\n- **Use case**: More frequent bookmark updates\n- **Advantage**: Separate from progress sync\n- **Efficiency**: Smaller payloads\n\n**KOReader Bookmark Features:**\n- Chapter-based organization\n- Quick navigation markers\n- Hierarchical bookmarks (via plugins)\n- Custom bookmark titles\n- Date/time tracking\n- EPUB CFI precision\n\n**Bookmark Types in KOReader:**\n- **Location bookmarks**: Quick navigation points\n- **Chapter marks**: Auto-generated chapter markers\n- **Progress bookmarks**: Last read positions\n- **Custom bookmarks**: User-created markers\n- **Search bookmarks**: Saved search results\n\n**Sync Behavior:**\n- Duplicate detection by position + text\n- Most recent wins on conflicts\n- Chapter order preserved\n- Auto-generated vs manual bookmarks differentiated\n- Merge with existing bookmarks\n\n**KOReader Device Integration:**\n- Created via \"Add\
-  \ bookmark\" menu\n- Shown in \"Bookmarks\" panel\n- Quick access via \"Go to bookmark\"\n- Exportable to JSON\n- Can be edited/deleted\n\n**Use Cases:**\n- Quick navigation aids\n- Chapter markers\n- Important passages\n- Reading progress points\n- Study session markers"
-http:
-  body:
-    type: json
-    data: "{\n  \"book_uuid\": \"{{media_item_id}}\",\n  \"bookmarks\": [\n    {\n      \"chapter\": 3,\n      \"datetime\": \"2026-01-30T19:55:00Z\",\n      \"page\": 45,\n      \"pos0\": \"epubcfi(/6/4/2:15)\",\n      \"pos1\": \"epubcfi(/6/4/2:20)\",\n      \"text\": \"Important passage\",\n      \"type\": \"bookmark\"\n    }\n  ]\n}"
-  headers:
-  - key: Content-Type
-    value: application/json
-  method: POST
-  url: '{{base_url}}/api/sync/koreader/bookmarks'
-  auth:
-    type: bearer
-    token: '{{koreader_device_token}}'
 info:
   name: Sync Bookmarks
-  seq: 5
   type: http
+  seq: 5
+
+http:
+  method: POST
+  url: '{{base_url}}/api/sync/koreader/bookmarks'
+  auth: inherit
+  headers:
+    - key: Content-Type
+      value: application/json
+  body:
+    type: json
+    json:
+      library_id: optional-library-uuid
+      books:
+        - uuid: book-uuid
+          bookmarks:
+            - chapter: 3
+              datetime: '2026-01-30T19:55:00Z'
+              notes: Marked this chapter as important
+              pos0: 'epubcfi(/6/4/2:15)'
+              pos1: 'epubcfi(/6/4/2:20)'
+              page: 45
+              text: Important passage
+              type: bookmark
+
+docs: |-
+  ## Sync KOReader Bookmarks
+
+  Synchronizes bookmarks separately from progress for KOReader.
+
+  **Method:** POST
+
+  **Endpoint:** /api/sync/koreader/bookmarks
+
+  **Authentication:** Bearer token
+
+  **Request Body:**
+  - `library_id` (string, optional): Library UUID
+  - `books` (array): Books with bookmarks
+    - `uuid` (string): Book UUID
+    - `bookmarks` (array): Bookmark items
+      - `chapter` (integer): Chapter number
+      - `datetime` (string): ISO 8601 timestamp
+      - `notes` (string): Bookmark description
+      - `pos0` (string): EPUB CFI start position
+      - `pos1` (string): EPUB CFI end position
+      - `page` (integer): Page number
+      - `text` (string): Displayed text
+      - `type` (string): `bookmark`, `highlight`, or `note`
+
+  **Response:**
+  - `synced` (integer): Number of bookmarks synced
+  - `duplicates_skipped` (integer): Duplicate bookmarks skipped
+  - `results` (array): Per-bookmark results
+  - `timestamp` (string): Sync timestamp
+
+  **Status Codes:**
+  - 200: Success
+  - 401: Unauthorized
+  - 400: Invalid data
+
+  **Dedicated Bookmark Endpoint:**
+  - **Purpose**: Sync bookmarks independently
+  - **Use case**: More frequent bookmark updates
+  - **Advantage**: Separate from progress sync
+  - **Efficiency**: Smaller payloads
+
+  **KOReader Bookmark Features:**
+  - Chapter-based organization
+  - Quick navigation markers
+  - Hierarchical bookmarks (via plugins)
+  - Custom bookmark titles
+  - Date/time tracking
+  - EPUB CFI precision
+
+  **Bookmark Types in KOReader:**
+  - **Location bookmarks**: Quick navigation points
+  - **Chapter marks**: Auto-generated chapter markers
+  - **Progress bookmarks**: Last read positions
+  - **Custom bookmarks**: User-created markers
+  - **Search bookmarks**: Saved search results
+
+  **Sync Behavior:**
+  - Duplicate detection by position + text
+  - Most recent wins on conflicts
+  - Chapter order preserved
+  - Auto-generated vs manual bookmarks differentiated
+  - Merge with existing bookmarks
+
+  **KOReader Device Integration:**
+  - Created via "Add bookmark" menu
+  - Shown in "Bookmarks" panel
+  - Quick access via "Go to bookmark"
+  - Exportable to JSON
+  - Can be edited/deleted
+
+  **Use Cases:**
+  - Quick navigation aids
+  - Chapter markers
+  - Important passages
+  - Reading progress points
+  - Study session markers

bruno/devices/koreader/scenarios/Sync Highlights.yml

@@ -1,16 +1,110 @@
-docs: "## Sync KOReader Highlights\n\nSynchronizes text highlights separately from other annotations.\n\n**Method:** POST\n\n**Endpoint:** /api/sync/koreader/highlights\n\n**Authentication:** Bearer token\n\n**Request Body:**\n- `library_id` (string, optional): Library UUID\n- `books` (array): Books with highlights\n  - `uuid` (string): Book UUID\n  - `highlights` (array): Highlight items\n    - `datetime` (string): Creation timestamp\n    - `text` (string): Highlighted text content\n    - `chapter` (integer): Chapter number\n    - `pos0` (string): EPUB CFI start position\n    - `pos1` (string): EPUB CFI end position\n    - `page_start` (integer): Start page\n    - `page_end` (integer): End page\n    - `color` (string, optional): Color name or hex\n    - `note` (string, optional): Attached note\n\n**Response:**\n- `synced` (integer): Highlights synced\n- `duplicates_skipped` (integer): Duplicates found\n- `with_notes` (integer): Highlights that have notes attached\n- `timestamp` (string):\
-  \ Sync timestamp\n\n**KOReader Highlight Features:**\n- Precise text selection (EPUB CFI)\n- Custom color support (via plugins)\n- Multi-page highlights\n- Chapter references\n- Timestamps for sorting\n- Attached notes support\n- Full text preservation\n\n**Highlight Colors (via plugins):**\n- Yellow (default): General highlighting\n- Green: Important concepts\n- Blue: Key information\n- Red/pink: Critical content\n- Orange: Interesting quotes\n- Custom RGB colors available\n\n**EPUB CFI Advantages:**\n- Precise start/end positions\n- Works across font size changes\n- Survives text reflow\n- Device-independent\n- Standardized format\n\n**Dedicated Highlight Endpoint:**\n- **Separate from progress**: Sync highlights independently\n- **Smaller payload**: Just highlights, no progress\n- **More frequent**: Can sync highlights immediately\n- **Focused**: Single-purpose endpoint\n\n**Sync Behavior:**\n- Exact text matching for duplicates\n- Position-based conflict resolution\n- Color preservation\
-  \ across devices\n- Note attachments preserved\n- Order maintained by position\n\n**KOReader Device Features:**\n- Created via long-press or selection\n- Color picker available\n- Can add notes immediately\n- Shows in \"Highlights\" panel\n- Exportable to Evernote, etc.\n- Searchable by content\n\n**Use Cases:**\n- Study and research\n- Content curation\n- Quote collection\n- Academic work\n- Sharing insights"
-http:
-  body:
-    type: json
-    data: "{\n  \"book_uuid\": \"786b9c39-e8c3-47ab-a48a-c7f6cd769930\",\n  \"highlights\": [\n    {\n      \"datetime\": \"2026-01-30T19:50:00Z\",\n      \"text\": \"bruno sweep highlight\",\n      \"chapter\": 1,\n      \"page\": 1,\n      \"pos0\": \"1\",\n      \"pos1\": \"9\",\n      \"color\": \"#ffff00\"\n    }\n  ]\n}"
-  method: POST
-  url: '{{base_url}}/api/sync/koreader/bookmarks'
-  auth:
-    type: bearer
-    token: '{{koreader_device_token}}'
 info:
   name: Sync Highlights
-  seq: 6
   type: http
+  seq: 6
+
+http:
+  method: POST
+  url: '{{base_url}}/api/sync/koreader/highlights'
+  auth: inherit
+  headers:
+    - key: Content-Type
+      value: application/json
+  body:
+    type: json
+    json:
+      library_id: optional-library-uuid
+      books:
+        - uuid: book-uuid
+          highlights:
+            - datetime: '2026-01-30T19:50:00Z'
+              text: Important quote from book
+              chapter: 4
+              pos0: 'epubcfi(/6/4/2:20)'
+              pos1: 'epubcfi(/6/4/2:30)'
+              page_start: 78
+              page_end: 79
+
+docs: |-
+  ## Sync KOReader Highlights
+
+  Synchronizes text highlights separately from other annotations.
+
+  **Method:** POST
+
+  **Endpoint:** /api/sync/koreader/highlights
+
+  **Authentication:** Bearer token
+
+  **Request Body:**
+  - `library_id` (string, optional): Library UUID
+  - `books` (array): Books with highlights
+    - `uuid` (string): Book UUID
+    - `highlights` (array): Highlight items
+      - `datetime` (string): Creation timestamp
+      - `text` (string): Highlighted text content
+      - `chapter` (integer): Chapter number
+      - `pos0` (string): EPUB CFI start position
+      - `pos1` (string): EPUB CFI end position
+      - `page_start` (integer): Start page
+      - `page_end` (integer): End page
+      - `color` (string, optional): Color name or hex
+      - `note` (string, optional): Attached note
+
+  **Response:**
+  - `synced` (integer): Highlights synced
+  - `duplicates_skipped` (integer): Duplicates found
+  - `with_notes` (integer): Highlights that have notes attached
+  - `timestamp` (string): Sync timestamp
+
+  **KOReader Highlight Features:**
+  - Precise text selection (EPUB CFI)
+  - Custom color support (via plugins)
+  - Multi-page highlights
+  - Chapter references
+  - Timestamps for sorting
+  - Attached notes support
+  - Full text preservation
+
+  **Highlight Colors (via plugins):**
+  - Yellow (default): General highlighting
+  - Green: Important concepts
+  - Blue: Key information
+  - Red/pink: Critical content
+  - Orange: Interesting quotes
+  - Custom RGB colors available
+
+  **EPUB CFI Advantages:**
+  - Precise start/end positions
+  - Works across font size changes
+  - Survives text reflow
+  - Device-independent
+  - Standardized format
+
+  **Dedicated Highlight Endpoint:**
+  - **Separate from progress**: Sync highlights independently
+  - **Smaller payload**: Just highlights, no progress
+  - **More frequent**: Can sync highlights immediately
+  - **Focused**: Single-purpose endpoint
+
+  **Sync Behavior:**
+  - Exact text matching for duplicates
+  - Position-based conflict resolution
+  - Color preservation across devices
+  - Note attachments preserved
+  - Order maintained by position
+
+  **KOReader Device Features:**
+  - Created via long-press or selection
+  - Color picker available
+  - Can add notes immediately
+  - Shows in "Highlights" panel
+  - Exportable to Evernote, etc.
+  - Searchable by content
+
+  **Use Cases:**
+  - Study and research
+  - Content curation
+  - Quote collection
+  - Academic work
+  - Sharing insights

bruno/devices/koreader/scenarios/Sync Notes.yml

@@ -1,19 +1,108 @@
-docs: "## Sync KOReader Notes\n\nSynchronizes user notes separately from highlights and bookmarks.\n\n**Method:** POST\n\n**Endpoint:** /api/sync/koreader/notes\n\n**Authentication:** Bearer token\n\n**Request Body:**\n- `library_id` (string, optional): Library UUID\n- `books` (array): Books with notes\n  - `uuid` (string): Book UUID\n  - `notes` (array): Note items\n    - `datetime` (string): Creation/modification timestamp\n    - `text` (string): Note content\n    - `chapter` (integer): Chapter number\n    - `pos0` (string, optional): Related EPUB CFI position\n    - `page` (integer, optional): Page number\n    - `highlighted_text` (string, optional): Related highlight\n\n**Response:**\n- `synced` (integer): Notes synced\n- `duplicates_skipped` (integer): Duplicate notes found\n- `attached_to_highlights` (integer): Notes linked to highlights\n- `timestamp` (string): Sync timestamp\n\n**KOReader Note Features:**\n- Free-form text notes\n- Can be standalone or attached to highlights\n- Chapter-based\
-  \ organization\n- Timestamped for sorting\n- Markdown support (some versions)\n- Longer form content\n- No character limit\n\n**Note Types:**\n- **Standalone notes**: Independent notes about chapter/section\n- **Attached notes**: Notes attached to specific highlights\n- **Chapter notes**: Notes about entire chapter\n- **Book notes**: General notes about the book\n\n**Dedicated Notes Endpoint:**\n- **Separate sync**: Notes sync independently\n- **Flexible**: Not tied to highlights\n- **Efficient**: Smaller, focused payload\n- **Immediate**: Can sync right after note creation\n\n**Attached Notes:**\n- Linked to specific highlight\n- Shares highlight's position\n- Shown together with highlight\n- Deleted when highlight deleted (optional)\n- Color matches highlight\n\n**Sync Behavior:**\n- Text-based duplicate detection\n- Time-based conflict resolution\n- Chapter organization preserved\n- Markdown formatting preserved\n- Attachment links maintained\n\n**KOReader Device Integration:**\n- Created\
-  \ via \"Add note\" option\n- Edited in note editor\n- Shown in \"Notes\" panel\n- Can be organized by chapter\n- Export functionality available\n- Search support\n\n**Advanced Features:**\n- **Markdown**: Bold, italic, lists (some versions)\n- **Tags**: User-defined tags (via plugins)\n- **Links**: Internal/external links\n- **Formatting**: Rich text in newer versions\n\n**Use Cases:**\n- Study notes\n- Personal reflections\n- Academic annotations\n- Research insights\n- Book club discussion prep\n- Knowledge management"
-http:
-  body:
-    type: json
-    data: "{\n  \"book_uuid\": \"{{media_item_id}}\",\n  \"notes\": [\n    {\n      \"datetime\": \"2026-01-30T19:52:00Z\",\n      \"notes\": \"A personal note about this chapter\",\n      \"chapter\": 4,\n      \"page\": 57,\n      \"pos0\": \"3\"\n    }\n  ]\n}"
-  headers:
-  - key: Content-Type
-    value: application/json
-  method: POST
-  url: '{{base_url}}/api/sync/koreader/bookmarks'
-  auth:
-    type: bearer
-    token: '{{koreader_device_token}}'
 info:
   name: Sync Notes
-  seq: 7
   type: http
+  seq: 7
+
+http:
+  method: POST
+  url: '{{base_url}}/api/sync/koreader/notes'
+  auth: inherit
+  headers:
+    - key: Content-Type
+      value: application/json
+  body:
+    type: json
+    json:
+      library_id: optional-library-uuid
+      books:
+        - uuid: book-uuid
+          notes:
+            - datetime: '2026-01-30T19:52:00Z'
+              text: My personal note about this chapter
+              chapter: 4
+
+docs: |-
+  ## Sync KOReader Notes
+
+  Synchronizes user notes separately from highlights and bookmarks.
+
+  **Method:** POST
+
+  **Endpoint:** /api/sync/koreader/notes
+
+  **Authentication:** Bearer token
+
+  **Request Body:**
+  - `library_id` (string, optional): Library UUID
+  - `books` (array): Books with notes
+    - `uuid` (string): Book UUID
+    - `notes` (array): Note items
+      - `datetime` (string): Creation/modification timestamp
+      - `text` (string): Note content
+      - `chapter` (integer): Chapter number
+      - `pos0` (string, optional): Related EPUB CFI position
+      - `page` (integer, optional): Page number
+      - `highlighted_text` (string, optional): Related highlight
+
+  **Response:**
+  - `synced` (integer): Notes synced
+  - `duplicates_skipped` (integer): Duplicate notes found
+  - `attached_to_highlights` (integer): Notes linked to highlights
+  - `timestamp` (string): Sync timestamp
+
+  **KOReader Note Features:**
+  - Free-form text notes
+  - Can be standalone or attached to highlights
+  - Chapter-based organization
+  - Timestamped for sorting
+  - Markdown support (some versions)
+  - Longer form content
+  - No character limit
+
+  **Note Types:**
+  - **Standalone notes**: Independent notes about chapter/section
+  - **Attached notes**: Notes attached to specific highlights
+  - **Chapter notes**: Notes about entire chapter
+  - **Book notes**: General notes about the book
+
+  **Dedicated Notes Endpoint:**
+  - **Separate sync**: Notes sync independently
+  - **Flexible**: Not tied to highlights
+  - **Efficient**: Smaller, focused payload
+  - **Immediate**: Can sync right after note creation
+
+  **Attached Notes:**
+  - Linked to specific highlight
+  - Shares highlight's position
+  - Shown together with highlight
+  - Deleted when highlight deleted (optional)
+  - Color matches highlight
+
+  **Sync Behavior:**
+  - Text-based duplicate detection
+  - Time-based conflict resolution
+  - Chapter organization preserved
+  - Markdown formatting preserved
+  - Attachment links maintained
+
+  **KOReader Device Integration:**
+  - Created via "Add note" option
+  - Edited in note editor
+  - Shown in "Notes" panel
+  - Can be organized by chapter
+  - Export functionality available
+  - Search support
+
+  **Advanced Features:**
+  - **Markdown**: Bold, italic, lists (some versions)
+  - **Tags**: User-defined tags (via plugins)
+  - **Links**: Internal/external links
+  - **Formatting**: Rich text in newer versions
+
+  **Use Cases:**
+  - Study notes
+  - Personal reflections
+  - Academic annotations
+  - Research insights
+  - Book club discussion prep
+  - Knowledge management

bruno/devices/koreader/scenarios/Sync Progress (SHA-256 Only).yml

@@ -1,15 +1,47 @@
-docs: "## KOReader Sync Progress - SHA-256 Only\n\n  Synchronizes reading progress using only SHA-256 hash for book identification (when UUID is not available).\n\n  **Method:** POST\n\n  **Endpoint:** /api/v1/koreader/sync/progress\n\n  **Authentication:** Bearer token (KOReader device token)\n\n  **Request Body:**\n  - `sync_mode` (string): Sync mode (immediate, deferred)\n  - `books` (array): Array of book progress objects\n    - `sha256` (string): SHA-256 hash of book file\n    - `file_path` (string): Path to book file\n    - `percentage` (number): Progress percentage\n    - `page` (number): Current page\n    - `total_pages` (number): Total pages\n\n  **Response:**\n  - `sync_status` (string): Sync status\n  - `books_synced` (number): Number of books synced\n\n  **Status Codes:**\n  - 200: Success\n  - 202: Accepted\n  - 401: Unauthorized\n  - 500: Internal server error\n\n  **Note:** Use this when book UUID is not available, falling back to SHA-256 hash for identification."
-http:
-  body:
-    type: json
-    data: "{\n  \"sync_mode\": \"immediate\",\n  \"books\": [\n    {\n      \"sha256\": \"{{book_sha256}}\",\n      \"percentage\": 0.5\n    }\n  ]\n}"
-  headers: []
-  method: POST
-  url: '{{base_url}}/api/sync/koreader/progress'
-  auth:
-    type: bearer
-    token: '{{koreader_device_token}}'
 info:
   name: KOReader Sync Progress - SHA-256 Only
-  seq: 2
   type: http
+  seq: 2
+http:
+  method: POST
+  url: '{{base_url}}/api/v1/koreader/sync/progress'
+  auth: inherit
+  body:
+    type: json
+    jsonBody: "{\n    \"sync_mode\": \"immediate\",\n    \"books\": [\n      {\n \
+      \       \"sha256\": \"{{book_sha256"
+  headers:
+  - key: Authorization
+    value: Bearer {{koreader_device_token
+
+docs: |-
+  ## KOReader Sync Progress - SHA-256 Only
+  
+    Synchronizes reading progress using only SHA-256 hash for book identification (when UUID is not available).
+  
+    **Method:** POST
+  
+    **Endpoint:** /api/v1/koreader/sync/progress
+  
+    **Authentication:** Bearer token (KOReader device token)
+  
+    **Request Body:**
+    - `sync_mode` (string): Sync mode (immediate, deferred)
+    - `books` (array): Array of book progress objects
+      - `sha256` (string): SHA-256 hash of book file
+      - `file_path` (string): Path to book file
+      - `percentage` (number): Progress percentage
+      - `page` (number): Current page
+      - `total_pages` (number): Total pages
+  
+    **Response:**
+    - `sync_status` (string): Sync status
+    - `books_synced` (number): Number of books synced
+  
+    **Status Codes:**
+    - 200: Success
+    - 202: Accepted
+    - 401: Unauthorized
+    - 500: Internal server error
+  
+    **Note:** Use this when book UUID is not available, falling back to SHA-256 hash for identification.

bruno/devices/koreader/scenarios/Sync Progress (SHA-256).yml

@@ -1,16 +1,51 @@
-docs: "## KOReader Sync Progress - SHA-256\n\n  Synchronizes reading progress from a KOReader device using SHA-256 book hash for identification.\n\n  **Method:** POST\n\n  **Endpoint:** /api/v1/koreader/sync/progress\n\n  **Authentication:** Bearer token (KOReader device token)\n\n  **Request Body:**\n  - `sync_mode` (string): Sync mode (immediate, deferred)\n  - `books` (array): Array of book progress objects\n    - `uuid` (string): Book UUID\n    - `sha256` (string): SHA-256 hash of book file for identification\n    - `file_path` (string): Path to book file on device\n    - `percentage` (number): Progress percentage (0-1)\n    - `chapter` (number): Current chapter\n    - `page` (number): Current page\n    - `total_pages` (number): Total pages\n    - `epubcfi` (string): EPUB location\n    - `last_read` (string): ISO 8601 timestamp\n    - `title` (string): Book title\n    - `authors` (array): List of authors\n\n  **Response:**\n  - `sync_status` (string): Sync status\n  - `books_synced`\
-  \ (number): Number of books synced\n\n  **Status Codes:**\n  - 200: Success\n  - 202: Accepted - processing\n  - 401: Unauthorized\n  - 500: Internal server error"
-http:
-  body:
-    type: json
-    data: "{\n  \"sync_mode\": \"immediate\",\n  \"books\": [\n    {\n      \"sha256\": \"{{book_sha256}}\",\n      \"percentage\": 0.5\n    }\n  ]\n}"
-  headers: []
-  method: POST
-  url: '{{base_url}}/api/sync/koreader/progress'
-  auth:
-    type: bearer
-    token: '{{koreader_device_token}}'
 info:
   name: KOReader Sync Progress - SHA-256
-  seq: 1
   type: http
+  seq: 1
+http:
+  method: POST
+  url: '{{base_url}}/api/v1/koreader/sync/progress'
+  auth: inherit
+  body:
+    type: json
+    jsonBody: "{\n    \"sync_mode\": \"immediate\",\n    \"books\": [\n      {\n \
+      \       \"uuid\": \"{{book_uuid"
+  headers:
+  - key: Authorization
+    value: Bearer {{koreader_device_token
+
+docs: |-
+  ## KOReader Sync Progress - SHA-256
+  
+    Synchronizes reading progress from a KOReader device using SHA-256 book hash for identification.
+  
+    **Method:** POST
+  
+    **Endpoint:** /api/v1/koreader/sync/progress
+  
+    **Authentication:** Bearer token (KOReader device token)
+  
+    **Request Body:**
+    - `sync_mode` (string): Sync mode (immediate, deferred)
+    - `books` (array): Array of book progress objects
+      - `uuid` (string): Book UUID
+      - `sha256` (string): SHA-256 hash of book file for identification
+      - `file_path` (string): Path to book file on device
+      - `percentage` (number): Progress percentage (0-1)
+      - `chapter` (number): Current chapter
+      - `page` (number): Current page
+      - `total_pages` (number): Total pages
+      - `epubcfi` (string): EPUB location
+      - `last_read` (string): ISO 8601 timestamp
+      - `title` (string): Book title
+      - `authors` (array): List of authors
+  
+    **Response:**
+    - `sync_status` (string): Sync status
+    - `books_synced` (number): Number of books synced
+  
+    **Status Codes:**
+    - 200: Success
+    - 202: Accepted - processing
+    - 401: Unauthorized
+    - 500: Internal server error

bruno/devices/koreader/scenarios/Sync Progress - Multiple Books.yml

@@ -1,18 +1,90 @@
-docs: "## Sync KOReader Progress - Multiple Books\n\nSynchronizes reading progress for multiple books in a single request.\n\n**Method:** POST\n\n**Endpoint:** /api/sync/koreader/progress\n\n**Authentication:** Bearer token\n\n**Request Body:**\n- `library_id` (string, optional): Library UUID\n- `books` (array): Multiple book progress items\n  - Each item contains: uuid, title, authors, progress, percentage, last_read, chapter, epubcfi\n\n**Response:**\n- `synced` (integer): Number of books successfully synced\n- `failed` (integer): Number of books that failed\n- `results` (array): Per-book sync results\n- `timestamp` (string): Sync timestamp\n\n**Status Codes:**\n- 200: Batch sync completed\n- 207: Multi-status (partial success)\n- 401: Unauthorized\n- 413: Payload too large\n\n**Batch Sync Advantages:**\n- Efficient sync of entire library\n- Single HTTP request for multiple books\n- Faster periodic sync\n- Reduced battery usage vs individual syncs\n- Better for batch processing\n\n**KOReader\
-  \ Batch Behavior:**\n- Triggered on device wake from sleep\n- Occurs during \"Sync now\" operation\n- Runs on WiFi connection\n- Limited to 100 books per request\n- Automatic retry on failed books\n\n**Performance:**\n- Small batch (2-10 books): 200-500ms\n- Medium batch (10-50 books): 500ms-2s\n- Large batch (50-100 books): 2-5s\n- Timeout: 30 seconds\n\n**Use Cases:**\n- Device initialization sync\n- Periodic background sync\n- Post-offline catch-up sync\n- Library-wide progress update\n- Before firmware update"
-http:
-  body:
-    type: json
-    data: "{\n  \"books\": [\n    {\n      \"authors\": [\n        \"Author One\"\n      ],\n      \"chapter\": 1,\n      \"epubcfi\": \"epubcfi(/6/4/2:10)\",\n      \"last_read\": \"2026-01-30T19:00:00Z\",\n      \"percentage\": 0.25,\n      \"progress\": 0.25,\n      \"title\": \"Book One\",\n      \"uuid\": \"{{media_item_id}}\"\n    },\n    {\n      \"authors\": [\n        \"Author Two\"\n      ],\n      \"chapter\": 8,\n      \"epubcfi\": \"epubcfi(/6/4/2:50)\",\n      \"last_read\": \"2026-01-30T20:00:00Z\",\n      \"percentage\": 0.75,\n      \"progress\": 0.75,\n      \"title\": \"Book Two\",\n      \"uuid\": \"{{media_item_id}}\"\n    }\n  ],\n  \"library_id\": \"optional-library-uuid\"\n}"
-  headers:
-  - key: Content-Type
-    value: application/json
-  method: POST
-  url: '{{base_url}}/api/sync/koreader/progress'
-  auth:
-    type: bearer
-    token: '{{koreader_device_token}}'
 info:
   name: Sync Progress - Multiple Books
-  seq: 2
   type: http
+  seq: 2
+
+http:
+  method: POST
+  url: '{{base_url}}/api/sync/koreader/progress'
+  auth: inherit
+  headers:
+    - key: Content-Type
+      value: application/json
+  body:
+    type: json
+    json:
+      library_id: optional-library-uuid
+      books:
+        - uuid: book-1-uuid
+          title: Book One
+          authors:
+            - Author One
+          progress: 0.25
+          percentage: 0.25
+          last_read: '2026-01-30T19:00:00Z'
+          chapter: 1
+          epubcfi: 'epubcfi(/6/4/2:10)'
+        - uuid: book-2-uuid
+          title: Book Two
+          authors:
+            - Author Two
+          progress: 0.75
+          percentage: 0.75
+          last_read: '2026-01-30T20:00:00Z'
+          chapter: 8
+          epubcfi: 'epubcfi(/6/4/2:50)'
+
+docs: |-
+  ## Sync KOReader Progress - Multiple Books
+
+  Synchronizes reading progress for multiple books in a single request.
+
+  **Method:** POST
+
+  **Endpoint:** /api/sync/koreader/progress
+
+  **Authentication:** Bearer token
+
+  **Request Body:**
+  - `library_id` (string, optional): Library UUID
+  - `books` (array): Multiple book progress items
+    - Each item contains: uuid, title, authors, progress, percentage, last_read, chapter, epubcfi
+
+  **Response:**
+  - `synced` (integer): Number of books successfully synced
+  - `failed` (integer): Number of books that failed
+  - `results` (array): Per-book sync results
+  - `timestamp` (string): Sync timestamp
+
+  **Status Codes:**
+  - 200: Batch sync completed
+  - 207: Multi-status (partial success)
+  - 401: Unauthorized
+  - 413: Payload too large
+
+  **Batch Sync Advantages:**
+  - Efficient sync of entire library
+  - Single HTTP request for multiple books
+  - Faster periodic sync
+  - Reduced battery usage vs individual syncs
+  - Better for batch processing
+
+  **KOReader Batch Behavior:**
+  - Triggered on device wake from sleep
+  - Occurs during "Sync now" operation
+  - Runs on WiFi connection
+  - Limited to 100 books per request
+  - Automatic retry on failed books
+
+  **Performance:**
+  - Small batch (2-10 books): 200-500ms
+  - Medium batch (10-50 books): 500ms-2s
+  - Large batch (50-100 books): 2-5s
+  - Timeout: 30 seconds
+
+  **Use Cases:**
+  - Device initialization sync
+  - Periodic background sync
+  - Post-offline catch-up sync
+  - Library-wide progress update
+  - Before firmware update

bruno/devices/koreader/scenarios/Sync Progress - Single Book.yml

@@ -1,19 +1,92 @@
-docs: "## Sync KOReader Progress - Single Book\n\nSynchronizes reading progress for a single book from KOReader device.\n\n**Method:** POST\n\n**Endpoint:** /api/sync/koreader/progress\n\n**Authentication:** Bearer token (koreader_device_token)\n\n**Request Body:**\n- `library_id` (string, optional): Library UUID for multi-library setups\n- `books` (array): Array with single book progress\n  - `uuid` (string): Unique book identifier (often SHA-256 hash)\n  - `title` (string): Book title\n  - `authors` (array): List of authors\n  - `progress` (number): Progress decimal (0.0 to 1.0)\n  - `percentage` (number): Progress percentage (0.45 = 45%)\n  - `last_read` (string): ISO 8601 timestamp of last read\n  - `chapter` (integer): Current chapter number\n  - `epubcfi` (string): EPUB Canonical Fragment Identifier\n  - `character` (integer): Character position in book\n  - `page` (integer, optional): Current page number\n\n**Response:**\n- `synced` (integer): Number of books synced\n- `timestamp`\
-  \ (string): Server sync timestamp\n- `books` (array): Sync results\n  - `uuid` (string): Book UUID\n  - `status` (string): `synced`, `updated`, `skipped`\n  - `server_progress` (object): Server-side progress data\n\n**Status Codes:**\n- 200: Success\n- 401: Unauthorized\n- 400: Invalid request format\n\n**KOReader Progress Tracking:**\n- SHA-256 based book identification (universal across devices)\n- EPUB CFI for precise location (standard format)\n- Chapter-based navigation\n- Character-level precision\n- Supports EPUB, FB2, PDF, DJVU, MOBI formats\n\n**EPUB CFI Format:**\n- Standardized location format for EPUBs\n- Example: `epubcfi(/6/4/2:15)`\n- Identifies exact position even after reflow\n- Works across different devices/apps\n- Preserved after file modifications\n\n**Book Identification:**\n- Primary: SHA-256 hash of book file\n- Universal: Same book = same UUID across devices\n- Format-agnostic: Works for any supported format\n- Case-sensitive: Hash must match exactly\n\n**Use Cases:**\n\
-  - Real-time page turn sync\n- Progress backup\n- Cross-device continuity\n- Reading time tracking\n- Chapter completion detection"
-http:
-  body:
-    type: json
-    data: "{\n  \"books\": [\n    {\n      \"authors\": [\n        \"Author Name\"\n      ],\n      \"chapter\": 3,\n      \"character\": 15432,\n      \"epubcfi\": \"epubcfi(/6/4/2:15)\",\n      \"last_read\": \"2026-01-30T20:00:00Z\",\n      \"percentage\": 0.45,\n      \"progress\": 0.45,\n      \"title\": \"Book Title\",\n      \"uuid\": \"{{media_item_id}}\"\n    }\n  ],\n  \"library_id\": \"optional-library-uuid\"\n}"
-  headers:
-  - key: Content-Type
-    value: application/json
-  method: POST
-  url: '{{base_url}}/api/sync/koreader/progress'
-  auth:
-    type: bearer
-    token: '{{koreader_device_token}}'
 info:
   name: Sync Progress - Single Book
-  seq: 1
   type: http
+  seq: 1
+
+http:
+  method: POST
+  url: '{{base_url}}/api/sync/koreader/progress'
+  auth: inherit
+  headers:
+    - key: Content-Type
+      value: application/json
+  body:
+    type: json
+    json:
+      library_id: optional-library-uuid
+      books:
+        - uuid: book-uuid-here
+          title: Book Title
+          authors:
+            - Author Name
+          progress: 0.45
+          percentage: 0.45
+          last_read: '2026-01-30T20:00:00Z'
+          chapter: 3
+          epubcfi: 'epubcfi(/6/4/2:15)'
+          character: 15432
+
+docs: |-
+  ## Sync KOReader Progress - Single Book
+
+  Synchronizes reading progress for a single book from KOReader device.
+
+  **Method:** POST
+
+  **Endpoint:** /api/sync/koreader/progress
+
+  **Authentication:** Bearer token (koreader_device_token)
+
+  **Request Body:**
+  - `library_id` (string, optional): Library UUID for multi-library setups
+  - `books` (array): Array with single book progress
+    - `uuid` (string): Unique book identifier (often SHA-256 hash)
+    - `title` (string): Book title
+    - `authors` (array): List of authors
+    - `progress` (number): Progress decimal (0.0 to 1.0)
+    - `percentage` (number): Progress percentage (0.45 = 45%)
+    - `last_read` (string): ISO 8601 timestamp of last read
+    - `chapter` (integer): Current chapter number
+    - `epubcfi` (string): EPUB Canonical Fragment Identifier
+    - `character` (integer): Character position in book
+    - `page` (integer, optional): Current page number
+
+  **Response:**
+  - `synced` (integer): Number of books synced
+  - `timestamp` (string): Server sync timestamp
+  - `books` (array): Sync results
+    - `uuid` (string): Book UUID
+    - `status` (string): `synced`, `updated`, `skipped`
+    - `server_progress` (object): Server-side progress data
+
+  **Status Codes:**
+  - 200: Success
+  - 401: Unauthorized
+  - 400: Invalid request format
+
+  **KOReader Progress Tracking:**
+  - SHA-256 based book identification (universal across devices)
+  - EPUB CFI for precise location (standard format)
+  - Chapter-based navigation
+  - Character-level precision
+  - Supports EPUB, FB2, PDF, DJVU, MOBI formats
+
+  **EPUB CFI Format:**
+  - Standardized location format for EPUBs
+  - Example: `epubcfi(/6/4/2:15)`
+  - Identifies exact position even after reflow
+  - Works across different devices/apps
+  - Preserved after file modifications
+
+  **Book Identification:**
+  - Primary: SHA-256 hash of book file
+  - Universal: Same book = same UUID across devices
+  - Format-agnostic: Works for any supported format
+  - Case-sensitive: Hash must match exactly
+
+  **Use Cases:**
+  - Real-time page turn sync
+  - Progress backup
+  - Cross-device continuity
+  - Reading time tracking
+  - Chapter completion detection

bruno/devices/koreader/scenarios/Sync Progress - With Bookmarks.yml

@@ -1,19 +1,106 @@
-docs: "## Sync Progress with Bookmarks\n\nSynchronizes reading progress with bookmarks/highlights from KOReader.\n\n**Method:** POST\n\n**Endpoint:** /api/sync/koreader/progress\n\n**Authentication:** Bearer token\n\n**Request Body:**\n- `library_id` (string, optional): Library UUID\n- `books` (array): Books with progress and bookmarks\n  - `uuid`, `title`, `authors`, `progress`, etc.\n  - `bookmarks` (array): Bookmark items\n    - `chapter` (integer): Chapter number\n    - `datetime` (string): ISO 8601 timestamp\n    - `notes` (string): Note content or highlighted text\n    - `pos0` (string): EPUB CFI start position\n    - `pos1` (string): EPUB CFI end position\n    - `page` (integer): Page number\n    - `text` (string): Displayed text excerpt\n    - `type` (string): `highlight`, `bookmark`, or `note`\n\n**Response:**\n- `progress_synced` (integer): Progress items synced\n- `bookmarks_synced` (integer): Bookmark items synced\n- `highlights_synced` (integer): Highlight count\n- `timestamp`\
-  \ (string): Sync timestamp\n\n**KOReader Bookmark Types:**\n- **highlight**: Selected text passages\n- **bookmark**: Location markers\n- **note**: Text annotations (can be attached to highlights)\n\n**KOReader Highlight Features:**\n- Custom colors (via color extensions)\n- Multi-color support\n- Precise EPUB CFI positioning\n- Chapter-based organization\n- Text excerpts preserved\n- Date/time stamped\n- Page number tracking\n\n**EPUB CFI in Bookmarks:**\n- `pos0`: Start position (highlight start)\n- `pos1`: End position (highlight end)\n- Exact text selection boundaries\n- Survives text reflow\n- Works across different font sizes\n\n**Sync Behavior:**\n- Duplicate detection by text + position\n- Most recent edit wins\n- Chapter references maintained\n- Order preserved from device\n- Merges with existing server bookmarks\n\n**KOReader Device Integration:**\n- Created in KOReader highlight interface\n- Shows in \"Bookmarks\" menu\n- Can be edited/deleted on device\n- Exportable to JSON/XML\n\
-  - Searchable by content\n\n**Use Cases:**\n- Study and research\n- Content review\n- Passage tracking\n- Quick navigation\n- Cross-device bookmark access"
-http:
-  body:
-    type: json
-    data: "{\n  \"books\": [\n    {\n      \"authors\": [\n        \"Author Name\"\n      ],\n      \"bookmarks\": [\n        {\n          \"chapter\": 3,\n          \"datetime\": \"2026-01-30T19:55:00Z\",\n          \"notes\": \"highlighted text\",\n          \"page\": 45,\n          \"pos0\": \"epubcfi(/6/4/2:15)\",\n          \"pos1\": \"epubcfi(/6/4/2:20)\",\n          \"text\": \"highlighted text excerpt\",\n          \"type\": \"highlight\"\n        }\n      ],\n      \"last_read\": \"2026-01-30T20:00:00Z\",\n      \"percentage\": 0.45,\n      \"progress\": 0.45,\n      \"title\": \"Book Title\",\n      \"uuid\": \"{{media_item_id}}\"\n    }\n  ],\n  \"library_id\": \"optional-library-uuid\"\n}"
-  headers:
-  - key: Content-Type
-    value: application/json
-  method: POST
-  url: '{{base_url}}/api/sync/koreader/progress'
-  auth:
-    type: bearer
-    token: '{{koreader_device_token}}'
 info:
   name: Sync Progress - With Bookmarks
-  seq: 3
   type: http
+  seq: 3
+
+http:
+  method: POST
+  url: '{{base_url}}/api/sync/koreader/progress'
+  auth: inherit
+  headers:
+    - key: Content-Type
+      value: application/json
+  body:
+    type: json
+    json:
+      library_id: optional-library-uuid
+      books:
+        - uuid: book-uuid-here
+          title: Book Title
+          authors:
+            - Author Name
+          progress: 0.45
+          percentage: 0.45
+          last_read: '2026-01-30T20:00:00Z'
+          bookmarks:
+            - chapter: 3
+              datetime: '2026-01-30T19:55:00Z'
+              notes: highlighted text
+              pos0: 'epubcfi(/6/4/2:15)'
+              pos1: 'epubcfi(/6/4/2:20)'
+              page: 45
+              text: highlighted text excerpt
+              type: highlight
+
+docs: |-
+  ## Sync Progress with Bookmarks
+
+  Synchronizes reading progress with bookmarks/highlights from KOReader.
+
+  **Method:** POST
+
+  **Endpoint:** /api/sync/koreader/progress
+
+  **Authentication:** Bearer token
+
+  **Request Body:**
+  - `library_id` (string, optional): Library UUID
+  - `books` (array): Books with progress and bookmarks
+    - `uuid`, `title`, `authors`, `progress`, etc.
+    - `bookmarks` (array): Bookmark items
+      - `chapter` (integer): Chapter number
+      - `datetime` (string): ISO 8601 timestamp
+      - `notes` (string): Note content or highlighted text
+      - `pos0` (string): EPUB CFI start position
+      - `pos1` (string): EPUB CFI end position
+      - `page` (integer): Page number
+      - `text` (string): Displayed text excerpt
+      - `type` (string): `highlight`, `bookmark`, or `note`
+
+  **Response:**
+  - `progress_synced` (integer): Progress items synced
+  - `bookmarks_synced` (integer): Bookmark items synced
+  - `highlights_synced` (integer): Highlight count
+  - `timestamp` (string): Sync timestamp
+
+  **KOReader Bookmark Types:**
+  - **highlight**: Selected text passages
+  - **bookmark**: Location markers
+  - **note**: Text annotations (can be attached to highlights)
+
+  **KOReader Highlight Features:**
+  - Custom colors (via color extensions)
+  - Multi-color support
+  - Precise EPUB CFI positioning
+  - Chapter-based organization
+  - Text excerpts preserved
+  - Date/time stamped
+  - Page number tracking
+
+  **EPUB CFI in Bookmarks:**
+  - `pos0`: Start position (highlight start)
+  - `pos1`: End position (highlight end)
+  - Exact text selection boundaries
+  - Survives text reflow
+  - Works across different font sizes
+
+  **Sync Behavior:**
+  - Duplicate detection by text + position
+  - Most recent edit wins
+  - Chapter references maintained
+  - Order preserved from device
+  - Merges with existing server bookmarks
+
+  **KOReader Device Integration:**
+  - Created in KOReader highlight interface
+  - Shows in "Bookmarks" menu
+  - Can be edited/deleted on device
+  - Exportable to JSON/XML
+  - Searchable by content
+
+  **Use Cases:**
+  - Study and research
+  - Content review
+  - Passage tracking
+  - Quick navigation
+  - Cross-device bookmark access

bruno/devices/koreader/scenarios/Sync Progress - With Highlights and Notes.yml

@@ -1,19 +1,117 @@
-docs: "## Sync Progress with Highlights and Notes\n\nSynchronizes reading progress with separate highlights and notes arrays.\n\n**Method:** POST\n\n**Endpoint:** /api/sync/koreader/progress\n\n**Authentication:** Bearer token\n\n**Request Body:**\n- `library_id` (string, optional): Library UUID\n- `books` (array): Books with progress and annotations\n  - `uuid`, `title`, `authors`, `progress`, `percentage`, `last_read`\n  - `highlights` (array): Text highlights\n    - `datetime` (string): Creation timestamp\n    - `text` (string): Highlighted text content\n    - `chapter` (integer): Chapter number\n    - `pos0` (string): EPUB CFI start\n    - `pos1` (string): EPUB CFI end\n    - `page_start` (integer): Start page\n    - `page_end` (integer): End page\n    - `color` (string, optional): Highlight color\n  - `notes` (array): Notes\n    - `datetime` (string): Creation timestamp\n    - `text` (string): Note content\n    - `chapter` (integer): Chapter number\n    - `pos0` (string, optional):\
-  \ Related position\n\n**Response:**\n- `progress_synced` (boolean): Progress sync status\n- `highlights_synced` (integer): Highlights synced\n- `notes_synced` (integer): Notes synced\n- `conflicts_resolved` (integer): Conflict count\n- `timestamp` (string): Sync timestamp\n\n**KOReader Annotation Model:**\n- **Separate arrays**: Highlights and notes stored separately\n- **Linked**: Notes can reference highlights\n- **Rich metadata**: Timestamps, positions, page numbers\n- **Flexible**: Supports complex annotations\n\n**Highlight Features:**\n- Multi-color highlighting (via plugins)\n- Precise text selection with EPUB CFI\n- Page range tracking\n- Chapter references\n- Timestamps for sorting\n- Full text preserved\n\n**Note Features:**\n- Free-form text notes\n- Can be standalone or attached\n- Chapter-based organization\n- Timestamped\n- Longer form than highlights\n- Support for markdown (some versions)\n\n**Color Support (via plugins):**\n- Yellow: Default highlight\n- Green: Important\
-  \ passages\n- Blue: Key concepts\n- Red: Critical information\n- Orange: Interesting quotes\n- Custom colors available\n\n**Sync Advantages:**\n- Separation allows granular control\n- Highlights sync without notes\n- Notes sync independently\n- Better conflict resolution\n- Efficient for large annotation sets\n\n**Use Cases:**\n- Academic research\n- Study groups\n- Content analysis\n- Personal knowledge management\n- Sharing insights"
-http:
-  body:
-    type: json
-    data: "{\n  \"books\": [\n    {\n      \"authors\": [\n        \"Author Name\"\n      ],\n      \"highlights\": [\n        {\n          \"chapter\": 4,\n          \"datetime\": \"2026-01-30T19:50:00Z\",\n          \"page_end\": 79,\n          \"page_start\": 78,\n          \"pos0\": \"epubcfi(/6/4/2:20)\",\n          \"pos1\": \"epubcfi(/6/4/2:30)\",\n          \"text\": \"Important passage\"\n        }\n      ],\n      \"last_read\": \"2026-01-30T20:00:00Z\",\n      \"notes\": [\n        {\n          \"chapter\": 4,\n          \"datetime\": \"2026-01-30T19:52:00Z\",\n          \"text\": \"My note about this chapter\"\n        }\n      ],\n      \"percentage\": 0.6,\n      \"progress\": 0.6,\n      \"title\": \"Book Title\",\n      \"uuid\": \"{{media_item_id}}\"\n    }\n  ],\n  \"library_id\": \"optional-library-uuid\"\n}"
-  headers:
-  - key: Content-Type
-    value: application/json
-  method: POST
-  url: '{{base_url}}/api/sync/koreader/progress'
-  auth:
-    type: bearer
-    token: '{{koreader_device_token}}'
 info:
   name: Sync Progress - With Highlights and Notes
-  seq: 4
   type: http
+  seq: 4
+
+http:
+  method: POST
+  url: '{{base_url}}/api/sync/koreader/progress'
+  auth: inherit
+  headers:
+    - key: Content-Type
+      value: application/json
+  body:
+    type: json
+    json:
+      library_id: optional-library-uuid
+      books:
+        - uuid: book-uuid-here
+          title: Book Title
+          authors:
+            - Author Name
+          progress: 0.6
+          percentage: 0.6
+          last_read: '2026-01-30T20:00:00Z'
+          highlights:
+            - datetime: '2026-01-30T19:50:00Z'
+              text: Important passage
+              chapter: 4
+              pos0: 'epubcfi(/6/4/2:20)'
+              pos1: 'epubcfi(/6/4/2:30)'
+              page_start: 78
+              page_end: 79
+          notes:
+            - datetime: '2026-01-30T19:52:00Z'
+              text: My note about this chapter
+              chapter: 4
+
+docs: |-
+  ## Sync Progress with Highlights and Notes
+
+  Synchronizes reading progress with separate highlights and notes arrays.
+
+  **Method:** POST
+
+  **Endpoint:** /api/sync/koreader/progress
+
+  **Authentication:** Bearer token
+
+  **Request Body:**
+  - `library_id` (string, optional): Library UUID
+  - `books` (array): Books with progress and annotations
+    - `uuid`, `title`, `authors`, `progress`, `percentage`, `last_read`
+    - `highlights` (array): Text highlights
+      - `datetime` (string): Creation timestamp
+      - `text` (string): Highlighted text content
+      - `chapter` (integer): Chapter number
+      - `pos0` (string): EPUB CFI start
+      - `pos1` (string): EPUB CFI end
+      - `page_start` (integer): Start page
+      - `page_end` (integer): End page
+      - `color` (string, optional): Highlight color
+    - `notes` (array): Notes
+      - `datetime` (string): Creation timestamp
+      - `text` (string): Note content
+      - `chapter` (integer): Chapter number
+      - `pos0` (string, optional): Related position
+
+  **Response:**
+  - `progress_synced` (boolean): Progress sync status
+  - `highlights_synced` (integer): Highlights synced
+  - `notes_synced` (integer): Notes synced
+  - `conflicts_resolved` (integer): Conflict count
+  - `timestamp` (string): Sync timestamp
+
+  **KOReader Annotation Model:**
+  - **Separate arrays**: Highlights and notes stored separately
+  - **Linked**: Notes can reference highlights
+  - **Rich metadata**: Timestamps, positions, page numbers
+  - **Flexible**: Supports complex annotations
+
+  **Highlight Features:**
+  - Multi-color highlighting (via plugins)
+  - Precise text selection with EPUB CFI
+  - Page range tracking
+  - Chapter references
+  - Timestamps for sorting
+  - Full text preserved
+
+  **Note Features:**
+  - Free-form text notes
+  - Can be standalone or attached
+  - Chapter-based organization
+  - Timestamped
+  - Longer form than highlights
+  - Support for markdown (some versions)
+
+  **Color Support (via plugins):**
+  - Yellow: Default highlight
+  - Green: Important passages
+  - Blue: Key concepts
+  - Red: Critical information
+  - Orange: Interesting quotes
+  - Custom colors available
+
+  **Sync Advantages:**
+  - Separation allows granular control
+  - Highlights sync without notes
+  - Notes sync independently
+  - Better conflict resolution
+  - Efficient for large annotation sets
+
+  **Use Cases:**
+  - Academic research
+  - Study groups
+  - Content analysis
+  - Personal knowledge management
+  - Sharing insights

bruno/devices/koreader/scenarios/Sync Progress.yml

@@ -1,16 +1,53 @@
-docs: "## KOReader Sync Progress\n\n  Synchronizes reading progress from a KOReader device to the Bookhoard server.\n\n  **Method:** POST\n\n  **Endpoint:** /api/sync/koreader/progress\n\n  **Authentication:** Bearer token (device token)\n\n  **Request Body:**\n  - `library_id` (string, optional): Library UUID\n  - `books` (array): Array of book progress objects\n    - `uuid` (string): Book UUID\n    - `title` (string): Book title\n    - `authors` (array): List of authors\n    - `progress` (number): Progress value\n    - `percentage` (number): Percentage complete (0-1)\n    - `last_read` (string): ISO 8601 timestamp\n    - `chapter` (number): Current chapter\n    - `epubcfi` (string): EPUB Canonical Fragment Identifier\n    - `page` (number): Current page\n    - `total_pages` (number): Total pages\n  - `sync_mode` (string): Sync mode (immediate, deferred)\n  - `device_info` (object): Device information\n    - `koreader_version` (string): KOReader version\n    - `device_model` (string): Device\
-  \ model identifier\n\n  **Response:**\n  - `sync_status` (string): Sync status (accepted, processing)\n  - `books_synced` (number): Number of books synced\n\n  **Status Codes:**\n  - 202: Accepted - sync queued\n  - 401: Unauthorized\n  - 500: Internal server error"
-http:
-  body:
-    type: json
-    data: "{\n  \"sync_mode\": \"immediate\",\n  \"books\": [\n    {\n      \"uuid\": \"{{media_item_id}}\",\n      \"percentage\": 0.45,\n      \"chapter\": 3\n    }\n  ]\n}"
-  headers: []
-  method: POST
-  url: '{{base_url}}/api/sync/koreader/progress'
-  auth:
-    type: bearer
-    token: '{{koreader_device_token}}'
 info:
   name: KOReader Sync Progress
-  seq: 1
   type: http
+  seq: 1
+http:
+  method: POST
+  url: '{{base_url}}/api/sync/koreader/progress'
+  auth: inherit
+  body:
+    type: json
+    jsonBody: "{\n    \"library_id\": null,\n    \"books\": [\n      {\n        \"\
+      uuid\": \"{{book_uuid"
+  headers:
+  - key: Authorization
+    value: Bearer {{device_token
+
+docs: |-
+  ## KOReader Sync Progress
+  
+    Synchronizes reading progress from a KOReader device to the Bookhoard server.
+  
+    **Method:** POST
+  
+    **Endpoint:** /api/sync/koreader/progress
+  
+    **Authentication:** Bearer token (device token)
+  
+    **Request Body:**
+    - `library_id` (string, optional): Library UUID
+    - `books` (array): Array of book progress objects
+      - `uuid` (string): Book UUID
+      - `title` (string): Book title
+      - `authors` (array): List of authors
+      - `progress` (number): Progress value
+      - `percentage` (number): Percentage complete (0-1)
+      - `last_read` (string): ISO 8601 timestamp
+      - `chapter` (number): Current chapter
+      - `epubcfi` (string): EPUB Canonical Fragment Identifier
+      - `page` (number): Current page
+      - `total_pages` (number): Total pages
+    - `sync_mode` (string): Sync mode (immediate, deferred)
+    - `device_info` (object): Device information
+      - `koreader_version` (string): KOReader version
+      - `device_model` (string): Device model identifier
+  
+    **Response:**
+    - `sync_status` (string): Sync status (accepted, processing)
+    - `books_synced` (number): Number of books synced
+  
+    **Status Codes:**
+    - 202: Accepted - sync queued
+    - 401: Unauthorized
+    - 500: Internal server error

bruno/devices/scenarios/Add Books to Kobo Shelf.yml

@@ -8,8 +8,16 @@ http:
   auth: inherit
   body:
     type: json
-    data: "{\n    \"media_item_ids\": [\n      \"{{bookUUID1"
+    jsonBody: "{\n    \"media_item_ids\": [\n      \"{{bookUUID1"
   headers:
   - key: Authorization
     value: Bearer {{userToken
-docs: "## Add Books to Kobo Shelf\n\n  Add one or more books to a Kobo device shelf. Manages which books should be synced to a specific Kobo device. Supports multiple shelves for organization.\n\n  **Method:** POST\n\n  **Endpoint:** /api/devices/{deviceID"
+
+docs: |-
+  ## Add Books to Kobo Shelf
+  
+    Add one or more books to a Kobo device shelf. Manages which books should be synced to a specific Kobo device. Supports multiple shelves for organization.
+  
+    **Method:** POST
+  
+    **Endpoint:** /api/devices/{deviceID

bruno/devices/scenarios/Check Pending Registration.yml

@@ -2,15 +2,51 @@ info:
   name: Check Pending Registration
   type: http
   seq: 4
+
 http:
   method: POST
   url: '{{base_url}}/api/devices/register/status'
   auth: none
   headers:
-  - key: Content-Type
-    value: application/json
+    - key: Content-Type
+      value: application/json
   body:
     type: json
-    data: "{\n  \"registration_id\": \"registration-uuid-here\"\n}"
-docs: "## Check Registration Status\n\nChecks the current status of a device registration request.\n\n**Method:** POST\n\n**Endpoint:** /api/devices/register/status\n\n**Authentication:** None\n\n**Request Body:**\n- `registration_id` (string): UUID received from registration request\n\n**Response:**\n- `registration_id` (string): The registration UUID\n- `status` (string): Current status\n  - `pending`: Awaiting user approval\n  - `approved`: Registration approved, device ready\n  - `rejected`: Registration rejected by user\n  - `expired`: Registration expired (not approved in time)\n- `device_name` (string): Name of the device\n- `device_type` (string): Type of device\n- `created_at` (string): Registration timestamp\n- `updated_at` (string): Last status update timestamp\n\n**Status Codes:**\n- 200: Status retrieved successfully\n- 404: Registration ID not found\n- 400: Invalid registration ID format\n\n**Polling Recommendations:**\n- Poll every 5-10 seconds while status is `pending`\n\
-  - Stop polling when status changes to `approved`, `rejected`, or `expired`\n- Use exponential backoff for mobile devices to save battery"
+    json:
+      registration_id: registration-uuid-here
+
+docs: |-
+  ## Check Registration Status
+
+  Checks the current status of a device registration request.
+
+  **Method:** POST
+
+  **Endpoint:** /api/devices/register/status
+
+  **Authentication:** None
+
+  **Request Body:**
+  - `registration_id` (string): UUID received from registration request
+
+  **Response:**
+  - `registration_id` (string): The registration UUID
+  - `status` (string): Current status
+    - `pending`: Awaiting user approval
+    - `approved`: Registration approved, device ready
+    - `rejected`: Registration rejected by user
+    - `expired`: Registration expired (not approved in time)
+  - `device_name` (string): Name of the device
+  - `device_type` (string): Type of device
+  - `created_at` (string): Registration timestamp
+  - `updated_at` (string): Last status update timestamp
+
+  **Status Codes:**
+  - 200: Status retrieved successfully
+  - 404: Registration ID not found
+  - 400: Invalid registration ID format
+
+  **Polling Recommendations:**
+  - Poll every 5-10 seconds while status is `pending`
+  - Stop polling when status changes to `approved`, `rejected`, or `expired`
+  - Use exponential backoff for mobile devices to save battery

bruno/devices/scenarios/Check Registration Status.yml

@@ -8,5 +8,30 @@ http:
   auth: none
   body:
     type: json
-    data: "{\n    \"registration_id\": \"{{registrationId}}"
-docs: "## Check Registration Status\n\n  Checks the current status of a device registration request.\n\n  **Method:** POST\n\n  **Endpoint:** /api/devices/register/status\n\n  **Authentication:** None\n\n  **Request Body:**\n  - `registration_id` (string, required): Registration request ID\n\n  **Response:**\n  - `status` (string): Registration status (pending, approved, rejected, expired)\n  - `device_name` (string): Device name\n  - `device_type` (string): Device type\n  - `created_at` (string): Request timestamp\n  - `expires_at` (string): Expiration timestamp\n\n  **Status Codes:**\n  - 200: Success\n  - 404: Registration ID not found\n  - 410: Registration expired"
+    jsonBody: "{\n    \"registration_id\": \"{{registrationId}}"
+
+docs: |-
+  ## Check Registration Status
+  
+    Checks the current status of a device registration request.
+  
+    **Method:** POST
+  
+    **Endpoint:** /api/devices/register/status
+  
+    **Authentication:** None
+  
+    **Request Body:**
+    - `registration_id` (string, required): Registration request ID
+  
+    **Response:**
+    - `status` (string): Registration status (pending, approved, rejected, expired)
+    - `device_name` (string): Device name
+    - `device_type` (string): Device type
+    - `created_at` (string): Request timestamp
+    - `expires_at` (string): Expiration timestamp
+  
+    **Status Codes:**
+    - 200: Success
+    - 404: Registration ID not found
+    - 410: Registration expired

bruno/devices/scenarios/Create Device File Alias.yml

@@ -8,12 +8,48 @@ http:
   auth: inherit
   body:
     type: json
-    data: "{\n    \"file_path\": \"/mnt/sd/books/my-book.kepub.epub\",\n    \"media_item_id\": \"{{media_item_id"
+    jsonBody: "{\n    \"file_path\": \"/mnt/sd/books/my-book.kepub.epub\",\n    \"\
+      media_item_id\": \"{{media_item_id"
   headers:
   - key: Content-Type
     value: application/json
 runtime:
   scripts:
   - type: tests
-    code: "test_create_device_file_alias_success(status, headers, body) {\n    if (status !== 201 && status !== 200) {\n      throw new Error(\"Expected status 201 or 200, got \" + status);"
-docs: "## Create Device File Alias\n\n  Creates a new file alias for a device. File aliases map device-specific file paths to media items.\n\n  **Method:** POST\n\n  **Endpoint:** /api/devices/:id/file-aliases\n\n  **Authentication:** Required (Bearer token)\n\n  **Path Parameters:**\n  - `id` (string, required): Device UUID\n\n  **Request Body:**\n  - `file_path` (string, required): Device-specific file path\n  - `media_item_id` (string, required): Media item UUID to link to\n\n  **Response:** Created file alias object\n  - `id` (string): Alias UUID\n  - `device_id` (string): Device UUID\n  - `file_path` (string): Device-specific file path\n  - `media_item_id` (string): Associated media item UUID\n  - `created_at` (string): Creation timestamp\n  - `updated_at` (string): Last update timestamp\n\n  **Status Codes:**\n  - 201: Created\n  - 200: Success\n  - 400: Invalid request body\n  - 401: Unauthorized\n  - 404: Device not found\n  - 500: Internal server error"
+    code: "test_create_device_file_alias_success(status, headers, body) {\n    if\
+      \ (status !== 201 && status !== 200) {\n      throw new Error(\"Expected status\
+      \ 201 or 200, got \" + status);"
+
+docs: |-
+  ## Create Device File Alias
+  
+    Creates a new file alias for a device. File aliases map device-specific file paths to media items.
+  
+    **Method:** POST
+  
+    **Endpoint:** /api/devices/:id/file-aliases
+  
+    **Authentication:** Required (Bearer token)
+  
+    **Path Parameters:**
+    - `id` (string, required): Device UUID
+  
+    **Request Body:**
+    - `file_path` (string, required): Device-specific file path
+    - `media_item_id` (string, required): Media item UUID to link to
+  
+    **Response:** Created file alias object
+    - `id` (string): Alias UUID
+    - `device_id` (string): Device UUID
+    - `file_path` (string): Device-specific file path
+    - `media_item_id` (string): Associated media item UUID
+    - `created_at` (string): Creation timestamp
+    - `updated_at` (string): Last update timestamp
+  
+    **Status Codes:**
+    - 201: Created
+    - 200: Success
+    - 400: Invalid request body
+    - 401: Unauthorized
+    - 404: Device not found
+    - 500: Internal server error

bruno/devices/scenarios/Disable Device Sync.yml

@@ -2,77 +2,57 @@ info:
   name: Disable Device Sync
   type: http
   seq: 8
+
 http:
   method: PUT
   url: '{{base_url}}/api/devices/{{device_id}}'
   auth: inherit
   headers:
-  - key: Content-Type
-    value: application/json
+    - key: Content-Type
+      value: application/json
   body:
     type: json
-    data: "{\n  \"device_name\": \"My Kobo Clara\",\n  \"sync_enabled\": false,\n  \"auto_sync\": false,\n  \"sync_frequency_minutes\": 30\n}"
-docs: '## Disable Device Sync
+    json:
+      device_name: My Kobo Clara
+      sync_enabled: false
+      auto_sync: false
+      sync_frequency_minutes: 30
 
+docs: |-
+  ## Disable Device Sync
 
   Disables synchronization for a specific device.
 
-
   **Method:** PUT
 
-
   **Endpoint:** /api/devices/:device_id
 
-
   **Authentication:** Required (Bearer token)
 
-
   **Path Parameters:**
-
   - `device_id` (string): UUID of the device
 
-
   **Request Body:**
-
   - `device_name` (string, optional): Device name
-
   - `sync_enabled` (boolean): Must be `false`
-
   - `auto_sync` (boolean): Should be `false`
-
   - `sync_frequency_minutes` (integer, optional): Any value (sync disabled)
 
-
   **Response:**
-
   - `id` (string): Device UUID
-
   - `device_name` (string): Device name
-
   - `sync_enabled` (boolean): `false`
-
   - `auto_sync` (boolean): `false`
-
   - `message` (string): Confirmation message
 
-
   **Status Codes:**
-
   - 200: Sync disabled successfully
-
   - 401: Unauthorized
-
   - 403: Forbidden
-
   - 404: Device not found
 
-
   **Use Cases:**
-
   - Temporarily disable sync for troubleshooting
-
   - Stop sync for a lost or stolen device
-
   - Disable sync before selling or giving away device
-
-  - Prevent data usage on limited connections'
+  - Prevent data usage on limited connections

bruno/devices/scenarios/Initiate Device Registration.yml

@@ -8,5 +8,32 @@ http:
   auth: none
   body:
     type: json
-    data: "{\n    \"device_name\": \"My Kindle Paperwhite\",\n    \"device_type\": \"koreader\",\n    \"device_identifier\": \"kindle-pw5-hardware-id-12345\""
-docs: "## Initiate Device Registration\n\n  Initiates a new device registration request that requires admin approval.\n\n  **Method:** POST\n\n  **Endpoint:** /api/devices/register\n\n  **Authentication:** None (open endpoint)\n\n  **Request Body:**\n  - `device_name` (string, required): Human-readable device name (max 100 chars)\n  - `device_type` (string, required): Device type (kobo, koreader, kindle, etc.)\n  - `device_identifier` (string, required): Unique hardware ID (max 200 chars)\n\n  **Response:**\n  - `registration_id` (string): Unique registration request ID\n  - `status` (string): Initial status (pending)\n  - `expires_at` (string): Expiration timestamp (usually 24 hours)\n  - `message` (string): Informational message\n\n  **Status Codes:**\n  - 201: Registration initiated\n  - 400: Invalid request\n  - 409: Device already registered"
+    jsonBody: "{\n    \"device_name\": \"My Kindle Paperwhite\",\n    \"device_type\"\
+      : \"koreader\",\n    \"device_identifier\": \"kindle-pw5-hardware-id-12345\""
+
+docs: |-
+  ## Initiate Device Registration
+  
+    Initiates a new device registration request that requires admin approval.
+  
+    **Method:** POST
+  
+    **Endpoint:** /api/devices/register
+  
+    **Authentication:** None (open endpoint)
+  
+    **Request Body:**
+    - `device_name` (string, required): Human-readable device name (max 100 chars)
+    - `device_type` (string, required): Device type (kobo, koreader, kindle, etc.)
+    - `device_identifier` (string, required): Unique hardware ID (max 200 chars)
+  
+    **Response:**
+    - `registration_id` (string): Unique registration request ID
+    - `status` (string): Initial status (pending)
+    - `expires_at` (string): Expiration timestamp (usually 24 hours)
+    - `message` (string): Informational message
+  
+    **Status Codes:**
+    - 201: Registration initiated
+    - 400: Invalid request
+    - 409: Device already registered

bruno/devices/scenarios/Register Device.yml

@@ -2,62 +2,48 @@ info:
   name: Register Device
   type: http
   seq: 1
+
 http:
   method: POST
   url: '{{base_url}}/api/devices/register'
   auth: none
   headers:
-  - key: Content-Type
-    value: application/json
+    - key: Content-Type
+      value: application/json
   body:
     type: json
-    data: "{\n  \"device_name\": \"My Kobo Clara\",\n  \"device_type\": \"kobo\",\n  \"device_identifier\": \"N1234567890123\"\n}"
-docs: '## Register Device
+    json:
+      device_name: My Kobo Clara
+      device_type: kobo
+      device_identifier: N1234567890123
 
+docs: |-
+  ## Register Device
 
   Initiates device registration by sending device information to the server.
 
-
   **Method:** POST
 
-
   **Endpoint:** /api/devices/register
 
-
   **Authentication:** None (public endpoint)
 
-
   **Request Body:**
-
   - `device_name` (string): Human-readable name for the device
-
   - `device_type` (string): Type of device - `kobo`, `koreader`, or `web`
-
   - `device_identifier` (string): Unique device identifier (serial number or other ID)
 
-
   **Response:**
-
   - `registration_id` (string): UUID for tracking registration status
-
   - `status` (string): Registration status - `pending`, `approved`, or `rejected`
-
   - `message` (string): Status message
 
-
   **Status Codes:**
-
   - 201: Registration initiated successfully
-
   - 400: Invalid request data
-
   - 409: Device already registered
 
-
   **Notes:**
-
   - Device registration requires user approval before activation
-
   - Registration ID should be stored for status checking
-
-  - Device identifier must be unique per device'
+  - Device identifier must be unique per device

bruno/devices/scenarios/Register KOReader Device.yml

@@ -2,60 +2,47 @@ info:
   name: Register KOReader Device
   type: http
   seq: 2
+
 http:
   method: POST
   url: '{{base_url}}/api/devices/register'
   auth: none
   headers:
-  - key: Content-Type
-    value: application/json
+    - key: Content-Type
+      value: application/json
   body:
     type: json
-    data: "{\n  \"device_name\": \"My Kindle Paperwhite\",\n  \"device_type\": \"koreader\",\n  \"device_identifier\": \"G090GP123456789\"\n}"
-docs: '## Register KOReader Device
+    json:
+      device_name: My Kindle Paperwhite
+      device_type: koreader
+      device_identifier: G090GP123456789
 
+docs: |-
+  ## Register KOReader Device
 
   Registers a KOReader device (typically Kindle devices running KOReader software).
 
-
   **Method:** POST
 
-
   **Endpoint:** /api/devices/register
 
-
   **Authentication:** None (public endpoint)
 
-
   **Request Body:**
-
   - `device_name` (string): Human-readable name for the device
-
   - `device_type` (string): Must be `koreader`
-
   - `device_identifier` (string): Kindle serial number or unique device ID
 
-
   **Response:**
-
   - `registration_id` (string): UUID for tracking registration status
-
   - `status` (string): Registration status - `pending`
-
   - `message` (string): Confirmation message
 
-
   **Status Codes:**
-
   - 201: Registration initiated
-
   - 400: Invalid device type or data
 
-
   **KOReader Notes:**
-
   - KOReader runs on Kindle, Kobo, PocketBook, and Android devices
-
   - Device identifier is typically the device serial number
-
-  - Supports bookmarks, progress, highlights, and annotations sync'
+  - Supports bookmarks, progress, highlights, and annotations sync

bruno/devices/scenarios/Register Web Device.yml

@@ -2,62 +2,48 @@ info:
   name: Register Web Device
   type: http
   seq: 3
+
 http:
   method: POST
   url: '{{base_url}}/api/devices/register'
   auth: none
   headers:
-  - key: Content-Type
-    value: application/json
+    - key: Content-Type
+      value: application/json
   body:
     type: json
-    data: "{\n  \"device_name\": \"Chrome Browser\",\n  \"device_type\": \"web\",\n  \"device_identifier\": \"web-client-abc123\"\n}"
-docs: '## Register Web Device
+    json:
+      device_name: Chrome Browser
+      device_type: web
+      device_identifier: web-client-abc123
 
+docs: |-
+  ## Register Web Device
 
   Registers a web browser client for reading progress sync.
 
-
   **Method:** POST
 
-
   **Endpoint:** /api/devices/register
 
-
   **Authentication:** None (public endpoint)
 
-
   **Request Body:**
-
   - `device_name` (string): Browser identification (e.g., "Chrome Browser")
-
   - `device_type` (string): Must be `web`
-
   - `device_identifier` (string): Unique browser/client identifier
 
-
   **Response:**
-
   - `registration_id` (string): UUID for tracking
-
   - `status` (string): `pending` or `auto-approved`
-
   - `message` (string): Status message
 
-
   **Status Codes:**
-
   - 201: Registration successful
-
   - 400: Invalid request
 
-
   **Web Device Notes:**
-
   - Web devices use localStorage for device identification
-
   - May be auto-approved without admin intervention
-
   - Used for browser-based reading progress tracking
-
-  - Supports manual progress updates, highlights, and notes'
+  - Supports manual progress updates, highlights, and notes

bruno/devices/scenarios/Update Device Settings.yml

@@ -2,83 +2,60 @@ info:
   name: Update Device Settings
   type: http
   seq: 7
+
 http:
   method: PUT
   url: '{{base_url}}/api/devices/{{device_id}}'
   auth: inherit
   headers:
-  - key: Content-Type
-    value: application/json
+    - key: Content-Type
+      value: application/json
   body:
     type: json
-    data: "{\n  \"device_name\": \"Updated Device Name\",\n  \"sync_enabled\": true,\n  \"auto_sync\": true,\n  \"sync_frequency_minutes\": 10\n}"
-docs: '## Update Device Settings
+    json:
+      device_name: Updated Device Name
+      sync_enabled: true
+      auto_sync: true
+      sync_frequency_minutes: 10
 
+docs: |-
+  ## Update Device Settings
 
   Updates device configuration and sync settings.
 
-
   **Method:** PUT
 
-
   **Endpoint:** /api/devices/:device_id
 
-
   **Authentication:** Required (Bearer token)
 
-
   **Path Parameters:**
-
   - `device_id` (string): UUID of the device
 
-
   **Request Body:**
-
   - `device_name` (string, optional): New device name
-
   - `sync_enabled` (boolean, optional): Enable/disable sync
-
   - `auto_sync` (boolean, optional): Enable automatic sync
-
   - `sync_frequency_minutes` (integer, optional): Sync interval (5-1440 minutes)
 
-
   **Response:**
-
   - `id` (string): Device UUID
-
   - `device_name` (string): Updated device name
-
   - `sync_enabled` (boolean): Updated sync status
-
   - `auto_sync` (boolean): Updated auto-sync setting
-
   - `sync_frequency_minutes` (integer): Updated sync interval
-
   - `updated_at` (string): Update timestamp
 
-
   **Status Codes:**
-
   - 200: Settings updated successfully
-
   - 400: Invalid sync frequency or data
-
   - 401: Unauthorized
-
   - 403: Forbidden (device belongs to different user)
-
   - 404: Device not found
 
-
   **Sync Frequency Guidelines:**
-
   - Mobile devices: 10-30 minutes
-
   - E-readers on WiFi: 15-60 minutes
-
   - Web clients: 5-15 minutes
-
   - Minimum: 5 minutes
-
-  - Maximum: 1440 minutes (24 hours)'
+  - Maximum: 1440 minutes (24 hours)

bruno/devices/scenarios/Update Device.yml

@@ -8,5 +8,35 @@ http:
   auth: inherit
   body:
     type: json
-    data: "{\n    \"device_name\": \"My Updated Kindle\",\n    \"sync_enabled\": true,\n    \"auto_sync\": true,\n    \"sync_frequency_minutes\": 10"
-docs: "## Update Device\n\n  Updates device settings and synchronization preferences.\n\n  **Method:** PUT\n\n  **Endpoint:** /api/devices/{device_id}\n\n  **Authentication:** Required (Bearer token, admin or device owner)\n\n  **Path Parameters:**\n  - `device_id` (string): Device ID\n\n  **Request Body:**\n  - `device_name` (string, optional): New device name (max 100 chars)\n  - `sync_enabled` (boolean, optional): Enable/disable synchronization\n  - `auto_sync` (boolean, optional): Enable automatic synchronization\n  - `sync_frequency_minutes` (integer, optional): Sync frequency in minutes (5-1440)\n\n  **Response:**\n  - Updated device object\n\n  **Status Codes:**\n  - 200: Success\n  - 400: Invalid request\n  - 401: Unauthorized\n  - 403: Forbidden (not device owner)\n  - 404: Device not found"
+    jsonBody: "{\n    \"device_name\": \"My Updated Kindle\",\n    \"sync_enabled\"\
+      : true,\n    \"auto_sync\": true,\n    \"sync_frequency_minutes\": 10"
+
+docs: |-
+  ## Update Device
+  
+    Updates device settings and synchronization preferences.
+  
+    **Method:** PUT
+  
+    **Endpoint:** /api/devices/{device_id}
+  
+    **Authentication:** Required (Bearer token, admin or device owner)
+  
+    **Path Parameters:**
+    - `device_id` (string): Device ID
+  
+    **Request Body:**
+    - `device_name` (string, optional): New device name (max 100 chars)
+    - `sync_enabled` (boolean, optional): Enable/disable synchronization
+    - `auto_sync` (boolean, optional): Enable automatic synchronization
+    - `sync_frequency_minutes` (integer, optional): Sync frequency in minutes (5-1440)
+  
+    **Response:**
+    - Updated device object
+  
+    **Status Codes:**
+    - 200: Success
+    - 400: Invalid request
+    - 401: Unauthorized
+    - 403: Forbidden (not device owner)
+    - 404: Device not found

bruno/devices/scenarios/Update Sync Frequency.yml

@@ -2,92 +2,65 @@ info:
   name: Update Sync Frequency
   type: http
   seq: 9
+
 http:
   method: PUT
   url: '{{base_url}}/api/devices/{{device_id}}'
   auth: inherit
   headers:
-  - key: Content-Type
-    value: application/json
+    - key: Content-Type
+      value: application/json
   body:
     type: json
-    data: "{\n  \"device_name\": \"My Kobo Clara\",\n  \"sync_enabled\": true,\n  \"auto_sync\": true,\n  \"sync_frequency_minutes\": 15\n}"
-docs: '## Update Sync Frequency
+    json:
+      device_name: My Kobo Clara
+      sync_enabled: true
+      auto_sync: true
+      sync_frequency_minutes: 15
 
+docs: |-
+  ## Update Sync Frequency
 
   Changes how often the device automatically syncs with the server.
 
-
   **Method:** PUT
 
-
   **Endpoint:** /api/devices/:device_id
 
-
   **Authentication:** Required (Bearer token)
 
-
   **Path Parameters:**
-
   - `device_id` (string): UUID of the device
 
-
   **Request Body:**
-
   - `device_name` (string, optional): Device name
-
   - `sync_enabled` (boolean): Must be `true` for auto-sync
-
   - `auto_sync` (boolean): Must be `true`
-
   - `sync_frequency_minutes` (integer): New sync interval (5-1440)
 
-
   **Response:**
-
   - `id` (string): Device UUID
-
   - `sync_enabled` (boolean): `true`
-
   - `auto_sync` (boolean): `true`
-
   - `sync_frequency_minutes` (integer): Updated interval
-
   - `next_sync_at` (string): Estimated next sync time
-
   - `updated_at` (string): Update timestamp
 
-
   **Status Codes:**
-
   - 200: Frequency updated successfully
-
   - 400: Invalid frequency value
-
   - 401: Unauthorized
-
   - 403: Forbidden
-
   - 404: Device not found
 
-
   **Recommended Frequencies:**
-
   - **Active reading:** 5-10 minutes
-
   - **Normal usage:** 15-30 minutes
-
   - **Occasional reading:** 30-60 minutes
-
   - **Battery saving:** 60+ minutes
-
   - **WiFi only (3G):** 30-60 minutes
 
-
   **Notes:**
-
   - More frequent sync = more battery usage
-
   - Sync only occurs when device is online
-
-  - Manual sync can be triggered anytime regardless of frequency'
+  - Manual sync can be triggered anytime regardless of frequency

bruno/environments/Bookhoard.yml

@@ -23,7 +23,7 @@ variables:
   - name: library_folder
     value: /app/uploads
   - name: opds_base_url
-    value: http://localhost:8765/opds
+    value: ""
   - secret: true
     name: token
   - secret: true
@@ -40,7 +40,3 @@ variables:
     name: comic_library_id
   - secret: true
     name: manga_library_id
-  - secret: true
-    name: book_sha256
-  - secret: true
-    name: book_uuid