docs(kubo): flag server-profile reverse-proxy gotcha

.github/styles/pln-ignore.txt

@@ -303,6 +303,7 @@ sys
 systemd
 sztandera
 takedown
+Tailscale
 testground
 testnet
 toolkits

docs/how-to/command-line-quick-start.md

@@ -16,11 +16,13 @@ If you have not yet installed Kubo, follow the [Kubo install guide](../install/c
 `ipfs` stores all its settings and internal data in a directory called _the repository._ Before using Kubo for the first time, you’ll need to initialize the repository. 
 
 :::tip
- - If you are running a Kubo node in a data center, you should initialize IPFS with the `server` profile. Doing so will prevent IPFS from creating data center-internal traffic trying to discover local nodes:
+ - If you are running Kubo on a public-internet host (data center, VPS, cloud), initialize with the `server` profile. It disables local-network discovery and refuses libp2p connections to and from non-globally-routable address ranges, so the node does not generate discovery traffic that some hosting providers flag as abuse:
 
     ```bash
     ipfs init --profile server
     ```
+
+    See the [`server` profile reference](https://github.com/ipfs/kubo/blob/master/docs/config.md#server-profile) for the full filter list, override rows, and the reverse-proxy interaction (a `/ip4/127.0.0.1/tcp/.../ws` listener fronted by a local nginx or Caddy proxy needs one of those overrides to keep working).
  - Be careful using `sudo` on Unix platforms (including macOS)! Running `sudo ipfs init` will create the repository for the `root` user, instead of your local user account. Kubo doesn't require root privileges, so it's best to run all `ipfs` commands as a regular user!
 :::
 

docs/how-to/nat-configuration.md

@@ -98,7 +98,14 @@ In this step, you will update your Kubo configuration to set `Swarm.AppendAnnoun
         "API": "/ip4/127.0.0.1/tcp/5001",
         "Gateway": "/ip4/127.0.0.1/tcp/8080"
     },
-    ``` 
+    ```
+
+   :::tip
+   `Addresses.NoAnnounce` and [`Swarm.AddrFilters`](https://github.com/ipfs/kubo/blob/master/docs/config.md#swarmaddrfilters) are not the same thing:
+
+   - `Addresses.NoAnnounce` is a publish-side filter. It strips matching addresses from what other peers learn about you. Use it to hide LAN or loopback addresses from your DHT self-record.
+   - `Swarm.AddrFilters` is a connection gate. It refuses libp2p dial and accept on matching addresses. Putting loopback here will also break a local reverse proxy talking to Kubo on `127.0.0.1`.
+   :::
 
 1. Update `AppendAnnounce`, where `<public-ip>` is your public IP address and `<port>` is the port number set in the previous step: 
 

docs/how-to/troubleshooting-kubo.md

@@ -155,6 +155,16 @@ To see the multiaddr used for the connection run:
 ipfs swarm peers -v | grep <peerId>
 ```
 
+## A configured Swarm listener appears unreachable
+
+If a listener you put in [`Addresses.Swarm`](https://github.com/ipfs/kubo/blob/master/docs/config.md#addressesswarm) does not work and Kubo logs an ERROR like
+
+```
+Addresses.Swarm listener "/ip4/127.0.0.1/tcp/8081/ws" matches Swarm.AddrFilters rule "/ip4/127.0.0.0/ipcidr/8", so Kubo rejects every incoming connection to it. Remove "/ip4/127.0.0.0/ipcidr/8" from Swarm.AddrFilters to allow connections to this listener.
+```
+
+(or the matching `Addresses.NoAnnounce` variant) at startup, the gate or announcement filter you configured covers that listener. The most common trigger is applying the [`server` profile](https://github.com/ipfs/kubo/blob/master/docs/config.md#server-profile) while keeping a `127.0.0.1` listener fronted by a local reverse proxy (nginx, Caddy). Remove the offending CIDR from the field named in the log line. The kubo [`server` profile override table](https://github.com/ipfs/kubo/blob/master/docs/config.md#overriding-specific-entries) lists the recommended removals for the common cases (multiple loopback daemons, LAN peering, Tailscale or other CGNAT overlays, IPv6 ULA mesh, Yggdrasil, NAT64).
+
 ## Go debugging
 
 When you see ipfs doing something (using lots of CPU, memory, or otherwise being weird), the first thing you want to do is gather all the relevant profiling information.