checkpoint: implement wgcloak v1 foundations

docs/TROUBLESHOOTING.md

@@ -0,0 +1,65 @@
+# Troubleshooting
+
+Check the simplest layer that can explain the symptom, then move outward.
+
+## Process exits immediately
+
+- Run the same command in the foreground and read the fatal configuration
+  error.
+- Check that every secret/certificate path exists and is readable by the
+  service account, but not by unrelated users.
+- Run `wgcloak --help` and, where implemented, `wgcloak check-config` to spot a
+  command or schema mismatch.
+- Confirm listener addresses are valid and no other process owns the port.
+
+## Client cannot connect
+
+- Verify DNS resolution and the configured server name/port.
+- Confirm the selected transport is implemented in this build; an `auto` list
+  may mention future transports.
+- For direct UDP, check both directions in the host firewall and allow the
+  server's UDP listener.
+- For TLS transports, verify the hostname matches the certificate and do not
+  disable certificate verification.
+- Authentication rejection means a bad/unknown client or secret and must not
+  be diagnosed as a firewall failure. Fix credentials before retrying.
+
+## Authentication failures or repeated probing
+
+Check client ID spelling, secret-file contents, ownership/mode, and system
+clock skew. Direct HELLO timestamps have a target default 60-second window;
+replayed client nonces are rejected. Repeated invalid credentials should stop
+fallback probing rather than generate traffic across every transport.
+
+## Connected but no application traffic
+
+- Confirm the local application sends to the configured local UDP address.
+- Confirm the server backend is listening at `[backend].target`.
+- Check `status`/`stats` or structured logs for selected transport, maximum
+  datagram size, dropped/oversized datagrams, and backend errors.
+- v1 remembers one most-recent local source peer per client tunnel. Concurrent
+  source peers can replace that return destination and produce a warning.
+- No application-layer fragmentation exists: reduce payload size when the
+  configured transport limit is exceeded (starting target is 1200 bytes).
+
+## Session disappears
+
+The target idle timeout is 120 seconds, refreshed by authenticated data or
+keepalive. Check keepalive settings, NAT expiry, server resource limits, and
+whether the client is reconnecting after a transport failure. A valid direct
+UDP packet can update the peer address after NAT rebinding; a spoofed packet
+without a valid MAC cannot.
+
+## Control socket unavailable
+
+Check the daemon's `XDG_RUNTIME_DIR`, socket ownership/mode, and whether a
+stale socket path remains after an unclean exit. The control interface is local
+only and may be absent until the operational-polish milestone is implemented.
+
+## Host hardening prevents startup
+
+Read the unit's journal output. Common causes are a secret/certificate path
+outside the unit's read paths, a changed binary location, or an address family
+not allowed by `RestrictAddressFamilies`. Correct the reviewed unit rather
+than weakening all hardening directives. `CAP_NET_BIND_SERVICE` is only needed
+for ports below 1024.