From 162312d16c9090b5119df51768ccd1c2e06b5fbc Mon Sep 17 00:00:00 2001
From: nav <nav@mgr.hangman-lab.top>
Date: Wed, 1 Apr 2026 01:53:20 +0000
Subject: [PATCH] add manifest and install plan

---
 MANIFEST.md | 228 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 228 insertions(+)
 create mode 100644 MANIFEST.md

diff --git a/MANIFEST.md b/MANIFEST.md
new file mode 100644
index 0000000..df06455
--- /dev/null
+++ b/MANIFEST.md
@@ -0,0 +1,228 @@
+# Yonexus.Server — Manifest & Install Plan
+
+This document refines the planned plugin manifest and install script behavior for `Yonexus.Server`.
+
+## 1. Manifest File Location
+
+Required file:
+
+```text
+plugin/openclaw.plugin.json
+```
+
+This file is the OpenClaw plugin manifest and must be treated as the single manifest entrypoint for this repository.
+
+---
+
+## 2. Planned Manifest Responsibilities
+
+The manifest should define at minimum:
+- plugin name
+- plugin version
+- plugin description
+- plugin entrypoint
+- default config shape
+- config validation expectations
+- permissions if required by runtime integration
+
+---
+
+## 3. Planned Manifest Skeleton
+
+Initial planning shape:
+
+```json
+{
+  "name": "Yonexus.Server",
+  "version": "0.1.0",
+  "description": "Yonexus central hub plugin for cross-instance OpenClaw communication",
+  "entry": "dist/plugin/index.js",
+  "permissions": [],
+  "config": {
+    "followerIdentifiers": [],
+    "notifyBotToken": "",
+    "adminUserId": "",
+    "listenHost": "0.0.0.0",
+    "listenPort": 8787,
+    "publicWsUrl": ""
+  }
+}
+```
+
+This is not yet final schema syntax; it is the planned manifest contract.
+
+---
+
+## 4. Field-Level Intent
+
+### `name`
+Must be:
+- `Yonexus.Server`
+
+### `version`
+Initial planned value:
+- `0.1.0`
+
+### `description`
+Should make clear this is the hub/server-side Yonexus plugin.
+
+### `entry`
+Expected build target:
+- `dist/plugin/index.js`
+
+This assumes build output mirrors the plugin source tree under `dist/`.
+
+### `permissions`
+Initial expected value:
+- empty or minimal until implementation proves extra permissions are needed
+
+Potential future needs may include:
+- messaging capability for Discord DM via bot token path if exposed through runtime integration
+- filesystem access depending on plugin runtime packaging expectations
+
+### `config`
+Server-specific config block.
+
+---
+
+## 5. Server Config Field Semantics
+
+### `followerIdentifiers: string[]`
+Allowlist of client identifiers permitted to pair/connect.
+
+Validation expectations:
+- required
+- must be an array
+- values should be non-empty strings
+- duplicates should be rejected or normalized away
+
+### `notifyBotToken: string`
+Discord bot token used by the server to send pairing DM notifications.
+
+Validation expectations:
+- required
+- non-empty string
+- treated as secret/sensitive config
+- never logged in plaintext
+
+### `adminUserId: string`
+Discord user id of the human administrator who receives pairing DMs.
+
+Validation expectations:
+- required
+- non-empty string
+- ideally numeric-string format validation if that is reliable for Discord usage
+
+### `listenHost: string`
+Local bind host for the WebSocket server.
+
+Validation expectations:
+- optional with default `0.0.0.0`
+- must be valid host/bind string
+
+### `listenPort: number`
+Local bind port for the WebSocket server.
+
+Validation expectations:
+- required
+- integer
+- valid TCP port range
+
+### `publicWsUrl: string`
+Optional canonical external WebSocket URL used for documentation/operator reference.
+
+Validation expectations:
+- optional
+- if provided, should be a valid `ws://` or `wss://` URL
+
+---
+
+## 6. Manifest Validation Policy
+
+Initialization must fail when:
+- `followerIdentifiers` is missing or malformed
+- `notifyBotToken` is missing
+- `adminUserId` is missing
+- `listenPort` is missing or invalid
+
+Initialization should warn or fail when:
+- `publicWsUrl` is provided but malformed
+- duplicate identifiers are present in `followerIdentifiers`
+
+---
+
+## 7. Install Script File Location
+
+Required file:
+
+```text
+scripts/install.mjs
+```
+
+---
+
+## 8. Install Script Responsibilities
+
+The install script should support:
+- `--install`
+- `--uninstall`
+- `--openclaw-profile-path <path>`
+
+Default profile path:
+- `~/.openclaw`
+
+### Install Behavior
+
+When `--install` is used:
+- ensure build output exists
+- copy the built plugin into the OpenClaw plugins directory
+- target path should correspond to `Yonexus.Server`
+
+Planned target form:
+
+```text
+${openclawProfilePath}/plugins/Yonexus.Server
+```
+
+### Uninstall Behavior
+
+When `--uninstall` is used:
+- remove installed plugin files from the OpenClaw plugins directory
+- optionally preserve or separately handle runtime data/config unless explicit cleanup mode is added later
+
+---
+
+## 9. Install Script Design Notes
+
+The install script should:
+- be idempotent where reasonable
+- fail clearly on missing build artifacts
+- not silently delete unrelated files
+- keep install/uninstall behavior explicit
+
+Possible future options:
+- `--force`
+- `--clean-config`
+- `--print-target`
+
+These are not required yet.
+
+---
+
+## 10. Expected Relationship to Build Output
+
+Planned build assumption:
+- source lives under `plugin/`
+- compiled output lands under `dist/plugin/`
+- manifest entry points at compiled `dist/plugin/index.js`
+
+The install script should copy only what is needed for runtime use.
+
+---
+
+## 11. Documentation Rule
+
+When implementation begins:
+- `MANIFEST.md` should stay as planning/reference
+- `plugin/openclaw.plugin.json` becomes the executable truth
+- if the two ever diverge, the manifest must be updated and docs corrected quickly