# 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.