1 files changed, 103 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..ac1d12b
--- /dev/null
+++ b/README.md
@@ -0,0 +1,103 @@
+# Aegis
+
+Aegis is a desktop Usenet reader written in Go with Fyne. It connects to an
+NNTP server directly or through SOCKS5, supports implicit TLS, optional
+`AUTHINFO USER/PASS` authentication, group discovery, local subscriptions,
+overview search, article retrieval, and text article posting.
+
+## Group population
+
+Before subscribing, Aegis displays an estimated post count for every group
+returned by `LIST ACTIVE`. The estimate is `high - low + 1`. NNTP article
+numbers can contain gaps, so this is an upper-bound style estimate rather than
+a guaranteed count. After selecting a group, the server's `GROUP` response is
+used for the current article count.
+
+## Build and test
+
+```sh
+gofmt -w .
+go test ./...
+go test -race ./...
+go vet -buildvcs=false ./...
+go build -buildvcs=false -o aegis .
+```
+
+The `-buildvcs=false` option is useful when the source directory is not a Git
+working tree.
+
+## Configuration and credentials
+
+Settings are stored in the user configuration directory as
+`aegis/config.json` with mode `0600`. The NNTP password is never written to
+that file and remains only in memory for the current application run.
+
+TLS certificate validation is enabled by default. The Settings screen has an
+explicit `Do not verify the TLS certificate` opt-in for local testing or a
+pinned/trusted connection that cannot present a verifiable certificate. It can
+expose account credentials and article traffic to a man-in-the-middle and
+should not be enabled on an untrusted network.
+
+## Identity and message cryptography
+
+The posting profile is VFace-compatible but optional for publishing. Its
+username, email address, and canonical Ed25519 public key are joined as
+`username|email|public-key`. That exact string produces the 48x48 transparent
+PNG identicon through the existing Ch1ffr3punk `identicon-cli` executable.
+Aegis accepts no uploaded or alternate profile image and no image format other
+than the validated PNG. It publishes the SHA-256 identity hash, the SHA-256
+hash of the PNG, and the verification link
+`https://identicons.virebent.art` together with `Face:` and the interoperable
+`X-Ed25519-Pub` header. Aegis looks first at
+`/home/gabriel1/Projects/identicons/identicons-cli`, then at the configured
+`AEGIS_IDENTICON_CLI` path and other standard locations. The executable must
+return a 48x48 PNG as base64. Aegis does not embed the identicon GUI.
+
+Age is the software encryption format. OpenPGP is not exposed as a standalone
+software format: it is reserved for the YubiKey OpenPGP integration. The
+optional VFace profile generates an Ed25519 identity and stores it in an
+age-encrypted local vault protected by a user password of at least 12
+characters.
+
+The composer keeps the classic Usenet path as the default. It sends RFC 5322
+and MIME-compatible text articles directly to NNTP, with UTF-8 `8bit` text,
+canonical CRLF line endings, and a generated `Message-ID`. Optional composer
+modes can sign the canonical body with an Ed25519 key, encrypt the body with
+age (native X25519 or SSH Ed25519/RSA recipients), or do both. These modes add
+`X-Aegis-*` metadata,
+including the inline verification key, its SHA-256 fingerprint, and an
+optional HTTPS key URL. The URL is metadata only and is never fetched
+automatically.
+
+Ed25519 is used for signatures, not encryption. The age recipient must be an
+encryption key, and private keys are supplied for the current operation only.
+The optional SURB integration remains a separate future task and is not part
+of classic Usenet posting.
+
+TLS connections require TLS 1.2 or 1.3. For TLS 1.2, Aegis offers only
+ECDHE-AES-GCM suites. Go does not expose TLS 1.3 cipher-suite selection, so a
+TLS 1.3 connection can still negotiate the platform's ChaCha20-Poly1305
+suite. Deployments that require GCM exclusively must cap the NNTP server at
+TLS 1.2.
+
+## Current limits
+
+- implicit TLS and STARTTLS are supported; COMPRESS DEFLATE is deliberately
+  rejected whenever TLS is enabled and is available only for cleartext NNTP;
+- SOCKS5 username/password authentication is not exposed in the interface;
+- at most the latest 500 overview records are loaded per group;
+- posting creates MIME 1.0 text articles with UTF-8 and `8bit` by default;
+  attachment file selection remains pending; article lines are validated at a maximum of 998
+  octets and sent with canonical CRLF line endings;
+- composer supports age and optional VFace Ed25519 signing; OpenPGP remains
+  reserved for the YubiKey integration;
+- SMTP mail2news delivery supports cleartext, implicit TLS or STARTTLS. It
+  reuses the single NNTP proxy configuration, and SOCKS5 routing is required
+  for `.onion` hosts; the SMTP password is session-only;
+- subscriptions are local Aegis preferences, because NNTP itself has no
+  standard server-side subscription command.
+
+The complete-client audit and prioritized roadmap are in
+[`docs/client-feature-audit.md`](docs/client-feature-audit.md). Optional
+features remain part of the main Aegis binary for now, without a runtime
+plugin directory.