docs: improve doucmentation

improve doucmentation and fix small store changes

docs-site/docs/plugin-development/api/channels.md

@@ -0,0 +1,85 @@
+---
+sidebar_position: 5
+---
+
+# Channels API
+
+The channels API reads, selects, creates, renames, and removes server channels.
+
+## Required Capabilities
+
+| Method | Capability |
+| --- | --- |
+| `channels.list()` | `channels.read` |
+| `channels.select(channelId)` | `channels.read` |
+| `channels.addAudioChannel(request)` | `channels.manage` |
+| `channels.addVideoChannel(request)` | `channels.manage` |
+| `channels.rename(channelId, name)` | `channels.manage` |
+| `channels.remove(channelId)` | `channels.manage` |
+
+## List Channels
+
+```js
+export function activate(context) {
+  const channels = context.api.channels.list();
+
+  context.api.logger.info('Channels', channels.map((channel) => ({
+    id: channel.id,
+    name: channel.name,
+    type: channel.type
+  })));
+}
+```
+
+Example channel list:
+
+```json
+[
+  { "id": "general", "name": "general", "type": "text", "position": 0 },
+  { "id": "support", "name": "support", "type": "text", "position": 1 },
+  { "id": "lobby", "name": "Lobby", "type": "audio", "position": 10 }
+]
+```
+
+## Select a Channel
+
+```js
+export function activate(context) {
+  context.api.channels.select('support');
+}
+```
+
+## Add a Voice Channel
+
+```js
+export function activate(context) {
+  context.api.channels.addAudioChannel({
+    id: 'raid-voice',
+    name: 'Raid Voice',
+    position: 20
+  });
+}
+```
+
+## Add a Video Channel Section
+
+```js
+export function activate(context) {
+  context.api.channels.addVideoChannel({
+    id: 'watch-party-video',
+    name: 'Watch Party',
+    position: 30
+  });
+}
+```
+
+## Rename and Remove
+
+```js
+export function activate(context) {
+  context.api.channels.rename('raid-voice', 'Raid Voice - Tonight');
+  context.api.channels.remove('old-event-room');
+}
+```
+
+Channel creation, rename, and removal should be user-confirmed because they change the shared server structure.

docs-site/docs/plugin-development/api/context-and-logging.md

@@ -0,0 +1,73 @@
+---
+sidebar_position: 1
+---
+
+# Context and Logging
+
+Context and logging are available to every plugin. They do not require privileged capabilities.
+
+## context.getCurrent()
+
+Reads the current interaction context.
+
+```js
+export function activate(context) {
+  const current = context.api.context.getCurrent();
+
+  context.api.logger.info('Current context', {
+    serverName: current.server?.name ?? 'No server open',
+    textChannel: current.textChannel?.name ?? 'No text channel selected',
+    voiceChannel: current.voiceChannel?.name ?? 'Not connected to voice',
+    user: current.user?.displayName ?? 'No user'
+  });
+}
+```
+
+Example context shape:
+
+```json
+{
+  "source": "manual",
+  "server": { "id": "room-7ebdde75", "name": "Friday Game Night" },
+  "textChannel": { "id": "general", "name": "general", "type": "text" },
+  "voiceChannel": { "id": "lobby", "name": "Lobby", "type": "audio" },
+  "user": { "id": "user-alice-01", "displayName": "Alice" }
+}
+```
+
+## Action Context
+
+Composer, toolbar, and profile actions receive context directly.
+
+```js
+export function activate(context) {
+  context.subscriptions.push(context.api.ui.registerToolbarAction('where-am-i', {
+    label: 'Where am I?',
+    run: (actionContext) => {
+      context.api.logger.info('Toolbar action context', {
+        source: actionContext.source,
+        serverId: actionContext.server?.id,
+        textChannelId: actionContext.textChannel?.id,
+        voiceChannelId: actionContext.voiceChannel?.id
+      });
+    }
+  }));
+}
+```
+
+Capability required: `ui.pages` for the toolbar action. The context object itself needs no extra capability.
+
+## Logger Methods
+
+```js
+export function activate(context) {
+  const { logger } = context.api;
+
+  logger.debug('Preparing plugin', { pluginId: context.pluginId });
+  logger.info('Plugin activated', { version: context.manifest.version });
+  logger.warn('Optional service unavailable', { service: 'weather.example.com' });
+  logger.error('Failed to parse saved preference', { key: 'soundboard:favorites' });
+}
+```
+
+Logs are visible in the Plugin Manager. Avoid logging passwords, bearer tokens, or private message contents.

