fix(readme): enhance clarity and structure of installation and documentation sections

README.md

@@ -1,16 +1,18 @@
+<!-- markdownlint-disable MD033 -->
 # Newt
+
 [![PkgGoDev](https://pkg.go.dev/badge/github.com/fosrl/newt)](https://pkg.go.dev/github.com/fosrl/newt)
 [![GitHub License](https://img.shields.io/github/license/fosrl/newt)](https://github.com/fosrl/newt/blob/main/LICENSE)
 [![Go Report Card](https://goreportcard.com/badge/github.com/fosrl/newt)](https://goreportcard.com/report/github.com/fosrl/newt)
 
 Newt is a fully user space [WireGuard](https://www.wireguard.com/) tunnel client and TCP/UDP proxy, designed to securely expose private resources controlled by Pangolin. By using Newt, you don't need to manage complex WireGuard tunnels and NATing.
 
-### Installation and Documentation
+## Installation and Documentation
 
 Newt is used with Pangolin and Gerbil as part of the larger system. See documentation below:
 
 - [Full Documentation](https://docs.fossorial.io)
--   Observability Quickstart: see docs/observability.md (Prometheus/OTel Collector setup, smoke tests)
+- Observability Quickstart: see `docs/observability.md` — canonical Prometheus/OTel Collector quickstart and smoke tests
 
 ## Preview
 
@@ -90,7 +92,7 @@ All CLI arguments can be set using environment variables as an alternative to co
 
 You can use `CONFIG_FILE` to define a location of a config file to store the credentials between runs.
 
-```
+```sh
 $ cat ~/.config/newt-client/config.json
 {
   "id": "spmzu8rbpzj1qq6",
@@ -108,12 +110,7 @@ Default locations:
 - **Windows**: `%PROGRAMDATA%\newt\newt-client\config.json`
 - **Linux/Others**: `~/.config/newt-client/config.json`
 
-## Observability Quickstart
+<!-- Observability Quickstart moved to docs/observability.md (canonical). -->
-
-For a quick start with Prometheus scraping and smoke checks, read the step-by-step guide in docs/observability.md. It includes:
-- docker-compose.metrics.yml for direct /metrics scraping (recommended)
-- docker-compose.metrics.collector.yml for the OTLP → Collector → Prometheus exporter path (no double-scrape)
-- scripts/smoke-metrics.sh for basic verification
 
 ## Examples
 
@@ -269,7 +266,6 @@ Supported values include:
 
     `ssh://user@host`
 
-
 ```yaml
 services:
     newt:
@@ -284,6 +280,7 @@ services:
             - NEWT_SECRET=nnisrfsdfc7prqsp9ewo1dvtvci50j5uiqotez00dgap0ii2
             - DOCKER_SOCKET=unix:///var/run/docker.sock
 ```
+
 >If you previously used just a path like `/var/run/docker.sock`, it still works — Newt assumes it is a UNIX socket by default.
 
 #### Hostnames vs IPs
@@ -329,12 +326,12 @@ Newt supports mutual TLS (mTLS) authentication if the server is configured to re
 
 > This is the original method and still supported.
 
-* File must contain:
+- File must contain:
 
-  * Client private key
+  - Client private key
-  * Public certificate
+  - Public certificate
-  * CA certificate
+  - CA certificate
-* Encrypted `.p12` files are **not supported**
+- Encrypted `.p12` files are **not supported**
 
 Example:
 
@@ -350,9 +347,9 @@ newt \
 
 You can now provide separate files for:
 
-* `--tls-client-cert`: client certificate (`.crt` or `.pem`)
+- `--tls-client-cert`: client certificate (`.crt` or `.pem`)
-* `--tls-client-key`: client private key (`.key` or `.pem`)
+- `--tls-client-key`: client private key (`.key` or `.pem`)
-* `--tls-ca-cert`: CA cert to verify the server
+- `--tls-ca-cert`: CA cert to verify the server
 
 Example:
 
@@ -366,7 +363,6 @@ newt \
 --tls-ca-cert ./ca.crt
 ```
 
-
 ```yaml
 services:
     newt: