From cb9a9bb42edb7f4aef42a91fd92d81e8d5578198 Mon Sep 17 00:00:00 2001
From: Till JS <tills95@gmail.com>
Date: Thu, 23 Apr 2026 18:09:57 +0200
Subject: [PATCH] refactor(profile,tool-registry): flip meImages from
 user-scoped to space-scoped (v40)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Flips `meImages` out of USER_LEVEL_TABLES so it lives under the same
tenancy model as every other data table (tags, scenes, tasks, …).
Precursor to the Wardrobe module, which is space-scoped across all
six space types — leaving meImages user-global would leave an
inconsistency where the Wardrobe catalog is per-space but its
reference input is cross-space, plus a latent privacy leak in shared
spaces (agents in a brand-space would see the owner's entire pool).

Plan: docs/plans/me-images-space-scope-migration.md.

Key decisions:

- Strict scope, no cross-space fallback. Switching into a brand-space
  with no uploaded face shows an empty state and links back to
  /profile/me-images; it does not quietly reach into the personal-
  space pool. Keeps the mental model clean.
- auth.users.image remains pinned to personal-space primary-avatar.
  Only a primary change inside personal space triggers the Better
  Auth sync; brand/club/family/team/practice primaries stay local.
- Single Dexie v40 upgrade: stamps `spaceId=_personal:<uid>`
  sentinel, `authorId=<uid>`, `visibility='space'` on every existing
  row and drops the legacy `userId` column. Dexie upgrades block app
  startup, so by the time the new code's scopedForModule reads run,
  every row is already space-stamped. reconcileSentinels() on the
  next active-space bootstrap rewrites `_personal:<uid>` to the real
  personal-space id, same path v28 used.
- Legacy-avatar migration (M2.5) now pins its row to
  `_personal:<uid>` explicitly — the legacy avatar is the user's
  global SSO identity and belongs in the personal space even if the
  migration happens to fire while the user is in a brand space.

Code changes:

- types.ts: LocalMeImage gains spaceId/authorId/visibility (all
  optional — stamped by hook). Public MeImage exposes spaceId for
  queries that want to branch on space type.
- database.ts: meImages out of USER_LEVEL_TABLES; new v40 upgrade
  block that stamps sentinels + drops userId in one pass.
- queries.ts: all four hooks (useAllMeImages, useMeImagesByKind,
  useReferenceImages, useImageByPrimary) read via scopedForModule.
  Scope-switch triggers automatic re-render via the existing
  scopedTable filter path.
- stores/me-images.svelte.ts: setPrimaryInTx uses scopedForModule so
  a setPrimary in Brand-space never clears Personal-space's holder.
  syncAvatarToAuth gates on activeSpace.type==='personal' so non-
  personal primary changes don't leak into Better Auth.
  createMeImage accepts optional spaceId override — the legacy-
  avatar migration uses it, regular uploads let the hook stamp the
  active space.
- migration/legacy-avatar.ts: explicitly passes
  spaceId=_personal:<uid> to pin the legacy row into personal space.
- MeImagesView.svelte: subtle badge in the intro card shows the
  active space ("Persönlich" for personal, space name otherwise) so
  users notice when the pool changes on space switch.
- packages/mana-tool-registry/src/modules/me.ts: me.listReferenceImages
  filters pulled rows by row.spaceId === ctx.spaceId. mana-sync
  returns all spaces the user belongs to; the tool only wants the
  active space's subset.

No schema/index change on meImages (non-indexed fields, pool size
small enough for in-memory scopedTable filter). If perf matters
later, adding [spaceId+kind] is a 5-minute follow-up.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 apps/mana/apps/web/src/lib/data/database.ts   | 45 ++++++++++-
 .../lib/modules/profile/MeImagesView.svelte   | 22 ++++-
 .../profile/migration/legacy-avatar.ts        |  8 ++
 .../web/src/lib/modules/profile/queries.ts    | 80 +++++++++++--------
 .../profile/stores/me-images.svelte.ts        | 48 ++++++++---
 .../apps/web/src/lib/modules/profile/types.ts | 10 +++
 docs/plans/me-images-space-scope-migration.md | 66 +++++++++++++++
 packages/mana-tool-registry/src/modules/me.ts | 12 ++-
 8 files changed, 245 insertions(+), 46 deletions(-)
 create mode 100644 docs/plans/me-images-space-scope-migration.md

diff --git a/apps/mana/apps/web/src/lib/data/database.ts b/apps/mana/apps/web/src/lib/data/database.ts
index ee8a9538d..21e22dea5 100644
--- a/apps/mana/apps/web/src/lib/data/database.ts
+++ b/apps/mana/apps/web/src/lib/data/database.ts
@@ -932,6 +932,48 @@ db.version(38).stores({
 	meImages: 'id, kind, primaryFor, createdAt',
 });
 
+// v40 — Flip meImages from USER_LEVEL_TABLES to space-scoped data
+// (docs/plans/me-images-space-scope-migration.md).
+//
+// Why: after Wardrobe's decision to be space-scoped across all six
+// space types, leaving meImages user-scoped creates a split-brain
+// model (space-scoped catalog, user-global input). Unification also
+// closes a latent privacy leak in shared spaces — an MCP agent in a
+// brand-space would otherwise see the owner's entire private pool.
+//
+// What the upgrade does to existing rows, in one pass:
+//   1. stamps `spaceId = _personal:<userId>` sentinel (reconcileSentinels
+//      rewrites it to the real personal-space id on next Better Auth
+//      membership load — same path as v28's sentinel population)
+//   2. stamps `authorId = userId`
+//   3. stamps `visibility = 'space'`
+//   4. drops `userId` (meImages is a data-table now, attribution lives
+//      on the Actor fields + tenancy on spaceId — same sweep as v35
+//      did for the other data-tables, just scoped to this one)
+//
+// No schema/index change: `spaceId`, `authorId`, `visibility` are
+// non-indexed fields, scopedTable filters in-memory. Tiny pool per
+// space (typ. 2-10 rows), no compound index warranted.
+db.version(40).upgrade(async (tx) => {
+	await tx
+		.table('meImages')
+		.toCollection()
+		.modify((record: Record<string, unknown>) => {
+			const ownerId =
+				typeof record.userId === 'string' && record.userId ? record.userId : GUEST_USER_ID;
+			if (record.spaceId === undefined || record.spaceId === null) {
+				record.spaceId = `_personal:${ownerId}`;
+			}
+			if (record.authorId === undefined || record.authorId === null) {
+				record.authorId = ownerId;
+			}
+			if (record.visibility === undefined || record.visibility === null) {
+				record.visibility = 'space';
+			}
+			if ('userId' in record) delete record.userId;
+		});
+});
+
 // ─── Sync Routing ──────────────────────────────────────────
 // SYNC_APP_MAP, TABLE_TO_SYNC_NAME, TABLE_TO_APP, SYNC_NAME_TO_TABLE,
 // toSyncName() and fromSyncName() are now derived from per-module
@@ -1114,7 +1156,8 @@ const USER_LEVEL_TABLES: ReadonlySet<string> = new Set([
 	'broadcastSettings',
 	'wetterSettings',
 	'userTagPresets',
-	'meImages',
+	// meImages removed in v40 — now space-scoped like every other
+	// data-table. See docs/plans/me-images-space-scope-migration.md.
 ]);
 
 for (const [appId, tables] of Object.entries(SYNC_APP_MAP)) {
diff --git a/apps/mana/apps/web/src/lib/modules/profile/MeImagesView.svelte b/apps/mana/apps/web/src/lib/modules/profile/MeImagesView.svelte
index 889f2ddfc..d67557d7d 100644
--- a/apps/mana/apps/web/src/lib/modules/profile/MeImagesView.svelte
+++ b/apps/mana/apps/web/src/lib/modules/profile/MeImagesView.svelte
@@ -16,6 +16,7 @@
 <script lang="ts">
 	import { onMount } from 'svelte';
 	import { Info, Sparkle } from '@mana/shared-icons';
+	import { getActiveSpace } from '$lib/data/scope';
 	import MeImageSlotCard from './components/MeImageSlotCard.svelte';
 	import MeImageTile from './components/MeImageTile.svelte';
 	import MeImageUploadZone from './components/MeImageUploadZone.svelte';
@@ -25,6 +26,11 @@
 	import { migrateLegacyAvatarIfNeeded } from './migration/legacy-avatar';
 	import type { MeImage, MeImageKind, MeImagePrimarySlot } from './types';
 
+	// Active-space indicator for the intro card. After v40 meImages are
+	// space-scoped — when the user switches spaces the pool changes. The
+	// badge makes that transparent without cluttering the rest of the UI.
+	const activeSpace = $derived(getActiveSpace());
+
 	// One-shot bootstrap: pull the pre-M1 auth.users.image into meImages
 	// as the avatar primary. Idempotent — see migration/legacy-avatar.ts.
 	onMount(() => {
@@ -108,9 +114,19 @@
 <div class="mx-auto max-w-4xl space-y-8 p-4 sm:p-6">
 	<!-- Intro + privacy hint -->
 	<section class="rounded-2xl border border-border bg-card p-5">
-		<div class="mb-2 flex items-center gap-2 text-foreground">
-			<Sparkle size={18} weight="fill" class="text-primary" />
-			<h2 class="text-base font-semibold">Meine Bilder</h2>
+		<div class="mb-2 flex items-center justify-between gap-2 text-foreground">
+			<div class="flex items-center gap-2">
+				<Sparkle size={18} weight="fill" class="text-primary" />
+				<h2 class="text-base font-semibold">Meine Bilder</h2>
+			</div>
+			{#if activeSpace}
+				<span
+					class="rounded-full bg-muted px-2.5 py-0.5 text-xs font-medium text-muted-foreground"
+					title="Der Pool ist pro Space — Bilder aus anderen Spaces bleiben dort."
+				>
+					{activeSpace.type === 'personal' ? 'Persönlich' : activeSpace.name}
+				</span>
+			{/if}
 		</div>
 		<p class="text-sm text-muted-foreground">
 			Hinterlege hier ein Gesichts- und ein Ganzkörper-Bild sowie weitere Referenzen. Die
diff --git a/apps/mana/apps/web/src/lib/modules/profile/migration/legacy-avatar.ts b/apps/mana/apps/web/src/lib/modules/profile/migration/legacy-avatar.ts
index 71db9255d..0732f3585 100644
--- a/apps/mana/apps/web/src/lib/modules/profile/migration/legacy-avatar.ts
+++ b/apps/mana/apps/web/src/lib/modules/profile/migration/legacy-avatar.ts
@@ -77,6 +77,14 @@ export async function migrateLegacyAvatarIfNeeded(): Promise<void> {
 		label: 'Bisheriges Profilbild',
 		usage: { aiReference: false, showInProfile: true },
 		primaryFor: 'avatar',
+		// Legacy avatar is the user's global SSO identity (Better Auth
+		// `users.image`) — it belongs explicitly in the *personal* space,
+		// regardless of which space the user happens to be in when the
+		// migration fires. Use the `_personal:<uid>` sentinel that
+		// reconcileSentinels() rewrites to the real personal-space id on
+		// the next active-space bootstrap (same pattern v28 used for the
+		// blanket data-table migration).
+		spaceId: `_personal:${user.id}`,
 	});
 
 	try {
diff --git a/apps/mana/apps/web/src/lib/modules/profile/queries.ts b/apps/mana/apps/web/src/lib/modules/profile/queries.ts
index 2d9373095..5d5336d93 100644
--- a/apps/mana/apps/web/src/lib/modules/profile/queries.ts
+++ b/apps/mana/apps/web/src/lib/modules/profile/queries.ts
@@ -1,14 +1,21 @@
 /**
  * Profile module — read-side queries.
+ *
+ * `userContext` stays a per-user singleton (read via the direct
+ * collection). `meImages` is now space-scoped (v40) — all reads go
+ * through `scopedForModule` so switching the active space flips the
+ * visible pool without any query re-write.
  */
 
 import { useLiveQueryWithDefault } from '@mana/local-store/svelte';
 import { decryptRecords } from '$lib/data/crypto';
-import { meImagesTable, userContextTable } from './collections';
+import { scopedForModule } from '$lib/data/scope';
+import { userContextTable } from './collections';
 import {
 	USER_CONTEXT_SINGLETON_ID,
 	toUserContext,
 	toMeImage,
+	type LocalMeImage,
 	type UserContext,
 	type MeImage,
 	type MeImageKind,
@@ -26,26 +33,13 @@ export function useUserContext() {
 }
 
 /**
- * All non-deleted me-images, newest first. Decrypted on the client —
- * filters and sorting happen before decrypt where possible (`kind`,
- * `primaryFor`, `createdAt` are plaintext indices).
+ * All non-deleted me-images in the active space, newest first. The
+ * `scopedForModule` wrapper filters in-memory by `spaceId`; the live-
+ * query re-runs automatically when the active space changes.
  */
 export function useAllMeImages() {
 	return useLiveQueryWithDefault<MeImage[]>(async () => {
-		const locals = await meImagesTable.orderBy('createdAt').reverse().toArray();
-		const visible = locals.filter((row) => !row.deletedAt);
-		const decrypted = await decryptRecords('meImages', visible);
-		return decrypted.map(toMeImage);
-	}, [] as MeImage[]);
-}
-
-/**
- * Me-images filtered by `kind`. Uses the `kind` Dexie index so large
- * pools still filter in one B-tree lookup.
- */
-export function useMeImagesByKind(kind: MeImageKind) {
-	return useLiveQueryWithDefault<MeImage[]>(async () => {
-		const locals = await meImagesTable.where('kind').equals(kind).toArray();
+		const locals = await scopedForModule<LocalMeImage, string>('profile', 'meImages').toArray();
 		const visible = locals
 			.filter((row) => !row.deletedAt)
 			.sort((a, b) => (b.createdAt ?? '').localeCompare(a.createdAt ?? ''));
@@ -55,33 +49,55 @@ export function useMeImagesByKind(kind: MeImageKind) {
 }
 
 /**
- * Only images the user explicitly opted in for AI reference use.
- * This is the authoritative list the Picture generator's Reference
- * picker reads from — if an image isn't here, it must not be sent
- * to OpenAI.
+ * Me-images in the active space filtered by `kind`.
  */
-export function useReferenceImages() {
+export function useMeImagesByKind(kind: MeImageKind) {
 	return useLiveQueryWithDefault<MeImage[]>(async () => {
-		const locals = await meImagesTable.orderBy('createdAt').reverse().toArray();
-		const visible = locals.filter((row) => !row.deletedAt && row.usage?.aiReference === true);
+		const locals = await scopedForModule<LocalMeImage, string>('profile', 'meImages')
+			.and((row) => row.kind === kind)
+			.toArray();
+		const visible = locals
+			.filter((row) => !row.deletedAt)
+			.sort((a, b) => (b.createdAt ?? '').localeCompare(a.createdAt ?? ''));
 		const decrypted = await decryptRecords('meImages', visible);
 		return decrypted.map(toMeImage);
 	}, [] as MeImage[]);
 }
 
 /**
- * Current holder of a primary slot (avatar / face-ref / body-ref),
- * or null if nobody claimed it yet. Powers the avatar fallback and
- * the Reference picker's default selection.
+ * Only images the user explicitly opted in for AI reference use
+ * **within the active space**. This is the authoritative list the
+ * Picture generator's Reference picker reads from — if an image
+ * isn't here, it must not be sent to OpenAI.
+ */
+export function useReferenceImages() {
+	return useLiveQueryWithDefault<MeImage[]>(async () => {
+		const locals = await scopedForModule<LocalMeImage, string>('profile', 'meImages').toArray();
+		const visible = locals
+			.filter((row) => !row.deletedAt && row.usage?.aiReference === true)
+			.sort((a, b) => (b.createdAt ?? '').localeCompare(a.createdAt ?? ''));
+		const decrypted = await decryptRecords('meImages', visible);
+		return decrypted.map(toMeImage);
+	}, [] as MeImage[]);
+}
+
+/**
+ * Current holder of a primary slot (avatar / face-ref / body-ref)
+ * **within the active space**. After v40 each space has its own
+ * primary slots. Personal-space's `avatar` slot drives
+ * `auth.users.image` globally — other spaces' `avatar` slots stay
+ * local to that space.
  */
 export function useImageByPrimary(slot: MeImagePrimarySlot) {
 	return useLiveQueryWithDefault<MeImage | null>(async () => {
-		const locals = await meImagesTable.where('primaryFor').equals(slot).toArray();
+		const locals = await scopedForModule<LocalMeImage, string>('profile', 'meImages')
+			.and((row) => row.primaryFor === slot)
+			.toArray();
 		const visible = locals.filter((row) => !row.deletedAt);
 		if (visible.length === 0) return null;
-		// The setPrimary store method keeps this to exactly one row. If
-		// somehow more than one slipped through (manual DB edit, race on
-		// a broken migration), prefer the most recent write.
+		// The setPrimary store method keeps this to exactly one row per
+		// space. If more than one slipped through (manual DB edit, race
+		// on a broken migration), prefer the most recent write.
 		visible.sort((a, b) => (b.updatedAt ?? '').localeCompare(a.updatedAt ?? ''));
 		const [decrypted] = await decryptRecords('meImages', [visible[0]]);
 		return toMeImage(decrypted);
diff --git a/apps/mana/apps/web/src/lib/modules/profile/stores/me-images.svelte.ts b/apps/mana/apps/web/src/lib/modules/profile/stores/me-images.svelte.ts
index 61ab991ae..6a49438f5 100644
--- a/apps/mana/apps/web/src/lib/modules/profile/stores/me-images.svelte.ts
+++ b/apps/mana/apps/web/src/lib/modules/profile/stores/me-images.svelte.ts
@@ -10,6 +10,7 @@
 
 import { encryptRecord } from '$lib/data/crypto';
 import { emitDomainEvent } from '$lib/data/events';
+import { scopedForModule, getActiveSpace } from '$lib/data/scope';
 import { profileService } from '$lib/api/profile';
 import { meImagesTable } from '../collections';
 import { toMeImage } from '../types';
@@ -33,6 +34,15 @@ export interface CreateMeImageInput {
 	tags?: string[];
 	usage?: Partial<MeImageUsage>;
 	primaryFor?: MeImagePrimarySlot | null;
+	/**
+	 * Override the auto-stamped spaceId. Only the legacy-avatar
+	 * migration needs this — it must pin the pre-M1 `auth.users.image`
+	 * explicitly into the user's personal space regardless of which
+	 * space happens to be active when the user first visits the route.
+	 * Regular upload paths leave this unset and let the Dexie hook
+	 * stamp the active space.
+	 */
+	spaceId?: string;
 }
 
 /**
@@ -49,11 +59,17 @@ function defaultUsage(override?: Partial<MeImageUsage>): MeImageUsage {
 }
 
 /**
- * After any primary-avatar change, push the current holder's publicUrl
- * back to Better Auth so `auth.users.image` stays in lockstep. Plan
- * M2.5 — this is the only path by which auth.users.image ever gets
- * written from now on; EditProfileModal's legacy inline upload is
- * gone in the same commit.
+ * After any primary-avatar change in the **personal** space, push the
+ * current holder's publicUrl back to Better Auth so `auth.users.image`
+ * stays in lockstep. Plan M2.5 — this is the only path by which
+ * auth.users.image ever gets written from now on.
+ *
+ * After v40 (space-scope migration), avatar-primary is per-space; only
+ * the personal-space holder represents the user's global SSO identity.
+ * A primary-avatar change inside a brand/club/family/team/practice
+ * space is local to that space and must NOT overwrite the Better Auth
+ * record — otherwise switching into a brand space and picking a new
+ * avatar would leak into the user's navigation/SSO identity elsewhere.
  *
  * Best-effort: failures are logged and swallowed. The meImages row is
  * authoritative for the app's own avatar rendering, so a stale
@@ -61,7 +77,11 @@ function defaultUsage(override?: Partial<MeImageUsage>): MeImageUsage {
  */
 async function syncAvatarToAuth(): Promise<void> {
 	try {
-		const rows = await meImagesTable.where('primaryFor').equals('avatar').toArray();
+		const active = getActiveSpace();
+		if (active?.type !== 'personal') return;
+		const rows = await scopedForModule<LocalMeImage, string>('profile', 'meImages')
+			.and((row) => row.primaryFor === 'avatar')
+			.toArray();
 		const holder = rows.find((row) => !row.deletedAt);
 		const nextImage = holder?.publicUrl ?? '';
 		await profileService.updateProfile({ image: nextImage });
@@ -72,13 +92,17 @@ async function syncAvatarToAuth(): Promise<void> {
 
 /**
  * Internal: swap the primary holder of `slot` to `id` (or clear it
- * when id is null) in one transaction. Extracted so `setPrimary` can
- * reuse it when avatar silently follows face-ref.
+ * when id is null) in one transaction — *within the active space only*.
+ * Extracted so `setPrimary` can reuse it when avatar silently follows
+ * face-ref. After v40, "primary slot" is per-space; a setPrimary in
+ * Brand-space must not clear Personal-space's holder.
  */
 async function setPrimaryInTx(id: string | null, slot: MeImagePrimarySlot): Promise<void> {
 	const nowIso = new Date().toISOString();
 	await meImagesTable.db.transaction('rw', meImagesTable, async () => {
-		const current = await meImagesTable.where('primaryFor').equals(slot).toArray();
+		const current = await scopedForModule<LocalMeImage, string>('profile', 'meImages')
+			.and((row) => row.primaryFor === slot)
+			.toArray();
 		for (const row of current) {
 			if (row.id === id) continue;
 			await meImagesTable.update(row.id, { primaryFor: null, updatedAt: nowIso });
@@ -105,6 +129,12 @@ export const meImagesStore = {
 			usage: defaultUsage(input.usage),
 			primaryFor: input.primaryFor ?? null,
 		};
+		// Pre-stamp the spaceId so the Dexie creating-hook leaves it
+		// alone. Only the legacy-avatar migration uses this — regular
+		// uploads let the hook stamp the active space.
+		if (input.spaceId !== undefined) {
+			newLocal.spaceId = input.spaceId;
+		}
 		const snapshot = toMeImage({ ...newLocal });
 		await encryptRecord('meImages', newLocal);
 		await meImagesTable.add(newLocal);
diff --git a/apps/mana/apps/web/src/lib/modules/profile/types.ts b/apps/mana/apps/web/src/lib/modules/profile/types.ts
index 4105c9a20..26afb0e2f 100644
--- a/apps/mana/apps/web/src/lib/modules/profile/types.ts
+++ b/apps/mana/apps/web/src/lib/modules/profile/types.ts
@@ -169,6 +169,14 @@ export interface LocalMeImage extends BaseRecord {
 	tags: string[];
 	usage: MeImageUsage;
 	primaryFor?: MeImagePrimarySlot | null;
+	// Space-scope fields (added in Dexie v40 — see
+	// docs/plans/me-images-space-scope-migration.md). Stamped by the
+	// Dexie creating-hook like any other data table; the initial
+	// `_personal:<userId>` sentinel is rewritten to the real space id
+	// by reconcileSentinels() on the first active-space bootstrap.
+	spaceId?: string;
+	authorId?: string;
+	visibility?: 'space' | 'private';
 }
 
 export interface MeImage {
@@ -184,6 +192,7 @@ export interface MeImage {
 	tags: string[];
 	usage: MeImageUsage;
 	primaryFor?: MeImagePrimarySlot | null;
+	spaceId?: string;
 	createdAt: string;
 	updatedAt: string;
 }
@@ -203,6 +212,7 @@ export function toMeImage(local: LocalMeImage): MeImage {
 		tags: local.tags ?? [],
 		usage: local.usage ?? { aiReference: false, showInProfile: true },
 		primaryFor: local.primaryFor ?? null,
+		spaceId: local.spaceId,
 		createdAt: local.createdAt ?? '',
 		updatedAt: local.updatedAt ?? '',
 	};
diff --git a/docs/plans/me-images-space-scope-migration.md b/docs/plans/me-images-space-scope-migration.md
new file mode 100644
index 000000000..12e82376f
--- /dev/null
+++ b/docs/plans/me-images-space-scope-migration.md
@@ -0,0 +1,66 @@
+# meImages — User-Scoped → Space-Scoped Migration
+
+## Status (2026-04-23)
+
+Greenfield-Folge-Plan zu `me-images-and-reference-generation.md` (M1–M5 shipped) und Precursor zu `wardrobe-module.md`. Flippt die `meImages`-Tabelle von User-Level auf Space-Scoped — einmalige retro-Migration bestehender Zeilen plus Code-Shift in Queries, Store, Avatar-Sync und MCP-Tool.
+
+## Warum
+
+Nach der Wardrobe-Entscheidung "alle sechs Space-Typen bekommen wardrobe" ist User-Level-`meImages` der einzige Sonderfall im System, wo der *Input* für Space-Daten cross-Space lebt während der *Output* (Wardrobe-Katalog, Try-On-Ergebnisse in Picture) space-scoped ist. Drei konkrete Gewinne durch Angleichung:
+
+1. **Privacy zwischen Spaces.** `me.listReferenceImages` sieht heute den gesamten User-Pool, egal aus welchem Space gerufen. In einem Brand-Space, der mit einem Geschäftspartner geteilt wird, würden dessen Personas/MCP-Tools potenziell private Selfies zu Gesicht bekommen. Nach Migration: jeder Space sieht nur seinen eigenen Pool.
+
+2. **Kontext-Match.** Brand-Space will Studio-Portrait, Personal-Space will Selfie, Club-Space will Action-Shot. Heute: Nutzer muss aus einem Pool die richtige Referenz pro Generation manuell aussuchen. Nachher: jeder Space hat seine 2-3 passenden Referenzen, null Denkarbeit.
+
+3. **Architektur-Kohärenz.** Eine Regel weniger zu erklären: *alle* Daten-Tabellen sind space-scoped, *alle* Singletons (userSettings, userContext, …) sind user-level.
+
+Die eine Reibung: wer drei Spaces hat, muss potenziell in jeden einmal ein Gesicht hochladen. Für Brand-/Club-Spaces ist das ohnehin erwünscht (anderes Bild als privat). Für Family-Spaces ist der Edge-Case dokumentiert (Try-On nutzt Caller-Identität, nicht Kind).
+
+## Entscheidungen
+
+1. **Strikte Scope-Trennung** — kein Fallback von Brand-Space auf Personal-Space-Referenzen. Leere Space = explizite Aufforderung zum Upload. Matched Wardrobe-Plan Decision #6.
+2. **`auth.users.image` bleibt an Personal-Space gekoppelt** — die globale SSO-Identity ist persönlich. Wer im Brand-Space ein Profilbild setzt, ändert damit sein Brand-Avatar, *nicht* seinen Better-Auth-Account-Avatar. Konkret: `syncAvatarToAuth` gatet auf `activeSpace.type === 'personal'`.
+3. **Einmaliger Dexie v40-Upgrade** — Sentinel-Stamping (`spaceId=_personal:<uid>`, `authorId=<uid>`, `visibility='space'`) plus `delete record.userId` in einer Version. Kein split auf v40+v41 nötig: Dexie-Upgrade läuft *vor* App-Start, die neue Code-Version trifft stets auf gestampte Daten. Multi-Tab-Edge-Cases sind benign — alte Tabs nutzen direkten Table-Access (pre-migration), sehen ihre Daten weiter, Reload lädt neue Code-Version.
+4. **Bestehende Zeilen → Personal-Space-Sentinel.** `reconcileSentinels()` im Scope-Bootstrap löst die Sentinel automatisch zur echten Personal-Space-ID auf, sobald der Nutzer den Personal-Space lädt. Kein Extra-Code.
+5. **Legacy-Avatar-Migration pinnt auf Personal-Space-Sentinel explizit.** Der Legacy-Avatar ist per Definition die globale Identity → gehört in Personal-Space, auch wenn der Nutzer die Migration zufällig aus einem Brand-Space triggert.
+6. **Keine Schema-Index-Änderungen.** meImages-Pools sind klein (typ. 2–10 Bilder), `scopedTable` filtert in-memory. Falls später >100 Zeilen pro Nutzer auftauchen, ist `[spaceId+kind]`-Compound-Index eine eigene ~5-Minuten-Änderung.
+
+## Change Matrix
+
+| Datei | Änderung |
+|---|---|
+| `apps/mana/apps/web/src/lib/modules/profile/types.ts` | `LocalMeImage` bekommt `spaceId?`, `authorId?`, `visibility?`; Public `MeImage` ebenfalls; in `toMeImage()` durchreichen |
+| `apps/mana/apps/web/src/lib/data/database.ts` | `'meImages'` raus aus `USER_LEVEL_TABLES`; neuer `db.version(40).upgrade(...)` block der meImages-Rows mit Sentinel stampt + userId löscht |
+| `apps/mana/apps/web/src/lib/modules/profile/queries.ts` | Alle 4 Hooks (`useAllMeImages`, `useMeImagesByKind`, `useReferenceImages`, `useImageByPrimary`) lesen via `scopedForModule<LocalMeImage, string>('profile', 'meImages')` |
+| `apps/mana/apps/web/src/lib/modules/profile/stores/me-images.svelte.ts` | `setPrimaryInTx` nutzt `scopedForModule` statt `meImagesTable` für die Primary-Holder-Suche; `createMeImage` akzeptiert optional `spaceId`-Override (für legacy-avatar); `syncAvatarToAuth` gatet auf `getActiveSpace()?.type === 'personal'` und nutzt `scopedForModule` |
+| `apps/mana/apps/web/src/lib/modules/profile/migration/legacy-avatar.ts` | ruft `createMeImage` mit explizitem `spaceId = _personal:<userId>` Sentinel |
+| `apps/mana/apps/web/src/lib/modules/profile/MeImagesView.svelte` | dezenter Badge in der Intro-Card: "Pool für: {Space-Name}" damit Nutzer bei Space-Switch merkt, welcher Pool angezeigt wird |
+| `packages/mana-tool-registry/src/modules/me.ts` | `me.listReferenceImages` filtert nach `pullAll` client-seitig auf `row.spaceId === ctx.spaceId` |
+
+## Migration-Risikoanalyse
+
+- **Multi-Tab während Upgrade**: Tab A auf alter Version, Tab B triggert Upgrade → Tab A sieht potenziell Ghost-Records bis Reload. Akzeptabel — Tab A nutzt direkten Table-Access (user-scoped, noch vor scopedForModule), alles bleibt sichtbar für ihn.
+- **Kein Personal-Space geladen**: Sehr früh nach Login, vor Bootstrap, ist `getActiveSpace()` null. Stores guarden mit Throw; Queries geben leere Arrays. Kein Data-Loss, nur "noch nichts da"-UI. Bootstrap resolved in < 200ms, Problem lokal und selbstheilend.
+- **Bestehender `auth.users.image`**: bleibt wie er ist. Die M2.5-Migration (legacy-avatar.ts) war ein One-Shot; meImages-Zeilen mit `primaryFor='avatar'` existieren bei Nutzern die vor M2.5 auf der Route waren. Diese werden durch v40 mit `spaceId=_personal:<uid>` gestampt, `reconcileSentinels()` rewritet zur echten Personal-Space-ID. Sync-Hook auf Personal-Space holt Primary → schreibt `auth.users.image` — Wert bleibt identisch, Null-Operation im Happy-Path.
+- **ZK-Nutzer**: unverändert; die Encryption-Eigenschaften der Tabelle ändern sich nicht (`label`+`tags` bleiben encrypted).
+
+## Milestones
+
+Ein Commit. Ein atomic `git add && git commit`.
+
+- [ ] Types extended (spaceId/authorId/visibility auf Local + Public)
+- [ ] Dexie v40 upgrade stamped sentinel + drops userId
+- [ ] `USER_LEVEL_TABLES` bereinigt
+- [ ] Queries über `scopedForModule<>`
+- [ ] Store setPrimary/setPrimaryInTx scope-aware
+- [ ] `createMeImage` nimmt optional spaceId-Override
+- [ ] `syncAvatarToAuth` gate + scope
+- [ ] legacy-avatar.ts stampt Personal-Sentinel
+- [ ] MeImagesView Space-Badge
+- [ ] MCP tool me.listReferenceImages filter
+- [ ] validate:all + type-check web + type-check api + type-check tool-registry + type-check mana-mcp
+- [ ] atomic commit
+
+## Was NACH der Migration möglich wird
+
+Wardrobe-Modul M1 startet direkt auf der neuen Grundlage, ohne Sonderfall-Ausnahmen für meImages. Try-On in Brand-Space nutzt automatisch die Brand-Space-Referenzen des Nutzers (oder zeigt den Upload-Empty-State). Personas in einem geteilten Space sehen nur die dort freigegebenen Referenzen.
diff --git a/packages/mana-tool-registry/src/modules/me.ts b/packages/mana-tool-registry/src/modules/me.ts
index 3d2f1d640..f413fa60f 100644
--- a/packages/mana-tool-registry/src/modules/me.ts
+++ b/packages/mana-tool-registry/src/modules/me.ts
@@ -70,6 +70,11 @@ interface RawMeImageRow {
 	height?: number | null;
 	usage?: { aiReference?: boolean } | null;
 	deletedAt?: string | null;
+	// Added by the web-app's Dexie v40 migration (docs/plans/
+	// me-images-space-scope-migration.md). Rows pulled from mana-sync
+	// for a user may span multiple spaces — the tool must filter down
+	// to the caller's active space to match the web-app's behaviour.
+	spaceId?: string | null;
 }
 
 // ─── me.listReferenceImages ───────────────────────────────────────
@@ -103,10 +108,15 @@ export const meListReferenceImages: ToolSpec<typeof listInput, typeof listOutput
 		const key = await ctx.getMasterKey();
 
 		const res = await pullAll<RawMeImageRow>(syncCfg(ctx), APP_ID, TABLE);
+		// mana-sync returns all of the caller's meImages across every
+		// space they belong to — filter down to the active space so
+		// agents in a brand-space never see the personal-space pool
+		// (and vice-versa). Matches the web-app's scopedForModule cut.
 		const alive = res.changes
 			.filter((c) => c.op !== 'delete' && c.data)
 			.map((c) => c.data as RawMeImageRow)
-			.filter((row) => !row.deletedAt);
+			.filter((row) => !row.deletedAt)
+			.filter((row) => row.spaceId === ctx.spaceId);
 
 		const optedIn = alive.filter((row) => row.usage?.aiReference === true);
 		const kindFiltered = input.kind ? optedIn.filter((row) => row.kind === input.kind) : optedIn;