@shadowob/openclaw-shadowob 1.1.3-dev.281 → 1.1.4

package/dist/{chunk-ATPTVU3K.js → chunk-4G572ZLC.js}

@@ -22,6 +22,9 @@ function mentionTargetsBot(params) {
     return mention.username?.toLowerCase() === botUsername;
   });
 }
+function mentionsTargetServerApp(mentions) {
+  return mentions.some((mention) => mention.kind === "app" && (mention.appKey || mention.targetId));
+}
 function formatShadowMentionsForAgent(mentions) {
   if (mentions.length === 0) return "";
   const lines = mentions.map((mention) => {
@@ -32,6 +35,9 @@ function formatShadowMentionsForAgent(mentions) {
     if (mention.kind === "server") {
       return `- ${label} [server] serverId=${mention.serverId ?? mention.targetId} slug=${mention.serverSlug ?? ""}`;
     }
+    if (mention.kind === "app") {
+      return `- ${label} [server-app] appKey=${mention.appKey ?? mention.targetId} appId=${mention.appId ?? mention.targetId} serverId=${mention.serverId ?? ""} server=${mention.serverName ?? ""}`;
+    }
     if (mention.kind === "user" || mention.kind === "buddy") {
       return `- ${label} [${mention.kind}] userId=${mention.userId ?? mention.targetId} username=${mention.username ?? ""}`;
     }
@@ -40,8 +46,9 @@ function formatShadowMentionsForAgent(mentions) {
   return [
     "Shadow mentions:",
     ...lines,
-    "To mention a Shadow entity in a reply, write its visible handle (for example @username or #channel); Shadow will resolve it before delivery."
-  ].join("\n");
+    "To mention a Shadow entity in a reply, write its visible handle (for example @username or #channel); Shadow will resolve it before delivery.",
+    mentionsTargetServerApp(mentions) ? 'If a server app is mentioned, operate it through the Shadow CLI only: first run `shadowob app discover --server "<serverId-or-slug>" --json`, then run `shadowob app call "<appKey>" <command> --server "<serverId-or-slug>" --json-input \'<raw-command-input-json>\' --json`. Do not use curl, fetch, raw HTTP routes, or the JavaScript SDK for server-app commands. Use the mentioned appKey/serverId; do not ask the user to describe the CLI path.' : ""
+  ].filter(Boolean).join("\n");
 }
 function mentionContextFields(mentions) {
   if (mentions.length === 0) return {};
@@ -66,6 +73,14 @@ function mentionContextFields(mentions) {
       serverId: mention.serverId ?? mention.targetId,
       serverSlug: mention.serverSlug,
       serverName: mention.serverName
+    })),
+    MentionedApps: mentions.filter((mention) => mention.kind === "app").map((mention) => ({
+      appId: mention.appId ?? mention.targetId,
+      appKey: mention.appKey,
+      appName: mention.appName,
+      serverId: mention.serverId,
+      serverSlug: mention.serverSlug,
+      serverName: mention.serverName
     }))
   };
 }
