# 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