docs-site/docs/plugin-development/api/events.md

@@ -0,0 +1,100 @@
+---
+sidebar_position: 7
+---
+
+# Events API
+
+Plugin events allow plugins to publish and subscribe to declared server or P2P events.
+
+## Required Capabilities
+
+| Method | Capability |
+| --- | --- |
+| `events.publishServer(eventName, payload)` | `events.server.publish` |
+| `events.subscribeServer(subscription)` | `events.server.subscribe` |
+| `events.publishP2p(eventName, payload)` | `events.p2p.publish` |
+| `events.subscribeP2p(subscription)` | `events.p2p.subscribe` |
+
+## Declare Events in the Manifest
+
+```json
+{
+  "events": [
+    {
+      "eventName": "poll:vote",
+      "direction": "p2pHint",
+      "scope": "channel",
+      "maxPayloadBytes": 2048
+    },
+    {
+      "eventName": "moderation:flag",
+      "direction": "serverRelay",
+      "scope": "server",
+      "maxPayloadBytes": 4096
+    }
+  ]
+}
+```
+
+## Publish and Subscribe to P2P Events
+
+```js
+export function activate(context) {
+  context.subscriptions.push(context.api.events.subscribeP2p({
+    eventName: 'poll:vote',
+    handler: (event) => {
+      context.api.logger.info('Vote received', {
+        optionId: event.payload?.optionId,
+        voterName: event.payload?.voterName,
+        eventId: event.eventId
+      });
+    }
+  }));
+
+  context.api.events.publishP2p('poll:vote', {
+    pollId: 'raid-night-2026-04-29',
+    optionId: 'dungeon',
+    voterName: 'Alice'
+  });
+}
+```
+
+## Publish and Subscribe to Server Events
+
+```js
+export function activate(context) {
+  context.subscriptions.push(context.api.events.subscribeServer({
+    eventName: 'moderation:flag',
+    handler: (event) => {
+      context.api.logger.warn('Moderation flag received', {
+        messageId: event.payload?.messageId,
+        reason: event.payload?.reason
+      });
+    }
+  }));
+
+  context.api.events.publishServer('moderation:flag', {
+    messageId: 'msg-20260429-flagged',
+    reason: 'Possible spam link',
+    reportedBy: 'user-alice-01'
+  });
+}
+```
+
+Example event envelope:
+
+```json
+{
+  "type": "plugin_event",
+  "eventName": "poll:vote",
+  "pluginId": "example.polls",
+  "serverId": "room-7ebdde75",
+  "eventId": "event-1777473600000-1",
+  "emittedAt": 1777473600000,
+  "payload": {
+    "pollId": "raid-night-2026-04-29",
+    "optionId": "dungeon",
+    "voterName": "Alice"
+  }
+}
+```

docs-site/docs/plugin-development/api/message-bus.md

