docs: add comprehensive project wiki for v1.0

Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>

droid-wiki/systems/framing-protocol.md

@@ -0,0 +1,50 @@
+# Framing protocol
+
+The framing protocol in `src/framing.rs` defines the binary message format used after the HTTP auth handshake upgrades the connection to a persistent tunnel.
+
+## Purpose
+
+Carry multiple bidirectional streams over a single TLS connection with minimal overhead.
+
+## Frame format
+
+All multi-byte integers are big-endian.
+
+```
++--------+----------+----------+-------+-----------+
+| Type   | StreamID | Len      | Flags | Payload.. |
+| 1 byte | 8 bytes  | 4 bytes  | 1 byte| variable  |
++--------+----------+----------+-------+-----------+
+```
+
+- **Type** — 0x01 CONNECT, 0x02 CONNECT_REPLY, 0x03 DATA, 0x04 CLOSE, 0x05 ERROR
+- **StreamID** — odd IDs for client-initiated streams, even reserved for server-initiated
+- **Len** — payload length, max 4 MiB
+- **Flags** — reserved for future use (currently always 0x00)
+
+## Key abstractions
+
+| Type | File | Description |
+| ---- | ---- | ----------- |
+| `Frame` | `src/framing.rs` | Struct holding frame_type, stream_id, flags, payload |
+| `FrameReader` | `src/framing.rs` | Async reader with buffering that handles partial TCP reads |
+| `FrameWriter` | `src/framing.rs` | Async writer that serializes and flushes frames |
+| `encode_target` | `src/framing.rs` | Encode a `Socks5Target` into CONNECT frame payload |
+| `decode_target` | `src/framing.rs` | Decode a `Socks5Target` from CONNECT frame payload |
+
+## Partial read discipline
+
+`FrameReader::read_frame` loops until a complete frame is available:
+
+1. Attempt to deserialize from the buffer.
+2. If the frame is incomplete (`FrameTooShort`), read more bytes from the underlying TCP stream into the buffer.
+3. If the connection closes with a partial frame in the buffer, return an error.
+4. Only consume bytes from the buffer once the full frame is present.
+
+This prevents header corruption when TCP segments arrive in arbitrary sizes.
+
+## Key source files
+
+| File | Purpose |
+| ---- | ------- |
+| `src/framing.rs` | Frame format, serialization, async reader/writer, target encoding |