2 files changed, 105 insertions, 3 deletions

diff --git a/docs/SERVER_SETUP.md b/docs/SERVER_SETUP.md
new file mode 100644
index 0000000..e2f3177
--- /dev/null
+++ b/docs/SERVER_SETUP.md
@@ -0,0 +1,100 @@
+# Server setup
+
+The server speaks TLS and needs a PKCS#12 identity (`identity.p12`) plus the
+PEM key/certificate used to build it. The files are read from the current
+working directory.
+
+## Quick start
+
+From the project root:
+
+```sh
+cargo run --bin server -- --init
+cargo run --bin server
+```
+
+`--init` creates a self-signed development identity and exits. The next
+command starts the server on `127.0.0.1:11525`.
+
+If `identity.p12` is missing at startup, the server now prints these same
+instructions instead of only the raw OS error.
+
+## What `--init` creates
+
+| File | Purpose |
+| --- | --- |
+| `identity.p12` | PKCS#12 identity loaded by `native-tls`. Empty password. Uses PBE-SHA1-3DES and a SHA-1 MAC so the Windows SChannel backend can load it. |
+| `key.pem` | RSA private key used to build the identity. Not read at runtime. |
+| `cert.pem` | Public certificate, useful for inspection. |
+
+On Unix, `identity.p12` and `key.pem` are set to mode `0600`. All three are
+ignored by git (`*.p12`, `*.pem`, `*.key`).
+
+## Manual setup
+
+If `openssl` is not installed or you want to control the certificate:
+
+```sh
+openssl req -x509 -newkey rsa:2048 \
+  -keyout key.pem -out cert.pem \
+  -days 3650 -nodes -subj "/CN=localhost"
+
+openssl pkcs12 -export -out identity.p12 \
+  -inkey key.pem -in cert.pem -passout pass:
+```
+
+The password must be empty because the server calls
+`Identity::from_pkcs12(&data, "")`.
+
+## Running
+
+```sh
+# default: 127.0.0.1:11525
+cargo run --bin server
+
+# listen on all interfaces
+cargo run --bin server -- -i 0.0.0.0 -p 11525
+
+# show options
+cargo run --bin server -- --help
+```
+
+Then start the client in another terminal:
+
+```sh
+cargo run --bin client
+```
+
+On first contact the client prints the SPKI fingerprint and pins it. If you
+regenerate the server identity, the client will reject the new key; run
+`forget-host` in the client if the change is intentional.
+
+## Windows
+
+`--init` shells out to `openssl`, so OpenSSL must be installed and on `PATH`
+(Git for Windows, WSL, or a standalone OpenSSL build). The generated files work
+the same way. `--init` uses SChannel-friendly PKCS#12 algorithms; if you build
+the identity by hand on Windows, use:
+
+```sh
+openssl pkcs12 -export -out identity.p12 -inkey key.pem -in cert.pem \
+  -passout pass: -keypbe PBE-SHA1-3DES -certpbe PBE-SHA1-3DES -macalg sha1
+```
+
+## Security notes
+
+- This is a self-signed development identity with an empty PKCS#12 password.
+  Treat `key.pem` and `identity.p12` as secrets and do not commit them.
+- The trust model is TOFU: clients pin the SPKI fingerprint on first contact.
+  A changed key is a loud error, not an automatic re-trust.
+- For a public deployment, use a CA-issued certificate and protect the
+  PKCS#12 with a password; the current server code expects an empty password.
+
+## Troubleshooting
+
+| Symptom | Fix |
+| --- | --- |
+| `Failed to initialize TLS: Could not read TLS identity` | Run `cargo run --bin server -- --init`. |
+| `Address already in use` | Stop the other server or pass `-p <port>`. |
+| Client says `HOST KEY CHANGED` | The server certificate changed. If intentional, run `forget-host` in the client. |
+| `openssl` not found | Install OpenSSL or use the manual commands on a machine that has it. |
diff --git a/docs/TESTING.md b/docs/TESTING.md
index 6cac6fa..55f5422 100644
--- a/docs/TESTING.md
+++ b/docs/TESTING.md
@@ -15,19 +15,21 @@ shared global database. Each test owns its state.
 | `tests/client_ui.rs` | Help, history, completion, bet parsing, display width, cursor math. |
 | `tests/protocol.rs` | Newline buffering and timeout/error classification. |
 | `tests/server_core.rs` | Handler, bcrypt migration, SQL injection, transaction rollback, `plays` audit, sessions. |
+| `tests/server_setup.rs` | `--init` identity generation, PKCS#12 loadability, overwrite refusal. |
 | `tests/slots.rs` | Server slots payout rules and overflow handling. |
 | `tests/storage.rs` | Client/server SQLite storage helpers. |
 | `tests/tofu.rs` | SPKI fingerprint and TOFU decisions. |
 
-`tests/tofu.rs` shells out to `openssl`, so run it on a machine where the
-`openssl` CLI is available.
+`tests/tofu.rs` and `tests/server_setup.rs` shell out to `openssl`, so run them
+on a machine where the `openssl` CLI is available.
 
 ## Manual TUI checklist
 
 There is no CI. Run this on Linux and on a Windows VM before a release.
 Use an 80-column terminal because several output lines are width-sensitive.
 
-1. Start the server with a valid `identity.p12`, then start the client.
+1. Run `cargo run --bin server -- --init` once, then start the server with a
+   valid `identity.p12` and start the client.
 2. First contact prints three lines and the 64-character fingerprint does not
    wrap at 80 columns. `Connected to ...` shows a one-decimal ping.
 3. `register` / `login`: backspace removes one `*` per key, Esc cancels the