diff --git a/README.md b/README.md
index 88ee3de..844edf4 100644
--- a/README.md
+++ b/README.md
@@ -1,14 +1,54 @@
-# Yonexus (MVP foundation)
+[English](./README.md) | [中文](./README.zh.md)
 
-OpenClaw plugin foundation for:
-- Organization hierarchy (Org/Dept/Team)
-- Agent registration + multi-identity
-- Supervisor mapping
+---
+
+# Yonexus
+
+Yonexus is an OpenClaw plugin for organization hierarchy and agent identity management.
+
+## Features
+
+- Organization hierarchy: `Organization -> Department -> Team -> Agent`
+- Agent registration and multi-identity assignment
+- Supervisor relationship mapping (does **not** imply permissions)
 - Role-based authorization
-- Query DSL (`eq | contains | regex`) with schema queryable guard
-- Scoped shared memory adapter (compatible with memory tools)
+- Query DSL: `eq | contains | regex`
+- Queryable field whitelist via schema (`queryable: true`)
+- Scope shared memory adapter (`org/dept/team`)
+- JSON persistence for structure data
+- Audit logs and structured error codes
+- Import / export support
 
-## Quick start
+## Project Layout
+
+```text
+.
+├─ plugin.json
+├─ src/
+│  ├─ index.ts
+│  ├─ models/
+│  ├─ permissions/
+│  ├─ store/
+│  ├─ tools/
+│  ├─ memory/
+│  └─ utils/
+├─ scripts/
+│  ├─ install.sh
+│  └─ demo.ts
+├─ tests/
+│  └─ smoke.ts
+├─ examples/
+│  └─ sample-data.json
+└─ dist/
+   └─ yonexus/
+```
+
+## Requirements
+
+- Node.js 22+
+- npm 10+
+
+## Quick Start
 
 ```bash
 npm install
@@ -18,32 +58,50 @@ npm run test:smoke
 npm run demo
 ```
 
-## Current status
+## Configuration
 
-Implemented in this branch:
-- Data models + JSON persistence store
-- Permission checker `authorize(action, actor, scope)`
-- Core APIs:
-  - `createDepartment`
-  - `createTeam`
-  - `registerAgent`
-  - `assignIdentity`
-  - `setSupervisor`
-  - `whoami`
-  - `queryAgents`
-- Query parser/executor with pagination
-- Scope memory adapter (`put/search`)
-- Management APIs:
-  - `renameDepartment`
-  - `renameTeam`
-  - `migrateTeam`
-  - `deleteDepartment`
-  - `deleteTeam`
-- Error code model (`YonexusError`) and audit logs
-- Import/export APIs (`importData` / `exportData`)
+`plugin.json` includes default config:
+
+- `name`: `yonexus`
+- `entry`: `dist/yonexus/index.js`
+- `config.dataFile`: `./data/org.json`
+- `config.registrars`: whitelist for registrar agents
+- `config.schema`: metadata field schema and queryability
+
+## Implemented APIs
+
+Core:
+- `createDepartment(actor, name, orgId)`
+- `createTeam(actor, name, deptId)`
+- `registerAgent(actor, agentId, name, roles?)`
+- `assignIdentity(actor, agentId, deptId, teamId, meta)`
+- `setSupervisor(actor, agentId, supervisorId, deptId?)`
+- `whoami(agentId)`
+- `queryAgents(actor, scope, query)`
+
+Management:
+- `renameDepartment(actor, deptId, newName)`
+- `renameTeam(actor, teamId, newName, deptId?)`
+- `migrateTeam(actor, teamId, newDeptId)`
+- `deleteDepartment(actor, deptId)`
+- `deleteTeam(actor, teamId, deptId?)`
+
+Data & audit:
+- `exportData(actor)`
+- `importData(actor, state)`
+- `listAuditLogs(limit?, offset?)`
+
+## Testing
+
+Smoke test:
+
+```bash
+npm run test:smoke
+```
 
 ## Notes
 
-- Persistence file defaults to `data/org.json`.
-- Meta fields are validated against schema; unknown fields are dropped.
-- Supervisor relation does not imply permissions.
+- Structure data is persisted in JSON, not memory_store.
+- Shared scope memory is handled via the scope memory adapter.
+- Unknown metadata fields are dropped during identity assignment.
+- `queryAgents` enforces schema queryable constraints.
diff --git a/README.zh.md b/README.zh.md
new file mode 100644
index 0000000..bdda11f
--- /dev/null
+++ b/README.zh.md
@@ -0,0 +1,107 @@
+[English](./README.md) | [中文](./README.zh.md)
+
+---
+
+# Yonexus
+
+Yonexus 是一个用于 OpenClaw 的组织结构与 Agent 身份管理插件。
+
+## 功能特性
+
+- 组织层级：`Organization -> Department -> Team -> Agent`
+- Agent 注册与多身份（Identity）管理
+- 上下级关系（Supervisor，**不自动赋权**）
+- 基于角色的权限控制
+- Query DSL：`eq | contains | regex`
+- 基于 schema 的可查询字段白名单（`queryable: true`）
+- scope 共享记忆适配（org/dept/team）
+- 结构化数据 JSON 持久化
+- 审计日志与结构化错误码
+- 导入 / 导出能力
+
+## 项目结构
+
+```text
+.
+├─ plugin.json
+├─ src/
+│  ├─ index.ts
+│  ├─ models/
+│  ├─ permissions/
+│  ├─ store/
+│  ├─ tools/
+│  ├─ memory/
+│  └─ utils/
+├─ scripts/
+│  ├─ install.sh
+│  └─ demo.ts
+├─ tests/
+│  └─ smoke.ts
+├─ examples/
+│  └─ sample-data.json
+└─ dist/
+   └─ yonexus/
+```
+
+## 环境要求
+
+- Node.js 22+
+- npm 10+
+
+## 快速开始
+
+```bash
+npm install
+npm run build
+bash scripts/install.sh
+npm run test:smoke
+npm run demo
+```
+
+## 配置说明
+
+`plugin.json` 默认包含以下配置：
+
+- `name`: `yonexus`
+- `entry`: `dist/yonexus/index.js`
+- `config.dataFile`: `./data/org.json`
+- `config.registrars`: 注册人白名单
+- `config.schema`: 元数据字段定义与可查询性
+
+## 已实现 API
+
+核心 API：
+- `createDepartment(actor, name, orgId)`
+- `createTeam(actor, name, deptId)`
+- `registerAgent(actor, agentId, name, roles?)`
+- `assignIdentity(actor, agentId, deptId, teamId, meta)`
+- `setSupervisor(actor, agentId, supervisorId, deptId?)`
+- `whoami(agentId)`
+- `queryAgents(actor, scope, query)`
+
+管理 API：
+- `renameDepartment(actor, deptId, newName)`
+- `renameTeam(actor, teamId, newName, deptId?)`
+- `migrateTeam(actor, teamId, newDeptId)`
+- `deleteDepartment(actor, deptId)`
+- `deleteTeam(actor, teamId, deptId?)`
+
+数据与审计：
+- `exportData(actor)`
+- `importData(actor, state)`
+- `listAuditLogs(limit?, offset?)`
+
+## 测试
+
+冒烟测试：
+
+```bash
+npm run test:smoke
+```
+
+## 说明
+
+- 结构数据保存在 JSON 文件，不进入 memory_store。
+- 共享记忆通过 scope memory 适配器处理。
+- 分配 identity 时，未知 meta 字段会被丢弃。
+- `queryAgents` 会严格校验字段是否在 schema 中标记为可查询。