Document Jellyfin 12 search plugin

README.md

@@ -322,6 +322,55 @@ When `SCENE_API_KEY` is set, search and thumbnail endpoints accept either `Autho
 
 The API intentionally runs with one worker. Multiple workers would each load their own copy of the embedding model into GPU memory.
 
+## Jellyfin 12 search plugin
+
+The repository now includes a thin Jellyfin 12 plugin under `jellyfin-plugin/`. Jellyfin 12's external search-provider API accepts real Jellyfin item IDs with relevance scores, while Jellyfin core applies the requesting user's library visibility and access filtering afterwards. The plugin therefore sends the search text to the local Python API and returns the matching Jellyfin item IDs; it does not run AI models inside Jellyfin.
+
+### Build
+
+Jellyfin 12 plugins target .NET 10:
+
+```bash
+dotnet build jellyfin-plugin/Jellyfin.Plugin.SceneSearch/Jellyfin.Plugin.SceneSearch.csproj -c Release
+```
+
+The plugin DLL is then:
+
+```text
+jellyfin-plugin/Jellyfin.Plugin.SceneSearch/bin/Release/net10.0/Jellyfin.Plugin.SceneSearch.dll
+```
+
+Copy that DLL into a Scene Search directory under Jellyfin's plugin directory and restart Jellyfin.
+
+### Initial configuration
+
+Open **Dashboard → Plugins → Scene Search** and configure:
+
+- API URL: `http://127.0.0.1:8097` when Jellyfin and scene-search run on the same machine.
+- API key: the same value as `SCENE_API_KEY`.
+- Require a search prefix: enabled by default.
+- Prefix: `scene:`.
+
+The prefix is intentional for the first rollout. Jellyfin 12 uses non-empty external-provider results instead of its built-in SQL search results. While only a test library is indexed, making Scene Search answer every query could hide ordinary Jellyfin results that have not been indexed yet.
+
+With the default configuration:
+
+```text
+scene: woman standing outside
+```
+
+uses semantic Scene Search, while:
+
+```text
+Alien
+```
+
+continues to use Jellyfin's normal search.
+
+Once the complete libraries you care about are indexed and semantic ranking is calibrated, the prefix requirement can be disabled in the plugin settings so normal Jellyfin searches use Scene Search directly.
+
+The first version contributes Movies, Episodes and generic Videos because those are the item types currently ingested by `jellyfin-index`.
+
 ## Removing indexed sources
 
 Old prototype clips and Jellyfin-backed items are stored with different source kinds.