-**PyVNCServer 3.2.1** · Python 3.11+ · RFB 3.8
+**PyVNCServer 3.2.1** · Python 3.11+ · RFB 3.8 · [Documentation](https://xulek.github.io/PyVNCServer/)
diff --git a/docs/api.md b/docs/api.md
new file mode 100644
index 0000000..90a0b1d
--- /dev/null
+++ b/docs/api.md
@@ -0,0 +1,73 @@
+# CLI & Python API
+
+## Command line
+
+The installed entry point is:
+
+```text
+pyvncserver
+```
+
+### Start the server
+
+```bash
+pyvncserver serve
+```
+
+### Custom configuration
+
+```bash
+pyvncserver serve --config path/to/config.toml
+```
+
+### Log level override
+
+```bash
+pyvncserver serve --log-level DEBUG
+```
+
+Accepted log-level values are handled by the server logging configuration; typical values are `DEBUG`, `INFO`, `WARNING`, `ERROR` and `CRITICAL`.
+
+Running without an explicit subcommand defaults to `serve`.
+
+## Public Python package surface
+
+The top-level package currently exports:
+
+```python
+from pyvncserver import (
+ __version__,
+ DEFAULT_CONFIG_PATH,
+ ServerSettings,
+ VNCServer,
+ VNCServerV3,
+ load_config_file,
+)
+```
+
+### Load and validate configuration
+
+```python
+from pyvncserver import ServerSettings
+
+settings = ServerSettings.from_file("config/pyvncserver.toml")
+print(settings.host, settings.port)
+```
+
+`ServerSettings` is immutable (`frozen`) and validates core/security values before use.
+
+### Flat compatibility mapping
+
+```python
+from pyvncserver import load_config_file
+
+config = load_config_file("config/pyvncserver.toml")
+print(config["host"])
+print(config["websocket_max_message_bytes"])
+```
+
+The loader flattens TOML sections into the mapping expected by the existing runtime while preserving typed validation through `ServerSettings`.
+
+## Stability note
+
+`pyvncserver` is the public package surface. `vnc_lib` remains an internal/compatibility implementation layer; new integrations should prefer imports from `pyvncserver` where an equivalent public symbol exists.
diff --git a/docs/architecture.md b/docs/architecture.md
new file mode 100644
index 0000000..4ba3ea5
--- /dev/null
+++ b/docs/architecture.md
@@ -0,0 +1,70 @@
+# Architecture
+
+PyVNCServer separates listener/session orchestration from reusable protocol, capture, runtime and encoding components while retaining `vnc_lib` as a compatibility implementation layer.
+
+## Runtime flow
+
+```mermaid
+sequenceDiagram
+ participant C as VNC client
+ participant S as VNCServer
+ participant P as RFB protocol
+ participant CP as CaptureProducer
+ participant E as Encoding pipeline
+
+ C->>S: TCP / WebSocket connection
+ S->>P: RFB version + security negotiation
+ C->>P: ClientInit / SetPixelFormat / SetEncodings
+ C->>S: FramebufferUpdateRequest
+ CP-->>S: latest framebuffer generation
+ S->>E: changed regions + client capabilities
+ E-->>S: encoded rectangles
+ S-->>C: FramebufferUpdate
+```
+
+## Main package layout
+
+```text
+src/pyvncserver/
+├── app/server.py listener, admission, authentication, lifecycle
+├── session/ per-client state and message/update loop
+├── platform/ capture producer and platform integration facade
+├── runtime/ limits, registry, network/runtime helpers
+├── rfb/ public RFB protocol facade
+├── observability/ logging, metrics and profiling facade
+├── config.py typed TOML loading and fail-closed validation
+├── default_config.toml packaged safe defaults
+└── cli.py pyvncserver command
+
+src/vnc_lib/ protocol/encoder compatibility implementation layer
+```
+
+## Capture model
+
+With `enable_capture_producer = true`, one server-wide producer captures the desktop and publishes monotonically newer framebuffer generations. Client sessions consume the newest appropriate generation instead of independently serializing capture calls.
+
+Benefits:
+
+- capture work does not scale linearly with client count;
+- slow clients do not force every other client to capture at their pace;
+- changed-region history can be associated with produced frames.
+
+## Session state
+
+Per-client state includes negotiated pixel format, client-advertised encodings, framebuffer request state, input-control state and encoder/session-specific state. Keeping this scoped to the connection prevents one viewer's negotiation from mutating another viewer's protocol state.
+
+## Encoding pipeline
+
+The framebuffer path can:
+
+1. obtain the latest frame;
+2. determine whether the request is full or incremental;
+3. collect or detect changed regions;
+4. split large/problematic regions where required;
+5. choose only from negotiated encodings;
+6. encode regions, optionally in parallel;
+7. send one RFB FramebufferUpdate containing consistent rectangle headers/payloads.
+
+## Compatibility layer
+
+`src/vnc_lib/` remains in the repository because existing implementation and import paths still depend on it. Public package exports are provided through `pyvncserver`; future refactors can move implementation behind those public modules without forcing downstream callers to follow every internal reorganization.
diff --git a/docs/assets/images/logo.svg b/docs/assets/images/logo.svg
new file mode 100644
index 0000000..f3a8ce0
--- /dev/null
+++ b/docs/assets/images/logo.svg
@@ -0,0 +1,13 @@
+
+
+
RFB 3.8 · Python 3.11+ · UltraVNC · noVNC
+
+# Remote framebuffer, under your control.
+
+
PyVNCServer is a modern VNC/RFB server written in Python, built for protocol correctness, practical client interoperability, low-latency desktop capture and an implementation you can actually inspect and extend.
+
+
+
+
+ RFB 3.8
+ UltraVNC tested
+ Tight · ZRLE · Hextile · Zlib
+ WebSocket / noVNC
+ Safe defaults
+
+
+
+
+
+⚡
+### Low-latency pipeline
+Shared capture production, incremental region detection, request coalescing and adaptive encoding keep avoidable work off the hot path.
+
+
+
+🧩
+### Real RFB encodings
+Raw, CopyRect, RRE, Hextile, Zlib, Tight and ZRLE are available, with optional JPEG and H.264 extension paths.
+
+
+
+🖥️
+### UltraVNC interoperability
+The server contains targeted fixes for Tight stream state and RRE fallback behavior discovered during UltraVNC compatibility testing.
+
+
+
+🌐
+### Browser transport
+Binary WebSocket transport supports noVNC-style browser connections with Origin allowlisting and bounded frame/message sizes.
+
+
+
+🔒
+### Security-conscious defaults
+Loopback binding, fail-closed configuration validation, TLS support, authentication throttling and connection admission limits are built in.
+
+
+
+🔬
+### Inspectable by design
+The protocol, capture, session, encoding and transport layers are Python code rather than a black-box native server.
+
+
+
+