From 108d0ec9e1f82ac282cb40031cd7184627dd9532 Mon Sep 17 00:00:00 2001
From: Latte <1+latte@noreply.hiddenden.cafe>
Date: Mon, 29 Jun 2026 13:53:43 +0000
Subject: [PATCH] Add Configuration wiki page

---
 Configuration.md | 59 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 59 insertions(+)
 create mode 100644 Configuration.md

diff --git a/Configuration.md b/Configuration.md
new file mode 100644
index 0000000..16b2f14
--- /dev/null
+++ b/Configuration.md
@@ -0,0 +1,59 @@
+# Configuration
+
+Everything in familiar is overridable via **environment variables**, so the defaults (which match the registered EVE application) can be changed without editing code. This page lists every variable and the on-disk paths.
+
+## EVE SSO & application
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `FAMILIAR_SSO_BASE` | `https://login.eveonline.com` | EVE SSO base; the authorize/token URLs derive from it. |
+| `FAMILIAR_CLIENT_ID` | *(the registered app's id)* | OAuth Client ID. Not a secret for a PKCE client. |
+| `FAMILIAR_CALLBACK_HOST` | `localhost` | Host the login callback server binds to. |
+| `FAMILIAR_CALLBACK_PORT` | `8765` | Port for the login callback (`/callback`). |
+| `FAMILIAR_SCOPES` | *all read + write scopes* | Space-separated scope list. Set to a subset for read-only login. |
+
+## ESI client
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `FAMILIAR_ESI_BASE` | `https://esi.evetech.net/latest` | ESI base URL. |
+| `FAMILIAR_ESI_DATASOURCE` | `tranquility` | ESI datasource (e.g. `tranquility`). |
+| `FAMILIAR_ERROR_LIMIT_THRESHOLD` | `5` | Back off when the rolling ESI error window has this few requests left. |
+| `FAMILIAR_DISABLE_CACHE` | *(unset)* | `1/true/yes` disables the `Expires`-header response cache. |
+
+## SDE (offline lookups)
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `FAMILIAR_SDE_PATH` | `<data_dir>/sde.sqlite` | Path to the local SQLite SDE. |
+| `FAMILIAR_SDE_URL` | Fuzzwork `sqlite-latest.sqlite.bz2` | Download source for `familiar sde download` (override for a mirror). |
+
+## Writes & data directory
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `FAMILIAR_ENABLE_WRITES` | *(unset → enabled)* | `1/true/yes/on` forces writes on; otherwise the on-disk flag decides. Wins over the flag file. |
+| `FAMILIAR_DATA_DIR` | platform default *(below)* | Where the encrypted token store, key, write flag, audit log, and SDE live. |
+
+### Data directory default
+
+When `FAMILIAR_DATA_DIR` is unset:
+
+- **Windows:** `%LOCALAPPDATA%\familiar`
+- **Linux/macOS:** `$XDG_DATA_HOME/familiar` (or `~/.local/share/familiar`)
+
+The directory is created with `0o700` permissions where supported.
+
+## Files in the data directory
+
+| File | Contents |
+|------|----------|
+| `token.enc` | The Fernet-encrypted multi-character token store. |
+| `key` | The Fernet symmetric key (`0o600`). |
+| `writes_disabled` | Present ⇒ writes are globally off (created by `familiar writes disable`). |
+| `audit.log` | One JSON line per executed write action. |
+| `sde.sqlite` | The local Static Data Export (if downloaded; or set `FAMILIAR_SDE_PATH`). |
+
+## Test-only knobs
+
+Tests set `FAMILIAR_DATA_DIR` to a temp dir and `FAMILIAR_ENABLE_WRITES` to exercise the write path in isolation, and inject mock transports via `esi.set_client` / `zkill.set_client` / `sde.set_connection` rather than hitting the network. See **[Development & CI](Development-and-CI)**.