@@ -0,0 +1,95 @@
+---
+sidebar_position: 8
+---
+
+# Message Bus API
+
+The plugin message bus sends plugin-only P2P events. It can also include bounded latest-message snapshots for plugins that coordinate around recent chat state.
+
+## Required Capabilities
+
+| Method | Capability |
+| --- | --- |
+| `messageBus.publish(request)` | `events.p2p.publish`, plus `messages.read` if `includeLatestMessages` is true |
+| `messageBus.sendLatestMessages(request?)` | `events.p2p.publish` and `messages.read` |
+| `messageBus.subscribe(subscription)` | `events.p2p.subscribe`, plus `messages.read` if replaying latest messages |
+
+## Subscribe
+
+```js
+export function activate(context) {
+  context.subscriptions.push(context.api.messageBus.subscribe({
+    topic: 'poll:votes',
+    channelId: 'general',
+    replayLatest: true,
+    latestMessageLimit: 10,
+    handler: (event) => {
+      context.api.logger.info('Poll bus event', {
+        topic: event.topic,
+        choice: event.payload?.choice,
+        messageCount: event.messages?.length ?? 0
+      });
+    }
+  }));
+}
+```
+
+## Publish
+
+```js
+export function activate(context) {
+  const envelope = context.api.messageBus.publish({
+    topic: 'poll:votes',
+    channelId: 'general',
+    payload: {
+      pollId: 'raid-night-2026-04-29',
+      choice: 'healer',
+      voter: 'Alice'
+    },
+    includeLatestMessages: true,
+    includeSelf: true,
+    latestMessageLimit: 10,
+    sinceTimestamp: 1777470000000
+  });
+
+  context.api.logger.info('Published poll event', { eventId: envelope.eventId });
+}
+```
+
+Example envelope:
+
+```json
+{
+  "eventId": "plugin-bus-1777473600000-1",
+  "pluginId": "example.polls",
+  "roomId": "room-7ebdde75",
+  "channelId": "general",
+  "topic": "poll:votes",
+  "sentAt": 1777473600000,
+  "payload": {
+    "pollId": "raid-night-2026-04-29",
+    "choice": "healer",
+    "voter": "Alice"
+  },
+  "messages": [
+    { "id": "msg-1", "content": "Raid tonight?", "channelId": "general" }
+  ]
+}
+```
+
+## Send Latest Messages
+
+```js
+export function activate(context) {
+  context.api.messageBus.sendLatestMessages({
+    topic: 'chat:snapshot',
+    channelId: 'support',
+    limit: 25,
+    includeDeleted: false,
+    sinceTimestamp: 1777460000000,
+    targetPeerId: 'peer-muse-laptop'
+  });
+}
+```
+
+Use the message bus for plugin coordination. Do not use it for normal user chat messages; use `messages.send()` for that.

docs-site/docs/plugin-development/api/messages-and-typing.md

