@codemem/server 0.22.0-alpha.3 → 0.22.0-alpha.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codemem/server",
-  "version": "0.22.0-alpha.3",
+  "version": "0.22.0-alpha.5",
   "type": "module",
   "types": "./dist/index.d.ts",
   "exports": {
@@ -18,7 +18,7 @@
     "@hono/node-server": "^1.14.3",
     "drizzle-orm": "^0.45.1",
     "hono": "^4.7.10",
-    "@codemem/core": "^0.22.0-alpha.3"
+    "@codemem/core": "^0.22.0-alpha.5"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.13",

package/static/app.js

@@ -146,6 +146,8 @@
 		lastTeamJoin: null,
 		lastSyncAttempts: [],
 		lastSyncLegacyDevices: [],
+		lastSyncViewModel: null,
+		lastSyncDuplicatePersonDecisions: {},
 		pairingPayloadRaw: null,
 		pairingCommandRaw: "",
 		configDefaults: {},
@@ -373,6 +375,20 @@
 		if (!resp.ok) throw new Error(payload?.error || text || "request failed");
 		return payload;
 	}
+	async function renamePeer(peerDeviceId, name) {
+		const resp = await fetch("/api/sync/peers/rename", {
+			method: "POST",
+			headers: { "Content-Type": "application/json" },
+			body: JSON.stringify({
+				peer_device_id: peerDeviceId,
+				name
+			})
+		});
+		const text = await resp.text();
+		const payload = text ? JSON.parse(text) : {};
+		if (!resp.ok) throw new Error(payload?.error || text || "request failed");
+		return payload;
+	}
 	async function acceptDiscoveredPeer(peerDeviceId, fingerprint) {
 		const resp = await fetch("/api/sync/peers/accept-discovered", {
 			method: "POST",
@@ -1794,6 +1810,228 @@
 		if (state.activeTab === "feed" && previousActorId !== nextActorId) updateFeedView(true);
 	}
 	//#endregion
+	//#region src/tabs/sync/view-model.ts
+	var SYNC_TERMINOLOGY = {
+		actor: "person",
+		actors: "people",
+		actorAssignment: "person assignment",
+		localActor: "you",
+		peer: "device",
+		peers: "devices",
+		pairedLocally: "Connected on this device",
+		discovered: "Seen on team",
+		conflicts: "Needs repair"
+	};
+	function cleanText(value) {
+		return String(value ?? "").trim();
+	}
+	function normalizeDisplayName(value) {
+		return cleanText(value).replace(/\s+/g, " ").toLowerCase();
+	}
+	function friendlyDeviceFallback(deviceId) {
+		const cleanId = cleanText(deviceId);
+		return cleanId ? cleanId.slice(0, 8) : "Unnamed device";
+	}
+	function resolveFriendlyDeviceName(input) {
+		const localName = cleanText(input.localName);
+		if (localName) return localName;
+		const coordinatorName = cleanText(input.coordinatorName);
+		if (coordinatorName) return coordinatorName;
+		return friendlyDeviceFallback(cleanText(input.deviceId));
+	}
+	function deviceNeedsFriendlyName(input) {
+		const localName = cleanText(input.localName);
+		const coordinatorName = cleanText(input.coordinatorName);
+		if (localName || coordinatorName) return false;
+		return Boolean(cleanText(input.deviceId));
+	}
+	function derivePeerUiStatus(peer) {
+		const peerState = cleanText(peer?.status?.peer_state);
+		if (peer?.has_error || peerState === "degraded") return "needs-repair";
+		if (peerState === "online") return "connected";
+		if (peerState === "offline" || peerState === "stale") return "offline";
+		if (peer?.status?.fresh) return "connected";
+		return "waiting";
+	}
+	function deriveDuplicatePeople(actors) {
+		const groups = /* @__PURE__ */ new Map();
+		(Array.isArray(actors) ? actors : []).forEach((actor) => {
+			const displayName = cleanText(actor?.display_name);
+			const actorId = cleanText(actor?.actor_id);
+			const normalized = normalizeDisplayName(displayName);
+			if (!displayName || !actorId || !normalized) return;
+			const current = groups.get(normalized) ?? {
+				displayName,
+				actorIds: [],
+				includesLocal: false
+			};
+			current.actorIds = [...current.actorIds, actorId];
+			current.includesLocal = current.includesLocal || Boolean(actor?.is_local);
+			groups.set(normalized, current);
+		});
+		return [...groups.values()].filter((item) => item.actorIds.length > 1).sort((a, b) => a.displayName.localeCompare(b.displayName));
+	}
+	function deriveVisiblePeopleActors(input) {
+		const actors = Array.isArray(input.actors) ? input.actors : [];
+		const peers = Array.isArray(input.peers) ? input.peers : [];
+		const duplicatePeople = Array.isArray(input.duplicatePeople) ? input.duplicatePeople : [];
+		const assignedCounts = /* @__PURE__ */ new Map();
+		peers.forEach((peer) => {
+			const actorId = cleanText(peer?.actor_id);
+			if (!actorId) return;
+			assignedCounts.set(actorId, (assignedCounts.get(actorId) ?? 0) + 1);
+		});
+		const hiddenIds = /* @__PURE__ */ new Set();
+		duplicatePeople.forEach((candidate) => {
+			if (!candidate.includesLocal) return;
+			candidate.actorIds.forEach((actorId) => {
+				const actor = actors.find((item) => cleanText(item?.actor_id) === actorId);
+				if (!actor || actor.is_local) return;
+				if ((assignedCounts.get(actorId) ?? 0) > 0) return;
+				hiddenIds.add(actorId);
+			});
+		});
+		return {
+			visibleActors: actors.filter((actor) => !hiddenIds.has(cleanText(actor?.actor_id))),
+			hiddenLocalDuplicateCount: hiddenIds.size
+		};
+	}
+	function createRepairItem(device) {
+		return {
+			id: `repair:${device.id}`,
+			kind: "device-needs-repair",
+			priority: 10,
+			title: `${device.name} needs repair`,
+			summary: device.summary,
+			actionLabel: "Review device",
+			deviceId: device.id
+		};
+	}
+	function createReviewItem(device) {
+		return {
+			id: `review:${device.id}`,
+			kind: "review-team-device",
+			priority: 20,
+			title: `${device.name} is available to review`,
+			summary: device.summary,
+			actionLabel: "Review device",
+			deviceId: device.id
+		};
+	}
+	function createNamingItem(device) {
+		return {
+			id: `name:${device.id}`,
+			kind: "name-device",
+			priority: 30,
+			title: `Name ${device.name}`,
+			summary: device.summary,
+			actionLabel: "Name device",
+			deviceId: device.id
+		};
+	}
+	function mergeDevices(peers, discoveredDevices) {
+		const devices = /* @__PURE__ */ new Map();
+		const getOrCreate = (deviceId) => {
+			const current = devices.get(deviceId) ?? {
+				deviceId,
+				localName: "",
+				coordinatorName: "",
+				peer: null,
+				discovered: null
+			};
+			devices.set(deviceId, current);
+			return current;
+		};
+		peers.forEach((peer) => {
+			const deviceId = cleanText(peer?.peer_device_id);
+			if (!deviceId) return;
+			const current = getOrCreate(deviceId);
+			current.peer = peer;
+			current.localName = cleanText(peer?.name);
+		});
+		discoveredDevices.forEach((device) => {
+			const deviceId = cleanText(device?.device_id);
+			if (!deviceId) return;
+			const current = getOrCreate(deviceId);
+			current.discovered = device;
+			current.coordinatorName = cleanText(device?.display_name);
+		});
+		return [...devices.values()];
+	}
+	function deriveSyncViewModel(input) {
+		const actors = Array.isArray(input.actors) ? input.actors : [];
+		const peers = Array.isArray(input.peers) ? input.peers : [];
+		const discoveredDevices = Array.isArray(input.coordinator?.discovered_devices) ? input.coordinator.discovered_devices : [];
+		const mergedDevices = mergeDevices(peers, discoveredDevices);
+		const duplicateDecisions = input.duplicatePersonDecisions ?? {};
+		const duplicatePeople = deriveDuplicatePeople(actors).filter((candidate) => !duplicateDecisions[[...candidate.actorIds].sort().join("::")]);
+		const attentionItems = [];
+		duplicatePeople.forEach((candidate) => {
+			attentionItems.push({
+				id: `duplicate:${candidate.actorIds.join(":")}`,
+				kind: "possible-duplicate-person",
+				priority: candidate.includesLocal ? 5 : 15,
+				title: `Possible duplicate person: ${candidate.displayName}`,
+				summary: candidate.includesLocal ? "At least one entry is marked as you. Confirm whether these records represent the same person." : "Multiple people share this name. Confirm whether they should stay separate or be combined.",
+				actionLabel: "Review people",
+				actorIds: candidate.actorIds
+			});
+		});
+		mergedDevices.forEach((device) => {
+			const name = resolveFriendlyDeviceName({
+				localName: device.localName,
+				coordinatorName: device.coordinatorName,
+				deviceId: device.deviceId
+			});
+			const peerStatus = device.peer ? derivePeerUiStatus(device.peer) : "waiting";
+			const discoveredFingerprint = cleanText(device.discovered?.fingerprint);
+			const peerFingerprint = cleanText(device.peer?.fingerprint);
+			if (Boolean(device.peer) && Boolean(discoveredFingerprint) && Boolean(peerFingerprint) && discoveredFingerprint !== peerFingerprint) {
+				attentionItems.push(createRepairItem({
+					id: device.deviceId,
+					name,
+					summary: "This device identity changed. Repair or remove the older local record before reconnecting it."
+				}));
+				return;
+			}
+			if (device.peer && peerStatus === "needs-repair") {
+				const detail = cleanText(device.peer?.last_error) || "Sync health is degraded or broken.";
+				attentionItems.push(createRepairItem({
+					id: device.deviceId,
+					name,
+					summary: detail
+				}));
+			} else if (device.peer && peerStatus === "offline") attentionItems.push(createRepairItem({
+				id: device.deviceId,
+				name,
+				summary: "This device is offline or stale. Review it before re-pairing or retrying sync."
+			}));
+			else if (!device.peer && device.discovered && !device.discovered?.stale) attentionItems.push(createReviewItem({
+				id: device.deviceId,
+				name,
+				summary: "This device is seen on the team and is ready for review or connection on this machine."
+			}));
+			if (device.peer && deviceNeedsFriendlyName({
+				localName: device.localName,
+				coordinatorName: device.coordinatorName,
+				deviceId: device.deviceId
+			})) attentionItems.push(createNamingItem({
+				id: device.deviceId,
+				name,
+				summary: "Give this device a friendly name so it is easier to recognize later."
+			}));
+		});
+		return {
+			summary: {
+				connectedDeviceCount: peers.filter((peer) => derivePeerUiStatus(peer) === "connected").length,
+				seenOnTeamCount: discoveredDevices.length,
+				offlineTeamDeviceCount: discoveredDevices.filter((device) => Boolean(device?.stale)).length
+			},
+			duplicatePeople,
+			attentionItems: attentionItems.sort((a, b) => a.priority - b.priority || a.title.localeCompare(b.title))
+		};
+	}
+	//#endregion
 	//#region src/tabs/sync/helpers.ts
 	function hideSkeleton(id) {
 		const skeleton = document.getElementById(id);
@@ -1810,6 +2048,7 @@
 	var openPeerScopeEditors = /* @__PURE__ */ new Set();
 	var pendingPeerScopeReviewIds = /* @__PURE__ */ new Set();
 	var freshPeerScopeReviewIds = /* @__PURE__ */ new Set();
+	var DUPLICATE_PERSON_DECISIONS_KEY = "codemem-sync-duplicate-person-decisions";
 	function requestPeerScopeReview(peerDeviceId) {
 		const value = String(peerDeviceId || "").trim();
 		if (!value) return;
@@ -1832,6 +2071,41 @@
 		freshPeerScopeReviewIds.delete(value);
 		return true;
 	}
+	function readDuplicatePersonDecisionStore() {
+		try {
+			const raw = localStorage.getItem(DUPLICATE_PERSON_DECISIONS_KEY);
+			if (!raw) return {};
+			const parsed = JSON.parse(raw);
+			return parsed && typeof parsed === "object" ? parsed : {};
+		} catch {
+			return {};
+		}
+	}
+	function writeDuplicatePersonDecisionStore(value) {
+		try {
+			localStorage.setItem(DUPLICATE_PERSON_DECISIONS_KEY, JSON.stringify(value));
+		} catch {}
+	}
+	function duplicatePersonDecisionKey(actorIds) {
+		return [...actorIds].map((value) => String(value || "").trim()).filter(Boolean).sort().join("::");
+	}
+	function readDuplicatePersonDecisions() {
+		return readDuplicatePersonDecisionStore();
+	}
+	function saveDuplicatePersonDecision(actorIds, decision) {
+		const key = duplicatePersonDecisionKey(actorIds);
+		if (!key) return;
+		const next = readDuplicatePersonDecisionStore();
+		next[key] = decision;
+		writeDuplicatePersonDecisionStore(next);
+	}
+	function clearDuplicatePersonDecision(actorIds) {
+		const key = duplicatePersonDecisionKey(actorIds);
+		if (!key) return;
+		const next = readDuplicatePersonDecisionStore();
+		delete next[key];
+		writeDuplicatePersonDecisionStore(next);
+	}
 	/** Redact the last two octets of IPv4 addresses. */
 	function redactIpOctets(text) {
 		return text.replace(/\b(\d{1,3}\.\d{1,3})\.\d{1,3}\.\d{1,3}\b/g, "$1.#.#");
@@ -1850,24 +2124,24 @@
 		return value.split(",").map((item) => item.trim()).filter(Boolean);
 	}
 	function actorLabel(actor) {
-		if (!actor || typeof actor !== "object") return "Unknown actor";
+		if (!actor || typeof actor !== "object") return "Unknown person";
 		const displayName = String(actor.display_name || "").trim();
-		if (!displayName) return String(actor.actor_id || "Unknown actor");
+		if (!displayName) return String(actor.actor_id || "Unknown person");
 		return displayName;
 	}
 	function assignedActorCount(actorId) {
 		return (Array.isArray(state.lastSyncPeers) ? state.lastSyncPeers : []).filter((peer) => String(peer?.actor_id || "") === actorId).length;
 	}
 	function assignmentNote(actorId) {
-		if (!actorId) return "Unassigned devices keep legacy fallback attribution until you choose an actor.";
-		if ((Array.isArray(state.lastSyncActors) ? state.lastSyncActors : []).find((item) => String(item?.actor_id || "") === actorId)?.is_local) return "Local actor assignment keeps this device in your same-person continuity path, including private sync.";
-		return "This actor receives memories from allowed projects by default. Use Only me on a memory when it should stay local.";
+		if (!actorId) return "Unassigned devices keep legacy fallback attribution until you choose a person.";
+		if ((Array.isArray(state.lastSyncActors) ? state.lastSyncActors : []).find((item) => String(item?.actor_id || "") === actorId)?.is_local) return "Assigning this device to you keeps it in your same-person continuity path, including private sync.";
+		return "This person receives memories from allowed projects by default. Use Only me on a memory when it should stay local.";
 	}
 	function buildActorOptions(selectedActorId) {
 		const options = [];
 		const unassigned = document.createElement("option");
 		unassigned.value = "";
-		unassigned.textContent = "No actor assigned";
+		unassigned.textContent = "No person assigned";
 		options.push(unassigned);
 		(Array.isArray(state.lastSyncActors) ? state.lastSyncActors : []).forEach((actor) => {
 			const option = document.createElement("option");
@@ -1884,7 +2158,7 @@
 	}
 	function actorMergeNote(targetActorId, secondaryActorId) {
 		const target = mergeTargetActors(secondaryActorId).find((actor) => String(actor?.actor_id || "") === targetActorId);
-		if (!targetActorId || !target) return "Choose where this duplicate actor should collapse.";
+		if (!targetActorId || !target) return "Choose which person should keep these devices.";
 		return `Merge into ${actorLabel(target)}. Assigned devices move now; existing memories keep their current provenance.`;
 	}
 	function createChipEditor(initialValues, placeholder, emptyLabel) {
@@ -2288,7 +2562,7 @@
 			const row = el("div", "actor-row");
 			const details = el("div", "actor-details");
 			const title = el("div", "actor-title");
-			title.append(el("strong", null, String(item.peer_name || item.peer_device_id || "Device")), el("span", "badge actor-badge", `actor: ${String(item.actor_display_name || item.actor_id || "unknown")}`));
+			title.append(el("strong", null, String(item.peer_name || item.peer_device_id || "Device")), el("span", "badge actor-badge", `person: ${String(item.actor_display_name || item.actor_id || "unknown")}`));
 			const note = el("div", "peer-meta", `${Number(item.shareable_count || 0)} share by default \u00b7 ${Number(item.private_count || 0)} marked Only me \u00b7 ${String(item.scope_label || "All allowed projects")}`);
 			details.append(title, note);
 			const actions = el("div", "actor-actions");
@@ -2325,8 +2599,95 @@
 		if (discoveredList) discoveredList.textContent = "";
 		setInviteOutputVisibility();
 		const coordinator = state.lastSyncCoordinator;
+		const syncView = state.lastSyncViewModel || {
+			summary: {},
+			attentionItems: []
+		};
+		const focusAttentionTarget = (item) => {
+			if (item.kind === "possible-duplicate-person") {
+				const actorList = document.getElementById("syncActorsList");
+				if (actorList instanceof HTMLElement) actorList.scrollIntoView({
+					block: "center",
+					behavior: "smooth"
+				});
+				return;
+			}
+			const deviceId = String(item.deviceId || "").trim();
+			if (!deviceId) return;
+			if (item.kind === "name-device") {
+				const renameInput = document.querySelector(`[data-device-name-input="${CSS.escape(deviceId)}"]`);
+				if (renameInput instanceof HTMLInputElement) {
+					renameInput.scrollIntoView({
+						block: "center",
+						behavior: "smooth"
+					});
+					renameInput.focus();
+					renameInput.select();
+					return;
+				}
+			}
+			const peerCard = document.querySelector(`[data-peer-device-id="${CSS.escape(deviceId)}"]`);
+			if (peerCard instanceof HTMLElement) {
+				peerCard.scrollIntoView({
+					block: "center",
+					behavior: "smooth"
+				});
+				return;
+			}
+			const discoveredRow = document.querySelector(`[data-discovered-device-id="${CSS.escape(deviceId)}"]`);
+			if (discoveredRow instanceof HTMLElement) discoveredRow.scrollIntoView({
+				block: "center",
+				behavior: "smooth"
+			});
+		};
+		const reviewDuplicatePeople = async (item) => {
+			const actorIds = Array.isArray(item.actorIds) ? item.actorIds.map((value) => String(value || "").trim()).filter(Boolean) : [];
+			const actors = (Array.isArray(state.lastSyncActors) ? state.lastSyncActors : []).filter((actor) => actorIds.includes(String(actor?.actor_id || "").trim()));
+			if (actors.length < 2) {
+				showGlobalNotice("This possible duplicate no longer has enough people to review.", "warning");
+				return;
+			}
+			const firstAnswer = window.prompt(`Possible duplicate person: ${item.title.replace(/^Possible duplicate person:\s*/, "")}\n\nChoose an option:\n1 = These are both me\n2 = These are different people\n3 = Decide later`, "1");
+			const choice = String(firstAnswer || "").trim();
+			if (choice === "2") {
+				saveDuplicatePersonDecision(actorIds, "different-people");
+				showGlobalNotice("Okay. I will keep these people separate on this device.");
+				await _loadSyncData$1();
+				return;
+			}
+			if (choice !== "1") return;
+			clearDuplicatePersonDecision(actorIds);
+			const localIndex = actors.findIndex((actor) => Boolean(actor?.is_local));
+			const defaultChoice = localIndex >= 0 ? String(localIndex + 1) : "1";
+			const options = actors.map((actor, index) => `${index + 1} = ${String(actor?.display_name || actor?.actor_id || `Person ${index + 1}`)}${actor?.is_local ? " (You)" : ""}`).join("\n");
+			const keepAnswer = window.prompt(`Which person should remain after combining them?\n\n${options}`, defaultChoice);
+			const primary = actors[Number.parseInt(String(keepAnswer || defaultChoice), 10) - 1] ?? actors[0];
+			const secondary = actors.find((actor) => actor !== primary);
+			if (!primary?.actor_id || !secondary?.actor_id) {
+				showGlobalNotice("Could not determine which people to combine.", "warning");
+				return;
+			}
+			try {
+				await mergeActor(String(primary.actor_id), String(secondary.actor_id));
+				showGlobalNotice(`Combined duplicate people into ${String(primary.display_name || primary.actor_id)}.`);
+				await _loadSyncData$1();
+			} catch (error) {
+				showGlobalNotice(friendlyError(error, "Failed to combine these people."), "warning");
+			}
+		};
+		const promptForDeviceName = async (deviceId, suggestedName) => {
+			const nextName = window.prompt("What should this device be called? You can change it later in People & devices.", suggestedName);
+			const value = String(nextName || "").trim();
+			if (!value) {
+				showGlobalNotice("You can name this device later from People & devices.", "warning");
+				return false;
+			}
+			await renamePeer(deviceId, value);
+			showGlobalNotice(`Saved device name: ${value}.`);
+			return true;
+		};
 		const configured = Boolean(coordinator && coordinator.configured);
-		meta.textContent = configured ? `Connected to ${String(coordinator.coordinator_url || "")} \u00b7 group: ${(coordinator.groups || []).join(", ") || "none"}` : "Create a team invite or join an existing team to start syncing memories with teammates.";
+		meta.textContent = configured ? `Connected to ${String(coordinator.coordinator_url || "")} \u00b7 group: ${(coordinator.groups || []).join(", ") || "none"}` : "Start here: join an existing team or create a new one before connecting devices and people.";
 		if (!configured) {
 			setupPanel.hidden = false;
 			list.hidden = true;
@@ -2347,38 +2708,59 @@
 		const statusLine = el("div", "sync-team-status-row");
 		const statusLabel = el("span", "sync-team-status-label", "Status");
 		const statusBadge = el("span", `pill ${coordinator.presence_status === "posted" ? "pill-success" : coordinator.presence_status === "not_enrolled" ? "pill-warning" : "pill-error"}`, presenceLabel);
-		const metricParts = [`Paired devices: ${Number(coordinator.paired_peer_count || 0)}`, `Fresh discovered: ${Number(coordinator.fresh_peer_count || 0)}`];
-		if (Number(coordinator.stale_peer_count || 0) > 0) metricParts.push(`Inactive: ${Number(coordinator.stale_peer_count || 0)}`);
+		const metricParts = [`Connected devices: ${Number(syncView.summary?.connectedDeviceCount || 0)}`, `Seen on team: ${Number(syncView.summary?.seenOnTeamCount || 0)}`];
+		if (Number(syncView.summary?.offlineTeamDeviceCount || 0) > 0) metricParts.push(`Offline on team: ${Number(syncView.summary?.offlineTeamDeviceCount || 0)}`);
 		statusLine.append(statusLabel, statusBadge);
 		statusRow.append(statusLine, el("div", "sync-team-metrics", metricParts.join(" · ")));
 		list.appendChild(statusRow);
 		const localPeers = Array.isArray(state.lastSyncPeers) ? state.lastSyncPeers : [];
-		const unhealthyPeers = localPeers.filter((peer) => {
-			const status = peer?.status || {};
-			return Boolean(peer?.has_error) || [
-				"offline",
-				"stale",
-				"degraded"
-			].includes(String(status.peer_state || ""));
-		});
-		if (unhealthyPeers.length) {
+		const attentionItems = Array.isArray(syncView.attentionItems) ? syncView.attentionItems : [];
+		if (attentionItems.length) {
+			const heading = el("div", "sync-action-text");
+			heading.textContent = "Needs attention";
+			actions.appendChild(heading);
+			attentionItems.slice(0, 4).forEach((item) => {
+				const row = el("div", "sync-action");
+				const textWrap = el("div", "sync-action-text");
+				textWrap.textContent = item.title;
+				textWrap.appendChild(el("span", "sync-action-command", item.summary));
+				const actionButton = el("button", "settings-button", item.actionLabel || "Review");
+				actionButton.addEventListener("click", async () => {
+					if (item.kind === "possible-duplicate-person") {
+						await reviewDuplicatePeople(item);
+						return;
+					}
+					focusAttentionTarget(item);
+				});
+				row.append(textWrap, actionButton);
+				actions.appendChild(row);
+			});
+		} else if (coordinator.presence_status === "posted") {
+			const row = el("div", "sync-action");
+			const textWrap = el("div", "sync-action-text");
+			textWrap.textContent = "No immediate issues";
+			textWrap.appendChild(el("span", "sync-action-command", "Your devices and team records do not currently need review."));
+			row.appendChild(textWrap);
+			actions.appendChild(row);
+		} else if (coordinator.presence_status === "not_enrolled") {
 			const row = el("div", "sync-action");
 			const textWrap = el("div", "sync-action-text");
-			textWrap.textContent = `${unhealthyPeers.length} paired device${unhealthyPeers.length === 1 ? "" : "s"} look stale or unhealthy.`;
-			textWrap.appendChild(el("span", "sync-action-command", "Use Remove peer in People or codemem sync peers remove <peer> before re-pairing."));
+			textWrap.textContent = "This device still needs team enrollment";
+			textWrap.appendChild(el("span", "sync-action-command", "Import an invite or ask your admin to enroll this device before expecting sync activity here."));
 			row.appendChild(textWrap);
 			actions.appendChild(row);
 		}
 		const discoveredDevices = Array.isArray(coordinator.discovered_devices) ? coordinator.discovered_devices : [];
 		if (discoveredPanel && discoveredMeta && discoveredList && discoveredDevices.length) {
 			discoveredPanel.hidden = false;
-			discoveredMeta.textContent = "These devices are visible through coordinator discovery only. They are not active sync peers unless you pair them.";
+			discoveredMeta.textContent = "These devices are visible through team discovery. Review them before connecting them on this machine.";
 			discoveredDevices.forEach((device) => {
 				const row = el("div", "actor-row");
 				const details = el("div", "actor-details");
 				const title = el("div", "actor-title");
 				const rowActions = el("div", "actor-actions");
 				const deviceId = String(device.device_id || "").trim();
+				if (deviceId) row.dataset.discoveredDeviceId = deviceId;
 				const displayName = String(device.display_name || "").trim() || deviceId || "Discovered device";
 				const fingerprint = String(device.fingerprint || "").trim();
 				const pairedPeer = localPeers.find((peer) => String(peer?.peer_device_id || "") === deviceId);
@@ -2386,8 +2768,8 @@
 				const hasConflict = Boolean(pairedPeer) && Boolean(fingerprint) && Boolean(pairedFingerprint) && pairedFingerprint !== fingerprint;
 				const canAccept = Boolean(deviceId) && Boolean(fingerprint) && !pairedPeer && !device.stale;
 				title.append(el("strong", null, displayName));
-				title.appendChild(el("span", `badge actor-badge${device.stale ? "" : " local"}`, device.stale ? "Inactive" : "Fresh"));
-				title.appendChild(el("span", "badge actor-badge", hasConflict ? "Conflicts with local peer" : pairedPeer ? "Paired locally" : "Not paired locally"));
+				title.appendChild(el("span", `badge actor-badge${device.stale ? "" : " local"}`, device.stale ? "Offline" : "Available"));
+				title.appendChild(el("span", "badge actor-badge", hasConflict ? SYNC_TERMINOLOGY.conflicts : pairedPeer ? SYNC_TERMINOLOGY.pairedLocally : "Not connected on this device"));
 				const addresses = Array.isArray(device.addresses) ? device.addresses : [];
 				const noteParts = [deviceId, addresses.length ? addresses.map((address) => isSyncRedactionEnabled() ? redactAddress(String(address || "")) : String(address || "")).filter(Boolean).join(" · ") : "No fresh addresses"];
 				if (hasConflict) noteParts.push("repair the local peer before accepting this discovered device");
@@ -2396,27 +2778,36 @@
 				else if (pairedPeer?.status?.peer_state) noteParts.push(`paired status: ${String(pairedPeer.status.peer_state)}`);
 				details.append(title, el("div", "peer-meta", noteParts.join(" · ")));
 				if (canAccept) {
-					const acceptBtn = el("button", "settings-button", "Accept peer");
+					const acceptBtn = el("button", "settings-button", "Review device");
 					acceptBtn.addEventListener("click", async () => {
 						acceptBtn.disabled = true;
-						acceptBtn.textContent = "Accepting…";
+						acceptBtn.textContent = "Opening…";
 						try {
-							await acceptDiscoveredPeer(deviceId, fingerprint);
+							const result = await acceptDiscoveredPeer(deviceId, fingerprint);
 							requestPeerScopeReview(deviceId);
-							showGlobalNotice(`Accepted ${displayName}. Its scope editor is now open in People so you can review sync scope next.`);
-							await _loadSyncData$1();
+							showGlobalNotice(`Connected ${displayName}. Its device settings are now open in People & devices so you can review sync scope next.`);
+							try {
+								await promptForDeviceName(deviceId, String(result?.name || displayName || "").trim() || displayName);
+							} catch (error) {
+								showGlobalNotice(friendlyError(error, "Device connected, but naming did not finish."), "warning");
+							}
+							try {
+								await _loadSyncData$1();
+							} catch (error) {
+								showGlobalNotice(friendlyError(error, "Device connected, but the screen did not refresh yet."), "warning");
+							}
 						} catch (error) {
-							showGlobalNotice(friendlyError(error, "Failed to accept discovered peer."), "warning");
-							acceptBtn.textContent = "Retry accept";
+							showGlobalNotice(friendlyError(error, "Failed to review this device."), "warning");
+							acceptBtn.textContent = "Retry review";
 						} finally {
 							acceptBtn.disabled = false;
-							if (acceptBtn.textContent === "Accepting…") acceptBtn.textContent = "Accept peer";
+							if (acceptBtn.textContent === "Opening…") acceptBtn.textContent = "Review device";
 						}
 					});
 					rowActions.appendChild(acceptBtn);
 				} else if (!pairedPeer && device.stale) rowActions.appendChild(el("div", "peer-meta", "Wait for a fresh coordinator presence update."));
 				else if (hasConflict) {
-					const inspectBtn = el("button", "settings-button", "Jump to local peer");
+					const inspectBtn = el("button", "settings-button", "Open device details");
 					inspectBtn.addEventListener("click", () => {
 						const peerCard = document.querySelector(`[data-peer-device-id="${CSS.escape(deviceId)}"]`);
 						if (peerCard instanceof HTMLElement) {
@@ -2424,34 +2815,34 @@
 								block: "center",
 								behavior: "smooth"
 							});
-							showGlobalNotice(`Jumped to the conflicting local peer for ${displayName}.`, "warning");
+							showGlobalNotice(`Opened the conflicting local device record for ${displayName}.`, "warning");
 							return;
 						}
-						showGlobalNotice("Conflicting local peer is not visible yet. Scroll to the People area and try again.", "warning");
+						showGlobalNotice("The conflicting local device record is not visible yet. Scroll to People & devices and try again.", "warning");
 					});
-					const removeConflictBtn = el("button", "settings-button", "Remove conflicting peer");
+					const removeConflictBtn = el("button", "settings-button", "Remove broken device record");
 					removeConflictBtn.addEventListener("click", async () => {
 						if (!pairedPeer) return;
-						if (!window.confirm(`Remove the conflicting local peer for ${displayName}? You can accept the discovered device again after this refreshes.`)) return;
+						if (!window.confirm(`Remove the broken local device record for ${displayName}? You can review this device again after the screen refreshes.`)) return;
 						removeConflictBtn.disabled = true;
 						inspectBtn.disabled = true;
 						removeConflictBtn.textContent = "Removing…";
 						try {
 							await deletePeer(deviceId);
-							showGlobalNotice(`Removed the conflicting local peer for ${displayName}. If it is still fresh, you can now accept it from Team sync.`);
+							showGlobalNotice(`Removed the broken local device record for ${displayName}. If it is still available, you can review it again from Needs attention.`);
 							await _loadSyncData$1();
 						} catch (error) {
-							showGlobalNotice(friendlyError(error, "Failed to remove the conflicting local peer."), "warning");
+							showGlobalNotice(friendlyError(error, "Failed to remove the broken local device record."), "warning");
 							removeConflictBtn.textContent = "Retry remove";
 						} finally {
 							removeConflictBtn.disabled = false;
 							inspectBtn.disabled = false;
-							if (removeConflictBtn.textContent === "Removing…") removeConflictBtn.textContent = "Remove conflicting peer";
+							if (removeConflictBtn.textContent === "Removing…") removeConflictBtn.textContent = "Remove broken device record";
 						}
 					});
 					rowActions.append(inspectBtn, removeConflictBtn);
-				} else if (pairedPeer && isPeerScopeReviewPending(deviceId)) rowActions.appendChild(el("div", "peer-meta", "Review this peer's scope in People next."));
-				else if (pairedPeer) rowActions.appendChild(el("div", "peer-meta", "Manage this peer in People."));
+				} else if (pairedPeer && isPeerScopeReviewPending(deviceId)) rowActions.appendChild(el("div", "peer-meta", "Review this device's scope in People & devices next."));
+				else if (pairedPeer) rowActions.appendChild(el("div", "peer-meta", "Manage this device in People & devices."));
 				row.append(details, rowActions);
 				discoveredList.appendChild(row);
 			});
@@ -2647,10 +3038,18 @@
 		if (!actorList) return;
 		hideSkeleton("syncActorsSkeleton");
 		actorList.textContent = "";
-		const actors = Array.isArray(state.lastSyncActors) ? state.lastSyncActors : [];
-		if (actorMeta) actorMeta.textContent = actors.length ? "Create, rename, and merge actors here. Assign each device below. Non-local actors receive memories from allowed projects unless you mark them Only me." : "No named actors yet. Create one here, then assign devices below.";
+		const actorVisibility = deriveVisiblePeopleActors({
+			actors: state.lastSyncActors,
+			peers: state.lastSyncPeers,
+			duplicatePeople: state.lastSyncViewModel?.duplicatePeople
+		});
+		const actors = actorVisibility.visibleActors;
+		if (actorMeta) {
+			actorMeta.textContent = actors.length ? "Create, rename, and combine people here. Assign each device below. Non-local people receive memories from allowed projects unless you mark them Only me." : "No named people yet. Create one here, then assign devices below.";
+			if (actorVisibility.hiddenLocalDuplicateCount > 0) actorMeta.textContent += ` ${actorVisibility.hiddenLocalDuplicateCount} unresolved duplicate ${actorVisibility.hiddenLocalDuplicateCount === 1 ? "entry is" : "entries are"} hidden here until reviewed in Needs attention.`;
+		}
 		if (!actors.length) {
-			actorList.appendChild(el("div", "sync-empty-state", "No actors yet. Create one to represent yourself or a teammate."));
+			actorList.appendChild(el("div", "sync-empty-state", "No people yet. Create one to represent yourself or a teammate."));
 			return;
 		}
 		actors.forEach((actor) => {
@@ -2661,7 +3060,7 @@
 			const count = assignedActorCount(String(actor.actor_id || ""));
 			const badge = el("span", `badge actor-badge${actor.is_local ? " local" : ""}`, actor.is_local ? "Local" : `${count} device${count === 1 ? "" : "s"}`);
 			title.append(name, badge);
-			const note = el("div", "peer-meta", actor.is_local ? "Used for this device and same-person devices." : `${count} assigned device${count === 1 ? "" : "s"}`);
+			const note = el("div", "peer-meta", actor.is_local ? `Used for this device and same-person devices.${actorVisibility.hiddenLocalDuplicateCount > 0 ? ` ${actorVisibility.hiddenLocalDuplicateCount} unresolved duplicate ${actorVisibility.hiddenLocalDuplicateCount === 1 ? "entry is" : "entries are"} hidden until reviewed in Needs attention.` : ""}` : `${count} assigned device${count === 1 ? "" : "s"}`);
 			details.append(title, note);
 			const actions = el("div", "actor-actions");
 			if (actor.is_local) actions.appendChild(el("div", "peer-meta", "Rename in config"));
@@ -2693,10 +3092,10 @@
 				const mergeControls = el("div", "actor-merge-controls");
 				const mergeSelect = document.createElement("select");
 				mergeSelect.className = "sync-actor-select actor-merge-select";
-				mergeSelect.setAttribute("aria-label", `Merge ${actorLabel(actor)} into another actor`);
+				mergeSelect.setAttribute("aria-label", `Combine ${actorLabel(actor)} into another person`);
 				const placeholder = document.createElement("option");
 				placeholder.value = "";
-				placeholder.textContent = "Merge into actor";
+				placeholder.textContent = "Combine into person";
 				placeholder.selected = true;
 				mergeSelect.appendChild(placeholder);
 				mergeTargets.forEach((target) => {
@@ -2705,16 +3104,16 @@
 					option.textContent = target.is_local ? `${actorLabel(target)} (local)` : actorLabel(target);
 					mergeSelect.appendChild(option);
 				});
-				const mergeBtn = el("button", "settings-button", "Merge into selected actor");
+				const mergeBtn = el("button", "settings-button", "Combine into selected person");
 				mergeBtn.disabled = mergeTargets.length === 0;
-				const mergeNote = el("div", "peer-meta actor-merge-note", mergeTargets.length ? actorMergeNote("", actorId) : "No merge targets yet. Create another actor or use the local actor.");
+				const mergeNote = el("div", "peer-meta actor-merge-note", mergeTargets.length ? actorMergeNote("", actorId) : "No people available to combine yet. Create another person or use You.");
 				mergeSelect.addEventListener("change", () => {
 					mergeNote.textContent = actorMergeNote(mergeSelect.value, actorId);
 				});
 				mergeBtn.addEventListener("click", async () => {
 					if (!mergeSelect.value) return;
 					const target = mergeTargets.find((candidate) => String(candidate.actor_id || "") === mergeSelect.value);
-					if (!window.confirm(`Merge ${actorLabel(actor)} into ${actorLabel(target)}? Assigned devices move now, but older memories keep their current stamped provenance for now.`)) return;
+					if (!window.confirm(`Combine ${actorLabel(actor)} into ${actorLabel(target)}? Assigned devices move now, but older memories keep their current stamped provenance for now.`)) return;
 					mergeBtn.disabled = true;
 					mergeSelect.disabled = true;
 					input.disabled = true;
@@ -2722,17 +3121,17 @@
 					mergeBtn.textContent = "Merging…";
 					try {
 						await mergeActor(mergeSelect.value, actorId);
-						showGlobalNotice("Actor merged. Assigned devices moved to the selected actor.");
+						showGlobalNotice("People combined. Assigned devices moved to the selected person.");
 						await _loadSyncData();
 					} catch (error) {
-						showGlobalNotice(friendlyError(error, "Failed to merge actor."), "warning");
+						showGlobalNotice(friendlyError(error, "Failed to combine people."), "warning");
 						mergeBtn.textContent = "Retry merge";
 					} finally {
 						mergeBtn.disabled = mergeTargets.length === 0;
 						mergeSelect.disabled = false;
 						input.disabled = false;
 						renameBtn.disabled = false;
-						if (mergeBtn.textContent === "Merging…") mergeBtn.textContent = "Merge into selected actor";
+						if (mergeBtn.textContent === "Merging…") mergeBtn.textContent = "Combine into selected person";
 					}
 				});
 				mergeControls.append(mergeSelect, mergeBtn);
@@ -2749,7 +3148,7 @@
 		syncPeers.textContent = "";
 		const peers = state.lastSyncPeers;
 		if (!Array.isArray(peers) || !peers.length) {
-			syncPeers.appendChild(el("div", "sync-empty-state", "No devices paired yet. Use the pairing command in Diagnostics to connect another device."));
+			syncPeers.appendChild(el("div", "sync-empty-state", "No devices connected on this machine yet. Use the pairing command in Diagnostics to connect another device."));
 			return;
 		}
 		peers.forEach((peer) => {
@@ -2768,6 +3167,38 @@
 			name.append(" ", badge);
 			if (pendingScopeReview) name.append(" ", el("span", "badge actor-badge", "Needs scope review"));
 			const actions = el("div", "peer-actions");
+			const renameInput = document.createElement("input");
+			renameInput.className = "peer-scope-input";
+			renameInput.value = displayName;
+			if (peerId) renameInput.dataset.deviceNameInput = peerId;
+			renameInput.setAttribute("aria-label", `Friendly name for ${displayName}`);
+			renameInput.placeholder = "Friendly device name";
+			const renameBtn = el("button", null, "Save name");
+			renameBtn.addEventListener("click", async () => {
+				if (!peerId) return;
+				const nextName = String(renameInput.value || "").trim();
+				if (!nextName) {
+					showGlobalNotice("Enter a friendly name for this device.", "warning");
+					renameInput.focus();
+					return;
+				}
+				renameBtn.disabled = true;
+				renameInput.disabled = true;
+				renameBtn.textContent = "Saving…";
+				try {
+					await renamePeer(peerId, nextName);
+					showGlobalNotice("Device name saved.");
+					await _loadSyncData();
+				} catch (error) {
+					showGlobalNotice(friendlyError(error, "Failed to save device name."), "warning");
+					renameBtn.textContent = "Retry save";
+				} finally {
+					renameBtn.disabled = false;
+					renameInput.disabled = false;
+					if (renameBtn.textContent === "Saving…") renameBtn.textContent = "Save name";
+				}
+			});
+			actions.append(renameInput, renameBtn);
 			const primaryAddress = pickPrimaryAddress(peer.addresses);
 			const syncBtn = el("button", null, "Sync now");
 			syncBtn.disabled = !primaryAddress;
@@ -2823,7 +3254,7 @@
 			const lastSyncAt = peerStatus.last_sync_at || peerStatus.last_sync_at_utc || "";
 			const lastPingAt = peerStatus.last_ping_at || peerStatus.last_ping_at_utc || "";
 			const meta = el("div", "peer-meta", [lastSyncAt ? `Sync: ${formatTimestamp(lastSyncAt)}` : "Sync: never", lastPingAt ? `Ping: ${formatTimestamp(lastPingAt)}` : "Ping: never"].join(" · "));
-			const identityMeta = el("div", "peer-meta", peer.actor_display_name ? `Assigned to ${String(peer.actor_display_name)}${peer.claimed_local_actor ? " · local actor" : ""}` : "Unassigned actor");
+			const identityMeta = el("div", "peer-meta", peer.actor_display_name ? `Assigned to ${String(peer.actor_display_name)}${peer.claimed_local_actor ? " · you" : ""}` : "Unassigned person");
 			const scope = peer.project_scope || {};
 			const includeList = Array.isArray(scope.include) ? scope.include : [];
 			const excludeList = Array.isArray(scope.exclude) ? scope.exclude : [];
@@ -2832,13 +3263,13 @@
 			const inheritsGlobal = Boolean(scope.inherits_global);
 			const scopePanel = el("div", "peer-scope");
 			const identityRow = el("div", "peer-scope-summary");
-			identityRow.textContent = "Assigned actor";
+			identityRow.textContent = "Assigned person";
 			const actorRow = el("div", "peer-actor-row");
 			const actorSelect = document.createElement("select");
 			actorSelect.className = "sync-actor-select";
-			actorSelect.setAttribute("aria-label", `Assigned actor for ${displayName}`);
+			actorSelect.setAttribute("aria-label", `Assigned person for ${displayName}`);
 			buildActorOptions(String(peer.actor_id || "")).forEach((option) => actorSelect.appendChild(option));
-			const applyActorBtn = el("button", "settings-button", "Save actor");
+			const applyActorBtn = el("button", "settings-button", "Save person");
 			const actorHint = el("div", "peer-scope-effective", assignmentNote(String(peer.actor_id || "")));
 			actorSelect.addEventListener("change", () => {
 				actorHint.textContent = assignmentNote(actorSelect.value);
@@ -2849,15 +3280,15 @@
 				applyActorBtn.textContent = "Applying…";
 				try {
 					await assignPeerActor(peerId, actorSelect.value || null);
-					showGlobalNotice(actorSelect.value ? "Device actor updated." : "Device actor cleared.");
+					showGlobalNotice(actorSelect.value ? "Device person updated." : "Device person cleared.");
 					await _loadSyncData();
 				} catch (error) {
-					showGlobalNotice(friendlyError(error, "Failed to update device actor."), "warning");
+					showGlobalNotice(friendlyError(error, "Failed to update device person."), "warning");
 					applyActorBtn.textContent = "Retry";
 				} finally {
 					actorSelect.disabled = false;
 					applyActorBtn.disabled = false;
-					if (applyActorBtn.textContent === "Applying…") applyActorBtn.textContent = "Save actor";
+					if (applyActorBtn.textContent === "Applying…") applyActorBtn.textContent = "Save person";
 				}
 			});
 			actorRow.append(actorSelect, applyActorBtn);
@@ -2969,7 +3400,7 @@
 			if (!syncActorCreateButton || !syncActorCreateInput) return;
 			const displayName = String(syncActorCreateInput.value || "").trim();
 			if (!displayName) {
-				markFieldError(syncActorCreateInput, "Enter a name for the actor.");
+				markFieldError(syncActorCreateInput, "Enter a name for the person.");
 				return;
 			}
 			clearFieldError(syncActorCreateInput);
@@ -2978,30 +3409,30 @@
 			syncActorCreateButton.textContent = "Creating…";
 			try {
 				await createActor(displayName);
-				showGlobalNotice("Actor created.");
+				showGlobalNotice("Person created.");
 				syncActorCreateInput.value = "";
 				await loadSyncData();
 			} catch (error) {
-				showGlobalNotice(friendlyError(error, "Failed to create actor."), "warning");
+				showGlobalNotice(friendlyError(error, "Failed to create person."), "warning");
 				syncActorCreateButton.textContent = "Retry";
 				syncActorCreateButton.disabled = false;
 				syncActorCreateInput.disabled = false;
 				return;
 			}
-			syncActorCreateButton.textContent = "Create actor";
+			syncActorCreateButton.textContent = "Create person";
 			syncActorCreateButton.disabled = false;
 			syncActorCreateInput.disabled = false;
 		});
 		syncLegacyClaimButton?.addEventListener("click", async () => {
 			const originDeviceId = String(syncLegacyDeviceSelect?.value || "").trim();
 			if (!originDeviceId || !syncLegacyClaimButton) return;
-			if (!window.confirm(`Attach old device history from ${originDeviceId} to your local actor? This updates legacy provenance for that device.`)) return;
+			if (!window.confirm(`Attach old device history from ${originDeviceId} to you? This updates legacy provenance for that device.`)) return;
 			syncLegacyClaimButton.disabled = true;
 			const originalText = syncLegacyClaimButton.textContent || "Attach device history";
 			syncLegacyClaimButton.textContent = "Attaching…";
 			try {
 				await claimLegacyDeviceIdentity(originDeviceId);
-				showGlobalNotice("Old device history attached to your local actor.");
+				showGlobalNotice("Old device history attached to you.");
 				await loadSyncData();
 			} catch (error) {
 				showGlobalNotice(friendlyError(error, "Failed to attach old device history."), "warning");
@@ -3060,12 +3491,17 @@
 			}
 			let actorsPayload = null;
 			let actorLoadError = false;
+			const duplicatePersonDecisions = readDuplicatePersonDecisions();
 			try {
 				actorsPayload = await loadSyncActors();
 			} catch {
 				actorLoadError = true;
 			}
-			const hash = JSON.stringify([payload, actorsPayload]);
+			const hash = JSON.stringify([
+				payload,
+				actorsPayload,
+				duplicatePersonDecisions
+			]);
 			if (hash === lastSyncHash) return;
 			lastSyncHash = hash;
 			const statusPayload = payload.status && typeof payload.status === "object" ? payload.status : null;
@@ -3077,6 +3513,13 @@
 			if (Array.isArray(payload.join_requests)) state.lastSyncJoinRequests = payload.join_requests;
 			state.lastSyncAttempts = payload.attempts || [];
 			state.lastSyncLegacyDevices = payload.legacy_devices || [];
+			state.lastSyncDuplicatePersonDecisions = duplicatePersonDecisions;
+			state.lastSyncViewModel = deriveSyncViewModel({
+				actors: state.lastSyncActors,
+				peers: state.lastSyncPeers,
+				coordinator: state.lastSyncCoordinator,
+				duplicatePersonDecisions: state.lastSyncDuplicatePersonDecisions
+			});
 			renderSyncStatus();
 			renderTeamSync();
 			renderSyncActors();
@@ -3087,7 +3530,7 @@
 			renderHealthOverview();
 			if (actorLoadError) {
 				const actorMeta = document.getElementById("syncActorsMeta");
-				if (actorMeta) actorMeta.textContent = "Actor controls are temporarily unavailable. Peer status and sync health still loaded.";
+				if (actorMeta) actorMeta.textContent = "People controls are temporarily unavailable. Device status and sync health still loaded.";
 			}
 		} catch {
 			hideSkeleton("syncTeamSkeleton");

package/static/index.html

@@ -1723,15 +1723,15 @@
     <!-- ── Tab: Sync ───────────────────────────────────────── -->
     <div class="tab-panel" id="tab-sync" hidden>
 
-      <!-- 1. Team sync — primary, always visible -->
+      <!-- 1. Needs attention + team setup/status -->
       <div class="card" id="syncTeamCard">
         <div class="section-header">
-          <h2>Team sync</h2>
+          <h2>Needs attention</h2>
           <div class="section-actions">
             <button class="settings-button" id="syncNowButton">Sync now</button>
           </div>
         </div>
-        <div class="section-meta" id="syncTeamMeta"></div>
+        <div class="section-meta" id="syncTeamMeta">See what needs action first, then review the current team status below.</div>
         <div class="sync-skeleton" id="syncTeamSkeleton" role="status" aria-label="Loading team sync">
           <div class="sync-skeleton-line medium"></div>
           <div class="sync-skeleton-block"></div>
@@ -1772,26 +1772,27 @@
             </div>
           </div>
         </div>
+        <h3 class="settings-group-title" style="margin-top: 20px">Team status</h3>
         <div class="actor-list" id="syncTeamStatus" aria-live="polite"></div>
         <div class="actor-list" id="syncJoinRequests"></div>
         <div id="syncCoordinatorDiscovered" hidden>
-          <h3 class="settings-group-title" style="margin-top: 20px">Coordinator-discovered devices</h3>
+          <h3 class="settings-group-title" style="margin-top: 20px">Devices seen on team</h3>
           <div class="section-meta" id="syncCoordinatorDiscoveredMeta"></div>
           <div class="actor-list" id="syncCoordinatorDiscoveredList"></div>
         </div>
         <div class="sync-actions" id="syncTeamActions" hidden></div>
       </div>
 
-      <!-- 2. People — actors, devices, sharing, legacy claims -->
+      <!-- 2. People & devices -->
       <div class="card" style="animation-delay: 0.04s">
-        <h2>People</h2>
+        <h2>People &amp; devices</h2>
 
-        <h3 class="settings-group-title">Actors</h3>
-        <div class="section-meta" id="syncActorsMeta">Create and rename actors here. Assign each device below.</div>
+        <h3 class="settings-group-title">People</h3>
+        <div class="section-meta" id="syncActorsMeta">Create and rename people here. Assign each device below.</div>
         <div class="actor-create-row">
-          <label for="syncActorCreateInput" class="sr-only">Actor name</label>
-          <input class="peer-scope-input" id="syncActorCreateInput" placeholder="Create a named actor" />
-          <button class="settings-button" id="syncActorCreateButton">Create actor</button>
+          <label for="syncActorCreateInput" class="sr-only">Person name</label>
+          <input class="peer-scope-input" id="syncActorCreateInput" placeholder="Create a named person" />
+          <button class="settings-button" id="syncActorCreateButton">Create person</button>
         </div>
         <div class="actor-list" id="syncActorsList"></div>
         <div class="sync-skeleton" id="syncActorsSkeleton" role="status" aria-label="Loading actors">
@@ -1823,10 +1824,10 @@
         </div>
       </div>
 
-      <!-- 3. Diagnostics — status, pairing, attempts -->
+      <!-- 3. Advanced diagnostics — status, pairing, attempts -->
       <div class="card" style="animation-delay: 0.06s">
         <div class="section-header">
-          <h2>Diagnostics</h2>
+          <h2>Advanced diagnostics</h2>
           <div class="section-actions">
             <button class="settings-button" id="syncPairingToggle">Show pairing</button>
             <label class="small" style="display:inline-flex;align-items:center;gap:6px;">
@@ -1835,7 +1836,7 @@
             </label>
           </div>
         </div>
-        <div class="section-meta" id="syncMeta">Loading sync status…</div>
+        <div class="section-meta" id="syncMeta">Debug details for sync status, pairing, and recent attempts.</div>
         <div class="sync-skeleton" id="syncDiagSkeleton" role="status" aria-label="Loading diagnostics">
           <div class="sync-skeleton-line long"></div>
           <div class="sync-skeleton-line medium"></div>