docs: finalize hacking guidelines

Signed-off-by: NotAShelf <raf@notashelf.dev>
Change-Id: I2d3a5a9d745630f5da305664f0bdc66e6a6a6964

.editorconfig

@@ -0,0 +1,32 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.rs]
+indent_style = space
+indent_size = 2
+
+[justfile]
+indent_style = space
+indent_size = 2
+
+[*.toml]
+indent_style = space
+indent_size = 2
+
+[*.md]
+indent_style = space
+indent_size = 2
+trim_trailing_whitespace = false
+
+[*.nix]
+indent_style = space
+indent_size = 2
+
+[*.scss]
+indent_style = space
+indent_size = 2

Cargo.toml

@@ -1,5 +1,5 @@
 [workspace]
-members = ["crates/*", "xtask"]
+members = ["crates/*", "packages/*", "xtask"]
 exclude = ["crates/pinakes-core/tests/fixtures/test-plugin"]
 resolver = "3"
 
@@ -11,35 +11,44 @@ readme = true
 rust-version = "1.95.0" # follows nightly Rust
 
 [workspace.dependencies]
-# Crate components for Pinakes.
+# Crate components for Pinakes. Those are the internal dependencies that are built
+# while building any package.
 pinakes-core = { path = "./crates/pinakes-core" }
-pinakes-server = { path = "./crates/pinakes-server" }
 pinakes-plugin-api = { path = "./crates/pinakes-plugin-api" }
-pinakes-ui = { path = "./crates/pinakes-ui" }
-pinakes-tui = { path = "./crates/pinakes-tui" }
 
-tokio = { version = "1.49.0", features = ["full"] }
+# Pinakes itself is a REST API server. UI and TUI are official visual components
+# that connect to the server. Using the API documentation, the user can write
+# their own clients, but we separate "crates" and "packages" to establish the
+# distinction properly.
+pinakes-server = { path = "./packages/pinakes-server" }
+pinakes-ui = { path = "./packages/pinakes-ui" }
+pinakes-tui = { path = "./packages/pinakes-tui" }
+
+# Other dependencies. Declaring them in the virtual manifests lets use reuse the crates
+# without having to track individual crate version across different types of crates. This
+# also includes *dev* dependencies.
+tokio = { version = "1.50.0", features = ["full"] }
 tokio-util = { version = "0.7.18", features = ["rt"] }
 serde = { version = "1.0.228", features = ["derive"] }
 serde_json = "1.0.149"
-toml = "1.0.3"
-clap = { version = "4.5.60", features = ["derive", "env"] }
+toml = "1.0.7"
+clap = { version = "4.6.0", features = ["derive", "env"] }
 chrono = { version = "0.4.44", features = ["serde"] }
-uuid = { version = "1.21.0", features = ["v7", "serde"] }
+uuid = { version = "1.22.0", features = ["v7", "serde"] }
 thiserror = "2.0.18"
 anyhow = "1.0.102"
 tracing = "0.1.44"
-tracing-subscriber = { version = "0.3.22", features = ["env-filter", "json"] }
+tracing-subscriber = { version = "0.3.23", features = ["env-filter", "json"] }
 blake3 = "1.8.3"
 rustc-hash = "2.1.1"
-ed25519-dalek = { version = "2.1.1", features = ["std"] }
-lofty = "0.23.2"
-lopdf = "0.39.0"
+ed25519-dalek = { version = "2.2.0", features = ["std"] }
+lofty = "0.23.3"
+lopdf = "0.40.0"
 epub = "2.1.5"
 matroska = "0.30.0"
 gray_matter = "0.3.2"
 kamadak-exif = "0.6.1"