@@ -0,0 +1,144 @@
+---
+sidebar_position: 6
+---
+
+# Messages and Typing API
+
+The messages API reads current messages, sends messages, edits or deletes plugin-owned messages, moderates messages, syncs messages, and exposes typing state.
+
+## Required Capabilities
+
+| Method | Capability |
+| --- | --- |
+| `messages.readCurrent()` | `messages.read` |
+| `messages.send(content, channelId?)` | `messages.send` |
+| `messages.sendAsPluginUser(request)` | `messages.send` |
+| `messages.setTyping(isTyping, channelId?)` | `messages.send` |
+| `messages.subscribeTyping(handler)` | `messages.read` |
+| `messages.edit(messageId, content)` | `messages.editOwn` |
+| `messages.delete(messageId)` | `messages.deleteOwn` |
+| `messages.moderateDelete(messageId)` | `messages.moderate` |
+| `messages.sync(messages)` | `messages.sync` |
+
+## Read Current Messages
+
+```js
+export function activate(context) {
+  const messages = context.api.messages.readCurrent();
+
+  context.api.logger.info('Current messages', messages.slice(-3).map((message) => ({
+    id: message.id,
+    channelId: message.channelId,
+    senderName: message.senderName,
+    content: message.content
+  })));
+}
+```
+
+## Send a Message
+
+```js
+export function activate(context) {
+  const created = context.api.messages.send(
+    'Reminder: raid starts at 20:00. Bring repairs and snacks.',
+    'general'
+  );
+
+  context.api.logger.info('Sent reminder', { messageId: created.id });
+}
+```
+
+## Send as a Plugin User
+
+```js
+export function activate(context) {
+  const botUserId = context.api.server.registerPluginUser({
+    id: 'poll-bot',
+    displayName: 'Poll Bot'
+  });
+
+  context.api.messages.sendAsPluginUser({
+    pluginUserId: botUserId,
+    channelId: 'general',
+    content: 'Poll is open: react with 1 for dungeon, 2 for arena, 3 for crafting.'
+  });
+}
+```
+
+Capabilities required: `users.manage` and `messages.send`.
+
+## Edit and Delete Plugin-Owned Messages
+
+```js
+export function activate(context) {
+  const message = context.api.messages.send('Draft event reminder', 'announcements');
+
+  context.api.messages.edit(message.id, 'Event reminder: voice meetup starts in 15 minutes.');
+  context.api.messages.delete(message.id);
+}
+```
+
+## Moderation Delete
+
+```js
+export function activate(context) {
+  context.api.messages.moderateDelete('msg-spam-20260429-001');
+}
+```
+
+Use moderation from explicit moderator actions, not automatic activation.
+
+## Typing State
+
+```js
+export function activate(context) {
+  context.api.messages.setTyping(true, 'general');
+
+  setTimeout(() => {
+    context.api.messages.setTyping(false, 'general');
+  }, 1500);
+
+  context.subscriptions.push(context.api.messages.subscribeTyping((event) => {
+    context.api.logger.info('Typing event', {
+      displayName: event.displayName,
+      isTyping: event.isTyping,
+      channelId: event.channelId,
+      serverId: event.serverId,
+      voiceChannel: event.voiceChannel?.name ?? null
+    });
+  }));
+}
+```
+
+Example typing event:
+
+```json
+{
+  "serverId": "room-7ebdde75",
+  "channelId": "general",
+  "userId": "user-muse-01",
+  "displayName": "Muse",
+  "isTyping": true
+}
+```
+
+## Sync Messages
+
+```js
+export function activate(context) {
+  context.api.messages.sync([
+    {
+      id: 'external-standup-001',
+      roomId: 'room-7ebdde75',
+      channelId: 'standup',
+      senderId: 'standup-importer',
+      senderName: 'Standup Importer',
+      content: 'Imported note: Alice is working on plugin docs.',
+      timestamp: 1777473600000,
+      isDeleted: false
+    }
+  ]);
+}
+```
+
+Sync should preserve message ids and timestamps from the source system when possible.

docs-site/docs/plugin-development/api/p2p-and-media.md

