docs(honcho): clarify pinUserPeer pins only non-agent users

'everyone collapses to your peer' read as a promise about all traffic.
pinUserPeer pins the user-side peer and is checked before userPeerAliases
(session.py:335), so a pin overrides every alias — including agent peers.
For a multi-agent operator that silently pools distinct agents onto one
peer, the opposite of intent.

Scopes the wording to 'every non-agent gateway user', notes the pin
overrides aliases, and points agent-mesh operators at pinUserPeer:false +
userPeerAliases instead. Same correction in the wizard menu/echo text,
the plugin README, and the website Honcho page.

plugins/memory/honcho/README.md

@@ -161,7 +161,7 @@ In gateway deployments (Telegram, Discord, Slack, etc.) each user arrives with a
 
 **Setup — gateway identity tree.** `hermes honcho setup` only asks about identity mapping when it detects a connected gateway platform (it inspects the gateway config; off-gateway the step is skipped because these keys do nothing without a runtime user ID). When it runs, it asks *who talks to this gateway?* and derives the keys:
 
-- **just me** → `pinUserPeer: true`. All gateway users collapse to `peerName`. Personal use where you connect Hermes to your own Telegram/Discord/etc.
+- **just me** → `pinUserPeer: true`. Every non-agent gateway user collapses to `peerName`; the pin overrides all aliases, so pick this only when no user-side identity needs its own peer. Personal use where you connect Hermes to your own Telegram/Discord/etc. If separate agents reach the gateway and each needs a distinct peer, do **not** pin — leave `pinUserPeer: false` and map them via `userPeerAliases` (the `[e]` editor).
 - **me + other people, pooled** → `pinUserPeer: false` + `userPeerAliases` mapping your runtime IDs to `peerName`. You stay on the shared history; everyone else gets their own peer.
 - **me + other people / only other people** → `pinUserPeer: false`, optional `runtimePeerPrefix`. Each runtime user → own peer. For bots serving many humans.
 

plugins/memory/honcho/cli.py

@@ -699,7 +699,7 @@ def cmd_setup(args) -> None:
         peer_target = hermes_host.get("peerName") or current_peer or "user"
         default_choice = {"single": "1", "hybrid": "2", "multi": "3"}.get(current_shape, "3")
         print("\n  How should gateway users map to memory peers?")
-        print("    [1] just me — everyone collapses to your peer")
+        print("    [1] just me — every non-agent user collapses to your peer")
         print("    [2] me + other people — keep mine pooled, others separate")
         print("    [3] only other people — everyone gets their own peer")
         print("    [s] skip (leave untouched)   [e] edit raw keys")
@@ -739,7 +739,7 @@ def cmd_setup(args) -> None:
         if shape == "single":
             _scrub_identity_mapping(hermes_host)
             hermes_host["pinUserPeer"] = True
-            print(f"  All gateway users route to '{peer_target}'.")
+            print(f"  All non-agent gateway users route to '{peer_target}' (pin overrides aliases).")
             _echo_identity_mapping(hermes_host)
         elif shape == "multi":
             # Preserve operator-curated host-level aliases across multi → multi

website/docs/user-guide/features/honcho.md

@@ -165,7 +165,7 @@ The setup wizard detects whether a gateway platform is connected and skips this
 
 | Answer | Result |
 |--------|--------|
-| **just me** | `pinUserPeer: true` — everyone collapses to your peer |
+| **just me** | `pinUserPeer: true` — every non-agent gateway user collapses to your peer. Pin overrides all aliases, so pick this only when no user-side identity needs its own peer. If separate agents reach the gateway and each needs a distinct peer, do **not** pin — leave `pinUserPeer: false` and map them via `userPeerAliases` (the `[e]` editor) instead |
 | **me + other people** (pooled) | `pinUserPeer: false` + `userPeerAliases` mapping your runtime IDs to `peerName` — you stay on your shared history, others get their own peers |
 | **only other people** | `pinUserPeer: false`, optional `runtimePeerPrefix` — each user gets their own peer |