From 25e1867adff0a7a473ad287da3c955ba4f65492d Mon Sep 17 00:00:00 2001
From: nav <nav@mgr.hangman-lab.top>
Date: Wed, 8 Apr 2026 23:32:33 +0000
Subject: [PATCH] docs: flesh out server readme

---
 README.md | 146 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 146 insertions(+)

diff --git a/README.md b/README.md
index e69de29..9be3f84 100644
--- a/README.md
+++ b/README.md
@@ -0,0 +1,146 @@
+# Yonexus.Server
+
+Yonexus.Server is the central hub plugin for a Yonexus network.
+
+It runs on the main OpenClaw instance and is responsible for:
+
+- accepting WebSocket connections from follower instances
+- enforcing the `followerIdentifiers` allowlist
+- driving pairing and authenticated reconnects
+- tracking heartbeat/liveness state
+- rewriting inbound client rule messages before dispatch
+- sending pairing notifications to the human admin via Discord DM
+
+## Status
+
+Current state: **scaffold + core runtime MVP**
+
+Implemented in this repository today:
+
+- config validation
+- runtime lifecycle wiring
+- JSON persistence for durable trust records
+- WebSocket transport and single-active-connection promotion model
+- pairing session creation
+- auth proof validation flow
+- heartbeat receive + liveness sweep
+- rule registry + send-to-client APIs
+- notification service stub/mock for pairing DM flow
+
+Still pending before production use:
+
+- automated Server unit/integration tests
+- real Discord DM transport wiring
+- operator hardening / troubleshooting docs
+- broader lifecycle integration with real OpenClaw plugin hooks
+
+## Install Layout
+
+This repo expects the shared protocol repo to be available at:
+
+```text
+protocol/
+```
+
+In the umbrella repo this is managed as a submodule.
+
+## Configuration
+
+Required config shape:
+
+```json
+{
+  "followerIdentifiers": ["client-a", "client-b"],
+  "notifyBotToken": "<discord-bot-token>",
+  "adminUserId": "123456789012345678",
+  "listenHost": "0.0.0.0",
+  "listenPort": 8787,
+  "publicWsUrl": "wss://example.com/yonexus"
+}
+```
+
+### Field notes
+
+- `followerIdentifiers`: allowlisted client identifiers
+- `notifyBotToken`: bot token used for pairing notifications
+- `adminUserId`: Discord user that receives pairing DMs
+- `listenHost`: optional bind host, defaults to local runtime handling
+- `listenPort`: required WebSocket listen port
+- `publicWsUrl`: optional public endpoint to document/share with clients
+
+## Runtime Overview
+
+Startup flow:
+
+1. validate config
+2. load persisted trust records
+3. ensure allowlisted identifiers have base records
+4. start WebSocket transport
+5. start liveness sweep timer
+
+Connection flow:
+
+1. unauthenticated socket connects
+2. client sends `hello`
+3. server decides `pair_required`, `waiting_pair_confirm`, or `auth_required`
+4. if needed, server creates a pending pairing request and notifies admin out-of-band
+5. client confirms pairing or authenticates with signed proof
+6. authenticated connection is promoted to the active session for that identifier
+
+## Public API Surface
+
+Exported runtime helpers currently include:
+
+```ts
+sendMessageToClient(identifier: string, message: string): Promise<boolean>
+sendRuleMessageToClient(identifier: string, ruleIdentifier: string, content: string): Promise<boolean>
+registerRule(rule: string, processor: (message: string) => unknown): void
+```
+
+Rules:
+
+- `builtin` is reserved and cannot be registered
+- server-side dispatch expects rewritten client-originated messages in the form:
+
+```text
+${rule_identifier}::${sender_identifier}::${message_content}
+```
+
+## Persistence
+
+Durable state is stored as JSON and includes at least:
+
+- identifier
+- pairing status
+- public key
+- secret
+- pairing metadata
+- heartbeat / auth timestamps
+- last known liveness status
+
+Rolling nonce and handshake windows are intentionally rebuilt on restart in v1.
+
+## Development
+
+Install dependencies and run type checks:
+
+```bash
+npm install
+npm run check
+```
+
+## Limitations
+
+Current known limitations:
+
+- pairing DM sending is still a stub/mock abstraction
+- no offline message queueing
+- no multi-server topology
+- no management UI
+- no server-side unit/integration test suite yet
+
+## Related Repos
+
+- Umbrella: `../`
+- Shared protocol: `../Yonexus.Protocol`
+- Client plugin: `../Yonexus.Client`