@@ -0,0 +1,128 @@
+---
+sidebar_position: 9
+---
+
+# P2P and Media API
+
+P2P APIs send plugin data to connected peers. Media APIs play audio and contribute custom streams.
+
+## Required Capabilities
+
+| Method | Capability |
+| --- | --- |
+| `p2p.connectedPeers()` | `p2p.data` |
+| `p2p.broadcastData(eventName, payload)` | `p2p.data` |
+| `p2p.sendData(peerId, eventName, payload)` | `p2p.data` |
+| `media.playAudioClip(request)` | `media.playAudio` |
+| `media.addCustomAudioStream(request)` | `media.addAudioStream` |
+| `media.addCustomVideoStream(request)` | `media.addVideoStream` |
+| `media.setInputVolume(volume)` | `audio.volume` |
+| `media.setOutputVolume(volume)` | `audio.volume` |
+
+## Connected Peers
+
+```js
+export function activate(context) {
+  const peerIds = context.api.p2p.connectedPeers();
+
+  context.api.logger.info('Connected peers', { peerIds });
+}
+```
+
+## Broadcast Data
+
+```js
+export function activate(context) {
+  context.api.p2p.broadcastData('soundboard:played', {
+    soundId: 'airhorn-short',
+    label: 'Airhorn',
+    playedBy: 'Alice',
+    playedAt: 1777473600000
+  });
+}
+```
+
+## Send Data to One Peer
+
+```js
+export function activate(context) {
+  context.api.p2p.sendData('peer-muse-laptop', 'private-tool:ping', {
+    requestId: 'ping-20260429-001',
+    message: 'Are you receiving plugin data?'
+  });
+}
+```
+
+## Play an Audio Clip
+
+```js
+export async function activate(context) {
+  await context.api.media.playAudioClip({
+    url: 'https://cdn.example.com/metoyou/sounds/chime.wav',
+    volume: 0.65
+  });
+}
+```
+
+## Add a Custom Audio Stream
+
+```js
+export async function activate(context) {
+  const audioContext = new AudioContext();
+  const oscillator = audioContext.createOscillator();
+  const gain = audioContext.createGain();
+  const destination = audioContext.createMediaStreamDestination();
+
+  oscillator.type = 'sine';
+  oscillator.frequency.value = 440;
+  gain.gain.value = 0.03;
+  oscillator.connect(gain);
+  gain.connect(destination);
+  oscillator.start();
+
+  await context.api.media.addCustomAudioStream({
+    label: 'Tuning tone',
+    stream: destination.stream
+  });
+
+  setTimeout(async () => {
+    oscillator.stop();
+    await audioContext.close();
+  }, 1000);
+}
+```
+
+## Add a Custom Video Stream
+
+```js
+export async function activate(context) {
+  const canvas = document.createElement('canvas');
+  canvas.width = 1280;
+  canvas.height = 720;
+  const ctx = canvas.getContext('2d');
+
+  ctx.fillStyle = '#111827';
+  ctx.fillRect(0, 0, canvas.width, canvas.height);
+  ctx.fillStyle = '#ffffff';
+  ctx.font = '48px sans-serif';
+  ctx.fillText('Plugin camera scene', 80, 120);
+
+  const stream = canvas.captureStream(15);
+
+  await context.api.media.addCustomVideoStream({
+    label: 'Plugin camera scene',
+    stream
+  });
+}
+```
+
+## Set Volumes
+
+```js
+export function activate(context) {
+  context.api.media.setInputVolume(0.85);
+  context.api.media.setOutputVolume(0.75);
+}
+```
+
+Use media APIs with visible controls and clear user consent. Unexpected audio or video is a poor user experience.

docs-site/docs/plugin-development/api/profile.md

@@ -0,0 +1,66 @@
+---
+sidebar_position: 2
+---
+
+# Profile API
+
+The profile API reads and updates the current user's local profile details.
+
+## Required Capabilities
+
+| Method | Capability |
+| --- | --- |
+| `profile.getCurrent()` | `profile.read` |
+| `profile.update(profile)` | `profile.write` |
+| `profile.updateAvatar(avatar)` | `profile.write` |
+
+## Read Current Profile
+
+```js
+export function activate(context) {
+  const user = context.api.profile.getCurrent();
+
+  context.api.logger.info('Current profile', {
+    id: user?.id,
+    displayName: user?.displayName,
+    username: user?.username
+  });
+}
+```
+
+Example result:
+
+```json
+{
+  "id": "user-alice-01",
+  "username": "alice",
+  "displayName": "Alice",
+  "description": "Raids on Fridays",
+  "avatarUrl": "/avatars/alice.webp"
+}
+```
+
+## Update Display Profile
+
+```js
+export function activate(context) {
+  context.api.profile.update({
+    displayName: 'Alice - Support Lead',
+    description: 'Available for onboarding and support questions.'
+  });
+}
+```
+
+## Update Avatar
+
+```js
+export function activate(context) {
+  context.api.profile.updateAvatar({
+    avatarUrl: 'https://cdn.example.com/metoyou/avatars/alice-support.png',
+    avatarMime: 'image/png',
+    avatarHash: 'sha256:9df5d5e4b0d8f41f3a3cf5d1f5a2c1f4'
+  });
+}
+```
+
+Use `profile.write` carefully. A plugin that changes a user's identity should explain why in its readme and UI.

docs-site/docs/plugin-development/api/server.md

