diff --git a/MANIFEST.md b/MANIFEST.md
new file mode 100644
index 0000000..6d3442d
--- /dev/null
+++ b/MANIFEST.md
@@ -0,0 +1,199 @@
+# Yonexus.Client — Manifest & Install Plan
+
+This document refines the planned plugin manifest and install script behavior for `Yonexus.Client`.
+
+## 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.Client",
+  "version": "0.1.0",
+  "description": "Yonexus client plugin for cross-instance OpenClaw communication",
+  "entry": "dist/plugin/index.js",
+  "permissions": [],
+  "config": {
+    "mainHost": "",
+    "identifier": "",
+    "notifyBotToken": "",
+    "adminUserId": ""
+  }
+}
+```
+
+This is not yet final schema syntax; it is the planned manifest contract.
+
+---
+
+## 4. Field-Level Intent
+
+### `name`
+Must be:
+- `Yonexus.Client`
+
+### `version`
+Initial planned value:
+- `0.1.0`
+
+### `description`
+Should make clear this is the client-side Yonexus plugin.
+
+### `entry`
+Expected build target:
+- `dist/plugin/index.js`
+
+### `permissions`
+Initial expected value:
+- empty or minimal until implementation proves extra permissions are needed
+
+### `config`
+Client-specific config block.
+
+---
+
+## 5. Client Config Field Semantics
+
+### `mainHost: string`
+WebSocket endpoint of `Yonexus.Server`.
+
+Validation expectations:
+- required
+- non-empty string
+- should be valid `ws://` or `wss://` URL
+
+### `identifier: string`
+Unique client identity within the Yonexus network.
+
+Validation expectations:
+- required
+- non-empty string
+- duplicates are a deployment/operator concern, but docs should clearly state uniqueness requirement
+
+### `notifyBotToken: string`
+Currently retained in config planning for symmetry with system-wide setup, but likely server-centric in practical usage.
+
+Validation expectations:
+- currently planned as present in config
+- may later be reconsidered if proven unnecessary on client side
+- must never be logged in plaintext if retained
+
+### `adminUserId: string`
+Human administrator identity reference shared with the Yonexus system.
+
+Validation expectations:
+- currently planned as present in config
+- may later be reconsidered if proven unnecessary on client side
+
+---
+
+## 6. Manifest Validation Policy
+
+Initialization must fail when:
+- `mainHost` is missing or malformed
+- `identifier` is missing
+
+Initialization may later be tightened when the fate of `notifyBotToken` and `adminUserId` on the client side is finalized.
+
+---
+
+## 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.Client`
+
+Planned target form:
+
+```text
+${openclawProfilePath}/plugins/Yonexus.Client
+```
+
+### Uninstall Behavior
+
+When `--uninstall` is used:
+- remove installed plugin files from the OpenClaw plugins directory
+- optionally preserve local 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