add Yonexus.Protocol submodule and update architecture docs

README.md

@@ -1,11 +1,13 @@
 # Yonexus
 
-Yonexus is a cross-instance communication system for OpenClaw built as **two separate plugins**:
+Yonexus is a cross-instance communication system for OpenClaw built as **three separate repositories**:
 
-- `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.
+| Repository | Role |
+|---|---|
+| `Yonexus` | Umbrella — architecture, planning, and coordination |
+| `Yonexus.Server` | Central hub plugin — accepts client connections, handles pairing/authentication |
+| `Yonexus.Client` | Client plugin — connects to server, manages local identity |
+| `Yonexus.Protocol` | Shared protocol specification — referenced as a submodule by both Server and Client |
 
 ## Overview
 
@@ -33,6 +35,22 @@ Responsibilities:
 - send messages to server
 - receive messages from server via rule dispatch
 
+### Yonexus.Protocol
+Shared protocol specification repository. Both `Yonexus.Server` and `Yonexus.Client` reference this as a submodule at `protocol/`.
+
+---
+
+## Repository Structure
+
+```
+Yonexus (umbrella)
+├── Yonexus.Protocol  ← shared protocol submodule
+├── Yonexus.Server    ← server plugin submodule
+│   └── protocol/     ← points to Yonexus.Protocol
+└── Yonexus.Client    ← client plugin submodule
+    └── protocol/     ← points to Yonexus.Protocol
+```
+
 ---
 
 ## Architecture
@@ -67,48 +85,46 @@ After pairing:
 
 ---
 
-## Current Spec Files
-
-This repository currently contains planning/spec-first documents:
+## Current Repository Spec Files
 
+### Umbrella (`Yonexus`)
 - `PLAN.md` — project plan and architecture
-- `PROTOCOL.md` — builtin WebSocket protocol details
+- `ARCHITECTURE.md` — architecture overview and repository graph
 - `FEAT.md` — implementation feature checklist
 
----
+### Protocol (`Yonexus.Protocol`)
+- `PROTOCOL.md` — shared communication protocol specification
 
-## Planned Plugin Manifests
+### Server (`Yonexus.Server`)
+- `PLAN.md` — server-specific implementation plan
+- `protocol/` — submodule pointing to `Yonexus.Protocol`
 
-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`.
+### Client (`Yonexus.Client`)
+- `PLAN.md` — client-specific implementation plan
+- `protocol/` — submodule pointing to `Yonexus.Protocol`
 
 ---
 
 ## Planned TypeScript APIs
 
 ### Yonexus.Server
-- `sendMessageToClient(identifier: string, message: string)`
-- `registerRule(rule: string, processor: (message: string) => unknown)`
+```ts
+sendMessageToClient(identifier: string, message: string): Promise<void>
+registerRule(rule: string, processor: (message: string) => unknown): void
+```
 
 ### Yonexus.Client
-- `sendMessageToServer(message: string)`
-- `registerRule(rule: string, processor: (message: string) => unknown)`
+```ts
+sendMessageToServer(message: string): Promise<void>
+registerRule(rule: string, processor: (message: string) => unknown): void
+```
 
 Message format:
-
 ```text
 ${rule_identifier}::${message_content}
 ```
 
-Reserved rule:
-
-```text
-builtin
-```
+Reserved rule: `builtin`
 
 ---
 
@@ -140,19 +156,16 @@ builtin
 
 ## Status
 
-Current repository status:
 - planning/specification stage
 - split-plugin architecture defined
-- protocol draft defined
+- protocol draft defined in `Yonexus.Protocol`
 - implementation not started yet
 
 ---
 
-## Next Steps
+## Repository URLs
 
-Recommended next deliverables:
-- plugin manifests
-- source tree scaffolds for server/client
-- protocol model types
-- transport skeleton
-- pairing/auth flow implementation
+- [Yonexus (umbrella)](https://git.hangman-lab.top/nav/Yonexus)
+- [Yonexus.Server](https://git.hangman-lab.top/nav/Yonexus.Server)
+- [Yonexus.Client](https://git.hangman-lab.top/nav/Yonexus.Client)
+- [Yonexus.Protocol](https://git.hangman-lab.top/nav/Yonexus.Protocol)