[English](./README.md) | [中文](./README.zh.md)

---

# Yonexus

Yonexus is an OpenClaw plugin for organization hierarchy and agent identity management.

## Features

- Organization hierarchy: `Organization -> Department -> Team -> Agent`
- Filesystem-backed resource layout under `${openclaw dir}/yonexus`
- Agent registration and multi-identity assignment
- Supervisor relationship mapping (does **not** imply permissions)
- Role-based authorization
- 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

## Project Layout

```text
.
├─ plugin/
│  ├─ index.ts          # wiring: init, register commands/hooks/tools
│  ├─ commands/          # slash commands
│  ├─ tools/             # query & resource tools
│  ├─ hooks/             # lifecycle hooks
│  └─ core/              # business logic, models, store, permissions
├─ skills/               # skill definitions
├─ docs/                 # project documentation
├─ scripts/              # demo & utility scripts
├─ tests/                # tests
├─ install.mjs           # install/uninstall script
├─ plugin.json           # plugin manifest
├─ README.md
└─ README.zh.md
```

## Requirements

- Node.js 22+
- npm 10+

## Quick Start

```bash
npm install
npm run build
npm run test:smoke
npm run demo
```

## Install / Uninstall

```bash
# Install (builds and copies to ~/.openclaw/plugins/yonexus)
node install.mjs --install

# Install to custom openclaw profile path
node install.mjs --install --openclaw-profile-path /path/to/.openclaw

# Uninstall
node install.mjs --uninstall
```

## Configuration

`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:
- `createOrganization(actor, name)`
- `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?)`

Docs:
- `getDocs(scope, topic, keyword)`

Data & audit:
- `exportData(actor)`
- `importData(actor, state)`
- `listAuditLogs(limit?, offset?)`

## Testing

```bash
npm run test:smoke
```

## Notes

- 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.