update developer documentation

AGENTS.md

@@ -0,0 +1,109 @@
+# AGENTS.md
+
+## Project overview
+
+Open OSCAR Server is an open-source instant messaging server written in Go that
+is compatible with classic AIM and ICQ clients. It implements the OSCAR, TOC,
+and Kerberos protocols, plus HTTP management and web APIs. It is independent of
+AOL/Yahoo and non-commercial.
+
+## Quick commands
+
+| Task | Command |
+|------|---------|
+| Build | `go build -o open_oscar_server ./cmd/server` |
+| Test | `go test -race ./...` |
+| Lint (matches CI) | `gofmt -s -l . && go vet ./...` |
+| Run (dev, plain) | `make run` |
+| Run (dev, SSL) | `make run-ssl` (+ `make run-stunnel` in a second terminal) |
+| Generate config | `make config` |
+| Regenerate mocks | `mockery` |
+| Build Docker images | `make docker-images` |
+
+## Architecture
+
+The binary in `cmd/server` starts five servers concurrently via `errgroup`:
+
+| Server | Protocol | Default port |
+|--------|----------|-------------|
+| OSCAR | FLAP/BOS (binary) | 5190 (5193 via stunnel for SSL) |
+| TOC | TOC (text-based) | 9898 |
+| Kerberos | Kerberos auth | 1088 |
+| MgmtAPI | HTTP (management) | 8080 |
+| WebAPI | HTTP (web AIM-style, AMF3) | 9000 (opt-in via `ENABLE_WEBAPI=1`) |
+
+All five servers share a common dependency container (`Container` in
+`cmd/server/factory.go`) that wires together config, persistence, and business
+logic.
+
+## Key packages
+
+| Package | Role |
+|---------|------|
+| `cmd/server` | Entry point; wires dependencies and starts all servers. |
+| `config` | Configuration via env vars (`envconfig`). Config files are generated from the `Config` struct—do **not** edit them by hand; run `make config` instead. |
+| `foodgroup` | Core business logic for OSCAR "food groups": Auth, Buddy, Feedbag, ICBM, Chat, BART, Locate, OService, ICQ, Admin, PermitDeny, ODir, Stats, UserLookup, ChatNav. Shared by the OSCAR, TOC, and WebAPI servers. |
+| `wire` | OSCAR wire protocol: SNAC/FLAP encoding, TLV, food group codes, rate limits, frames. |
+| `state` | Persistence and in-memory state: `SQLiteUserStore`, `InMemorySessionManager`, `InMemoryChatSessionManager`, DB migrations. |
+| `server/oscar` | OSCAR protocol server; SNAC routing and handler wiring. |
+| `server/toc` | TOC protocol server (text-based). |
+| `server/kerberos` | Kerberos auth server. |
+| `server/http` | Management HTTP API (users, sessions, chat rooms). Spec: `api.yml`. |
+| `server/webapi` | Web AIM-style API (AMF3). Spec: `docs/open_api/webapi.yml`. |
+
+## Database
+
+SQLite via `modernc.org/sqlite` (pure-Go, no CGO). Default file: `oscar.sqlite`.
+Migrations live in `state/migrations/` as numbered `.up.sql` / `.down.sql` pairs
+and are applied automatically at startup.
+
+## Configuration
+
+Configuration is env-var driven via `kelseyhightower/envconfig`. Settings files
+(`config/settings.env`, `config/ssl/settings.env`) are **generated** from the
+`Config` struct by running `make config`. Never edit them by hand—change the
+`Config` struct and regenerate.
+
+## Testing conventions
+
+- **Table-driven tests** — slices of structs with `name`, inputs, and expected
+  outputs; iterated with `t.Run`.
+- **Assertions** — `github.com/stretchr/testify/assert` (`assert.Equal`,
+  `assert.NoError`, etc.).
+- **Mocks** — generated by [mockery](https://github.com/vektra/mockery)
+  (config in `.mockery.yaml`). Mock files are named `mock_*_test.go` and live
+  next to the code they test. Regenerate with `mockery` at the repo root.
+- **`mockParams` structs** — group per-test-case mock expectations; defined in
+  `*_helpers_test.go` files alongside the tests.
+- **Test helpers** — shared fixtures and builders live in `*_helpers_test.go`.
+
+## Code style
+
+- Standard Go conventions; CI enforces `gofmt -s` and `go vet`.
+- Small, focused interfaces for dependency injection and testability (e.g.
+  `SessionRetriever`, `FeedbagManager`).
+- Doc comments on all exported symbols.
+- Errors follow the standard `if err != nil` pattern; sentinel errors and custom
+  error types are used where appropriate.
+
+## OSCAR protocol reference
+
+The [OSCAR protocol specification](https://devinsmith.net/backups/OSCAR/) covers
+roughly 80% of the protocol: FLAP framing, SNAC structure, and the major food
+groups (OSERVICE, BUDDY, ICBM, FEEDBAG, BART, LOCATE, PD, INVITE). The
+remaining ~20% (e.g. some ICQ-specific SNACs, chat, and lesser-used food groups)
+is not documented there and must be reverse-engineered from client behavior or
+other sources.
+
+## Useful docs
+
+| Document | Path |
+|----------|------|
+| Build & run | `docs/BUILD.md` |
+| Management API spec | `api.yml` |
+| Web API spec | `docs/open_api/webapi.yml` |
+| OSCAR protocol spec | https://devinsmith.net/backups/OSCAR/ |
+| Client setup guides | `docs/CLIENT.md`, `docs/CLIENT_TIK.md`, `docs/CLIENT_ICQ.md` |
+| Docker guide | `docs/DOCKER.md` |
+| Platform guides | `docs/LINUX.md`, `docs/MACOS.md`, `docs/WINDOWS.md` |
+

Makefile

@@ -56,6 +56,18 @@ docker-run-bg: ## Run Open OSCAR Server in background with docker-compose
 docker-run-stop: ## Stop Open OSCAR Server docker-compose services
 	OSCAR_HOST=$(OSCAR_HOST) docker compose down
 
+.PHONY: run
+run: # run the server with plain socket config
+	./scripts/run_dev.sh ./config/settings.env
+
+.PHONY: run-ssl
+run-ssl: # run the server with ssl socket config
+	./scripts/run_dev.sh ./config/ssl/settings.env
+
+.PHONY: run-stunnel
+run-stunnel: # run stunnel for SSL termination
+	./scripts/run_stunnel.sh ./certs/server.pem
+
 ################################################################################
 # SSL Helpers
 ################################################################################

docs/BUILD.md

@@ -11,7 +11,8 @@ Before you can run Open OSCAR Server, set up the following software dependencies
 
 Since Open OSCAR Server is written in go, install the latest version of [golang](https://go.dev/).
 
-If you're new to go, try [Visual Studio Code](https://code.visualstudio.com) wth the [go plugin](https://code.visualstudio.com/docs/languages/go)
+If you're new to go, try [Visual Studio Code](https://code.visualstudio.com) with
+the [go plugin](https://code.visualstudio.com/docs/languages/go)
 as your first IDE.
 
 ### Mockery (optional)
@@ -20,7 +21,7 @@ as your first IDE.
 mocks if you change any interfaces.
 
 ```shell
-go install github.com/vektra/mockery/v2@latest
+go install github.com/vektra/mockery/v3@latest
 ```
 
 Run the following command in a terminal from the root of the repository in order to regenerate test mocks,
@@ -29,16 +30,7 @@ Run the following command in a terminal from the root of the repository in order
 mockery
 ```
 
-## Run the Server
-
-To run the server using `go run`, run the following script from the root of the repository. The default settings can be
-modified in `config/settings.env`.
-
-```shell
-scripts/run_dev.sh
-```
-
-## Build the Server
+## Building the Server Binary
 
 To build the server binary:
 
@@ -52,6 +44,106 @@ To run the binary with the settings file:
 ./open_oscar_server -config config/settings.env
 ```
 
+## Running the Server
+
+This project provides configuration for running with plain sockets and SSL sockets. Choose the mode that best suits
+your needs.
+
+### Plain Socket Config (most common)
+
+To run AIM v1.0-v6.1, you can use the plain socket config (located in `config/settings.env`) with no additional
+dependencies.
+
+```shell
+make run
+```
+
+### SSL Socket Config (for AIM v6.2-v7.0)
+
+To run AIM v6.2-v7.0, you must run the server with SSL enabled. This project provides tooling for generating a
+self-signed certificate and fronting the server with the SSL proxy [stunnel](https://www.stunnel.org/downloads.html).
+
+#### Prerequisites
+
+- Git
+- [Docker Desktop](https://docs.docker.com/get-started/get-docker/)
+- Unix-like terminal with Make installed (use WSL2 for Windows)
+
+#### 1. Clone the Repository
+
+```bash
+git clone https://github.com/mk6i/open-oscar-server.git
+cd open-oscar-server
+```
+
+#### 2. Build Docker Images
+
+This builds Docker images for:
+
+- Certificate generation
+- SSL termination
+- The Open OSCAR Server runtime
+
+```bash
+make docker-images
+```
+
+#### 3. Configure SSL Certificate
+
+The following creates a self-signed certificate under `certs/server.pem`.
+
+```bash
+make docker-cert OSCAR_HOST=ras.dev
+```
+
+Replace `ras.dev` with the hostname clients will use to connect.
+
+#### 4. Generate NSS Certificate Database
+
+This creates the [NSS certificate database](https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSS) in
+`certs/nss/`, which must be installed on each AIM 6.2+ client.
+
+```bash
+make docker-nss
+```
+
+#### 5. Start Open OSCAR Server
+
+Start the server in a terminal.
+
+```bash
+make run-ssl
+```
+
+#### 6. Start stunnel
+
+In a separate terminal, start stunnel.
+
+```bash
+make run-stunnel
+```
+
+#### 7. Client Configuration
+
+##### Certificate Database
+
+Follow the [AIM 6.x client setup instructions](AIM_6_7.md#aim-6265312-setup) to install the `certs/nss/` database on
+each client.
+
+##### Resolving Hostname
+
+If `OSCAR_HOST` (e.g., `ras.dev`) is not a real domain with DNS configured, you'll need to add it to each client's hosts
+file so clients can resolve it.
+
+- Linux/macOS: `/etc/hosts`
+- Windows: `C:\Windows\System32\drivers\etc\hosts`
+
+Add a line like this, replacing the IP with your server's IP address:
+
+```
+127.0.0.1 ras.dev
+```
+
 ## Testing
 
 Open OSCAR Server includes a test suite that must pass before merging new code. To run the unit tests, run the following
@@ -66,3 +158,14 @@ go test -race ./...
 The config file `config/settings.env` is generated programmatically from the [Config](../config/config.go) struct using
 `go generate`. If you want to add or remove application configuration options, first edit the Config struct and then
 generate the configuration files by running `make config` from the project root. Do not edit the config files by hand.
+
+## Setting Up Test Clients (optional)
+
+Windows XP is the most convenient OS for running Windows OSCAR clients, which were released across the 1990s, 2000s,
+and 2010s. An ISO of the most recent version is available on [archive.org](https://archive.org/details/WinXPProSP3x86).
+
+To run Windows XP on your modern machine, install a hypervisor:
+
+- [UTM](https://mac.getutm.app/) (macOS)
+- [QEMU w/ KVM](https://www.qemu.org/) (Linux)
+- [VirtualBox](https://www.virtualbox.org/) (Windows)

docs/DOCKER.md

@@ -6,7 +6,7 @@ This guide explains how to set up an SSL-enabled instance of Open OSCAR Server u
 
 - Git
 - [Docker Desktop](https://docs.docker.com/get-started/get-docker/)
-- Unix-like terminal with Makefile installed (use WSL2 for Windows)
+- Unix-like terminal with Make installed (use WSL2 for Windows)
 
 ## Getting Started
 

scripts/run_dev.sh

@@ -6,7 +6,7 @@
 set -e
 
 SCRIPT_DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
-DEFAULT_ENV_FILE="$SCRIPT_DIR/../config/ssl/settings.env"
+DEFAULT_ENV_FILE="$SCRIPT_DIR/../config/settings.env"
 
 if [ "$#" -gt 1 ]; then
   echo "Usage: $0 [path/to/settings.env]"