From 98a7383f0bd375631ef1c01dc64d0557e86a8800 Mon Sep 17 00:00:00 2001
From: nav <nav@mgr.hangman-lab.top>
Date: Wed, 1 Apr 2026 01:38:34 +0000
Subject: [PATCH] add scaffold plan

---
 SCAFFOLD.md | 242 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 242 insertions(+)
 create mode 100644 SCAFFOLD.md

diff --git a/SCAFFOLD.md b/SCAFFOLD.md
new file mode 100644
index 0000000..2bd20a0
--- /dev/null
+++ b/SCAFFOLD.md
@@ -0,0 +1,242 @@
+# Yonexus.Client — Scaffold Plan
+
+This document refines the repository structure into concrete planned files and responsibilities.
+
+## 1. Planned Tree
+
+```text
+.
+├── plugin/
+│   ├── core/
+│   │   ├── localState.ts
+│   │   ├── keys.ts
+│   │   ├── pairing.ts
+│   │   ├── auth.ts
+│   │   ├── heartbeat.ts
+│   │   ├── dispatch.ts
+│   │   └── errors.ts
+│   ├── hooks/
+│   │   ├── onGatewayStart.ts
+│   │   └── onGatewayStop.ts
+│   ├── commands/
+│   │   ├── showStatus.ts
+│   │   ├── reconnect.ts
+│   │   └── resetTrust.ts
+│   ├── tools/
+│   │   ├── sendMessageToServer.ts
+│   │   └── getConnectionState.ts
+│   ├── index.ts
+│   └── openclaw.plugin.json
+├── skills/
+│   └── ...
+├── servers/
+│   └── clientRuntime.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 client core modules
+- import hooks
+- import commands
+- import tools
+- initialize client runtime container
+- register hooks with OpenClaw
+- register commands with OpenClaw
+- register tools with OpenClaw
+
+Design rule:
+- no reconnect/auth/pairing business logic should live directly in this file
+
+---
+
+## 3. `plugin/openclaw.plugin.json`
+
+Planned manifest responsibilities:
+- define plugin name: `Yonexus.Client`
+- define entrypoint
+- declare version
+- define config schema / default config shape
+- declare plugin metadata
+- declare permissions if needed
+
+### Planned Config Shape
+
+```json
+{
+  "mainHost": "",
+  "identifier": "",
+  "notifyBotToken": "",
+  "adminUserId": ""
+}
+```
+
+### Planned Validation Expectations
+
+- `mainHost` must be required
+- `identifier` must be required
+- `mainHost` should be a valid WebSocket endpoint
+
+---
+
+## 4. `plugin/core/`
+
+### `localState.ts`
+Planned responsibilities:
+- load/save client local trust state
+- persist secret and timestamps
+- manage current pairing/auth state
+
+### `keys.ts`
+Planned responsibilities:
+- generate Ed25519 keypair
+- load/save encoded keys
+- sign auth proof payloads
+
+### `pairing.ts`
+Planned responsibilities:
+- track pending pairing flow
+- accept human-provided pairing code
+- send pair_confirm
+- store secret after pair_success
+
+### `auth.ts`
+Planned responsibilities:
+- construct proof payload
+- create signature
+- send auth_request
+- handle auth_success/auth_failed
+- react to re_pair_required
+
+### `heartbeat.ts`
+Planned responsibilities:
+- schedule heartbeat loop
+- stop loop on disconnect
+- handle optional heartbeat_ack
+
+### `dispatch.ts`
+Planned responsibilities:
+- builtin message routing
+- application rule registry
+- inbound message dispatch
+- sendMessageToServer routing
+
+### `errors.ts`
+Planned responsibilities:
+- typed/structured error definitions
+- standard client-side error codes
+
+---
+
+## 5. `plugin/hooks/`
+
+### `onGatewayStart.ts`
+Planned responsibilities:
+- initialize local state
+- ensure keypair exists
+- start client runtime
+- attempt initial connection
+
+### `onGatewayStop.ts`
+Planned responsibilities:
+- stop heartbeat
+- close socket gracefully
+- persist final state if needed
+
+---
+
+## 6. `plugin/commands/`
+
+These are optional in early versions, but the directory should exist.
+
+Potential first commands:
+- `showStatus.ts` — inspect connection/auth/pairing status
+- `reconnect.ts` — manually trigger reconnect
+- `resetTrust.ts` — clear local secret and force re-pair
+
+---
+
+## 7. `plugin/tools/`
+
+Potential first tools:
+- `sendMessageToServer.ts`
+- `getConnectionState.ts`
+
+These should wrap core logic, not duplicate it.
+
+---
+
+## 8. `servers/`
+
+### `clientRuntime.ts`
+Planned responsibilities:
+- manage WebSocket client runtime
+- manage reconnect/backoff loop
+- broker raw send/receive with server
+
+Design rule:
+- even though the client is not primarily a server, runtime/service bootstrap code still belongs in `servers/` for structural consistency
+- reusable logic remains in `plugin/core/`
+
+---
+
+## 9. `skills/`
+
+Initial version may keep this minimal.
+
+Possible future skill topics:
+- reconnect troubleshooting
+- pairing recovery
+- auth debugging guidance
+
+---
+
+## 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 local client config if explicitly desired later
+
+---
+
+## 11. Initial Bring-Up Order
+
+Recommended first implementation order:
+1. manifest + `plugin/index.ts`
+2. `servers/clientRuntime.ts`
+3. `plugin/core/localState.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.
+- `servers/` should exist even if early client runtime is lightweight.