@@ -0,0 +1,81 @@
+---
+sidebar_position: 4
+---
+
+# Server API
+
+The server API reads the active server, registers plugin-owned users, and updates server settings or permissions.
+
+## Required Capabilities
+
+| Method | Capability |
+| --- | --- |
+| `server.getCurrent()` | `server.read` |
+| `server.registerPluginUser(request)` | `users.manage` |
+| `server.updatePermissions(permissions)` | `server.manage` |
+| `server.updateSettings(settings)` | `server.manage` |
+
+## Read Current Server
+
+```js
+export function activate(context) {
+  const server = context.api.server.getCurrent();
+
+  context.api.logger.info('Current server', {
+    id: server?.id,
+    name: server?.name,
+    topic: server?.topic,
+    isPrivate: server?.isPrivate
+  });
+}
+```
+
+## Register a Plugin User
+
+Plugin users are useful for bot-style messages.
+
+```js
+export function activate(context) {
+  const botUserId = context.api.server.registerPluginUser({
+    id: 'standup-helper-bot',
+    displayName: 'Standup Helper',
+    avatarUrl: 'https://cdn.example.com/metoyou/plugins/standup-helper.png'
+  });
+
+  context.api.messages.sendAsPluginUser({
+    pluginUserId: botUserId,
+    channelId: 'general',
+    content: 'Standup reminder: share yesterday, today, and blockers.'
+  });
+}
+```
+
+Capabilities required: `users.manage` and `messages.send`.
+
+## Update Server Settings
+
+```js
+export function activate(context) {
+  context.api.server.updateSettings({
+    name: 'Friday Game Night',
+    topic: 'Co-op games, voice chat, and clips',
+    description: 'A friendly server for Friday sessions.',
+    maxUsers: 64,
+    isPrivate: false
+  });
+}
+```
+
+## Update Permissions
+
+```js
+export function activate(context) {
+  context.api.server.updatePermissions({
+    allowVoice: true,
+    allowVideo: true,
+    allowScreenShare: true
+  });
+}
+```
+
+Only update settings or permissions as part of an explicit admin flow. Plugins should not silently rename servers or change access rules.

docs-site/docs/plugin-development/api/storage.md

@@ -0,0 +1,101 @@
+---
+sidebar_position: 10
+---
+
+# Storage API
+
+Plugins can store local client data and per-server data. Desktop builds use Electron persistence when available; browser fallback uses renderer storage.
+
+## Required Capabilities
+
+| Method | Capability |
+| --- | --- |
+| `clientData.read(key)` | `storage.local` |
+| `clientData.write(key, value)` | `storage.local` |
+| `clientData.remove(key)` | `storage.local` |
+| `serverData.read(key)` | `storage.serverData.read` |
+| `serverData.write(key, value)` | `storage.serverData.write` |
+| `serverData.remove(key)` | `storage.serverData.write` |
+| `storage.get(key)` | `storage.local` |
+| `storage.set(key, value)` | `storage.local` |
+| `storage.remove(key)` | `storage.local` |
+
+## Client Data
+
+Client data belongs to this local user and client.
+
+```js
+export async function activate(context) {
+  await context.api.clientData.write('soundboard:volume', {
+    masterVolume: 0.7,
+    updatedAt: 1777473600000
+  });
+
+  const value = await context.api.clientData.read('soundboard:volume');
+
+  context.api.logger.info('Loaded client data', value);
+}
+```
+
+## Server Data
+
+Server data is local per-user/per-server state. It is not arbitrary signal-server persistence.
+
+```js
+export async function activate(context) {
+  await context.api.serverData.write('soundboard:favorites', [
+    { id: 'chime', label: 'Chime', url: 'https://cdn.example.com/chime.wav' },
+    { id: 'ready', label: 'Ready Check', url: 'https://cdn.example.com/ready.wav' }
+  ]);
+
+  const favorites = await context.api.serverData.read('soundboard:favorites');
+
+  context.api.logger.info('Loaded server favorites', favorites);
+}
+```
+
+## Remove Data
+
+```js
+export async function activate(context) {
+  await context.api.clientData.remove('soundboard:volume');
+  await context.api.serverData.remove('soundboard:favorites');
+}
+```
+
+## Legacy Synchronous Storage
+
+The `storage.*` methods are legacy local storage helpers. Prefer `clientData.*` for new plugins when async reads are acceptable.
+
+```js
+export function activate(context) {
+  context.api.storage.set('quick-toggle', { enabled: true });
+
+  const saved = context.api.storage.get('quick-toggle');
+
+  context.api.logger.info('Legacy storage value', saved);
+
+  context.api.storage.remove('quick-toggle');
+}
+```
+
+## Manifest Data Declarations
+
+Declare important data keys in the manifest.
+
+```json
+{
+  "data": [
+    {
+      "key": "soundboard:volume",
+      "scope": "client",
+      "storage": "local"
+    },
+    {
+      "key": "soundboard:favorites",
+      "scope": "server",
+      "storage": "serverData"
+    }
+  ]
+}
+```

