From 8104dc7b11ebde4fd691078ff5be4f60b0f7a5af Mon Sep 17 00:00:00 2001
From: Logan Johnson <loganj@squareup.com>
Date: Fri, 9 Oct 2026 12:17:37 -0400
Subject: [PATCH] docs(nips): add system channels to NIP-CL

Define the system channel type. List it in ARCHITECTURE.md.

Co-authored-by: Larry <627498bd4bd1f281a16431e3c6cce3b5c25b6692798c78672298aefbf2f8f8b5@buzz.block.builderlab.xyz>
Signed-off-by: Logan Johnson <loganj@squareup.com>
---
 ARCHITECTURE.md     |  2 +-
 docs/nips/NIP-CL.md | 19 ++++++++++++++++++-
 2 files changed, 19 insertions(+), 2 deletions(-)

diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index 82d7cac7bc..3c78215e81 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -469,7 +469,7 @@ All database access. Uses `sqlx::query()` (runtime, not compile-time macros) —
 | `user.rs` | User profile storage |
 | `error.rs` | Database error types |
 
-**Channel types:** `Stream`, `Forum`, `Dm`, `Workflow`  
+**Channel types:** `Stream`, `Forum`, `Dm`, `Workflow`, `System`  
 **Member roles:** `Owner`, `Admin`, `Member`, `Guest`, `Bot`  
 **Workflow statuses:** `Active`, `Disabled`, `Archived`  
 **Run statuses:** `Pending`, `Running`, `WaitingApproval`, `Completed`, `Failed`, `Cancelled`
diff --git a/docs/nips/NIP-CL.md b/docs/nips/NIP-CL.md
index 222bfb9e0d..9e00b539ca 100644
--- a/docs/nips/NIP-CL.md
+++ b/docs/nips/NIP-CL.md
@@ -24,12 +24,16 @@ plain NIP-29, a client cannot:
 A client also cannot mark its own channels so that it can find them again.
 Channel labels (below) do this.
 
+Also, every channel that a person belongs to shows in their client as a chat.
+So a group that exists only to control who can read some data appears in
+sidebars, search results and unread counts. System channels (below) fix this.
+
 ## Channel identity tags
 
 On every channel-state event that the relay signs, the relay MUST put these
 tags in this order, before any other `t` or `P` tag:
 
-1. `["t", <channel type>]`, for example `stream`, `forum`, `dm`, `workflow`.
+1. `["t", <channel type>]`, for example `stream`, `forum`, `dm`, `workflow`, `system`.
 2. `["t", <label>]` for each channel label, in stored order (see
    [Channel labels](#channel-labels)).
 3. `["P", <creator public key, hex>]`.
@@ -135,6 +139,19 @@ channel without a `created_at` tag ranks after every channel that has one.
 Every reader that follows this rule picks the same channel, even after either
 channel is edited.
 
+## System channels
+
+A system channel exists only to control who can read some data, for example
+config that only an agent and its owner can read. It has the channel type
+`system`. In every other way it is an ordinary channel: it has members, roles,
+messages and labels.
+
+**Create.** A kind:9007 with `["channel_type", "system"]` creates a system
+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.
+
 ## Trust
 
 A client that relies on these tags MUST check that the relay's key signed the