flesh out the entire thing.

29.md

@@ -8,21 +8,35 @@ Relay-based Groups
 
 This NIP defines a standard for groups that are only writable by a closed set of users. They can be public for reading by external users or not.
 
+Groups are identified by a random string of any length that serves as an _id_.
+
+There is no way to create a group, what happens is just that relays (most likely when asked by users) create rules around some specific ids so these ids can serve as an actual group, henceforth messages sent to that group will be subject to these rules.
+
+Normally a group will originally belong to one specific relay, but the community may choose to move the group to other relays or even fork the group so it exists in different forms -- still using the same _id_ -- across different relays.
+
+## Relay-generated events
+
+Relays are supposed to generate the events that describe group metadata and group admins. These are parameterized replaceable events signed by the relay keypair directly, with the group _id_ as the `d` tag.
+
+## The `h` tag
+
+Events sent by users to groups (chat messages, text notes, moderation events etc) must have an `h` tag with the value set to the group _id_.
+
 ## Timeline references
 
-In order to not be used out of context, events sent to these groups may contain a reference to previous events seen from the same relay.
+In order to not be used out of context, events sent to these groups may contain references to previous events seen from the same relay in the `previous` tag. The choice of which previous events to pick belongs to the clients.
+
+This is a hack to prevent messages from being broadcasted to external relays that have forks of one group out of context. Relays are expected to reject any events that contain timeline references to events not found in their own database. Clients must also check these to keep relays honest about them.
 
 ## Trimmed signatures
 
-For private groups that are not intended to be read by external users, relays must strip the signatures before sending the events to clients.
+Relays must strip the signature of messages in groups that are `private` so they do not leak.
 
 ### Event definitions
 
 - *text note* (`kind:11`)
 
-This is the basic unit of a text note sent to a group.
+This is the basic unit of a "microblog" text note sent to a group.
-
-It must commit in the `h` tag to the subgroup path and may also commit to up to the last 3 events of the same kind seen in the group.
 
 ```js
   "kind": 11,
@@ -36,7 +50,7 @@ It must commit in the `h` tag to the subgroup path and may also commit to up to
 
 - *chat message* (`kind:9`)
 
-Similar to kind 11, this is the basic unit of a chat message sent to a group.
+Similar to `kind:11`, this is the basic unit of a chat message sent to a group.
 
 ```js
   "kind": 9,
@@ -67,6 +81,8 @@ If this event does not exist, the group should be identified in the client UI by
 }
 ```
 
+The [NIP-19](19.md) `naddr` pointer for this event including with a mandatory relay can be used as the canonical group identifier.
+
 - *group admins* (`kind:39001`) (optional)
 
 Each admin gets a label that is only used for display purposes, and a list of permissions it has are listed afterwards. These permissions can inform client building UI, but ultimately are evaluated by the relay in order to become effective.
@@ -86,23 +102,27 @@ The list of capabilities, as defined by this NIP, for now, is the following:
   "content": "list of admins for the pizza lovers group",
   "tags": [
     ["d", "<group-id>"],
-    ["<pubkey1-as-hex>", "admin", "add-user", "edit-metadata", "delete-event", "ban-user"],
+    ["<pubkey1-as-hex>", "ceo", "add-user", "edit-metadata", "delete-event", "ban-user"],
-    ["<pubkey2-as-hex>", "mod", "add-user", "delete-event"]
+    ["<pubkey2-as-hex>", "secretary", "add-user", "delete-event"]
   ]
   ...
 }
 ```
 
+- *deletion event* (`kind:5`) (optional)
+
+This is the same event as described in [NIP-09](09.md), the difference is that if there are admins with `delete-event` capability for the relevant group their `kind:5` events must be honored by the relays.
+
 - *moderation event* (`kind:9000`) (optional)
 
-An event sent from a client to the relay in order to accomplish a moderation action. The relay should read this event and act on it if the user sending the event has the required permissions and the date is close to the current date. The relay may discard the event after taking action or keep it as a way to expose a moderation log. This is similar to the `kind:9` event in its structure.
+An event sent from a client to the relay in order to accomplish a moderation action (except `delete-event`, as that is the job of `kind:5`). The relay should read this event and act on it if the user sending the event has the required permissions and the date is close to the current date. The relay may discard the event after taking action or keep it as a way to expose a moderation log.
 
 ```js
 {
   "kind": 9000,
   "content": "action description and/or reason",
   "tags": [
-    ["g", "<group-id>"],
+    ["h", "<group-id>"],
     ["action", "add-user", "<pubkey-to-add>"],
     ["action", "ban-user", "<pubkey-to-ban>"],
     ["action", "edit-metadata", "<field-name>", "<field-value>"],