@Mention Users

PATTERN: @Mention Users
INPUT: text_being_typed, current_user, available_users[]
OUTPUT: parsed_text_with_mentions, notifications_to_send[]

AUTOCOMPLETE_STEPS:
  1. User types "@" character in editor
  2. Show floating dropdown with user list (default: most-frequently-mentioned + recent)
  3. As user types after @, filter list by name fuzzy match
  4. Show user avatar, display name, optional secondary info (role, team)
  5. User picks from list (Enter, Tab, or click)
  6. Replace "@x" with mention chip (visual pill with avatar) referencing user_id
  7. Continue typing normally

SUBMIT_STEPS:
  1. User submits the comment/message
  2. Parse text for mention chips, extract user_ids
  3. Persist text with mentions (store as JSON or markdown with [@user-id] markers)
  4. For each unique mentioned user (excluding self):
     - Check notification preferences (email? push? both?)
     - Check permissions (can they see the resource?)
     - Send notification with: who mentioned, where, link to context
  5. Render: rich preview in app, plain @username in plain-text contexts (email)

ERROR_HANDLING:
  - Mention nonexistent user → strip from list, show "couldn't find user X" toast
  - Mention deleted user → render as plain text "@deleted"
  - Permission denied (mention a user who can't see the resource) → either skip notification OR offer to invite them
  - Mass mention abuse (@everyone in 100-person channel) → require admin permission for >10 mentions

EXTENSION_POINTS:
  - @group / @team mentions (composable_with: ["groups"])
  - Notification rate limiting per user
  - Mention in approval to add reviewers (composable_with: ["approval"])
  - Activity feed entry for each mention received (composable_with: ["activity-feed"])

• What if a user is mentioned but has 'do not disturb' on?

  low

  Notification sent inappropriately at night.

  Suggested handling: Respect user's notification preferences (DND windows, channels). Queue notification, deliver when DND ends. Show "(silenced) — will notify at 9am" to mentioner if relevant.

• What if the same user is mentioned 5 times in one message?

  low

  5 redundant notifications.

  Suggested handling: De-duplicate by user_id when sending notifications. Show "@alice mentioned you (3 times) in [doc]" instead of 3 separate notifications.

• What if a user mentions someone who can't see the resource?

  medium

  User clicks notification, gets "access denied" page. Frustrating.

  Suggested handling: Detect at compose time. Show inline "Alice doesn't have access — invite her?" prompt. If sent, include context excerpt in notification email so they understand without needing access.

• What if mentioning users in a private DM creates a spam vector?

  medium

  Spammer mentions strangers to bypass DM permissions.

  Suggested handling: Limit @-mentions to people in the same workspace/team. Or per-user "mention only by people I've interacted with" setting. Add report-spam button on mentions.

• What if the mentioned user's display name is changed later?

  low

  Old @alice still shows alice in old comments, but user is now Alex.

  Suggested handling: Store mentions as user_id, not name. Render with current name on display. Old comments auto-update. Optional: show old name in tooltip for historical context.