diff --git a/docs/swarm/README.md b/docs/swarm/README.md
index d39ba838..9e0e4f2f 100644
--- a/docs/swarm/README.md
+++ b/docs/swarm/README.md
@@ -345,6 +345,11 @@ result over the file only when both pass:
 | 504    | the harness didn't answer within ten seconds, so whether the edit applied is unknown                                                    |
 | 500    | the harness couldn't read or write the file or run git, or the queue failed the request                                                 |
 
+The harness refuses a diff that sets any file mode other than `100644`, so an
+edit can't turn `AGENTS.md` into a symlink. `PUT` is operator-only, behind
+`Remote-User` like cancel: whoever can call it can rewrite the agent's
+instructions, so don't widen who holds it without revisiting this.
+
 An edit needs the agent running, and a read of a stopped agent shows the text
 it last published. A harness older than this route doesn't know the command and
 drops it unanswered, which reads as a 504. `swarmctl agent agents-md get` and