3 files changed, 21 insertions, 1 deletions

diff --git a/08.md b/08.md
index 113cb53..d82787d 100644
--- a/08.md
+++ b/08.md
@@ -1,3 +1,5 @@
+> __Warning__  `unrecommended`: discouraged in favor of NIP-27
+
 NIP-08
 ======
 
diff --git a/27.md b/27.md
new file mode 100644
index 0000000..b2d1e5a
--- /dev/null
+++ b/27.md
@@ -0,0 +1,17 @@
+NIP-27
+======
+
+Handling Mentions
+-----------------
+
+`draft` `optional` `author:fiatjaf` `author:scsibug` `author:arthurfranca`
+
+This document standardizes the treatment given by clients of inline mentions of other events and pubkeys inside the content of `text_note`s.
+
+Clients that want to allow inline mentions they MUST show an autocomplete component or something analogous to that whenever the user starts typing a special key (for example, "@") or presses some button to include a mention etc -- or these clients can come up with other ways to unambiguously differentiate between mentions and normal text.
+
+Once a mention is identified, for example, the pubkey `27866e9d854c78ae625b867eefdfa9580434bc3e675be08d2acb526610d96fbe`, the client MUST replace its textual reference (inside `.content`) with the notation `nostr:nprofile1qqsw3dy8cpu...6x2argwghx6egsqstvg` as per NIP-21. If client doesn't support NIP-21, it can instead use a regular http link to a nostr client such as `https://snort.social/p/nprofile1qqsw3dy8cpu...6x2argwghx6egsqstvg`. The client MAY add that pubkey to the `.tags` with the tag `p` if it wishes to notify mentioned user.
+
+The same process applies for mentioning event IDs, except that the client SHOULD NOT add the event id to the `.tags` with the tag `e` so to not negatively impact thread loading.
+
+A client that receives a `text_note` event with such `nostr:...` mentions in its `.content` CAN do any desired context augmentation (for example, linking to the pubkey or showing a preview of the mentioned event contents) it wants in the process.
diff --git a/README.md b/README.md
index 37b2fe4..d93f5c2 100644
--- a/README.md
+++ b/README.md
@@ -9,7 +9,7 @@ NIPs stand for **Nostr Implementation Possibilities**. They exist to document wh
 - [NIP-05: Mapping Nostr keys to DNS-based internet identifiers](05.md)
 - [NIP-06: Basic key derivation from mnemonic seed phrase](06.md)
 - [NIP-07: `window.nostr` capability for web browsers](07.md)
-- [NIP-08: Handling Mentions](08.md)
+- [NIP-08: Handling Mentions](08.md) – `unrecommended`: discouraged in favor of [NIP-27](27.md)
 - [NIP-09: Event Deletion](09.md)
 - [NIP-10: Conventions for clients' use of `e` and `p` tags in text events](10.md)
 - [NIP-11: Relay Information Document](11.md)
@@ -25,6 +25,7 @@ NIPs stand for **Nostr Implementation Possibilities**. They exist to document wh
 - [NIP-23: Long-form Content](23.md)
 - [NIP-25: Reactions](25.md)
 - [NIP-26: Delegated Event Signing](26.md)
+- [NIP-27: Handling Mentions](27.md)
 - [NIP-28: Public Chat](28.md)
 - [NIP-33: Parameterized Replaceable Events](33.md)
 - [NIP-36: Sensitive Content](36.md)