@oxyhq/services 26.1.0 → 27.0.0

package/src/ui/hooks/queries/userCache.ts

@@ -36,10 +36,38 @@
  *     never overwritten by a degraded/empty one (empty username, the
  *     `'Unknown user'` ghost-author sentinel, `null` avatar).
  *
+ * EXPRESSING A DELIBERATE CLEAR ("remove my picture")
+ * ---------------------------------------------------
+ * The anti-degradation rule above is right for a sparse source and wrong for a
+ * user who just emptied the field — and the two are NOT distinguishable from the
+ * payload. Measured against oxy-api's canonical serializer (`formatUserResponse`
+ * in `packages/api/src/utils/userTransform.ts`, which passes every field through
+ * `typeof value === 'string' ? value : undefined`): an account whose avatar,
+ * bio and display name were all just CLEARED serializes to
+ * `{"id":…,"publicKey":…,"username":…,"name":{},"languages":[]}` — byte-identical
+ * to the same account read as a sparse projection. There is no `null` and no
+ * `''` on the wire to key on. The information that a field was deliberately
+ * emptied exists ONLY at the call site that performed the write.
+ *
+ * So the caller declares it: `upsertCachedUser(qc, user, viewerId, { cleared:
+ * ['avatar'] })`. For a declared field an incoming EMPTY value means the field
+ * IS empty and the stale value is dropped; a MEANINGFUL incoming value still
+ * wins as usual (so `{ cleared: ['name.displayName'] }` on a personal account,
+ * where clearing the explicit name makes the server return the COMPOSED one,
+ * keeps the composed name rather than blanking it).
+ *
+ * A blanket "this source is authoritative, treat every absent field as cleared"
+ * flag was considered and rejected: because the two payloads are byte-identical,
+ * such a flag is an unverifiable promise about provenance, and the failure mode
+ * of getting it wrong is blanking real identity data in every Oxy app. Naming
+ * the fields states something the caller actually observed — which fields the
+ * user emptied — and bounds the damage to exactly those.
+ *
  * It is a cache write only — zero network, one `setQueryData` per key.
  */
 
-import type { UserNameResponse } from "@oxyhq/contracts";
+import type { UserNameResponse, UserProfileUpdate } from "@oxyhq/contracts";
+import type { UpdateAccountInput } from "@oxyhq/core";
 import type { QueryClient } from "@tanstack/react-query";
 import { useAuthStore } from "../../stores/authStore";
 import { queryKeys } from "./queryKeys";