docs-site/docs/plugin-development/api/ui.md

@@ -0,0 +1,235 @@
+---
+sidebar_position: 11
+---
+
+# UI API
+
+The UI API lets plugins add pages, settings pages, side panels, channel sections, actions, embed renderers, and controlled DOM mounts.
+
+Prefer registered UI contributions over direct DOM mounting. Contribution APIs let Angular render the plugin UI when the matching app surface exists. Direct DOM mounting runs immediately and throws if the target selector is not present.
+
+## Required Capabilities
+
+| Method | Capability |
+| --- | --- |
+| `ui.registerAppPage(id, contribution)` | `ui.pages` |
+| `ui.registerSettingsPage(id, contribution)` | `ui.settings` |
+| `ui.registerSidePanel(id, contribution)` | `ui.sidePanel` |
+| `ui.registerChannelSection(id, contribution)` | `ui.channelsSection` |
+| `ui.registerComposerAction(id, contribution)` | `ui.pages` |
+| `ui.registerProfileAction(id, contribution)` | `ui.pages` |
+| `ui.registerToolbarAction(id, contribution)` | `ui.pages` |
+| `ui.registerEmbedRenderer(id, contribution)` | `ui.embeds` |
+| `ui.mountElement(id, request)` | `ui.dom` |
+
+Every registration returns a disposable. Push it into `context.subscriptions`.
+
+## App Page
+
+```js
+export function activate(context) {
+  context.subscriptions.push(context.api.ui.registerAppPage('dashboard', {
+    label: 'Raid Dashboard',
+    path: '/plugins/example.raid-helper/dashboard',
+    render: () => {
+      const root = document.createElement('section');
+      root.innerHTML = '<h1>Raid Dashboard</h1><p>Tonight: dungeon practice.</p>';
+      return root;
+    }
+  }));
+}
+```
+
+The page is hosted by `/plugins/:pluginId/:pageId`.
+
+## Settings Page
+
+```js
+export function activate(context) {
+  context.subscriptions.push(context.api.ui.registerSettingsPage('preferences', {
+    label: 'Raid Helper',
+    settingsKey: 'raid-helper',
+    order: 20,
+    render: () => {
+      const wrapper = document.createElement('section');
+      const label = document.createElement('label');
+      const checkbox = document.createElement('input');
+
+      checkbox.type = 'checkbox';
+      checkbox.checked = true;
+      label.append(checkbox, ' Enable ready-check reminders');
+      wrapper.append(label);
+      return wrapper;
+    }
+  }));
+}
+```
+
+## Side Panel
+
+Use `ui.registerSidePanel` for content that belongs in the server sidebar plugin area. Do not mount directly into `[data-testid="plugin-room-side-panel"]`; that host is route-specific and may not exist during plugin activation.
+
+```js
+export function activate(context) {
+  context.subscriptions.push(context.api.ui.registerSidePanel('soundboard', {
+    label: 'Soundboard',
+    order: 10,
+    render: () => {
+      const panel = document.createElement('div');
+      const button = document.createElement('button');
+
+      button.type = 'button';
+      button.textContent = 'Play chime';
+      button.onclick = () => context.api.media.playAudioClip({
+        url: 'https://cdn.example.com/chime.wav',
+        volume: 0.6
+      });
+      panel.append(button);
+      return panel;
+    }
+  }));
+}
+```
+
+Capabilities required: `ui.sidePanel` and `media.playAudio`.
+
+## Channel Section
+
+```js
+export function activate(context) {
+  context.subscriptions.push(context.api.ui.registerChannelSection('events', {
+    label: 'Event Rooms',
+    type: 'custom',
+    order: 50
+  }));
+}
+```
+
+## Composer Action
+
+```js
+export function activate(context) {
+  context.subscriptions.push(context.api.ui.registerComposerAction('insert-standup', {
+    icon: 'ST',
+    label: 'Insert standup prompt',
+    run: (actionContext) => {
+      context.api.messages.send(
+        'Standup: yesterday I..., today I..., blocked by...',
+        actionContext.textChannel?.id
+      );
+    }
+  }));
+}
+```
+
+Capabilities required: `ui.pages` and `messages.send`.
+
+## Profile Action
+
+```js
+export function activate(context) {
+  context.subscriptions.push(context.api.ui.registerProfileAction('wave', {
+    label: 'Wave',
+    run: (actionContext) => {
+      context.api.messages.send(`Waving at ${actionContext.user?.displayName ?? 'someone'}!`);
+    }
+  }));
+}
+```
+
+## Toolbar Action
+
+```js
+export function activate(context) {
+  context.subscriptions.push(context.api.ui.registerToolbarAction('open-dashboard', {
+    label: 'Raid Helper',
+    run: () => {
+      context.api.logger.info('Open the Raid Helper plugin page from /plugins/example.raid-helper/dashboard');
+    }
+  }));
+}
+```
+
+## Embed Renderer
+
+```js
+export function activate(context) {
+  context.subscriptions.push(context.api.ui.registerEmbedRenderer('raid-card', {
+    embedType: 'raid.card',
+    render: (payload) => {
+      const card = document.createElement('article');
+      const title = document.createElement('h3');
+      const body = document.createElement('p');
+
+      title.textContent = payload?.title ?? 'Raid';
+      body.textContent = payload?.description ?? 'No description provided.';
+      card.append(title, body);
+      return card;
+    }
+  }));
+}
+```
+
+Example message content for this embed:
+
+```text
+toju:embed:raid.card:{"title":"Friday Raid","description":"Meet in Lobby at 20:00."}
+```
+
+## DOM Mount
+
+Use DOM mounting only when normal UI contribution points are not enough. `ui.mountElement` resolves its target immediately. If the target does not exist, plugin activation fails with `Plugin mount target not found: <selector>`.
+
+Safe uses:
+
+- Mounting a global overlay, badge, or modal into `body` during activation.
+- Mounting into a route-specific element only after checking that element exists.
+
+Avoid:
+
+- Mounting sidebar content into `[data-testid="plugin-room-side-panel"]`. Use `ui.registerSidePanel`.
+- Mounting chat content into `app-chat-messages` during activation without checking for the element.
+
+```js
+export function activate(context) {
+  const badge = document.createElement('div');
+  badge.textContent = 'Raid helper active';
+  badge.style.position = 'fixed';
+  badge.style.right = '16px';
+  badge.style.bottom = '16px';
+  badge.style.padding = '8px 10px';
+  badge.style.background = '#111827';
+  badge.style.color = 'white';
+  badge.style.borderRadius = '6px';
+
+  context.subscriptions.push(context.api.ui.mountElement('active-badge', {
+    target: 'body',
+    position: 'beforeend',
+    element: badge
+  }));
+}
+```
+
+Route-specific mount example with a guard:
+
+```js
+export function activate(context) {
+  const target = document.querySelector('app-chat-messages');
+
+  if (!target) {
+    context.api.logger.warn('Chat messages host is not rendered yet; skipping chat mount');
+    return;
+  }
+
+  const banner = document.createElement('div');
+  banner.textContent = 'Raid helper active in this chat.';
+
+  context.subscriptions.push(context.api.ui.mountElement('chat-banner', {
+    target,
+    position: 'afterbegin',
+    element: banner
+  }));
+}
+```
+
+The runtime tags plugin-owned DOM and removes it on unload, but plugins should still keep mounts minimal and accessible.

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.