document pidgin client setup

docs/CLIENT_PIDGIN.md

@@ -0,0 +1,58 @@
+# Pidgin Client Setup
+
+This guide explains how to configure [Pidgin](https://www.pidgin.im/) to connect to Open OSCAR Server, either
+unencrypted or over SSL.
+
+## Prerequisites
+
+1. **Pidgin with AIM Support**
+
+   Use one of the following:
+
+    - **Modern Pidgin**: Install the [retro-prpl](https://github.com/pidgin/retro-prpl) plugin, which adds AIM and
+      ICQ support.
+    - **Pidgin 2.14.2**: The last version that supported AIM natively. Download it from
+      [SourceForge](https://sourceforge.net/projects/pidgin/files/Pidgin/2.14.2/).
+
+2. **Open OSCAR Server Instance**
+
+   Configure and run an Open OSCAR Server instance using one of the available guides.
+
+    - For a simple **unencrypted** installation, follow the release setup guide for your operating system.
+        - [Windows](./WINDOWS.md)
+        - [Linux](./LINUX.md)
+        - [macOS (Intel & Apple Silicon)](./MACOS.md)
+    - For an advanced **SSL-enabled** installation, follow the [Docker Setup Guide](./DOCKER.md).
+
+## Setup Procedure
+
+1. **Add an AIM Account**
+
+   Open **Accounts** → **Manage Accounts** → **Add...** and select **AIM** as the protocol. On the **Basic** tab,
+   enter your screen name as the **Username** and your password.
+
+2. **Configure the Connection**
+
+   On the **Advanced** tab, configure the connection type that matches your server installation.
+
+    - **Unencrypted**: Set **Server** and **Port** according to the `OSCAR_ADVERTISED_LISTENERS_PLAIN` configuration
+      found in `config/settings.env`. For example, if `OSCAR_ADVERTISED_LISTENERS_PLAIN=LOCAL://127.0.0.1:5190`, set
+      **Server** to `127.0.0.1` and **Port** to `5190`. Set **Connection security** to **Don't use encryption**.
+    - **SSL**: Set **Server** and **Port** according to the `OSCAR_ADVERTISED_LISTENERS_SSL` configuration found in
+      `config/ssl/settings.env`. For example, if `OSCAR_ADVERTISED_LISTENERS_SSL=LOCAL://ras.dev:5193`, set **Server**
+      to `ras.dev` and **Port** to `5193`. Set **Connection security** to **Require encryption**.
+
+   For both connection types, set **Authentication method** to **MD5-based**.
+
+   Click **Add** to save the account. Pidgin signs on immediately.
+
+3. **Sign On and Accept the Certificates (SSL Only)**
+
+   If your server uses the certificate generated by `make docker-cert`, which is signed by the server's private root
+   CA, Pidgin warns twice that it cannot validate the certificate. Click **Accept** both times. Pidgin remembers both
+   certificates, so the warnings do not appear again.
+
+    - The first warning is for your server's hostname, during authentication.
+    - The second warning is for `bos.oscar.aol.com` and says the certificate claims to be from your server's hostname
+      instead. Pidgin checks the connection made after authentication against this hardcoded AOL hostname, so the
+      warning appears even with a certificate from a trusted CA.