From 488fc29a896dcad13ba6827b93f6f98c38586cce Mon Sep 17 00:00:00 2001
From: nav <nav@mgr.hangman-lab.top>
Date: Tue, 31 Mar 2026 23:37:59 +0000
Subject: [PATCH] add yonexus dual-plugin readme and manifests

---
 README.md          | 158 +++++++++++++++++++++++++++++++++++++++++++++
 plugin.client.json |  13 ++++
 plugin.server.json |  15 +++++
 3 files changed, 186 insertions(+)
 create mode 100644 README.md
 create mode 100644 plugin.client.json
 create mode 100644 plugin.server.json

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..a5cc5fb
--- /dev/null
+++ b/README.md
@@ -0,0 +1,158 @@
+# Yonexus
+
+Yonexus is a cross-instance communication system for OpenClaw built as **two separate plugins**:
+
+- `Yonexus.Server`
+- `Yonexus.Client`
+
+It is designed for scenarios where one OpenClaw instance acts as a central communication hub and multiple other OpenClaw instances connect to it as clients.
+
+## Overview
+
+### Yonexus.Server
+Installed on the central OpenClaw instance.
+
+Responsibilities:
+- run the WebSocket server
+- maintain the client registry
+- handle pairing and authentication
+- track heartbeat and liveness state
+- relay messages to connected clients
+- rewrite inbound client messages before rule dispatch
+- notify a human administrator of pairing requests via Discord DM
+
+### Yonexus.Client
+Installed on follower OpenClaw instances.
+
+Responsibilities:
+- connect to `Yonexus.Server`
+- manage local keypair and shared secret
+- complete pairing with out-of-band pairing code
+- authenticate on reconnect
+- send periodic heartbeat
+- send messages to server
+- receive messages from server via rule dispatch
+
+---
+
+## Architecture
+
+A Yonexus network contains:
+- exactly one OpenClaw instance running `Yonexus.Server`
+- one or more OpenClaw instances running `Yonexus.Client`
+
+Topology rules:
+- `Yonexus.Server` must be reachable via a stable address
+- `Yonexus.Client` instances connect outbound to the server
+- direct client-to-client sockets are not required in v1
+- client-to-client communication, if needed, is relayed by the server
+
+---
+
+## Security Model
+
+Pairing is intentionally **out-of-band**.
+
+When a new client needs pairing:
+- the server generates a pairing code
+- the server sends that pairing code by Discord DM to a configured human admin
+- the pairing code is **not** sent over the Yonexus WebSocket connection
+- the human relays the code to the client side manually
+- the client submits the code back through the protocol
+
+After pairing:
+- the server issues a shared secret
+- the client stores its private key and secret locally
+- reconnect authentication uses signed proof derived from `secret + nonce + timestamp`
+
+---
+
+## Current Spec Files
+
+This repository currently contains planning/spec-first documents:
+
+- `PLAN.md` — project plan and architecture
+- `PROTOCOL.md` — builtin WebSocket protocol details
+- `FEAT.md` — implementation feature checklist
+
+---
+
+## Planned Plugin Manifests
+
+This repo is expected to define separate plugin manifests for:
+
+- `plugin.server.json`
+- `plugin.client.json`
+
+These represent the initial config surface for `Yonexus.Server` and `Yonexus.Client`.
+
+---
+
+## Planned TypeScript APIs
+
+### Yonexus.Server
+- `sendMessageToClient(identifier: string, message: string)`
+- `registerRule(rule: string, processor: (message: string) => unknown)`
+
+### Yonexus.Client
+- `sendMessageToServer(message: string)`
+- `registerRule(rule: string, processor: (message: string) => unknown)`
+
+Message format:
+
+```text
+${rule_identifier}::${message_content}
+```
+
+Reserved rule:
+
+```text
+builtin
+```
+
+---
+
+## Planned Server Config
+
+```json
+{
+  "followerIdentifiers": ["client-a", "client-b"],
+  "notifyBotToken": "<discord-bot-token>",
+  "adminUserId": "123456789012345678",
+  "listenHost": "0.0.0.0",
+  "listenPort": 8787,
+  "publicWsUrl": "wss://example.com/yonexus"
+}
+```
+
+## Planned Client Config
+
+```json
+{
+  "mainHost": "wss://example.com/yonexus",
+  "identifier": "client-a",
+  "notifyBotToken": "<discord-bot-token>",
+  "adminUserId": "123456789012345678"
+}
+```
+
+---
+
+## Status
+
+Current repository status:
+- planning/specification stage
+- split-plugin architecture defined
+- protocol draft defined
+- implementation not started yet
+
+---
+
+## Next Steps
+
+Recommended next deliverables:
+- plugin manifests
+- source tree scaffolds for server/client
+- protocol model types
+- transport skeleton
+- pairing/auth flow implementation
diff --git a/plugin.client.json b/plugin.client.json
new file mode 100644
index 0000000..3476091
--- /dev/null
+++ b/plugin.client.json
@@ -0,0 +1,13 @@
+{
+  "name": "Yonexus.Client",
+  "version": "0.1.0",
+  "description": "Yonexus client plugin for cross-instance OpenClaw communication",
+  "entry": "dist/client/index.js",
+  "permissions": [],
+  "config": {
+    "mainHost": "",
+    "identifier": "",
+    "notifyBotToken": "",
+    "adminUserId": ""
+  }
+}
diff --git a/plugin.server.json b/plugin.server.json
new file mode 100644
index 0000000..1b87f65
--- /dev/null
+++ b/plugin.server.json
@@ -0,0 +1,15 @@
+{
+  "name": "Yonexus.Server",
+  "version": "0.1.0",
+  "description": "Yonexus central server plugin for cross-instance OpenClaw communication",
+  "entry": "dist/server/index.js",
+  "permissions": [],
+  "config": {
+    "followerIdentifiers": [],
+    "notifyBotToken": "",
+    "adminUserId": "",
+    "listenHost": "0.0.0.0",
+    "listenPort": 8787,
+    "publicWsUrl": ""
+  }
+}