@shadowob/openclaw-shadowob 1.1.7 → 1.1.8

package/dist/{chunk-XOO7S6K5.js → chunk-6B7WPA2D.js}

@@ -216,10 +216,13 @@ async function getDataDir() {
 // src/monitor/media.ts
 function isShadowResolvableMediaUrl(url) {
   if (url.startsWith("/")) {
-    return url.includes("/uploads/") || url.startsWith("/api/media/signed/");
+    return url.includes("/uploads/") || url.includes("/voice/") || url.startsWith("/api/media/signed/");
   }
   return url.startsWith("http");
 }
+function visibleMessageText(text) {
+  return text.replace(/\u200B/gu, "").trim();
+}
 function inferMimeType(filename, headerType) {
   const ext = filename.split(".").pop()?.toLowerCase() ?? "";
   const map = {
@@ -240,7 +243,12 @@ function inferMimeType(filename, headerType) {
 }
 async function resolveShadowInboundMediaContext(params) {
   const { account, message, rawBody, runtime } = params;
-  const attachmentUrls = (message.attachments ?? []).map((a) => a.url).filter(Boolean);
+  const attachments = message.attachments ?? [];
+  const attachmentUrls = attachments.map((a) => a.url).filter(Boolean);
+  const voiceAttachment = attachments.find(
+    (attachment) => attachment.kind === "voice" || String(attachment.contentType ?? "").startsWith("audio/")
+  );
+  const voiceTranscript = voiceAttachment?.transcript?.status === "ready" && voiceAttachment.transcript.text?.trim() ? voiceAttachment.transcript.text.trim() : "";
   const markdownMediaRegex = /!?\[[^\]]*\]\(([^)]+)\)/g;
   const markdownUrls = [];
   for (const mdMatch of rawBody.matchAll(markdownMediaRegex)) {
@@ -280,10 +288,22 @@ async function resolveShadowInboundMediaContext(params) {
       runtime.error?.(`[media] Failed to download ${rawUrl}: ${String(err)}`);
     }
   }
+  const bodyWithoutMedia = rawBody.replace(
+    /!?\[[^\]]*\]\((?:[^)]*\/uploads\/[^)]+|[^)]*\/voice\/[^)]+|[^)]*\/api\/media\/signed\/[^)]+)\)/g,
+    ""
+  ).replace(/\u200B/gu, "").replace(/\n{2,}/g, "\n").trim();
+  const cleanBody = bodyWithoutMedia || (voiceTranscript && !visibleMessageText(rawBody) ? voiceTranscript : "") || voiceTranscript || "[Media attached]";
+  const voiceFields = voiceAttachment ? {
+    VoiceMessage: true,
+    VoiceAttachmentId: voiceAttachment.id,
+    VoiceDurationMs: voiceAttachment.durationMs ?? null,
+    VoiceWaveformPeaks: voiceAttachment.waveformPeaks ?? null,
+    VoiceTranscript: voiceAttachment.transcript?.text ?? null,
+    VoiceTranscriptStatus: voiceAttachment.transcript?.status ?? null
+  } : {};
   if (localMediaPaths.length === 0) {
-    return { cleanBody: rawBody, fields: {} };
+    return { cleanBody, fields: voiceFields };
   }
-  const cleanBody = rawBody.replace(/!?\[[^\]]*\]\((?:[^)]*\/uploads\/[^)]+|[^)]*\/api\/media\/signed\/[^)]+)\)/g, "").replace(/\n{2,}/g, "\n").trim() || "[Media attached]";
   return {
     cleanBody,
     fields: {
@@ -292,7 +312,8 @@ async function resolveShadowInboundMediaContext(params) {
       MediaUrl: resolvedMediaUrls[0],
       MediaUrls: resolvedMediaUrls,
       MediaType: localMediaTypes[0],
-      MediaTypes: localMediaTypes
+      MediaTypes: localMediaTypes,
+      ...voiceFields
     }
   };
 }
@@ -303,6 +324,20 @@ function normalizeTriggerUserIds(policyConfig) {
   if (!Array.isArray(value)) return null;
   return value.filter((item) => typeof item === "string" && item.length > 0);
 }