@@ -78,6 +106,108 @@ export interface CacheableUser {
 /** The degraded display-name sentinel (ghost-author rule). */
 const DEGRADED_DISPLAY_NAME = "Unknown user";
 
+/**
+ * The profile fields a user can genuinely EMPTY through a real Oxy write, and
+ * for which "empty" is a state every renderer already handles.
+ *
+ * Deliberately a closed list rather than "any field": a clear DELETES data from
+ * the cache, so the blast radius of a mistaken declaration is bounded here
+ * instead of resting on each call site. `username` is absent because an account
+ * always has one; `_count` and `relationship` are absent because they are
+ * server-derived, never user-emptied — and dropping a viewer `relationship` is
+ * the exact "Follows you vanishes" bug this module exists to prevent.
+ *
+ * Each entry is clearable through a shipped write path: `avatar`, `bio`,
+ * `description` and `name.displayName` via `UserProfileUpdate` (`''` clears) and
+ * `UpdateAccountInput` (`null` clears avatar/bio; `accountCategories: []`
+ * clears the ordered category list), and `color` via its nullable field.
+ */
+export const CLEARABLE_USER_FIELDS = [
+	"avatar",
+	"bio",
+	"description",
+	"color",
+	"accountCategories",
+	"name.displayName",
+] as const;
+
+/** A field nameable in {@link UpsertCachedUserOptions.cleared}. */
+export type ClearableUserField = (typeof CLEARABLE_USER_FIELDS)[number];
+
+/**
+ * Fields the caller deliberately emptied in a `PUT /users/me` patch. The wire
+ * response omits cleared scalars, so the cache needs this list to drop stale
+ * values immediately instead of waiting for a refetch that merges the same
+ * sparse payload.
+ */
+export function clearedFieldsFromProfileUpdate(
+	updates: UserProfileUpdate,
+): ClearableUserField[] {
+	const cleared: ClearableUserField[] = [];
+	if ("avatar" in updates && !isMeaningful(updates.avatar)) {
+		cleared.push("avatar");
+	}
+	if ("bio" in updates && !isMeaningful(updates.bio)) {
+		cleared.push("bio");
+	}
+	if ("description" in updates && !isMeaningful(updates.description)) {
+		cleared.push("description");
+	}
+	if ("color" in updates && updates.color === null) {
+		cleared.push("color");
+	}
+	if (
+		updates.name !== undefined &&
+		"displayName" in updates.name &&
+		!isMeaningful(updates.name.displayName)
+	) {
+		cleared.push("name.displayName");
+	}
+	return cleared;
+}
+
+/**
+ * Same contract as {@link clearedFieldsFromProfileUpdate} for managed-account
+ * `PATCH /accounts/:id` writes (`null` clears avatar/bio/category).
+ */
+export function clearedFieldsFromAccountUpdate(
+	input: UpdateAccountInput,
+): ClearableUserField[] {
+	const cleared: ClearableUserField[] = [];
+	if ("avatar" in input && !isMeaningful(input.avatar)) {
+		cleared.push("avatar");
+	}
+	if ("bio" in input && !isMeaningful(input.bio)) {
+		cleared.push("bio");
+	}
+	if (
+		"accountCategories" in input &&
+		Array.isArray(input.accountCategories) &&
+		input.accountCategories.length === 0
+	) {
+		cleared.push("accountCategories");
+	}
+	if (
+		input.name !== undefined &&
+		"displayName" in input.name &&
+		!isMeaningful(input.name.displayName)
+	) {
+		cleared.push("name.displayName");
+	}
+	return cleared;
+}
+
+/** Options for {@link upsertCachedUser}. */
+export interface UpsertCachedUserOptions {
+	/**
+	 * Fields the write that produced this user DELIBERATELY emptied. For each,
+	 * an incoming empty value stops meaning "this source does not carry it" and
+	 * starts meaning "it is empty" — so the stale value is dropped rather than
+	 * preserved. Everything not named here keeps the anti-degradation guard.
+	 */
+	cleared?: readonly ClearableUserField[];
+}
+
 /** A cache entry always carries a resolved string `id`. */
 type CachedUser = CacheableUser & { id: string; name?: UserNameResponse };
 
@@ -142,23 +272,55 @@ function normalizeIncoming(user: CacheableUser): CachedUser | null {
 	return cached.id ? cached : null;
 }
 
-/** Merge two `name` objects field-by-field, with anti-degradation on `displayName`. */
+/**
+ * Copy a name WITHOUT its `displayName`. The key must end up ABSENT rather than
+ * present-and-`undefined`: consumers render `name.displayName` directly and fall
+ * back to the handle when it is missing, and a present-but-undefined key also
+ * changes what a later merge sees.
+ */
+function omitDisplayName(name: UserNameResponse): UserNameResponse {
+	const result: UserNameResponse = {};
+	for (const [key, value] of Object.entries(name)) {
+		if (key !== "displayName") result[key] = value;
+	}
+	return result;
+}
+
+/**
+ * Merge two `name` objects field-by-field, with anti-degradation on
+ * `displayName`.
+ *
+ * `clearDisplayName` is the declared-clear escape hatch: the incoming value
+ * still wins whenever it is meaningful (an account that clears its explicit
+ * display name gets the server-COMPOSED one back, which must not be discarded),
+ * and only a genuinely empty incoming value drops the stored one.
+ *
+ * Both incoming shapes reach the clear, and they are separate branches: the
+ * measured oxy-api response carries `name` as a PRESENT-but-empty object, while
+ * a caller passing a bare user object may carry no `name` key at all.
+ */
 function mergeName(
 	existing: UserNameResponse | undefined,
 	incoming: UserNameResponse | undefined,
+	clearDisplayName: boolean,
 ): UserNameResponse | undefined {
-	if (incoming === undefined) return existing;
+	if (incoming === undefined) {
+		if (!clearDisplayName || existing === undefined) return existing;
+		return omitDisplayName(existing);
+	}
 	if (existing === undefined) return incoming;
 	const merged: UserNameResponse = { ...existing };
 	for (const [key, value] of Object.entries(incoming)) {
 		if (key === "displayName") continue;
 		if (isMeaningful(value)) merged[key] = value;
 	}
-	// Never let an empty / `'Unknown user'` displayName overwrite a real one.
+	// Never let an empty / `'Unknown user'` displayName overwrite a real one —
+	// unless the caller declared that the user cleared it.
 	if (isMeaningfulDisplayName(incoming.displayName)) {
 		merged.displayName = incoming.displayName;
+		return merged;
 	}
-	return merged;
+	return clearDisplayName ? omitDisplayName(merged) : merged;
 }
 
 /** Merge `_count` field-by-field so a partial count never replaces a fuller one. */
@@ -203,13 +365,22 @@ function mergeRelationship(
  * When `includeRelationship` is false (the viewer-independent by-id key), the
  * viewer-relative `relationship` field is never read, written, or preserved —
  * only the by-username key carries it (`useUserByUsername`).
+ *
+ * `cleared` names the fields the write deliberately emptied. It is applied
+ * AFTER the merge, because the merge loop can only ever COPY a meaningful value
+ * — an emptied field is absent from `incoming` (see the module docs: oxy-api
+ * omits it entirely) and would otherwise survive from `existing` untouched.
  */
 function mergeUsers(
 	existing: CachedUser,
 	incoming: CachedUser,
-	options?: { includeRelationship?: boolean },
+	options?: {
+		includeRelationship?: boolean;
+		cleared?: readonly ClearableUserField[];
+	},
 ): CachedUser {
 	const includeRelationship = options?.includeRelationship ?? true;
+	const cleared = options?.cleared;
 	const merged: CachedUser = { ...existing };
 	for (const [key, value] of Object.entries(incoming)) {
 		if (key === "name" || key === "_count" || key === "relationship") continue;
@@ -219,7 +390,11 @@ function mergeUsers(
 		}
 		if (isMeaningful(value)) merged[key] = value;
 	}
-	const name = mergeName(existing.name, incoming.name);
+	const name = mergeName(
+		existing.name,
+		incoming.name,
+		cleared?.includes("name.displayName") ?? false,
+	);
 	if (name !== undefined) merged.name = name;
 	const count = mergeCount(existing._count, incoming._count);
 	if (count !== undefined) merged._count = count;
@@ -232,6 +407,12 @@ function mergeUsers(
 	} else {
 		merged.relationship = undefined;
 	}
+	if (cleared) {
+		for (const field of cleared) {
+			if (field === "name.displayName") continue; // handled by `mergeName`.
+			if (!isMeaningful(incoming[field])) delete merged[field];
+		}
+	}
 	return merged;
 }
 
@@ -240,9 +421,15 @@ function upsertOneKey(
 	queryClient: QueryClient,
 	key: readonly unknown[],
 	incoming: CachedUser,
-	options: { includeRelationship: boolean },
+	options: {
+		includeRelationship: boolean;
+		cleared?: readonly ClearableUserField[];
+	},
 ): void {
-	const mergeOpts = { includeRelationship: options.includeRelationship };
+	const mergeOpts = {
+		includeRelationship: options.includeRelationship,
+		cleared: options.cleared,
+	};
 	const existing = queryClient.getQueryData<CacheableUser>(key);
 	if (existing === undefined) {
 		// Cold slot: seed the full incoming object, STALE, so react-query refetches
@@ -284,20 +471,27 @@ function resolveViewerId(viewerId?: string): string {
  * @param user        A `User`-shaped object (may be sparse).
  * @param viewerId    The active viewer id for the by-username key. Defaults to
  *                    the current auth-store user id.
+ * @param options     `cleared` names the fields the write deliberately emptied
+ *                    — the ONLY way "remove my picture" can propagate, since a
+ *                    cleared field and an uncarried one are byte-identical on
+ *                    the wire (see the module docs).
  */
 export function upsertCachedUser(
 	queryClient: QueryClient,
 	user: CacheableUser,
 	viewerId?: string,
+	options?: UpsertCachedUserOptions,
 ): void {
 	const incoming = normalizeIncoming(user);
 	if (!incoming) return;
+	const cleared = options?.cleared;
 
 	// By-id identity entry (read by `useUserById`). Not viewer-scoped — never store
 	// the viewer-relative `relationship` here or one viewer's follow state leaks
 	// into every other viewer's by-id cache entry.
 	upsertOneKey(queryClient, queryKeys.users.detail(incoming.id), incoming, {
 		includeRelationship: false,
+		cleared,
 	});
 
 	const username = incoming.username;
@@ -307,7 +501,10 @@ export function upsertCachedUser(
 		// the key through the SAME helper the hook uses so username normalization
 		// (`trim().toLowerCase()`) matches byte-for-byte.
 		const key = queryKeys.users.byUsername(username, resolveViewerId(viewerId));
-		upsertOneKey(queryClient, key, incoming, { includeRelationship: true });
+		upsertOneKey(queryClient, key, incoming, {
+			includeRelationship: true,
+			cleared,
+		});
 	}
 }
 
@@ -315,6 +512,10 @@ export function upsertCachedUser(
  * Batch merge-upsert many users at once (for a feed / list / search response).
  * Resolves the viewer id once and upserts each user cumulatively — a user that
  * appears twice merges both slices into the single cache entry.
+ *
+ * Takes NO `cleared`, deliberately: a batch is a multi-user projection, so it is
+ * exactly the sparse source the anti-degradation guard exists for, and one
+ * declaration could not be true of every user in the array anyway.
  */
 export function upsertCachedUsers(
 	queryClient: QueryClient,

package/src/ui/screens/AccountSettingsScreen.tsx

@@ -18,6 +18,10 @@ import { SettingsIcon } from '../components/SettingsIcon';
 import { useOxy } from '../context/OxyContext';
 import { useI18n } from '../hooks/useI18n';
 import { useSurfaceHeader } from '../hooks/useSurfaceHeader';
+import {
+  clearedFieldsFromAccountUpdate,
+  upsertCachedUser,
+} from '../hooks/queries/userCache';
 
 const DISPLAY_NAME_MAX = MAX_DISPLAY_NAME_LENGTH;
 const BIO_MAX = 160;
@@ -78,7 +82,11 @@ const AccountSettingsScreen: React.FC<BaseScreenProps> = ({ onClose, goBack, nav
   const updateMutation = useMutation({
     mutationKey: ['accounts', 'update', id],
     mutationFn: (input: UpdateAccountInput) => oxyServices.updateAccount(id, input),
-    onSuccess: () => {
+    onSuccess: (updatedNode, input) => {
+      const cleared = clearedFieldsFromAccountUpdate(input);
+      upsertCachedUser(queryClient, updatedNode.account, user?.id, {
+        cleared: cleared.length > 0 ? cleared : undefined,
+      });
       queryClient.invalidateQueries({ queryKey: ['accounts', 'detail', id] });
       queryClient.invalidateQueries({ queryKey: ['accounts'] });
       toast.success(t('accounts.settings.toasts.saved') || 'Account updated');

package/src/ui/screens/CreateAccountScreen.tsx

@@ -2,8 +2,8 @@ import type React from 'react';
 import { useState, useCallback, useRef, useEffect } from 'react';
 import { View, ActivityIndicator } from 'react-native';
 import Ionicons from '@expo/vector-icons/Ionicons';
-import type { AccountKind, CreateAccountInput, OrganizationCategory } from '@oxyhq/core';
-import { DISPLAY_NAME_INVALID_MESSAGE, isValidDisplayName, MAX_DISPLAY_NAME_LENGTH, ORGANIZATION_CATEGORIES } from '@oxyhq/core';
+import type { AccountCategoryId, AccountKind, CreateAccountInput } from '@oxyhq/core';
+import { DISPLAY_NAME_INVALID_MESSAGE, isValidDisplayName, MAX_ACCOUNT_CATEGORIES, MAX_DISPLAY_NAME_LENGTH, SELECTABLE_ACCOUNT_CATEGORY_IDS } from '@oxyhq/core';
 import type { BaseScreenProps } from '../types/navigation';
 import { useI18n } from '../hooks/useI18n';
 import { useSurfaceHeader } from '../hooks/useSurfaceHeader';
@@ -21,12 +21,18 @@ type UsernameStatus = 'idle' | 'checking' | 'available' | 'taken' | 'invalid';
  * Kind of account this screen can create.
  *
  * A strict subset of what `POST /accounts` accepts, not `Exclude<AccountKind,
- * 'personal'>`: this screen SWITCHES INTO the account it just created, so it can
- * only offer kinds an operator may act as. `personal` is a signup-minted root,
- * and a `channel` is a content identity nobody occupies — creating one is
- * Mention's job, through the API. Spelling the subset out here is what keeps a
- * newly-added kind from silently inheriting the `project` label in
- * {@link kindLabel}'s fallback.
+ * 'personal'>`: this screen CREATES AND ENTERS in one gesture, so it can only
+ * offer kinds an operator may act as — `isActAsEligibleKind` is the same
+ * predicate the server enforces on `POST /accounts/:id/switch`.
+ *
+ * So `channel` is absent here even though `POST /accounts` accepts it from any
+ * signed-in caller: a channel is a content identity nobody occupies, and
+ * offering it would create the account and then fail the switch. The reason is
+ * this screen's own shape, NOT a rule about who may create a channel — that rule
+ * changed once already, and a comment tied to it would now be false.
+ *
+ * Spelling the subset out here is what keeps a newly-added kind from silently
+ * inheriting the `project` label in {@link kindLabel}'s fallback.
  */
 type CreatableAccountKind = Extract<AccountKind, 'organization' | 'project' | 'bot'>;
 
@@ -77,23 +83,25 @@ const kindDescription = (
   }
 };
 
-const organizationCategoryLabel = (
+/**
+ * The visible label for a category id.
+ *
+ * A lookup, deliberately not a `switch` with a `default`: a `default` would let
+ * an id with no translation render as some OTHER category's label, silently and
+ * only in the languages that are missing it. Falling back to the raw id is ugly
+ * and correct — it is visibly wrong, and it names the missing key.
+ */
+const accountCategoryLabel = (
   t: (key: string, vars?: Record<string, string | number>) => string,
-  category: OrganizationCategory,
-): string => {
-  switch (category) {
-    case 'agency':
-      return t('accounts.organizationCategory.agency');
-    case 'cooperative':
-      return t('accounts.organizationCategory.cooperative');
-    case 'landlord':
-      return t('accounts.organizationCategory.landlord');
-    default:
-      return t('accounts.organizationCategory.other');
-  }
-};
+  category: AccountCategoryId,
+): string => t(`accounts.accountCategory.${category}`) || category;
 
-const ORGANIZATION_CATEGORY_OPTIONS: OrganizationCategory[] = [...ORGANIZATION_CATEGORIES];
+/**
+ * Only the SELECTABLE ids are offered. The full `ACCOUNT_CATEGORY_IDS` still
+ * contains withdrawn ones so that accounts already carrying them keep working —
+ * offering them here would be how an account newly acquires one.
+ */
+const ACCOUNT_CATEGORY_OPTIONS: readonly AccountCategoryId[] = SELECTABLE_ACCOUNT_CATEGORY_IDS;
 
 /**
  * Create a new account in the unified account graph (an organization, project,
@@ -119,7 +127,12 @@ const CreateAccountScreen: React.FC<BaseScreenProps> = ({
   const parentId = typeof parentAccountId === 'string' ? parentAccountId : undefined;
 
   const [kind, setKind] = useState<CreatableAccountKind>('project');
-  const [organizationCategory, setOrganizationCategory] = useState<OrganizationCategory>('agency');
+  /**
+   * ORDER IS THE DATA: index 0 is the primary category. Selecting appends,
+   * de-selecting removes, and neither sorts — so the list the user assembles is
+   * the list that is sent, and the first one they picked stays the primary.
+   */
+  const [accountCategories, setAccountCategories] = useState<AccountCategoryId[]>([]);
   const [username, setUsername] = useState('');
   const [displayName, setDisplayName] = useState('');
   const [displayNameError, setDisplayNameError] = useState('');
@@ -209,6 +222,23 @@ const CreateAccountScreen: React.FC<BaseScreenProps> = ({
     );
   }, [t]);
 
+  /**
+   * Append on select, splice out on de-select. Never sorts — appending is what
+   * makes the FIRST category the user chose the primary one, and a sort would
+   * silently reassign that. De-selecting the primary promotes whatever the user
+   * picked next, which is the only interpretation that does not invent a choice
+   * on their behalf.
+   */
+  const toggleAccountCategory = useCallback((category: AccountCategoryId) => {
+    setAccountCategories((current) => {
+      if (current.includes(category)) {
+        return current.filter((entry) => entry !== category);
+      }
+      if (current.length >= MAX_ACCOUNT_CATEGORIES) return current;
+      return [...current, category];
+    });
+  }, []);
+
   const canCreate = usernameStatus === 'available'
     && displayName.trim().length > 0
     && !displayNameError
@@ -219,17 +249,14 @@ const CreateAccountScreen: React.FC<BaseScreenProps> = ({
 
     setIsCreating(true);
     try {
-      // Split display name into first/last
-      const nameParts = displayName.trim().split(/\s+/);
-      const firstName = nameParts[0] || '';
-      const lastName = nameParts.length > 1 ? nameParts.slice(1).join(' ') : undefined;
-
       const input: CreateAccountInput = {
         kind,
         username,
-        name: { first: firstName, last: lastName },
+        name: { displayName: displayName.trim() },
         bio: bio.trim() || undefined,
-        ...(kind === 'organization' ? { organizationCategory } : null),
+        // Sent in the user's own order, or omitted entirely when empty — the
+        // API distinguishes "no categories" from "not stated" only by absence.
+        ...(accountCategories.length > 0 ? { accountCategories } : null),
         ...(parentId ? { parentAccountId: parentId } : null),
       };
       const account = await createAccount(input);
@@ -239,6 +266,13 @@ const CreateAccountScreen: React.FC<BaseScreenProps> = ({
       // Switch INTO the new account (real-session switch — the whole app becomes
       // it). Best-effort: creation already succeeded, so a switch hiccup should
       // not surface as a create failure.
+      //
+      // That trade holds for a TRANSIENT failure and only for one. A kind the
+      // server refuses outright fails DETERMINISTICALLY — `/switch` answers 403
+      // every time, never sometimes — and this swallow would turn it into a
+      // created account, no switch, and no error anywhere. Which is why
+      // `CreatableAccountKind` above is a subset of what `POST /accounts`
+      // accepts rather than of what it rejects.
       if (account.accountId) {
         await switchToAccount(account.accountId).catch(() => undefined);
       }
@@ -252,7 +286,7 @@ const CreateAccountScreen: React.FC<BaseScreenProps> = ({
     } finally {
       setIsCreating(false);
     }
-  }, [canCreate, kind, organizationCategory, username, displayName, bio, parentId, createAccount, switchToAccount, onClose, t]);
+  }, [canCreate, kind, accountCategories, username, displayName, bio, parentId, createAccount, switchToAccount, onClose, t]);
 
   // Status icon + color shown alongside the username field message
   const usernameIsInvalid = usernameStatus === 'taken' || usernameStatus === 'invalid';
@@ -294,26 +328,35 @@ const CreateAccountScreen: React.FC<BaseScreenProps> = ({
         })}
       </SettingsListGroup>
 
-      {/* Organization category — grouped selection rows, shown only for organizations */}
-      {kind === 'organization' ? (
-        <SettingsListGroup title={t('accounts.create.organizationCategory.label')}>
-          {ORGANIZATION_CATEGORY_OPTIONS.map((option) => {
-            const selected = option === organizationCategory;
+      {/* Categories — multi-select, shown for every kind this screen can create
+          (they are all non-personal). The badge on a selected row is its
+          POSITION, so the primary is legible as "1" rather than being a rule the
+          user has to be told. */}
+      <View className="gap-space-4">
+        <SettingsListGroup title={t('accounts.create.accountCategory.label')}>
+          {ACCOUNT_CATEGORY_OPTIONS.map((option) => {
+            const position = accountCategories.indexOf(option);
+            const selected = position >= 0;
+            const label = accountCategoryLabel(t, option);
             return (
               <SettingsListItem
                 key={option}
-                title={organizationCategoryLabel(t, option)}
-                onPress={() => setOrganizationCategory(option)}
+                title={label}
+                disabled={!selected && accountCategories.length >= MAX_ACCOUNT_CATEGORIES}
+                onPress={() => toggleAccountCategory(option)}
                 showChevron={false}
                 rightElement={selected ? (
-                  <Ionicons name="checkmark-circle" size={20} color={bloomTheme.colors.primary} />
+                  <Text className="text-caption-1 font-semibold text-primary">{position + 1}</Text>
                 ) : undefined}
-                accessibilityLabel={organizationCategoryLabel(t, option)}
+                accessibilityLabel={label}
               />
             );
           })}
         </SettingsListGroup>
-      ) : null}
+        <Text className="text-caption font-caption text-text-tertiary px-space-4">
+          {t('accounts.create.accountCategory.hint', { max: MAX_ACCOUNT_CATEGORIES })}
+        </Text>
+      </View>
 
       {/* Details — a grouped section card hosting the form fields */}
       <SettingsListGroup title={t('accounts.create.detailsSection') || 'Details'}>

package/src/ui/utils/avatarUtils.ts

@@ -5,6 +5,10 @@ import { useAccountStore } from '../stores/accountStore';
 import { useAuthStore } from '../stores/authStore';
 import type { QueryClient } from '@tanstack/react-query';
 import { queryKeys, invalidateUserQueries, invalidateAccountQueries } from '../hooks/queries/queryKeys';
+import {
+  clearedFieldsFromProfileUpdate,
+  upsertCachedUser,
+} from '../hooks/queries/userCache';
 
 /**
  * Refreshes avatar in accountStore with cache-busted URL to force image reload.
@@ -60,6 +64,11 @@ export async function updateProfileWithAvatar(
   // Update authStore so frontend components see the changes immediately
   useAuthStore.getState().setUser(data);
 
+  const cleared = clearedFieldsFromProfileUpdate(updates);
+  upsertCachedUser(queryClient, data, data.id, {
+    cleared: cleared.length > 0 ? cleared : undefined,
+  });
+
   // If avatar was updated, refresh accountStore with a cache-busted URL. An
   // EMPTY avatar is a removal: clear both fields so the switcher falls back to
   // initials instead of pointing at a download URL for the empty file id.