LycheeOrg · ildyria · Jul 2, 2026 · Jul 2, 2026
diff --git a/src/content/docs/docs/faq/general.md b/src/content/docs/docs/faq/general.md
@@ -64,7 +64,7 @@ There is a discord associated with the project, feel free to join us there: http
 
 ### How can I set thumbnails for my albums?
 
-Thumbnails are selected automatically from the photos inside the album (and any subalbums) based on the photo sorting order specified in the [Settings](/docs/getting-started/settings/#sorting). _Precedence is given to starred photos_. In practical terms, if only one photo inside an album is starred, that photo is guaranteed to be the top thumbnail.
+Thumbnails are selected automatically from the photos inside the album (and any subalbums) based on the photo sorting order specified in the [Settings](/docs/getting-started/settings/#sorting_photos_col). _Precedence is given to starred photos_. In practical terms, if only one photo inside an album is starred, that photo is guaranteed to be the top thumbnail.
 
 ### Is it possible to create folders inside another folder? If so, how to do that?
 
@@ -77,7 +77,7 @@ Either press `n` (as **N**ew) or use the add menu.
 In order to bypass the CSRF protection, you can set up the `api_key` setting to a secret value and send that value over in the `Authorization` header.  
 Note that `api_key` only disables the CSRF protection, you still need to authenticate to the server.
 
-In order to authenticate, use [Session::login](https://lycheeorg.dev/docs/api.html#apisessionlogin) and pass the returned `lychee_session` cookie to all subsequent requests.
+In order to authenticate, use [Session::login](https://demo.lycheeorg.dev/docs/api) and pass the returned `lychee_session` cookie to all subsequent requests.
 
 The related code is available [here](https://github.com/LycheeOrg/Lychee/blob/master/app/Http/Middleware/VerifyCsrfToken.php#L55)
 
@@ -222,23 +222,18 @@ Edit the `custom.js` file in `/path/to/lychee/public/dist/` or use the _"Persona
 
 ### How is the upload folder protected?
 
-From [#304](https://github.com/LycheeOrg/Lychee/issues/304)
+There are now two possibilities:
 
-Short version: It's not protected
-
-Long answer: [#295](https://github.com/LycheeOrg/Lychee/pull/295) added some protection through symlinking, so that the URLs used are temporary.
-
-Right now, the protection is basically through the use of difficult to guess names (it's an MD5 checksum of the system time at the time of upload). [#295](https://github.com/LycheeOrg/Lychee/pull/295) not only made those names temporary (this needs to be enabled in the Settings, BTW) but it also provided optional support for hiding the full-size version (this is only effective with symlinking as without it the URL can be derived from that of intermediate-size images).
-
-[@ildyria](https://github.com/ildyria) recently posted the following link on how a more effective protection could be implemented: https://bedigit.com/blog/laravel-5-how-to-access-image-uploaded-in-storage-within-view/. He didn't go down that route himself due to performance concerns but we agree that if somebody contributed a clean implementation as an option, we'd probably accept it.
+- Use signed URLs to access the photos and avoid hot-linking, via the [`temporary_image_link_enabled`](/docs/getting-started/settings/#temporary_image_link_enabled) setting.
+- Use AES encrypted URLs, via the [`secure_image_link_enabled`](/docs/getting-started/settings/#secure_image_link_enabled) setting (only available for SE users).
 
 ### My login is timing out after two hours, how can this be changed?
 
 You can edit your `.env` and modify the `SESSION_LIFETIME=120` part (in minutes).
 
 ### How can I see the correct client IP address when running Lychee behind Cloudflare?
 
-Please see [https://github.com/monicahq/laravel-cloudflare](https://github.com/monicahq/laravel-cloudflare). The Lychee file that needs changing can be found [here](https://github.com/LycheeOrg/Lychee/blob/master/app/Http/Middleware/TrustProxies.php).
+Please see [https://github.com/monicahq/laravel-cloudflare](https://github.com/monicahq/laravel-cloudflare). The Lychee file that needs changing can be found [here](https://github.com/LycheeOrg/Lychee/blob/master/config/trustedproxy.php).
 
 ### Can I set up Lychee to watch a folder for new images and automatically add them to albums?
 
@@ -259,10 +254,3 @@ For example:
 ![](/docs/img/special-right-click-missing.png)
 
 No this is normal. This user does not have the ownership of that Album, so the right click is not available. You can see _sharing_ as a _read_ permission.
-
-### The divider h1 shows the text "Admin" when logged in with an ordinary user. Shouln't this be "Albums"?
-
-Actually no, this is because the user does not have any albums (yet). The `h1` divider is to show who is the owner of those albums. See below.
-![2020-02-19_3840x1080_12:29:19](https://user-images.githubusercontent.com/627094/74830496-92c3a200-5313-11ea-9065-60cb8090c7ac.png)
-And yes the right-click menu is available on the _PhD Defenses_ part but not in the _Admin_ parts.
-Also because this user has upload right, he can see the _Unsorted, Public, Starred, Recent_ smart albums.
diff --git a/src/content/docs/docs/features/facial-recognition.md b/src/content/docs/docs/features/facial-recognition.md
@@ -24,7 +24,7 @@ Facial recognition processes biometric data, which is subject to strict legal re
 
 - **Auto-scan on upload** — newly uploaded photos are automatically queued for face detection once both AI Vision and facial recognition are enabled.
 - **Detection** — the AI Vision service finds faces in each photo and returns bounding boxes plus an embedding (a numeric "fingerprint") for each face.
-- **Clustering** — faces that aren't yet linked to a person are grouped into clusters of similar-looking faces, so you can label a whole group at once instead of one face at a time.
+- **Clustering** — faces that aren't yet linked to a person are grouped into clusters of similar-looking faces, so you can label a whole group at once instead of one face at a time. Clustering can be re-run at any time from _Settings &rArr; Maintenance &rArr; Run Clustering_ (visible whenever unclustered faces exist) — useful after changing the microservice's `VISION_FACE_CLUSTER_EPS` if the resulting clusters aren't grouping people as expected. It only affects faces not yet assigned to a person; already-labelled faces are left untouched.
 - **Overlays** — when viewing a photo, detected faces are shown as overlays. Press `P` to toggle their visibility.
 
 ## People and Person Albums
@@ -169,3 +169,46 @@ The container exposes interactive API docs at `/docs` and a health check at `/he
 |---------------------------------------------|----------------------------------------------------------------------------------|
 | `php artisan lychee:scan-faces`          | Enqueue all unscanned photos for face detection. Use `--album={id}` to limit to the direct photos of one album. |
 | `php artisan lychee:rescan-failed-faces` | Re-enqueue photos whose scan previously failed. Add `--stuck-pending` (with `--older-than=<minutes>`, default 60) to also reset scans stuck in "pending" back to unscanned. |
+
+## Troubleshooting
+
+**Facial recognition options don't appear in Settings:**
+- Check that `ai_vision_enabled` and `ai_vision_face_enabled` are both turned on. Facial recognition is disabled by default and requires both.
+
+**Diagnostics reports the AI Vision service as unreachable:**
+- Verify `AI_VISION_FACE_URL` and `AI_VISION_FACE_API_KEY` are set in Lychee's `.env` and match the `VISION_FACE_API_KEY` configured on the microservice side.
+- Confirm the microservice container is running and reachable from Lychee (`docker-compose logs` on the facial-recognition service, or check its `/health` endpoint).
+- If Lychee and the microservice are on different hosts/networks, make sure firewalls and Docker networks allow the connection.
+
+**Photos are never scanned / stay stuck on "pending":**
+- Confirm a Lychee queue worker is running — face scans are processed asynchronously like other jobs.
+- Run `php artisan lychee:rescan-failed-faces --stuck-pending` to reset scans that have been stuck in "pending" for longer than `--older-than` minutes (default 60).
+- Check the microservice logs for `429 Too Many Requests`, which means its job queue (`VISION_FACE_QUEUE_MAX_SIZE`) is full; either wait for it to drain or increase the limit.
+
+**Some faces in a photo are detected but others are missed:**
+- Check `VISION_FACE_DETECTION_THRESHOLD` (default `0.5`) on the microservice — faces below this confidence are dropped; lower it to catch more faces at the cost of more false positives.
+- Small, angled, or partially occluded faces are the most likely to be missed. `VISION_FACE_MIN_FACE_SIZE_PIXELS` (default `0`, i.e. no filter) can be raising the bar further if set above zero — make sure it isn't filtering out legitimately small faces.
+- Blurry faces are discarded via `VISION_FACE_BLUR_THRESHOLD` (default `0.5`, Laplacian variance) — lower it if sharp-enough faces are still being rejected.
+- `VISION_FACE_MAX_FACES_PER_PHOTO` (default `10`) caps how many faces are returned per photo; group photos with more people than this will only have the top matches included.
+- Try a different `VISION_FACE_DETECTOR_BACKEND` (`retinaface`, `mtcnn`, `opencv`, `ssd`) — detectors vary in recall depending on pose, lighting, and image resolution.
+
+**Clustering groups unrelated faces together, or fails to group similar faces:**
+- Clustering is controlled by `VISION_FACE_CLUSTER_EPS` (default `0.6`), the DBSCAN epsilon (maximum cosine distance) allowed within a cluster. Lower it if dissimilar people are being grouped together; raise it if the same person is being split across multiple clusters.
+- To apply a new value: update `VISION_FACE_CLUSTER_EPS` in the microservice's `.env`, restart the microservice so it picks up the change, then re-trigger clustering from _Settings &rArr; Maintenance &rArr; Run Clustering_ in Lychee. This re-clusters every currently unassigned face with the new epsilon — repeat with a different value if the result still isn't right.
+- The `VISION_FACE_MODEL_NAME` (default `ArcFace`) recognition model determines embedding quality — a different model may produce more consistent embeddings for your photo set, but changing it does not retroactively update existing embeddings.
+- Poor detections (blurry, low-confidence, or partial faces — see above) produce noisy embeddings that cluster poorly; fixing detection quality often improves clustering as a side effect.
+- Clusters are only formed from faces not yet linked to a person; once a face is assigned to a person it's removed from the pool of unclustered faces.
+
+**Faces are detected but nothing shows up when opening a photo:**
+- Press `P` to toggle overlay visibility — they may just be hidden.
+- Check `ai_vision_face_overlay_enabled` and `ai_vision_face_overlay_default_visibility`.
+- Overlays and the People page are gated by `ai_vision_face_permission_mode` — see [Permission modes](#permission-modes); as an ordinary user you may simply lack the rights to view them.
+
+**Selfie claim doesn't match the right person:**
+- The match confidence must exceed `ai_vision_face_selfie_confidence_threshold` (default `0.8`). Lower it if legitimate matches are being rejected, or raise it if false positives occur.
+- Make sure the person you expect to match has enough labelled faces for a reliable embedding average.
+
+**The microservice fails to start:**
+- Missing required environment variables (`VISION_FACE_LYCHEE_API_URL`, `VISION_FACE_API_KEY`) produce a formatted error at startup — check the container logs for which variable is missing.
+- If using self-signed certificates for the Lychee callback URL, set `VISION_FACE_VERIFY_SSL=false`.
+- For local development without a reachable Lychee instance, set `VISION_FACE_SKIP_LYCHEE_CHECK=true`.