docs: peering trust terminology — names for the four concepts (#134)

Gives stable names to what issue #134 showed gets conflated: Trusted peer
(invite-verified, operator decision), Discovered peer (learned from a
Trusted peer's advertisement, hard-capped at Observer — TRUST IS NOT
TRANSITIVE), Routing hint (what a Discovered peer actually contributes:
reachability, not trust), and Peer advertisement (the mechanism itself,
a feature not a leak).

Records the two rules that make the model sound (trust requires a
traceable operator decision; discovery is transitive, trust is not), why
advertisement exists (one invite makes a node reachable to the trusted
set without granting anything), and the deferred open questions: the
'don't advertise my peers' privacy toggle and UI tier vocabulary.

docs/README.md

@@ -54,6 +54,7 @@ step-by-step guides, and some predate the current implementation.
 - [Dual Ecash](dual-ecash-design.md)
 - [Hardware Signer](hardware-signer-design.md)
 - [Manifest Hooks](manifest-hooks-design.md)
+- [Peering & Federation Trust](peering-trust-model.md) — naming/semantics of trust levels vs discovery (#134)
 - [kdump + rasdaemon Troubleshooting](kdump-rasdaemon-design.md) — post-mortem and hardware-error capture on nodes (#144)
 - [Meshroller Integration](meshroller-integration-design.md)
 - [Nostr Git Source Hosting](nostr-git-source-hosting.md)

docs/peering-trust-model.md

@@ -0,0 +1,47 @@
+# Peering & Federation Trust — naming and semantics
+
+Status: TERMINOLOGY SET — records what the code does today (#134).
+Deferred: the "don't advertise my peers" opt-out (see §Open questions).
+
+The code is the authority; this doc gives names to the four concepts that
+issue #134 showed get conflated in conversation. Where a name changed in
+user-facing discussion, the term below is the one to use everywhere
+(UI copy, docs, issues, reviews).
+
+## The four concepts
+
+| Term (use this) | What it is | Where it lives |
+|---|---|---|
+| **Trusted peer** | A node THIS operator invited and verified: bilateral DID challenge over an out-of-band invite code (`federation::sync`, ADR-007). The only level that grants full access. | `TrustLevel::Trusted`, set via `TrustSource::Invite` or `Manual` |
+| **Discovered peer** | A peer we learned about from a Trusted peer's advertised list — the transitive merge. Never better than **Observer**: `TRUST IS NOT TRANSITIVE` (sync.rs guard). | `TrustLevel::Observer`, `TrustSource::TransitiveMerge` |
+| **Routing hint** | What a Discovered peer actually contributes: an address that lets us route directly over FIPS without a second invite hop. Reachability, not trust. | Observer-level sync + FIPS endpoint records |
+| **Peer advertisement** | The act of a Trusted peer sharing its own peer list during sync. This is the *mechanism* #134 observed — a feature, not a leak. | sync.rs merge path |
+
+## The two rules that make it sound
+
+1. **Trust requires an operator decision, always traceable.** Every trust
+   level carries a `TrustSource`. Only a minted invite (or an explicit
+   operator change) can produce `Trusted`; uninvited joins and transitive
+   merges are hard-capped at `Observer` — a peer can never expand our
+   trusted set on its own authority.
+2. **Discovery is transitive; trust is not.** Seeing more nodes through a
+   Trusted peer is expected and useful (routing). Granting those nodes
+   anything is an operator action, never automatic.
+
+## Why a Trusted peer advertising its list is by design
+
+Without advertisement, every new node needs a direct invite from every node
+that wants to reach it — the invite graph becomes the routing bottleneck
+AdDR-007 set out to remove. With it, one invite makes a node *reachable* to
+the trusted set (routing hints), while *authorization* still requires each
+operator's own invite. Reachability ≠ access.
+
+## Open questions (deferred, tracked in #134)
+
+- **"Don't advertise my peers"** — an operator privacy toggle suppressing
+  peer advertisement during sync. Small code change, real design questions:
+  it hides peers who may WANT discovery, and it degrades the routing benefit
+  for every node trusting you. Needs a product decision, not just code.
+- **Tier vocabulary in the UI** — whether to surface "Observer" as such or
+  a friendlier term ("Connected"/"Visible") — part of the TODO.md peering
+  trust-model item.