From 653bd78700940dbeefe54d779daea416f2a9ea4d Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 3 Feb 2026 13:01:01 +0000
Subject: [PATCH] fix(bot): Clarify critical distinction between -a, -p, and
 --tag P

CRITICAL DISTINCTIONS now clearly stated:
- -a, --author = WHO SIGNED the event (cryptographic author)
- -p = WHO IS MENTIONED via p-tag (tagged pubkey, NOT author)
- --tag P = WHO IS MARKED AS AUTHOR in P-tag (original content author)

Also:
- Added TAG FILTERING section explaining k, P, e, p tags
- Added REACTION QUERIES section with proper examples
- Clarified zap receipts are SIGNED by LNURL servers

https://claude.ai/code/session_01X4HWkMGrghBv2RfY89L5Lz
---
 bot/src/llm.ts | 42 ++++++++++++++++++++++++++----------------
 1 file changed, 26 insertions(+), 16 deletions(-)

diff --git a/bot/src/llm.ts b/bot/src/llm.ts
index a2b9cdb..4ca48b7 100644
--- a/bot/src/llm.ts
+++ b/bot/src/llm.ts
@@ -40,16 +40,21 @@ const SYSTEM_PROMPT = `You help users craft Nostr REQ commands for Grimoire.
 
 REQ syntax: req [options] [relay...]
 
+CRITICAL DISTINCTIONS:
+-a, --author = WHO SIGNED the event (the actual cryptographic author)
+-p = WHO IS MENTIONED via p-tag (tagged/referenced pubkey, NOT the author)
+--tag P = WHO IS MARKED AS AUTHOR in the P-tag (used by zaps/reactions for original content author)
+
 OPTIONS:
 -k, --kind <n> - event kind (comma-separated ok)
--a, --author <pubkey> - author filter (npub, hex, or NIP-05)
+-a, --author <pubkey> - filter by event signer (npub, hex, or NIP-05)
 -i, --id <id> - fetch by ID (note1, nevent1, naddr1, hex)
 -l, --limit <n> - max events
 -e <id> - events referencing this event ID (#e tag)
--p <pubkey> - events tagging this pubkey (#p tag)
+-p <pubkey> - events that MENTION this pubkey (#p tag)
 -t <hashtag> - hashtag filter (#t tag)
 -d <identifier> - d-tag filter
---tag <name> <value> - generic tag filter (e.g. --tag k 1)
+--tag <name> <value> - generic tag filter
 --since <time> - after time (unix or relative: 30m, 6h, 7d, 2w)
 --until <time> - before time
 --search <query> - full-text search (NIP-50)
@@ -61,22 +66,27 @@ $contacts - all followed pubkeys
 KINDS:
 0=profile, 1=note, 3=follows, 6=repost, 7=reaction, 1111=comment, 9735=zap, 30023=article
 
-K-TAG FILTERING:
-Many events include a k-tag indicating the kind of event they reference:
-- Reactions (7) have k-tag for what they react to
-- Zaps (9735) have k-tag for what was zapped
-- Comments (1111) have k-tag for what they comment on
-Use --tag k <kind> to filter by referenced kind.
-Example: req -k 7 --tag k 1 -p $me = reactions to notes mentioning me
+TAG FILTERING:
+Use --tag <name> <value> for any tag. Common tags:
+- k tag: kind of referenced event (reactions, zaps, comments have this)
+- P tag: author of referenced content (NOT the event signer)
+- e tag: referenced event ID
+- p tag: mentioned pubkey
 
 ZAP QUERIES:
-Zaps have two pubkey tags: p=recipient (gets sats), P=original author (of zapped content).
-- Zaps I received: req -k 9735 -p $me
-- Zaps to my content: req -k 9735 --tag P $me
+Zap receipts (9735) are SIGNED by LNURL servers, not users.
+- p tag = recipient (who receives sats, who is mentioned)
+- P tag = author of the zapped content
+Examples:
+- Zaps where I'm mentioned (received): req -k 9735 -p $me
+- Zaps to content I authored: req -k 9735 --tag P $me
 - Zaps to content by people I follow: req -k 9735 --tag P $contacts
-- Zaps to notes specifically: req -k 9735 -p $me --tag k 1
-- Zaps to articles: req -k 9735 -p $me --tag k 30023
-Note: -a is the LNURL server, not the sender. Use -p for recipient, --tag P for author.
+- Zaps to notes I received: req -k 9735 -p $me --tag k 1
+
+REACTION QUERIES:
+- Reactions mentioning me: req -k 7 -p $me
+- Reactions to content I authored: req -k 7 --tag P $me
+- Reactions to notes specifically: req -k 7 --tag k 1 -p $me
 
 COMMENTS VS REPLIES:
 - "comments" = kind 1111 (NIP-22 comments on any content)