NOTIFICATIONS

Swamp Club notifies operatives when they are @mentioned in a Lab issue body or comment. Notifications surface in the /inbox page and as an unread count in the nav.

What triggers a notification

• Posting a Lab issue whose body contains one or more @username mentions.
• Editing a Lab issue body to add @username mentions that were not present in the previous body. Pre-existing mentions do NOT re-fire on every edit.
• Posting a new comment on a Lab issue containing @username mentions.
• Editing a comment to add mentions that were not present previously.

Mention parsing rules

A mention matches when:

• The handle is 3–32 characters of lowercase alphanumeric, _, or - (the BetterAuth username rules).
• The character before @ is not a letter, digit, @, /, ., or : — so email addresses (foo@bar.com), URL paths (http://x/@u), and version strings are NOT parsed as mentions.
• The mention is NOT inside a fenced code block (``` or ~~~) or an inline code span (`…`). Code regions render literally.

Up to 20 unique mentions are honoured per write; everything beyond that is silently ignored to bound fan-out.

Delivery rules

• Self-mentions never fire. Mentioning yourself in your own issue or comment does not produce a row.
• Unknown handles never fire. Well-formed mentions that don't resolve to an existing operative are dropped.
• Security-type issues respect access. Mentioning someone in a security issue produces a notification only if the recipient is the issue author or an admin. If an issue is reclassified to security later, inbox rows that reference it drop from the viewer's inbox the next time they load /inbox.
• Dedup: one mention per (recipient, sourceType, sourceId) — if an edit removes-then-re-adds the same user on the same issue/comment, no second row is created.
• Rate limit: at most 5 notifications from a single actor to a single recipient within a rolling 10 minute window.

Rename behaviour

Notifications store stable user IDs and issue numbers, not usernames or titles. When an operative renames their username or an issue title is edited, the inbox automatically reflects the current values on the next load — stored rows are not rewritten.

Excerpt snapshots

The short excerpt shown for each notification is captured at the moment the mention is created. Later edits to the source body do NOT update existing excerpts. If the excerpt looks stale, follow the link to the issue or comment to see the current content.

Out of scope (v1)

• Email delivery — tracked in #131.
• Blocking operatives so their mentions are suppressed — tracked in #132.
• Collective mentions (e.g. @my-collective), mentions on non-issue surfaces, mobile push notifications, and digest emails.
• Backfill of existing issues and comments — only mentions posted after this feature shipped will produce notifications.