@@ -162,6 +177,8 @@ async function buildInteractiveResponseContext(params) {
   const responsePrompt = sourceInteractive && typeof sourceInteractive === "object" && !Array.isArray(sourceInteractive) ? sourceInteractive.responsePrompt : void 0;
   const lines = [
     "Shadow interactive response received.",
+    "Use the submitted values once. Do not separately restate or grade the submitted form unless the source command explicitly asks for an evaluation.",
+    "If the next step is another Shadow interactive dialog, send that dialog only and do not add a separate normal text reply for the same step.",
     `Source message: ${source?.content ?? "(unavailable)"}`,
     typeof sourcePrompt === "string" && sourcePrompt.trim() ? `Source prompt: ${sourcePrompt.trim()}` : "",
     typeof responsePrompt === "string" && responsePrompt.trim() ? `Follow-up instruction: ${responsePrompt.trim()}` : "",
@@ -358,7 +375,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 }) || mentionRegex.test(message.content);
+  const wasMentionedExplicitly = mentionTargetsBot({ mentions: structuredMentions, botUserId, botUsername }) || mentionsTargetServerApp(structuredMentions) || mentionRegex.test(message.content);
   if (policy?.mentionOnly && !wasMentionedExplicitly) {
     return {
       ok: false,
@@ -543,6 +560,7 @@ function resolveSessionStore(cfg) {
 // src/monitor/slash-commands.ts
 import fsPromises2 from "fs/promises";
 var SLASH_COMMAND_RE = /^\/([a-zA-Z][a-zA-Z0-9._-]{0,63})(?:\s+([\s\S]*))?$/;
+var DEFAULT_SLASH_COMMANDS_PATH = "/etc/shadowob/slash-commands.json";
 function normalizeSlashCommandName(value) {
   if (typeof value !== "string") return null;
   const name = value.trim().replace(/^\/+/, "");
@@ -641,6 +659,7 @@ function normalizeShadowSlashCommands(input) {
       )
     ].filter((alias) => alias.toLowerCase() !== key) : void 0;
     const interaction = normalizeSlashInteraction(record.interaction);
+    const dispatch = readString(record.dispatch, 40);
     commands.push({
       name,
       ...typeof record.description === "string" && record.description.trim() ? { description: record.description.trim().slice(0, 240) } : {},
@@ -648,13 +667,14 @@ function normalizeShadowSlashCommands(input) {
       ...typeof record.packId === "string" && record.packId.trim() ? { packId: record.packId.trim().slice(0, 80) } : {},
       ...typeof record.sourcePath === "string" && record.sourcePath.trim() ? { sourcePath: record.sourcePath.trim().slice(0, 500) } : {},
       ...typeof record.body === "string" && record.body.trim() ? { body: record.body.trim().slice(0, 2e4) } : {},
+      ...dispatch === "agent" || dispatch === "passthrough" ? { dispatch } : {},
       ...interaction ? { interaction } : {}
     });
   }
   return commands.slice(0, 200);
 }
 function toPublicSlashCommands(commands) {
-  return commands.map(({ body: _body, ...command }) => command);
+  return commands.map(({ body: _body, dispatch: _dispatch, ...command }) => command);
 }
 async function fileExists(path) {
   try {
@@ -676,10 +696,27 @@ async function loadSlashCommandFile(indexPath, runtime) {
     return [];
   }
 }
+function logDuplicateSlashCommands(sources, runtime) {
+  const owners = /* @__PURE__ */ new Map();
+  for (const source of sources) {
+    for (const command of source.commands) {
+      const key = command.name.toLowerCase();
+      const existingPath = owners.get(key);
+      if (existingPath) {
+        runtime.log?.(
+          `[slash] Ignoring duplicate command /${command.name} from ${source.path}; already defined by ${existingPath}`
+        );
+        continue;
+      }
+      owners.set(key, source.path);
+    }
+  }
+}
 async function runtimeExtensionSlashCommandPaths(runtime) {
   const candidates = [
     process.env.SHADOW_RUNTIME_EXTENSIONS_PATH,
     process.env.OPENCLAW_RUNTIME_EXTENSIONS_PATH,
+    "/etc/shadowob/runtime-extensions.json",
     "/etc/openclaw/runtime-extensions.json"
   ].filter((path) => Boolean(path));
   const paths = [];
@@ -703,16 +740,25 @@ async function runtimeExtensionSlashCommandPaths(runtime) {
   return paths;
 }
 async function loadShadowSlashCommands(runtime) {
+  const defaultIndexPath = process.env.SHADOW_DEFAULT_SLASH_COMMANDS_PATH || DEFAULT_SLASH_COMMANDS_PATH;
   const paths = [
+    defaultIndexPath,
     process.env.SHADOW_SLASH_COMMANDS_PATH,
     ...await runtimeExtensionSlashCommandPaths(runtime)
   ].filter((path) => Boolean(path));
   const seenPaths = [...new Set(paths)];
-  const loaded = await Promise.all(seenPaths.map((path) => loadSlashCommandFile(path, runtime)));
-  const merged = normalizeShadowSlashCommands(loaded.flat());
-  if (seenPaths.length > 1) {
+  const existingPaths = (await Promise.all(seenPaths.map(async (path) => await fileExists(path) ? path : null))).filter((path) => Boolean(path));
+  const sources = await Promise.all(
+    existingPaths.map(async (path) => ({
+      path,
+      commands: await loadSlashCommandFile(path, runtime)
+    }))
+  );
+  logDuplicateSlashCommands(sources, runtime);
+  const merged = normalizeShadowSlashCommands(sources.flatMap((source) => source.commands));
+  if (existingPaths.length > 1) {
     runtime.log?.(
-      `[slash] Merged ${merged.length} slash command(s) from ${seenPaths.length} source(s)`
+      `[slash] Merged ${merged.length} slash command(s) from ${existingPaths.length} source(s)`
     );
   }
   return merged;
@@ -1137,6 +1183,66 @@ function buildChannelContextForAgent(info, channelId) {
     `Shadow channel id: ${channelId}`
   ].join("\n");
 }
+function normalizeStringList(value) {
+  if (!Array.isArray(value)) return [];
+  return value.filter((item) => typeof item === "string" && item.trim().length > 0);
+}
+function isSenderCommandAuthorized(policyConfig, senderId) {
+  const triggerUserIds = normalizeStringList(
+    policyConfig?.allowedTriggerUserIds ?? policyConfig?.triggerUserIds
+  );
+  if (triggerUserIds.length > 0) return triggerUserIds.includes(senderId);
+  const ownerId = typeof policyConfig?.ownerId === "string" ? policyConfig.ownerId.trim() : "";
+  if (ownerId && ownerId === senderId) return true;
+  const activeTenantIds = normalizeStringList(policyConfig?.activeTenantIds);
+  return activeTenantIds.includes(senderId);
+}
+function resolveOwnerAllowFrom(policyConfig) {
+  const ownerId = typeof policyConfig?.ownerId === "string" ? policyConfig.ownerId.trim() : "";
+  return ownerId ? [ownerId] : void 0;
+}
+async function buildMentionedServerAppSkillsContext(params) {
+  const appRefs = /* @__PURE__ */ new Map();
+  for (const mention of params.mentions) {
+    if (mention.kind !== "app") continue;
+    const appKey = mention.appKey ?? mention.targetId;
+    const server = mention.serverId ?? mention.serverSlug ?? params.serverInfo?.serverId;
+    if (!appKey || !server) continue;
+    appRefs.set(`${server}:${appKey}`, {
+      appKey,
+      server,
+      label: mention.label || mention.sourceToken || mention.token || appKey
+    });
+  }
+  if (appRefs.size === 0) return "";
+  const documents = await Promise.all(
+    Array.from(appRefs.values()).map(async (ref) => {
+      try {
+        const skill = await params.client.getServerAppSkills(ref.server, ref.appKey);
+        return [
+          `## ${ref.label}`,
+          `Server reference: ${ref.server}`,
+          `App key: ${ref.appKey}`,
+          "",
+          skill.markdown
+        ].join("\n");
+      } catch (err) {
+        params.runtime.error?.(
+          `[server-app] Failed loading skills for ${ref.appKey} on ${ref.server}: ${String(err)}`
+        );
+        return "";
+      }
+    })
+  );
+  const loaded = documents.filter(Boolean);
+  if (loaded.length === 0) return "";
+  return [
+    "Injected Shadow Server App Skills:",
+    "These instructions are authoritative for mentioned server apps in this message. Use the Shadow CLI path described below so Shadow can bind identity, app grants, and policy.",
+    "",
+    ...loaded
+  ].join("\n");
+}
 async function processShadowMessage(params) {
   const {
     message,
@@ -1198,6 +1304,7 @@ async function processShadowMessage(params) {
     slashCommands
   });
   const slashCommandMatch = matchShadowSlashCommand(cleanBody, slashCommands);
+  const slashCommandPassThrough = slashCommandMatch?.command.dispatch === "passthrough";
   if (slashCommandMatch) {
     runtime.log?.(
       `[slash] Matched /${slashCommandMatch.invokedName} -> /${slashCommandMatch.command.name}`
@@ -1220,17 +1327,22 @@ async function processShadowMessage(params) {
     });
     return;
   }
-  const baseBodyForAgent = slashCommandMatch ? formatSlashCommandPrompt(cleanBody, slashCommandMatch) : cleanBody;
+  const baseBodyForAgent = slashCommandMatch && !slashCommandPassThrough ? formatSlashCommandPrompt(cleanBody, slashCommandMatch) : cleanBody;
+  const commandBody = slashCommandPassThrough ? cleanBody : slashCommandMatch?.args ?? cleanBody;
+  const ownerAllowFrom = resolveOwnerAllowFrom(preflight.policyConfig);
   const structuredMentions = getShadowMessageMentions(message);
   const mentionContext = formatShadowMentionsForAgent(structuredMentions);
   const serverInfo = channelServerMap.get(channelId);
   const channelLabel = serverInfo ? `#${serverInfo.channelName}` : `channel:${channelId}`;
   const conversationLabel = serverInfo ? `${serverInfo.serverName} ${channelLabel}` : peerId;
-  const messageBodyForAgent = interactiveResponseContext.text ? `${interactiveResponseContext.text}
-
-User message:
-${baseBodyForAgent}` : baseBodyForAgent;
+  const messageBodyForAgent = interactiveResponseContext.text || baseBodyForAgent;
   const client = new ShadowClient2(account.serverUrl, account.token);
+  const serverAppSkillsContext = await buildMentionedServerAppSkillsContext({
+    mentions: structuredMentions,
+    client,
+    serverInfo,
+    runtime
+  });
   const viewerCommerceContext = await buildCommerceViewerContextForAgent({
     account,
     client,
@@ -1241,6 +1353,7 @@ ${baseBodyForAgent}` : baseBodyForAgent;
     buildCommerceContextForAgent(account),
     viewerCommerceContext,
     mentionContext,
+    serverAppSkillsContext,
     messageBodyForAgent
   ].filter(Boolean).join("\n\n");
   const body = core.channel.reply.formatAgentEnvelope({
@@ -1252,12 +1365,15 @@ ${baseBodyForAgent}` : baseBodyForAgent;
   });
   const escapedBotUsername = botUsername.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
   const mentionRegex = new RegExp(`@${escapedBotUsername}(?:\\s|$)`, "i");
-  const wasMentioned = mentionTargetsBot({ mentions: structuredMentions, botUserId, botUsername }) || mentionRegex.test(message.content);
+  const wasMentioned = mentionTargetsBot({ mentions: structuredMentions, botUserId, botUsername }) || mentionsTargetServerApp(structuredMentions) || Boolean(slashCommandMatch) || mentionRegex.test(message.content);
   const ctxPayload = core.channel.reply.finalizeInboundContext({
     Body: body,
     BodyForAgent: bodyForAgent,
     RawBody: rawBody,
-    CommandBody: slashCommandMatch?.args ?? cleanBody,
+    CommandBody: commandBody,
+    BodyForCommands: commandBody,
+    CommandAuthorized: isSenderCommandAuthorized(preflight.policyConfig, senderId),
+    CommandSource: "text",
     From: `shadowob:user:${senderId}`,
     To: `shadowob:channel:${channelId}`,
     SessionKey: route.sessionKey,
@@ -1274,6 +1390,8 @@ ${baseBodyForAgent}` : baseBodyForAgent;
     ...mentionContextFields(structuredMentions),
     OriginatingChannel: "shadowob",
     OriginatingTo: `shadowob:channel:${channelId}`,
+    NativeChannelId: channelId,
+    ...ownerAllowFrom ? { OwnerAllowFrom: ownerAllowFrom } : {},
     ...serverInfo ? {
       ServerId: serverInfo.serverId,
       ServerSlug: serverInfo.serverSlug,
@@ -1922,9 +2040,7 @@ async function monitorShadowProvider(options) {
                   channelName: ch.name
                 });
                 channelPolicies.set(ch.id, {
-                  listen: true,
-                  reply: true,
-                  mentionOnly: false,
+                  ...ch.policy,
                   config: { ...ch.policy.config, ...accessConfig2 }
                 });
                 if (!allChannelIds.includes(ch.id)) {
@@ -1945,9 +2061,6 @@ async function monitorShadowProvider(options) {
               if (channelServerMap.has(channelId)) continue;
               channelPolicies.set(channelId, {
                 ...existing2,
-                listen: true,
-                reply: true,
-                mentionOnly: false,
                 config: { ...existing2.config, ...accessConfig2 }
               });
             }
@@ -1958,23 +2071,24 @@ async function monitorShadowProvider(options) {
         })();
         return;
       }
-      const mentionOnly = false;
+      const existing = channelPolicies.get(data.channelId);
+      const mentionOnly = data.mentionOnly ?? existing?.mentionOnly ?? false;
+      const reply = data.reply ?? existing?.reply ?? true;
       const accessConfig = buildAccessPolicyConfig(remoteConfig);
       runtime.log?.(
-        `[ws] Received agent:policy-changed for channel ${data.channelId}: mentionOnly=${mentionOnly}, reply=${data.reply}, config=${JSON.stringify(data.config ?? {})}`
+        `[ws] Received agent:policy-changed for channel ${data.channelId}: mentionOnly=${mentionOnly}, reply=${reply}, config=${JSON.stringify(data.config ?? {})}`
       );
-      const existing = channelPolicies.get(data.channelId);
       if (existing) {
         channelPolicies.set(data.channelId, {
           ...existing,
           mentionOnly,
-          reply: true,
+          reply,
           config: { ...existing.config, ...accessConfig, ...data.config ?? {} }
         });
       } else {
         channelPolicies.set(data.channelId, {
           listen: true,
-          reply: true,
+          reply,
           mentionOnly,
           config: { ...accessConfig, ...data.config ?? {} }
         });

package/dist/index.js

@@ -15,7 +15,7 @@ import {
   resolveOutboundMentions,
   setShadowRuntime,
   tryGetShadowRuntime
-} from "./chunk-ATPTVU3K.js";
+} from "./chunk-4G572ZLC.js";
 
 // index.ts
 import { defineChannelPluginEntry } from "openclaw/plugin-sdk/core";
@@ -808,6 +808,7 @@ var shadowAgentPromptHints = [
   "- When a Shadow user asks for buttons, choices, a select menu, a form, or approval, prefer sending a Shadow interactive dialog instead of plain text options.",
   "- ShadowOwnBuddy enables inline buttons, forms, and file uploads for Shadow channels by default. Do not tell the user that `shadowob.capabilities.inlineButtons` or file sending is unavailable; use the message tool instead.",
   '- Shadow interactive dialogs use the shared message tool with `action: "send"` plus `target`, `message`, `kind`, `prompt`, and shape fields. `message` is required by the shared tool; set `message` and `prompt` to the same user-visible text unless there is a specific reason not to. Supported `kind` values are `buttons`, `select`, `form`, and `approval`; Shadow stores these as `metadata.interactive` so the user can answer in-channel.',
+  "- When your next action is a Shadow interactive dialog, put the full user-visible prompt in that dialog and do not also send a separate ordinary reply in the same turn. This prevents duplicate form-plus-commentary messages.",
   '- Example buttons dialog: `action: "send"`, `target: "shadowob:channel:<ChannelId>"`, `message: "Choose the next step"`, `kind: "buttons"`, `prompt: "Choose the next step"`, `buttons: [{"id":"icp","label":"ICP / JTBD","value":"icp"}]`.',
   '- Example form dialog: `action: "send"`, `target: "shadowob:channel:<ChannelId>"`, `message: "Fill the decision inputs"`, `kind: "form"`, `fields: [{"id":"decision","label":"Decision","kind":"textarea","required":true}]`.',
   '- When Shadow context includes CommerceOfferIds and the user is interested in buying, viewing pricing, or receiving a product card, call the shared message tool yourself: `action: "send"`, `target: "shadowob:channel:<ChannelId>"`, `message: "A natural sales message"`, `commerceOfferId: "<CommerceOfferId>"`. Plain final text will not attach a product card.',
@@ -959,7 +960,7 @@ shadowPlugin.gateway = {
       lastError: null
     });
     ctx.log?.info(`Starting Shadow connection for account ${accountId}`);
-    const { monitorShadowProvider: monitorShadowProvider2 } = await import("./monitor-PUXW5FI2.js");
+    const { monitorShadowProvider: monitorShadowProvider2 } = await import("./monitor-XDUBTELB.js");
     await monitorShadowProvider2({
       account,
       accountId,

package/dist/{monitor-PUXW5FI2.js → monitor-XDUBTELB.js}

@@ -5,7 +5,7 @@ import {
   normalizeShadowSlashCommands,
   resolveShadowAgentIdFromConfig,
   shouldCatchUpShadowMessage
-} from "./chunk-ATPTVU3K.js";
+} from "./chunk-4G572ZLC.js";
 export {
   formatSlashCommandPrompt,
   matchShadowSlashCommand,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shadowob/openclaw-shadowob",
-  "version": "1.1.3-dev.281",
+  "version": "1.1.4",
   "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.3-dev.281"
+    "@shadowob/sdk": "1.1.4"
   },
   "devDependencies": {
     "@types/node": "^22.15.21",

package/skills/shadowob/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: shadowob
-description: "Shadow server CLI — complete command-line interface for Shadow servers including servers, channels, DMs, workspace, shop, apps, agents, marketplace, OAuth, and more"
+description: "Use when live Shadow context or actions are needed: channel/DM history, pins, members, server/channel/workspace/shop/app/agent data, or sending/managing Shadow content via the shadowob CLI."
 metadata:
   {
     "openclaw":
@@ -17,6 +17,10 @@ allowed-tools: ["exec"]
 
 Use `shadowob` CLI to interact with Shadow servers.
 
+Activate this skill when you need current Shadow context, such as recent channel or DM history,
+pinned messages, member/server/channel state, workspace/shop/app/agent data, or when you need to
+send or manage Shadow content. Prefer narrow `--json` reads before acting.
+
 ## Quickstart
 
 ```bash
@@ -66,11 +70,6 @@ shadowob servers leave <server-id>
 # Members
 shadowob servers members <server-id> --json
 
-# Homepage
-shadowob servers homepage <server-id>
-shadowob servers homepage <server-id> --set <file.html>
-shadowob servers homepage <server-id> --clear
-
 # Discover public servers
 shadowob servers discover --json
 ```
@@ -179,19 +178,27 @@ shadowob workspace stats <server-id> --json
 shadowob workspace children <server-id> [--parent-id <id>] --json
 
 # Files
-shadowob workspace files get <file-id> --json
-shadowob workspace files create <server-id> --name <name> [--content <text>] [--parent-id <id>] --json
-shadowob workspace files update <file-id> [--name <name>] [--content <text>] --json
-shadowob workspace files delete <file-id>
+shadowob workspace files get <server-id> <file-id> --json
 shadowob workspace files upload <server-id> --file <path> [--name <name>] [--parent-id <id>] --json
-shadowob workspace files download <file-id> [--output <path>]
+shadowob workspace files update <server-id> <file-id> [--name <name>] [--parent-id <id>] --json
+shadowob workspace files delete <server-id> <file-id>
+shadowob workspace files search <server-id> [--search-text <text>] [--ext <ext>] [--parent-id <id>] --json
+# Note: files download is not yet implemented in CLI; download via contentRef URL instead.
 
 # Folders
 shadowob workspace folders create <server-id> --name <name> [--parent-id <id>] --json
-shadowob workspace folders update <folder-id> --name <name> --json
-shadowob workspace folders delete <folder-id>
+shadowob workspace folders update <server-id> <folder-id> [--name <name>] [--parent-id <id>] --json
+shadowob workspace folders delete <server-id> <folder-id>
 ```
 
+### Workspace Node Metadata
+
+Each workspace node has a `flags` JSONB field with optional metadata:
+
+- **Access control**: `flags.access = { scope: "server" | "channel", serverId, channelId? }`. All nodes have at least `scope: "server"` + `serverId`. Channel-scoped nodes require channel membership for access.
+- **Traceability**: `flags.source = "channel_message_attachment"` with `channelId` and `messageId` for files uploaded via channel messages, enabling reverse lookup to the originating message.
+- **Path is server-computed**: `path` is derived from parent path + name, maintained server-side. Do not set path manually — it is auto-updated on rename/move.
+
 ## Shop
 
 ```bash
@@ -216,7 +223,23 @@ shadowob shop wallet balance --json
 ## Apps
 
 ```bash
-# List apps
+# Server App integrations
+shadowob app list --server <server-id-or-slug> --json
+shadowob app preview --server <server-id-or-slug> --manifest-url <manifest-url> --json
+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> --json-input '<raw-command-input-json>' --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.
+When a channel message mentions a server App, use the mentioned app key/server id directly.
+
+```bash
+# Legacy workspace apps
 shadowob apps list <server-id> --json
 
 # Get app