docs: markdown documentation section (sidebar nav, per-page toc, search, hljs)

content/docs/accounts.md

@@ -0,0 +1,50 @@
+# Accounts & SASL
+
+Registering a nickname creates an account you can protect, use to found channels, and log in with
+via SASL.
+
+## Register
+
+Message **NickServ** to register your current nick, then identify:
+
+```text
+/msg NickServ REGISTER <password> <email>
+/msg NickServ IDENTIFY <password>
+```
+
+## SASL mechanisms
+
+SASL logs you in *during* connection, before you join anything. echoIRCd advertises:
+
+| Mechanism | How it works |
+| --- | --- |
+| `PLAIN` | account + password |
+| `EXTERNAL` | your TLS client-certificate fingerprint |
+| `SCRAM-SHA-256` | salted challenge / response — no password on the wire |
+| `ECDSA-NIST256P-CHALLENGE` | sign a challenge with a NIST P-256 key |
+
+## SASL EXTERNAL (client certificate)
+
+Add your certificate fingerprint to your account, then select **EXTERNAL** in your client:
+
+```text
+/msg NickServ CERT ADD
+```
+
+## Key-based login (ECDSA)
+
+Generate a NIST P-256 key and register its public half. At login the server sends a random
+challenge, your client signs it, and the signature is verified against the stored key — nothing
+secret crosses the wire.
+
+```sh
+ecdsatool keygen ~/.ecdsa.pem
+ecdsatool pubkey ~/.ecdsa.pem
+```
+
+```text
+/msg NickServ SET PUBKEY <printed-public-key>
+```
+
+Then point your client's SASL settings at the key file and choose the
+`ECDSA-NIST256P-CHALLENGE` mechanism. See `/msg NickServ HELP SET PUBKEY` for more.

content/docs/configuration.md

@@ -0,0 +1,62 @@
+# Configuration
+
+echoIRCd is configured from a single file (`echoircd.conf` by default). The format is a set of
+**blocks** made of `key value;` fields.
+
+> Inline `#` comments are **not** stripped from a value — keep active lines to bare values and put
+> comments on their own line.
+
+## Format
+
+```ini
+network "echoiRCd";
+sid     "0AA";
+
+listen { ip "[::]"; port 6697; tls yes; }   # dual-stack v4 + v6
+```
+
+## Listeners
+
+Each `listen` block opens one port. `tls yes` makes it a direct-TLS port, `wss yes` a
+WebSocket-over-TLS port, and `type server` a server-to-server port.
+
+```ini
+listen { ip "[::]"; port 6667; }              # plaintext clients
+listen { ip "[::]"; port 6697; tls yes; }     # direct-TLS clients
+listen { ip "[::]"; port 7799; wss yes; }     # WebSocket (wss)
+listen { ip "[::]"; port 7700; type server; } # server links
+```
+
+## TLS
+
+Point the `tls` block at a certificate and private key. Both the OpenSSL and rustls backends are
+available, and certificates are re-read on rehash. Per-host certificates can be supplied with
+repeatable `sni` entries.
+
+```ini
+tls {
+    cert    "/etc/echoircd/tls/cert.pem";
+    key     "/etc/echoircd/tls/key.pem";
+    backend openssl;                          # or: rustls
+    sni     "irc.example.net ./tls/example.crt ./tls/example.key";
+}
+```
+
+## Cloaking
+
+Set a secret `cloak` key to enable host masking:
+
+```ini
+cloak { key "a-long-random-secret"; }
+```
+
+## Applying changes
+
+Validate, then rehash the running server — no restart required:
+
+```sh
+echoircd checkconfig echoircd.conf
+echoircd rehash echoircd.conf         # sends SIGHUP
+```
+
+See the shipped `echoircd.conf.example` for every available option.

content/docs/connecting.md

