docs(nips): NIP-CL reads leave system channels out

Define which reads leave system channels out and how a filter names one.
Note the change in the AGENTS.md channel scoping guidance.

Co-authored-by: Larry <627498bd4bd1f281a16431e3c6cce3b5c25b6692798c78672298aefbf2f8f8b5@buzz.block.builderlab.xyz>
Signed-off-by: Logan Johnson <loganj@squareup.com>
This commit is contained in:
Logan Johnson
2026-10-09 12:17:39 -04:00
parent 1128ef21fd
commit 0d06eaf8ba
2 changed files with 27 additions and 1 deletions

View File

@@ -313,7 +313,9 @@ Filters and queries must scope to `h` tags when operating within a channel.
This applies to events *inside* a channel. Addressable events that describe a
channel carry its id in their `d` tag instead: kind:39000 (metadata),
kind:39001, kind:39002 (membership). `get_channels` resolves a user's channels
from the `d` tag of their kind:39002 events, not from `h`.
from the `d` tag of their kind:39002 events, not from `h`. The relay leaves
system channels out of these reads unless the filter asks for them (see
`docs/nips/NIP-CL.md`).
**Agent-facing operations go in `buzz-cli`**: New agent-facing features belong in `buzz-cli` — add a subcommand there first, then wire the REST/WebSocket call in `client.rs`. `buzz-dev-mcp` (shell + file tools for `buzz-agent`) is separate.

View File

@@ -152,6 +152,30 @@ channel. It is private unless the kind:9007 also has `["visibility", "open"]`.
**Hidden.** While a system channel is private, its kind:39000 carries the
NIP-29 `hidden` tag.
### Reads that leave system channels out
The relay leaves system channels out of every read that does not name them.
Clients that do not know about system channels then stay correct with no
change. This applies to:
- a filter without `#h`, for example the channels or messages a reader can see;
- kind:39002 `#p:["<reader>"]`, the channels a reader belongs to;
- COUNT and NIP-50 search; and
- any relay-specific query API that does the same reads.
A filter **names** a system channel when it has the channel ID in `#h`, or in
`#d` on a filter whose kinds are all 39000–39003. Then the ordinary read rules
apply: the reader can read the channel if they are a member or if it is open.
A client that has the ID, for example from a link, can open the channel. Thus
a system channel stays an ordinary NIP-29 group.
The relay decides this for each filter. A filter that names a system channel
does not add it to another filter in the same request.
The relay MUST NOT send push notifications or kind:44100/44101 membership
notifications for system channels. A client that received one would show the
channel.
## Trust
A client that relies on these tags MUST check that the relay's key signed the