docs: Document HTTPS support in README

Author: thced

README.md

@@ -20,6 +20,7 @@ endpoints declared in an OpenAPI 3.1.x specification. Handlers are pure function
 - [JSON mapping](#json-mapping)
 - [Body parsers and response writers](#body-parsers-and-response-writers)
 - [Server configuration](#server-configuration)
+  - [HTTPS](#https)
 - [Interceptors and response decorators](#interceptors-and-response-decorators)
 - [After-response hooks](#after-response-hooks)
 - [Security](#security)
@@ -326,6 +327,64 @@ OpenApiServer.builder()
     .build();
 ```
 
+### HTTPS
+
+Point the builder at a PEM certificate chain and a PEM PKCS#8 private key:
+
+```java
+import java.nio.file.Path;
+
+var server = OpenApiServer.builder()
+    .spec(spec)
+    .handlers(handlers)
+    .https(
+        Path.of("/etc/letsencrypt/live/example.com/fullchain.pem"),
+        Path.of("/etc/letsencrypt/live/example.com/privkey.pem"))
+    .build();
+```
+
+certbot / Let's Encrypt write exactly these two files to
+`/etc/letsencrypt/live/<domain>/`: `fullchain.pem` (your certificate + the
+issuing intermediates, concatenated PEM) and `privkey.pem` (unencrypted PKCS#8).
+No conversion to PKCS12 / JKS is needed; the library parses the PEM directly
+using JDK APIs only.
+
+Both RSA and EC (P-256) private keys are accepted; the algorithm is detected
+automatically.
+
+When `.https(...)` is set, the default port changes from `8080` to `8443`.
+`port(int)` still overrides explicitly:
+
+```java
+OpenApiServer.builder()
+    .spec(spec)
+    .handlers(handlers)
+    .https(certChain, privateKey)
+    .port(443)              // overrides the 8443 default
+    .build();
+```
+
+For local development without a real certificate, generate a self-signed pair
+with one openssl command:
+
+```bash
+openssl req -x509 -newkey rsa:2048 -nodes -days 365 \
+  -keyout privkey.pem -out fullchain.pem \
+  -subj "/CN=localhost" \
+  -addext "subjectAltName=DNS:localhost,IP:127.0.0.1"
+```
+
+Clients (browsers, `curl`, `HttpClient`) need to trust the resulting certificate
+explicitly — it isn't signed by a public CA.
+
+**Not in this release** (each can land later without breaking the API):
+
+- Encrypted / password-protected private keys
+- PKCS12 / JKS keystore inputs
+- Certificate hot-reload on renewal (restart the process after `certbot renew`)
+- TLS protocol / cipher overrides (JDK defaults apply: TLS 1.2 and 1.3)
+- Serving HTTP and HTTPS from one `OpenApiServer` instance
+
 ### Graceful shutdown
 
 `OpenApiServer` exposes `stop(int delaySeconds)` for explicit shutdown that waits up to the given

docs/superpowers/plans/2026-05-21-https-support.md

@@ -779,7 +779,7 @@ SKIP=commitlint git commit -m "feat: Enable HTTPS via Builder.https(certChain, p
 
 - Modify: `README.md`
 
-- [ ] **Step 1: Add the table-of-contents entry**
+- [x] **Step 1: Add the table-of-contents entry**
 
 In the `## Table of contents` block, under `## Server configuration`, change:
 
@@ -796,7 +796,7 @@ to add a nested HTTPS link (mirroring the existing nesting style if present, oth
 
 Confirm the existing TOC's indentation style first by reading the top of `README.md`; match it.
 
-- [ ] **Step 2: Add the HTTPS subsection**
+- [x] **Step 2: Add the HTTPS subsection**
 
 In `README.md`, find the existing `### Graceful shutdown` heading inside `## Server configuration`. Immediately *before* it, insert:
 
@@ -860,15 +860,15 @@ explicitly — it isn't signed by a public CA.
 - Serving HTTP and HTTPS from one `OpenApiServer` instance
 ````
 
-- [ ] **Step 3: Verify the README renders the new section**
+- [x] **Step 3: Verify the README renders the new section**
 
 ```bash
 grep -n "^### HTTPS$" README.md
 ```
 
 Expected: one line, between the `### Bind address` and `### Graceful shutdown` headings inside `## Server configuration`.
 
-- [ ] **Step 4: Commit**
+- [x] **Step 4: Commit**
 
 ```bash
 git add README.md