add project structure document

STRUCTURE.md

@@ -0,0 +1,140 @@
+# Yonexus.Server — 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.Server`, this includes:
+- client registry
+- pairing state machine
+- secret issuance
+- authentication verification
+- nonce/replay protection
+- heartbeat/liveness tracking
+- message rewrite and dispatch
+
+### `plugin/hooks/`
+Hook handlers triggered by OpenClaw lifecycle or special events.
+
+For `Yonexus.Server`, expected hooks include:
+- gateway startup hook to initialize server runtime
+- shutdown/cleanup hook if needed
+
+### `plugin/commands/`
+Slash commands exposed by the plugin.
+
+Planned examples for `Yonexus.Server`:
+- inspect client status
+- force re-pair a client
+- list online/offline clients
+- rotate/revoke client trust
+
+### `plugin/tools/`
+Plugin-provided tools callable from the runtime.
+
+Planned examples for `Yonexus.Server`:
+- send message to client
+- query client registry
+- inspect pairing/auth status
+
+### `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.Server`, this should eventually describe:
+- plugin name
+- version
+- entrypoint
+- config schema
+- required permissions if any
+
+### `skills/`
+Skills provided by the plugin.
+
+Potential future contents:
+- operational help for Yonexus.Server
+- admin workflows for pairing/recovery
+- troubleshooting guidance
+
+### `servers/`
+Long-running services started by the plugin.
+
+For `Yonexus.Server`, this is where the WebSocket server implementation belongs.
+
+Expected contents later:
+- WebSocket server bootstrap
+- connection/session manager
+- protocol transport handling
+
+### `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.Server` 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`.
+- Services should stay out of `plugin/core/` if they are process/service bootstraps; put those in `servers/` and let `core/` contain reusable logic.