diff --git a/SCAFFOLD.md b/SCAFFOLD.md
new file mode 100644
index 0000000..d1c6ecb
--- /dev/null
+++ b/SCAFFOLD.md
@@ -0,0 +1,249 @@
+# Yonexus.Server — Scaffold Plan
+
+This document refines the repository structure into concrete planned files and responsibilities.
+
+## 1. Planned Tree
+
+```text
+.
+├── plugin/
+│   ├── core/
+│   │   ├── registry.ts
+│   │   ├── pairing.ts
+│   │   ├── auth.ts
+│   │   ├── heartbeat.ts
+│   │   ├── dispatch.ts
+│   │   └── errors.ts
+│   ├── hooks/
+│   │   ├── onGatewayStart.ts
+│   │   └── onGatewayStop.ts
+│   ├── commands/
+│   │   ├── listClients.ts
+│   │   ├── showClient.ts
+│   │   └── rePairClient.ts
+│   ├── tools/
+│   │   ├── sendMessageToClient.ts
+│   │   ├── listClientStatus.ts
+│   │   └── getPairingState.ts
+│   ├── index.ts
+│   └── openclaw.plugin.json
+├── skills/
+│   └── ...
+├── servers/
+│   ├── wsServer.ts
+│   └── sessionManager.ts
+├── scripts/
+│   └── install.mjs
+├── protocol/
+│   └── ... (submodule)
+├── PLAN.md
+├── STRUCTURE.md
+└── SCAFFOLD.md
+```
+
+This is a planning scaffold, not yet an implementation commitment down to exact filenames. Names may evolve, but responsibilities should remain stable.
+
+---
+
+## 2. `plugin/index.ts`
+
+`plugin/index.ts` is wiring only.
+
+Planned responsibilities:
+- import server core modules
+- import hooks
+- import commands
+- import tools
+- initialize server runtime container
+- register hooks with OpenClaw
+- register commands with OpenClaw
+- register tools with OpenClaw
+
+Design rule:
+- no pairing/auth/dispatch business logic should live directly in this file
+
+---
+
+## 3. `plugin/openclaw.plugin.json`
+
+Planned manifest responsibilities:
+- define plugin name: `Yonexus.Server`
+- define entrypoint
+- declare version
+- define config schema / default config shape
+- declare plugin metadata
+- declare permissions if needed
+
+### Planned Config Shape
+
+```json
+{
+  "followerIdentifiers": [],
+  "notifyBotToken": "",
+  "adminUserId": "",
+  "listenHost": "0.0.0.0",
+  "listenPort": 8787,
+  "publicWsUrl": ""
+}
+```
+
+### Planned Validation Expectations
+
+- `listenPort` must be required
+- `followerIdentifiers` must be an array
+- `notifyBotToken` must be required
+- `adminUserId` must be required
+
+---
+
+## 4. `plugin/core/`
+
+### `registry.ts`
+Planned responsibilities:
+- client registry CRUD
+- active session tracking
+- persistent state load/save
+
+### `pairing.ts`
+Planned responsibilities:
+- pairing code generation
+- pairing pending state
+- Discord DM notification orchestration
+- pair_confirm validation
+- secret issuance
+
+### `auth.ts`
+Planned responsibilities:
+- auth_request verification
+- signature verification
+- nonce window validation
+- rate-limit checks
+- re-pair trigger decisions
+
+### `heartbeat.ts`
+Planned responsibilities:
+- lastHeartbeatAt updates
+- status transitions
+- sweep timer logic
+- disconnect timeout handling
+
+### `dispatch.ts`
+Planned responsibilities:
+- builtin message routing
+- application rule rewriting
+- rule registry
+- rule dispatch
+- sendMessageToClient routing
+
+### `errors.ts`
+Planned responsibilities:
+- typed/structured error definitions
+- standard server-side error codes
+
+---
+
+## 5. `plugin/hooks/`
+
+### `onGatewayStart.ts`
+Planned responsibilities:
+- initialize registry/runtime
+- start WebSocket server
+- start heartbeat sweep
+
+### `onGatewayStop.ts`
+Planned responsibilities:
+- stop heartbeat sweep
+- close sockets gracefully
+- persist final state if needed
+
+---
+
+## 6. `plugin/commands/`
+
+These are optional in early versions, but the directory should exist.
+
+Potential first commands:
+- `listClients.ts` — list known clients and statuses
+- `showClient.ts` — inspect one client’s trust/liveness state
+- `rePairClient.ts` — revoke trust and force next reconnect to re-pair
+
+---
+
+## 7. `plugin/tools/`
+
+Potential first tools:
+- `sendMessageToClient.ts`
+- `listClientStatus.ts`
+- `getPairingState.ts`
+
+These should wrap core logic, not duplicate it.
+
+---
+
+## 8. `servers/`
+
+### `wsServer.ts`
+Planned responsibilities:
+- WebSocket server startup and bind
+- connection accept lifecycle
+- socket-level send/receive plumbing
+
+### `sessionManager.ts`
+Planned responsibilities:
+- map identifiers to active connections
+- enforce one active session per identifier
+- close/replace older sessions when needed
+
+Design rule:
+- service bootstrap/network transport code belongs here
+- reusable business/state logic stays in `plugin/core/`
+
+---
+
+## 9. `skills/`
+
+Initial version may keep this minimal.
+
+Possible future skill topics:
+- Yonexus.Server operations
+- pairing recovery
+- debugging auth failures
+
+---
+
+## 10. `scripts/install.mjs`
+
+Planned CLI responsibilities:
+- `--install`
+- `--uninstall`
+- `--openclaw-profile-path <path>`
+
+Planned install behavior:
+- build output copied into the OpenClaw plugin directory
+- install target path determined by profile path
+
+Planned uninstall behavior:
+- remove installed plugin directory
+- optionally clean server plugin config if explicitly desired later
+
+---
+
+## 11. Initial Bring-Up Order
+
+Recommended first implementation order:
+1. manifest + `plugin/index.ts`
+2. `servers/wsServer.ts`
+3. `plugin/core/registry.ts`
+4. hello / hello_ack routing
+5. pairing flow
+6. auth flow
+7. heartbeat
+8. commands/tools
+
+---
+
+## 12. Notes
+
+- `protocol/` is the single protocol source of truth; do not duplicate protocol docs in this repo.
+- File names can change, but the wiring/core/service separation should remain.
+- Commands and tools can start thin and grow later.