+function messageHasActiveTaskForBot(message, botUserId) {
+  const cards = message.metadata?.cards;
+  if (!Array.isArray(cards)) return false;
+  return cards.some((card) => {
+    if (!card || typeof card !== "object" || Array.isArray(card)) return false;
+    const record = card;
+    if (record.kind !== "task") return false;
+    if (record.status === "completed" || record.status === "failed" || record.status === "canceled" || record.status === "transferred") {
+      return false;
+    }
+    const assignee = record.assignee && typeof record.assignee === "object" && !Array.isArray(record.assignee) ? record.assignee : null;
+    return assignee?.userId === botUserId;
+  });
+}
 function evaluateShadowMessagePreflight(params) {
   const { message, botUserId, botUsername, channelPolicies, runtime } = params;
   const senderLabel = message.author?.username ?? message.authorId;
@@ -375,7 +410,7 @@ function evaluateShadowMessagePreflight(params) {
   const structuredMentions = getShadowMessageMentions(message);
   const escapedBotUsername = botUsername.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
   const mentionRegex = new RegExp(`@${escapedBotUsername}(?:\\s|$)`, "i");
-  const wasMentionedExplicitly = mentionTargetsBot({ mentions: structuredMentions, botUserId, botUsername }) || mentionsTargetServerApp(structuredMentions) || mentionRegex.test(message.content);
+  const wasMentionedExplicitly = mentionTargetsBot({ mentions: structuredMentions, botUserId, botUsername }) || mentionsTargetServerApp(structuredMentions) || messageHasActiveTaskForBot(message, botUserId) || mentionRegex.test(message.content);
   if (policy?.mentionOnly && !wasMentionedExplicitly) {
     return {
       ok: false,
@@ -506,7 +541,7 @@ async function deliverShadowReply(params) {
           await withDeliveryRetry({
             label: "reply-media",
             runtime,
-            operation: () => client.uploadMediaFromUrl(mediaUrl, messageId)
+            operation: () => client.uploadMediaFromUrl(mediaUrl, { messageId })
           });
           runtime.log?.("[reply] Media uploaded successfully");
         } catch (err) {
@@ -1187,6 +1222,50 @@ function normalizeStringList(value) {
   if (!Array.isArray(value)) return [];
   return value.filter((item) => typeof item === "string" && item.trim().length > 0);
 }
+function isRuntimeTaskCard(card) {
+  return card.kind === "task" && typeof card.id === "string" && typeof card.title === "string" && typeof card.status === "string";
+}
+function isTerminalTaskStatus(status) {
+  return status === "completed" || status === "failed" || status === "canceled" || status === "transferred";
+}
+function taskClaimExpired(card) {
+  if (!card.claim?.expiresAt) return true;
+  return new Date(card.claim.expiresAt).getTime() <= Date.now();
+}
+function findRuntimeTaskCard(message, botUserId) {
+  const cards = message.metadata?.cards;
+  if (!Array.isArray(cards)) return null;
+  return cards.find(
+    (card) => isRuntimeTaskCard(card) && card.assignee?.userId === botUserId && !isTerminalTaskStatus(card.status)
+  ) ?? null;
+}
+function findTaskCardById(message, cardId) {
+  const cards = message?.metadata?.cards;
+  if (!Array.isArray(cards)) return null;
+  return cards.find((card) => isRuntimeTaskCard(card) && card.id === cardId) ?? null;
+}
+function taskCardPrompt(message, card) {
+  const workspaceId = card.data?.task && typeof card.data.task.workspaceId === "string" ? card.data.task.workspaceId : void 0;
+  const claimId = typeof card.claim?.id === "string" ? card.claim.id : void 0;
+  return [
+    "Shadow Inbox task:",
+    `Task message id: ${message.id}`,
+    `Task card id: ${card.id}`,
+    claimId ? `Task claim id: ${claimId}` : "",
+    workspaceId ? `Task workspace id: ${workspaceId}` : "",
+    `Task status: ${card.status}`,
+    `Task title: ${card.title}`,
+    card.priority ? `Task priority: ${card.priority}` : "",
+    card.body ? `Task body:
+${card.body}` : "",
+    card.source ? `Task source: ${JSON.stringify(card.source)}` : "",
+    claimId ? [
+      "When calling Shadow Server App commands for this task, bind the call with:",
+      `--task-message-id ${message.id} --task-card-id ${card.id} --task-claim-id ${claimId}`
+    ].join("\n") : "",
+    "When you complete useful work for this task, reply with the concrete result and any next action."
+  ].filter(Boolean).join("\n");
+}
 function isSenderCommandAuthorized(policyConfig, senderId) {
   const triggerUserIds = normalizeStringList(
     policyConfig?.allowedTriggerUserIds ?? policyConfig?.triggerUserIds
@@ -1361,6 +1440,31 @@ async function processShadowMessage(params) {
   });
   runtime.log?.(`[routing] Resolved agent: ${route.agentId} (account ${accountId})`);
   const mediaClient = new ShadowClient2(account.serverUrl, account.token);
+  let runtimeTaskCard = findRuntimeTaskCard(message, botUserId);
+  if (runtimeTaskCard && (runtimeTaskCard.status === "queued" || (runtimeTaskCard.status === "claimed" || runtimeTaskCard.status === "running") && taskClaimExpired(runtimeTaskCard))) {
+    try {
+      const claimed = await mediaClient.claimTaskCard(message.id, runtimeTaskCard.id, {
+        ttlSeconds: 3600,
+        note: "OpenClaw runtime claimed task"
+      });
+      runtimeTaskCard = findTaskCardById(claimed, runtimeTaskCard.id) ?? runtimeTaskCard;
+    } catch (err) {
+      runtime.error?.(`[task] Failed claiming task card ${runtimeTaskCard.id}: ${String(err)}`);
+      return;
+    }
+  }
+  if (runtimeTaskCard && runtimeTaskCard.status === "claimed") {
+    await mediaClient.updateTaskCard(message.id, runtimeTaskCard.id, {
+      status: "running",
+      note: "OpenClaw runtime started work"
+    }).then((updated) => {
+      runtimeTaskCard = findTaskCardById(updated, runtimeTaskCard.id) ?? runtimeTaskCard;
+    }).catch((err) => {
+      runtime.error?.(
+        `[task] Failed marking task card ${runtimeTaskCard?.id} running: ${String(err)}`
+      );
+    });
+  }
   const mediaContext = await resolveShadowInboundMediaContext({
     account,
     message,
@@ -1425,6 +1529,7 @@ async function processShadowMessage(params) {
     viewerCommerceContext,
     mentionContext,
     serverAppContext.prompt,
+    runtimeTaskCard ? taskCardPrompt(message, runtimeTaskCard) : "",
     messageBodyForAgent
   ].filter(Boolean).join("\n\n");
   const body = core.channel.reply.formatAgentEnvelope({
@@ -1437,6 +1542,7 @@ async function processShadowMessage(params) {
   const escapedBotUsername = botUsername.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
   const mentionRegex = new RegExp(`@${escapedBotUsername}(?:\\s|$)`, "i");
   const wasMentioned = mentionTargetsBot({ mentions: structuredMentions, botUserId, botUsername }) || mentionsTargetServerApp(structuredMentions) || Boolean(slashCommandMatch) || mentionRegex.test(message.content);
+  const taskSessionKey = runtimeTaskCard ? `${route.sessionKey}:task:${runtimeTaskCard.id}` : route.sessionKey;
   const ctxPayload = core.channel.reply.finalizeInboundContext({
     Body: body,
     BodyForAgent: bodyForAgent,
@@ -1447,7 +1553,7 @@ async function processShadowMessage(params) {
     CommandSource: "text",
     From: `shadowob:user:${senderId}`,
     To: `shadowob:channel:${channelId}`,
-    SessionKey: route.sessionKey,
+    SessionKey: taskSessionKey,
     AccountId: route.accountId,
     ChatType: chatType,
     ConversationLabel: conversationLabel,
@@ -1473,6 +1579,12 @@ async function processShadowMessage(params) {
     } : {},
     BotUserId: botUserId,
     BotUsername: botUsername,
+    ...runtimeTaskCard ? {
+      TaskCardId: runtimeTaskCard.id,
+      TaskCardTitle: runtimeTaskCard.title,
+      TaskCardStatus: runtimeTaskCard.status,
+      TaskCardPriority: runtimeTaskCard.priority
+    } : {},
     AgentId: route.agentId,
     ChannelId: channelId,
     ...slashCommandMatch ? {
@@ -1593,9 +1705,29 @@ async function processShadowMessage(params) {
     }).catch((err) => {
       runtime.error?.(`[usage] Failed to report usage snapshot for ${message.id}: ${String(err)}`);
     });
+    if (runtimeTaskCard) {
+      await client.updateTaskCard(message.id, runtimeTaskCard.id, {
+        status: "completed",
+        note: "OpenClaw runtime completed reply dispatch"
+      }).catch((err) => {
+        runtime.error?.(
+          `[task] Failed marking task card ${runtimeTaskCard?.id} completed: ${String(err)}`
+        );
+      });
+    }
     socket.updateActivity(channelId, "ready");
   } catch (err) {
     runtime.error?.(`[msg] AI dispatch failed for message ${message.id}: ${String(err)}`);
+    if (runtimeTaskCard) {
+      await client.updateTaskCard(message.id, runtimeTaskCard.id, {
+        status: "failed",
+        note: `OpenClaw runtime failed: ${String(err)}`.slice(0, 4e3)
+      }).catch((updateErr) => {
+        runtime.error?.(
+          `[task] Failed marking task card ${runtimeTaskCard?.id} failed: ${String(updateErr)}`
+        );
+      });
+    }
     socket.updateActivity(channelId, null);
     throw err;
   } finally {

package/dist/index.js

@@ -15,7 +15,7 @@ import {
   resolveOutboundMentions,
   setShadowRuntime,
   tryGetShadowRuntime
-} from "./chunk-XOO7S6K5.js";
+} from "./chunk-6B7WPA2D.js";
 
 // index.ts
 import { defineChannelPluginEntry } from "openclaw/plugin-sdk/core";
@@ -151,7 +151,7 @@ async function sendMediaToShadow(params) {
   const uploadErrors = [];
   for (const mediaUrl of mediaUrls) {
     try {
-      await params.client.uploadMediaFromUrl(mediaUrl, sent.message.id);
+      await params.client.uploadMediaFromUrl(mediaUrl, { messageId: sent.message.id });
     } catch (err) {
       const fallback = await sendTextChunks({
         client: params.client,
@@ -507,6 +507,20 @@ var shadowMessageToolSchemaProperties = {
   filename: optionalSchema(stringSchema("Attachment filename when buffer is used.")),
   contentType: optionalSchema(stringSchema("Attachment MIME type when buffer is used.")),
   mimeType: optionalSchema(stringSchema("Alias for contentType.")),
+  attachmentKind: optionalSchema(
+    enumSchema(["file", "image", "voice"], "Use voice when sending a Shadow voice message.")
+  ),
+  durationMs: optionalSchema(numberSchema("Voice message duration in milliseconds.")),
+  waveformPeaks: optionalSchema(
+    arraySchema(numberSchema("Voice waveform peak from 0 to 100."), {
+      minItems: 32,
+      maxItems: 96
+    })
+  ),
+  transcript: optionalSchema(stringSchema("Optional transcript text for a voice message.")),
+  transcriptLanguage: optionalSchema(
+    stringSchema("Optional BCP-47 transcript language, e.g. zh-CN.")
+  ),
   caption: optionalSchema(stringSchema("Optional text sent with an attachment.")),
   commerceOfferId: optionalSchema(
     stringSchema("Shadow CommerceOfferId to attach as a purchasable product card.")
@@ -533,7 +547,14 @@ function buildShadowMessageToolSchemaProperties(input) {
 }
 
 // src/channel/actions.ts
-var SHADOW_DISCOVERED_ACTIONS = ["send", "upload-file", "react", "edit", "delete"];
+var SHADOW_DISCOVERED_ACTIONS = [
+  "send",
+  "upload-file",
+  "send-voice",
+  "react",
+  "edit",
+  "delete"
+];
 var SHADOW_HANDLED_ACTIONS = [...SHADOW_DISCOVERED_ACTIONS, "get-connection-status"];
 function textResult(value) {
   return {
@@ -571,6 +592,39 @@ function readAttachmentFilename(params) {
 function readCommerceOfferId(params) {
   return firstString(params.commerceOfferId, params.offerId);
 }
+function readNumber(params, ...keys) {
+  for (const key of keys) {
+    const value = params[key];
+    if (typeof value === "number" && Number.isFinite(value)) return value;
+    if (typeof value === "string" && value.trim()) {
+      const parsed = Number(value);
+      if (Number.isFinite(parsed)) return parsed;
+    }
+  }
+  return void 0;
+}
+function readWaveformPeaks(params) {
+  const value = params.waveformPeaks ?? params.waveform_peaks;
+  if (Array.isArray(value)) {
+    const peaks = value.map((item) => Number(item));
+    return peaks.every((item) => Number.isInteger(item) && item >= 0 && item <= 100) ? peaks : void 0;
+  }
+  if (typeof value === "string" && value.trim()) {
+    try {
+      const parsed = JSON.parse(value);
+      if (!Array.isArray(parsed)) return void 0;
+      const peaks = parsed.map((item) => Number(item));
+      return peaks.every((item) => Number.isInteger(item) && item >= 0 && item <= 100) ? peaks : void 0;
+    } catch {
+      return void 0;
+    }
+  }
+  return void 0;
+}
+function readAttachmentKind(params) {
+  const kind = firstString(params.attachmentKind, params.kind);
+  return kind === "voice" || kind === "image" || kind === "file" ? kind : void 0;
+}
 function buildSendMetadata(params) {
   const metadata = {};
   if (params.interactiveBlock) metadata.interactive = params.interactiveBlock;
@@ -585,16 +639,36 @@ async function uploadShadowAttachment(params) {
   const uploadTarget = params.messageId;
   const base64Buffer = firstString(params.actionParams.buffer);
   const mediaUrl = readAttachmentSource(params.actionParams);
+  const kind = readAttachmentKind(params.actionParams);
+  const durationMs = readNumber(params.actionParams, "durationMs", "duration_ms");
+  const waveformPeaks = readWaveformPeaks(params.actionParams);
+  const transcriptText = firstString(
+    params.actionParams.transcript,
+    params.actionParams.transcriptText
+  );
+  const transcriptLanguage = firstString(
+    params.actionParams.transcriptLanguage,
+    params.actionParams.transcript_language
+  );
+  const uploadOptions = { messageId: uploadTarget };
+  if (kind) uploadOptions.kind = kind;
+  if (typeof durationMs === "number") uploadOptions.durationMs = durationMs;
+  if (waveformPeaks) uploadOptions.waveformPeaks = waveformPeaks;
+  if (transcriptText) {
+    uploadOptions.transcriptText = transcriptText;
+    uploadOptions.transcriptSource = "runtime";
+  }
+  if (transcriptLanguage) uploadOptions.transcriptLanguage = transcriptLanguage;
   if (base64Buffer) {
     const raw = base64Buffer.includes(",") ? base64Buffer.split(",")[1] ?? "" : base64Buffer;
     if (!raw) throw new Error("Invalid base64 attachment payload");
     const bytes = Buffer.from(raw, "base64");
     const blob = new Blob([Uint8Array.from(bytes)], { type: contentType });
-    await params.client.uploadMedia(blob, filename, contentType, uploadTarget);
+    await params.client.uploadMedia(blob, filename, contentType, uploadOptions);
     return { filename, contentType, source: "buffer" };
   }
   if (mediaUrl) {
-    await params.client.uploadMediaFromUrl(mediaUrl, uploadTarget);
+    await params.client.uploadMediaFromUrl(mediaUrl, uploadOptions);
     return { filename, contentType, source: "media", mediaUrl };
   }
   throw new Error("No buffer or media URL provided for attachment");
@@ -624,12 +698,14 @@ var shadowMessageActions = {
           "file",
           "fileUrl",
           "buffer"
-        ]
+        ],
+        "send-voice": ["media", "mediaUrl", "url", "path", "filePath", "file", "fileUrl", "buffer"]
       }
     };
   },
   messageActionTargetAliases: {
-    "upload-file": { aliases: ["recipient", "to", "channelId"] }
+    "upload-file": { aliases: ["recipient", "to", "channelId"] },
+    "send-voice": { aliases: ["recipient", "to", "channelId"] }
   },
   supportsAction: ({ action }) => SHADOW_HANDLED_ACTIONS.includes(action),
   handleAction: async (ctx) => {
@@ -686,7 +762,7 @@ var shadowMessageActions = {
         return textResult({ ok: false, error: err instanceof Error ? err.message : String(err) });
       }
     }
-    if (action === "upload-file") {
+    if (action === "upload-file" || action === "send-voice") {
       try {
         const client = new ShadowClient2(account.serverUrl, account.token);
         const to = readMessageTarget(params);
@@ -697,24 +773,35 @@ var shadowMessageActions = {
             error: "upload-file requires buffer, media, path, or filePath"
           });
         }
-        const text = firstString(params.message, params.content, params.text, params.caption) ?? "";
+        const attachmentParams = action === "send-voice" ? { ...params, kind: "voice", attachmentKind: "voice" } : params;
+        if (action === "send-voice") {
+          if (readNumber(attachmentParams, "durationMs", "duration_ms") === void 0) {
+            return textResult({ ok: false, error: "send-voice requires durationMs" });
+          }
+        }
+        const text = firstString(
+          attachmentParams.message,
+          attachmentParams.content,
+          attachmentParams.text,
+          attachmentParams.caption
+        ) ?? "";
         const message = await sendShadowMessage({
           client,
           to,
           content: text || "\u200B",
-          threadId: params.threadId,
-          replyToId: params.replyTo ?? params.replyToId
+          threadId: attachmentParams.threadId,
+          replyToId: attachmentParams.replyTo ?? attachmentParams.replyToId
         });
         const attachment = await uploadShadowAttachment({
           client,
           to,
           messageId: message.id,
-          actionParams: params
+          actionParams: attachmentParams
         });
         return textResult({
           ok: true,
           action: requestedAction,
-          canonicalAction: "upload-file",
+          canonicalAction: action,
           messageId: message.id,
           filename: attachment.filename
         });
@@ -960,7 +1047,7 @@ shadowPlugin.gateway = {
       lastError: null
     });
     ctx.log?.info(`Starting Shadow connection for account ${accountId}`);
-    const { monitorShadowProvider: monitorShadowProvider2 } = await import("./monitor-K7U33EFS.js");
+    const { monitorShadowProvider: monitorShadowProvider2 } = await import("./monitor-5FSCOBE4.js");
     await monitorShadowProvider2({
       account,
       accountId,

package/dist/{monitor-K7U33EFS.js → monitor-5FSCOBE4.js}

@@ -5,7 +5,7 @@ import {
   normalizeShadowSlashCommands,
   resolveShadowAgentIdFromConfig,
   shouldCatchUpShadowMessage
-} from "./chunk-XOO7S6K5.js";
+} from "./chunk-6B7WPA2D.js";
 export {
   formatSlashCommandPrompt,
   matchShadowSlashCommand,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shadowob/openclaw-shadowob",
-  "version": "1.1.7",
+  "version": "1.1.8",
   "description": "OpenClaw Shadow channel plugin — enables AI agents to interact in Shadow server channels",
   "type": "module",
   "main": "./dist/index.js",
@@ -58,7 +58,7 @@
   "dependencies": {
     "zod": "^3.25.67",
     "openclaw": "^2026.5.7",
-    "@shadowob/sdk": "1.1.7"
+    "@shadowob/sdk": "1.1.8"
   },
   "devDependencies": {
     "@types/node": "^22.15.21",

package/skills/shadowob/SKILL.md

@@ -282,12 +282,19 @@ shadowob app discover --server <server-id-or-slug> --json
 shadowob app inspect <app-key> --server <server-id-or-slug> --json
 shadowob app skills <app-key> --server <server-id-or-slug>
 shadowob app call <app-key> <command> --server <server-id-or-slug> --channel-id <channel-id> --json-input '<raw-command-input-json>' --json
+shadowob app call <app-key> <command> --server <server-id-or-slug> --help
+shadowob app call <app-key> <command> --server <server-id-or-slug> --file <path> --json-input '<raw-command-input-json>' --json
+shadowob app events <app-key> --server <server-id-or-slug> --json
 ```
 
 For server App commands, use the `shadowob app` CLI path only. Do not use curl, fetch, raw HTTP
 routes, or the JavaScript SDK to call server App commands. Pass the command input object directly
 to `--json-input`, for example `{"title":"Example","priority":"high"}`; the CLI wraps the HTTP
 request for you and binds Shadow OAuth identity, server membership, App grants, and command policy.
+Use progressive disclosure: start with `shadowob app skills` or `shadowob app discover`, then call
+`shadowob app call <app-key> <command> --server <server> --help` only when you need that command's
+full schema, file-upload support, or examples. For realtime app updates, subscribe with
+`shadowob app events <app-key> --server <server> --json` instead of polling.
 When a channel message mentions a server App, use the mentioned app key/server id directly and pass
 the current channel id with `--channel-id` when available. If a server App command requires
 approval, do not send a chat form or call the approval endpoint yourself as a Buddy. Wait for a