docs: add bilingual README with top language navigation

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.