From cff36f4400bb57ad30053cf81cdd6fff23e5bc20 Mon Sep 17 00:00:00 2001
From: Tinnus Napbus <admin@tinnus-napbus.xyz>
Date: Wed, 12 Apr 2023 17:57:35 +1200
Subject: [PATCH] ames: document %snub task and /ax/snubbed scry

---
 content/reference/arvo/ames/scry.md  | 18 ++++++++++++++++++
 content/reference/arvo/ames/tasks.md | 27 +++++++++++++++++++++++++++
 2 files changed, 45 insertions(+)

diff --git a/content/reference/arvo/ames/scry.md b/content/reference/arvo/ames/scry.md
index 518134f..b402fca 100644
--- a/content/reference/arvo/ames/scry.md
+++ b/content/reference/arvo/ames/scry.md
@@ -123,3 +123,21 @@ A scry with a `%x` `care` and a `path` of `/snd-bones/[ship]/[bone]`, where `[sh
   ]
 ]
 ```
+
+## /snubbed
+
+A scry with a `%x` `care` and a `path` of `/snubbed` will return Ames' current
+ship whitelist/blacklist. The type is a `[form=?(%allow %deny) ships=(list
+ship)]`, where `form` says whether it's a whitelist or blacklist and `ships`
+are the ships on that list.
+
+#### Example
+
+
+```
+> |ames-snub %deny ~wet ~sampel
+>=
+
+> .^([form=?(%allow %deny) ships=(list ship)] %ax /=//=/snubbed)
+[form=%deny ships=[i=~sampel t=[i=~wet t=~]]]
+```
diff --git a/content/reference/arvo/ames/tasks.md b/content/reference/arvo/ames/tasks.md
index 646fb8f..8ff15d9 100644
--- a/content/reference/arvo/ames/tasks.md
+++ b/content/reference/arvo/ames/tasks.md
@@ -148,6 +148,33 @@ The `ships` field specifies the ships for which debug output is desired.
 
 This `task` returns no `gift`s.
 
+### `%snub`
+
+```hoon
+[%snub form=?(%allow %deny) ships=(list ship)]
+```
+
+This `task` blacklists/whitelists ships in Ames.
+
+The `form` field specifies whether the given ships should be blacklisted or whitelisted. The `ships` field are the ships to blacklist/whitelist.
+
+The Ames `snub` settings can only have one form at a time: an `%allow` list or
+`%deny` list. If an `%allow` form is set, packets from **all ships not on the
+list will be blocked**. If a `%deny` form is set, packets from **any ship on
+the list will be blocked, and all others allowed**.
+
+{% callout %}
+
+Note: a `%snub` `task` overrides the existing snub list and form entirely,
+it does not merely add/remove ships from the existing list.
+
+If you just want to add/remove a ship from an existing blacklist/whitelist,
+you'll need to first [scry out the existing snub
+settings](/reference/arvo/ames/scry#snubbed), make your changes, and send the
+whole modified list and form in a new `%snub` `task`. 
+
+{% /callout %}
+
 ### `%spew`
 
 ```hoon