docs: improve doucmentation

improve doucmentation and fix small store changes

docs-site/docs/plugin-development/api/users-and-roles.md

@@ -0,0 +1,89 @@
+---
+sidebar_position: 3
+---
+
+# Users and Roles API
+
+The users and roles APIs read known users, read room members, and perform moderation or role changes when granted.
+
+## Required Capabilities
+
+| Method | Capability |
+| --- | --- |
+| `users.getCurrent()` | `users.read` |
+| `users.list()` | `users.read` |
+| `users.readMembers()` | `users.read` |
+| `users.setRole(userId, role)` | `roles.manage` |
+| `users.kick(userId)` | `users.manage` |
+| `users.ban(userId, reason?)` | `users.manage` |
+| `roles.list()` | `roles.read` |
+| `roles.setAssignments(assignments)` | `roles.manage` |
+
+## Read Users
+
+```js
+export function activate(context) {
+  const currentUser = context.api.users.getCurrent();
+  const knownUsers = context.api.users.list();
+  const roomMembers = context.api.users.readMembers();
+
+  context.api.logger.info('Room user summary', {
+    currentUser: currentUser?.displayName,
+    knownUserCount: knownUsers.length,
+    memberCount: roomMembers.length
+  });
+}
+```
+
+Example member data:
+
+```json
+[
+  { "id": "member-1", "userId": "user-alice-01", "displayName": "Alice", "role": "admin" },
+  { "id": "member-2", "userId": "user-muse-01", "displayName": "Muse", "role": "member" }
+]
+```
+
+## Read Roles
+
+```js
+export function activate(context) {
+  const roles = context.api.roles.list();
+
+  context.api.logger.info('Available roles', roles.map((role) => ({
+    id: role.id,
+    name: role.name,
+    permissions: role.permissions
+  })));
+}
+```
+
+## Set a User Role
+
+```js
+export function activate(context) {
+  context.api.users.setRole('user-muse-01', 'moderator');
+}
+```
+
+## Replace Role Assignments
+
+```js
+export function activate(context) {
+  context.api.roles.setAssignments([
+    { userId: 'user-alice-01', roleId: 'admin' },
+    { userId: 'user-muse-01', roleId: 'moderator' }
+  ]);
+}
+```
+
+## Kick or Ban a User
+
+```js
+export function activate(context) {
+  context.api.users.kick('user-spam-01');
+  context.api.users.ban('user-spam-02', 'Repeated spam in support channels');
+}
+```
+
+Moderation calls should normally be behind an explicit user action in plugin UI. Do not run destructive moderation automatically on activation.