Update release docs: TLS has shipped

midge.readme

@@ -30,21 +30,28 @@ This release ships:
 mqtt_pub/mqtt_sub and their -static counterparts all follow the same
 AmigaDOS conventions (ReadArgs templates, Ctrl-C to stop) and speak plain
 MQTT 3.1.1 over TCP. mqtt_pub/mqtt_sub are backed by mqtt.library and
-support QoS 0 and QoS 1 publish; mqtt_pub-static/mqtt_sub-static talk to
-bsdsocket.library directly with no library install required, but
-mqtt_pub-static only supports QoS 0 publish. mqtt.library itself also
-exposes an optional auto-reconnect mode to programs written against it
-directly. See https://sidick.github.io/midge/mqtt-library/ for the full
-mqtt.library guide.
+support QoS 0 and QoS 1 publish, plus TLS via AmiSSL (TLS/TLSINSECURE -
+needs AmiSSL installed separately, see Requirements below);
+mqtt_pub-static/mqtt_sub-static talk to bsdsocket.library directly with no
+library install required, but mqtt_pub-static only supports QoS 0 publish
+and neither -static tool supports TLS. mqtt.library itself also exposes an
+optional auto-reconnect mode to programs written against it directly. See
+https://sidick.github.io/midge/mqtt-library/ for the full mqtt.library
+guide.
 
-Planned for future releases: TLS via AmiSSL, and a ReAction dashboard
-application with Home Assistant MQTT discovery.
+Planned for future releases: a ReAction dashboard application with Home
+Assistant MQTT discovery.
 
 Requirements
 ------------
   - AmigaOS 3.1+ (3.2 is the reference platform), 68020 or better.
   - A TCP/IP stack providing bsdsocket.library (Roadshow, AmiTCP, Miami,
     or an emulator-provided stack).
+  - For TLS (mqtt_pub/mqtt_sub's TLS/TLSINSECURE switches): AmiSSL 5.x
+    (https://github.com/jens-maus/amissl), installed separately - not
+    bundled with this archive. Software TLS is CPU-intensive; a genuinely
+    stock, unaccelerated 68020 may see intermittent failures under it -
+    see https://sidick.github.io/midge/CLI-Reference/ for details.
 
 Quick start
 -----------

userdocs/Installation.md

@@ -47,6 +47,30 @@ If you'd rather not install anything, use `mqtt_pub-static`/
 [Two build flavours](CLI-Reference.md#two-build-flavours) for exactly what
 that trade-off costs you (QoS 1 publish support).
 
+## Installing AmiSSL (needed for TLS)
+
+`mqtt_pub`/`mqtt_sub`'s `TLS`/`TLSINSECURE` switches (see
+[CLI Reference](CLI-Reference.md)) need
+[AmiSSL](https://github.com/jens-maus/amissl) 5.x installed - it is not
+bundled with this archive. Download the OS3 package from AmiSSL's own
+releases and run its installer; that sets up `LIBS:amisslmaster.library`,
+the CPU-tier `LIBS:AmiSSL/` library, and the `AmiSSL:` assign the TLS
+certificate store is read through. All three matter - a missing `AmiSSL:`
+assign in particular can make AmigaOS pop up a "please insert volume"
+requester instead of a clean connect failure.
+
+Without AmiSSL installed, `TLS`/`TLSINSECURE` fail with a connect error;
+everything else in this release works exactly the same either way - TLS is
+entirely opt-in.
+
+Software TLS is CPU-intensive: a genuinely stock, unaccelerated 68020 has
+been found to intermittently fail under it, while any real accelerator (or
+a 68030 or better) is reliable - see
+[CLI Reference](CLI-Reference.md#a-note-on-tls-and-cpu-speed).
+
+`mqtt_pub-static`/`mqtt_sub-static` have no AmiSSL support at all and
+reject `TLS` outright.
+
 ## Verifying it worked
 
 ```

userdocs/index.md

@@ -6,14 +6,16 @@ as both a display/control surface and a publisher of its own telemetry.
 
 This release ships the command-line tools `mqtt_pub` and `mqtt_sub`, and
 `mqtt.library`, a shared library exposing the same MQTT client to other
-AmigaOS programs. TLS support and a ReAction dashboard application are
-planned for future releases.
+AmigaOS programs, with optional TLS via AmiSSL. A ReAction dashboard
+application is planned for a future release.
 
 ## Requirements
 
 - AmigaOS 3.1+ (3.2 is the reference platform), 68020 or better.
 - A TCP/IP stack providing `bsdsocket.library` (Roadshow, AmiTCP, Miami, or
   an emulator-provided stack).
+- For TLS: [AmiSSL](https://github.com/jens-maus/amissl) 5.x, installed
+  separately - see [Installation](Installation.md#installing-amissl-needed-for-tls).
 
 See [Installation](Installation.md) for unpacking the archive and the
 `mqtt.library` install step the default tools need.