Improve documentation

[ildyria]

This pull request significantly updates and expands the facial recognition configuration documentation for Lychee. It clarifies service naming, environment variables, and Docker Compose setup, adds new sections on clustering and maintenance operations, and improves troubleshooting guidance. The documentation now better reflects the current architecture and provides more detailed instructions for both administrators and developers.

Key improvements and additions:

Service Naming & Docker Compose Configuration

• Standardizes naming to lychee_facial_recognition (instead of ai_vision), updates all references, and revises Docker Compose examples to reflect the latest setup and environment variables. [1] [2] [3]

Environment Variables & Settings

• Expands and reorganizes the documentation of environment variables for both Lychee and the facial recognition service, including new variables for clustering, concurrency, detection thresholds, and queue management. Adds a table of admin UI settings with defaults and descriptions. [1] [2]

Clustering & Maintenance Operations

• Adds new sections detailing how to run face clustering (DBSCAN) via the admin UI, explains cluster labeling, and documents all available maintenance operations (bulk scan, clustering, face deletion, embedding sync, and scan reset), including relevant CLI commands.

Troubleshooting & Diagnostics

• Expands troubleshooting guidance, clarifies volume mount and API key issues, and adds new tips for clustering and stuck scans. Notes the inclusion of a service health check in the Lychee admin diagnostics page.

General Documentation Improvements

• Updates terminology for clarity (e.g., "facial recognition service" instead of "AI Vision"), improves formatting, and ensures all instructions and references are current and consistent. [1] [2] [3] [4] [5] [6] [7]

Summary by CodeRabbit

• Documentation
  • Updated facial recognition configuration guide with new service references and expanded configuration options.
  • Added comprehensive configuration and permission tables for enabling facial recognition features in Lychee Admin.
  • Updated CLI commands and procedures for scanning and maintenance operations.
  • Enhanced troubleshooting section with improved guidance for resolving common configuration and operational issues.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: a9399edf-b78c-47df-90d1-722cd9827344

📥 Commits

Reviewing files that changed from the base of the PR and between 7d55399 and 485dc92.

📒 Files selected for processing (1)

• docs/specs/2-how-to/configure-facial-recognition.md

---

📝 Walkthrough

Walkthrough

Updates docs/specs/2-how-to/configure-facial-recognition.md to rename the facial recognition service from ai_vision to lychee_facial_recognition, expand environment variable documentation into two structured tables, add explicit admin settings, provide concrete CLI commands, and rewrite the troubleshooting section with new diagnostic steps.

Changes

Facial Recognition Configuration Guide Refresh

Layer / File(s)	Summary
Overview, prerequisites, and Docker Compose wiring docs/specs/2-how-to/configure-facial-recognition.md	Updates the last-updated date, renames the service to lychee_facial_recognition/lychee-facial-recognition sidecar throughout the overview, rewrites Prerequisites and Docker Compose Setup with new container names, environment variable wiring (AI Vision enablement, API URL/key/SSL, port mapping), and enforces identical host bind mount paths in the shared-volume table.
Environment variable tables and admin settings docs/specs/2-how-to/configure-facial-recognition.md	Replaces the prior env-var listing with two structured tables (Lychee-side and Python service) covering DBSCAN/clustering, concurrency/workers, queue backend/max size, detection/matching thresholds, quality filters, and storage backend; replaces optional-settings prose with an admin settings table for permission mode, selfie confidence, default is_searchable, user claiming, overlay visibility, and legal warning.
CLI commands, clustering, maintenance, and health check docs/specs/2-how-to/configure-facial-recognition.md	Adds concrete artisan commands for bulk scan (all unscanned and per-album), revises clustering trigger to reference the admin UI card, expands the maintenance table with rescan-failed-faces variants and stuck-pending handling, and updates the health check section with network/host example calls and an expanded JSON response schema (model_loaded, embedding_count).
Rewritten troubleshooting section docs/specs/2-how-to/configure-facial-recognition.md	Adds Admin → Diagnostics as a health-check entry point; updates each subsection covering 403 enablement, pending scan reset command with QUEUE_CONNECTION check, volume-mount/path consistency, 401 API key mismatch, selfie no-match threshold, and clustering re-run steps after changing VISION_FACE_CLUSTER_EPS.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

🐇 Hop hop, the docs are fresh and clear,
New service names for all to hear!
Two tidy tables, env vars aligned,
Troubleshooting traps now redefined.
The rabbit cheers — no more confusion here! 🎉

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}