From c621d9ad506e88d00a5da428f0c1e6e966cbe52d Mon Sep 17 00:00:00 2001
From: "google-labs-jules[bot]"
 <161369871+google-labs-jules[bot]@users.noreply.github.com>
Date: Tue, 6 Jan 2026 14:37:33 +0000
Subject: [PATCH] doc: add NIP-33 addressing lessons to AGENTS.md

Adds a new section to `AGENTS.md` documenting the importance of using
the `d` tag (network identifier) over logical IDs (like `videoRootId`)
when creating pointers for parameterized replaceable events (NIP-33).
This captures the lessons learned from recent watch history bugs where
mismatched identifiers caused hydration failures.
---
 AGENTS.md | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index 435758d3..823343e6 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -170,6 +170,16 @@ When moving a feature to a controller, follow these steps:
 
 ---
 
+## 9. Nostr Addressing & NIP-33 (Lessons Learned)
+
+* **Addressing Rule:** NIP-33 events (e.g., videos, long-form content) are uniquely identified by the combination of `kind`, `pubkey`, and the `d` tag.
+* **The `d` tag is King:** When creating pointers for these events, **always use the `d` tag** as the identifier.
+* **Avoid Logical IDs:** Do not confuse logical identifiers (like `videoRootId`) with the network identifier (`d` tag). While they might often be the same, they are not guaranteed to be.
+* **Hydration Pitfall:** If you create a pointer using a logical ID that differs from the `d` tag, relays will fail to find the event during hydration because the index relies on the `d` tag.
+* **Fix Pattern:** When resolving a pointer from an event, prioritize checking `tags.find(t => t[0] === 'd')?.[1]` over any other ID field.
+
+---
+
 ## Next
 
 Please read these documents next.