From f0a5336cc7638d983cc6a3326eecedb91111c399 Mon Sep 17 00:00:00 2001
From: nav <nav@mgr.hangman-lab.top>
Date: Wed, 1 Apr 2026 01:36:05 +0000
Subject: [PATCH] add project structure document

---
 STRUCTURE.md | 142 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 142 insertions(+)
 create mode 100644 STRUCTURE.md

diff --git a/STRUCTURE.md b/STRUCTURE.md
new file mode 100644
index 0000000..561c8de
--- /dev/null
+++ b/STRUCTURE.md
@@ -0,0 +1,142 @@
+# Yonexus.Client — Project Structure
+
+This repository follows the standard OpenClaw plugin project layout.
+
+## Required Layout
+
+```text
+${proj}/plugin/
+${proj}/plugin/core/
+${proj}/plugin/hooks/
+${proj}/plugin/commands/
+${proj}/plugin/tools/
+${proj}/plugin/index.ts
+${proj}/plugin/openclaw.plugin.json
+${proj}/skills/
+${proj}/servers/
+${proj}/scripts/
+${proj}/scripts/install.mjs
+```
+
+Where:
+- `D` = directory
+- `F` = file
+
+Equivalent expanded tree:
+
+```text
+.
+├── plugin/
+│   ├── core/
+│   ├── hooks/
+│   ├── commands/
+│   ├── tools/
+│   ├── index.ts
+│   └── openclaw.plugin.json
+├── skills/
+├── servers/
+├── scripts/
+│   └── install.mjs
+├── protocol/   # git submodule -> Yonexus.Protocol
+└── PLAN.md
+```
+
+## Responsibility Mapping
+
+### `plugin/core/`
+Core plugin logic lives here.
+
+For `Yonexus.Client`, this includes:
+- local identity state
+- keypair generation
+- secret persistence
+- auth proof construction/signing
+- heartbeat scheduling
+- inbound message dispatch
+- reconnect state machine
+
+### `plugin/hooks/`
+Hook handlers triggered by OpenClaw lifecycle or special events.
+
+For `Yonexus.Client`, expected hooks include:
+- gateway startup hook to initialize client runtime
+- reconnect/startup orchestration hook if needed
+
+### `plugin/commands/`
+Slash commands exposed by the plugin.
+
+Planned examples for `Yonexus.Client`:
+- show current connection status
+- show pairing state
+- trigger reconnect
+- clear local trust and re-pair
+
+### `plugin/tools/`
+Plugin-provided tools callable from the runtime.
+
+Planned examples for `Yonexus.Client`:
+- send message to server
+- inspect local auth/pairing state
+
+### `plugin/index.ts`
+Must only do wiring.
+
+It should:
+- initialize plugin entrypoint
+- register hooks
+- register commands
+- register tools
+- compose core modules
+
+It should **not** contain business logic directly.
+
+### `plugin/openclaw.plugin.json`
+Plugin manifest and config entrypoint.
+
+For `Yonexus.Client`, this should eventually describe:
+- plugin name
+- version
+- entrypoint
+- config schema
+- required permissions if any
+
+### `skills/`
+Skills provided by the plugin.
+
+Potential future contents:
+- client recovery flow
+- pairing troubleshooting guidance
+- operator guidance for reconnect/auth issues
+
+### `servers/`
+Long-running services started by the plugin.
+
+For `Yonexus.Client`, this may stay small or even nearly empty in early versions.
+
+Possible later contents:
+- local helper process
+- background runtime wrappers if needed
+
+Important note:
+- unlike `Yonexus.Server`, the client does not primarily exist to expose a network service
+- but the directory should still exist for consistency with the standard project structure
+
+### `scripts/install.mjs`
+Install/uninstall/deployment helper script.
+
+Expected responsibilities:
+- install built plugin into OpenClaw plugin directory
+- support uninstall
+- support explicit OpenClaw profile path
+
+## Design Rule
+
+This repo should follow the `Dirigent` style of plugin organization, with one intentional difference:
+- `Yonexus.Client` uses `servers/`
+- it does **not** use a root-level special folder like `no-reply-api/`
+
+## Notes
+
+- Shared protocol specification must live in `protocol/` submodule, not duplicated locally.
+- Business logic should stay out of `plugin/index.ts`.
+- Even if `servers/` is light in early versions, keep the directory to preserve a consistent project template across Yonexus repos.