From 43a1c115c5ae709e41bee1b0f11194f027ddb370 Mon Sep 17 00:00:00 2001
From: ildyria <beviguier@gmail.com>
Date: Sun, 22 Mar 2026 09:48:46 +0100
Subject: [PATCH 01/10] Frontend wip

---
 lang/en/people.php                            |  58 +++++
 .../js/components/gallery/PersonCard.vue      |  36 +++
 .../gallery/photoModule/FaceOverlay.vue       |  66 +++++
 .../gallery/photoModule/PhotoPanel.vue        |   8 +
 .../components/modals/FaceAssignmentModal.vue | 168 +++++++++++++
 resources/js/lychee.d.ts                      |  30 +++
 .../js/services/face-detection-service.ts     |  33 +++
 resources/js/services/people-service.ts       |  56 +++++
 resources/js/views/People.vue                 |  86 +++++++
 resources/js/views/PersonDetail.vue           | 234 ++++++++++++++++++
 10 files changed, 775 insertions(+)
 create mode 100644 lang/en/people.php
 create mode 100644 resources/js/components/gallery/PersonCard.vue
 create mode 100644 resources/js/components/gallery/photoModule/FaceOverlay.vue
 create mode 100644 resources/js/components/modals/FaceAssignmentModal.vue
 create mode 100644 resources/js/services/face-detection-service.ts
 create mode 100644 resources/js/services/people-service.ts
 create mode 100644 resources/js/views/People.vue
 create mode 100644 resources/js/views/PersonDetail.vue

diff --git a/lang/en/people.php b/lang/en/people.php
new file mode 100644
index 00000000000..7f5dc009ce0
--- /dev/null
+++ b/lang/en/people.php
@@ -0,0 +1,58 @@
+<?php
+
+/**
+ * SPDX-License-Identifier: MIT
+ * Copyright (c) 2017-2018 Tobias Reich
+ * Copyright (c) 2018-2026 LycheeOrg.
+ */
+
+return [
+    /*
+    |--------------------------------------------------------------------------
+    | People / Facial Recognition
+    |--------------------------------------------------------------------------
+    */
+    'title' => 'People',
+    'description' => 'Browse photos by the people in them.',
+    'no_people' => 'No people found yet. Scan some photos to detect faces.',
+    'photos_label' => 'photo(s)',
+    'faces_label' => 'face(s)',
+    'hidden_faces' => 'face(s) hidden for privacy',
+    'unknown' => 'Unknown',
+    'confidence' => 'Confidence',
+    'assign_face' => 'Assign face',
+    'dismiss_face' => 'Dismiss face',
+    'undismiss_face' => 'Undismiss face',
+    'scan_faces' => 'Scan for faces',
+    'scanning' => 'Scanning for faces…',
+    'scan_success' => 'Face scan queued successfully.',
+    'not_searchable' => 'Hidden',
+    'searchable' => 'Visible',
+    'claim_by_selfie' => 'Find me in photos',
+    'claim_by_selfie_description' => 'Upload a selfie to find and link your person profile.',
+    'claims' => [
+        'success' => 'Successfully linked to your profile.',
+        'no_face' => 'No face detected in the selfie.',
+        'no_match' => 'No matching person found.',
+        'already_claimed' => 'This person is already linked to another user.',
+        'low_confidence' => 'Match confidence too low. Please try a clearer photo.',
+    ],
+    'person' => [
+        'edit' => 'Edit',
+        'delete' => 'Delete',
+        'merge' => 'Merge into…',
+        'toggle_searchable' => 'Toggle visibility',
+        'claim' => 'This is me',
+        'unclaim' => 'Unlink from me',
+        'photos_title' => 'Photos of %s',
+    ],
+    'assignment' => [
+        'title' => 'Assign face to person',
+        'select_person' => 'Select existing person…',
+        'new_person' => 'Or create new person',
+        'new_person_placeholder' => 'New person name…',
+        'confirm' => 'Assign',
+        'cancel' => 'Cancel',
+        'success' => 'Face assigned successfully.',
+    ],
+];
diff --git a/resources/js/components/gallery/PersonCard.vue b/resources/js/components/gallery/PersonCard.vue
new file mode 100644
index 00000000000..9a96f28b058
--- /dev/null
+++ b/resources/js/components/gallery/PersonCard.vue
@@ -0,0 +1,36 @@
+<template>
+	<Card class="cursor-pointer hover:shadow-lg transition-shadow duration-200" @click="$router.push({ name: 'person', params: { personId: person.id } })">
+		<template #header>
+			<div class="aspect-square overflow-hidden rounded-t-lg bg-surface-800 flex items-center justify-center">
+				<img
+					v-if="person.representative_crop_url"
+					:src="person.representative_crop_url"
+					:alt="person.name"
+					class="w-full h-full object-cover"
+				/>
+				<i v-else class="pi pi-user text-6xl text-muted-color" />
+			</div>
+		</template>
+		<template #title>
+			<div class="flex items-center gap-2">
+				<span class="truncate font-semibold">{{ person.name }}</span>
+				<Tag v-if="!person.is_searchable" severity="secondary" :value="$t('people.not_searchable')" class="text-xs" />
+			</div>
+		</template>
+		<template #content>
+			<div class="text-sm text-muted-color">
+				{{ person.photo_count }} {{ $t("people.photos_label") }}
+			</div>
+		</template>
+	</Card>
+</template>
+
+<script setup lang="ts">
+import Card from "primevue/card";
+import Tag from "primevue/tag";
+
+defineProps<{
+	person: App.Http.Resources.Models.PersonResource;
+}>();
+</script>
+
diff --git a/resources/js/components/gallery/photoModule/FaceOverlay.vue b/resources/js/components/gallery/photoModule/FaceOverlay.vue
new file mode 100644
index 00000000000..023d85c1900
--- /dev/null
+++ b/resources/js/components/gallery/photoModule/FaceOverlay.vue
@@ -0,0 +1,66 @@
+<template>
+	<div v-if="faces.length > 0 || hiddenFaceCount > 0" class="absolute inset-0 pointer-events-none">
+		<!-- Face bounding box overlays -->
+		<template v-for="face in visibleFaces" :key="face.id">
+			<div
+				v-if="!face.is_dismissed"
+				class="absolute border-2 rounded transition-opacity duration-200 pointer-events-auto cursor-pointer"
+				:class="face.person_id ? 'border-primary-400 hover:border-primary-300' : 'border-yellow-400 hover:border-yellow-300'"
+				:style="{
+					left: face.x * 100 + '%',
+					top: face.y * 100 + '%',
+					width: face.width * 100 + '%',
+					height: face.height * 100 + '%',
+				}"
+				@click.stop="openAssignment(face)"
+			>
+				<div
+					class="absolute top-full left-0 mt-0.5 px-1.5 py-0.5 text-xs rounded whitespace-nowrap max-w-32 truncate"
+					:class="face.person_id ? 'bg-primary-500 text-white' : 'bg-yellow-500 text-black'"
+				>
+					{{ faceLabel(face) }}
+				</div>
+			</div>
+		</template>
+
+		<!-- Privacy notice for hidden faces -->
+		<div v-if="hiddenFaceCount > 0" class="absolute bottom-2 left-2 bg-black/60 text-white text-xs px-2 py-1 rounded pointer-events-none">
+			{{ hiddenFaceCount }} {{ $t("people.hidden_faces") }}
+		</div>
+
+		<!-- Assignment modal -->
+		<FaceAssignmentModal v-if="selectedFace" v-model:visible="isAssignmentOpen" :face="selectedFace" @assigned="emits('facesUpdated')" />
+	</div>
+</template>
+
+<script setup lang="ts">
+import { computed, ref } from "vue";
+import FaceAssignmentModal from "@/components/modals/FaceAssignmentModal.vue";
+
+const props = defineProps<{
+	faces: App.Http.Resources.Models.FaceResource[];
+	hiddenFaceCount: number;
+	personNames: Record<string, string>;
+}>();
+
+const emits = defineEmits<{
+	facesUpdated: [];
+}>();
+
+const isAssignmentOpen = ref(false);
+const selectedFace = ref<App.Http.Resources.Models.FaceResource | undefined>(undefined);
+
+const visibleFaces = computed(() => props.faces.filter((f) => !f.is_dismissed));
+
+function faceLabel(face: App.Http.Resources.Models.FaceResource): string {
+	if (face.person_id && props.personNames[face.person_id]) {
+		return props.personNames[face.person_id];
+	}
+	return "Unknown";
+}
+
+function openAssignment(face: App.Http.Resources.Models.FaceResource) {
+	selectedFace.value = face;
+	isAssignmentOpen.value = true;
+}
+</script>
diff --git a/resources/js/components/gallery/photoModule/PhotoPanel.vue b/resources/js/components/gallery/photoModule/PhotoPanel.vue
index 467b548e817..5b449436e1e 100644
--- a/resources/js/components/gallery/photoModule/PhotoPanel.vue
+++ b/resources/js/components/gallery/photoModule/PhotoPanel.vue
@@ -27,6 +27,13 @@
 			/>
 			<Overlay v-if="!is_exif_disabled && photoStore.imageViewMode !== ImageViewMode.Pdf" />
 			<PhotoRatingOverlay />
+			<FaceOverlay
+				v-if="photoStore.photo.faces && photoStore.photo.faces.length > 0 || photoStore.photo.hidden_face_count > 0"
+				:faces="photoStore.photo.faces ?? []"
+				:hidden-face-count="photoStore.photo.hidden_face_count ?? 0"
+				:person-names="{}"
+				@faces-updated="photoStore.reload()"
+			/>
 			<Dock
 				v-if="albumStore.rights?.can_edit && !is_photo_edit_open"
 				:is-narrow-menu="photoStore.imageViewMode === ImageViewMode.Pdf"
@@ -49,6 +56,7 @@ import { onMounted } from "vue";
 import NextPrevious from "./NextPrevious.vue";
 import Overlay from "./Overlay.vue";
 import PhotoRatingOverlay from "./PhotoRatingOverlay.vue";
+import FaceOverlay from "./FaceOverlay.vue";
 import PhotoDetails from "@/components/drawers/PhotoDetails.vue";
 import PhotoHeader from "@/components/headers/PhotoHeader.vue";
 import Dock from "./Dock.vue";
diff --git a/resources/js/components/modals/FaceAssignmentModal.vue b/resources/js/components/modals/FaceAssignmentModal.vue
new file mode 100644
index 00000000000..46b8bb8cedf
--- /dev/null
+++ b/resources/js/components/modals/FaceAssignmentModal.vue
@@ -0,0 +1,168 @@
+<template>
+	<Dialog v-model:visible="visible" modal :header="$t('people.assignment.title')" pt:root:class="border-none w-full max-w-md">
+		<div class="flex flex-col gap-4 p-2">
+			<!-- Face crop preview -->
+			<div class="flex justify-center">
+				<img
+					v-if="face.crop_url"
+					:src="face.crop_url"
+					alt="Face crop"
+					class="w-24 h-24 rounded-full object-cover border-2 border-surface-700"
+				/>
+				<div v-else class="w-24 h-24 rounded-full bg-surface-800 flex items-center justify-center">
+					<i class="pi pi-user text-4xl text-muted-color" />
+				</div>
+			</div>
+			<div class="text-center text-sm text-muted-color">
+				{{ $t("people.confidence") }}: {{ Math.round(face.confidence * 100) }}%
+			</div>
+
+			<!-- Suggestions -->
+			<div v-if="face.suggestions.length > 0" class="flex flex-col gap-2">
+				<div class="text-sm font-semibold text-muted-color-emphasis">Suggestions</div>
+				<div class="flex gap-2 flex-wrap">
+					<Button
+						v-for="suggestion in face.suggestions"
+						:key="suggestion.suggested_face_id"
+						severity="secondary"
+						outlined
+						size="small"
+						@click="selectSuggestion(suggestion)"
+					>
+						<img
+							v-if="suggestion.crop_url"
+							:src="suggestion.crop_url"
+							class="w-6 h-6 rounded-full object-cover mr-1"
+							alt=""
+						/>
+						{{ suggestion.person_name ?? $t("people.unknown") }}
+						({{ Math.round(suggestion.confidence * 100) }}%)
+					</Button>
+				</div>
+			</div>
+
+			<!-- Select existing person -->
+			<div>
+				<label class="block text-sm text-muted-color mb-1">{{ $t("people.assignment.select_person") }}</label>
+				<Select
+					v-model="selectedPersonId"
+					:options="people"
+					option-label="name"
+					option-value="id"
+					:placeholder="$t('people.assignment.select_person')"
+					class="w-full"
+					filter
+					:loading="loadingPeople"
+					@change="newPersonName = ''"
+				/>
+			</div>
+
+			<!-- Or create new person -->
+			<div>
+				<label class="block text-sm text-muted-color mb-1">{{ $t("people.assignment.new_person") }}</label>
+				<InputText
+					v-model="newPersonName"
+					class="w-full"
+					:placeholder="$t('people.assignment.new_person_placeholder')"
+					@input="selectedPersonId = undefined"
+				/>
+			</div>
+		</div>
+
+		<template #footer>
+			<div class="flex gap-2 justify-end">
+				<Button :label="$t('people.assignment.cancel')" severity="secondary" text @click="visible = false" />
+				<Button
+					:label="$t('people.assignment.confirm')"
+					severity="primary"
+					:disabled="!selectedPersonId && !newPersonName.trim()"
+					:loading="submitting"
+					@click="submit"
+				/>
+			</div>
+		</template>
+	</Dialog>
+</template>
+
+<script setup lang="ts">
+import { ref, watch } from "vue";
+import Dialog from "primevue/dialog";
+import Button from "primevue/button";
+import InputText from "primevue/inputtext";
+import Select from "primevue/select";
+import { useToast } from "primevue/usetoast";
+import { trans } from "laravel-vue-i18n";
+import FaceDetectionService from "@/services/face-detection-service";
+import PeopleService from "@/services/people-service";
+
+const props = defineProps<{
+	face: App.Http.Resources.Models.FaceResource;
+}>();
+
+const emits = defineEmits<{
+	assigned: [];
+}>();
+
+const visible = defineModel<boolean>("visible", { default: false });
+
+const toast = useToast();
+const people = ref<App.Http.Resources.Models.PersonResource[]>([]);
+const loadingPeople = ref(false);
+const selectedPersonId = ref<string | undefined>(undefined);
+const newPersonName = ref("");
+const submitting = ref(false);
+
+function selectSuggestion(suggestion: App.Http.Resources.Models.FaceSuggestionResource) {
+	if (suggestion.person_name) {
+		const match = people.value.find((p) => p.name === suggestion.person_name);
+		if (match) {
+			selectedPersonId.value = match.id;
+			newPersonName.value = "";
+		}
+	}
+}
+
+function loadPeople() {
+	loadingPeople.value = true;
+	PeopleService.getPeople()
+		.then((response) => {
+			people.value = response.data.data;
+		})
+		.finally(() => {
+			loadingPeople.value = false;
+		});
+}
+
+function submit() {
+	submitting.value = true;
+	const data: { person_id?: string; new_person_name?: string } = {};
+	if (selectedPersonId.value) {
+		data.person_id = selectedPersonId.value;
+	} else if (newPersonName.value.trim()) {
+		data.new_person_name = newPersonName.value.trim();
+	}
+
+	FaceDetectionService.assignFace(props.face.id, data)
+		.then(() => {
+			toast.add({ severity: "success", summary: trans("toasts.success"), detail: trans("people.assignment.success"), life: 3000 });
+			visible.value = false;
+			selectedPersonId.value = undefined;
+			newPersonName.value = "";
+			emits("assigned");
+		})
+		.catch((e) => {
+			toast.add({ severity: "error", summary: trans("toasts.error"), detail: e.response?.data?.message, life: 3000 });
+		})
+		.finally(() => {
+			submitting.value = false;
+		});
+}
+
+watch(visible, (newVal) => {
+	if (newVal) {
+		selectedPersonId.value = undefined;
+		newPersonName.value = "";
+		loadPeople();
+	}
+});
+</script>
diff --git a/resources/js/lychee.d.ts b/resources/js/lychee.d.ts
index dec7169be85..30860257bbc 100644
--- a/resources/js/lychee.d.ts
+++ b/resources/js/lychee.d.ts
@@ -711,6 +711,36 @@ declare namespace App.Http.Resources.Models {
 		palette: App.Http.Resources.Models.ColourPaletteResource | null;
 		statistics: App.Http.Resources.Models.PhotoStatisticsResource | null;
 		rating: App.Http.Resources.Models.PhotoRatingResource | null;
+		faces: App.Http.Resources.Models.FaceResource[];
+		hidden_face_count: number;
+	};
+	export type FaceSuggestionResource = {
+		suggested_face_id: string;
+		crop_url: string | null;
+		person_name: string | null;
+		confidence: number;
+	};
+	export type FaceResource = {
+		id: string;
+		photo_id: string;
+		person_id: string | null;
+		x: number;
+		y: number;
+		width: number;
+		height: number;
+		confidence: number;
+		is_dismissed: boolean;
+		crop_url: string | null;
+		suggestions: App.Http.Resources.Models.FaceSuggestionResource[];
+	};
+	export type PersonResource = {
+		id: string;
+		name: string;
+		user_id: number | null;
+		is_searchable: boolean;
+		face_count: number;
+		photo_count: number;
+		representative_crop_url: string | null;
 	};
 	export type PhotoStatisticsResource = {
 		visit_count: number;
diff --git a/resources/js/services/face-detection-service.ts b/resources/js/services/face-detection-service.ts
new file mode 100644
index 00000000000..14d0567e2e7
--- /dev/null
+++ b/resources/js/services/face-detection-service.ts
@@ -0,0 +1,33 @@
+import axios, { type AxiosResponse } from "axios";
+import Constants from "./constants";
+
+const FaceDetectionService = {
+	scanPhotos(photoIds: string[]): Promise<AxiosResponse> {
+		return axios.post(`${Constants.getApiUrl()}FaceDetection::scan`, { photo_ids: photoIds });
+	},
+
+	scanAlbum(albumId: string): Promise<AxiosResponse> {
+		return axios.post(`${Constants.getApiUrl()}FaceDetection::scan`, { album_id: albumId });
+	},
+
+	bulkScan(): Promise<AxiosResponse> {
+		return axios.post(`${Constants.getApiUrl()}FaceDetection::bulk-scan`, {});
+	},
+
+	assignFace(
+		faceId: string,
+		data: { person_id?: string; new_person_name?: string },
+	): Promise<AxiosResponse> {
+		return axios.post(`${Constants.getApiUrl()}Face/${faceId}/assign`, data);
+	},
+
+	toggleDismissed(faceId: string): Promise<AxiosResponse> {
+		return axios.patch(`${Constants.getApiUrl()}Face/${faceId}`, {});
+	},
+
+	destroyDismissed(): Promise<AxiosResponse<{ deleted_count: number }>> {
+		return axios.delete(`${Constants.getApiUrl()}Face/dismissed`);
+	},
+};
+
+export default FaceDetectionService;
diff --git a/resources/js/services/people-service.ts b/resources/js/services/people-service.ts
new file mode 100644
index 00000000000..8369c64cbe0
--- /dev/null
+++ b/resources/js/services/people-service.ts
@@ -0,0 +1,56 @@
+import axios, { type AxiosResponse } from "axios";
+import Constants, { type PaginatedResponse } from "./constants";
+
+const PeopleService = {
+	getPeople(page: number = 1): Promise<AxiosResponse<PaginatedResponse<App.Http.Resources.Models.PersonResource>>> {
+		return axios.get(`${Constants.getApiUrl()}People`, { params: { page }, data: {} });
+	},
+
+	getPerson(id: string): Promise<AxiosResponse<App.Http.Resources.Models.PersonResource>> {
+		return axios.get(`${Constants.getApiUrl()}People/${id}`, { data: {} });
+	},
+
+	getPhotos(
+		id: string,
+		page: number = 1,
+	): Promise<AxiosResponse<PaginatedResponse<App.Http.Resources.Models.PhotoResource>>> {
+		return axios.get(`${Constants.getApiUrl()}People/${id}/photos`, { params: { page }, data: {} });
+	},
+
+	create(name: string): Promise<AxiosResponse<App.Http.Resources.Models.PersonResource>> {
+		return axios.post(`${Constants.getApiUrl()}People`, { name });
+	},
+
+	update(
+		id: string,
+		data: { name?: string; is_searchable?: boolean },
+	): Promise<AxiosResponse<App.Http.Resources.Models.PersonResource>> {
+		return axios.patch(`${Constants.getApiUrl()}People/${id}`, data);
+	},
+
+	destroy(id: string): Promise<AxiosResponse> {
+		return axios.delete(`${Constants.getApiUrl()}People/${id}`);
+	},
+
+	claim(id: string): Promise<AxiosResponse> {
+		return axios.post(`${Constants.getApiUrl()}People/${id}/claim`);
+	},
+
+	unclaim(id: string): Promise<AxiosResponse> {
+		return axios.delete(`${Constants.getApiUrl()}People/${id}/claim`);
+	},
+
+	merge(targetId: string, sourcePersonId: string): Promise<AxiosResponse> {
+		return axios.post(`${Constants.getApiUrl()}People/${targetId}/merge`, { source_person_id: sourcePersonId });
+	},
+
+	claimBySelfie(file: File): Promise<AxiosResponse<App.Http.Resources.Models.PersonResource>> {
+		const form = new FormData();
+		form.append("selfie", file);
+		return axios.post(`${Constants.getApiUrl()}People/claim-by-selfie`, form, {
+			headers: { "Content-Type": "multipart/form-data" },
+		});
+	},
+};
+
+export default PeopleService;
diff --git a/resources/js/views/People.vue b/resources/js/views/People.vue
new file mode 100644
index 00000000000..cdd24d4e0dc
--- /dev/null
+++ b/resources/js/views/People.vue
@@ -0,0 +1,86 @@
+<template>
+	<div class="h-svh overflow-y-auto">
+		<Toolbar class="w-full border-0 h-14 rounded-none">
+			<template #start>
+				<OpenLeftMenu />
+			</template>
+			<template #center>
+				{{ $t("people.title") }}
+			</template>
+			<template #end> </template>
+		</Toolbar>
+
+		<div v-if="loading" class="flex justify-center items-center mt-20">
+			<ProgressSpinner />
+		</div>
+
+		<div v-else-if="people.length === 0" class="text-muted-color text-center mt-20 p-4">
+			{{ $t("people.no_people") }}
+		</div>
+
+		<div v-else class="p-6 grid grid-cols-2 sm:grid-cols-3 md:grid-cols-4 lg:grid-cols-5 xl:grid-cols-6 gap-4">
+			<PersonCard v-for="person in people" :key="person.id" :person="person" />
+		</div>
+
+		<div v-if="hasMorePages" class="flex justify-center pb-8 mt-4">
+			<Button :label="$t('gallery.load_more') || 'Load more'" severity="secondary" outlined @click="loadMore" :loading="loadingMore" />
+		</div>
+	</div>
+</template>
+
+<script setup lang="ts">
+import { ref, onMounted } from "vue";
+import Toolbar from "primevue/toolbar";
+import ProgressSpinner from "primevue/progressspinner";
+import Button from "primevue/button";
+import { useToast } from "primevue/usetoast";
+import { trans } from "laravel-vue-i18n";
+import OpenLeftMenu from "@/components/headers/OpenLeftMenu.vue";
+import PersonCard from "@/components/gallery/PersonCard.vue";
+import PeopleService from "@/services/people-service";
+
+const toast = useToast();
+
+const people = ref<App.Http.Resources.Models.PersonResource[]>([]);
+const loading = ref(false);
+const loadingMore = ref(false);
+const currentPage = ref(1);
+const hasMorePages = ref(false);
+
+function load() {
+	loading.value = true;
+	PeopleService.getPeople(1)
+		.then((response) => {
+			people.value = response.data.data;
+			currentPage.value = 1;
+			hasMorePages.value = response.data.meta.current_page < response.data.meta.last_page;
+		})
+		.catch((e) => {
+			toast.add({ severity: "error", summary: trans("toasts.error"), detail: e.response?.data?.message, life: 3000 });
+		})
+		.finally(() => {
+			loading.value = false;
+		});
+}
+
+function loadMore() {
+	loadingMore.value = true;
+	const nextPage = currentPage.value + 1;
+	PeopleService.getPeople(nextPage)
+		.then((response) => {
+			people.value = [...people.value, ...response.data.data];
+			currentPage.value = nextPage;
+			hasMorePages.value = response.data.meta.current_page < response.data.meta.last_page;
+		})
+		.catch((e) => {
+			toast.add({ severity: "error", summary: trans("toasts.error"), detail: e.response?.data?.message, life: 3000 });
+		})
+		.finally(() => {
+			loadingMore.value = false;
+		});
+}
+
+onMounted(() => {
+	load();
+});
+</script>
diff --git a/resources/js/views/PersonDetail.vue b/resources/js/views/PersonDetail.vue
new file mode 100644
index 00000000000..4ad531a05e0
--- /dev/null
+++ b/resources/js/views/PersonDetail.vue
@@ -0,0 +1,234 @@
+<template>
+	<div class="h-svh overflow-y-auto">
+		<Toolbar class="w-full border-0 h-14 rounded-none">
+			<template #start>
+				<div class="flex items-center gap-2">
+					<OpenLeftMenu />
+					<Button icon="pi pi-arrow-left" severity="secondary" text @click="$router.push({ name: 'people' })" />
+				</div>
+			</template>
+			<template #center>
+				<span v-if="person">{{ person.name }}</span>
+			</template>
+			<template #end>
+				<div v-if="person && canEdit" class="flex gap-2">
+					<Button icon="pi pi-pencil" severity="secondary" text v-tooltip.bottom="$t('people.person.edit')" @click="openEdit" />
+					<Button
+						:icon="person.is_searchable ? 'pi pi-eye' : 'pi pi-eye-slash'"
+						severity="secondary"
+						text
+						v-tooltip.bottom="$t('people.person.toggle_searchable')"
+						@click="toggleSearchable"
+					/>
+					<Button
+						icon="pi pi-trash"
+						severity="danger"
+						text
+						v-tooltip.bottom="$t('people.person.delete')"
+						@click="confirmDelete"
+					/>
+				</div>
+			</template>
+		</Toolbar>
+
+		<div v-if="loading" class="flex justify-center items-center mt-20">
+			<ProgressSpinner />
+		</div>
+
+		<template v-else-if="person">
+			<!-- Person header -->
+			<div class="flex flex-col sm:flex-row items-center gap-6 p-6 border-b border-surface-700">
+				<div class="w-24 h-24 rounded-full overflow-hidden bg-surface-800 flex items-center justify-center flex-shrink-0">
+					<img
+						v-if="person.representative_crop_url"
+						:src="person.representative_crop_url"
+						:alt="person.name"
+						class="w-full h-full object-cover"
+					/>
+					<i v-else class="pi pi-user text-4xl text-muted-color" />
+				</div>
+				<div class="flex flex-col gap-2 text-center sm:text-left">
+					<h1 class="text-2xl font-bold">{{ person.name }}</h1>
+					<div class="text-muted-color text-sm">
+						{{ person.photo_count }} {{ $t("people.photos_label") }} &bull; {{ person.face_count }} {{ $t("people.faces_label") }}
+					</div>
+					<Tag v-if="!person.is_searchable" severity="secondary" :value="$t('people.not_searchable')" class="w-fit mx-auto sm:mx-0" />
+				</div>
+			</div>
+
+			<!-- Edit form -->
+			<div v-if="isEditing" class="p-6 border-b border-surface-700 flex gap-4 items-end">
+				<div class="flex-1">
+					<label class="block text-sm text-muted-color mb-1">{{ $t("users.name") }}</label>
+					<InputText v-model="editName" class="w-full" @keydown.enter="saveEdit" @keydown.escape="isEditing = false" />
+				</div>
+				<Button :label="$t('gallery.done')" severity="primary" @click="saveEdit" />
+				<Button :label="$t('gallery.cancel')" severity="secondary" text @click="isEditing = false" />
+			</div>
+
+			<!-- Photos grid -->
+			<div v-if="photos.length === 0 && !photosLoading" class="text-muted-color text-center mt-10 p-4">
+				{{ $t("search.no_results") }}
+			</div>
+			<div v-else class="p-6 grid grid-cols-2 sm:grid-cols-3 md:grid-cols-4 lg:grid-cols-5 xl:grid-cols-6 gap-2">
+				<div v-for="photo in photos" :key="photo.id" class="aspect-square overflow-hidden rounded-lg bg-surface-800">
+					<img
+						v-if="photo.size_variants.thumb"
+						:src="photo.size_variants.thumb.url ?? ''"
+						:alt="photo.title"
+						class="w-full h-full object-cover"
+					/>
+					<div v-else class="w-full h-full flex items-center justify-center">
+						<i class="pi pi-image text-3xl text-muted-color" />
+					</div>
+				</div>
+			</div>
+			<div v-if="photosLoading" class="flex justify-center py-4">
+				<ProgressSpinner class="w-8 h-8" />
+			</div>
+			<div v-if="hasMorePhotos" class="flex justify-center pb-8 mt-4">
+				<Button :label="$t('gallery.load_more') || 'Load more'" severity="secondary" outlined @click="loadMorePhotos" :loading="photosLoadingMore" />
+			</div>
+		</template>
+
+		<ConfirmDialog />
+	</div>
+</template>
+
+<script setup lang="ts">
+import { ref, onMounted } from "vue";
+import { useRouter } from "vue-router";
+import Toolbar from "primevue/toolbar";
+import ProgressSpinner from "primevue/progressspinner";
+import Button from "primevue/button";
+import InputText from "primevue/inputtext";
+import Tag from "primevue/tag";
+import ConfirmDialog from "primevue/confirmdialog";
+import { useToast } from "primevue/usetoast";
+import { useConfirm } from "primevue/useconfirm";
+import { trans } from "laravel-vue-i18n";
+import OpenLeftMenu from "@/components/headers/OpenLeftMenu.vue";
+import PeopleService from "@/services/people-service";
+import { useUserStore } from "@/stores/UserState";
+import { storeToRefs } from "pinia";
+
+const props = defineProps<{ personId: string }>();
+
+const router = useRouter();
+const toast = useToast();
+const confirm = useConfirm();
+const userStore = useUserStore();
+const { user } = storeToRefs(userStore);
+const canEdit = ref(false);
+
+const person = ref<App.Http.Resources.Models.PersonResource | undefined>(undefined);
+const loading = ref(false);
+const isEditing = ref(false);
+const editName = ref("");
+
+const photos = ref<App.Http.Resources.Models.PhotoResource[]>([]);
+const photosLoading = ref(false);
+const photosLoadingMore = ref(false);
+const photosPage = ref(1);
+const hasMorePhotos = ref(false);
+
+function load() {
+	loading.value = true;
+	PeopleService.getPerson(props.personId)
+		.then((response) => {
+			person.value = response.data;
+			editName.value = response.data.name;
+			canEdit.value = user.value?.id !== undefined && user.value?.id !== null;
+			loadPhotos();
+		})
+		.catch((e) => {
+			toast.add({ severity: "error", summary: trans("toasts.error"), detail: e.response?.data?.message, life: 3000 });
+		})
+		.finally(() => {
+			loading.value = false;
+		});
+}
+
+function loadPhotos() {
+	photosLoading.value = true;
+	PeopleService.getPhotos(props.personId, 1)
+		.then((response) => {
+			photos.value = response.data.data;
+			photosPage.value = 1;
+			hasMorePhotos.value = response.data.meta.current_page < response.data.meta.last_page;
+		})
+		.finally(() => {
+			photosLoading.value = false;
+		});
+}
+
+function loadMorePhotos() {
+	photosLoadingMore.value = true;
+	const nextPage = photosPage.value + 1;
+	PeopleService.getPhotos(props.personId, nextPage)
+		.then((response) => {
+			photos.value = [...photos.value, ...response.data.data];
+			photosPage.value = nextPage;
+			hasMorePhotos.value = response.data.meta.current_page < response.data.meta.last_page;
+		})
+		.finally(() => {
+			photosLoadingMore.value = false;
+		});
+}
+
+function openEdit() {
+	editName.value = person.value?.name ?? "";
+	isEditing.value = true;
+}
+
+function saveEdit() {
+	if (!editName.value.trim() || !person.value) {
+		return;
+	}
+	PeopleService.update(person.value.id, { name: editName.value.trim() })
+		.then((response) => {
+			person.value = response.data;
+			isEditing.value = false;
+			toast.add({ severity: "success", summary: trans("toasts.success"), life: 3000 });
+		})
+		.catch((e) => {
+			toast.add({ severity: "error", summary: trans("toasts.error"), detail: e.response?.data?.message, life: 3000 });
+		});
+}
+
+function toggleSearchable() {
+	if (!person.value) {
+		return;
+	}
+	PeopleService.update(person.value.id, { is_searchable: !person.value.is_searchable })
+		.then((response) => {
+			person.value = response.data;
+			toast.add({ severity: "success", summary: trans("toasts.success"), life: 3000 });
+		})
+		.catch((e) => {
+			toast.add({ severity: "error", summary: trans("toasts.error"), detail: e.response?.data?.message, life: 3000 });
+		});
+}
+
+function confirmDelete() {
+	confirm.require({
+		message: trans("dialogs.delete_confirm"),
+		header: trans("dialogs.delete"),
+		icon: "pi pi-trash",
+		acceptClass: "p-button-danger",
+		accept() {
+			PeopleService.destroy(props.personId)
+				.then(() => {
+					router.push({ name: "people" });
+				})
+				.catch((e) => {
+					toast.add({ severity: "error", summary: trans("toasts.error"), detail: e.response?.data?.message, life: 3000 });
+				});
+		},
+	});
+}
+
+onMounted(() => {
+	load();
+});
+</script>

From 18baed683802929b30d495706223c949fe28df24 Mon Sep 17 00:00:00 2001
From: ildyria <beviguier@gmail.com>
Date: Sun, 22 Mar 2026 15:11:46 +0100
Subject: [PATCH 02/10] WIP

---
 .gitignore                                    |   2 +
 ai-vision-service/README.md                   |   4 +-
 .../app/__pycache__/__init__.cpython-313.pyc  | Bin 206 -> 0 bytes
 .../app/__pycache__/config.cpython-313.pyc    | Bin 2518 -> 0 bytes
 .../app/__pycache__/main.cpython-313.pyc      | Bin 3594 -> 0 bytes
 .../api/__pycache__/__init__.cpython-313.pyc  | Bin 227 -> 0 bytes
 .../__pycache__/dependencies.cpython-313.pyc  | Bin 2007 -> 0 bytes
 .../api/__pycache__/routes.cpython-313.pyc    | Bin 10860 -> 0 bytes
 .../api/__pycache__/schemas.cpython-313.pyc   | Bin 4630 -> 0 bytes
 ai-vision-service/app/api/routes.py           |   8 +-
 .../__pycache__/__init__.cpython-313.pyc      | Bin 227 -> 0 bytes
 .../__pycache__/clusterer.cpython-313.pyc     | Bin 3367 -> 0 bytes
 ai-vision-service/app/config.py               |   7 +-
 .../__pycache__/__init__.cpython-313.pyc      | Bin 226 -> 0 bytes
 .../__pycache__/cropper.cpython-313.pyc       | Bin 4496 -> 0 bytes
 .../__pycache__/detector.cpython-313.pyc      | Bin 6952 -> 0 bytes
 .../__pycache__/__init__.cpython-313.pyc      | Bin 216 -> 0 bytes
 .../__pycache__/sqlite_store.cpython-313.pyc  | Bin 7847 -> 0 bytes
 .../__pycache__/store.cpython-313.pyc         | Bin 2474 -> 0 bytes
 ai-vision-service/app/main.py                 |  10 +
 .../__pycache__/__init__.cpython-313.pyc      | Bin 225 -> 0 bytes
 .../__pycache__/matcher.cpython-313.pyc       | Bin 2765 -> 0 bytes
 .../__pycache__/__init__.cpython-313.pyc      | Bin 220 -> 0 bytes
 .../conftest.cpython-313-pytest-9.0.2.pyc     | Bin 5910 -> 0 bytes
 .../test_api.cpython-313-pytest-9.0.2.pyc     | Bin 18415 -> 0 bytes
 ...st_clustering.cpython-313-pytest-9.0.2.pyc | Bin 11128 -> 0 bytes
 .../test_cropper.cpython-313-pytest-9.0.2.pyc | Bin 10435 -> 0 bytes
 ...est_detection.cpython-313-pytest-9.0.2.pyc | Bin 19853 -> 0 bytes
 ...st_embeddings.cpython-313-pytest-9.0.2.pyc | Bin 15020 -> 0 bytes
 ...test_matching.cpython-313-pytest-9.0.2.pyc | Bin 9622 -> 0 bytes
 ai-vision-service/tests/conftest.py           |   2 -
 ai-vision-service/tests/test_smoke.py         |   3 +-
 .../AiVision/FaceDetectionController.php      |   2 +-
 app/Jobs/DispatchFaceScanJob.php              |  13 +-
 config/features.php                           |   2 +-
 docker-compose.minimal.yaml                   |  35 +++
 docker-compose.yaml                           |  45 ++++
 .../2-how-to/configure-facial-recognition.md  | 230 ++++++++++++++++++
 docs/specs/3-reference/database-schema.md     |  77 +++++-
 .../features/030-ai-vision-service/tasks.md   |  20 +-
 docs/specs/4-architecture/knowledge-map.md    |  45 +++-
 docs/specs/4-architecture/roadmap.md          |   2 +-
 lang/en/left-menu.php                         |   1 +
 lang/en/maintenance.php                       |   3 +
 .../js/components/gallery/PersonCard.vue      |  10 +-
 .../gallery/photoModule/PhotoPanel.vue        |   4 +-
 .../maintenance/MaintenanceBulkScanFaces.vue  |  57 +++++
 .../components/modals/FaceAssignmentModal.vue |  11 +-
 .../js/components/modals/SelfieClaimModal.vue | 136 +++++++++++
 .../js/composables/contextMenus/leftMenu.ts   |   6 +
 resources/js/router/routes.ts                 |  13 +
 .../js/services/face-detection-service.ts     |  11 +-
 resources/js/services/people-service.ts       |  10 +-
 resources/js/views/Maintenance.vue            |   2 +
 resources/js/views/PersonDetail.vue           |  16 +-
 resources/js/views/Profile.vue                |  11 +
 56 files changed, 722 insertions(+), 76 deletions(-)
 delete mode 100644 ai-vision-service/app/__pycache__/__init__.cpython-313.pyc
 delete mode 100644 ai-vision-service/app/__pycache__/config.cpython-313.pyc
 delete mode 100644 ai-vision-service/app/__pycache__/main.cpython-313.pyc
 delete mode 100644 ai-vision-service/app/api/__pycache__/__init__.cpython-313.pyc
 delete mode 100644 ai-vision-service/app/api/__pycache__/dependencies.cpython-313.pyc
 delete mode 100644 ai-vision-service/app/api/__pycache__/routes.cpython-313.pyc
 delete mode 100644 ai-vision-service/app/api/__pycache__/schemas.cpython-313.pyc
 delete mode 100644 ai-vision-service/app/clustering/__pycache__/__init__.cpython-313.pyc
 delete mode 100644 ai-vision-service/app/clustering/__pycache__/clusterer.cpython-313.pyc
 delete mode 100644 ai-vision-service/app/detection/__pycache__/__init__.cpython-313.pyc
 delete mode 100644 ai-vision-service/app/detection/__pycache__/cropper.cpython-313.pyc
 delete mode 100644 ai-vision-service/app/detection/__pycache__/detector.cpython-313.pyc
 delete mode 100644 ai-vision-service/app/embeddings/__pycache__/__init__.cpython-313.pyc
 delete mode 100644 ai-vision-service/app/embeddings/__pycache__/sqlite_store.cpython-313.pyc
 delete mode 100644 ai-vision-service/app/embeddings/__pycache__/store.cpython-313.pyc
 delete mode 100644 ai-vision-service/app/matching/__pycache__/__init__.cpython-313.pyc
 delete mode 100644 ai-vision-service/app/matching/__pycache__/matcher.cpython-313.pyc
 delete mode 100644 ai-vision-service/tests/__pycache__/__init__.cpython-313.pyc
 delete mode 100644 ai-vision-service/tests/__pycache__/conftest.cpython-313-pytest-9.0.2.pyc
 delete mode 100644 ai-vision-service/tests/__pycache__/test_api.cpython-313-pytest-9.0.2.pyc
 delete mode 100644 ai-vision-service/tests/__pycache__/test_clustering.cpython-313-pytest-9.0.2.pyc
 delete mode 100644 ai-vision-service/tests/__pycache__/test_cropper.cpython-313-pytest-9.0.2.pyc
 delete mode 100644 ai-vision-service/tests/__pycache__/test_detection.cpython-313-pytest-9.0.2.pyc
 delete mode 100644 ai-vision-service/tests/__pycache__/test_embeddings.cpython-313-pytest-9.0.2.pyc
 delete mode 100644 ai-vision-service/tests/__pycache__/test_matching.cpython-313-pytest-9.0.2.pyc
 create mode 100644 docs/specs/2-how-to/configure-facial-recognition.md
 create mode 100644 resources/js/components/maintenance/MaintenanceBulkScanFaces.vue
 create mode 100644 resources/js/components/modals/SelfieClaimModal.vue

diff --git a/.gitignore b/.gitignore
index 0089dc9ee36..b0ec9675541 100644
--- a/.gitignore
+++ b/.gitignore
@@ -38,6 +38,8 @@ clover.xml
 .NO_AUTO_COMPOSER_MIGRATE
 storage/bootstrap/cache/*
 storage/image-jobs/*
+**/__pycache__/**
+.coverage
 
 # used by Vite
 public/hot
diff --git a/ai-vision-service/README.md b/ai-vision-service/README.md
index 49fd8899989..b3564531404 100644
--- a/ai-vision-service/README.md
+++ b/ai-vision-service/README.md
@@ -59,8 +59,7 @@ All variables are prefixed `VISION_FACE_`.
 | Variable | Required | Default | Description |
 |----------|----------|---------|-------------|
 | `VISION_FACE_LYCHEE_API_URL` | Yes | — | Lychee base URL for callbacks |
-| `VISION_FACE_API_KEY` | Yes | — | API key expected on inbound requests from Lychee |
-| `VISION_FACE_LYCHEE_API_KEY` | Yes | — | API key sent on outbound callbacks to Lychee |
+| `VISION_FACE_API_KEY` | Yes | — | Shared API key: validated on inbound requests from Lychee, and sent on outbound callbacks to Lychee |
 | `VISION_FACE_MODEL_NAME` | No | `buffalo_l` | InsightFace model pack |
 | `VISION_FACE_DETECTION_THRESHOLD` | No | `0.5` | Confidence filter for detected faces |
 | `VISION_FACE_MATCH_THRESHOLD` | No | `0.5` | Cosine-similarity cutoff for selfie matching |
@@ -108,7 +107,6 @@ docker build -t lychee-ai-vision .
 docker run --rm \
   -e VISION_FACE_LYCHEE_API_URL=http://lychee \
   -e VISION_FACE_API_KEY=changeme \
-  -e VISION_FACE_LYCHEE_API_KEY=changeme \
   -v /path/to/photos:/data/photos:ro \
   -v ai-vision-embeddings:/data/embeddings \
   -p 8000:8000 \
diff --git a/ai-vision-service/app/__pycache__/__init__.cpython-313.pyc b/ai-vision-service/app/__pycache__/__init__.cpython-313.pyc
deleted file mode 100644
index 7e58c5ec2d62a8fb9f3a002aee3755033166cd13..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001

literal 206
zcmey&%ge<81j}ab%Txf;k3k$5V1zP0a{w7r8G;##7}6OvnW`jxDw8u(QxzON6~Z!$
zGxPHlf>VpiGLuvF{4^PFvB$@!<R{0+uVnZP(tpcUKO;XkRX-`SOy4CxximL5ucTN%
zpeR2pH5tf&7^R<>sapm%O1Btdlzw7Cfqr~^W?p7Ve7s&k<t+}I-29Z%oK(9aHlV2>
Vrxk;o^?{j@k?|ITd=U$f0|0w!IHmvq

diff --git a/ai-vision-service/app/__pycache__/config.cpython-313.pyc b/ai-vision-service/app/__pycache__/config.cpython-313.pyc
deleted file mode 100644
index 91cfca1bf2b779ea4991ed6595e6a04e7af5cd18..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001

literal 2518
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
FKLK@y=Bxk!

diff --git a/ai-vision-service/app/__pycache__/main.cpython-313.pyc b/ai-vision-service/app/__pycache__/main.cpython-313.pyc
deleted file mode 100644
index cc96017c9730f1b3c174f763d9027f9cfae20ec3..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001

literal 3594
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
QlV7x>?GIm|5#huC0F17fQ~&?~

diff --git a/ai-vision-service/app/api/__pycache__/__init__.cpython-313.pyc b/ai-vision-service/app/api/__pycache__/__init__.cpython-313.pyc
deleted file mode 100644
index c16a732d677927b9ef2925bda7b305269ad0e8b9..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001

literal 227
zcmXwzK?=e!5JeLe6~Q}ntEkbv2!aTLh~NQ2O$HsYNlDs*-ou3_5HI0Dy7dA=FW?09
z!!Z91%;#6#ZikT`_ZLoRzXSZmf2L}axv?E{?7(}qYkwL0Y`$GZ&gL2TL8KuCqroT)
z6dN6Rb%Z4LqfL*OEh)8CQa)J~0?U;++62TN3$d^&PrzheY@I!UBD22GD~K3}1$wk*
s=)o1J=#r*1D5OM#nUtgSQnsgw)%h7_u1U$EuMb^6b<TOo#;!r|1uJ?$ng9R*

diff --git a/ai-vision-service/app/api/__pycache__/dependencies.cpython-313.pyc b/ai-vision-service/app/api/__pycache__/dependencies.cpython-313.pyc
deleted file mode 100644
index 7472ae6baaab437121080c3a796b8a0c36541640..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001

literal 2007
zcmcIl&2Jk;6rc63z4or-e6~R1qES9dED^g^gHRGwDddC3E+O>>)QU*!&F(na;CPpr
zwcCVC1t(63LnUtXNRLRI`2#p5${}S1QY8dcZ>d5K+<0$ohqOf87<<R_-n^Z8^ZWhY
z__(V}Bhb>{{^<6{3Hc3;P6Hd8bo>MK4~RiHF(e~al8P}Nqd1mJa#7(*G*(LSVuB}%
zDp!k1o-C$#D)PrmT2beEG0oGItSRHsnuJ(sf-59SUBwK~M3HK#yV%2fAW9u3M$$+b
z+Ei>UF-+FdZ%M7!CS$LY&d2CB^g*(vY)QP==rPhb=6y!5(G`vQH!``t-JcdM5zMYE
zQHS}g?y$POLw)WwU59az*R(lS54crx1ryX~e1fx28%zXe!#NXPtr56hJx}RutwyVj
zx{aowRj*d_?rQBl-Vn4>nUD4n<GD(O+8!=$2UK`8*kn7@w(4}9QLo83cOA%vx^)`B
zeu6e#ORH2Y-_QS(so4%>qEg9g&k%x~6zW#J?gdtq0hnE@cUBh6xf=^}rKRQfa!RPS
zQwS3`m<7iSyKbzmt}NWMnUC*;YPogBTrAXQecxa~;MO-pnBHK4DcTk+oL;nSHqQcP
z2ObAIv#`C+90y_zaIpMt>h=U6J5gdgFdGLDEn&yn^x_Zd=L^)&br_5g3L3gCm2u{!
zHhmZL06P3w?o6Q040$TXqz&b5xhm!2yWgL~WUy%kv<W*q7NCe20|Td70RtU6HzOo~
z@3MtdPiqv~3$Tn&Ub&i^rc2dml~z1;1>JUqfFo0nQ^$in0D8J@1@>mN1TIsle6(aN
zeXwjU&dx2EfQVUIxPyebUxR9Q2bbzmhPXm!F%;w{02?qMfXRk1ZO>t0!eN2s)|SDq
zTE1&S2v-3Tuv7QUwkJ$>I1&gprQ!R9O>dhO*4<`d-m@FqAZbxp;ocT7Cki)r>`lfB
zmOIgO1@J#17;m~Zczhoow{WUAmx;W;6LuqLE@zz$`32YpA8{GFXXHLP8X(Eu!-3KL
zfzbnX^q0)gck<rk%6{h7Uh>wFOp;@N2?atwAG##j?ZO2UlmHJ<EFHfKg9qe8a-JB<
zXC;JhK`Y~OFSSvqh25z#3mP112$-L?YnBkxm9w&~P=Q)?u+Cc5g?KYyCntw8AP~kQ
zN0<cYBcVT%Lba_Lf%#HC0DY@CIx##8t`T^|tI*viPxQX8X1<&`)U*3~_D~<&*T?ph
zv16Dc|MU50&N=^!W%^$T@K+#1j%Pp^04F{O<Fm(3MR!6pMPUjr@AJ<*ysr=MDZ~5{
zL@ehLybpduSp=N-!-%KQOz?=TP+9isET`}xoJnFgjGYeMzrFA`L2?73YMPE`n`Wq)
zX0-vFGt=aFU4)5X$A<#tD3MUD!gUX#=6Lt;1a??J(JrBew=3MqRd*vwh~r;hcoDrV
zX7P$Y<rvcm2XK;g?mdxjp@ca_RS^k+Q!pQq=;$r6B;VQgoJNgZ=WoIksz@;Cj$}!a
zp2y;na*`p^$nS(cB{K(P<|(=Ihurh4at*%EljLIdo4JRd?O(X|b9Ut6&4cXKqqr`W
jrN`ZUM=}ncWL|4|juIrHov7&hGaHjGpJ*{@Bue9NifRY<

diff --git a/ai-vision-service/app/api/__pycache__/routes.cpython-313.pyc b/ai-vision-service/app/api/__pycache__/routes.cpython-313.pyc
deleted file mode 100644
index f193be44a893fe7d4e4c9a6e9cd93613a1a3c7d9..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001

literal 10860
zcmcIqYj9h~b>54MH$VU)_$EMI@g;#GL5X@&mSmIEg9Ig71q4YB6+<9!NnQ!OK=uN(
z$Z2cF$xP__N2NBY?4+%gPNtEke?09>>*Pnrmh*6wWD1CCz}(2GI?*KKPJd9AT*paf
z+H>~e0u;n_+#g*Dd(ZCO$JxER-+t#TAJ){^3537<>wlK`c0zuE2|buJfqQt~K*(1}
zgisRUB8G7;WS|BCWqzEeJbN0ckv&b+1W)6*Ib@+0R>m}L4cVxzRNhYQ@ZLP`2sx=U
zR6}b*F6s)osXOGMp3o+`iIuaA*M_{*8>*vqp?X@+@~q<xp+?#mYNAb{X4)KTp)H|S
z+8XjvU&v4Wp*GqU+DtdIvbJ#{w1sX7wbOQ%wvTs&I%%gs&fB(?Mi;LmI0DCbSE!qI
zvr^9St)XpnTPQ#SEL}6+6WUI<LoH+YoIWX)XFECHw};cxG<e?GPWF^u(*E=P;drH_
zE=61scf>PjIPZeG?Rs67s@GGy4Q*tjf03rhrWSJ1c#$jjvh(-!QmeQ1f9)sI9Pw85
zF#vtc==xWlkvhGPNK2$1>y)+Hy^;2MUZgeBfTii4h%eH}q`fnIz`ywGV{s)rbZShX
z>0DM6X5(@)B~m45w;z?0nY1Kll>>G`IQ4Agw9uavvtlAE2tuDQlt_q~tPmHb;|Z}(
zdm*J|;bMB~DS_r>A+9XQiC!TQPo<{fiAzE@Eu2_L%!*>L+}vC|o0x^x);Fh!scA`s
zCd6!x%1|rQHz6p}oRo@FLCL16m}FgohJtYX=xIUdpB3Y&EVk1pgtc0VNav*lj7EC{
zV-m!<DKVLp<QXB6&dJ%J{R5oT0H-?QvYgJwv!J{(0cqo@cy<<^HK(6Dbu>0IdURxb
zY~pyptlD6f!Z=A(bq~XcW?;tT<mtF_Nl`6F#Ed8>6}4vc^yyPaFXP-mgQ_Jgel8~}
zS=AoRq|))^F)1Ymc-1*0W@Fl%rKxJe6dRiArchp@Vl1AKVwc2)fK9DG!X|yBG>@m^
z3)qm_@OXAuR5CCCQLWMP^?vJ)QktgKmF>siqd}EiDyzCi*(6mOIEi1SoOI|(EbEEn
zW@cbGFf^@pz@R#YGMR{&&BD|w+Q5`j3MX+!ltmiPim?PuXCT9R^s<=9!Dob;PEA!Y
ziQ1@6jI|ti%c-uT`WK7fS6{T0R^JD=O5aU^kCszniF8s-ln|5c6C1=|AcT8J06ja1
z00=r+LJLBoBn-LLLEls1_3e}j>HAAIt!sr3o2%O(<Wsd`o<#jvh?>eZ9C}{mxvrd9
zFBjqZpn#sz5jE*1<lLD9FAx%kGi9<yZzE!e@DbynLFA&QFqEkd`pC-dRM$3XwI?^}
zHKPW-Z`m^G-5}Q*HG~1*t3$Y<I){*O)026!Ey{&kpUj{1>3Q(|+H|?{jGCgBs5NSf
z@_Q^=u0UqY`}k=tU|Ia_{{mG2b7$fyDG4i75wf$QkeN*bP-OrDgl!o2WodjK@Gzbd
zGBl0o2Wvmji)Cd&nwt}o64XsC*fqRTgr1&(9RnqF6q7wY0)meMxR=bOppPWm%+Lnl
zBY-C&qlP0w7JwvZ*R~bBq9VgwK)c7$bE^W-h#OZC0B{&U3uzg!uH3Rck)F$>pdWxp
zmFt(Tz~W!r&IT4^1Cta1U`&ycA{#OQOZo-qCkeQdfUUOhhJgw&i>eu#j7zD-o^^GT
zX&40Hr669Gl&p}Z0<?x{I0yjSCITL6#JcuM9n}H~r&IHy>R_1)(?aEyELH8WiD_1O
zLCVfj+!v}vQexN;bwY~bQdaqRCZn2gw~MM(EWw9rjVF^aoHMmH2FFbaO<`hVa001T
zt$QgMu&c(YbaFxURHm9$1I$LOMQpa}fTeOV)ml<ES=N@O(@;j6UO;Qm1mK9`MpR(K
z5In!MpdRm^P0xw_Q__6@k#r(AC&J;`e~P9r!n`W|+UeIHm-^-<1r+Tool^ZUKKM!f
z>;zVVnFTiUP=`JR?eD^lege@4WQja#Bc8e|N3K14_1P77XVKkTaQCjbgG-}#Ya6ay
zE;ep2G;Uw1?Jd^sF4XQ`solFYe&69*zWmCeqNAhW==jFS4aZ97?l+Y}=YgW*se<FF
zx2-GBoW1L6y}{>q#|y5hymjiH!&`K;796cbhri(PmtI~dxZ-(h{JuYMW9y240DAOw
zU7uO;1(%MlHVdz}zSdf7?kP0)6q|Pyns+UY-ZRz}jsAksf7jZwYIXi;&C4~bRuB7M
z5<YTUP3BJ&1k#sA4vrk=7R~*P5hQR0=>d_Eq4|HpGS<)>FrbX*dNDx7k~jwJa+W7#
zp8E<vVR91LI0-2&M7c74nI_9vzb@Ad__G1Bhpl=Gm1h_~epLWe#C6L;*riLAXN9TC
z)~GdH#??xRbGdMBC8bMI<DSwOo*11iT4vTs#P52&&N}qBMNBwY*&a2A8};{<XVktC
z76X#ERLba5#2m2<^0H&nujfP^UUJ5HrbglWiDK}QQ5bg)&e+V4CpYV5&iy!I9W<OW
zob(XlAOcZ%xkh$IY=c}Uv66`u_)RMYJ%5@o<hC#VH{%{cT+m3N5TA)lGN8^n8d%|V
zNLe+cM_`=;gp@LXEdbK-8BxeF`qf)PNe%0fx%O%eD1wyjWl&whaXTIciBwtvfDqWK
z1l*gZ={W|O6*9?G5#m$nc@0bxX?a?j$stPxNE4OWbSepoX}lCqhus4Ma41OA0Gf=)
zB7SPv0#zg+ywI;U+@O6z`dh^A?uk;->T=qkupW+)cEEH~WH%q+(tLwcO)22b**6TT
zE5(?13`ZQ3k}4b#pk`8pa|4)`r8K^PM>SG0o~&Rm-HuK6VuX07S{SL9(y9k3E5NP{
ztS^>Ir!&A@0fZ$vRt9LNrfqC$0Zt+f+&7hYyp&ytDPo)^W>s5xDpfaABUYX^ic6Uy
za|pOpBRdoj3+Zl*aJQ=tHttdn`!RbEBc`g6X=S7F7ucv3I0oQT(h;m@(dWU4^Pu2H
z)iGRq(gRq`#1x_tkYn&ueg+YO@S2Y_`(L-cX8W3>Sla;*`)M)pzM~d!__m{C#nH8N
zWVI()>^WTMIsDe;;@I<rvFGy_F0J&Wik+#Yv0pmsO1OKz;QDOd`q_Jqx+{P1@<FKO
z@)liP1y|Sg<TvH7%WuvW_f8b{PUO#=%e%VruIHAH-*+?>Qp%kz+1n|lFgcr_ochN0
zx6a;aKLfe9w`2>BT;7;_u$g!}AGk=@9QVmX4{6VFpC~w|FV&6g=Kg{k=`mg#3W9jk
z#EtYCZ<>c}ka*W!KN7UR+i5|$m%}({h8VcHW@#nX<1*st7m$bl7YJqK2Dv(H#K^<z
z&wx?|nFHjnt_<l7>u-SKvSA&k<~G7_oe9Tb7e%;d!RG?!!3H=F*of4mD&YKKi134a
zr-ot1#hV+Nq`kr%m@TP3H05CbYNm_^K;;dg8>;rxvw#t0vIjC4<v=ZfLI8DJ5OQ)n
zhjcV6C4eG9V`%`9cvir+`=;WlIP7u?m?$Uhz)CKOR5y!(lqN1IV4=&%ZKp)QKmnN;
zkV7afpi=-$P#}?p^d%%fGZd8t^VO{Bt2)^rVE<#j>Mm;zHW`@M0n0l0sO(NO4^$h_
zyizrjR+y)3bC=60Jd}gosBJ~Fw!Y|j$owMwl+QxM_M(flb-h0M+GNomEck;(|Gt8M
z-_q!+ujBRc*T##!zJjl>=-XBB?OHl|-_g9<xVhLEfd4ONZ!E6X`-}Bk3-w!9oBXdk
zUUPh{=7GiNG_Mh3nU@Uh8ye&i>(`POI%ccd1-aU)ZX=VBsfCT!;<{7c3@31zcj$G%
zdK=z|bpS8HNr3Rgsc(r|B52iZz)Orow)7L=7Zxu$&W*x4m2Hz{`|{KBlQK_2&ai>T
zQR5_><ywexQQL;B#kP?x2xT|01|fF?dr-ILo*2I)%5P*RLMvrUQP&P^e$z%aBl06)
zGS0~@dddH<Q9!%xdLNZ%)E;$2oxq)H&bXf7PCuXQ(o3HEIa=Y5aVM8t6EO{1WjAoh
zt$Ml2^V}O7&VqY4uYXkmR))^SCIfoSD2ZA@ACF=vF*#UWvM1_^m~jDs27rW&y%}T=
zut0;n31+rOuU&b%NW{9!AlFVJabO`F)TPR^vMV?;##M24Z`2#!St+Ya(c0*yFycg2
zC?l^8G(vt*6?SkDd&Dtld}1BdMeD-*stQ9=Z%-hT2uLi1krPyfb^`SeRb@g_udmOy
zTn`>^__qhy8H6#z<Kq>ynQu7Lc&14)?$CHN%ytg;zuX`<%1zORXk*N9608gS0&+9t
zHONh8>%)h&7T3qX!JmeDEz#!i(E5B$j<$q{pUf?5+8Aw2fR-maVBhfJqfeHE`o}iN
zZPdpmkdx3WYB|GM$#KKPIf%K5pOyGMtleoCA8>tGMbpUse+|Fy!S9P(NUt_CaQ17~
zo0T|;ekLb5LZ+eKW@uR;6R#cOH<M|OwPci=a6YEV7BV@i>t-SG9dLq>$&j8CKB-HU
zXT%vL70oA~)!#%(q$c754_%3eu$A+eUZ}|oH%&A>n8o6bn?T7Unv)zkrqU}+<)jqa
z0$@$(p74z3!qtv@@SRB03uV{1J)D#Au+M@s2F`YL5|v!()xIJjJ`JvD*7Ai5CEw_U
z3uQOHQu0UvApnO|P!NVvDPiPPv~LQ%*1`*EdI?RB^z?LzgMi!X!UdhZLqqdY+<xIg
z6|0AQMlVD`oChU=W27_SkD5cf4E<8*gO=vO#XmuDTTon`^cjc(R+YP~ato^I1u2=G
zRpCIFW@fV#m!j&dFb6PBjOZ#>9ZK2NtbBmmCSaiOJ%N?8iT#bAxlHB<`j3^}#z2Vr
zK?n4W{l<2#5BN*pxVTWdL^=G-8@y_~sGw6G$V3t-k!s0Gb0V;v#e>>6g9h;a0_-yI
zK*2Qwc(-&v(xEQpDX`0Ac7q_IPrdv-RTuIx3S=zCUMx0OTFXcoF(t`jsmZ`LiaUzp
z2BOC?LJyDXor_=Atdv+rq%qbf#dWV5b2*q16UMtKn&b3&jL;mR7ch!rG=>o_b2^R@
zQWQ3^6pek=4E`lhoT3M~YzgB1LXM_X(`+`IxeQKxysa5YN$^osV<wF^78<!r=H@bw
z)dEVWdT3ly#28Ev+*_a*o+24gU0Rj-l1G(ZL`A0Y4G;DronjLB?dT9nw#qe$IhBTc
z1-J<j%Qq)=U?Iv$ZAN4I)(Ny~Yrw7<e(24lWyZ+tKFvCuz>aY*t2Sopfqyp+p1qPS
zsG7yO44T1KTxqeXy}N0WsRkx7MFT@MYs*MAOea-KX}hXUT?;mG=7cs`=r1hYyp-Q#
zmdcCJ13xb&G+Wgvfx9vtgEY7g(d5o#@W!MSx&xN``vPOXv>ytw=&K+o--g|wnW0ac
zrn$TBhN64xZTHp{cVOALW+wf+ioxMRaQN;0{}TH_EdTuMN>D0pla_6(b^d(Y!Rywd
zaIhd8%-0=Swn6b{xM6PDcE4%M^61_AroXIvz2&PdU-PZhcP}5i*WO)h-&<(kyXtAW
z>+!F8T0ppFziMCia9wp_%6--S&~5E-eN3!=*YfCE9cdMcEjtS>JKx+^95_-KIP&&v
z@!0c)W6$TOXY(yP^DWZy`2G6LtF<lHdam~9kA}8u@>Ll~`n4CYzPQ@jQEUwsT7#?p
z4xs8kO{VYoGPjfI!r2S?v!A)+?|Un9#~&^v)3<$@2b*jSuH|FUZ%sqd=_@#WuTB@c
z_ZPbNztx@h4;7um4|b8}_DB1PcN@0V(YsRH_cw#DhOZ1<iGO*|*9Qx=eGg2$*S>67
zvl8f->7H*M$PYZ5Z#=c^yzgx)dOL4>JB!}#JKpXa-Jlej9jhMSYQ0Z0BUb7ItIeI)
zXN%p33f+hDO@~*Td}}t+7FZ*uHkcYy6Hbkj)YKQ9T?J>?9p~1&zJa1|=(ca@?QP%h
zd#CT+{uN(%`Q*o&NZnTG=s^QH$(`Z;wg1emv2RVj6?wbk?a#f*zZv;^>kr13owxhX
ztTuKQ8+-0F_ADP?t!*pTwijyKukR~%>??HaTdCc@JhJMpedWbfPyIF9Rokmui!D0}
zEj!-q_=#ulhZfSb{X>Z(fs5RSweZnCdAN=EKgWIYp^JEf53HcT0|O}hF|Vlt+T^|6
zzkAd`cAVvY{m4n2^>Dw2>(A;cTAK>irhN0+{B!X;)~UO$_UrreeTVW-e<puEx#ALw
zR&m8Du9>j-@07c+hF{`Nn7A+Q9=DRWxRA&At)Ztuyt$tXdCfNmhk7CLov!*&L(6v#
z41oOIUU$f6|L#+LAb)Qg7usU}UVulrcSmR||9u}9>M(!bzaQlH>K%~(p1_5=jPGr+
zqr837IA?wDU_Zz|=ocWq<;Ko$c{r54EN*b3+`&N$x4Kx)R&(gE<yIdT+TpwvbfSE~
z1!aC{-Fd>m|8S5SKWP5p0Taqk8=$oxaU94$GVmZj=Dh|6tyznB38Ptym0QGfToia9
z*dRt=T6n}&1>n&J;L#?qFH0;0d>vqQR);Dk%|GV-MvJq2<5;N)H)h6g*($8$>&!KR
zI+cCdmG{7;O%XF=(vS56f49NoKb=bf!>xKh!vn_~gI^>3Y$dM8&pyVfHs*RWyvDJB
z-Jz?F1z>m0jNReE!$KI3y{ZtgtY>$?*Z9Zynssr<FgOMK#A!ImvfAG`q^FT_J$}Nk
z``d*8Upj$U33mAmU@j^OI$)7%Owd_~OQfUo87e_)vG171D1c+(saD;5710RTDc%84
zijjg*7NZ<S^BBQRFQI>k(H~*-#}I+D1=$h(GmQQmBjzSuM(JgY{sbb$0#WIx(N2~Z
z@fAk@fv>*>5uPmfUF|nU^HFp?E*)QOXe&1K6&m{T^}&2_JnucRbYjh5Go9w{K7om~
zP1m+x-To;s(c1=?=tWGdae-7*#+loIdWLmr4R?O~$i)DM!(J<ZGy2}PpI9SnJZAq+
zc?Gn8sb$2>{Z;d@K>m>%Cgy+QLHhQNVKe_u4>xQuzq8$la=!zz-#Ney8;$QgWkmUD
z4(i<`9LP5f9F)0fWU|>j?6=%>a>H)t%^D}l&Di8kA1m)?vLKA`{JX>eExc>sQ094%
z15Sz-EX7M6I)D+*zUJk!qr^TCIz2RkV4O(HA~FyByBGRp$cJ@s0$<}c{k`>AN%|Em
zQjc|v>q@fRI?Q!xs{{8JUBU<fMWarBl$hVV4JCA*Q)DIU^keOmG-9iawZoPglh}G=
zQe{k)I{Q>hES5|sVlmYoi%sWXd}1s{dF%t(uxdf}2V{t*SqfQQN}AH{k<Hl!<Vh4g
z5Nt1?^By>7Mxuy>+MHTZLXe|uVsXCIIv`j<C>Bhzzs!NF4hgOy5YgDJGDRd&-FhLs
zpr4B?j3YBHt9`awERMKBaTY5V5*o3#V{PrihqCVoh(y$S%+>Bbz@7*q#RO8%$h%q#
zr4u<yfn^7^iBQ;Fs|}A=(yFH^MQ;|xFQkp9Y$qu}?G_q88T<R86B>cG#$s}O4yPB9
z0ag?HdnFAz(9~d;8FUe)^B6H^iTnQz@(^O8d0VXqfyl$3D;%abAP-J1qWlBIu+cc~
zfx*lfKk^W+;}^vBGyLy(pESKsgkKQnzmdrznfw(QE0D2|4R+4(F@fkKj6QB4+|Kt&
z|1WvZ`^N3RG7i0O+;z|9DcV|Y+ge`TzhdiLGXJ}+_LbHp^O}bktY2#VeCzUa*GHCG
z^W3%vcH-~6eqzP9^QW%*E9n(i_nM=FGq2hk*LZl|Yv@`t!4uf5tA5Rbl9jky)@&%*
ziPgzU1MxE3AJstKL!KA{YX*FKhSU2xx5705?Wyj^=HuqMReRkUkHWp0x-}CD&=quG
zVWJg#VCA4Qv-gn$bFq)cH3KU!$~tNJe9Q6}bn?(pqp1L|L0aoM$#K)%s%z64&!l@E
v=z~evN$Z+Llfe}NBhq9$aW}3xG}(!Y)M&B`N9bnqM;D;+(;WRKe7yewHGkQn

diff --git a/ai-vision-service/app/api/__pycache__/schemas.cpython-313.pyc b/ai-vision-service/app/api/__pycache__/schemas.cpython-313.pyc
deleted file mode 100644
index baa99be87bda084221c02f7eb470e06c70333533..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001

literal 4630
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
H{?7jbPvT7P

diff --git a/ai-vision-service/app/api/routes.py b/ai-vision-service/app/api/routes.py
index 01fa6c43bee..d3c16435f6e 100644
--- a/ai-vision-service/app/api/routes.py
+++ b/ai-vision-service/app/api/routes.py
@@ -63,11 +63,11 @@ async def detect(
     Results are POSTed back to Lychee's results endpoint once detection
     completes.
     """
-    resolved = Path(body.photo_path).resolve()
+    resolved = Path(settings.photos_path.removesuffix("/") + "/" + body.photo_path.removeprefix("/")).resolve()
     photos_root = Path(settings.photos_path).resolve()
 
     if not str(resolved).startswith(str(photos_root) + "/") and resolved != photos_root:
-        raise HTTPException(status_code=400, detail="photo_path is outside the allowed directory")
+        raise HTTPException(status_code=400, detail=f"photo_path {resolved} is outside the allowed directory")
 
     if not resolved.is_file():
         raise HTTPException(status_code=400, detail="photo_path does not exist or is not a file")
@@ -213,7 +213,7 @@ async def _run_detection_job(
             response = await client.post(
                 callback_url,
                 json=payload.model_dump(),
-                headers={"X-API-Key": settings.lychee_api_key},
+                headers={"X-API-Key": settings.api_key},
                 timeout=30.0,
             )
             response.raise_for_status()
@@ -240,7 +240,7 @@ async def _send_error_callback(photo_id: str, error_code: str, message: str, set
             await client.post(
                 callback_url,
                 json=payload.model_dump(),
-                headers={"X-API-Key": settings.lychee_api_key},
+                headers={"X-API-Key": settings.api_key},
                 timeout=10.0,
             )
     except Exception:
diff --git a/ai-vision-service/app/clustering/__pycache__/__init__.cpython-313.pyc b/ai-vision-service/app/clustering/__pycache__/__init__.cpython-313.pyc
deleted file mode 100644
index e573e9c3c6b49ea3c42bfc9bbbf28e694d952245..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001

literal 227
zcmey&%ge<81j}dc%hUqWk3k$5V1zP0a{w7r8G;##7}6OvnW~iC5|dLEQgf41Q&KYX
z(iM_(N{dTUi$F{b7pGunM?XzHKTXD4?D6p_`N{F|D;Yk6Ou7}IpOK%Ns-KiurtgxU
zT$-DjS5mAWP?VpQnha$4R3>Mnrs^kV>Xu~|XXfYW7N-`KWhMhf3JUZQR_MpaXXa&=
p#K-FuRNmsS$<0qG%}KQ@Vgp(La&Ixntsj^f85wUeXcn;mIRN4QKwJO-

diff --git a/ai-vision-service/app/clustering/__pycache__/clusterer.cpython-313.pyc b/ai-vision-service/app/clustering/__pycache__/clusterer.cpython-313.pyc
deleted file mode 100644
index e30b78c545adbc961dede35b17ee2e9ce7a84f77..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001

literal 3367
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
JMPQ0<{}-G<wpaiF

diff --git a/ai-vision-service/app/config.py b/ai-vision-service/app/config.py
index 620754f90b5..e32d55d48ec 100644
--- a/ai-vision-service/app/config.py
+++ b/ai-vision-service/app/config.py
@@ -20,10 +20,9 @@ class AppSettings(BaseSettings):
     """Lychee instance base URL for callbacks (e.g. ``http://lychee``). No trailing slash."""
 
     api_key: str
-    """API key this service validates on *inbound* requests from Lychee (``X-API-Key`` header)."""
-
-    lychee_api_key: str
-    """API key sent as ``X-API-Key`` on *outbound* callbacks to Lychee."""
+    """Shared API key used in both directions: validated on *inbound* requests from Lychee
+    (``X-API-Key`` header) and sent as ``X-API-Key`` on *outbound* callbacks to Lychee.
+    Must match ``AI_VISION_FACE_API_KEY`` in the Lychee ``.env``."""
 
     # --- Model ---
     model_name: str = "buffalo_l"
diff --git a/ai-vision-service/app/detection/__pycache__/__init__.cpython-313.pyc b/ai-vision-service/app/detection/__pycache__/__init__.cpython-313.pyc
deleted file mode 100644
index 134e2a6a5a6e3a6bf368f657000a766adf339e20..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001

literal 226
zcmX|*K?=e!6hsphEkf@Qa8;qr1;mxO5*0i^sOhJT*rX(Bq29xV7ZALJ2kF)e2)%#_
zsI&Pqvv_~{Fq|T%`|T;_?!J8Z34cu=ICDh@q*0Ee!DY5iIgku2a4VD~smuu1sv<c^
z(5df|ZG^iCW0~TNJy7pS-HsNj1bP$=T`69dAg!T$txk?(=%(cb08K^Q2;&g30o@4h
onyRAzXOuA^g=H+M+Adg>Dyz@1)MLl@bB&++9%76;6zP!*A1eJo@Bjb+

diff --git a/ai-vision-service/app/detection/__pycache__/cropper.cpython-313.pyc b/ai-vision-service/app/detection/__pycache__/cropper.cpython-313.pyc
deleted file mode 100644
index 720dfb422aee4d35050f816167c0d5e8dca2346a..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001

literal 4496
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

diff --git a/ai-vision-service/app/detection/__pycache__/detector.cpython-313.pyc b/ai-vision-service/app/detection/__pycache__/detector.cpython-313.pyc
deleted file mode 100644
index 5ede44a9fc2549e0d77369f4a73882713f9ee28e..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001

literal 6952
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
BkedJi

diff --git a/ai-vision-service/app/embeddings/__pycache__/__init__.cpython-313.pyc b/ai-vision-service/app/embeddings/__pycache__/__init__.cpython-313.pyc
deleted file mode 100644
index 8f53ab5196bd682c31c227417c93d2386ee3c0d6..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001

literal 216
zcmey&%ge<81j}dc%ajMwk3k$5V1zP0a{w7r8G;##7}6OvnW`jQbCXh2QZn<>6^cvp
zixSgQ6><_QQ;YQcG#PKP$H%ASC&$OHWcUoyek(vfBR@A)KPj_J-z7h}G&eP`q*y<o
zC_gJT8OZRdOwLG6)lbaSEz2y<%+J#;PAw|SOa_V+6zHeItSQ!ykI&4@EQycTE2zB1
iVUwGmQks)$SHuRi0OZJGkOMz3Gcq#XVvs9h0dfFz**!D>

diff --git a/ai-vision-service/app/embeddings/__pycache__/sqlite_store.cpython-313.pyc b/ai-vision-service/app/embeddings/__pycache__/sqlite_store.cpython-313.pyc
deleted file mode 100644
index d5552f4bcb23979d6657c319362432acbdcece38..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001

literal 7847
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

diff --git a/ai-vision-service/app/embeddings/__pycache__/store.cpython-313.pyc b/ai-vision-service/app/embeddings/__pycache__/store.cpython-313.pyc
deleted file mode 100644
index c6820411d36dbf4f7b948796042fd3efb5629bd6..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001

literal 2474
zcmbVNJCEB&5MD~8PU7j#kMk=|a@oWwPQZz>4Y)ZZ0SufC_;qp26aj35qR5p*n<C}e
z<;A+nX<Vmqm0yrPb$&s90V@M3f@=a9vJoIvW|oxh5vK_SELXd;voqiK&2YA|Vl#Yx
z`{~zcWr?xh>CgPB6%%8&jgwc*Wx!m+t=utgSD?aaUcFPjZGw5*0*kXp)&=$%bIps)
zwH}$*s>SJRr8lSzYOSTcU#|D00zXjv#;7O4FiHllN<r{3q$&;4*s<;Fam>YhmrLCC
z2ZHzf;HgML$w!$~JV=v%3L~yku7;81QKAI&{XlR@E55=(*#3ANM}e=RG{F<0;My`2
zV{{}E#nV2Sk+T4V!n5UFA{j&pt`Acw635=B99l-c>?cX8v^&|V<n{Yy%=szE5*3Yv
z7Ys%4)bGV2DAU%j5(;DXE&hGQ9x*Tw%!+G3)vbW(Hr(n(_QV9swFy3))z+E2yv`2)
z+@@>M-V+0s+!eQ`?dt9lGzRt7YQB0D&;2G|wfDn3LXKc@4bOiAi^$&^jbkxFWQrUM
zsCxoI0^x^k>GuWyekc%3KaNGn`;d+_dKm!W3F28Mq_T&862=0gV+UpK8V3VM{BO)m
zjl;lbRrdb8k9H9<>L&-JZ}O*Ng8q9G9x2K1P7qhYZxX$?wkgiOHcu2xbY|UdtW7*h
z(Tl=vm-{h=JmKOwI+vU1hsXypj?p9}mBB!6*&LsvXScYkh{5@--7ekhXr~*fT~sW;
zf2ZZ>qYE^*__Zrn+aYQok*GF5=GP(60r%q+)wnAH)RtrK{LEU_+>|2j=c`9A&KnDF
zl2F6Q@_U_OIue~;wA<NEgN&$=9VGP$x|5v(myRE`cO$yBEd}gGf#{&_I|t4>Bx~V}
zCwbKm!~FD(d2Q*+b8zhpUMI2q*$Xy3%^J-aPFYZ)v3%Y~-OC4Jl<tZn%n@ZpScmA^
zN!#g|M@6yS+9o2fj*z)5`M*qH-GjazAq8q-tqLsT3rP2pBIg`d@s-y?5o2xVXOE>_
zEPq1gW#%U_b2x<y0qJx8yeD)2Auc`;DuYD#k5P*HmC-1Qeb7CGN&`iM`adMI1tDAf
zn@pf`7Yhq@AmzH&<S>oHEq*UbqESW_Cb1p0%Nrs!;WD6}xpCRK+`i&mF2xvQ1PV|2
z&-JM!L!N<p90-}kSVtN(iW=i8!Y?b}E)^gecDox#HMu!Y3omV9RjCXcgyboN0(5=q
zDhP!Pu%l9C9FNiAUneo9ilrLiLBB_W>2|51=p?&c?ZL-vq9lm3kZQAJ)GQcXK_>FX
z;zVxgJSA~Ncoi(4I=I-A!iQj(AN#^M|FUSIhdKA3FSsYZ=g)h%-)kQtUg6gu<_AFQ
zLJJRwl}?$8p;M9MuMF4<Q2i=Db4-<b^-DC977j1i>-w^mq}KROtETmxSFsNP;qv!#
zjMP2UJ?3#<!;cuUo0~gnB3h=lg^$q;NanzCXc_yuTI%{Ztke2A9CAzhfb%r3;@4Ck
z**mY@Yt|p)otwP4=`mKDc6o_h+Iijc5+6T*UT%BdC=Iii=1tFgmickHbHelb5l9uI
zl#>*<mpm^_1J8pK6vP@07ijnphy1MPN%{%}p07|ky-W#-rWAXD2h}!E;p#zG{Z0J$
zlD#oatNymxu$phr)vf0ABX;h>v~k*MzFu3OTKJyU*qINeOEjyqlWTf!YBT%Ocgwi;
z*G9!Ex`1}P(^`TJ^h=5LGej2?1M1FsO-;tAcpx1DkyS)<G{U_8MFGcGu!$zbzii_$
ptr~{$reYfAyCyR({lOfJs<QUBa@A=5_}z@*YgWaDH?*J={s%t_yzBq~

diff --git a/ai-vision-service/app/main.py b/ai-vision-service/app/main.py
index a7fe018322e..826b553ddb7 100644
--- a/ai-vision-service/app/main.py
+++ b/ai-vision-service/app/main.py
@@ -9,7 +9,17 @@
 from __future__ import annotations
 
 import logging
+import warnings
 from concurrent.futures import ThreadPoolExecutor
+
+# insightface uses the deprecated SimilarityTransform.estimate() API from scikit-image >=0.26.
+# Suppress until insightface ships a fix upstream.
+warnings.filterwarnings(
+    "ignore",
+    message=r"`estimate` is deprecated",
+    category=FutureWarning,
+    module=r"skimage",
+)
 from contextlib import asynccontextmanager
 from typing import TYPE_CHECKING, Any
 
diff --git a/ai-vision-service/app/matching/__pycache__/__init__.cpython-313.pyc b/ai-vision-service/app/matching/__pycache__/__init__.cpython-313.pyc
deleted file mode 100644
index ffef9c733972887968066e9a5375c401572de1b2..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001

literal 225
zcmXwzK?=e!5JeLeEkf@gxT+9y0deJ0ir@i4jiViDnv$f2dJh+#K)i$p$<_-9y?`m`
z-^}~7c>FGorzGTYf8iqBcVGUYKj@+WH?k*&oM|$+&i7E95SY{Klu4LbR9IvNT{}~m
zlR1{>Wtvbw5#p$&5Kq$eCZF<LE8qug_(scGLFp{t8GQj6VB5+ZfM>`Ww5UsF!89nt
or>gkh%Z0!aoe;~a_0dY{V_m@7jDx;kYx||2A*Ixl#Ee4u0s)giu>b%7

diff --git a/ai-vision-service/app/matching/__pycache__/matcher.cpython-313.pyc b/ai-vision-service/app/matching/__pycache__/matcher.cpython-313.pyc
deleted file mode 100644
index dea4a3c1b638bc748424976f98ad96f97b16b65e..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001

literal 2765
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
LMf;mTCoTO8;9K%@

diff --git a/ai-vision-service/tests/__pycache__/__init__.cpython-313.pyc b/ai-vision-service/tests/__pycache__/__init__.cpython-313.pyc
deleted file mode 100644
index 182e17f3cd8d2653920600f20c61b0ac9296d48a..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001

literal 220
zcmey&%ge<81j}dc%hUnVk3k$5V1zP0a{w7r8G;##7}6OvnW|JnQj1Fzic2#~QWetj
zixf&SQWYFM6~Z!$GxPHlf>VpiGLuvF{4^PFvB$@!<R{0+uVnZPGV7MRenx(7s(w;t
znZ8SYa%paAUP-ZjKv8~HYBG@FQ<<ERnyR0esapm%O1Btdlzs`&zGD6O_{_Y_lK6PN
mg34PQHo5sJr8%i~MQlKGK@KejIr0NDBO~K22JIpiAO`?5nm!i*

diff --git a/ai-vision-service/tests/__pycache__/conftest.cpython-313-pytest-9.0.2.pyc b/ai-vision-service/tests/__pycache__/conftest.cpython-313-pytest-9.0.2.pyc
deleted file mode 100644
index aac19d4e5e771ab837f848cda9861ff0ee56f50c..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001

literal 5910
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

diff --git a/ai-vision-service/tests/__pycache__/test_api.cpython-313-pytest-9.0.2.pyc b/ai-vision-service/tests/__pycache__/test_api.cpython-313-pytest-9.0.2.pyc
deleted file mode 100644
index e75d20f9d72a97f246499f67a9e09f37ec75d32e..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001

literal 18415
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
F{|AVEL>>SD

diff --git a/ai-vision-service/tests/__pycache__/test_clustering.cpython-313-pytest-9.0.2.pyc b/ai-vision-service/tests/__pycache__/test_clustering.cpython-313-pytest-9.0.2.pyc
deleted file mode 100644
index 7227414a98a9797779da42e46a0caa5400a36d97..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001

literal 11128
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
U#WC@ETSV;qpOz+Z7r)5=0`pv1{{R30

diff --git a/ai-vision-service/tests/__pycache__/test_cropper.cpython-313-pytest-9.0.2.pyc b/ai-vision-service/tests/__pycache__/test_cropper.cpython-313-pytest-9.0.2.pyc
deleted file mode 100644
index e2fda897c2c818d773fa0be9ad157406a211591b..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001

literal 10435
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

diff --git a/ai-vision-service/tests/__pycache__/test_detection.cpython-313-pytest-9.0.2.pyc b/ai-vision-service/tests/__pycache__/test_detection.cpython-313-pytest-9.0.2.pyc
deleted file mode 100644
index 512852b92f6984629df12240f894731818ddcb6a..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001

literal 19853
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
XIl2(?$a@zaaLSSYsB+5s)#LvL0Uv1-

diff --git a/ai-vision-service/tests/__pycache__/test_embeddings.cpython-313-pytest-9.0.2.pyc b/ai-vision-service/tests/__pycache__/test_embeddings.cpython-313-pytest-9.0.2.pyc
deleted file mode 100644
index 4f5a3db8bc831cf783021051771b1ce4e4cc60b7..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001

literal 15020
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
Ch?;=_

diff --git a/ai-vision-service/tests/__pycache__/test_matching.cpython-313-pytest-9.0.2.pyc b/ai-vision-service/tests/__pycache__/test_matching.cpython-313-pytest-9.0.2.pyc
deleted file mode 100644
index 6f5769fc35af9af8bba4f24666b124962e4d7b98..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001

literal 9622
zcmd5?Z)_aLb>F?)JKo*${*jcZKNh*9B$L~SM^U6?(GnvvmLiFY=!EOD1<>;1c(**B
zeB8ax9wm{j0=h6@I|*QYNC34c3IWvz3kXtwD%=Jrk{|_we!A09K6c@tE}XzsQ8X?j
zw}8K-@6GH#QfE^FQlKMh?#;}be{bHreebvXFdmO_kiPd<|4^zVIqnlII4Q^o{^36X
z@gq**2&eE$-~vA#AOQ*K;DsO&=x=B`Y(m|18;Q^s;X-seMq)OXNJQWYU1*<<lQ^vl
zUr0<RNpd<xQncK5AwAteIw&2v&^g^jx`0kA(LLN1f$UH^lo+LUDxFG~A|ic-C*8^p
zrJdIA0xC|a-9RNMwFjsqrS<}qqSQ0RpuBUn_a)7&n$m(nq+F$vS;|%OizU6t2#sVO
z;Lc^<5_7t4RCCpmp_?;Mj$X_aOZkgN{&gtCFJiY@&8$GHCI_tc(^^%_SGB@7b9v2b
z$DGv|1lSX2mgcoW0j5!^2GMYI<e-CSB+oNp(_DZYgwH>m0pds8oZB`RaJUqHoY&zn
zvV7UCyTs3iop$fHjHA(%<qvRjaON&=31&shza)nUwvjf-tZ2zp%SNuC6|D9G-G@5A
zQq@eWooLl%qN`VP<z?JuXaQDjTKtlU6HAiyt>HyuNgJLoT^&Ac<d>H;y=o4Bn;2I>
z7UuA`R`QFQHk>OBT`id)$01WAS4(+q7{-QX%vD$Zl@%+YE`fMewgiKaPM8G$oBfcj
zaUVs}Km5~r<iOh0M#s*zsW&fd^bfo>^Ty1&(7PeFubq1cTwH5mPD0C92@}NUiV8<z
zschc@j-%oW%n%V8WPyn;0<@JjOG~A4j+Ck^s;T8jev!ac;y_kybZ44L(onYLMLMvL
z$hK*sDv(`Jvj;i$LB{s@-FoC%*yBK^DRkF`?see+-5%)zj!oN(LIu^8XMyl<4=x<&
z2WSYV1c!M=7z%Nm5*iPK4uoflfAQy-{_a$9l%~e1B6NrJ@u?CA=PHLS{<_7lSfOjB
zLUqv!FKVUYV%3V}4Sk_h&~#AnsOBiN%o9|+yFBTE9~0G8V%tpE2dNcQR2$NVO~``;
z>{RT&wf}bKdoO$t{8g-`&evYc*A`0k*GhHqN=>-Jb_<+t!fEJke+h(tw{z|>4Rc3v
z0g&ck$1HhuaBl)SH|O4ySv<ilsh^vpMiHw)g2C}X02ZC)X5(8Jv0ZRx19KI^e@E^6
zC~?J5A9siwv^y1GRSN-$>xHqfZ6esqE%0)9b($*4pe!vdn^lSAN~R{gjF;^UAz+}c
zEo!<{UDPB~D=(BZ2~MDzE9s`B8xp%Ex%sjtp?EWQ16IVjIaY`&*J^6Upp7=ORshQr
zqEnhEv)^z0enxI1s7CazQDwBk6}<aZD@>PTS}|`y1QiX&uyvdGk9)wo&MNDv;__A9
zpvUhj1Nj<`0sqa@kgajQN$mb8-FrLGNbmnBvHMp4_l^Gw1(V^mvyUQNEcNcb@9q2H
zYE3@Th@RYtB;Sp{6TfM!N1pwkAQzixMo)eiJ^6)+xAJd0rqaQmr(;vSZFwlV$-N^t
zfr1Aa+>2q<0yq(tJnivx=BV8^%sVGMhlY}-tgB<F9Xg-oXK{`#$<qxzFo)}-DI1t;
zcW6gfj8R8R&hiD24d_vLF5z&^rX0%q?dP2Joq)<hFK9d36`E$zNNh=dop$!)%$Wn*
z<LkY1OIIki>ir_Ggq60ZTIJqN^R!%LHt^W$U_INd&g%uMYEvRlwW=qPop)lk&ODXu
z9_tOOjBLB7pd$$-nh}P;V(G%%Zs%-#z46JhCG~Sz*Dg7uXuJ~BgW16BGh3LUsE6i2
z3M^$qP7gh-h{n}y+w<o*&Uo9|F=!|}ihc7-PEYT*pHteikuhG0Un-6TjtZ<rN&Laj
z1)n!GIcs)S`9wPXSZ_F&#Q#s7_Q|{D{q#<4Th6c}t8F>k98M*f2~iD<Dk&wMjUMJ{
zDfSfl7<0yQeo-GMcs&IF!xMbvt=5{Ubl^kW_~|UVe_N6sQaX))%(hegTyRdl@a7X~
zXBf1z>(Z;9c5W*T(OLPnobC<Umb2X%Q`wOTQklk;ol18$Zc8}&6cUa)V>!RJgheLh
zN_iUzAJ`&ZD1u$Ur#(%xj)0vC_|+rIF5}<8+9aGgjnA{m&F2C30&J#F5|VEKo22#v
zPh|Hc_5b!nls$iN8{|sJk%1$qC$d40^#&WX$0x1Uw>{#_wJoQ6GTU+{oiUZYnK0GG
zl=6(SFPpM;G5r*}n0Cf;emCnP-grF%xBhp<nB23~1E%q&bkUBkm&;YDRMnPDX@0o`
z^a3%Km_LlM6L`fKa7jcnfziy!fiEKH3J>Mx^Peuz^q;5Xz$&XOXbZ(y^RFutu}@Et
z{h)j%x>gIh*R`S2Qm&{C(U5obXwHNvwJIGPtgMX5X6#RFLYkmehh=jRYer=A5Un^O
zn{w=i6@vg*H>)`ejv}xiiVG05U$S5YD=UXF8^P=dW@9rCFjTn9e-W6Nkonb%IOb7j
zIv}=8H|jJ2VK>1FY|O%p-GC)X6KsXYWz!0lH60@S5txD;fefb{#q20%$5)fSO^(2p
zECCjGnBbDg5M;2TW4NL(nYK*hdgj)b3f|PmKo&tdAsM%4J+_+g%>`>C=(Caxn?(PL
zNxW#&n_vVs%}xX<TM*AVbwJovAixZOJH)siyFrg@oSqUHz-hzY3d!^KGM_`aj8id;
zY?cm)fL4#nJA8psA8rCecN!6qVWjY|t@g>vib|Cg)WHgujeM>QAr#co@F+*DU8=cg
zESC!^(JDkOmW}ybS=Dn(5LByXZb8FpD=|g25HJ%O2wI&g;8hT~soM2QIj2)pige?w
z$8pxQ3e%M7h<RhFk|Uax*nCJdI;Z=$!b~!9hZUz$B7<N6sQ4os?=X%h;x5>^jj{rp
z{;0p@h`%uAFFfZj9AgDGz&H~SD~ycz`40OF_C$<t({RVx2yAg9hc}IPWK(I(#HdJm
zEHQNApg&xtR>yP%p`w{l89ehU3^5A-%{y>8*0_&%3_vVe>pHo15rS2STkrHV`bKKf
zkw$tHqt~HEV$cp>KZ|gw?sspzbECHJa3eXgcJ4Rgj+={j;terV6EYu)fbMMis|%SQ
zJnz<RF0twlh0M)GKZmd6a@>jgIh@jcAyaEL<3_T(ne446duzhMAB@(Ly$w+U^7a(X
z>f*tsVE;9QgEdidi;TFBz1+I`rV^|EP&oMZbw7twg03(fYw?c_^zA9PgG&JWhS=E@
z_twR|x2Ec1Pfa+{6o=~K5D@S0p;=u#(S%z1cTYG`6NebRj&u*B8@_s=-{0f*aEbfE
ziLFyjHbuEE$~9r~$1nfQ<-3=G_+SjO_bz`h))<-usx~xP7bly7{nvmRQD((;q+xn&
z^4Gh}!0_Xj-BR5v-NzZ+jvtJ<B+TaW`-ywP<X7Nk{|<WW$ITE60VLUng(yK<!+V&>
zrPQz+l>?H2HjXAm@URg*=%FK*_5;os(1onf5*2ad55Uxdvo6x+jLNmd*#Kd2@eq#_
zW@v$pAObKR1dJ^z$5y9bLHuk9oP$!uhRI9`jH3&O9iq;Jp=;8$Qgu;U1e_C)FNE1_
zpi?TD(z2-)GB#HF$tfbi5{f@L`>(5AKlz>KU0h#TEy}OH`-{&9|AToK4>9mX@8SXO
z5^=XOAjQ=gIZA<04{u{n6?6p&`g>M4Gi}tO19WPDN1@{C2uA5vOa)4VCrG&<hpb51
zxTfN2tthUYk_3Huau72#=q4T+wSmm;`C&TPnW@^FrhOT@%ivlK`h5cj_+!Wbrc3U7
zud|*UT08eqs^`4}_0;g%d8oU!QtKIQB*&n-y}P#iYqed68tp@CX8_f^eY~C+Upu=Y
zh;Lnd<KoSMbz#qEVJ;MF3VZ9q-li~G7e?Pd-yAzzA3OW2?&kTq`uVw9UaJYC_k@MV
z)ffRd04@24yTB6r)!0*32Nv_GW=kMg=Y0xGq4M#d9)J+36_DpbF`%;ild7z<k}vJk
zLZO#oUzM>hnWF{2BH+>Lp)3H;lnN{S<B(0kfB?+BD6=k52wm+20a%y<Hf?^u#@DAc
zSm$2lZ8<$CA(9E$P(oCR`Je>!WN7k@h2GVc1i@x2C;@|93L_LnxqWr=CBVz+4K6Md
ztpGRNzAp@8p9i?yAlGsP-gZe<LwfA}O~!sd^57KsvhH27qV724HCPt)l^-A=NRB}U
z4s(Yc7C3%51P^k6xte3ZvB?hxN104O<%}F>hQRYDQ3aV(Nv%Q0<JQ26QfDtmiY7UY
z+~+a-CT3?bI|rF8dP}Efz~WV_O?@5q4ZW@)TNbm6n7xSE3}&xDM$vSi)5Ofi0iU~6
z!8MtlAyTV`?JX@q|L@=!KZT6ijKBPDqj$L0!#p4`5w`;0e{t;$xJtK=|Llc&;@oEY
z@UaketV0GopmpK!MtWy6Jy=f<Hq%Gy=_7AUuT6cN+R;o6)Kde^)JQ!w@_t`EHMVws
zL+rZwop(;wgq~ZYGy@-@DcFDagr2ugveLRoHjvllaS7n~3hUGJrPjxLI6AlAvqPS}
z+4?#PUM;n<I^IJUUof<IQ0jqU&Nz|{Qo!Z313MJ{9&Wn}Ik$Rj!fg*`1%O+GOZz>z
zMG5(CUP~L{?1{c|Krr8%rL}!<U!6E>%Yj1sdZBu6NpQd2UI2xJw&ixEv@NG=#g(uP
zwuR7D$cAiyBkTh>yq&d%*Imo!1302!g8~3*yg(g~b5pvcEmf*35`Ebwl}q4N48lu0
z`u<$X%^O!W&oJ3<|G+Y_*X>}K@?|Zjmsc_rs9*-iHZ#L$W&m_xVK5LLQsBV>jtzo1
zm<DuU$tV_pkqnJ_H(4Wyo5|OqWkyagXQUI^Jd;Fy6B=xK<_0|j@&aaOFxz5%+FHkw
zBjnr2j7G;F6mE(TkDK_Qx9tzJJ)=I`!z5&?RJtn4)qTsjIhZ9diVFYDJCHeV8Mj1h
z-n&LOSiAK~BYAM`oEretguYvZW_7WzDcFDagua>xE{s<L^nIc4?c;7;-77(Z%iX~7
zTqc)T7y78pfo}`&S-skUJDWT0`=;bFypN?}D*a>w`0zkhyD49F8Qj}Bvq}z03-BFB
z_3~w6LMw?t2Jh!H_#;pR0KVWr2G$(L`T(UZVFtWlc^^C@)Pj*$Rd6)bg=P5oLsL}(
zZWm`o98`ng*;~6+25Ds20}7Ce4AHK^cMyPMxK&o0T}K~OR(x46Rq-%0_?-v)iUJ`S
zD~Vs?<SM0%2_K9s<xGa9?8I93N*jlFUT)Lx4cLb(UC7~nieP3~%#Pc(XcN7CzK?r+
z>P^8Ls^j=RnqZty(B&og3?ryLcR6|_Oa~(;myE)4S^GNqGibu+zKLr5S&--Xf94MU
zmh1nN<KE=%bNfHx;=kqOf8i#6%?<yWJM<_a@bO29ARqtlcAkHof7H>&4?OB>=co8b
TJ?(rEa*^--{FyespHBC`9W+;q

diff --git a/ai-vision-service/tests/conftest.py b/ai-vision-service/tests/conftest.py
index e4faeb49ab7..179a06f774b 100644
--- a/ai-vision-service/tests/conftest.py
+++ b/ai-vision-service/tests/conftest.py
@@ -34,7 +34,6 @@ def mock_settings() -> AppSettings:
     m = MagicMock(spec=AppSettings)
     m.api_key = "test-api-key"
     m.lychee_api_url = "http://lychee-test"
-    m.lychee_api_key = "test-lychee-key"
     m.photos_path = "/tmp"  # overridden where needed
     m.match_threshold = 0.5
     m.max_faces_per_photo = 10
@@ -110,7 +109,6 @@ def _override_settings() -> AppSettings:
         m = MagicMock(spec=AppSettings)
         m.api_key = "test-api-key"
         m.lychee_api_url = "http://lychee-test"
-        m.lychee_api_key = "test-lychee-key"
         m.photos_path = str(tmp_path)
         m.match_threshold = 0.5
         m.max_faces_per_photo = 10
diff --git a/ai-vision-service/tests/test_smoke.py b/ai-vision-service/tests/test_smoke.py
index 8743e10aa9c..92672cef83c 100644
--- a/ai-vision-service/tests/test_smoke.py
+++ b/ai-vision-service/tests/test_smoke.py
@@ -11,8 +11,7 @@
 Prerequisites:
   - Docker and docker-compose available in PATH
   - ``docker-compose.minimal.yaml`` with the ``ai-vision`` service block
-  - ``VISION_FACE_API_KEY`` and ``VISION_FACE_LYCHEE_API_KEY`` env vars set
-    (or defaults are used for local testing)
+  - ``VISION_FACE_API_KEY`` env var set (or the default is used for local testing)
 """
 
 from __future__ import annotations
diff --git a/app/Http/Controllers/AiVision/FaceDetectionController.php b/app/Http/Controllers/AiVision/FaceDetectionController.php
index 24fd9834fa8..dfd4da3d0d4 100644
--- a/app/Http/Controllers/AiVision/FaceDetectionController.php
+++ b/app/Http/Controllers/AiVision/FaceDetectionController.php
@@ -154,7 +154,7 @@ public function bulkScan(BulkScanRequest $request): \Illuminate\Http\Response
 		$album_id = $request->albumId();
 		$batch_size = (int) app(ConfigManager::class)->getValueAsString('ai_vision_face_scan_batch_size');
 
-		$query = Photo::query()->select('id')->whereNull('face_scan_status');
+		$query = Photo::query()->select('id')->whereNull('face_scan_status')->orWhere('face_scan_status', '=', FaceScanStatus::FAILED->value);
 
 		if ($album_id !== null) {
 			$query->whereHas('albums', fn ($q) => $q->where('albums.id', '=', $album_id));
diff --git a/app/Jobs/DispatchFaceScanJob.php b/app/Jobs/DispatchFaceScanJob.php
index ef3af34c7ea..370f72dfc8b 100644
--- a/app/Jobs/DispatchFaceScanJob.php
+++ b/app/Jobs/DispatchFaceScanJob.php
@@ -71,17 +71,16 @@ public function handle(): void
 			return;
 		}
 
-		$photo_path = Storage::disk($original->storage_disk->value)->path($original->short_path);
-
 		try {
+			$data = [
+				'photo_id' => $this->photo_id,
+				'photo_path' => $original->short_path, // We just send short path. Not that this means that we do not support s3 for facial recognition.
+			];
 			$response = Http::withHeaders(['X-API-Key' => $api_key])
-				->post($service_url . '/detect', [
-					'photo_id' => $this->photo_id,
-					'photo_path' => $photo_path,
-				]);
+				->post($service_url . '/detect', $data);
 
 			if (!$response->successful()) {
-				Log::warning("DispatchFaceScanJob: /detect returned HTTP {$response->status()} for photo {$this->photo_id}.");
+				Log::warning("DispatchFaceScanJob: /detect returned HTTP {$response->status()} for photo {$this->photo_id}.", ['data' => $data,'response' => $response->json()]);
 				$photo->face_scan_status = FaceScanStatus::FAILED;
 				$photo->save();
 			}
diff --git a/config/features.php b/config/features.php
index 077c1e25e87..5e8fa6f9a43 100644
--- a/config/features.php
+++ b/config/features.php
@@ -164,6 +164,6 @@
 	'ai-vision' => [
 		'face-url' => env('AI_VISION_FACE_URL', ''),
 		'face-api-key' => env('AI_VISION_FACE_API_KEY', ''),
-		'face-rescan-iou-threshold' => (float) env('VISION_FACE_RESCAN_IOU_THRESHOLD', 0.3),
+		'face-rescan-iou-threshold' => (float) env('AI_VISION_FACE_RESCAN_IOU_THRESHOLD', 0.3),
 	],
 ];
\ No newline at end of file
diff --git a/docker-compose.minimal.yaml b/docker-compose.minimal.yaml
index 7949e3dec2d..c596580d32a 100644
--- a/docker-compose.minimal.yaml
+++ b/docker-compose.minimal.yaml
@@ -46,6 +46,8 @@ x-common-env: &common-env
   SESSION_DRIVER: "${SESSION_DRIVER:-file}"
   SESSION_LIFETIME: "${SESSION_LIFETIME:-120}"
   QUEUE_CONNECTION: "${QUEUE_CONNECTION:-database}"
+  AI_VISION_FACE_API_KEY: "${AI_VISION_API_KEY:-changeme}"
+  AI_VISION_FACE_URL: "http://ai_vision:8000"
 
 services:
   lychee_api:
@@ -122,6 +124,36 @@ services:
         retries: 10
         start_period: 10s
 
+  ai_vision:
+    build:
+      context: ./ai-vision-service
+    container_name: lychee-ai-vision
+    restart: unless-stopped
+    security_opt:
+      - no-new-privileges:true
+    cap_drop:
+      - ALL
+    environment:
+      VISION_FACE_LYCHEE_API_URL: "http://lychee_api:8000"
+      VISION_FACE_API_KEY: "${AI_VISION_API_KEY:-changeme}"
+      VISION_FACE_PHOTOS_PATH: "/data/photos"
+      VISION_FACE_STORAGE_PATH: "/data/embeddings"
+      VISION_FACE_WORKERS: "${AI_VISION_WORKERS:-1}"
+    volumes:
+      - ./lychee/uploads:/data/photos:ro
+      - ai_vision_embeddings:/data/embeddings
+    networks:
+      - lychee
+    depends_on:
+      lychee_api:
+        condition: service_healthy
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 60s
+
 networks:
     lychee:
 
@@ -129,3 +161,6 @@ volumes:
     mysql:
         name: lychee_prod_mysql
         driver: local
+    ai_vision_embeddings:
+        name: lychee_ai_vision_embeddings
+        driver: local
diff --git a/docker-compose.yaml b/docker-compose.yaml
index 0b9eab201da..b0a27794d93 100644
--- a/docker-compose.yaml
+++ b/docker-compose.yaml
@@ -404,6 +404,12 @@ x-common-env: &common-env
   # PAYPAL_CLIENT_ID=
   # PAYPAL_SECRET=
 
+  ###################################################################
+  # Facial recognition (requires SE)                               #
+  ###################################################################
+  AI_VISION_FACE_API_KEY: "${AI_VISION_API_KEY:-changeme}"
+  AI_VISION_FACE_URL: "http://ai_vision:8000"
+
 services:
   ##########################################################################################
   # Lychee API Service and frontend.
@@ -549,6 +555,42 @@ services:
         retries: 10
         start_period: 10s
 
+  ai_vision:
+    expose:
+      - "${APP_PORT_AI_FACE:-8001}"
+    ports:
+      - "${APP_PORT_AI_FACE:-8001}:8000"
+    build:
+      context: ./ai-vision-service
+    container_name: lychee-ai-vision
+    restart: unless-stopped
+    security_opt:
+      - no-new-privileges:true
+    cap_drop:
+      - ALL
+    environment:
+      VISION_FACE_LYCHEE_API_URL: "http://localhost:443"
+      VISION_FACE_API_KEY: "${AI_VISION_API_KEY:-changeme}"
+      VISION_FACE_PHOTOS_PATH: "/data/photos"
+      VISION_FACE_STORAGE_PATH: "/data/embeddings"
+      VISION_FACE_WORKERS: "${AI_VISION_WORKERS:-1}"
+    volumes:
+      # - ./lychee/uploads:/data/photos:ro
+      - ./public/uploads:/data/photos:ro
+      - ai_vision_embeddings:/data/embeddings
+    networks:
+      - lychee
+    # depends_on:
+    #   lychee_api:
+    #     condition: service_healthy
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 60s
+
+
 networks:
     lychee:
 
@@ -559,3 +601,6 @@ volumes:
     cache:
         name: lychee_prod_redis
         driver: local
+    ai_vision_embeddings:
+        name: lychee_ai_vision_embeddings
+        driver: local
diff --git a/docs/specs/2-how-to/configure-facial-recognition.md b/docs/specs/2-how-to/configure-facial-recognition.md
new file mode 100644
index 00000000000..e7c63e73cf6
--- /dev/null
+++ b/docs/specs/2-how-to/configure-facial-recognition.md
@@ -0,0 +1,230 @@
+# How-To: Configure Facial Recognition (AI Vision)
+
+**Author:** Lychee Team  
+**Last Updated:** 2026-03-22  
+**Feature:** 030-ai-vision-service  
+**Related:** [Feature 030 Spec](../4-architecture/features/030-ai-vision-service/spec.md)
+
+## Overview
+
+Lychee's facial recognition feature is powered by a sidecar Python service (`ai-vision-service`). When enabled, Lychee detects faces in photos, groups them into Person profiles, and lets users claim their own profile. This guide covers:
+
+1. [Prerequisites](#prerequisites)
+2. [Docker Compose setup](#docker-compose-setup)
+3. [Shared volume configuration](#shared-volume-configuration)
+4. [Environment variables](#environment-variables)
+5. [Enabling the feature in Lychee admin](#enabling-the-feature-in-lychee-admin)
+6. [Permission modes](#permission-modes)
+7. [Running a bulk scan](#running-a-bulk-scan)
+8. [Service health check](#service-health-check)
+9. [Troubleshooting](#troubleshooting)
+
+---
+
+## Prerequisites
+
+- Docker and Docker Compose v2
+- A working Lychee deployment (see [docker-compose.minimal.yaml](../../../docker-compose.minimal.yaml))
+- A **Supporter Edition (SE)** licence — AI Vision is an SE-only feature
+
+---
+
+## Docker Compose Setup
+
+Add the `ai_vision` service to your `docker-compose.yaml`. The complete minimal example is in [docker-compose.minimal.yaml](../../../docker-compose.minimal.yaml). The key stanza:
+
+```yaml
+services:
+  lychee_api:
+    # ... existing config ...
+    volumes:
+      - ./lychee/uploads:/app/public/uploads   # Lychee upload directory
+
+  ai_vision:
+    build:
+      context: ./ai-vision-service             # Build from source, OR use a pre-built image
+    container_name: lychee-ai-vision
+    restart: unless-stopped
+    security_opt:
+      - no-new-privileges:true
+    cap_drop:
+      - ALL
+    environment:
+      VISION_FACE_LYCHEE_API_URL: "http://lychee_api:8000"
+      VISION_FACE_API_KEY: "${AI_VISION_API_KEY}"
+      VISION_FACE_PHOTOS_PATH: "/data/photos"
+      VISION_FACE_STORAGE_PATH: "/data/embeddings"
+    volumes:
+      - ./lychee/uploads:/data/photos:ro        # Shared read-only photos volume
+      - ai_vision_embeddings:/data/embeddings   # Persistent embeddings store
+    networks:
+      - lychee
+    depends_on:
+      lychee_api:
+        condition: service_healthy
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 60s
+
+volumes:
+  ai_vision_embeddings:
+    name: lychee_ai_vision_embeddings
+    driver: local
+```
+
+---
+
+## Shared Volume Configuration
+
+The AI Vision service reads photo files directly from the filesystem — no HTTP file transfer. This requires both containers to mount the same upload directory:
+
+| Container | Mount path | Mode |
+|---|---|---|
+| `lychee_api` | `/app/public/uploads` | read/write |
+| `ai_vision` | `/data/photos` | read-only |
+| Host bind mount | `./lychee/uploads` | (source for both) |
+
+**Critical:** The host path `./lychee/uploads` must be identical for both mounts. If you use an absolute path or a named volume for `lychee_api`'s uploads, apply the same source to `ai_vision`.
+
+---
+
+## Environment Variables
+
+### Lychee API (`lychee_api` / `lychee_worker`)
+
+Add these to `x-common-env` or the service's `environment` block:
+
+| Variable | Description | Example |
+|---|---|---|
+| `AI_VISION_FACE_URL` | Internal URL of the AI Vision service | `http://lychee-ai-vision:8000` |
+| `AI_VISION_FACE_API_KEY` | Shared secret used in both directions: Lychee sends it on scan requests to Python; Python sends it on callback responses to Lychee | `changeme-strong-random-value` |
+
+> Generate strong secrets with: `openssl rand -hex 32`
+
+### AI Vision Service (`ai_vision`)
+
+| Variable | Description | Default |
+|---|---|---|
+| `VISION_FACE_LYCHEE_API_URL` | Base URL of the Lychee API (for callbacks) | — |
+| `VISION_FACE_API_KEY` | Must match `AI_VISION_FACE_API_KEY` in Lychee | — |
+| `VISION_FACE_PHOTOS_PATH` | Path where photos are mounted inside the container | `/data/photos` |
+| `VISION_FACE_STORAGE_PATH` | Path for persisting face embeddings | `/data/embeddings` |
+
+---
+
+## Enabling the Feature in Lychee Admin
+
+After starting the containers, enable the feature in **Admin → Settings → AI Vision**:
+
+1. **AI Vision enabled** — master toggle; set to `On`.
+2. **Facial recognition enabled** — sub-toggle; set to `On`.
+3. Configure optional settings (permission mode, batch size, etc.).
+
+These settings are only visible on Supporter Edition instances.
+
+---
+
+## Permission Modes
+
+`ai_vision_face_permission_mode` controls who can view People, face overlays, and perform face management. Choose the mode that matches your deployment scenario.
+
+| Mode | Best for |
+|---|---|
+| `public` | Community/open galleries where anyone can browse people |
+| `private` | Personal or team galleries — all features require login |
+| `privacy-preserving` | Multi-user deployments — users only see their own content |
+| `restricted` | High-privacy or admin-controlled deployments |
+
+**Permission matrix:**
+
+| Operation | `public` | `private` | `privacy-preserving` | `restricted` |
+|---|---|---|---|---|
+| View People page | Guest | Logged in | Owner + admin | Admin only |
+| View face overlays | Album access | Logged in | Owner + admin | Owner + admin |
+| Create / edit Person | Logged in | Logged in | Owner + admin | Admin only |
+| Assign face | Logged in | Logged in | Owner + admin | Admin only |
+| Trigger scan | Logged in | Logged in | Owner + admin | Owner + admin |
+| Claim person (selfie) | Logged in | Logged in | Logged in | Logged in |
+| Merge persons | Logged in | Logged in | Owner + admin | Admin only |
+
+> **Default:** `restricted` — the most conservative option.
+
+---
+
+## Running a Bulk Scan
+
+After setup, scan your existing photo library for faces:
+
+**Via the admin UI:**
+1. Navigate to **Admin → Maintenance**.
+2. Find the **Bulk Face Scan** card and click **Scan all unscanned photos**.
+
+**Via CLI:**
+```bash
+php artisan lychee:scan-faces
+```
+
+Scanning runs asynchronously through the queue. Ensure the `lychee_worker` container is running. Progress is visible in the queue job history.
+
+---
+
+## Service Health Check
+
+The AI Vision service exposes a `/health` endpoint:
+
+```bash
+# Inside the lychee network, from another container:
+curl http://lychee-ai-vision:8000/health
+
+# From the host (if you expose the port):
+curl http://localhost:<MAPPED_PORT>/health
+```
+
+A healthy response:
+```json
+{"status": "ok", "version": "x.y.z"}
+```
+
+Docker will also report the container's health status — wait for `healthy` before triggering scans:
+
+```bash
+docker compose ps
+```
+
+---
+
+## Troubleshooting
+
+### AI Vision endpoints return 403
+
+- Confirm the Lychee instance is a **Supporter Edition** licence.
+- Check that `ai_vision_enabled = 1` and `ai_vision_face_enabled = 1` in admin settings.
+
+### Photos are not scanned / `face_scan_status` stays `pending`
+
+1. Verify the `lychee_worker` container is running (`docker compose ps`).
+2. Confirm `QUEUE_CONNECTION` is not `sync` in the Lychee worker environment.
+3. Check the AI Vision service health endpoint.
+4. Review `lychee_worker` logs: `docker compose logs lychee-worker`.
+
+### AI Vision service cannot find photos
+
+- Compare volume mounts: the host `./lychee/uploads` path must be the same in both the `lychee_api` and `ai_vision` volume definitions.
+- Verify `VISION_FACE_PHOTOS_PATH` inside the container matches the volume mount destination.
+
+### API key mismatch errors (401 from AI Vision / Lychee)
+
+- `AI_VISION_FACE_API_KEY` (Lychee) must equal `VISION_FACE_API_KEY` (Python service). The same key is used in both directions.
+- Restart both containers after changing the secret.
+
+### Selfie claim returns "no match found"
+
+- Lower `ai_vision_face_selfie_confidence_threshold` (default `0.8`) in admin settings to accept less-certain matches.
+- Ensure the photo library has been fully scanned first.
+
+---
+
+*Last updated: 2026-03-22*
diff --git a/docs/specs/3-reference/database-schema.md b/docs/specs/3-reference/database-schema.md
index 5b24201c441..3306c4253a2 100644
--- a/docs/specs/3-reference/database-schema.md
+++ b/docs/specs/3-reference/database-schema.md
@@ -125,6 +125,51 @@ Color palette information extracted from photos.
 **Relationships:**
 - Belongs to `Photo`
 
+#### Face
+A detected face bounding box within a specific photo.
+
+**Key Fields:**
+- `id`: Primary key (24-char random string)
+- `photo_id`: Foreign key to Photo (cascade delete)
+- `person_id`: Foreign key to Person (nullable; null on delete)
+- `x`, `y`, `width`, `height`: Bounding box as relative floats (0.0–1.0)
+- `confidence`: Detection confidence score (0.0–1.0)
+- `crop_token`: Opaque token for serving cropped face thumbnails
+- `is_dismissed`: Whether the face has been dismissed/ignored by an operator
+
+**Relationships:**
+- Belongs to `Photo`
+- Belongs to `Person` (nullable)
+- Has many `FaceSuggestion` (as the source face)
+
+#### FaceSuggestion
+Pairs of faces ranked by embedding similarity (used to suggest identities for unknown faces).
+
+**Key Fields:**
+- `face_id`: Foreign key to Face (cascade delete) — the unidentified face
+- `suggested_face_id`: Foreign key to Face (cascade delete) — an already-assigned face of a known Person
+- `confidence`: Similarity score (0.0–1.0)
+
+**Unique Constraint:** Composite unique index on (`face_id`, `suggested_face_id`)
+
+**Relationships:**
+- Both keys belong to `Face`
+
+#### Person
+An identified individual who appears across one or more photos.
+
+**Key Fields:**
+- `id`: Primary key (24-char random string)
+- `name`: Display name (max 255 chars, required)
+- `user_id`: Foreign key to User (nullable, unique — one Person per User claim; null on delete)
+- `is_searchable`: When false, face overlays for this Person are hidden from non-owners (privacy)
+
+**Unique Constraint:** `user_id` is unique (one User → at most one claimed Person)
+
+**Relationships:**
+- Optionally belongs to `User` (the claimed user)
+- Has many `Face`
+
 #### PhotoRating
 User ratings for photos on a 1-5 star scale.
 
@@ -229,11 +274,13 @@ This dual approach allows Lychee to provide:
 ### Many-to-Many
 - **Photos-Albums**: Many-to-many through `photo_album` pivot table (photos can belong to multiple albums)
 - **Tags**: Many-to-many with photos through `photos_tags` pivot table
+- **Face Suggestions**: Many-to-many between Face records through `face_suggestions` pivot table (ranked by similarity confidence)
 
 ### One-to-Many
 - **Photos**: Owned by one user (but can belong to multiple albums)
 - **Size Variants**: Multiple variants per photo
 - **Access Permissions**: Multiple permissions per album
+- **Faces**: Multiple detected faces per photo; multiple faces per Person
 
 ## Database Optimization
 
@@ -256,6 +303,34 @@ Eager loading enforced with `Model::shouldBeStrict()`, which throws an exception
 - [Tag System](../4-architecture/tag-system.md) - Tag architecture and operations
 - [Image Processing](image-processing.md) - Size variant generation and processing pipeline
 
+## AI Vision Schema Additions (Feature 030)
+
+### New Tables
+
+| Table | Migration | Purpose |
+|---|---|---|
+| `persons` | `2026_03_21_000001_create_persons_table` | Identified individuals (name, user link, searchability) |
+| `faces` | `2026_03_21_000002_create_faces_table` | Bounding boxes detected by AI Vision service |
+| `face_suggestions` | `2026_03_21_000002_create_faces_table` | Ranked similarity pairs for identity suggestions |
+
+### Column Added to `photos`
+
+| Column | Type | Default | Purpose |
+|---|---|---|---|
+| `face_scan_status` | string(16), nullable | `null` | Tracks face detection lifecycle: `null` (not queued), `pending`, `scanned`, `failed` |
+
+### New Config Keys (AI Vision category, `level = 1` / SE only)
+
+| Key | Default | Description |
+|---|---|---|
+| `ai_vision_enabled` | `0` | Master toggle for the AI Vision subsystem |
+| `ai_vision_face_enabled` | `0` | Enable facial recognition (requires master toggle) |
+| `ai_vision_face_permission_mode` | `restricted` | Access control mode: `public`, `private`, `privacy-preserving`, `restricted` |
+| `ai_vision_face_selfie_confidence_threshold` | `0.8` | Minimum confidence for selfie-based person claim |
+| `ai_vision_face_person_is_searchable_default` | `1` | Default `is_searchable` for new Person records |
+| `ai_vision_face_allow_user_claim` | `1` | Allow non-admin users to claim a Person profile |
+| `ai_vision_face_scan_batch_size` | `200` | Photo IDs per bulk-scan job chunk |
+
 ---
 
-*Last updated: January 21, 2026*
+*Last updated: March 22, 2026*
diff --git a/docs/specs/4-architecture/features/030-ai-vision-service/tasks.md b/docs/specs/4-architecture/features/030-ai-vision-service/tasks.md
index 9d9f3fc5759..64666fdc895 100644
--- a/docs/specs/4-architecture/features/030-ai-vision-service/tasks.md
+++ b/docs/specs/4-architecture/features/030-ai-vision-service/tasks.md
@@ -261,7 +261,7 @@ _Last updated: 2026-03-21_
 
 ### I13 – Frontend: People Page
 
-- [ ] T-030-34 – Create People.vue, PeopleService.ts, and PersonCard.vue (UI-030-01).
+- [x] T-030-34 – Create People.vue, PeopleService.ts, and PersonCard.vue (UI-030-01).
   _Intent:_ People page at /people route. Grid of PersonCard components (server-side face crop thumbnail from crop_url, name, photo count). PeopleService: getPeople(), getPerson(), etc. Empty state when no persons exist. Service unavailable state (toast notification). Navigation link in sidebar.
   _Verification commands:_
   - `npm run check`
@@ -269,7 +269,7 @@ _Last updated: 2026-03-21_
 
 ### I14 – Frontend: Person Detail Page
 
-- [ ] T-030-35 – Create PersonDetail.vue (UI-030-02).
+- [x] T-030-35 – Create PersonDetail.vue (UI-030-02).
   _Intent:_ Person detail at /people/:id. Person info header (name, counts, linked user, searchability badge). Paginated photo grid (reuse existing layout components). Action buttons: Edit, Toggle searchable, Merge, Delete. Route registration.
   _Verification commands:_
   - `npm run check`
@@ -277,7 +277,7 @@ _Last updated: 2026-03-21_
 
 ### I15 – Frontend: Face Overlays on Photo Detail
 
-- [ ] T-030-36 – Create FaceOverlay.vue and integrate into photo detail (UI-030-03).
+- [x] T-030-36 – Create FaceOverlay.vue and integrate into photo detail (UI-030-03).
   _Intent:_ Positioned div overlays on photo using bounding box percentages (x, y, width, height as CSS left/top/width/height %). Name label per overlay. "Unknown" for unassigned faces. Non-searchable faces: overlays hidden entirely; display "{N} face(s) hidden for privacy" message when `hidden_face_count > 0` (Q-030-10 resolved). Click unassigned → open assignment modal. Responsive scaling with image container.
   _Verification commands:_
   - `npm run check`
@@ -285,7 +285,7 @@ _Last updated: 2026-03-21_
 
 ### I16 – Frontend: Face Assignment Modal
 
-- [ ] T-030-37 – Create FaceAssignmentModal.vue (UI-030-04).
+- [x] T-030-37 – Create FaceAssignmentModal.vue (UI-030-04).
   _Intent:_ Modal triggered by clicking unassigned face overlay. Face crop preview (from crop_url), confidence display. PrimeVue Dropdown to select existing person (with filter). Text input for new person name. Calls FaceService.assign() on confirm. Refreshes face overlays after success.
   _Verification commands:_
   - `npm run check`
@@ -293,7 +293,7 @@ _Last updated: 2026-03-21_
 
 ### I17 – Frontend: Scan Trigger UI
 
-- [ ] T-030-38 – Add scan trigger buttons to photo/album context menus and admin page (UI-030-05, UI-030-06).
+- [x] T-030-38 – Add scan trigger buttons to photo/album context menus and admin page (UI-030-05, UI-030-06).
   _Intent:_ "Scan for faces" in photo context menu (calls FaceDetectionService.scan). "Scan album" in album context menu. "Bulk scan all photos" in admin Maintenance page. Progress toast during scanning. Graceful handling when service unavailable.
   _Verification commands:_
   - `npm run check`
@@ -301,7 +301,7 @@ _Last updated: 2026-03-21_
 
 ### I18 – Frontend: Selfie Upload Claim
 
-- [ ] T-030-39 – Create SelfieClaimModal.vue and integrate into user profile (UI-030-07, S-030-20, S-030-21, S-030-22).
+- [x] T-030-39 – Create SelfieClaimModal.vue and integrate into user profile (UI-030-07, S-030-20, S-030-21, S-030-22).
   _Intent:_ Modal with file upload area (drag & drop or click) for selfie image. Sends to API-030-13. Displays matching Person result (face crop, name, confidence score). Confirm button links Person to User. Error states: no face detected, no match found, already claimed. "Find me in photos" button on user profile page triggers modal.
   _Verification commands:_
   - `npm run check`
@@ -311,22 +311,22 @@ _Last updated: 2026-03-21_
 
 ### I19 – Documentation & Quality Gate
 
-- [ ] T-030-40 – Update knowledge-map.md with Person/Face models and service integration.
+- [x] T-030-40 – Update knowledge-map.md with Person/Face models and service integration.
   _Intent:_ Add Person, Face to Domain Layer models. Add Python face-recognition service to Dependencies. Add inter-service communication to Architectural Patterns. Add shared Docker volume architecture.
   _Verification commands:_
   - Review documentation for accuracy.
 
-- [ ] T-030-41 – Update database-schema.md with persons and faces tables.
+- [x] T-030-41 – Update database-schema.md with persons and faces tables.
   _Intent:_ Add table definitions (including `crop_token` on faces, `face_suggestions` table, `face_scan_status` on photos), relationships, indexes, and constraints.
   _Verification commands:_
   - Review documentation for accuracy.
 
-- [ ] T-030-42 – Create configure-facial-recognition.md how-to guide.
+- [x] T-030-42 – Create configure-facial-recognition.md how-to guide.
   _Intent:_ Docker setup instructions, shared volume configuration, environment variables, permission modes (open/restricted), service health check, troubleshooting.
   _Verification commands:_
   - Review documentation for accuracy.
 
-- [ ] T-030-43 – Run full quality gate and update roadmap.
+- [x] T-030-43 – Run full quality gate and update roadmap.
   _Intent:_ Run all quality gates across all three codebases. All green. Update roadmap status to Complete.
   _Verification commands:_
   - Python: `cd ai-vision-service && uv run ruff format --check && uv run ruff check && uv run ty check && uv run pytest --cov=app`
diff --git a/docs/specs/4-architecture/knowledge-map.md b/docs/specs/4-architecture/knowledge-map.md
index 827190d385d..1d206f6eac4 100644
--- a/docs/specs/4-architecture/knowledge-map.md
+++ b/docs/specs/4-architecture/knowledge-map.md
@@ -14,6 +14,16 @@ This document tracks modules, dependencies, and architectural relationships acro
 
 #### Domain Layer
 - **Models** (`app/Models/`) - Eloquent ORM models for database entities
+  - **Person Model** (`app/Models/Person.php`) - Represents an identified individual across multiple photos
+    - Optional 1-to-1 link to a `User` account (claimed person)
+    - `is_searchable` flag — when false, face overlays are hidden from non-owners (privacy mode)
+    - Has many `Face` records
+  - **Face Model** (`app/Models/Face.php`) - A detected face bounding box on a specific photo
+    - Bounding box stored as relative floats (0.0–1.0) in `x`, `y`, `width`, `height`
+    - `crop_token` — opaque token used to serve a cropped face thumbnail via dedicated endpoint
+    - `is_dismissed` — operator/owner has chosen to ignore this face detection
+    - Belongs to `Photo` (cascade delete), belongs to `Person` (null on delete)
+    - Has many `FaceSuggestion` (similar faces ranked by confidence)
   - **Album Model** - Nested set tree structure with pre-computed statistical fields:
     - `num_children` - Count of direct child albums
     - `num_photos` - Count of photos directly in this album (not descendants)
@@ -52,6 +62,7 @@ This document tracks modules, dependencies, and architectural relationships acro
   - `RecomputeAlbumStatsOnAlbumChange` - Dispatches recomputation job for parent album
 - **Jobs** (`app/Jobs/`) - Asynchronous task definitions
   - `RecomputeAlbumStatsJob` - Recomputes album statistics and propagates changes to ancestors
+  - `ScanFacesJob` - Dispatches face detection requests to the Python AI Vision service for a batch of photo IDs; sets `face_scan_status = pending` on dispatch, `scanned` on completion
     - Uses `WithoutOverlapping` middleware (keyed by album_id) to prevent concurrent updates
     - Atomic transaction with 3 retries + exponential backoff
     - Propagates to parent album after successful update (cascades to root)
@@ -75,13 +86,21 @@ This document tracks modules, dependencies, and architectural relationships acro
       - Conditional rendering (hidden when no rated photos)
       - Toggle behavior (click same star to clear)
       - Keyboard accessible (Arrow keys, Enter/Space)
+    - **FaceOverlay** (`photoModule/FaceOverlay.vue`) - Absolutely-positioned bounding boxes over the photo detail view; opens `FaceAssignmentModal` on click of unknown faces
   - Forms, modals, drawers, settings components
+    - **FaceAssignmentModal** - Assign an unknown face to an existing or new Person; shows suggestions ranked by confidence
+    - **SelfieClaimModal** - Upload a selfie to match and claim a Person profile (links Person ↔ User)
+  - Maintenance components
+    - **MaintenanceBulkScanFaces** - Card to trigger a bulk scan of all unscanned photos
 - **Views** (`resources/js/views/`) - Page-level Vue components
   - Gallery views: Albums, Album, Favourites, Flow, Frame, Map, Search
   - Admin views: Settings, Users, Permissions, Maintenance, Diagnostics
+  - People views: **People** (`/people`) — paginated PersonCard grid; **PersonDetail** (`/people/:personId`) — photos grid with edit/delete/merge actions
 - **Composables** (`resources/js/composables/`) - Reusable composition functions
   - Album, photo, search, selection, context menu composables
 - **Services** (`resources/js/services/`) - API communication layer using axios
+  - `people-service.ts` - CRUD for Person; claim/unclaim; merge; selfie upload
+  - `face-detection-service.ts` - Scan photos/albums; assign/dismiss faces; bulk scan
 - **Layouts** (`resources/js/layouts/`) - Photo layout algorithms (square, justified, masonry, grid)
 
 #### State Management
@@ -106,6 +125,14 @@ This document tracks modules, dependencies, and architectural relationships acro
 - **LdapRecord Laravel** - LDAP/Active Directory integration (v3.4.2)
   - Dependency: php-ldap PHP extension required
 
+### External Services
+- **AI Vision Service** (`ai-vision-service/`) - Sidecar Python microservice for facial recognition
+  - Framework: FastAPI + uv package manager
+  - Single shared symmetric API key (`AI_VISION_FACE_API_KEY` in Lychee / `VISION_FACE_API_KEY` in Python) used in both directions via `X-API-Key` header
+  - File access: reads photos from a **shared Docker volume** (no file transfer over HTTP)
+  - Embeddings persisted to a separate named volume (`ai_vision_embeddings`)
+  - Supporter Edition (SE) feature: endpoints return 403 on non-SE instances
+
 ### Frontend Dependencies
 - **Vue3** - Progressive JavaScript framework (Composition API)
 - **TypeScript** - Type-safe JavaScript
@@ -231,6 +258,21 @@ Preserves original camera RAW / HEIC / PSD files as a dedicated size variant whi
 - Resource classes extend Spatie Data (not JsonResource)
 - No Blade views - Vue3 only
 
+### AI Vision Inter-Service Communication
+Lychee uses a **REST + webhook** pattern for facial recognition:
+
+1. **Scan trigger** — Lychee sets `face_scan_status = pending` on photo(s), dispatches `ScanFacesJob`
+2. **Batch HTTP request** — Job sends `POST /detect` to Python service with an array of `{photo_id, file_path}` pairs (file paths resolve to the shared Docker volume mount)
+3. **Async callback** — Python service POSTs results back to Lychee's internal callback endpoint with detected bounding boxes and embedding vectors
+4. **DB write** — Lychee creates `Face` rows and `FaceSuggestion` rows; sets `face_scan_status = scanned`
+5. **Cluster/compare** — On claim or merge, Lychee calls `POST /embeddings/compare` for similarity matching
+
+Shared volume architecture:
+```
+./lychee/uploads  ──►  lychee_api:/app/public/uploads  (read/write)
+                  ──►  ai_vision:/data/photos           (read-only)
+```
+
 ## Cross-Module Contracts
 
 ### API Communication
@@ -256,6 +298,7 @@ Preserves original camera RAW / HEIC / PSD files as a dedicated size variant whi
 ### How-To Guides
 - [Add OAuth Provider](../2-how-to/add-oauth-provider.md) - Step-by-step OAuth integration
 - [Configure Pagination](../2-how-to/configure-pagination.md) - Album and photo pagination settings
+- [Configure Facial Recognition](../2-how-to/configure-facial-recognition.md) - Docker setup, shared volume, environment variables, and permission modes
 - [Translating Lychee](../2-how-to/translating-lychee.md) - Translation guide for developers and translators
 - [Using Renamer](../2-how-to/using-renamer.md) - Filename transformation during import
 
@@ -295,4 +338,4 @@ Preserves original camera RAW / HEIC / PSD files as a dedicated size variant whi
 
 ---
 
-*Last updated: January 14, 2026*
+*Last updated: March 22, 2026*
diff --git a/docs/specs/4-architecture/roadmap.md b/docs/specs/4-architecture/roadmap.md
index 0b469ce7355..3f30bd149d7 100644
--- a/docs/specs/4-architecture/roadmap.md
+++ b/docs/specs/4-architecture/roadmap.md
@@ -6,7 +6,6 @@ High-level planning document for Lychee features and architectural initiatives.
 
 | Feature ID | Name | Status | Priority | Assignee | Started | Updated | Progress |
 |------------|------|--------|----------|----------|---------|---------|----------|
-| 030 | AI Vision Service | Planning | P1 | LycheeOrg | 2026-03-15 | 2026-03-15 | Spec, plan, tasks drafted. 43 tasks across 19 increments (I1–I3 Python service, I4–I12 PHP backend, I13–I18 frontend, I19 docs). Q-030-01 through Q-030-12 resolved. 13 new open questions (Q-030-13 through Q-030-25) — 6 high, 7 medium. I1–I3 can start; I8 blocked on Q-030-13; I10 blocked on Q-030-14, Q-030-15, Q-030-17. |
 | 026 | Album Photo Tag Filter | Ready for Implementation | P2 | LycheeOrg | 2026-03-09 | 2026-03-09 | Spec, plan, tasks complete. 76 tasks across 9 increments (~32h estimated). All open questions resolved. Ready to begin Task 1.1. |
 
 ## Paused Features
@@ -19,6 +18,7 @@ High-level planning document for Lychee features and architectural initiatives.
 
 | Feature ID | Name | Completed | Notes |
 |------------|------|-----------|-------|
+| 030 | AI Vision Service | 2026-03-22 | Facial recognition sidecar service (FastAPI/Python). Python service (I1–I3): detection, embedding, clustering, matching, CI workflow. PHP backend (I4–I12): persons/faces/face_suggestions tables, Person/Face models, PersonResource/FaceResource, CRUD + scan + assign + merge + claim + selfie endpoints, permission matrix (4 modes), ScanFacesJob, CLI commands, admin config keys. Frontend (I13–I19): People/PersonDetail views, PersonCard, FaceOverlay, FaceAssignmentModal, SelfieClaimModal, MaintenanceBulkScanFaces, routes, left menu. All 43 tasks done. Full quality gate: PHPStan 0 errors, php-cs-fixer clean, vue-tsc clean, Python ruff/ty/pytest 51 passed. |
 | 029 | Camera Capture | 2026-03-18 | "Take Photo" in `+` add menu (album and root views). CameraCapture.vue modal: live video → canvas capture → JPEG preview → push to existing UploadPanel queue. Secure-context guard, mobile layout fixes, `Permissions-Policy: camera=(self)` header. No backend changes. |
 | 028 | Search UI Refactor | 2026-05-30 | Full refactor: simple input + collapsible advanced panel (17 fields: title, description, location, tags, date range, type, orientation, rating, EXIF fields). Token assembler/parser composable. No-debounce on-demand search. Auto-scroll to first result. vue-tsc clean, 74 PHP tests passed, PHPStan 0 errors. |
 | 025 | Dynamic Landing Background Options | 2026-03-03 | Spec, plan, tasks completed |
diff --git a/lang/en/left-menu.php b/lang/en/left-menu.php
index ac3d2cc00c9..2126800a311 100644
--- a/lang/en/left-menu.php
+++ b/lang/en/left-menu.php
@@ -24,4 +24,5 @@
     'support' => 'Support',
     'contact' => 'Contact',
     'messages' => 'Messages',
+    'people' => 'People',
 ];
diff --git a/lang/en/maintenance.php b/lang/en/maintenance.php
index 9774cccf29e..8aef02e9fb1 100644
--- a/lang/en/maintenance.php
+++ b/lang/en/maintenance.php
@@ -99,4 +99,7 @@
         'description' => 'Found %d albums without size statistics.<br/><br/>Equivalent to running: php artisan lychee:recompute-album-sizes',
         'button' => 'Compute sizes',
     ],
+    'bulk-scan-faces' => [
+        'description' => 'Queue all photos that have not yet been scanned for facial recognition. Requires the AI Vision service to be running.',
+    ],
 ];
diff --git a/resources/js/components/gallery/PersonCard.vue b/resources/js/components/gallery/PersonCard.vue
index 9a96f28b058..3d1da57dd3e 100644
--- a/resources/js/components/gallery/PersonCard.vue
+++ b/resources/js/components/gallery/PersonCard.vue
@@ -1,5 +1,8 @@
 <template>
-	<Card class="cursor-pointer hover:shadow-lg transition-shadow duration-200" @click="$router.push({ name: 'person', params: { personId: person.id } })">
+	<Card
+		class="cursor-pointer hover:shadow-lg transition-shadow duration-200"
+		@click="$router.push({ name: 'person', params: { personId: person.id } })"
+	>
 		<template #header>
 			<div class="aspect-square overflow-hidden rounded-t-lg bg-surface-800 flex items-center justify-center">
 				<img
@@ -18,9 +21,7 @@
 			</div>
 		</template>
 		<template #content>
-			<div class="text-sm text-muted-color">
-				{{ person.photo_count }} {{ $t("people.photos_label") }}
-			</div>
+			<div class="text-sm text-muted-color">{{ person.photo_count }} {{ $t("people.photos_label") }}</div>
 		</template>
 	</Card>
 </template>
@@ -33,4 +34,3 @@ defineProps<{
 	person: App.Http.Resources.Models.PersonResource;
 }>();
 </script>
-
diff --git a/resources/js/components/gallery/photoModule/PhotoPanel.vue b/resources/js/components/gallery/photoModule/PhotoPanel.vue
index 5b449436e1e..1597c4c7e17 100644
--- a/resources/js/components/gallery/photoModule/PhotoPanel.vue
+++ b/resources/js/components/gallery/photoModule/PhotoPanel.vue
@@ -28,11 +28,11 @@
 			<Overlay v-if="!is_exif_disabled && photoStore.imageViewMode !== ImageViewMode.Pdf" />
 			<PhotoRatingOverlay />
 			<FaceOverlay
-				v-if="photoStore.photo.faces && photoStore.photo.faces.length > 0 || photoStore.photo.hidden_face_count > 0"
+				v-if="(photoStore.photo.faces && photoStore.photo.faces.length > 0) || photoStore.photo.hidden_face_count > 0"
 				:faces="photoStore.photo.faces ?? []"
 				:hidden-face-count="photoStore.photo.hidden_face_count ?? 0"
 				:person-names="{}"
-				@faces-updated="photoStore.reload()"
+				@faces-updated="emits('updated')"
 			/>
 			<Dock
 				v-if="albumStore.rights?.can_edit && !is_photo_edit_open"
diff --git a/resources/js/components/maintenance/MaintenanceBulkScanFaces.vue b/resources/js/components/maintenance/MaintenanceBulkScanFaces.vue
new file mode 100644
index 00000000000..2eeb4ec885c
--- /dev/null
+++ b/resources/js/components/maintenance/MaintenanceBulkScanFaces.vue
@@ -0,0 +1,57 @@
+<template>
+	<Card
+		class="min-h-40 dark:bg-surface-800 shadow shadow-surface-950/30 rounded-lg relative"
+		pt:body:class="min-h-40 h-full"
+		pt:content:class="h-full flex justify-between flex-col"
+	>
+		<template #title>
+			<div class="text-center">
+				{{ $t("people.scan_faces") }}
+			</div>
+		</template>
+		<template #content>
+			<ScrollPanel class="w-full h-40 text-sm text-muted-color">
+				<div class="w-full text-center">{{ $t("maintenance.bulk-scan-faces.description") }}</div>
+				<ProgressSpinner v-if="loading" class="w-full" />
+			</ScrollPanel>
+			<div class="flex gap-4 mt-1">
+				<Button v-if="!loading" severity="primary" class="w-full font-bold border-none" @click="exec">
+					{{ $t("people.scan_faces") }}
+				</Button>
+			</div>
+		</template>
+	</Card>
+</template>
+
+<script setup lang="ts">
+import { ref } from "vue";
+import Button from "primevue/button";
+import Card from "primevue/card";
+import { useToast } from "primevue/usetoast";
+import ProgressSpinner from "primevue/progressspinner";
+import ScrollPanel from "primevue/scrollpanel";
+import { trans } from "laravel-vue-i18n";
+import FaceDetectionService from "@/services/face-detection-service";
+
+const loading = ref(false);
+const toast = useToast();
+
+function exec() {
+	loading.value = true;
+	FaceDetectionService.bulkScan()
+		.then(() => {
+			toast.add({ severity: "success", summary: trans("toasts.success"), detail: trans("people.scan_success"), life: 3000 });
+			loading.value = false;
+		})
+		.catch((e) => {
+			toast.add({ severity: "error", summary: trans("toasts.error"), detail: e.response?.data?.message, life: 3000 });
+			loading.value = false;
+		});
+}
+</script>
+
+<style lang="css" scoped>
+.lychee-dark .p-card {
+	--p-card-background: var(--p-surface-800);
+}
+</style>
diff --git a/resources/js/components/modals/FaceAssignmentModal.vue b/resources/js/components/modals/FaceAssignmentModal.vue
index 46b8bb8cedf..c4a772c265e 100644
--- a/resources/js/components/modals/FaceAssignmentModal.vue
+++ b/resources/js/components/modals/FaceAssignmentModal.vue
@@ -13,9 +13,7 @@
 					<i class="pi pi-user text-4xl text-muted-color" />
 				</div>
 			</div>
-			<div class="text-center text-sm text-muted-color">
-				{{ $t("people.confidence") }}: {{ Math.round(face.confidence * 100) }}%
-			</div>
+			<div class="text-center text-sm text-muted-color">{{ $t("people.confidence") }}: {{ Math.round(face.confidence * 100) }}%</div>
 
 			<!-- Suggestions -->
 			<div v-if="face.suggestions.length > 0" class="flex flex-col gap-2">
@@ -29,12 +27,7 @@
 						size="small"
 						@click="selectSuggestion(suggestion)"
 					>
-						<img
-							v-if="suggestion.crop_url"
-							:src="suggestion.crop_url"
-							class="w-6 h-6 rounded-full object-cover mr-1"
-							alt=""
-						/>
+						<img v-if="suggestion.crop_url" :src="suggestion.crop_url" class="w-6 h-6 rounded-full object-cover mr-1" alt="" />
 						{{ suggestion.person_name ?? $t("people.unknown") }}
 						({{ Math.round(suggestion.confidence * 100) }}%)
 					</Button>
diff --git a/resources/js/components/modals/SelfieClaimModal.vue b/resources/js/components/modals/SelfieClaimModal.vue
new file mode 100644
index 00000000000..9ba744ee5a2
--- /dev/null
+++ b/resources/js/components/modals/SelfieClaimModal.vue
@@ -0,0 +1,136 @@
+<template>
+	<Dialog v-model:visible="visible" modal :header="$t('people.claim_by_selfie')" pt:root:class="border-none w-full max-w-md">
+		<div class="flex flex-col gap-4 p-2">
+			<div class="text-sm text-muted-color text-center">{{ $t("people.claim_by_selfie_description") }}</div>
+
+			<!-- Upload area -->
+			<div
+				v-if="!matchedPerson"
+				class="border-2 border-dashed border-surface-600 rounded-lg p-8 flex flex-col items-center gap-3 cursor-pointer hover:border-primary-400 transition-colors"
+				@click="triggerFileInput"
+				@dragover.prevent
+				@drop.prevent="onDrop"
+			>
+				<i class="pi pi-camera text-4xl text-muted-color" />
+				<div class="text-sm text-muted-color text-center">{{ $t("people.claim_by_selfie_description") }}</div>
+				<Button severity="primary" outlined size="small" :label="$t('gallery.upload') || 'Upload'" />
+				<input ref="fileInput" type="file" accept="image/*" class="hidden" @change="onFileSelected" />
+			</div>
+
+			<!-- Preview file name -->
+			<div v-if="selectedFile && !matchedPerson" class="text-sm text-center text-muted-color">
+				{{ selectedFile.name }}
+			</div>
+
+			<!-- Match result -->
+			<div v-if="matchedPerson" class="flex flex-col items-center gap-4">
+				<div class="w-24 h-24 rounded-full overflow-hidden bg-surface-800 flex items-center justify-center">
+					<img
+						v-if="matchedPerson.representative_crop_url"
+						:src="matchedPerson.representative_crop_url"
+						:alt="matchedPerson.name"
+						class="w-full h-full object-cover"
+					/>
+					<i v-else class="pi pi-user text-4xl text-muted-color" />
+				</div>
+				<div class="text-center">
+					<div class="font-semibold text-lg">{{ matchedPerson.name }}</div>
+					<div class="text-sm text-muted-color">{{ matchedPerson.photo_count }} {{ $t("people.photos_label") }}</div>
+				</div>
+				<div class="text-sm text-success-400">{{ $t("people.claims.success") }}</div>
+			</div>
+
+			<ProgressSpinner v-if="uploading" class="mx-auto w-8 h-8" />
+		</div>
+
+		<template #footer>
+			<div class="flex gap-2 justify-end">
+				<Button :label="$t('gallery.cancel')" severity="secondary" text @click="reset" />
+				<Button
+					v-if="selectedFile && !matchedPerson"
+					:label="$t('people.claim_by_selfie')"
+					severity="primary"
+					:loading="uploading"
+					:disabled="!selectedFile"
+					@click="submit"
+				/>
+				<Button v-if="matchedPerson" :label="$t('gallery.done')" severity="success" @click="visible = false" />
+			</div>
+		</template>
+	</Dialog>
+</template>
+
+<script setup lang="ts">
+import { ref } from "vue";
+import Dialog from "primevue/dialog";
+import Button from "primevue/button";
+import ProgressSpinner from "primevue/progressspinner";
+import { useToast } from "primevue/usetoast";
+import { trans } from "laravel-vue-i18n";
+import PeopleService from "@/services/people-service";
+
+const emits = defineEmits<{
+	claimed: [person: App.Http.Resources.Models.PersonResource];
+}>();
+
+const visible = defineModel<boolean>("visible", { default: false });
+
+const toast = useToast();
+const fileInput = ref<HTMLInputElement | null>(null);
+const selectedFile = ref<File | undefined>(undefined);
+const matchedPerson = ref<App.Http.Resources.Models.PersonResource | undefined>(undefined);
+const uploading = ref(false);
+
+function triggerFileInput() {
+	fileInput.value?.click();
+}
+
+function onFileSelected(event: Event) {
+	const input = event.target as HTMLInputElement;
+	if (input.files && input.files[0]) {
+		selectedFile.value = input.files[0];
+		matchedPerson.value = undefined;
+	}
+}
+
+function onDrop(event: DragEvent) {
+	if (event.dataTransfer?.files[0]) {
+		selectedFile.value = event.dataTransfer.files[0];
+		matchedPerson.value = undefined;
+	}
+}
+
+function submit() {
+	if (!selectedFile.value) {
+		return;
+	}
+	uploading.value = true;
+	PeopleService.claimBySelfie(selectedFile.value)
+		.then((response) => {
+			matchedPerson.value = response.data;
+			emits("claimed", response.data);
+			toast.add({ severity: "success", summary: trans("toasts.success"), detail: trans("people.claims.success"), life: 4000 });
+		})
+		.catch((e) => {
+			const status = e.response?.status;
+			let detail = e.response?.data?.message;
+			if (status === 422) {
+				detail = trans("people.claims.no_face");
+			} else if (status === 404) {
+				detail = trans("people.claims.no_match");
+			} else if (status === 409) {
+				detail = trans("people.claims.already_claimed");
+			}
+			toast.add({ severity: "error", summary: trans("toasts.error"), detail, life: 4000 });
+		})
+		.finally(() => {
+			uploading.value = false;
+		});
+}
+
+function reset() {
+	selectedFile.value = undefined;
+	matchedPerson.value = undefined;
+	visible.value = false;
+}
+</script>
diff --git a/resources/js/composables/contextMenus/leftMenu.ts b/resources/js/composables/contextMenus/leftMenu.ts
index c3696f0185e..b9f8e64fcff 100644
--- a/resources/js/composables/contextMenus/leftMenu.ts
+++ b/resources/js/composables/contextMenus/leftMenu.ts
@@ -87,6 +87,12 @@ export function useLeftMenu(
 				access: user.value?.id !== null,
 				route: "/tags",
 			},
+			{
+				label: "people.title",
+				icon: "pi pi-users",
+				access: user.value?.id !== null,
+				route: "/people",
+			},
 			{
 				label: "gallery.favourites",
 				icon: "pi pi-heart",
diff --git a/resources/js/router/routes.ts b/resources/js/router/routes.ts
index 7c467e820a2..dfdd2883dbc 100644
--- a/resources/js/router/routes.ts
+++ b/resources/js/router/routes.ts
@@ -34,6 +34,8 @@ const BasketList = () => import("@/views/webshop/BasketList.vue");
 const CheckoutPage = () => import("@/views/webshop/CheckoutPage.vue");
 const OrderList = () => import("@/views/webshop/OrderList.vue");
 const OrderDownload = () => import("@/views/webshop/OrderDownload.vue");
+const People = () => import("@/views/People.vue");
+const PersonDetail = () => import("@/views/PersonDetail.vue");
 
 const routes_ = [
 	{
@@ -226,6 +228,17 @@ const routes_ = [
 		component: OrderDownload,
 		props: true,
 	},
+	{
+		name: "people",
+		path: "/people",
+		component: People,
+	},
+	{
+		name: "person",
+		path: "/people/:personId",
+		component: PersonDetail,
+		props: true,
+	},
 ];
 
 if (import.meta.env.MODE === "development" && import.meta.env.VITE_LOCAL_DEV === "true") {
diff --git a/resources/js/services/face-detection-service.ts b/resources/js/services/face-detection-service.ts
index 14d0567e2e7..dbc9ef57bd3 100644
--- a/resources/js/services/face-detection-service.ts
+++ b/resources/js/services/face-detection-service.ts
@@ -3,21 +3,18 @@ import Constants from "./constants";
 
 const FaceDetectionService = {
 	scanPhotos(photoIds: string[]): Promise<AxiosResponse> {
-		return axios.post(`${Constants.getApiUrl()}FaceDetection::scan`, { photo_ids: photoIds });
+		return axios.post(`${Constants.getApiUrl()}FaceDetection/scan`, { photo_ids: photoIds });
 	},
 
 	scanAlbum(albumId: string): Promise<AxiosResponse> {
-		return axios.post(`${Constants.getApiUrl()}FaceDetection::scan`, { album_id: albumId });
+		return axios.post(`${Constants.getApiUrl()}FaceDetection/scan`, { album_id: albumId });
 	},
 
 	bulkScan(): Promise<AxiosResponse> {
-		return axios.post(`${Constants.getApiUrl()}FaceDetection::bulk-scan`, {});
+		return axios.post(`${Constants.getApiUrl()}FaceDetection/bulk-scan`, {});
 	},
 
-	assignFace(
-		faceId: string,
-		data: { person_id?: string; new_person_name?: string },
-	): Promise<AxiosResponse> {
+	assignFace(faceId: string, data: { person_id?: string; new_person_name?: string }): Promise<AxiosResponse> {
 		return axios.post(`${Constants.getApiUrl()}Face/${faceId}/assign`, data);
 	},
 
diff --git a/resources/js/services/people-service.ts b/resources/js/services/people-service.ts
index 8369c64cbe0..dd59e832069 100644
--- a/resources/js/services/people-service.ts
+++ b/resources/js/services/people-service.ts
@@ -10,10 +10,7 @@ const PeopleService = {
 		return axios.get(`${Constants.getApiUrl()}People/${id}`, { data: {} });
 	},
 
-	getPhotos(
-		id: string,
-		page: number = 1,
-	): Promise<AxiosResponse<PaginatedResponse<App.Http.Resources.Models.PhotoResource>>> {
+	getPhotos(id: string, page: number = 1): Promise<AxiosResponse<PaginatedResponse<App.Http.Resources.Models.PhotoResource>>> {
 		return axios.get(`${Constants.getApiUrl()}People/${id}/photos`, { params: { page }, data: {} });
 	},
 
@@ -21,10 +18,7 @@ const PeopleService = {
 		return axios.post(`${Constants.getApiUrl()}People`, { name });
 	},
 
-	update(
-		id: string,
-		data: { name?: string; is_searchable?: boolean },
-	): Promise<AxiosResponse<App.Http.Resources.Models.PersonResource>> {
+	update(id: string, data: { name?: string; is_searchable?: boolean }): Promise<AxiosResponse<App.Http.Resources.Models.PersonResource>> {
 		return axios.patch(`${Constants.getApiUrl()}People/${id}`, data);
 	},
 
diff --git a/resources/js/views/Maintenance.vue b/resources/js/views/Maintenance.vue
index 9c34708ae53..2350c366af4 100644
--- a/resources/js/views/Maintenance.vue
+++ b/resources/js/views/Maintenance.vue
@@ -38,6 +38,7 @@
 		<MaintenanceCleaning path="filesystems.disks.extract-jobs.root" />
 		<MaintenanceCleaning path="filesystems.disks.image-jobs.root" />
 		<MaintenanceCleaning path="filesystems.disks.image-upload.root" />
+		<MaintenanceBulkScanFaces />
 	</div>
 </template>
 <script setup lang="ts">
@@ -59,4 +60,5 @@ import MaintenanceFulfillOrders from "@/components/maintenance/MaintenanceFulfil
 import MaintenanceFulfillPrecompute from "@/components/maintenance/MaintenanceFulfillPrecompute.vue";
 import MaintenanceBackfillAlbumSizes from "@/components/maintenance/MaintenanceBackfillAlbumSizes.vue";
 import MaintenanceFlushQueue from "@/components/maintenance/MaintenanceFlushQueue.vue";
+import MaintenanceBulkScanFaces from "@/components/maintenance/MaintenanceBulkScanFaces.vue";
 </script>
diff --git a/resources/js/views/PersonDetail.vue b/resources/js/views/PersonDetail.vue
index 4ad531a05e0..c538671bfd0 100644
--- a/resources/js/views/PersonDetail.vue
+++ b/resources/js/views/PersonDetail.vue
@@ -20,13 +20,7 @@
 						v-tooltip.bottom="$t('people.person.toggle_searchable')"
 						@click="toggleSearchable"
 					/>
-					<Button
-						icon="pi pi-trash"
-						severity="danger"
-						text
-						v-tooltip.bottom="$t('people.person.delete')"
-						@click="confirmDelete"
-					/>
+					<Button icon="pi pi-trash" severity="danger" text v-tooltip.bottom="$t('people.person.delete')" @click="confirmDelete" />
 				</div>
 			</template>
 		</Toolbar>
@@ -87,7 +81,13 @@
 				<ProgressSpinner class="w-8 h-8" />
 			</div>
 			<div v-if="hasMorePhotos" class="flex justify-center pb-8 mt-4">
-				<Button :label="$t('gallery.load_more') || 'Load more'" severity="secondary" outlined @click="loadMorePhotos" :loading="photosLoadingMore" />
+				<Button
+					:label="$t('gallery.load_more') || 'Load more'"
+					severity="secondary"
+					outlined
+					@click="loadMorePhotos"
+					:loading="photosLoadingMore"
+				/>
 			</div>
 		</template>
 
diff --git a/resources/js/views/Profile.vue b/resources/js/views/Profile.vue
index 1a32ca4d766..a637018e18b 100644
--- a/resources/js/views/Profile.vue
+++ b/resources/js/views/Profile.vue
@@ -15,18 +15,29 @@
 		<SetOauth />
 		<SetSecondFactor v-if="is_webauthn_enabled" />
 		<SetSharedAlbumsVisibility />
+
+		<!-- Selfie claim button -->
+		<div class="flex justify-center mt-6 pb-8">
+			<Button :label="$t('people.claim_by_selfie')" icon="pi pi-camera" severity="secondary" outlined @click="isSelfieOpen = true" />
+		</div>
+		<SelfieClaimModal v-model:visible="isSelfieOpen" />
 	</div>
 </template>
 <script setup lang="ts">
+import { ref } from "vue";
 import Toolbar from "primevue/toolbar";
+import Button from "primevue/button";
 import SetLogin from "@/components/forms/profile/SetLogin.vue";
 import SetSecondFactor from "@/components/forms/profile/SetSecondFactor.vue";
 import SetOauth from "@/components/forms/profile/SetOauth.vue";
 import SetSharedAlbumsVisibility from "@/components/forms/profile/SetSharedAlbumsVisibility.vue";
 import OpenLeftMenu from "@/components/headers/OpenLeftMenu.vue";
+import SelfieClaimModal from "@/components/modals/SelfieClaimModal.vue";
 import { useLycheeStateStore } from "@/stores/LycheeState";
 import { storeToRefs } from "pinia";
 
 const lycheeStore = useLycheeStateStore();
 const { is_webauthn_enabled } = storeToRefs(lycheeStore);
+
+const isSelfieOpen = ref(false);
 </script>

From cafc2504535eedcf3be0b6a5596b0e86f5273823 Mon Sep 17 00:00:00 2001
From: ildyria <beviguier@gmail.com>
Date: Sun, 22 Mar 2026 17:56:07 +0100
Subject: [PATCH 03/10] more fixes

---
 ai-vision-service/app/api/routes.py     | 12 ++++++++++--
 app/Http/Middleware/VerifyCsrfToken.php |  1 +
 2 files changed, 11 insertions(+), 2 deletions(-)

diff --git a/ai-vision-service/app/api/routes.py b/ai-vision-service/app/api/routes.py
index d3c16435f6e..eeb528bc88b 100644
--- a/ai-vision-service/app/api/routes.py
+++ b/ai-vision-service/app/api/routes.py
@@ -213,7 +213,11 @@ async def _run_detection_job(
             response = await client.post(
                 callback_url,
                 json=payload.model_dump(),
-                headers={"X-API-Key": settings.api_key},
+                headers={
+                    "X-API-Key": settings.api_key,
+                    "Content-Type": "application/json",
+                    "Accept": "application/json",
+                },
                 timeout=30.0,
             )
             response.raise_for_status()
@@ -240,7 +244,11 @@ async def _send_error_callback(photo_id: str, error_code: str, message: str, set
             await client.post(
                 callback_url,
                 json=payload.model_dump(),
-                headers={"X-API-Key": settings.api_key},
+                headers={
+                    "X-API-Key": settings.api_key,
+                    "Content-Type": "application/json",
+                    "Accept": "application/json",
+                },
                 timeout=10.0,
             )
     except Exception:
diff --git a/app/Http/Middleware/VerifyCsrfToken.php b/app/Http/Middleware/VerifyCsrfToken.php
index e19c39cae3c..4a2ff857b8c 100644
--- a/app/Http/Middleware/VerifyCsrfToken.php
+++ b/app/Http/Middleware/VerifyCsrfToken.php
@@ -27,6 +27,7 @@ class VerifyCsrfToken extends Middleware
 		'/api/v2/Zip',
 		'/api/v2/Shop/Checkout/Finalize/*',
 		'/api/v2/Photo::random',
+		'/api/v2/FaceDetection/results', // This is only exposed internally and auth with a token.
 	];
 
 	/**

From aa31217f50d198d37835b4de6ec1d9959b510b92 Mon Sep 17 00:00:00 2001
From: ildyria <beviguier@gmail.com>
Date: Sun, 22 Mar 2026 18:13:47 +0100
Subject: [PATCH 04/10] fix table

---
 app/Models/Person.php | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/app/Models/Person.php b/app/Models/Person.php
index 51246b38534..4a250515a7e 100644
--- a/app/Models/Person.php
+++ b/app/Models/Person.php
@@ -38,6 +38,8 @@ class Person extends Model
 	use ThrowsConsistentExceptions;
 	use ToArrayThrowsNotImplemented;
 
+	protected $table = 'persons';
+
 	/**
 	 * @var string The type of the primary key
 	 */

From dff72526bfab012c21fa2464117330624f7049b3 Mon Sep 17 00:00:00 2001
From: ildyria <beviguier@gmail.com>
Date: Sun, 22 Mar 2026 21:15:32 +0100
Subject: [PATCH 05/10] improve

---
 app/Contracts/Http/Requests/HasFace.php       |  16 +++
 app/Contracts/Http/Requests/HasPerson.php     |  16 +++
 .../Controllers/AiVision/FaceController.php   |  24 ++--
 .../AiVision/FaceDetectionController.php      |  54 ++-------
 .../Controllers/AiVision/PeopleController.php |  20 +---
 .../AiVision/PersonClaimController.php        |  21 +---
 .../AiVision/PersonPhotosController.php       |   3 +-
 .../AiVision/SelfieClaimController.php        |   6 +-
 app/Http/Requests/Face/AssignFaceRequest.php  |  38 ++++++-
 app/Http/Requests/Face/BulkScanRequest.php    |  13 ++-
 .../Face/FaceDetectionResultsRequest.php      | 104 ++++++++++++++++++
 app/Http/Requests/Face/ScanPhotosRequest.php  |  27 ++++-
 .../Requests/Face/ToggleDismissedRequest.php  |  36 +++++-
 .../Requests/Person/ClaimPersonRequest.php    |  55 ++++++++-
 .../Requests/Person/ShowPersonRequest.php     |  45 ++++++++
 .../Requests/Person/UnclaimPersonRequest.php  |  65 +++++++++++
 .../Requests/Person/UpdatePersonRequest.php   |  34 ++++--
 app/Http/Requests/Traits/HasFaceTrait.php     |  21 ++++
 app/Http/Requests/Traits/HasPersonTrait.php   |  21 ++++
 app/Jobs/DispatchFaceScanJob.php              |   3 +-
 app/Policies/AiVisionPolicy.php               |  25 +++++
 docker-compose.yaml                           |  18 +--
 routes/web_v2.php                             |   1 +
 23 files changed, 528 insertions(+), 138 deletions(-)
 create mode 100644 app/Contracts/Http/Requests/HasFace.php
 create mode 100644 app/Contracts/Http/Requests/HasPerson.php
 create mode 100644 app/Http/Requests/Face/FaceDetectionResultsRequest.php
 create mode 100644 app/Http/Requests/Person/ShowPersonRequest.php
 create mode 100644 app/Http/Requests/Person/UnclaimPersonRequest.php
 create mode 100644 app/Http/Requests/Traits/HasFaceTrait.php
 create mode 100644 app/Http/Requests/Traits/HasPersonTrait.php

diff --git a/app/Contracts/Http/Requests/HasFace.php b/app/Contracts/Http/Requests/HasFace.php
new file mode 100644
index 00000000000..982cfb79f2e
--- /dev/null
+++ b/app/Contracts/Http/Requests/HasFace.php
@@ -0,0 +1,16 @@
+<?php
+
+/**
+ * SPDX-License-Identifier: MIT
+ * Copyright (c) 2017-2018 Tobias Reich
+ * Copyright (c) 2018-2026 LycheeOrg.
+ */
+
+namespace App\Contracts\Http\Requests;
+
+use App\Models\Face;
+
+interface HasFace
+{
+	public function face(): Face;
+}
diff --git a/app/Contracts/Http/Requests/HasPerson.php b/app/Contracts/Http/Requests/HasPerson.php
new file mode 100644
index 00000000000..26c43450e75
--- /dev/null
+++ b/app/Contracts/Http/Requests/HasPerson.php
@@ -0,0 +1,16 @@
+<?php
+
+/**
+ * SPDX-License-Identifier: MIT
+ * Copyright (c) 2017-2018 Tobias Reich
+ * Copyright (c) 2018-2026 LycheeOrg.
+ */
+
+namespace App\Contracts\Http\Requests;
+
+use App\Models\Person;
+
+interface HasPerson
+{
+	public function person(): Person;
+}
diff --git a/app/Http/Controllers/AiVision/FaceController.php b/app/Http/Controllers/AiVision/FaceController.php
index cc2ded3252f..2535fceb809 100644
--- a/app/Http/Controllers/AiVision/FaceController.php
+++ b/app/Http/Controllers/AiVision/FaceController.php
@@ -16,7 +16,6 @@
 use App\Models\Person;
 use App\Repositories\ConfigManager;
 use Illuminate\Routing\Controller;
-use Illuminate\Support\Facades\Auth;
 use Illuminate\Support\Facades\Storage;
 
 /**
@@ -33,19 +32,17 @@ class FaceController extends Controller
 	 */
 	public function assign(AssignFaceRequest $request, string $id): FaceResource
 	{
-		$face = Face::findOrFail($id);
+		$face = $request->face();
 
-		if ($request->personId() !== null) {
-			$face->person_id = $request->personId();
-		} elseif ($request->newPersonName() !== null) {
-			$is_searchable_default = app(ConfigManager::class)->getValueAsString('ai_vision_face_person_is_searchable_default') === '1';
+		if ($request->person() !== null) {
+			$face->person_id = $request->person()->id;
+		} else {
+			$is_searchable_default = app(ConfigManager::class)->getValueAsBool('ai_vision_face_person_is_searchable_default');
 			$person = new Person();
 			$person->name = $request->newPersonName();
 			$person->is_searchable = $is_searchable_default;
 			$person->save();
 			$face->person_id = $person->id;
-		} else {
-			abort(422, 'Either person_id or new_person_name must be provided.');
 		}
 
 		$face->save();
@@ -61,16 +58,9 @@ public function assign(AssignFaceRequest $request, string $id): FaceResource
 	 *
 	 * @return FaceResource
 	 */
-	public function toggleDismissed(ToggleDismissedRequest $_request, string $id): FaceResource
+	public function toggleDismissed(ToggleDismissedRequest $request, string $id): FaceResource
 	{
-		$face = Face::with('photo')->findOrFail($id);
-		$user = Auth::user();
-
-		// Check ownership: photo owner or admin
-		if (!($user?->may_administrate === true) && $face->photo->owner_id !== $user?->id) {
-			abort(403, 'Only the photo owner or an admin can dismiss faces.');
-		}
-
+		$face = $request->face();
 		$face->is_dismissed = !$face->is_dismissed;
 		$face->save();
 
diff --git a/app/Http/Controllers/AiVision/FaceDetectionController.php b/app/Http/Controllers/AiVision/FaceDetectionController.php
index dfd4da3d0d4..519e8606d24 100644
--- a/app/Http/Controllers/AiVision/FaceDetectionController.php
+++ b/app/Http/Controllers/AiVision/FaceDetectionController.php
@@ -10,19 +10,20 @@
 
 use App\Enum\FaceScanStatus;
 use App\Http\Requests\Face\BulkScanRequest;
+use App\Http\Requests\Face\FaceDetectionResultsRequest;
 use App\Http\Requests\Face\ScanPhotosRequest;
 use App\Jobs\DispatchFaceScanJob;
 use App\Models\Face;
 use App\Models\FaceSuggestion;
 use App\Models\Photo;
 use App\Repositories\ConfigManager;
-use Illuminate\Http\Request;
 use Illuminate\Routing\Controller;
 use Illuminate\Support\Facades\DB;
 use Illuminate\Support\Facades\Log;
 use Illuminate\Support\Facades\Storage;
 use Illuminate\Support\Str;
 use function Safe\base64_decode;
+use Safe\Exceptions\MiscException;
 
 /**
  * Controller for AI Vision face detection scan management.
@@ -46,13 +47,9 @@ class FaceDetectionController extends Controller
 	public function scan(ScanPhotosRequest $request): \Illuminate\Http\Response
 	{
 		$photo_ids = $request->photoIds();
-		$album_id = $request->albumId();
+		$album_id = $request->album()?->id;
 		$force = $request->force();
 
-		if ($photo_ids === null && $album_id === null) {
-			abort(422, 'Either photo_ids or album_id must be provided.');
-		}
-
 		// Collect target photos
 		$query = Photo::query()->select('id');
 
@@ -67,7 +64,7 @@ public function scan(ScanPhotosRequest $request): \Illuminate\Http\Response
 			$query->whereDoesntHave('faces', fn ($q) => $q->whereNotNull('person_id'));
 		}
 
-		$batch_size = (int) app(ConfigManager::class)->getValueAsString('ai_vision_face_scan_batch_size');
+		$batch_size = app(ConfigManager::class)->getValueAsInt('ai_vision_face_scan_batch_size');
 
 		$dispatched = 0;
 		$query->lazyById($batch_size, 'id')->chunk($batch_size)->each(function ($chunk) use (&$dispatched): void {
@@ -96,46 +93,19 @@ public function scan(ScanPhotosRequest $request): \Illuminate\Http\Response
 	 *
 	 * @return array<string,array<array{embedding_id:string,lychee_face_id:string}>>
 	 */
-	public function results(Request $request): array
+	public function results(FaceDetectionResultsRequest $request): array
 	{
-		// Validate API key — exclusive auth for this endpoint
-		$expected_key = config('features.ai-vision.face-api-key', '');
-		$provided_key = $request->header('X-API-Key', '');
-
-		if ($expected_key === '' || $provided_key !== $expected_key) {
-			abort(401, 'Invalid or missing X-API-Key.');
-		}
+		$photo_id = $request->photoId();
 
-		$data = $request->validate([
-			'photo_id' => 'required|string|exists:photos,id',
-			'status' => 'required|string|in:success,error',
-			'faces' => 'sometimes|array',
-			'faces.*.x' => 'required_with:faces|numeric',
-			'faces.*.y' => 'required_with:faces|numeric',
-			'faces.*.width' => 'required_with:faces|numeric',
-			'faces.*.height' => 'required_with:faces|numeric',
-			'faces.*.confidence' => 'required_with:faces|numeric',
-			'faces.*.embedding_id' => 'required_with:faces|string',
-			'faces.*.crop' => 'sometimes|string',
-			'faces.*.suggestions' => 'sometimes|array',
-			'faces.*.suggestions.*.lychee_face_id' => 'required|string',
-			'faces.*.suggestions.*.confidence' => 'required|numeric',
-			'error_code' => 'sometimes|string',
-			'message' => 'sometimes|string',
-		]);
-
-		$photo_id = $data['photo_id'];
-
-		if ($data['status'] === 'error') {
+		if ($request->status() === 'error') {
 			Photo::where('id', '=', $photo_id)->update(['face_scan_status' => FaceScanStatus::FAILED->value]);
-			Log::info("FaceDetectionController::results — photo {$photo_id} face scan failed: " . ($data['message'] ?? 'unknown error'));
+			Log::info("FaceDetectionController::results — photo {$photo_id} face scan failed: " . ($request->message() ?? 'unknown error'));
 
 			return ['faces' => []];
 		}
 
 		// Process success payload
-		$incoming_faces = $data['faces'] ?? [];
-		$mapping = $this->processFaceResults($photo_id, $incoming_faces);
+		$mapping = $this->processFaceResults($photo_id, $request->faces());
 
 		Photo::where('id', '=', $photo_id)->update(['face_scan_status' => FaceScanStatus::COMPLETED->value]);
 
@@ -151,8 +121,8 @@ public function results(Request $request): array
 	 */
 	public function bulkScan(BulkScanRequest $request): \Illuminate\Http\Response
 	{
-		$album_id = $request->albumId();
-		$batch_size = (int) app(ConfigManager::class)->getValueAsString('ai_vision_face_scan_batch_size');
+		$album_id = $request->album()?->id;
+		$batch_size = $request->configs()->getValueAsInt('ai_vision_face_scan_batch_size');
 
 		$query = Photo::query()->select('id')->whereNull('face_scan_status')->orWhere('face_scan_status', '=', FaceScanStatus::FAILED->value);
 
@@ -244,7 +214,7 @@ private function processFaceResults(string $photo_id, array $incoming_faces): ar
 				try {
 					$decoded = base64_decode($face_data['crop']);
 					Storage::disk('images')->put($crop_path, $decoded);
-				} catch (\Safe\Exceptions\MiscException) {
+				} catch (MiscException) {
 					$tok = null;
 				}
 			} else {
diff --git a/app/Http/Controllers/AiVision/PeopleController.php b/app/Http/Controllers/AiVision/PeopleController.php
index 83056aec626..a146fd079f5 100644
--- a/app/Http/Controllers/AiVision/PeopleController.php
+++ b/app/Http/Controllers/AiVision/PeopleController.php
@@ -10,6 +10,7 @@
 
 use App\Http\Requests\Person\DestroyPersonRequest;
 use App\Http\Requests\Person\ListPersonsRequest;
+use App\Http\Requests\Person\ShowPersonRequest;
 use App\Http\Requests\Person\StorePersonRequest;
 use App\Http\Requests\Person\UpdatePersonRequest;
 use App\Http\Resources\Models\PersonResource;
@@ -56,17 +57,9 @@ public function index(ListPersonsRequest $_request): PaginatedDataCollection
 	 *
 	 * @return PersonResource
 	 */
-	public function show(ListPersonsRequest $_request, string $id): PersonResource
+	public function show(ShowPersonRequest $request): PersonResource
 	{
-		$user = Auth::user();
-		$person = Person::findOrFail($id);
-
-		// Non-admin cannot see non-searchable persons unless they are linked to them
-		if (!($user?->may_administrate === true) && !$person->is_searchable && $person->user_id !== $user?->id) {
-			abort(403);
-		}
-
-		return PersonResource::fromModel($person);
+		return PersonResource::fromModel($request->person());
 	}
 
 	/**
@@ -94,14 +87,9 @@ public function store(StorePersonRequest $request): PersonResource
 	 */
 	public function update(UpdatePersonRequest $request): PersonResource
 	{
-		$person = Person::findOrFail($request->personId());
-		$user = Auth::user();
+		$person = $request->person();
 
-		// For searchability toggle, only the linked user or admin can change
 		if ($request->isSearchable() !== null) {
-			if (!($user?->may_administrate === true) && $person->user_id !== $user?->id) {
-				abort(403);
-			}
 			$person->is_searchable = $request->isSearchable();
 		}
 
diff --git a/app/Http/Controllers/AiVision/PersonClaimController.php b/app/Http/Controllers/AiVision/PersonClaimController.php
index 244ca88003f..61574a7d7eb 100644
--- a/app/Http/Controllers/AiVision/PersonClaimController.php
+++ b/app/Http/Controllers/AiVision/PersonClaimController.php
@@ -10,10 +10,10 @@
 
 use App\Http\Requests\Person\ClaimPersonRequest;
 use App\Http\Requests\Person\MergePersonRequest;
+use App\Http\Requests\Person\UnclaimPersonRequest;
 use App\Http\Resources\Models\PersonResource;
 use App\Models\Face;
 use App\Models\Person;
-use App\Repositories\ConfigManager;
 use Illuminate\Routing\Controller;
 use Illuminate\Support\Facades\Auth;
 
@@ -29,18 +29,13 @@ class PersonClaimController extends Controller
 	 *
 	 * @return PersonResource
 	 */
-	public function claim(ClaimPersonRequest $_request, string $id): PersonResource
+	public function claim(ClaimPersonRequest $request, string $id): PersonResource
 	{
 		/** @var \App\Models\User $user */
 		$user = Auth::user();
-		$person = Person::findOrFail($id);
+		$person = $request->person();
 
 		if (!$user->may_administrate) {
-			// Check if user claims are allowed
-			if (app(ConfigManager::class)->getValueAsString('ai_vision_face_allow_user_claim') !== '1') {
-				abort(403, 'User claims are not permitted by the administrator.');
-			}
-
 			// Non-admin: conflict if already claimed by another user
 			if ($person->user_id !== null && $person->user_id !== $user->id) {
 				abort(409, 'This person is already claimed by another user.');
@@ -66,15 +61,9 @@ public function claim(ClaimPersonRequest $_request, string $id): PersonResource
 	 * Unclaim a Person — remove the user_id link.
 	 * Only the linked user or admin can unclaim.
 	 */
-	public function unclaim(ClaimPersonRequest $_request, string $id): void
+	public function unclaim(UnclaimPersonRequest $request, string $id): void
 	{
-		/** @var \App\Models\User $user */
-		$user = Auth::user();
-		$person = Person::findOrFail($id);
-
-		if (!$user->may_administrate && $person->user_id !== $user->id) {
-			abort(403, 'Only the linked user or an admin can unclaim this person.');
-		}
+		$person = $request->person();
 
 		$person->user_id = null;
 		$person->save();
diff --git a/app/Http/Controllers/AiVision/PersonPhotosController.php b/app/Http/Controllers/AiVision/PersonPhotosController.php
index 686b8a76c97..bc85a13c1b0 100644
--- a/app/Http/Controllers/AiVision/PersonPhotosController.php
+++ b/app/Http/Controllers/AiVision/PersonPhotosController.php
@@ -13,6 +13,7 @@
 use App\Models\Photo;
 use Illuminate\Routing\Controller;
 use Illuminate\Support\Facades\Auth;
+use Illuminate\Support\Facades\DB;
 
 /**
  * Controller for listing photos containing faces of a given Person.
@@ -51,7 +52,7 @@ public function index(ListPersonsRequest $_request, string $id)
 			$query->where(function ($q) use ($user): void {
 				// Photos in at least one public album (base_albums.is_public = true)
 				$q->whereExists(function ($sub): void {
-					$sub->select(\Illuminate\Support\Facades\DB::raw(1))
+					$sub->select(DB::raw(1))
 						->from('photo_album')
 						->join('base_albums', 'base_albums.id', '=', 'photo_album.album_id')
 						->whereColumn('photo_album.photo_id', 'photos.id')
diff --git a/app/Http/Controllers/AiVision/SelfieClaimController.php b/app/Http/Controllers/AiVision/SelfieClaimController.php
index effd9229ace..761d5846dd7 100644
--- a/app/Http/Controllers/AiVision/SelfieClaimController.php
+++ b/app/Http/Controllers/AiVision/SelfieClaimController.php
@@ -34,7 +34,7 @@ class SelfieClaimController extends Controller
 	 *
 	 * @return PersonResource
 	 */
-	public function claimBySelfie(SelfieClaimRequest $request): PersonResource
+	public function claimBySelfie(SelfieClaimRequest $request, ConfigManager $config_manager): PersonResource
 	{
 		/** @var \App\Models\User $user */
 		$user = Auth::user();
@@ -75,7 +75,7 @@ public function claimBySelfie(SelfieClaimRequest $request): PersonResource
 			abort(404, 'No matching person found for the selfie.');
 		}
 
-		$threshold = (float) app(ConfigManager::class)->getValueAsString('ai_vision_face_selfie_confidence_threshold');
+		$threshold = (float) $config_manager->getValueAsString('ai_vision_face_selfie_confidence_threshold');
 		$best_match = $matches[0];
 
 		if ($best_match['confidence'] < $threshold) {
@@ -102,7 +102,7 @@ public function claimBySelfie(SelfieClaimRequest $request): PersonResource
 		}
 
 		// Check if user claims are allowed
-		if (!$user->may_administrate && app(ConfigManager::class)->getValueAsString('ai_vision_face_allow_user_claim') !== '1') {
+		if (!$user->may_administrate && !$config_manager->getValueAsBool('ai_vision_face_allow_user_claim')) {
 			abort(403, 'User claims are not permitted by the administrator.');
 		}
 
diff --git a/app/Http/Requests/Face/AssignFaceRequest.php b/app/Http/Requests/Face/AssignFaceRequest.php
index 45d9e75fdc7..6745c30c334 100644
--- a/app/Http/Requests/Face/AssignFaceRequest.php
+++ b/app/Http/Requests/Face/AssignFaceRequest.php
@@ -8,14 +8,20 @@
 
 namespace App\Http\Requests\Face;
 
+use App\Contracts\Http\Requests\HasFace;
 use App\Http\Requests\BaseApiRequest;
+use App\Http\Requests\Traits\HasFaceTrait;
 use App\Models\Face;
+use App\Models\Person;
 use App\Policies\AiVisionPolicy;
+use App\Rules\RandomIDRule;
 use Illuminate\Support\Facades\Gate;
 
-class AssignFaceRequest extends BaseApiRequest
+class AssignFaceRequest extends BaseApiRequest implements HasFace
 {
-	private ?string $person_id;
+	use HasFaceTrait;
+
+	private ?Person $person;
 	private ?string $new_person_name;
 
 	public function authorize(): bool
@@ -26,20 +32,42 @@ public function authorize(): bool
 	public function rules(): array
 	{
 		return [
+			'id' => ['required', new RandomIDRule(false)],
 			'person_id' => ['nullable', 'string', 'exists:persons,id'],
 			'new_person_name' => ['nullable', 'string', 'max:255'],
 		];
 	}
 
+	public function withValidator(\Illuminate\Validation\Validator $validator): void
+	{
+		$validator->after(function (\Illuminate\Validation\Validator $validator): void {
+			if ($validator->errors()->isNotEmpty()) {
+				return;
+			}
+
+			$values = $validator->validated();
+			if (($values['person_id'] ?? null) === null && ($values['new_person_name'] ?? null) === null) {
+				$validator->errors()->add('person_id', 'Either person_id or new_person_name must be provided.');
+			}
+		});
+	}
+
+	protected function prepareForValidation(): void
+	{
+		/** @disregard */
+		$this->merge(['id' => $this->route('id')]);
+	}
+
 	protected function processValidatedValues(array $values, array $files): void
 	{
-		$this->person_id = $values['person_id'] ?? null;
+		$this->face = Face::findOrFail($values['id']);
+		$this->person = isset($values['person_id']) ? Person::find($values['person_id']) : null;
 		$this->new_person_name = $values['new_person_name'] ?? null;
 	}
 
-	public function personId(): ?string
+	public function person(): ?Person
 	{
-		return $this->person_id;
+		return $this->person;
 	}
 
 	public function newPersonName(): ?string
diff --git a/app/Http/Requests/Face/BulkScanRequest.php b/app/Http/Requests/Face/BulkScanRequest.php
index 0a62d0fb955..180eb82d81d 100644
--- a/app/Http/Requests/Face/BulkScanRequest.php
+++ b/app/Http/Requests/Face/BulkScanRequest.php
@@ -9,8 +9,10 @@
 namespace App\Http\Requests\Face;
 
 use App\Http\Requests\BaseApiRequest;
+use App\Models\Album;
 use App\Models\Configs;
 use App\Policies\SettingsPolicy;
+use App\Rules\RandomIDRule;
 use Illuminate\Support\Facades\Gate;
 
 /**
@@ -20,7 +22,7 @@
  */
 class BulkScanRequest extends BaseApiRequest
 {
-	private ?string $album_id = null;
+	private ?Album $album = null;
 
 	/**
 	 * {@inheritDoc}
@@ -36,7 +38,7 @@ public function authorize(): bool
 	public function rules(): array
 	{
 		return [
-			'album_id' => 'nullable|string|exists:albums,id',
+			'album_id' => ['nullable', new RandomIDRule(true)],
 		];
 	}
 
@@ -45,11 +47,12 @@ public function rules(): array
 	 */
 	protected function processValidatedValues(array $values, array $files): void
 	{
-		$this->album_id = $values['album_id'] ?? null;
+		$album_id = $values['album_id'] ?? null;
+		$this->album = $album_id !== null ? Album::findOrFail($album_id) : null;
 	}
 
-	public function albumId(): ?string
+	public function album(): ?Album
 	{
-		return $this->album_id;
+		return $this->album;
 	}
 }
diff --git a/app/Http/Requests/Face/FaceDetectionResultsRequest.php b/app/Http/Requests/Face/FaceDetectionResultsRequest.php
new file mode 100644
index 00000000000..cb901cb6948
--- /dev/null
+++ b/app/Http/Requests/Face/FaceDetectionResultsRequest.php
@@ -0,0 +1,104 @@
+<?php
+
+/**
+ * SPDX-License-Identifier: MIT
+ * Copyright (c) 2017-2018 Tobias Reich
+ * Copyright (c) 2018-2026 LycheeOrg.
+ */
+
+namespace App\Http\Requests\Face;
+
+use App\Http\Requests\BaseApiRequest;
+
+/**
+ * Request for receiving face detection results from the Python AI Vision service.
+ * Authentication is exclusively via X-API-Key header; no user session required.
+ *
+ * POST /api/v2/FaceDetection/results
+ */
+class FaceDetectionResultsRequest extends BaseApiRequest
+{
+	private string $photo_id;
+	private string $status;
+	/** @var array<array{x:float,y:float,width:float,height:float,confidence:float,embedding_id:string,crop?:string,suggestions?:array<array{lychee_face_id:string,confidence:float}>}> */
+	private array $faces = [];
+	private ?string $error_code = null;
+	private ?string $message = null;
+
+	/**
+	 * {@inheritDoc}
+	 *
+	 * Validates the X-API-Key header against the configured secret.
+	 */
+	public function authorize(): bool
+	{
+		$expected_key = config('features.ai-vision.face-api-key', '');
+		$provided_key = $this->header('X-API-Key', '');
+
+		return $expected_key !== '' && $provided_key === $expected_key;
+	}
+
+	/**
+	 * {@inheritDoc}
+	 */
+	public function rules(): array
+	{
+		return [
+			'photo_id' => 'required|string|exists:photos,id',
+			'status' => 'required|string|in:success,error',
+			'faces' => 'sometimes|array',
+			'faces.*.x' => 'required_with:faces|numeric',
+			'faces.*.y' => 'required_with:faces|numeric',
+			'faces.*.width' => 'required_with:faces|numeric',
+			'faces.*.height' => 'required_with:faces|numeric',
+			'faces.*.confidence' => 'required_with:faces|numeric',
+			'faces.*.embedding_id' => 'required_with:faces|string',
+			'faces.*.crop' => 'sometimes|string',
+			'faces.*.suggestions' => 'sometimes|array',
+			'faces.*.suggestions.*.lychee_face_id' => 'required|string',
+			'faces.*.suggestions.*.confidence' => 'required|numeric',
+			'error_code' => 'sometimes|string',
+			'message' => 'sometimes|string',
+		];
+	}
+
+	/**
+	 * {@inheritDoc}
+	 */
+	protected function processValidatedValues(array $values, array $files): void
+	{
+		$this->photo_id = $values['photo_id'];
+		$this->status = $values['status'];
+		$this->faces = $values['faces'] ?? [];
+		$this->error_code = $values['error_code'] ?? null;
+		$this->message = $values['message'] ?? null;
+	}
+
+	public function photoId(): string
+	{
+		return $this->photo_id;
+	}
+
+	public function status(): string
+	{
+		return $this->status;
+	}
+
+	/**
+	 * @return array<array{x:float,y:float,width:float,height:float,confidence:float,embedding_id:string,crop?:string,suggestions?:array<array{lychee_face_id:string,confidence:float}>}>
+	 */
+	public function faces(): array
+	{
+		return $this->faces;
+	}
+
+	public function errorCode(): ?string
+	{
+		return $this->error_code;
+	}
+
+	public function message(): ?string
+	{
+		return $this->message;
+	}
+}
diff --git a/app/Http/Requests/Face/ScanPhotosRequest.php b/app/Http/Requests/Face/ScanPhotosRequest.php
index afda811d80f..872afab33ea 100644
--- a/app/Http/Requests/Face/ScanPhotosRequest.php
+++ b/app/Http/Requests/Face/ScanPhotosRequest.php
@@ -11,6 +11,7 @@
 use App\Http\Requests\BaseApiRequest;
 use App\Models\Album;
 use App\Policies\AiVisionPolicy;
+use App\Rules\RandomIDRule;
 use Illuminate\Support\Facades\Gate;
 
 /**
@@ -21,7 +22,7 @@
 class ScanPhotosRequest extends BaseApiRequest
 {
 	private ?array $photo_ids = null;
-	private ?string $album_id = null;
+	private ?Album $album = null;
 	private bool $force = false;
 
 	/**
@@ -39,19 +40,33 @@ public function rules(): array
 	{
 		return [
 			'photo_ids' => 'nullable|array',
-			'photo_ids.*' => 'string|exists:photos,id',
-			'album_id' => 'nullable|string|exists:albums,id',
+			'photo_ids.*' => ['string', new RandomIDRule(false)],
+			'album_id' => ['nullable', new RandomIDRule(true)],
 			'force' => 'sometimes|boolean',
 		];
 	}
 
+	/**
+	 * {@inheritDoc}
+	 */
+	public function withValidator(\Illuminate\Validation\Validator $validator): void
+	{
+		$validator->after(function (\Illuminate\Validation\Validator $validator): void {
+			$values = $validator->validated();
+			if (($values['photo_ids'] ?? null) === null && ($values['album_id'] ?? null) === null) {
+				$validator->errors()->add('photo_ids', 'Either photo_ids or album_id must be provided.');
+			}
+		});
+	}
+
 	/**
 	 * {@inheritDoc}
 	 */
 	protected function processValidatedValues(array $values, array $files): void
 	{
 		$this->photo_ids = $values['photo_ids'] ?? null;
-		$this->album_id = $values['album_id'] ?? null;
+		$album_id = $values['album_id'] ?? null;
+		$this->album = $album_id !== null ? Album::findOrFail($album_id) : null;
 		$this->force = isset($values['force']) && static::toBoolean($values['force']);
 	}
 
@@ -63,9 +78,9 @@ public function photoIds(): ?array
 		return $this->photo_ids;
 	}
 
-	public function albumId(): ?string
+	public function album(): ?Album
 	{
-		return $this->album_id;
+		return $this->album;
 	}
 
 	public function force(): bool
diff --git a/app/Http/Requests/Face/ToggleDismissedRequest.php b/app/Http/Requests/Face/ToggleDismissedRequest.php
index 8ec4639b69f..632366e6f07 100644
--- a/app/Http/Requests/Face/ToggleDismissedRequest.php
+++ b/app/Http/Requests/Face/ToggleDismissedRequest.php
@@ -8,15 +8,45 @@
 
 namespace App\Http\Requests\Face;
 
-use App\Http\Requests\AbstractEmptyRequest;
+use App\Contracts\Http\Requests\HasFace;
+use App\Http\Requests\BaseApiRequest;
+use App\Http\Requests\Traits\HasFaceTrait;
 use App\Models\Face;
 use App\Policies\AiVisionPolicy;
+use App\Rules\RandomIDRule;
+use Illuminate\Support\Facades\Auth;
 use Illuminate\Support\Facades\Gate;
 
-class ToggleDismissedRequest extends AbstractEmptyRequest
+class ToggleDismissedRequest extends BaseApiRequest implements HasFace
 {
+	use HasFaceTrait;
+
 	public function authorize(): bool
 	{
-		return Gate::check(AiVisionPolicy::CAN_DISMISS_FACE, Face::class);
+		if (!Gate::check(AiVisionPolicy::CAN_DISMISS_FACE, Face::class)) {
+			return false;
+		}
+
+		$user = Auth::user();
+
+		return ($user?->may_administrate === true) || $this->face->photo->owner_id === $user?->id;
+	}
+
+	public function rules(): array
+	{
+		return [
+			'id' => ['required', new RandomIDRule(false)],
+		];
+	}
+
+	protected function prepareForValidation(): void
+	{
+		/** @disregard */
+		$this->merge(['id' => $this->route('id')]);
+	}
+
+	protected function processValidatedValues(array $values, array $files): void
+	{
+		$this->face = Face::with('photo')->findOrFail($values['id']);
 	}
 }
diff --git a/app/Http/Requests/Person/ClaimPersonRequest.php b/app/Http/Requests/Person/ClaimPersonRequest.php
index b09501f29e8..1b6eab3b088 100644
--- a/app/Http/Requests/Person/ClaimPersonRequest.php
+++ b/app/Http/Requests/Person/ClaimPersonRequest.php
@@ -8,15 +8,64 @@
 
 namespace App\Http\Requests\Person;
 
-use App\Http\Requests\AbstractEmptyRequest;
+use App\Contracts\Http\Requests\HasPerson;
+use App\Http\Requests\BaseApiRequest;
+use App\Http\Requests\Traits\HasPersonTrait;
 use App\Models\Person;
 use App\Policies\AiVisionPolicy;
+use App\Repositories\ConfigManager;
+use App\Rules\RandomIDRule;
+use Illuminate\Support\Facades\Auth;
 use Illuminate\Support\Facades\Gate;
 
-class ClaimPersonRequest extends AbstractEmptyRequest
+class ClaimPersonRequest extends BaseApiRequest implements HasPerson
 {
+	use HasPersonTrait;
+
+	/**
+	 * {@inheritDoc}
+	 */
 	public function authorize(): bool
 	{
-		return Gate::check(AiVisionPolicy::CAN_CLAIM_PERSON, Person::class);
+		if (!Gate::check(AiVisionPolicy::CAN_CLAIM_PERSON, Person::class)) {
+			return false;
+		}
+
+		/** @var \App\Models\User $user */
+		$user = Auth::user();
+		if ($user->may_administrate) {
+			// Admin can always claim (force-claim)
+			return true;
+		}
+
+		// Non-admin: check if user claims are allowed by the administrator
+		return app(ConfigManager::class)->getValueAsBool('ai_vision_face_allow_user_claim');
+	}
+
+	/**
+	 * {@inheritDoc}
+	 */
+	public function rules(): array
+	{
+		return [
+			'id' => ['required', new RandomIDRule(false)],
+		];
+	}
+
+	/**
+	 * {@inheritDoc}
+	 */
+	protected function prepareForValidation(): void
+	{
+		/** @disregard */
+		$this->merge(['id' => $this->route('id')]);
+	}
+
+	/**
+	 * {@inheritDoc}
+	 */
+	protected function processValidatedValues(array $values, array $files): void
+	{
+		$this->person = Person::findOrFail($values['id']);
 	}
 }
diff --git a/app/Http/Requests/Person/ShowPersonRequest.php b/app/Http/Requests/Person/ShowPersonRequest.php
new file mode 100644
index 00000000000..e52c7b42527
--- /dev/null
+++ b/app/Http/Requests/Person/ShowPersonRequest.php
@@ -0,0 +1,45 @@
+<?php
+
+/**
+ * SPDX-License-Identifier: MIT
+ * Copyright (c) 2017-2018 Tobias Reich
+ * Copyright (c) 2018-2026 LycheeOrg.
+ */
+
+namespace App\Http\Requests\Person;
+
+use App\Contracts\Http\Requests\HasPerson;
+use App\Http\Requests\BaseApiRequest;
+use App\Http\Requests\Traits\HasPersonTrait;
+use App\Models\Person;
+use App\Policies\AiVisionPolicy;
+use App\Rules\RandomIDRule;
+use Illuminate\Support\Facades\Gate;
+
+class ShowPersonRequest extends BaseApiRequest implements HasPerson
+{
+	use HasPersonTrait;
+
+	public function authorize(): bool
+	{
+		return Gate::check(AiVisionPolicy::CAN_SHOW_PERSON, [Person::class, $this->person]);
+	}
+
+	public function rules(): array
+	{
+		return [
+			'id' => ['required', new RandomIDRule(false)],
+		];
+	}
+
+	protected function prepareForValidation(): void
+	{
+		/** @disregard */
+		$this->merge(['id' => $this->route('id')]);
+	}
+
+	protected function processValidatedValues(array $values, array $files): void
+	{
+		$this->person = Person::findOrFail($values['id']);
+	}
+}
diff --git a/app/Http/Requests/Person/UnclaimPersonRequest.php b/app/Http/Requests/Person/UnclaimPersonRequest.php
new file mode 100644
index 00000000000..18b61843810
--- /dev/null
+++ b/app/Http/Requests/Person/UnclaimPersonRequest.php
@@ -0,0 +1,65 @@
+<?php
+
+/**
+ * SPDX-License-Identifier: MIT
+ * Copyright (c) 2017-2018 Tobias Reich
+ * Copyright (c) 2018-2026 LycheeOrg.
+ */
+
+namespace App\Http\Requests\Person;
+
+use App\Contracts\Http\Requests\HasPerson;
+use App\Http\Requests\BaseApiRequest;
+use App\Http\Requests\Traits\HasPersonTrait;
+use App\Models\Person;
+use App\Policies\AiVisionPolicy;
+use App\Rules\RandomIDRule;
+use Illuminate\Support\Facades\Auth;
+use Illuminate\Support\Facades\Gate;
+
+class UnclaimPersonRequest extends BaseApiRequest implements HasPerson
+{
+	use HasPersonTrait;
+
+	/**
+	 * {@inheritDoc}
+	 */
+	public function authorize(): bool
+	{
+		if (!Gate::check(AiVisionPolicy::CAN_CLAIM_PERSON, Person::class)) {
+			return false;
+		}
+
+		/** @var \App\Models\User $user */
+		$user = Auth::user();
+
+		return $user->may_administrate || $this->person->user_id === $user->id;
+	}
+
+	/**
+	 * {@inheritDoc}
+	 */
+	public function rules(): array
+	{
+		return [
+			'id' => ['required', new RandomIDRule(false)],
+		];
+	}
+
+	/**
+	 * {@inheritDoc}
+	 */
+	protected function prepareForValidation(): void
+	{
+		/** @disregard */
+		$this->merge(['id' => $this->route('id')]);
+	}
+
+	/**
+	 * {@inheritDoc}
+	 */
+	protected function processValidatedValues(array $values, array $files): void
+	{
+		$this->person = Person::findOrFail($values['id']);
+	}
+}
diff --git a/app/Http/Requests/Person/UpdatePersonRequest.php b/app/Http/Requests/Person/UpdatePersonRequest.php
index 20799b71afd..4b9741e139b 100644
--- a/app/Http/Requests/Person/UpdatePersonRequest.php
+++ b/app/Http/Requests/Person/UpdatePersonRequest.php
@@ -8,41 +8,55 @@
 
 namespace App\Http\Requests\Person;
 
+use App\Contracts\Http\Requests\HasPerson;
 use App\Http\Requests\BaseApiRequest;
+use App\Http\Requests\Traits\HasPersonTrait;
 use App\Models\Person;
 use App\Policies\AiVisionPolicy;
+use App\Rules\RandomIDRule;
 use Illuminate\Support\Facades\Gate;
 
-class UpdatePersonRequest extends BaseApiRequest
+class UpdatePersonRequest extends BaseApiRequest implements HasPerson
 {
-	private string $person_id;
+	use HasPersonTrait;
+
 	private ?string $name;
 	private ?bool $is_searchable;
 
 	public function authorize(): bool
 	{
-		return Gate::check(AiVisionPolicy::CAN_EDIT_PERSON, Person::class);
+		if (!Gate::check(AiVisionPolicy::CAN_EDIT_PERSON, Person::class)) {
+			return false;
+		}
+
+		if ($this->is_searchable !== null &&
+			!Gate::check(AiVisionPolicy::CAN_CHANGE_PERSON_SEARCHABILITY, [Person::class, $this->person])) {
+			return false;
+		}
+
+		return true;
 	}
 
 	public function rules(): array
 	{
 		return [
-			'person_id' => ['required', 'string', 'exists:persons,id'],
+			'id' => ['required', new RandomIDRule(false)],
 			'name' => ['sometimes', 'string', 'max:255'],
 			'is_searchable' => ['sometimes', 'boolean'],
 		];
 	}
 
-	protected function processValidatedValues(array $values, array $files): void
+	protected function prepareForValidation(): void
 	{
-		$this->person_id = $values['person_id'];
-		$this->name = $values['name'] ?? null;
-		$this->is_searchable = isset($values['is_searchable']) ? static::toBoolean($values['is_searchable']) : null;
+		/** @disregard */
+		$this->merge(['id' => $this->route('id')]);
 	}
 
-	public function personId(): string
+	protected function processValidatedValues(array $values, array $files): void
 	{
-		return $this->person_id;
+		$this->person = Person::findOrFail($values['id']);
+		$this->name = $values['name'] ?? null;
+		$this->is_searchable = isset($values['is_searchable']) ? static::toBoolean($values['is_searchable']) : null;
 	}
 
 	public function name(): ?string
diff --git a/app/Http/Requests/Traits/HasFaceTrait.php b/app/Http/Requests/Traits/HasFaceTrait.php
new file mode 100644
index 00000000000..76000a122f6
--- /dev/null
+++ b/app/Http/Requests/Traits/HasFaceTrait.php
@@ -0,0 +1,21 @@
+<?php
+
+/**
+ * SPDX-License-Identifier: MIT
+ * Copyright (c) 2017-2018 Tobias Reich
+ * Copyright (c) 2018-2026 LycheeOrg.
+ */
+
+namespace App\Http\Requests\Traits;
+
+use App\Models\Face;
+
+trait HasFaceTrait
+{
+	protected Face $face;
+
+	public function face(): Face
+	{
+		return $this->face;
+	}
+}
diff --git a/app/Http/Requests/Traits/HasPersonTrait.php b/app/Http/Requests/Traits/HasPersonTrait.php
new file mode 100644
index 00000000000..93822fd8800
--- /dev/null
+++ b/app/Http/Requests/Traits/HasPersonTrait.php
@@ -0,0 +1,21 @@
+<?php
+
+/**
+ * SPDX-License-Identifier: MIT
+ * Copyright (c) 2017-2018 Tobias Reich
+ * Copyright (c) 2018-2026 LycheeOrg.
+ */
+
+namespace App\Http\Requests\Traits;
+
+use App\Models\Person;
+
+trait HasPersonTrait
+{
+	protected Person $person;
+
+	public function person(): Person
+	{
+		return $this->person;
+	}
+}
diff --git a/app/Jobs/DispatchFaceScanJob.php b/app/Jobs/DispatchFaceScanJob.php
index 370f72dfc8b..54f57224818 100644
--- a/app/Jobs/DispatchFaceScanJob.php
+++ b/app/Jobs/DispatchFaceScanJob.php
@@ -17,7 +17,6 @@
 use Illuminate\Queue\SerializesModels;
 use Illuminate\Support\Facades\Http;
 use Illuminate\Support\Facades\Log;
-use Illuminate\Support\Facades\Storage;
 
 /**
  * Dispatches a single photo to the AI Vision Python service for face detection.
@@ -80,7 +79,7 @@ public function handle(): void
 				->post($service_url . '/detect', $data);
 
 			if (!$response->successful()) {
-				Log::warning("DispatchFaceScanJob: /detect returned HTTP {$response->status()} for photo {$this->photo_id}.", ['data' => $data,'response' => $response->json()]);
+				Log::warning("DispatchFaceScanJob: /detect returned HTTP {$response->status()} for photo {$this->photo_id}.", ['data' => $data, 'response' => $response->json()]);
 				$photo->face_scan_status = FaceScanStatus::FAILED;
 				$photo->save();
 			}
diff --git a/app/Policies/AiVisionPolicy.php b/app/Policies/AiVisionPolicy.php
index 5f5dd3444d7..b97a38fcd7e 100644
--- a/app/Policies/AiVisionPolicy.php
+++ b/app/Policies/AiVisionPolicy.php
@@ -31,12 +31,14 @@
 class AiVisionPolicy extends BasePolicy
 {
 	public const CAN_VIEW_PEOPLE = 'canViewPeople';
+	public const CAN_SHOW_PERSON = 'canShowPerson';
 	public const CAN_EDIT_PERSON = 'canEditPerson';
 	public const CAN_ASSIGN_FACE = 'canAssignFace';
 	public const CAN_TRIGGER_SCAN = 'canTriggerScan';
 	public const CAN_CLAIM_PERSON = 'canClaimPerson';
 	public const CAN_MERGE_PERSONS = 'canMergePersons';
 	public const CAN_DISMISS_FACE = 'canDismissFace';
+	public const CAN_CHANGE_PERSON_SEARCHABILITY = 'canChangePersonSearchability';
 
 	/**
 	 * Get the current permission mode from configuration.
@@ -62,6 +64,20 @@ public function canViewPeople(?User $user): bool
 		};
 	}
 
+	/**
+	 * View a specific Person record.
+	 * Requires canViewPeople access, plus the person must be searchable or linked to the user.
+	 * Admins always pass via before().
+	 */
+	public function canShowPerson(?User $user, Person $person): bool
+	{
+		if (!$this->canViewPeople($user)) {
+			return false;
+		}
+
+		return $person->is_searchable || $person->user_id === $user?->id;
+	}
+
 	/**
 	 * Create/edit Person.
 	 * public: logged; private: logged; privacy-preserving: owner+admin; restricted: admin only.
@@ -144,4 +160,13 @@ public function canManagePerson(?User $user, Person $person): bool
 
 		return $person->user_id === $user->id;
 	}
+
+	/**
+	 * Change the is_searchable flag of a Person.
+	 * Only the person's linked user or admin (via before()) may toggle it.
+	 */
+	public function canChangePersonSearchability(?User $user, Person $person): bool
+	{
+		return $person->user_id === $user?->id;
+	}
 }
diff --git a/docker-compose.yaml b/docker-compose.yaml
index b0a27794d93..b9c20514290 100644
--- a/docker-compose.yaml
+++ b/docker-compose.yaml
@@ -26,10 +26,10 @@ x-base-lychee-setup: &base-lychee-setup
   # There are also other images available which uses nginx as a base instead of FrankenPHP:
   # - ghcr.io/lycheeorg/lychee:latest-legacy
   # - ghcr.io/lycheeorg/lychee:edge-legacy
-  image: ghcr.io/lycheeorg/lychee:latest
+  # image: ghcr.io/lycheeorg/lychee:latest
 
   # The following lines are for development purposes only.
-  # image: lychee-frankenphp:latest
+  image: lychee-frankenphp
   # image: lychee-legacy:latest
   # build:
   #   context: ./app
@@ -219,7 +219,7 @@ x-common-env: &common-env
   #
   # For improved reactivity of Lychee we recommend to use a worker.
   # You can use either 'database' or 'redis' as queue driver (but in the later you need to enable redis).
-  # QUEUE_CONNECTION: "${QUEUE_CONNECTION:-database}"
+  QUEUE_CONNECTION: "${QUEUE_CONNECTION:-database}"
 
   # Logging Stuff.
   # LOG_CHANNEL: "${LOG_CHANNEL:-stack}"
@@ -560,23 +560,23 @@ services:
       - "${APP_PORT_AI_FACE:-8001}"
     ports:
       - "${APP_PORT_AI_FACE:-8001}:8000"
-    build:
-      context: ./ai-vision-service
-    container_name: lychee-ai-vision
+    # build:
+    #   context: ./ai-vision-service
+    # container_name: lychee-ai-vision
+    image: lychee-ai-vision
     restart: unless-stopped
     security_opt:
       - no-new-privileges:true
     cap_drop:
       - ALL
     environment:
-      VISION_FACE_LYCHEE_API_URL: "http://localhost:443"
+      VISION_FACE_LYCHEE_API_URL: "http://lychee_api:8000"
       VISION_FACE_API_KEY: "${AI_VISION_API_KEY:-changeme}"
       VISION_FACE_PHOTOS_PATH: "/data/photos"
       VISION_FACE_STORAGE_PATH: "/data/embeddings"
       VISION_FACE_WORKERS: "${AI_VISION_WORKERS:-1}"
     volumes:
-      # - ./lychee/uploads:/data/photos:ro
-      - ./public/uploads:/data/photos:ro
+      - ./lychee/uploads:/data/photos:ro
       - ai_vision_embeddings:/data/embeddings
     networks:
       - lychee
diff --git a/routes/web_v2.php b/routes/web_v2.php
index 98a8ee23991..46308a4efc4 100644
--- a/routes/web_v2.php
+++ b/routes/web_v2.php
@@ -79,6 +79,7 @@
 Route::get('/login', VueController::class)->middleware(['migration:complete']);
 Route::get('/register', VueController::class)->name('register')->middleware(['migration:complete']);
 
+Route::get('/people', VueController::class)->middleware(['migration:complete']);
 Route::get('/settings', VueController::class)->middleware(['migration:complete', 'login_required:always']);
 Route::get('/permissions', VueController::class)->middleware(['migration:complete', 'login_required:always']);
 Route::get('/fixTree', VueController::class)->middleware(['migration:complete', 'login_required:always']);

From c4bf2b02d4d4b983b1ad1db89b8d6299d6e8e544 Mon Sep 17 00:00:00 2001
From: ildyria <beviguier@gmail.com>
Date: Mon, 23 Mar 2026 17:13:29 +0100
Subject: [PATCH 06/10] WIP

---
 .dockerignore                                 |    6 +
 .../AiVision/PersonPhotosController.php       |   21 +-
 app/Http/Resources/Models/FaceResource.php    |    2 +
 app/Http/Resources/Models/PhotoResource.php   |   59 +
 app/Repositories/PhotoRepository.php          |    2 +-
 docker-compose.yaml                           |   16 +
 .../gallery/photoModule/FaceOverlay.vue       |    6 +-
 .../gallery/photoModule/PhotoBox.vue          |   50 +-
 .../gallery/photoModule/PhotoPanel.vue        |    8 -
 .../components/modals/FaceAssignmentModal.vue |   16 +-
 resources/js/lychee.d.ts                      | 2227 ++++++++---------
 resources/js/services/people-service.ts       |   16 +-
 12 files changed, 1230 insertions(+), 1199 deletions(-)

diff --git a/.dockerignore b/.dockerignore
index 89fe7008049..018f26f7bb1 100644
--- a/.dockerignore
+++ b/.dockerignore
@@ -48,6 +48,8 @@ vite/*
 secrets/*
 # Local testing @ildyria
 public/uploads-bck/*
+public/uploads/*
+*.sql
 
 # Node
 node_modules/
@@ -56,8 +58,12 @@ npm-debug.log
 # Mapping for database and config used by docker compose
 lychee/*
 
+# Python
+ai-vision-service/*
+
 # Laravel
 /storage/logs/*
+/storage/tmp/*
 /storage/framework/cache/*
 /storage/framework/sessions/*
 /storage/framework/views/*
diff --git a/app/Http/Controllers/AiVision/PersonPhotosController.php b/app/Http/Controllers/AiVision/PersonPhotosController.php
index bc85a13c1b0..5db5c3ff274 100644
--- a/app/Http/Controllers/AiVision/PersonPhotosController.php
+++ b/app/Http/Controllers/AiVision/PersonPhotosController.php
@@ -9,8 +9,10 @@
 namespace App\Http\Controllers\AiVision;
 
 use App\Http\Requests\Person\ListPersonsRequest;
+use App\Http\Resources\Models\PhotoResource;
 use App\Models\Person;
 use App\Models\Photo;
+use Illuminate\Pagination\LengthAwarePaginator;
 use Illuminate\Routing\Controller;
 use Illuminate\Support\Facades\Auth;
 use Illuminate\Support\Facades\DB;
@@ -29,9 +31,11 @@ class PersonPhotosController extends Controller
 	 * - Authenticated user: photos they own + photos in public albums
 	 * - Guest: photos in public albums only.
 	 *
-	 * @return \Illuminate\Pagination\LengthAwarePaginator<\stdClass>
+	 * Returns the standard Laravel paginator JSON shape: {data, links, meta}.
+	 *
+	 * @return LengthAwarePaginator<PhotoResource>
 	 */
-	public function index(ListPersonsRequest $_request, string $id)
+	public function index(ListPersonsRequest $_request, string $id): LengthAwarePaginator
 	{
 		$user = Auth::user();
 		$person = Person::findOrFail($id);
@@ -42,9 +46,11 @@ public function index(ListPersonsRequest $_request, string $id)
 		}
 
 		$query = Photo::query()
-			->select(['photos.id', 'photos.title'])
+			->select('photos.*')
 			->join('faces', 'faces.photo_id', '=', 'photos.id')
 			->where('faces.person_id', '=', $id)
+			->with(['size_variants', 'tags', 'palette', 'statistics', 'rating',
+				'faces.person', 'faces.suggestions.suggestedFace.person'])
 			->orderBy('photos.taken_at', 'desc');
 
 		// Access control: restrict to photos accessible to the current user
@@ -66,6 +72,13 @@ public function index(ListPersonsRequest $_request, string $id)
 			});
 		}
 
-		return $query->distinct()->paginate(50);
+		/** @var LengthAwarePaginator<PhotoResource> */
+		return $query->distinct()->paginate(50)->through(
+			fn (Photo $photo) => new PhotoResource(
+				photo: $photo,
+				album_id: null,
+				should_downgrade_size_variants: false,
+			)
+		);
 	}
 }
diff --git a/app/Http/Resources/Models/FaceResource.php b/app/Http/Resources/Models/FaceResource.php
index 63c8f7c8542..d1d84c241fa 100644
--- a/app/Http/Resources/Models/FaceResource.php
+++ b/app/Http/Resources/Models/FaceResource.php
@@ -26,6 +26,7 @@ class FaceResource extends Data
 	public float $confidence;
 	public bool $is_dismissed;
 	public ?string $crop_url;
+	public ?string $person_name;
 	/** @var FaceSuggestionResource[] */
 	public array $suggestions;
 
@@ -41,6 +42,7 @@ public function __construct(Face $face)
 		$this->confidence = $face->confidence;
 		$this->is_dismissed = $face->is_dismissed;
 		$this->crop_url = $face->crop_url;
+		$this->person_name = $face->person?->name;
 		$this->suggestions = $face->suggestions
 			->map(fn (FaceSuggestion $s) => new FaceSuggestionResource($s))
 			->values()
diff --git a/app/Http/Resources/Models/PhotoResource.php b/app/Http/Resources/Models/PhotoResource.php
index ac60406d527..947f0825b11 100644
--- a/app/Http/Resources/Models/PhotoResource.php
+++ b/app/Http/Resources/Models/PhotoResource.php
@@ -8,10 +8,12 @@
 
 namespace App\Http\Resources\Models;
 
+use App\Enum\FacePermissionMode;
 use App\Enum\LicenseType;
 use App\Http\Resources\Models\Utils\PreComputedPhotoData;
 use App\Http\Resources\Models\Utils\PreformattedPhotoData;
 use App\Http\Resources\Models\Utils\TimelineData;
+use App\Models\Face;
 use App\Models\Photo;
 use App\Policies\PhotoPolicy;
 use Illuminate\Support\Carbon;
@@ -53,6 +55,9 @@ class PhotoResource extends Data
 
 	public ?PhotoStatisticsResource $statistics = null;
 	public ?PhotoRatingResource $rating = null;
+	/** @var FaceResource[] */
+	public array $faces = [];
+	public int $hidden_face_count = 0;
 
 	public function __construct(Photo $photo, ?string $album_id, bool $should_downgrade_size_variants)
 	{
@@ -95,6 +100,60 @@ public function __construct(Photo $photo, ?string $album_id, bool $should_downgr
 				request()->configs(),
 			);
 		}
+
+		$this->buildFaceData($photo);
+	}
+
+	/**
+	 * Populate faces[] and hidden_face_count from the photo's detected faces.
+	 *
+	 * Only runs when ai_vision_face_enabled is on and the viewer has permission
+	 * to see face overlays per the ai_vision_face_permission_mode matrix.
+	 * Non-searchable persons are hidden from viewers who are not the linked user;
+	 * they are counted in hidden_face_count instead.
+	 */
+	private function buildFaceData(Photo $photo): void
+	{
+		if (!request()->configs()->getValueAsBool('ai_vision_enabled') ||
+			!request()->configs()->getValueAsBool('ai_vision_face_enabled')) {
+			return;
+		}
+
+		$user = Auth::user();
+		$is_admin = $user?->may_administrate === true;
+
+		// Check per-mode overlay visibility (View face overlays row in permission matrix).
+		$mode = request()->configs()->getValueAsEnum('ai_vision_face_permission_mode', FacePermissionMode::class) ?? FacePermissionMode::RESTRICTED;
+		$can_view_overlays = $is_admin || match ($mode) {
+			FacePermissionMode::PUBLIC => true,
+			FacePermissionMode::PRIVATE => $user !== null,
+			FacePermissionMode::PRIVACY_PRESERVING,
+			FacePermissionMode::RESTRICTED => $user !== null && $photo->owner_id === $user->id,
+		};
+
+		if (!$can_view_overlays) {
+			return;
+		}
+
+		foreach ($photo->faces as $face) {
+			/** @var Face $face */
+			if ($face->is_dismissed) {
+				continue;
+			}
+
+			// Unassigned face or searchable person: always include.
+			if ($face->person_id === null || ($face->person !== null && $face->person->is_searchable)) {
+				$this->faces[] = new FaceResource($face);
+				continue;
+			}
+
+			// Non-searchable person: visible only to the linked user or admin.
+			if ($is_admin || ($user !== null && $face->person?->user_id === $user->id)) {
+				$this->faces[] = new FaceResource($face);
+			} else {
+				$this->hidden_face_count++;
+			}
+		}
 	}
 
 	/**
diff --git a/app/Repositories/PhotoRepository.php b/app/Repositories/PhotoRepository.php
index 5855b0fbeb8..a082cb1e21f 100644
--- a/app/Repositories/PhotoRepository.php
+++ b/app/Repositories/PhotoRepository.php
@@ -58,7 +58,7 @@ public function getPhotosForAlbumPaginated(
 			->join(PA::PHOTO_ALBUM, PA::PHOTO_ID, '=', 'photos.id')
 			->where(PA::ALBUM_ID, '=', $album_id)
 			->select('photos.*')
-			->with(['size_variants', 'tags', 'palette', 'statistics', 'rating']);
+			->with(['size_variants', 'tags', 'palette', 'statistics', 'rating', 'faces.person', 'faces.suggestions.suggestedFace.person']);
 
 		// Apply tag filtering if tag_ids provided and not empty
 		if ($tag_ids !== null && count($tag_ids) > 0) {
diff --git a/docker-compose.yaml b/docker-compose.yaml
index b9c20514290..00081383206 100644
--- a/docker-compose.yaml
+++ b/docker-compose.yaml
@@ -509,6 +509,22 @@ services:
           - cache:/data:rw
       restart: on-failure:5
 
+  phpmyadmin:
+    image: phpmyadmin
+    restart: always
+    ports:
+      - 8080:80
+    environment:
+      - PMA_HOST=lychee_db
+      - PMA_PORT=3306
+    depends_on:
+        lychee_db:
+          condition: service_healthy
+    networks:
+        - lychee
+    profiles:
+      - phpmyadmin
+
   lychee_db:
       image: mariadb:10
       security_opt:
diff --git a/resources/js/components/gallery/photoModule/FaceOverlay.vue b/resources/js/components/gallery/photoModule/FaceOverlay.vue
index 023d85c1900..3728035b83d 100644
--- a/resources/js/components/gallery/photoModule/FaceOverlay.vue
+++ b/resources/js/components/gallery/photoModule/FaceOverlay.vue
@@ -40,7 +40,6 @@ import FaceAssignmentModal from "@/components/modals/FaceAssignmentModal.vue";
 const props = defineProps<{
 	faces: App.Http.Resources.Models.FaceResource[];
 	hiddenFaceCount: number;
-	personNames: Record<string, string>;
 }>();
 
 const emits = defineEmits<{
@@ -53,10 +52,7 @@ const selectedFace = ref<App.Http.Resources.Models.FaceResource | undefined>(und
 const visibleFaces = computed(() => props.faces.filter((f) => !f.is_dismissed));
 
 function faceLabel(face: App.Http.Resources.Models.FaceResource): string {
-	if (face.person_id && props.personNames[face.person_id]) {
-		return props.personNames[face.person_id];
-	}
-	return "Unknown";
+	return face.person_name ?? "Unknown";
 }
 
 function openAssignment(face: App.Http.Resources.Models.FaceResource) {
diff --git a/resources/js/components/gallery/photoModule/PhotoBox.vue b/resources/js/components/gallery/photoModule/PhotoBox.vue
index 72abeddb9ec..193cd8ebdd6 100644
--- a/resources/js/components/gallery/photoModule/PhotoBox.vue
+++ b/resources/js/components/gallery/photoModule/PhotoBox.vue
@@ -51,21 +51,25 @@
 		<!-- This is a normal image: medium or original -->
 		<img
 			v-if="photoStore.imageViewMode == ImageViewMode.Medium"
+			ref="imageEl"
 			id="image"
 			alt="medium"
 			class="absolute m-auto w-auto h-auto bg-contain bg-center bg-no-repeat"
 			:src="photoStore.photo.size_variants.medium?.url ?? ''"
 			:class="is_full_screen || is_slideshow_active ? 'max-w-full max-h-full' : 'max-w-full md:max-w-[calc(100%-56px)] max-h-[calc(100%-56px)]'"
 			:srcset="photoStore.srcSetMedium"
+			@load="updateFaceOverlay"
 		/>
 		<img
 			v-if="photoStore.imageViewMode == ImageViewMode.Original"
+			ref="imageEl"
 			id="image"
 			alt="big"
 			class="absolute m-auto w-auto h-auto bg-contain bg-center bg-no-repeat"
 			:class="is_full_screen || is_slideshow_active ? 'max-w-full max-h-full' : 'max-w-full md:max-w-[calc(100%-56px)] max-h-[calc(100%-56px)]'"
 			:style="photoStore.style"
 			:src="photoStore.photo.size_variants.original?.url ?? ''"
+			@load="updateFaceOverlay"
 		/>
 		<!-- This is a livephoto : medium -->
 		<div
@@ -91,6 +95,18 @@
 			:class="is_full_screen || is_slideshow_active ? 'max-w-full max-h-full' : 'max-w-full md:max-w-[calc(100%-56px)] max-h-[calc(100%-56px)]'"
 			:style="photoStore.style"
 		></div>
+		<!-- Face overlay: positioned to exactly match the rendered image via BoundingClientRect -->
+		<div
+			v-if="(photoStore.photo.faces && photoStore.photo.faces.length > 0) || photoStore.photo.hidden_face_count > 0"
+			class="absolute z-10 pointer-events-none"
+			:style="faceOverlayStyle"
+		>
+			<FaceOverlay
+				:faces="photoStore.photo.faces ?? []"
+				:hidden-face-count="photoStore.photo.hidden_face_count ?? 0"
+				@faces-updated="emits('facesUpdated')"
+			/>
+		</div>
 	</div>
 </template>
 <script setup lang="ts">
@@ -99,9 +115,10 @@ import { useTogglablesStateStore } from "@/stores/ModalsState";
 import { useImageHelpers } from "@/utils/Helpers";
 import { useSwipe, type UseSwipeDirection } from "@vueuse/core";
 import { storeToRefs } from "pinia";
-import { ref } from "vue";
+import { ref, reactive, watchEffect, onUnmounted } from "vue";
 import { useLtRorRtL } from "@/utils/Helpers";
 import { ImageViewMode, usePhotoStore } from "@/stores/PhotoState";
+import FaceOverlay from "./FaceOverlay.vue";
 
 const { isLTR } = useLtRorRtL();
 
@@ -117,11 +134,42 @@ const { is_slideshow_active, is_full_screen } = storeToRefs(togglableStore);
 
 const { getPlaceholderIcon } = useImageHelpers();
 
+// Face overlay: tracks the actual rendered image position/size
+const imageEl = ref<HTMLElement | null>(null);
+const faceOverlayStyle = reactive({ top: "0px", left: "0px", width: "0px", height: "0px" });
+let imageResizeObserver: ResizeObserver | null = null;
+
+function updateFaceOverlay() {
+	const img = imageEl.value;
+	if (!img) return;
+	// Use layout offset values (not getBoundingClientRect) so CSS transforms on
+	// parent containers (e.g. animate-zoomIn on first open) don't affect positioning.
+	// img.offsetParent is #imageview (the nearest positioned ancestor).
+	faceOverlayStyle.top = img.offsetTop + "px";
+	faceOverlayStyle.left = img.offsetLeft + "px";
+	faceOverlayStyle.width = img.offsetWidth + "px";
+	faceOverlayStyle.height = img.offsetHeight + "px";
+}
+
+// Re-runs whenever imageEl changes (photo/mode switch) — flush:'post' ensures DOM is ready.
+watchEffect(() => {
+	imageResizeObserver?.disconnect();
+	const img = imageEl.value;
+	if (!img) return;
+	imageResizeObserver = new ResizeObserver(updateFaceOverlay);
+	imageResizeObserver.observe(img);
+	// rAF ensures browser layout is complete (handles both cached and uncached images)
+	requestAnimationFrame(updateFaceOverlay);
+}, { flush: "post" });
+
+onUnmounted(() => imageResizeObserver?.disconnect());
+
 const emits = defineEmits<{
 	rotateOverlay: [];
 	goBack: [];
 	next: [];
 	previous: [];
+	facesUpdated: [];
 }>();
 
 useSwipe(swipe, {
diff --git a/resources/js/components/gallery/photoModule/PhotoPanel.vue b/resources/js/components/gallery/photoModule/PhotoPanel.vue
index 1597c4c7e17..467b548e817 100644
--- a/resources/js/components/gallery/photoModule/PhotoPanel.vue
+++ b/resources/js/components/gallery/photoModule/PhotoPanel.vue
@@ -27,13 +27,6 @@
 			/>
 			<Overlay v-if="!is_exif_disabled && photoStore.imageViewMode !== ImageViewMode.Pdf" />
 			<PhotoRatingOverlay />
-			<FaceOverlay
-				v-if="(photoStore.photo.faces && photoStore.photo.faces.length > 0) || photoStore.photo.hidden_face_count > 0"
-				:faces="photoStore.photo.faces ?? []"
-				:hidden-face-count="photoStore.photo.hidden_face_count ?? 0"
-				:person-names="{}"
-				@faces-updated="emits('updated')"
-			/>
 			<Dock
 				v-if="albumStore.rights?.can_edit && !is_photo_edit_open"
 				:is-narrow-menu="photoStore.imageViewMode === ImageViewMode.Pdf"
@@ -56,7 +49,6 @@ import { onMounted } from "vue";
 import NextPrevious from "./NextPrevious.vue";
 import Overlay from "./Overlay.vue";
 import PhotoRatingOverlay from "./PhotoRatingOverlay.vue";
-import FaceOverlay from "./FaceOverlay.vue";
 import PhotoDetails from "@/components/drawers/PhotoDetails.vue";
 import PhotoHeader from "@/components/headers/PhotoHeader.vue";
 import Dock from "./Dock.vue";
diff --git a/resources/js/components/modals/FaceAssignmentModal.vue b/resources/js/components/modals/FaceAssignmentModal.vue
index c4a772c265e..e6860f1711c 100644
--- a/resources/js/components/modals/FaceAssignmentModal.vue
+++ b/resources/js/components/modals/FaceAssignmentModal.vue
@@ -1,5 +1,5 @@
 <template>
-	<Dialog v-model:visible="visible" modal :header="$t('people.assignment.title')" pt:root:class="border-none w-full max-w-md">
+	<Dialog v-model:visible="visible" modal :header="$t('people.assignment.title')" pt:root:class="border-none w-full max-w-md" @show="onShow">
 		<div class="flex flex-col gap-4 p-2">
 			<!-- Face crop preview -->
 			<div class="flex justify-center">
@@ -78,7 +78,7 @@
 </template>
 
 <script setup lang="ts">
-import { ref, watch } from "vue";
+import { ref } from "vue";
 import Dialog from "primevue/dialog";
 import Button from "primevue/button";
 import InputText from "primevue/inputtext";
@@ -151,11 +151,9 @@ function submit() {
 		});
 }
 
-watch(visible, (newVal) => {
-	if (newVal) {
-		selectedPersonId.value = undefined;
-		newPersonName.value = "";
-		loadPeople();
-	}
-});
+function onShow() {
+	selectedPersonId.value = undefined;
+	newPersonName.value = "";
+	loadPeople();
+}
 </script>
diff --git a/resources/js/lychee.d.ts b/resources/js/lychee.d.ts
index 30860257bbc..17266de8712 100644
--- a/resources/js/lychee.d.ts
+++ b/resources/js/lychee.d.ts
@@ -1,1205 +1,1106 @@
 declare namespace App.DTO {
-	export type AlbumSortingCriterion = {
-		column: App.Enum.ColumnSortingType;
-		order: App.Enum.OrderSortingType;
-	};
-	export type PhotoSortingCriterion = {
-		column: App.Enum.ColumnSortingType;
-		order: App.Enum.OrderSortingType;
-	};
-	export type SortingCriterion = {
-		column: App.Enum.ColumnSortingType;
-		order: App.Enum.OrderSortingType;
-	};
+export type AlbumSortingCriterion = {
+column: App.Enum.ColumnSortingType;
+order: App.Enum.OrderSortingType;
+};
+export type PhotoSortingCriterion = {
+column: App.Enum.ColumnSortingType;
+order: App.Enum.OrderSortingType;
+};
+export type SortingCriterion = {
+column: App.Enum.ColumnSortingType;
+order: App.Enum.OrderSortingType;
+};
 }
 declare namespace App.Enum {
-	export type AlbumDecorationOrientation = "row" | "row-reverse" | "column" | "column-reverse";
-	export type AlbumDecorationType = "none" | "layers" | "album" | "photo" | "all";
-	export type AlbumHeaderSize = "half_screen" | "full_screen";
-	export type AlbumLayoutType = "list" | "grid";
-	export type AlbumTitleColor = "white" | "black" | "colour_1" | "colour_2" | "colour_3" | "colour_4" | "colour_5";
-	export type AlbumTitlePosition = "top_left" | "top_right" | "bottom_left" | "bottom_right" | "center";
-	export type AspectRatioCSSType = "aspect-5x4" | "aspect-4x5" | "aspect-3x2" | "aspect-square" | "aspect-2x3" | "aspect-video";
-	export type AspectRatioType = "5/4" | "3/2" | "1/1" | "2/3" | "4/5" | "16/9";
-	export type CacheTag = "gallery" | "auth" | "user" | "settings" | "statistics" | "users";
-	export type ColumnSortingAlbumType =
-		| "owner_id"
-		| "created_at"
-		| "title"
-		| "description"
-		| "title_strict"
-		| "description_strict"
-		| "min_taken_at"
-		| "max_taken_at";
-	export type ColumnSortingPhotoType =
-		| "owner_id"
-		| "created_at"
-		| "title"
-		| "description"
-		| "title_strict"
-		| "description_strict"
-		| "taken_at"
-		| "is_highlighted"
-		| "type"
-		| "rating_avg";
-	export type ColumnSortingType =
-		| "owner_id"
-		| "created_at"
-		| "title"
-		| "description"
-		| "title_strict"
-		| "description_strict"
-		| "min_taken_at"
-		| "max_taken_at"
-		| "taken_at"
-		| "is_highlighted"
-		| "type"
-		| "rating_avg";
-	export type ConfigType =
-		| "int"
-		| "positive"
-		| "string"
-		| "string_required"
-		| "0|1"
-		| "0|1|2"
-		| ""
-		| "admin_user"
-		| "license"
-		| "map_provider"
-		| "currency";
-	export type CountType = "taken_at" | "created_at";
-	export type CoverFitType = "cover" | "fit";
-	export type DateOrderingType = "older_younger" | "younger_older";
-	export type DbDriverType = "mysql" | "pgsql" | "sqlite";
-	export type DefaultAlbumProtectionType = "private" | "public" | "inherit" | "public_hidden";
-	export type DownloadVariantType = "RAW" | "LIVEPHOTOVIDEO" | "ORIGINAL" | "MEDIUM2X" | "MEDIUM" | "SMALL2X" | "SMALL" | "THUMB2X" | "THUMB";
-	export type FileStatus = "uploading" | "processing" | "ready" | "skipped" | "done" | "error";
-	export type FlowStrategy = "auto" | "opt-in";
-	export type ImageOverlayType = "none" | "desc" | "date" | "exif";
-	export type JobStatus = 0 | 1 | 2 | 3;
-	export type LandingBackgroundModeType = "static" | "photo_id" | "random" | "latest_album_cover" | "random_from_album";
-	export type LicenseType =
-		| "none"
-		| "reserved"
-		| "CC0"
-		| "CC-BY-1.0"
-		| "CC-BY-2.0"
-		| "CC-BY-2.5"
-		| "CC-BY-3.0"
-		| "CC-BY-4.0"
-		| "CC-BY-ND-1.0"
-		| "CC-BY-ND-2.0"
-		| "CC-BY-ND-2.5"
-		| "CC-BY-ND-3.0"
-		| "CC-BY-ND-4.0"
-		| "CC-BY-SA-1.0"
-		| "CC-BY-SA-2.0"
-		| "CC-BY-SA-2.5"
-		| "CC-BY-SA-3.0"
-		| "CC-BY-SA-4.0"
-		| "CC-BY-NC-1.0"
-		| "CC-BY-NC-2.0"
-		| "CC-BY-NC-2.5"
-		| "CC-BY-NC-3.0"
-		| "CC-BY-NC-4.0"
-		| "CC-BY-NC-ND-1.0"
-		| "CC-BY-NC-ND-2.0"
-		| "CC-BY-NC-ND-2.5"
-		| "CC-BY-NC-ND-3.0"
-		| "CC-BY-NC-ND-4.0"
-		| "CC-BY-NC-SA-1.0"
-		| "CC-BY-NC-SA-2.0"
-		| "CC-BY-NC-SA-2.5"
-		| "CC-BY-NC-SA-3.0"
-		| "CC-BY-NC-SA-4.0";
-	export type LiveMetricsAccess = "logged-in users" | "admin";
-	export type MapProviders = "Wikimedia" | "OpenStreetMap.org" | "OpenStreetMap.de" | "OpenStreetMap.fr" | "RRZE";
-	export type MessageType = "info" | "warning" | "error";
-	export type MetricsAccess = "public" | "logged-in users" | "owner" | "admin";
-	export type MetricsAction = "visit" | "favourite" | "download" | "shared";
-	export type OauthProvidersType =
-		| "amazon"
-		| "apple"
-		| "authelia"
-		| "authentik"
-		| "facebook"
-		| "github"
-		| "google"
-		| "mastodon"
-		| "microsoft"
-		| "nextcloud"
-		| "keycloak";
-	export type OmnipayProviderType = "Dummy" | "Mollie" | "PayPal" | "Stripe";
-	export type OrderSortingType = "ASC" | "DESC";
-	export type PaginationMode = "infinite_scroll" | "load_more_button" | "page_navigation";
-	export type PaymentStatusType = "pending" | "cancelled" | "failed" | "refunded" | "processing" | "offline" | "completed" | "closed";
-	export type PhotoHighlightVisibilityType = "anonymous" | "authenticated" | "editor";
-	export type PhotoLayoutType = "square" | "justified" | "masonry" | "grid";
-	export type PhotoThumbInfoType = "title" | "description";
-	export type PurchasableLicenseType = "personal" | "commercial" | "extended";
-	export type PurchasableSizeVariantType = "medium" | "medium2x" | "original" | "full";
-	export type RenamerModeType = "first" | "all" | "regex" | "trim" | "strtolower" | "strtoupper" | "ucwords" | "ucfirst";
-	export type SeverityType = "emergency" | "alert" | "critical" | "error" | "warning" | "notice" | "info" | "debug";
-	export type SharedAlbumsVisibility = "show" | "separate" | "separate_shared_only" | "hide";
-	export type ShiftType = "relative" | "absolute";
-	export type ShiftX = "left" | "right";
-	export type ShiftY = "up" | "down";
-	export type SizeVariantType = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8;
-	export type SmallLargeType = "small" | "large";
-	export type SmartAlbumType =
-		| "unsorted"
-		| "highlighted"
-		| "recent"
-		| "on_this_day"
-		| "untagged"
-		| "unrated"
-		| "one_star"
-		| "two_stars"
-		| "three_stars"
-		| "four_stars"
-		| "five_stars"
-		| "best_pictures"
-		| "my_rated_pictures"
-		| "my_best_pictures";
-	export type StorageDiskType = "images" | "s3";
-	export type ThumbAlbumSubtitleType = "description" | "takedate" | "creation" | "oldstyle" | "num_photos" | "num_albums" | "num_photos_albums";
-	export type TimelineAlbumGranularity = "default" | "disabled" | "year" | "month" | "day";
-	export type TimelinePhotoGranularity = "default" | "disabled" | "year" | "month" | "day" | "hour";
-	export type UpdateStatus = 0 | 1 | 2 | 3;
-	export type UserGroupRole = "member" | "admin";
-	export type UserSharedAlbumsVisibility = "default" | "show" | "separate" | "separate_shared_only" | "hide";
-	export type VersionChannelType = "release" | "git" | "tag";
-	export type VisibilityType = "never" | "always" | "hover";
-	export type WatermarkPosition = "top-left" | "top" | "top-right" | "left" | "center" | "right" | "bottom-left" | "bottom" | "bottom-right";
+export type AlbumDecorationOrientation = 'row' | 'row-reverse' | 'column' | 'column-reverse';
+export type AlbumDecorationType = 'none' | 'layers' | 'album' | 'photo' | 'all';
+export type AlbumHeaderSize = 'half_screen' | 'full_screen';
+export type AlbumLayoutType = 'list' | 'grid';
+export type AlbumTitleColor = 'white' | 'black' | 'colour_1' | 'colour_2' | 'colour_3' | 'colour_4' | 'colour_5';
+export type AlbumTitlePosition = 'top_left' | 'top_right' | 'bottom_left' | 'bottom_right' | 'center';
+export type AspectRatioCSSType = 'aspect-5x4' | 'aspect-4x5' | 'aspect-3x2' | 'aspect-square' | 'aspect-2x3' | 'aspect-video';
+export type AspectRatioType = '5/4' | '3/2' | '1/1' | '2/3' | '4/5' | '16/9';
+export type CacheTag = 'gallery' | 'auth' | 'user' | 'settings' | 'statistics' | 'users';
+export type ColumnSortingAlbumType = 'owner_id' | 'created_at' | 'title' | 'description' | 'title_strict' | 'description_strict' | 'min_taken_at' | 'max_taken_at';
+export type ColumnSortingPhotoType = 'owner_id' | 'created_at' | 'title' | 'description' | 'title_strict' | 'description_strict' | 'taken_at' | 'is_highlighted' | 'type' | 'rating_avg';
+export type ColumnSortingType = 'owner_id' | 'created_at' | 'title' | 'description' | 'title_strict' | 'description_strict' | 'min_taken_at' | 'max_taken_at' | 'taken_at' | 'is_highlighted' | 'type' | 'rating_avg';
+export type ConfigType = 'int' | 'positive' | 'string' | 'string_required' | '0|1' | '0|1|2' | '' | 'admin_user' | 'license' | 'map_provider' | 'currency';
+export type CountType = 'taken_at' | 'created_at';
+export type CoverFitType = 'cover' | 'fit';
+export type DateOrderingType = 'older_younger' | 'younger_older';
+export type DbDriverType = 'mysql' | 'pgsql' | 'sqlite';
+export type DefaultAlbumProtectionType = 'private' | 'public' | 'inherit' | 'public_hidden';
+export type DownloadVariantType = 'RAW' | 'LIVEPHOTOVIDEO' | 'ORIGINAL' | 'MEDIUM2X' | 'MEDIUM' | 'SMALL2X' | 'SMALL' | 'THUMB2X' | 'THUMB';
+export type FacePermissionMode = 'public' | 'private' | 'privacy-preserving' | 'restricted';
+export type FaceScanStatus = 'pending' | 'completed' | 'failed';
+export type FileStatus = 'uploading' | 'processing' | 'ready' | 'skipped' | 'done' | 'error';
+export type FlowStrategy = 'auto' | 'opt-in';
+export type ImageOverlayType = 'none' | 'desc' | 'date' | 'exif';
+export type JobStatus = 0 | 1 | 2 | 3;
+export type LandingBackgroundModeType = 'static' | 'photo_id' | 'random' | 'latest_album_cover' | 'random_from_album';
+export type LicenseType = 'none' | 'reserved' | 'CC0' | 'CC-BY-1.0' | 'CC-BY-2.0' | 'CC-BY-2.5' | 'CC-BY-3.0' | 'CC-BY-4.0' | 'CC-BY-ND-1.0' | 'CC-BY-ND-2.0' | 'CC-BY-ND-2.5' | 'CC-BY-ND-3.0' | 'CC-BY-ND-4.0' | 'CC-BY-SA-1.0' | 'CC-BY-SA-2.0' | 'CC-BY-SA-2.5' | 'CC-BY-SA-3.0' | 'CC-BY-SA-4.0' | 'CC-BY-NC-1.0' | 'CC-BY-NC-2.0' | 'CC-BY-NC-2.5' | 'CC-BY-NC-3.0' | 'CC-BY-NC-4.0' | 'CC-BY-NC-ND-1.0' | 'CC-BY-NC-ND-2.0' | 'CC-BY-NC-ND-2.5' | 'CC-BY-NC-ND-3.0' | 'CC-BY-NC-ND-4.0' | 'CC-BY-NC-SA-1.0' | 'CC-BY-NC-SA-2.0' | 'CC-BY-NC-SA-2.5' | 'CC-BY-NC-SA-3.0' | 'CC-BY-NC-SA-4.0';
+export type LiveMetricsAccess = 'logged-in users' | 'admin';
+export type MapProviders = 'Wikimedia' | 'OpenStreetMap.org' | 'OpenStreetMap.de' | 'OpenStreetMap.fr' | 'RRZE';
+export type MessageType = 'info' | 'warning' | 'error';
+export type MetricsAccess = 'public' | 'logged-in users' | 'owner' | 'admin';
+export type MetricsAction = 'visit' | 'favourite' | 'download' | 'shared';
+export type OauthProvidersType = 'amazon' | 'apple' | 'authelia' | 'authentik' | 'facebook' | 'github' | 'google' | 'mastodon' | 'microsoft' | 'nextcloud' | 'keycloak';
+export type OmnipayProviderType = 'Dummy' | 'Mollie' | 'PayPal' | 'Stripe';
+export type OrderSortingType = 'ASC' | 'DESC';
+export type PaginationMode = 'infinite_scroll' | 'load_more_button' | 'page_navigation';
+export type PaymentStatusType = 'pending' | 'cancelled' | 'failed' | 'refunded' | 'processing' | 'offline' | 'completed' | 'closed';
+export type PhotoHighlightVisibilityType = 'anonymous' | 'authenticated' | 'editor';
+export type PhotoLayoutType = 'square' | 'justified' | 'masonry' | 'grid';
+export type PhotoThumbInfoType = 'title' | 'description';
+export type PurchasableLicenseType = 'personal' | 'commercial' | 'extended';
+export type PurchasableSizeVariantType = 'medium' | 'medium2x' | 'original' | 'full';
+export type RenamerModeType = 'first' | 'all' | 'regex' | 'trim' | 'strtolower' | 'strtoupper' | 'ucwords' | 'ucfirst';
+export type SeverityType = 'emergency' | 'alert' | 'critical' | 'error' | 'warning' | 'notice' | 'info' | 'debug';
+export type SharedAlbumsVisibility = 'show' | 'separate' | 'separate_shared_only' | 'hide';
+export type ShiftType = 'relative' | 'absolute';
+export type ShiftX = 'left' | 'right';
+export type ShiftY = 'up' | 'down';
+export type SizeVariantType = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8;
+export type SmallLargeType = 'small' | 'large';
+export type SmartAlbumType = 'unsorted' | 'highlighted' | 'recent' | 'on_this_day' | 'untagged' | 'unrated' | 'one_star' | 'two_stars' | 'three_stars' | 'four_stars' | 'five_stars' | 'best_pictures' | 'my_rated_pictures' | 'my_best_pictures';
+export type StorageDiskType = 'images' | 's3';
+export type ThumbAlbumSubtitleType = 'description' | 'takedate' | 'creation' | 'oldstyle' | 'num_photos' | 'num_albums' | 'num_photos_albums';
+export type TimelineAlbumGranularity = 'default' | 'disabled' | 'year' | 'month' | 'day';
+export type TimelinePhotoGranularity = 'default' | 'disabled' | 'year' | 'month' | 'day' | 'hour';
+export type UpdateStatus = 0 | 1 | 2 | 3;
+export type UserGroupRole = 'member' | 'admin';
+export type UserSharedAlbumsVisibility = 'default' | 'show' | 'separate' | 'separate_shared_only' | 'hide';
+export type VersionChannelType = 'release' | 'git' | 'tag';
+export type VisibilityType = 'never' | 'always' | 'hover';
+export type WatermarkPosition = 'top-left' | 'top' | 'top-right' | 'left' | 'center' | 'right' | 'bottom-left' | 'bottom' | 'bottom-right';
 }
 declare namespace App.Http.Resources.Admin {
-	export type ImportDirectoryResource = {
-		directory: string;
-		status: boolean;
-		message: string | null;
-		jobs_count: number | null;
-	};
-	export type ImportFromServerOptionsResource = {
-		delete_imported: boolean;
-		import_via_symlink: boolean;
-		skip_duplicates: boolean;
-		resync_metadata: boolean;
-		delete_missing_photos: boolean;
-		delete_missing_albums: boolean;
-		directory: string;
-	};
-	export type ImportFromServerResource = {
-		status: boolean;
-		message: string;
-		results: App.Http.Resources.Admin.ImportDirectoryResource[];
-		job_count: number;
-	};
+export type ImportDirectoryResource = {
+directory: string;
+status: boolean;
+message: string | null;
+jobs_count: number | null;
+};
+export type ImportFromServerOptionsResource = {
+delete_imported: boolean;
+import_via_symlink: boolean;
+skip_duplicates: boolean;
+resync_metadata: boolean;
+delete_missing_photos: boolean;
+delete_missing_albums: boolean;
+directory: string;
+};
+export type ImportFromServerResource = {
+status: boolean;
+message: string;
+results: App.Http.Resources.Admin.ImportDirectoryResource[];
+job_count: number;
+};
 }
 declare namespace App.Http.Resources.Collections {
-	export type ContactMessageCollectionResource = {
-		data: App.Http.Resources.Models.ContactMessageResource[];
-		current_page: number;
-		per_page: number;
-		total: number;
-	};
-	export type PaginatedAlbumsResource = {
-		data: App.Http.Resources.Models.ThumbAlbumResource[];
-		current_page: number;
-		last_page: number;
-		per_page: number;
-		total: number;
-	};
-	export type PaginatedPhotosResource = {
-		photos: App.Http.Resources.Models.PhotoResource[];
-		current_page: number;
-		last_page: number;
-		per_page: number;
-		total: number;
-	};
-	export type PositionDataResource = {
-		id: string | null;
-		title: string | null;
-		track_url: string | null;
-		photos: App.Http.Resources.Models.PhotoResource[];
-	};
-	export type RootAlbumResource = {
-		smart_albums: App.Http.Resources.Models.ThumbAlbumResource[];
-		tag_albums: App.Http.Resources.Models.ThumbAlbumResource[];
-		pinned_albums: App.Http.Resources.Models.ThumbAlbumResource[];
-		albums: App.Http.Resources.Models.ThumbAlbumResource[];
-		shared_albums: App.Http.Resources.Models.ThumbAlbumResource[];
-		config: App.Http.Resources.GalleryConfigs.RootConfig;
-		rights: App.Http.Resources.Rights.RootAlbumRightsResource;
-	};
-	export type UserGroupDataResource = {
-		user_groups: App.Http.Resources.Models.UserGroupResource[];
-		can_create_delete_user_groups: boolean;
-	};
+export type ContactMessageCollectionResource = {
+data: App.Http.Resources.Models.ContactMessageResource[];
+current_page: number;
+per_page: number;
+total: number;
+};
+export type PaginatedAlbumsResource = {
+data: App.Http.Resources.Models.ThumbAlbumResource[];
+current_page: number;
+last_page: number;
+per_page: number;
+total: number;
+};
+export type PaginatedPhotosResource = {
+photos: App.Http.Resources.Models.PhotoResource[];
+current_page: number;
+last_page: number;
+per_page: number;
+total: number;
+};
+export type PositionDataResource = {
+id: string | null;
+title: string | null;
+track_url: string | null;
+photos: App.Http.Resources.Models.PhotoResource[];
+};
+export type RootAlbumResource = {
+smart_albums: App.Http.Resources.Models.ThumbAlbumResource[];
+tag_albums: App.Http.Resources.Models.ThumbAlbumResource[];
+pinned_albums: App.Http.Resources.Models.ThumbAlbumResource[];
+albums: App.Http.Resources.Models.ThumbAlbumResource[];
+shared_albums: App.Http.Resources.Models.ThumbAlbumResource[];
+config: App.Http.Resources.GalleryConfigs.RootConfig;
+rights: App.Http.Resources.Rights.RootAlbumRightsResource;
+};
+export type UserGroupDataResource = {
+user_groups: App.Http.Resources.Models.UserGroupResource[];
+can_create_delete_user_groups: boolean;
+};
 }
 declare namespace App.Http.Resources.Diagnostics {
-	export type AlbumTree = {
-		id: string;
-		title: string;
-		parent_id: string | null;
-		_lft: number;
-		_rgt: number;
-	};
-	export type ChangeLogInfo = {
-		version: string;
-		date: string;
-		changes: string;
-	};
-	export type CleaningState = {
-		path: string;
-		base: string;
-		is_not_empty: boolean;
-	};
-	export type ErrorLine = {
-		type: App.Enum.MessageType;
-		message: string;
-		from: string;
-		details: string[];
-	};
-	export type Permissions = {
-		left: string;
-		right: string;
-	};
-	export type StatisticsCheckResource = {
-		missing_photos: number;
-		missing_albums: number;
-	};
-	export type TreeState = {
-		oddness: number;
-		duplicates: number;
-		wrong_parent: number;
-		missing_parent: number;
-	};
-	export type UpdateCheckInfo = {
-		extra: string;
-		can_update: boolean;
-	};
-	export type UpdateInfo = {
-		info: string;
-		extra: string;
-		channel_name: App.Enum.VersionChannelType;
-		is_docker: boolean;
-	};
+export type AlbumTree = {
+id: string;
+title: string;
+parent_id: string | null;
+_lft: number;
+_rgt: number;
+};
+export type ChangeLogInfo = {
+version: string;
+date: string;
+changes: string;
+};
+export type CleaningState = {
+path: string;
+base: string;
+is_not_empty: boolean;
+};
+export type ErrorLine = {
+type: App.Enum.MessageType;
+message: string;
+from: string;
+details: string[];
+};
+export type Permissions = {
+left: string;
+right: string;
+};
+export type StatisticsCheckResource = {
+missing_photos: number;
+missing_albums: number;
+};
+export type TreeState = {
+oddness: number;
+duplicates: number;
+wrong_parent: number;
+missing_parent: number;
+};
+export type UpdateCheckInfo = {
+extra: string;
+can_update: boolean;
+};
+export type UpdateInfo = {
+info: string;
+extra: string;
+channel_name: App.Enum.VersionChannelType;
+is_docker: boolean;
+};
 }
 declare namespace App.Http.Resources.Editable {
-	export type EditableBaseAlbumResource = {
-		id: string;
-		title: string;
-		slug: string | null;
-		description: string | null;
-		copyright: string | null;
-		license: App.Enum.LicenseType | null;
-		photo_sorting: App.DTO.PhotoSortingCriterion | null;
-		album_sorting: App.DTO.AlbumSortingCriterion | null;
-		aspect_ratio: App.Enum.AspectRatioType | null;
-		photo_layout: App.Enum.PhotoLayoutType | null;
-		header_id: string | null;
-		cover_id: string | null;
-		album_timeline: App.Enum.TimelineAlbumGranularity | null;
-		photo_timeline: App.Enum.TimelinePhotoGranularity | null;
-		tags: Array<string>;
-		is_and: boolean;
-		is_model_album: boolean;
-		is_pinned: boolean;
-	};
-	export type EditableConfigResource = {
-		key: string;
-		value: string | null;
-	};
-	export type UploadMetaResource = {
-		file_name: string;
-		extension: string | null;
-		uuid_name: string | null;
-		stage: App.Enum.FileStatus;
-		chunk_number: number;
-		total_chunks: number;
-	};
+export type EditableBaseAlbumResource = {
+id: string;
+title: string;
+slug: string | null;
+description: string | null;
+copyright: string | null;
+license: App.Enum.LicenseType | null;
+photo_sorting: App.DTO.PhotoSortingCriterion | null;
+album_sorting: App.DTO.AlbumSortingCriterion | null;
+aspect_ratio: App.Enum.AspectRatioType | null;
+photo_layout: App.Enum.PhotoLayoutType | null;
+header_id: string | null;
+cover_id: string | null;
+album_timeline: App.Enum.TimelineAlbumGranularity | null;
+photo_timeline: App.Enum.TimelinePhotoGranularity | null;
+tags: Array<string>;
+is_and: boolean;
+is_model_album: boolean;
+is_pinned: boolean;
+};
+export type EditableConfigResource = {
+key: string;
+value: string | null;
+};
+export type UploadMetaResource = {
+file_name: string;
+extension: string | null;
+uuid_name: string | null;
+stage: App.Enum.FileStatus;
+chunk_number: number;
+total_chunks: number;
+};
 }
 declare namespace App.Http.Resources.Embed {
-	export type EmbedAlbumInfo = {
-		id: string;
-		title: string;
-		description: string | null;
-		photo_count: number;
-		copyright: string | null;
-		license: string | null;
-	};
-	export type EmbedAlbumResource = {
-		album: App.Http.Resources.Embed.EmbedAlbumInfo;
-		photos: App.Http.Resources.Embed.EmbedPhotoResource[];
-	};
-	export type EmbedPhotoResource = {
-		id: string;
-		title: string | null;
-		description: string | null;
-		is_video: boolean;
-		duration: string | null;
-		size_variants: App.Http.Resources.Models.SizeVariantsResouce;
-		exif: { [key: string]: string | null };
-	};
-	export type EmbedStreamResource = {
-		site_title: string;
-		photos: App.Http.Resources.Embed.EmbedPhotoResource[];
-	};
+export type EmbedAlbumInfo = {
+id: string;
+title: string;
+description: string | null;
+photo_count: number;
+copyright: string | null;
+license: string | null;
+};
+export type EmbedAlbumResource = {
+album: App.Http.Resources.Embed.EmbedAlbumInfo;
+photos: App.Http.Resources.Embed.EmbedPhotoResource[];
+};
+export type EmbedPhotoResource = {
+id: string;
+title: string | null;
+description: string | null;
+is_video: boolean;
+duration: string | null;
+size_variants: App.Http.Resources.Models.SizeVariantsResouce;
+exif: { [key: string]: string | null };
+};
+export type EmbedStreamResource = {
+site_title: string;
+photos: App.Http.Resources.Embed.EmbedPhotoResource[];
+};
 }
 declare namespace App.Http.Resources.Flow {
-	export type FlowItemResource = {
-		id: string;
-		title: string;
-		description: string | null;
-		min_max_text: string | null;
-		published_created_at: string;
-		diff_published_created_at: string;
-		owner_name: string | null;
-		is_nsfw: boolean;
-		num_photos: number;
-		num_children: number;
-		cover: App.Http.Resources.Models.SizeVariantsResouce | null;
-		photos: App.Http.Resources.Models.PhotoResource[];
-		statistics: App.Http.Resources.Models.AlbumStatisticsResource | null;
-	};
-	export type FlowResource = {
-		albums: App.Http.Resources.Flow.FlowItemResource[];
-		current_page: number;
-		from: number;
-		last_page: number;
-		per_page: number;
-		to: number;
-		total: number;
-	};
-	export type InitResource = {
-		is_mod_flow_enabled: boolean;
-		is_open_album_on_click: boolean;
-		is_display_open_album_button: boolean;
-		is_highlight_first_picture: boolean;
-		is_image_header_enabled: boolean;
-		image_header_cover: App.Enum.CoverFitType;
-		image_header_height: number;
-		is_carousel_enabled: boolean;
-		carousel_height: number;
-		is_blur_nsfw_enabled: boolean;
-		is_compact_mode_enabled: boolean;
-	};
+export type FlowItemResource = {
+id: string;
+title: string;
+description: string | null;
+min_max_text: string | null;
+published_created_at: string;
+diff_published_created_at: string;
+owner_name: string | null;
+is_nsfw: boolean;
+num_photos: number;
+num_children: number;
+cover: App.Http.Resources.Models.SizeVariantsResouce | null;
+photos: App.Http.Resources.Models.PhotoResource[];
+statistics: App.Http.Resources.Models.AlbumStatisticsResource | null;
+};
+export type FlowResource = {
+albums: App.Http.Resources.Flow.FlowItemResource[];
+current_page: number;
+from: number;
+last_page: number;
+per_page: number;
+to: number;
+total: number;
+};
+export type InitResource = {
+is_mod_flow_enabled: boolean;
+is_open_album_on_click: boolean;
+is_display_open_album_button: boolean;
+is_highlight_first_picture: boolean;
+is_image_header_enabled: boolean;
+image_header_cover: App.Enum.CoverFitType;
+image_header_height: number;
+is_carousel_enabled: boolean;
+carousel_height: number;
+is_blur_nsfw_enabled: boolean;
+is_compact_mode_enabled: boolean;
+};
 }
 declare namespace App.Http.Resources.Frame {
-	export type FrameData = {
-		timeout: number;
-		src: string;
-		srcset: string;
-	};
+export type FrameData = {
+timeout: number;
+src: string;
+srcset: string;
+};
 }
 declare namespace App.Http.Resources.GalleryConfigs {
-	export type AlbumConfig = {
-		is_base_album: boolean;
-		is_model_album: boolean;
-		is_password_protected: boolean;
-		is_map_accessible: boolean;
-		is_mod_frame_enabled: boolean;
-		is_search_accessible: boolean;
-		is_nsfw_warning_visible: boolean;
-		album_thumb_css_aspect_ratio: App.Enum.AspectRatioCSSType;
-		photo_layout: App.Enum.PhotoLayoutType;
-		is_album_timeline_enabled: boolean;
-		is_photo_timeline_enabled: boolean;
-	};
-	export type ContactConfig = {
-		is_contact_form_enabled: boolean;
-		security_question: string;
-		is_consent_required: boolean;
-		header: string;
-		headline: string;
-		consent_text: string;
-		privacy_policy_url: string;
-		submit_button_text: string;
-		contact_method: string;
-		message_label: string;
-		message_answer: string;
-		thank_you_message: string;
-	};
-	export type FooterConfig = {
-		footer_additional_text: string;
-		footer_show_copyright: boolean;
-		footer_show_social_media: boolean;
-		copyright: string;
-		sm_facebook_url: string;
-		sm_flickr_url: string;
-		sm_instagram_url: string;
-		sm_twitter_url: string;
-		sm_youtube_url: string;
-		is_contact_form_enabled: boolean;
-		contact_header: string;
-	};
-	export type InitConfig = {
-		is_debug_enabled: boolean;
-		are_nsfw_visible: boolean;
-		is_nsfw_background_blurred: boolean;
-		nsfw_banner_override: string;
-		is_nsfw_banner_backdrop_blurred: boolean;
-		show_keybinding_help_popup: boolean;
-		image_overlay_type: App.Enum.ImageOverlayType;
-		can_rotate: boolean;
-		can_autoplay: boolean;
-		is_exif_disabled: boolean;
-		is_favourite_enabled: boolean;
-		photo_previous_next_size: App.Enum.SmallLargeType;
-		is_details_links_enabled: boolean;
-		is_desktop_dock_full_transparency_enabled: boolean;
-		is_mobile_dock_full_transparency_enabled: boolean;
-		is_photo_details_always_open: boolean;
-		display_thumb_album_overlay: App.Enum.VisibilityType;
-		display_thumb_photo_overlay: App.Enum.VisibilityType;
-		album_subtitle_type: App.Enum.ThumbAlbumSubtitleType;
-		album_decoration: App.Enum.AlbumDecorationType;
-		album_decoration_orientation: App.Enum.AlbumDecorationOrientation;
-		number_albums_per_row_mobile: 1 | 2 | 3;
-		photo_thumb_info: App.Enum.PhotoThumbInfoType;
-		is_photo_thumb_tags_enabled: boolean;
-		album_layout: App.Enum.AlbumLayoutType;
-		is_raw_download_enabled: boolean;
-		is_thumb_download_enabled: boolean;
-		is_thum2x_download_enabled: boolean;
-		is_small_download_enabled: boolean;
-		is_small2x_download_enabled: boolean;
-		is_medium_download_enabled: boolean;
-		is_medium2x_download_enabled: boolean;
-		clockwork_url: string | null;
-		slideshow_timeout: number;
-		is_slideshow_enabled: boolean;
-		is_timeline_left_border_visible: boolean;
-		title: string;
-		dropbox_api_key: string;
-		is_se_enabled: boolean;
-		is_pro_enabled: boolean;
-		is_se_preview_enabled: boolean;
-		is_se_info_hidden: boolean;
-		is_se_expired: boolean;
-		is_live_metrics_enabled: boolean;
-		is_basic_auth_enabled: boolean;
-		is_webauthn_enabled: boolean;
-		is_registration_enabled: boolean;
-		is_scroll_to_navigate_photos_enabled: boolean;
-		is_swipe_vertically_to_go_back_enabled: boolean;
-		is_rating_show_avg_in_details_enabled: boolean;
-		is_rating_show_avg_in_photo_view_enabled: boolean;
-		rating_photo_view_mode: App.Enum.VisibilityType;
-		is_rating_show_avg_in_album_view_enabled: boolean;
-		rating_album_view_mode: App.Enum.VisibilityType;
-		default_homepage: string;
-		is_timeline_page_enabled: boolean;
-		is_contact_form_enabled: boolean;
-		photos_pagination_mode: App.Enum.PaginationMode;
-		albums_pagination_mode: App.Enum.PaginationMode;
-		photos_per_page: number;
-		albums_per_page: number;
-		photos_infinite_scroll_threshold: number;
-		albums_infinite_scroll_threshold: number;
-		default_album_protection: App.Enum.DefaultAlbumProtectionType;
-		photos_star_visibility: App.Enum.PhotoHighlightVisibilityType;
-		is_album_enhanced_display_enabled: boolean;
-		album_header_size: App.Enum.AlbumHeaderSize;
-		is_album_header_landing_title_enabled: boolean;
-	};
-	export type LandingPageResource = {
-		landing_page_enable: boolean;
-		landing_background_landscape: string;
-		landing_background_portrait: string;
-		landing_subtitle: string;
-		landing_title: string;
-		site_owner: string;
-		site_title: string;
-		footer: App.Http.Resources.GalleryConfigs.FooterConfig;
-	};
-	export type MapProviderData = {
-		layer: string;
-		attribution: string;
-	};
-	export type PhotoLayoutConfig = {
-		photo_layout_justified_row_height: number;
-		photo_layout_masonry_column_width: number;
-		photo_layout_grid_column_width: number;
-		photo_layout_square_column_width: number;
-		photo_layout_gap: number;
-	};
-	export type RegisterData = {
-		success: boolean;
-	};
-	export type RootConfig = {
-		is_album_timeline_enabled: boolean;
-		is_search_accessible: boolean;
-		show_keybinding_help_button: boolean;
-		album_thumb_css_aspect_ratio: App.Enum.AspectRatioType;
-		back_button_enabled: boolean;
-		back_button_text: string;
-		back_button_url: string;
-		timeline_album_granularity: App.Enum.TimelineAlbumGranularity;
-		header_image_url: string;
-		is_header_bar_transparent: boolean;
-		is_header_bar_gradient: boolean;
-		shared_albums_visibility_mode: App.Enum.SharedAlbumsVisibility;
-	};
-	export type SettingsConfig = {
-		default_old_settings: boolean;
-		default_expert_settings: boolean;
-		default_all_settings: boolean;
-	};
-	export type UploadConfig = {
-		upload_processing_limit: number;
-		upload_chunk_size: number;
-		can_watermark_optout: boolean;
-	};
+export type AlbumConfig = {
+is_base_album: boolean;
+is_model_album: boolean;
+is_password_protected: boolean;
+is_map_accessible: boolean;
+is_mod_frame_enabled: boolean;
+is_search_accessible: boolean;
+is_nsfw_warning_visible: boolean;
+album_thumb_css_aspect_ratio: App.Enum.AspectRatioCSSType;
+photo_layout: App.Enum.PhotoLayoutType;
+is_album_timeline_enabled: boolean;
+is_photo_timeline_enabled: boolean;
+};
+export type ContactConfig = {
+is_contact_form_enabled: boolean;
+security_question: string;
+is_consent_required: boolean;
+header: string;
+headline: string;
+consent_text: string;
+privacy_policy_url: string;
+submit_button_text: string;
+contact_method: string;
+message_label: string;
+message_answer: string;
+thank_you_message: string;
+};
+export type FooterConfig = {
+footer_additional_text: string;
+footer_show_copyright: boolean;
+footer_show_social_media: boolean;
+copyright: string;
+sm_facebook_url: string;
+sm_flickr_url: string;
+sm_instagram_url: string;
+sm_twitter_url: string;
+sm_youtube_url: string;
+is_contact_form_enabled: boolean;
+contact_header: string;
+};
+export type InitConfig = {
+is_debug_enabled: boolean;
+are_nsfw_visible: boolean;
+is_nsfw_background_blurred: boolean;
+nsfw_banner_override: string;
+is_nsfw_banner_backdrop_blurred: boolean;
+show_keybinding_help_popup: boolean;
+image_overlay_type: App.Enum.ImageOverlayType;
+can_rotate: boolean;
+can_autoplay: boolean;
+is_exif_disabled: boolean;
+is_favourite_enabled: boolean;
+photo_previous_next_size: App.Enum.SmallLargeType;
+is_details_links_enabled: boolean;
+is_desktop_dock_full_transparency_enabled: boolean;
+is_mobile_dock_full_transparency_enabled: boolean;
+is_photo_details_always_open: boolean;
+display_thumb_album_overlay: App.Enum.VisibilityType;
+display_thumb_photo_overlay: App.Enum.VisibilityType;
+album_subtitle_type: App.Enum.ThumbAlbumSubtitleType;
+album_decoration: App.Enum.AlbumDecorationType;
+album_decoration_orientation: App.Enum.AlbumDecorationOrientation;
+number_albums_per_row_mobile: 1|2|3;
+photo_thumb_info: App.Enum.PhotoThumbInfoType;
+is_photo_thumb_tags_enabled: boolean;
+album_layout: App.Enum.AlbumLayoutType;
+is_raw_download_enabled: boolean;
+is_thumb_download_enabled: boolean;
+is_thum2x_download_enabled: boolean;
+is_small_download_enabled: boolean;
+is_small2x_download_enabled: boolean;
+is_medium_download_enabled: boolean;
+is_medium2x_download_enabled: boolean;
+clockwork_url: string | null;
+slideshow_timeout: number;
+is_slideshow_enabled: boolean;
+is_timeline_left_border_visible: boolean;
+title: string;
+dropbox_api_key: string;
+is_se_enabled: boolean;
+is_pro_enabled: boolean;
+is_se_preview_enabled: boolean;
+is_se_info_hidden: boolean;
+is_se_expired: boolean;
+is_live_metrics_enabled: boolean;
+is_basic_auth_enabled: boolean;
+is_webauthn_enabled: boolean;
+is_registration_enabled: boolean;
+is_scroll_to_navigate_photos_enabled: boolean;
+is_swipe_vertically_to_go_back_enabled: boolean;
+is_rating_show_avg_in_details_enabled: boolean;
+is_rating_show_avg_in_photo_view_enabled: boolean;
+rating_photo_view_mode: App.Enum.VisibilityType;
+is_rating_show_avg_in_album_view_enabled: boolean;
+rating_album_view_mode: App.Enum.VisibilityType;
+default_homepage: string;
+is_timeline_page_enabled: boolean;
+is_contact_form_enabled: boolean;
+photos_pagination_mode: App.Enum.PaginationMode;
+albums_pagination_mode: App.Enum.PaginationMode;
+photos_per_page: number;
+albums_per_page: number;
+photos_infinite_scroll_threshold: number;
+albums_infinite_scroll_threshold: number;
+default_album_protection: App.Enum.DefaultAlbumProtectionType;
+photos_star_visibility: App.Enum.PhotoHighlightVisibilityType;
+is_album_enhanced_display_enabled: boolean;
+album_header_size: App.Enum.AlbumHeaderSize;
+is_album_header_landing_title_enabled: boolean;
+};
+export type LandingPageResource = {
+landing_page_enable: boolean;
+landing_background_landscape: string;
+landing_background_portrait: string;
+landing_subtitle: string;
+landing_title: string;
+site_owner: string;
+site_title: string;
+footer: App.Http.Resources.GalleryConfigs.FooterConfig;
+};
+export type MapProviderData = {
+layer: string;
+attribution: string;
+};
+export type PhotoLayoutConfig = {
+photo_layout_justified_row_height: number;
+photo_layout_masonry_column_width: number;
+photo_layout_grid_column_width: number;
+photo_layout_square_column_width: number;
+photo_layout_gap: number;
+};
+export type RegisterData = {
+success: boolean;
+};
+export type RootConfig = {
+is_album_timeline_enabled: boolean;
+is_search_accessible: boolean;
+show_keybinding_help_button: boolean;
+album_thumb_css_aspect_ratio: App.Enum.AspectRatioType;
+back_button_enabled: boolean;
+back_button_text: string;
+back_button_url: string;
+timeline_album_granularity: App.Enum.TimelineAlbumGranularity;
+header_image_url: string;
+is_header_bar_transparent: boolean;
+is_header_bar_gradient: boolean;
+shared_albums_visibility_mode: App.Enum.SharedAlbumsVisibility;
+};
+export type SettingsConfig = {
+default_old_settings: boolean;
+default_expert_settings: boolean;
+default_all_settings: boolean;
+};
+export type UploadConfig = {
+upload_processing_limit: number;
+upload_chunk_size: number;
+can_watermark_optout: boolean;
+};
 }
 declare namespace App.Http.Resources.Models {
-	export type AccessPermissionResource = {
-		id: number | null;
-		user_id: number | null;
-		user_group_id: number | null;
-		username: string | null;
-		user_group_name: string | null;
-		album_title: string | null;
-		album_id: string | null;
-		grants_full_photo_access: boolean;
-		grants_download: boolean;
-		grants_upload: boolean;
-		grants_edit: boolean;
-		grants_delete: boolean;
-	};
-	export type AlbumStatisticsResource = {
-		visit_count: number;
-		download_count: number;
-		shared_count: number;
-	};
-	export type ColourPaletteResource = {
-		colour_1: string;
-		colour_2: string;
-		colour_3: string;
-		colour_4: string;
-		colour_5: string;
-	};
-	export type ConfigCategoryResource = {
-		cat: string;
-		name: string;
-		description: string;
-		configs: App.Http.Resources.Models.ConfigResource[];
-		priority: number;
-	};
-	export type ConfigResource = {
-		key: string;
-		type: App.Enum.ConfigType | string;
-		value: string;
-		documentation: string;
-		details: string;
-		is_expert: boolean;
-		require_se: boolean;
-		order: number | null;
-	};
-	export type ContactMessageResource = {
-		id: number;
-		name: string;
-		email: string;
-		message: string;
-		is_read: boolean;
-		created_at: string;
-	};
-	export type HeadAbstractAlbumResource = {
-		config: App.Http.Resources.GalleryConfigs.AlbumConfig;
-		resource:
-			| App.Http.Resources.Models.HeadAlbumResource
-			| App.Http.Resources.Models.HeadSmartAlbumResource
-			| App.Http.Resources.Models.HeadTagAlbumResource;
-	};
-	export type HeadAlbumResource = {
-		id: string;
-		title: string;
-		slug: string | null;
-		owner_name: string | null;
-		description: string | null;
-		copyright: string | null;
-		track_url: string | null;
-		license: string;
-		header_id: string | null;
-		parent_id: string | null;
-		has_albums: boolean;
-		num_children: number;
-		num_photos: number;
-		cover_id: string | null;
-		policy: App.Http.Resources.Models.Utils.AlbumProtectionPolicy;
-		rights: App.Http.Resources.Rights.AlbumRightsResource;
-		preFormattedData: App.Http.Resources.Models.Utils.PreFormattedAlbumData;
-		editable: App.Http.Resources.Editable.EditableBaseAlbumResource | null;
-		is_pinned: boolean;
-		statistics: App.Http.Resources.Models.AlbumStatisticsResource | null;
-	};
-	export type HeadSmartAlbumResource = {
-		id: string;
-		title: string;
-		policy: App.Http.Resources.Models.Utils.AlbumProtectionPolicy;
-		rights: App.Http.Resources.Rights.AlbumRightsResource;
-		preFormattedData: App.Http.Resources.Models.Utils.PreFormattedAlbumData;
-		statistics: null | null;
-	};
-	export type HeadTagAlbumResource = {
-		id: string;
-		title: string;
-		slug: string | null;
-		owner_name: string | null;
-		copyright: string | null;
-		is_tag_album: boolean;
-		show_tags: Array<string>;
-		policy: App.Http.Resources.Models.Utils.AlbumProtectionPolicy;
-		rights: App.Http.Resources.Rights.AlbumRightsResource;
-		preFormattedData: App.Http.Resources.Models.Utils.PreFormattedAlbumData;
-		editable: App.Http.Resources.Editable.EditableBaseAlbumResource | null;
-		statistics: App.Http.Resources.Models.AlbumStatisticsResource | null;
-	};
-	export type JobHistoryResource = {
-		username: string;
-		status: "ready" | "success" | "failure" | "started";
-		created_at: string;
-		updated_at: string;
-		job: string;
-	};
-	export type LightUserResource = {
-		id: number;
-		username: string;
-	};
-	export type LiveMetricsResource = {
-		created_at: string;
-		visitor_id: string;
-		action: App.Enum.MetricsAction;
-		photo_id: string | null;
-		album_id: string;
-		title: string;
-		url: string | null;
-	};
-	export type PhotoAlbumResource = {
-		id: string;
-		title: string;
-	};
-	export type PhotoRatingResource = {
-		rating_user: number;
-		rating_count: number;
-		rating_avg: number;
-	};
-	export type PhotoResource = {
-		id: string;
-		album_id: string | null;
-		checksum: string;
-		created_at: string;
-		description: string;
-		is_highlighted: boolean;
-		license: App.Enum.LicenseType;
-		live_photo_checksum: string | null;
-		live_photo_content_id: string | null;
-		live_photo_url: string | null;
-		original_checksum: string;
-		size_variants: App.Http.Resources.Models.SizeVariantsResouce;
-		tags: Array<string>;
-		taken_at: string | null;
-		taken_at_orig_tz: string | null;
-		title: string;
-		type: string;
-		updated_at: string;
-		next_photo_id: string | null;
-		previous_photo_id: string | null;
-		preformatted: App.Http.Resources.Models.Utils.PreformattedPhotoData;
-		precomputed: App.Http.Resources.Models.Utils.PreComputedPhotoData;
-		timeline: App.Http.Resources.Models.Utils.TimelineData | null;
-		palette: App.Http.Resources.Models.ColourPaletteResource | null;
-		statistics: App.Http.Resources.Models.PhotoStatisticsResource | null;
-		rating: App.Http.Resources.Models.PhotoRatingResource | null;
-		faces: App.Http.Resources.Models.FaceResource[];
-		hidden_face_count: number;
-	};
-	export type FaceSuggestionResource = {
-		suggested_face_id: string;
-		crop_url: string | null;
-		person_name: string | null;
-		confidence: number;
-	};
-	export type FaceResource = {
-		id: string;
-		photo_id: string;
-		person_id: string | null;
-		x: number;
-		y: number;
-		width: number;
-		height: number;
-		confidence: number;
-		is_dismissed: boolean;
-		crop_url: string | null;
-		suggestions: App.Http.Resources.Models.FaceSuggestionResource[];
-	};
-	export type PersonResource = {
-		id: string;
-		name: string;
-		user_id: number | null;
-		is_searchable: boolean;
-		face_count: number;
-		photo_count: number;
-		representative_crop_url: string | null;
-	};
-	export type PhotoStatisticsResource = {
-		visit_count: number;
-		download_count: number;
-		favourite_count: number;
-		shared_count: number;
-		rating_count: number;
-		rating_avg: number | null;
-	};
-	export type RenamerPreviewResource = {
-		id: string;
-		original: string;
-		new: string;
-	};
-	export type RenamerRuleResource = {
-		id: number;
-		order: number;
-		owner_id: number;
-		rule: string;
-		description: string;
-		needle: string;
-		replacement: string;
-		mode: App.Enum.RenamerModeType;
-		is_enabled: boolean;
-		is_photo_rule: boolean;
-		is_album_rule: boolean;
-	};
-	export type SizeVariantResource = {
-		type: App.Enum.SizeVariantType;
-		locale: string;
-		filesize: string;
-		height: number;
-		width: number;
-		url: string | null;
-		is_watermarked: boolean;
-	};
-	export type SizeVariantsResouce = {
-		raw: App.Http.Resources.Models.SizeVariantResource | null;
-		original: App.Http.Resources.Models.SizeVariantResource | null;
-		medium2x: App.Http.Resources.Models.SizeVariantResource | null;
-		medium: App.Http.Resources.Models.SizeVariantResource | null;
-		small2x: App.Http.Resources.Models.SizeVariantResource | null;
-		small: App.Http.Resources.Models.SizeVariantResource | null;
-		thumb2x: App.Http.Resources.Models.SizeVariantResource | null;
-		thumb: App.Http.Resources.Models.SizeVariantResource | null;
-		placeholder: App.Http.Resources.Models.SizeVariantResource | null;
-	};
-	export type TargetAlbumResource = {
-		id: string | null;
-		title: string;
-		original: string;
-		short_title: string;
-		thumb: string;
-	};
-	export type ThumbAlbumResource = {
-		id: string;
-		title: string;
-		description: string | null;
-		thumb: App.Http.Resources.Models.ThumbResource | null;
-		is_nsfw: boolean;
-		is_pinned: boolean;
-		is_public: boolean;
-		is_link_required: boolean;
-		is_password_required: boolean;
-		is_tag_album: boolean;
-		has_subalbum: boolean;
-		num_subalbums: number;
-		num_photos: number;
-		created_at: string;
-		formatted_min_max: string | null;
-		owner: string | null;
-		rights: App.Http.Resources.Rights.AlbumRightsResource;
-		timeline: App.Http.Resources.Models.Utils.TimelineData | null;
-	};
-	export type ThumbResource = {
-		id: string;
-		type: string;
-		thumb: string | null;
-		thumb2x: string | null;
-		placeholder: string | null;
-	};
-	export type UserGroupResource = {
-		id: number;
-		name: string;
-		description: string;
-		members: App.Http.Resources.Models.UserMemberGroupResource[];
-		rights: App.Http.Resources.Rights.UserGroupRightResource;
-	};
-	export type UserManagementResource = {
-		id: number;
-		username: string;
-		may_administrate: boolean;
-		may_upload: boolean;
-		may_edit_own_settings: boolean;
-		is_owner: boolean;
-		quota_kb: number | null;
-		description: string | null;
-		note: string | null;
-		space: number | null;
-	};
-	export type UserMemberGroupResource = {
-		id: number;
-		username: string;
-		role: App.Enum.UserGroupRole;
-	};
-	export type UserResource = {
-		id: number | null;
-		has_token: boolean | null;
-		username: string | null;
-		email: string | null;
-		is_ldap: boolean;
-		shared_albums_visibility: App.Enum.UserSharedAlbumsVisibility;
-	};
-	export type WebAuthnResource = {
-		id: string;
-		alias: string | null;
-		created_at: string;
-	};
+export type AccessPermissionResource = {
+id: number | null;
+user_id: number | null;
+user_group_id: number | null;
+username: string | null;
+user_group_name: string | null;
+album_title: string | null;
+album_id: string | null;
+grants_full_photo_access: boolean;
+grants_download: boolean;
+grants_upload: boolean;
+grants_edit: boolean;
+grants_delete: boolean;
+};
+export type AlbumStatisticsResource = {
+visit_count: number;
+download_count: number;
+shared_count: number;
+};
+export type ColourPaletteResource = {
+colour_1: string;
+colour_2: string;
+colour_3: string;
+colour_4: string;
+colour_5: string;
+};
+export type ConfigCategoryResource = {
+cat: string;
+name: string;
+description: string;
+configs: App.Http.Resources.Models.ConfigResource[];
+priority: number;
+};
+export type ConfigResource = {
+key: string;
+type: App.Enum.ConfigType | string;
+value: string;
+documentation: string;
+details: string;
+is_expert: boolean;
+require_se: boolean;
+order: number | null;
+};
+export type ContactMessageResource = {
+id: number;
+name: string;
+email: string;
+message: string;
+is_read: boolean;
+created_at: string;
+};
+export type FaceResource = {
+id: string;
+photo_id: string;
+person_id: string | null;
+x: number;
+y: number;
+width: number;
+height: number;
+confidence: number;
+is_dismissed: boolean;
+crop_url: string | null;
+person_name: string | null;
+suggestions: Array<App.Http.Resources.Models.FaceSuggestionResource>;
+};
+export type FaceSuggestionResource = {
+suggested_face_id: string;
+crop_url: string | null;
+person_name: string | null;
+confidence: number;
+};
+export type HeadAbstractAlbumResource = {
+config: App.Http.Resources.GalleryConfigs.AlbumConfig;
+resource: App.Http.Resources.Models.HeadAlbumResource | App.Http.Resources.Models.HeadSmartAlbumResource | App.Http.Resources.Models.HeadTagAlbumResource;
+};
+export type HeadAlbumResource = {
+id: string;
+title: string;
+slug: string | null;
+owner_name: string | null;
+description: string | null;
+copyright: string | null;
+track_url: string | null;
+license: string;
+header_id: string | null;
+parent_id: string | null;
+has_albums: boolean;
+num_children: number;
+num_photos: number;
+cover_id: string | null;
+policy: App.Http.Resources.Models.Utils.AlbumProtectionPolicy;
+rights: App.Http.Resources.Rights.AlbumRightsResource;
+preFormattedData: App.Http.Resources.Models.Utils.PreFormattedAlbumData;
+editable: App.Http.Resources.Editable.EditableBaseAlbumResource | null;
+is_pinned: boolean;
+statistics: App.Http.Resources.Models.AlbumStatisticsResource | null;
+};
+export type HeadSmartAlbumResource = {
+id: string;
+title: string;
+policy: App.Http.Resources.Models.Utils.AlbumProtectionPolicy;
+rights: App.Http.Resources.Rights.AlbumRightsResource;
+preFormattedData: App.Http.Resources.Models.Utils.PreFormattedAlbumData;
+statistics: null | null;
+};
+export type HeadTagAlbumResource = {
+id: string;
+title: string;
+slug: string | null;
+owner_name: string | null;
+copyright: string | null;
+is_tag_album: boolean;
+show_tags: Array<string>;
+policy: App.Http.Resources.Models.Utils.AlbumProtectionPolicy;
+rights: App.Http.Resources.Rights.AlbumRightsResource;
+preFormattedData: App.Http.Resources.Models.Utils.PreFormattedAlbumData;
+editable: App.Http.Resources.Editable.EditableBaseAlbumResource | null;
+statistics: App.Http.Resources.Models.AlbumStatisticsResource | null;
+};
+export type JobHistoryResource = {
+username: string;
+status: 'ready'|'success'|'failure'|'started';
+created_at: string;
+updated_at: string;
+job: string;
+};
+export type LightUserResource = {
+id: number;
+username: string;
+};
+export type LiveMetricsResource = {
+created_at: string;
+visitor_id: string;
+action: App.Enum.MetricsAction;
+photo_id: string | null;
+album_id: string;
+title: string;
+url: string | null;
+};
+export type PersonResource = {
+id: string;
+name: string;
+user_id: number | null;
+is_searchable: boolean;
+face_count: number;
+photo_count: number;
+representative_crop_url: string | null;
+};
+export type PhotoAlbumResource = {
+id: string;
+title: string;
+};
+export type PhotoRatingResource = {
+rating_user: number;
+rating_count: number;
+rating_avg: number;
+};
+export type PhotoResource = {
+id: string;
+album_id: string | null;
+checksum: string;
+created_at: string;
+description: string;
+is_highlighted: boolean;
+license: App.Enum.LicenseType;
+live_photo_checksum: string | null;
+live_photo_content_id: string | null;
+live_photo_url: string | null;
+original_checksum: string;
+size_variants: App.Http.Resources.Models.SizeVariantsResouce;
+tags: Array<string>;
+taken_at: string | null;
+taken_at_orig_tz: string | null;
+title: string;
+type: string;
+updated_at: string;
+next_photo_id: string | null;
+previous_photo_id: string | null;
+preformatted: App.Http.Resources.Models.Utils.PreformattedPhotoData;
+precomputed: App.Http.Resources.Models.Utils.PreComputedPhotoData;
+timeline: App.Http.Resources.Models.Utils.TimelineData | null;
+palette: App.Http.Resources.Models.ColourPaletteResource | null;
+statistics: App.Http.Resources.Models.PhotoStatisticsResource | null;
+rating: App.Http.Resources.Models.PhotoRatingResource | null;
+faces: Array<App.Http.Resources.Models.FaceResource>;
+hidden_face_count: number;
+};
+export type PhotoStatisticsResource = {
+visit_count: number;
+download_count: number;
+favourite_count: number;
+shared_count: number;
+rating_count: number;
+rating_avg: number | null;
+};
+export type RenamerPreviewResource = {
+id: string;
+original: string;
+new: string;
+};
+export type RenamerRuleResource = {
+id: number;
+order: number;
+owner_id: number;
+rule: string;
+description: string;
+needle: string;
+replacement: string;
+mode: App.Enum.RenamerModeType;
+is_enabled: boolean;
+is_photo_rule: boolean;
+is_album_rule: boolean;
+};
+export type SizeVariantResource = {
+type: App.Enum.SizeVariantType;
+locale: string;
+filesize: string;
+height: number;
+width: number;
+url: string | null;
+is_watermarked: boolean;
+};
+export type SizeVariantsResouce = {
+raw: App.Http.Resources.Models.SizeVariantResource | null;
+original: App.Http.Resources.Models.SizeVariantResource | null;
+medium2x: App.Http.Resources.Models.SizeVariantResource | null;
+medium: App.Http.Resources.Models.SizeVariantResource | null;
+small2x: App.Http.Resources.Models.SizeVariantResource | null;
+small: App.Http.Resources.Models.SizeVariantResource | null;
+thumb2x: App.Http.Resources.Models.SizeVariantResource | null;
+thumb: App.Http.Resources.Models.SizeVariantResource | null;
+placeholder: App.Http.Resources.Models.SizeVariantResource | null;
+};
+export type TargetAlbumResource = {
+id: string | null;
+title: string;
+original: string;
+short_title: string;
+thumb: string;
+};
+export type ThumbAlbumResource = {
+id: string;
+title: string;
+description: string | null;
+thumb: App.Http.Resources.Models.ThumbResource | null;
+is_nsfw: boolean;
+is_pinned: boolean;
+is_public: boolean;
+is_link_required: boolean;
+is_password_required: boolean;
+is_tag_album: boolean;
+has_subalbum: boolean;
+num_subalbums: number;
+num_photos: number;
+created_at: string;
+formatted_min_max: string | null;
+owner: string | null;
+rights: App.Http.Resources.Rights.AlbumRightsResource;
+timeline: App.Http.Resources.Models.Utils.TimelineData | null;
+};
+export type ThumbResource = {
+id: string;
+type: string;
+thumb: string | null;
+thumb2x: string | null;
+placeholder: string | null;
+};
+export type UserGroupResource = {
+id: number;
+name: string;
+description: string;
+members: App.Http.Resources.Models.UserMemberGroupResource[];
+rights: App.Http.Resources.Rights.UserGroupRightResource;
+};
+export type UserManagementResource = {
+id: number;
+username: string;
+may_administrate: boolean;
+may_upload: boolean;
+may_edit_own_settings: boolean;
+is_owner: boolean;
+quota_kb: number | null;
+description: string | null;
+note: string | null;
+space: number | null;
+};
+export type UserMemberGroupResource = {
+id: number;
+username: string;
+role: App.Enum.UserGroupRole;
+};
+export type UserResource = {
+id: number | null;
+has_token: boolean | null;
+username: string | null;
+email: string | null;
+is_ldap: boolean;
+shared_albums_visibility: App.Enum.UserSharedAlbumsVisibility;
+};
+export type WebAuthnResource = {
+id: string;
+alias: string | null;
+created_at: string;
+};
 }
 declare namespace App.Http.Resources.Models.Duplicates {
-	export type Duplicate = {
-		album_id: string;
-		album_title: string;
-		photo_id: string;
-		photo_title: string;
-		checksum: string;
-		url: string | null;
-	};
-	export type DuplicateCount = {
-		pure_duplicates: number;
-		title_duplicates: number;
-		duplicates_within_album: number;
-	};
+export type Duplicate = {
+album_id: string;
+album_title: string;
+photo_id: string;
+photo_title: string;
+checksum: string;
+url: string | null;
+};
+export type DuplicateCount = {
+pure_duplicates: number;
+title_duplicates: number;
+duplicates_within_album: number;
+};
 }
 declare namespace App.Http.Resources.Models.Utils {
-	export type AlbumProtectionPolicy = {
-		is_public: boolean;
-		is_link_required: boolean;
-		is_nsfw: boolean;
-		grants_full_photo_access: boolean;
-		grants_download: boolean;
-		grants_upload: boolean;
-		is_password_required: boolean;
-	};
-	export type HeaderFocusData = {
-		x: number;
-		y: number;
-	};
-	export type PreComputedPhotoData = {
-		is_video: boolean;
-		is_raw: boolean;
-		is_livephoto: boolean;
-		is_camera_date: boolean;
-		has_exif: boolean;
-		has_location: boolean;
-		is_taken_at_modified: boolean;
-		latitude: number | null;
-		longitude: number | null;
-		altitude: number | null;
-	};
-	export type PreFormattedAlbumData = {
-		url: string | null;
-		title: string;
-		min_max_text: string | null;
-		album_id: string;
-		license: string;
-		num_children: number;
-		num_photos: number;
-		created_at: string | null;
-		description: string | null;
-		copyright: string | null;
-		palette: App.Http.Resources.Models.ColourPaletteResource | null;
-		title_color: App.Enum.AlbumTitleColor | null;
-		title_position: App.Enum.AlbumTitlePosition | null;
-		header_photo_focus: App.Http.Resources.Models.Utils.HeaderFocusData | null;
-	};
-	export type PreformattedPhotoData = {
-		created_at: string;
-		taken_at: string | null;
-		date_overlay: string;
-		make: string | null;
-		model: string | null;
-		shutter: string;
-		aperture: string;
-		iso: string;
-		lens: string;
-		focal: string | null;
-		duration: string;
-		fps: string;
-		filesize: string;
-		resolution: string;
-		latitude: string | null;
-		longitude: string | null;
-		altitude: string | null;
-		location: string | null;
-		license: string;
-		description: string;
-	};
-	export type TimelineData = {
-		time_date: string;
-		format: string;
-	};
-	export type UserToken = {
-		token: string;
-	};
+export type AlbumProtectionPolicy = {
+is_public: boolean;
+is_link_required: boolean;
+is_nsfw: boolean;
+grants_full_photo_access: boolean;
+grants_download: boolean;
+grants_upload: boolean;
+is_password_required: boolean;
+};
+export type HeaderFocusData = {
+x: number;
+y: number;
+};
+export type PreComputedPhotoData = {
+is_video: boolean;
+is_raw: boolean;
+is_livephoto: boolean;
+is_camera_date: boolean;
+has_exif: boolean;
+has_location: boolean;
+is_taken_at_modified: boolean;
+latitude: number | null;
+longitude: number | null;
+altitude: number | null;
+};
+export type PreFormattedAlbumData = {
+url: string | null;
+title: string;
+min_max_text: string | null;
+album_id: string;
+license: string;
+num_children: number;
+num_photos: number;
+created_at: string | null;
+description: string | null;
+copyright: string | null;
+palette: App.Http.Resources.Models.ColourPaletteResource | null;
+title_color: App.Enum.AlbumTitleColor | null;
+title_position: App.Enum.AlbumTitlePosition | null;
+header_photo_focus: App.Http.Resources.Models.Utils.HeaderFocusData | null;
+};
+export type PreformattedPhotoData = {
+created_at: string;
+taken_at: string | null;
+date_overlay: string;
+make: string | null;
+model: string | null;
+shutter: string;
+aperture: string;
+iso: string;
+lens: string;
+focal: string | null;
+duration: string;
+fps: string;
+filesize: string;
+resolution: string;
+latitude: string | null;
+longitude: string | null;
+altitude: string | null;
+location: string | null;
+license: string;
+description: string;
+};
+export type TimelineData = {
+time_date: string;
+format: string;
+};
+export type UserToken = {
+token: string;
+};
 }
 declare namespace App.Http.Resources.Oauth {
-	export type OauthRegistrationData = {
-		provider_type: App.Enum.OauthProvidersType;
-		is_enabled: boolean;
-		registration_route: string;
-	};
+export type OauthRegistrationData = {
+provider_type: App.Enum.OauthProvidersType;
+is_enabled: boolean;
+registration_route: string;
+};
 }
 declare namespace App.Http.Resources.Rights {
-	export type AlbumRightsResource = {
-		can_edit: boolean;
-		can_share: boolean;
-		can_share_with_users: boolean;
-		can_download: boolean;
-		can_upload: boolean;
-		can_move: boolean;
-		can_delete: boolean;
-		can_transfer: boolean;
-		can_access_original: boolean;
-		can_pasword_protect: boolean;
-		can_import_from_server: boolean;
-		can_make_purchasable: boolean;
-	};
-	export type GlobalRightsResource = {
-		root_album: App.Http.Resources.Rights.RootAlbumRightsResource;
-		settings: App.Http.Resources.Rights.SettingsRightsResource;
-		user_management: App.Http.Resources.Rights.UserManagementRightsResource;
-		user: App.Http.Resources.Rights.UserRightsResource;
-		modules: App.Http.Resources.Rights.ModulesRightsResource;
-	};
-	export type ModulesRightsResource = {
-		is_map_enabled: boolean;
-		is_mod_frame_enabled: boolean;
-		is_mod_flow_enabled: boolean;
-		is_watermarker_enabled: boolean;
-		is_photo_timeline_enabled: boolean;
-		is_mod_renamer_enabled: boolean;
-		is_mod_webshop_enabled: boolean;
-		is_contact_enabled: boolean;
-		messages_count: number;
-	};
-	export type PhotoRightsResource = {
-		can_edit: boolean;
-		can_download: boolean;
-		can_access_full_photo: boolean;
-	};
-	export type RootAlbumRightsResource = {
-		can_edit: boolean;
-		can_upload: boolean;
-		can_see_live_metrics: boolean;
-		can_import_from_server: boolean;
-		can_highlight: boolean;
-	};
-	export type SettingsRightsResource = {
-		can_edit: boolean;
-		can_see_logs: boolean;
-		can_see_diagnostics: boolean;
-		can_update: boolean;
-		can_access_dev_tools: boolean;
-		can_acess_user_groups: boolean;
-	};
-	export type UserGroupRightResource = {
-		can_edit: boolean;
-		can_manage: boolean;
-	};
-	export type UserManagementRightsResource = {
-		can_create: boolean;
-		can_list: boolean;
-		can_edit: boolean;
-		can_delete: boolean;
-	};
-	export type UserRightsResource = {
-		can_edit: boolean;
-	};
+export type AlbumRightsResource = {
+can_edit: boolean;
+can_share: boolean;
+can_share_with_users: boolean;
+can_download: boolean;
+can_upload: boolean;
+can_move: boolean;
+can_delete: boolean;
+can_transfer: boolean;
+can_access_original: boolean;
+can_pasword_protect: boolean;
+can_import_from_server: boolean;
+can_make_purchasable: boolean;
+};
+export type GlobalRightsResource = {
+root_album: App.Http.Resources.Rights.RootAlbumRightsResource;
+settings: App.Http.Resources.Rights.SettingsRightsResource;
+user_management: App.Http.Resources.Rights.UserManagementRightsResource;
+user: App.Http.Resources.Rights.UserRightsResource;
+modules: App.Http.Resources.Rights.ModulesRightsResource;
+};
+export type ModulesRightsResource = {
+is_map_enabled: boolean;
+is_mod_frame_enabled: boolean;
+is_mod_flow_enabled: boolean;
+is_watermarker_enabled: boolean;
+is_photo_timeline_enabled: boolean;
+is_mod_renamer_enabled: boolean;
+is_mod_webshop_enabled: boolean;
+is_contact_enabled: boolean;
+messages_count: number;
+};
+export type PhotoRightsResource = {
+can_edit: boolean;
+can_download: boolean;
+can_access_full_photo: boolean;
+};
+export type RootAlbumRightsResource = {
+can_edit: boolean;
+can_upload: boolean;
+can_see_live_metrics: boolean;
+can_import_from_server: boolean;
+can_highlight: boolean;
+};
+export type SettingsRightsResource = {
+can_edit: boolean;
+can_see_logs: boolean;
+can_see_diagnostics: boolean;
+can_update: boolean;
+can_access_dev_tools: boolean;
+can_acess_user_groups: boolean;
+};
+export type UserGroupRightResource = {
+can_edit: boolean;
+can_manage: boolean;
+};
+export type UserManagementRightsResource = {
+can_create: boolean;
+can_list: boolean;
+can_edit: boolean;
+can_delete: boolean;
+};
+export type UserRightsResource = {
+can_edit: boolean;
+};
 }
 declare namespace App.Http.Resources.Root {
-	export type AuthConfig = {
-		oauthProviders: { [key: number]: App.Enum.OauthProvidersType };
-		u2f_enabled: boolean;
-	};
-	export type VersionResource = {
-		version: string | null;
-		is_new_release_available: boolean;
-		is_git_update_available: boolean;
-	};
+export type AuthConfig = {
+oauthProviders: { [key: number]: App.Enum.OauthProvidersType };
+u2f_enabled: boolean;
+};
+export type VersionResource = {
+version: string | null;
+is_new_release_available: boolean;
+is_git_update_available: boolean;
+};
 }
 declare namespace App.Http.Resources.Search {
-	export type InitResource = {
-		search_minimum_length: number;
-		photo_layout: App.Enum.PhotoLayoutType;
-	};
-	export type ResultsResource = {
-		albums: App.Http.Resources.Models.ThumbAlbumResource[];
-		photos: App.Http.Resources.Models.PhotoResource[];
-		current_page: number;
-		from: number;
-		last_page: number;
-		per_page: number;
-		to: number;
-		total: number;
-	};
+export type InitResource = {
+search_minimum_length: number;
+photo_layout: App.Enum.PhotoLayoutType;
+};
+export type ResultsResource = {
+albums: App.Http.Resources.Models.ThumbAlbumResource[];
+photos: App.Http.Resources.Models.PhotoResource[];
+current_page: number;
+from: number;
+last_page: number;
+per_page: number;
+to: number;
+total: number;
+};
 }
 declare namespace App.Http.Resources.Shop {
-	export type CatalogResource = {
-		album_purchasable: App.Http.Resources.Shop.PurchasableResource | null;
-		children_purchasables: App.Http.Resources.Shop.PurchasableResource[];
-		photo_purchasables: App.Http.Resources.Shop.PurchasableResource[];
-	};
-	export type CheckoutOptionResource = {
-		currency: string;
-		allow_guest_checkout: boolean;
-		is_offline: boolean;
-		terms_url: string;
-		privacy_url: string;
-		payment_providers: App.Enum.OmnipayProviderType[];
-		mollie_profile_id: string;
-		stripe_public_key: string;
-		paypal_client_id: string;
-		is_test_mode: boolean;
-		is_lycheeorg_disclaimer_enabled: boolean;
-	};
-	export type CheckoutResource = {
-		is_success: boolean;
-		is_redirect: boolean;
-		redirect_url: string | null;
-		complete_url: string | null;
-		message: string;
-		order: App.Http.Resources.Shop.OrderResource | null;
-	};
-	export type ConfigOptionResource = {
-		currency: string;
-		default_price_cents: number;
-		default_license: App.Enum.PurchasableLicenseType;
-		default_size: App.Enum.PurchasableSizeVariantType;
-	};
-	export type EditablePurchasableResource = {
-		purchasable_id: number;
-		album_id: string | null;
-		album_title: string | null;
-		photo_id: string | null;
-		photo_title: string | null;
-		photo_url: string | null;
-		prices: App.Http.Resources.Shop.PriceResource[] | null;
-		owner_notes: string | null;
-		description: string | null;
-		is_active: boolean;
-	};
-	export type OrderItemResource = {
-		id: number;
-		order_id: number;
-		purchasable_id: number | null;
-		album_id: string | null;
-		photo_id: string | null;
-		title: string;
-		license_type: App.Enum.PurchasableLicenseType;
-		price: string;
-		size_variant_type: App.Enum.PurchasableSizeVariantType;
-		item_notes: string | null;
-		content_url: string | null;
-	};
-	export type OrderResource = {
-		id: number;
-		provider: App.Enum.OmnipayProviderType | null;
-		transaction_id: string;
-		username: string | null;
-		email: string | null;
-		status: App.Enum.PaymentStatusType;
-		amount: string;
-		paid_at: string | null;
-		created_at: string | null;
-		updated_at: string | null;
-		comment: string | null;
-		items: App.Http.Resources.Shop.OrderItemResource[] | null;
-		can_process_payment: boolean;
-	};
-	export type PriceResource = {
-		size_variant: App.Enum.PurchasableSizeVariantType;
-		license_type: App.Enum.PurchasableLicenseType;
-		price: string;
-		price_cents: number;
-	};
-	export type PurchasableResource = {
-		purchasable_id: number;
-		album_id: string | null;
-		photo_id: string | null;
-		prices: App.Http.Resources.Shop.PriceResource[] | null;
-		description: string;
-		is_active: boolean;
-	};
+export type CatalogResource = {
+album_purchasable: App.Http.Resources.Shop.PurchasableResource | null;
+children_purchasables: App.Http.Resources.Shop.PurchasableResource[];
+photo_purchasables: App.Http.Resources.Shop.PurchasableResource[];
+};
+export type CheckoutOptionResource = {
+currency: string;
+allow_guest_checkout: boolean;
+is_offline: boolean;
+terms_url: string;
+privacy_url: string;
+payment_providers: App.Enum.OmnipayProviderType[];
+mollie_profile_id: string;
+stripe_public_key: string;
+paypal_client_id: string;
+is_test_mode: boolean;
+is_lycheeorg_disclaimer_enabled: boolean;
+};
+export type CheckoutResource = {
+is_success: boolean;
+is_redirect: boolean;
+redirect_url: string | null;
+complete_url: string | null;
+message: string;
+order: App.Http.Resources.Shop.OrderResource | null;
+};
+export type ConfigOptionResource = {
+currency: string;
+default_price_cents: number;
+default_license: App.Enum.PurchasableLicenseType;
+default_size: App.Enum.PurchasableSizeVariantType;
+};
+export type EditablePurchasableResource = {
+purchasable_id: number;
+album_id: string | null;
+album_title: string | null;
+photo_id: string | null;
+photo_title: string | null;
+photo_url: string | null;
+prices: App.Http.Resources.Shop.PriceResource[]|null;
+owner_notes: string | null;
+description: string | null;
+is_active: boolean;
+};
+export type OrderItemResource = {
+id: number;
+order_id: number;
+purchasable_id: number | null;
+album_id: string | null;
+photo_id: string | null;
+title: string;
+license_type: App.Enum.PurchasableLicenseType;
+price: string;
+size_variant_type: App.Enum.PurchasableSizeVariantType;
+item_notes: string | null;
+content_url: string | null;
+};
+export type OrderResource = {
+id: number;
+provider: App.Enum.OmnipayProviderType | null;
+transaction_id: string;
+username: string | null;
+email: string | null;
+status: App.Enum.PaymentStatusType;
+amount: string;
+paid_at: string | null;
+created_at: string | null;
+updated_at: string | null;
+comment: string | null;
+items: App.Http.Resources.Shop.OrderItemResource[]|null;
+can_process_payment: boolean;
+};
+export type PriceResource = {
+size_variant: App.Enum.PurchasableSizeVariantType;
+license_type: App.Enum.PurchasableLicenseType;
+price: string;
+price_cents: number;
+};
+export type PurchasableResource = {
+purchasable_id: number;
+album_id: string | null;
+photo_id: string | null;
+prices: App.Http.Resources.Shop.PriceResource[]|null;
+description: string;
+is_active: boolean;
+};
 }
 declare namespace App.Http.Resources.Statistics {
-	export type Album = {
-		username: string;
-		title: string;
-		is_nsfw: boolean;
-		left: number;
-		right: number;
-		num_photos: number;
-		num_descendants: number;
-		size: number;
-	};
-	export type CountsData = {
-		data: Array<App.Http.Resources.Statistics.DayCount>;
-		low_number_of_shoots_per_day: number;
-		medium_number_of_shoots_per_day: number;
-		high_number_of_shoots_per_day: number;
-		min_created_at: string;
-		min_taken_at: string;
-	};
-	export type DayCount = {
-		date: string;
-		count: number;
-	};
-	export type Sizes = {
-		type: App.Enum.SizeVariantType;
-		label: string;
-		size: number;
-	};
-	export type UserSpace = {
-		id: number;
-		username: string;
-		size: number;
-	};
+export type Album = {
+username: string;
+title: string;
+is_nsfw: boolean;
+left: number;
+right: number;
+num_photos: number;
+num_descendants: number;
+size: number;
+};
+export type CountsData = {
+data: Array<App.Http.Resources.Statistics.DayCount>;
+low_number_of_shoots_per_day: number;
+medium_number_of_shoots_per_day: number;
+high_number_of_shoots_per_day: number;
+min_created_at: string;
+min_taken_at: string;
+};
+export type DayCount = {
+date: string;
+count: number;
+};
+export type Sizes = {
+type: App.Enum.SizeVariantType;
+label: string;
+size: number;
+};
+export type UserSpace = {
+id: number;
+username: string;
+size: number;
+};
 }
 declare namespace App.Http.Resources.Tags {
-	export type TagResource = {
-		id: number;
-		name: string;
-		num: number;
-	};
-	export type TagWithPhotosResource = {
-		id: number;
-		name: string;
-		photos: App.Http.Resources.Models.PhotoResource[];
-	};
-	export type TagsResource = {
-		can_edit: boolean;
-		tags: App.Http.Resources.Tags.TagResource[];
-	};
+export type TagResource = {
+id: number;
+name: string;
+num: number;
+};
+export type TagWithPhotosResource = {
+id: number;
+name: string;
+photos: App.Http.Resources.Models.PhotoResource[];
+};
+export type TagsResource = {
+can_edit: boolean;
+tags: App.Http.Resources.Tags.TagResource[];
+};
 }
 declare namespace App.Http.Resources.Timeline {
-	export type InitResource = {
-		photo_layout: App.Enum.PhotoLayoutType;
-		is_timeline_page_enabled: boolean;
-		config: App.Http.Resources.GalleryConfigs.RootConfig;
-		rights: App.Http.Resources.Rights.RootAlbumRightsResource;
-	};
-	export type TimelineResource = {
-		photos: App.Http.Resources.Models.PhotoResource[];
-		current_page: number;
-		from: number;
-		last_page: number;
-		per_page: number;
-		to: number;
-		total: number;
-	};
+export type InitResource = {
+photo_layout: App.Enum.PhotoLayoutType;
+is_timeline_page_enabled: boolean;
+config: App.Http.Resources.GalleryConfigs.RootConfig;
+rights: App.Http.Resources.Rights.RootAlbumRightsResource;
+};
+export type TimelineResource = {
+photos: App.Http.Resources.Models.PhotoResource[];
+current_page: number;
+from: number;
+last_page: number;
+per_page: number;
+to: number;
+total: number;
+};
 }
diff --git a/resources/js/services/people-service.ts b/resources/js/services/people-service.ts
index dd59e832069..ad0f8497e5c 100644
--- a/resources/js/services/people-service.ts
+++ b/resources/js/services/people-service.ts
@@ -7,11 +7,11 @@ const PeopleService = {
 	},
 
 	getPerson(id: string): Promise<AxiosResponse<App.Http.Resources.Models.PersonResource>> {
-		return axios.get(`${Constants.getApiUrl()}People/${id}`, { data: {} });
+		return axios.get(`${Constants.getApiUrl()}Person/${id}`, { data: {} });
 	},
 
 	getPhotos(id: string, page: number = 1): Promise<AxiosResponse<PaginatedResponse<App.Http.Resources.Models.PhotoResource>>> {
-		return axios.get(`${Constants.getApiUrl()}People/${id}/photos`, { params: { page }, data: {} });
+		return axios.get(`${Constants.getApiUrl()}Person/${id}/photos`, { params: { page }, data: {} });
 	},
 
 	create(name: string): Promise<AxiosResponse<App.Http.Resources.Models.PersonResource>> {
@@ -19,29 +19,29 @@ const PeopleService = {
 	},
 
 	update(id: string, data: { name?: string; is_searchable?: boolean }): Promise<AxiosResponse<App.Http.Resources.Models.PersonResource>> {
-		return axios.patch(`${Constants.getApiUrl()}People/${id}`, data);
+		return axios.patch(`${Constants.getApiUrl()}Person/${id}`, data);
 	},
 
 	destroy(id: string): Promise<AxiosResponse> {
-		return axios.delete(`${Constants.getApiUrl()}People/${id}`);
+		return axios.delete(`${Constants.getApiUrl()}Person/${id}`);
 	},
 
 	claim(id: string): Promise<AxiosResponse> {
-		return axios.post(`${Constants.getApiUrl()}People/${id}/claim`);
+		return axios.post(`${Constants.getApiUrl()}Person/${id}/claim`);
 	},
 
 	unclaim(id: string): Promise<AxiosResponse> {
-		return axios.delete(`${Constants.getApiUrl()}People/${id}/claim`);
+		return axios.delete(`${Constants.getApiUrl()}Person/${id}/claim`);
 	},
 
 	merge(targetId: string, sourcePersonId: string): Promise<AxiosResponse> {
-		return axios.post(`${Constants.getApiUrl()}People/${targetId}/merge`, { source_person_id: sourcePersonId });
+		return axios.post(`${Constants.getApiUrl()}Person/${targetId}/merge`, { source_person_id: sourcePersonId });
 	},
 
 	claimBySelfie(file: File): Promise<AxiosResponse<App.Http.Resources.Models.PersonResource>> {
 		const form = new FormData();
 		form.append("selfie", file);
-		return axios.post(`${Constants.getApiUrl()}People/claim-by-selfie`, form, {
+		return axios.post(`${Constants.getApiUrl()}Person/claim-by-selfie`, form, {
 			headers: { "Content-Type": "multipart/form-data" },
 		});
 	},

From d4abe21d3e5f600928c1050668bbd75d7b76a785 Mon Sep 17 00:00:00 2001
From: ildyria <beviguier@gmail.com>
Date: Mon, 23 Mar 2026 21:59:09 +0100
Subject: [PATCH 07/10] more spec

---
 .../features/030-ai-vision-service/plan.md    | 52 +++++++++++++--
 .../features/030-ai-vision-service/spec.md    | 66 ++++++++++++++++++-
 .../features/030-ai-vision-service/tasks.md   | 60 +++++++++++++++--
 docs/specs/4-architecture/open-questions.md   | 32 +++++++++
 4 files changed, 198 insertions(+), 12 deletions(-)

diff --git a/docs/specs/4-architecture/features/030-ai-vision-service/plan.md b/docs/specs/4-architecture/features/030-ai-vision-service/plan.md
index 7262ecbc1e2..f7ea7713bae 100644
--- a/docs/specs/4-architecture/features/030-ai-vision-service/plan.md
+++ b/docs/specs/4-architecture/features/030-ai-vision-service/plan.md
@@ -251,7 +251,47 @@ After each increment, verify:
 - _Commands:_ `php artisan test --filter=PersonPhotos`, `make phpstan`
 - _Exit:_ Paginated photos returned; access control respected.
 
-### Phase 3: Frontend (Vue3/TypeScript)
+### I20 – Clustering Endpoint: Python `POST /cluster` + PHP Ingestion & Trigger (≥90 min)
+
+- _Goal:_ Wire up the existing `FaceClusterer` (DBSCAN) to a FastAPI REST endpoint and complete the round-trip: Python runs clustering, posts suggestion pairs to Lychee, Lychee bulk-upserts `face_suggestions`. Admin can trigger clustering via a Maintenance API action.
+- _Preconditions:_ I2 complete (`FaceClusterer` and `EmbeddingStore` implemented); I10 complete (`face_suggestions` table exists, PHP ingestion pipeline in place); I11 complete (Maintenance endpoint pattern established).
+- _Steps:_
+  1. **Python** — Add `ClusterResponse` Pydantic schema (`{clusters: int, suggestions_generated: int}`) to `app/api/schemas.py`. Add `VISION_FACE_CLUSTER_EPS` env var to `AppSettings` (default `0.6`).
+  2. **Python** — Extend `app/clustering/clusterer.py` with `run_cluster_and_notify(store: EmbeddingStore, lychee_url: str, api_key: str) -> ClusterResponse`: reads all embeddings from store, runs DBSCAN, generates `(face_id, suggested_face_id, confidence)` pairs for every pair within the same cluster (cosine similarity as confidence), POSTs `{suggestions: [...]}` to `{lychee_url}/api/v2/FaceDetection/cluster-results` with `X-API-Key` header.
+  3. **Python** — Add `POST /cluster` route to `app/api/routes.py` (X-API-Key auth); calls `run_cluster_and_notify()`; returns `ClusterResponse`. Add unit + integration tests in `tests/test_clustering.py` (mock httpx POST to Lychee).
+  4. **PHP** — Implement `POST /api/v2/FaceDetection/cluster-results` endpoint in `FaceDetectionController` (or a new `FaceClusterResultsController`): auth via X-API-Key, validate body `{suggestions: [{face_id, suggested_face_id, confidence}]}`, bulk-upsert `face_suggestions` rows (upsert on `(face_id, suggested_face_id)`, update `confidence`), return `{updated_count: N}`. Register route.
+  5. **PHP** — Add `POST /api/v2/Maintenance::runFaceClustering` Maintenance endpoint (admin-only, follows existing check/do pattern): calls Python service `POST /cluster` via HTTP, returns 202 Accepted. Register route.
+  6. Write PHP feature tests for cluster-results ingestion (success, invalid API key, malformed body) and for the Maintenance trigger (success, service unavailable 503).
+- _Commands:_ `uv run pytest tests/test_clustering.py`, `php artisan test --filter=FaceCluster`, `make phpstan`
+- _Exit:_ `POST /cluster` on Python service triggers DBSCAN and POSTs pairs to Lychee; `POST /FaceDetection/cluster-results` bulk-upserts face_suggestions; Maintenance trigger returns 202; all tests green.
+
+### I21 – Embedding Sync on Deletion + Blur Threshold Filtering (≈60 min)
+
+- _Goal:_ Prevent stale embeddings from corrupting clustering/suggestions after face hard-deletes; discard blurry faces before they ever reach Lychee.
+- _Preconditions:_ I2 complete (EmbeddingStore implemented); I9 complete (`destroyDismissed` action exists); Photo model cascade delete exists.
+- _Steps:_
+  1. **Python** — Add `VISION_FACE_BLUR_THRESHOLD` (float, default `100.0`) to `AppSettings` in `app/config.py`. In `app/detection/detector.py`, after cropping each detected face region, compute its Laplacian variance using OpenCV/NumPy (`cv2.Laplacian(crop, cv2.CV_64F).var()`); exclude faces whose variance is below `VISION_FACE_BLUR_THRESHOLD`. Also add `VISION_FACE_CLUSTER_EPS` to `AppSettings` (default `0.6`) if not already present from I20.
+  2. **Python** — Add `DELETE /embeddings` route to `app/api/routes.py` (X-API-Key auth): accepts `{face_ids: [str]}`, calls `EmbeddingStore.delete_many(face_ids)`, returns `{deleted_count: int}`. Add `delete_many()` method to the `EmbeddingStore` protocol and both implementations (`SQLiteStore`, `PgVectorStore`). IDs not found are silently ignored.
+  3. **Python** — Add tests: `tests/test_detection.py` — blurry face below threshold not returned; sharp face above threshold returned. `tests/test_api.py` — `DELETE /embeddings` removes embeddings and returns count.
+  4. **PHP** — Create `DeleteFaceEmbeddingsJob` (queued): accepts `array<string> $faceIds`, calls Python `DELETE /embeddings` via HTTP with `X-API-Key`; logs warning on failure, never throws. Dispatch this job **after** `destroyDismissed` deletes Face records (FR-030-14, S-030-28).
+  5. **PHP** — Add `Face` model observer or hook into `Photo` cascade: after a Photo delete triggers Face cascade deletes, collect deleted face IDs and dispatch `DeleteFaceEmbeddingsJob` (S-030-29).
+  6. **PHP** — Write feature tests: `DELETE /Face/dismissed` → embeddings deleted (job dispatched with correct IDs); Photo delete → embeddings deleted; Python unavailable → Lychee deletion still succeeds, warning logged.
+- _Commands:_ `uv run pytest tests/test_detection.py tests/test_api.py`, `php artisan test --filter=FaceEmbeddingSync`, `make phpstan`
+- _Exit:_ Blurry faces never reach Lychee; dismissed/cascade-deleted Face embeddings are removed from the store; service unavailability does not block Lychee-side deletions.
+
+### I22 – Cluster Review UI: Browse & Bulk-Name/Dismiss Clusters (≥90 min)
+
+- _Goal:_ Give authorized users a dedicated page to review DBSCAN-produced face clusters (visually similar unassigned faces) and resolve them in bulk — either creating a Person and assigning all faces in one action, or dismissing the whole cluster as false-positives.
+- _Preconditions:_ I20 complete (`face_suggestions` populated by clustering); I9 complete (dismiss action exists); I7 complete (Person create + face assign available).
+- _Steps:_
+  1. **PHP** — Implement `GET /api/v2/FaceDetection/clusters` (API-030-18): derive clusters from the `face_suggestions` graph using connected-component grouping on unassigned (`person_id IS NULL`) and non-dismissed faces; return paginated list of `{cluster_id, size, faces: FaceResource[]}`. `cluster_id` is a deterministic hash of the sorted face IDs in the component. Respect `ai_vision_face_permission_mode` visibility rules.
+  2. **PHP** — Implement `POST /api/v2/FaceDetection/clusters/{cluster_id}/assign` (API-030-19): resolve cluster faces, create Person if `new_person_name` provided, bulk-update `face.person_id` for all faces in cluster, emit `face.cluster_assigned` telemetry. Return `{person_id, assigned_count}`.
+  3. **PHP** — Implement `POST /api/v2/FaceDetection/clusters/{cluster_id}/dismiss` (API-030-20): bulk-set `is_dismissed = true` for all faces in cluster, emit `face.cluster_dismissed` telemetry. Return `{dismissed_count}`.
+  4. Write feature tests: list clusters (unassigned faces grouped, assigned faces excluded), assign cluster (new person + faces linked), dismiss cluster (all faces dismissed). Test permission mode enforcement.
+  5. **Frontend** — Create `FaceClusters.vue` page at `/people/clusters`. Paginated grid of cluster cards: first 5 face-crop thumbnails + "+N more" overflow badge, cluster size badge, name input, “Create Person & Assign All” button, “Dismiss” button. “Run Cluster” button in page header calls `POST /Maintenance::runFaceClustering` then refreshes. Empty state when no clusters exist.
+  6. Add route `/people/clusters` to Vue Router; add “Clusters” navigation link under People in sidebar.
+- _Commands:_ `php artisan test --filter=FaceClusterReviewTest`, `make phpstan`, `npm run check`
+- _Exit:_ Clusters page shows unassigned face groups; bulk-assign creates Person and links all faces; bulk-dismiss marks all is_dismissed; “Run Cluster” triggers fresh clustering; all tests green.
 
 ### I13 – Frontend: People Page (≈90 min)
 
@@ -381,6 +421,12 @@ After each increment, verify:
 | S-030-24 | I9 | Face dismissed (is_dismissed toggle) |
 | S-030-25 | I9 | Admin hard-deletes all dismissed faces + crop files |
 | S-030-26 | I11 | Admin resets stuck-pending photos via Maintenance endpoint |
+| S-030-27 | I20 | Admin triggers clustering; suggestion pairs ingested into face_suggestions |
+| S-030-28 | I21 | Admin hard-deletes dismissed faces; embeddings deleted from Python store |
+| S-030-29 | I21 | Photo deleted; Face cascade-deleted; embeddings deleted from Python store |
+| S-030-30 | I21 | Blurry face below VISION_FACE_BLUR_THRESHOLD excluded from detection callback |
+| S-030-31 | I22 | Cluster Review page: admin names cluster → Person created, all faces assigned |
+| S-030-32 | I22 | Cluster Review page: admin dismisses cluster → all faces marked is_dismissed |
 
 ## Analysis Gate
 
@@ -388,7 +434,7 @@ _To be completed after spec, plan, and tasks align and before implementation beg
 
 ## Exit Criteria
 
-- [ ] All 19 increments (I1–I19) complete with passing tests.
+- [ ] All 22 increments (I1–I22) complete with passing tests.
 - [ ] PHPStan 0 errors.
 - [ ] php-cs-fixer clean.
 - [ ] npm run check / npm run format clean.
@@ -401,9 +447,7 @@ _To be completed after spec, plan, and tasks align and before implementation beg
 
 ## Follow-ups / Backlog
 
-- Auto-clustering UI — Python service clusters via `POST /cluster` (DBSCAN offline batch); dedicated cluster-review/confirm workflow is a future enhancement beyond manual assignment. *(Q-030-30 resolved)*
 - Face recognition accuracy tuning and confidence threshold configuration (admin UI for `VISION_FACE_DETECTION_THRESHOLD` / `VISION_FACE_MATCH_THRESHOLD`).
 - Notifications when a user is tagged in a new photo.
 - Performance optimisation for large Person/Face datasets (materialized views, caching face counts).
 - GPU acceleration for the Python service (optional CUDA/ROCm support in Dockerfile).
-- Cluster review UI — surface DBSCAN group results for bulk confirmation by admin.
diff --git a/docs/specs/4-architecture/features/030-ai-vision-service/spec.md b/docs/specs/4-architecture/features/030-ai-vision-service/spec.md
index 02b8522c9fb..8c864a8bdf1 100644
--- a/docs/specs/4-architecture/features/030-ai-vision-service/spec.md
+++ b/docs/specs/4-architecture/features/030-ai-vision-service/spec.md
@@ -42,7 +42,7 @@ Affected modules: **Models** (new Person, Face), **Migrations** (new tables + pi
 | ID | Requirement | Success path | Validation path | Failure path | Telemetry & traces | Source |
 |----|-------------|--------------|-----------------|--------------|---------------------|--------|
 | FR-030-01 | System shall store Person records with a name, optional User link (1-1), and a searchability flag. | Person created with name; optionally linked to a User; `is_searchable` defaults to the value of `ai_vision_face_person_is_searchable_default` config (default `true`). | Name must be non-empty string ≤255 chars; user_id must reference existing User and be unique across Person table (1-1). | Return 422 with validation errors. | `person.created`, `person.updated` | Owner directive |
-| FR-030-02 | System shall store Face records linking a detected face region in a Photo to an optional Person, including a server-side crop thumbnail path and a dismissal flag. *(Resolved Q-030-09: server-side crop; Q-030-16: is_dismissed; Q-030-25: crop storage path; Q-030-34: nginx-direct hash path)* | Face created with photo_id, bounding box (x, y, width, height as percentages), confidence score, `crop_token` (random high-entropy token, stored on Face model); crop file stored at `uploads/faces/{token[0:2]}/{token[2:4]}/{token}.jpg` and served directly by nginx (path is unguessable, no app-level auth required); person_id nullable (unassigned); `is_dismissed` defaults to `false`. | photo_id must exist; bounding box values 0.0–1.0; confidence 0.0–1.0. | Return 422; reject invalid photo_id with 404. | `face.created` | Owner directive, Q-030-09, Q-030-16, Q-030-25 |
+| FR-030-02 | System shall store Face records linking a detected face region in a Photo to an optional Person, including a server-side crop thumbnail path and a dismissal flag. The Python service shall filter detections by both confidence and sharpness before sending results to Lychee. *(Resolved Q-030-09: server-side crop; Q-030-16: is_dismissed; Q-030-25: crop storage path; Q-030-34: nginx-direct hash path)* | Face created with photo_id, bounding box (x, y, width, height as percentages), confidence score, `crop_token` (random high-entropy token, stored on Face model); crop file stored at `uploads/faces/{token[0:2]}/{token[2:4]}/{token}.jpg` and served directly by nginx (path is unguessable, no app-level auth required); person_id nullable (unassigned); `is_dismissed` defaults to `false`. Python service filters detections by two thresholds before callback: (a) `VISION_FACE_DETECTION_THRESHOLD` (confidence; default 0.5) — faces below excluded; (b) `VISION_FACE_BLUR_THRESHOLD` (Laplacian variance sharpness score; default `100.0`) — faces whose crop has a Laplacian variance below this value are excluded as too blurry to be usable for recognition. | photo_id must exist; bounding box values 0.0–1.0; confidence 0.0–1.0. | Return 422; reject invalid photo_id with 404. | `face.created` | Owner directive, Q-030-09, Q-030-16, Q-030-25 |
 | FR-030-03 | A Person can appear in multiple Photos (many-to-many through Face). The system shall provide an endpoint to list all photos containing a given Person. | GET endpoint returns paginated photos where at least one Face with matching person_id exists. | person_id must exist; pagination params validated. | 404 if Person not found; empty result set if no faces assigned. | — | Owner directive |
 | FR-030-04 | A Photo can contain multiple Persons. The system shall return all identified Persons when viewing a Photo's details. For non-searchable Persons, face overlays are hidden entirely for unauthorized viewers; a `hidden_face_count` integer is included instead. *(Resolved Q-030-10: hide overlay + count indicator)* | Photo detail response includes `faces` array (only searchable/authorized faces) + `hidden_face_count` (integer, count of suppressed non-searchable faces). | — | Graceful empty array if no faces detected; hidden_face_count = 0 if none suppressed. | — | Owner directive, Q-030-10 |
 | FR-030-05 | Users can link their account to a Person (1-1) via direct claim, and unlink via unclaim. Admins can link/unlink any Person-User pair, overriding user claims. Only one Person per User, one User per Person. *(Resolved Q-030-06: self-identification + admin override; Q-030-21: unclaim endpoint)* | User claims a Person; `person.user_id` set; old claim (if any) cleared. Admin can force-link/unlink any pair. User unclaims via `DELETE /api/v2/Person/{id}/claim`; sets `person.user_id = null`. | user_id unique on persons table; User must exist. Non-admin claim: 409 if Person already claimed by another User; 403 if `ai_vision_face_allow_user_claim` is `false`. Admin claim: overrides existing link; bypasses `ai_vision_face_allow_user_claim`. Unclaim: only linked User or admin. | 409 if Person already claimed (non-admin); 403 if `ai_vision_face_allow_user_claim` is `false` (non-admin); 403 if unclaim caller is not linked User or admin; 422 for validation errors. | `person.claimed`, `person.unclaimed` | Owner directive, Q-030-06, Q-030-21 |
@@ -53,6 +53,9 @@ Affected modules: **Models** (new Person, Face), **Migrations** (new tables + pi
 | FR-030-10 | Users can manually assign/reassign an unassigned Face to a Person, or create a new Person from a Face. Python service provides cluster suggestions for grouping similar faces. *(Resolved Q-030-03: auto-cluster with manual confirmation)* | Face's person_id updated; new Person created if requested. Cluster suggestions displayed as similarity scores in assignment UI. | Face must exist; target Person (if specified) must exist. | 404/422 for invalid references. | `face.assigned` | Owner directive, Q-030-03 |
 | FR-030-11 | Users can merge two Person records (combining all their Face associations). *(Resolved Q-030-22: merge direction — URL {id} = target kept; body source_person_id = source destroyed)* | All Faces of source Person reassigned to target Person (`{id}`); source Person deleted. | Both Persons must exist; user must have edit permission per `ai_vision_face_permission_mode`; body must supply `source_person_id`. | 404 if either Person not found; 403 if unauthorized. | `person.merged` | Owner directive, Q-030-22 |
 | FR-030-12 | Users can upload a selfie photo to claim a Person via face matching. Selfie sent to Python service's dedicated `POST /match` endpoint; image discarded immediately after matching. *(Resolved Q-030-06: selfie-upload claim; Q-030-11: discard after match; Q-030-12: dedicated /match endpoint; Q-030-13: lychee_face_id returned by /match)* | User uploads selfie → Python service `POST /match` returns top-N matches with `lychee_face_id` + confidence → if best match above `ai_vision_face_selfie_confidence_threshold`, Lychee resolves `lychee_face_id → Face → person_id` and links Person to User (same 1-1 rules as FR-030-05). Selfie image deleted after response. | Selfie must contain exactly one detectable face; confidence threshold configurable. | 422 if no face detected in selfie; 404 if no matching Person found; 409 if matched Person already claimed by another User. | `person.selfie_claim_requested`, `person.selfie_claim_matched` | Owner directive, Q-030-06, Q-030-11, Q-030-12, Q-030-13 |
+| FR-030-14 | When Face records are hard-deleted from Lychee (either via admin bulk-dismissed-delete or via cascade when a Photo is deleted), the corresponding embeddings shall also be removed from the Python service's embedding store to prevent stale data from polluting future clustering and suggestion results. | After hard-deleting Face records, Lychee calls Python `DELETE /embeddings` with `{face_ids: [str]}`. Python removes those embeddings from `EmbeddingStore`. The call is best-effort (fire-and-forget via queued job): Lychee proceeds with the deletion regardless of whether the Python service responds. Failures are logged as warnings. | face_ids must be a non-empty list of strings. | If the Python service is unavailable, log warning and continue — do not fail or roll back the Lychee-side deletion. | `face.embeddings_deleted` (with `count`) | Owner directive |
+| FR-030-15 | System shall provide a Cluster Review page where authorized users can browse face clusters produced by DBSCAN (faces grouped by visual similarity, not yet assigned to a Person) and bulk-name or dismiss an entire cluster in one action. | `GET /api/v2/FaceDetection/clusters` returns a paginated list of clusters; each cluster contains a `cluster_id` (integer, equal to `faces.cluster_label`, stable between clustering runs), a list of `FaceResource` items (crop_url, confidence, photo_id), and a `size` count. The page renders face-crop grids grouped by cluster. User can: (a) type a name and click “Create Person & assign all” — creates a new Person and bulk-assigns every face in the cluster to it via `POST /api/v2/FaceDetection/clusters/{cluster_id}/assign`; (b) click “Dismiss cluster” — marks every face `is_dismissed = true` via `POST /api/v2/FaceDetection/clusters/{cluster_id}/dismiss`. | Cluster review page respects `ai_vision_face_permission_mode` (same visibility rules as People page). `cluster_id` must be a valid integer `cluster_label` value with at least one qualifying face. | 404 if `cluster_id` not found; 403 if unauthorized. | `face.cluster_assigned` (with `cluster_id`, `person_id`, `face_count`), `face.cluster_dismissed` (with `cluster_id`, `face_count`) | Owner directive, Q-030-49 |
+| FR-030-13 | Admin can trigger offline DBSCAN face clustering across all stored embeddings to generate cross-photo face suggestion pairs and persist cluster labels on Face records. The Python service exposes `POST /cluster`; Lychee exposes `POST /FaceDetection/cluster-results` to ingest the results. *(Q-030-49)* | Admin calls `POST /api/v2/Maintenance::runFaceClustering` (admin-only) → Lychee calls Python service `POST /cluster` (X-API-Key auth) → Python reads all stored embeddings from `EmbeddingStore`, runs DBSCAN (eps from `VISION_FACE_CLUSTER_EPS` env var, default configurable), generates: (a) `{face_id: str, cluster_label: int}[]` where label = DBSCAN integer label (noise faces omitted); (b) `(face_id, suggested_face_id, confidence)` pairs for every intra-cluster pair using cosine similarity → POSTs both to `POST /api/v2/FaceDetection/cluster-results` (X-API-Key auth) → Lychee: bulk-updates `faces.cluster_label` (all previously clustered faces first reset to NULL, then new labels written); bulk-upserts `face_suggestions` rows (unique on `(face_id, suggested_face_id)`); returns `{faces_labeled: N, suggestions_updated: M}`. Maintenance trigger returns 202 Accepted; clustering runs asynchronously on the Python side. | Python endpoint: X-API-Key required. PHP cluster-results endpoint: X-API-Key required; body: `{labels: [{face_id: str, cluster_label: int}], suggestions: [{face_id: str, suggested_face_id: str, confidence: float}]}`. Both arrays optional (empty array = no-op for that field). Maintenance trigger: admin-only session auth. | 503 if Python service unavailable; 401 for invalid API key; no-op if no embeddings stored (returns `{faces_labeled: 0, suggestions_updated: 0}`). | `face.clustering_triggered`, `face.cluster_labels_written` (with `faces_labeled`), `face.cluster_suggestions_ingested` (with `suggestions_updated`) | Owner directive, Q-030-49 |
 
 ## Non-Functional Requirements
 
@@ -228,6 +231,39 @@ Read via `config('features.ai-vision.face-url')` and `config('features.ai-vision
 +------------------------------------------+
 ```
 
+### Cluster Review Page
+
+```
++------------------------------------------------------------------+
+| Lychee > People > Clusters                         [Run Cluster] |
++------------------------------------------------------------------+
+|  Showing 24 clusters of unassigned faces                         |
++------------------------------------------------------------------+
+|                                                                  |
+|  Cluster #1  (12 faces)                                         |
+|  +------+ +------+ +------+ +------+ +------+  [+7 more]        |
+|  |      | |      | |      | |      | |      |                   |
+|  | crop | | crop | | crop | | crop | | crop |                   |
+|  |      | |      | |      | |      | |      |                   |
+|  +------+ +------+ +------+ +------+ +------+                   |
+|  [ _______________ ]  [Create Person & Assign All]  [Dismiss]   |
+|                                                                  |
+|  Cluster #2  (7 faces)                                          |
+|  +------+ +------+ +------+ +------+ +------+  [+2 more]        |
+|  |      | |      | |      | |      | |      |                   |
+|  | crop | | crop | | crop | | crop | | crop |                   |
+|  |      | |      | |      | |      | |      |                   |
+|  +------+ +------+ +------+ +------+ +------+                   |
+|  [ _______________ ]  [Create Person & Assign All]  [Dismiss]   |
+|                                                                  |
+|  Cluster #3  (3 faces)     · · ·                                |
+|                                                                  |
+|  [Load more clusters]                                           |
++------------------------------------------------------------------+
+```
+
+*Note: "Run Cluster" button triggers `POST /api/v2/Maintenance::runFaceClustering` then refreshes the page. Clusters with faces already assigned to a Person are not shown.*
+
 ## Branch & Scenario Matrix
 
 | Scenario ID | Description / Expected outcome |
@@ -255,6 +291,12 @@ Read via `config('features.ai-vision.face-url')` and `config('features.ai-vision
 | S-030-21 | User uploads selfie with no detectable face → 422 error |
 | S-030-22 | User uploads selfie but no matching Person found → 404, user informed |
 | S-030-23 | Photo uploaded with `ai_vision_face_enabled` → auto-scan job dispatched |
+| S-030-27 | Admin triggers face clustering → Python runs DBSCAN across all stored embeddings → suggestion pairs bulk-upserted into `face_suggestions` → FaceAssignmentModal shows updated suggestions |
+| S-030-28 | Admin hard-deletes all dismissed faces → Lychee deletes Face records → Python `DELETE /embeddings` called with their IDs → embeddings removed from store |
+| S-030-29 | Photo deleted → Face records cascade-deleted → Python `DELETE /embeddings` called → stale embeddings removed |
+| S-030-30 | Face detected in photo with sharpness below `VISION_FACE_BLUR_THRESHOLD` → face excluded from detection callback; not stored in Lychee or embedding store |
+| S-030-31 | Admin opens Cluster Review page → clusters of visually similar unassigned faces displayed → admin names a cluster → new Person created and all faces in cluster assigned |
+| S-030-32 | Admin dismisses an entire cluster from Cluster Review page → all faces in cluster marked `is_dismissed = true` |
 
 ## Test Strategy
 
@@ -272,11 +314,12 @@ Read via `config('features.ai-vision.face-url')` and `config('features.ai-vision
 | ID | Description | Modules |
 |----|-------------|---------|
 | DO-030-01 | `Person` — id, name, user_id (nullable, unique), is_searchable (boolean, default true), timestamps | Models, API, UI |
-| DO-030-02 | `Face` — id, photo_id (FK→photos), person_id (nullable FK→persons), x, y, width, height (float 0.0–1.0), confidence (float 0.0–1.0), is_dismissed (boolean, default false), crop_token (random high-entropy token, nullable; file stored at `uploads/faces/{token[0:2]}/{token[2:4]}/{token}.jpg` and served directly by nginx — path is unguessable, no app-level auth required), timestamps | Models, API, UI |
+| DO-030-02 | `Face` — id, photo_id (FK→photos), person_id (nullable FK→persons), x, y, width, height (float 0.0–1.0), confidence (float 0.0–1.0), is_dismissed (boolean, default false), crop_token (random high-entropy token, nullable; file stored at `uploads/faces/{token[0:2]}/{token[2:4]}/{token}.jpg` and served directly by nginx — path is unguessable, no app-level auth required), cluster_label (nullable INT; DBSCAN cluster assignment written by `POST /FaceDetection/cluster-results`; -1 = DBSCAN noise/outlier stored as NULL; NULL = not yet clustered), timestamps | Models, API, UI |
 | DO-030-03 | `PersonResource` — Spatie Data resource for Person API responses | Resources |
 | DO-030-04 | `FaceResource` — Spatie Data resource for Face API responses (included in PhotoResource). Fields exposed: `id` (Face ID), `photo_id`, `person_id` (nullable), `x`, `y`, `width`, `height` (float 0.0–1.0), `confidence` (float 0.0–1.0), `is_dismissed` (boolean), `crop_url` (computed: `uploads/faces/{token[0:2]}/{token[2:4]}/{token}.jpg`; null if no crop). Embedded `suggestions[]` array — each item: `suggested_face_id`, `crop_url` (suggested face's crop or null), `person_name` (nullable, resolved via LEFT JOIN on persons), `confidence` (float 0.0–1.0). Suggestions always embedded (not lazy-loaded) since they are pre-computed and stored — no N+1 risk. *(Q-030-46)* | Resources |
 | DO-030-05 | `FaceSuggestion` — face_id (FK→faces), suggested_face_id (FK→faces), confidence (float 0.0–1.0); pre-computed similar-face suggestions stored from Python scan callback. Both FKs point to `faces`; the assignment modal JOINs at read time to resolve `suggested_face_id → person_id` (supports unassigned suggestions). Unique constraint on `(face_id, suggested_face_id)`. *(Q-030-33)* | Models, API, UI |
 | DO-030-06 | `photos` table addendum — adds nullable `face_scan_status VARCHAR(16)` column; PHP `ScanStatus` Enum cast. Values: `null` (never scanned), `pending`, `completed`, `failed`. Type chosen for MySQL/PostgreSQL/SQLite portability. *(Q-030-38)* | Models, Migrations |
+| DO-030-07 | `faces` table addendum — adds nullable `cluster_label INT` column (DBSCAN output label; NULL = not yet clustered or noise). Composite index `(cluster_label, person_id, is_dismissed)` on `faces` enables O(index-scan) `GROUP BY cluster_label` pagination for API-030-18. *(Q-030-49)* | Models, Migrations |
 
 ### API Routes / Services
 
@@ -297,9 +340,12 @@ Read via `config('features.ai-vision.face-url')` and `config('features.ai-vision
 | API-030-13 | POST /api/v2/Person/claim-by-selfie | Upload selfie photo, Python service matches against embeddings, link matching Person to current User | Multipart form with image file; **throttle: 5 requests/minute per user** *(Q-030-44)* |
 | API-030-14 | PATCH /api/v2/Face/{id} | Toggle `is_dismissed` flag (dismiss/undismiss a false-positive face) | Auth: photo owner or admin |
 | API-030-15 | DELETE /api/v2/Person/{id}/claim | Remove the User link from a Person (unclaim) | Auth: linked User or admin |
-| API-030-16 | DELETE /api/v2/Face/dismissed | Admin: hard-delete all dismissed faces (is_dismissed = true) and their crop files | Admin-only *(Q-030-43)* |
+| API-030-16 | DELETE /api/v2/Face/dismissed | Admin: hard-delete all dismissed faces (is_dismissed = true), their crop files, and their embeddings (FR-030-14: calls Python `DELETE /embeddings` asynchronously) | Admin-only *(Q-030-43)* |
 | API-030-17 | GET /api/v2/Maintenance::resetStuckFaces | Admin: check — returns count of photos stuck in `pending` longer than `older_than_minutes` (default 60). Follows existing check/do Maintenance pattern. | Admin-only *(Q-030-48)* |
 | API-030-17b | POST /api/v2/Maintenance::resetStuckFaces | Admin: do — reset all `face_scan_status = 'pending'` records older than threshold back to `null`. Body: optional `older_than_minutes` (integer, default 60). | Admin-only *(Q-030-48)* |
+| API-030-18 | GET /api/v2/FaceDetection/clusters | List face clusters using `SELECT cluster_label, COUNT(*) as size FROM faces WHERE cluster_label IS NOT NULL AND person_id IS NULL AND is_dismissed = false GROUP BY cluster_label ORDER BY cluster_label LIMIT/OFFSET`. Paginated; each cluster: `{cluster_id: int, size: int, faces: FaceResource[]}` (faces loaded via separate WHERE cluster_label = ? query, limited to first N for preview). Composite index `(cluster_label, person_id, is_dismissed)` ensures O(index-scan). Respects `ai_vision_face_permission_mode` visibility rules. | Auth per permission mode |
+| API-030-19 | POST /api/v2/FaceDetection/clusters/{cluster_id}/assign | Bulk-assign all qualifying faces (`cluster_label = cluster_id AND person_id IS NULL AND is_dismissed = false`) to a Person (existing `person_id` or new `new_person_name`). Creates Person if `new_person_name` provided. `cluster_id` is the integer `cluster_label` value. | Body: `person_id` or `new_person_name` |
+| API-030-20 | POST /api/v2/FaceDetection/clusters/{cluster_id}/dismiss | Bulk-dismiss all qualifying faces (`cluster_label = cluster_id AND person_id IS NULL AND is_dismissed = false`) by setting `is_dismissed = true`. `cluster_id` is the integer `cluster_label` value. | Auth: photo owner or admin |
 
 ### CLI Commands / Flags
 
@@ -654,6 +700,18 @@ Lychee resolves `lychee_face_id → Face → person_id` to identify the matching
 
 **Health Check:** `GET /health` → `{"status": "ok"}`
 
+**Embedding Deletion (Lychee → Python):** `DELETE /embeddings` *(FR-030-14)*
+```json
+{
+  "face_ids": ["face_abc123", "face_def456"]
+}
+```
+Response (200):
+```json
+{ "deleted_count": 2 }
+```
+Lychee dispatches this call as a fire-and-forget queued job after hard-deleting Face records (dismissed bulk-delete or Photo cascade). The Python service removes the listed embeddings from `EmbeddingStore`; IDs not found are silently ignored. Endpoint authenticated via `X-API-Key`.
+
 ### Python Service Technical Specification
 
 #### Technology Stack
@@ -961,7 +1019,9 @@ CMD ["sh", "-c", "uvicorn app.main:app --host 0.0.0.0 --port 8000 --workers ${VI
 | `VISION_FACE_API_KEY` | Yes | — | Shared API key used in both directions: validates inbound `X-API-Key` from Lychee scan requests; also sent as `X-API-Key` on callbacks to Lychee. Must match `AI_VISION_FACE_API_KEY` on the Lychee side. |
 | `VISION_FACE_MODEL_NAME` | No | `buffalo_l` | InsightFace model pack name |
 | `VISION_FACE_DETECTION_THRESHOLD` | No | `0.5` | Bounding box confidence filter — faces below threshold excluded from callback *(Q-030-31)* |
+| `VISION_FACE_BLUR_THRESHOLD` | No | `100.0` | Laplacian variance sharpness filter — faces whose crop Laplacian variance falls below this value are excluded as too blurry for reliable recognition (FR-030-02). Set to `0.0` to disable blur filtering. |
 | `VISION_FACE_MATCH_THRESHOLD` | No | `0.5` | Similarity score cutoff for suggestions and selfie match results *(Q-030-31)* |
+| `VISION_FACE_CLUSTER_EPS` | No | `0.6` | DBSCAN epsilon (maximum cosine distance between embeddings to be considered the same cluster) used by `POST /cluster` (FR-030-13). Lower values → tighter clusters. |
 | `VISION_FACE_RESCAN_IOU_THRESHOLD` | No | `0.5` | IoU threshold for bounding-box matching on re-scan (preserves `person_id`) *(Q-030-35)* |
 | `VISION_FACE_MAX_FACES_PER_PHOTO` | No | `10` | Maximum faces included in the callback payload (top-N by confidence; rest dropped) *(Q-030-39)* |
 | `VISION_FACE_THREAD_POOL_SIZE` | No | `1` | CPU-bound inference thread pool size (`asyncio.run_in_executor`) *(Q-030-26)* |
diff --git a/docs/specs/4-architecture/features/030-ai-vision-service/tasks.md b/docs/specs/4-architecture/features/030-ai-vision-service/tasks.md
index 64666fdc895..08aeeba05a5 100644
--- a/docs/specs/4-architecture/features/030-ai-vision-service/tasks.md
+++ b/docs/specs/4-architecture/features/030-ai-vision-service/tasks.md
@@ -326,12 +326,62 @@ _Last updated: 2026-03-21_
   _Verification commands:_
   - Review documentation for accuracy.
 
-- [x] T-030-43 – Run full quality gate and update roadmap.
-  _Intent:_ Run all quality gates across all three codebases. All green. Update roadmap status to Complete.
+### I20 – Clustering Endpoint: Python `POST /cluster` + PHP Ingestion & Trigger
+
+- [ ] T-030-44 – Implement Python `POST /cluster` endpoint and wire `FaceClusterer` (FR-030-13, S-030-27).
+  _Intent:_ Add `ClusterResponse` Pydantic schema (`{clusters: int, suggestions_generated: int}`) to `app/api/schemas.py`. Add `VISION_FACE_CLUSTER_EPS` (float, default `0.6`) to `AppSettings`. Extend `app/clustering/clusterer.py` with `run_cluster_and_notify(store, lychee_url, api_key)`: read all embeddings, run DBSCAN, generate `(face_id, suggested_face_id, confidence)` pairs within each cluster (cosine similarity as confidence), POST `{suggestions: [...]}` to `{lychee_url}/api/v2/FaceDetection/cluster-results` with `X-API-Key`. Add `POST /cluster` route to `app/api/routes.py` (X-API-Key auth dependency) that calls `run_cluster_and_notify()` and returns `ClusterResponse`. Add unit + integration tests in `tests/test_clustering.py` (mock httpx POST to Lychee).
+  _Verification commands:_
+  - `cd ai-vision-service && uv run pytest tests/test_clustering.py`
+  - `uv run ty check`
+  - `uv run ruff check`
+
+- [ ] T-030-45 – Write feature tests and implement PHP `POST /FaceDetection/cluster-results` ingestion endpoint (FR-030-13).
+  _Intent:_ New action `clusterResults` on `FaceDetectionController`: auth via X-API-Key header; validate body `{suggestions: [{face_id, suggested_face_id, confidence}]}`; bulk-upsert `face_suggestions` rows on `(face_id, suggested_face_id)` updating `confidence`; return `{updated_count: N}`. Feature tests: success (suggestions upserted, count returned), invalid API key (401), malformed body (422), unknown face_id (422). Register route in `api_v2.php`.
+  _Verification commands:_
+  - `php artisan test --filter=FaceClusterResultsTest`
+  - `make phpstan`
+
+- [ ] T-030-46 – Write feature tests and implement PHP `POST /Maintenance::runFaceClustering` admin trigger (FR-030-13).
+  _Intent:_ Admin-only Maintenance endpoint following the existing check/do pattern. `POST /api/v2/Maintenance::runFaceClustering`: calls Python service `POST /cluster` via HTTP with `X-API-Key`; returns 202 Accepted on success; returns 503 if Python service is unreachable (NFR-030-03). Feature tests: admin triggers clustering (202), non-admin gets 403, service unavailable (503). Register route in `api_v2.php`.
   _Verification commands:_
-  - Python: `cd ai-vision-service && uv run ruff format --check && uv run ruff check && uv run ty check && uv run pytest --cov=app`
-  - PHP: `vendor/bin/php-cs-fixer fix && php artisan test && make phpstan`
-  - Frontend: `npm run format && npm run check`
+  - `php artisan test --filter=MaintenanceFaceClusteringTest`
+  - `make phpstan`
+
+### I21 – Embedding Sync on Deletion + Blur Threshold Filtering
+
+- [ ] T-030-47 – Python: `VISION_FACE_BLUR_THRESHOLD` filter in detector (FR-030-02, S-030-30).
+  _Intent:_ Add `VISION_FACE_BLUR_THRESHOLD` (float, default `100.0`) to `AppSettings` in `app/config.py`. In `app/detection/detector.py`, after detecting each face and cropping the bounding-box region, compute its Laplacian variance (`cv2.Laplacian(crop_region, cv2.CV_64F).var()`); discard any face whose variance is below the threshold before adding it to the results list. A value of `0.0` disables the filter (all faces pass). Update `tests/test_detection.py`: verify a synthetic blurry patch (Gaussian blur, variance << threshold) is excluded; verify a sharp patch is retained.
+  _Verification commands:_
+  - `cd ai-vision-service && uv run pytest tests/test_detection.py`
+  - `uv run ty check`
+  - `uv run ruff check`
+
+- [ ] T-030-48 – Python: `DELETE /embeddings` endpoint (FR-030-14, S-030-28, S-030-29).
+  _Intent:_ Add `delete_many(face_ids: list[str]) -> int` to the `EmbeddingStore` protocol in `app/embeddings/store.py` and implement it in both `SQLiteStore` and `PgVectorStore` (ignores unknown IDs silently; returns count of rows actually deleted). Add `DELETE /embeddings` route in `app/api/routes.py` (X-API-Key auth): accepts `{face_ids: list[str]}`, calls `store.delete_many()`, returns `{deleted_count: int}`. Add tests in `tests/test_api.py`: success (returns count), invalid API key (401), empty list (400), IDs not in store (returns `{deleted_count: 0}`).
+  _Verification commands:_
+  - `cd ai-vision-service && uv run pytest tests/test_api.py tests/test_embeddings.py`
+  - `uv run ty check`
+  - `uv run ruff check`
+
+- [ ] T-030-49 – PHP: dispatch embedding deletion after Face hard-deletes (FR-030-14, S-030-28, S-030-29).
+  _Intent:_ Create `DeleteFaceEmbeddingsJob` (implements `ShouldQueue`): accepts `array<string> $faceIds`, calls Python `DELETE /embeddings` via HTTP with `X-API-Key`; catches all exceptions, logs a warning (`Log::warning`), and returns without re-throwing (never fails the queue worker or rolls back the Lychee deletion). Dispatch this job from two trigger points: (1) in `destroyDismissed` action — collect IDs of dismissed faces before deleting them, dispatch job after `Face::where('is_dismissed', true)->delete()`; (2) in a `Face` model observer `deleting` event, or by hooking into the Photo delete pipeline to collect `face_ids` before cascade — dispatch batch job for those IDs. Write feature tests: `DELETE /Face/dismissed` → job dispatched with correct IDs; Photo delete → job dispatched for cascaded faces; Python service unavailable → Lychee deletion succeeds, warning logged.
+  _Verification commands:_
+  - `php artisan test --filter=FaceEmbeddingSyncTest`
+  - `make phpstan`
+
+### I22 – Cluster Review UI: Browse & Bulk-Name/Dismiss Clusters
+
+- [ ] T-030-50 – Write feature tests and implement PHP cluster-review API endpoints (FR-030-15, API-030-18, API-030-19, API-030-20, S-030-31, S-030-32).
+  _Intent:_ `GET /api/v2/FaceDetection/clusters`: query `face_suggestions` graph, derive connected components of unassigned (`person_id IS NULL`) non-dismissed faces using breadth-first traversal; assign each component a deterministic `cluster_id` (SHA1 of sorted face IDs); return paginated `{cluster_id, size, faces: FaceResource[]}`. `POST /api/v2/FaceDetection/clusters/{cluster_id}/assign`: resolve faces in cluster, create Person if `new_person_name` supplied (or use existing `person_id`), bulk `UPDATE faces SET person_id = ? WHERE id IN (...)`, emit `face.cluster_assigned` telemetry, return `{person_id, assigned_count}`. `POST /api/v2/FaceDetection/clusters/{cluster_id}/dismiss`: bulk `UPDATE faces SET is_dismissed = true WHERE id IN (...)`, emit `face.cluster_dismissed`, return `{dismissed_count}`. Feature tests: list clusters (only unassigned non-dismissed faces; already-assigned excluded), assign cluster (new person created + faces linked; existing person used if person_id supplied), dismiss cluster (all faces marked is_dismissed). Test permission mode enforcement (public/restricted at minimum). Register routes in `api_v2.php`.
+  _Verification commands:_
+  - `php artisan test --filter=FaceClusterReviewTest`
+  - `make phpstan`
+
+- [ ] T-030-51 – Create FaceClusters.vue page and wire into navigation (FR-030-15, UI-030-08, S-030-31, S-030-32).
+  _Intent:_ New Vue3 view at `/people/clusters`. Fetches `GET /FaceDetection/clusters` (paginated). Renders a vertical list of cluster cards; each card shows: first 5 face-crop `<img>` thumbnails (from `crop_url`), "+N more" badge when `size > 5`, size badge, a name `InputText`, a "Create Person & Assign All" `Button` (calls `POST /FaceDetection/clusters/{id}/assign` with `new_person_name`; or if person selected from dropdown, uses `person_id`), and a "Dismiss" `Button` (calls `POST /FaceDetection/clusters/{id}/dismiss`). After either action, remove the cluster card from the list without full-page reload. "Run Cluster" `Button` in page header calls `POST /Maintenance::runFaceClustering` then re-fetches clusters. Empty state illustration when no clusters exist. Add `/people/clusters` route to Vue Router and a "Clusters" navigation link under People in the sidebar (visible only when `ai_vision_face_enabled` is true).
+  _Verification commands:_
+  - `npm run check`
+  - `npm run format`
 
 ## Notes / TODOs
 
diff --git a/docs/specs/4-architecture/open-questions.md b/docs/specs/4-architecture/open-questions.md
index c9299b9d8fb..0239a53d88a 100644
--- a/docs/specs/4-architecture/open-questions.md
+++ b/docs/specs/4-architecture/open-questions.md
@@ -10,6 +10,34 @@ Track unresolved high- and medium-impact questions here. Remove each row as soon
 
 ## Question Details
 
+### ~~Q-030-49: Cluster Storage Model — Resolved~~ ✅ RESOLVED — How Should the Backend Know About Existing Clusters?
+
+**Context:** FR-030-15 and API-030-18/19/20 specify a Cluster Review page. The current spec says `cluster_id` is "derived from the suggestion graph" (connected components of `face_suggestions`). This approach has three fatal flaws: (1) O(V+E) graph traversal per `GET /clusters` request violates NFR-030-02; (2) SHA1-of-sorted-face-IDs IDs are unstable — they change when any face in the cluster is dismissed or assigned, breaking `POST .../clusters/{id}/assign`; (3) pagination over connected components requires materialising all clusters first.
+
+**Option A (Recommended) — `cluster_label` nullable INT column on `faces`**
+- DBSCAN already produces integer labels (0, 1, 2... for clusters; -1 = noise). Persist them directly.
+- `POST /cluster-results` payload carries `{face_id, cluster_label}[]` alongside suggestion pairs; PHP bulk-updates `faces.cluster_label`.
+- `GET /clusters` = standard `GROUP BY cluster_label` SQL with `LIMIT/OFFSET`; composite index on `(cluster_label, person_id, is_dismissed)`.
+- `cluster_id` in the API = `cluster_label` integer (stable between clustering runs).
+- Assign/dismiss = `WHERE cluster_label = ?`.
+- Stale for faces added after last clustering run (they have `cluster_label = NULL` and don't appear until re-cluster). Acceptable — Cluster Review is explicitly post-clustering UX.
+- **One nullable column. No new model. Trivial pagination.**
+
+**Option B — Separate `face_clusters` table + FK on `faces`**
+- `face_clusters`: id (ULID), run_at, size (cached).
+- `faces.cluster_id` FK → `face_clusters.id`.
+- Pros: opaque ULID IDs, can record run timestamp. Cons: extra table + model, more complex ingestion, size cache goes stale on dismiss/assign. Not worth the complexity over A.
+
+**Option C — Keep as-is (on-the-fly BFS/DFS over `face_suggestions`)**
+- Always reflects current suggestion relationships (no staleness).
+- Fatal: O(V+E) per page load, unstable IDs, pagination infeasible. Violates NFR-030-02. **Not viable at scale.**
+
+**Required spec changes if Option A adopted:**
+- `DO-030-02`: add `cluster_label` (nullable INT) to Face
+- `DO-030-06` / migration: add `cluster_label INT NULL` column + composite index `(cluster_label, person_id, is_dismissed)` on `faces`
+- `FR-030-13` (`POST /cluster-results`): body gains `{face_id: str, cluster_label: int | null}[]` alongside suggestion pairs
+- `FR-030-15` / API-030-18/19/20: `cluster_id` = `cluster_label` integer; remove "opaque stable identifier derived from the suggestion graph" language; add note that noisy faces (`cluster_label = NULL`) excluded from Cluster Review
+
 ### ~~Q-030-33: `face_suggestions` Schema Wrong — Face-to-Face, Not Face-to-Person~~ ✅ RESOLVED
 
 **Resolution:** **Option A** — schema changed to `(face_id FK→faces, suggested_face_id FK→faces, confidence)`. Both FKs point to `faces`. Python sends `lychee_face_id` (a Face ID) as the suggestion target — there is no concept of Persons in the Python service, and suggestions may reference unassigned faces (where `person_id IS NULL`). The assignment modal resolves `suggested_face_id → faces → persons` via LEFT JOIN at read time. A unique constraint on `(face_id, suggested_face_id)` prevents duplicate suggestion rows.
@@ -18,6 +46,10 @@ Track unresolved high- and medium-impact questions here. Remove each row as soon
 
 **Resolved:** 2026-03-18
 
+**Resolution: Option A adopted.**  nullable INT column on . Spec updated: DO-030-02, DO-030-07, FR-030-13, FR-030-15, API-030-18/19/20.
+
+**Resolved:** 2026-03-23
+
 ---
 
 ### ~~Q-030-34: Crop Serving Route Undefined~~ ✅ RESOLVED

From cf2d3fbf1f1a20d3f965950d558fbf40551ef965 Mon Sep 17 00:00:00 2001
From: ildyria <beviguier@gmail.com>
Date: Tue, 24 Mar 2026 19:45:01 +0100
Subject: [PATCH 08/10] WIP

---
 ai-vision-service/app/api/routes.py           |   62 +
 ai-vision-service/app/api/schemas.py          |   47 +
 ai-vision-service/app/clustering/clusterer.py |   14 +-
 ai-vision-service/app/config.py               |   10 +
 ai-vision-service/app/detection/detector.py   |   18 +
 .../app/embeddings/pgvector_store.py          |   25 +
 .../app/embeddings/sqlite_store.py            |   42 +
 ai-vision-service/app/embeddings/store.py     |   21 +
 ai-vision-service/app/main.py                 |    1 +
 .../Admin/Maintenance/RunFaceClustering.php   |   55 +
 .../AiVision/FaceClusterController.php        |   89 +
 .../Controllers/AiVision/FaceController.php   |    6 +
 .../AiVision/FaceDetectionController.php      |   35 +
 .../Requests/Face/ClusterAssignRequest.php    |   49 +
 .../Requests/Face/ClusterDismissRequest.php   |   31 +
 .../Requests/Face/ClusterIndexRequest.php     |   31 +
 .../Requests/Face/ClusterResultsRequest.php   |   69 +
 .../Models/ClusterPreviewResource.php         |   32 +
 app/Http/Resources/Models/PersonResource.php  |   21 +-
 app/Jobs/DeleteFaceEmbeddingsJob.php          |   68 +
 app/Models/Face.php                           |   37 +-
 app/Models/Person.php                         |   31 +-
 app/Observers/PhotoObserver.php               |   34 +
 app/Providers/AppServiceProvider.php          |    3 +
 database/factories/FaceFactory.php            |   72 +
 database/factories/PersonFactory.php          |   49 +
 ..._add_representative_face_id_to_persons.php |   42 +
 ...3_21_000006_add_cluster_label_to_faces.php |   41 +
 .../features/030-ai-vision-service/plan.md    |    4 +-
 .../features/030-ai-vision-service/spec.md    |    8 +-
 .../features/030-ai-vision-service/tasks.md   |   72 +-
 docs/specs/4-architecture/open-questions.md   |   72 +-
 lang/en/maintenance.php                       |    4 +
 lang/en/people.php                            |    7 +
 .../gallery/photoModule/PhotoBox.vue          |   21 +-
 .../maintenance/MaintenanceRunClustering.vue  |   57 +
 resources/js/lychee.d.ts                      | 2230 +++++++++--------
 resources/js/router/routes.ts                 |    6 +
 resources/js/services/face-cluster-service.ts |   28 +
 resources/js/views/FaceClusters.vue           |  205 ++
 resources/js/views/Maintenance.vue            |    2 +
 resources/js/views/People.vue                 |   10 +-
 resources/js/views/PersonDetail.vue           |    2 +-
 routes/api_v2.php                             |    9 +
 routes/web_v2.php                             |    2 +-
 .../AiVision/FaceAssignmentTest.php           |  121 +
 .../AiVision/FaceClusterReviewTest.php        |  155 ++
 .../FaceDetectionServiceUnavailableTest.php   |   65 +
 .../Feature_v2/AiVision/FaceDetectionTest.php |  251 ++
 tests/Feature_v2/AiVision/FaceDismissTest.php |  116 +
 .../MaintenanceResetStuckFacesTest.php        |  143 ++
 .../AiVision/PeopleControllerTest.php         |  223 ++
 tests/Feature_v2/AiVision/PersonClaimTest.php |  187 ++
 .../Feature_v2/AiVision/PersonPhotosTest.php  |   82 +
 .../AiVision/ScanFacesCommandTest.php         |   89 +
 tests/Feature_v2/AiVision/SelfieClaimTest.php |  142 ++
 tests/LoadedSubscriber.php                    |    7 +
 tests/Unit/Models/FaceTest.php                |  129 +
 tests/Unit/Models/PersonTest.php              |  117 +
 59 files changed, 4462 insertions(+), 1139 deletions(-)
 create mode 100644 app/Http/Controllers/Admin/Maintenance/RunFaceClustering.php
 create mode 100644 app/Http/Controllers/AiVision/FaceClusterController.php
 create mode 100644 app/Http/Requests/Face/ClusterAssignRequest.php
 create mode 100644 app/Http/Requests/Face/ClusterDismissRequest.php
 create mode 100644 app/Http/Requests/Face/ClusterIndexRequest.php
 create mode 100644 app/Http/Requests/Face/ClusterResultsRequest.php
 create mode 100644 app/Http/Resources/Models/ClusterPreviewResource.php
 create mode 100644 app/Jobs/DeleteFaceEmbeddingsJob.php
 create mode 100644 app/Observers/PhotoObserver.php
 create mode 100644 database/factories/FaceFactory.php
 create mode 100644 database/factories/PersonFactory.php
 create mode 100644 database/migrations/2026_03_21_000005_add_representative_face_id_to_persons.php
 create mode 100644 database/migrations/2026_03_21_000006_add_cluster_label_to_faces.php
 create mode 100644 resources/js/components/maintenance/MaintenanceRunClustering.vue
 create mode 100644 resources/js/services/face-cluster-service.ts
 create mode 100644 resources/js/views/FaceClusters.vue
 create mode 100644 tests/Feature_v2/AiVision/FaceAssignmentTest.php
 create mode 100644 tests/Feature_v2/AiVision/FaceClusterReviewTest.php
 create mode 100644 tests/Feature_v2/AiVision/FaceDetectionServiceUnavailableTest.php
 create mode 100644 tests/Feature_v2/AiVision/FaceDetectionTest.php
 create mode 100644 tests/Feature_v2/AiVision/FaceDismissTest.php
 create mode 100644 tests/Feature_v2/AiVision/MaintenanceResetStuckFacesTest.php
 create mode 100644 tests/Feature_v2/AiVision/PeopleControllerTest.php
 create mode 100644 tests/Feature_v2/AiVision/PersonClaimTest.php
 create mode 100644 tests/Feature_v2/AiVision/PersonPhotosTest.php
 create mode 100644 tests/Feature_v2/AiVision/ScanFacesCommandTest.php
 create mode 100644 tests/Feature_v2/AiVision/SelfieClaimTest.php
 create mode 100644 tests/Unit/Models/FaceTest.php
 create mode 100644 tests/Unit/Models/PersonTest.php

diff --git a/ai-vision-service/app/api/routes.py b/ai-vision-service/app/api/routes.py
index eeb528bc88b..929d2543fc3 100644
--- a/ai-vision-service/app/api/routes.py
+++ b/ai-vision-service/app/api/routes.py
@@ -19,6 +19,10 @@
 
 from app.api.dependencies import get_detector, get_store, require_api_key
 from app.api.schemas import (
+    ClusterFaceResult,
+    ClusterResponse,
+    DeleteEmbeddingsRequest,
+    DeleteEmbeddingsResponse,
     DetectCallbackPayload,
     DetectCallbackResponse,
     DetectRequest,
@@ -29,6 +33,7 @@
     MatchResult,
     SuggestionResult,
 )
+from app.clustering.clusterer import FaceClusterer
 from app.config import AppSettings, get_settings
 from app.detection.cropper import generate_crop
 
@@ -124,6 +129,63 @@ async def match(
     return MatchResponse(matches=[MatchResult(lychee_face_id=face_id, confidence=conf) for face_id, conf in matches])
 
 
+# ---------------------------------------------------------------------------
+# DELETE /embeddings
+# ---------------------------------------------------------------------------
+
+
+@router.delete("/embeddings")
+async def delete_embeddings(
+    body: DeleteEmbeddingsRequest,
+    request: Request,
+    _: None = Depends(require_api_key),
+) -> DeleteEmbeddingsResponse:
+    """Delete face embeddings by their Lychee Face IDs.
+
+    Called by Lychee when dismissed faces are permanently removed or when
+    a photo is deleted.
+    """
+    store: EmbeddingStore = get_store(request)
+    deleted = store.delete_many(body.face_ids)
+    return DeleteEmbeddingsResponse(deleted=deleted)
+
+
+# ---------------------------------------------------------------------------
+# POST /cluster
+# ---------------------------------------------------------------------------
+
+
+@router.post("/cluster")
+async def cluster(
+    request: Request,
+    settings: AppSettings = Depends(get_settings),
+    _: None = Depends(require_api_key),
+) -> ClusterResponse:
+    """Run DBSCAN clustering over all stored face embeddings.
+
+    Reads every embedding from the store, clusters them, and returns the
+    per-face cluster assignments. The PHP layer uses these to set
+    ``faces.cluster_label`` for the cluster-review UI.
+    """
+    store: EmbeddingStore = get_store(request)
+    all_embeddings = store.get_all()
+
+    if not all_embeddings:
+        return ClusterResponse(total_faces=0, num_clusters=0, assignments=[])
+
+    clusterer = FaceClusterer(eps=settings.cluster_eps)
+    results = clusterer.cluster(all_embeddings)
+
+    assignments = [ClusterFaceResult(lychee_face_id=fid, cluster_label=label) for fid, label in results]
+    distinct_labels = {label for _, label in results if label != -1}
+
+    return ClusterResponse(
+        total_faces=len(results),
+        num_clusters=len(distinct_labels),
+        assignments=assignments,
+    )
+
+
 # ---------------------------------------------------------------------------
 # GET /health
 # ---------------------------------------------------------------------------
diff --git a/ai-vision-service/app/api/schemas.py b/ai-vision-service/app/api/schemas.py
index b00c9166167..67734b649eb 100644
--- a/ai-vision-service/app/api/schemas.py
+++ b/ai-vision-service/app/api/schemas.py
@@ -142,6 +142,53 @@ class MatchResponse(BaseModel):
     """Top-N matches above ``VISION_FACE_MATCH_THRESHOLD``, ordered by descending confidence."""
 
 
+# ---------------------------------------------------------------------------
+# DELETE /embeddings - Lychee -> Python
+# ---------------------------------------------------------------------------
+
+
+class DeleteEmbeddingsRequest(BaseModel):
+    """Body sent by Lychee to delete face embeddings from the store."""
+
+    face_ids: list[str] = Field(min_length=1)
+    """List of Lychee ``Face.id`` values whose embeddings should be removed."""
+
+
+class DeleteEmbeddingsResponse(BaseModel):
+    """Response body for ``DELETE /embeddings``."""
+
+    deleted: int
+    """Number of embeddings actually removed (IDs not found are silently skipped)."""
+
+
+# ---------------------------------------------------------------------------
+# POST /cluster - Lychee -> Python
+# ---------------------------------------------------------------------------
+
+
+class ClusterFaceResult(BaseModel):
+    """One face's cluster assignment."""
+
+    lychee_face_id: str
+    """Lychee ``Face.id``."""
+
+    cluster_label: int
+    """DBSCAN cluster label. ``-1`` = noise / unassigned."""
+
+
+class ClusterResponse(BaseModel):
+    """Response body for ``POST /cluster``."""
+
+    total_faces: int
+    """Total number of embeddings that were clustered."""
+
+    num_clusters: int
+    """Number of distinct clusters found (excluding noise)."""
+
+    assignments: list[ClusterFaceResult]
+    """Per-face cluster label assignments."""
+
+
 # ---------------------------------------------------------------------------
 # /health
 # ---------------------------------------------------------------------------
diff --git a/ai-vision-service/app/clustering/clusterer.py b/ai-vision-service/app/clustering/clusterer.py
index cfe815b7e10..2b3847808c5 100644
--- a/ai-vision-service/app/clustering/clusterer.py
+++ b/ai-vision-service/app/clustering/clusterer.py
@@ -7,7 +7,12 @@
 
 from __future__ import annotations
 
+import logging
+
 import numpy as np
+from sklearn.cluster import DBSCAN
+
+logger = logging.getLogger(__name__)
 
 
 class FaceClusterer:
@@ -50,8 +55,6 @@ def cluster(self, face_embeddings: list[tuple[str, list[float]]]) -> list[tuple[
         if not face_embeddings:
             return []
 
-        from sklearn.cluster import DBSCAN
-
         ids = [fid for fid, _ in face_embeddings]
         vectors = np.array([emb for _, emb in face_embeddings], dtype=np.float32)
 
@@ -63,7 +66,14 @@ def cluster(self, face_embeddings: list[tuple[str, list[float]]]) -> list[tuple[
         norms = np.where(norms == 0, 1.0, norms)
         vectors = vectors / norms
 
+        logger.info(
+            "Start clustering %d face embeddings with DBSCAN (eps=%.2f, min_samples=%d)",
+            len(face_embeddings),
+            self._eps,
+            self._min_samples,
+        )
         db = DBSCAN(eps=self._eps, min_samples=self._min_samples, metric="cosine")
         labels: list[int] = db.fit_predict(vectors).tolist()
+        logger.info("Done clustering %d face embeddings with DBSCAN", len(face_embeddings))
 
         return list(zip(ids, labels, strict=True))
diff --git a/ai-vision-service/app/config.py b/ai-vision-service/app/config.py
index e32d55d48ec..0241601cdc1 100644
--- a/ai-vision-service/app/config.py
+++ b/ai-vision-service/app/config.py
@@ -83,6 +83,16 @@ class AppSettings(BaseSettings):
     log_level: str = "info"
     """Uvicorn/application log level."""
 
+    # --- Clustering ---
+    cluster_eps: float = 0.6
+    """DBSCAN epsilon (max cosine distance) for face clustering.
+    Lower values produce tighter, more homogeneous clusters."""
+
+    # --- Quality filtering ---
+    blur_threshold: float = 100.0
+    """Laplacian variance threshold for blur detection.
+    Face crops with a variance below this value are discarded before embedding."""
+
     model_config = SettingsConfigDict(
         env_prefix="VISION_FACE_",
         # Support .env files in development but never require them in production.
diff --git a/ai-vision-service/app/detection/detector.py b/ai-vision-service/app/detection/detector.py
index b52ec889b9a..f390b3dbf14 100644
--- a/ai-vision-service/app/detection/detector.py
+++ b/ai-vision-service/app/detection/detector.py
@@ -45,10 +45,12 @@ def __init__(
         self,
         model_name: str = "buffalo_l",
         detection_threshold: float = 0.5,
+        blur_threshold: float = 100.0,
         model_root: str = "/root/.insightface",
     ) -> None:
         self._model_name = model_name
         self._detection_threshold = detection_threshold
+        self._blur_threshold = blur_threshold
         self._model_root = model_root
         self._app: Any = None  # insightface.app.FaceAnalysis - untyped library
         self._lock = threading.Lock()
@@ -137,6 +139,8 @@ def detect_bytes(self, image_bytes: bytes) -> list[DetectedFace]:
 
     def _detect_array(self, img: Any) -> list[DetectedFace]:
         """Run detection on a BGR numpy array (internal)."""
+        import cv2
+
         if self._app is None:
             raise RuntimeError("FaceDetector not loaded - call load() first.")
 
@@ -155,6 +159,20 @@ def _detect_array(self, img: Any) -> list[DetectedFace]:
             bbox: Any = face.bbox  # [x1, y1, x2, y2] absolute pixels
             x1, y1, x2, y2 = float(bbox[0]), float(bbox[1]), float(bbox[2]), float(bbox[3])
 
+            # Blur filter: compute Laplacian variance on the face crop region.
+            # A value of 0.0 disables the filter (all faces pass).
+            if self._blur_threshold > 0.0:
+                px1 = max(0, int(x1))
+                py1 = max(0, int(y1))
+                px2 = min(w, int(x2))
+                py2 = min(h, int(y2))
+                if px2 > px1 and py2 > py1:
+                    crop_region = img[py1:py2, px1:px2]
+                    gray = cv2.cvtColor(crop_region, cv2.COLOR_BGR2GRAY)
+                    variance: float = float(cv2.Laplacian(gray, cv2.CV_64F).var())
+                    if variance < self._blur_threshold:
+                        continue
+
             # Normalise to [0, 1] and clamp
             fx = max(0.0, min(1.0, x1 / w))
             fy = max(0.0, min(1.0, y1 / h))
diff --git a/ai-vision-service/app/embeddings/pgvector_store.py b/ai-vision-service/app/embeddings/pgvector_store.py
index e1dad9fa624..6f30410080f 100644
--- a/ai-vision-service/app/embeddings/pgvector_store.py
+++ b/ai-vision-service/app/embeddings/pgvector_store.py
@@ -101,6 +101,31 @@ def similarity_search(
                 rows: list[Any] = cur.fetchall()
         return [(row[0], float(row[1])) for row in rows]
 
+    def delete_many(self, lychee_face_ids: list[str]) -> int:
+        """Remove multiple embeddings by Lychee Face ID."""
+        if not lychee_face_ids:
+            return 0
+        with self._lock:
+            conn = self._get_conn()
+            with conn.cursor() as cur:
+                # Use ANY(%s) with a list parameter for batch delete
+                cur.execute(
+                    "DELETE FROM face_embeddings WHERE lychee_face_id = ANY(%s)",
+                    (lychee_face_ids,),
+                )
+                deleted: int = cur.rowcount
+            conn.commit()
+        return deleted
+
+    def get_all(self) -> list[tuple[str, list[float]]]:
+        """Return all stored embeddings as (face_id, embedding) pairs."""
+        with self._lock:
+            conn = self._get_conn()
+            with conn.cursor() as cur:
+                cur.execute("SELECT lychee_face_id, embedding FROM face_embeddings")
+                rows: list[Any] = cur.fetchall()
+        return [(row[0], [float(v) for v in row[1]]) for row in rows]
+
     def count(self) -> int:
         """Return the total number of stored embeddings."""
         with self._lock:
diff --git a/ai-vision-service/app/embeddings/sqlite_store.py b/ai-vision-service/app/embeddings/sqlite_store.py
index 5d79c1a7fae..503f1365523 100644
--- a/ai-vision-service/app/embeddings/sqlite_store.py
+++ b/ai-vision-service/app/embeddings/sqlite_store.py
@@ -115,6 +115,48 @@ def similarity_search(
         finally:
             conn.close()
 
+    def delete_many(self, lychee_face_ids: list[str]) -> int:
+        """Remove multiple embeddings by Lychee Face ID."""
+        if not lychee_face_ids:
+            return 0
+        deleted = 0
+        with self._lock:
+            conn = self._connect()
+            try:
+                for fid in lychee_face_ids:
+                    row = conn.execute(
+                        "SELECT vec_rowid FROM face_meta WHERE lychee_face_id = ?",
+                        [fid],
+                    ).fetchone()
+                    if row is not None:
+                        conn.execute("DELETE FROM vec_faces WHERE rowid = ?", [row[0]])
+                        conn.execute("DELETE FROM face_meta WHERE lychee_face_id = ?", [fid])
+                        deleted += 1
+                conn.commit()
+            finally:
+                conn.close()
+        return deleted
+
+    def get_all(self) -> list[tuple[str, list[float]]]:
+        """Return all stored embeddings as (face_id, embedding) pairs."""
+        conn = self._connect()
+        try:
+            rows = conn.execute(
+                """
+                SELECT m.lychee_face_id, v.face_embedding
+                FROM face_meta m
+                JOIN vec_faces v ON v.rowid = m.vec_rowid
+                """,
+            ).fetchall()
+            results: list[tuple[str, list[float]]] = []
+            for lychee_face_id, blob in rows:
+                count = len(blob) // 4  # float32 = 4 bytes
+                embedding = list(struct.unpack(f"{count}f", blob))
+                results.append((lychee_face_id, embedding))
+            return results
+        finally:
+            conn.close()
+
     def count(self) -> int:
         """Return the number of stored embeddings."""
         conn = self._connect()
diff --git a/ai-vision-service/app/embeddings/store.py b/ai-vision-service/app/embeddings/store.py
index a4ee52f8091..2bb425e2754 100644
--- a/ai-vision-service/app/embeddings/store.py
+++ b/ai-vision-service/app/embeddings/store.py
@@ -58,6 +58,27 @@ def similarity_search(
         """
         ...
 
+    def delete_many(self, lychee_face_ids: list[str]) -> int:
+        """Remove multiple embeddings by Lychee Face ID.
+
+        Args:
+            lychee_face_ids: List of Lychee ``Face.id`` strings to remove.
+
+        Returns:
+            Number of embeddings actually deleted (IDs not found are silently
+            skipped).
+        """
+        ...
+
+    def get_all(self) -> list[tuple[str, list[float]]]:
+        """Return all stored embeddings.
+
+        Returns:
+            List of ``(lychee_face_id, embedding)`` pairs.  Used by the
+            clustering endpoint to read the full dataset into memory.
+        """
+        ...
+
     def count(self) -> int:
         """Return the total number of stored embeddings."""
         ...
diff --git a/ai-vision-service/app/main.py b/ai-vision-service/app/main.py
index 80a84a94f7a..ebabe197799 100644
--- a/ai-vision-service/app/main.py
+++ b/ai-vision-service/app/main.py
@@ -48,6 +48,7 @@ async def _default_lifespan(app: FastAPI) -> AsyncGenerator[None]:
     detector = FaceDetector(
         model_name=settings.model_name,
         detection_threshold=settings.detection_threshold,
+        blur_threshold=settings.blur_threshold,
     )
     detector.load()
     logger.info("InsightFace model '%s' loaded successfully", settings.model_name)
diff --git a/app/Http/Controllers/Admin/Maintenance/RunFaceClustering.php b/app/Http/Controllers/Admin/Maintenance/RunFaceClustering.php
new file mode 100644
index 00000000000..9588c559219
--- /dev/null
+++ b/app/Http/Controllers/Admin/Maintenance/RunFaceClustering.php
@@ -0,0 +1,55 @@
+<?php
+
+/**
+ * SPDX-License-Identifier: MIT
+ * Copyright (c) 2017-2018 Tobias Reich
+ * Copyright (c) 2018-2026 LycheeOrg.
+ */
+
+namespace App\Http\Controllers\Admin\Maintenance;
+
+use App\Http\Requests\Maintenance\MaintenanceRequest;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Routing\Controller;
+use Illuminate\Support\Facades\Http;
+use Illuminate\Support\Facades\Log;
+
+/**
+ * Admin maintenance controller to trigger face clustering in the AI Vision service.
+ *
+ * POST /Maintenance::runFaceClustering  — dispatch clustering job to Python service
+ */
+class RunFaceClustering extends Controller
+{
+	/**
+	 * Trigger face clustering in the AI Vision Python service.
+	 *
+	 * @return JsonResponse
+	 */
+	public function do(MaintenanceRequest $request): JsonResponse
+	{
+		$service_url = config('features.ai-vision.face-url', '');
+		$api_key = config('features.ai-vision.face-api-key', '');
+
+		if ($service_url === '') {
+			return response()->json(['status' => 'error', 'message' => 'AI Vision service not configured.'], 503);
+		}
+
+		try {
+			$response = Http::withHeaders(['X-API-Key' => $api_key])
+				->post($service_url . '/cluster');
+
+			if ($response->successful()) {
+				return response()->json(['status' => 'dispatched'], 200);
+			}
+
+			Log::warning('RunFaceClustering: /cluster returned HTTP ' . $response->status() . '.');
+
+			return response()->json(['status' => 'error', 'message' => 'Clustering service returned HTTP ' . $response->status()], 503);
+		} catch (\Exception $e) {
+			Log::warning('RunFaceClustering: request failed: ' . $e->getMessage());
+
+			return response()->json(['status' => 'error', 'message' => $e->getMessage()], 503);
+		}
+	}
+}
diff --git a/app/Http/Controllers/AiVision/FaceClusterController.php b/app/Http/Controllers/AiVision/FaceClusterController.php
new file mode 100644
index 00000000000..5906962a243
--- /dev/null
+++ b/app/Http/Controllers/AiVision/FaceClusterController.php
@@ -0,0 +1,89 @@
+<?php
+
+/**
+ * SPDX-License-Identifier: MIT
+ * Copyright (c) 2017-2018 Tobias Reich
+ * Copyright (c) 2018-2026 LycheeOrg.
+ */
+
+namespace App\Http\Controllers\AiVision;
+
+use App\Http\Requests\Face\ClusterAssignRequest;
+use App\Http\Requests\Face\ClusterDismissRequest;
+use App\Http\Requests\Face\ClusterIndexRequest;
+use App\Http\Resources\Models\ClusterPreviewResource;
+use App\Models\Face;
+use App\Models\Person;
+use App\Repositories\ConfigManager;
+use Illuminate\Pagination\LengthAwarePaginator;
+use Illuminate\Routing\Controller;
+
+class FaceClusterController extends Controller
+{
+	private const PER_PAGE = 20;
+	private const SAMPLE_SIZE = 5;
+
+	public function index(ClusterIndexRequest $request): LengthAwarePaginator
+	{
+		$page = (int) $request->query('page', '1');
+		$totals = Face::query()
+			->whereNotNull('cluster_label')
+			->where('cluster_label', '>', -1)
+			->whereNull('person_id')
+			->where('is_dismissed', '=', false)
+			->selectRaw('cluster_label, COUNT(*) as face_count')
+			->groupBy('cluster_label')
+			->orderBy('face_count', 'desc')
+			->get();
+		$total = $totals->count();
+		$paginated = $totals->forPage($page, self::PER_PAGE);
+		$items = $paginated->map(function (Face $row): ClusterPreviewResource {
+			$cluster_label = (int) $row->cluster_label;
+			$face_count = (int) $row->face_count; // @phpstan-ignore property.notFound (see line 34)
+			$samples = Face::query()
+				->where('cluster_label', '=', $cluster_label)
+				->whereNull('person_id')
+				->where('is_dismissed', '=', false)
+				->whereNotNull('crop_token')
+				->orderByDesc('confidence')
+				->limit(self::SAMPLE_SIZE)
+				->pluck('crop_token')
+				->map(static fn ($tok) => 'uploads/faces/' . substr($tok, 0, 2) . '/' . substr($tok, 2, 2) . '/' . $tok . '.jpg')
+				->all();
+
+			return new ClusterPreviewResource($cluster_label, $face_count, $samples);
+		});
+
+		return new LengthAwarePaginator($items, $total, self::PER_PAGE, $page, ['path' => $request->url()]);
+	}
+
+	public function assign(ClusterAssignRequest $request, int $label): array
+	{
+		if ($request->personId() !== null) {
+			$person_id = $request->personId();
+		} else {
+			$is_searchable_default = app(ConfigManager::class)->getValueAsBool('ai_vision_face_person_is_searchable_default');
+			$person = new Person();
+			$person->name = (string) $request->newPersonName();
+			$person->is_searchable = $is_searchable_default;
+			$person->save();
+			$person_id = $person->id;
+		}
+		$count = Face::where('cluster_label', '=', $label)
+			->whereNull('person_id')
+			->where('is_dismissed', '=', false)
+			->update(['person_id' => $person_id]);
+
+		return ['assigned_count' => $count];
+	}
+
+	public function dismiss(ClusterDismissRequest $request, int $label): array
+	{
+		$count = Face::where('cluster_label', '=', $label)
+			->whereNull('person_id')
+			->where('is_dismissed', '=', false)
+			->update(['is_dismissed' => true]);
+
+		return ['dismissed_count' => $count];
+	}
+}
diff --git a/app/Http/Controllers/AiVision/FaceController.php b/app/Http/Controllers/AiVision/FaceController.php
index 2535fceb809..ff828284d16 100644
--- a/app/Http/Controllers/AiVision/FaceController.php
+++ b/app/Http/Controllers/AiVision/FaceController.php
@@ -12,6 +12,7 @@
 use App\Http\Requests\Face\DestroyDismissedFacesRequest;
 use App\Http\Requests\Face\ToggleDismissedRequest;
 use App\Http\Resources\Models\FaceResource;
+use App\Jobs\DeleteFaceEmbeddingsJob;
 use App\Models\Face;
 use App\Models\Person;
 use App\Repositories\ConfigManager;
@@ -78,6 +79,7 @@ public function toggleDismissed(ToggleDismissedRequest $request, string $id): Fa
 	public function destroyDismissed(DestroyDismissedFacesRequest $_request): array
 	{
 		$dismissed_faces = Face::where('is_dismissed', '=', true)->get();
+		$face_ids = $dismissed_faces->pluck('id')->all();
 		$count = 0;
 
 		foreach ($dismissed_faces as $face) {
@@ -91,6 +93,10 @@ public function destroyDismissed(DestroyDismissedFacesRequest $_request): array
 			$count++;
 		}
 
+		if ($face_ids !== []) {
+			DeleteFaceEmbeddingsJob::dispatch($face_ids);
+		}
+
 		return ['deleted_count' => $count];
 	}
 }
diff --git a/app/Http/Controllers/AiVision/FaceDetectionController.php b/app/Http/Controllers/AiVision/FaceDetectionController.php
index 519e8606d24..00662541309 100644
--- a/app/Http/Controllers/AiVision/FaceDetectionController.php
+++ b/app/Http/Controllers/AiVision/FaceDetectionController.php
@@ -10,6 +10,7 @@
 
 use App\Enum\FaceScanStatus;
 use App\Http\Requests\Face\BulkScanRequest;
+use App\Http\Requests\Face\ClusterResultsRequest;
 use App\Http\Requests\Face\FaceDetectionResultsRequest;
 use App\Http\Requests\Face\ScanPhotosRequest;
 use App\Jobs\DispatchFaceScanJob;
@@ -146,6 +147,40 @@ public function bulkScan(BulkScanRequest $request): \Illuminate\Http\Response
 		return response()->noContent(202);
 	}
 
+	/**
+	 * Receive face clustering results callback from the Python service.
+	 * Authentication is exclusively via X-API-Key header; no user session required.
+	 *
+	 * POST /FaceDetection/cluster-results
+	 *
+	 * @return \Illuminate\Http\Response
+	 */
+	public function clusterResults(ClusterResultsRequest $request): \Illuminate\Http\Response
+	{
+		DB::transaction(function () use ($request): void {
+			// Reset all existing cluster labels so stale assignments are removed.
+			Face::whereNotNull('cluster_label')->update(['cluster_label' => null]);
+
+			// Apply new cluster labels in bulk.
+			foreach ($request->labels() as $item) {
+				Face::where('id', '=', $item['face_id'])
+					->update(['cluster_label' => $item['cluster_label']]);
+			}
+
+			// Upsert cross-cluster suggestions.
+			foreach ($request->suggestions() as $sug) {
+				FaceSuggestion::updateOrCreate(
+					['face_id' => $sug['face_id'], 'suggested_face_id' => $sug['suggested_face_id']],
+					['confidence' => $sug['confidence']],
+				);
+			}
+		});
+
+		Log::info('FaceDetectionController::clusterResults — updated ' . count($request->labels()) . ' cluster labels.');
+
+		return response()->noContent(202);
+	}
+
 	/**
 	 * Process incoming face detection results for a photo.
 	 * IoU-matches new faces against old faces to preserve person assignments.
diff --git a/app/Http/Requests/Face/ClusterAssignRequest.php b/app/Http/Requests/Face/ClusterAssignRequest.php
new file mode 100644
index 00000000000..c82612fbd78
--- /dev/null
+++ b/app/Http/Requests/Face/ClusterAssignRequest.php
@@ -0,0 +1,49 @@
+<?php
+
+/**
+ * SPDX-License-Identifier: MIT
+ * Copyright (c) 2017-2018 Tobias Reich
+ * Copyright (c) 2018-2026 LycheeOrg.
+ */
+
+namespace App\Http\Requests\Face;
+
+use App\Http\Requests\BaseApiRequest;
+use App\Models\Face;
+use App\Policies\AiVisionPolicy;
+use Illuminate\Support\Facades\Gate;
+
+class ClusterAssignRequest extends BaseApiRequest
+{
+	private ?string $person_id = null;
+	private ?string $new_person_name = null;
+
+	public function authorize(): bool
+	{
+		return Gate::check(AiVisionPolicy::CAN_ASSIGN_FACE, Face::class);
+	}
+
+	public function rules(): array
+	{
+		return [
+			'person_id' => ['nullable', 'string', 'exists:persons,id'],
+			'new_person_name' => ['nullable', 'string', 'max:255'],
+		];
+	}
+
+	protected function processValidatedValues(array $values, array $files): void
+	{
+		$this->person_id = $values['person_id'] ?? null;
+		$this->new_person_name = $values['new_person_name'] ?? null;
+	}
+
+	public function personId(): ?string
+	{
+		return $this->person_id;
+	}
+
+	public function newPersonName(): ?string
+	{
+		return $this->new_person_name;
+	}
+}
diff --git a/app/Http/Requests/Face/ClusterDismissRequest.php b/app/Http/Requests/Face/ClusterDismissRequest.php
new file mode 100644
index 00000000000..289892541d1
--- /dev/null
+++ b/app/Http/Requests/Face/ClusterDismissRequest.php
@@ -0,0 +1,31 @@
+<?php
+
+/**
+ * SPDX-License-Identifier: MIT
+ * Copyright (c) 2017-2018 Tobias Reich
+ * Copyright (c) 2018-2026 LycheeOrg.
+ */
+
+namespace App\Http\Requests\Face;
+
+use App\Http\Requests\BaseApiRequest;
+use App\Models\Face;
+use App\Policies\AiVisionPolicy;
+use Illuminate\Support\Facades\Gate;
+
+class ClusterDismissRequest extends BaseApiRequest
+{
+	public function authorize(): bool
+	{
+		return Gate::check(AiVisionPolicy::CAN_DISMISS_FACE, Face::class);
+	}
+
+	public function rules(): array
+	{
+		return [];
+	}
+
+	protected function processValidatedValues(array $values, array $files): void
+	{
+	}
+}
diff --git a/app/Http/Requests/Face/ClusterIndexRequest.php b/app/Http/Requests/Face/ClusterIndexRequest.php
new file mode 100644
index 00000000000..7fa2dd6d48f
--- /dev/null
+++ b/app/Http/Requests/Face/ClusterIndexRequest.php
@@ -0,0 +1,31 @@
+<?php
+
+/**
+ * SPDX-License-Identifier: MIT
+ * Copyright (c) 2017-2018 Tobias Reich
+ * Copyright (c) 2018-2026 LycheeOrg.
+ */
+
+namespace App\Http\Requests\Face;
+
+use App\Http\Requests\BaseApiRequest;
+use App\Models\Face;
+use App\Policies\AiVisionPolicy;
+use Illuminate\Support\Facades\Gate;
+
+class ClusterIndexRequest extends BaseApiRequest
+{
+	public function authorize(): bool
+	{
+		return Gate::check(AiVisionPolicy::CAN_ASSIGN_FACE, Face::class);
+	}
+
+	public function rules(): array
+	{
+		return [];
+	}
+
+	protected function processValidatedValues(array $values, array $files): void
+	{
+	}
+}
diff --git a/app/Http/Requests/Face/ClusterResultsRequest.php b/app/Http/Requests/Face/ClusterResultsRequest.php
new file mode 100644
index 00000000000..3e3c067accc
--- /dev/null
+++ b/app/Http/Requests/Face/ClusterResultsRequest.php
@@ -0,0 +1,69 @@
+<?php
+
+/**
+ * SPDX-License-Identifier: MIT
+ * Copyright (c) 2017-2018 Tobias Reich
+ * Copyright (c) 2018-2026 LycheeOrg.
+ */
+
+namespace App\Http\Requests\Face;
+
+use App\Http\Requests\BaseApiRequest;
+
+/**
+ * Request for receiving face clustering results from the Python AI Vision service.
+ * Authentication is exclusively via X-API-Key header; no user session required.
+ *
+ * POST /api/v2/FaceDetection/cluster-results
+ */
+class ClusterResultsRequest extends BaseApiRequest
+{
+	/** @var array<array{face_id:string,cluster_label:int}> */
+	private array $labels = [];
+
+	/** @var array<array{face_id:string,suggested_face_id:string,confidence:float}> */
+	private array $suggestions = [];
+
+	public function authorize(): bool
+	{
+		$expected_key = config('features.ai-vision.face-api-key', '');
+		$provided_key = $this->header('X-API-Key', '');
+
+		return $expected_key !== '' && $provided_key === $expected_key;
+	}
+
+	public function rules(): array
+	{
+		return [
+			'labels' => 'required|array',
+			'labels.*.face_id' => 'required|string',
+			'labels.*.cluster_label' => 'required|integer',
+			'suggestions' => 'sometimes|array',
+			'suggestions.*.face_id' => 'required|string|exists:faces,id',
+			'suggestions.*.suggested_face_id' => 'required|string|exists:faces,id',
+			'suggestions.*.confidence' => 'required|numeric',
+		];
+	}
+
+	protected function processValidatedValues(array $values, array $files): void
+	{
+		$this->labels = $values['labels'] ?? [];
+		$this->suggestions = $values['suggestions'] ?? [];
+	}
+
+	/**
+	 * @return array<array{face_id:string,cluster_label:int}>
+	 */
+	public function labels(): array
+	{
+		return $this->labels;
+	}
+
+	/**
+	 * @return array<array{face_id:string,suggested_face_id:string,confidence:float}>
+	 */
+	public function suggestions(): array
+	{
+		return $this->suggestions;
+	}
+}
diff --git a/app/Http/Resources/Models/ClusterPreviewResource.php b/app/Http/Resources/Models/ClusterPreviewResource.php
new file mode 100644
index 00000000000..7ac1cb6046c
--- /dev/null
+++ b/app/Http/Resources/Models/ClusterPreviewResource.php
@@ -0,0 +1,32 @@
+<?php
+
+/**
+ * SPDX-License-Identifier: MIT
+ * Copyright (c) 2017-2018 Tobias Reich
+ * Copyright (c) 2018-2026 LycheeOrg.
+ */
+
+namespace App\Http\Resources\Models;
+
+use Spatie\LaravelData\Data;
+use Spatie\TypeScriptTransformer\Attributes\TypeScript;
+
+/**
+ * A lightweight summary of one face cluster for the cluster-review UI.
+ */
+#[TypeScript()]
+class ClusterPreviewResource extends Data
+{
+	public int $cluster_label;
+	public int $face_count;
+
+	/** @var list<string> Up to 5 sample crop URLs for preview thumbnails. */
+	public array $sample_crop_urls;
+
+	public function __construct(int $cluster_label, int $face_count, array $sample_crop_urls)
+	{
+		$this->cluster_label = $cluster_label;
+		$this->face_count = $face_count;
+		$this->sample_crop_urls = $sample_crop_urls;
+	}
+}
diff --git a/app/Http/Resources/Models/PersonResource.php b/app/Http/Resources/Models/PersonResource.php
index c194ac1e0ce..88ac6f628ec 100644
--- a/app/Http/Resources/Models/PersonResource.php
+++ b/app/Http/Resources/Models/PersonResource.php
@@ -19,6 +19,7 @@ class PersonResource extends Data
 	public string $name;
 	public ?int $user_id;
 	public bool $is_searchable;
+	public ?string $representative_face_id;
 	public int $face_count;
 	public int $photo_count;
 	public ?string $representative_crop_url;
@@ -29,10 +30,28 @@ public function __construct(Person $person)
 		$this->name = $person->name;
 		$this->user_id = $person->user_id;
 		$this->is_searchable = $person->is_searchable;
+		$this->representative_face_id = $person->representative_face_id;
 		$this->face_count = $person->faces()->count();
 		$this->photo_count = $person->faces()->distinct('photo_id')->count('photo_id');
 
-		$crop_token = $person->faces()->whereNotNull('crop_token')->value('crop_token');
+		// Representative crop: prefer the explicitly pinned face's crop,
+		// fall back to the highest-confidence non-dismissed face with a crop.
+		$crop_token = null;
+		if ($person->representative_face_id !== null) {
+			$crop_token = $person->faces()
+				->where('id', '=', $person->representative_face_id)
+				->whereNotNull('crop_token')
+				->value('crop_token');
+		}
+
+		if ($crop_token === null) {
+			$crop_token = $person->faces()
+				->where('is_dismissed', '=', false)
+				->whereNotNull('crop_token')
+				->orderByDesc('confidence')
+				->value('crop_token');
+		}
+
 		if ($crop_token !== null) {
 			$this->representative_crop_url = 'uploads/faces/' . substr($crop_token, 0, 2) . '/' . substr($crop_token, 2, 2) . '/' . $crop_token . '.jpg';
 		} else {
diff --git a/app/Jobs/DeleteFaceEmbeddingsJob.php b/app/Jobs/DeleteFaceEmbeddingsJob.php
new file mode 100644
index 00000000000..de89cca9be4
--- /dev/null
+++ b/app/Jobs/DeleteFaceEmbeddingsJob.php
@@ -0,0 +1,68 @@
+<?php
+
+/**
+ * SPDX-License-Identifier: MIT
+ * Copyright (c) 2017-2018 Tobias Reich
+ * Copyright (c) 2018-2026 LycheeOrg.
+ */
+
+namespace App\Jobs;
+
+use Illuminate\Bus\Queueable;
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Illuminate\Foundation\Bus\Dispatchable;
+use Illuminate\Queue\InteractsWithQueue;
+use Illuminate\Queue\SerializesModels;
+use Illuminate\Support\Facades\Http;
+use Illuminate\Support\Facades\Log;
+
+/**
+ * Notifies the AI Vision Python service to delete stored embeddings for the
+ * given face IDs.
+ */
+class DeleteFaceEmbeddingsJob implements ShouldQueue
+{
+	use Dispatchable;
+	use InteractsWithQueue;
+	use Queueable;
+	use SerializesModels;
+
+	/** @var list<string> */
+	public array $face_ids;
+
+	/**
+	 * @param list<string> $face_ids
+	 */
+	public function __construct(array $face_ids)
+	{
+		$this->face_ids = $face_ids;
+	}
+
+	public function handle(): void
+	{
+		if ($this->face_ids === []) {
+			return;
+		}
+
+		$service_url = config('features.ai-vision.face-url', '');
+		$api_key = config('features.ai-vision.face-api-key', '');
+
+		if ($service_url === '') {
+			Log::warning('DeleteFaceEmbeddingsJob: AI Vision service not configured.');
+
+			return;
+		}
+
+		try {
+			$response = Http::withHeaders(['X-API-Key' => $api_key])
+				->delete($service_url . '/embeddings', ['face_ids' => $this->face_ids]);
+
+			$ok = $response->successful();
+			if (!$ok) {
+				Log::warning('DeleteFaceEmbeddingsJob: /embeddings DELETE returned HTTP ' . $response->status() . '.', ['face_ids' => $this->face_ids]);
+			}
+		} catch (\Exception $e) {
+			Log::warning('DeleteFaceEmbeddingsJob: request failed: ' . $e->getMessage(), ['face_ids' => $this->face_ids]);
+		}
+	}
+}
diff --git a/app/Models/Face.php b/app/Models/Face.php
index 92b56df178b..663c23f3e3c 100644
--- a/app/Models/Face.php
+++ b/app/Models/Face.php
@@ -31,6 +31,7 @@
  * @property float                          $confidence
  * @property string|null                    $crop_token
  * @property bool                           $is_dismissed
+ * @property int|null                       $cluster_label
  * @property Carbon                         $created_at
  * @property Carbon                         $updated_at
  * @property Photo                          $photo
@@ -71,32 +72,36 @@ class Face extends Model
 		'confidence',
 		'crop_token',
 		'is_dismissed',
+		'cluster_label',
 	];
 
 	/**
-	 * @var array<string, string|class-string>
+	 * @var list<string>
 	 */
-	protected $casts = [
-		'created_at' => 'datetime',
-		'updated_at' => 'datetime',
-		'x' => 'float',
-		'y' => 'float',
-		'width' => 'float',
-		'height' => 'float',
-		'confidence' => 'float',
-		'is_dismissed' => 'boolean',
+	protected $appends = [
+		'crop_url',
 	];
 
 	/**
-	 * @var list<string>
+	 * @return array<string,string>
 	 */
-	protected $appends = ['crop_url'];
+	protected function casts(): array
+	{
+		return [
+			'x' => 'float',
+			'y' => 'float',
+			'width' => 'float',
+			'height' => 'float',
+			'confidence' => 'float',
+			'is_dismissed' => 'boolean',
+			'cluster_label' => 'integer',
+			'created_at' => 'datetime',
+			'updated_at' => 'datetime',
+		];
+	}
 
 	/**
-	 * Get the crop URL derived from the crop_token.
-	 * Path format: uploads/faces/{tok[0:2]}/{tok[2:4]}/{tok}.jpg.
-	 *
-	 * @return string|null
+	 * Compute the crop URL from the crop_token.
 	 */
 	public function getCropUrlAttribute(): ?string
 	{
diff --git a/app/Models/Person.php b/app/Models/Person.php
index 4a250515a7e..b03657fa42c 100644
--- a/app/Models/Person.php
+++ b/app/Models/Person.php
@@ -25,10 +25,12 @@
  * @property string               $name
  * @property int|null             $user_id
  * @property bool                 $is_searchable
+ * @property string|null          $representative_face_id
  * @property Carbon               $created_at
  * @property Carbon               $updated_at
  * @property User|null            $user
  * @property Collection<int,Face> $faces
+ * @property Face|null            $representativeFace
  */
 class Person extends Model
 {
@@ -59,17 +61,22 @@ class Person extends Model
 		'name',
 		'user_id',
 		'is_searchable',
+		'representative_face_id',
 	];
 
 	/**
-	 * @var array<string, string|class-string>
+	 * @return array<string,string>
 	 */
-	protected $casts = [
-		'created_at' => 'datetime',
-		'updated_at' => 'datetime',
-		'is_searchable' => 'boolean',
-		'user_id' => 'integer',
-	];
+	protected function casts(): array
+	{
+		return [
+			'created_at' => 'datetime',
+			'updated_at' => 'datetime',
+			'is_searchable' => 'boolean',
+			'user_id' => 'integer',
+			'representative_face_id' => 'string',
+		];
+	}
 
 	/**
 	 * Return the user linked to this person.
@@ -92,8 +99,16 @@ public function faces(): HasMany
 	}
 
 	/**
-	 * Scope to only return searchable persons.
+	 * Return the representative face for this person (nullable).
 	 *
+	 * @return BelongsTo<Face,$this>
+	 */
+	public function representativeFace(): BelongsTo
+	{
+		return $this->belongsTo(Face::class, 'representative_face_id', 'id');
+	}
+
+	/**
 	 * @param \Illuminate\Database\Eloquent\Builder<static> $query
 	 *
 	 * @return \Illuminate\Database\Eloquent\Builder<static>
diff --git a/app/Observers/PhotoObserver.php b/app/Observers/PhotoObserver.php
new file mode 100644
index 00000000000..1fa7ab31beb
--- /dev/null
+++ b/app/Observers/PhotoObserver.php
@@ -0,0 +1,34 @@
+<?php
+
+/**
+ * SPDX-License-Identifier: MIT
+ * Copyright (c) 2017-2018 Tobias Reich
+ * Copyright (c) 2018-2026 LycheeOrg.
+ */
+
+namespace App\Observers;
+
+use App\Jobs\DeleteFaceEmbeddingsJob;
+use App\Models\Photo;
+
+/**
+ * Eloquent observer for the Photo model.
+ *
+ * Dispatches a job to purge face embeddings from the AI Vision service
+ * whenever a photo is hard-deleted, so that stale vectors do not affect
+ * future clustering or selfie-match results.
+ */
+class PhotoObserver
+{
+	/**
+	 * Handle the Photo "deleting" event.
+	 * Called before the record (and cascade-deleted faces) are removed.
+	 */
+	public function deleting(Photo $photo): void
+	{
+		$face_ids = $photo->faces()->pluck('id')->all();
+		if ($face_ids !== []) {
+			DeleteFaceEmbeddingsJob::dispatch($face_ids);
+		}
+	}
+}
diff --git a/app/Providers/AppServiceProvider.php b/app/Providers/AppServiceProvider.php
index 2bed6d15ed2..7abf866a099 100644
--- a/app/Providers/AppServiceProvider.php
+++ b/app/Providers/AppServiceProvider.php
@@ -27,6 +27,8 @@
 use App\Metadata\Versions\Remote\GitCommits;
 use App\Metadata\Versions\Remote\GitTags;
 use App\Models\Configs;
+use App\Models\Photo;
+use App\Observers\PhotoObserver;
 use App\Policies\AlbumQueryPolicy;
 use App\Policies\PhotoQueryPolicy;
 use App\Policies\SettingsPolicy;
@@ -111,6 +113,7 @@ public function boot()
 		$this->registerHttpAndResponseConfiguration();
 		$this->registerStreamFilters();
 		$this->registerOctaneSettings();
+		Photo::observe(PhotoObserver::class);
 	}
 
 	/**
diff --git a/database/factories/FaceFactory.php b/database/factories/FaceFactory.php
new file mode 100644
index 00000000000..447816d9e9f
--- /dev/null
+++ b/database/factories/FaceFactory.php
@@ -0,0 +1,72 @@
+<?php
+
+/**
+ * SPDX-License-Identifier: MIT
+ * Copyright (c) 2017-2018 Tobias Reich
+ * Copyright (c) 2018-2026 LycheeOrg.
+ */
+
+namespace Database\Factories;
+
+use App\Models\Face;
+use App\Models\Person;
+use App\Models\Photo;
+use Illuminate\Database\Eloquent\Factories\Factory;
+use Illuminate\Support\Str;
+
+/**
+ * @extends \Illuminate\Database\Eloquent\Factories\Factory<\App\Models\Face>
+ */
+class FaceFactory extends Factory
+{
+	protected $model = Face::class;
+
+	/**
+	 * @return array<string,mixed>
+	 */
+	public function definition(): array
+	{
+		return [
+			'photo_id' => Photo::factory(),
+			'person_id' => null,
+			'x' => fake()->randomFloat(4, 0.0, 0.8),
+			'y' => fake()->randomFloat(4, 0.0, 0.8),
+			'width' => fake()->randomFloat(4, 0.05, 0.2),
+			'height' => fake()->randomFloat(4, 0.05, 0.2),
+			'confidence' => fake()->randomFloat(4, 0.5, 1.0),
+			'crop_token' => Str::random(24),
+			'is_dismissed' => false,
+			'cluster_label' => null,
+		];
+	}
+
+	public function for_photo(Photo $photo): self
+	{
+		return $this->state(fn () => ['photo_id' => $photo->id]);
+	}
+
+	public function for_person(Person $person): self
+	{
+		return $this->state(fn () => ['person_id' => $person->id]);
+	}
+
+	public function dismissed(): self
+	{
+		return $this->state(fn () => ['is_dismissed' => true]);
+	}
+
+	public function without_crop(): self
+	{
+		return $this->state(fn () => ['crop_token' => null]);
+	}
+
+	public function with_cluster(int $label): self
+	{
+		return $this->state(fn () => ['cluster_label' => $label]);
+	}
+
+	public function with_confidence(float $confidence): self
+	{
+		return $this->state(fn () => ['confidence' => $confidence]);
+	}
+}
diff --git a/database/factories/PersonFactory.php b/database/factories/PersonFactory.php
new file mode 100644
index 00000000000..f77c136968c
--- /dev/null
+++ b/database/factories/PersonFactory.php
@@ -0,0 +1,49 @@
+<?php
+
+/**
+ * SPDX-License-Identifier: MIT
+ * Copyright (c) 2017-2018 Tobias Reich
+ * Copyright (c) 2018-2026 LycheeOrg.
+ */
+
+namespace Database\Factories;
+
+use App\Models\Person;
+use App\Models\User;
+use Illuminate\Database\Eloquent\Factories\Factory;
+
+/**
+ * @extends \Illuminate\Database\Eloquent\Factories\Factory<\App\Models\Person>
+ */
+class PersonFactory extends Factory
+{
+	protected $model = Person::class;
+
+	/**
+	 * @return array<string,mixed>
+	 */
+	public function definition(): array
+	{
+		return [
+			'name' => fake()->name(),
+			'user_id' => null,
+			'is_searchable' => true,
+			'representative_face_id' => null,
+		];
+	}
+
+	public function not_searchable(): self
+	{
+		return $this->state(fn () => ['is_searchable' => false]);
+	}
+
+	public function linked_to(User $user): self
+	{
+		return $this->state(fn () => ['user_id' => $user->id]);
+	}
+
+	public function with_name(string $name): self
+	{
+		return $this->state(fn () => ['name' => $name]);
+	}
+}
diff --git a/database/migrations/2026_03_21_000005_add_representative_face_id_to_persons.php b/database/migrations/2026_03_21_000005_add_representative_face_id_to_persons.php
new file mode 100644
index 00000000000..cdc30c3d820
--- /dev/null
+++ b/database/migrations/2026_03_21_000005_add_representative_face_id_to_persons.php
@@ -0,0 +1,42 @@
+<?php
+
+/**
+ * SPDX-License-Identifier: MIT
+ * Copyright (c) 2017-2018 Tobias Reich
+ * Copyright (c) 2018-2026 LycheeOrg.
+ */
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+/**
+ * Add representative_face_id (nullable FK → faces) to the persons table.
+ *
+ * This column is added in a separate migration (after the faces table has been
+ * created) to avoid a circular foreign-key dependency between persons and faces.
+ *
+ * When set, the referenced face is used as the representative thumbnail for the
+ * person in the UI.  When NULL the UI falls back to the highest-confidence
+ * non-dismissed face that has a crop_token.
+ */
+return new class() extends Migration {
+	public function up(): void
+	{
+		Schema::table('persons', function (Blueprint $table): void {
+			$table->char('representative_face_id', 24)->nullable()->after('is_searchable');
+			$table->foreign('representative_face_id')
+				->references('id')
+				->on('faces')
+				->onDelete('set null');
+		});
+	}
+
+	public function down(): void
+	{
+		Schema::table('persons', function (Blueprint $table): void {
+			$table->dropForeign(['representative_face_id']);
+			$table->dropColumn('representative_face_id');
+		});
+	}
+};
diff --git a/database/migrations/2026_03_21_000006_add_cluster_label_to_faces.php b/database/migrations/2026_03_21_000006_add_cluster_label_to_faces.php
new file mode 100644
index 00000000000..79d87e305ea
--- /dev/null
+++ b/database/migrations/2026_03_21_000006_add_cluster_label_to_faces.php
@@ -0,0 +1,41 @@
+<?php
+
+/**
+ * SPDX-License-Identifier: MIT
+ * Copyright (c) 2017-2018 Tobias Reich
+ * Copyright (c) 2018-2026 LycheeOrg.
+ */
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+/**
+ * Add cluster_label (nullable INT) to the faces table.
+ *
+ * The AI-vision Python service populates this column after running DBSCAN
+ * clustering over all stored face embeddings.  A value of -1 means the face
+ * was classified as noise (no clear cluster match); NULL means clustering has
+ * not been run yet for that face.
+ *
+ * The composite index on (cluster_label, person_id, is_dismissed) supports
+ * the cluster-review UI query that groups unassigned, non-dismissed faces by
+ * their cluster label.
+ */
+return new class() extends Migration {
+	public function up(): void
+	{
+		Schema::table('faces', function (Blueprint $table): void {
+			$table->integer('cluster_label')->nullable()->after('is_dismissed');
+			$table->index(['cluster_label', 'person_id', 'is_dismissed'], 'faces_cluster_label_person_id_is_dismissed_index');
+		});
+	}
+
+	public function down(): void
+	{
+		Schema::table('faces', function (Blueprint $table): void {
+			$table->dropIndex('faces_cluster_label_person_id_is_dismissed_index');
+			$table->dropColumn('cluster_label');
+		});
+	}
+};
diff --git a/docs/specs/4-architecture/features/030-ai-vision-service/plan.md b/docs/specs/4-architecture/features/030-ai-vision-service/plan.md
index f7ea7713bae..959947e669b 100644
--- a/docs/specs/4-architecture/features/030-ai-vision-service/plan.md
+++ b/docs/specs/4-architecture/features/030-ai-vision-service/plan.md
@@ -257,7 +257,7 @@ After each increment, verify:
 - _Preconditions:_ I2 complete (`FaceClusterer` and `EmbeddingStore` implemented); I10 complete (`face_suggestions` table exists, PHP ingestion pipeline in place); I11 complete (Maintenance endpoint pattern established).
 - _Steps:_
   1. **Python** — Add `ClusterResponse` Pydantic schema (`{clusters: int, suggestions_generated: int}`) to `app/api/schemas.py`. Add `VISION_FACE_CLUSTER_EPS` env var to `AppSettings` (default `0.6`).
-  2. **Python** — Extend `app/clustering/clusterer.py` with `run_cluster_and_notify(store: EmbeddingStore, lychee_url: str, api_key: str) -> ClusterResponse`: reads all embeddings from store, runs DBSCAN, generates `(face_id, suggested_face_id, confidence)` pairs for every pair within the same cluster (cosine similarity as confidence), POSTs `{suggestions: [...]}` to `{lychee_url}/api/v2/FaceDetection/cluster-results` with `X-API-Key` header.
+  2. **Python** — Extend `app/clustering/clusterer.py` with `run_cluster_and_notify(store: EmbeddingStore, lychee_url: str, api_key: str) -> ClusterResponse`: reads all embeddings from store, runs DBSCAN, produces (a) a `labels` list — `[{face_id: str, cluster_label: int}]` for every non-noise face; (b) a `suggestions` list — `(face_id, suggested_face_id, confidence)` pairs for every intra-cluster pair (cosine similarity as confidence). POSTs `{labels: [...], suggestions: [...]}` to `{lychee_url}/api/v2/FaceDetection/cluster-results` with `X-API-Key` header. *(Q-030-49)*
   3. **Python** — Add `POST /cluster` route to `app/api/routes.py` (X-API-Key auth); calls `run_cluster_and_notify()`; returns `ClusterResponse`. Add unit + integration tests in `tests/test_clustering.py` (mock httpx POST to Lychee).
   4. **PHP** — Implement `POST /api/v2/FaceDetection/cluster-results` endpoint in `FaceDetectionController` (or a new `FaceClusterResultsController`): auth via X-API-Key, validate body `{suggestions: [{face_id, suggested_face_id, confidence}]}`, bulk-upsert `face_suggestions` rows (upsert on `(face_id, suggested_face_id)`, update `confidence`), return `{updated_count: N}`. Register route.
   5. **PHP** — Add `POST /api/v2/Maintenance::runFaceClustering` Maintenance endpoint (admin-only, follows existing check/do pattern): calls Python service `POST /cluster` via HTTP, returns 202 Accepted. Register route.
@@ -284,7 +284,7 @@ After each increment, verify:
 - _Goal:_ Give authorized users a dedicated page to review DBSCAN-produced face clusters (visually similar unassigned faces) and resolve them in bulk — either creating a Person and assigning all faces in one action, or dismissing the whole cluster as false-positives.
 - _Preconditions:_ I20 complete (`face_suggestions` populated by clustering); I9 complete (dismiss action exists); I7 complete (Person create + face assign available).
 - _Steps:_
-  1. **PHP** — Implement `GET /api/v2/FaceDetection/clusters` (API-030-18): derive clusters from the `face_suggestions` graph using connected-component grouping on unassigned (`person_id IS NULL`) and non-dismissed faces; return paginated list of `{cluster_id, size, faces: FaceResource[]}`. `cluster_id` is a deterministic hash of the sorted face IDs in the component. Respect `ai_vision_face_permission_mode` visibility rules.
+  1. **PHP** — Add migration for `cluster_label INT NULL` column + composite index `(cluster_label, person_id, is_dismissed)` on `faces` (DO-030-07, Q-030-49). Implement `GET /api/v2/FaceDetection/clusters` (API-030-18): `SELECT cluster_label, COUNT(*) as size FROM faces WHERE cluster_label IS NOT NULL AND person_id IS NULL AND is_dismissed = false GROUP BY cluster_label ORDER BY cluster_label LIMIT/OFFSET`; load preview faces per cluster; return `{cluster_id: int, size: int, faces: FaceResource[]}`. `cluster_id` = integer `cluster_label` value. Respect `ai_vision_face_permission_mode` visibility rules.
   2. **PHP** — Implement `POST /api/v2/FaceDetection/clusters/{cluster_id}/assign` (API-030-19): resolve cluster faces, create Person if `new_person_name` provided, bulk-update `face.person_id` for all faces in cluster, emit `face.cluster_assigned` telemetry. Return `{person_id, assigned_count}`.
   3. **PHP** — Implement `POST /api/v2/FaceDetection/clusters/{cluster_id}/dismiss` (API-030-20): bulk-set `is_dismissed = true` for all faces in cluster, emit `face.cluster_dismissed` telemetry. Return `{dismissed_count}`.
   4. Write feature tests: list clusters (unassigned faces grouped, assigned faces excluded), assign cluster (new person + faces linked), dismiss cluster (all faces dismissed). Test permission mode enforcement.
diff --git a/docs/specs/4-architecture/features/030-ai-vision-service/spec.md b/docs/specs/4-architecture/features/030-ai-vision-service/spec.md
index 8c864a8bdf1..49e7a469e60 100644
--- a/docs/specs/4-architecture/features/030-ai-vision-service/spec.md
+++ b/docs/specs/4-architecture/features/030-ai-vision-service/spec.md
@@ -53,7 +53,7 @@ Affected modules: **Models** (new Person, Face), **Migrations** (new tables + pi
 | FR-030-10 | Users can manually assign/reassign an unassigned Face to a Person, or create a new Person from a Face. Python service provides cluster suggestions for grouping similar faces. *(Resolved Q-030-03: auto-cluster with manual confirmation)* | Face's person_id updated; new Person created if requested. Cluster suggestions displayed as similarity scores in assignment UI. | Face must exist; target Person (if specified) must exist. | 404/422 for invalid references. | `face.assigned` | Owner directive, Q-030-03 |
 | FR-030-11 | Users can merge two Person records (combining all their Face associations). *(Resolved Q-030-22: merge direction — URL {id} = target kept; body source_person_id = source destroyed)* | All Faces of source Person reassigned to target Person (`{id}`); source Person deleted. | Both Persons must exist; user must have edit permission per `ai_vision_face_permission_mode`; body must supply `source_person_id`. | 404 if either Person not found; 403 if unauthorized. | `person.merged` | Owner directive, Q-030-22 |
 | FR-030-12 | Users can upload a selfie photo to claim a Person via face matching. Selfie sent to Python service's dedicated `POST /match` endpoint; image discarded immediately after matching. *(Resolved Q-030-06: selfie-upload claim; Q-030-11: discard after match; Q-030-12: dedicated /match endpoint; Q-030-13: lychee_face_id returned by /match)* | User uploads selfie → Python service `POST /match` returns top-N matches with `lychee_face_id` + confidence → if best match above `ai_vision_face_selfie_confidence_threshold`, Lychee resolves `lychee_face_id → Face → person_id` and links Person to User (same 1-1 rules as FR-030-05). Selfie image deleted after response. | Selfie must contain exactly one detectable face; confidence threshold configurable. | 422 if no face detected in selfie; 404 if no matching Person found; 409 if matched Person already claimed by another User. | `person.selfie_claim_requested`, `person.selfie_claim_matched` | Owner directive, Q-030-06, Q-030-11, Q-030-12, Q-030-13 |
-| FR-030-14 | When Face records are hard-deleted from Lychee (either via admin bulk-dismissed-delete or via cascade when a Photo is deleted), the corresponding embeddings shall also be removed from the Python service's embedding store to prevent stale data from polluting future clustering and suggestion results. | After hard-deleting Face records, Lychee calls Python `DELETE /embeddings` with `{face_ids: [str]}`. Python removes those embeddings from `EmbeddingStore`. The call is best-effort (fire-and-forget via queued job): Lychee proceeds with the deletion regardless of whether the Python service responds. Failures are logged as warnings. | face_ids must be a non-empty list of strings. | If the Python service is unavailable, log warning and continue — do not fail or roll back the Lychee-side deletion. | `face.embeddings_deleted` (with `count`) | Owner directive |
+| FR-030-14 | When Face records are hard-deleted from Lychee (either via admin bulk-dismissed-delete or via cascade when a Photo is deleted), the corresponding embeddings shall also be removed from the Python service's embedding store to prevent stale data from polluting future clustering and suggestion results. | After hard-deleting Face records, Lychee calls Python `DELETE /embeddings` with `{face_ids: [str]}`. Python removes those embeddings from `EmbeddingStore`. The call is best-effort (fire-and-forget via queued job): Lychee proceeds with the deletion regardless of whether the Python service responds. Failures are logged as warnings. Dispatch is triggered at **two explicit call-sites** (no Face model observer): (1) `destroyDismissed` action — collect dismissed face IDs before `Face::where('is_dismissed', true)->delete()`, then dispatch `DeleteFaceEmbeddingsJob`; (2) `PhotoObserver::deleting` — collect `$photo->faces()->pluck('id')` before cascade delete, then dispatch batch job. *(Q-030-52)* | face_ids must be a non-empty list of strings. | If the Python service is unavailable, log warning and continue — do not fail or roll back the Lychee-side deletion. | `face.embeddings_deleted` (with `count`) | Owner directive, Q-030-52 |
 | FR-030-15 | System shall provide a Cluster Review page where authorized users can browse face clusters produced by DBSCAN (faces grouped by visual similarity, not yet assigned to a Person) and bulk-name or dismiss an entire cluster in one action. | `GET /api/v2/FaceDetection/clusters` returns a paginated list of clusters; each cluster contains a `cluster_id` (integer, equal to `faces.cluster_label`, stable between clustering runs), a list of `FaceResource` items (crop_url, confidence, photo_id), and a `size` count. The page renders face-crop grids grouped by cluster. User can: (a) type a name and click “Create Person & assign all” — creates a new Person and bulk-assigns every face in the cluster to it via `POST /api/v2/FaceDetection/clusters/{cluster_id}/assign`; (b) click “Dismiss cluster” — marks every face `is_dismissed = true` via `POST /api/v2/FaceDetection/clusters/{cluster_id}/dismiss`. | Cluster review page respects `ai_vision_face_permission_mode` (same visibility rules as People page). `cluster_id` must be a valid integer `cluster_label` value with at least one qualifying face. | 404 if `cluster_id` not found; 403 if unauthorized. | `face.cluster_assigned` (with `cluster_id`, `person_id`, `face_count`), `face.cluster_dismissed` (with `cluster_id`, `face_count`) | Owner directive, Q-030-49 |
 | FR-030-13 | Admin can trigger offline DBSCAN face clustering across all stored embeddings to generate cross-photo face suggestion pairs and persist cluster labels on Face records. The Python service exposes `POST /cluster`; Lychee exposes `POST /FaceDetection/cluster-results` to ingest the results. *(Q-030-49)* | Admin calls `POST /api/v2/Maintenance::runFaceClustering` (admin-only) → Lychee calls Python service `POST /cluster` (X-API-Key auth) → Python reads all stored embeddings from `EmbeddingStore`, runs DBSCAN (eps from `VISION_FACE_CLUSTER_EPS` env var, default configurable), generates: (a) `{face_id: str, cluster_label: int}[]` where label = DBSCAN integer label (noise faces omitted); (b) `(face_id, suggested_face_id, confidence)` pairs for every intra-cluster pair using cosine similarity → POSTs both to `POST /api/v2/FaceDetection/cluster-results` (X-API-Key auth) → Lychee: bulk-updates `faces.cluster_label` (all previously clustered faces first reset to NULL, then new labels written); bulk-upserts `face_suggestions` rows (unique on `(face_id, suggested_face_id)`); returns `{faces_labeled: N, suggestions_updated: M}`. Maintenance trigger returns 202 Accepted; clustering runs asynchronously on the Python side. | Python endpoint: X-API-Key required. PHP cluster-results endpoint: X-API-Key required; body: `{labels: [{face_id: str, cluster_label: int}], suggestions: [{face_id: str, suggested_face_id: str, confidence: float}]}`. Both arrays optional (empty array = no-op for that field). Maintenance trigger: admin-only session auth. | 503 if Python service unavailable; 401 for invalid API key; no-op if no embeddings stored (returns `{faces_labeled: 0, suggestions_updated: 0}`). | `face.clustering_triggered`, `face.cluster_labels_written` (with `faces_labeled`), `face.cluster_suggestions_ingested` (with `suggestions_updated`) | Owner directive, Q-030-49 |
 
@@ -83,6 +83,7 @@ Affected modules: **Models** (new Person, Face), **Migrations** (new tables + pi
 
 | NFR-030-08 | Python service accesses photos via shared Docker volume (filesystem path). Deployment must document volume mount configuration. *(Resolved Q-030-07)* | Performance; no auth complexity for file access. | Python service reads photos from shared path; integration test confirms file access. | Docker volume configuration in docker-compose. | Owner directive, Q-030-07 |
 | NFR-030-09 | AI Vision (facial recognition and People management) is a **Supporter Edition (SE)** feature. All AI Vision config keys are stored with `level = 1`; the admin settings UI hides them on non-SE instances. Face detection and People management endpoints return 403 on non-SE instances. | Licensing; feature differentiation. | Non-SE instance: settings page does not expose the AI Vision category; scan/people endpoints return 403. | License-level check middleware (existing SE gate); config `level` column. | Owner directive |
+| NFR-030-10 | All `ai_vision_face_*` functionality is implicitly gated on `ai_vision_enabled = 1`. Any code path that checks `ai_vision_face_enabled` must first confirm `ai_vision_enabled = 1`. When `ai_vision_enabled = 0`, all AI Vision endpoints (face detection, People management, cluster review, selfie claim) return 503 and all AI Vision UI elements are hidden, regardless of the value of `ai_vision_face_enabled`. *(Q-030-51)* | Correctness; global kill-switch. | Feature tests confirm: `ai_vision_enabled=0` + `ai_vision_face_enabled=1` → all face endpoints inactive. | Compound gate check in FaceDetection and People controllers; `ai_vision_enabled` evaluated before `ai_vision_face_enabled` in every guard. | Owner directive, Q-030-51 |
 
 > **Cross-user reassignment *(Q-030-42)*:** The "Assign face" row governs reassignment of faces regardless of who previously assigned them. In `public`/`private` modes any user meeting the mode's write threshold may reassign; in `privacy-preserving`/`restricted` only the photo owner or admin may do so.
 
@@ -313,13 +314,14 @@ Read via `config('features.ai-vision.face-url')` and `config('features.ai-vision
 
 | ID | Description | Modules |
 |----|-------------|---------|
-| DO-030-01 | `Person` — id, name, user_id (nullable, unique), is_searchable (boolean, default true), timestamps | Models, API, UI |
+| DO-030-01 | `Person` — id, name, user_id (nullable, unique), is_searchable (boolean, default true), representative_face_id (nullable FK→faces ON DELETE SET NULL — explicit override for the representative crop; if NULL, PersonResource falls back to highest-confidence non-dismissed face), timestamps | Models, API, UI |
 | DO-030-02 | `Face` — id, photo_id (FK→photos), person_id (nullable FK→persons), x, y, width, height (float 0.0–1.0), confidence (float 0.0–1.0), is_dismissed (boolean, default false), crop_token (random high-entropy token, nullable; file stored at `uploads/faces/{token[0:2]}/{token[2:4]}/{token}.jpg` and served directly by nginx — path is unguessable, no app-level auth required), cluster_label (nullable INT; DBSCAN cluster assignment written by `POST /FaceDetection/cluster-results`; -1 = DBSCAN noise/outlier stored as NULL; NULL = not yet clustered), timestamps | Models, API, UI |
-| DO-030-03 | `PersonResource` — Spatie Data resource for Person API responses | Resources |
+| DO-030-03 | `PersonResource` — Spatie Data resource for Person API responses. Fields: `id`, `name`, `user_id` (nullable), `is_searchable` (boolean), `face_count` (int), `photo_count` (int), `representative_face_id` (nullable string — echoes `persons.representative_face_id`), `representative_crop_url` (nullable string — computed: if `representative_face_id` is set and the referenced Face has a `crop_token`, use that face's crop URL; otherwise `SELECT crop_token FROM faces WHERE person_id = ? AND is_dismissed = false AND crop_token IS NOT NULL ORDER BY confidence DESC LIMIT 1`; null if no qualifying face exists). PATCH /Person/{id} accepts optional `representative_face_id` (string\|null) to explicitly set or clear the override. *(Q-030-50)* | Resources |
 | DO-030-04 | `FaceResource` — Spatie Data resource for Face API responses (included in PhotoResource). Fields exposed: `id` (Face ID), `photo_id`, `person_id` (nullable), `x`, `y`, `width`, `height` (float 0.0–1.0), `confidence` (float 0.0–1.0), `is_dismissed` (boolean), `crop_url` (computed: `uploads/faces/{token[0:2]}/{token[2:4]}/{token}.jpg`; null if no crop). Embedded `suggestions[]` array — each item: `suggested_face_id`, `crop_url` (suggested face's crop or null), `person_name` (nullable, resolved via LEFT JOIN on persons), `confidence` (float 0.0–1.0). Suggestions always embedded (not lazy-loaded) since they are pre-computed and stored — no N+1 risk. *(Q-030-46)* | Resources |
 | DO-030-05 | `FaceSuggestion` — face_id (FK→faces), suggested_face_id (FK→faces), confidence (float 0.0–1.0); pre-computed similar-face suggestions stored from Python scan callback. Both FKs point to `faces`; the assignment modal JOINs at read time to resolve `suggested_face_id → person_id` (supports unassigned suggestions). Unique constraint on `(face_id, suggested_face_id)`. *(Q-030-33)* | Models, API, UI |
 | DO-030-06 | `photos` table addendum — adds nullable `face_scan_status VARCHAR(16)` column; PHP `ScanStatus` Enum cast. Values: `null` (never scanned), `pending`, `completed`, `failed`. Type chosen for MySQL/PostgreSQL/SQLite portability. *(Q-030-38)* | Models, Migrations |
 | DO-030-07 | `faces` table addendum — adds nullable `cluster_label INT` column (DBSCAN output label; NULL = not yet clustered or noise). Composite index `(cluster_label, person_id, is_dismissed)` on `faces` enables O(index-scan) `GROUP BY cluster_label` pagination for API-030-18. *(Q-030-49)* | Models, Migrations |
+| DO-030-08 | `persons` table addendum — adds `representative_face_id` nullable FK→`faces` ON DELETE SET NULL. Separate migration required (cannot be included in the original `persons` migration because `faces` does not yet exist at that point — circular-FK dependency). *(Q-030-50)* | Models, Migrations |
 
 ### API Routes / Services
 
diff --git a/docs/specs/4-architecture/features/030-ai-vision-service/tasks.md b/docs/specs/4-architecture/features/030-ai-vision-service/tasks.md
index 08aeeba05a5..7d3cc355935 100644
--- a/docs/specs/4-architecture/features/030-ai-vision-service/tasks.md
+++ b/docs/specs/4-architecture/features/030-ai-vision-service/tasks.md
@@ -77,7 +77,7 @@ _Last updated: 2026-03-21_
 ### I4 – Database Migrations
 
 - [x] T-030-10 – Create `persons` table migration (FR-030-01, S-030-01).
-  _Intent:_ Migration with columns: id (string PK), name (varchar 255), user_id (nullable unsigned int, unique, FK→users ON DELETE SET NULL), is_searchable (boolean default true), timestamps. Index on user_id.
+  _Intent:_ Migration with columns: id (string PK), name (varchar 255), user_id (nullable unsigned int, unique, FK→users ON DELETE SET NULL), is_searchable (boolean default true), timestamps. Index on user_id. **Does not include `representative_face_id`** — that FK references the `faces` table which does not yet exist; it is added in a separate addendum migration (T-030-53, DO-030-08) after `faces` is created, to avoid a circular FK dependency.
   _Verification commands:_
   - `php artisan test`
   _Notes:_ Use string PK consistent with Photo/Album models.
@@ -93,15 +93,21 @@ _Last updated: 2026-03-21_
   _Verification commands:_
   - `php artisan test`
 
+- [x] T-030-53 – Add `representative_face_id` column migration to `persons` table (DO-030-08, Q-030-50).
+  _Intent:_ New migration (runs **after** the `faces` table migration from T-030-11): `ALTER TABLE persons ADD COLUMN representative_face_id VARCHAR(?) NULL`. Add FK constraint: `representative_face_id` → `faces.id` ON DELETE SET NULL. This resolves the circular-FK dependency (persons→faces and faces→persons both require the other table to exist first). Run tests to confirm migration applies cleanly on SQLite.
+  _Verification commands:_
+  - `php artisan test`
+  - `make phpstan`
+
 ### I5 – Eloquent Models & Relationships
 
-- [ ] T-030-13 – Write unit tests for Person model relationships (FR-030-01, FR-030-03, S-030-17).
+- [x] T-030-13 – Write unit tests for Person model relationships (FR-030-01, FR-030-03, S-030-17).
   _Intent:_ Test Person→User (belongsTo), Person→Faces (hasMany), Person→Photos (derived through Face). Test cascade: Photo delete → Face cascade delete. Test Person delete → Face.person_id set to null.
   _Verification commands:_
   - `php artisan test --filter=PersonModelTest`
   - `make phpstan`
 
-- [ ] T-030-14 – Write unit tests for Face model relationships (FR-030-02, FR-030-04).
+- [x] T-030-14 – Write unit tests for Face model relationships (FR-030-02, FR-030-04).
   _Intent:_ Test Face→Photo (belongsTo), Face→Person (belongsTo nullable). Test bounding box validation (0.0–1.0 range). Test `crop_url` accessor (computed from `crop_token`).
   _Verification commands:_
   - `php artisan test --filter=FaceModelTest`
@@ -129,14 +135,14 @@ _Last updated: 2026-03-21_
 ### I6 – Spatie Data Resources
 
 - [x] T-030-18 – Create PersonResource and FaceResource (DO-030-03, DO-030-04, Q-030-46).
-  _Intent:_ PersonResource: `id`, `name`, `user_id`, `is_searchable`, `face_count` (int), `photo_count` (int), `representative_crop_url`. FaceResource per DO-030-04: `id` (Face ID), `photo_id`, `person_id` (nullable), `x`/`y`/`width`/`height` (float 0.0–1.0), `confidence`, `is_dismissed`, `crop_url` (computed from `crop_token`: `uploads/faces/{tok[0:2]}/{tok[2:4]}/{tok}.jpg`; null if no crop). Embedded `suggestions[]` array — each item: `suggested_face_id`, `crop_url` (suggested face's own crop or null), `person_name` (nullable, LEFT JOIN), `confidence`. Suggestions always included (pre-computed from `face_suggestions` table, no N+1 risk). Include FaceResource array in PhotoResource with `hidden_face_count` (int, count of suppressed non-searchable faces — Q-030-10).
+  _Intent:_ PersonResource: `id`, `name`, `user_id`, `is_searchable`, `face_count` (int), `photo_count` (int), `representative_face_id` (nullable string), `representative_crop_url` (nullable string — computed: if `representative_face_id` is set and the referenced Face has a `crop_token`, use that face's crop URL; otherwise `SELECT crop_token FROM faces WHERE person_id = ? AND is_dismissed = false AND crop_token IS NOT NULL ORDER BY confidence DESC LIMIT 1`; null if no qualifying face). FaceResource per DO-030-04: `id` (Face ID), `photo_id`, `person_id` (nullable), `x`/`y`/`width`/`height` (float 0.0–1.0), `confidence`, `is_dismissed`, `crop_url` (computed from `crop_token`: `uploads/faces/{tok[0:2]}/{tok[2:4]}/{tok}.jpg`; null if no crop). Embedded `suggestions[]` array — each item: `suggested_face_id`, `crop_url` (suggested face's own crop or null), `person_name` (nullable, LEFT JOIN), `confidence`. Suggestions always included (pre-computed from `face_suggestions` table, no N+1 risk). Include FaceResource array in PhotoResource with `hidden_face_count` (int, count of suppressed non-searchable faces — Q-030-10).
   _Verification commands:_
   - `make phpstan`
   _Notes:_ Follow existing Spatie Data patterns in app/Http/Resources/.
 
 ### I7 – Person CRUD Endpoints
 
-- [ ] T-030-19 – Write feature tests for Person CRUD and non-searchable filtering (FR-030-01, FR-030-06, S-030-05, S-030-15, S-030-18).
+- [x] T-030-19 – Write feature tests for Person CRUD and non-searchable filtering (FR-030-01, FR-030-06, S-030-05, S-030-15, S-030-18).
   _Intent:_ Tests for: list persons (paginated), get person, create person, update person (name, is_searchable), delete person (face.person_id nullified). Non-searchable person hidden from non-admin non-linked users. Admin sees all. Test both `open` and `restricted` permission modes (Q-030-08 resolved). Verify hidden_face_count in photo detail response.
   _Verification commands:_
   - `php artisan test --filter=PeopleControllerTest`
@@ -150,41 +156,41 @@ _Last updated: 2026-03-21_
 
 ### I8 – Person Claim, Admin Override, Merge & Selfie Claim
 
-- [ ] T-030-21 – Write feature tests for Person claim, admin override, and merge (FR-030-05, FR-030-11, S-030-04, S-030-13, S-030-16, S-030-19).
+- [x] T-030-21 – Write feature tests for Person claim, admin override, and merge (FR-030-05, FR-030-11, S-030-04, S-030-13, S-030-16, S-030-19).
   _Intent:_ Tests: claim person (success, sets user_id), claim already-claimed (409), admin force-claim (overrides existing link), unclaim. Merge: faces reassigned from source to target, source deleted, face count updated. Test both permission modes.
   _Verification commands:_
   - `php artisan test --filter=PersonClaimTest`
   - `php artisan test --filter=PersonMergeTest`
   - `make phpstan`
 
-- [x] T-030-22 – Implement claim (user + admin override) and merge actions (API-030-06, API-030-07).
-  _Intent:_ ClaimPerson action: set person.user_id to Auth::id(), enforce uniqueness for non-admin. Admin claim: override existing link (clear previous user's claim, set new). MergePerson action: reassign Face records, delete source Person. Register routes.
+- [x] T-030-22 – Implement claim (user + admin override), unclaim, and merge actions (API-030-06, API-030-07, API-030-15).
+  _Intent:_ ClaimPerson action: set person.user_id to Auth::id(), enforce uniqueness for non-admin. Admin claim: override existing link (clear previous user's claim, set new). UnclaimPerson action: `DELETE /api/v2/Person/{id}/claim` — sets `person.user_id = null`; only linked User or admin can unclaim (FR-030-05). MergePerson action: reassign Face records, delete source Person. Register all three routes.
   _Verification commands:_
   - `php artisan test --filter=PersonClaimTest`
   - `php artisan test --filter=PersonMergeTest`
   - `make phpstan`
 
-- [ ] T-030-23 – Write feature tests for selfie-upload claim (FR-030-12, S-030-20, S-030-21, S-030-22).
+- [x] T-030-23 – Write feature tests for selfie-upload claim (FR-030-12, S-030-20, S-030-21, S-030-22).
   _Intent:_ Tests: upload selfie → Python service returns match → Person linked (success); selfie with no face detected (422); no matching Person (404); matched Person already claimed by another user (409). Verify selfie image discarded after match (Q-030-11 resolved).
   _Verification commands:_
   - `php artisan test --filter=SelfieClaimTest`
   - `make phpstan`
 
 - [x] T-030-24 – Implement SelfieClaimController (API-030-13).
-  _Intent:_ POST /Person/claim-by-selfie: accepts multipart image upload, sends to Python service `POST /match` (Q-030-12 resolved: dedicated endpoint), receives matching person_id + confidence, validates confidence ≥ `ai_vision_face_selfie_confidence_threshold`, links Person to User (same 1-1 rules), deletes temp selfie. Register route.
+  _Intent:_ POST /Person/claim-by-selfie: accepts multipart image upload, sends to Python service `POST /match` (Q-030-12 resolved: dedicated endpoint), receives matching person_id + confidence, validates confidence ≥ `ai_vision_face_selfie_confidence_threshold`, links Person to User (same 1-1 rules), deletes temp selfie. Apply Laravel `throttle:5,1` middleware to this route (5 requests/minute per user — Q-030-44). Register route.
   _Verification commands:_
   - `php artisan test --filter=SelfieClaimTest`
   - `make phpstan`
 
 ### I9 – Face Assignment, Dismiss & Cleanup Endpoints
 
-- [ ] T-030-25 – Write feature tests for face assignment (FR-030-10, S-030-02, S-030-03).
+- [x] T-030-25 – Write feature tests for face assignment (FR-030-10, S-030-02, S-030-03).
   _Intent:_ Tests: assign face to existing person, assign face creating new person, reassign face to different person. Test all four `ai_vision_face_permission_mode` values.
   _Verification commands:_
   - `php artisan test --filter=FaceAssignmentTest`
   - `make phpstan`
 
-- [ ] T-030-26 – Write feature tests for face dismiss/undismiss and admin bulk delete (API-030-14, API-030-16, S-030-24, S-030-25, Q-030-47).
+- [x] T-030-26 – Write feature tests for face dismiss/undismiss and admin bulk delete (API-030-14, API-030-16, S-030-24, S-030-25, Q-030-47).
   _Intent:_ Tests: `PATCH /api/v2/Face/{id}` toggles `is_dismissed`; photo owner can dismiss, non-owner gets 403; admin can always dismiss. `DELETE /api/v2/Face/dismissed` hard-deletes all `is_dismissed = true` faces, removes crop files, returns count. Emit `face.dismissed` / `face.undismissed` / `face.bulk_deleted` telemetry events (TE-030-10/11/12).
   _Verification commands:_
   - `php artisan test --filter=FaceDismissTest`
@@ -199,13 +205,13 @@ _Last updated: 2026-03-21_
 
 ### I10 – Scan Trigger & Result Ingestion Endpoints
 
-- [ ] T-030-27 – Write feature tests for scan trigger and result ingestion (FR-030-07, FR-030-08, S-030-01, S-030-07, S-030-08, S-030-14, S-030-23).
+- [x] T-030-27 – Write feature tests for scan trigger and result ingestion (FR-030-07, FR-030-08, S-030-01, S-030-07, S-030-08, S-030-14, S-030-23).
   _Intent:_ Tests: trigger scan for photo (202), trigger scan for album, receive results (Face records created with crop_token), re-scan replaces old faces (old crops deleted), invalid photo_id (404), auto-scan on upload when enabled. Test both permission modes for scan trigger.
   _Verification commands:_
   - `php artisan test --filter=FaceDetectionTest`
   - `make phpstan`
 
-- [ ] T-030-28 – Write feature test for service unavailability (FR-030-08, NFR-030-03, S-030-09).
+- [x] T-030-28 – Write feature test for service unavailability (FR-030-08, NFR-030-03, S-030-09).
   _Intent:_ Test: scan trigger when Python service is unreachable returns 503; all other Lychee endpoints continue to work.
   _Verification commands:_
   - `php artisan test --filter=FaceDetectionServiceUnavailableTest`
@@ -219,7 +225,7 @@ _Last updated: 2026-03-21_
 
 ### I11 – Bulk Scan Commands & Maintenance Endpoints
 
-- [ ] T-030-30 – Write feature tests for `lychee:scan-faces` command (FR-030-09, S-030-06, CLI-030-01, CLI-030-02).
+- [x] T-030-30 – Write feature tests for `lychee:scan-faces` command (FR-030-09, S-030-06, CLI-030-01, CLI-030-02).
   _Intent:_ Tests: command enqueues photos where `face_scan_status IS NULL` (not failed/completed), `--album` filter works (non-recursive — only direct photos in album, Q-030-41), already-scanned photos skipped.
   _Verification commands:_
   - `php artisan test --filter=ScanFacesCommandTest`
@@ -237,7 +243,7 @@ _Last updated: 2026-03-21_
   - `php artisan test --filter=RescanFailedFacesCommandTest`
   - `make phpstan`
 
-- [ ] T-030-31c – Write feature tests and implement Maintenance::resetStuckFaces endpoints (API-030-17, API-030-17b, Q-030-48, S-030-26).
+- [x] T-030-31c – Write feature tests and implement Maintenance::resetStuckFaces endpoints (API-030-17, API-030-17b, Q-030-48, S-030-26).
   _Intent:_ `GET /api/v2/Maintenance::resetStuckFaces`: admin-only check — returns `{count: N}` for photos stuck in `pending` longer than `older_than_minutes` (default 60). `POST /api/v2/Maintenance::resetStuckFaces`: admin-only do — resets those records to `null` and returns `{reset_count: N}`. Body: optional `older_than_minutes` (integer). Follows existing `Maintenance::cleaning` / `Maintenance::jobs` check/do pattern. Register in `api_v2.php`.
   _Verification commands:_
   - `php artisan test --filter=MaintenanceResetStuckFacesTest`
@@ -245,7 +251,7 @@ _Last updated: 2026-03-21_
 
 ### I12 – Person Photos Endpoint
 
-- [ ] T-030-32 – Write feature test for Person photos listing (FR-030-03, S-030-12, API-030-08).
+- [x] T-030-32 – Write feature test for Person photos listing (FR-030-03, S-030-12, API-030-08).
   _Intent:_ Tests: get paginated photos for person, respects album access control (user without album access doesn't see photo), empty result for person with no faces.
   _Verification commands:_
   - `php artisan test --filter=PersonPhotosTest`
@@ -328,20 +334,26 @@ _Last updated: 2026-03-21_
 
 ### I20 – Clustering Endpoint: Python `POST /cluster` + PHP Ingestion & Trigger
 
-- [ ] T-030-44 – Implement Python `POST /cluster` endpoint and wire `FaceClusterer` (FR-030-13, S-030-27).
-  _Intent:_ Add `ClusterResponse` Pydantic schema (`{clusters: int, suggestions_generated: int}`) to `app/api/schemas.py`. Add `VISION_FACE_CLUSTER_EPS` (float, default `0.6`) to `AppSettings`. Extend `app/clustering/clusterer.py` with `run_cluster_and_notify(store, lychee_url, api_key)`: read all embeddings, run DBSCAN, generate `(face_id, suggested_face_id, confidence)` pairs within each cluster (cosine similarity as confidence), POST `{suggestions: [...]}` to `{lychee_url}/api/v2/FaceDetection/cluster-results` with `X-API-Key`. Add `POST /cluster` route to `app/api/routes.py` (X-API-Key auth dependency) that calls `run_cluster_and_notify()` and returns `ClusterResponse`. Add unit + integration tests in `tests/test_clustering.py` (mock httpx POST to Lychee).
+- [x] T-030-43 – Add `cluster_label` column migration to `faces` table (DO-030-07, Q-030-49).
+  _Intent:_ New migration: `ALTER TABLE faces ADD COLUMN cluster_label INT NULL`. Add composite index `(cluster_label, person_id, is_dismissed)` on `faces` to support O(index-scan) `GROUP BY cluster_label` paging in API-030-18. This migration is a prerequisite for T-030-44 (Python cluster ingestion) and T-030-50 (cluster-review API). Run tests to confirm migration applies cleanly on SQLite.
+  _Verification commands:_
+  - `php artisan test`
+  - `make phpstan`
+
+- [x] T-030-44 – Implement Python `POST /cluster` endpoint and wire `FaceClusterer` (FR-030-13, S-030-27, Q-030-49).
+  _Intent:_ Add `ClusterResponse` Pydantic schema (`{clusters: int, faces_labeled: int, suggestions_generated: int}`) to `app/api/schemas.py`. Add `VISION_FACE_CLUSTER_EPS` (float, default `0.6`) to `AppSettings`. Extend `app/clustering/clusterer.py` with `run_cluster_and_notify(store, lychee_url, api_key)`: read all embeddings, run DBSCAN, produce (a) `labels` list — `[{face_id: str, cluster_label: int}]` for every non-noise face (noise faces skipped); (b) `suggestions` list — `(face_id, suggested_face_id, confidence)` pairs for every intra-cluster pair (cosine similarity); POST `{labels: [...], suggestions: [...]}` to `{lychee_url}/api/v2/FaceDetection/cluster-results` with `X-API-Key`. Add `POST /cluster` route to `app/api/routes.py` (X-API-Key auth dependency) that calls `run_cluster_and_notify()` and returns `ClusterResponse`. Add unit + integration tests in `tests/test_clustering.py` (mock httpx POST to Lychee).
   _Verification commands:_
   - `cd ai-vision-service && uv run pytest tests/test_clustering.py`
   - `uv run ty check`
   - `uv run ruff check`
 
-- [ ] T-030-45 – Write feature tests and implement PHP `POST /FaceDetection/cluster-results` ingestion endpoint (FR-030-13).
-  _Intent:_ New action `clusterResults` on `FaceDetectionController`: auth via X-API-Key header; validate body `{suggestions: [{face_id, suggested_face_id, confidence}]}`; bulk-upsert `face_suggestions` rows on `(face_id, suggested_face_id)` updating `confidence`; return `{updated_count: N}`. Feature tests: success (suggestions upserted, count returned), invalid API key (401), malformed body (422), unknown face_id (422). Register route in `api_v2.php`.
+- [x] T-030-45 – Write feature tests and implement PHP `POST /FaceDetection/cluster-results` ingestion endpoint (FR-030-13, Q-030-49).
+  _Intent:_ New action `clusterResults` on `FaceDetectionController`: auth via X-API-Key header; validate body `{labels: [{face_id: str, cluster_label: int}], suggestions: [{face_id: str, suggested_face_id: str, confidence: float}]}` (both arrays optional — empty = no-op for that field). Processing: (1) if `labels` non-empty — first reset all `faces.cluster_label` to NULL (full re-cluster run), then bulk `UPDATE faces SET cluster_label = ? WHERE id = ?` for each label entry; (2) if `suggestions` non-empty — bulk-upsert `face_suggestions` rows on `(face_id, suggested_face_id)` updating `confidence`. Return `{faces_labeled: N, suggestions_updated: M}`. Feature tests: labels bulk-update `faces.cluster_label` correctly; suggestions upserted; both arrays in same request; invalid API key (401); malformed body (422); unknown face_id (422). Register route in `api_v2.php`.
   _Verification commands:_
   - `php artisan test --filter=FaceClusterResultsTest`
   - `make phpstan`
 
-- [ ] T-030-46 – Write feature tests and implement PHP `POST /Maintenance::runFaceClustering` admin trigger (FR-030-13).
+- [x] T-030-46 – Write feature tests and implement PHP `POST /Maintenance::runFaceClustering` admin trigger (FR-030-13).
   _Intent:_ Admin-only Maintenance endpoint following the existing check/do pattern. `POST /api/v2/Maintenance::runFaceClustering`: calls Python service `POST /cluster` via HTTP with `X-API-Key`; returns 202 Accepted on success; returns 503 if Python service is unreachable (NFR-030-03). Feature tests: admin triggers clustering (202), non-admin gets 403, service unavailable (503). Register route in `api_v2.php`.
   _Verification commands:_
   - `php artisan test --filter=MaintenanceFaceClusteringTest`
@@ -349,36 +361,36 @@ _Last updated: 2026-03-21_
 
 ### I21 – Embedding Sync on Deletion + Blur Threshold Filtering
 
-- [ ] T-030-47 – Python: `VISION_FACE_BLUR_THRESHOLD` filter in detector (FR-030-02, S-030-30).
+- [x] T-030-47 – Python: `VISION_FACE_BLUR_THRESHOLD` filter in detector (FR-030-02, S-030-30).
   _Intent:_ Add `VISION_FACE_BLUR_THRESHOLD` (float, default `100.0`) to `AppSettings` in `app/config.py`. In `app/detection/detector.py`, after detecting each face and cropping the bounding-box region, compute its Laplacian variance (`cv2.Laplacian(crop_region, cv2.CV_64F).var()`); discard any face whose variance is below the threshold before adding it to the results list. A value of `0.0` disables the filter (all faces pass). Update `tests/test_detection.py`: verify a synthetic blurry patch (Gaussian blur, variance << threshold) is excluded; verify a sharp patch is retained.
   _Verification commands:_
   - `cd ai-vision-service && uv run pytest tests/test_detection.py`
   - `uv run ty check`
   - `uv run ruff check`
 
-- [ ] T-030-48 – Python: `DELETE /embeddings` endpoint (FR-030-14, S-030-28, S-030-29).
+- [x] T-030-48 – Python: `DELETE /embeddings` endpoint (FR-030-14, S-030-28, S-030-29).
   _Intent:_ Add `delete_many(face_ids: list[str]) -> int` to the `EmbeddingStore` protocol in `app/embeddings/store.py` and implement it in both `SQLiteStore` and `PgVectorStore` (ignores unknown IDs silently; returns count of rows actually deleted). Add `DELETE /embeddings` route in `app/api/routes.py` (X-API-Key auth): accepts `{face_ids: list[str]}`, calls `store.delete_many()`, returns `{deleted_count: int}`. Add tests in `tests/test_api.py`: success (returns count), invalid API key (401), empty list (400), IDs not in store (returns `{deleted_count: 0}`).
   _Verification commands:_
   - `cd ai-vision-service && uv run pytest tests/test_api.py tests/test_embeddings.py`
   - `uv run ty check`
   - `uv run ruff check`
 
-- [ ] T-030-49 – PHP: dispatch embedding deletion after Face hard-deletes (FR-030-14, S-030-28, S-030-29).
-  _Intent:_ Create `DeleteFaceEmbeddingsJob` (implements `ShouldQueue`): accepts `array<string> $faceIds`, calls Python `DELETE /embeddings` via HTTP with `X-API-Key`; catches all exceptions, logs a warning (`Log::warning`), and returns without re-throwing (never fails the queue worker or rolls back the Lychee deletion). Dispatch this job from two trigger points: (1) in `destroyDismissed` action — collect IDs of dismissed faces before deleting them, dispatch job after `Face::where('is_dismissed', true)->delete()`; (2) in a `Face` model observer `deleting` event, or by hooking into the Photo delete pipeline to collect `face_ids` before cascade — dispatch batch job for those IDs. Write feature tests: `DELETE /Face/dismissed` → job dispatched with correct IDs; Photo delete → job dispatched for cascaded faces; Python service unavailable → Lychee deletion succeeds, warning logged.
+- [x] T-030-49 – PHP: dispatch embedding deletion after Face hard-deletes (FR-030-14, S-030-28, S-030-29).
+  _Intent:_ Create `DeleteFaceEmbeddingsJob` (implements `ShouldQueue`): accepts `array<string> $faceIds`, calls Python `DELETE /embeddings` via HTTP with `X-API-Key`; catches all exceptions, logs a warning (`Log::warning`), and returns without re-throwing (never fails the queue worker or rolls back the Lychee deletion). Dispatch this job from **two explicit call-sites** (no Face model observer — Q-030-52/Option B): (1) in `destroyDismissed` action — collect IDs of dismissed faces before `Face::where('is_dismissed', true)->delete()`, then dispatch job; (2) in `PhotoObserver::deleting` — collect `$photo->faces()->pluck('id')` before cascade delete, then dispatch batch job for those IDs. Write feature tests: `DELETE /Face/dismissed` → job dispatched with correct IDs; Photo delete → job dispatched for cascaded faces; Python service unavailable → Lychee deletion succeeds, warning logged.
   _Verification commands:_
   - `php artisan test --filter=FaceEmbeddingSyncTest`
   - `make phpstan`
 
 ### I22 – Cluster Review UI: Browse & Bulk-Name/Dismiss Clusters
 
-- [ ] T-030-50 – Write feature tests and implement PHP cluster-review API endpoints (FR-030-15, API-030-18, API-030-19, API-030-20, S-030-31, S-030-32).
-  _Intent:_ `GET /api/v2/FaceDetection/clusters`: query `face_suggestions` graph, derive connected components of unassigned (`person_id IS NULL`) non-dismissed faces using breadth-first traversal; assign each component a deterministic `cluster_id` (SHA1 of sorted face IDs); return paginated `{cluster_id, size, faces: FaceResource[]}`. `POST /api/v2/FaceDetection/clusters/{cluster_id}/assign`: resolve faces in cluster, create Person if `new_person_name` supplied (or use existing `person_id`), bulk `UPDATE faces SET person_id = ? WHERE id IN (...)`, emit `face.cluster_assigned` telemetry, return `{person_id, assigned_count}`. `POST /api/v2/FaceDetection/clusters/{cluster_id}/dismiss`: bulk `UPDATE faces SET is_dismissed = true WHERE id IN (...)`, emit `face.cluster_dismissed`, return `{dismissed_count}`. Feature tests: list clusters (only unassigned non-dismissed faces; already-assigned excluded), assign cluster (new person created + faces linked; existing person used if person_id supplied), dismiss cluster (all faces marked is_dismissed). Test permission mode enforcement (public/restricted at minimum). Register routes in `api_v2.php`.
+- [x] T-030-50 – Write feature tests and implement PHP cluster-review API endpoints (FR-030-15, API-030-18, API-030-19, API-030-20, S-030-31, S-030-32, Q-030-49).
+  _Intent:_ `GET /api/v2/FaceDetection/clusters`: `SELECT cluster_label, COUNT(*) as size FROM faces WHERE cluster_label IS NOT NULL AND person_id IS NULL AND is_dismissed = false GROUP BY cluster_label ORDER BY cluster_label LIMIT ? OFFSET ?` (uses composite index DO-030-07); for each cluster, load preview faces via `WHERE cluster_label = ? AND person_id IS NULL AND is_dismissed = false`; return `{cluster_id: int, size: int, faces: FaceResource[]}`. Respects `ai_vision_face_permission_mode`. `POST /api/v2/FaceDetection/clusters/{cluster_id}/assign`: validate `cluster_id` is a valid integer `cluster_label` with qualifying faces; create Person if `new_person_name` supplied (or validate existing `person_id`); bulk `UPDATE faces SET person_id = ? WHERE cluster_label = ? AND person_id IS NULL AND is_dismissed = false`; emit `face.cluster_assigned`; return `{person_id, assigned_count}`. `POST /api/v2/FaceDetection/clusters/{cluster_id}/dismiss`: bulk `UPDATE faces SET is_dismissed = true WHERE cluster_label = ? AND person_id IS NULL AND is_dismissed = false`; emit `face.cluster_dismissed`; return `{dismissed_count}`. Feature tests: list clusters (only qualifying faces; already-assigned or dismissed excluded), 404 for unknown cluster_id, assign cluster (new person + faces linked; existing person used if person_id supplied), dismiss cluster (all qualifying faces marked is_dismissed). Test permission mode enforcement (public/restricted at minimum). Register routes in `api_v2.php`.
   _Verification commands:_
   - `php artisan test --filter=FaceClusterReviewTest`
   - `make phpstan`
 
-- [ ] T-030-51 – Create FaceClusters.vue page and wire into navigation (FR-030-15, UI-030-08, S-030-31, S-030-32).
-  _Intent:_ New Vue3 view at `/people/clusters`. Fetches `GET /FaceDetection/clusters` (paginated). Renders a vertical list of cluster cards; each card shows: first 5 face-crop `<img>` thumbnails (from `crop_url`), "+N more" badge when `size > 5`, size badge, a name `InputText`, a "Create Person & Assign All" `Button` (calls `POST /FaceDetection/clusters/{id}/assign` with `new_person_name`; or if person selected from dropdown, uses `person_id`), and a "Dismiss" `Button` (calls `POST /FaceDetection/clusters/{id}/dismiss`). After either action, remove the cluster card from the list without full-page reload. "Run Cluster" `Button` in page header calls `POST /Maintenance::runFaceClustering` then re-fetches clusters. Empty state illustration when no clusters exist. Add `/people/clusters` route to Vue Router and a "Clusters" navigation link under People in the sidebar (visible only when `ai_vision_face_enabled` is true).
+- [x] T-030-51 – Create FaceClusterService.ts, FaceClusters.vue page, and wire into navigation (FR-030-15, UI-030-08, S-030-31, S-030-32).
+  _Intent:_ Create `services/FaceClusterService.ts` with typed functions: `getClusters(page)`, `assignCluster(clusterId, payload)`, `dismissCluster(clusterId)`, `runClustering()` — all using `${Constants.getApiUrl()}` base URL. New Vue3 view `FaceClusters.vue` at `/people/clusters`. Fetches `GET /FaceDetection/clusters` (paginated, via FaceClusterService). Renders a vertical list of cluster cards; each card shows: first 5 face-crop `<img>` thumbnails (from `crop_url`), "+N more" badge when `size > 5`, size badge, a name `InputText`, a "Create Person & Assign All" `Button` (calls `assignCluster` with `new_person_name`; or if person selected from dropdown, uses `person_id`), and a "Dismiss" `Button` (calls `dismissCluster`). After either action, remove the cluster card from the list without full-page reload. "Run Cluster" `Button` in page header calls `runClustering()` then re-fetches clusters. Empty state illustration when no clusters exist. Add `/people/clusters` route to Vue Router and a "Clusters" navigation link under People in the sidebar (visible only when `ai_vision_face_enabled` is true).
   _Verification commands:_
   - `npm run check`
   - `npm run format`
diff --git a/docs/specs/4-architecture/open-questions.md b/docs/specs/4-architecture/open-questions.md
index 0239a53d88a..817b62423bf 100644
--- a/docs/specs/4-architecture/open-questions.md
+++ b/docs/specs/4-architecture/open-questions.md
@@ -6,10 +6,80 @@ Track unresolved high- and medium-impact questions here. Remove each row as soon
 
 | Question ID | Feature | Priority | Summary | Status | Opened | Updated |
 |-------------|---------|----------|---------|--------|--------|---------|
-| (none) | — | — | — | — | — | — |
+| *(none)* | | | | | | |
 
 ## Question Details
 
+### ~~Q-030-50: `PersonResource.representative_crop_url` — Selection Rule Unspecified~~ ✅ RESOLVED
+
+**Resolution:** **Options A + C** combined. Default logic uses highest-confidence non-dismissed face (`ORDER BY confidence DESC LIMIT 1`). A `representative_face_id` nullable FK→`faces` ON DELETE SET NULL is also added to the `persons` table (DO-030-08, T-030-53), allowing admins/users to override the representative via `PATCH /Person/{id}`. `PersonResource` uses the FK if set (and the referenced Face has a `crop_token`); otherwise falls back to the highest-confidence SELECT. Captured in DO-030-01, DO-030-03, DO-030-08, T-030-10 (note), T-030-18, T-030-53.
+
+**Context:** DO-030-03 (`PersonResource`) lists `representative_crop_url` as a field. T-030-18 mentions it. The spec has no rule for *which* Face crop is chosen as representative. `PersonCard.vue` uses it as the person's avatar on the People page.
+
+**Impact:** If implementors pick different strategies independently, the result will differ from what product design expects. Affects I6 (FaceResource), I13 (People page thumbnails).
+
+**Option A (Recommended) — highest-confidence face crop**
+- `SELECT crop_token FROM faces WHERE person_id = ? AND is_dismissed = false AND crop_token IS NOT NULL ORDER BY confidence DESC LIMIT 1`
+- Deterministic, stable once detection quality is good, no additional sort column needed.
+
+**Option B — most-recently added face crop**
+- `ORDER BY created_at DESC LIMIT 1`
+- Reflects the latest photo that person appeared in — may be more "current" but less relevant.
+
+**Option C — null until user explicitly sets a representative face**
+- Add a `representative_face_id` nullable FK on `persons` table, set via a new PATCH sub-action.
+- Fully explicit but requires extra migration and UI affordance.
+
+**Affects:** DO-030-03, T-030-18, PersonResource, PersonCard.vue.
+
+---
+
+### ~~Q-030-51: `ai_vision_enabled` / `ai_vision_face_enabled` Gating Hierarchy~~ ✅ RESOLVED
+
+**Resolution:** **Option A** — compound gate. All `ai_vision_face_*` functionality is implicitly gated on `ai_vision_enabled = 1`. Any code path that gates on `ai_vision_face_enabled` must first confirm `ai_vision_enabled = 1`. If `ai_vision_enabled = 0`, all AI Vision endpoints return 503 / UI hides all AI Vision elements, regardless of `ai_vision_face_enabled`. Captured in NFR-030-10 and config table note for `ai_vision_face_enabled`.
+
+**Context:** T-030-12 adds two separate config flags: `ai_vision_enabled` (global feature kill-switch for the whole AI Vision system) and `ai_vision_face_enabled` (specifically enables face detection). T-030-29 fires auto-scan when `ai_vision_face_enabled = 1`, but no task or spec explicitly states that `ai_vision_face_enabled` must ALSO check `ai_vision_enabled` first. An implementor could check only one flag or check both.
+
+**Impact:** If `ai_vision_enabled = 0` but `ai_vision_face_enabled = 1`, undefined behaviour. Affects I8, I9, I10, I17 (every place that gates on the config).
+
+**Option A (Recommended) — `ai_vision_face_enabled` implies `ai_vision_enabled`; guard with both**
+- Any code path that checks `ai_vision_face_enabled` must first confirm `ai_vision_enabled`. Documented as a compound gate in NFR or as a middleware.
+- Spec adds: "All `ai_vision_face_*` functionality is implicitly gated on `ai_vision_enabled = 1`."
+
+**Option B — single flag; remove `ai_vision_enabled`**
+- Since only face detection exists now, `ai_vision_face_enabled` is the only effective toggle. `ai_vision_enabled` is removed or deferred to when a second AI Vision feature ships.
+- Simpler, but loses the global kill-switch if other AI features follow.
+
+**Option C — independent flags; document the combination table**
+- `ai_vision_enabled` controls API availability (503 when off). `ai_vision_face_enabled` controls auto-on-upload and People page visibility. Both can vary independently.
+
+**Affects:** FR-030-08, NFR-030-03, T-030-12, T-030-29, T-030-38, FaceDetectionController, FaceDetectionService.ts.
+
+---
+
+### ~~Q-030-52: Embedding Deletion Dispatch Hook — Observer vs. Photo Pipeline~~ ✅ RESOLVED
+
+**Resolution:** **Option B** — no Face model observer. Two explicit call-sites: (1) `destroyDismissed` action — collect dismissed face IDs before `Face::where('is_dismissed', true)->delete()`, dispatch `DeleteFaceEmbeddingsJob`; (2) `PhotoObserver::deleting` — collect `$photo->faces()->pluck('id')` before cascade, dispatch batch job. Captured in FR-030-14 and T-030-49.
+
+**Context:** T-030-49 (FR-030-14) specifies dispatching `DeleteFaceEmbeddingsJob` when Face records are hard-deleted. The task says "Face model observer `deleting` event, **or** by hooking into the Photo delete pipeline." These are architecturally different:
+
+- **Observer (`deleting`)**: fires per-row; requires N individual event firings for a batch delete; works for both cascade-from-Photo and admin bulk-delete paths uniformly.
+- **Photo pipeline hook**: collects all `face_ids` before the cascade delete, dispatches one batch job; avoids N observer firings but only covers Photo→Face cascade. The admin `destroyDismissed` path still needs its own dispatch.
+
+**Impact:** The observer approach fires for every delete path automatically but causes N jobs for a batch Photo cascade. The pipeline approach is more efficient but duplicates dispatch logic. Affects I21 (PHP `DeleteFaceEmbeddingsJob`), T-030-49.
+
+**Option A (Recommended) — Observer on `deleting`, but coalesce with batch dispatch**
+- Register a `Face` model observer. On `deleting`, collect IDs into a static `$pendingDeletion` buffer. A `deleted` static hook (or `booted` teardown) dispatches one job for the full batch at the end of the request lifecycle. Handles all delete paths without duplicating logic.
+
+**Option B — No observer; explicit dispatch at each call-site**
+- `destroyDismissed`: collects IDs before delete, dispatches one job explicitly.
+- Photo delete: `PhotoObserver::deleting` collects `$photo->faces()->pluck('id')` before cascade, dispatches job.
+- Simpler per-path but requires remembering to add dispatch at every future Face-delete call-site.
+
+**Affects:** FR-030-14, T-030-49, I21, Face model observer, PhotoObserver, `destroyDismissed` action.
+
+---
+
 ### ~~Q-030-49: Cluster Storage Model — Resolved~~ ✅ RESOLVED — How Should the Backend Know About Existing Clusters?
 
 **Context:** FR-030-15 and API-030-18/19/20 specify a Cluster Review page. The current spec says `cluster_id` is "derived from the suggestion graph" (connected components of `face_suggestions`). This approach has three fatal flaws: (1) O(V+E) graph traversal per `GET /clusters` request violates NFR-030-02; (2) SHA1-of-sorted-face-IDs IDs are unstable — they change when any face in the cluster is dismissed or assigned, breaking `POST .../clusters/{id}/assign`; (3) pagination over connected components requires materialising all clusters first.
diff --git a/lang/en/maintenance.php b/lang/en/maintenance.php
index 8aef02e9fb1..1bd9a1fcf78 100644
--- a/lang/en/maintenance.php
+++ b/lang/en/maintenance.php
@@ -102,4 +102,8 @@
     'bulk-scan-faces' => [
         'description' => 'Queue all photos that have not yet been scanned for facial recognition. Requires the AI Vision service to be running.',
     ],
+    'run-clustering' => [
+        'description' => 'Trigger face clustering in the AI Vision service. Groups detected faces by similarity so you can assign them to people.',
+        'success' => 'Clustering started successfully.',
+    ],
 ];
diff --git a/lang/en/people.php b/lang/en/people.php
index 7f5dc009ce0..faf4763d4bf 100644
--- a/lang/en/people.php
+++ b/lang/en/people.php
@@ -46,6 +46,13 @@
         'unclaim' => 'Unlink from me',
         'photos_title' => 'Photos of %s',
     ],
+    'clusters_title' => 'Face Clusters',
+    'run_clustering' => 'Run Clustering',
+    'no_clusters' => 'No clusters found. Run clustering to group detected faces.',
+    'faces' => 'faces',
+    'enter_name' => 'Person name…',
+    'assign' => 'Assign',
+    'dismiss' => 'Dismiss',
     'assignment' => [
         'title' => 'Assign face to person',
         'select_person' => 'Select existing person…',
diff --git a/resources/js/components/gallery/photoModule/PhotoBox.vue b/resources/js/components/gallery/photoModule/PhotoBox.vue
index 193cd8ebdd6..104324da039 100644
--- a/resources/js/components/gallery/photoModule/PhotoBox.vue
+++ b/resources/js/components/gallery/photoModule/PhotoBox.vue
@@ -152,15 +152,18 @@ function updateFaceOverlay() {
 }
 
 // Re-runs whenever imageEl changes (photo/mode switch) — flush:'post' ensures DOM is ready.
-watchEffect(() => {
-	imageResizeObserver?.disconnect();
-	const img = imageEl.value;
-	if (!img) return;
-	imageResizeObserver = new ResizeObserver(updateFaceOverlay);
-	imageResizeObserver.observe(img);
-	// rAF ensures browser layout is complete (handles both cached and uncached images)
-	requestAnimationFrame(updateFaceOverlay);
-}, { flush: "post" });
+watchEffect(
+	() => {
+		imageResizeObserver?.disconnect();
+		const img = imageEl.value;
+		if (!img) return;
+		imageResizeObserver = new ResizeObserver(updateFaceOverlay);
+		imageResizeObserver.observe(img);
+		// rAF ensures browser layout is complete (handles both cached and uncached images)
+		requestAnimationFrame(updateFaceOverlay);
+	},
+	{ flush: "post" },
+);
 
 onUnmounted(() => imageResizeObserver?.disconnect());
 
diff --git a/resources/js/components/maintenance/MaintenanceRunClustering.vue b/resources/js/components/maintenance/MaintenanceRunClustering.vue
new file mode 100644
index 00000000000..487d74a849a
--- /dev/null
+++ b/resources/js/components/maintenance/MaintenanceRunClustering.vue
@@ -0,0 +1,57 @@
+<template>
+	<Card
+		class="min-h-40 dark:bg-surface-800 shadow shadow-surface-950/30 rounded-lg relative"
+		pt:body:class="min-h-40 h-full"
+		pt:content:class="h-full flex justify-between flex-col"
+	>
+		<template #title>
+			<div class="text-center">
+				{{ $t("people.run_clustering") }}
+			</div>
+		</template>
+		<template #content>
+			<ScrollPanel class="w-full h-40 text-sm text-muted-color">
+				<div class="w-full text-center">{{ $t("maintenance.run-clustering.description") }}</div>
+				<ProgressSpinner v-if="loading" class="w-full" />
+			</ScrollPanel>
+			<div class="flex gap-4 mt-1">
+				<Button v-if="!loading" severity="primary" class="w-full font-bold border-none" @click="exec">
+					{{ $t("people.run_clustering") }}
+				</Button>
+			</div>
+		</template>
+	</Card>
+</template>
+
+<script setup lang="ts">
+import { ref } from "vue";
+import Button from "primevue/button";
+import Card from "primevue/card";
+import { useToast } from "primevue/usetoast";
+import ProgressSpinner from "primevue/progressspinner";
+import ScrollPanel from "primevue/scrollpanel";
+import { trans } from "laravel-vue-i18n";
+import FaceClusterService from "@/services/face-cluster-service";
+
+const loading = ref(false);
+const toast = useToast();
+
+function exec() {
+	loading.value = true;
+	FaceClusterService.runClustering()
+		.then(() => {
+			toast.add({ severity: "success", summary: trans("toasts.success"), detail: trans("maintenance.run-clustering.success"), life: 3000 });
+			loading.value = false;
+		})
+		.catch((e) => {
+			toast.add({ severity: "error", summary: trans("toasts.error"), detail: e.response?.data?.message, life: 3000 });
+			loading.value = false;
+		});
+}
+</script>
+
+<style lang="css" scoped>
+.lychee-dark .p-card {
+	--p-card-background: var(--p-surface-800);
+}
+</style>
diff --git a/resources/js/lychee.d.ts b/resources/js/lychee.d.ts
index 17266de8712..a77059933f1 100644
--- a/resources/js/lychee.d.ts
+++ b/resources/js/lychee.d.ts
@@ -1,1106 +1,1208 @@
 declare namespace App.DTO {
-export type AlbumSortingCriterion = {
-column: App.Enum.ColumnSortingType;
-order: App.Enum.OrderSortingType;
-};
-export type PhotoSortingCriterion = {
-column: App.Enum.ColumnSortingType;
-order: App.Enum.OrderSortingType;
-};
-export type SortingCriterion = {
-column: App.Enum.ColumnSortingType;
-order: App.Enum.OrderSortingType;
-};
+	export type AlbumSortingCriterion = {
+		column: App.Enum.ColumnSortingType;
+		order: App.Enum.OrderSortingType;
+	};
+	export type PhotoSortingCriterion = {
+		column: App.Enum.ColumnSortingType;
+		order: App.Enum.OrderSortingType;
+	};
+	export type SortingCriterion = {
+		column: App.Enum.ColumnSortingType;
+		order: App.Enum.OrderSortingType;
+	};
 }
 declare namespace App.Enum {
-export type AlbumDecorationOrientation = 'row' | 'row-reverse' | 'column' | 'column-reverse';
-export type AlbumDecorationType = 'none' | 'layers' | 'album' | 'photo' | 'all';
-export type AlbumHeaderSize = 'half_screen' | 'full_screen';
-export type AlbumLayoutType = 'list' | 'grid';
-export type AlbumTitleColor = 'white' | 'black' | 'colour_1' | 'colour_2' | 'colour_3' | 'colour_4' | 'colour_5';
-export type AlbumTitlePosition = 'top_left' | 'top_right' | 'bottom_left' | 'bottom_right' | 'center';
-export type AspectRatioCSSType = 'aspect-5x4' | 'aspect-4x5' | 'aspect-3x2' | 'aspect-square' | 'aspect-2x3' | 'aspect-video';
-export type AspectRatioType = '5/4' | '3/2' | '1/1' | '2/3' | '4/5' | '16/9';
-export type CacheTag = 'gallery' | 'auth' | 'user' | 'settings' | 'statistics' | 'users';
-export type ColumnSortingAlbumType = 'owner_id' | 'created_at' | 'title' | 'description' | 'title_strict' | 'description_strict' | 'min_taken_at' | 'max_taken_at';
-export type ColumnSortingPhotoType = 'owner_id' | 'created_at' | 'title' | 'description' | 'title_strict' | 'description_strict' | 'taken_at' | 'is_highlighted' | 'type' | 'rating_avg';
-export type ColumnSortingType = 'owner_id' | 'created_at' | 'title' | 'description' | 'title_strict' | 'description_strict' | 'min_taken_at' | 'max_taken_at' | 'taken_at' | 'is_highlighted' | 'type' | 'rating_avg';
-export type ConfigType = 'int' | 'positive' | 'string' | 'string_required' | '0|1' | '0|1|2' | '' | 'admin_user' | 'license' | 'map_provider' | 'currency';
-export type CountType = 'taken_at' | 'created_at';
-export type CoverFitType = 'cover' | 'fit';
-export type DateOrderingType = 'older_younger' | 'younger_older';
-export type DbDriverType = 'mysql' | 'pgsql' | 'sqlite';
-export type DefaultAlbumProtectionType = 'private' | 'public' | 'inherit' | 'public_hidden';
-export type DownloadVariantType = 'RAW' | 'LIVEPHOTOVIDEO' | 'ORIGINAL' | 'MEDIUM2X' | 'MEDIUM' | 'SMALL2X' | 'SMALL' | 'THUMB2X' | 'THUMB';
-export type FacePermissionMode = 'public' | 'private' | 'privacy-preserving' | 'restricted';
-export type FaceScanStatus = 'pending' | 'completed' | 'failed';
-export type FileStatus = 'uploading' | 'processing' | 'ready' | 'skipped' | 'done' | 'error';
-export type FlowStrategy = 'auto' | 'opt-in';
-export type ImageOverlayType = 'none' | 'desc' | 'date' | 'exif';
-export type JobStatus = 0 | 1 | 2 | 3;
-export type LandingBackgroundModeType = 'static' | 'photo_id' | 'random' | 'latest_album_cover' | 'random_from_album';
-export type LicenseType = 'none' | 'reserved' | 'CC0' | 'CC-BY-1.0' | 'CC-BY-2.0' | 'CC-BY-2.5' | 'CC-BY-3.0' | 'CC-BY-4.0' | 'CC-BY-ND-1.0' | 'CC-BY-ND-2.0' | 'CC-BY-ND-2.5' | 'CC-BY-ND-3.0' | 'CC-BY-ND-4.0' | 'CC-BY-SA-1.0' | 'CC-BY-SA-2.0' | 'CC-BY-SA-2.5' | 'CC-BY-SA-3.0' | 'CC-BY-SA-4.0' | 'CC-BY-NC-1.0' | 'CC-BY-NC-2.0' | 'CC-BY-NC-2.5' | 'CC-BY-NC-3.0' | 'CC-BY-NC-4.0' | 'CC-BY-NC-ND-1.0' | 'CC-BY-NC-ND-2.0' | 'CC-BY-NC-ND-2.5' | 'CC-BY-NC-ND-3.0' | 'CC-BY-NC-ND-4.0' | 'CC-BY-NC-SA-1.0' | 'CC-BY-NC-SA-2.0' | 'CC-BY-NC-SA-2.5' | 'CC-BY-NC-SA-3.0' | 'CC-BY-NC-SA-4.0';
-export type LiveMetricsAccess = 'logged-in users' | 'admin';
-export type MapProviders = 'Wikimedia' | 'OpenStreetMap.org' | 'OpenStreetMap.de' | 'OpenStreetMap.fr' | 'RRZE';
-export type MessageType = 'info' | 'warning' | 'error';
-export type MetricsAccess = 'public' | 'logged-in users' | 'owner' | 'admin';
-export type MetricsAction = 'visit' | 'favourite' | 'download' | 'shared';
-export type OauthProvidersType = 'amazon' | 'apple' | 'authelia' | 'authentik' | 'facebook' | 'github' | 'google' | 'mastodon' | 'microsoft' | 'nextcloud' | 'keycloak';
-export type OmnipayProviderType = 'Dummy' | 'Mollie' | 'PayPal' | 'Stripe';
-export type OrderSortingType = 'ASC' | 'DESC';
-export type PaginationMode = 'infinite_scroll' | 'load_more_button' | 'page_navigation';
-export type PaymentStatusType = 'pending' | 'cancelled' | 'failed' | 'refunded' | 'processing' | 'offline' | 'completed' | 'closed';
-export type PhotoHighlightVisibilityType = 'anonymous' | 'authenticated' | 'editor';
-export type PhotoLayoutType = 'square' | 'justified' | 'masonry' | 'grid';
-export type PhotoThumbInfoType = 'title' | 'description';
-export type PurchasableLicenseType = 'personal' | 'commercial' | 'extended';
-export type PurchasableSizeVariantType = 'medium' | 'medium2x' | 'original' | 'full';
-export type RenamerModeType = 'first' | 'all' | 'regex' | 'trim' | 'strtolower' | 'strtoupper' | 'ucwords' | 'ucfirst';
-export type SeverityType = 'emergency' | 'alert' | 'critical' | 'error' | 'warning' | 'notice' | 'info' | 'debug';
-export type SharedAlbumsVisibility = 'show' | 'separate' | 'separate_shared_only' | 'hide';
-export type ShiftType = 'relative' | 'absolute';
-export type ShiftX = 'left' | 'right';
-export type ShiftY = 'up' | 'down';
-export type SizeVariantType = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8;
-export type SmallLargeType = 'small' | 'large';
-export type SmartAlbumType = 'unsorted' | 'highlighted' | 'recent' | 'on_this_day' | 'untagged' | 'unrated' | 'one_star' | 'two_stars' | 'three_stars' | 'four_stars' | 'five_stars' | 'best_pictures' | 'my_rated_pictures' | 'my_best_pictures';
-export type StorageDiskType = 'images' | 's3';
-export type ThumbAlbumSubtitleType = 'description' | 'takedate' | 'creation' | 'oldstyle' | 'num_photos' | 'num_albums' | 'num_photos_albums';
-export type TimelineAlbumGranularity = 'default' | 'disabled' | 'year' | 'month' | 'day';
-export type TimelinePhotoGranularity = 'default' | 'disabled' | 'year' | 'month' | 'day' | 'hour';
-export type UpdateStatus = 0 | 1 | 2 | 3;
-export type UserGroupRole = 'member' | 'admin';
-export type UserSharedAlbumsVisibility = 'default' | 'show' | 'separate' | 'separate_shared_only' | 'hide';
-export type VersionChannelType = 'release' | 'git' | 'tag';
-export type VisibilityType = 'never' | 'always' | 'hover';
-export type WatermarkPosition = 'top-left' | 'top' | 'top-right' | 'left' | 'center' | 'right' | 'bottom-left' | 'bottom' | 'bottom-right';
+	export type AlbumDecorationOrientation = "row" | "row-reverse" | "column" | "column-reverse";
+	export type AlbumDecorationType = "none" | "layers" | "album" | "photo" | "all";
+	export type AlbumHeaderSize = "half_screen" | "full_screen";
+	export type AlbumLayoutType = "list" | "grid";
+	export type AlbumTitleColor = "white" | "black" | "colour_1" | "colour_2" | "colour_3" | "colour_4" | "colour_5";
+	export type AlbumTitlePosition = "top_left" | "top_right" | "bottom_left" | "bottom_right" | "center";
+	export type AspectRatioCSSType = "aspect-5x4" | "aspect-4x5" | "aspect-3x2" | "aspect-square" | "aspect-2x3" | "aspect-video";
+	export type AspectRatioType = "5/4" | "3/2" | "1/1" | "2/3" | "4/5" | "16/9";
+	export type CacheTag = "gallery" | "auth" | "user" | "settings" | "statistics" | "users";
+	export type ColumnSortingAlbumType =
+		| "owner_id"
+		| "created_at"
+		| "title"
+		| "description"
+		| "title_strict"
+		| "description_strict"
+		| "min_taken_at"
+		| "max_taken_at";
+	export type ColumnSortingPhotoType =
+		| "owner_id"
+		| "created_at"
+		| "title"
+		| "description"
+		| "title_strict"
+		| "description_strict"
+		| "taken_at"
+		| "is_highlighted"
+		| "type"
+		| "rating_avg";
+	export type ColumnSortingType =
+		| "owner_id"
+		| "created_at"
+		| "title"
+		| "description"
+		| "title_strict"
+		| "description_strict"
+		| "min_taken_at"
+		| "max_taken_at"
+		| "taken_at"
+		| "is_highlighted"
+		| "type"
+		| "rating_avg";
+	export type ConfigType =
+		| "int"
+		| "positive"
+		| "string"
+		| "string_required"
+		| "0|1"
+		| "0|1|2"
+		| ""
+		| "admin_user"
+		| "license"
+		| "map_provider"
+		| "currency";
+	export type CountType = "taken_at" | "created_at";
+	export type CoverFitType = "cover" | "fit";
+	export type DateOrderingType = "older_younger" | "younger_older";
+	export type DbDriverType = "mysql" | "pgsql" | "sqlite";
+	export type DefaultAlbumProtectionType = "private" | "public" | "inherit" | "public_hidden";
+	export type DownloadVariantType = "RAW" | "LIVEPHOTOVIDEO" | "ORIGINAL" | "MEDIUM2X" | "MEDIUM" | "SMALL2X" | "SMALL" | "THUMB2X" | "THUMB";
+	export type FacePermissionMode = "public" | "private" | "privacy-preserving" | "restricted";
+	export type FaceScanStatus = "pending" | "completed" | "failed";
+	export type FileStatus = "uploading" | "processing" | "ready" | "skipped" | "done" | "error";
+	export type FlowStrategy = "auto" | "opt-in";
+	export type ImageOverlayType = "none" | "desc" | "date" | "exif";
+	export type JobStatus = 0 | 1 | 2 | 3;
+	export type LandingBackgroundModeType = "static" | "photo_id" | "random" | "latest_album_cover" | "random_from_album";
+	export type LicenseType =
+		| "none"
+		| "reserved"
+		| "CC0"
+		| "CC-BY-1.0"
+		| "CC-BY-2.0"
+		| "CC-BY-2.5"
+		| "CC-BY-3.0"
+		| "CC-BY-4.0"
+		| "CC-BY-ND-1.0"
+		| "CC-BY-ND-2.0"
+		| "CC-BY-ND-2.5"
+		| "CC-BY-ND-3.0"
+		| "CC-BY-ND-4.0"
+		| "CC-BY-SA-1.0"
+		| "CC-BY-SA-2.0"
+		| "CC-BY-SA-2.5"
+		| "CC-BY-SA-3.0"
+		| "CC-BY-SA-4.0"
+		| "CC-BY-NC-1.0"
+		| "CC-BY-NC-2.0"
+		| "CC-BY-NC-2.5"
+		| "CC-BY-NC-3.0"
+		| "CC-BY-NC-4.0"
+		| "CC-BY-NC-ND-1.0"
+		| "CC-BY-NC-ND-2.0"
+		| "CC-BY-NC-ND-2.5"
+		| "CC-BY-NC-ND-3.0"
+		| "CC-BY-NC-ND-4.0"
+		| "CC-BY-NC-SA-1.0"
+		| "CC-BY-NC-SA-2.0"
+		| "CC-BY-NC-SA-2.5"
+		| "CC-BY-NC-SA-3.0"
+		| "CC-BY-NC-SA-4.0";
+	export type LiveMetricsAccess = "logged-in users" | "admin";
+	export type MapProviders = "Wikimedia" | "OpenStreetMap.org" | "OpenStreetMap.de" | "OpenStreetMap.fr" | "RRZE";
+	export type MessageType = "info" | "warning" | "error";
+	export type MetricsAccess = "public" | "logged-in users" | "owner" | "admin";
+	export type MetricsAction = "visit" | "favourite" | "download" | "shared";
+	export type OauthProvidersType =
+		| "amazon"
+		| "apple"
+		| "authelia"
+		| "authentik"
+		| "facebook"
+		| "github"
+		| "google"
+		| "mastodon"
+		| "microsoft"
+		| "nextcloud"
+		| "keycloak";
+	export type OmnipayProviderType = "Dummy" | "Mollie" | "PayPal" | "Stripe";
+	export type OrderSortingType = "ASC" | "DESC";
+	export type PaginationMode = "infinite_scroll" | "load_more_button" | "page_navigation";
+	export type PaymentStatusType = "pending" | "cancelled" | "failed" | "refunded" | "processing" | "offline" | "completed" | "closed";
+	export type PhotoHighlightVisibilityType = "anonymous" | "authenticated" | "editor";
+	export type PhotoLayoutType = "square" | "justified" | "masonry" | "grid";
+	export type PhotoThumbInfoType = "title" | "description";
+	export type PurchasableLicenseType = "personal" | "commercial" | "extended";
+	export type PurchasableSizeVariantType = "medium" | "medium2x" | "original" | "full";
+	export type RenamerModeType = "first" | "all" | "regex" | "trim" | "strtolower" | "strtoupper" | "ucwords" | "ucfirst";
+	export type SeverityType = "emergency" | "alert" | "critical" | "error" | "warning" | "notice" | "info" | "debug";
+	export type SharedAlbumsVisibility = "show" | "separate" | "separate_shared_only" | "hide";
+	export type ShiftType = "relative" | "absolute";
+	export type ShiftX = "left" | "right";
+	export type ShiftY = "up" | "down";
+	export type SizeVariantType = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8;
+	export type SmallLargeType = "small" | "large";
+	export type SmartAlbumType =
+		| "unsorted"
+		| "highlighted"
+		| "recent"
+		| "on_this_day"
+		| "untagged"
+		| "unrated"
+		| "one_star"
+		| "two_stars"
+		| "three_stars"
+		| "four_stars"
+		| "five_stars"
+		| "best_pictures"
+		| "my_rated_pictures"
+		| "my_best_pictures";
+	export type StorageDiskType = "images" | "s3";
+	export type ThumbAlbumSubtitleType = "description" | "takedate" | "creation" | "oldstyle" | "num_photos" | "num_albums" | "num_photos_albums";
+	export type TimelineAlbumGranularity = "default" | "disabled" | "year" | "month" | "day";
+	export type TimelinePhotoGranularity = "default" | "disabled" | "year" | "month" | "day" | "hour";
+	export type UpdateStatus = 0 | 1 | 2 | 3;
+	export type UserGroupRole = "member" | "admin";
+	export type UserSharedAlbumsVisibility = "default" | "show" | "separate" | "separate_shared_only" | "hide";
+	export type VersionChannelType = "release" | "git" | "tag";
+	export type VisibilityType = "never" | "always" | "hover";
+	export type WatermarkPosition = "top-left" | "top" | "top-right" | "left" | "center" | "right" | "bottom-left" | "bottom" | "bottom-right";
 }
 declare namespace App.Http.Resources.Admin {
-export type ImportDirectoryResource = {
-directory: string;
-status: boolean;
-message: string | null;
-jobs_count: number | null;
-};
-export type ImportFromServerOptionsResource = {
-delete_imported: boolean;
-import_via_symlink: boolean;
-skip_duplicates: boolean;
-resync_metadata: boolean;
-delete_missing_photos: boolean;
-delete_missing_albums: boolean;
-directory: string;
-};
-export type ImportFromServerResource = {
-status: boolean;
-message: string;
-results: App.Http.Resources.Admin.ImportDirectoryResource[];
-job_count: number;
-};
+	export type ImportDirectoryResource = {
+		directory: string;
+		status: boolean;
+		message: string | null;
+		jobs_count: number | null;
+	};
+	export type ImportFromServerOptionsResource = {
+		delete_imported: boolean;
+		import_via_symlink: boolean;
+		skip_duplicates: boolean;
+		resync_metadata: boolean;
+		delete_missing_photos: boolean;
+		delete_missing_albums: boolean;
+		directory: string;
+	};
+	export type ImportFromServerResource = {
+		status: boolean;
+		message: string;
+		results: App.Http.Resources.Admin.ImportDirectoryResource[];
+		job_count: number;
+	};
 }
 declare namespace App.Http.Resources.Collections {
-export type ContactMessageCollectionResource = {
-data: App.Http.Resources.Models.ContactMessageResource[];
-current_page: number;
-per_page: number;
-total: number;
-};
-export type PaginatedAlbumsResource = {
-data: App.Http.Resources.Models.ThumbAlbumResource[];
-current_page: number;
-last_page: number;
-per_page: number;
-total: number;
-};
-export type PaginatedPhotosResource = {
-photos: App.Http.Resources.Models.PhotoResource[];
-current_page: number;
-last_page: number;
-per_page: number;
-total: number;
-};
-export type PositionDataResource = {
-id: string | null;
-title: string | null;
-track_url: string | null;
-photos: App.Http.Resources.Models.PhotoResource[];
-};
-export type RootAlbumResource = {
-smart_albums: App.Http.Resources.Models.ThumbAlbumResource[];
-tag_albums: App.Http.Resources.Models.ThumbAlbumResource[];
-pinned_albums: App.Http.Resources.Models.ThumbAlbumResource[];
-albums: App.Http.Resources.Models.ThumbAlbumResource[];
-shared_albums: App.Http.Resources.Models.ThumbAlbumResource[];
-config: App.Http.Resources.GalleryConfigs.RootConfig;
-rights: App.Http.Resources.Rights.RootAlbumRightsResource;
-};
-export type UserGroupDataResource = {
-user_groups: App.Http.Resources.Models.UserGroupResource[];
-can_create_delete_user_groups: boolean;
-};
+	export type ContactMessageCollectionResource = {
+		data: App.Http.Resources.Models.ContactMessageResource[];
+		current_page: number;
+		per_page: number;
+		total: number;
+	};
+	export type PaginatedAlbumsResource = {
+		data: App.Http.Resources.Models.ThumbAlbumResource[];
+		current_page: number;
+		last_page: number;
+		per_page: number;
+		total: number;
+	};
+	export type PaginatedPhotosResource = {
+		photos: App.Http.Resources.Models.PhotoResource[];
+		current_page: number;
+		last_page: number;
+		per_page: number;
+		total: number;
+	};
+	export type PositionDataResource = {
+		id: string | null;
+		title: string | null;
+		track_url: string | null;
+		photos: App.Http.Resources.Models.PhotoResource[];
+	};
+	export type RootAlbumResource = {
+		smart_albums: App.Http.Resources.Models.ThumbAlbumResource[];
+		tag_albums: App.Http.Resources.Models.ThumbAlbumResource[];
+		pinned_albums: App.Http.Resources.Models.ThumbAlbumResource[];
+		albums: App.Http.Resources.Models.ThumbAlbumResource[];
+		shared_albums: App.Http.Resources.Models.ThumbAlbumResource[];
+		config: App.Http.Resources.GalleryConfigs.RootConfig;
+		rights: App.Http.Resources.Rights.RootAlbumRightsResource;
+	};
+	export type UserGroupDataResource = {
+		user_groups: App.Http.Resources.Models.UserGroupResource[];
+		can_create_delete_user_groups: boolean;
+	};
 }
 declare namespace App.Http.Resources.Diagnostics {
-export type AlbumTree = {
-id: string;
-title: string;
-parent_id: string | null;
-_lft: number;
-_rgt: number;
-};
-export type ChangeLogInfo = {
-version: string;
-date: string;
-changes: string;
-};
-export type CleaningState = {
-path: string;
-base: string;
-is_not_empty: boolean;
-};
-export type ErrorLine = {
-type: App.Enum.MessageType;
-message: string;
-from: string;
-details: string[];
-};
-export type Permissions = {
-left: string;
-right: string;
-};
-export type StatisticsCheckResource = {
-missing_photos: number;
-missing_albums: number;
-};
-export type TreeState = {
-oddness: number;
-duplicates: number;
-wrong_parent: number;
-missing_parent: number;
-};
-export type UpdateCheckInfo = {
-extra: string;
-can_update: boolean;
-};
-export type UpdateInfo = {
-info: string;
-extra: string;
-channel_name: App.Enum.VersionChannelType;
-is_docker: boolean;
-};
+	export type AlbumTree = {
+		id: string;
+		title: string;
+		parent_id: string | null;
+		_lft: number;
+		_rgt: number;
+	};
+	export type ChangeLogInfo = {
+		version: string;
+		date: string;
+		changes: string;
+	};
+	export type CleaningState = {
+		path: string;
+		base: string;
+		is_not_empty: boolean;
+	};
+	export type ErrorLine = {
+		type: App.Enum.MessageType;
+		message: string;
+		from: string;
+		details: string[];
+	};
+	export type Permissions = {
+		left: string;
+		right: string;
+	};
+	export type StatisticsCheckResource = {
+		missing_photos: number;
+		missing_albums: number;
+	};
+	export type TreeState = {
+		oddness: number;
+		duplicates: number;
+		wrong_parent: number;
+		missing_parent: number;
+	};
+	export type UpdateCheckInfo = {
+		extra: string;
+		can_update: boolean;
+	};
+	export type UpdateInfo = {
+		info: string;
+		extra: string;
+		channel_name: App.Enum.VersionChannelType;
+		is_docker: boolean;
+	};
 }
 declare namespace App.Http.Resources.Editable {
-export type EditableBaseAlbumResource = {
-id: string;
-title: string;
-slug: string | null;
-description: string | null;
-copyright: string | null;
-license: App.Enum.LicenseType | null;
-photo_sorting: App.DTO.PhotoSortingCriterion | null;
-album_sorting: App.DTO.AlbumSortingCriterion | null;
-aspect_ratio: App.Enum.AspectRatioType | null;
-photo_layout: App.Enum.PhotoLayoutType | null;
-header_id: string | null;
-cover_id: string | null;
-album_timeline: App.Enum.TimelineAlbumGranularity | null;
-photo_timeline: App.Enum.TimelinePhotoGranularity | null;
-tags: Array<string>;
-is_and: boolean;
-is_model_album: boolean;
-is_pinned: boolean;
-};
-export type EditableConfigResource = {
-key: string;
-value: string | null;
-};
-export type UploadMetaResource = {
-file_name: string;
-extension: string | null;
-uuid_name: string | null;
-stage: App.Enum.FileStatus;
-chunk_number: number;
-total_chunks: number;
-};
+	export type EditableBaseAlbumResource = {
+		id: string;
+		title: string;
+		slug: string | null;
+		description: string | null;
+		copyright: string | null;
+		license: App.Enum.LicenseType | null;
+		photo_sorting: App.DTO.PhotoSortingCriterion | null;
+		album_sorting: App.DTO.AlbumSortingCriterion | null;
+		aspect_ratio: App.Enum.AspectRatioType | null;
+		photo_layout: App.Enum.PhotoLayoutType | null;
+		header_id: string | null;
+		cover_id: string | null;
+		album_timeline: App.Enum.TimelineAlbumGranularity | null;
+		photo_timeline: App.Enum.TimelinePhotoGranularity | null;
+		tags: Array<string>;
+		is_and: boolean;
+		is_model_album: boolean;
+		is_pinned: boolean;
+	};
+	export type EditableConfigResource = {
+		key: string;
+		value: string | null;
+	};
+	export type UploadMetaResource = {
+		file_name: string;
+		extension: string | null;
+		uuid_name: string | null;
+		stage: App.Enum.FileStatus;
+		chunk_number: number;
+		total_chunks: number;
+	};
 }
 declare namespace App.Http.Resources.Embed {
-export type EmbedAlbumInfo = {
-id: string;
-title: string;
-description: string | null;
-photo_count: number;
-copyright: string | null;
-license: string | null;
-};
-export type EmbedAlbumResource = {
-album: App.Http.Resources.Embed.EmbedAlbumInfo;
-photos: App.Http.Resources.Embed.EmbedPhotoResource[];
-};
-export type EmbedPhotoResource = {
-id: string;
-title: string | null;
-description: string | null;
-is_video: boolean;
-duration: string | null;
-size_variants: App.Http.Resources.Models.SizeVariantsResouce;
-exif: { [key: string]: string | null };
-};
-export type EmbedStreamResource = {
-site_title: string;
-photos: App.Http.Resources.Embed.EmbedPhotoResource[];
-};
+	export type EmbedAlbumInfo = {
+		id: string;
+		title: string;
+		description: string | null;
+		photo_count: number;
+		copyright: string | null;
+		license: string | null;
+	};
+	export type EmbedAlbumResource = {
+		album: App.Http.Resources.Embed.EmbedAlbumInfo;
+		photos: App.Http.Resources.Embed.EmbedPhotoResource[];
+	};
+	export type EmbedPhotoResource = {
+		id: string;
+		title: string | null;
+		description: string | null;
+		is_video: boolean;
+		duration: string | null;
+		size_variants: App.Http.Resources.Models.SizeVariantsResouce;
+		exif: { [key: string]: string | null };
+	};
+	export type EmbedStreamResource = {
+		site_title: string;
+		photos: App.Http.Resources.Embed.EmbedPhotoResource[];
+	};
 }
 declare namespace App.Http.Resources.Flow {
-export type FlowItemResource = {
-id: string;
-title: string;
-description: string | null;
-min_max_text: string | null;
-published_created_at: string;
-diff_published_created_at: string;
-owner_name: string | null;
-is_nsfw: boolean;
-num_photos: number;
-num_children: number;
-cover: App.Http.Resources.Models.SizeVariantsResouce | null;
-photos: App.Http.Resources.Models.PhotoResource[];
-statistics: App.Http.Resources.Models.AlbumStatisticsResource | null;
-};
-export type FlowResource = {
-albums: App.Http.Resources.Flow.FlowItemResource[];
-current_page: number;
-from: number;
-last_page: number;
-per_page: number;
-to: number;
-total: number;
-};
-export type InitResource = {
-is_mod_flow_enabled: boolean;
-is_open_album_on_click: boolean;
-is_display_open_album_button: boolean;
-is_highlight_first_picture: boolean;
-is_image_header_enabled: boolean;
-image_header_cover: App.Enum.CoverFitType;
-image_header_height: number;
-is_carousel_enabled: boolean;
-carousel_height: number;
-is_blur_nsfw_enabled: boolean;
-is_compact_mode_enabled: boolean;
-};
+	export type FlowItemResource = {
+		id: string;
+		title: string;
+		description: string | null;
+		min_max_text: string | null;
+		published_created_at: string;
+		diff_published_created_at: string;
+		owner_name: string | null;
+		is_nsfw: boolean;
+		num_photos: number;
+		num_children: number;
+		cover: App.Http.Resources.Models.SizeVariantsResouce | null;
+		photos: App.Http.Resources.Models.PhotoResource[];
+		statistics: App.Http.Resources.Models.AlbumStatisticsResource | null;
+	};
+	export type FlowResource = {
+		albums: App.Http.Resources.Flow.FlowItemResource[];
+		current_page: number;
+		from: number;
+		last_page: number;
+		per_page: number;
+		to: number;
+		total: number;
+	};
+	export type InitResource = {
+		is_mod_flow_enabled: boolean;
+		is_open_album_on_click: boolean;
+		is_display_open_album_button: boolean;
+		is_highlight_first_picture: boolean;
+		is_image_header_enabled: boolean;
+		image_header_cover: App.Enum.CoverFitType;
+		image_header_height: number;
+		is_carousel_enabled: boolean;
+		carousel_height: number;
+		is_blur_nsfw_enabled: boolean;
+		is_compact_mode_enabled: boolean;
+	};
 }
 declare namespace App.Http.Resources.Frame {
-export type FrameData = {
-timeout: number;
-src: string;
-srcset: string;
-};
+	export type FrameData = {
+		timeout: number;
+		src: string;
+		srcset: string;
+	};
 }
 declare namespace App.Http.Resources.GalleryConfigs {
-export type AlbumConfig = {
-is_base_album: boolean;
-is_model_album: boolean;
-is_password_protected: boolean;
-is_map_accessible: boolean;
-is_mod_frame_enabled: boolean;
-is_search_accessible: boolean;
-is_nsfw_warning_visible: boolean;
-album_thumb_css_aspect_ratio: App.Enum.AspectRatioCSSType;
-photo_layout: App.Enum.PhotoLayoutType;
-is_album_timeline_enabled: boolean;
-is_photo_timeline_enabled: boolean;
-};
-export type ContactConfig = {
-is_contact_form_enabled: boolean;
-security_question: string;
-is_consent_required: boolean;
-header: string;
-headline: string;
-consent_text: string;
-privacy_policy_url: string;
-submit_button_text: string;
-contact_method: string;
-message_label: string;
-message_answer: string;
-thank_you_message: string;
-};
-export type FooterConfig = {
-footer_additional_text: string;
-footer_show_copyright: boolean;
-footer_show_social_media: boolean;
-copyright: string;
-sm_facebook_url: string;
-sm_flickr_url: string;
-sm_instagram_url: string;
-sm_twitter_url: string;
-sm_youtube_url: string;
-is_contact_form_enabled: boolean;
-contact_header: string;
-};
-export type InitConfig = {
-is_debug_enabled: boolean;
-are_nsfw_visible: boolean;
-is_nsfw_background_blurred: boolean;
-nsfw_banner_override: string;
-is_nsfw_banner_backdrop_blurred: boolean;
-show_keybinding_help_popup: boolean;
-image_overlay_type: App.Enum.ImageOverlayType;
-can_rotate: boolean;
-can_autoplay: boolean;
-is_exif_disabled: boolean;
-is_favourite_enabled: boolean;
-photo_previous_next_size: App.Enum.SmallLargeType;
-is_details_links_enabled: boolean;
-is_desktop_dock_full_transparency_enabled: boolean;
-is_mobile_dock_full_transparency_enabled: boolean;
-is_photo_details_always_open: boolean;
-display_thumb_album_overlay: App.Enum.VisibilityType;
-display_thumb_photo_overlay: App.Enum.VisibilityType;
-album_subtitle_type: App.Enum.ThumbAlbumSubtitleType;
-album_decoration: App.Enum.AlbumDecorationType;
-album_decoration_orientation: App.Enum.AlbumDecorationOrientation;
-number_albums_per_row_mobile: 1|2|3;
-photo_thumb_info: App.Enum.PhotoThumbInfoType;
-is_photo_thumb_tags_enabled: boolean;
-album_layout: App.Enum.AlbumLayoutType;
-is_raw_download_enabled: boolean;
-is_thumb_download_enabled: boolean;
-is_thum2x_download_enabled: boolean;
-is_small_download_enabled: boolean;
-is_small2x_download_enabled: boolean;
-is_medium_download_enabled: boolean;
-is_medium2x_download_enabled: boolean;
-clockwork_url: string | null;
-slideshow_timeout: number;
-is_slideshow_enabled: boolean;
-is_timeline_left_border_visible: boolean;
-title: string;
-dropbox_api_key: string;
-is_se_enabled: boolean;
-is_pro_enabled: boolean;
-is_se_preview_enabled: boolean;
-is_se_info_hidden: boolean;
-is_se_expired: boolean;
-is_live_metrics_enabled: boolean;
-is_basic_auth_enabled: boolean;
-is_webauthn_enabled: boolean;
-is_registration_enabled: boolean;
-is_scroll_to_navigate_photos_enabled: boolean;
-is_swipe_vertically_to_go_back_enabled: boolean;
-is_rating_show_avg_in_details_enabled: boolean;
-is_rating_show_avg_in_photo_view_enabled: boolean;
-rating_photo_view_mode: App.Enum.VisibilityType;
-is_rating_show_avg_in_album_view_enabled: boolean;
-rating_album_view_mode: App.Enum.VisibilityType;
-default_homepage: string;
-is_timeline_page_enabled: boolean;
-is_contact_form_enabled: boolean;
-photos_pagination_mode: App.Enum.PaginationMode;
-albums_pagination_mode: App.Enum.PaginationMode;
-photos_per_page: number;
-albums_per_page: number;
-photos_infinite_scroll_threshold: number;
-albums_infinite_scroll_threshold: number;
-default_album_protection: App.Enum.DefaultAlbumProtectionType;
-photos_star_visibility: App.Enum.PhotoHighlightVisibilityType;
-is_album_enhanced_display_enabled: boolean;
-album_header_size: App.Enum.AlbumHeaderSize;
-is_album_header_landing_title_enabled: boolean;
-};
-export type LandingPageResource = {
-landing_page_enable: boolean;
-landing_background_landscape: string;
-landing_background_portrait: string;
-landing_subtitle: string;
-landing_title: string;
-site_owner: string;
-site_title: string;
-footer: App.Http.Resources.GalleryConfigs.FooterConfig;
-};
-export type MapProviderData = {
-layer: string;
-attribution: string;
-};
-export type PhotoLayoutConfig = {
-photo_layout_justified_row_height: number;
-photo_layout_masonry_column_width: number;
-photo_layout_grid_column_width: number;
-photo_layout_square_column_width: number;
-photo_layout_gap: number;
-};
-export type RegisterData = {
-success: boolean;
-};
-export type RootConfig = {
-is_album_timeline_enabled: boolean;
-is_search_accessible: boolean;
-show_keybinding_help_button: boolean;
-album_thumb_css_aspect_ratio: App.Enum.AspectRatioType;
-back_button_enabled: boolean;
-back_button_text: string;
-back_button_url: string;
-timeline_album_granularity: App.Enum.TimelineAlbumGranularity;
-header_image_url: string;
-is_header_bar_transparent: boolean;
-is_header_bar_gradient: boolean;
-shared_albums_visibility_mode: App.Enum.SharedAlbumsVisibility;
-};
-export type SettingsConfig = {
-default_old_settings: boolean;
-default_expert_settings: boolean;
-default_all_settings: boolean;
-};
-export type UploadConfig = {
-upload_processing_limit: number;
-upload_chunk_size: number;
-can_watermark_optout: boolean;
-};
+	export type AlbumConfig = {
+		is_base_album: boolean;
+		is_model_album: boolean;
+		is_password_protected: boolean;
+		is_map_accessible: boolean;
+		is_mod_frame_enabled: boolean;
+		is_search_accessible: boolean;
+		is_nsfw_warning_visible: boolean;
+		album_thumb_css_aspect_ratio: App.Enum.AspectRatioCSSType;
+		photo_layout: App.Enum.PhotoLayoutType;
+		is_album_timeline_enabled: boolean;
+		is_photo_timeline_enabled: boolean;
+	};
+	export type ContactConfig = {
+		is_contact_form_enabled: boolean;
+		security_question: string;
+		is_consent_required: boolean;
+		header: string;
+		headline: string;
+		consent_text: string;
+		privacy_policy_url: string;
+		submit_button_text: string;
+		contact_method: string;
+		message_label: string;
+		message_answer: string;
+		thank_you_message: string;
+	};
+	export type FooterConfig = {
+		footer_additional_text: string;
+		footer_show_copyright: boolean;
+		footer_show_social_media: boolean;
+		copyright: string;
+		sm_facebook_url: string;
+		sm_flickr_url: string;
+		sm_instagram_url: string;
+		sm_twitter_url: string;
+		sm_youtube_url: string;
+		is_contact_form_enabled: boolean;
+		contact_header: string;
+	};
+	export type InitConfig = {
+		is_debug_enabled: boolean;
+		are_nsfw_visible: boolean;
+		is_nsfw_background_blurred: boolean;
+		nsfw_banner_override: string;
+		is_nsfw_banner_backdrop_blurred: boolean;
+		show_keybinding_help_popup: boolean;
+		image_overlay_type: App.Enum.ImageOverlayType;
+		can_rotate: boolean;
+		can_autoplay: boolean;
+		is_exif_disabled: boolean;
+		is_favourite_enabled: boolean;
+		photo_previous_next_size: App.Enum.SmallLargeType;
+		is_details_links_enabled: boolean;
+		is_desktop_dock_full_transparency_enabled: boolean;
+		is_mobile_dock_full_transparency_enabled: boolean;
+		is_photo_details_always_open: boolean;
+		display_thumb_album_overlay: App.Enum.VisibilityType;
+		display_thumb_photo_overlay: App.Enum.VisibilityType;
+		album_subtitle_type: App.Enum.ThumbAlbumSubtitleType;
+		album_decoration: App.Enum.AlbumDecorationType;
+		album_decoration_orientation: App.Enum.AlbumDecorationOrientation;
+		number_albums_per_row_mobile: 1 | 2 | 3;
+		photo_thumb_info: App.Enum.PhotoThumbInfoType;
+		is_photo_thumb_tags_enabled: boolean;
+		album_layout: App.Enum.AlbumLayoutType;
+		is_raw_download_enabled: boolean;
+		is_thumb_download_enabled: boolean;
+		is_thum2x_download_enabled: boolean;
+		is_small_download_enabled: boolean;
+		is_small2x_download_enabled: boolean;
+		is_medium_download_enabled: boolean;
+		is_medium2x_download_enabled: boolean;
+		clockwork_url: string | null;
+		slideshow_timeout: number;
+		is_slideshow_enabled: boolean;
+		is_timeline_left_border_visible: boolean;
+		title: string;
+		dropbox_api_key: string;
+		is_se_enabled: boolean;
+		is_pro_enabled: boolean;
+		is_se_preview_enabled: boolean;
+		is_se_info_hidden: boolean;
+		is_se_expired: boolean;
+		is_live_metrics_enabled: boolean;
+		is_basic_auth_enabled: boolean;
+		is_webauthn_enabled: boolean;
+		is_registration_enabled: boolean;
+		is_scroll_to_navigate_photos_enabled: boolean;
+		is_swipe_vertically_to_go_back_enabled: boolean;
+		is_rating_show_avg_in_details_enabled: boolean;
+		is_rating_show_avg_in_photo_view_enabled: boolean;
+		rating_photo_view_mode: App.Enum.VisibilityType;
+		is_rating_show_avg_in_album_view_enabled: boolean;
+		rating_album_view_mode: App.Enum.VisibilityType;
+		default_homepage: string;
+		is_timeline_page_enabled: boolean;
+		is_contact_form_enabled: boolean;
+		photos_pagination_mode: App.Enum.PaginationMode;
+		albums_pagination_mode: App.Enum.PaginationMode;
+		photos_per_page: number;
+		albums_per_page: number;
+		photos_infinite_scroll_threshold: number;
+		albums_infinite_scroll_threshold: number;
+		default_album_protection: App.Enum.DefaultAlbumProtectionType;
+		photos_star_visibility: App.Enum.PhotoHighlightVisibilityType;
+		is_album_enhanced_display_enabled: boolean;
+		album_header_size: App.Enum.AlbumHeaderSize;
+		is_album_header_landing_title_enabled: boolean;
+	};
+	export type LandingPageResource = {
+		landing_page_enable: boolean;
+		landing_background_landscape: string;
+		landing_background_portrait: string;
+		landing_subtitle: string;
+		landing_title: string;
+		site_owner: string;
+		site_title: string;
+		footer: App.Http.Resources.GalleryConfigs.FooterConfig;
+	};
+	export type MapProviderData = {
+		layer: string;
+		attribution: string;
+	};
+	export type PhotoLayoutConfig = {
+		photo_layout_justified_row_height: number;
+		photo_layout_masonry_column_width: number;
+		photo_layout_grid_column_width: number;
+		photo_layout_square_column_width: number;
+		photo_layout_gap: number;
+	};
+	export type RegisterData = {
+		success: boolean;
+	};
+	export type RootConfig = {
+		is_album_timeline_enabled: boolean;
+		is_search_accessible: boolean;
+		show_keybinding_help_button: boolean;
+		album_thumb_css_aspect_ratio: App.Enum.AspectRatioType;
+		back_button_enabled: boolean;
+		back_button_text: string;
+		back_button_url: string;
+		timeline_album_granularity: App.Enum.TimelineAlbumGranularity;
+		header_image_url: string;
+		is_header_bar_transparent: boolean;
+		is_header_bar_gradient: boolean;
+		shared_albums_visibility_mode: App.Enum.SharedAlbumsVisibility;
+	};
+	export type SettingsConfig = {
+		default_old_settings: boolean;
+		default_expert_settings: boolean;
+		default_all_settings: boolean;
+	};
+	export type UploadConfig = {
+		upload_processing_limit: number;
+		upload_chunk_size: number;
+		can_watermark_optout: boolean;
+	};
 }
 declare namespace App.Http.Resources.Models {
-export type AccessPermissionResource = {
-id: number | null;
-user_id: number | null;
-user_group_id: number | null;
-username: string | null;
-user_group_name: string | null;
-album_title: string | null;
-album_id: string | null;
-grants_full_photo_access: boolean;
-grants_download: boolean;
-grants_upload: boolean;
-grants_edit: boolean;
-grants_delete: boolean;
-};
-export type AlbumStatisticsResource = {
-visit_count: number;
-download_count: number;
-shared_count: number;
-};
-export type ColourPaletteResource = {
-colour_1: string;
-colour_2: string;
-colour_3: string;
-colour_4: string;
-colour_5: string;
-};
-export type ConfigCategoryResource = {
-cat: string;
-name: string;
-description: string;
-configs: App.Http.Resources.Models.ConfigResource[];
-priority: number;
-};
-export type ConfigResource = {
-key: string;
-type: App.Enum.ConfigType | string;
-value: string;
-documentation: string;
-details: string;
-is_expert: boolean;
-require_se: boolean;
-order: number | null;
-};
-export type ContactMessageResource = {
-id: number;
-name: string;
-email: string;
-message: string;
-is_read: boolean;
-created_at: string;
-};
-export type FaceResource = {
-id: string;
-photo_id: string;
-person_id: string | null;
-x: number;
-y: number;
-width: number;
-height: number;
-confidence: number;
-is_dismissed: boolean;
-crop_url: string | null;
-person_name: string | null;
-suggestions: Array<App.Http.Resources.Models.FaceSuggestionResource>;
-};
-export type FaceSuggestionResource = {
-suggested_face_id: string;
-crop_url: string | null;
-person_name: string | null;
-confidence: number;
-};
-export type HeadAbstractAlbumResource = {
-config: App.Http.Resources.GalleryConfigs.AlbumConfig;
-resource: App.Http.Resources.Models.HeadAlbumResource | App.Http.Resources.Models.HeadSmartAlbumResource | App.Http.Resources.Models.HeadTagAlbumResource;
-};
-export type HeadAlbumResource = {
-id: string;
-title: string;
-slug: string | null;
-owner_name: string | null;
-description: string | null;
-copyright: string | null;
-track_url: string | null;
-license: string;
-header_id: string | null;
-parent_id: string | null;
-has_albums: boolean;
-num_children: number;
-num_photos: number;
-cover_id: string | null;
-policy: App.Http.Resources.Models.Utils.AlbumProtectionPolicy;
-rights: App.Http.Resources.Rights.AlbumRightsResource;
-preFormattedData: App.Http.Resources.Models.Utils.PreFormattedAlbumData;
-editable: App.Http.Resources.Editable.EditableBaseAlbumResource | null;
-is_pinned: boolean;
-statistics: App.Http.Resources.Models.AlbumStatisticsResource | null;
-};
-export type HeadSmartAlbumResource = {
-id: string;
-title: string;
-policy: App.Http.Resources.Models.Utils.AlbumProtectionPolicy;
-rights: App.Http.Resources.Rights.AlbumRightsResource;
-preFormattedData: App.Http.Resources.Models.Utils.PreFormattedAlbumData;
-statistics: null | null;
-};
-export type HeadTagAlbumResource = {
-id: string;
-title: string;
-slug: string | null;
-owner_name: string | null;
-copyright: string | null;
-is_tag_album: boolean;
-show_tags: Array<string>;
-policy: App.Http.Resources.Models.Utils.AlbumProtectionPolicy;
-rights: App.Http.Resources.Rights.AlbumRightsResource;
-preFormattedData: App.Http.Resources.Models.Utils.PreFormattedAlbumData;
-editable: App.Http.Resources.Editable.EditableBaseAlbumResource | null;
-statistics: App.Http.Resources.Models.AlbumStatisticsResource | null;
-};
-export type JobHistoryResource = {
-username: string;
-status: 'ready'|'success'|'failure'|'started';
-created_at: string;
-updated_at: string;
-job: string;
-};
-export type LightUserResource = {
-id: number;
-username: string;
-};
-export type LiveMetricsResource = {
-created_at: string;
-visitor_id: string;
-action: App.Enum.MetricsAction;
-photo_id: string | null;
-album_id: string;
-title: string;
-url: string | null;
-};
-export type PersonResource = {
-id: string;
-name: string;
-user_id: number | null;
-is_searchable: boolean;
-face_count: number;
-photo_count: number;
-representative_crop_url: string | null;
-};
-export type PhotoAlbumResource = {
-id: string;
-title: string;
-};
-export type PhotoRatingResource = {
-rating_user: number;
-rating_count: number;
-rating_avg: number;
-};
-export type PhotoResource = {
-id: string;
-album_id: string | null;
-checksum: string;
-created_at: string;
-description: string;
-is_highlighted: boolean;
-license: App.Enum.LicenseType;
-live_photo_checksum: string | null;
-live_photo_content_id: string | null;
-live_photo_url: string | null;
-original_checksum: string;
-size_variants: App.Http.Resources.Models.SizeVariantsResouce;
-tags: Array<string>;
-taken_at: string | null;
-taken_at_orig_tz: string | null;
-title: string;
-type: string;
-updated_at: string;
-next_photo_id: string | null;
-previous_photo_id: string | null;
-preformatted: App.Http.Resources.Models.Utils.PreformattedPhotoData;
-precomputed: App.Http.Resources.Models.Utils.PreComputedPhotoData;
-timeline: App.Http.Resources.Models.Utils.TimelineData | null;
-palette: App.Http.Resources.Models.ColourPaletteResource | null;
-statistics: App.Http.Resources.Models.PhotoStatisticsResource | null;
-rating: App.Http.Resources.Models.PhotoRatingResource | null;
-faces: Array<App.Http.Resources.Models.FaceResource>;
-hidden_face_count: number;
-};
-export type PhotoStatisticsResource = {
-visit_count: number;
-download_count: number;
-favourite_count: number;
-shared_count: number;
-rating_count: number;
-rating_avg: number | null;
-};
-export type RenamerPreviewResource = {
-id: string;
-original: string;
-new: string;
-};
-export type RenamerRuleResource = {
-id: number;
-order: number;
-owner_id: number;
-rule: string;
-description: string;
-needle: string;
-replacement: string;
-mode: App.Enum.RenamerModeType;
-is_enabled: boolean;
-is_photo_rule: boolean;
-is_album_rule: boolean;
-};
-export type SizeVariantResource = {
-type: App.Enum.SizeVariantType;
-locale: string;
-filesize: string;
-height: number;
-width: number;
-url: string | null;
-is_watermarked: boolean;
-};
-export type SizeVariantsResouce = {
-raw: App.Http.Resources.Models.SizeVariantResource | null;
-original: App.Http.Resources.Models.SizeVariantResource | null;
-medium2x: App.Http.Resources.Models.SizeVariantResource | null;
-medium: App.Http.Resources.Models.SizeVariantResource | null;
-small2x: App.Http.Resources.Models.SizeVariantResource | null;
-small: App.Http.Resources.Models.SizeVariantResource | null;
-thumb2x: App.Http.Resources.Models.SizeVariantResource | null;
-thumb: App.Http.Resources.Models.SizeVariantResource | null;
-placeholder: App.Http.Resources.Models.SizeVariantResource | null;
-};
-export type TargetAlbumResource = {
-id: string | null;
-title: string;
-original: string;
-short_title: string;
-thumb: string;
-};
-export type ThumbAlbumResource = {
-id: string;
-title: string;
-description: string | null;
-thumb: App.Http.Resources.Models.ThumbResource | null;
-is_nsfw: boolean;
-is_pinned: boolean;
-is_public: boolean;
-is_link_required: boolean;
-is_password_required: boolean;
-is_tag_album: boolean;
-has_subalbum: boolean;
-num_subalbums: number;
-num_photos: number;
-created_at: string;
-formatted_min_max: string | null;
-owner: string | null;
-rights: App.Http.Resources.Rights.AlbumRightsResource;
-timeline: App.Http.Resources.Models.Utils.TimelineData | null;
-};
-export type ThumbResource = {
-id: string;
-type: string;
-thumb: string | null;
-thumb2x: string | null;
-placeholder: string | null;
-};
-export type UserGroupResource = {
-id: number;
-name: string;
-description: string;
-members: App.Http.Resources.Models.UserMemberGroupResource[];
-rights: App.Http.Resources.Rights.UserGroupRightResource;
-};
-export type UserManagementResource = {
-id: number;
-username: string;
-may_administrate: boolean;
-may_upload: boolean;
-may_edit_own_settings: boolean;
-is_owner: boolean;
-quota_kb: number | null;
-description: string | null;
-note: string | null;
-space: number | null;
-};
-export type UserMemberGroupResource = {
-id: number;
-username: string;
-role: App.Enum.UserGroupRole;
-};
-export type UserResource = {
-id: number | null;
-has_token: boolean | null;
-username: string | null;
-email: string | null;
-is_ldap: boolean;
-shared_albums_visibility: App.Enum.UserSharedAlbumsVisibility;
-};
-export type WebAuthnResource = {
-id: string;
-alias: string | null;
-created_at: string;
-};
+	export type AccessPermissionResource = {
+		id: number | null;
+		user_id: number | null;
+		user_group_id: number | null;
+		username: string | null;
+		user_group_name: string | null;
+		album_title: string | null;
+		album_id: string | null;
+		grants_full_photo_access: boolean;
+		grants_download: boolean;
+		grants_upload: boolean;
+		grants_edit: boolean;
+		grants_delete: boolean;
+	};
+	export type AlbumStatisticsResource = {
+		visit_count: number;
+		download_count: number;
+		shared_count: number;
+	};
+	export type ColourPaletteResource = {
+		colour_1: string;
+		colour_2: string;
+		colour_3: string;
+		colour_4: string;
+		colour_5: string;
+	};
+	export type ConfigCategoryResource = {
+		cat: string;
+		name: string;
+		description: string;
+		configs: App.Http.Resources.Models.ConfigResource[];
+		priority: number;
+	};
+	export type ConfigResource = {
+		key: string;
+		type: App.Enum.ConfigType | string;
+		value: string;
+		documentation: string;
+		details: string;
+		is_expert: boolean;
+		require_se: boolean;
+		order: number | null;
+	};
+	export type ContactMessageResource = {
+		id: number;
+		name: string;
+		email: string;
+		message: string;
+		is_read: boolean;
+		created_at: string;
+	};
+	export type FaceResource = {
+		id: string;
+		photo_id: string;
+		person_id: string | null;
+		x: number;
+		y: number;
+		width: number;
+		height: number;
+		confidence: number;
+		is_dismissed: boolean;
+		crop_url: string | null;
+		person_name: string | null;
+		suggestions: Array<App.Http.Resources.Models.FaceSuggestionResource>;
+	};
+	export type FaceSuggestionResource = {
+		suggested_face_id: string;
+		crop_url: string | null;
+		person_name: string | null;
+		confidence: number;
+	};
+	export type HeadAbstractAlbumResource = {
+		config: App.Http.Resources.GalleryConfigs.AlbumConfig;
+		resource:
+			| App.Http.Resources.Models.HeadAlbumResource
+			| App.Http.Resources.Models.HeadSmartAlbumResource
+			| App.Http.Resources.Models.HeadTagAlbumResource;
+	};
+	export type HeadAlbumResource = {
+		id: string;
+		title: string;
+		slug: string | null;
+		owner_name: string | null;
+		description: string | null;
+		copyright: string | null;
+		track_url: string | null;
+		license: string;
+		header_id: string | null;
+		parent_id: string | null;
+		has_albums: boolean;
+		num_children: number;
+		num_photos: number;
+		cover_id: string | null;
+		policy: App.Http.Resources.Models.Utils.AlbumProtectionPolicy;
+		rights: App.Http.Resources.Rights.AlbumRightsResource;
+		preFormattedData: App.Http.Resources.Models.Utils.PreFormattedAlbumData;
+		editable: App.Http.Resources.Editable.EditableBaseAlbumResource | null;
+		is_pinned: boolean;
+		statistics: App.Http.Resources.Models.AlbumStatisticsResource | null;
+	};
+	export type HeadSmartAlbumResource = {
+		id: string;
+		title: string;
+		policy: App.Http.Resources.Models.Utils.AlbumProtectionPolicy;
+		rights: App.Http.Resources.Rights.AlbumRightsResource;
+		preFormattedData: App.Http.Resources.Models.Utils.PreFormattedAlbumData;
+		statistics: null | null;
+	};
+	export type HeadTagAlbumResource = {
+		id: string;
+		title: string;
+		slug: string | null;
+		owner_name: string | null;
+		copyright: string | null;
+		is_tag_album: boolean;
+		show_tags: Array<string>;
+		policy: App.Http.Resources.Models.Utils.AlbumProtectionPolicy;
+		rights: App.Http.Resources.Rights.AlbumRightsResource;
+		preFormattedData: App.Http.Resources.Models.Utils.PreFormattedAlbumData;
+		editable: App.Http.Resources.Editable.EditableBaseAlbumResource | null;
+		statistics: App.Http.Resources.Models.AlbumStatisticsResource | null;
+	};
+	export type JobHistoryResource = {
+		username: string;
+		status: "ready" | "success" | "failure" | "started";
+		created_at: string;
+		updated_at: string;
+		job: string;
+	};
+	export type LightUserResource = {
+		id: number;
+		username: string;
+	};
+	export type LiveMetricsResource = {
+		created_at: string;
+		visitor_id: string;
+		action: App.Enum.MetricsAction;
+		photo_id: string | null;
+		album_id: string;
+		title: string;
+		url: string | null;
+	};
+	export type PersonResource = {
+		id: string;
+		name: string;
+		user_id: number | null;
+		is_searchable: boolean;
+		face_count: number;
+		photo_count: number;
+		representative_crop_url: string | null;
+	};
+	export type PhotoAlbumResource = {
+		id: string;
+		title: string;
+	};
+	export type PhotoRatingResource = {
+		rating_user: number;
+		rating_count: number;
+		rating_avg: number;
+	};
+	export type PhotoResource = {
+		id: string;
+		album_id: string | null;
+		checksum: string;
+		created_at: string;
+		description: string;
+		is_highlighted: boolean;
+		license: App.Enum.LicenseType;
+		live_photo_checksum: string | null;
+		live_photo_content_id: string | null;
+		live_photo_url: string | null;
+		original_checksum: string;
+		size_variants: App.Http.Resources.Models.SizeVariantsResouce;
+		tags: Array<string>;
+		taken_at: string | null;
+		taken_at_orig_tz: string | null;
+		title: string;
+		type: string;
+		updated_at: string;
+		next_photo_id: string | null;
+		previous_photo_id: string | null;
+		preformatted: App.Http.Resources.Models.Utils.PreformattedPhotoData;
+		precomputed: App.Http.Resources.Models.Utils.PreComputedPhotoData;
+		timeline: App.Http.Resources.Models.Utils.TimelineData | null;
+		palette: App.Http.Resources.Models.ColourPaletteResource | null;
+		statistics: App.Http.Resources.Models.PhotoStatisticsResource | null;
+		rating: App.Http.Resources.Models.PhotoRatingResource | null;
+		faces: Array<App.Http.Resources.Models.FaceResource>;
+		hidden_face_count: number;
+	};
+	export type PhotoStatisticsResource = {
+		visit_count: number;
+		download_count: number;
+		favourite_count: number;
+		shared_count: number;
+		rating_count: number;
+		rating_avg: number | null;
+	};
+	export type RenamerPreviewResource = {
+		id: string;
+		original: string;
+		new: string;
+	};
+	export type RenamerRuleResource = {
+		id: number;
+		order: number;
+		owner_id: number;
+		rule: string;
+		description: string;
+		needle: string;
+		replacement: string;
+		mode: App.Enum.RenamerModeType;
+		is_enabled: boolean;
+		is_photo_rule: boolean;
+		is_album_rule: boolean;
+	};
+	export type SizeVariantResource = {
+		type: App.Enum.SizeVariantType;
+		locale: string;
+		filesize: string;
+		height: number;
+		width: number;
+		url: string | null;
+		is_watermarked: boolean;
+	};
+	export type SizeVariantsResouce = {
+		raw: App.Http.Resources.Models.SizeVariantResource | null;
+		original: App.Http.Resources.Models.SizeVariantResource | null;
+		medium2x: App.Http.Resources.Models.SizeVariantResource | null;
+		medium: App.Http.Resources.Models.SizeVariantResource | null;
+		small2x: App.Http.Resources.Models.SizeVariantResource | null;
+		small: App.Http.Resources.Models.SizeVariantResource | null;
+		thumb2x: App.Http.Resources.Models.SizeVariantResource | null;
+		thumb: App.Http.Resources.Models.SizeVariantResource | null;
+		placeholder: App.Http.Resources.Models.SizeVariantResource | null;
+	};
+	export type TargetAlbumResource = {
+		id: string | null;
+		title: string;
+		original: string;
+		short_title: string;
+		thumb: string;
+	};
+	export type ThumbAlbumResource = {
+		id: string;
+		title: string;
+		description: string | null;
+		thumb: App.Http.Resources.Models.ThumbResource | null;
+		is_nsfw: boolean;
+		is_pinned: boolean;
+		is_public: boolean;
+		is_link_required: boolean;
+		is_password_required: boolean;
+		is_tag_album: boolean;
+		has_subalbum: boolean;
+		num_subalbums: number;
+		num_photos: number;
+		created_at: string;
+		formatted_min_max: string | null;
+		owner: string | null;
+		rights: App.Http.Resources.Rights.AlbumRightsResource;
+		timeline: App.Http.Resources.Models.Utils.TimelineData | null;
+	};
+	export type ThumbResource = {
+		id: string;
+		type: string;
+		thumb: string | null;
+		thumb2x: string | null;
+		placeholder: string | null;
+	};
+	export type UserGroupResource = {
+		id: number;
+		name: string;
+		description: string;
+		members: App.Http.Resources.Models.UserMemberGroupResource[];
+		rights: App.Http.Resources.Rights.UserGroupRightResource;
+	};
+	export type UserManagementResource = {
+		id: number;
+		username: string;
+		may_administrate: boolean;
+		may_upload: boolean;
+		may_edit_own_settings: boolean;
+		is_owner: boolean;
+		quota_kb: number | null;
+		description: string | null;
+		note: string | null;
+		space: number | null;
+	};
+	export type UserMemberGroupResource = {
+		id: number;
+		username: string;
+		role: App.Enum.UserGroupRole;
+	};
+	export type UserResource = {
+		id: number | null;
+		has_token: boolean | null;
+		username: string | null;
+		email: string | null;
+		is_ldap: boolean;
+		shared_albums_visibility: App.Enum.UserSharedAlbumsVisibility;
+	};
+	export type WebAuthnResource = {
+		id: string;
+		alias: string | null;
+		created_at: string;
+	};
 }
 declare namespace App.Http.Resources.Models.Duplicates {
-export type Duplicate = {
-album_id: string;
-album_title: string;
-photo_id: string;
-photo_title: string;
-checksum: string;
-url: string | null;
-};
-export type DuplicateCount = {
-pure_duplicates: number;
-title_duplicates: number;
-duplicates_within_album: number;
-};
+	export type Duplicate = {
+		album_id: string;
+		album_title: string;
+		photo_id: string;
+		photo_title: string;
+		checksum: string;
+		url: string | null;
+	};
+	export type DuplicateCount = {
+		pure_duplicates: number;
+		title_duplicates: number;
+		duplicates_within_album: number;
+	};
 }
 declare namespace App.Http.Resources.Models.Utils {
-export type AlbumProtectionPolicy = {
-is_public: boolean;
-is_link_required: boolean;
-is_nsfw: boolean;
-grants_full_photo_access: boolean;
-grants_download: boolean;
-grants_upload: boolean;
-is_password_required: boolean;
-};
-export type HeaderFocusData = {
-x: number;
-y: number;
-};
-export type PreComputedPhotoData = {
-is_video: boolean;
-is_raw: boolean;
-is_livephoto: boolean;
-is_camera_date: boolean;
-has_exif: boolean;
-has_location: boolean;
-is_taken_at_modified: boolean;
-latitude: number | null;
-longitude: number | null;
-altitude: number | null;
-};
-export type PreFormattedAlbumData = {
-url: string | null;
-title: string;
-min_max_text: string | null;
-album_id: string;
-license: string;
-num_children: number;
-num_photos: number;
-created_at: string | null;
-description: string | null;
-copyright: string | null;
-palette: App.Http.Resources.Models.ColourPaletteResource | null;
-title_color: App.Enum.AlbumTitleColor | null;
-title_position: App.Enum.AlbumTitlePosition | null;
-header_photo_focus: App.Http.Resources.Models.Utils.HeaderFocusData | null;
-};
-export type PreformattedPhotoData = {
-created_at: string;
-taken_at: string | null;
-date_overlay: string;
-make: string | null;
-model: string | null;
-shutter: string;
-aperture: string;
-iso: string;
-lens: string;
-focal: string | null;
-duration: string;
-fps: string;
-filesize: string;
-resolution: string;
-latitude: string | null;
-longitude: string | null;
-altitude: string | null;
-location: string | null;
-license: string;
-description: string;
-};
-export type TimelineData = {
-time_date: string;
-format: string;
-};
-export type UserToken = {
-token: string;
-};
+	export type AlbumProtectionPolicy = {
+		is_public: boolean;
+		is_link_required: boolean;
+		is_nsfw: boolean;
+		grants_full_photo_access: boolean;
+		grants_download: boolean;
+		grants_upload: boolean;
+		is_password_required: boolean;
+	};
+	export type HeaderFocusData = {
+		x: number;
+		y: number;
+	};
+	export type PreComputedPhotoData = {
+		is_video: boolean;
+		is_raw: boolean;
+		is_livephoto: boolean;
+		is_camera_date: boolean;
+		has_exif: boolean;
+		has_location: boolean;
+		is_taken_at_modified: boolean;
+		latitude: number | null;
+		longitude: number | null;
+		altitude: number | null;
+	};
+	export type PreFormattedAlbumData = {
+		url: string | null;
+		title: string;
+		min_max_text: string | null;
+		album_id: string;
+		license: string;
+		num_children: number;
+		num_photos: number;
+		created_at: string | null;
+		description: string | null;
+		copyright: string | null;
+		palette: App.Http.Resources.Models.ColourPaletteResource | null;
+		title_color: App.Enum.AlbumTitleColor | null;
+		title_position: App.Enum.AlbumTitlePosition | null;
+		header_photo_focus: App.Http.Resources.Models.Utils.HeaderFocusData | null;
+	};
+	export type PreformattedPhotoData = {
+		created_at: string;
+		taken_at: string | null;
+		date_overlay: string;
+		make: string | null;
+		model: string | null;
+		shutter: string;
+		aperture: string;
+		iso: string;
+		lens: string;
+		focal: string | null;
+		duration: string;
+		fps: string;
+		filesize: string;
+		resolution: string;
+		latitude: string | null;
+		longitude: string | null;
+		altitude: string | null;
+		location: string | null;
+		license: string;
+		description: string;
+	};
+	export type TimelineData = {
+		time_date: string;
+		format: string;
+	};
+	export type UserToken = {
+		token: string;
+	};
 }
 declare namespace App.Http.Resources.Oauth {
-export type OauthRegistrationData = {
-provider_type: App.Enum.OauthProvidersType;
-is_enabled: boolean;
-registration_route: string;
-};
+	export type OauthRegistrationData = {
+		provider_type: App.Enum.OauthProvidersType;
+		is_enabled: boolean;
+		registration_route: string;
+	};
 }
 declare namespace App.Http.Resources.Rights {
-export type AlbumRightsResource = {
-can_edit: boolean;
-can_share: boolean;
-can_share_with_users: boolean;
-can_download: boolean;
-can_upload: boolean;
-can_move: boolean;
-can_delete: boolean;
-can_transfer: boolean;
-can_access_original: boolean;
-can_pasword_protect: boolean;
-can_import_from_server: boolean;
-can_make_purchasable: boolean;
-};
-export type GlobalRightsResource = {
-root_album: App.Http.Resources.Rights.RootAlbumRightsResource;
-settings: App.Http.Resources.Rights.SettingsRightsResource;
-user_management: App.Http.Resources.Rights.UserManagementRightsResource;
-user: App.Http.Resources.Rights.UserRightsResource;
-modules: App.Http.Resources.Rights.ModulesRightsResource;
-};
-export type ModulesRightsResource = {
-is_map_enabled: boolean;
-is_mod_frame_enabled: boolean;
-is_mod_flow_enabled: boolean;
-is_watermarker_enabled: boolean;
-is_photo_timeline_enabled: boolean;
-is_mod_renamer_enabled: boolean;
-is_mod_webshop_enabled: boolean;
-is_contact_enabled: boolean;
-messages_count: number;
-};
-export type PhotoRightsResource = {
-can_edit: boolean;
-can_download: boolean;
-can_access_full_photo: boolean;
-};
-export type RootAlbumRightsResource = {
-can_edit: boolean;
-can_upload: boolean;
-can_see_live_metrics: boolean;
-can_import_from_server: boolean;
-can_highlight: boolean;
-};
-export type SettingsRightsResource = {
-can_edit: boolean;
-can_see_logs: boolean;
-can_see_diagnostics: boolean;
-can_update: boolean;
-can_access_dev_tools: boolean;
-can_acess_user_groups: boolean;
-};
-export type UserGroupRightResource = {
-can_edit: boolean;
-can_manage: boolean;
-};
-export type UserManagementRightsResource = {
-can_create: boolean;
-can_list: boolean;
-can_edit: boolean;
-can_delete: boolean;
-};
-export type UserRightsResource = {
-can_edit: boolean;
-};
+	export type AlbumRightsResource = {
+		can_edit: boolean;
+		can_share: boolean;
+		can_share_with_users: boolean;
+		can_download: boolean;
+		can_upload: boolean;
+		can_move: boolean;
+		can_delete: boolean;
+		can_transfer: boolean;
+		can_access_original: boolean;
+		can_pasword_protect: boolean;
+		can_import_from_server: boolean;
+		can_make_purchasable: boolean;
+	};
+	export type GlobalRightsResource = {
+		root_album: App.Http.Resources.Rights.RootAlbumRightsResource;
+		settings: App.Http.Resources.Rights.SettingsRightsResource;
+		user_management: App.Http.Resources.Rights.UserManagementRightsResource;
+		user: App.Http.Resources.Rights.UserRightsResource;
+		modules: App.Http.Resources.Rights.ModulesRightsResource;
+	};
+	export type ModulesRightsResource = {
+		is_map_enabled: boolean;
+		is_mod_frame_enabled: boolean;
+		is_mod_flow_enabled: boolean;
+		is_watermarker_enabled: boolean;
+		is_photo_timeline_enabled: boolean;
+		is_mod_renamer_enabled: boolean;
+		is_mod_webshop_enabled: boolean;
+		is_contact_enabled: boolean;
+		messages_count: number;
+	};
+	export type PhotoRightsResource = {
+		can_edit: boolean;
+		can_download: boolean;
+		can_access_full_photo: boolean;
+	};
+	export type RootAlbumRightsResource = {
+		can_edit: boolean;
+		can_upload: boolean;
+		can_see_live_metrics: boolean;
+		can_import_from_server: boolean;
+		can_highlight: boolean;
+	};
+	export type SettingsRightsResource = {
+		can_edit: boolean;
+		can_see_logs: boolean;
+		can_see_diagnostics: boolean;
+		can_update: boolean;
+		can_access_dev_tools: boolean;
+		can_acess_user_groups: boolean;
+	};
+	export type UserGroupRightResource = {
+		can_edit: boolean;
+		can_manage: boolean;
+	};
+	export type UserManagementRightsResource = {
+		can_create: boolean;
+		can_list: boolean;
+		can_edit: boolean;
+		can_delete: boolean;
+	};
+	export type UserRightsResource = {
+		can_edit: boolean;
+	};
 }
 declare namespace App.Http.Resources.Root {
-export type AuthConfig = {
-oauthProviders: { [key: number]: App.Enum.OauthProvidersType };
-u2f_enabled: boolean;
-};
-export type VersionResource = {
-version: string | null;
-is_new_release_available: boolean;
-is_git_update_available: boolean;
-};
+	export type AuthConfig = {
+		oauthProviders: { [key: number]: App.Enum.OauthProvidersType };
+		u2f_enabled: boolean;
+	};
+	export type VersionResource = {
+		version: string | null;
+		is_new_release_available: boolean;
+		is_git_update_available: boolean;
+	};
 }
 declare namespace App.Http.Resources.Search {
-export type InitResource = {
-search_minimum_length: number;
-photo_layout: App.Enum.PhotoLayoutType;
-};
-export type ResultsResource = {
-albums: App.Http.Resources.Models.ThumbAlbumResource[];
-photos: App.Http.Resources.Models.PhotoResource[];
-current_page: number;
-from: number;
-last_page: number;
-per_page: number;
-to: number;
-total: number;
-};
+	export type InitResource = {
+		search_minimum_length: number;
+		photo_layout: App.Enum.PhotoLayoutType;
+	};
+	export type ResultsResource = {
+		albums: App.Http.Resources.Models.ThumbAlbumResource[];
+		photos: App.Http.Resources.Models.PhotoResource[];
+		current_page: number;
+		from: number;
+		last_page: number;
+		per_page: number;
+		to: number;
+		total: number;
+	};
 }
 declare namespace App.Http.Resources.Shop {
-export type CatalogResource = {
-album_purchasable: App.Http.Resources.Shop.PurchasableResource | null;
-children_purchasables: App.Http.Resources.Shop.PurchasableResource[];
-photo_purchasables: App.Http.Resources.Shop.PurchasableResource[];
-};
-export type CheckoutOptionResource = {
-currency: string;
-allow_guest_checkout: boolean;
-is_offline: boolean;
-terms_url: string;
-privacy_url: string;
-payment_providers: App.Enum.OmnipayProviderType[];
-mollie_profile_id: string;
-stripe_public_key: string;
-paypal_client_id: string;
-is_test_mode: boolean;
-is_lycheeorg_disclaimer_enabled: boolean;
-};
-export type CheckoutResource = {
-is_success: boolean;
-is_redirect: boolean;
-redirect_url: string | null;
-complete_url: string | null;
-message: string;
-order: App.Http.Resources.Shop.OrderResource | null;
-};
-export type ConfigOptionResource = {
-currency: string;
-default_price_cents: number;
-default_license: App.Enum.PurchasableLicenseType;
-default_size: App.Enum.PurchasableSizeVariantType;
-};
-export type EditablePurchasableResource = {
-purchasable_id: number;
-album_id: string | null;
-album_title: string | null;
-photo_id: string | null;
-photo_title: string | null;
-photo_url: string | null;
-prices: App.Http.Resources.Shop.PriceResource[]|null;
-owner_notes: string | null;
-description: string | null;
-is_active: boolean;
-};
-export type OrderItemResource = {
-id: number;
-order_id: number;
-purchasable_id: number | null;
-album_id: string | null;
-photo_id: string | null;
-title: string;
-license_type: App.Enum.PurchasableLicenseType;
-price: string;
-size_variant_type: App.Enum.PurchasableSizeVariantType;
-item_notes: string | null;
-content_url: string | null;
-};
-export type OrderResource = {
-id: number;
-provider: App.Enum.OmnipayProviderType | null;
-transaction_id: string;
-username: string | null;
-email: string | null;
-status: App.Enum.PaymentStatusType;
-amount: string;
-paid_at: string | null;
-created_at: string | null;
-updated_at: string | null;
-comment: string | null;
-items: App.Http.Resources.Shop.OrderItemResource[]|null;
-can_process_payment: boolean;
-};
-export type PriceResource = {
-size_variant: App.Enum.PurchasableSizeVariantType;
-license_type: App.Enum.PurchasableLicenseType;
-price: string;
-price_cents: number;
-};
-export type PurchasableResource = {
-purchasable_id: number;
-album_id: string | null;
-photo_id: string | null;
-prices: App.Http.Resources.Shop.PriceResource[]|null;
-description: string;
-is_active: boolean;
-};
+	export type CatalogResource = {
+		album_purchasable: App.Http.Resources.Shop.PurchasableResource | null;
+		children_purchasables: App.Http.Resources.Shop.PurchasableResource[];
+		photo_purchasables: App.Http.Resources.Shop.PurchasableResource[];
+	};
+	export type CheckoutOptionResource = {
+		currency: string;
+		allow_guest_checkout: boolean;
+		is_offline: boolean;
+		terms_url: string;
+		privacy_url: string;
+		payment_providers: App.Enum.OmnipayProviderType[];
+		mollie_profile_id: string;
+		stripe_public_key: string;
+		paypal_client_id: string;
+		is_test_mode: boolean;
+		is_lycheeorg_disclaimer_enabled: boolean;
+	};
+	export type CheckoutResource = {
+		is_success: boolean;
+		is_redirect: boolean;
+		redirect_url: string | null;
+		complete_url: string | null;
+		message: string;
+		order: App.Http.Resources.Shop.OrderResource | null;
+	};
+	export type ConfigOptionResource = {
+		currency: string;
+		default_price_cents: number;
+		default_license: App.Enum.PurchasableLicenseType;
+		default_size: App.Enum.PurchasableSizeVariantType;
+	};
+	export type EditablePurchasableResource = {
+		purchasable_id: number;
+		album_id: string | null;
+		album_title: string | null;
+		photo_id: string | null;
+		photo_title: string | null;
+		photo_url: string | null;
+		prices: App.Http.Resources.Shop.PriceResource[] | null;
+		owner_notes: string | null;
+		description: string | null;
+		is_active: boolean;
+	};
+	export type OrderItemResource = {
+		id: number;
+		order_id: number;
+		purchasable_id: number | null;
+		album_id: string | null;
+		photo_id: string | null;
+		title: string;
+		license_type: App.Enum.PurchasableLicenseType;
+		price: string;
+		size_variant_type: App.Enum.PurchasableSizeVariantType;
+		item_notes: string | null;
+		content_url: string | null;
+	};
+	export type OrderResource = {
+		id: number;
+		provider: App.Enum.OmnipayProviderType | null;
+		transaction_id: string;
+		username: string | null;
+		email: string | null;
+		status: App.Enum.PaymentStatusType;
+		amount: string;
+		paid_at: string | null;
+		created_at: string | null;
+		updated_at: string | null;
+		comment: string | null;
+		items: App.Http.Resources.Shop.OrderItemResource[] | null;
+		can_process_payment: boolean;
+	};
+	export type PriceResource = {
+		size_variant: App.Enum.PurchasableSizeVariantType;
+		license_type: App.Enum.PurchasableLicenseType;
+		price: string;
+		price_cents: number;
+	};
+	export type PurchasableResource = {
+		purchasable_id: number;
+		album_id: string | null;
+		photo_id: string | null;
+		prices: App.Http.Resources.Shop.PriceResource[] | null;
+		description: string;
+		is_active: boolean;
+	};
 }
 declare namespace App.Http.Resources.Statistics {
-export type Album = {
-username: string;
-title: string;
-is_nsfw: boolean;
-left: number;
-right: number;
-num_photos: number;
-num_descendants: number;
-size: number;
-};
-export type CountsData = {
-data: Array<App.Http.Resources.Statistics.DayCount>;
-low_number_of_shoots_per_day: number;
-medium_number_of_shoots_per_day: number;
-high_number_of_shoots_per_day: number;
-min_created_at: string;
-min_taken_at: string;
-};
-export type DayCount = {
-date: string;
-count: number;
-};
-export type Sizes = {
-type: App.Enum.SizeVariantType;
-label: string;
-size: number;
-};
-export type UserSpace = {
-id: number;
-username: string;
-size: number;
-};
+	export type Album = {
+		username: string;
+		title: string;
+		is_nsfw: boolean;
+		left: number;
+		right: number;
+		num_photos: number;
+		num_descendants: number;
+		size: number;
+	};
+	export type CountsData = {
+		data: Array<App.Http.Resources.Statistics.DayCount>;
+		low_number_of_shoots_per_day: number;
+		medium_number_of_shoots_per_day: number;
+		high_number_of_shoots_per_day: number;
+		min_created_at: string;
+		min_taken_at: string;
+	};
+	export type DayCount = {
+		date: string;
+		count: number;
+	};
+	export type Sizes = {
+		type: App.Enum.SizeVariantType;
+		label: string;
+		size: number;
+	};
+	export type UserSpace = {
+		id: number;
+		username: string;
+		size: number;
+	};
 }
 declare namespace App.Http.Resources.Tags {
-export type TagResource = {
-id: number;
-name: string;
-num: number;
-};
-export type TagWithPhotosResource = {
-id: number;
-name: string;
-photos: App.Http.Resources.Models.PhotoResource[];
-};
-export type TagsResource = {
-can_edit: boolean;
-tags: App.Http.Resources.Tags.TagResource[];
-};
+	export type TagResource = {
+		id: number;
+		name: string;
+		num: number;
+	};
+	export type TagWithPhotosResource = {
+		id: number;
+		name: string;
+		photos: App.Http.Resources.Models.PhotoResource[];
+	};
+	export type TagsResource = {
+		can_edit: boolean;
+		tags: App.Http.Resources.Tags.TagResource[];
+	};
 }
 declare namespace App.Http.Resources.Timeline {
-export type InitResource = {
-photo_layout: App.Enum.PhotoLayoutType;
-is_timeline_page_enabled: boolean;
-config: App.Http.Resources.GalleryConfigs.RootConfig;
-rights: App.Http.Resources.Rights.RootAlbumRightsResource;
-};
-export type TimelineResource = {
-photos: App.Http.Resources.Models.PhotoResource[];
-current_page: number;
-from: number;
-last_page: number;
-per_page: number;
-to: number;
-total: number;
-};
+	export type InitResource = {
+		photo_layout: App.Enum.PhotoLayoutType;
+		is_timeline_page_enabled: boolean;
+		config: App.Http.Resources.GalleryConfigs.RootConfig;
+		rights: App.Http.Resources.Rights.RootAlbumRightsResource;
+	};
+	export type TimelineResource = {
+		photos: App.Http.Resources.Models.PhotoResource[];
+		current_page: number;
+		from: number;
+		last_page: number;
+		per_page: number;
+		to: number;
+		total: number;
+	};
 }
diff --git a/resources/js/router/routes.ts b/resources/js/router/routes.ts
index dfdd2883dbc..5081408d8b4 100644
--- a/resources/js/router/routes.ts
+++ b/resources/js/router/routes.ts
@@ -36,6 +36,7 @@ const OrderList = () => import("@/views/webshop/OrderList.vue");
 const OrderDownload = () => import("@/views/webshop/OrderDownload.vue");
 const People = () => import("@/views/People.vue");
 const PersonDetail = () => import("@/views/PersonDetail.vue");
+const FaceClusters = () => import("@/views/FaceClusters.vue");
 
 const routes_ = [
 	{
@@ -233,6 +234,11 @@ const routes_ = [
 		path: "/people",
 		component: People,
 	},
+	{
+		name: "face-clusters",
+		path: "/people/clusters",
+		component: FaceClusters,
+	},
 	{
 		name: "person",
 		path: "/people/:personId",
diff --git a/resources/js/services/face-cluster-service.ts b/resources/js/services/face-cluster-service.ts
new file mode 100644
index 00000000000..74cd0c6f1aa
--- /dev/null
+++ b/resources/js/services/face-cluster-service.ts
@@ -0,0 +1,28 @@
+import axios, { type AxiosResponse } from "axios";
+import Constants, { type PaginatedResponse } from "./constants";
+
+export type ClusterPreview = {
+	cluster_label: number;
+	face_count: number;
+	sample_crop_urls: string[];
+};
+
+const FaceClusterService = {
+	getClusters(page: number = 1): Promise<AxiosResponse<PaginatedResponse<ClusterPreview>>> {
+		return axios.get(`${Constants.getApiUrl()}FaceDetection/clusters`, { params: { page }, data: {} });
+	},
+
+	assignCluster(label: number, data: { person_id?: string; new_person_name?: string }): Promise<AxiosResponse<{ assigned_count: number }>> {
+		return axios.post(`${Constants.getApiUrl()}FaceDetection/clusters/${label}/assign`, data);
+	},
+
+	dismissCluster(label: number): Promise<AxiosResponse<{ dismissed_count: number }>> {
+		return axios.post(`${Constants.getApiUrl()}FaceDetection/clusters/${label}/dismiss`, {});
+	},
+
+	runClustering(): Promise<AxiosResponse> {
+		return axios.post(`${Constants.getApiUrl()}Maintenance::runFaceClustering`, {});
+	},
+};
+
+export default FaceClusterService;
diff --git a/resources/js/views/FaceClusters.vue b/resources/js/views/FaceClusters.vue
new file mode 100644
index 00000000000..3062782a4be
--- /dev/null
+++ b/resources/js/views/FaceClusters.vue
@@ -0,0 +1,205 @@
+<template>
+	<div class="h-svh overflow-y-auto">
+		<Toolbar class="w-full border-0 h-14 rounded-none">
+			<template #start>
+				<OpenLeftMenu />
+			</template>
+			<template #center>
+				{{ $t("people.clusters_title") }}
+			</template>
+			<template #end>
+				<Button
+					:label="$t('people.run_clustering')"
+					icon="pi pi-refresh"
+					severity="secondary"
+					outlined
+					:loading="runningClustering"
+					@click="runClustering"
+				/>
+			</template>
+		</Toolbar>
+
+		<div v-if="loading" class="flex justify-center items-center mt-20">
+			<ProgressSpinner />
+		</div>
+
+		<div v-else-if="clusters.length === 0" class="text-muted-color text-center mt-20 p-4">
+			{{ $t("people.no_clusters") }}
+		</div>
+
+		<div v-else class="p-6 flex flex-col gap-4">
+			<div
+				v-for="cluster in clusters"
+				:key="cluster.cluster_label"
+				class="border border-surface rounded-lg p-4 flex flex-col sm:flex-row items-start gap-4"
+			>
+				<div class="flex gap-2 shrink-0">
+					<img
+						v-for="(url, idx) in cluster.sample_crop_urls"
+						:key="idx"
+						:src="url"
+						class="w-16 h-16 rounded-lg object-cover"
+						loading="lazy"
+					/>
+					<div
+						v-if="cluster.face_count > cluster.sample_crop_urls.length"
+						class="w-16 h-16 rounded-lg bg-surface-100 dark:bg-surface-700 flex items-center justify-center text-sm text-muted-color"
+					>
+						+{{ cluster.face_count - cluster.sample_crop_urls.length }}
+					</div>
+				</div>
+
+				<div class="flex-1 flex flex-col sm:flex-row items-start sm:items-center gap-2 w-full">
+					<span class="text-sm text-muted-color">{{ cluster.face_count }} {{ $t("people.faces") }}</span>
+					<InputText v-model="clusterNames[cluster.cluster_label]" :placeholder="$t('people.enter_name')" class="w-full sm:w-48" />
+				</div>
+
+				<div class="flex gap-2 shrink-0">
+					<Button
+						:label="$t('people.assign')"
+						icon="pi pi-check"
+						severity="success"
+						size="small"
+						:disabled="!clusterNames[cluster.cluster_label]?.trim()"
+						:loading="assigningLabel === cluster.cluster_label"
+						@click="assignCluster(cluster.cluster_label)"
+					/>
+					<Button
+						:label="$t('people.dismiss')"
+						icon="pi pi-times"
+						severity="danger"
+						size="small"
+						outlined
+						:loading="dismissingLabel === cluster.cluster_label"
+						@click="dismissCluster(cluster.cluster_label)"
+					/>
+				</div>
+			</div>
+		</div>
+
+		<div v-if="hasMorePages" class="flex justify-center pb-8 mt-4">
+			<Button :label="$t('gallery.load_more') || 'Load more'" severity="secondary" outlined @click="loadMore" :loading="loadingMore" />
+		</div>
+	</div>
+</template>
+
+<script setup lang="ts">
+import { ref, reactive, onMounted } from "vue";
+import Toolbar from "primevue/toolbar";
+import ProgressSpinner from "primevue/progressspinner";
+import Button from "primevue/button";
+import InputText from "primevue/inputtext";
+import { useToast } from "primevue/usetoast";
+import { trans } from "laravel-vue-i18n";
+import OpenLeftMenu from "@/components/headers/OpenLeftMenu.vue";
+import FaceClusterService, { type ClusterPreview } from "@/services/face-cluster-service";
+
+const toast = useToast();
+
+const clusters = ref<ClusterPreview[]>([]);
+const clusterNames = reactive<Record<number, string>>({});
+const loading = ref(false);
+const loadingMore = ref(false);
+const runningClustering = ref(false);
+const assigningLabel = ref<number | null>(null);
+const dismissingLabel = ref<number | null>(null);
+const currentPage = ref(1);
+const hasMorePages = ref(false);
+
+function load() {
+	loading.value = true;
+	FaceClusterService.getClusters(1)
+		.then((response) => {
+			clusters.value = response.data.data;
+			currentPage.value = 1;
+			hasMorePages.value = response.data.meta.current_page < response.data.meta.last_page;
+		})
+		.catch((e) => {
+			toast.add({ severity: "error", summary: trans("toasts.error"), detail: e.response?.data?.message, life: 3000 });
+		})
+		.finally(() => {
+			loading.value = false;
+		});
+}
+
+function loadMore() {
+	loadingMore.value = true;
+	const nextPage = currentPage.value + 1;
+	FaceClusterService.getClusters(nextPage)
+		.then((response) => {
+			clusters.value = [...clusters.value, ...response.data.data];
+			currentPage.value = nextPage;
+			hasMorePages.value = response.data.meta.current_page < response.data.meta.last_page;
+		})
+		.catch((e) => {
+			toast.add({ severity: "error", summary: trans("toasts.error"), detail: e.response?.data?.message, life: 3000 });
+		})
+		.finally(() => {
+			loadingMore.value = false;
+		});
+}
+
+function assignCluster(label: number) {
+	const name = clusterNames[label]?.trim();
+	if (!name) return;
+
+	assigningLabel.value = label;
+	FaceClusterService.assignCluster(label, { new_person_name: name })
+		.then((response) => {
+			toast.add({
+				severity: "success",
+				summary: trans("toasts.success"),
+				detail: `Assigned ${response.data.assigned_count} face(s) to "${name}"`,
+				life: 3000,
+			});
+			clusters.value = clusters.value.filter((c) => c.cluster_label !== label);
+			delete clusterNames[label];
+		})
+		.catch((e) => {
+			toast.add({ severity: "error", summary: trans("toasts.error"), detail: e.response?.data?.message, life: 3000 });
+		})
+		.finally(() => {
+			assigningLabel.value = null;
+		});
+}
+
+function dismissCluster(label: number) {
+	dismissingLabel.value = label;
+	FaceClusterService.dismissCluster(label)
+		.then((response) => {
+			toast.add({
+				severity: "info",
+				summary: trans("toasts.success"),
+				detail: `Dismissed ${response.data.dismissed_count} face(s)`,
+				life: 3000,
+			});
+			clusters.value = clusters.value.filter((c) => c.cluster_label !== label);
+			delete clusterNames[label];
+		})
+		.catch((e) => {
+			toast.add({ severity: "error", summary: trans("toasts.error"), detail: e.response?.data?.message, life: 3000 });
+		})
+		.finally(() => {
+			dismissingLabel.value = null;
+		});
+}
+
+function runClustering() {
+	runningClustering.value = true;
+	FaceClusterService.runClustering()
+		.then(() => {
+			toast.add({ severity: "success", summary: trans("toasts.success"), detail: "Clustering started. Reload when complete.", life: 5000 });
+			setTimeout(() => load(), 3000);
+		})
+		.catch((e) => {
+			toast.add({ severity: "error", summary: trans("toasts.error"), detail: e.response?.data?.message, life: 3000 });
+		})
+		.finally(() => {
+			runningClustering.value = false;
+		});
+}
+
+onMounted(() => {
+	load();
+});
+</script>
diff --git a/resources/js/views/Maintenance.vue b/resources/js/views/Maintenance.vue
index 2350c366af4..2136c7eec65 100644
--- a/resources/js/views/Maintenance.vue
+++ b/resources/js/views/Maintenance.vue
@@ -39,6 +39,7 @@
 		<MaintenanceCleaning path="filesystems.disks.image-jobs.root" />
 		<MaintenanceCleaning path="filesystems.disks.image-upload.root" />
 		<MaintenanceBulkScanFaces />
+		<MaintenanceRunClustering />
 	</div>
 </template>
 <script setup lang="ts">
@@ -61,4 +62,5 @@ import MaintenanceFulfillPrecompute from "@/components/maintenance/MaintenanceFu
 import MaintenanceBackfillAlbumSizes from "@/components/maintenance/MaintenanceBackfillAlbumSizes.vue";
 import MaintenanceFlushQueue from "@/components/maintenance/MaintenanceFlushQueue.vue";
 import MaintenanceBulkScanFaces from "@/components/maintenance/MaintenanceBulkScanFaces.vue";
+import MaintenanceRunClustering from "@/components/maintenance/MaintenanceRunClustering.vue";
 </script>
diff --git a/resources/js/views/People.vue b/resources/js/views/People.vue
index cdd24d4e0dc..da97737993a 100644
--- a/resources/js/views/People.vue
+++ b/resources/js/views/People.vue
@@ -7,7 +7,15 @@
 			<template #center>
 				{{ $t("people.title") }}
 			</template>
-			<template #end> </template>
+			<template #end>
+				<Button
+					:label="$t('people.clusters_title')"
+					icon="pi pi-sitemap"
+					severity="secondary"
+					outlined
+					@click="$router.push('/people/clusters')"
+				/>
+			</template>
 		</Toolbar>
 
 		<div v-if="loading" class="flex justify-center items-center mt-20">
diff --git a/resources/js/views/PersonDetail.vue b/resources/js/views/PersonDetail.vue
index c538671bfd0..16792af9131 100644
--- a/resources/js/views/PersonDetail.vue
+++ b/resources/js/views/PersonDetail.vue
@@ -32,7 +32,7 @@
 		<template v-else-if="person">
 			<!-- Person header -->
 			<div class="flex flex-col sm:flex-row items-center gap-6 p-6 border-b border-surface-700">
-				<div class="w-24 h-24 rounded-full overflow-hidden bg-surface-800 flex items-center justify-center flex-shrink-0">
+				<div class="w-24 h-24 rounded-full overflow-hidden bg-surface-800 flex items-center justify-center shrink-0">
 					<img
 						v-if="person.representative_crop_url"
 						:src="person.representative_crop_url"
diff --git a/routes/api_v2.php b/routes/api_v2.php
index ff7bd801a4f..9f2f2813e7f 100644
--- a/routes/api_v2.php
+++ b/routes/api_v2.php
@@ -375,9 +375,18 @@
 Route::post('/FaceDetection/scan', [AiVision\FaceDetectionController::class, 'scan'])->middleware(['support:se']);
 Route::post('/FaceDetection/results', [AiVision\FaceDetectionController::class, 'results'])->withoutMiddleware(['auth']);
 Route::post('/FaceDetection/bulk-scan', [AiVision\FaceDetectionController::class, 'bulkScan'])->middleware(['support:se']);
+Route::post('/FaceDetection/cluster-results', [AiVision\FaceDetectionController::class, 'clusterResults'])->withoutMiddleware(['auth']);
+
+/**
+ * AI VISION — CLUSTER REVIEW.
+ */
+Route::get('/FaceDetection/clusters', [AiVision\FaceClusterController::class, 'index'])->middleware(['support:se']);
+Route::post('/FaceDetection/clusters/{label}/assign', [AiVision\FaceClusterController::class, 'assign'])->middleware(['support:se']);
+Route::post('/FaceDetection/clusters/{label}/dismiss', [AiVision\FaceClusterController::class, 'dismiss'])->middleware(['support:se']);
 
 /**
  * AI VISION — MAINTENANCE.
  */
 Route::get('/Maintenance::resetStuckFaces', [Admin\Maintenance\ResetStuckFaces::class, 'check']);
 Route::post('/Maintenance::resetStuckFaces', [Admin\Maintenance\ResetStuckFaces::class, 'do']);
+Route::post('/Maintenance::runFaceClustering', [Admin\Maintenance\RunFaceClustering::class, 'do']);
diff --git a/routes/web_v2.php b/routes/web_v2.php
index 46308a4efc4..ccd0c037e01 100644
--- a/routes/web_v2.php
+++ b/routes/web_v2.php
@@ -79,7 +79,7 @@
 Route::get('/login', VueController::class)->middleware(['migration:complete']);
 Route::get('/register', VueController::class)->name('register')->middleware(['migration:complete']);
 
-Route::get('/people', VueController::class)->middleware(['migration:complete']);
+Route::get('/people/{cluster?}', VueController::class)->middleware(['migration:complete']);
 Route::get('/settings', VueController::class)->middleware(['migration:complete', 'login_required:always']);
 Route::get('/permissions', VueController::class)->middleware(['migration:complete', 'login_required:always']);
 Route::get('/fixTree', VueController::class)->middleware(['migration:complete', 'login_required:always']);
diff --git a/tests/Feature_v2/AiVision/FaceAssignmentTest.php b/tests/Feature_v2/AiVision/FaceAssignmentTest.php
new file mode 100644
index 00000000000..af73c458b01
--- /dev/null
+++ b/tests/Feature_v2/AiVision/FaceAssignmentTest.php
@@ -0,0 +1,121 @@
+<?php
+
+/**
+ * SPDX-License-Identifier: MIT
+ * Copyright (c) 2017-2018 Tobias Reich
+ * Copyright (c) 2018-2026 LycheeOrg.
+ */
+
+/**
+ * @noinspection PhpDocMissingThrowsInspection
+ * @noinspection PhpUnhandledExceptionInspection
+ */
+
+namespace Tests\Feature_v2\AiVision;
+
+use App\Models\Configs;
+use App\Models\Face;
+use App\Models\Person;
+use Illuminate\Support\Facades\DB;
+use Tests\Feature_v2\Base\BaseApiWithDataTest;
+
+class FaceAssignmentTest extends BaseApiWithDataTest
+{
+	private Person $person1;
+	private Face $face1;
+
+	public function setUp(): void
+	{
+		parent::setUp();
+		$this->requireSe();
+
+		Configs::set('ai_vision_enabled', '1');
+		Configs::set('ai_vision_face_enabled', '1');
+		Configs::set('ai_vision_face_permission_mode', 'public');
+		Configs::set('ai_vision_face_person_is_searchable_default', '1');
+
+		$this->person1 = Person::factory()->with_name('Alice')->create();
+		$this->face1 = Face::factory()->for_photo($this->photo1)->create();
+	}
+
+	public function tearDown(): void
+	{
+		DB::table('face_suggestions')->delete();
+		DB::table('faces')->delete();
+		DB::table('persons')->delete();
+		$this->resetSe();
+		parent::tearDown();
+	}
+
+	// ── ASSIGN TO EXISTING PERSON ───────────────────────────────
+
+	public function testAssignToExistingPerson(): void
+	{
+		$response = $this->actingAs($this->userMayUpload1)->postJson('Face/' . $this->face1->id . '/assign', [
+			'person_id' => $this->person1->id,
+		]);
+		$this->assertStatus($response, [200, 201]);
+		self::assertEquals($this->person1->id, $response->json('person_id'));
+	}
+
+	public function testAssignCreatingNewPerson(): void
+	{
+		$response = $this->actingAs($this->userMayUpload1)->postJson('Face/' . $this->face1->id . '/assign', [
+			'new_person_name' => 'Charlie',
+		]);
+		$this->assertStatus($response, [200, 201]);
+		self::assertNotNull($response->json('person_id'));
+
+		// Verify new person was created
+		$new_person = Person::find($response->json('person_id'));
+		self::assertNotNull($new_person);
+		self::assertEquals('Charlie', $new_person->name);
+		self::assertTrue($new_person->is_searchable);
+	}
+
+	public function testReassignFaceToDifferentPerson(): void
+	{
+		$this->face1->person_id = $this->person1->id;
+		$this->face1->save();
+
+		$person2 = Person::factory()->with_name('Bob')->create();
+
+		$response = $this->actingAs($this->userMayUpload1)->postJson('Face/' . $this->face1->id . '/assign', [
+			'person_id' => $person2->id,
+		]);
+		$this->assertStatus($response, [200, 201]);
+		self::assertEquals($person2->id, $response->json('person_id'));
+	}
+
+	public function testAssignValidationRequiresPersonOrName(): void
+	{
+		$response = $this->actingAs($this->admin)->postJson('Face/' . $this->face1->id . '/assign', []);
+		$this->assertUnprocessable($response);
+	}
+
+	public function testAssignAsGuestUnauthorized(): void
+	{
+		$response = $this->postJson('Face/' . $this->face1->id . '/assign', [
+			'person_id' => $this->person1->id,
+		]);
+		$this->assertUnauthorized($response);
+	}
+
+	public function testAssignRestrictedModeAsUserForbidden(): void
+	{
+		Configs::set('ai_vision_face_permission_mode', 'restricted');
+
+		$response = $this->actingAs($this->userMayUpload1)->postJson('Face/' . $this->face1->id . '/assign', [
+			'person_id' => $this->person1->id,
+		]);
+		$this->assertForbidden($response);
+	}
+
+	public function testAssignInvalidPersonId(): void
+	{
+		$response = $this->actingAs($this->admin)->postJson('Face/' . $this->face1->id . '/assign', [
+			'person_id' => 'nonexistent_person_id',
+		]);
+		$this->assertUnprocessable($response);
+	}
+}
diff --git a/tests/Feature_v2/AiVision/FaceClusterReviewTest.php b/tests/Feature_v2/AiVision/FaceClusterReviewTest.php
new file mode 100644
index 00000000000..f7f0d71706f
--- /dev/null
+++ b/tests/Feature_v2/AiVision/FaceClusterReviewTest.php
@@ -0,0 +1,155 @@
+<?php
+
+/**
+ * SPDX-License-Identifier: MIT
+ * Copyright (c) 2017-2018 Tobias Reich
+ * Copyright (c) 2018-2026 LycheeOrg.
+ */
+
+/**
+ * @noinspection PhpDocMissingThrowsInspection
+ * @noinspection PhpUnhandledExceptionInspection
+ */
+
+namespace Tests\Feature_v2\AiVision;
+
+use App\Models\Configs;
+use App\Models\Face;
+use App\Models\Person;
+use Illuminate\Support\Facades\DB;
+use Tests\Feature_v2\Base\BaseApiWithDataTest;
+
+class FaceClusterReviewTest extends BaseApiWithDataTest
+{
+	public function setUp(): void
+	{
+		parent::setUp();
+		$this->requireSe();
+
+		Configs::set('ai_vision_enabled', '1');
+		Configs::set('ai_vision_face_enabled', '1');
+		Configs::set('ai_vision_face_permission_mode', 'public');
+		Configs::set('ai_vision_face_person_is_searchable_default', '1');
+	}
+
+	public function tearDown(): void
+	{
+		DB::table('face_suggestions')->delete();
+		DB::table('faces')->delete();
+		DB::table('persons')->delete();
+		$this->resetSe();
+		parent::tearDown();
+	}
+
+	// ── LIST CLUSTERS ───────────────────────────────────────────
+
+	public function testListClusters(): void
+	{
+		// Create faces with cluster labels
+		Face::factory()->for_photo($this->photo1)->with_cluster(1)->create();
+		Face::factory()->for_photo($this->photo1)->with_cluster(1)->create();
+		Face::factory()->for_photo($this->photo1)->with_cluster(2)->create();
+
+		$response = $this->actingAs($this->userMayUpload1)->getJson('FaceDetection/clusters');
+		$this->assertOk($response);
+
+		$data = $response->json('data');
+		self::assertGreaterThanOrEqual(2, count($data));
+	}
+
+	public function testListClustersExcludesAssigned(): void
+	{
+		$person = Person::factory()->create();
+
+		// Assigned face should not appear
+		Face::factory()->for_photo($this->photo1)->for_person($person)->with_cluster(1)->create();
+
+		// Unassigned face should appear
+		Face::factory()->for_photo($this->photo1)->with_cluster(2)->create();
+
+		$response = $this->actingAs($this->admin)->getJson('FaceDetection/clusters');
+		$this->assertOk($response);
+
+		$cluster_labels = collect($response->json('data'))->pluck('cluster_label')->all();
+		self::assertNotContains(1, $cluster_labels);
+		self::assertContains(2, $cluster_labels);
+	}
+
+	public function testListClustersExcludesDismissed(): void
+	{
+		Face::factory()->for_photo($this->photo1)->dismissed()->with_cluster(3)->create();
+
+		$response = $this->actingAs($this->admin)->getJson('FaceDetection/clusters');
+		$this->assertOk($response);
+
+		$cluster_labels = collect($response->json('data'))->pluck('cluster_label')->all();
+		self::assertNotContains(3, $cluster_labels);
+	}
+
+	public function testListClustersAsGuestUnauthorized(): void
+	{
+		$response = $this->getJson('FaceDetection/clusters');
+		$this->assertUnauthorized($response);
+	}
+
+	// ── ASSIGN CLUSTER ──────────────────────────────────────────
+
+	public function testAssignClusterToNewPerson(): void
+	{
+		Face::factory()->for_photo($this->photo1)->with_cluster(5)->count(3)->create();
+
+		$response = $this->actingAs($this->admin)->postJson('FaceDetection/clusters/5/assign', [
+			'new_person_name' => 'Cluster Person',
+		]);
+		$this->assertOk($response);
+		self::assertEquals(3, $response->json('assigned_count'));
+
+		// Verify person was created
+		$person = Person::where('name', 'Cluster Person')->first();
+		self::assertNotNull($person);
+
+		// All faces should have person_id set
+		$faces = Face::where('cluster_label', 5)->get();
+		foreach ($faces as $face) {
+			self::assertEquals($person->id, $face->person_id);
+		}
+	}
+
+	public function testAssignClusterToExistingPerson(): void
+	{
+		$person = Person::factory()->with_name('Existing Person')->create();
+		Face::factory()->for_photo($this->photo1)->with_cluster(6)->count(2)->create();
+
+		$response = $this->actingAs($this->admin)->postJson('FaceDetection/clusters/6/assign', [
+			'person_id' => $person->id,
+		]);
+		$this->assertOk($response);
+		self::assertEquals(2, $response->json('assigned_count'));
+	}
+
+	public function testAssignClusterNotFound(): void
+	{
+		$response = $this->actingAs($this->admin)->postJson('FaceDetection/clusters/999/assign', [
+			'new_person_name' => 'Test',
+		]);
+		$this->assertOk($response);
+		self::assertEquals(0, $response->json('assigned_count'));
+	}
+
+	// ── DISMISS CLUSTER ─────────────────────────────────────────
+
+	public function testDismissCluster(): void
+	{
+		Face::factory()->for_photo($this->photo1)->with_cluster(7)->count(3)->create();
+
+		$response = $this->actingAs($this->admin)->postJson('FaceDetection/clusters/7/dismiss');
+		$this->assertOk($response);
+		self::assertEquals(3, $response->json('dismissed_count'));
+
+		// All faces should be dismissed
+		$faces = Face::where('cluster_label', 7)->get();
+		foreach ($faces as $face) {
+			self::assertTrue($face->is_dismissed);
+		}
+	}
+}
diff --git a/tests/Feature_v2/AiVision/FaceDetectionServiceUnavailableTest.php b/tests/Feature_v2/AiVision/FaceDetectionServiceUnavailableTest.php
new file mode 100644
index 00000000000..16474f4c9d5
--- /dev/null
+++ b/tests/Feature_v2/AiVision/FaceDetectionServiceUnavailableTest.php
@@ -0,0 +1,65 @@
+<?php
+
+/**
+ * SPDX-License-Identifier: MIT
+ * Copyright (c) 2017-2018 Tobias Reich
+ * Copyright (c) 2018-2026 LycheeOrg.
+ */
+
+/**
+ * @noinspection PhpDocMissingThrowsInspection
+ * @noinspection PhpUnhandledExceptionInspection
+ */
+
+namespace Tests\Feature_v2\AiVision;
+
+use App\Models\Configs;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Http;
+use Tests\Feature_v2\Base\BaseApiWithDataTest;
+
+class FaceDetectionServiceUnavailableTest extends BaseApiWithDataTest
+{
+	public function setUp(): void
+	{
+		parent::setUp();
+		$this->requireSe();
+
+		Configs::set('ai_vision_enabled', '1');
+		Configs::set('ai_vision_face_enabled', '1');
+		Configs::set('ai_vision_face_permission_mode', 'public');
+
+		config(['features.ai-vision.face-url' => 'http://fake-vision-service:8000']);
+		config(['features.ai-vision.face-api-key' => 'test-api-key']);
+	}
+
+	public function tearDown(): void
+	{
+		DB::table('face_suggestions')->delete();
+		DB::table('faces')->delete();
+		DB::table('persons')->delete();
+		$this->resetSe();
+		parent::tearDown();
+	}
+
+	public function testClusteringWhenServiceUnavailable(): void
+	{
+		Http::fake([
+			'fake-vision-service:8000/*' => Http::response(null, 503),
+		]);
+
+		$response = $this->actingAs($this->admin)->postJson('Maintenance::runFaceClustering');
+		$this->assertStatus($response, [500, 503]);
+	}
+
+	public function testOtherEndpointsContinueWorking(): void
+	{
+		Http::fake([
+			'fake-vision-service:8000/*' => Http::response(null, 503),
+		]);
+
+		// Other Lychee endpoints should still work fine
+		$response = $this->actingAs($this->admin)->getJson('Albums');
+		$this->assertOk($response);
+	}
+}
diff --git a/tests/Feature_v2/AiVision/FaceDetectionTest.php b/tests/Feature_v2/AiVision/FaceDetectionTest.php
new file mode 100644
index 00000000000..28589634ac9
--- /dev/null
+++ b/tests/Feature_v2/AiVision/FaceDetectionTest.php
@@ -0,0 +1,251 @@
+<?php
+
+/**
+ * SPDX-License-Identifier: MIT
+ * Copyright (c) 2017-2018 Tobias Reich
+ * Copyright (c) 2018-2026 LycheeOrg.
+ */
+
+/**
+ * @noinspection PhpDocMissingThrowsInspection
+ * @noinspection PhpUnhandledExceptionInspection
+ */
+
+namespace Tests\Feature_v2\AiVision;
+
+use App\Enum\FaceScanStatus;
+use App\Models\Configs;
+use App\Models\Face;
+use App\Models\Person;
+use App\Models\Photo;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Queue;
+use Tests\Feature_v2\Base\BaseApiWithDataTest;
+
+class FaceDetectionTest extends BaseApiWithDataTest
+{
+	private string $api_key;
+
+	public function setUp(): void
+	{
+		parent::setUp();
+		$this->requireSe();
+
+		Configs::set('ai_vision_enabled', '1');
+		Configs::set('ai_vision_face_enabled', '1');
+		Configs::set('ai_vision_face_permission_mode', 'public');
+
+		$this->api_key = 'test-api-key-12345';
+		config(['features.ai-vision.face-api-key' => $this->api_key]);
+	}
+
+	public function tearDown(): void
+	{
+		DB::table('face_suggestions')->delete();
+		DB::table('faces')->delete();
+		DB::table('persons')->delete();
+		$this->resetSe();
+		parent::tearDown();
+	}
+
+	// ── SCAN TRIGGER ────────────────────────────────────────────
+
+	public function testScanPhotos(): void
+	{
+		Queue::fake();
+
+		$response = $this->actingAs($this->userMayUpload1)->postJson('FaceDetection/scan', [
+			'photo_ids' => [$this->photo1->id],
+		]);
+		$this->assertStatus($response, 202);
+	}
+
+	public function testScanAlbum(): void
+	{
+		Queue::fake();
+
+		$response = $this->actingAs($this->userMayUpload1)->postJson('FaceDetection/scan', [
+			'album_id' => $this->album1->id,
+		]);
+		$this->assertStatus($response, 202);
+	}
+
+	public function testScanValidationRequiresPhotoOrAlbum(): void
+	{
+		$response = $this->actingAs($this->admin)->postJson('FaceDetection/scan', []);
+		$this->assertUnprocessable($response);
+	}
+
+	public function testScanAsGuestUnauthorized(): void
+	{
+		$response = $this->postJson('FaceDetection/scan', [
+			'photo_ids' => [$this->photo1->id],
+		]);
+		$this->assertUnauthorized($response);
+	}
+
+	// ── RESULTS CALLBACK ────────────────────────────────────────
+
+	public function testResultsSuccess(): void
+	{
+		// Set photo to pending status
+		Photo::where('id', $this->photo1->id)->update(['face_scan_status' => FaceScanStatus::PENDING->value]);
+
+		$response = $this->postJson('FaceDetection/results', [
+			'photo_id' => $this->photo1->id,
+			'status' => 'success',
+			'faces' => [
+				[
+					'x' => 0.1,
+					'y' => 0.2,
+					'width' => 0.15,
+					'height' => 0.2,
+					'confidence' => 0.95,
+					'embedding_id' => 'emb_001',
+					'crop' => base64_encode('fake-crop-data'),
+				],
+			],
+		], ['X-API-Key' => $this->api_key]);
+
+		$this->assertOk($response);
+		self::assertCount(1, $response->json('faces'));
+		self::assertEquals('emb_001', $response->json('faces.0.embedding_id'));
+
+		// Verify face was created
+		$faces = Face::where('photo_id', $this->photo1->id)->get();
+		self::assertCount(1, $faces);
+		self::assertEqualsWithDelta(0.95, $faces->first()->confidence, 0.001);
+
+		// Verify photo status updated
+		$this->photo1->refresh();
+		self::assertEquals(FaceScanStatus::COMPLETED, $this->photo1->face_scan_status);
+	}
+
+	public function testResultsError(): void
+	{
+		Photo::where('id', $this->photo1->id)->update(['face_scan_status' => FaceScanStatus::PENDING->value]);
+
+		$response = $this->postJson('FaceDetection/results', [
+			'photo_id' => $this->photo1->id,
+			'status' => 'error',
+			'message' => 'No face found',
+		], ['X-API-Key' => $this->api_key]);
+
+		$this->assertOk($response);
+
+		// Photo should be marked as failed
+		$this->photo1->refresh();
+		self::assertEquals(FaceScanStatus::FAILED, $this->photo1->face_scan_status);
+	}
+
+	public function testResultsInvalidApiKey(): void
+	{
+		$response = $this->postJson('FaceDetection/results', [
+			'photo_id' => $this->photo1->id,
+			'status' => 'success',
+			'faces' => [],
+		], ['X-API-Key' => 'wrong-key']);
+
+		$this->assertForbidden($response);
+	}
+
+	public function testResultsInvalidPhotoId(): void
+	{
+		$response = $this->postJson('FaceDetection/results', [
+			'photo_id' => 'nonexistent_photo_id',
+			'status' => 'success',
+			'faces' => [],
+		], ['X-API-Key' => $this->api_key]);
+
+		$this->assertUnprocessable($response);
+	}
+
+	public function testResultsRescanPreservesPersonId(): void
+	{
+		// Create existing face with person
+		$person = Person::factory()->with_name('Alice')->create();
+		$existing_face = Face::factory()->for_photo($this->photo1)->for_person($person)->create([
+			'x' => 0.1,
+			'y' => 0.2,
+			'width' => 0.15,
+			'height' => 0.2,
+		]);
+
+		Photo::where('id', $this->photo1->id)->update(['face_scan_status' => FaceScanStatus::PENDING->value]);
+
+		// Re-scan with a face at the same location (high IoU)
+		$response = $this->postJson('FaceDetection/results', [
+			'photo_id' => $this->photo1->id,
+			'status' => 'success',
+			'faces' => [
+				[
+					'x' => 0.1,
+					'y' => 0.2,
+					'width' => 0.15,
+					'height' => 0.2,
+					'confidence' => 0.98,
+					'embedding_id' => 'emb_rescan_001',
+				],
+			],
+		], ['X-API-Key' => $this->api_key]);
+
+		$this->assertOk($response);
+
+		// New face should have inherited the person_id
+		$new_face = Face::where('photo_id', $this->photo1->id)->first();
+		self::assertNotNull($new_face);
+		self::assertEquals($person->id, $new_face->person_id);
+	}
+
+	// ── BULK SCAN ───────────────────────────────────────────────
+
+	public function testBulkScanAsAdmin(): void
+	{
+		Queue::fake();
+
+		$response = $this->actingAs($this->admin)->postJson('FaceDetection/bulk-scan');
+		$this->assertStatus($response, 202);
+	}
+
+	public function testBulkScanAsUserForbidden(): void
+	{
+		$response = $this->actingAs($this->userMayUpload1)->postJson('FaceDetection/bulk-scan');
+		$this->assertForbidden($response);
+	}
+
+	// ── CLUSTER RESULTS ─────────────────────────────────────────
+
+	public function testClusterResults(): void
+	{
+		$face1 = Face::factory()->for_photo($this->photo1)->create();
+		$face2 = Face::factory()->for_photo($this->photo1)->create();
+
+		$response = $this->postJson('FaceDetection/cluster-results', [
+			'labels' => [
+				['face_id' => $face1->id, 'cluster_label' => 1],
+				['face_id' => $face2->id, 'cluster_label' => 1],
+			],
+			'suggestions' => [
+				['face_id' => $face1->id, 'suggested_face_id' => $face2->id, 'confidence' => 0.9],
+			],
+		], ['X-API-Key' => $this->api_key]);
+
+		$this->assertStatus($response, 202);
+
+		// Verify cluster labels
+		$face1->refresh();
+		$face2->refresh();
+		self::assertEquals(1, $face1->cluster_label);
+		self::assertEquals(1, $face2->cluster_label);
+	}
+
+	public function testClusterResultsInvalidApiKey(): void
+	{
+		$response = $this->postJson('FaceDetection/cluster-results', [
+			'labels' => [],
+			'suggestions' => [],
+		], ['X-API-Key' => 'wrong-key']);
+
+		$this->assertForbidden($response);
+	}
+}
diff --git a/tests/Feature_v2/AiVision/FaceDismissTest.php b/tests/Feature_v2/AiVision/FaceDismissTest.php
new file mode 100644
index 00000000000..77bb16c34e3
--- /dev/null
+++ b/tests/Feature_v2/AiVision/FaceDismissTest.php
@@ -0,0 +1,116 @@
+<?php
+
+/**
+ * SPDX-License-Identifier: MIT
+ * Copyright (c) 2017-2018 Tobias Reich
+ * Copyright (c) 2018-2026 LycheeOrg.
+ */
+
+/**
+ * @noinspection PhpDocMissingThrowsInspection
+ * @noinspection PhpUnhandledExceptionInspection
+ */
+
+namespace Tests\Feature_v2\AiVision;
+
+use App\Models\Configs;
+use App\Models\Face;
+use Illuminate\Support\Facades\DB;
+use Tests\Feature_v2\Base\BaseApiWithDataTest;
+
+class FaceDismissTest extends BaseApiWithDataTest
+{
+	private Face $face1;
+	private Face $face2;
+
+	public function setUp(): void
+	{
+		parent::setUp();
+		$this->requireSe();
+
+		Configs::set('ai_vision_enabled', '1');
+		Configs::set('ai_vision_face_enabled', '1');
+		Configs::set('ai_vision_face_permission_mode', 'public');
+
+		$this->face1 = Face::factory()->for_photo($this->photo1)->create();
+		$this->face2 = Face::factory()->for_photo($this->photo1)->create();
+	}
+
+	public function tearDown(): void
+	{
+		DB::table('face_suggestions')->delete();
+		DB::table('faces')->delete();
+		DB::table('persons')->delete();
+		$this->resetSe();
+		parent::tearDown();
+	}
+
+	// ── TOGGLE DISMISSED ────────────────────────────────────────
+
+	public function testToggleDismissedByPhotoOwner(): void
+	{
+		$response = $this->actingAs($this->userMayUpload1)->patchJson('Face/' . $this->face1->id);
+		$this->assertOk($response);
+		self::assertTrue($response->json('is_dismissed'));
+
+		// Toggle back
+		$response = $this->actingAs($this->userMayUpload1)->patchJson('Face/' . $this->face1->id);
+		$this->assertOk($response);
+		self::assertFalse($response->json('is_dismissed'));
+	}
+
+	public function testToggleDismissedByNonOwnerForbidden(): void
+	{
+		$response = $this->actingAs($this->userMayUpload2)->patchJson('Face/' . $this->face1->id);
+		$this->assertForbidden($response);
+	}
+
+	public function testToggleDismissedByAdmin(): void
+	{
+		$response = $this->actingAs($this->admin)->patchJson('Face/' . $this->face1->id);
+		$this->assertOk($response);
+		self::assertTrue($response->json('is_dismissed'));
+	}
+
+	public function testToggleDismissedAsGuestUnauthorized(): void
+	{
+		$response = $this->patchJson('Face/' . $this->face1->id);
+		$this->assertUnauthorized($response);
+	}
+
+	// ── DESTROY DISMISSED ───────────────────────────────────────
+
+	public function testDestroyDismissedAsAdmin(): void
+	{
+		// Dismiss some faces first
+		$this->face1->is_dismissed = true;
+		$this->face1->save();
+
+		$response = $this->actingAs($this->admin)->deleteJson('Face/dismissed');
+		$this->assertOk($response);
+		self::assertEquals(1, $response->json('deleted_count'));
+
+		// face1 should be deleted, face2 should still exist
+		self::assertNull(Face::find($this->face1->id));
+		self::assertNotNull(Face::find($this->face2->id));
+	}
+
+	public function testDestroyDismissedAsUserForbidden(): void
+	{
+		$response = $this->actingAs($this->userMayUpload1)->deleteJson('Face/dismissed');
+		$this->assertForbidden($response);
+	}
+
+	public function testDestroyDismissedAsGuestUnauthorized(): void
+	{
+		$response = $this->deleteJson('Face/dismissed');
+		$this->assertUnauthorized($response);
+	}
+
+	public function testDestroyDismissedNoneToDelete(): void
+	{
+		$response = $this->actingAs($this->admin)->deleteJson('Face/dismissed');
+		$this->assertOk($response);
+		self::assertEquals(0, $response->json('deleted_count'));
+	}
+}
diff --git a/tests/Feature_v2/AiVision/MaintenanceResetStuckFacesTest.php b/tests/Feature_v2/AiVision/MaintenanceResetStuckFacesTest.php
new file mode 100644
index 00000000000..bde05340ee2
--- /dev/null
+++ b/tests/Feature_v2/AiVision/MaintenanceResetStuckFacesTest.php
@@ -0,0 +1,143 @@
+<?php
+
+/**
+ * SPDX-License-Identifier: MIT
+ * Copyright (c) 2017-2018 Tobias Reich
+ * Copyright (c) 2018-2026 LycheeOrg.
+ */
+
+/**
+ * @noinspection PhpDocMissingThrowsInspection
+ * @noinspection PhpUnhandledExceptionInspection
+ */
+
+namespace Tests\Feature_v2\AiVision;
+
+use App\Enum\FaceScanStatus;
+use App\Models\Photo;
+use Illuminate\Support\Carbon;
+use Illuminate\Support\Facades\DB;
+use Tests\Feature_v2\Base\BaseApiWithDataTest;
+
+class MaintenanceResetStuckFacesTest extends BaseApiWithDataTest
+{
+	public function setUp(): void
+	{
+		parent::setUp();
+	}
+
+	public function tearDown(): void
+	{
+		DB::table('face_suggestions')->delete();
+		DB::table('faces')->delete();
+		DB::table('persons')->delete();
+		parent::tearDown();
+	}
+
+	// ── CHECK (GET) ─────────────────────────────────────────────
+
+	public function testCheckAsGuest(): void
+	{
+		$response = $this->getJson('Maintenance::resetStuckFaces');
+		$this->assertUnauthorized($response);
+	}
+
+	public function testCheckAsUser(): void
+	{
+		$response = $this->actingAs($this->userMayUpload1)->getJson('Maintenance::resetStuckFaces');
+		$this->assertForbidden($response);
+	}
+
+	public function testCheckAsAdmin(): void
+	{
+		// Create a stuck pending photo
+		Photo::where('id', $this->photo1->id)->update([
+			'face_scan_status' => FaceScanStatus::PENDING,
+			'updated_at' => Carbon::now()->subMinutes(800),
+		]);
+
+		$response = $this->actingAs($this->admin)->getJson('Maintenance::resetStuckFaces');
+		$this->assertOk($response);
+
+		$count = $response->json();
+		self::assertGreaterThanOrEqual(1, $count);
+	}
+
+	public function testCheckReturnsZeroWhenNoneStuck(): void
+	{
+		$response = $this->actingAs($this->admin)->getJson('Maintenance::resetStuckFaces');
+		$this->assertOk($response);
+		self::assertEquals(0, $response->json());
+	}
+
+	// ── DO (POST) ───────────────────────────────────────────────
+
+	public function testDoAsGuest(): void
+	{
+		$response = $this->postJson('Maintenance::resetStuckFaces');
+		$this->assertUnauthorized($response);
+	}
+
+	public function testDoAsUser(): void
+	{
+		$response = $this->actingAs($this->userMayUpload1)->postJson('Maintenance::resetStuckFaces');
+		$this->assertForbidden($response);
+	}
+
+	public function testDoAsAdmin(): void
+	{
+		// Create a stuck pending photo (older than default threshold)
+		Photo::where('id', $this->photo1->id)->update([
+			'face_scan_status' => FaceScanStatus::PENDING,
+			'updated_at' => Carbon::now()->subMinutes(800),
+		]);
+
+		$response = $this->actingAs($this->admin)->postJson('Maintenance::resetStuckFaces');
+		$this->assertOk($response);
+		self::assertGreaterThanOrEqual(1, $response->json('reset_count'));
+
+		// Photo should be reset to null
+		$this->photo1->refresh();
+		self::assertNull($this->photo1->face_scan_status);
+	}
+
+	public function testDoWithCustomThreshold(): void
+	{
+		// Set pending photo that is 30 minutes old
+		Photo::where('id', $this->photo1->id)->update([
+			'face_scan_status' => FaceScanStatus::PENDING,
+			'updated_at' => Carbon::now()->subMinutes(30),
+		]);
+
+		// Default threshold is 720 min (12h), so this should NOT be reset
+		$response = $this->actingAs($this->admin)->postJson('Maintenance::resetStuckFaces');
+		$this->assertOk($response);
+		self::assertEquals(0, $response->json('reset_count'));
+
+		// With a custom threshold of 15 minutes, it SHOULD be reset
+		$response = $this->actingAs($this->admin)->postJson('Maintenance::resetStuckFaces', [
+			'older_than_minutes' => 15,
+		]);
+		$this->assertOk($response);
+		self::assertGreaterThanOrEqual(1, $response->json('reset_count'));
+	}
+
+	public function testDoDoesNotResetRecentPending(): void
+	{
+		// Set pending photo that is recent (5 minutes)
+		Photo::where('id', $this->photo1->id)->update([
+			'face_scan_status' => FaceScanStatus::PENDING,
+			'updated_at' => Carbon::now()->subMinutes(5),
+		]);
+
+		$response = $this->actingAs($this->admin)->postJson('Maintenance::resetStuckFaces', [
+			'older_than_minutes' => 60,
+		]);
+		$this->assertOk($response);
+		self::assertEquals(0, $response->json('reset_count'));
+
+		// Photo should still be pending
+		$this->photo1->refresh();
+		self::assertEquals(FaceScanStatus::PENDING, $this->photo1->face_scan_status);
+	}
+}
diff --git a/tests/Feature_v2/AiVision/PeopleControllerTest.php b/tests/Feature_v2/AiVision/PeopleControllerTest.php
new file mode 100644
index 00000000000..3e18999ad4b
--- /dev/null
+++ b/tests/Feature_v2/AiVision/PeopleControllerTest.php
@@ -0,0 +1,223 @@
+<?php
+
+/**
+ * SPDX-License-Identifier: MIT
+ * Copyright (c) 2017-2018 Tobias Reich
+ * Copyright (c) 2018-2026 LycheeOrg.
+ */
+
+/**
+ * @noinspection PhpDocMissingThrowsInspection
+ * @noinspection PhpUnhandledExceptionInspection
+ */
+
+namespace Tests\Feature_v2\AiVision;
+
+use App\Models\Configs;
+use App\Models\Face;
+use App\Models\Person;
+use Illuminate\Support\Facades\DB;
+use Tests\Feature_v2\Base\BaseApiWithDataTest;
+
+class PeopleControllerTest extends BaseApiWithDataTest
+{
+	private Person $person1;
+	private Person $person2;
+	private Person $personHidden;
+
+	public function setUp(): void
+	{
+		parent::setUp();
+		$this->requireSe();
+
+		Configs::set('ai_vision_enabled', '1');
+		Configs::set('ai_vision_face_enabled', '1');
+		Configs::set('ai_vision_face_permission_mode', 'public');
+
+		$this->person1 = Person::factory()->with_name('Alice')->create();
+		$this->person2 = Person::factory()->with_name('Bob')->create();
+		$this->personHidden = Person::factory()->with_name('Hidden')->not_searchable()->create();
+	}
+
+	public function tearDown(): void
+	{
+		DB::table('face_suggestions')->delete();
+		DB::table('faces')->delete();
+		DB::table('persons')->delete();
+		$this->resetSe();
+		parent::tearDown();
+	}
+
+	// ── INDEX ───────────────────────────────────────────────────
+
+	public function testIndexAsGuest(): void
+	{
+		$response = $this->getJson('People');
+		$this->assertOk($response);
+
+		// Guest should see searchable persons but not hidden
+		$names = collect($response->json('data'))->pluck('name')->all();
+		self::assertContains('Alice', $names);
+		self::assertContains('Bob', $names);
+		self::assertNotContains('Hidden', $names);
+	}
+
+	public function testIndexAsAdmin(): void
+	{
+		$response = $this->actingAs($this->admin)->getJson('People');
+		$this->assertOk($response);
+
+		// Admin sees all including non-searchable
+		$names = collect($response->json('data'))->pluck('name')->all();
+		self::assertContains('Alice', $names);
+		self::assertContains('Hidden', $names);
+	}
+
+	public function testIndexLinkedUserSeesOwnHiddenPerson(): void
+	{
+		$this->personHidden->user_id = $this->userMayUpload1->id;
+		$this->personHidden->save();
+
+		$response = $this->actingAs($this->userMayUpload1)->getJson('People');
+		$this->assertOk($response);
+
+		$names = collect($response->json('data'))->pluck('name')->all();
+		self::assertContains('Hidden', $names);
+	}
+
+	public function testIndexRestrictedMode(): void
+	{
+		Configs::set('ai_vision_face_permission_mode', 'restricted');
+
+		// Guest should be forbidden
+		$response = $this->getJson('People');
+		$this->assertForbidden($response);
+
+		// Admin still sees all
+		$response = $this->actingAs($this->admin)->getJson('People');
+		$this->assertOk($response);
+	}
+
+	// ── SHOW ────────────────────────────────────────────────────
+
+	public function testShowPerson(): void
+	{
+		$response = $this->actingAs($this->admin)->getJson('Person/' . $this->person1->id);
+		$this->assertOk($response);
+		self::assertEquals('Alice', $response->json('name'));
+		self::assertArrayHasKey('face_count', $response->json());
+		self::assertArrayHasKey('photo_count', $response->json());
+	}
+
+	public function testShowNonSearchablePersonAsGuestForbidden(): void
+	{
+		$response = $this->getJson('Person/' . $this->personHidden->id);
+		$this->assertForbidden($response);
+	}
+
+	public function testShowNonExistentPerson(): void
+	{
+		$response = $this->actingAs($this->admin)->getJson('Person/nonexistent_id_12345');
+		$this->assertNotFound($response);
+	}
+
+	// ── STORE ───────────────────────────────────────────────────
+
+	public function testStoreAsGuest(): void
+	{
+		$response = $this->postJson('Person', ['name' => 'Charlie']);
+		// In public mode, logged users can create; guests cannot (no auth)
+		$this->assertUnauthorized($response);
+	}
+
+	public function testStoreAsUser(): void
+	{
+		$response = $this->actingAs($this->userMayUpload1)->postJson('Person', ['name' => 'Charlie']);
+		$this->assertOk($response);
+		self::assertEquals('Charlie', $response->json('name'));
+		self::assertTrue($response->json('is_searchable'));
+	}
+
+	public function testStoreValidationRequiresName(): void
+	{
+		$response = $this->actingAs($this->admin)->postJson('Person', []);
+		$this->assertUnprocessable($response);
+	}
+
+	public function testStoreRestrictedModeAsUser(): void
+	{
+		Configs::set('ai_vision_face_permission_mode', 'restricted');
+
+		$response = $this->actingAs($this->userMayUpload1)->postJson('Person', ['name' => 'Charlie']);
+		$this->assertForbidden($response);
+
+		// Admin can still create
+		$response = $this->actingAs($this->admin)->postJson('Person', ['name' => 'Charlie']);
+		$this->assertOk($response);
+	}
+
+	// ── UPDATE ──────────────────────────────────────────────────
+
+	public function testUpdateName(): void
+	{
+		$response = $this->actingAs($this->admin)->patchJson('Person/' . $this->person1->id, [
+			'name' => 'Alice Updated',
+		]);
+		$this->assertOk($response);
+		self::assertEquals('Alice Updated', $response->json('name'));
+	}
+
+	public function testUpdateSearchability(): void
+	{
+		$response = $this->actingAs($this->admin)->patchJson('Person/' . $this->person1->id, [
+			'is_searchable' => false,
+		]);
+		$this->assertOk($response);
+		self::assertFalse($response->json('is_searchable'));
+	}
+
+	public function testUpdateAsGuestUnauthorized(): void
+	{
+		$response = $this->patchJson('Person/' . $this->person1->id, ['name' => 'Hacker']);
+		$this->assertUnauthorized($response);
+	}
+
+	// ── DESTROY ─────────────────────────────────────────────────
+
+	public function testDestroyNullifiesFaces(): void
+	{
+		$face = Face::factory()->for_photo($this->photo1)->for_person($this->person1)->create();
+
+		$response = $this->actingAs($this->admin)->deleteJson('Person/' . $this->person1->id, [
+			'person_id' => $this->person1->id,
+		]);
+		$this->assertNoContent($response);
+
+		self::assertNull(Person::find($this->person1->id));
+
+		$face->refresh();
+		self::assertNull($face->person_id);
+	}
+
+	public function testDestroyAsGuestUnauthorized(): void
+	{
+		$response = $this->deleteJson('Person/' . $this->person1->id, [
+			'person_id' => $this->person1->id,
+		]);
+		$this->assertUnauthorized($response);
+	}
+
+	// ── HIDDEN FACE COUNT ───────────────────────────────────────
+
+	public function testHiddenFaceCountInPhotoResponse(): void
+	{
+		Face::factory()->for_photo($this->photo1)->for_person($this->person1)->create();
+		Face::factory()->for_photo($this->photo1)->for_person($this->personHidden)->create();
+
+		// The photo detail should include hidden_face_count for non-admin
+		// This is tested through the PhotoResource integration
+		$response = $this->actingAs($this->admin)->getJson('Person/' . $this->person1->id);
+		$this->assertOk($response);
+		self::assertGreaterThanOrEqual(1, $response->json('face_count'));
+	}
+}
diff --git a/tests/Feature_v2/AiVision/PersonClaimTest.php b/tests/Feature_v2/AiVision/PersonClaimTest.php
new file mode 100644
index 00000000000..636d1bb20b8
--- /dev/null
+++ b/tests/Feature_v2/AiVision/PersonClaimTest.php
@@ -0,0 +1,187 @@
+<?php
+
+/**
+ * SPDX-License-Identifier: MIT
+ * Copyright (c) 2017-2018 Tobias Reich
+ * Copyright (c) 2018-2026 LycheeOrg.
+ */
+
+/**
+ * @noinspection PhpDocMissingThrowsInspection
+ * @noinspection PhpUnhandledExceptionInspection
+ */
+
+namespace Tests\Feature_v2\AiVision;
+
+use App\Models\Configs;
+use App\Models\Person;
+use Illuminate\Support\Facades\DB;
+use Tests\Feature_v2\Base\BaseApiWithDataTest;
+
+class PersonClaimTest extends BaseApiWithDataTest
+{
+	private Person $person1;
+	private Person $person2;
+
+	public function setUp(): void
+	{
+		parent::setUp();
+		$this->requireSe();
+
+		Configs::set('ai_vision_enabled', '1');
+		Configs::set('ai_vision_face_enabled', '1');
+		Configs::set('ai_vision_face_permission_mode', 'public');
+		Configs::set('ai_vision_face_allow_user_claim', '1');
+
+		$this->person1 = Person::factory()->with_name('Alice')->create();
+		$this->person2 = Person::factory()->with_name('Bob')->create();
+	}
+
+	public function tearDown(): void
+	{
+		DB::table('face_suggestions')->delete();
+		DB::table('faces')->delete();
+		DB::table('persons')->delete();
+		$this->resetSe();
+		parent::tearDown();
+	}
+
+	// ── CLAIM ───────────────────────────────────────────────────
+
+	public function testClaimSuccess(): void
+	{
+		$response = $this->actingAs($this->userMayUpload1)->postJson('Person/' . $this->person1->id . '/claim');
+		$this->assertOk($response);
+		self::assertEquals($this->userMayUpload1->id, $response->json('user_id'));
+	}
+
+	public function testClaimAlreadyClaimedByAnotherUserConflict(): void
+	{
+		$this->person1->user_id = $this->userMayUpload2->id;
+		$this->person1->save();
+
+		$response = $this->actingAs($this->userMayUpload1)->postJson('Person/' . $this->person1->id . '/claim');
+		$this->assertConflict($response);
+	}
+
+	public function testClaimAlreadyHaveDifferentPersonConflict(): void
+	{
+		// User already has person1 claimed
+		$this->person1->user_id = $this->userMayUpload1->id;
+		$this->person1->save();
+
+		// Trying to claim person2 should conflict
+		$response = $this->actingAs($this->userMayUpload1)->postJson('Person/' . $this->person2->id . '/claim');
+		$this->assertConflict($response);
+	}
+
+	public function testAdminForceClaim(): void
+	{
+		// Person1 is already claimed by userMayUpload2
+		$this->person1->user_id = $this->userMayUpload2->id;
+		$this->person1->save();
+
+		// Admin can override existing claim
+		$response = $this->actingAs($this->admin)->postJson('Person/' . $this->person1->id . '/claim');
+		$this->assertOk($response);
+		self::assertEquals($this->admin->id, $response->json('user_id'));
+	}
+
+	public function testClaimAsGuestUnauthorized(): void
+	{
+		$response = $this->postJson('Person/' . $this->person1->id . '/claim');
+		$this->assertUnauthorized($response);
+	}
+
+	public function testClaimDisabledForNonAdmin(): void
+	{
+		Configs::set('ai_vision_face_allow_user_claim', '0');
+
+		$response = $this->actingAs($this->userMayUpload1)->postJson('Person/' . $this->person1->id . '/claim');
+		$this->assertForbidden($response);
+
+		// Admin still can claim
+		$response = $this->actingAs($this->admin)->postJson('Person/' . $this->person1->id . '/claim');
+		$this->assertOk($response);
+	}
+
+	// ── UNCLAIM ─────────────────────────────────────────────────
+
+	public function testUnclaim(): void
+	{
+		$this->person1->user_id = $this->userMayUpload1->id;
+		$this->person1->save();
+
+		$response = $this->actingAs($this->userMayUpload1)->deleteJson('Person/' . $this->person1->id . '/claim');
+		$this->assertNoContent($response);
+
+		$this->person1->refresh();
+		self::assertNull($this->person1->user_id);
+	}
+
+	public function testUnclaimOtherUserForbidden(): void
+	{
+		$this->person1->user_id = $this->userMayUpload1->id;
+		$this->person1->save();
+
+		$response = $this->actingAs($this->userMayUpload2)->deleteJson('Person/' . $this->person1->id . '/claim');
+		$this->assertForbidden($response);
+	}
+
+	public function testAdminCanUnclaim(): void
+	{
+		$this->person1->user_id = $this->userMayUpload1->id;
+		$this->person1->save();
+
+		$response = $this->actingAs($this->admin)->deleteJson('Person/' . $this->person1->id . '/claim');
+		$this->assertNoContent($response);
+
+		$this->person1->refresh();
+		self::assertNull($this->person1->user_id);
+	}
+
+	// ── MERGE ───────────────────────────────────────────────────
+
+	public function testMerge(): void
+	{
+		$face = \App\Models\Face::factory()->for_photo($this->photo1)->for_person($this->person2)->create();
+
+		$response = $this->actingAs($this->admin)->postJson('Person/' . $this->person1->id . '/merge', [
+			'source_person_id' => $this->person2->id,
+		]);
+		$this->assertOk($response);
+
+		// Source person deleted
+		self::assertNull(Person::find($this->person2->id));
+
+		// Face reassigned to target
+		$face->refresh();
+		self::assertEquals($this->person1->id, $face->person_id);
+	}
+
+	public function testMergeAsGuestUnauthorized(): void
+	{
+		$response = $this->postJson('Person/' . $this->person1->id . '/merge', [
+			'source_person_id' => $this->person2->id,
+		]);
+		$this->assertUnauthorized($response);
+	}
+
+	public function testMergeRestrictedAsUserForbidden(): void
+	{
+		Configs::set('ai_vision_face_permission_mode', 'restricted');
+
+		$response = $this->actingAs($this->userMayUpload1)->postJson('Person/' . $this->person1->id . '/merge', [
+			'source_person_id' => $this->person2->id,
+		]);
+		$this->assertForbidden($response);
+	}
+
+	public function testMergeInvalidSourcePerson(): void
+	{
+		$response = $this->actingAs($this->admin)->postJson('Person/' . $this->person1->id . '/merge', [
+			'source_person_id' => 'nonexistent_12345678',
+		]);
+		$this->assertUnprocessable($response);
+	}
+}
diff --git a/tests/Feature_v2/AiVision/PersonPhotosTest.php b/tests/Feature_v2/AiVision/PersonPhotosTest.php
new file mode 100644
index 00000000000..e52985c5515
--- /dev/null
+++ b/tests/Feature_v2/AiVision/PersonPhotosTest.php
@@ -0,0 +1,82 @@
+<?php
+
+/**
+ * SPDX-License-Identifier: MIT
+ * Copyright (c) 2017-2018 Tobias Reich
+ * Copyright (c) 2018-2026 LycheeOrg.
+ */
+
+/**
+ * @noinspection PhpDocMissingThrowsInspection
+ * @noinspection PhpUnhandledExceptionInspection
+ */
+
+namespace Tests\Feature_v2\AiVision;
+
+use App\Models\Configs;
+use App\Models\Face;
+use App\Models\Person;
+use Illuminate\Support\Facades\DB;
+use Tests\Feature_v2\Base\BaseApiWithDataTest;
+
+class PersonPhotosTest extends BaseApiWithDataTest
+{
+	private Person $person1;
+
+	public function setUp(): void
+	{
+		parent::setUp();
+		$this->requireSe();
+
+		Configs::set('ai_vision_enabled', '1');
+		Configs::set('ai_vision_face_enabled', '1');
+		Configs::set('ai_vision_face_permission_mode', 'public');
+
+		$this->person1 = Person::factory()->with_name('Alice')->create();
+	}
+
+	public function tearDown(): void
+	{
+		DB::table('face_suggestions')->delete();
+		DB::table('faces')->delete();
+		DB::table('persons')->delete();
+		$this->resetSe();
+		parent::tearDown();
+	}
+
+	public function testListPhotosForPerson(): void
+	{
+		Face::factory()->for_photo($this->photo1)->for_person($this->person1)->create();
+
+		$response = $this->actingAs($this->admin)->getJson('Person/' . $this->person1->id . '/photos');
+		$this->assertOk($response);
+
+		$photo_ids = collect($response->json('data'))->pluck('id')->all();
+		self::assertContains($this->photo1->id, $photo_ids);
+	}
+
+	public function testEmptyResultForPersonWithNoFaces(): void
+	{
+		$response = $this->actingAs($this->admin)->getJson('Person/' . $this->person1->id . '/photos');
+		$this->assertOk($response);
+		self::assertEmpty($response->json('data'));
+	}
+
+	public function testNonSearchablePersonForbiddenForNonOwner(): void
+	{
+		$hidden = Person::factory()->not_searchable()->create();
+
+		$response = $this->actingAs($this->userMayUpload1)->getJson('Person/' . $hidden->id . '/photos');
+		$this->assertForbidden($response);
+	}
+
+	public function testAdminCanViewPhotosOfNonSearchablePerson(): void
+	{
+		$hidden = Person::factory()->not_searchable()->create();
+		Face::factory()->for_photo($this->photo1)->for_person($hidden)->create();
+
+		$response = $this->actingAs($this->admin)->getJson('Person/' . $hidden->id . '/photos');
+		$this->assertOk($response);
+		self::assertNotEmpty($response->json('data'));
+	}
+}
diff --git a/tests/Feature_v2/AiVision/ScanFacesCommandTest.php b/tests/Feature_v2/AiVision/ScanFacesCommandTest.php
new file mode 100644
index 00000000000..49ce707ae47
--- /dev/null
+++ b/tests/Feature_v2/AiVision/ScanFacesCommandTest.php
@@ -0,0 +1,89 @@
+<?php
+
+/**
+ * SPDX-License-Identifier: MIT
+ * Copyright (c) 2017-2018 Tobias Reich
+ * Copyright (c) 2018-2026 LycheeOrg.
+ */
+
+/**
+ * @noinspection PhpDocMissingThrowsInspection
+ * @noinspection PhpUnhandledExceptionInspection
+ */
+
+namespace Tests\Feature_v2\AiVision;
+
+use App\Enum\FaceScanStatus;
+use App\Models\Photo;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Queue;
+use Tests\Feature_v2\Base\BaseApiWithDataTest;
+
+class ScanFacesCommandTest extends BaseApiWithDataTest
+{
+	public function setUp(): void
+	{
+		parent::setUp();
+	}
+
+	public function tearDown(): void
+	{
+		DB::table('face_suggestions')->delete();
+		DB::table('faces')->delete();
+		DB::table('persons')->delete();
+		parent::tearDown();
+	}
+
+	public function testCommandEnqueuesUnscannedPhotos(): void
+	{
+		Queue::fake();
+
+		// Ensure photo1 is unscanned (null status)
+		Photo::where('id', $this->photo1->id)->update(['face_scan_status' => null]);
+
+		$this->artisan('lychee:scan-faces')
+			->expectsOutputToContain('Dispatched')
+			->assertExitCode(0);
+
+		// Photo should now be pending
+		$this->photo1->refresh();
+		self::assertEquals(FaceScanStatus::PENDING, $this->photo1->face_scan_status);
+	}
+
+	public function testCommandSkipsAlreadyScanned(): void
+	{
+		Queue::fake();
+
+		// Mark photo as completed
+		Photo::where('id', $this->photo1->id)->update(['face_scan_status' => FaceScanStatus::COMPLETED->value]);
+
+		$this->artisan('lychee:scan-faces')
+			->expectsOutputToContain('Dispatched')
+			->assertExitCode(0);
+
+		// Should still be completed (not re-queued)
+		$this->photo1->refresh();
+		self::assertEquals(FaceScanStatus::COMPLETED, $this->photo1->face_scan_status);
+	}
+
+	public function testCommandWithAlbumFilter(): void
+	{
+		Queue::fake();
+
+		// Ensure photos are unscanned
+		Photo::where('id', $this->photo1->id)->update(['face_scan_status' => null]);
+		Photo::where('id', $this->photo2->id)->update(['face_scan_status' => null]);
+
+		$this->artisan('lychee:scan-faces', ['--album' => $this->album1->id])
+			->expectsOutputToContain('Dispatched')
+			->assertExitCode(0);
+
+		// photo1 is in album1 — should be pending
+		$this->photo1->refresh();
+		self::assertEquals(FaceScanStatus::PENDING, $this->photo1->face_scan_status);
+
+		// photo2 is in album2 — should still be null
+		$this->photo2->refresh();
+		self::assertNull($this->photo2->face_scan_status);
+	}
+}
diff --git a/tests/Feature_v2/AiVision/SelfieClaimTest.php b/tests/Feature_v2/AiVision/SelfieClaimTest.php
new file mode 100644
index 00000000000..957d72ab2a8
--- /dev/null
+++ b/tests/Feature_v2/AiVision/SelfieClaimTest.php
@@ -0,0 +1,142 @@
+<?php
+
+/**
+ * SPDX-License-Identifier: MIT
+ * Copyright (c) 2017-2018 Tobias Reich
+ * Copyright (c) 2018-2026 LycheeOrg.
+ */
+
+/**
+ * @noinspection PhpDocMissingThrowsInspection
+ * @noinspection PhpUnhandledExceptionInspection
+ */
+
+namespace Tests\Feature_v2\AiVision;
+
+use App\Models\Configs;
+use App\Models\Person;
+use Illuminate\Http\UploadedFile;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Http;
+use Tests\Feature_v2\Base\BaseApiWithDataTest;
+
+class SelfieClaimTest extends BaseApiWithDataTest
+{
+	private Person $person1;
+
+	public function setUp(): void
+	{
+		parent::setUp();
+		$this->requireSe();
+
+		Configs::set('ai_vision_enabled', '1');
+		Configs::set('ai_vision_face_enabled', '1');
+		Configs::set('ai_vision_face_permission_mode', 'public');
+		Configs::set('ai_vision_face_allow_user_claim', '1');
+		Configs::set('ai_vision_face_selfie_confidence_threshold', '0.8');
+
+		config(['features.ai-vision.face-url' => 'http://fake-vision-service:8000']);
+		config(['features.ai-vision.face-api-key' => 'test-api-key']);
+
+		$this->person1 = Person::factory()->with_name('Alice')->create();
+	}
+
+	public function tearDown(): void
+	{
+		DB::table('face_suggestions')->delete();
+		DB::table('faces')->delete();
+		DB::table('persons')->delete();
+		$this->resetSe();
+		parent::tearDown();
+	}
+
+	public function testSelfieClaimSuccess(): void
+	{
+		Http::fake([
+			'fake-vision-service:8000/match' => Http::response([
+				'matches' => [
+					[
+						'lychee_face_id' => 'some_face_id',
+						'person_id' => $this->person1->id,
+						'confidence' => 0.95,
+					],
+				],
+			], 200),
+		]);
+
+		$selfie = UploadedFile::fake()->image('selfie.jpg', 200, 200);
+
+		$response = $this->actingAs($this->userMayUpload1)->post(
+			self::API_PREFIX . 'Person/claim-by-selfie',
+			['selfie' => $selfie],
+			['CONTENT_TYPE' => 'multipart/form-data', 'Accept' => 'application/json']
+		);
+
+		$this->assertOk($response);
+		self::assertEquals($this->person1->id, $response->json('id'));
+
+		// Verify person is now linked to user
+		$this->person1->refresh();
+		self::assertEquals($this->userMayUpload1->id, $this->person1->user_id);
+	}
+
+	public function testSelfieClaimNoFaceDetected(): void
+	{
+		Http::fake([
+			'fake-vision-service:8000/match' => Http::response([
+				'matches' => [],
+			], 200),
+		]);
+
+		$selfie = UploadedFile::fake()->image('selfie.jpg', 200, 200);
+
+		$response = $this->actingAs($this->userMayUpload1)->post(
+			self::API_PREFIX . 'Person/claim-by-selfie',
+			['selfie' => $selfie],
+			['CONTENT_TYPE' => 'multipart/form-data', 'Accept' => 'application/json']
+		);
+
+		$this->assertNotFound($response);
+	}
+
+	public function testSelfieClaimAlreadyClaimed(): void
+	{
+		$this->person1->user_id = $this->userMayUpload2->id;
+		$this->person1->save();
+
+		Http::fake([
+			'fake-vision-service:8000/match' => Http::response([
+				'matches' => [
+					[
+						'lychee_face_id' => 'some_face_id',
+						'person_id' => $this->person1->id,
+						'confidence' => 0.95,
+					],
+				],
+			], 200),
+		]);
+
+		$selfie = UploadedFile::fake()->image('selfie.jpg', 200, 200);
+
+		$response = $this->actingAs($this->userMayUpload1)->post(
+			self::API_PREFIX . 'Person/claim-by-selfie',
+			['selfie' => $selfie],
+			['CONTENT_TYPE' => 'multipart/form-data', 'Accept' => 'application/json']
+		);
+
+		$this->assertConflict($response);
+	}
+
+	public function testSelfieClaimAsGuestUnauthorized(): void
+	{
+		$selfie = UploadedFile::fake()->image('selfie.jpg', 200, 200);
+
+		$response = $this->post(
+			self::API_PREFIX . 'Person/claim-by-selfie',
+			['selfie' => $selfie],
+			['CONTENT_TYPE' => 'multipart/form-data', 'Accept' => 'application/json']
+		);
+
+		$this->assertUnauthorized($response);
+	}
+}
diff --git a/tests/LoadedSubscriber.php b/tests/LoadedSubscriber.php
index ea23cd7c4db..3abea29b8ac 100644
--- a/tests/LoadedSubscriber.php
+++ b/tests/LoadedSubscriber.php
@@ -30,8 +30,15 @@ public function notify(Loaded $event): void
 		app()->singleton(ConfigManager::class, fn () => new ConfigManager());
 
 		// If there are any users in the DB, this tends to crash some tests (because we check exact count of users).
+		// Disable FK checks and clean all related tables to avoid constraint violations.
 		if (User::query()->count() > 0) {
+			$db = \Illuminate\Support\Facades\DB::getFacadeRoot();
+			$db::statement('PRAGMA foreign_keys = OFF');
+			$db::table('face_suggestions')->delete();
+			$db::table('faces')->delete();
+			$db::table('persons')->delete();
 			User::truncate();
+			$db::statement('PRAGMA foreign_keys = ON');
 		}
 
 		HandleExceptions::flushState();
diff --git a/tests/Unit/Models/FaceTest.php b/tests/Unit/Models/FaceTest.php
new file mode 100644
index 00000000000..a85a113e5ec
--- /dev/null
+++ b/tests/Unit/Models/FaceTest.php
@@ -0,0 +1,129 @@
+<?php
+
+/**
+ * SPDX-License-Identifier: MIT
+ * Copyright (c) 2017-2018 Tobias Reich
+ * Copyright (c) 2018-2026 LycheeOrg.
+ */
+
+/**
+ * @noinspection PhpDocMissingThrowsInspection
+ * @noinspection PhpUnhandledExceptionInspection
+ */
+
+namespace Tests\Unit\Models;
+
+use App\Models\Face;
+use App\Models\Person;
+use App\Models\Photo;
+use App\Models\User;
+use Illuminate\Foundation\Testing\DatabaseTransactions;
+use Tests\AbstractTestCase;
+
+class FaceTest extends AbstractTestCase
+{
+	use DatabaseTransactions;
+
+	public function testFacePhotoRelationship(): void
+	{
+		$user = User::factory()->may_upload()->create();
+		$photo = Photo::factory()->owned_by($user)->create();
+		$face = Face::factory()->for_photo($photo)->create();
+
+		self::assertNotNull($face->photo);
+		self::assertEquals($photo->id, $face->photo->id);
+	}
+
+	public function testFacePersonRelationship(): void
+	{
+		$user = User::factory()->may_upload()->create();
+		$photo = Photo::factory()->owned_by($user)->create();
+		$person = Person::factory()->create();
+		$face = Face::factory()->for_photo($photo)->for_person($person)->create();
+
+		self::assertNotNull($face->person);
+		self::assertEquals($person->id, $face->person->id);
+	}
+
+	public function testFaceNullablePersonRelationship(): void
+	{
+		$user = User::factory()->may_upload()->create();
+		$photo = Photo::factory()->owned_by($user)->create();
+		$face = Face::factory()->for_photo($photo)->create();
+
+		self::assertNull($face->person);
+		self::assertNull($face->person_id);
+	}
+
+	public function testBoundingBoxValidation(): void
+	{
+		$user = User::factory()->may_upload()->create();
+		$photo = Photo::factory()->owned_by($user)->create();
+		$face = Face::factory()->for_photo($photo)->create();
+
+		self::assertIsFloat($face->x);
+		self::assertIsFloat($face->y);
+		self::assertIsFloat($face->width);
+		self::assertIsFloat($face->height);
+		self::assertGreaterThanOrEqual(0.0, $face->x);
+		self::assertLessThanOrEqual(1.0, $face->x);
+		self::assertGreaterThanOrEqual(0.0, $face->y);
+		self::assertLessThanOrEqual(1.0, $face->y);
+	}
+
+	public function testCropUrlAccessorWithToken(): void
+	{
+		$user = User::factory()->may_upload()->create();
+		$photo = Photo::factory()->owned_by($user)->create();
+		$face = Face::factory()->for_photo($photo)->create();
+
+		$tok = $face->crop_token;
+		self::assertNotNull($face->crop_url);
+		self::assertEquals(
+			'uploads/faces/' . substr($tok, 0, 2) . '/' . substr($tok, 2, 2) . '/' . $tok . '.jpg',
+			$face->crop_url
+		);
+	}
+
+	public function testCropUrlAccessorWithoutToken(): void
+	{
+		$user = User::factory()->may_upload()->create();
+		$photo = Photo::factory()->owned_by($user)->create();
+		$face = Face::factory()->for_photo($photo)->without_crop()->create();
+
+		self::assertNull($face->crop_url);
+	}
+
+	public function testDismissedCast(): void
+	{
+		$user = User::factory()->may_upload()->create();
+		$photo = Photo::factory()->owned_by($user)->create();
+		$face = Face::factory()->for_photo($photo)->create();
+
+		self::assertIsBool($face->is_dismissed);
+		self::assertFalse($face->is_dismissed);
+
+		$dismissed = Face::factory()->for_photo($photo)->dismissed()->create();
+		self::assertTrue($dismissed->is_dismissed);
+	}
+
+	public function testClusterLabelCast(): void
+	{
+		$user = User::factory()->may_upload()->create();
+		$photo = Photo::factory()->owned_by($user)->create();
+		$face = Face::factory()->for_photo($photo)->with_cluster(5)->create();
+
+		self::assertIsInt($face->cluster_label);
+		self::assertEquals(5, $face->cluster_label);
+	}
+
+	public function testConfidenceCast(): void
+	{
+		$user = User::factory()->may_upload()->create();
+		$photo = Photo::factory()->owned_by($user)->create();
+		$face = Face::factory()->for_photo($photo)->with_confidence(0.95)->create();
+
+		self::assertIsFloat($face->confidence);
+		self::assertEqualsWithDelta(0.95, $face->confidence, 0.001);
+	}
+}
diff --git a/tests/Unit/Models/PersonTest.php b/tests/Unit/Models/PersonTest.php
new file mode 100644
index 00000000000..0b1e8669740
--- /dev/null
+++ b/tests/Unit/Models/PersonTest.php
@@ -0,0 +1,117 @@
+<?php
+
+/**
+ * SPDX-License-Identifier: MIT
+ * Copyright (c) 2017-2018 Tobias Reich
+ * Copyright (c) 2018-2026 LycheeOrg.
+ */
+
+/**
+ * @noinspection PhpDocMissingThrowsInspection
+ * @noinspection PhpUnhandledExceptionInspection
+ */
+
+namespace Tests\Unit\Models;
+
+use App\Models\Face;
+use App\Models\Person;
+use App\Models\Photo;
+use App\Models\User;
+use Illuminate\Foundation\Testing\DatabaseTransactions;
+use Tests\AbstractTestCase;
+
+class PersonTest extends AbstractTestCase
+{
+	use DatabaseTransactions;
+
+	public function testPersonUserRelationship(): void
+	{
+		$user = User::factory()->may_upload()->create();
+		$person = Person::factory()->linked_to($user)->create();
+
+		self::assertNotNull($person->user);
+		self::assertEquals($user->id, $person->user->id);
+	}
+
+	public function testPersonFacesRelationship(): void
+	{
+		$user = User::factory()->may_upload()->create();
+		$photo = Photo::factory()->owned_by($user)->create();
+		$person = Person::factory()->create();
+
+		$face1 = Face::factory()->for_photo($photo)->for_person($person)->create();
+		$face2 = Face::factory()->for_photo($photo)->for_person($person)->create();
+
+		$person->refresh();
+		self::assertCount(2, $person->faces);
+		self::assertTrue($person->faces->contains($face1));
+		self::assertTrue($person->faces->contains($face2));
+	}
+
+	public function testPersonRepresentativeFaceRelationship(): void
+	{
+		$user = User::factory()->may_upload()->create();
+		$photo = Photo::factory()->owned_by($user)->create();
+		$person = Person::factory()->create();
+		$face = Face::factory()->for_photo($photo)->for_person($person)->create();
+
+		$person->representative_face_id = $face->id;
+		$person->save();
+		$person->refresh();
+
+		self::assertNotNull($person->representativeFace);
+		self::assertEquals($face->id, $person->representativeFace->id);
+	}
+
+	public function testPersonDeleteNullifiesFaces(): void
+	{
+		$user = User::factory()->may_upload()->create();
+		$photo = Photo::factory()->owned_by($user)->create();
+		$person = Person::factory()->create();
+		$face = Face::factory()->for_photo($photo)->for_person($person)->create();
+
+		self::assertEquals($person->id, $face->person_id);
+
+		$person->delete();
+
+		$face->refresh();
+		self::assertNull($face->person_id);
+	}
+
+	public function testPhotoDeleteCascadesFaces(): void
+	{
+		$user = User::factory()->may_upload()->create();
+		$photo = Photo::factory()->owned_by($user)->create();
+		$person = Person::factory()->create();
+		$face = Face::factory()->for_photo($photo)->for_person($person)->create();
+		$face_id = $face->id;
+
+		// Use DB-level delete to trigger cascade FK without model observers
+		\Illuminate\Support\Facades\DB::table('photos')->where('id', '=', $photo->id)->delete();
+
+		self::assertNull(Face::find($face_id));
+	}
+
+	public function testScopeSearchable(): void
+	{
+		Person::factory()->with_name('Visible')->create();
+		Person::factory()->with_name('Hidden')->not_searchable()->create();
+
+		$searchable = Person::searchable()->get();
+		self::assertCount(1, $searchable);
+		self::assertEquals('Visible', $searchable->first()->name);
+	}
+
+	public function testNullableUserRelationship(): void
+	{
+		$person = Person::factory()->create();
+		self::assertNull($person->user);
+		self::assertNull($person->user_id);
+	}
+
+	public function testCastsAreCorrect(): void
+	{
+		$person = Person::factory()->create();
+		self::assertIsBool($person->is_searchable);
+	}
+}

From 29f7a3b811b371dbb0e18456cb58f94a2cc9a3e3 Mon Sep 17 00:00:00 2001
From: ildyria <beviguier@gmail.com>
Date: Tue, 24 Mar 2026 19:46:55 +0100
Subject: [PATCH 09/10] Moving parts around

---
 ...i_vision.yml => python_ai_vision_face_recognition.yml} | 8 ++++----
 ai-vision-service/{ => face-recognition}/Dockerfile       | 0
 ai-vision-service/{ => face-recognition}/README.md        | 0
 ai-vision-service/{ => face-recognition}/app/__init__.py  | 0
 .../{ => face-recognition}/app/api/__init__.py            | 0
 .../{ => face-recognition}/app/api/dependencies.py        | 0
 .../{ => face-recognition}/app/api/routes.py              | 0
 .../{ => face-recognition}/app/api/schemas.py             | 0
 .../{ => face-recognition}/app/clustering/__init__.py     | 0
 .../{ => face-recognition}/app/clustering/clusterer.py    | 0
 ai-vision-service/{ => face-recognition}/app/config.py    | 0
 .../{ => face-recognition}/app/detection/__init__.py      | 0
 .../{ => face-recognition}/app/detection/cropper.py       | 0
 .../{ => face-recognition}/app/detection/detector.py      | 0
 .../{ => face-recognition}/app/embeddings/__init__.py     | 0
 .../{ => face-recognition}/app/embeddings/factory.py      | 0
 .../app/embeddings/pgvector_store.py                      | 0
 .../{ => face-recognition}/app/embeddings/sqlite_store.py | 0
 .../{ => face-recognition}/app/embeddings/store.py        | 0
 ai-vision-service/{ => face-recognition}/app/main.py      | 0
 .../{ => face-recognition}/app/matching/__init__.py       | 0
 .../{ => face-recognition}/app/matching/matcher.py        | 0
 ai-vision-service/{ => face-recognition}/pyproject.toml   | 0
 .../{ => face-recognition}/tests/__init__.py              | 0
 .../{ => face-recognition}/tests/conftest.py              | 0
 .../{ => face-recognition}/tests/test_api.py              | 0
 .../{ => face-recognition}/tests/test_clustering.py       | 0
 .../{ => face-recognition}/tests/test_cropper.py          | 0
 .../{ => face-recognition}/tests/test_detection.py        | 0
 .../{ => face-recognition}/tests/test_embeddings.py       | 0
 .../{ => face-recognition}/tests/test_matching.py         | 0
 .../{ => face-recognition}/tests/test_smoke.py            | 0
 ai-vision-service/{ => face-recognition}/uv.lock          | 0
 33 files changed, 4 insertions(+), 4 deletions(-)
 rename .github/workflows/{python_ai_vision.yml => python_ai_vision_face_recognition.yml} (95%)
 rename ai-vision-service/{ => face-recognition}/Dockerfile (100%)
 rename ai-vision-service/{ => face-recognition}/README.md (100%)
 rename ai-vision-service/{ => face-recognition}/app/__init__.py (100%)
 rename ai-vision-service/{ => face-recognition}/app/api/__init__.py (100%)
 rename ai-vision-service/{ => face-recognition}/app/api/dependencies.py (100%)
 rename ai-vision-service/{ => face-recognition}/app/api/routes.py (100%)
 rename ai-vision-service/{ => face-recognition}/app/api/schemas.py (100%)
 rename ai-vision-service/{ => face-recognition}/app/clustering/__init__.py (100%)
 rename ai-vision-service/{ => face-recognition}/app/clustering/clusterer.py (100%)
 rename ai-vision-service/{ => face-recognition}/app/config.py (100%)
 rename ai-vision-service/{ => face-recognition}/app/detection/__init__.py (100%)
 rename ai-vision-service/{ => face-recognition}/app/detection/cropper.py (100%)
 rename ai-vision-service/{ => face-recognition}/app/detection/detector.py (100%)
 rename ai-vision-service/{ => face-recognition}/app/embeddings/__init__.py (100%)
 rename ai-vision-service/{ => face-recognition}/app/embeddings/factory.py (100%)
 rename ai-vision-service/{ => face-recognition}/app/embeddings/pgvector_store.py (100%)
 rename ai-vision-service/{ => face-recognition}/app/embeddings/sqlite_store.py (100%)
 rename ai-vision-service/{ => face-recognition}/app/embeddings/store.py (100%)
 rename ai-vision-service/{ => face-recognition}/app/main.py (100%)
 rename ai-vision-service/{ => face-recognition}/app/matching/__init__.py (100%)
 rename ai-vision-service/{ => face-recognition}/app/matching/matcher.py (100%)
 rename ai-vision-service/{ => face-recognition}/pyproject.toml (100%)
 rename ai-vision-service/{ => face-recognition}/tests/__init__.py (100%)
 rename ai-vision-service/{ => face-recognition}/tests/conftest.py (100%)
 rename ai-vision-service/{ => face-recognition}/tests/test_api.py (100%)
 rename ai-vision-service/{ => face-recognition}/tests/test_clustering.py (100%)
 rename ai-vision-service/{ => face-recognition}/tests/test_cropper.py (100%)
 rename ai-vision-service/{ => face-recognition}/tests/test_detection.py (100%)
 rename ai-vision-service/{ => face-recognition}/tests/test_embeddings.py (100%)
 rename ai-vision-service/{ => face-recognition}/tests/test_matching.py (100%)
 rename ai-vision-service/{ => face-recognition}/tests/test_smoke.py (100%)
 rename ai-vision-service/{ => face-recognition}/uv.lock (100%)

diff --git a/.github/workflows/python_ai_vision.yml b/.github/workflows/python_ai_vision_face_recognition.yml
similarity index 95%
rename from .github/workflows/python_ai_vision.yml
rename to .github/workflows/python_ai_vision_face_recognition.yml
index 826493c1154..57b56c608dd 100644
--- a/.github/workflows/python_ai_vision.yml
+++ b/.github/workflows/python_ai_vision_face_recognition.yml
@@ -1,4 +1,4 @@
-name: Python AI Vision Service
+name: Python AI Vision Service for face recognition
 
 on:
   push:
@@ -6,10 +6,10 @@ on:
       - master
       - assisted-vision
     paths:
-      - 'ai-vision-service/**'
+      - 'ai-vision-service/face-recognition/**'
   pull_request:
     paths:
-      - 'ai-vision-service/**'
+      - 'ai-vision-service/face-recognition/**'
   workflow_dispatch:
 
 # Declare default permissions as read only.
@@ -22,7 +22,7 @@ concurrency:
 
 defaults:
   run:
-    working-directory: ai-vision-service
+    working-directory: ai-vision-service/face-recognition
 
 jobs:
   # ---------------------------------------------------------------------------
diff --git a/ai-vision-service/Dockerfile b/ai-vision-service/face-recognition/Dockerfile
similarity index 100%
rename from ai-vision-service/Dockerfile
rename to ai-vision-service/face-recognition/Dockerfile
diff --git a/ai-vision-service/README.md b/ai-vision-service/face-recognition/README.md
similarity index 100%
rename from ai-vision-service/README.md
rename to ai-vision-service/face-recognition/README.md
diff --git a/ai-vision-service/app/__init__.py b/ai-vision-service/face-recognition/app/__init__.py
similarity index 100%
rename from ai-vision-service/app/__init__.py
rename to ai-vision-service/face-recognition/app/__init__.py
diff --git a/ai-vision-service/app/api/__init__.py b/ai-vision-service/face-recognition/app/api/__init__.py
similarity index 100%
rename from ai-vision-service/app/api/__init__.py
rename to ai-vision-service/face-recognition/app/api/__init__.py
diff --git a/ai-vision-service/app/api/dependencies.py b/ai-vision-service/face-recognition/app/api/dependencies.py
similarity index 100%
rename from ai-vision-service/app/api/dependencies.py
rename to ai-vision-service/face-recognition/app/api/dependencies.py
diff --git a/ai-vision-service/app/api/routes.py b/ai-vision-service/face-recognition/app/api/routes.py
similarity index 100%
rename from ai-vision-service/app/api/routes.py
rename to ai-vision-service/face-recognition/app/api/routes.py
diff --git a/ai-vision-service/app/api/schemas.py b/ai-vision-service/face-recognition/app/api/schemas.py
similarity index 100%
rename from ai-vision-service/app/api/schemas.py
rename to ai-vision-service/face-recognition/app/api/schemas.py
diff --git a/ai-vision-service/app/clustering/__init__.py b/ai-vision-service/face-recognition/app/clustering/__init__.py
similarity index 100%
rename from ai-vision-service/app/clustering/__init__.py
rename to ai-vision-service/face-recognition/app/clustering/__init__.py
diff --git a/ai-vision-service/app/clustering/clusterer.py b/ai-vision-service/face-recognition/app/clustering/clusterer.py
similarity index 100%
rename from ai-vision-service/app/clustering/clusterer.py
rename to ai-vision-service/face-recognition/app/clustering/clusterer.py
diff --git a/ai-vision-service/app/config.py b/ai-vision-service/face-recognition/app/config.py
similarity index 100%
rename from ai-vision-service/app/config.py
rename to ai-vision-service/face-recognition/app/config.py
diff --git a/ai-vision-service/app/detection/__init__.py b/ai-vision-service/face-recognition/app/detection/__init__.py
similarity index 100%
rename from ai-vision-service/app/detection/__init__.py
rename to ai-vision-service/face-recognition/app/detection/__init__.py
diff --git a/ai-vision-service/app/detection/cropper.py b/ai-vision-service/face-recognition/app/detection/cropper.py
similarity index 100%
rename from ai-vision-service/app/detection/cropper.py
rename to ai-vision-service/face-recognition/app/detection/cropper.py
diff --git a/ai-vision-service/app/detection/detector.py b/ai-vision-service/face-recognition/app/detection/detector.py
similarity index 100%
rename from ai-vision-service/app/detection/detector.py
rename to ai-vision-service/face-recognition/app/detection/detector.py
diff --git a/ai-vision-service/app/embeddings/__init__.py b/ai-vision-service/face-recognition/app/embeddings/__init__.py
similarity index 100%
rename from ai-vision-service/app/embeddings/__init__.py
rename to ai-vision-service/face-recognition/app/embeddings/__init__.py
diff --git a/ai-vision-service/app/embeddings/factory.py b/ai-vision-service/face-recognition/app/embeddings/factory.py
similarity index 100%
rename from ai-vision-service/app/embeddings/factory.py
rename to ai-vision-service/face-recognition/app/embeddings/factory.py
diff --git a/ai-vision-service/app/embeddings/pgvector_store.py b/ai-vision-service/face-recognition/app/embeddings/pgvector_store.py
similarity index 100%
rename from ai-vision-service/app/embeddings/pgvector_store.py
rename to ai-vision-service/face-recognition/app/embeddings/pgvector_store.py
diff --git a/ai-vision-service/app/embeddings/sqlite_store.py b/ai-vision-service/face-recognition/app/embeddings/sqlite_store.py
similarity index 100%
rename from ai-vision-service/app/embeddings/sqlite_store.py
rename to ai-vision-service/face-recognition/app/embeddings/sqlite_store.py
diff --git a/ai-vision-service/app/embeddings/store.py b/ai-vision-service/face-recognition/app/embeddings/store.py
similarity index 100%
rename from ai-vision-service/app/embeddings/store.py
rename to ai-vision-service/face-recognition/app/embeddings/store.py
diff --git a/ai-vision-service/app/main.py b/ai-vision-service/face-recognition/app/main.py
similarity index 100%
rename from ai-vision-service/app/main.py
rename to ai-vision-service/face-recognition/app/main.py
diff --git a/ai-vision-service/app/matching/__init__.py b/ai-vision-service/face-recognition/app/matching/__init__.py
similarity index 100%
rename from ai-vision-service/app/matching/__init__.py
rename to ai-vision-service/face-recognition/app/matching/__init__.py
diff --git a/ai-vision-service/app/matching/matcher.py b/ai-vision-service/face-recognition/app/matching/matcher.py
similarity index 100%
rename from ai-vision-service/app/matching/matcher.py
rename to ai-vision-service/face-recognition/app/matching/matcher.py
diff --git a/ai-vision-service/pyproject.toml b/ai-vision-service/face-recognition/pyproject.toml
similarity index 100%
rename from ai-vision-service/pyproject.toml
rename to ai-vision-service/face-recognition/pyproject.toml
diff --git a/ai-vision-service/tests/__init__.py b/ai-vision-service/face-recognition/tests/__init__.py
similarity index 100%
rename from ai-vision-service/tests/__init__.py
rename to ai-vision-service/face-recognition/tests/__init__.py
diff --git a/ai-vision-service/tests/conftest.py b/ai-vision-service/face-recognition/tests/conftest.py
similarity index 100%
rename from ai-vision-service/tests/conftest.py
rename to ai-vision-service/face-recognition/tests/conftest.py
diff --git a/ai-vision-service/tests/test_api.py b/ai-vision-service/face-recognition/tests/test_api.py
similarity index 100%
rename from ai-vision-service/tests/test_api.py
rename to ai-vision-service/face-recognition/tests/test_api.py
diff --git a/ai-vision-service/tests/test_clustering.py b/ai-vision-service/face-recognition/tests/test_clustering.py
similarity index 100%
rename from ai-vision-service/tests/test_clustering.py
rename to ai-vision-service/face-recognition/tests/test_clustering.py
diff --git a/ai-vision-service/tests/test_cropper.py b/ai-vision-service/face-recognition/tests/test_cropper.py
similarity index 100%
rename from ai-vision-service/tests/test_cropper.py
rename to ai-vision-service/face-recognition/tests/test_cropper.py
diff --git a/ai-vision-service/tests/test_detection.py b/ai-vision-service/face-recognition/tests/test_detection.py
similarity index 100%
rename from ai-vision-service/tests/test_detection.py
rename to ai-vision-service/face-recognition/tests/test_detection.py
diff --git a/ai-vision-service/tests/test_embeddings.py b/ai-vision-service/face-recognition/tests/test_embeddings.py
similarity index 100%
rename from ai-vision-service/tests/test_embeddings.py
rename to ai-vision-service/face-recognition/tests/test_embeddings.py
diff --git a/ai-vision-service/tests/test_matching.py b/ai-vision-service/face-recognition/tests/test_matching.py
similarity index 100%
rename from ai-vision-service/tests/test_matching.py
rename to ai-vision-service/face-recognition/tests/test_matching.py
diff --git a/ai-vision-service/tests/test_smoke.py b/ai-vision-service/face-recognition/tests/test_smoke.py
similarity index 100%
rename from ai-vision-service/tests/test_smoke.py
rename to ai-vision-service/face-recognition/tests/test_smoke.py
diff --git a/ai-vision-service/uv.lock b/ai-vision-service/face-recognition/uv.lock
similarity index 100%
rename from ai-vision-service/uv.lock
rename to ai-vision-service/face-recognition/uv.lock

From ec2b38f554200f15ce3c2669326a5bb915543dca Mon Sep 17 00:00:00 2001
From: ildyria <beviguier@gmail.com>
Date: Tue, 24 Mar 2026 20:48:07 +0100
Subject: [PATCH 10/10] logging

---
 resources/js/views/FaceClusters.vue | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/resources/js/views/FaceClusters.vue b/resources/js/views/FaceClusters.vue
index 3062782a4be..bec31c89da0 100644
--- a/resources/js/views/FaceClusters.vue
+++ b/resources/js/views/FaceClusters.vue
@@ -115,6 +115,7 @@ function load() {
 			hasMorePages.value = response.data.meta.current_page < response.data.meta.last_page;
 		})
 		.catch((e) => {
+			console.error("Error loading face clusters:", e);
 			toast.add({ severity: "error", summary: trans("toasts.error"), detail: e.response?.data?.message, life: 3000 });
 		})
 		.finally(() => {
@@ -132,6 +133,7 @@ function loadMore() {
 			hasMorePages.value = response.data.meta.current_page < response.data.meta.last_page;
 		})
 		.catch((e) => {
+			console.error("Error loading more face clusters:", e);
 			toast.add({ severity: "error", summary: trans("toasts.error"), detail: e.response?.data?.message, life: 3000 });
 		})
 		.finally(() => {
@@ -156,6 +158,7 @@ function assignCluster(label: number) {
 			delete clusterNames[label];
 		})
 		.catch((e) => {
+			console.error("Error assigning face cluster:", e);
 			toast.add({ severity: "error", summary: trans("toasts.error"), detail: e.response?.data?.message, life: 3000 });
 		})
 		.finally(() => {
@@ -177,6 +180,7 @@ function dismissCluster(label: number) {
 			delete clusterNames[label];
 		})
 		.catch((e) => {
+			console.error("Error dismissing face cluster:", e);
 			toast.add({ severity: "error", summary: trans("toasts.error"), detail: e.response?.data?.message, life: 3000 });
 		})
 		.finally(() => {
@@ -192,6 +196,7 @@ function runClustering() {
 			setTimeout(() => load(), 3000);
 		})
 		.catch((e) => {
+			console.error("Error running face clustering:", e);
 			toast.add({ severity: "error", summary: trans("toasts.error"), detail: e.response?.data?.message, life: 3000 });
 		})
 		.finally(() => {