-rusqlite = { version = "=0.37.0", features = ["bundled", "column_decltype"] }
+rusqlite = { version = "0.37.0", features = ["bundled", "column_decltype"] }
 tokio-postgres = { version = "0.7.16", features = [
   "with-uuid-1",
   "with-chrono-0_4",
@@ -52,7 +61,7 @@ native-tls = "0.2.18"
 refinery = { version = "0.9.0", features = ["rusqlite", "tokio-postgres"] }
 walkdir = "2.5.0"
 notify = { version = "8.2.0", features = ["macos_fsevent"] }
-winnow = "0.7.14"
+winnow = "1.0.0"
 axum = { version = "0.8.8", features = ["macros", "multipart"] }
 axum-server = { version = "0.8.0" }
 tower = "0.5.3"
@@ -67,7 +76,7 @@ dioxus = { version = "0.7.3", features = ["desktop", "router"] }
 dioxus-core = { version = "0.7.3" }
 async-trait = "0.1.89"
 futures = "0.3.32"
-image = { version = "0.25.9", default-features = false, features = [
+image = { version = "0.25.10", default-features = false, features = [
   "jpeg",
   "png",
   "webp",
@@ -75,7 +84,7 @@ image = { version = "0.25.9", default-features = false, features = [
   "tiff",
   "bmp",
 ] }
-pulldown-cmark = "0.13.1"
+pulldown-cmark = "0.13.3"
 ammonia = "4.1.2"
 argon2 = { version = "0.5.3", features = ["std"] }
 mime_guess = "2.0.5"
@@ -84,17 +93,18 @@ dioxus-free-icons = { version = "0.10.0", features = ["font-awesome-solid"] }
 rfd = "0.17.2"
 gloo-timers = { version = "0.3.0", features = ["futures"] }
 rand = "0.10.0"
-moka = { version = "0.12.14", features = ["future"] }
+moka = { version = "0.12.15", features = ["future"] }
 urlencoding = "2.1.3"
 image_hasher = "3.1.1"
 percent-encoding = "2.3.2"
 http = "1.4.0"
-wasmtime = { version = "42.0.1", features = ["component-model"] }
-wit-bindgen = "0.53.1"
-tempfile = "3.26.0"
+wasmtime = { version = "43.0.0", features = ["component-model"] }
+wit-bindgen = "0.54.0"
+tempfile = "3.27.0"
 utoipa = { version = "5.4.0", features = ["axum_extras", "uuid", "chrono"] }
 utoipa-axum = { version = "0.2.0" }
 utoipa-swagger-ui = { version = "9.0.2", features = ["axum"] }
+http-body-util = "0.1.3"
 
 # See:
 #  <https://doc.rust-lang.org/rustc/lints/listing/allowed-by-default.html>

HACKING.md

@@ -1,32 +0,0 @@
-# Hacking Pinakes
-
-Pinakes is a lot of things. One of the things it aims to be is _complete_. To be
-complete in features, to be complete in documentation and to be complete in
-hackability. This document covers, very comprehensively, how you may:
-
-- Build Pinakes
-- Develop Pinakes
-- Contribute to Pinakes
-
-for developers as well as:
-
-- Distribute Pinakes
-
-for Pinakes maintainers and packagers.
-
-## Building Pinakes
-
-Pinakes is built with Rust (nightly edition) and various crates. The most
-_notable_ crate among those is Dioxus, which provides its own toolkit. The UI
-for Pinakes is usually _not_ built with the Dioxus CLI but instead with
-`cargo build`. This also applies to distributable build results.
-
-[Direnv]: https://direnv.net
-
-To build Pinakes, simply pick the components you want and build them with
-`cargo build --release --package <component>`. A Nix shell is provided for
-reproducible developer environments and you may obtain all build dependencies by
-simply running `nix develop` or `direnv allow` if you use [Direnv]. Nix is a
-cross-platform build tool and works on most Linux distributions as well as
-Darwin. While distro-specific package managers _might_ work, Nix is the only
-supported one.

crates/pinakes-core/Cargo.toml

@@ -4,6 +4,9 @@ edition.workspace = true
 version.workspace = true
 license.workspace = true
 
+[features]
+ffmpeg-tests = []
+
 [dependencies]
 tokio = { workspace = true }
 serde = { workspace = true }
@@ -43,18 +46,13 @@ moka = { workspace = true }
 urlencoding = { workspace = true }
 image_hasher = { workspace = true }
 rustc-hash = { workspace = true }
-
-# Plugin system
-pinakes-plugin-api.workspace = true
-wasmtime.workspace = true
-ed25519-dalek.workspace = true
-
-[features]
-ffmpeg-tests = []
-
-[lints]
-workspace = true
+pinakes-plugin-api = { workspace = true }
+wasmtime = { workspace = true }
+ed25519-dalek = { workspace = true }
 
 [dev-dependencies]
 tempfile = { workspace = true }
 rand = { workspace = true }
+
+[lints]
+workspace = true

crates/pinakes-plugin-api/Cargo.toml

@@ -4,32 +4,25 @@ version.workspace = true
 edition.workspace = true
 license.workspace = true
 
+[features]
+default = []
+wasm = ["wit-bindgen"]
+
 [dependencies]
-# Core dependencies
 serde = { workspace = true }
 serde_json = { workspace = true }
 thiserror = { workspace = true }
 async-trait = { workspace = true }
 tracing = { workspace = true }
-
-# For plugin manifest parsing
 toml = { workspace = true }
-
-# For media types and identifiers
 uuid = { workspace = true }
 chrono = { workspace = true }
 mime_guess = { workspace = true }
 rustc-hash = { workspace = true }
-
-# WASM bridge types
 wit-bindgen = { workspace = true, optional = true }
 
-[lints]
-workspace = true
-
-[features]
-default = []
-wasm = ["wit-bindgen"]
-
 [dev-dependencies]
 tokio = { workspace = true, features = ["rt", "rt-multi-thread", "macros"] }
+
+[lints]
+workspace = true

docs/HACKING.md

@@ -0,0 +1,276 @@
+# Hacking Pinakes
+
+Pinakes is a lot of things. It also _plans_ to be a lot of things. One of those
+things, as you might have noticed, is _complete_. To be complete in features, to
+be complete in documentation and to be complete in hackability. This document
+covers, very comprehensively, how you may:
+
+- Develop Pinakes
+- Build Pinakes
+- Contribute to Pinakes
+
+for developers as well as:
+
+- Distribute Pinakes
+
+for Pinakes maintainers and packagers.
+
+## Development Environment
+
+[Nix]: https://nixos.org
+[Direnv]: https://direnv.net
+
+Pinakes uses [Nix] with flakes for pure, reproducible developer environments.
+All of the build dependencies that you need, from Rust to GTK and webkit, are
+provided in the devshell. In addition to _not_ requiring system libraries, we'd
+like to _actively discourage you_ from relying on system libraries.
+
+[Direnv] may be preferred by some users as an alternative to `nix develop`.
+
+```bash
+# Enter the dev shell
+$ nix develop
+
+# Or with direnv (recommended)
+$ direnv allow
+```
+
+Nix is the only supported way to get all dependencies. Distro package managers
+_may_ work for the core crates but are not supported for the UI.
+
+## Building Pinakes
+
+Pinakes is a Cargo workspace with multiple crates targeting multiple aspects of
+the projects. The user-facing crates are provided in `packages/*`.
+`pinakes-server` and `pinakes-tui` can be built normally with `cargo` while the
+UI crate, i.e., `pinakes-ui` **must** be built with the Dioxus CLI (`dx`) so
+that the SCSS stylesheets are compiled correctly. Everything else should work
+perfectly fine with the standard `cargo build`.
+
+[Just]: https://just.systems
+
+To make the things a _little_ bit more convenient, this project uses [Just] as
+its command runner and provides a few recipes for common tasks.
+
+```bash
+# Build all crates (server + TUI + UI)
+$ just build-all
+
+# Build individual components
+$ just build-server   # pinakes-server (HTTP API)
+$ just build-tui      # pinakes-tui (terminal UI)
+$ just build-ui       # pinakes-ui (Dioxus desktop/web UI, requires dx)
+```
+
+The dependencies required for the recipes, including Just itself, is provided by
+the Nix devshell. You may also run the cargo equivalents of those commands:
+
+```bash
+# Core crates
+$ cargo build -p pinakes-server
+$ cargo build -p pinakes-tui
+
+# The UI crate must be built with dx, not cargo.
+$ dx build -p pinakes-ui
+```
+
+Release builds follow the same pattern, but with `--release`. Nothing else
+should be required for the most part.
+
+## Running Pinakes
+
+For the time being, UI clients require the server to be running before they can
+function. Offline sync is planned, but likely come later alongside cross-device
+sync. All UIs connect to the server over HTTP.
+
+```bash
+# 1. Copy and edit the example config (first time only)
+$ cp pinakes.example.toml pinakes.toml
+
+# 2. Start the server (defaults to 127.0.0.1:3000)
+$ cargo run -p pinakes-server -- pinakes.toml
+
+# 3a. Run the TUI client
+$ cargo run -p pinakes-tui
+
+# 3b. Run the desktop/web UI
+$ cargo run -p pinakes-ui
+
+# Connect TUI to a non-default server address
+$ cargo run -p pinakes-tui -- --server http://localhost:3000
+```
+
+The GUI reads `PINAKES_SERVER_URL` if set; otherwise it assumes
+`http://127.0.0.1:3000`. You may change the host and port if you require.
+
+## Testing
+
+[cargo-nextest]: https://nexte.st
+
+Pinakes boasts, or well, attempts to boast a very comprehensive testing suite to
+ensure no regressions are introduced while in development. For fast parallel
+test execution, we use [cargo-nextest] and while you are recommended to use it
+over `cargo test` both should be supported. For CI and package tests, only
+`cargo-nextest` is supported.
+
+```bash
+# Run all workspace tests (preferred)
+$ just test
+
+# Equivalent without Just
+$ cargo nextest run --workspace
+
+# Tests for a single crate
+$ cargo nextest run -p pinakes-core
+$ cargo nextest run -p pinakes-server
+
+# Run a specific test by name and show output
+$ cargo test -p pinakes-core -- test_name --nocapture
+```
+
+## Linting and Formatting
+
+### Formatting
+
+There is a treewide formatter provided within the `flake.nix` that invokes the
+recommended formatter tooling across the various filetypes, including database
+migrations and Markdown sources. While a `just fmt` recipe is provided, it will
+not cover most of the files. Still, you may format the Rust sources as such:
+
+```bash
+# Format all code
+$ just fmt          # or: cargo fmt
+
+# Check formatting without modifying files
+$ cargo fmt --check
+```
+
+### Linting
+
+For now lints only cover Rust sources, and are provided by the Clippy tool. You
+may, as usual, invoke it with `just lint`.
+
+```bash
+# Run Clippy
+$ just lint                               # or: cargo clippy --workspace
+
+# Treat Clippy warnings as errors (used in CI)
+$ cargo clippy --workspace -- -D warnings # `-D warnings` is recommended
+```
+
+All Clippy warnings, besides some of the really annoying ones or false
+positives, must be resolved at the source. **Do not** use `#[allow(...)]` or
+`#[expect(...)]` to silence warnings unless there is a documented reason.
+
+It may be okay, at times, to suppress lints but you should focus on _resolving_
+them rather than suppressing them. _If_ suppressing, prefer `#[expect]` and
+provide the `reason` parameter.
+
+## Generating API Documentation
+
+The REST API documentation is generated from OpenAPI annotations in
+`pinakes-server` using `cargo xtask`:
+
+```bash
+# Generate the API documentation at docs/api/
+$ just docs # or: cargo xtask docs
+```
+
+This writes:
+
+- `docs/api.md` - Index linking all generated files
+- `docs/api/<tag>.md` - One Markdown file per API tag
+- `docs/api/openapi.json` - Full OpenAPI 3.0 specification
+
+Please do not edit files under `docs/api/` by hand; they are regenerated on each
+run.
+
+## Code Style
+
+There are many conventions that are in play within the Pinakes codebase. You'll
+get used and adjust to most of them naturally, but here are some of the general
+conventions written down for convenience.
+
+### General
+
+1. **Make illegal states unrepresentable**; ıse ADTs and newtype wrappers to
+   encode constraints in the type system. Parse and validate at system
+   boundaries (user input, external APIs); trust internal types everywhere else.
+2. This one is kind of obvious, but please use the `tracing` crate with
+   structured fields. Do not use `println!` or `eprintln!` in library or server
+   code.
+3. All storage operations must be implemented for both the SQLite and PostgreSQL
+   backends. Neither backend is optional.
+
+Naming is kind of obvious, but I'd like to remind you that we use `snake_case`
+for functions and variables, `PascalCase` for types and traits,
+`SCREAMING_SNAKE_CASE` for constants. There is not much else to it.
+
+### Error Handling
+
+- **`unwrap()` and `expect()` are banned** in non-test code. Use `?`,
+  `ok_or_else`, `match`, or `if let` instead.
+  - The only accepted exception is when a failure is truly impossible (e.g., a
+    hardcoded regex that is known-valid at compile time). In that case, add
+    `#[expect(clippy::expect_used, reason = "...")]` with a clear explanation.
+- Wrap storage errors with the `db_ctx` helper so error messages include the
+  operation and relevant ID:
+
+  ```rust
+  stmt.execute(params).map_err(db_ctx("insert_media", &media_id))?;
+  ```
+
+### Disallowed Types and APIs
+
+Pinakes uses hashers from `rustc_hash`, i.e., `FxHashMap` and `FxHashSet` over
+the `std` equivalents due to their faster nature without random state. This is
+enforced by clippy.
+
+As Pinakes uses Rust 1.90+, the now-deprecated `once_cell` crate is also banned.
+Use the stdlib equivalents:
+
+- `once_cell::unsync::OnceCell` -> `std::cell::OnceCell`
+- `once_cell::sync::OnceCell` -> `std::sync::OnceLock`
+- `once_cell::unsync::Lazy` -> `std::cell::LazyCell`
+- `once_cell::sync::Lazy` -> `std::sync::LazyLock`
+
+## Contributing
+
+1. Fork the repository and create a feature branch.
+2. Enter the dev shell: `nix develop` (or `direnv allow`).
+3. Make your changes; keep commits focused and descriptive. We use **scoped
+   commits**.
+4. Run `just fmt` and `just lint` before opening a pull request.
+5. Run `just test` to verify nothing is broken.
+6. Open a pull request against `main`. Describe what you changed and why.
+
+For significant changes, consider opening an issue first to discuss the
+approach.
+
+## Packaging and Distribution
+
+Pinakes is released under EUPL v1.2. For distributable release builds, please
+respect the license. You may create release builds for the user-facing crates
+using `cargo build --release` for server and TUI components. Use `dx` instead
+for the GUI:
+
+```bash
+# Server
+$ cargo build --release -p pinakes-server
+
+# TUI
+$ cargo build --release -p pinakes-tui
+
+# GUI
+$ dx build --release -p pinakes-ui
+```
+
+The resulting binaries are self-contained except for system libraries required
+by the UI (GTK3, libsoup, webkit2gtk). Database migrations run automatically on
+first server startup via the `refinery` crate; no manual migration step is
+needed.
+
+SQLite (the default backend) requires no external database server. PostgreSQL
+deployments need the `pg_trgm` extension enabled on the target database. It is
+generally advisable to document those requirements for the users, even though
+they do not require additional packaging steps.

docs/README.md

@@ -11,19 +11,41 @@ PostgreSQL (production deployments) as available database backends.
 
 ## Building
 
+This project uses [Just](https://just.systems/) as its command runner to help
+run cargo with a consistent interface. You are recommended to get it with Nix,
+using the default devshell which provides Just.
+
 ```bash
-# Build all compilable crates
+# Build everything (core crates + UI)
+$ just build
+
+# Build only core crates (cargo)
+$ just build-core
+
+# Build only the UI (uses dx - see note below)
+$ just build-ui
+```
+
+> [!IMPORTANT]
+> The Dioxus UI (`pinakes-ui`) must be built with `dx` (Dioxus CLI) to compile
+> SCSS stylesheets. Using `cargo build -p pinakes-ui` will not work correctly as
+> it skips the SCSS compilation step. This was previously "remedied" with an
+> intermediate build wrapper, which turned out to be fragile. It is highly
+> recommended that you prefer `just` to build.
+
+Manual build commands if not using Just:
+
+```bash
+# Core crates (standard cargo)
 $ cargo build -p pinakes-core -p pinakes-server -p pinakes-tui
 
-# The Dioxus UI requires GTK3 and libsoup system libraries:
+# UI (requires Dioxus CLI for SCSS compilation)
+$ dx build -p pinakes-ui
+
+# System dependencies for the UI:
 # On Debian/Ubuntu: apt install libgtk-3-dev libsoup-3.0-dev libwebkit2gtk-4.1-dev
 # On Fedora: dnf install gtk3-devel libsoup3-devel webkit2gtk4.1-devel
 # On Nix: Use the dev shell, everything is provided :)
-$ cargo build -p pinakes-ui
-
-# Alternatively, while app deps are in PATH, you may simply build the entire
-# workspace.
-$ cargo build --workspace
 ```
 
 ## Configuration
@@ -53,17 +75,20 @@ Key settings:
 
 ## Running
 
+All commands are available via Just. Run `just --list` to see all available
+recipes.
+
 ### Server
 
 To use Pinakes, you will need the server to be running. The GUI on its own will
 work, but it will not be functional without the server.
 
-```sh
-# Start the server first
-$ cargo run -p pinakes-server -- pinakes.toml
+```bash
+# Using Just
+$ just run-server
 
-# or:
-$ cargo run -p pinakes-server -- --config pinakes.toml
+# Or manually:
+$ cargo run -p pinakes-server -- pinakes.toml
 ```
 
 The server starts on the configured host:port (default `127.0.0.1:3000`). In a
@@ -77,11 +102,11 @@ terminal. While the server is running you may connect to it using the `--server`
 flag.
 
 ```bash
-# Using defaults
-$ cargo run -p pinakes-tui
+# Using Just
+$ just run-tui
 
-# or with a custom server URL:
-$ cargo run -p pinakes-tui -- --server http://localhost:3000
+# Or manually:
+$ cargo run -p pinakes-tui
 ```
 
 #### Keybindings
@@ -120,9 +145,15 @@ Pinakes features a fully fledged Desktop and Web UI powered by Dioxus. Those two
 components are meant as a GUI frontend for the Pinakes server, and are
 interchangeable in terms of usage.
 
+> [!IMPORTANT]
+> The UI must be run with `dx` (Dioxus CLI), not `cargo run`.
+
 ```bash
-# Build the UI
-$ cargo run -p pinakes-ui
+# Using Just
+$ just run-ui
+
+# Or manually with dx:
+$ dx serve -p pinakes-ui
 ```
 
 > [!TIP]
@@ -170,8 +201,11 @@ and design.
 ## Storage Backends
 
 Two storage backends are supported. For convenience, SQLite is the default
-backend out of the box but for production deployments you may choose to prefer
-PostgreSQL.
+backend out of the box but for production deployments, with improved search and
+scaling capabilities you may choose to prefer PostgreSQL. Both backends are
+considered first-class citizens, and will be developed as such going further. If
+your needs for Pinakes are modest, or if you are simply testing it out, SQLite
+is the recommended database.
 
 ### **SQLite** (default)
 
@@ -180,6 +214,34 @@ guarantees FTS5 availability.
 
 ### **PostgreSQL**
 
+[pg_trgm]: https://www.postgresql.org/docs/current/pgtrgm.html
+
 Native async with connection pooling (deadpool-postgres). Uses tsvector with
-weighted columns for full-text search and pg_trgm for fuzzy matching. Requires
+weighted columns for full-text search and [pg_trgm] for fuzzy matching. Requires
 the `pg_trgm` extension.
+
+## Contributing
+
+[HACKING document]: ./HACKING.md
+
+Pinakes, despite all the work going into it, is still in an early beta. Some of
+the features still lack the polish they deserve and there _may_ be breaking
+changes to the UI, databases, and the APIs. You may find a comprehensive
+introduction to developing Pinakes in the [HACKING document].
+
+It is generally advisable that you familiarize yourself with the codebase before
+proposing or contributing changes. Pinakes consists of _many_ moving parts, and
+it is better for the contributor experience to approach issues slowly and
+discuss them beforehand.
+
+## License
+
+<!-- markdownlint-disable MD059 -->
+
+[here]: https://interoperable-europe.ec.europa.eu/sites/default/files/custom-page/attachment/eupl_v1.2_en.pdf
+
+This project is made available under European Union Public Licence (EUPL)
+version 1.2. See [LICENSE](LICENSE) for more details on the exact conditions. An
+online copy is provided [here].
+
+<!-- markdownlint-enable MD059 -->

docs/api.md

@@ -0,0 +1,47 @@
+# API Documentation
+
+This is the index of all generated REST API documentation for Pinakes.
+
+Documentation is generated from OpenAPI annotations via `cargo xtask docs` (or
+`just docs`). Do not edit generated files by hand.
+
+## Reference
+
+- [openapi.json](api/openapi.json) - Full OpenAPI 3.0 specification
+
+## Endpoints by Tag
+
+- [Analytics](api/analytics.md) - Usage analytics and viewing history
+- [Audit](api/audit.md) - Audit log entries
+- [Auth](api/auth.md) - Authentication and session management
+- [Backup](api/backup.md) - Database backup
+- [Books](api/books.md) - Book metadata, series, authors, and reading progress
+- [Collections](api/collections.md) - Media collections
+- [Config](api/config.md) - Server configuration
+- [Database](api/database.md) - Database administration
+- [Duplicates](api/duplicates.md) - Duplicate media detection
+- [Enrichment](api/enrichment.md) - External metadata enrichment
+- [Export](api/export.md) - Media library export
+- [Health](api/health.md) - Server health checks
+- [Integrity](api/integrity.md) - Library integrity checks and repairs
+- [Jobs](api/jobs.md) - Background job management
+- [Media](api/media.md) - Media item management
+- [Notes](api/notes.md) - Markdown notes link graph
+- [Photos](api/photos.md) - Photo timeline and map view
+- [Playlists](api/playlists.md) - Media playlists
+- [Plugins](api/plugins.md) - Plugin management
+- [Saved_searches](api/saved_searches.md) - Saved search queries
+- [Scan](api/scan.md) - Directory scanning
+- [Scheduled_tasks](api/scheduled_tasks.md) - Scheduled background tasks
+- [Search](api/search.md) - Full-text media search
+- [Shares](api/shares.md) - Media sharing and notifications
+- [Social](api/social.md) - Ratings, comments, favorites, and share links
+- [Statistics](api/statistics.md) - Library statistics
+- [Streaming](api/streaming.md) - HLS and DASH adaptive streaming
+- [Subtitles](api/subtitles.md) - Media subtitle management
+- [Sync](api/sync.md) - Multi-device library synchronization
+- [Tags](api/tags.md) - Media tag management
+- [Transcode](api/transcode.md) - Video transcoding sessions
+- [Upload](api/upload.md) - File upload and managed storage
+- [Users](api/users.md) - User and library access management
+- [Webhooks](api/webhooks.md) - Webhook configuration

docs/api/analytics.md

@@ -16,11 +16,11 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Event recorded |
-| 401 | Unauthorized |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | Event recorded        |
+| 401    | Unauthorized          |
+| 500    | Internal server error |
 
 ---
 
@@ -30,18 +30,18 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `limit` | query | No | Maximum number of results |
-| `offset` | query | No | Pagination offset |
+| Name     | In    | Required | Description               |
+| -------- | ----- | -------- | ------------------------- |
+| `limit`  | query | No       | Maximum number of results |
+| `offset` | query | No       | Pagination offset         |
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Most viewed media |
-| 401 | Unauthorized |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | Most viewed media     |
+| 401    | Unauthorized          |
+| 500    | Internal server error |
 
 ---
 
@@ -51,18 +51,18 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `limit` | query | No | Maximum number of results |
-| `offset` | query | No | Pagination offset |
+| Name     | In    | Required | Description               |
+| -------- | ----- | -------- | ------------------------- |
+| `limit`  | query | No       | Maximum number of results |
+| `offset` | query | No       | Pagination offset         |
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Recently viewed media |
-| 401 | Unauthorized |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | Recently viewed media |
+| 401    | Unauthorized          |
+| 500    | Internal server error |
 
 ---
 
@@ -72,18 +72,18 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `id` | path | Yes | Media item ID |
+| Name | In   | Required | Description   |
+| ---- | ---- | -------- | ------------- |
+| `id` | path | Yes      | Media item ID |
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Watch progress |
-| 401 | Unauthorized |
-| 404 | Not found |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | Watch progress        |
+| 401    | Unauthorized          |
+| 404    | Not found             |
+| 500    | Internal server error |
 
 ---
 
@@ -93,9 +93,9 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `id` | path | Yes | Media item ID |
+| Name | In   | Required | Description   |
+| ---- | ---- | -------- | ------------- |
+| `id` | path | Yes      | Media item ID |
 
 #### Request Body
 
@@ -105,13 +105,12 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Progress updated |
-| 400 | Bad request |
-| 401 | Unauthorized |
-| 404 | Not found |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | Progress updated      |
+| 400    | Bad request           |
+| 401    | Unauthorized          |
+| 404    | Not found             |
+| 500    | Internal server error |
 
 ---
-

docs/api/audit.md

@@ -10,18 +10,17 @@ Audit log entries
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `offset` | query | No | Pagination offset |
-| `limit` | query | No | Page size |
+| Name     | In    | Required | Description       |
+| -------- | ----- | -------- | ----------------- |
+| `offset` | query | No       | Pagination offset |
+| `limit`  | query | No       | Page size         |
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Audit log entries |
-| 401 | Unauthorized |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | Audit log entries     |
+| 401    | Unauthorized          |
+| 500    | Internal server error |
 
 ---
-

docs/api/auth.md

@@ -16,12 +16,12 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Login successful |
-| 400 | Bad request |
-| 401 | Invalid credentials |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | Login successful      |
+| 400    | Bad request           |
+| 401    | Invalid credentials   |
+| 500    | Internal server error |
 
 ---
 
@@ -31,11 +31,11 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Logged out |
-| 401 | Unauthorized |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | Logged out            |
+| 401    | Unauthorized          |
+| 500    | Internal server error |
 
 ---
 
@@ -45,28 +45,27 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Current user info |
-| 401 | Unauthorized |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | Current user info     |
+| 401    | Unauthorized          |
+| 500    | Internal server error |
 
 ---
 
 ### POST /api/v1/auth/refresh
 
-Refresh the current session, extending its expiry by the configured
-duration.
+Refresh the current session, extending its expiry by the configured duration.
 
 **Authentication:** Required (Bearer JWT)
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Session refreshed |
-| 401 | Unauthorized |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | Session refreshed     |
+| 401    | Unauthorized          |
+| 500    | Internal server error |
 
 ---
 
@@ -78,11 +77,11 @@ Revoke all sessions for the current user
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | All sessions revoked |
-| 401 | Unauthorized |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | All sessions revoked  |
+| 401    | Unauthorized          |
+| 500    | Internal server error |
 
 ---
 
@@ -92,12 +91,11 @@ Revoke all sessions for the current user
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Active sessions |
-| 401 | Unauthorized |
-| 403 | Forbidden |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | Active sessions       |
+| 401    | Unauthorized          |
+| 403    | Forbidden             |
+| 500    | Internal server error |
 
 ---
-

docs/api/backup.md

@@ -6,22 +6,21 @@ Database backup
 
 ### POST /api/v1/admin/backup
 
-Create a database backup and return it as a downloadable file.
-POST /api/v1/admin/backup
+Create a database backup and return it as a downloadable file. POST
+/api/v1/admin/backup
 
-For `SQLite`: creates a backup via VACUUM INTO and returns the file.
-For `PostgreSQL`: returns unsupported error (use `pg_dump` instead).
+For `SQLite`: creates a backup via VACUUM INTO and returns the file. For
+`PostgreSQL`: returns unsupported error (use `pg_dump` instead).
 
 **Authentication:** Required (Bearer JWT)
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Backup file download |
-| 401 | Unauthorized |
-| 403 | Forbidden |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | Backup file download  |
+| 401    | Unauthorized          |
+| 403    | Forbidden             |
+| 500    | Internal server error |
 
 ---
-

docs/api/books.md

@@ -12,23 +12,23 @@ List all books with optional search filters
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `isbn` | query | No | Filter by ISBN |
-| `author` | query | No | Filter by author |
-| `series` | query | No | Filter by series |
-| `publisher` | query | No | Filter by publisher |
-| `language` | query | No | Filter by language |
-| `offset` | query | No | Pagination offset |
-| `limit` | query | No | Pagination limit |
+| Name        | In    | Required | Description         |
+| ----------- | ----- | -------- | ------------------- |
+| `isbn`      | query | No       | Filter by ISBN      |
+| `author`    | query | No       | Filter by author    |
+| `series`    | query | No       | Filter by series    |
+| `publisher` | query | No       | Filter by publisher |
+| `language`  | query | No       | Filter by language  |
+| `offset`    | query | No       | Pagination offset   |
+| `limit`     | query | No       | Pagination limit    |
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | List of books |
-| 401 | Unauthorized |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | List of books         |
+| 401    | Unauthorized          |
+| 500    | Internal server error |
 
 ---
 
@@ -40,17 +40,17 @@ List all authors with book counts
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `offset` | query | No | Pagination offset |
-| `limit` | query | No | Pagination limit |
+| Name     | In    | Required | Description       |
+| -------- | ----- | -------- | ----------------- |
+| `offset` | query | No       | Pagination offset |
+| `limit`  | query | No       | Pagination limit  |
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Authors with book counts |
-| 401 | Unauthorized |
+| Status | Description              |
+| ------ | ------------------------ |
+| 200    | Authors with book counts |
+| 401    | Unauthorized             |
 
 ---
 
@@ -62,18 +62,18 @@ Get books by a specific author
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `name` | path | Yes | Author name |
-| `offset` | query | No | Pagination offset |
-| `limit` | query | No | Pagination limit |
+| Name     | In    | Required | Description       |
+| -------- | ----- | -------- | ----------------- |
+| `name`   | path  | Yes      | Author name       |
+| `offset` | query | No       | Pagination offset |
+| `limit`  | query | No       | Pagination limit  |
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Books by author |
-| 401 | Unauthorized |
+| Status | Description     |
+| ------ | --------------- |
+| 200    | Books by author |
+| 401    | Unauthorized    |
 
 ---
 
@@ -85,16 +85,16 @@ Get user's reading list
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `status` | query | No | Filter by reading status |
+| Name     | In    | Required | Description                                                                    |
+| -------- | ----- | -------- | ------------------------------------------------------------------------------ |
+| `status` | query | No       | Filter by reading status. Valid values: to_read, reading, completed, abandoned |
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Reading list |
-| 401 | Unauthorized |
+| Status | Description  |
+| ------ | ------------ |
+| 200    | Reading list |
+| 401    | Unauthorized |
 
 ---
 
@@ -106,10 +106,10 @@ List all series with book counts
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | List of series with counts |
-| 401 | Unauthorized |
+| Status | Description                |
+| ------ | -------------------------- |
+| 200    | List of series with counts |
+| 401    | Unauthorized               |
 
 ---
 
@@ -121,16 +121,16 @@ Get books in a specific series
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `name` | path | Yes | Series name |
+| Name   | In   | Required | Description |
+| ------ | ---- | -------- | ----------- |
+| `name` | path | Yes      | Series name |
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Books in series |
-| 401 | Unauthorized |
+| Status | Description     |
+| ------ | --------------- |
+| 200    | Books in series |
+| 401    | Unauthorized    |
 
 ---
 
@@ -142,17 +142,17 @@ Get book metadata by media ID
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `id` | path | Yes | Media item ID |
+| Name | In   | Required | Description   |
+| ---- | ---- | -------- | ------------- |
+| `id` | path | Yes      | Media item ID |
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Book metadata |
-| 401 | Unauthorized |
-| 404 | Not found |
+| Status | Description   |
+| ------ | ------------- |
+| 200    | Book metadata |
+| 401    | Unauthorized  |
+| 404    | Not found     |
 
 ---
 
@@ -164,17 +164,17 @@ Get reading progress for a book
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `id` | path | Yes | Media item ID |
+| Name | In   | Required | Description   |
+| ---- | ---- | -------- | ------------- |
+| `id` | path | Yes      | Media item ID |
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Reading progress |
-| 401 | Unauthorized |
-| 404 | Not found |
+| Status | Description      |
+| ------ | ---------------- |
+| 200    | Reading progress |
+| 401    | Unauthorized     |
+| 404    | Not found        |
 
 ---
 
@@ -186,9 +186,9 @@ Update reading progress for a book
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `id` | path | Yes | Media item ID |
+| Name | In   | Required | Description   |
+| ---- | ---- | -------- | ------------- |
+| `id` | path | Yes      | Media item ID |
 
 #### Request Body
 
@@ -198,11 +198,10 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 204 | Progress updated |
-| 400 | Bad request |
-| 401 | Unauthorized |
+| Status | Description      |
+| ------ | ---------------- |
+| 204    | Progress updated |
+| 400    | Bad request      |
+| 401    | Unauthorized     |
 
 ---
-

docs/api/collections.md

@@ -10,11 +10,11 @@ Media collections
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | List of collections |
-| 401 | Unauthorized |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | List of collections   |
+| 401    | Unauthorized          |
+| 500    | Internal server error |
 
 ---
 
@@ -30,13 +30,13 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Collection created |
-| 400 | Bad request |
-| 401 | Unauthorized |
-| 403 | Forbidden |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | Collection created    |
+| 400    | Bad request           |
+| 401    | Unauthorized          |
+| 403    | Forbidden             |
+| 500    | Internal server error |
 
 ---
 
@@ -46,18 +46,18 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `id` | path | Yes | Collection ID |
+| Name | In   | Required | Description   |
+| ---- | ---- | -------- | ------------- |
+| `id` | path | Yes      | Collection ID |
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Collection |
-| 401 | Unauthorized |
-| 404 | Not found |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | Collection            |
+| 401    | Unauthorized          |
+| 404    | Not found             |
+| 500    | Internal server error |
 
 ---
 
@@ -67,19 +67,19 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `id` | path | Yes | Collection ID |
+| Name | In   | Required | Description   |
+| ---- | ---- | -------- | ------------- |
+| `id` | path | Yes      | Collection ID |
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Collection deleted |
-| 401 | Unauthorized |
-| 403 | Forbidden |
-| 404 | Not found |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | Collection deleted    |
+| 401    | Unauthorized          |
+| 403    | Forbidden             |
+| 404    | Not found             |
+| 500    | Internal server error |
 
 ---
 
@@ -89,18 +89,18 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `id` | path | Yes | Collection ID |
+| Name | In   | Required | Description   |
+| ---- | ---- | -------- | ------------- |
+| `id` | path | Yes      | Collection ID |
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Collection members |
-| 401 | Unauthorized |
-| 404 | Not found |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | Collection members    |
+| 401    | Unauthorized          |
+| 404    | Not found             |
+| 500    | Internal server error |
 
 ---
 
@@ -110,9 +110,9 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `id` | path | Yes | Collection ID |
+| Name | In   | Required | Description   |
+| ---- | ---- | -------- | ------------- |
+| `id` | path | Yes      | Collection ID |
 
 #### Request Body
 
@@ -122,13 +122,13 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Member added |
-| 401 | Unauthorized |
-| 403 | Forbidden |
-| 404 | Not found |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | Member added          |
+| 401    | Unauthorized          |
+| 403    | Forbidden             |
+| 404    | Not found             |
+| 500    | Internal server error |
 
 ---
 
@@ -138,20 +138,19 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `id` | path | Yes | Collection ID |
-| `media_id` | path | Yes | Media item ID |
+| Name       | In   | Required | Description   |
+| ---------- | ---- | -------- | ------------- |
+| `id`       | path | Yes      | Collection ID |
+| `media_id` | path | Yes      | Media item ID |
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Member removed |
-| 401 | Unauthorized |
-| 403 | Forbidden |
-| 404 | Not found |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | Member removed        |
+| 401    | Unauthorized          |
+| 403    | Forbidden             |
+| 404    | Not found             |
+| 500    | Internal server error |
 
 ---
-

docs/api/config.md

@@ -10,12 +10,12 @@ Server configuration
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Current server configuration |
-| 401 | Unauthorized |
-| 403 | Forbidden |
-| 500 | Internal server error |
+| Status | Description                  |
+| ------ | ---------------------------- |
+| 200    | Current server configuration |
+| 401    | Unauthorized                 |
+| 403    | Forbidden                    |
+| 500    | Internal server error        |
 
 ---
 
@@ -31,13 +31,13 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Updated configuration |
-| 400 | Bad request |
-| 401 | Unauthorized |
-| 403 | Forbidden |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | Updated configuration |
+| 400    | Bad request           |
+| 401    | Unauthorized          |
+| 403    | Forbidden             |
+| 500    | Internal server error |
 
 ---
 
@@ -53,12 +53,12 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Updated configuration |
-| 401 | Unauthorized |
-| 403 | Forbidden |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | Updated configuration |
+| 401    | Unauthorized          |
+| 403    | Forbidden             |
+| 500    | Internal server error |
 
 ---
 
@@ -74,12 +74,12 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Updated configuration |
-| 401 | Unauthorized |
-| 403 | Forbidden |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | Updated configuration |
+| 401    | Unauthorized          |
+| 403    | Forbidden             |
+| 500    | Internal server error |
 
 ---
 
@@ -89,11 +89,11 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | UI configuration |
-| 401 | Unauthorized |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | UI configuration      |
+| 401    | Unauthorized          |
+| 500    | Internal server error |
 
 ---
 
@@ -109,12 +109,11 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Updated UI configuration |
-| 401 | Unauthorized |
-| 403 | Forbidden |
-| 500 | Internal server error |
+| Status | Description              |
+| ------ | ------------------------ |
+| 200    | Updated UI configuration |
+| 401    | Unauthorized             |
+| 403    | Forbidden                |
+| 500    | Internal server error    |
 
 ---
-

docs/api/database.md

@@ -10,12 +10,12 @@ Database administration
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Database cleared |
-| 401 | Unauthorized |
-| 403 | Forbidden |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | Database cleared      |
+| 401    | Unauthorized          |
+| 403    | Forbidden             |
+| 500    | Internal server error |
 
 ---
 
@@ -25,12 +25,12 @@ Database administration
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Database statistics |
-| 401 | Unauthorized |
-| 403 | Forbidden |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | Database statistics   |
+| 401    | Unauthorized          |
+| 403    | Forbidden             |
+| 500    | Internal server error |
 
 ---
 
@@ -40,12 +40,11 @@ Database administration
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Database vacuumed |
-| 401 | Unauthorized |
-| 403 | Forbidden |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | Database vacuumed     |
+| 401    | Unauthorized          |
+| 403    | Forbidden             |
+| 500    | Internal server error |
 
 ---
-

docs/api/duplicates.md

@@ -10,11 +10,10 @@ Duplicate media detection
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Duplicate groups |
-| 401 | Unauthorized |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | Duplicate groups      |
+| 401    | Unauthorized          |
+| 500    | Internal server error |
 
 ---
-

docs/api/enrichment.md

@@ -16,13 +16,13 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Enrichment job submitted |
-| 400 | Bad request |
-| 401 | Unauthorized |
-| 403 | Forbidden |
-| 500 | Internal server error |
+| Status | Description              |
+| ------ | ------------------------ |
+| 200    | Enrichment job submitted |
+| 400    | Bad request              |
+| 401    | Unauthorized             |
+| 403    | Forbidden                |
+| 500    | Internal server error    |
 
 ---
 
@@ -32,19 +32,19 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `id` | path | Yes | Media item ID |
+| Name | In   | Required | Description   |
+| ---- | ---- | -------- | ------------- |
+| `id` | path | Yes      | Media item ID |
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Enrichment job submitted |
-| 401 | Unauthorized |
-| 403 | Forbidden |
-| 404 | Not found |
-| 500 | Internal server error |
+| Status | Description              |
+| ------ | ------------------------ |
+| 200    | Enrichment job submitted |
+| 401    | Unauthorized             |
+| 403    | Forbidden                |
+| 404    | Not found                |
+| 500    | Internal server error    |
 
 ---
 
@@ -54,18 +54,17 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `id` | path | Yes | Media item ID |
+| Name | In   | Required | Description   |
+| ---- | ---- | -------- | ------------- |
+| `id` | path | Yes      | Media item ID |
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | External metadata |
-| 401 | Unauthorized |
-| 404 | Not found |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | External metadata     |
+| 401    | Unauthorized          |
+| 404    | Not found             |
+| 500    | Internal server error |
 
 ---
-

docs/api/export.md

@@ -10,12 +10,12 @@ Media library export
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Export job submitted |
-| 401 | Unauthorized |
-| 403 | Forbidden |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | Export job submitted  |
+| 401    | Unauthorized          |
+| 403    | Forbidden             |
+| 500    | Internal server error |
 
 ---
 
@@ -31,12 +31,11 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Export job submitted |
-| 401 | Unauthorized |
-| 403 | Forbidden |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | Export job submitted  |
+| 401    | Unauthorized          |
+| 403    | Forbidden             |
+| 500    | Internal server error |
 
 ---
-

docs/api/health.md

@@ -12,9 +12,9 @@ Comprehensive health check - includes database, filesystem, and cache status
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Health status |
+| Status | Description   |
+| ------ | ------------- |
+| 200    | Health status |
 
 ---
 
@@ -24,40 +24,39 @@ Comprehensive health check - includes database, filesystem, and cache status
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Detailed health status |
+| Status | Description            |
+| ------ | ---------------------- |
+| 200    | Detailed health status |
 
 ---
 
 ### GET /api/v1/health/live
 
-Liveness probe - just checks if the server is running
-Returns 200 OK if the server process is alive
+Liveness probe - just checks if the server is running Returns 200 OK if the
+server process is alive
 
 **Authentication:** Required (Bearer JWT)
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Server is alive |
+| Status | Description     |
+| ------ | --------------- |
+| 200    | Server is alive |
 
 ---
 
 ### GET /api/v1/health/ready
 
-Readiness probe - checks if the server can serve requests
-Returns 200 OK if database is accessible
+Readiness probe - checks if the server can serve requests Returns 200 OK if
+database is accessible
 
 **Authentication:** Required (Bearer JWT)
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Server is ready |
-| 503 | Server not ready |
+| Status | Description      |
+| ------ | ---------------- |
+| 200    | Server is ready  |
+| 503    | Server not ready |
 
 ---
-

docs/api/integrity.md

@@ -10,12 +10,12 @@ Library integrity checks and repairs
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Orphan detection job submitted |
-| 401 | Unauthorized |
-| 403 | Forbidden |
-| 500 | Internal server error |
+| Status | Description                    |
+| ------ | ------------------------------ |
+| 200    | Orphan detection job submitted |
+| 401    | Unauthorized                   |
+| 403    | Forbidden                      |
+| 500    | Internal server error          |
 
 ---
 
@@ -31,12 +31,12 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Orphans resolved |
-| 401 | Unauthorized |
-| 403 | Forbidden |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | Orphans resolved      |
+| 401    | Unauthorized          |
+| 403    | Forbidden             |
+| 500    | Internal server error |
 
 ---
 
@@ -46,12 +46,12 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Thumbnail cleanup job submitted |
-| 401 | Unauthorized |
-| 403 | Forbidden |
-| 500 | Internal server error |
+| Status | Description                     |
+| ------ | ------------------------------- |
+| 200    | Thumbnail cleanup job submitted |
+| 401    | Unauthorized                    |
+| 403    | Forbidden                       |
+| 500    | Internal server error           |
 
 ---
 
@@ -67,12 +67,12 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Thumbnail generation job submitted |
-| 401 | Unauthorized |
-| 403 | Forbidden |
-| 500 | Internal server error |
+| Status | Description                        |
+| ------ | ---------------------------------- |
+| 200    | Thumbnail generation job submitted |
+| 401    | Unauthorized                       |
+| 403    | Forbidden                          |
+| 500    | Internal server error              |
 
 ---
 
@@ -88,12 +88,11 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Integrity verification job submitted |
-| 401 | Unauthorized |
-| 403 | Forbidden |
-| 500 | Internal server error |
+| Status | Description                          |
+| ------ | ------------------------------------ |
+| 200    | Integrity verification job submitted |
+| 401    | Unauthorized                         |
+| 403    | Forbidden                            |
+| 500    | Internal server error                |
 
 ---
-

docs/api/jobs.md

@@ -10,11 +10,11 @@ Background job management
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | List of jobs |
-| 401 | Unauthorized |
-| 403 | Forbidden |
+| Status | Description  |
+| ------ | ------------ |
+| 200    | List of jobs |
+| 401    | Unauthorized |
+| 403    | Forbidden    |
 
 ---
 
@@ -24,18 +24,18 @@ Background job management
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `id` | path | Yes | Job ID |
+| Name | In   | Required | Description |
+| ---- | ---- | -------- | ----------- |
+| `id` | path | Yes      | Job ID      |
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Job details |
-| 401 | Unauthorized |
-| 403 | Forbidden |
-| 404 | Not found |
+| Status | Description  |
+| ------ | ------------ |
+| 200    | Job details  |
+| 401    | Unauthorized |
+| 403    | Forbidden    |
+| 404    | Not found    |
 
 ---
 
@@ -45,18 +45,17 @@ Background job management
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `id` | path | Yes | Job ID |
+| Name | In   | Required | Description |
+| ---- | ---- | -------- | ----------- |
+| `id` | path | Yes      | Job ID      |
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Job cancelled |
-| 401 | Unauthorized |
-| 403 | Forbidden |
-| 404 | Not found |
+| Status | Description   |
+| ------ | ------------- |
+| 200    | Job cancelled |
+| 401    | Unauthorized  |
+| 403    | Forbidden     |
+| 404    | Not found     |
 
 ---
-

docs/api/media.md

@@ -10,19 +10,19 @@ Media item management
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `offset` | query | No | Pagination offset |
-| `limit` | query | No | Page size |
-| `sort` | query | No | Sort field |
+| Name     | In    | Required | Description       |
+| -------- | ----- | -------- | ----------------- |
+| `offset` | query | No       | Pagination offset |
+| `limit`  | query | No       | Page size         |
+| `sort`   | query | No       | Sort field        |
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | List of media items |
-| 401 | Unauthorized |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | List of media items   |
+| 401    | Unauthorized          |
+| 500    | Internal server error |
 
 ---
 
@@ -32,12 +32,12 @@ Media item management
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | All media deleted |
-| 401 | Unauthorized |
-| 403 | Forbidden |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | All media deleted     |
+| 401    | Unauthorized          |
+| 403    | Forbidden             |
+| 500    | Internal server error |
 
 ---
 
@@ -53,13 +53,13 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Batch collection result |
-| 400 | Bad request |
-| 401 | Unauthorized |
-| 403 | Forbidden |
-| 500 | Internal server error |
+| Status | Description             |
+| ------ | ----------------------- |
+| 200    | Batch collection result |
+| 400    | Bad request             |
+| 401    | Unauthorized            |
+| 403    | Forbidden               |
+| 500    | Internal server error   |
 
 ---
 
@@ -75,13 +75,13 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Batch delete result |
-| 400 | Bad request |
-| 401 | Unauthorized |
-| 403 | Forbidden |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | Batch delete result   |
+| 400    | Bad request           |
+| 401    | Unauthorized          |
+| 403    | Forbidden             |
+| 500    | Internal server error |
 
 ---
 
@@ -97,13 +97,13 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Batch move result |
-| 400 | Bad request |
-| 401 | Unauthorized |
-| 403 | Forbidden |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | Batch move result     |
+| 400    | Bad request           |
+| 401    | Unauthorized          |
+| 403    | Forbidden             |
+| 500    | Internal server error |
 
 ---
 
@@ -119,13 +119,13 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Batch tag result |
-| 400 | Bad request |
-| 401 | Unauthorized |
-| 403 | Forbidden |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | Batch tag result      |
+| 400    | Bad request           |
+| 401    | Unauthorized          |
+| 403    | Forbidden             |
+| 500    | Internal server error |
 
 ---
 
@@ -141,13 +141,13 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Batch update result |
-| 400 | Bad request |
-| 401 | Unauthorized |
-| 403 | Forbidden |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | Batch update result   |
+| 400    | Bad request           |
+| 401    | Unauthorized          |
+| 403    | Forbidden             |
+| 500    | Internal server error |
 
 ---
 
@@ -157,11 +157,11 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Media count |
-| 401 | Unauthorized |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | Media count           |
+| 401    | Unauthorized          |
+| 500    | Internal server error |
 
 ---
 
@@ -177,13 +177,13 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Media imported |
-| 400 | Bad request |
-| 401 | Unauthorized |
-| 403 | Forbidden |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | Media imported        |
+| 400    | Bad request           |
+| 401    | Unauthorized          |
+| 403    | Forbidden             |
+| 500    | Internal server error |
 
 ---
 
@@ -199,13 +199,13 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Batch import results |
-| 400 | Bad request |
-| 401 | Unauthorized |
-| 403 | Forbidden |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | Batch import results  |
+| 400    | Bad request           |
+| 401    | Unauthorized          |
+| 403    | Forbidden             |
+| 500    | Internal server error |
 
 ---
 
@@ -221,13 +221,13 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Directory import results |
-| 400 | Bad request |
-| 401 | Unauthorized |
-| 403 | Forbidden |
-| 500 | Internal server error |
+| Status | Description              |
+| ------ | ------------------------ |
+| 200    | Directory import results |
+| 400    | Bad request              |
+| 401    | Unauthorized             |
+| 403    | Forbidden                |
+| 500    | Internal server error    |
 
 ---
 
@@ -243,13 +243,13 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Media imported |
-| 400 | Bad request |
-| 401 | Unauthorized |
-| 403 | Forbidden |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | Media imported        |
+| 400    | Bad request           |
+| 401    | Unauthorized          |
+| 403    | Forbidden             |
+| 500    | Internal server error |
 
 ---
 
@@ -265,13 +265,13 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Directory preview |
-| 400 | Bad request |
-| 401 | Unauthorized |
-| 403 | Forbidden |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | Directory preview     |
+| 400    | Bad request           |
+| 401    | Unauthorized          |
+| 403    | Forbidden             |
+| 500    | Internal server error |
 
 ---
 
@@ -281,18 +281,18 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `offset` | query | No | Pagination offset |
-| `limit` | query | No | Page size |
+| Name     | In    | Required | Description       |
+| -------- | ----- | -------- | ----------------- |
+| `offset` | query | No       | Pagination offset |
+| `limit`  | query | No       | Page size         |
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Trashed media items |
-| 401 | Unauthorized |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | Trashed media items   |
+| 401    | Unauthorized          |
+| 500    | Internal server error |
 
 ---
 
@@ -302,12 +302,12 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Trash emptied |
-| 401 | Unauthorized |
-| 403 | Forbidden |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | Trash emptied         |
+| 401    | Unauthorized          |
+| 403    | Forbidden             |
+| 500    | Internal server error |
 
 ---
 
@@ -317,11 +317,11 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Trash info |
-| 401 | Unauthorized |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | Trash info            |
+| 401    | Unauthorized          |
+| 500    | Internal server error |
 
 ---
 
@@ -331,18 +331,18 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `id` | path | Yes | Media item ID |
+| Name | In   | Required | Description   |
+| ---- | ---- | -------- | ------------- |
+| `id` | path | Yes      | Media item ID |
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Media item |
-| 401 | Unauthorized |
-| 404 | Not found |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | Media item            |
+| 401    | Unauthorized          |
+| 404    | Not found             |
+| 500    | Internal server error |
 
 ---
 
@@ -352,9 +352,9 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `id` | path | Yes | Media item ID |
+| Name | In   | Required | Description   |
+| ---- | ---- | -------- | ------------- |
+| `id` | path | Yes      | Media item ID |
 
 #### Request Body
 
@@ -364,14 +364,14 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Updated media item |
-| 400 | Bad request |
-| 401 | Unauthorized |
-| 403 | Forbidden |
-| 404 | Not found |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | Updated media item    |
+| 400    | Bad request           |
+| 401    | Unauthorized          |
+| 403    | Forbidden             |
+| 404    | Not found             |
+| 500    | Internal server error |
 
 ---
 
@@ -381,19 +381,19 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `id` | path | Yes | Media item ID |
+| Name | In   | Required | Description   |
+| ---- | ---- | -------- | ------------- |
+| `id` | path | Yes      | Media item ID |
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Media deleted |
-| 401 | Unauthorized |
-| 403 | Forbidden |
-| 404 | Not found |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | Media deleted         |
+| 401    | Unauthorized          |
+| 403    | Forbidden             |
+| 404    | Not found             |
+| 500    | Internal server error |
 
 ---
 
@@ -403,9 +403,9 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `id` | path | Yes | Media item ID |
+| Name | In   | Required | Description   |
+| ---- | ---- | -------- | ------------- |
+| `id` | path | Yes      | Media item ID |
 
 #### Request Body
 
@@ -415,14 +415,14 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Custom field set |
-| 400 | Bad request |
-| 401 | Unauthorized |
-| 403 | Forbidden |
-| 404 | Not found |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | Custom field set      |
+| 400    | Bad request           |
+| 401    | Unauthorized          |
+| 403    | Forbidden             |
+| 404    | Not found             |
+| 500    | Internal server error |
 
 ---
 
@@ -432,20 +432,20 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `id` | path | Yes | Media item ID |
-| `name` | path | Yes | Custom field name |
+| Name   | In   | Required | Description       |
+| ------ | ---- | -------- | ----------------- |
+| `id`   | path | Yes      | Media item ID     |
+| `name` | path | Yes      | Custom field name |
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Custom field deleted |
-| 401 | Unauthorized |
-| 403 | Forbidden |
-| 404 | Not found |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | Custom field deleted  |
+| 401    | Unauthorized          |
+| 403    | Forbidden             |
+| 404    | Not found             |
+| 500    | Internal server error |
 
 ---
 
@@ -455,9 +455,9 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `id` | path | Yes | Media item ID |
+| Name | In   | Required | Description   |
+| ---- | ---- | -------- | ------------- |
+| `id` | path | Yes      | Media item ID |
 
 #### Request Body
 
@@ -467,14 +467,14 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Moved media item |
-| 400 | Bad request |
-| 401 | Unauthorized |
-| 403 | Forbidden |
-| 404 | Not found |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | Moved media item      |
+| 400    | Bad request           |
+| 401    | Unauthorized          |
+| 403    | Forbidden             |
+| 404    | Not found             |
+| 500    | Internal server error |
 
 ---
 
@@ -484,18 +484,18 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `id` | path | Yes | Media item ID |
+| Name | In   | Required | Description   |
+| ---- | ---- | -------- | ------------- |
+| `id` | path | Yes      | Media item ID |
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Media opened |
-| 401 | Unauthorized |
-| 404 | Not found |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | Media opened          |
+| 401    | Unauthorized          |
+| 404    | Not found             |
+| 500    | Internal server error |
 
 ---
 
@@ -505,20 +505,20 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `id` | path | Yes | Media item ID |
-| `permanent` | query | No | Set to 'true' for permanent deletion |
+| Name        | In    | Required | Description                          |
+| ----------- | ----- | -------- | ------------------------------------ |
+| `id`        | path  | Yes      | Media item ID                        |
+| `permanent` | query | No       | Set to 'true' for permanent deletion |
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Media deleted |
-| 401 | Unauthorized |
-| 403 | Forbidden |
-| 404 | Not found |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | Media deleted         |
+| 401    | Unauthorized          |
+| 403    | Forbidden             |
+| 404    | Not found             |
+| 500    | Internal server error |
 
 ---
 
@@ -528,9 +528,9 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `id` | path | Yes | Media item ID |
+| Name | In   | Required | Description   |
+| ---- | ---- | -------- | ------------- |
+| `id` | path | Yes      | Media item ID |
 
 #### Request Body
 
@@ -540,14 +540,14 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Renamed media item |
-| 400 | Bad request |
-| 401 | Unauthorized |
-| 403 | Forbidden |
-| 404 | Not found |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | Renamed media item    |
+| 400    | Bad request           |
+| 401    | Unauthorized          |
+| 403    | Forbidden             |
+| 404    | Not found             |
+| 500    | Internal server error |
 
 ---
 
@@ -557,19 +557,19 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `id` | path | Yes | Media item ID |
+| Name | In   | Required | Description   |
+| ---- | ---- | -------- | ------------- |
+| `id` | path | Yes      | Media item ID |
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Media restored |
-| 401 | Unauthorized |
-| 403 | Forbidden |
-| 404 | Not found |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | Media restored        |
+| 401    | Unauthorized          |
+| 403    | Forbidden             |
+| 404    | Not found             |
+| 500    | Internal server error |
 
 ---
 
@@ -579,19 +579,19 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `id` | path | Yes | Media item ID |
+| Name | In   | Required | Description   |
+| ---- | ---- | -------- | ------------- |
+| `id` | path | Yes      | Media item ID |
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Media stream |
-| 206 | Partial content |
-| 401 | Unauthorized |
-| 404 | Not found |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | Media stream          |
+| 206    | Partial content       |
+| 401    | Unauthorized          |
+| 404    | Not found             |
+| 500    | Internal server error |
 
 ---
 
@@ -601,18 +601,18 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `id` | path | Yes | Media item ID |
+| Name | In   | Required | Description   |
+| ---- | ---- | -------- | ------------- |
+| `id` | path | Yes      | Media item ID |
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Thumbnail image |
-| 401 | Unauthorized |
-| 404 | Not found |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | Thumbnail image       |
+| 401    | Unauthorized          |
+| 404    | Not found             |
+| 500    | Internal server error |
 
 ---
 
@@ -622,19 +622,18 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `id` | path | Yes | Media item ID |
+| Name | In   | Required | Description   |
+| ---- | ---- | -------- | ------------- |
+| `id` | path | Yes      | Media item ID |
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Media moved to trash |
-| 401 | Unauthorized |
-| 403 | Forbidden |
-| 404 | Not found |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | Media moved to trash  |
+| 401    | Unauthorized          |
+| 403    | Forbidden             |
+| 404    | Not found             |
+| 500    | Internal server error |
 
 ---
-

docs/api/notes.md

@@ -14,18 +14,18 @@ GET /api/v1/media/{id}/backlinks
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `id` | path | Yes | Media item ID |
+| Name | In   | Required | Description   |
+| ---- | ---- | -------- | ------------- |
+| `id` | path | Yes      | Media item ID |
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Backlinks |
-| 401 | Unauthorized |
-| 404 | Not found |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | Backlinks             |
+| 401    | Unauthorized          |
+| 404    | Not found             |
+| 500    | Internal server error |
 
 ---
 
@@ -39,18 +39,18 @@ GET /api/v1/media/{id}/outgoing-links
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `id` | path | Yes | Media item ID |
+| Name | In   | Required | Description   |
+| ---- | ---- | -------- | ------------- |
+| `id` | path | Yes      | Media item ID |
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Outgoing links |
-| 401 | Unauthorized |
-| 404 | Not found |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | Outgoing links        |
+| 401    | Unauthorized          |
+| 404    | Not found             |
+| 500    | Internal server error |
 
 ---
 
@@ -64,18 +64,18 @@ POST /api/v1/media/{id}/reindex-links
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `id` | path | Yes | Media item ID |
+| Name | In   | Required | Description   |
+| ---- | ---- | -------- | ------------- |
+| `id` | path | Yes      | Media item ID |
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Links reindexed |
-| 401 | Unauthorized |
-| 404 | Not found |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | Links reindexed       |
+| 401    | Unauthorized          |
+| 404    | Not found             |
+| 500    | Internal server error |
 
 ---
 
@@ -89,18 +89,18 @@ GET /api/v1/notes/graph?center={uuid}&depth={n}
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `center` | query | No | Center node ID |
-| `depth` | query | No | Traversal depth (max 5, default 2) |
+| Name     | In    | Required | Description                        |
+| -------- | ----- | -------- | ---------------------------------- |
+| `center` | query | No       | Center node ID                     |
+| `depth`  | query | No       | Traversal depth (max 5, default 2) |
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Graph data |
-| 401 | Unauthorized |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | Graph data            |
+| 401    | Unauthorized          |
+| 500    | Internal server error |
 
 ---
 
@@ -114,11 +114,11 @@ POST /api/v1/notes/resolve-links
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Links resolved |
-| 401 | Unauthorized |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | Links resolved        |
+| 401    | Unauthorized          |
+| 500    | Internal server error |
 
 ---
 
@@ -132,11 +132,10 @@ GET /api/v1/notes/unresolved-count
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Unresolved link count |
-| 401 | Unauthorized |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | Unresolved link count |
+| 401    | Unauthorized          |
+| 500    | Internal server error |
 
 ---
-

docs/api/openapi.json

@@ -1275,7 +1275,7 @@
           {
             "name": "status",
             "in": "query",
-            "description": "Filter by reading status",
+            "description": "Filter by reading status. Valid values: to_read, reading, completed, abandoned",
             "required": false,
             "schema": {
               "type": "string"
@@ -4704,14 +4704,11 @@
         ],
         "responses": {
           "200": {
-            "description": "Subtitles",
+            "description": "Subtitles and available embedded tracks",
             "content": {
               "application/json": {
                 "schema": {
-                  "type": "array",
-                  "items": {
-                    "$ref": "#/components/schemas/SubtitleResponse"
-                  }
+                  "$ref": "#/components/schemas/SubtitleListResponse"
                 }
               }
             }
@@ -8529,6 +8526,7 @@
               "integer",
               "null"
             ],
+            "format": "int32",
             "minimum": 0
           }
         }
@@ -11787,6 +11785,28 @@
         ],
         "description": "Response for accessing shared content.\nSingle-media shares return the media object directly (backwards compatible).\nCollection/Tag/SavedSearch shares return a list of items."
       },
+      "SubtitleListResponse": {
+        "type": "object",
+        "description": "Response for listing subtitles on a media item.",
+        "required": [
+          "subtitles",
+          "available_tracks"
+        ],
+        "properties": {
+          "available_tracks": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/SubtitleTrackInfoResponse"
+            }
+          },
+          "subtitles": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/SubtitleResponse"
+            }
+          }
+        }
+      },
       "SubtitleResponse": {
         "type": "object",
         "required": [
@@ -11829,10 +11849,41 @@
               "integer",
               "null"
             ],
+            "format": "int32",
             "minimum": 0
           }
         }
       },
+      "SubtitleTrackInfoResponse": {
+        "type": "object",
+        "description": "Information about an embedded subtitle track available for extraction.",
+        "required": [
+          "index",
+          "format"
+        ],
+        "properties": {
+          "format": {
+            "type": "string"
+          },
+          "index": {
+            "type": "integer",
+            "format": "int32",
+            "minimum": 0
+          },
+          "language": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "title": {
+            "type": [
+              "string",
+              "null"
+            ]
+          }
+        }
+      },
       "SyncChangeResponse": {
         "type": "object",
         "required": [

docs/api/photos.md

@@ -12,21 +12,21 @@ Get photos in a bounding box for map view
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `lat1` | query | Yes | Bounding box latitude 1 |
-| `lon1` | query | Yes | Bounding box longitude 1 |
-| `lat2` | query | Yes | Bounding box latitude 2 |
-| `lon2` | query | Yes | Bounding box longitude 2 |
+| Name   | In    | Required | Description              |
+| ------ | ----- | -------- | ------------------------ |
+| `lat1` | query | Yes      | Bounding box latitude 1  |
+| `lon1` | query | Yes      | Bounding box longitude 1 |
+| `lat2` | query | Yes      | Bounding box latitude 2  |
+| `lon2` | query | Yes      | Bounding box longitude 2 |
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Map markers |
-| 400 | Bad request |
-| 401 | Unauthorized |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | Map markers           |
+| 400    | Bad request           |
+| 401    | Unauthorized          |
+| 500    | Internal server error |
 
 ---
 
@@ -38,20 +38,19 @@ Get timeline of photos grouped by date
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `group_by` | query | No | Grouping: day, month, year |
-| `year` | query | No | Filter by year |
-| `month` | query | No | Filter by month |
-| `limit` | query | No | Max items (default 10000) |
+| Name       | In    | Required | Description                |
+| ---------- | ----- | -------- | -------------------------- |
+| `group_by` | query | No       | Grouping: day, month, year |
+| `year`     | query | No       | Filter by year             |
+| `month`    | query | No       | Filter by month            |
+| `limit`    | query | No       | Max items (default 10000)  |
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Photo timeline groups |
-| 401 | Unauthorized |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | Photo timeline groups |
+| 401    | Unauthorized          |
+| 500    | Internal server error |
 
 ---
-

docs/api/playlists.md

@@ -10,11 +10,11 @@ Media playlists
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | List of playlists |
-| 401 | Unauthorized |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | List of playlists     |
+| 401    | Unauthorized          |
+| 500    | Internal server error |
 
 ---
 
@@ -30,12 +30,12 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Playlist created |
-| 400 | Bad request |
-| 401 | Unauthorized |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | Playlist created      |
+| 400    | Bad request           |
+| 401    | Unauthorized          |
+| 500    | Internal server error |
 
 ---
 
@@ -45,18 +45,18 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `id` | path | Yes | Playlist ID |
+| Name | In   | Required | Description |
+| ---- | ---- | -------- | ----------- |
+| `id` | path | Yes      | Playlist ID |
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Playlist details |
-| 401 | Unauthorized |
-| 403 | Forbidden |
-| 404 | Not found |
+| Status | Description      |
+| ------ | ---------------- |
+| 200    | Playlist details |
+| 401    | Unauthorized     |
+| 403    | Forbidden        |
+| 404    | Not found        |
 
 ---
 
@@ -66,9 +66,9 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `id` | path | Yes | Playlist ID |
+| Name | In   | Required | Description |
+| ---- | ---- | -------- | ----------- |
+| `id` | path | Yes      | Playlist ID |
 
 #### Request Body
 
@@ -78,13 +78,13 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Playlist updated |
-| 400 | Bad request |
-| 401 | Unauthorized |
-| 403 | Forbidden |
-| 404 | Not found |
+| Status | Description      |
+| ------ | ---------------- |
+| 200    | Playlist updated |
+| 400    | Bad request      |
+| 401    | Unauthorized     |
+| 403    | Forbidden        |
+| 404    | Not found        |
 
 ---
 
@@ -94,18 +94,18 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `id` | path | Yes | Playlist ID |
+| Name | In   | Required | Description |
+| ---- | ---- | -------- | ----------- |
+| `id` | path | Yes      | Playlist ID |
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Playlist deleted |
-| 401 | Unauthorized |
-| 403 | Forbidden |
-| 404 | Not found |
+| Status | Description      |
+| ------ | ---------------- |
+| 200    | Playlist deleted |
+| 401    | Unauthorized     |
+| 403    | Forbidden        |
+| 404    | Not found        |
 
 ---
 
@@ -115,18 +115,18 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `id` | path | Yes | Playlist ID |
+| Name | In   | Required | Description |
+| ---- | ---- | -------- | ----------- |
+| `id` | path | Yes      | Playlist ID |
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Playlist items |
-| 401 | Unauthorized |
-| 403 | Forbidden |
-| 404 | Not found |
+| Status | Description    |
+| ------ | -------------- |
+| 200    | Playlist items |
+| 401    | Unauthorized   |
+| 403    | Forbidden      |
+| 404    | Not found      |
 
 ---
 
@@ -136,9 +136,9 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `id` | path | Yes | Playlist ID |
+| Name | In   | Required | Description |
+| ---- | ---- | -------- | ----------- |
+| `id` | path | Yes      | Playlist ID |
 
 #### Request Body
 
@@ -148,12 +148,12 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Item added |
-| 401 | Unauthorized |
-| 403 | Forbidden |
-| 404 | Not found |
+| Status | Description  |
+| ------ | ------------ |
+| 200    | Item added   |
+| 401    | Unauthorized |
+| 403    | Forbidden    |
+| 404    | Not found    |
 
 ---
 
@@ -163,9 +163,9 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `id` | path | Yes | Playlist ID |
+| Name | In   | Required | Description |
+| ---- | ---- | -------- | ----------- |
+| `id` | path | Yes      | Playlist ID |
 
 #### Request Body
 
@@ -175,12 +175,12 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Item reordered |
-| 401 | Unauthorized |
-| 403 | Forbidden |
-| 404 | Not found |
+| Status | Description    |
+| ------ | -------------- |
+| 200    | Item reordered |
+| 401    | Unauthorized   |
+| 403    | Forbidden      |
+| 404    | Not found      |
 
 ---
 
@@ -190,19 +190,19 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `id` | path | Yes | Playlist ID |
-| `media_id` | path | Yes | Media item ID |
+| Name       | In   | Required | Description   |
+| ---------- | ---- | -------- | ------------- |
+| `id`       | path | Yes      | Playlist ID   |
+| `media_id` | path | Yes      | Media item ID |
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Item removed |
-| 401 | Unauthorized |
-| 403 | Forbidden |
-| 404 | Not found |
+| Status | Description  |
+| ------ | ------------ |
+| 200    | Item removed |
+| 401    | Unauthorized |
+| 403    | Forbidden    |
+| 404    | Not found    |
 
 ---
 
@@ -212,18 +212,17 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `id` | path | Yes | Playlist ID |
+| Name | In   | Required | Description |
+| ---- | ---- | -------- | ----------- |
+| `id` | path | Yes      | Playlist ID |
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Shuffled playlist items |
-| 401 | Unauthorized |
-| 403 | Forbidden |
-| 404 | Not found |
+| Status | Description             |
+| ------ | ----------------------- |
+| 200    | Shuffled playlist items |
+| 401    | Unauthorized            |
+| 403    | Forbidden               |
+| 404    | Not found               |
 
 ---
-

docs/api/plugins.md

@@ -12,11 +12,11 @@ List all installed plugins
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | List of plugins |
-| 401 | Unauthorized |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | List of plugins       |
+| 401    | Unauthorized          |
+| 500    | Internal server error |
 
 ---
 
@@ -34,12 +34,12 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Plugin installed |
-| 400 | Bad request |
-| 401 | Unauthorized |
-| 403 | Forbidden |
+| Status | Description      |
+| ------ | ---------------- |
+| 200    | Plugin installed |
+| 400    | Bad request      |
+| 401    | Unauthorized     |
+| 403    | Forbidden        |
 
 ---
 
@@ -58,10 +58,10 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Event received |
-| 401 | Unauthorized |
+| Status | Description    |
+| ------ | -------------- |
+| 200    | Event received |
+| 401    | Unauthorized   |
 
 ---
 
@@ -73,10 +73,10 @@ List all UI pages provided by loaded plugins
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Plugin UI pages |
-| 401 | Unauthorized |
+| Status | Description     |
+| ------ | --------------- |
+| 200    | Plugin UI pages |
+| 401    | Unauthorized    |
 
 ---
 
@@ -88,10 +88,10 @@ List merged CSS custom property overrides from all enabled plugins
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Plugin UI theme extensions |
-| 401 | Unauthorized |
+| Status | Description                |
+| ------ | -------------------------- |
+| 200    | Plugin UI theme extensions |
+| 401    | Unauthorized               |
 
 ---
 
@@ -103,10 +103,10 @@ List all UI widgets provided by loaded plugins
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Plugin UI widgets |
-| 401 | Unauthorized |
+| Status | Description       |
+| ------ | ----------------- |
+| 200    | Plugin UI widgets |
+| 401    | Unauthorized      |
 
 ---
 
@@ -118,17 +118,17 @@ Get a specific plugin by ID
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `id` | path | Yes | Plugin ID |
+| Name | In   | Required | Description |
+| ---- | ---- | -------- | ----------- |
+| `id` | path | Yes      | Plugin ID   |
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Plugin details |
-| 401 | Unauthorized |
-| 404 | Not found |
+| Status | Description    |
+| ------ | -------------- |
+| 200    | Plugin details |
+| 401    | Unauthorized   |
+| 404    | Not found      |
 
 ---
 
@@ -140,18 +140,18 @@ Uninstall a plugin
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `id` | path | Yes | Plugin ID |
+| Name | In   | Required | Description |
+| ---- | ---- | -------- | ----------- |
+| `id` | path | Yes      | Plugin ID   |
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Plugin uninstalled |
-| 401 | Unauthorized |
-| 403 | Forbidden |
-| 404 | Not found |
+| Status | Description        |
+| ------ | ------------------ |
+| 200    | Plugin uninstalled |
+| 401    | Unauthorized       |
+| 403    | Forbidden          |
+| 404    | Not found          |
 
 ---
 
@@ -163,18 +163,18 @@ Reload a plugin (for development)
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `id` | path | Yes | Plugin ID |
+| Name | In   | Required | Description |
+| ---- | ---- | -------- | ----------- |
+| `id` | path | Yes      | Plugin ID   |
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Plugin reloaded |
-| 401 | Unauthorized |
-| 403 | Forbidden |
-| 404 | Not found |
+| Status | Description     |
+| ------ | --------------- |
+| 200    | Plugin reloaded |
+| 401    | Unauthorized    |
+| 403    | Forbidden       |
+| 404    | Not found       |
 
 ---
 
@@ -186,9 +186,9 @@ Enable or disable a plugin
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `id` | path | Yes | Plugin ID |
+| Name | In   | Required | Description |
+| ---- | ---- | -------- | ----------- |
+| `id` | path | Yes      | Plugin ID   |
 
 #### Request Body
 
@@ -198,12 +198,11 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Plugin toggled |
-| 401 | Unauthorized |
-| 403 | Forbidden |
-| 404 | Not found |
+| Status | Description    |
+| ------ | -------------- |
+| 200    | Plugin toggled |
+| 401    | Unauthorized   |
+| 403    | Forbidden      |
+| 404    | Not found      |
 
 ---
-

docs/api/saved_searches.md

@@ -10,11 +10,11 @@ Saved search queries
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | List of saved searches |
-| 401 | Unauthorized |
-| 500 | Internal server error |
+| Status | Description            |
+| ------ | ---------------------- |
+| 200    | List of saved searches |
+| 401    | Unauthorized           |
+| 500    | Internal server error  |
 
 ---
 
@@ -30,12 +30,12 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Search saved |
-| 400 | Bad request |
-| 401 | Unauthorized |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | Search saved          |
+| 400    | Bad request           |
+| 401    | Unauthorized          |
+| 500    | Internal server error |
 
 ---
 
@@ -45,18 +45,17 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `id` | path | Yes | Saved search ID |
+| Name | In   | Required | Description     |
+| ---- | ---- | -------- | --------------- |
+| `id` | path | Yes      | Saved search ID |
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Saved search deleted |
-| 401 | Unauthorized |
-| 404 | Not found |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | Saved search deleted  |
+| 401    | Unauthorized          |
+| 404    | Not found             |
+| 500    | Internal server error |
 
 ---
-

docs/api/scan.md

@@ -18,12 +18,12 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Scan job submitted |
-| 401 | Unauthorized |
-| 403 | Forbidden |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | Scan job submitted    |
+| 401    | Unauthorized          |
+| 403    | Forbidden             |
+| 500    | Internal server error |
 
 ---
 
@@ -33,10 +33,9 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Scan status |
-| 401 | Unauthorized |
+| Status | Description  |
+| ------ | ------------ |
+| 200    | Scan status  |
+| 401    | Unauthorized |
 
 ---
-

docs/api/scheduled_tasks.md

@@ -10,11 +10,11 @@ Scheduled background tasks
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | List of scheduled tasks |
-| 401 | Unauthorized |
-| 403 | Forbidden |
+| Status | Description             |
+| ------ | ----------------------- |
+| 200    | List of scheduled tasks |
+| 401    | Unauthorized            |
+| 403    | Forbidden               |
 
 ---
 
@@ -24,18 +24,18 @@ Scheduled background tasks
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `id` | path | Yes | Task ID |
+| Name | In   | Required | Description |
+| ---- | ---- | -------- | ----------- |
+| `id` | path | Yes      | Task ID     |
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Task triggered |
-| 401 | Unauthorized |
-| 403 | Forbidden |
-| 404 | Not found |
+| Status | Description    |
+| ------ | -------------- |
+| 200    | Task triggered |
+| 401    | Unauthorized   |
+| 403    | Forbidden      |
+| 404    | Not found      |
 
 ---
 
@@ -45,18 +45,17 @@ Scheduled background tasks
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `id` | path | Yes | Task ID |
+| Name | In   | Required | Description |
+| ---- | ---- | -------- | ----------- |
+| `id` | path | Yes      | Task ID     |
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Task toggled |
-| 401 | Unauthorized |
-| 403 | Forbidden |
-| 404 | Not found |
+| Status | Description  |
+| ------ | ------------ |
+| 200    | Task toggled |
+| 401    | Unauthorized |
+| 403    | Forbidden    |
+| 404    | Not found    |
 
 ---
-

docs/api/search.md

@@ -10,21 +10,21 @@ Full-text media search
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `q` | query | Yes | Search query |
-| `sort` | query | No | Sort order |
-| `offset` | query | No | Pagination offset |
-| `limit` | query | No | Pagination limit |
+| Name     | In    | Required | Description       |
+| -------- | ----- | -------- | ----------------- |
+| `q`      | query | Yes      | Search query      |
+| `sort`   | query | No       | Sort order        |
+| `offset` | query | No       | Pagination offset |
+| `limit`  | query | No       | Pagination limit  |
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Search results |
-| 400 | Bad request |
-| 401 | Unauthorized |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | Search results        |
+| 400    | Bad request           |
+| 401    | Unauthorized          |
+| 500    | Internal server error |
 
 ---
 
@@ -40,12 +40,11 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Search results |
-| 400 | Bad request |
-| 401 | Unauthorized |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | Search results        |
+| 400    | Bad request           |
+| 401    | Unauthorized          |
+| 500    | Internal server error |
 
 ---
-

docs/api/shares.md

@@ -6,86 +6,81 @@ Media sharing and notifications
 
 ### GET /api/v1/notifications/shares
 
-Get unread share notifications
-GET /api/notifications/shares
+Get unread share notifications GET /api/notifications/shares
 
 **Authentication:** Required (Bearer JWT)
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Unread notifications |
-| 401 | Unauthorized |
+| Status | Description          |
+| ------ | -------------------- |
+| 200    | Unread notifications |
+| 401    | Unauthorized         |
 
 ---
 
 ### POST /api/v1/notifications/shares/read-all
 
-Mark all notifications as read
-POST /api/notifications/shares/read-all
+Mark all notifications as read POST /api/notifications/shares/read-all
 
 **Authentication:** Required (Bearer JWT)
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | All notifications marked as read |
-| 401 | Unauthorized |
+| Status | Description                      |
+| ------ | -------------------------------- |
+| 200    | All notifications marked as read |
+| 401    | Unauthorized                     |
 
 ---
 
 ### POST /api/v1/notifications/shares/{id}/read
 
-Mark a notification as read
-POST /api/notifications/shares/{id}/read
+Mark a notification as read POST /api/notifications/shares/{id}/read
 
 **Authentication:** Required (Bearer JWT)
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `id` | path | Yes | Notification ID |
+| Name | In   | Required | Description     |
+| ---- | ---- | -------- | --------------- |
+| `id` | path | Yes      | Notification ID |
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Notification marked as read |
-| 401 | Unauthorized |
+| Status | Description                 |
+| ------ | --------------------------- |
+| 200    | Notification marked as read |
+| 401    | Unauthorized                |
 
 ---
 
 ### GET /api/v1/shared/{token}
 
-Access a public shared resource
-GET /api/shared/{token}
+Access a public shared resource GET /api/shared/{token}
 
 **Authentication:** Required (Bearer JWT)
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `token` | path | Yes | Share token |
-| `password` | query | No | Share password if required |
+| Name       | In    | Required | Description                |
+| ---------- | ----- | -------- | -------------------------- |
+| `token`    | path  | Yes      | Share token                |
+| `password` | query | No       | Share password if required |
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Shared content |
-| 401 | Unauthorized |
-| 404 | Not found |
+| Status | Description    |
+| ------ | -------------- |
+| 200    | Shared content |
+| 401    | Unauthorized   |
+| 404    | Not found      |
 
 ---
 
 ### POST /api/v1/shares
 
-Create a new share
-POST /api/shares
+Create a new share POST /api/shares
 
 **Authentication:** Required (Bearer JWT)
 
@@ -97,19 +92,18 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Share created |
-| 400 | Bad request |
-| 401 | Unauthorized |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | Share created         |
+| 400    | Bad request           |
+| 401    | Unauthorized          |
+| 500    | Internal server error |
 
 ---
 
 ### POST /api/v1/shares/batch/delete
 
-Batch delete shares
-POST /api/shares/batch/delete
+Batch delete shares POST /api/shares/batch/delete
 
 **Authentication:** Required (Bearer JWT)
 
@@ -121,97 +115,93 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Shares deleted |
-| 400 | Bad request |
-| 401 | Unauthorized |
-| 403 | Forbidden |
+| Status | Description    |
+| ------ | -------------- |
+| 200    | Shares deleted |
+| 400    | Bad request    |
+| 401    | Unauthorized   |
+| 403    | Forbidden      |
 
 ---
 
 ### GET /api/v1/shares/incoming
 
-List incoming shares (shares shared with me)
-GET /api/shares/incoming
+List incoming shares (shares shared with me) GET /api/shares/incoming
 
 **Authentication:** Required (Bearer JWT)
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `offset` | query | No | Pagination offset |
-| `limit` | query | No | Pagination limit |
+| Name     | In    | Required | Description       |
+| -------- | ----- | -------- | ----------------- |
+| `offset` | query | No       | Pagination offset |
+| `limit`  | query | No       | Pagination limit  |
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Incoming shares |
-| 401 | Unauthorized |
+| Status | Description     |
+| ------ | --------------- |
+| 200    | Incoming shares |
+| 401    | Unauthorized    |
 
 ---
 
 ### GET /api/v1/shares/outgoing
 
-List outgoing shares (shares I created)
-GET /api/shares/outgoing
+List outgoing shares (shares I created) GET /api/shares/outgoing
 
 **Authentication:** Required (Bearer JWT)
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `offset` | query | No | Pagination offset |
-| `limit` | query | No | Pagination limit |
+| Name     | In    | Required | Description       |
+| -------- | ----- | -------- | ----------------- |
+| `offset` | query | No       | Pagination offset |
+| `limit`  | query | No       | Pagination limit  |
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Outgoing shares |
-| 401 | Unauthorized |
+| Status | Description     |
+| ------ | --------------- |
+| 200    | Outgoing shares |
+| 401    | Unauthorized    |
 
 ---
 
 ### GET /api/v1/shares/{id}
 
-Get share details
-GET /api/shares/{id}
+Get share details GET /api/shares/{id}
 
 **Authentication:** Required (Bearer JWT)
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `id` | path | Yes | Share ID |
+| Name | In   | Required | Description |
+| ---- | ---- | -------- | ----------- |
+| `id` | path | Yes      | Share ID    |
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Share details |
-| 401 | Unauthorized |
-| 403 | Forbidden |
-| 404 | Not found |
+| Status | Description   |
+| ------ | ------------- |
+| 200    | Share details |
+| 401    | Unauthorized  |
+| 403    | Forbidden     |
+| 404    | Not found     |
 
 ---
 
 ### PATCH /api/v1/shares/{id}
 
-Update a share
-PATCH /api/shares/{id}
+Update a share PATCH /api/shares/{id}
 
 **Authentication:** Required (Bearer JWT)
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `id` | path | Yes | Share ID |
+| Name | In   | Required | Description |
+| ---- | ---- | -------- | ----------- |
+| `id` | path | Yes      | Share ID    |
 
 #### Request Body
 
@@ -221,62 +211,59 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Share updated |
-| 401 | Unauthorized |
-| 403 | Forbidden |
-| 404 | Not found |
+| Status | Description   |
+| ------ | ------------- |
+| 200    | Share updated |
+| 401    | Unauthorized  |
+| 403    | Forbidden     |
+| 404    | Not found     |
 
 ---
 
 ### DELETE /api/v1/shares/{id}
 
-Delete (revoke) a share
-DELETE /api/shares/{id}
+Delete (revoke) a share DELETE /api/shares/{id}
 
 **Authentication:** Required (Bearer JWT)
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `id` | path | Yes | Share ID |
+| Name | In   | Required | Description |
+| ---- | ---- | -------- | ----------- |
+| `id` | path | Yes      | Share ID    |
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 204 | Share deleted |
-| 401 | Unauthorized |
-| 403 | Forbidden |
-| 404 | Not found |
+| Status | Description   |
+| ------ | ------------- |
+| 204    | Share deleted |
+| 401    | Unauthorized  |
+| 403    | Forbidden     |
+| 404    | Not found     |
 
 ---
 
 ### GET /api/v1/shares/{id}/activity
 
-Get share activity log
-GET /api/shares/{id}/activity
+Get share activity log GET /api/shares/{id}/activity
 
 **Authentication:** Required (Bearer JWT)
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `id` | path | Yes | Share ID |
-| `offset` | query | No | Pagination offset |
-| `limit` | query | No | Pagination limit |
+| Name     | In    | Required | Description       |
+| -------- | ----- | -------- | ----------------- |
+| `id`     | path  | Yes      | Share ID          |
+| `offset` | query | No       | Pagination offset |
+| `limit`  | query | No       | Pagination limit  |
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Share activity |
-| 401 | Unauthorized |
-| 403 | Forbidden |
-| 404 | Not found |
+| Status | Description    |
+| ------ | -------------- |
+| 200    | Share activity |
+| 401    | Unauthorized   |
+| 403    | Forbidden      |
+| 404    | Not found      |
 
 ---
-

docs/api/social.md

@@ -10,11 +10,11 @@ Ratings, comments, favorites, and share links
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | User favorites |
-| 401 | Unauthorized |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | User favorites        |
+| 401    | Unauthorized          |
+| 500    | Internal server error |
 
 ---
 
@@ -30,11 +30,11 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Added to favorites |
-| 401 | Unauthorized |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | Added to favorites    |
+| 401    | Unauthorized          |
+| 500    | Internal server error |
 
 ---
 
@@ -44,17 +44,17 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `media_id` | path | Yes | Media item ID |
+| Name       | In   | Required | Description   |
+| ---------- | ---- | -------- | ------------- |
+| `media_id` | path | Yes      | Media item ID |
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Removed from favorites |
-| 401 | Unauthorized |
-| 500 | Internal server error |
+| Status | Description            |
+| ------ | ---------------------- |
+| 200    | Removed from favorites |
+| 401    | Unauthorized           |
+| 500    | Internal server error  |
 
 ---
 
@@ -70,12 +70,12 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Share link created |
-| 400 | Bad request |
-| 401 | Unauthorized |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | Share link created    |
+| 400    | Bad request           |
+| 401    | Unauthorized          |
+| 500    | Internal server error |
 
 ---
 
@@ -85,17 +85,17 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `id` | path | Yes | Media item ID |
+| Name | In   | Required | Description   |
+| ---- | ---- | -------- | ------------- |
+| `id` | path | Yes      | Media item ID |
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Media comments |
-| 401 | Unauthorized |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | Media comments        |
+| 401    | Unauthorized          |
+| 500    | Internal server error |
 
 ---
 
@@ -105,9 +105,9 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `id` | path | Yes | Media item ID |
+| Name | In   | Required | Description   |
+| ---- | ---- | -------- | ------------- |
+| `id` | path | Yes      | Media item ID |
 
 #### Request Body
 
@@ -117,12 +117,12 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Comment added |
-| 400 | Bad request |
-| 401 | Unauthorized |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | Comment added         |
+| 400    | Bad request           |
+| 401    | Unauthorized          |
+| 500    | Internal server error |
 
 ---
 
@@ -132,9 +132,9 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `id` | path | Yes | Media item ID |
+| Name | In   | Required | Description   |
+| ---- | ---- | -------- | ------------- |
+| `id` | path | Yes      | Media item ID |
 
 #### Request Body
 
@@ -144,12 +144,12 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Rating saved |
-| 400 | Bad request |
-| 401 | Unauthorized |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | Rating saved          |
+| 400    | Bad request           |
+| 401    | Unauthorized          |
+| 500    | Internal server error |
 
 ---
 
@@ -159,17 +159,17 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `id` | path | Yes | Media item ID |
+| Name | In   | Required | Description   |
+| ---- | ---- | -------- | ------------- |
+| `id` | path | Yes      | Media item ID |
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Media ratings |
-| 401 | Unauthorized |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | Media ratings         |
+| 401    | Unauthorized          |
+| 500    | Internal server error |
 
 ---
 
@@ -179,18 +179,17 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `token` | path | Yes | Share token |
-| `password` | query | No | Share password |
+| Name       | In    | Required | Description    |
+| ---------- | ----- | -------- | -------------- |
+| `token`    | path  | Yes      | Share token    |
+| `password` | query | No       | Share password |
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Shared media |
-| 401 | Unauthorized |
-| 404 | Not found |
+| Status | Description  |
+| ------ | ------------ |
+| 200    | Shared media |
+| 401    | Unauthorized |
+| 404    | Not found    |
 
 ---
-

docs/api/statistics.md

@@ -10,11 +10,10 @@ Library statistics
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Library statistics |
-| 401 | Unauthorized |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | Library statistics    |
+| 401    | Unauthorized          |
+| 500    | Internal server error |
 
 ---
-

docs/api/streaming.md

@@ -10,18 +10,18 @@ HLS and DASH adaptive streaming
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `id` | path | Yes | Media item ID |
+| Name | In   | Required | Description   |
+| ---- | ---- | -------- | ------------- |
+| `id` | path | Yes      | Media item ID |
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | DASH manifest |
-| 400 | Bad request |
-| 401 | Unauthorized |
-| 404 | Not found |
+| Status | Description   |
+| ------ | ------------- |
+| 200    | DASH manifest |
+| 400    | Bad request   |
+| 401    | Unauthorized  |
+| 404    | Not found     |
 
 ---
 
@@ -31,20 +31,20 @@ HLS and DASH adaptive streaming
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `id` | path | Yes | Media item ID |
-| `profile` | path | Yes | Transcode profile name |
-| `segment` | path | Yes | Segment filename |
+| Name      | In   | Required | Description            |
+| --------- | ---- | -------- | ---------------------- |
+| `id`      | path | Yes      | Media item ID          |
+| `profile` | path | Yes      | Transcode profile name |
+| `segment` | path | Yes      | Segment filename       |
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | DASH segment data |
-| 202 | Segment not yet available |
-| 400 | Bad request |
-| 401 | Unauthorized |
+| Status | Description               |
+| ------ | ------------------------- |
+| 200    | DASH segment data         |
+| 202    | Segment not yet available |
+| 400    | Bad request               |
+| 401    | Unauthorized              |
 
 ---
 
@@ -54,17 +54,17 @@ HLS and DASH adaptive streaming
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `id` | path | Yes | Media item ID |
+| Name | In   | Required | Description   |
+| ---- | ---- | -------- | ------------- |
+| `id` | path | Yes      | Media item ID |
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | HLS master playlist |
-| 401 | Unauthorized |
-| 404 | Not found |
+| Status | Description         |
+| ------ | ------------------- |
+| 200    | HLS master playlist |
+| 401    | Unauthorized        |
+| 404    | Not found           |
 
 ---
 
@@ -74,19 +74,19 @@ HLS and DASH adaptive streaming
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `id` | path | Yes | Media item ID |
-| `profile` | path | Yes | Transcode profile name |
+| Name      | In   | Required | Description            |
+| --------- | ---- | -------- | ---------------------- |
+| `id`      | path | Yes      | Media item ID          |
+| `profile` | path | Yes      | Transcode profile name |
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | HLS variant playlist |
-| 400 | Bad request |
-| 401 | Unauthorized |
-| 404 | Not found |
+| Status | Description          |
+| ------ | -------------------- |
+| 200    | HLS variant playlist |
+| 400    | Bad request          |
+| 401    | Unauthorized         |
+| 404    | Not found            |
 
 ---
 
@@ -96,20 +96,19 @@ HLS and DASH adaptive streaming
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `id` | path | Yes | Media item ID |
-| `profile` | path | Yes | Transcode profile name |
-| `segment` | path | Yes | Segment filename |
+| Name      | In   | Required | Description            |
+| --------- | ---- | -------- | ---------------------- |
+| `id`      | path | Yes      | Media item ID          |
+| `profile` | path | Yes      | Transcode profile name |
+| `segment` | path | Yes      | Segment filename       |
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | HLS segment data |
-| 202 | Segment not yet available |
-| 400 | Bad request |
-| 401 | Unauthorized |
+| Status | Description               |
+| ------ | ------------------------- |
+| 200    | HLS segment data          |
+| 202    | Segment not yet available |
+| 400    | Bad request               |
+| 401    | Unauthorized              |
 
 ---
-

docs/api/subtitles.md

@@ -10,17 +10,17 @@ Media subtitle management
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `id` | path | Yes | Media item ID |
+| Name | In   | Required | Description   |
+| ---- | ---- | -------- | ------------- |
+| `id` | path | Yes      | Media item ID |
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Subtitles |
-| 401 | Unauthorized |
-| 404 | Not found |
+| Status | Description                             |
+| ------ | --------------------------------------- |
+| 200    | Subtitles and available embedded tracks |
+| 401    | Unauthorized                            |
+| 404    | Not found                               |
 
 ---
 
@@ -30,9 +30,9 @@ Media subtitle management
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `id` | path | Yes | Media item ID |
+| Name | In   | Required | Description   |
+| ---- | ---- | -------- | ------------- |
+| `id` | path | Yes      | Media item ID |
 
 #### Request Body
 
@@ -42,12 +42,12 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Subtitle added |
-| 400 | Bad request |
-| 401 | Unauthorized |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | Subtitle added        |
+| 400    | Bad request           |
+| 401    | Unauthorized          |
+| 500    | Internal server error |
 
 ---
 
@@ -57,18 +57,18 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `media_id` | path | Yes | Media item ID |
-| `subtitle_id` | path | Yes | Subtitle ID |
+| Name          | In   | Required | Description   |
+| ------------- | ---- | -------- | ------------- |
+| `media_id`    | path | Yes      | Media item ID |
+| `subtitle_id` | path | Yes      | Subtitle ID   |
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Subtitle content |
-| 401 | Unauthorized |
-| 404 | Not found |
+| Status | Description      |
+| ------ | ---------------- |
+| 200    | Subtitle content |
+| 401    | Unauthorized     |
+| 404    | Not found        |
 
 ---
 
@@ -78,17 +78,17 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `id` | path | Yes | Subtitle ID |
+| Name | In   | Required | Description |
+| ---- | ---- | -------- | ----------- |
+| `id` | path | Yes      | Subtitle ID |
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Subtitle deleted |
-| 401 | Unauthorized |
-| 404 | Not found |
+| Status | Description      |
+| ------ | ---------------- |
+| 200    | Subtitle deleted |
+| 401    | Unauthorized     |
+| 404    | Not found        |
 
 ---
 
@@ -98,9 +98,9 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `id` | path | Yes | Subtitle ID |
+| Name | In   | Required | Description |
+| ---- | ---- | -------- | ----------- |
+| `id` | path | Yes      | Subtitle ID |
 
 #### Request Body
 
@@ -110,11 +110,10 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Offset updated |
-| 401 | Unauthorized |
-| 404 | Not found |
+| Status | Description    |
+| ------ | -------------- |
+| 200    | Offset updated |
+| 401    | Unauthorized   |
+| 404    | Not found      |
 
 ---
-

docs/api/sync.md

@@ -6,8 +6,7 @@ Multi-device library synchronization
 
 ### POST /api/v1/sync/ack
 
-Acknowledge processed changes
-POST /api/sync/ack
+Acknowledge processed changes POST /api/sync/ack
 
 **Authentication:** Required (Bearer JWT)
 
@@ -19,66 +18,63 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Changes acknowledged |
-| 400 | Bad request |
-| 401 | Unauthorized |
+| Status | Description          |
+| ------ | -------------------- |
+| 200    | Changes acknowledged |
+| 400    | Bad request          |
+| 401    | Unauthorized         |
 
 ---
 
 ### GET /api/v1/sync/changes
 
-Get changes since cursor
-GET /api/sync/changes
+Get changes since cursor GET /api/sync/changes
 
 **Authentication:** Required (Bearer JWT)
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `cursor` | query | No | Sync cursor |
-| `limit` | query | No | Max changes (max 1000) |
+| Name     | In    | Required | Description            |
+| -------- | ----- | -------- | ---------------------- |
+| `cursor` | query | No       | Sync cursor            |
+| `limit`  | query | No       | Max changes (max 1000) |
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Changes since cursor |
-| 400 | Bad request |
-| 401 | Unauthorized |
+| Status | Description          |
+| ------ | -------------------- |
+| 200    | Changes since cursor |
+| 400    | Bad request          |
+| 401    | Unauthorized         |
 
 ---
 
 ### GET /api/v1/sync/conflicts
 
-List unresolved conflicts
-GET /api/sync/conflicts
+List unresolved conflicts GET /api/sync/conflicts
 
 **Authentication:** Required (Bearer JWT)
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Unresolved conflicts |
-| 401 | Unauthorized |
+| Status | Description          |
+| ------ | -------------------- |
+| 200    | Unresolved conflicts |
+| 401    | Unauthorized         |
 
 ---
 
 ### POST /api/v1/sync/conflicts/{id}/resolve
 
-Resolve a sync conflict
-POST /api/sync/conflicts/{id}/resolve
+Resolve a sync conflict POST /api/sync/conflicts/{id}/resolve
 
 **Authentication:** Required (Bearer JWT)
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `id` | path | Yes | Conflict ID |
+| Name | In   | Required | Description |
+| ---- | ---- | -------- | ----------- |
+| `id` | path | Yes      | Conflict ID |
 
 #### Request Body
 
@@ -88,34 +84,32 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Conflict resolved |
-| 400 | Bad request |
-| 401 | Unauthorized |
+| Status | Description       |
+| ------ | ----------------- |
+| 200    | Conflict resolved |
+| 400    | Bad request       |
+| 401    | Unauthorized      |
 
 ---
 
 ### GET /api/v1/sync/devices
 
-List user's sync devices
-GET /api/sync/devices
+List user's sync devices GET /api/sync/devices
 
 **Authentication:** Required (Bearer JWT)
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | List of devices |
-| 401 | Unauthorized |
+| Status | Description     |
+| ------ | --------------- |
+| 200    | List of devices |
+| 401    | Unauthorized    |
 
 ---
 
 ### POST /api/v1/sync/devices
 
-Register a new sync device
-POST /api/sync/devices
+Register a new sync device POST /api/sync/devices
 
 **Authentication:** Required (Bearer JWT)
 
@@ -127,51 +121,49 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Device registered |
-| 400 | Bad request |
-| 401 | Unauthorized |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | Device registered     |
+| 400    | Bad request           |
+| 401    | Unauthorized          |
+| 500    | Internal server error |
 
 ---
 
 ### GET /api/v1/sync/devices/{id}
 
-Get device details
-GET /api/sync/devices/{id}
+Get device details GET /api/sync/devices/{id}
 
 **Authentication:** Required (Bearer JWT)
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `id` | path | Yes | Device ID |
+| Name | In   | Required | Description |
+| ---- | ---- | -------- | ----------- |
+| `id` | path | Yes      | Device ID   |
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Device details |
-| 401 | Unauthorized |
-| 403 | Forbidden |
-| 404 | Not found |
+| Status | Description    |
+| ------ | -------------- |
+| 200    | Device details |
+| 401    | Unauthorized   |
+| 403    | Forbidden      |
+| 404    | Not found      |
 
 ---
 
 ### PUT /api/v1/sync/devices/{id}
 
-Update a device
-PUT /api/sync/devices/{id}
+Update a device PUT /api/sync/devices/{id}
 
 **Authentication:** Required (Bearer JWT)
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `id` | path | Yes | Device ID |
+| Name | In   | Required | Description |
+| ---- | ---- | -------- | ----------- |
+| `id` | path | Yes      | Device ID   |
 
 #### Request Body
 
@@ -181,91 +173,87 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Device updated |
-| 401 | Unauthorized |
-| 403 | Forbidden |
-| 404 | Not found |
+| Status | Description    |
+| ------ | -------------- |
+| 200    | Device updated |
+| 401    | Unauthorized   |
+| 403    | Forbidden      |
+| 404    | Not found      |
 
 ---
 
 ### DELETE /api/v1/sync/devices/{id}
 
-Delete a device
-DELETE /api/sync/devices/{id}
+Delete a device DELETE /api/sync/devices/{id}
 
 **Authentication:** Required (Bearer JWT)
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `id` | path | Yes | Device ID |
+| Name | In   | Required | Description |
+| ---- | ---- | -------- | ----------- |
+| `id` | path | Yes      | Device ID   |
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 204 | Device deleted |
-| 401 | Unauthorized |
-| 403 | Forbidden |
-| 404 | Not found |
+| Status | Description    |
+| ------ | -------------- |
+| 204    | Device deleted |
+| 401    | Unauthorized   |
+| 403    | Forbidden      |
+| 404    | Not found      |
 
 ---
 
 ### POST /api/v1/sync/devices/{id}/token
 
-Regenerate device token
-POST /api/sync/devices/{id}/token
+Regenerate device token POST /api/sync/devices/{id}/token
 
 **Authentication:** Required (Bearer JWT)
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `id` | path | Yes | Device ID |
+| Name | In   | Required | Description |
+| ---- | ---- | -------- | ----------- |
+| `id` | path | Yes      | Device ID   |
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Token regenerated |
-| 401 | Unauthorized |
-| 403 | Forbidden |
-| 404 | Not found |
+| Status | Description       |
+| ------ | ----------------- |
+| 200    | Token regenerated |
+| 401    | Unauthorized      |
+| 403    | Forbidden         |
+| 404    | Not found         |
 
 ---
 
 ### GET /api/v1/sync/download/{path}
 
-Download a file for sync (supports Range header)
-GET /api/sync/download/{*path}
+Download a file for sync (supports Range header) GET /api/sync/download/{*path}
 
 **Authentication:** Required (Bearer JWT)
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `path` | path | Yes | File path |
+| Name   | In   | Required | Description |
+| ------ | ---- | -------- | ----------- |
+| `path` | path | Yes      | File path   |
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | File content |
-| 206 | Partial content |
-| 401 | Unauthorized |
-| 404 | Not found |
+| Status | Description     |
+| ------ | --------------- |
+| 200    | File content    |
+| 206    | Partial content |
+| 401    | Unauthorized    |
+| 404    | Not found       |
 
 ---
 
 ### POST /api/v1/sync/report
 
-Report local changes from client
-POST /api/sync/report
+Report local changes from client POST /api/sync/report
 
 **Authentication:** Required (Bearer JWT)
 
@@ -277,18 +265,17 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Changes processed |
-| 400 | Bad request |
-| 401 | Unauthorized |
+| Status | Description       |
+| ------ | ----------------- |
+| 200    | Changes processed |
+| 400    | Bad request       |
+| 401    | Unauthorized      |
 
 ---
 
 ### POST /api/v1/sync/upload
 
-Create an upload session for chunked upload
-POST /api/sync/upload
+Create an upload session for chunked upload POST /api/sync/upload
 
 **Authentication:** Required (Bearer JWT)
 
@@ -300,113 +287,107 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Upload session created |
-| 400 | Bad request |
-| 401 | Unauthorized |
+| Status | Description            |
+| ------ | ---------------------- |
+| 200    | Upload session created |
+| 400    | Bad request            |
+| 401    | Unauthorized           |
 
 ---
 
 ### GET /api/v1/sync/upload/{id}
 
-Get upload session status
-GET /api/sync/upload/{id}
+Get upload session status GET /api/sync/upload/{id}
 
 **Authentication:** Required (Bearer JWT)
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `id` | path | Yes | Upload session ID |
+| Name | In   | Required | Description       |
+| ---- | ---- | -------- | ----------------- |
+| `id` | path | Yes      | Upload session ID |
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Upload session status |
-| 401 | Unauthorized |
-| 404 | Not found |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | Upload session status |
+| 401    | Unauthorized          |
+| 404    | Not found             |
 
 ---
 
 ### DELETE /api/v1/sync/upload/{id}
 
-Cancel an upload session
-DELETE /api/sync/upload/{id}
+Cancel an upload session DELETE /api/sync/upload/{id}
 
 **Authentication:** Required (Bearer JWT)
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `id` | path | Yes | Upload session ID |
+| Name | In   | Required | Description       |
+| ---- | ---- | -------- | ----------------- |
+| `id` | path | Yes      | Upload session ID |
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 204 | Upload cancelled |
-| 401 | Unauthorized |
-| 404 | Not found |
+| Status | Description      |
+| ------ | ---------------- |
+| 204    | Upload cancelled |
+| 401    | Unauthorized     |
+| 404    | Not found        |
 
 ---
 
 ### PUT /api/v1/sync/upload/{id}/chunks/{index}
 
-Upload a chunk
-PUT /api/sync/upload/{id}/chunks/{index}
+Upload a chunk PUT /api/sync/upload/{id}/chunks/{index}
 
 **Authentication:** Required (Bearer JWT)
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `id` | path | Yes | Upload session ID |
-| `index` | path | Yes | Chunk index |
+| Name    | In   | Required | Description       |
+| ------- | ---- | -------- | ----------------- |
+| `id`    | path | Yes      | Upload session ID |
+| `index` | path | Yes      | Chunk index       |
 
 #### Request Body
 
-Chunk binary data
-`Content-Type: application/octet-stream`
+Chunk binary data `Content-Type: application/octet-stream`
 
 See `docs/api/openapi.json` for the full schema.
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Chunk received |
-| 400 | Bad request |
-| 401 | Unauthorized |
-| 404 | Not found |
+| Status | Description    |
+| ------ | -------------- |
+| 200    | Chunk received |
+| 400    | Bad request    |
+| 401    | Unauthorized   |
+| 404    | Not found      |
 
 ---
 
 ### POST /api/v1/sync/upload/{id}/complete
 
-Complete an upload session
-POST /api/sync/upload/{id}/complete
+Complete an upload session POST /api/sync/upload/{id}/complete
 
 **Authentication:** Required (Bearer JWT)
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `id` | path | Yes | Upload session ID |
+| Name | In   | Required | Description       |
+| ---- | ---- | -------- | ----------------- |
+| `id` | path | Yes      | Upload session ID |
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Upload completed |
-| 400 | Bad request |
-| 401 | Unauthorized |
-| 404 | Not found |
+| Status | Description      |
+| ------ | ---------------- |
+| 200    | Upload completed |
+| 400    | Bad request      |
+| 401    | Unauthorized     |
+| 404    | Not found        |
 
 ---
-

docs/api/tags.md

@@ -10,18 +10,18 @@ Media tag management
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `media_id` | path | Yes | Media item ID |
+| Name       | In   | Required | Description   |
+| ---------- | ---- | -------- | ------------- |
+| `media_id` | path | Yes      | Media item ID |
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Media tags |
-| 401 | Unauthorized |
-| 404 | Not found |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | Media tags            |
+| 401    | Unauthorized          |
+| 404    | Not found             |
+| 500    | Internal server error |
 
 ---
 
@@ -31,9 +31,9 @@ Media tag management
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `media_id` | path | Yes | Media item ID |
+| Name       | In   | Required | Description   |
+| ---------- | ---- | -------- | ------------- |
+| `media_id` | path | Yes      | Media item ID |
 
 #### Request Body
 
@@ -43,13 +43,13 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Tag applied |
-| 401 | Unauthorized |
-| 403 | Forbidden |
-| 404 | Not found |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | Tag applied           |
+| 401    | Unauthorized          |
+| 403    | Forbidden             |
+| 404    | Not found             |
+| 500    | Internal server error |
 
 ---
 
@@ -59,20 +59,20 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `media_id` | path | Yes | Media item ID |
-| `tag_id` | path | Yes | Tag ID |
+| Name       | In   | Required | Description   |
+| ---------- | ---- | -------- | ------------- |
+| `media_id` | path | Yes      | Media item ID |
+| `tag_id`   | path | Yes      | Tag ID        |
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Tag removed |
-| 401 | Unauthorized |
-| 403 | Forbidden |
-| 404 | Not found |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | Tag removed           |
+| 401    | Unauthorized          |
+| 403    | Forbidden             |
+| 404    | Not found             |
+| 500    | Internal server error |
 
 ---
 
@@ -82,11 +82,11 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | List of tags |
-| 401 | Unauthorized |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | List of tags          |
+| 401    | Unauthorized          |
+| 500    | Internal server error |
 
 ---
 
@@ -102,13 +102,13 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Tag created |
-| 400 | Bad request |
-| 401 | Unauthorized |
-| 403 | Forbidden |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | Tag created           |
+| 400    | Bad request           |
+| 401    | Unauthorized          |
+| 403    | Forbidden             |
+| 500    | Internal server error |
 
 ---
 
@@ -118,18 +118,18 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `id` | path | Yes | Tag ID |
+| Name | In   | Required | Description |
+| ---- | ---- | -------- | ----------- |
+| `id` | path | Yes      | Tag ID      |
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Tag |
-| 401 | Unauthorized |
-| 404 | Not found |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | Tag                   |
+| 401    | Unauthorized          |
+| 404    | Not found             |
+| 500    | Internal server error |
 
 ---
 
@@ -139,19 +139,18 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `id` | path | Yes | Tag ID |
+| Name | In   | Required | Description |
+| ---- | ---- | -------- | ----------- |
+| `id` | path | Yes      | Tag ID      |
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Tag deleted |
-| 401 | Unauthorized |
-| 403 | Forbidden |
-| 404 | Not found |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | Tag deleted           |
+| 401    | Unauthorized          |
+| 403    | Forbidden             |
+| 404    | Not found             |
+| 500    | Internal server error |
 
 ---
-

docs/api/transcode.md

@@ -10,9 +10,9 @@ Video transcoding sessions
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `id` | path | Yes | Media item ID |
+| Name | In   | Required | Description   |
+| ---- | ---- | -------- | ------------- |
+| `id` | path | Yes      | Media item ID |
 
 #### Request Body
 
@@ -22,12 +22,12 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Transcode job submitted |
-| 400 | Bad request |
-| 401 | Unauthorized |
-| 500 | Internal server error |
+| Status | Description             |
+| ------ | ----------------------- |
+| 200    | Transcode job submitted |
+| 400    | Bad request             |
+| 401    | Unauthorized            |
+| 500    | Internal server error   |
 
 ---
 
@@ -37,10 +37,10 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | List of transcode sessions |
-| 401 | Unauthorized |
+| Status | Description                |
+| ------ | -------------------------- |
+| 200    | List of transcode sessions |
+| 401    | Unauthorized               |
 
 ---
 
@@ -50,17 +50,17 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `id` | path | Yes | Transcode session ID |
+| Name | In   | Required | Description          |
+| ---- | ---- | -------- | -------------------- |
+| `id` | path | Yes      | Transcode session ID |
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Transcode session details |
-| 401 | Unauthorized |
-| 404 | Not found |
+| Status | Description               |
+| ------ | ------------------------- |
+| 200    | Transcode session details |
+| 401    | Unauthorized              |
+| 404    | Not found                 |
 
 ---
 
@@ -70,17 +70,16 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `id` | path | Yes | Transcode session ID |
+| Name | In   | Required | Description          |
+| ---- | ---- | -------- | -------------------- |
+| `id` | path | Yes      | Transcode session ID |
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Transcode session cancelled |
-| 401 | Unauthorized |
-| 404 | Not found |
+| Status | Description                 |
+| ------ | --------------------------- |
+| 200    | Transcode session cancelled |
+| 401    | Unauthorized                |
+| 404    | Not found                   |
 
 ---
-

docs/api/upload.md

@@ -6,84 +6,79 @@ File upload and managed storage
 
 ### GET /api/v1/managed/stats
 
-Get managed storage statistics
-GET /api/managed/stats
+Get managed storage statistics GET /api/managed/stats
 
 **Authentication:** Required (Bearer JWT)
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Managed storage statistics |
-| 401 | Unauthorized |
-| 500 | Internal server error |
+| Status | Description                |
+| ------ | -------------------------- |
+| 200    | Managed storage statistics |
+| 401    | Unauthorized               |
+| 500    | Internal server error      |
 
 ---
 
 ### GET /api/v1/media/{id}/download
 
-Download a managed file
-GET /api/media/{id}/download
+Download a managed file GET /api/media/{id}/download
 
 **Authentication:** Required (Bearer JWT)
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `id` | path | Yes | Media item ID |
+| Name | In   | Required | Description   |
+| ---- | ---- | -------- | ------------- |
+| `id` | path | Yes      | Media item ID |
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | File content |
-| 400 | Bad request |
-| 401 | Unauthorized |
-| 404 | Not found |
+| Status | Description  |
+| ------ | ------------ |
+| 200    | File content |
+| 400    | Bad request  |
+| 401    | Unauthorized |
+| 404    | Not found    |
 
 ---
 
 ### POST /api/v1/media/{id}/move-to-managed
 
-Migrate an external file to managed storage
-POST /api/media/{id}/move-to-managed
+Migrate an external file to managed storage POST /api/media/{id}/move-to-managed
 
 **Authentication:** Required (Bearer JWT)
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `id` | path | Yes | Media item ID |
+| Name | In   | Required | Description   |
+| ---- | ---- | -------- | ------------- |
+| `id` | path | Yes      | Media item ID |
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 204 | File migrated |
-| 400 | Bad request |
-| 401 | Unauthorized |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 204    | File migrated         |
+| 400    | Bad request           |
+| 401    | Unauthorized          |
+| 500    | Internal server error |
 
 ---
 
 ### POST /api/v1/upload
 
-Upload a file to managed storage
-POST /api/upload
+Upload a file to managed storage POST /api/upload
 
 **Authentication:** Required (Bearer JWT)
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | File uploaded |
-| 400 | Bad request |
-| 401 | Unauthorized |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | File uploaded         |
+| 400    | Bad request           |
+| 401    | Unauthorized          |
+| 500    | Internal server error |
 
 ---
-

docs/api/users.md

@@ -12,11 +12,11 @@ List all users (admin only)
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | List of users |
-| 401 | Unauthorized |
-| 403 | Forbidden |
+| Status | Description   |
+| ------ | ------------- |
+| 200    | List of users |
+| 401    | Unauthorized  |
+| 403    | Forbidden     |
 
 ---
 
@@ -35,13 +35,13 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | User created |
-| 400 | Bad request |
-| 401 | Unauthorized |
-| 403 | Forbidden |
-| 500 | Internal server error |
+| Status | Description           |
+| ------ | --------------------- |
+| 200    | User created          |
+| 400    | Bad request           |
+| 401    | Unauthorized          |
+| 403    | Forbidden             |
+| 500    | Internal server error |
 
 ---
 
@@ -53,18 +53,18 @@ Get a specific user by ID
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `id` | path | Yes | User ID |
+| Name | In   | Required | Description |
+| ---- | ---- | -------- | ----------- |
+| `id` | path | Yes      | User ID     |
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | User details |
-| 401 | Unauthorized |
-| 403 | Forbidden |
-| 404 | Not found |
+| Status | Description  |
+| ------ | ------------ |
+| 200    | User details |
+| 401    | Unauthorized |
+| 403    | Forbidden    |
+| 404    | Not found    |
 
 ---
 
@@ -76,9 +76,9 @@ Update a user
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `id` | path | Yes | User ID |
+| Name | In   | Required | Description |
+| ---- | ---- | -------- | ----------- |
+| `id` | path | Yes      | User ID     |
 
 #### Request Body
 
@@ -89,13 +89,13 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | User updated |
-| 400 | Bad request |
-| 401 | Unauthorized |
-| 403 | Forbidden |
-| 404 | Not found |
+| Status | Description  |
+| ------ | ------------ |
+| 200    | User updated |
+| 400    | Bad request  |
+| 401    | Unauthorized |
+| 403    | Forbidden    |
+| 404    | Not found    |
 
 ---
 
@@ -107,18 +107,18 @@ Delete a user (admin only)
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `id` | path | Yes | User ID |
+| Name | In   | Required | Description |
+| ---- | ---- | -------- | ----------- |
+| `id` | path | Yes      | User ID     |
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | User deleted |
-| 401 | Unauthorized |
-| 403 | Forbidden |
-| 404 | Not found |
+| Status | Description  |
+| ------ | ------------ |
+| 200    | User deleted |
+| 401    | Unauthorized |
+| 403    | Forbidden    |
+| 404    | Not found    |
 
 ---
 
@@ -130,17 +130,17 @@ Get user's accessible libraries
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `id` | path | Yes | User ID |
+| Name | In   | Required | Description |
+| ---- | ---- | -------- | ----------- |
+| `id` | path | Yes      | User ID     |
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | User libraries |
-| 401 | Unauthorized |
-| 403 | Forbidden |
+| Status | Description    |
+| ------ | -------------- |
+| 200    | User libraries |
+| 401    | Unauthorized   |
+| 403    | Forbidden      |
 
 ---
 
@@ -152,9 +152,9 @@ Grant library access to a user (admin only)
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `id` | path | Yes | User ID |
+| Name | In   | Required | Description |
+| ---- | ---- | -------- | ----------- |
+| `id` | path | Yes      | User ID     |
 
 #### Request Body
 
@@ -164,12 +164,12 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Access granted |
-| 400 | Bad request |
-| 401 | Unauthorized |
-| 403 | Forbidden |
+| Status | Description    |
+| ------ | -------------- |
+| 200    | Access granted |
+| 400    | Bad request    |
+| 401    | Unauthorized   |
+| 403    | Forbidden      |
 
 ---
 
@@ -184,9 +184,9 @@ slashes that conflict with URL routing.
 
 #### Parameters
 
-| Name | In | Required | Description |
-|------|----|----------|-------------|
-| `id` | path | Yes | User ID |
+| Name | In   | Required | Description |
+| ---- | ---- | -------- | ----------- |
+| `id` | path | Yes      | User ID     |
 
 #### Request Body
 
@@ -196,12 +196,11 @@ See `docs/api/openapi.json` for the full schema.
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Access revoked |
-| 400 | Bad request |
-| 401 | Unauthorized |
-| 403 | Forbidden |
+| Status | Description    |
+| ------ | -------------- |
+| 200    | Access revoked |
+| 400    | Bad request    |
+| 401    | Unauthorized   |
+| 403    | Forbidden      |
 
 ---
-

docs/api/webhooks.md

@@ -10,11 +10,11 @@ Webhook configuration
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | List of configured webhooks |
-| 401 | Unauthorized |
-| 403 | Forbidden |
+| Status | Description                 |
+| ------ | --------------------------- |
+| 200    | List of configured webhooks |
+| 401    | Unauthorized                |
+| 403    | Forbidden                   |
 
 ---
 
@@ -24,11 +24,10 @@ Webhook configuration
 
 #### Responses
 
-| Status | Description |
-|--------|-------------|
-| 200 | Test webhook sent |
-| 401 | Unauthorized |
-| 403 | Forbidden |
+| Status | Description       |
+| ------ | ----------------- |
+| 200    | Test webhook sent |
+| 401    | Unauthorized      |
+| 403    | Forbidden         |
 
 ---
-

examples/plugins/README.md

@@ -1,518 +0,0 @@
-# Pinakes Plugin Examples
-
-This directory contains example plugins demonstrating the Pinakes plugin system.
-
-## Overview
-
-Pinakes supports extensibility through a WASM-based plugin system. Plugins can
-extend Pinakes functionality by:
-
-- **Media Type Providers**: Add support for new file formats
-- **Metadata Extractors**: Extract metadata from files
-- **Thumbnail Generators**: Generate thumbnails for media types
-- **Search Backends**: Implement custom search algorithms
-- **Event Handlers**: React to system events
-- **Theme Providers**: Provide custom UI themes
-
-## Example Plugins
-
-### 1. Markdown Metadata Extractor
-
-**Directory**: `markdown-metadata/`
-
-Enhances markdown file support with advanced frontmatter parsing.
-
-**Demonstrates**:
-
-- Metadata extraction from files
-- Plugin configuration via `plugin.toml`
-- Minimal capability requirements
-
-**Plugin Kind**: `metadata_extractor`
-
-### 2. HEIF/HEIC Support
-
-**Directory**: `heif-support/`
-
-Adds support for HEIF and HEIC image formats.
-
-**Demonstrates**:
-
-- Media type registration
-- Metadata extraction from binary formats
-- Thumbnail generation
-- Resource limits (memory, CPU time)
-
-**Plugin Kinds**: `media_type`, `metadata_extractor`, `thumbnail_generator`
-
-## Plugin Architecture
-
-### Plugin Structure
-
-```
-my-plugin/
-├── plugin.toml          # Plugin manifest
-├── Cargo.toml           # Rust project configuration
-├── src/
-│   └── lib.rs          # Plugin implementation
-└── README.md           # Plugin documentation
-```
-
-### Plugin Manifest (plugin.toml)
-
-```toml
-[plugin]
-name = "my-plugin"
-version = "1.0.0"
-api_version = "1.0"
-author = "Your Name"
-description = "Description of your plugin"
-kind = ["metadata_extractor"]
-
-[plugin.binary]
-wasm = "my_plugin.wasm"
-
-[capabilities]
-network = false
-
-[capabilities.filesystem]
-read = ["/path/to/read"]
-write = ["/path/to/write"]
-
-[config]
-# Plugin-specific configuration
-option1 = "value1"
-option2 = 42
-```
-
-### Manifest Fields
-
-#### [plugin] Section
-
-- `name`: Plugin identifier (must be unique)
-- `version`: Semantic version (e.g., "1.0.0")
-- `api_version`: Pinakes Plugin API version (currently "1.0")
-- `author`: Plugin author (optional)
-- `description`: Short description (optional)
-- `homepage`: Plugin homepage URL (optional)
-- `license`: License identifier (optional)
-- `kind`: Array of plugin kinds
-- `dependencies`: Array of plugin names this plugin depends on (optional)
-
-#### [plugin.binary] Section
-
-- `wasm`: Path to WASM binary (relative to manifest)
-- `entrypoint`: Custom entrypoint function name (optional, default: "_start")
-
-#### [capabilities] Section
-
-Capabilities define what the plugin can access:
-
-**Filesystem**:
-
-```toml
-[capabilities.filesystem]
-read = ["/tmp/cache", "/var/data"]
-write = ["/tmp/output"]
-```
-
-**Network**:
-
-```toml
-[capabilities]
-network = true  # or false
-```
-
-**Environment**:
-
-```toml
-[capabilities]
-environment = ["PATH", "HOME"]  # or omit for no access
-```
-
-**Resource Limits**:
-
-```toml
-[capabilities]
-max_memory_mb = 128
-max_cpu_time_secs = 10
-```
-
-### Plugin Kinds
-
-#### media_type
-
-Register new media types with file extensions and MIME types.
-
-**Trait**: `MediaTypeProvider`
-
-**Methods**:
-
-- `supported_media_types()`: Returns list of media type definitions
-- `can_handle(path, mime_type)`: Check if plugin can handle a file
-
-#### metadata_extractor
-
-Extract metadata from files.
-
-**Trait**: `MetadataExtractor`
-
-**Methods**:
-
-- `extract_metadata(path)`: Extract metadata from file
-- `supported_types()`: Returns list of supported media type IDs
-
-#### thumbnail_generator
-
-Generate thumbnails for media files.
-
-**Trait**: `ThumbnailGenerator`
-
-**Methods**:
-
-- `generate_thumbnail(path, output_path, options)`: Generate thumbnail
-- `supported_types()`: Returns list of supported media type IDs
-
-#### search_backend
-
-Implement custom search algorithms.
-
-**Trait**: `SearchBackend`
-
-**Methods**:
-
-- `index_item(item)`: Index a media item
-- `remove_item(item_id)`: Remove item from index
-- `search(query)`: Perform search
-- `get_stats()`: Get index statistics
-
-#### event_handler
-
-React to system events.
-
-**Trait**: `EventHandler`
-
-**Methods**:
-
-- `handle_event(event)`: Handle an event
-- `interested_events()`: Returns list of event types to receive
-
-#### theme_provider
-
-Provide UI themes.
-
-**Trait**: `ThemeProvider`
-
-**Methods**:
-
-- `get_themes()`: List available themes
-- `load_theme(theme_id)`: Load theme data
-
-## Creating a Plugin
-
-### Step 1: Set Up Project
-
-```bash
-# Create new Rust library project
-cargo new --lib my-plugin
-cd my-plugin
-
-# Add dependencies
-cat >> Cargo.toml <<EOF
-[dependencies]
-pinakes-plugin-api = { path = "../../crates/pinakes-plugin-api" }
-async-trait = "0.1"
-serde = { version = "1.0", features = ["derive"] }
-
-[lib]
-crate-type = ["cdylib"]
-
-[profile.release]
-opt-level = "z"
-lto = true
-EOF
-```
-
-### Step 2: Implement Plugin
-
-```rust
-use async_trait::async_trait;
-use pinakes_plugin_api::*;
-use std::path::PathBuf;
-
-pub struct MyPlugin {
-    context: Option<PluginContext>,
-}
-
-#[async_trait]
-impl Plugin for MyPlugin {
-    fn metadata(&self) -> &PluginMetadata {
-        // Return plugin metadata
-    }
-
-    async fn initialize(&mut self, context: PluginContext) -> PluginResult<()> {
-        self.context = Some(context);
-        Ok(())
-    }
-
-    async fn shutdown(&mut self) -> PluginResult<()> {
-        Ok(())
-    }
-
-    async fn health_check(&self) -> PluginResult<HealthStatus> {
-        Ok(HealthStatus {
-            healthy: true,
-            message: None,
-            metrics: Default::default(),
-        })
-    }
-}
-
-#[async_trait]
-impl MetadataExtractor for MyPlugin {
-    async fn extract_metadata(&self, path: &PathBuf) -> PluginResult<ExtractedMetadata> {
-        // Extract metadata from file
-    }
-
-    fn supported_types(&self) -> Vec<String> {
-        vec!["my_type".to_string()]
-    }
-}
-```
-
-### Step 3: Build to WASM
-
-```bash
-# Install WASM target
-rustup target add wasm32-wasi
-
-# Build
-cargo build --target wasm32-wasi --release
-
-# Optimize (optional, wasm-tools provides wasm-strip functionality)
-cargo install wasm-tools
-wasm-tools strip target/wasm32-wasi/release/my_plugin.wasm -o target/wasm32-wasi/release/my_plugin.wasm
-
-# Copy to plugin directory
-cp target/wasm32-wasi/release/my_plugin.wasm .
-```
-
-### Step 4: Create Manifest
-
-Create `plugin.toml` with appropriate configuration (see examples above).
-
-### Step 5: Install Plugin
-
-```bash
-# Copy to plugins directory
-cp -r my-plugin ~/.config/pinakes/plugins/
-
-# Or use API
-curl -X POST http://localhost:3000/api/v1/plugins/install \
-  -d '{"source": "/path/to/my-plugin"}'
-```
-
-## Testing Plugins
-
-### Unit Tests
-
-```rust
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    #[tokio::test]
-    async fn test_metadata_extraction() {
-        let mut plugin = MyPlugin::default();
-        let context = PluginContext {
-            data_dir: PathBuf::from("/tmp/data"),
-            cache_dir: PathBuf::from("/tmp/cache"),
-            config: Default::default(),
-            capabilities: Default::default(),
-        };
-
-        plugin.initialize(context).await.unwrap();
-
-        let metadata = plugin
-            .extract_metadata(&PathBuf::from("test.txt"))
-            .await
-            .unwrap();
-
-        assert!(metadata.title.is_some());
-    }
-}
-```
-
-### Integration Tests
-
-```bash
-# Load plugin in test Pinakes instance
-pinakes --config test-config.toml plugin load /path/to/plugin
-
-# Verify plugin is loaded
-pinakes plugin list
-
-# Test plugin functionality
-pinakes scan /path/to/test/files
-```
-
-## Security Considerations
-
-### Capability-Based Security
-
-Plugins operate in a sandbox with explicit capabilities. Only request the
-minimum capabilities needed:
-
-**Good**:
-
-```toml
-[capabilities.filesystem]
-read = ["/tmp/cache"]
-```
-
-**Bad**:
-
-```toml
-[capabilities.filesystem]
-read = ["/", "/home", "/etc"]  # Too broad!
-```
-
-### Resource Limits
-
-Always set appropriate resource limits:
-
-```toml
-[capabilities]
-max_memory_mb = 128      # Reasonable for image processing
-max_cpu_time_secs = 10   # Prevent runaway operations
-```
-
-### Input Validation
-
-Always validate input in your plugin:
-
-```rust
-async fn extract_metadata(&self, path: &PathBuf) -> PluginResult<ExtractedMetadata> {
-    // Check file exists
-    if !path.exists() {
-        return Err(PluginError::InvalidInput("File not found".to_string()));
-    }
-
-    // Check file size
-    let metadata = std::fs::metadata(path)
-        .map_err(|e| PluginError::IoError(e.to_string()))?;
-    if metadata.len() > 10_000_000 {  // 10MB limit
-        return Err(PluginError::InvalidInput("File too large".to_string()));
-    }
-
-    // Process file...
-}
-```
-
-## Best Practices
-
-### Error Handling
-
-- Use descriptive error messages
-- Return appropriate `PluginError` variants
-- Don't panic - return errors instead
-
-### Performance
-
-- Avoid blocking operations in async functions
-- Use streaming for large files
-- Implement timeouts for external operations
-- Cache results when appropriate
-
-### Configuration
-
-- Provide sensible defaults
-- Document all configuration options
-- Validate configuration during initialization
-
-### Documentation
-
-- Write clear README with examples
-- Document all configuration options
-- Include troubleshooting section
-- Provide integration examples
-
-## API Reference
-
-See the
-[pinakes-plugin-api documentation](../../crates/pinakes-plugin-api/README.md)
-for detailed API reference.
-
-## Plugin Distribution
-
-### Plugin Registry (Future)
-
-A centralized plugin registry is planned for future releases:
-
-```bash
-# Install from registry
-pinakes plugin install markdown-metadata
-
-# Search plugins
-pinakes plugin search heif
-
-# Update all plugins
-pinakes plugin update --all
-```
-
-### Manual Distribution
-
-Currently, plugins are distributed as directories containing:
-
-- `plugin.toml` manifest
-- WASM binary
-- README and documentation
-
-## Troubleshooting
-
-### Plugin Won't Load
-
-**Check manifest syntax**:
-
-```bash
-# Validate TOML syntax
-taplo check plugin.toml
-```
-
-**Check API version**: Ensure `api_version = "1.0"` in manifest.
-
-**Check binary path**: Verify WASM binary exists at path specified in
-`plugin.binary.wasm`.
-
-### Plugin Crashes
-
-**Check resource limits**: Increase `max_memory_mb` or `max_cpu_time_secs` if
-operations are timing out.
-
-**Check capabilities**: Ensure plugin has necessary filesystem/network
-capabilities.
-
-**Check logs**:
-
-```bash
-# View plugin logs
-tail -f ~/.local/share/pinakes/logs/plugin.log
-```
-
-### Permission Denied Errors
-
-**Filesystem capabilities**: Add required paths to
-`capabilities.filesystem.read` or `.write`.
-
-**Network capabilities**: Set `capabilities.network = true` if plugin needs
-network access.
-
-## Support
-
-- **Issues**: https://github.com/notashelf/pinakes/issues
-- **Discussions**: https://github.com/notashelf/pinakes/discussions
-- **Documentation**: https://pinakes.readthedocs.io
-
-## License
-
-All example plugins are licensed under MIT.

examples/plugins/heif-support/README.md

@@ -1,257 +0,0 @@
-# HEIF/HEIC Support Plugin
-
-This example plugin adds support for HEIF (High Efficiency Image Format) and HEIC (HEIF Container) to Pinakes.
-
-## Overview
-
-HEIF is a modern image format that provides better compression than JPEG while maintaining higher quality. This plugin enables Pinakes to:
-- Recognize HEIF/HEIC files as a media type
-- Extract metadata from HEIF images
-- Generate thumbnails from HEIF images
-
-## Features
-
-- **Media Type Registration**: Registers `.heif`, `.heic`, `.hif` extensions as image media types
-- **EXIF Extraction**: Extracts EXIF metadata including camera info, GPS coordinates, timestamps
-- **Thumbnail Generation**: Generates thumbnails in JPEG, PNG, or WebP format
-- **Resource Limits**: Configurable memory and CPU limits for safe processing
-- **Large Image Support**: Handles images up to 8192x8192 pixels
-
-## Supported Formats
-
-- **HEIF**: High Efficiency Image Format (`.heif`, `.hif`)
-- **HEIC**: HEIF Container format used by Apple devices (`.heic`)
-- **HEIF Sequences**: Multi-image HEIF files
-- **HEIF with Alpha**: HEIF images with transparency
-
-## Implementation
-
-The plugin implements three traits:
-
-### MediaTypeProvider
-
-```rust
-#[async_trait]
-impl MediaTypeProvider for HeifPlugin {
-    fn supported_media_types(&self) -> Vec<MediaTypeDefinition> {
-        vec![MediaTypeDefinition {
-            id: "heif".to_string(),
-            name: "HEIF Image".to_string(),
-            category: "image".to_string(),
-            extensions: vec!["heif".to_string(), "heic".to_string(), "hif".to_string()],
-            mime_types: vec!["image/heif".to_string(), "image/heic".to_string()],
-            icon: Some("image".to_string()),
-        }]
-    }
-
-    async fn can_handle(&self, path: &PathBuf, mime_type: Option<&str>) -> PluginResult<bool> {
-        // Check file extension and/or MIME type
-    }
-}
-```
-
-### MetadataExtractor
-
-```rust
-#[async_trait]
-impl MetadataExtractor for HeifPlugin {
-    async fn extract_metadata(&self, path: &PathBuf) -> PluginResult<ExtractedMetadata> {
-        // 1. Parse HEIF file structure
-        // 2. Extract EXIF metadata
-        // 3. Get image dimensions
-        // 4. Return ExtractedMetadata
-    }
-
-    fn supported_types(&self) -> Vec<String> {
-        vec!["heif".to_string()]
-    }
-}
-```
-
-### ThumbnailGenerator
-
-```rust
-#[async_trait]
-impl ThumbnailGenerator for HeifPlugin {
-    async fn generate_thumbnail(
-        &self,
-        path: &PathBuf,
-        output_path: &PathBuf,
-        options: ThumbnailOptions,
-    ) -> PluginResult<ThumbnailInfo> {
-        // 1. Decode HEIF image
-        // 2. Resize to thumbnail dimensions
-        // 3. Encode to output format
-        // 4. Save to output_path
-        // 5. Return ThumbnailInfo
-    }
-
-    fn supported_types(&self) -> Vec<String> {
-        vec!["heif".to_string()]
-    }
-}
-```
-
-## Dependencies
-
-The plugin uses the following Rust crates (compiled to WASM):
-- `libheif-rs`: HEIF decoding and encoding
-- `image`: Image processing and thumbnail generation
-- `kamadak-exif`: EXIF metadata parsing
-
-## Building
-
-### Prerequisites
-
-```bash
-# Install WASM target
-rustup target add wasm32-wasi
-
-# Install wasm-tools for optimization (provides strip functionality)
-cargo install wasm-tools
-```
-
-### Build Process
-
-```bash
-# Build the plugin
-cargo build --target wasm32-wasi --release
-
-# Strip debug symbols to reduce size
-wasm-tools strip target/wasm32-wasi/release/heif_support.wasm -o target/wasm32-wasi/release/heif_support.wasm
-
-# Copy to plugin directory
-cp target/wasm32-wasi/release/heif_support.wasm .
-```
-
-### Size Optimization
-
-```bash
-# Use wasm-opt for further optimization
-wasm-opt -Oz heif_support.wasm -o heif_support_optimized.wasm
-```
-
-## Installation
-
-### Manual Installation
-
-```bash
-# Copy plugin directory to Pinakes plugins directory
-cp -r examples/plugins/heif-support ~/.config/pinakes/plugins/
-```
-
-### Via API
-
-```bash
-curl -X POST http://localhost:3000/api/v1/plugins/install \
-  -H "Content-Type: application/json" \
-  -d '{"source": "/path/to/heif-support"}'
-```
-
-### Via Plugin Manager
-
-```bash
-pinakes plugin install /path/to/heif-support
-```
-
-## Configuration
-
-The plugin can be configured through the `config` section in `plugin.toml`:
-
-### EXIF Extraction
-- `extract_exif`: Enable EXIF metadata extraction (default: true)
-
-### Thumbnail Generation
-- `generate_thumbnails`: Enable thumbnail generation (default: true)
-- `thumbnail_quality`: JPEG quality for thumbnails, 1-100 (default: 85)
-- `thumbnail_format`: Output format - "jpeg", "png", or "webp" (default: "jpeg")
-
-### Resource Limits
-- `max_memory_mb`: Maximum memory the plugin can use in megabytes (default: 256, set in `[capabilities]`)
-- `max_width`: Maximum image width to process (default: 8192)
-- `max_height`: Maximum image height to process (default: 8192)
-
-## Security
-
-### Capabilities
-
-- **Filesystem Read**: Only files being processed (via Pinakes)
-- **Filesystem Write**: Thumbnail directory only
-- **Network**: Disabled
-- **Environment**: No access
-
-### Resource Limits
-
-- **Memory**: 256 MB maximum
-- **CPU Time**: 30 seconds maximum per operation
-
-### Sandboxing
-
-The plugin runs in a WASM sandbox with:
-- No access to host filesystem beyond granted paths
-- No network access
-- No arbitrary code execution
-- Memory and CPU time limits enforced by runtime
-
-## Performance
-
-### Typical Performance
-
-- **Metadata Extraction**: ~50-100ms for typical HEIF files
-- **Thumbnail Generation**: ~200-500ms depending on source image size
-- **Memory Usage**: 50-150 MB typical, 256 MB maximum
-
-### Optimization Tips
-
-1. Keep source images below 8192x8192 for best performance
-2. Use JPEG thumbnail format for smaller file sizes
-3. Adjust thumbnail quality vs file size tradeoff with `thumbnail_quality`
-
-## Error Handling
-
-The plugin handles:
-- **Corrupted Files**: Returns descriptive error
-- **Unsupported Variants**: Gracefully skips unsupported HEIF features
-- **Memory Limits**: Fails safely if image too large
-- **Timeout**: Returns error if processing exceeds CPU time limit
-
-## Testing
-
-```bash
-# Run unit tests
-cargo test
-
-# Test with sample HEIF files
-cargo test --test integration -- --nocapture
-```
-
-## Troubleshooting
-
-### Plugin Fails to Load
-
-- Check that `heif_support.wasm` exists in plugin directory
-- Verify `plugin.toml` is valid TOML
-- Check Pinakes logs for detailed error messages
-
-### Thumbnails Not Generated
-
-- Verify `generate_thumbnails = true` in config
-- Check filesystem write permissions for thumbnail directory
-- Ensure source image is below size limits
-
-### Out of Memory Errors
-
-- Reduce `max_width` and `max_height` in config
-- Increase `max_memory_mb` if source images are large
-- Check that source files aren't corrupted
-
-## Future Enhancements
-
-- Support for HEIF image sequences (burst photos)
-- HDR metadata extraction
-- Live Photo support
-- AVIF format support (similar to HEIF)
-
-## License
-
-MIT

examples/plugins/heif-support/plugin.toml

@@ -1,29 +0,0 @@
-[plugin]
-name = "heif-support"
-version = "1.0.0"
-api_version = "1.0"
-author = "Pinakes Contributors"
-description = "HEIF/HEIC image format support for Pinakes"
-homepage = "https://github.com/notashelf/pinakes"
-license = "MIT"
-kind = ["media_type", "metadata_extractor", "thumbnail_generator"]
-
-[plugin.binary]
-wasm = "heif_support.wasm"
-
-[capabilities]
-network = false
-max_memory_mb = 256
-max_cpu_time_secs = 30
-
-[capabilities.filesystem]
-read = ["/media"]
-write = ["/tmp/pinakes"]
-
-[config]
-extract_exif = true
-generate_thumbnails = true
-thumbnail_quality = 85
-thumbnail_format = "jpeg"
-max_width = 8192
-max_height = 8192

examples/plugins/markdown-metadata/README.md

@@ -1,103 +0,0 @@
-# Markdown Metadata Extractor Plugin
-
-This example plugin demonstrates how to create a metadata extractor plugin for Pinakes.
-
-## Overview
-
-The Markdown Metadata Extractor enhances Pinakes' built-in markdown support by:
-- Parsing YAML and TOML frontmatter
-- Extracting metadata from frontmatter fields
-- Converting frontmatter tags to Pinakes media tags
-- Extracting custom fields from frontmatter
-
-## Features
-
-- **Frontmatter Parsing**: Supports both YAML (`---`) and TOML (`+++`) frontmatter formats
-- **Tag Extraction**: Automatically extracts tags from frontmatter and applies them to media items
-- **Custom Fields**: Preserves all frontmatter fields as custom metadata
-- **Configuration**: Configurable via `plugin.toml` config section
-
-## Frontmatter Example
-
-```markdown
----
-title: "My Document"
-author: "John Doe"
-date: "2024-01-15"
-tags: ["documentation", "example", "markdown"]
-category: "tutorials"
-draft: false
----
-
-# My Document
-
-Content goes here...
-```
-
-## Implementation
-
-The plugin implements the `MetadataExtractor` trait from `pinakes-plugin-api`:
-
-```rust
-#[async_trait]
-impl MetadataExtractor for MarkdownMetadataPlugin {
-    async fn extract_metadata(&self, path: &PathBuf) -> PluginResult<ExtractedMetadata> {
-        // 1. Read the file
-        // 2. Parse frontmatter
-        // 3. Extract metadata fields
-        // 4. Return ExtractedMetadata
-    }
-
-    fn supported_types(&self) -> Vec<String> {
-        vec!["markdown".to_string()]
-    }
-}
-```
-
-## Building
-
-The plugin is compiled to WebAssembly:
-
-```bash
-cargo build --target wasm32-wasi --release
-wasm-strip target/wasm32-wasi/release/markdown_metadata.wasm
-cp target/wasm32-wasi/release/markdown_metadata.wasm .
-```
-
-## Installation
-
-```bash
-# Copy plugin directory to Pinakes plugins directory
-cp -r examples/plugins/markdown-metadata ~/.config/pinakes/plugins/
-
-# Or via API
-curl -X POST http://localhost:3000/api/v1/plugins/install \
-  -H "Content-Type: application/json" \
-  -d '{"source": "/path/to/markdown-metadata"}'
-```
-
-## Configuration
-
-The plugin can be configured through the `config` section in `plugin.toml`:
-
-- `extract_tags`: Extract tags from frontmatter (default: true)
-- `parse_yaml`: Parse YAML frontmatter (default: true)
-- `parse_toml`: Parse TOML frontmatter (default: true)
-- `max_file_size`: Maximum file size to process in bytes (default: 10MB)
-
-## Security
-
-This plugin has minimal capabilities:
-- **Filesystem**: No write access, read access only to files being processed
-- **Network**: Disabled
-- **Environment**: No access
-
-## Testing
-
-```bash
-cargo test
-```
-
-## License
-
-MIT

examples/plugins/markdown-metadata/plugin.toml

@@ -1,25 +0,0 @@
-[plugin]
-name = "markdown-metadata"
-version = "1.0.0"
-api_version = "1.0"
-author = "Pinakes Contributors"
-description = "Extract metadata from Markdown files with YAML frontmatter"
-homepage = "https://github.com/notashelf/pinakes"
-license = "MIT"
-kind = ["metadata_extractor"]
-
-[plugin.binary]
-wasm = "markdown_metadata.wasm"
-
-[capabilities]
-network = false
-
-[capabilities.filesystem]
-read = []
-write = []
-
-[config]
-extract_tags = true
-parse_yaml = true
-parse_toml = true
-max_file_size = 10485760

examples/plugins/media-stats-ui/Cargo.toml

@@ -1,20 +0,0 @@
-[workspace]
-
-[package]
-name = "media-stats-ui"
-version = "1.0.0"
-edition = "2024"
-description = "Library statistics dashboard and tag manager, a UI-only Pinakes plugin"
-license = "EUPL-1.2"
-
-[lib]
-name = "media_stats_ui"
-crate-type = ["cdylib"]
-
-[dependencies]
-dlmalloc = { version = "0.2.12", features = ["global"] }
-
-[profile.release]
-opt-level = "s"
-lto = true
-strip = true

examples/plugins/media-stats-ui/pages/stats.json

@@ -1,132 +0,0 @@
-{
-  "id": "stats",
-  "title": "Library Statistics",
-  "route": "/plugins/media-stats-ui/stats",
-  "icon": "chart-bar",
-  "layout": {
-    "type": "tabs",
-    "default_tab": 0,
-    "tabs": [
-      {
-        "label": "Overview",
-        "content": {
-          "type": "container",
-          "gap": 24,
-          "children": [
-            {
-              "type": "heading",
-              "level": 2,
-              "content": "Library Statistics"
-            },
-            {
-              "type": "text",
-              "content": "Live summary of your media library. Refreshes every 30 seconds.",
-              "variant": "secondary"
-            },
-            {
-              "type": "card",
-              "title": "Summary",
-              "content": [
-                {
-                  "type": "description_list",
-                  "data": "stats",
-                  "horizontal": true
-                }
-              ]
-            },
-            {
-              "type": "chart",
-              "chart_type": "bar",
-              "data": "type-breakdown",
-              "title": "Files by Type",
-              "x_axis_label": "Media Type",
-              "y_axis_label": "Count",
-              "height": 280
-            }
-          ]
-        }
-      },
-      {
-        "label": "Recent Files",
-        "content": {
-          "type": "container",
-          "gap": 16,
-          "children": [
-            {
-              "type": "heading",
-              "level": 2,
-              "content": "Recently Added"
-            },
-            {
-              "type": "data_table",
-              "data": "recent",
-              "sortable": true,
-              "filterable": true,
-              "page_size": 10,
-              "columns": [
-                {
-                  "key": "file_name",
-                  "header": "Filename"
-                },
-                {
-                  "key": "title",
-                  "header": "Title"
-                },
-                {
-                  "key": "media_type",
-                  "header": "Type"
-                },
-                {
-                  "key": "file_size",
-                  "header": "Size",
-                  "data_type": "file_size"
-                },
-                {
-                  "key": "created_at",
-                  "header": "Added",
-                  "data_type": "date_time"
-                }
-              ]
-            }
-          ]
-        }
-      },
-      {
-        "label": "Media Grid",
-        "content": {
-          "type": "container",
-          "gap": 16,
-          "children": [
-            {
-              "type": "heading",
-              "level": 2,
-              "content": "Browse Media"
-            },
-            {
-              "type": "media_grid",
-              "data": "recent",
-              "columns": 4,
-              "gap": 12
-            }
-          ]
-        }
-      }
-    ]
-  },
-  "data_sources": {
-    "stats": {
-      "type": "endpoint",
-      "path": "/api/v1/statistics",
-      "poll_interval": 30
-    },
-    "recent": {
-      "type": "endpoint",
-      "path": "/api/v1/media"
-    },
-    "type-breakdown": {
-      "type": "transform",
-      "source": "stats",
-      "expression": "stats.media_by_type"
-    }
-  }
-}

examples/plugins/media-stats-ui/pages/tag-manager.json

@@ -1,126 +0,0 @@
-{
-  "id": "tag-manager",
-  "title": "Tag Manager",
-  "route": "/plugins/media-stats-ui/tag-manager",
-  "icon": "tag",
-  "layout": {
-    "type": "tabs",
-    "default_tab": 0,
-    "tabs": [
-      {
-        "label": "All Tags",
-        "content": {
-          "type": "container",
-          "gap": 16,
-          "children": [
-            {
-              "type": "heading",
-              "level": 2,
-              "content": "Manage Tags"
-            },
-            {
-              "type": "conditional",
-              "condition": {
-                "op": "eq",
-                "left": { "function": "len", "args": ["tags"] },
-                "right": 0
-              },
-              "then": {
-                "type": "text",
-                "content": "No tags yet. Use the 'Create Tag' tab to add one.",
-                "variant": "secondary"
-              },
-              "else": {
-                "type": "data_table",
-                "data": "tags",
-                "sortable": true,
-                "filterable": true,
-                "page_size": 20,
-                "columns": [
-                  { "key": "name",       "header": "Tag Name" },
-                  { "key": "color",      "header": "Color" },
-                  { "key": "item_count", "header": "Items", "data_type": "number" }
-                ]
-              }
-            }
-          ]
-        }
-      },
-      {
-        "label": "Create Tag",
-        "content": {
-          "type": "container",
-          "gap": 24,
-          "children": [
-            {
-              "type": "heading",
-              "level": 2,
-              "content": "Create New Tag"
-            },
-            {
-              "type": "text",
-              "content": "Tags are used to organise media items. Choose a name and an optional colour.",
-              "variant": "secondary"
-            },
-            {
-              "type": "form",
-              "submit_label": "Create Tag",
-              "submit_action": "create-tag",
-              "cancel_label": "Reset",
-              "fields": [
-                {
-                  "id": "name",
-                  "label": "Tag Name",
-                  "type": { "type": "text", "max_length": 64 },
-                  "required": true,
-                  "placeholder": "e.g. favourite, to-watch, archived",
-                  "help_text": "Must be unique. Alphanumeric characters, spaces, and hyphens.",
-                  "validation": [
-                    { "type": "min_length", "value": 1 },
-                    { "type": "max_length", "value": 64 },
-                    { "type": "pattern",    "regex": "^[a-zA-Z0-9 \\-]+$" }
-                  ]
-                },
-                {
-                  "id": "color",
-                  "label": "Colour",
-                  "type": {
-                    "type": "select",
-                    "options": [
-                      { "value": "#ef4444", "label": "Red" },
-                      { "value": "#f97316", "label": "Orange" },
-                      { "value": "#eab308", "label": "Yellow" },
-                      { "value": "#22c55e", "label": "Green" },
-                      { "value": "#3b82f6", "label": "Blue" },
-                      { "value": "#8b5cf6", "label": "Purple" },
-                      { "value": "#ec4899", "label": "Pink" },
-                      { "value": "#6b7280", "label": "Grey" }
-                    ]
-                  },
-                  "required": false,
-                  "default_value": "#3b82f6",
-                  "help_text": "Optional accent colour shown beside the tag."
-                }
-              ]
-            }
-          ]
-        }
-      }
-    ]
-  },
-  "data_sources": {
-    "tags": {
-      "type": "endpoint",
-      "path": "/api/v1/tags",
-      "poll_interval": 0
-    }
-  },
-  "actions": {
-    "create-tag": {
-      "method": "POST",
-      "path": "/api/v1/tags",
-      "success_message": "Tag created successfully!",
-      "error_message": "Failed to create tag: the name may already be in use."
-    }
-  }
-}

examples/plugins/media-stats-ui/plugin.toml

@@ -1,39 +0,0 @@
-[plugin]
-name = "media-stats-ui"
-version = "1.0.0"
-api_version = "1.0"
-author = "Pinakes Contributors"
-description = "Library statistics dashboard and tag manager UI plugin"
-homepage = "https://github.com/notashelf/pinakes"
-license = "EUPL-1.2"
-kind = ["ui_page"]
-
-[plugin.binary]
-wasm = "target/wasm32-unknown-unknown/release/media_stats_ui.wasm"
-
-[capabilities]
-network = false
-
-[capabilities.filesystem]
-read = []
-write = []
-
-[ui]
-required_endpoints = ["/api/v1/statistics", "/api/v1/media", "/api/v1/tags"]
-
-# UI pages
-[[ui.pages]]
-file = "pages/stats.json"
-
-[[ui.pages]]
-file = "pages/tag-manager.json"
-
-# Widgets injected into host views
-[[ui.widgets]]
-id = "stats-badge"
-target = "library_header"
-
-[ui.widgets.content]
-type = "badge"
-text = "Stats"
-variant = "info"

examples/plugins/media-stats-ui/src/lib.rs

@@ -1,101 +0,0 @@
-//! Media Stats UI - Pinakes plugin
-//!
-//! A UI-only plugin that adds a library statistics dashboard and a tag manager
-//! page. All UI definitions live in `pages/stats.json` and
-//! `pages/tag-manager.json`; this WASM binary provides the minimum lifecycle
-//! surface the host runtime requires.
-//!
-//! This plugin is kind = ["ui_page"]: no media-type, metadata, thumbnail, or
-//! event-handler extension points are needed. The host will never call them,
-//! but exporting them avoids linker warnings if the host performs capability
-//! discovery via symbol inspection.
-
-#![no_std]
-
-extern crate alloc;
-
-use core::alloc::Layout;
-
-#[global_allocator]
-static ALLOC: dlmalloc::GlobalDlmalloc = dlmalloc::GlobalDlmalloc;
-
-#[panic_handler]
-fn panic(_: &core::panic::PanicInfo) -> ! {
-  core::arch::wasm32::unreachable()
-}
-
-// Host functions provided by the Pinakes runtime.
-unsafe extern "C" {
-  // Write a result value back to the host (ptr + byte length).
-  fn host_set_result(ptr: i32, len: i32);
-
-  // Emit a structured log message to the host logger.
-  // `level` mirrors tracing severity: 0=trace 1=debug 2=info 3=warn 4=error
-  fn host_log(level: i32, ptr: i32, len: i32);
-}
-
-/// # Safety
-///
-/// `json` is a valid slice; the host copies the bytes before
-/// returning so there are no lifetime concerns.
-fn set_response(json: &[u8]) {
-  unsafe { host_set_result(json.as_ptr() as i32, json.len() as i32) }
-}
-
-/// # Safety
-///
-///  Same as [`set_response`]
-fn log_info(msg: &[u8]) {
-  unsafe { host_log(2, msg.as_ptr() as i32, msg.len() as i32) }
-}
-
-/// Allocate a buffer for the host to write request data into.
-///
-/// # Returns
-///
-/// The byte offset of the allocation, or -1 on failure.
-///
-/// # Safety
-///
-/// Size is positive; Layout construction cannot fail for align=1.
-#[unsafe(no_mangle)]
-pub extern "C" fn alloc(size: i32) -> i32 {
-  if size <= 0 {
-    return 0;
-  }
-  unsafe {
-    let layout = Layout::from_size_align_unchecked(size as usize, 1);
-    let ptr = alloc::alloc::alloc(layout);
-    if ptr.is_null() { -1 } else { ptr as i32 }
-  }
-}
-
-/// Called once after the plugin is loaded. Returns 0 on success.
-#[unsafe(no_mangle)]
-pub extern "C" fn initialize() -> i32 {
-  log_info(b"media-stats-ui: initialized");
-  0
-}
-
-/// Called before the plugin is unloaded. Returns 0 on success.
-#[unsafe(no_mangle)]
-pub extern "C" fn shutdown() -> i32 {
-  log_info(b"media-stats-ui: shutdown");
-  0
-}
-
-/// # Returns
-///
-/// an empty JSON array; this plugin adds no custom media types.
-#[unsafe(no_mangle)]
-pub extern "C" fn supported_media_types(_ptr: i32, _len: i32) {
-  set_response(b"[]");
-}
-
-/// # Returns
-///
-/// An empty JSON array; this plugin handles no event types.
-#[unsafe(no_mangle)]
-pub extern "C" fn interested_events(_ptr: i32, _len: i32) {
-  set_response(b"[]");
-}

flake.nix

@@ -21,5 +21,38 @@
     in {
       default = pkgs.callPackage ./nix/shell.nix {};
     });
+
+    formatter = forEachSystem (system: let
+      pkgs = nixpkgs.legacyPackages.${system};
+    in
+      pkgs.writeShellApplication {
+        name = "nix3-fmt-wrapper";
+
+        runtimeInputs = [
+          pkgs.alejandra
+          pkgs.fd
+          pkgs.prettier
+          pkgs.deno
+          pkgs.taplo
+          pkgs.sql-formatter
+        ];
+
+        text = ''
+          # Format Nix with Alejandra
+          fd "$@" -t f -e nix -x alejandra -q '{}'
+
+          # Format TOML with Taplo
+          fd "$@" -t f -e toml -x taplo fmt '{}'
+
+          # Format CSS with Prettier
+          fd "$@" -t f -e css -x prettier --write '{}'
+
+          # Format SQL with sql-format
+          fd "$@" -t f -e sql -x sql-formatter --fix '{}' -l postgresql
+
+          # Format Markdown with Deno
+          fd "$@" -t f -e md -x deno fmt -q '{}'
+        '';
+      });
   };
 }

justfile

@@ -0,0 +1,40 @@
+# Default recipe to show help
+@default:
+  just --list
+
+# Build all crates
+build-all: build-server build-tui build-ui
+
+# Build the server crate
+build-server:
+  cargo build -p pinakes-server
+
+# Build the TUI crate
+build-tui:
+  cargo build -p pinakes-tui
+
+# Build the UI using Dioxus CLI. The UI *has* to be built with `dx`, because CSS
+# is not correctly embedded otherwise.
+build-ui:
+  dx build -p pinakes-ui
+
+# Generate REST API documentation using cargo xtask
+@docs:
+  cargo xtask docs
+
+# Run all tests
+@test:
+  cargo nextest run --workspace
+
+# Format code
+@fmt:
+  cargo fmt
+
+# Run clippy linting
+@lint:
+  cargo clippy --workspace
+
+# Clean build artifacts
+@clean:
+  cargo clean
+  rm -rf target/dx/

migrations/postgres/V10__incremental_scan.sql

@@ -1,19 +1,19 @@
 -- Add file_mtime column to media_items table for incremental scanning
 -- Stores Unix timestamp in seconds of the file's modification time
-
-ALTER TABLE media_items ADD COLUMN file_mtime BIGINT;
+ALTER TABLE media_items
+ADD COLUMN file_mtime BIGINT;
 
 -- Create index for quick mtime lookups
-CREATE INDEX IF NOT EXISTS idx_media_items_file_mtime ON media_items(file_mtime);
+CREATE INDEX IF NOT EXISTS idx_media_items_file_mtime ON media_items (file_mtime);
 
 -- Create a scan_history table to track when each directory was last scanned
 CREATE TABLE IF NOT EXISTS scan_history (
-    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-    directory TEXT NOT NULL UNIQUE,
-    last_scan_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
-    files_scanned INTEGER NOT NULL DEFAULT 0,
-    files_changed INTEGER NOT NULL DEFAULT 0,
-    scan_duration_ms INTEGER
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  directory TEXT NOT NULL UNIQUE,
+  last_scan_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  files_scanned INTEGER NOT NULL DEFAULT 0,
+  files_changed INTEGER NOT NULL DEFAULT 0,
+  scan_duration_ms INTEGER
 );
 
-CREATE INDEX IF NOT EXISTS idx_scan_history_directory ON scan_history(directory);
+CREATE INDEX IF NOT EXISTS idx_scan_history_directory ON scan_history (directory);

migrations/postgres/V11__session_persistence.sql

@@ -1,18 +1,17 @@
 -- Session persistence for database-backed sessions
 -- Replaces in-memory session storage
-
 CREATE TABLE IF NOT EXISTS sessions (
-    session_token TEXT PRIMARY KEY NOT NULL,
-    user_id TEXT,
-    username TEXT NOT NULL,
-    role TEXT NOT NULL,
-    created_at TIMESTAMPTZ NOT NULL,
-    expires_at TIMESTAMPTZ NOT NULL,
-    last_accessed TIMESTAMPTZ NOT NULL
+  session_token TEXT PRIMARY KEY NOT NULL,
+  user_id TEXT,
+  username TEXT NOT NULL,
+  role TEXT NOT NULL,
+  created_at TIMESTAMPTZ NOT NULL,
+  expires_at TIMESTAMPTZ NOT NULL,
+  last_accessed TIMESTAMPTZ NOT NULL
 );
 
 -- Index for efficient cleanup of expired sessions
-CREATE INDEX IF NOT EXISTS idx_sessions_expires_at ON sessions(expires_at);
+CREATE INDEX IF NOT EXISTS idx_sessions_expires_at ON sessions (expires_at);
 
 -- Index for listing sessions by username
-CREATE INDEX IF NOT EXISTS idx_sessions_username ON sessions(username);
+CREATE INDEX IF NOT EXISTS idx_sessions_username ON sessions (username);

migrations/postgres/V12__book_management.sql

@@ -1,60 +1,61 @@
 -- V12: Book Management Schema (PostgreSQL)
 -- Adds comprehensive book metadata tracking, authors, and identifiers
-
 -- Book metadata (supplements media_items for EPUB/PDF/MOBI)
 CREATE TABLE book_metadata (
-    media_id UUID PRIMARY KEY REFERENCES media_items(id) ON DELETE CASCADE,
-    isbn TEXT,
-    isbn13 TEXT,              -- Normalized ISBN-13 for lookups
-    publisher TEXT,
-    language TEXT,            -- ISO 639-1 code
-    page_count INTEGER,
-    publication_date DATE,
-    series_name TEXT,
-    series_index DOUBLE PRECISION,  -- Supports 1.5, etc.
-    format TEXT,              -- 'epub', 'pdf', 'mobi', 'azw3'
-    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
-    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+  media_id UUID PRIMARY KEY REFERENCES media_items (id) ON DELETE CASCADE,
+  isbn TEXT,
+  isbn13 TEXT, -- Normalized ISBN-13 for lookups
+  publisher TEXT,
+  language TEXT, -- ISO 639-1 code
+  page_count INTEGER,
+  publication_date DATE,
+  series_name TEXT,
+  series_index DOUBLE PRECISION, -- Supports 1.5, etc.
+  format TEXT, -- 'epub', 'pdf', 'mobi', 'azw3'
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
 );
 
-CREATE INDEX idx_book_isbn13 ON book_metadata(isbn13);
-CREATE INDEX idx_book_series ON book_metadata(series_name, series_index);
-CREATE INDEX idx_book_publisher ON book_metadata(publisher);
-CREATE INDEX idx_book_language ON book_metadata(language);
+CREATE INDEX idx_book_isbn13 ON book_metadata (isbn13);
+
+CREATE INDEX idx_book_series ON book_metadata (series_name, series_index);
+
+CREATE INDEX idx_book_publisher ON book_metadata (publisher);
+
+CREATE INDEX idx_book_language ON book_metadata (language);
 
 -- Multiple authors per book (many-to-many)
 CREATE TABLE book_authors (
-    media_id UUID NOT NULL REFERENCES media_items(id) ON DELETE CASCADE,
-    author_name TEXT NOT NULL,
-    author_sort TEXT,         -- "Last, First" for sorting
-    role TEXT NOT NULL DEFAULT 'author', -- author, translator, editor, illustrator
-    position INTEGER NOT NULL DEFAULT 0,
-    PRIMARY KEY (media_id, author_name, role)
+  media_id UUID NOT NULL REFERENCES media_items (id) ON DELETE CASCADE,
+  author_name TEXT NOT NULL,
+  author_sort TEXT, -- "Last, First" for sorting
+  role TEXT NOT NULL DEFAULT 'author', -- author, translator, editor, illustrator
+  position INTEGER NOT NULL DEFAULT 0,
+  PRIMARY KEY (media_id, author_name, role)
 );
 
-CREATE INDEX idx_book_authors_name ON book_authors(author_name);
-CREATE INDEX idx_book_authors_sort ON book_authors(author_sort);
+CREATE INDEX idx_book_authors_name ON book_authors (author_name);
+
+CREATE INDEX idx_book_authors_sort ON book_authors (author_sort);
 
 -- Multiple identifiers (ISBN variants, ASIN, DOI, etc.)
 CREATE TABLE book_identifiers (
-    media_id UUID NOT NULL REFERENCES media_items(id) ON DELETE CASCADE,
-    identifier_type TEXT NOT NULL,  -- isbn, isbn13, asin, doi, lccn, oclc
-    identifier_value TEXT NOT NULL,
-    PRIMARY KEY (media_id, identifier_type, identifier_value)
+  media_id UUID NOT NULL REFERENCES media_items (id) ON DELETE CASCADE,
+  identifier_type TEXT NOT NULL, -- isbn, isbn13, asin, doi, lccn, oclc
+  identifier_value TEXT NOT NULL,
+  PRIMARY KEY (media_id, identifier_type, identifier_value)
 );
 
-CREATE INDEX idx_book_identifiers ON book_identifiers(identifier_type, identifier_value);
+CREATE INDEX idx_book_identifiers ON book_identifiers (identifier_type, identifier_value);
 
 -- Trigger to update updated_at on book_metadata changes
-CREATE OR REPLACE FUNCTION update_book_metadata_timestamp()
-RETURNS TRIGGER AS $$
+CREATE OR REPLACE FUNCTION update_book_metadata_timestamp () RETURNS TRIGGER AS $$
 BEGIN
     NEW.updated_at = NOW();
     RETURN NEW;
 END;
 $$ LANGUAGE plpgsql;
 
-CREATE TRIGGER update_book_metadata_timestamp
-    BEFORE UPDATE ON book_metadata
-    FOR EACH ROW
-    EXECUTE FUNCTION update_book_metadata_timestamp();
+CREATE TRIGGER update_book_metadata_timestamp BEFORE
+UPDATE ON book_metadata FOR EACH ROW
+EXECUTE FUNCTION update_book_metadata_timestamp ();

migrations/postgres/V13__photo_metadata.sql

@@ -1,15 +1,40 @@
 -- V13: Enhanced photo metadata support
 -- Add photo-specific fields to media_items table
+ALTER TABLE media_items
+ADD COLUMN date_taken TIMESTAMPTZ;
 
-ALTER TABLE media_items ADD COLUMN date_taken TIMESTAMPTZ;
-ALTER TABLE media_items ADD COLUMN latitude DOUBLE PRECISION;
-ALTER TABLE media_items ADD COLUMN longitude DOUBLE PRECISION;
-ALTER TABLE media_items ADD COLUMN camera_make TEXT;
-ALTER TABLE media_items ADD COLUMN camera_model TEXT;
-ALTER TABLE media_items ADD COLUMN rating INTEGER CHECK (rating >= 0 AND rating <= 5);
+ALTER TABLE media_items
+ADD COLUMN latitude DOUBLE PRECISION;
+
+ALTER TABLE media_items
+ADD COLUMN longitude DOUBLE PRECISION;
+
+ALTER TABLE media_items
+ADD COLUMN camera_make TEXT;
+
+ALTER TABLE media_items
+ADD COLUMN camera_model TEXT;
+
+ALTER TABLE media_items
+ADD COLUMN rating INTEGER CHECK (
+  rating >= 0
+  AND rating <= 5
+);
 
 -- Indexes for photo queries
-CREATE INDEX idx_media_date_taken ON media_items(date_taken) WHERE date_taken IS NOT NULL;
-CREATE INDEX idx_media_location ON media_items(latitude, longitude) WHERE latitude IS NOT NULL AND longitude IS NOT NULL;
-CREATE INDEX idx_media_camera ON media_items(camera_make) WHERE camera_make IS NOT NULL;
-CREATE INDEX idx_media_rating ON media_items(rating) WHERE rating IS NOT NULL;
+CREATE INDEX idx_media_date_taken ON media_items (date_taken)
+WHERE
+  date_taken IS NOT NULL;
+
+CREATE INDEX idx_media_location ON media_items (latitude, longitude)
+WHERE
+  latitude IS NOT NULL
+  AND longitude IS NOT NULL;
+
+CREATE INDEX idx_media_camera ON media_items (camera_make)
+WHERE
+  camera_make IS NOT NULL;
+
+CREATE INDEX idx_media_rating ON media_items (rating)
+WHERE
+  rating IS NOT NULL;

migrations/postgres/V14__perceptual_hash.sql

@@ -1,7 +1,9 @@
 -- V14: Perceptual hash for duplicate detection
 -- Add perceptual hash column for image similarity detection
-
-ALTER TABLE media_items ADD COLUMN perceptual_hash TEXT;
+ALTER TABLE media_items
+ADD COLUMN perceptual_hash TEXT;
 
 -- Index for perceptual hash lookups
-CREATE INDEX idx_media_phash ON media_items(perceptual_hash) WHERE perceptual_hash IS NOT NULL;
+CREATE INDEX idx_media_phash ON media_items (perceptual_hash)
+WHERE
+  perceptual_hash IS NOT NULL;

migrations/postgres/V15__managed_storage.sql

@@ -1,30 +1,33 @@
 -- V15: Managed File Storage
 -- Adds server-side content-addressable storage for uploaded files
-
 -- Add storage mode to media_items (external = file on disk, managed = in content-addressable storage)
-ALTER TABLE media_items ADD COLUMN storage_mode TEXT NOT NULL DEFAULT 'external';
+ALTER TABLE media_items
+ADD COLUMN storage_mode TEXT NOT NULL DEFAULT 'external';
 
 -- Original filename for managed uploads (preserved separately from file_name which may be normalized)
-ALTER TABLE media_items ADD COLUMN original_filename TEXT;
+ALTER TABLE media_items
+ADD COLUMN original_filename TEXT;
 
 -- When the file was uploaded to managed storage
-ALTER TABLE media_items ADD COLUMN uploaded_at TIMESTAMPTZ;
+ALTER TABLE media_items
+ADD COLUMN uploaded_at TIMESTAMPTZ;
 
 -- Storage key for looking up the blob (usually same as content_hash for deduplication)
-ALTER TABLE media_items ADD COLUMN storage_key TEXT;
+ALTER TABLE media_items
+ADD COLUMN storage_key TEXT;
 
 -- Managed blobs table - tracks deduplicated file storage
 CREATE TABLE managed_blobs (
-    content_hash TEXT PRIMARY KEY NOT NULL,
-    file_size BIGINT NOT NULL,
-    mime_type TEXT NOT NULL,
-    reference_count INTEGER NOT NULL DEFAULT 1,
-    stored_at TIMESTAMPTZ NOT NULL,
-    last_verified TIMESTAMPTZ
+  content_hash TEXT PRIMARY KEY NOT NULL,
+  file_size BIGINT NOT NULL,
+  mime_type TEXT NOT NULL,
+  reference_count INTEGER NOT NULL DEFAULT 1,
+  stored_at TIMESTAMPTZ NOT NULL,
+  last_verified TIMESTAMPTZ
 );
 
 -- Index for finding managed media items
-CREATE INDEX idx_media_storage_mode ON media_items(storage_mode);
+CREATE INDEX idx_media_storage_mode ON media_items (storage_mode);
 
 -- Index for finding orphaned blobs (reference_count = 0)
-CREATE INDEX idx_blobs_reference_count ON managed_blobs(reference_count);
+CREATE INDEX idx_blobs_reference_count ON managed_blobs (reference_count);

migrations/postgres/V16__sync_system.sql

@@ -1,91 +1,100 @@
 -- V16: Cross-Device Sync System
 -- Adds device registration, change tracking, and chunked upload support
-
 -- Sync devices table
 CREATE TABLE sync_devices (
-    id TEXT PRIMARY KEY NOT NULL,
-    user_id TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
-    name TEXT NOT NULL,
-    device_type TEXT NOT NULL,
-    client_version TEXT NOT NULL,
-    os_info TEXT,
-    device_token_hash TEXT NOT NULL UNIQUE,
-    last_sync_at TIMESTAMPTZ,
-    last_seen_at TIMESTAMPTZ NOT NULL,
-    sync_cursor BIGINT DEFAULT 0,
-    enabled BOOLEAN NOT NULL DEFAULT TRUE,
-    created_at TIMESTAMPTZ NOT NULL,
-    updated_at TIMESTAMPTZ NOT NULL
+  id TEXT PRIMARY KEY NOT NULL,
+  user_id TEXT NOT NULL REFERENCES users (id) ON DELETE CASCADE,
+  name TEXT NOT NULL,
+  device_type TEXT NOT NULL,
+  client_version TEXT NOT NULL,
+  os_info TEXT,
+  device_token_hash TEXT NOT NULL UNIQUE,
+  last_sync_at TIMESTAMPTZ,
+  last_seen_at TIMESTAMPTZ NOT NULL,
+  sync_cursor BIGINT DEFAULT 0,
+  enabled BOOLEAN NOT NULL DEFAULT TRUE,
+  created_at TIMESTAMPTZ NOT NULL,
+  updated_at TIMESTAMPTZ NOT NULL
 );
 
-CREATE INDEX idx_sync_devices_user ON sync_devices(user_id);
-CREATE INDEX idx_sync_devices_token ON sync_devices(device_token_hash);
+CREATE INDEX idx_sync_devices_user ON sync_devices (user_id);
+
+CREATE INDEX idx_sync_devices_token ON sync_devices (device_token_hash);
 
 -- Sync log table - tracks all changes for sync
 CREATE TABLE sync_log (
-    id TEXT PRIMARY KEY NOT NULL,
-    sequence BIGSERIAL UNIQUE NOT NULL,
-    change_type TEXT NOT NULL,
-    media_id TEXT REFERENCES media_items(id) ON DELETE SET NULL,
-    path TEXT NOT NULL,
-    content_hash TEXT,
-    file_size BIGINT,
-    metadata_json TEXT,
-    changed_by_device TEXT REFERENCES sync_devices(id) ON DELETE SET NULL,
-    timestamp TIMESTAMPTZ NOT NULL
+  id TEXT PRIMARY KEY NOT NULL,
+  sequence BIGSERIAL UNIQUE NOT NULL,
+  change_type TEXT NOT NULL,
+  media_id TEXT REFERENCES media_items (id) ON DELETE SET NULL,
+  path TEXT NOT NULL,
+  content_hash TEXT,
+  file_size BIGINT,
+  metadata_json TEXT,
+  changed_by_device TEXT REFERENCES sync_devices (id) ON DELETE SET NULL,
+  timestamp TIMESTAMPTZ NOT NULL
 );
 
-CREATE INDEX idx_sync_log_sequence ON sync_log(sequence);
-CREATE INDEX idx_sync_log_path ON sync_log(path);
-CREATE INDEX idx_sync_log_timestamp ON sync_log(timestamp);
+CREATE INDEX idx_sync_log_sequence ON sync_log (sequence);
+
+CREATE INDEX idx_sync_log_path ON sync_log (path);
+
+CREATE INDEX idx_sync_log_timestamp ON sync_log (timestamp);
 
 -- Sequence counter for sync log
 CREATE TABLE sync_sequence (
-    id INTEGER PRIMARY KEY CHECK (id = 1),
-    current_value BIGINT NOT NULL DEFAULT 0
+  id INTEGER PRIMARY KEY CHECK (id = 1),
+  current_value BIGINT NOT NULL DEFAULT 0
 );
-INSERT INTO sync_sequence (id, current_value) VALUES (1, 0);
+
+INSERT INTO
+  sync_sequence (id, current_value)
+VALUES
+  (1, 0);
 
 -- Device sync state - tracks sync status per device per file
 CREATE TABLE device_sync_state (
-    device_id TEXT NOT NULL REFERENCES sync_devices(id) ON DELETE CASCADE,
-    path TEXT NOT NULL,
-    local_hash TEXT,
-    server_hash TEXT,
-    local_mtime BIGINT,
-    server_mtime BIGINT,
-    sync_status TEXT NOT NULL,
-    last_synced_at TIMESTAMPTZ,
-    conflict_info_json TEXT,
-    PRIMARY KEY (device_id, path)
+  device_id TEXT NOT NULL REFERENCES sync_devices (id) ON DELETE CASCADE,
+  path TEXT NOT NULL,
+  local_hash TEXT,
+  server_hash TEXT,
+  local_mtime BIGINT,
+  server_mtime BIGINT,
+  sync_status TEXT NOT NULL,
+  last_synced_at TIMESTAMPTZ,
+  conflict_info_json TEXT,
+  PRIMARY KEY (device_id, path)
 );
 
-CREATE INDEX idx_device_sync_status ON device_sync_state(device_id, sync_status);
+CREATE INDEX idx_device_sync_status ON device_sync_state (device_id, sync_status);
 
 -- Upload sessions for chunked uploads
 CREATE TABLE upload_sessions (
-    id TEXT PRIMARY KEY NOT NULL,
-    device_id TEXT NOT NULL REFERENCES sync_devices(id) ON DELETE CASCADE,
-    target_path TEXT NOT NULL,
-    expected_hash TEXT NOT NULL,
-    expected_size BIGINT NOT NULL,
-    chunk_size BIGINT NOT NULL,
-    chunk_count BIGINT NOT NULL,
-    status TEXT NOT NULL,
-    created_at TIMESTAMPTZ NOT NULL,
-    expires_at TIMESTAMPTZ NOT NULL,
-    last_activity TIMESTAMPTZ NOT NULL
+  id TEXT PRIMARY KEY NOT NULL,
+  device_id TEXT NOT NULL REFERENCES sync_devices (id) ON DELETE CASCADE,
+  target_path TEXT NOT NULL,
+  expected_hash TEXT NOT NULL,
+  expected_size BIGINT NOT NULL,
+  chunk_size BIGINT NOT NULL,
+  chunk_count BIGINT NOT NULL,
+  status TEXT NOT NULL,
+  created_at TIMESTAMPTZ NOT NULL,
+  expires_at TIMESTAMPTZ NOT NULL,
+  last_activity TIMESTAMPTZ NOT NULL
 );
 
-CREATE INDEX idx_upload_sessions_device ON upload_sessions(device_id);
-CREATE INDEX idx_upload_sessions_status ON upload_sessions(status);
-CREATE INDEX idx_upload_sessions_expires ON upload_sessions(expires_at);
+CREATE INDEX idx_upload_sessions_device ON upload_sessions (device_id);
+
+CREATE INDEX idx_upload_sessions_status ON upload_sessions (status);
+
+CREATE INDEX idx_upload_sessions_expires ON upload_sessions (expires_at);
 
 -- Upload chunks - tracks received chunks
 CREATE TABLE upload_chunks (
-    upload_id TEXT NOT NULL REFERENCES upload_sessions(id) ON DELETE CASCADE,
-    chunk_index BIGINT NOT NULL,
-    offset BIGINT NOT NULL,
+  upload_id TEXT NOT NULL REFERENCES upload_sessions (id) ON DELETE CASCADE,
+  chunk_index BIGINT NOT NULL,
+  offset
+    BIGINT NOT NULL,
     size BIGINT NOT NULL,
     hash TEXT NOT NULL,
     received_at TIMESTAMPTZ NOT NULL,
@@ -94,17 +103,20 @@ CREATE TABLE upload_chunks (
 
 -- Sync conflicts
 CREATE TABLE sync_conflicts (
-    id TEXT PRIMARY KEY NOT NULL,
-    device_id TEXT NOT NULL REFERENCES sync_devices(id) ON DELETE CASCADE,
-    path TEXT NOT NULL,
-    local_hash TEXT NOT NULL,
-    local_mtime BIGINT NOT NULL,
-    server_hash TEXT NOT NULL,
-    server_mtime BIGINT NOT NULL,
-    detected_at TIMESTAMPTZ NOT NULL,
-    resolved_at TIMESTAMPTZ,
-    resolution TEXT
+  id TEXT PRIMARY KEY NOT NULL,
+  device_id TEXT NOT NULL REFERENCES sync_devices (id) ON DELETE CASCADE,
+  path TEXT NOT NULL,
+  local_hash TEXT NOT NULL,
+  local_mtime BIGINT NOT NULL,
+  server_hash TEXT NOT NULL,
+  server_mtime BIGINT NOT NULL,
+  detected_at TIMESTAMPTZ NOT NULL,
+  resolved_at TIMESTAMPTZ,
+  resolution TEXT
 );
 
-CREATE INDEX idx_sync_conflicts_device ON sync_conflicts(device_id);
-CREATE INDEX idx_sync_conflicts_unresolved ON sync_conflicts(device_id) WHERE resolved_at IS NULL;
+CREATE INDEX idx_sync_conflicts_device ON sync_conflicts (device_id);
+
+CREATE INDEX idx_sync_conflicts_unresolved ON sync_conflicts (device_id)
+WHERE
+  resolved_at IS NULL;

migrations/postgres/V17__enhanced_sharing.sql

@@ -1,68 +1,85 @@
 -- V17: Enhanced Sharing System
 -- Replaces simple share_links with comprehensive sharing capabilities
-
 -- Enhanced shares table
 CREATE TABLE shares (
-    id TEXT PRIMARY KEY NOT NULL,
-    target_type TEXT NOT NULL CHECK (target_type IN ('media', 'collection', 'tag', 'saved_search')),
-    target_id TEXT NOT NULL,
-    owner_id TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
-    recipient_type TEXT NOT NULL CHECK (recipient_type IN ('public_link', 'user', 'group', 'federated')),
-    recipient_user_id TEXT REFERENCES users(id) ON DELETE CASCADE,
-    recipient_group_id TEXT,
-    recipient_federated_handle TEXT,
-    recipient_federated_server TEXT,
-    public_token TEXT UNIQUE,
-    public_password_hash TEXT,
-    perm_view BOOLEAN NOT NULL DEFAULT TRUE,
-    perm_download BOOLEAN NOT NULL DEFAULT FALSE,
-    perm_edit BOOLEAN NOT NULL DEFAULT FALSE,
-    perm_delete BOOLEAN NOT NULL DEFAULT FALSE,
-    perm_reshare BOOLEAN NOT NULL DEFAULT FALSE,
-    perm_add BOOLEAN NOT NULL DEFAULT FALSE,
-    note TEXT,
-    expires_at TIMESTAMPTZ,
-    access_count BIGINT NOT NULL DEFAULT 0,
-    last_accessed TIMESTAMPTZ,
-    inherit_to_children BOOLEAN NOT NULL DEFAULT TRUE,
-    parent_share_id TEXT REFERENCES shares(id) ON DELETE CASCADE,
-    created_at TIMESTAMPTZ NOT NULL,
-    updated_at TIMESTAMPTZ NOT NULL,
-    UNIQUE(owner_id, target_type, target_id, recipient_type, recipient_user_id)
+  id TEXT PRIMARY KEY NOT NULL,
+  target_type TEXT NOT NULL CHECK (
+    target_type IN ('media', 'collection', 'tag', 'saved_search')
+  ),
+  target_id TEXT NOT NULL,
+  owner_id TEXT NOT NULL REFERENCES users (id) ON DELETE CASCADE,
+  recipient_type TEXT NOT NULL CHECK (
+    recipient_type IN ('public_link', 'user', 'group', 'federated')
+  ),
+  recipient_user_id TEXT REFERENCES users (id) ON DELETE CASCADE,
+  recipient_group_id TEXT,
+  recipient_federated_handle TEXT,
+  recipient_federated_server TEXT,
+  public_token TEXT UNIQUE,
+  public_password_hash TEXT,
+  perm_view BOOLEAN NOT NULL DEFAULT TRUE,
+  perm_download BOOLEAN NOT NULL DEFAULT FALSE,
+  perm_edit BOOLEAN NOT NULL DEFAULT FALSE,
+  perm_delete BOOLEAN NOT NULL DEFAULT FALSE,
+  perm_reshare BOOLEAN NOT NULL DEFAULT FALSE,
+  perm_add BOOLEAN NOT NULL DEFAULT FALSE,
+  note TEXT,
+  expires_at TIMESTAMPTZ,
+  access_count BIGINT NOT NULL DEFAULT 0,
+  last_accessed TIMESTAMPTZ,
+  inherit_to_children BOOLEAN NOT NULL DEFAULT TRUE,
+  parent_share_id TEXT REFERENCES shares (id) ON DELETE CASCADE,
+  created_at TIMESTAMPTZ NOT NULL,
+  updated_at TIMESTAMPTZ NOT NULL,
+  UNIQUE (
+    owner_id,
+    target_type,
+    target_id,
+    recipient_type,
+    recipient_user_id
+  )
 );
 
-CREATE INDEX idx_shares_owner ON shares(owner_id);
-CREATE INDEX idx_shares_recipient_user ON shares(recipient_user_id);
-CREATE INDEX idx_shares_target ON shares(target_type, target_id);
-CREATE INDEX idx_shares_token ON shares(public_token);
-CREATE INDEX idx_shares_expires ON shares(expires_at);
+CREATE INDEX idx_shares_owner ON shares (owner_id);
+
+CREATE INDEX idx_shares_recipient_user ON shares (recipient_user_id);
+
+CREATE INDEX idx_shares_target ON shares (target_type, target_id);
+
+CREATE INDEX idx_shares_token ON shares (public_token);
+
+CREATE INDEX idx_shares_expires ON shares (expires_at);
 
 -- Share activity log
 CREATE TABLE share_activity (
-    id TEXT PRIMARY KEY NOT NULL,
-    share_id TEXT NOT NULL REFERENCES shares(id) ON DELETE CASCADE,
-    actor_id TEXT REFERENCES users(id) ON DELETE SET NULL,
-    actor_ip TEXT,
-    action TEXT NOT NULL,
-    details TEXT,
-    timestamp TIMESTAMPTZ NOT NULL
+  id TEXT PRIMARY KEY NOT NULL,
+  share_id TEXT NOT NULL REFERENCES shares (id) ON DELETE CASCADE,
+  actor_id TEXT REFERENCES users (id) ON DELETE SET NULL,
+  actor_ip TEXT,
+  action TEXT NOT NULL,
+  details TEXT,
+  timestamp TIMESTAMPTZ NOT NULL
 );
 
-CREATE INDEX idx_share_activity_share ON share_activity(share_id);
-CREATE INDEX idx_share_activity_timestamp ON share_activity(timestamp);
+CREATE INDEX idx_share_activity_share ON share_activity (share_id);
+
+CREATE INDEX idx_share_activity_timestamp ON share_activity (timestamp);
 
 -- Share notifications
 CREATE TABLE share_notifications (
-    id TEXT PRIMARY KEY NOT NULL,
-    user_id TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
-    share_id TEXT NOT NULL REFERENCES shares(id) ON DELETE CASCADE,
-    notification_type TEXT NOT NULL,
-    is_read BOOLEAN NOT NULL DEFAULT FALSE,
-    created_at TIMESTAMPTZ NOT NULL
+  id TEXT PRIMARY KEY NOT NULL,
+  user_id TEXT NOT NULL REFERENCES users (id) ON DELETE CASCADE,
+  share_id TEXT NOT NULL REFERENCES shares (id) ON DELETE CASCADE,
+  notification_type TEXT NOT NULL,
+  is_read BOOLEAN NOT NULL DEFAULT FALSE,
+  created_at TIMESTAMPTZ NOT NULL
 );
 
-CREATE INDEX idx_share_notifications_user ON share_notifications(user_id);
-CREATE INDEX idx_share_notifications_unread ON share_notifications(user_id) WHERE is_read = FALSE;
+CREATE INDEX idx_share_notifications_user ON share_notifications (user_id);
+
+CREATE INDEX idx_share_notifications_unread ON share_notifications (user_id)
+WHERE
+  is_read = FALSE;
 
 -- Migrate existing share_links to new shares table
 DO $$

migrations/postgres/V18__file_management.sql

@@ -1,11 +1,13 @@
 -- V18: File Management (Rename, Move, Trash)
 -- Adds soft delete support for trash/recycle bin functionality
-
 -- Add deleted_at column for soft delete (trash)
-ALTER TABLE media_items ADD COLUMN deleted_at TIMESTAMPTZ;
+ALTER TABLE media_items
+ADD COLUMN deleted_at TIMESTAMPTZ;
 
 -- Index for efficient trash queries
-CREATE INDEX idx_media_deleted_at ON media_items(deleted_at);
+CREATE INDEX idx_media_deleted_at ON media_items (deleted_at);
 
 -- Partial index for listing non-deleted items (most common query pattern)
-CREATE INDEX idx_media_not_deleted ON media_items(id) WHERE deleted_at IS NULL;
+CREATE INDEX idx_media_not_deleted ON media_items (id)
+WHERE
+  deleted_at IS NULL;

migrations/postgres/V19__markdown_links.sql

@@ -1,35 +1,35 @@
 -- V19: Markdown Links (Obsidian-style bidirectional links)
 -- Adds support for wikilinks, markdown links, embeds, and backlink tracking
-
 -- Table for storing extracted markdown links
 CREATE TABLE IF NOT EXISTS markdown_links (
-    id TEXT PRIMARY KEY NOT NULL,
-    source_media_id TEXT NOT NULL,
-    target_path TEXT NOT NULL,           -- raw link target (wikilink or path)
-    target_media_id TEXT,                -- resolved media_id (nullable if unresolved)
-    link_type TEXT NOT NULL,             -- 'wikilink', 'markdown_link', 'embed'
-    link_text TEXT,                      -- display text for the link
-    line_number INTEGER,                 -- line number in source file
-    context TEXT,                        -- surrounding text for preview
-    created_at TIMESTAMPTZ NOT NULL,
-    FOREIGN KEY (source_media_id) REFERENCES media_items(id) ON DELETE CASCADE,
-    FOREIGN KEY (target_media_id) REFERENCES media_items(id) ON DELETE SET NULL
+  id TEXT PRIMARY KEY NOT NULL,
+  source_media_id TEXT NOT NULL,
+  target_path TEXT NOT NULL, -- raw link target (wikilink or path)
+  target_media_id TEXT, -- resolved media_id (nullable if unresolved)
+  link_type TEXT NOT NULL, -- 'wikilink', 'markdown_link', 'embed'
+  link_text TEXT, -- display text for the link
+  line_number INTEGER, -- line number in source file
+  context TEXT, -- surrounding text for preview
+  created_at TIMESTAMPTZ NOT NULL,
+  FOREIGN KEY (source_media_id) REFERENCES media_items (id) ON DELETE CASCADE,
+  FOREIGN KEY (target_media_id) REFERENCES media_items (id) ON DELETE SET NULL
 );
 
 -- Index for efficient outgoing link queries (what does this note link to?)
-CREATE INDEX idx_links_source ON markdown_links(source_media_id);
+CREATE INDEX idx_links_source ON markdown_links (source_media_id);
 
 -- Index for efficient backlink queries (what links to this note?)
-CREATE INDEX idx_links_target ON markdown_links(target_media_id);
+CREATE INDEX idx_links_target ON markdown_links (target_media_id);
 
 -- Index for path-based resolution (finding unresolved links)
-CREATE INDEX idx_links_target_path ON markdown_links(target_path);
+CREATE INDEX idx_links_target_path ON markdown_links (target_path);
 
 -- Index for link type filtering
-CREATE INDEX idx_links_type ON markdown_links(link_type);
+CREATE INDEX idx_links_type ON markdown_links (link_type);
 
 -- Track when links were last extracted from a media item
-ALTER TABLE media_items ADD COLUMN links_extracted_at TIMESTAMPTZ;
+ALTER TABLE media_items
+ADD COLUMN links_extracted_at TIMESTAMPTZ;
 
 -- Index for finding media items that need link extraction
-CREATE INDEX idx_media_links_extracted ON media_items(links_extracted_at);
+CREATE INDEX idx_media_links_extracted ON media_items (links_extracted_at);

migrations/postgres/V1__initial_schema.sql

@@ -1,73 +1,75 @@
 CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
+
 CREATE EXTENSION IF NOT EXISTS pg_trgm;
 
-CREATE TABLE IF NOT EXISTS root_dirs (
-    path TEXT PRIMARY KEY NOT NULL
-);
+CREATE TABLE IF NOT EXISTS root_dirs (path TEXT PRIMARY KEY NOT NULL);
 
 CREATE TABLE IF NOT EXISTS media_items (
-    id UUID PRIMARY KEY NOT NULL,
-    path TEXT NOT NULL UNIQUE,
-    file_name TEXT NOT NULL,
-    media_type TEXT NOT NULL,
-    content_hash TEXT NOT NULL UNIQUE,
-    file_size BIGINT NOT NULL,
-    title TEXT,
-    artist TEXT,
-    album TEXT,
-    genre TEXT,
-    year INTEGER,
-    duration_secs DOUBLE PRECISION,
-    description TEXT,
-    created_at TIMESTAMPTZ NOT NULL,
-    updated_at TIMESTAMPTZ NOT NULL
+  id UUID PRIMARY KEY NOT NULL,
+  path TEXT NOT NULL UNIQUE,
+  file_name TEXT NOT NULL,
+  media_type TEXT NOT NULL,
+  content_hash TEXT NOT NULL UNIQUE,
+  file_size BIGINT NOT NULL,
+  title TEXT,
+  artist TEXT,
+  album TEXT,
+  genre TEXT,
+  year INTEGER,
+  duration_secs DOUBLE PRECISION,
+  description TEXT,
+  created_at TIMESTAMPTZ NOT NULL,
+  updated_at TIMESTAMPTZ NOT NULL
 );
 
 CREATE TABLE IF NOT EXISTS tags (
-    id UUID PRIMARY KEY NOT NULL,
-    name TEXT NOT NULL,
-    parent_id UUID REFERENCES tags(id) ON DELETE SET NULL,
-    created_at TIMESTAMPTZ NOT NULL
+  id UUID PRIMARY KEY NOT NULL,
+  name TEXT NOT NULL,
+  parent_id UUID REFERENCES tags (id) ON DELETE SET NULL,
+  created_at TIMESTAMPTZ NOT NULL
 );
 
-CREATE UNIQUE INDEX IF NOT EXISTS idx_tags_name_parent ON tags(name, COALESCE(parent_id, '00000000-0000-0000-0000-000000000000'));
+CREATE UNIQUE INDEX IF NOT EXISTS idx_tags_name_parent ON tags (
+  name,
+  COALESCE(parent_id, '00000000-0000-0000-0000-000000000000')
+);
 
 CREATE TABLE IF NOT EXISTS media_tags (
-    media_id UUID NOT NULL REFERENCES media_items(id) ON DELETE CASCADE,
-    tag_id UUID NOT NULL REFERENCES tags(id) ON DELETE CASCADE,
-    PRIMARY KEY (media_id, tag_id)
+  media_id UUID NOT NULL REFERENCES media_items (id) ON DELETE CASCADE,
+  tag_id UUID NOT NULL REFERENCES tags (id) ON DELETE CASCADE,
+  PRIMARY KEY (media_id, tag_id)
 );
 
 CREATE TABLE IF NOT EXISTS collections (
-    id UUID PRIMARY KEY NOT NULL,
-    name TEXT NOT NULL,
-    description TEXT,
-    kind TEXT NOT NULL,
-    filter_query TEXT,
-    created_at TIMESTAMPTZ NOT NULL,
-    updated_at TIMESTAMPTZ NOT NULL
+  id UUID PRIMARY KEY NOT NULL,
+  name TEXT NOT NULL,
+  description TEXT,
+  kind TEXT NOT NULL,
+  filter_query TEXT,
+  created_at TIMESTAMPTZ NOT NULL,
+  updated_at TIMESTAMPTZ NOT NULL
 );
 
 CREATE TABLE IF NOT EXISTS collection_members (
-    collection_id UUID NOT NULL REFERENCES collections(id) ON DELETE CASCADE,
-    media_id UUID NOT NULL REFERENCES media_items(id) ON DELETE CASCADE,
-    position INTEGER NOT NULL DEFAULT 0,
-    added_at TIMESTAMPTZ NOT NULL,
-    PRIMARY KEY (collection_id, media_id)
+  collection_id UUID NOT NULL REFERENCES collections (id) ON DELETE CASCADE,
+  media_id UUID NOT NULL REFERENCES media_items (id) ON DELETE CASCADE,
+  position INTEGER NOT NULL DEFAULT 0,
+  added_at TIMESTAMPTZ NOT NULL,
+  PRIMARY KEY (collection_id, media_id)
 );
 
 CREATE TABLE IF NOT EXISTS audit_log (
-    id UUID PRIMARY KEY NOT NULL,
-    media_id UUID REFERENCES media_items(id) ON DELETE SET NULL,
-    action TEXT NOT NULL,
-    details TEXT,
-    timestamp TIMESTAMPTZ NOT NULL
+  id UUID PRIMARY KEY NOT NULL,
+  media_id UUID REFERENCES media_items (id) ON DELETE SET NULL,
+  action TEXT NOT NULL,
+  details TEXT,
+  timestamp TIMESTAMPTZ NOT NULL
 );
 
 CREATE TABLE IF NOT EXISTS custom_fields (
-    media_id UUID NOT NULL REFERENCES media_items(id) ON DELETE CASCADE,
-    field_name TEXT NOT NULL,
-    field_type TEXT NOT NULL,
-    field_value TEXT NOT NULL,
-    PRIMARY KEY (media_id, field_name)
+  media_id UUID NOT NULL REFERENCES media_items (id) ON DELETE CASCADE,
+  field_name TEXT NOT NULL,
+  field_type TEXT NOT NULL,
+  field_value TEXT NOT NULL,
+  PRIMARY KEY (media_id, field_name)
 );

migrations/postgres/V2__fts_indexes.sql

@@ -1,11 +1,12 @@
-ALTER TABLE media_items ADD COLUMN IF NOT EXISTS search_vector tsvector
-    GENERATED ALWAYS AS (
-        setweight(to_tsvector('english', COALESCE(title, '')), 'A') ||
-        setweight(to_tsvector('english', COALESCE(artist, '')), 'B') ||
-        setweight(to_tsvector('english', COALESCE(album, '')), 'B') ||
-        setweight(to_tsvector('english', COALESCE(genre, '')), 'C') ||
-        setweight(to_tsvector('english', COALESCE(description, '')), 'C') ||
-        setweight(to_tsvector('english', COALESCE(file_name, '')), 'D')
-    ) STORED;
+ALTER TABLE media_items
+ADD COLUMN IF NOT EXISTS search_vector tsvector GENERATED ALWAYS AS (
+  setweight(to_tsvector('english', COALESCE(title, '')), 'A') || setweight(to_tsvector('english', COALESCE(artist, '')), 'B') || setweight(to_tsvector('english', COALESCE(album, '')), 'B') || setweight(to_tsvector('english', COALESCE(genre, '')), 'C') || setweight(
+    to_tsvector('english', COALESCE(description, '')),
+    'C'
+  ) || setweight(
+    to_tsvector('english', COALESCE(file_name, '')),
+    'D'
+  )
+) STORED;
 
-CREATE INDEX IF NOT EXISTS idx_media_search ON media_items USING GIN(search_vector);
+CREATE INDEX IF NOT EXISTS idx_media_search ON media_items USING GIN (search_vector);

migrations/postgres/V3__audit_indexes.sql

@@ -1,8 +1,15 @@
-CREATE INDEX IF NOT EXISTS idx_audit_media_id ON audit_log(media_id);
-CREATE INDEX IF NOT EXISTS idx_audit_timestamp ON audit_log(timestamp);
-CREATE INDEX IF NOT EXISTS idx_audit_action ON audit_log(action);
-CREATE INDEX IF NOT EXISTS idx_media_content_hash ON media_items(content_hash);
-CREATE INDEX IF NOT EXISTS idx_media_media_type ON media_items(media_type);
-CREATE INDEX IF NOT EXISTS idx_media_created_at ON media_items(created_at);
-CREATE INDEX IF NOT EXISTS idx_media_title_trgm ON media_items USING GIN(title gin_trgm_ops);
-CREATE INDEX IF NOT EXISTS idx_media_artist_trgm ON media_items USING GIN(artist gin_trgm_ops);
+CREATE INDEX IF NOT EXISTS idx_audit_media_id ON audit_log (media_id);
+
+CREATE INDEX IF NOT EXISTS idx_audit_timestamp ON audit_log (timestamp);
+
+CREATE INDEX IF NOT EXISTS idx_audit_action ON audit_log (action);
+
+CREATE INDEX IF NOT EXISTS idx_media_content_hash ON media_items (content_hash);
+
+CREATE INDEX IF NOT EXISTS idx_media_media_type ON media_items (media_type);
+
+CREATE INDEX IF NOT EXISTS idx_media_created_at ON media_items (created_at);
+
+CREATE INDEX IF NOT EXISTS idx_media_title_trgm ON media_items USING GIN (title gin_trgm_ops);
+
+CREATE INDEX IF NOT EXISTS idx_media_artist_trgm ON media_items USING GIN (artist gin_trgm_ops);

migrations/postgres/V4__thumbnail_path.sql

@@ -1 +1,2 @@
-ALTER TABLE media_items ADD COLUMN thumbnail_path TEXT;
+ALTER TABLE media_items
+ADD COLUMN thumbnail_path TEXT;

migrations/postgres/V5__integrity_and_saved_searches.sql

@@ -1,12 +1,15 @@
 -- Integrity tracking columns
-ALTER TABLE media_items ADD COLUMN last_verified_at TIMESTAMPTZ;
-ALTER TABLE media_items ADD COLUMN integrity_status TEXT DEFAULT 'unverified';
+ALTER TABLE media_items
+ADD COLUMN last_verified_at TIMESTAMPTZ;
+
+ALTER TABLE media_items
+ADD COLUMN integrity_status TEXT DEFAULT 'unverified';
 
 -- Saved searches
 CREATE TABLE IF NOT EXISTS saved_searches (
-    id UUID PRIMARY KEY,
-    name TEXT NOT NULL,
-    query TEXT NOT NULL,
-    sort_order TEXT,
-    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+  id UUID PRIMARY KEY,
+  name TEXT NOT NULL,
+  query TEXT NOT NULL,
+  sort_order TEXT,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
 );

migrations/postgres/V6__plugin_system.sql

@@ -1,15 +1,16 @@
 -- Plugin registry table
 CREATE TABLE plugin_registry (
-    id TEXT PRIMARY KEY,
-    name TEXT NOT NULL,
-    version TEXT NOT NULL,
-    enabled BOOLEAN NOT NULL DEFAULT TRUE,
-    config_json TEXT,
-    manifest_json TEXT,
-    installed_at TIMESTAMP WITH TIME ZONE NOT NULL,
-    updated_at TIMESTAMP WITH TIME ZONE NOT NULL
+  id TEXT PRIMARY KEY,
+  name TEXT NOT NULL,
+  version TEXT NOT NULL,
+  enabled BOOLEAN NOT NULL DEFAULT TRUE,
+  config_json TEXT,
+  manifest_json TEXT,
+  installed_at TIMESTAMP WITH TIME ZONE NOT NULL,
+  updated_at TIMESTAMP WITH TIME ZONE NOT NULL
 );
 
 -- Index for quick lookups
-CREATE INDEX idx_plugin_registry_enabled ON plugin_registry(enabled);
-CREATE INDEX idx_plugin_registry_name ON plugin_registry(name);
+CREATE INDEX idx_plugin_registry_enabled ON plugin_registry (enabled);
+
+CREATE INDEX idx_plugin_registry_name ON plugin_registry (name);

migrations/postgres/V7__user_management.sql

@@ -1,35 +1,37 @@
 -- Users table
 CREATE TABLE users (
-    id UUID PRIMARY KEY,
-    username TEXT UNIQUE NOT NULL,
-    password_hash TEXT NOT NULL,
-    role JSONB NOT NULL,
-    created_at TIMESTAMP WITH TIME ZONE NOT NULL,
-    updated_at TIMESTAMP WITH TIME ZONE NOT NULL
+  id UUID PRIMARY KEY,
+  username TEXT UNIQUE NOT NULL,
+  password_hash TEXT NOT NULL,
+  role JSONB NOT NULL,
+  created_at TIMESTAMP WITH TIME ZONE NOT NULL,
+  updated_at TIMESTAMP WITH TIME ZONE NOT NULL
 );
 
 -- User profiles table
 CREATE TABLE user_profiles (
-    user_id UUID PRIMARY KEY,
-    avatar_path TEXT,
-    bio TEXT,
-    preferences_json JSONB NOT NULL DEFAULT '{}',
-    created_at TIMESTAMP WITH TIME ZONE NOT NULL,
-    updated_at TIMESTAMP WITH TIME ZONE NOT NULL,
-    FOREIGN KEY (user_id) REFERENCES users(id)
+  user_id UUID PRIMARY KEY,
+  avatar_path TEXT,
+  bio TEXT,
+  preferences_json JSONB NOT NULL DEFAULT '{}',
+  created_at TIMESTAMP WITH TIME ZONE NOT NULL,
+  updated_at TIMESTAMP WITH TIME ZONE NOT NULL,
+  FOREIGN KEY (user_id) REFERENCES users (id)
 );
 
 -- User library access table
 CREATE TABLE user_libraries (
-    user_id UUID NOT NULL,
-    root_path TEXT NOT NULL,
-    permission JSONB NOT NULL,
-    granted_at TIMESTAMP WITH TIME ZONE NOT NULL,
-    PRIMARY KEY (user_id, root_path),
-    FOREIGN KEY (user_id) REFERENCES users(id)
+  user_id UUID NOT NULL,
+  root_path TEXT NOT NULL,
+  permission JSONB NOT NULL,
+  granted_at TIMESTAMP WITH TIME ZONE NOT NULL,
+  PRIMARY KEY (user_id, root_path),
+  FOREIGN KEY (user_id) REFERENCES users (id)
 );
 
 -- Indexes for efficient lookups
-CREATE INDEX idx_users_username ON users(username);
-CREATE INDEX idx_user_libraries_user_id ON user_libraries(user_id);
-CREATE INDEX idx_user_libraries_root_path ON user_libraries(root_path);
+CREATE INDEX idx_users_username ON users (username);
+
+CREATE INDEX idx_user_libraries_user_id ON user_libraries (user_id);
+
+CREATE INDEX idx_user_libraries_root_path ON user_libraries (root_path);

migrations/postgres/V8__media_server_features.sql

@@ -1,131 +1,136 @@
 -- Ratings
 CREATE TABLE IF NOT EXISTS ratings (
-    id UUID PRIMARY KEY,
-    user_id UUID NOT NULL,
-    media_id UUID NOT NULL REFERENCES media_items(id) ON DELETE CASCADE,
-    stars INTEGER NOT NULL CHECK (stars >= 1 AND stars <= 5),
-    review_text TEXT,
-    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
-    UNIQUE(user_id, media_id)
+  id UUID PRIMARY KEY,
+  user_id UUID NOT NULL,
+  media_id UUID NOT NULL REFERENCES media_items (id) ON DELETE CASCADE,
+  stars INTEGER NOT NULL CHECK (
+    stars >= 1
+    AND stars <= 5
+  ),
+  review_text TEXT,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  UNIQUE (user_id, media_id)
 );
 
 -- Comments
 CREATE TABLE IF NOT EXISTS comments (
-    id UUID PRIMARY KEY,
-    user_id UUID NOT NULL,
-    media_id UUID NOT NULL REFERENCES media_items(id) ON DELETE CASCADE,
-    parent_comment_id UUID REFERENCES comments(id) ON DELETE CASCADE,
-    text TEXT NOT NULL,
-    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+  id UUID PRIMARY KEY,
+  user_id UUID NOT NULL,
+  media_id UUID NOT NULL REFERENCES media_items (id) ON DELETE CASCADE,
+  parent_comment_id UUID REFERENCES comments (id) ON DELETE CASCADE,
+  text TEXT NOT NULL,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
 );
 
 -- Favorites
 CREATE TABLE IF NOT EXISTS favorites (
-    user_id UUID NOT NULL,
-    media_id UUID NOT NULL REFERENCES media_items(id) ON DELETE CASCADE,
-    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
-    PRIMARY KEY (user_id, media_id)
+  user_id UUID NOT NULL,
+  media_id UUID NOT NULL REFERENCES media_items (id) ON DELETE CASCADE,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  PRIMARY KEY (user_id, media_id)
 );
 
 -- Share links
 CREATE TABLE IF NOT EXISTS share_links (
-    id UUID PRIMARY KEY,
-    media_id UUID NOT NULL REFERENCES media_items(id) ON DELETE CASCADE,
-    created_by UUID NOT NULL,
-    token TEXT NOT NULL UNIQUE,
-    password_hash TEXT,
-    expires_at TIMESTAMPTZ,
-    view_count INTEGER NOT NULL DEFAULT 0,
-    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+  id UUID PRIMARY KEY,
+  media_id UUID NOT NULL REFERENCES media_items (id) ON DELETE CASCADE,
+  created_by UUID NOT NULL,
+  token TEXT NOT NULL UNIQUE,
+  password_hash TEXT,
+  expires_at TIMESTAMPTZ,
+  view_count INTEGER NOT NULL DEFAULT 0,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
 );
 
 -- Playlists
 CREATE TABLE IF NOT EXISTS playlists (
-    id UUID PRIMARY KEY,
-    owner_id UUID NOT NULL,
-    name TEXT NOT NULL,
-    description TEXT,
-    is_public BOOLEAN NOT NULL DEFAULT FALSE,
-    is_smart BOOLEAN NOT NULL DEFAULT FALSE,
-    filter_query TEXT,
-    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
-    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+  id UUID PRIMARY KEY,
+  owner_id UUID NOT NULL,
+  name TEXT NOT NULL,
+  description TEXT,
+  is_public BOOLEAN NOT NULL DEFAULT FALSE,
+  is_smart BOOLEAN NOT NULL DEFAULT FALSE,
+  filter_query TEXT,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
 );
 
 -- Playlist items
 CREATE TABLE IF NOT EXISTS playlist_items (
-    playlist_id UUID NOT NULL REFERENCES playlists(id) ON DELETE CASCADE,
-    media_id UUID NOT NULL REFERENCES media_items(id) ON DELETE CASCADE,
-    position INTEGER NOT NULL DEFAULT 0,
-    added_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
-    PRIMARY KEY (playlist_id, media_id)
+  playlist_id UUID NOT NULL REFERENCES playlists (id) ON DELETE CASCADE,
+  media_id UUID NOT NULL REFERENCES media_items (id) ON DELETE CASCADE,
+  position INTEGER NOT NULL DEFAULT 0,
+  added_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  PRIMARY KEY (playlist_id, media_id)
 );
 
 -- Usage events
 CREATE TABLE IF NOT EXISTS usage_events (
-    id UUID PRIMARY KEY,
-    media_id UUID REFERENCES media_items(id) ON DELETE SET NULL,
-    user_id UUID,
-    event_type TEXT NOT NULL,
-    timestamp TIMESTAMPTZ NOT NULL DEFAULT NOW(),
-    duration_secs DOUBLE PRECISION,
-    context_json JSONB
+  id UUID PRIMARY KEY,
+  media_id UUID REFERENCES media_items (id) ON DELETE SET NULL,
+  user_id UUID,
+  event_type TEXT NOT NULL,
+  timestamp TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  duration_secs DOUBLE PRECISION,
+  context_json JSONB
 );
 
-CREATE INDEX IF NOT EXISTS idx_usage_events_media ON usage_events(media_id);
-CREATE INDEX IF NOT EXISTS idx_usage_events_user ON usage_events(user_id);
-CREATE INDEX IF NOT EXISTS idx_usage_events_timestamp ON usage_events(timestamp);
+CREATE INDEX IF NOT EXISTS idx_usage_events_media ON usage_events (media_id);
+
+CREATE INDEX IF NOT EXISTS idx_usage_events_user ON usage_events (user_id);
+
+CREATE INDEX IF NOT EXISTS idx_usage_events_timestamp ON usage_events (timestamp);
 
 -- Watch history / progress
 CREATE TABLE IF NOT EXISTS watch_history (
-    id UUID PRIMARY KEY,
-    user_id UUID NOT NULL,
-    media_id UUID NOT NULL REFERENCES media_items(id) ON DELETE CASCADE,
-    progress_secs DOUBLE PRECISION NOT NULL DEFAULT 0,
-    last_watched TIMESTAMPTZ NOT NULL DEFAULT NOW(),
-    UNIQUE(user_id, media_id)
+  id UUID PRIMARY KEY,
+  user_id UUID NOT NULL,
+  media_id UUID NOT NULL REFERENCES media_items (id) ON DELETE CASCADE,
+  progress_secs DOUBLE PRECISION NOT NULL DEFAULT 0,
+  last_watched TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  UNIQUE (user_id, media_id)
 );
 
 -- Subtitles
 CREATE TABLE IF NOT EXISTS subtitles (
-    id UUID PRIMARY KEY,
-    media_id UUID NOT NULL REFERENCES media_items(id) ON DELETE CASCADE,
-    language TEXT,
-    format TEXT NOT NULL,
-    file_path TEXT,
-    is_embedded BOOLEAN NOT NULL DEFAULT FALSE,
-    track_index INTEGER,
-    offset_ms INTEGER NOT NULL DEFAULT 0,
-    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+  id UUID PRIMARY KEY,
+  media_id UUID NOT NULL REFERENCES media_items (id) ON DELETE CASCADE,
+  language TEXT,
+  format TEXT NOT NULL,
+  file_path TEXT,
+  is_embedded BOOLEAN NOT NULL DEFAULT FALSE,
+  track_index INTEGER,
+  offset_ms INTEGER NOT NULL DEFAULT 0,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
 );
 
-CREATE INDEX IF NOT EXISTS idx_subtitles_media ON subtitles(media_id);
+CREATE INDEX IF NOT EXISTS idx_subtitles_media ON subtitles (media_id);
 
 -- External metadata (enrichment)
 CREATE TABLE IF NOT EXISTS external_metadata (
-    id UUID PRIMARY KEY,
-    media_id UUID NOT NULL REFERENCES media_items(id) ON DELETE CASCADE,
-    source TEXT NOT NULL,
-    external_id TEXT,
-    metadata_json JSONB NOT NULL DEFAULT '{}',
-    confidence DOUBLE PRECISION NOT NULL DEFAULT 0.0,
-    last_updated TIMESTAMPTZ NOT NULL DEFAULT NOW()
+  id UUID PRIMARY KEY,
+  media_id UUID NOT NULL REFERENCES media_items (id) ON DELETE CASCADE,
+  source TEXT NOT NULL,
+  external_id TEXT,
+  metadata_json JSONB NOT NULL DEFAULT '{}',
+  confidence DOUBLE PRECISION NOT NULL DEFAULT 0.0,
+  last_updated TIMESTAMPTZ NOT NULL DEFAULT NOW()
 );
 
-CREATE INDEX IF NOT EXISTS idx_external_metadata_media ON external_metadata(media_id);
+CREATE INDEX IF NOT EXISTS idx_external_metadata_media ON external_metadata (media_id);
 
 -- Transcode sessions
 CREATE TABLE IF NOT EXISTS transcode_sessions (
-    id UUID PRIMARY KEY,
-    media_id UUID NOT NULL REFERENCES media_items(id) ON DELETE CASCADE,
-    user_id UUID,
-    profile TEXT NOT NULL,
-    cache_path TEXT NOT NULL,
-    status TEXT NOT NULL DEFAULT 'pending',
-    progress DOUBLE PRECISION NOT NULL DEFAULT 0.0,
-    error_message TEXT,
-    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
-    expires_at TIMESTAMPTZ
+  id UUID PRIMARY KEY,
+  media_id UUID NOT NULL REFERENCES media_items (id) ON DELETE CASCADE,
+  user_id UUID,
+  profile TEXT NOT NULL,
+  cache_path TEXT NOT NULL,
+  status TEXT NOT NULL DEFAULT 'pending',
+  progress DOUBLE PRECISION NOT NULL DEFAULT 0.0,
+  error_message TEXT,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  expires_at TIMESTAMPTZ
 );
 
-CREATE INDEX IF NOT EXISTS idx_transcode_sessions_media ON transcode_sessions(media_id);
+CREATE INDEX IF NOT EXISTS idx_transcode_sessions_media ON transcode_sessions (media_id);

migrations/postgres/V9__fix_indexes_and_constraints.sql

@@ -1,19 +1,26 @@
 -- Drop redundant indexes (already covered by UNIQUE constraints)
 DROP INDEX IF EXISTS idx_users_username;
+
 DROP INDEX IF EXISTS idx_user_libraries_user_id;
 
 -- Add missing indexes for comments table
-CREATE INDEX IF NOT EXISTS idx_comments_media ON comments(media_id);
-CREATE INDEX IF NOT EXISTS idx_comments_parent ON comments(parent_comment_id);
+CREATE INDEX IF NOT EXISTS idx_comments_media ON comments (media_id);
+
+CREATE INDEX IF NOT EXISTS idx_comments_parent ON comments (parent_comment_id);
 
 -- Remove duplicates before adding unique constraint
 DELETE FROM external_metadata e1
-WHERE EXISTS (
-    SELECT 1 FROM external_metadata e2
-    WHERE e1.media_id = e2.media_id
-    AND e1.source = e2.source
-    AND e1.ctid < e2.ctid
-);
+WHERE
+  EXISTS (
+    SELECT
+      1
+    FROM
+      external_metadata e2
+    WHERE
+      e1.media_id = e2.media_id
+      AND e1.source = e2.source
+      AND e1.ctid < e2.ctid
+  );
 
 -- Add unique constraint for external_metadata (idempotent)
 DO $$

migrations/sqlite/V10__incremental_scan.sql

@@ -1,19 +1,19 @@
 -- Add file_mtime column to media_items table for incremental scanning
 -- Stores Unix timestamp in seconds of the file's modification time
-
-ALTER TABLE media_items ADD COLUMN file_mtime INTEGER;
+ALTER TABLE media_items
+ADD COLUMN file_mtime INTEGER;
 
 -- Create index for quick mtime lookups
-CREATE INDEX IF NOT EXISTS idx_media_items_file_mtime ON media_items(file_mtime);
+CREATE INDEX IF NOT EXISTS idx_media_items_file_mtime ON media_items (file_mtime);
 
 -- Create a scan_history table to track when each directory was last scanned
 CREATE TABLE IF NOT EXISTS scan_history (
-    id TEXT PRIMARY KEY,
-    directory TEXT NOT NULL UNIQUE,
-    last_scan_at TEXT NOT NULL,
-    files_scanned INTEGER NOT NULL DEFAULT 0,
-    files_changed INTEGER NOT NULL DEFAULT 0,
-    scan_duration_ms INTEGER
+  id TEXT PRIMARY KEY,
+  directory TEXT NOT NULL UNIQUE,
+  last_scan_at TEXT NOT NULL,
+  files_scanned INTEGER NOT NULL DEFAULT 0,
+  files_changed INTEGER NOT NULL DEFAULT 0,
+  scan_duration_ms INTEGER
 );
 
-CREATE INDEX IF NOT EXISTS idx_scan_history_directory ON scan_history(directory);
+CREATE INDEX IF NOT EXISTS idx_scan_history_directory ON scan_history (directory);

migrations/sqlite/V11__session_persistence.sql

@@ -1,18 +1,17 @@
 -- Session persistence for database-backed sessions
 -- Replaces in-memory session storage
-
 CREATE TABLE IF NOT EXISTS sessions (
-    session_token TEXT PRIMARY KEY NOT NULL,
-    user_id TEXT,
-    username TEXT NOT NULL,
-    role TEXT NOT NULL,
-    created_at TEXT NOT NULL,
-    expires_at TEXT NOT NULL,
-    last_accessed TEXT NOT NULL
+  session_token TEXT PRIMARY KEY NOT NULL,
+  user_id TEXT,
+  username TEXT NOT NULL,
+  role TEXT NOT NULL,
+  created_at TEXT NOT NULL,
+  expires_at TEXT NOT NULL,
+  last_accessed TEXT NOT NULL
 );
 
 -- Index for efficient cleanup of expired sessions
-CREATE INDEX IF NOT EXISTS idx_sessions_expires_at ON sessions(expires_at);
+CREATE INDEX IF NOT EXISTS idx_sessions_expires_at ON sessions (expires_at);
 
 -- Index for listing sessions by username
-CREATE INDEX IF NOT EXISTS idx_sessions_username ON sessions(username);
+CREATE INDEX IF NOT EXISTS idx_sessions_username ON sessions (username);

migrations/sqlite/V12__book_management.sql

@@ -1,54 +1,62 @@
 -- V12: Book Management Schema
 -- Adds comprehensive book metadata tracking, authors, and identifiers
-
 -- Book metadata (supplements media_items for EPUB/PDF/MOBI)
 CREATE TABLE book_metadata (
-    media_id TEXT PRIMARY KEY REFERENCES media_items(id) ON DELETE CASCADE,
-    isbn TEXT,
-    isbn13 TEXT,              -- Normalized ISBN-13 for lookups
-    publisher TEXT,
-    language TEXT,            -- ISO 639-1 code
-    page_count INTEGER,
-    publication_date TEXT,    -- ISO 8601 date string
-    series_name TEXT,
-    series_index REAL,        -- Supports 1.5, etc.
-    format TEXT,              -- 'epub', 'pdf', 'mobi', 'azw3'
-    created_at TEXT NOT NULL DEFAULT (datetime('now')),
-    updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+  media_id TEXT PRIMARY KEY REFERENCES media_items (id) ON DELETE CASCADE,
+  isbn TEXT,
+  isbn13 TEXT, -- Normalized ISBN-13 for lookups
+  publisher TEXT,
+  language TEXT, -- ISO 639-1 code
+  page_count INTEGER,
+  publication_date TEXT, -- ISO 8601 date string
+  series_name TEXT,
+  series_index REAL, -- Supports 1.5, etc.
+  format TEXT, -- 'epub', 'pdf', 'mobi', 'azw3'
+  created_at TEXT NOT NULL DEFAULT (datetime ('now')),
+  updated_at TEXT NOT NULL DEFAULT (datetime ('now'))
 ) STRICT;
 
-CREATE INDEX idx_book_isbn13 ON book_metadata(isbn13);
-CREATE INDEX idx_book_series ON book_metadata(series_name, series_index);
-CREATE INDEX idx_book_publisher ON book_metadata(publisher);
-CREATE INDEX idx_book_language ON book_metadata(language);
+CREATE INDEX idx_book_isbn13 ON book_metadata (isbn13);
+
+CREATE INDEX idx_book_series ON book_metadata (series_name, series_index);
+
+CREATE INDEX idx_book_publisher ON book_metadata (publisher);
+
+CREATE INDEX idx_book_language ON book_metadata (language);
 
 -- Multiple authors per book (many-to-many)
 CREATE TABLE book_authors (
-    media_id TEXT NOT NULL REFERENCES media_items(id) ON DELETE CASCADE,
-    author_name TEXT NOT NULL,
-    author_sort TEXT,         -- "Last, First" for sorting
-    role TEXT NOT NULL DEFAULT 'author', -- author, translator, editor, illustrator
-    position INTEGER NOT NULL DEFAULT 0,
-    PRIMARY KEY (media_id, author_name, role)
+  media_id TEXT NOT NULL REFERENCES media_items (id) ON DELETE CASCADE,
+  author_name TEXT NOT NULL,
+  author_sort TEXT, -- "Last, First" for sorting
+  role TEXT NOT NULL DEFAULT 'author', -- author, translator, editor, illustrator
+  position INTEGER NOT NULL DEFAULT 0,
+  PRIMARY KEY (media_id, author_name, role)
 ) STRICT;
 
-CREATE INDEX idx_book_authors_name ON book_authors(author_name);
-CREATE INDEX idx_book_authors_sort ON book_authors(author_sort);
+CREATE INDEX idx_book_authors_name ON book_authors (author_name);
+
+CREATE INDEX idx_book_authors_sort ON book_authors (author_sort);
 
 -- Multiple identifiers (ISBN variants, ASIN, DOI, etc.)
 CREATE TABLE book_identifiers (
-    media_id TEXT NOT NULL REFERENCES media_items(id) ON DELETE CASCADE,
-    identifier_type TEXT NOT NULL,  -- isbn, isbn13, asin, doi, lccn, oclc
-    identifier_value TEXT NOT NULL,
-    PRIMARY KEY (media_id, identifier_type, identifier_value)
+  media_id TEXT NOT NULL REFERENCES media_items (id) ON DELETE CASCADE,
+  identifier_type TEXT NOT NULL, -- isbn, isbn13, asin, doi, lccn, oclc
+  identifier_value TEXT NOT NULL,
+  PRIMARY KEY (media_id, identifier_type, identifier_value)
 ) STRICT;
 
-CREATE INDEX idx_book_identifiers ON book_identifiers(identifier_type, identifier_value);
+CREATE INDEX idx_book_identifiers ON book_identifiers (identifier_type, identifier_value);
 
 -- Trigger to update updated_at on book_metadata changes
 CREATE TRIGGER update_book_metadata_timestamp
-    AFTER UPDATE ON book_metadata
-    FOR EACH ROW
+AFTER
+UPDATE ON book_metadata FOR EACH ROW
 BEGIN
-    UPDATE book_metadata SET updated_at = datetime('now') WHERE media_id = NEW.media_id;
+UPDATE book_metadata
+SET
+  updated_at = datetime ('now')
+WHERE
+  media_id = NEW.media_id;
+
 END;

migrations/sqlite/V13__photo_metadata.sql

@@ -1,15 +1,40 @@
 -- V13: Enhanced photo metadata support
 -- Add photo-specific fields to media_items table
+ALTER TABLE media_items
+ADD COLUMN date_taken TIMESTAMP;
 
-ALTER TABLE media_items ADD COLUMN date_taken TIMESTAMP;
-ALTER TABLE media_items ADD COLUMN latitude REAL;
-ALTER TABLE media_items ADD COLUMN longitude REAL;
-ALTER TABLE media_items ADD COLUMN camera_make TEXT;
-ALTER TABLE media_items ADD COLUMN camera_model TEXT;
-ALTER TABLE media_items ADD COLUMN rating INTEGER CHECK (rating >= 0 AND rating <= 5);
+ALTER TABLE media_items
+ADD COLUMN latitude REAL;
+
+ALTER TABLE media_items
+ADD COLUMN longitude REAL;
+
+ALTER TABLE media_items
+ADD COLUMN camera_make TEXT;
+
+ALTER TABLE media_items
+ADD COLUMN camera_model TEXT;
+
+ALTER TABLE media_items
+ADD COLUMN rating INTEGER CHECK (
+  rating >= 0
+  AND rating <= 5
+);
 
 -- Indexes for photo queries
-CREATE INDEX idx_media_date_taken ON media_items(date_taken) WHERE date_taken IS NOT NULL;
-CREATE INDEX idx_media_location ON media_items(latitude, longitude) WHERE latitude IS NOT NULL AND longitude IS NOT NULL;
-CREATE INDEX idx_media_camera ON media_items(camera_make) WHERE camera_make IS NOT NULL;
-CREATE INDEX idx_media_rating ON media_items(rating) WHERE rating IS NOT NULL;
+CREATE INDEX idx_media_date_taken ON media_items (date_taken)
+WHERE
+  date_taken IS NOT NULL;
+
+CREATE INDEX idx_media_location ON media_items (latitude, longitude)
+WHERE
+  latitude IS NOT NULL
+  AND longitude IS NOT NULL;
+
+CREATE INDEX idx_media_camera ON media_items (camera_make)
+WHERE
+  camera_make IS NOT NULL;
+
+CREATE INDEX idx_media_rating ON media_items (rating)
+WHERE
+  rating IS NOT NULL;

migrations/sqlite/V14__perceptual_hash.sql

@@ -1,7 +1,9 @@
 -- V14: Perceptual hash for duplicate detection
 -- Add perceptual hash column for image similarity detection
-
-ALTER TABLE media_items ADD COLUMN perceptual_hash TEXT;
+ALTER TABLE media_items
+ADD COLUMN perceptual_hash TEXT;
 
 -- Index for perceptual hash lookups
-CREATE INDEX idx_media_phash ON media_items(perceptual_hash) WHERE perceptual_hash IS NOT NULL;
+CREATE INDEX idx_media_phash ON media_items (perceptual_hash)
+WHERE
+  perceptual_hash IS NOT NULL;

migrations/sqlite/V15__managed_storage.sql

@@ -1,30 +1,33 @@
 -- V15: Managed File Storage
 -- Adds server-side content-addressable storage for uploaded files
-
 -- Add storage mode to media_items (external = file on disk, managed = in content-addressable storage)
-ALTER TABLE media_items ADD COLUMN storage_mode TEXT NOT NULL DEFAULT 'external';
+ALTER TABLE media_items
+ADD COLUMN storage_mode TEXT NOT NULL DEFAULT 'external';
 
 -- Original filename for managed uploads (preserved separately from file_name which may be normalized)
-ALTER TABLE media_items ADD COLUMN original_filename TEXT;
+ALTER TABLE media_items
+ADD COLUMN original_filename TEXT;
 
 -- When the file was uploaded to managed storage
-ALTER TABLE media_items ADD COLUMN uploaded_at TEXT;
+ALTER TABLE media_items
+ADD COLUMN uploaded_at TEXT;
 
 -- Storage key for looking up the blob (usually same as content_hash for deduplication)
-ALTER TABLE media_items ADD COLUMN storage_key TEXT;
+ALTER TABLE media_items
+ADD COLUMN storage_key TEXT;
 
 -- Managed blobs table - tracks deduplicated file storage
 CREATE TABLE managed_blobs (
-    content_hash TEXT PRIMARY KEY NOT NULL,
-    file_size INTEGER NOT NULL,
-    mime_type TEXT NOT NULL,
-    reference_count INTEGER NOT NULL DEFAULT 1,
-    stored_at TEXT NOT NULL,
-    last_verified TEXT
+  content_hash TEXT PRIMARY KEY NOT NULL,
+  file_size INTEGER NOT NULL,
+  mime_type TEXT NOT NULL,
+  reference_count INTEGER NOT NULL DEFAULT 1,
+  stored_at TEXT NOT NULL,
+  last_verified TEXT
 );
 
 -- Index for finding managed media items
-CREATE INDEX idx_media_storage_mode ON media_items(storage_mode);
+CREATE INDEX idx_media_storage_mode ON media_items (storage_mode);
 
 -- Index for finding orphaned blobs (reference_count = 0)
-CREATE INDEX idx_blobs_reference_count ON managed_blobs(reference_count);
+CREATE INDEX idx_blobs_reference_count ON managed_blobs (reference_count);

migrations/sqlite/V16__sync_system.sql

@@ -1,117 +1,129 @@
 -- V16: Cross-Device Sync System
 -- Adds device registration, change tracking, and chunked upload support
-
 -- Sync devices table
 CREATE TABLE sync_devices (
-    id TEXT PRIMARY KEY NOT NULL,
-    user_id TEXT NOT NULL,
-    name TEXT NOT NULL,
-    device_type TEXT NOT NULL,
-    client_version TEXT NOT NULL,
-    os_info TEXT,
-    device_token_hash TEXT NOT NULL UNIQUE,
-    last_sync_at TEXT,
-    last_seen_at TEXT NOT NULL,
-    sync_cursor INTEGER DEFAULT 0,
-    enabled INTEGER NOT NULL DEFAULT 1,
-    created_at TEXT NOT NULL,
-    updated_at TEXT NOT NULL,
-    FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
+  id TEXT PRIMARY KEY NOT NULL,
+  user_id TEXT NOT NULL,
+  name TEXT NOT NULL,
+  device_type TEXT NOT NULL,
+  client_version TEXT NOT NULL,
+  os_info TEXT,
+  device_token_hash TEXT NOT NULL UNIQUE,
+  last_sync_at TEXT,
+  last_seen_at TEXT NOT NULL,
+  sync_cursor INTEGER DEFAULT 0,
+  enabled INTEGER NOT NULL DEFAULT 1,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL,
+  FOREIGN KEY (user_id) REFERENCES users (id) ON DELETE CASCADE
 );
 
-CREATE INDEX idx_sync_devices_user ON sync_devices(user_id);
-CREATE INDEX idx_sync_devices_token ON sync_devices(device_token_hash);
+CREATE INDEX idx_sync_devices_user ON sync_devices (user_id);
+
+CREATE INDEX idx_sync_devices_token ON sync_devices (device_token_hash);
 
 -- Sync log table - tracks all changes for sync
 CREATE TABLE sync_log (
-    id TEXT PRIMARY KEY NOT NULL,
-    sequence INTEGER NOT NULL UNIQUE,
-    change_type TEXT NOT NULL,
-    media_id TEXT,
-    path TEXT NOT NULL,
-    content_hash TEXT,
-    file_size INTEGER,
-    metadata_json TEXT,
-    changed_by_device TEXT,
-    timestamp TEXT NOT NULL,
-    FOREIGN KEY (media_id) REFERENCES media_items(id) ON DELETE SET NULL,
-    FOREIGN KEY (changed_by_device) REFERENCES sync_devices(id) ON DELETE SET NULL
+  id TEXT PRIMARY KEY NOT NULL,
+  sequence INTEGER NOT NULL UNIQUE,
+  change_type TEXT NOT NULL,
+  media_id TEXT,
+  path TEXT NOT NULL,
+  content_hash TEXT,
+  file_size INTEGER,
+  metadata_json TEXT,
+  changed_by_device TEXT,
+  timestamp TEXT NOT NULL,
+  FOREIGN KEY (media_id) REFERENCES media_items (id) ON DELETE SET NULL,
+  FOREIGN KEY (changed_by_device) REFERENCES sync_devices (id) ON DELETE SET NULL
 );
 
-CREATE INDEX idx_sync_log_sequence ON sync_log(sequence);
-CREATE INDEX idx_sync_log_path ON sync_log(path);
-CREATE INDEX idx_sync_log_timestamp ON sync_log(timestamp);
+CREATE INDEX idx_sync_log_sequence ON sync_log (sequence);
+
+CREATE INDEX idx_sync_log_path ON sync_log (path);
+
+CREATE INDEX idx_sync_log_timestamp ON sync_log (timestamp);
 
 -- Sequence counter for sync log
 CREATE TABLE sync_sequence (
-    id INTEGER PRIMARY KEY CHECK (id = 1),
-    current_value INTEGER NOT NULL DEFAULT 0
+  id INTEGER PRIMARY KEY CHECK (id = 1),
+  current_value INTEGER NOT NULL DEFAULT 0
 );
-INSERT INTO sync_sequence (id, current_value) VALUES (1, 0);
+
+INSERT INTO
+  sync_sequence (id, current_value)
+VALUES
+  (1, 0);
 
 -- Device sync state - tracks sync status per device per file
 CREATE TABLE device_sync_state (
-    device_id TEXT NOT NULL,
-    path TEXT NOT NULL,
-    local_hash TEXT,
-    server_hash TEXT,
-    local_mtime INTEGER,
-    server_mtime INTEGER,
-    sync_status TEXT NOT NULL,
-    last_synced_at TEXT,
-    conflict_info_json TEXT,
-    PRIMARY KEY (device_id, path),
-    FOREIGN KEY (device_id) REFERENCES sync_devices(id) ON DELETE CASCADE
+  device_id TEXT NOT NULL,
+  path TEXT NOT NULL,
+  local_hash TEXT,
+  server_hash TEXT,
+  local_mtime INTEGER,
+  server_mtime INTEGER,
+  sync_status TEXT NOT NULL,
+  last_synced_at TEXT,
+  conflict_info_json TEXT,
+  PRIMARY KEY (device_id, path),
+  FOREIGN KEY (device_id) REFERENCES sync_devices (id) ON DELETE CASCADE
 );
 
-CREATE INDEX idx_device_sync_status ON device_sync_state(device_id, sync_status);
+CREATE INDEX idx_device_sync_status ON device_sync_state (device_id, sync_status);
 
 -- Upload sessions for chunked uploads
 CREATE TABLE upload_sessions (
-    id TEXT PRIMARY KEY NOT NULL,
-    device_id TEXT NOT NULL,
-    target_path TEXT NOT NULL,
-    expected_hash TEXT NOT NULL,
-    expected_size INTEGER NOT NULL,
-    chunk_size INTEGER NOT NULL,
-    chunk_count INTEGER NOT NULL,
-    status TEXT NOT NULL,
-    created_at TEXT NOT NULL,
-    expires_at TEXT NOT NULL,
-    last_activity TEXT NOT NULL,
-    FOREIGN KEY (device_id) REFERENCES sync_devices(id) ON DELETE CASCADE
+  id TEXT PRIMARY KEY NOT NULL,
+  device_id TEXT NOT NULL,
+  target_path TEXT NOT NULL,
+  expected_hash TEXT NOT NULL,
+  expected_size INTEGER NOT NULL,
+  chunk_size INTEGER NOT NULL,
+  chunk_count INTEGER NOT NULL,
+  status TEXT NOT NULL,
+  created_at TEXT NOT NULL,
+  expires_at TEXT NOT NULL,
+  last_activity TEXT NOT NULL,
+  FOREIGN KEY (device_id) REFERENCES sync_devices (id) ON DELETE CASCADE
 );
 
-CREATE INDEX idx_upload_sessions_device ON upload_sessions(device_id);
-CREATE INDEX idx_upload_sessions_status ON upload_sessions(status);
-CREATE INDEX idx_upload_sessions_expires ON upload_sessions(expires_at);
+CREATE INDEX idx_upload_sessions_device ON upload_sessions (device_id);
+
+CREATE INDEX idx_upload_sessions_status ON upload_sessions (status);
+
+CREATE INDEX idx_upload_sessions_expires ON upload_sessions (expires_at);
 
 -- Upload chunks - tracks received chunks
 CREATE TABLE upload_chunks (
-    upload_id TEXT NOT NULL,
-    chunk_index INTEGER NOT NULL,
-    offset INTEGER NOT NULL,
+  upload_id TEXT NOT NULL,
+  chunk_index INTEGER NOT NULL,
+  offset
+    INTEGER NOT NULL,
     size INTEGER NOT NULL,
     hash TEXT NOT NULL,
     received_at TEXT NOT NULL,
     PRIMARY KEY (upload_id, chunk_index),
-    FOREIGN KEY (upload_id) REFERENCES upload_sessions(id) ON DELETE CASCADE
+    FOREIGN KEY (upload_id) REFERENCES upload_sessions (id) ON DELETE CASCADE
 );
 
 -- Sync conflicts
 CREATE TABLE sync_conflicts (
-    id TEXT PRIMARY KEY NOT NULL,
-    device_id TEXT NOT NULL,
-    path TEXT NOT NULL,
-    local_hash TEXT NOT NULL,
-    local_mtime INTEGER NOT NULL,
-    server_hash TEXT NOT NULL,
-    server_mtime INTEGER NOT NULL,
-    detected_at TEXT NOT NULL,
-    resolved_at TEXT,
-    resolution TEXT,
-    FOREIGN KEY (device_id) REFERENCES sync_devices(id) ON DELETE CASCADE
+  id TEXT PRIMARY KEY NOT NULL,
+  device_id TEXT NOT NULL,
+  path TEXT NOT NULL,
+  local_hash TEXT NOT NULL,
+  local_mtime INTEGER NOT NULL,
+  server_hash TEXT NOT NULL,
+  server_mtime INTEGER NOT NULL,
+  detected_at TEXT NOT NULL,
+  resolved_at TEXT,
+  resolution TEXT,
+  FOREIGN KEY (device_id) REFERENCES sync_devices (id) ON DELETE CASCADE
 );
 
-CREATE INDEX idx_sync_conflicts_device ON sync_conflicts(device_id);
-CREATE INDEX idx_sync_conflicts_unresolved ON sync_conflicts(device_id, resolved_at) WHERE resolved_at IS NULL;
+CREATE INDEX idx_sync_conflicts_device ON sync_conflicts (device_id);
+
+CREATE INDEX idx_sync_conflicts_unresolved ON sync_conflicts (device_id, resolved_at)
+WHERE
+  resolved_at IS NULL;

migrations/sqlite/V17__enhanced_sharing.sql

@@ -1,85 +1,133 @@
 -- V17: Enhanced Sharing System
 -- Replaces simple share_links with comprehensive sharing capabilities
-
 -- Enhanced shares table
 CREATE TABLE shares (
-    id TEXT PRIMARY KEY NOT NULL,
-    target_type TEXT NOT NULL CHECK (target_type IN ('media', 'collection', 'tag', 'saved_search')),
-    target_id TEXT NOT NULL,
-    owner_id TEXT NOT NULL,
-    recipient_type TEXT NOT NULL CHECK (recipient_type IN ('public_link', 'user', 'group', 'federated')),
-    recipient_user_id TEXT,
-    recipient_group_id TEXT,
-    recipient_federated_handle TEXT,
-    recipient_federated_server TEXT,
-    public_token TEXT UNIQUE,
-    public_password_hash TEXT,
-    perm_view INTEGER NOT NULL DEFAULT 1,
-    perm_download INTEGER NOT NULL DEFAULT 0,
-    perm_edit INTEGER NOT NULL DEFAULT 0,
-    perm_delete INTEGER NOT NULL DEFAULT 0,
-    perm_reshare INTEGER NOT NULL DEFAULT 0,
-    perm_add INTEGER NOT NULL DEFAULT 0,
-    note TEXT,
-    expires_at TEXT,
-    access_count INTEGER NOT NULL DEFAULT 0,
-    last_accessed TEXT,
-    inherit_to_children INTEGER NOT NULL DEFAULT 1,
-    parent_share_id TEXT,
-    created_at TEXT NOT NULL,
-    updated_at TEXT NOT NULL,
-    FOREIGN KEY (owner_id) REFERENCES users(id) ON DELETE CASCADE,
-    FOREIGN KEY (recipient_user_id) REFERENCES users(id) ON DELETE CASCADE,
-    FOREIGN KEY (parent_share_id) REFERENCES shares(id) ON DELETE CASCADE,
-    UNIQUE(owner_id, target_type, target_id, recipient_type, recipient_user_id)
+  id TEXT PRIMARY KEY NOT NULL,
+  target_type TEXT NOT NULL CHECK (
+    target_type IN ('media', 'collection', 'tag', 'saved_search')
+  ),
+  target_id TEXT NOT NULL,
+  owner_id TEXT NOT NULL,
+  recipient_type TEXT NOT NULL CHECK (
+    recipient_type IN ('public_link', 'user', 'group', 'federated')
+  ),
+  recipient_user_id TEXT,
+  recipient_group_id TEXT,
+  recipient_federated_handle TEXT,
+  recipient_federated_server TEXT,
+  public_token TEXT UNIQUE,
+  public_password_hash TEXT,
+  perm_view INTEGER NOT NULL DEFAULT 1,
+  perm_download INTEGER NOT NULL DEFAULT 0,
+  perm_edit INTEGER NOT NULL DEFAULT 0,
+  perm_delete INTEGER NOT NULL DEFAULT 0,
+  perm_reshare INTEGER NOT NULL DEFAULT 0,
+  perm_add INTEGER NOT NULL DEFAULT 0,
+  note TEXT,
+  expires_at TEXT,
+  access_count INTEGER NOT NULL DEFAULT 0,
+  last_accessed TEXT,
+  inherit_to_children INTEGER NOT NULL DEFAULT 1,
+  parent_share_id TEXT,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL,
+  FOREIGN KEY (owner_id) REFERENCES users (id) ON DELETE CASCADE,
+  FOREIGN KEY (recipient_user_id) REFERENCES users (id) ON DELETE CASCADE,
+  FOREIGN KEY (parent_share_id) REFERENCES shares (id) ON DELETE CASCADE,
+  UNIQUE (
+    owner_id,
+    target_type,
+    target_id,
+    recipient_type,
+    recipient_user_id
+  )
 );
 
-CREATE INDEX idx_shares_owner ON shares(owner_id);
-CREATE INDEX idx_shares_recipient_user ON shares(recipient_user_id);
-CREATE INDEX idx_shares_target ON shares(target_type, target_id);
-CREATE INDEX idx_shares_token ON shares(public_token);
-CREATE INDEX idx_shares_expires ON shares(expires_at);
+CREATE INDEX idx_shares_owner ON shares (owner_id);
+
+CREATE INDEX idx_shares_recipient_user ON shares (recipient_user_id);
+
+CREATE INDEX idx_shares_target ON shares (target_type, target_id);
+
+CREATE INDEX idx_shares_token ON shares (public_token);
+
+CREATE INDEX idx_shares_expires ON shares (expires_at);
 
 -- Share activity log
 CREATE TABLE share_activity (
-    id TEXT PRIMARY KEY NOT NULL,
-    share_id TEXT NOT NULL,
-    actor_id TEXT,
-    actor_ip TEXT,
-    action TEXT NOT NULL,
-    details TEXT,
-    timestamp TEXT NOT NULL,
-    FOREIGN KEY (share_id) REFERENCES shares(id) ON DELETE CASCADE,
-    FOREIGN KEY (actor_id) REFERENCES users(id) ON DELETE SET NULL
+  id TEXT PRIMARY KEY NOT NULL,
+  share_id TEXT NOT NULL,
+  actor_id TEXT,
+  actor_ip TEXT,
+  action TEXT NOT NULL,
+  details TEXT,
+  timestamp TEXT NOT NULL,
+  FOREIGN KEY (share_id) REFERENCES shares (id) ON DELETE CASCADE,
+  FOREIGN KEY (actor_id) REFERENCES users (id) ON DELETE SET NULL
 );
 
-CREATE INDEX idx_share_activity_share ON share_activity(share_id);
-CREATE INDEX idx_share_activity_timestamp ON share_activity(timestamp);
+CREATE INDEX idx_share_activity_share ON share_activity (share_id);
+
+CREATE INDEX idx_share_activity_timestamp ON share_activity (timestamp);
 
 -- Share notifications
 CREATE TABLE share_notifications (
-    id TEXT PRIMARY KEY NOT NULL,
-    user_id TEXT NOT NULL,
-    share_id TEXT NOT NULL,
-    notification_type TEXT NOT NULL,
-    is_read INTEGER NOT NULL DEFAULT 0,
-    created_at TEXT NOT NULL,
-    FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE,
-    FOREIGN KEY (share_id) REFERENCES shares(id) ON DELETE CASCADE
+  id TEXT PRIMARY KEY NOT NULL,
+  user_id TEXT NOT NULL,
+  share_id TEXT NOT NULL,
+  notification_type TEXT NOT NULL,
+  is_read INTEGER NOT NULL DEFAULT 0,
+  created_at TEXT NOT NULL,
+  FOREIGN KEY (user_id) REFERENCES users (id) ON DELETE CASCADE,
+  FOREIGN KEY (share_id) REFERENCES shares (id) ON DELETE CASCADE
 );
 
-CREATE INDEX idx_share_notifications_user ON share_notifications(user_id);
-CREATE INDEX idx_share_notifications_unread ON share_notifications(user_id, is_read) WHERE is_read = 0;
+CREATE INDEX idx_share_notifications_user ON share_notifications (user_id);
+
+CREATE INDEX idx_share_notifications_unread ON share_notifications (user_id, is_read)
+WHERE
+  is_read = 0;
 
 -- Migrate existing share_links to new shares table (if share_links exists)
-INSERT OR IGNORE INTO shares (
-    id, target_type, target_id, owner_id, recipient_type,
-    public_token, public_password_hash, perm_view, perm_download,
-    access_count, expires_at, created_at, updated_at
+INSERT
+OR IGNORE INTO shares (
+  id,
+  target_type,
+  target_id,
+  owner_id,
+  recipient_type,
+  public_token,
+  public_password_hash,
+  perm_view,
+  perm_download,
+  access_count,
+  expires_at,
+  created_at,
+  updated_at
 )
 SELECT
-    id, 'media', media_id, created_by, 'public_link',
-    token, password_hash, 1, 1,
-    view_count, expires_at, created_at, created_at
-FROM share_links
-WHERE EXISTS (SELECT 1 FROM sqlite_master WHERE type='table' AND name='share_links');
+  id,
+  'media',
+  media_id,
+  created_by,
+  'public_link',
+  token,
+  password_hash,
+  1,
+  1,
+  view_count,
+  expires_at,
+  created_at,
+  created_at
+FROM
+  share_links
+WHERE
+  EXISTS (
+    SELECT
+      1
+    FROM
+      sqlite_master
+    WHERE
+      type = 'table'
+      AND name = 'share_links'
+  );

migrations/sqlite/V18__file_management.sql

@@ -1,11 +1,13 @@
 -- V18: File Management (Rename, Move, Trash)
 -- Adds soft delete support for trash/recycle bin functionality
-
 -- Add deleted_at column for soft delete (trash)
-ALTER TABLE media_items ADD COLUMN deleted_at TEXT;
+ALTER TABLE media_items
+ADD COLUMN deleted_at TEXT;
 
 -- Index for efficient trash queries
-CREATE INDEX idx_media_deleted_at ON media_items(deleted_at);
+CREATE INDEX idx_media_deleted_at ON media_items (deleted_at);
 
 -- Index for listing non-deleted items (most common query pattern)
-CREATE INDEX idx_media_not_deleted ON media_items(id) WHERE deleted_at IS NULL;
+CREATE INDEX idx_media_not_deleted ON media_items (id)
+WHERE
+  deleted_at IS NULL;

migrations/sqlite/V19__markdown_links.sql

@@ -1,35 +1,35 @@
 -- V19: Markdown Links (Obsidian-style bidirectional links)
 -- Adds support for wikilinks, markdown links, embeds, and backlink tracking
-
 -- Table for storing extracted markdown links
 CREATE TABLE IF NOT EXISTS markdown_links (
-    id TEXT PRIMARY KEY NOT NULL,
-    source_media_id TEXT NOT NULL,
-    target_path TEXT NOT NULL,           -- raw link target (wikilink or path)
-    target_media_id TEXT,                -- resolved media_id (nullable if unresolved)
-    link_type TEXT NOT NULL,             -- 'wikilink', 'markdown_link', 'embed'
-    link_text TEXT,                      -- display text for the link
-    line_number INTEGER,                 -- line number in source file
-    context TEXT,                        -- surrounding text for preview
-    created_at TEXT NOT NULL,
-    FOREIGN KEY (source_media_id) REFERENCES media_items(id) ON DELETE CASCADE,
-    FOREIGN KEY (target_media_id) REFERENCES media_items(id) ON DELETE SET NULL
+  id TEXT PRIMARY KEY NOT NULL,
+  source_media_id TEXT NOT NULL,
+  target_path TEXT NOT NULL, -- raw link target (wikilink or path)
+  target_media_id TEXT, -- resolved media_id (nullable if unresolved)
+  link_type TEXT NOT NULL, -- 'wikilink', 'markdown_link', 'embed'
+  link_text TEXT, -- display text for the link
+  line_number INTEGER, -- line number in source file
+  context TEXT, -- surrounding text for preview
+  created_at TEXT NOT NULL,
+  FOREIGN KEY (source_media_id) REFERENCES media_items (id) ON DELETE CASCADE,
+  FOREIGN KEY (target_media_id) REFERENCES media_items (id) ON DELETE SET NULL
 );
 
 -- Index for efficient outgoing link queries (what does this note link to?)
-CREATE INDEX idx_links_source ON markdown_links(source_media_id);
+CREATE INDEX idx_links_source ON markdown_links (source_media_id);
 
 -- Index for efficient backlink queries (what links to this note?)
-CREATE INDEX idx_links_target ON markdown_links(target_media_id);
+CREATE INDEX idx_links_target ON markdown_links (target_media_id);
 
 -- Index for path-based resolution (finding unresolved links)
-CREATE INDEX idx_links_target_path ON markdown_links(target_path);
+CREATE INDEX idx_links_target_path ON markdown_links (target_path);
 
 -- Index for link type filtering
-CREATE INDEX idx_links_type ON markdown_links(link_type);
+CREATE INDEX idx_links_type ON markdown_links (link_type);
 
 -- Track when links were last extracted from a media item
-ALTER TABLE media_items ADD COLUMN links_extracted_at TEXT;
+ALTER TABLE media_items
+ADD COLUMN links_extracted_at TEXT;
 
 -- Index for finding media items that need link extraction
-CREATE INDEX idx_media_links_extracted ON media_items(links_extracted_at);
+CREATE INDEX idx_media_links_extracted ON media_items (links_extracted_at);

migrations/sqlite/V1__initial_schema.sql

@@ -1,77 +1,75 @@
-CREATE TABLE IF NOT EXISTS root_dirs (
-    path TEXT PRIMARY KEY NOT NULL
-);
+CREATE TABLE IF NOT EXISTS root_dirs (path TEXT PRIMARY KEY NOT NULL);
 
 CREATE TABLE IF NOT EXISTS media_items (
-    id TEXT PRIMARY KEY NOT NULL,
-    path TEXT NOT NULL UNIQUE,
-    file_name TEXT NOT NULL,
-    media_type TEXT NOT NULL,
-    content_hash TEXT NOT NULL UNIQUE,
-    file_size INTEGER NOT NULL,
-    title TEXT,
-    artist TEXT,
-    album TEXT,
-    genre TEXT,
-    year INTEGER,
-    duration_secs REAL,
-    description TEXT,
-    created_at TEXT NOT NULL,
-    updated_at TEXT NOT NULL
+  id TEXT PRIMARY KEY NOT NULL,
+  path TEXT NOT NULL UNIQUE,
+  file_name TEXT NOT NULL,
+  media_type TEXT NOT NULL,
+  content_hash TEXT NOT NULL UNIQUE,
+  file_size INTEGER NOT NULL,
+  title TEXT,
+  artist TEXT,
+  album TEXT,
+  genre TEXT,
+  year INTEGER,
+  duration_secs REAL,
+  description TEXT,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL
 );
 
 CREATE TABLE IF NOT EXISTS tags (
-    id TEXT PRIMARY KEY NOT NULL,
-    name TEXT NOT NULL,
-    parent_id TEXT,
-    created_at TEXT NOT NULL,
-    FOREIGN KEY (parent_id) REFERENCES tags(id) ON DELETE SET NULL
+  id TEXT PRIMARY KEY NOT NULL,
+  name TEXT NOT NULL,
+  parent_id TEXT,
+  created_at TEXT NOT NULL,
+  FOREIGN KEY (parent_id) REFERENCES tags (id) ON DELETE SET NULL
 );
 
-CREATE UNIQUE INDEX IF NOT EXISTS idx_tags_name_parent ON tags(name, parent_id);
+CREATE UNIQUE INDEX IF NOT EXISTS idx_tags_name_parent ON tags (name, parent_id);
 
 CREATE TABLE IF NOT EXISTS media_tags (
-    media_id TEXT NOT NULL,
-    tag_id TEXT NOT NULL,
-    PRIMARY KEY (media_id, tag_id),
-    FOREIGN KEY (media_id) REFERENCES media_items(id) ON DELETE CASCADE,
-    FOREIGN KEY (tag_id) REFERENCES tags(id) ON DELETE CASCADE
+  media_id TEXT NOT NULL,
+  tag_id TEXT NOT NULL,
+  PRIMARY KEY (media_id, tag_id),
+  FOREIGN KEY (media_id) REFERENCES media_items (id) ON DELETE CASCADE,
+  FOREIGN KEY (tag_id) REFERENCES tags (id) ON DELETE CASCADE
 );
 
 CREATE TABLE IF NOT EXISTS collections (
-    id TEXT PRIMARY KEY NOT NULL,
-    name TEXT NOT NULL,
-    description TEXT,
-    kind TEXT NOT NULL,
-    filter_query TEXT,
-    created_at TEXT NOT NULL,
-    updated_at TEXT NOT NULL
+  id TEXT PRIMARY KEY NOT NULL,
+  name TEXT NOT NULL,
+  description TEXT,
+  kind TEXT NOT NULL,
+  filter_query TEXT,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL
 );
 
 CREATE TABLE IF NOT EXISTS collection_members (
-    collection_id TEXT NOT NULL,
-    media_id TEXT NOT NULL,
-    position INTEGER NOT NULL DEFAULT 0,
-    added_at TEXT NOT NULL,
-    PRIMARY KEY (collection_id, media_id),
-    FOREIGN KEY (collection_id) REFERENCES collections(id) ON DELETE CASCADE,
-    FOREIGN KEY (media_id) REFERENCES media_items(id) ON DELETE CASCADE
+  collection_id TEXT NOT NULL,
+  media_id TEXT NOT NULL,
+  position INTEGER NOT NULL DEFAULT 0,
+  added_at TEXT NOT NULL,
+  PRIMARY KEY (collection_id, media_id),
+  FOREIGN KEY (collection_id) REFERENCES collections (id) ON DELETE CASCADE,
+  FOREIGN KEY (media_id) REFERENCES media_items (id) ON DELETE CASCADE
 );
 
 CREATE TABLE IF NOT EXISTS audit_log (
-    id TEXT PRIMARY KEY NOT NULL,
-    media_id TEXT,
-    action TEXT NOT NULL,
-    details TEXT,
-    timestamp TEXT NOT NULL,
-    FOREIGN KEY (media_id) REFERENCES media_items(id) ON DELETE SET NULL
+  id TEXT PRIMARY KEY NOT NULL,
+  media_id TEXT,
+  action TEXT NOT NULL,
+  details TEXT,
+  timestamp TEXT NOT NULL,
+  FOREIGN KEY (media_id) REFERENCES media_items (id) ON DELETE SET NULL
 );
 
 CREATE TABLE IF NOT EXISTS custom_fields (
-    media_id TEXT NOT NULL,
-    field_name TEXT NOT NULL,
-    field_type TEXT NOT NULL,
-    field_value TEXT NOT NULL,
-    PRIMARY KEY (media_id, field_name),
-    FOREIGN KEY (media_id) REFERENCES media_items(id) ON DELETE CASCADE
+  media_id TEXT NOT NULL,
+  field_name TEXT NOT NULL,
+  field_type TEXT NOT NULL,
+  field_value TEXT NOT NULL,
+  PRIMARY KEY (media_id, field_name),
+  FOREIGN KEY (media_id) REFERENCES media_items (id) ON DELETE CASCADE
 );

migrations/sqlite/V2__fts5_indexes.sql

@@ -1,27 +1,114 @@
-CREATE VIRTUAL TABLE IF NOT EXISTS media_fts USING fts5(
+CREATE VIRTUAL TABLE IF NOT EXISTS media_fts USING fts5 (
+  title,
+  artist,
+  album,
+  genre,
+  description,
+  file_name,
+  content = 'media_items',
+  content_rowid = 'rowid'
+);
+
+CREATE TRIGGER IF NOT EXISTS media_fts_insert
+AFTER INSERT ON media_items
+BEGIN
+INSERT INTO
+  media_fts (
+    rowid,
     title,
     artist,
     album,
     genre,
     description,
-    file_name,
-    content='media_items',
-    content_rowid='rowid'
-);
+    file_name
+  )
+VALUES
+  (
+    new.rowid,
+    new.title,
+    new.artist,
+    new.album,
+    new.genre,
+    new.description,
+    new.file_name
+  );
 
-CREATE TRIGGER IF NOT EXISTS media_fts_insert AFTER INSERT ON media_items BEGIN
-    INSERT INTO media_fts(rowid, title, artist, album, genre, description, file_name)
-    VALUES (new.rowid, new.title, new.artist, new.album, new.genre, new.description, new.file_name);
 END;
 
-CREATE TRIGGER IF NOT EXISTS media_fts_update AFTER UPDATE ON media_items BEGIN
-    INSERT INTO media_fts(media_fts, rowid, title, artist, album, genre, description, file_name)
-    VALUES ('delete', old.rowid, old.title, old.artist, old.album, old.genre, old.description, old.file_name);
-    INSERT INTO media_fts(rowid, title, artist, album, genre, description, file_name)
-    VALUES (new.rowid, new.title, new.artist, new.album, new.genre, new.description, new.file_name);
+CREATE TRIGGER IF NOT EXISTS media_fts_update
+AFTER
+UPDATE ON media_items
+BEGIN
+INSERT INTO
+  media_fts (
+    media_fts,
+    rowid,
+    title,
+    artist,
+    album,
+    genre,
+    description,
+    file_name
+  )
+VALUES
+  (
+    'delete',
+    old.rowid,
+    old.title,
+    old.artist,
+    old.album,
+    old.genre,
+    old.description,
+    old.file_name
+  );
+
+INSERT INTO
+  media_fts (
+    rowid,
+    title,
+    artist,
+    album,
+    genre,
+    description,
+    file_name
+  )
+VALUES
+  (
+    new.rowid,
+    new.title,
+    new.artist,
+    new.album,
+    new.genre,
+    new.description,
+    new.file_name
+  );
+
 END;
 
-CREATE TRIGGER IF NOT EXISTS media_fts_delete AFTER DELETE ON media_items BEGIN
-    INSERT INTO media_fts(media_fts, rowid, title, artist, album, genre, description, file_name)
-    VALUES ('delete', old.rowid, old.title, old.artist, old.album, old.genre, old.description, old.file_name);
+CREATE TRIGGER IF NOT EXISTS media_fts_delete
+AFTER DELETE ON media_items
+BEGIN
+INSERT INTO
+  media_fts (
+    media_fts,
+    rowid,
+    title,
+    artist,
+    album,
+    genre,
+    description,
+    file_name
+  )
+VALUES
+  (
+    'delete',
+    old.rowid,
+    old.title,
+    old.artist,
+    old.album,
+    old.genre,
+    old.description,
+    old.file_name
+  );
+
 END;

migrations/sqlite/V3__audit_indexes.sql

@@ -1,6 +1,11 @@
-CREATE INDEX IF NOT EXISTS idx_audit_media_id ON audit_log(media_id);
-CREATE INDEX IF NOT EXISTS idx_audit_timestamp ON audit_log(timestamp);
-CREATE INDEX IF NOT EXISTS idx_audit_action ON audit_log(action);
-CREATE INDEX IF NOT EXISTS idx_media_content_hash ON media_items(content_hash);
-CREATE INDEX IF NOT EXISTS idx_media_media_type ON media_items(media_type);
-CREATE INDEX IF NOT EXISTS idx_media_created_at ON media_items(created_at);
+CREATE INDEX IF NOT EXISTS idx_audit_media_id ON audit_log (media_id);
+
+CREATE INDEX IF NOT EXISTS idx_audit_timestamp ON audit_log (timestamp);
+
+CREATE INDEX IF NOT EXISTS idx_audit_action ON audit_log (action);
+
+CREATE INDEX IF NOT EXISTS idx_media_content_hash ON media_items (content_hash);
+
+CREATE INDEX IF NOT EXISTS idx_media_media_type ON media_items (media_type);
+
+CREATE INDEX IF NOT EXISTS idx_media_created_at ON media_items (created_at);

migrations/sqlite/V4__thumbnail_path.sql

@@ -1 +1,2 @@
-ALTER TABLE media_items ADD COLUMN thumbnail_path TEXT;
+ALTER TABLE media_items
+ADD COLUMN thumbnail_path TEXT;

migrations/sqlite/V5__integrity_and_saved_searches.sql

@@ -1,12 +1,15 @@
 -- Integrity tracking columns
-ALTER TABLE media_items ADD COLUMN last_verified_at TEXT;
-ALTER TABLE media_items ADD COLUMN integrity_status TEXT DEFAULT 'unverified';
+ALTER TABLE media_items
+ADD COLUMN last_verified_at TEXT;
+
+ALTER TABLE media_items
+ADD COLUMN integrity_status TEXT DEFAULT 'unverified';
 
 -- Saved searches
 CREATE TABLE IF NOT EXISTS saved_searches (
-    id TEXT PRIMARY KEY,
-    name TEXT NOT NULL,
-    query TEXT NOT NULL,
-    sort_order TEXT,
-    created_at TEXT NOT NULL
+  id TEXT PRIMARY KEY,
+  name TEXT NOT NULL,
+  query TEXT NOT NULL,
+  sort_order TEXT,
+  created_at TEXT NOT NULL
 );

migrations/sqlite/V6__plugin_system.sql

@@ -1,15 +1,16 @@
 -- Plugin registry table
 CREATE TABLE plugin_registry (
-    id TEXT PRIMARY KEY,
-    name TEXT NOT NULL,
-    version TEXT NOT NULL,
-    enabled BOOLEAN NOT NULL DEFAULT TRUE,
-    config_json TEXT,
-    manifest_json TEXT,
-    installed_at TEXT NOT NULL,
-    updated_at TEXT NOT NULL
+  id TEXT PRIMARY KEY,
+  name TEXT NOT NULL,
+  version TEXT NOT NULL,
+  enabled BOOLEAN NOT NULL DEFAULT TRUE,
+  config_json TEXT,
+  manifest_json TEXT,
+  installed_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL
 );
 
 -- Index for quick lookups
-CREATE INDEX idx_plugin_registry_enabled ON plugin_registry(enabled);
-CREATE INDEX idx_plugin_registry_name ON plugin_registry(name);
+CREATE INDEX idx_plugin_registry_enabled ON plugin_registry (enabled);
+
+CREATE INDEX idx_plugin_registry_name ON plugin_registry (name);

migrations/sqlite/V7__user_management.sql

@@ -1,35 +1,37 @@
 -- Users table
 CREATE TABLE users (
-    id TEXT PRIMARY KEY,
-    username TEXT UNIQUE NOT NULL,
-    password_hash TEXT NOT NULL,
-    role TEXT NOT NULL,
-    created_at TEXT NOT NULL,
-    updated_at TEXT NOT NULL
+  id TEXT PRIMARY KEY,
+  username TEXT UNIQUE NOT NULL,
+  password_hash TEXT NOT NULL,
+  role TEXT NOT NULL,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL
 );
 
 -- User profiles table
 CREATE TABLE user_profiles (
-    user_id TEXT PRIMARY KEY,
-    avatar_path TEXT,
-    bio TEXT,
-    preferences_json TEXT NOT NULL DEFAULT '{}',
-    created_at TEXT NOT NULL,
-    updated_at TEXT NOT NULL,
-    FOREIGN KEY (user_id) REFERENCES users(id)
+  user_id TEXT PRIMARY KEY,
+  avatar_path TEXT,
+  bio TEXT,
+  preferences_json TEXT NOT NULL DEFAULT '{}',
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL,
+  FOREIGN KEY (user_id) REFERENCES users (id)
 );
 
 -- User library access table
 CREATE TABLE user_libraries (
-    user_id TEXT NOT NULL,
-    root_path TEXT NOT NULL,
-    permission TEXT NOT NULL,
-    granted_at TEXT NOT NULL,
-    PRIMARY KEY (user_id, root_path),
-    FOREIGN KEY (user_id) REFERENCES users(id)
+  user_id TEXT NOT NULL,
+  root_path TEXT NOT NULL,
+  permission TEXT NOT NULL,
+  granted_at TEXT NOT NULL,
+  PRIMARY KEY (user_id, root_path),
+  FOREIGN KEY (user_id) REFERENCES users (id)
 );
 
 -- Indexes for efficient lookups
-CREATE INDEX idx_users_username ON users(username);
-CREATE INDEX idx_user_libraries_user_id ON user_libraries(user_id);
-CREATE INDEX idx_user_libraries_root_path ON user_libraries(root_path);
+CREATE INDEX idx_users_username ON users (username);
+
+CREATE INDEX idx_user_libraries_user_id ON user_libraries (user_id);
+
+CREATE INDEX idx_user_libraries_root_path ON user_libraries (root_path);

migrations/sqlite/V8__media_server_features.sql

@@ -1,143 +1,148 @@
 -- Ratings
 CREATE TABLE IF NOT EXISTS ratings (
-    id TEXT PRIMARY KEY,
-    user_id TEXT NOT NULL,
-    media_id TEXT NOT NULL,
-    stars INTEGER NOT NULL CHECK (stars >= 1 AND stars <= 5),
-    review_text TEXT,
-    created_at TEXT NOT NULL DEFAULT (datetime('now')),
-    UNIQUE(user_id, media_id),
-    FOREIGN KEY (media_id) REFERENCES media_items(id) ON DELETE CASCADE
+  id TEXT PRIMARY KEY,
+  user_id TEXT NOT NULL,
+  media_id TEXT NOT NULL,
+  stars INTEGER NOT NULL CHECK (
+    stars >= 1
+    AND stars <= 5
+  ),
+  review_text TEXT,
+  created_at TEXT NOT NULL DEFAULT (datetime ('now')),
+  UNIQUE (user_id, media_id),
+  FOREIGN KEY (media_id) REFERENCES media_items (id) ON DELETE CASCADE
 );
 
 -- Comments
 CREATE TABLE IF NOT EXISTS comments (
-    id TEXT PRIMARY KEY,
-    user_id TEXT NOT NULL,
-    media_id TEXT NOT NULL,
-    parent_comment_id TEXT,
-    text TEXT NOT NULL,
-    created_at TEXT NOT NULL DEFAULT (datetime('now')),
-    FOREIGN KEY (media_id) REFERENCES media_items(id) ON DELETE CASCADE,
-    FOREIGN KEY (parent_comment_id) REFERENCES comments(id) ON DELETE CASCADE
+  id TEXT PRIMARY KEY,
+  user_id TEXT NOT NULL,
+  media_id TEXT NOT NULL,
+  parent_comment_id TEXT,
+  text TEXT NOT NULL,
+  created_at TEXT NOT NULL DEFAULT (datetime ('now')),
+  FOREIGN KEY (media_id) REFERENCES media_items (id) ON DELETE CASCADE,
+  FOREIGN KEY (parent_comment_id) REFERENCES comments (id) ON DELETE CASCADE
 );
 
 -- Favorites
 CREATE TABLE IF NOT EXISTS favorites (
-    user_id TEXT NOT NULL,
-    media_id TEXT NOT NULL,
-    created_at TEXT NOT NULL DEFAULT (datetime('now')),
-    PRIMARY KEY (user_id, media_id),
-    FOREIGN KEY (media_id) REFERENCES media_items(id) ON DELETE CASCADE
+  user_id TEXT NOT NULL,
+  media_id TEXT NOT NULL,
+  created_at TEXT NOT NULL DEFAULT (datetime ('now')),
+  PRIMARY KEY (user_id, media_id),
+  FOREIGN KEY (media_id) REFERENCES media_items (id) ON DELETE CASCADE
 );
 
 -- Share links
 CREATE TABLE IF NOT EXISTS share_links (
-    id TEXT PRIMARY KEY,
-    media_id TEXT NOT NULL,
-    created_by TEXT NOT NULL,
-    token TEXT NOT NULL UNIQUE,
-    password_hash TEXT,
-    expires_at TEXT,
-    view_count INTEGER NOT NULL DEFAULT 0,
-    created_at TEXT NOT NULL DEFAULT (datetime('now')),
-    FOREIGN KEY (media_id) REFERENCES media_items(id) ON DELETE CASCADE
+  id TEXT PRIMARY KEY,
+  media_id TEXT NOT NULL,
+  created_by TEXT NOT NULL,
+  token TEXT NOT NULL UNIQUE,
+  password_hash TEXT,
+  expires_at TEXT,
+  view_count INTEGER NOT NULL DEFAULT 0,
+  created_at TEXT NOT NULL DEFAULT (datetime ('now')),
+  FOREIGN KEY (media_id) REFERENCES media_items (id) ON DELETE CASCADE
 );
 
 -- Playlists
 CREATE TABLE IF NOT EXISTS playlists (
-    id TEXT PRIMARY KEY,
-    owner_id TEXT NOT NULL,
-    name TEXT NOT NULL,
-    description TEXT,
-    is_public INTEGER NOT NULL DEFAULT 0,
-    is_smart INTEGER NOT NULL DEFAULT 0,
-    filter_query TEXT,
-    created_at TEXT NOT NULL DEFAULT (datetime('now')),
-    updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+  id TEXT PRIMARY KEY,
+  owner_id TEXT NOT NULL,
+  name TEXT NOT NULL,
+  description TEXT,
+  is_public INTEGER NOT NULL DEFAULT 0,
+  is_smart INTEGER NOT NULL DEFAULT 0,
+  filter_query TEXT,
+  created_at TEXT NOT NULL DEFAULT (datetime ('now')),
+  updated_at TEXT NOT NULL DEFAULT (datetime ('now'))
 );
 
 -- Playlist items
 CREATE TABLE IF NOT EXISTS playlist_items (
-    playlist_id TEXT NOT NULL,
-    media_id TEXT NOT NULL,
-    position INTEGER NOT NULL DEFAULT 0,
-    added_at TEXT NOT NULL DEFAULT (datetime('now')),
-    PRIMARY KEY (playlist_id, media_id),
-    FOREIGN KEY (playlist_id) REFERENCES playlists(id) ON DELETE CASCADE,
-    FOREIGN KEY (media_id) REFERENCES media_items(id) ON DELETE CASCADE
+  playlist_id TEXT NOT NULL,
+  media_id TEXT NOT NULL,
+  position INTEGER NOT NULL DEFAULT 0,
+  added_at TEXT NOT NULL DEFAULT (datetime ('now')),
+  PRIMARY KEY (playlist_id, media_id),
+  FOREIGN KEY (playlist_id) REFERENCES playlists (id) ON DELETE CASCADE,
+  FOREIGN KEY (media_id) REFERENCES media_items (id) ON DELETE CASCADE
 );
 
 -- Usage events
 CREATE TABLE IF NOT EXISTS usage_events (
-    id TEXT PRIMARY KEY,
-    media_id TEXT,
-    user_id TEXT,
-    event_type TEXT NOT NULL,
-    timestamp TEXT NOT NULL DEFAULT (datetime('now')),
-    duration_secs REAL,
-    context_json TEXT,
-    FOREIGN KEY (media_id) REFERENCES media_items(id) ON DELETE SET NULL
+  id TEXT PRIMARY KEY,
+  media_id TEXT,
+  user_id TEXT,
+  event_type TEXT NOT NULL,
+  timestamp TEXT NOT NULL DEFAULT (datetime ('now')),
+  duration_secs REAL,
+  context_json TEXT,
+  FOREIGN KEY (media_id) REFERENCES media_items (id) ON DELETE SET NULL
 );
 
-CREATE INDEX IF NOT EXISTS idx_usage_events_media ON usage_events(media_id);
-CREATE INDEX IF NOT EXISTS idx_usage_events_user ON usage_events(user_id);
-CREATE INDEX IF NOT EXISTS idx_usage_events_timestamp ON usage_events(timestamp);
+CREATE INDEX IF NOT EXISTS idx_usage_events_media ON usage_events (media_id);
+
+CREATE INDEX IF NOT EXISTS idx_usage_events_user ON usage_events (user_id);
+
+CREATE INDEX IF NOT EXISTS idx_usage_events_timestamp ON usage_events (timestamp);
 
 -- Watch history / progress
 CREATE TABLE IF NOT EXISTS watch_history (
-    id TEXT PRIMARY KEY,
-    user_id TEXT NOT NULL,
-    media_id TEXT NOT NULL,
-    progress_secs REAL NOT NULL DEFAULT 0,
-    last_watched TEXT NOT NULL DEFAULT (datetime('now')),
-    UNIQUE(user_id, media_id),
-    FOREIGN KEY (media_id) REFERENCES media_items(id) ON DELETE CASCADE
+  id TEXT PRIMARY KEY,
+  user_id TEXT NOT NULL,
+  media_id TEXT NOT NULL,
+  progress_secs REAL NOT NULL DEFAULT 0,
+  last_watched TEXT NOT NULL DEFAULT (datetime ('now')),
+  UNIQUE (user_id, media_id),
+  FOREIGN KEY (media_id) REFERENCES media_items (id) ON DELETE CASCADE
 );
 
 -- Subtitles
 CREATE TABLE IF NOT EXISTS subtitles (
-    id TEXT PRIMARY KEY,
-    media_id TEXT NOT NULL,
-    language TEXT,
-    format TEXT NOT NULL,
-    file_path TEXT,
-    is_embedded INTEGER NOT NULL DEFAULT 0,
-    track_index INTEGER,
-    offset_ms INTEGER NOT NULL DEFAULT 0,
-    created_at TEXT NOT NULL DEFAULT (datetime('now')),
-    FOREIGN KEY (media_id) REFERENCES media_items(id) ON DELETE CASCADE
+  id TEXT PRIMARY KEY,
+  media_id TEXT NOT NULL,
+  language TEXT,
+  format TEXT NOT NULL,
+  file_path TEXT,
+  is_embedded INTEGER NOT NULL DEFAULT 0,
+  track_index INTEGER,
+  offset_ms INTEGER NOT NULL DEFAULT 0,
+  created_at TEXT NOT NULL DEFAULT (datetime ('now')),
+  FOREIGN KEY (media_id) REFERENCES media_items (id) ON DELETE CASCADE
 );
 
-CREATE INDEX IF NOT EXISTS idx_subtitles_media ON subtitles(media_id);
+CREATE INDEX IF NOT EXISTS idx_subtitles_media ON subtitles (media_id);
 
 -- External metadata (enrichment)
 CREATE TABLE IF NOT EXISTS external_metadata (
-    id TEXT PRIMARY KEY,
-    media_id TEXT NOT NULL,
-    source TEXT NOT NULL,
-    external_id TEXT,
-    metadata_json TEXT NOT NULL DEFAULT '{}',
-    confidence REAL NOT NULL DEFAULT 0.0,
-    last_updated TEXT NOT NULL DEFAULT (datetime('now')),
-    FOREIGN KEY (media_id) REFERENCES media_items(id) ON DELETE CASCADE
+  id TEXT PRIMARY KEY,
+  media_id TEXT NOT NULL,
+  source TEXT NOT NULL,
+  external_id TEXT,
+  metadata_json TEXT NOT NULL DEFAULT '{}',
+  confidence REAL NOT NULL DEFAULT 0.0,
+  last_updated TEXT NOT NULL DEFAULT (datetime ('now')),
+  FOREIGN KEY (media_id) REFERENCES media_items (id) ON DELETE CASCADE
 );
 
-CREATE INDEX IF NOT EXISTS idx_external_metadata_media ON external_metadata(media_id);
+CREATE INDEX IF NOT EXISTS idx_external_metadata_media ON external_metadata (media_id);
 
 -- Transcode sessions
 CREATE TABLE IF NOT EXISTS transcode_sessions (
-    id TEXT PRIMARY KEY,
-    media_id TEXT NOT NULL,
-    user_id TEXT,
-    profile TEXT NOT NULL,
-    cache_path TEXT NOT NULL,
-    status TEXT NOT NULL DEFAULT 'pending',
-    progress REAL NOT NULL DEFAULT 0.0,
-    error_message TEXT,
-    created_at TEXT NOT NULL DEFAULT (datetime('now')),
-    expires_at TEXT,
-    FOREIGN KEY (media_id) REFERENCES media_items(id) ON DELETE CASCADE
+  id TEXT PRIMARY KEY,
+  media_id TEXT NOT NULL,
+  user_id TEXT,
+  profile TEXT NOT NULL,
+  cache_path TEXT NOT NULL,
+  status TEXT NOT NULL DEFAULT 'pending',
+  progress REAL NOT NULL DEFAULT 0.0,
+  error_message TEXT,
+  created_at TEXT NOT NULL DEFAULT (datetime ('now')),
+  expires_at TEXT,
+  FOREIGN KEY (media_id) REFERENCES media_items (id) ON DELETE CASCADE
 );
 
-CREATE INDEX IF NOT EXISTS idx_transcode_sessions_media ON transcode_sessions(media_id);
+CREATE INDEX IF NOT EXISTS idx_transcode_sessions_media ON transcode_sessions (media_id);

migrations/sqlite/V9__fix_indexes_and_constraints.sql

@@ -1,18 +1,25 @@
 -- Drop redundant indexes (already covered by UNIQUE constraints)
 DROP INDEX IF EXISTS idx_users_username;
+
 DROP INDEX IF EXISTS idx_user_libraries_user_id;
 
 -- Add missing indexes for comments table
-CREATE INDEX IF NOT EXISTS idx_comments_media ON comments(media_id);
-CREATE INDEX IF NOT EXISTS idx_comments_parent ON comments(parent_comment_id);
+CREATE INDEX IF NOT EXISTS idx_comments_media ON comments (media_id);
+
+CREATE INDEX IF NOT EXISTS idx_comments_parent ON comments (parent_comment_id);
 
 -- Remove duplicates before adding unique index (keep the first row)
 DELETE FROM external_metadata
-WHERE rowid NOT IN (
-    SELECT MIN(rowid)
-    FROM external_metadata
-    GROUP BY media_id, source
-);
+WHERE
+  rowid NOT IN (
+    SELECT
+      MIN(rowid)
+    FROM
+      external_metadata
+    GROUP BY
+      media_id,
+      source
+  );
 
 -- Add unique index for external_metadata to prevent duplicates
-CREATE UNIQUE INDEX IF NOT EXISTS uq_external_metadata_source ON external_metadata(media_id, source);
+CREATE UNIQUE INDEX IF NOT EXISTS uq_external_metadata_source ON external_metadata (media_id, source);

nix/shell.nix

@@ -26,21 +26,22 @@ in
     name = "pinakes-dev";
     packages =
       [
-        # Build tools
         # We use the rust-overlay to get the stable Rust toolchain for various targets.
         # This is not exactly necessary, but it allows for compiling for various targets
-        # with the least amount of friction.
+        # with the least amount of friction. The extensions are to make sure all tooling
+        # uses the same Rust version and the general surrounding tooling.
         (rust-bin.nightly.latest.default.override {
           extensions = ["rustfmt" "rust-src" "rust-analyzer" "clippy" "rust-analyzer"];
           targets = ["wasm32-unknown-unknown" "wasm32-wasip1"]; # web + plugins
         })
 
-        # Modern, LLVM based linking pipeline
+        # Modern, LLVM based linking pipeline. Kind of sucks on Windows, though.
         llvmPackages.lld
         llvmPackages.clang
 
-        # Handy CLI for packaging Dioxus apps and such
-        pkgs.dioxus-cli
+        # CLI helpers
+        pkgs.dioxus-cli # for packaging Dioxus apps and such
+        pkgs.just # general command runner for everything
 
         # Additional Cargo Tooling
         pkgs.cargo-nextest
@@ -49,29 +50,9 @@ in
         #  Other tools
         pkgs.taplo # TOML formatter
         pkgs.lldb # debugger
-        pkgs.sccache # distributed Rust cache
       ]
       ++ runtimeDeps;
 
-    # We could do this in the NixOS configuration via ~/.config/cargo.toml
-    # or something, but this is better because it lets everyone benefit
-    # from sccache while working with Pinakes. The reason those variables
-    # are not in 'env' are that we have to use Bash, which doesn't mix well
-    # with Nix strings.
-    shellHook = ''
-      if [ -n "$SCCACHE_BIN" ]; then
-        export RUSTC_WRAPPER="$SCCACHE_BIN"
-        export SCCACHE_DIR="''${HOME}/.cache/sccache"
-        export SCCACHE_CACHE_SIZE="50G"
-        mkdir -p "$SCCACHE_DIR"
-
-        echo "sccache setup complete!"
-      fi
-
-      # Start the daemon early for slightly faster startup.
-      "$SCCACHE_BIN" --start-server >/dev/null 2>&1 || true
-    '';
-
     env = {
       # Allow Cargo to use lld and clang properly
       LIBCLANG_PATH = "${llvmPackages.libclang.lib}/lib";
@@ -84,8 +65,5 @@ in
 
       # Runtime library path for GTK/WebKit/xdotool
       LD_LIBRARY_PATH = "${lib.makeLibraryPath runtimeDeps}";
-
-      # Enable sccache for local nix develop shell
-      SCCACHE_BIN = "${pkgs.sccache}/bin/sccache";
     };
   }

packages/pinakes-server/Cargo.toml

@@ -36,10 +36,10 @@ utoipa = { workspace = true }
 utoipa-axum = { workspace = true }
 utoipa-swagger-ui = { workspace = true }
 
-[lints]
-workspace = true
-
 [dev-dependencies]
-http-body-util = "0.1.3"
+http-body-util = { workspace = true }
 reqwest = { workspace = true }
 tempfile = { workspace = true }
+
+[lints]
+workspace = true