@@ -0,0 +1,36 @@
+# Connecting
+
+Point any IRC client at the network, or use the browser.
+
+## Network details
+
+| Setting | Value |
+| --- | --- |
+| Server | `irc.echoircd.org` |
+| TLS (recommended) | `6697` |
+| Plaintext | `6667` |
+| Network | echoiRCd |
+
+## One-line connect
+
+Most clients accept a single server string; a leading `+` marks the port as TLS.
+
+```text
+/server irc.echoircd.org +6697
+/join #echoircd
+```
+
+## Popular clients
+
+| Client | Command |
+| --- | --- |
+| HexChat | add `irc.echoircd.org/+6697`, tick “Use SSL” |
+| WeeChat | `/server add echo irc.echoircd.org/6697 -tls` |
+| irssi | `/connect -tls irc.echoircd.org 6697` |
+| mIRC | `/server irc.echoircd.org +6697` |
+
+## In the browser
+
+A web client is available at <https://orbit.devtronic.pro>.
+
+Once connected, [register your nick](/docs/accounts) to keep it and to log in with SASL.

content/docs/installation.md

@@ -0,0 +1,50 @@
+# Installation
+
+echoIRCd builds with a recent stable Rust toolchain and has no C dependencies of its own beyond an
+SSL library when using the OpenSSL TLS backend.
+
+## Requirements
+
+- Rust **1.85** or newer (`rustup` recommended).
+- For the OpenSSL backend: `libssl-dev` / `openssl` and `pkg-config`. The `rustls` backend needs
+  neither.
+
+## Build from source
+
+```sh
+git clone https://git.devtronic.pro/echo/echoIRCd
+cd echoIRCd
+cargo build --release
+```
+
+The server binary is written to `target/release/echoircd`.
+
+## Configure and run
+
+Copy the shipped example configuration, edit it, and start the server:
+
+```sh
+cp echoircd.conf.example echoircd.conf
+$EDITOR echoircd.conf
+./target/release/echoircd echoircd.conf
+```
+
+Validate a configuration without starting the server:
+
+```sh
+./target/release/echoircd checkconfig echoircd.conf
+```
+
+## TLS certificates
+
+Point the `tls` block at a certificate and key (for example, from Let's Encrypt). See
+[Configuration](/docs/configuration#tls) for the details.
+
+## Running as a service
+
+Run `echoircd` under your init system of choice. A `SIGHUP` triggers a live configuration
+rehash — including a certificate reload — with no restart and no disconnects:
+
+```sh
+./target/release/echoircd rehash echoircd.conf
+```

content/docs/introduction.md

@@ -0,0 +1,25 @@
+# Introduction
+
+**echoIRCd** is a modern IRC daemon and a full services suite, written from scratch in Rust. It is
+original code — not a fork of another ircd — and the entire tree compiles with
+`#![forbid(unsafe_code)]`.
+
+## What you get
+
+- **echoIRCd** — the server: a single-threaded core with an epoll reactor pool, the full channel
+  and user mode set, host cloaking, connection classes, and an operator privilege model.
+- **echo services** — NickServ, ChanServ, OperServ, MemoServ and more, linked over a standard
+  server-to-server protocol and backed by an event-sourced store.
+
+## Highlights
+
+- Full **IRCv3**, including `chathistory`, `labeled-response`, `multiline` and more.
+- Modern **TLS 1.3** (OpenSSL and rustls backends) with post-quantum `X25519MLKEM768`.
+- **SASL**: `PLAIN`, `EXTERNAL`, `SCRAM-SHA-256`, and `ECDSA-NIST256P-CHALLENGE`.
+- A native **anti-abuse** engine built into the core.
+
+> New here? Start with [Installation](/docs/installation), then [Connecting](/docs/connecting).
+
+## The public network
+
+A live network runs at **irc.echoircd.org** — see [Connecting](/docs/connecting) to join.

content/docs/ircv3.md

@@ -0,0 +1,28 @@
+# IRCv3 capabilities
+
+echoIRCd implements a broad set of IRCv3 capabilities. Clients negotiate them with `CAP LS` and
+`CAP REQ`.
+
+## Advertised capabilities
+
+```text
+server-time        message-tags          account-tag          account-notify
+extended-join      chghost               multi-prefix         away-notify
+invite-notify      setname               echo-message         userhost-in-names
+batch              labeled-response      standard-replies     extended-monitor
+draft/chathistory  draft/event-playback  draft/message-redaction
+draft/multiline    draft/metadata-2      draft/read-marker    draft/webpush
+draft/account-registration               sts
+```
+
+## Notable features
+
+- **CHATHISTORY** — replay recent conversation, with server-side storage.
+- **labeled-response** + **batch** — correlate replies to the command that caused them.
+- **multiline** — send a message that spans lines as a single logical message.
+- **STS** — advertise a strict-transport-security policy so clients upgrade to TLS.
+- **draft/webpush** — RFC 8291 / 8292 Web Push notifications for supporting clients.
+
+## SASL
+
+SASL is a capability too — see [Accounts & SASL](/docs/accounts) for the supported mechanisms.

content/docs/linking.md

@@ -0,0 +1,45 @@
+# Server links
+
+echoIRCd links to other servers — and to echo services — over a standard server-to-server
+protocol, wire-compatible with the InspIRCd 1206 protocol.
+
+## Server identity
+
+Every server needs a unique **SID** (three characters, the first a digit) and a name.
+
+```ini
+network "echoiRCd";
+sid     "0AA";
+```
+
+## A link block
+
+Each `link` block describes a peer: its name, address, port, and the passwords used to
+authenticate the connection in each direction.
+
+```ini
+listen { ip "[::]"; port 7700; type server; }
+
+link {
+    name         "hub.example.net";
+    ip           "203.0.113.10";
+    port         7700;
+    sendpassword "outbound-secret";
+    recvpassword "inbound-secret";
+}
+```
+
+> Treat link passwords as secrets, and restrict the server port to trusted peers.
+
+## Services
+
+echo services connect as a special linked server. In the ircd, mark the services server name as a
+**U-lined** server (and as the SASL server) so its privileged commands and SASL relay are
+accepted:
+
+```ini
+uline { server "services.echoircd.org"; }
+sasl_server "services.echoircd.org";
+```
+
+See [Services](/docs/services) for the services side of the link.

content/docs/operators.md

@@ -0,0 +1,55 @@
+# Operators
+
+Server operators are defined by `oper` blocks and typed by `opertype` blocks. An oper's power is
+the sum of three allow-lists: the **commands** they may run, the named **privileges** they hold,
+and the user/channel **modes** they may set.
+
+## Oper types
+
+An `opertype` groups a set of powers so many opers can share one role.
+
+```ini
+opertype {
+    name      "netadmin";
+    commands  "*";                 # every oper command
+    privs     "*";                 # every named privilege
+    usermodes "*";
+    chanmodes "*";
+}
+
+opertype {
+    name      "helper";
+    commands  "KILL SANICK";
+    privs     "users/auspex channels/auspex";
+    usermodes "-*";                # no privileged usermodes
+    chanmodes "b";
+}
+```
+
+Lists are space-separated tokens. `*` grants everything; a `-` prefix denies a specific token —
+for example `* -KILL` means "everything except `KILL`".
+
+## Oper accounts
+
+An `oper` block ties a login to an `opertype`. Hash the password with the `mkpasswd` helper.
+
+```ini
+oper {
+    name     "alice";
+    password "$argon2id$...";       # from: echoircd mkpasswd
+    type     "netadmin";
+    host     "*@192.0.2.0/24";
+}
+```
+
+Then, as a client:
+
+```text
+/oper alice hunter2
+```
+
+## Privileges
+
+Named privileges gate individual abilities — for example `users/auspex` (see hidden user
+details), `channels/auspex`, `servers/rehash`, or `users/mass-message`. Assign them per
+`opertype` through `privs`, and the daemon enforces them everywhere the ability is used.

content/docs/services.md

@@ -0,0 +1,30 @@
+# Services
+
+echo services is a suite of pseudo-clients that runs as its own program and links to the network
+as a services server. State is **event-sourced** — every change is an appended event, replayed to
+rebuild the database.
+
+## The services
+
+| Service | Purpose |
+| --- | --- |
+| **NickServ** | account registration, grouped nicks, certificates, public keys, vhosts, profiles |
+| **ChanServ** | channel founders and access, auto-op, akick, topic and mode locks |
+| **OperServ** | network administration, akills, session control |
+| **MemoServ** | offline messages between accounts |
+
+## Running
+
+echo services is configured from its own file and connects to the ircd over the server port:
+
+```sh
+echo config.toml
+```
+
+On the ircd side, the services server must be U-lined and named as the SASL server — see
+[Server links](/docs/linking#services).
+
+## Accounts & SASL
+
+Registration and login are covered in [Accounts & SASL](/docs/accounts). SASL is relayed from the
+daemon to services mechanism-agnostically, so new mechanisms work without daemon changes.