@parall/parall 1.34.0 → 1.36.0

package/dist/index.bundle.mjs

@@ -26662,6 +26662,25 @@ function buildEventBody(event) {
     if (event.attachedUri)
       lines.push(`[Attached: ${sanitizeMeta(event.attachedUri)}]`);
     lines.push("", event.body);
+  } else if (event.type === "external_trigger") {
+    lines.push(`[Event: external.trigger]`);
+    lines.push(`[Trigger: prll://${event.targetId}]`);
+    lines.push(`[Run: prll://${event.messageId}]`);
+    if (event.externalConnectionId) {
+      const label = event.externalConnectionDisplayName ? `${sanitizeMeta(event.externalConnectionDisplayName)} (prll://${event.externalConnectionId})` : `prll://${event.externalConnectionId}`;
+      lines.push(`[Connection: ${label}]`);
+    }
+    if (event.externalIngressEventId)
+      lines.push(`[Ingress: prll://${event.externalIngressEventId}]`);
+    if (event.attachedUri)
+      lines.push(`[Attached: ${sanitizeMeta(event.attachedUri)}]`);
+    if (event.externalConnectionSourceType) {
+      lines.push(`[Source: ${sanitizeMeta(event.externalConnectionSourceType)}]`);
+    }
+    if (event.externalIngressEventType) {
+      lines.push(`[External event: ${sanitizeMeta(event.externalIngressEventType)}]`);
+    }
+    lines.push("", event.body);
   } else {
     lines.push(`[Event: task.assigned]`);
     const taskLabel = event.targetName ? `${event.targetName} (prll://${event.targetId})` : `prll://${event.targetId}`;
@@ -26693,6 +26712,10 @@ function buildSendMessageHint(event) {
   if (event.targetId.startsWith("sch_")) {
     return `
 <system-reminder>To communicate, use the CLI: \`parall messages send\` / \`parall dm\`. Your plain text output is not delivered.</system-reminder>`;
+  }
+  if (event.type === "external_trigger" || event.targetId.startsWith("xtr_")) {
+    return `
+<system-reminder>This external trigger is incoming-only. Your plain text output is not sent back to the external provider. To communicate in Parall, use \`parall messages send\` / \`parall dm\`; provider-specific outbound actions require a separate capability.</system-reminder>`;
   }
   return "";
 }
@@ -27010,6 +27033,7 @@ var ENDPOINTS = {
   // Org-scoped
   ORG: (orgId) => `${API_BASE}/orgs/${orgId}`,
   ORG_MEMBERS: (orgId) => `${API_BASE}/orgs/${orgId}/members`,
+  TEAMS: (orgId) => `${API_BASE}/orgs/${orgId}/teams`,
   ORG_MEMBERS_ONLINE: (orgId) => `${API_BASE}/orgs/${orgId}/members/online`,
   ORG_MEMBER: (orgId, userId) => `${API_BASE}/orgs/${orgId}/members/${userId}`,
   ORG_MEMBER_CHATS: (orgId, memberId) => `${API_BASE}/orgs/${orgId}/members/${memberId}/chats`,
@@ -27054,6 +27078,7 @@ var ENDPOINTS = {
   AGENT: (orgId, agentId) => `${API_BASE}/orgs/${orgId}/agents/${agentId}`,
   AGENT_API_KEYS: (orgId, agentId) => `${API_BASE}/orgs/${orgId}/agents/${agentId}/api-keys`,
   AGENT_API_KEY: (orgId, agentId, key) => `${API_BASE}/orgs/${orgId}/agents/${agentId}/api-keys/${key}`,
+  AGENT_API_KEY_REGENERATE: (orgId, agentId) => `${API_BASE}/orgs/${orgId}/agents/${agentId}/api-keys/regenerate`,
   AGENT_AVATAR: (orgId, agentId) => `${API_BASE}/orgs/${orgId}/agents/${agentId}/avatar`,
   AGENT_ACTIVITY: (orgId, agentId) => `${API_BASE}/orgs/${orgId}/agents/${agentId}/activity`,
   AGENT_MONITOR: (orgId, agentId) => `${API_BASE}/orgs/${orgId}/agents/${agentId}/monitor`,
@@ -27093,6 +27118,7 @@ var ENDPOINTS = {
   MACHINE_AGENT_WORKSPACE_SETUP: (orgId, machineId, agentId) => `${API_BASE}/orgs/${orgId}/machines/${machineId}/agents/${agentId}/workspace/setup`,
   MACHINE_LLM_SOURCE: (orgId, machineId) => `${API_BASE}/orgs/${orgId}/machines/${machineId}/llm-source`,
   MACHINE_PROVIDER_ENABLED: (orgId, machineId) => `${API_BASE}/orgs/${orgId}/machines/${machineId}/provider-enabled`,
+  MACHINE_CAPABILITIES: (orgId, machineId) => `${API_BASE}/orgs/${orgId}/machines/${machineId}/capabilities`,
   MACHINE_RUNTIME_AUTH: (orgId, machineId) => `${API_BASE}/orgs/${orgId}/machines/${machineId}/runtime-auth`,
   MACHINE_KEYS: (orgId, machineId) => `${API_BASE}/orgs/${orgId}/machines/${machineId}/keys`,
   MACHINE_KEY: (orgId, machineId, keyId) => `${API_BASE}/orgs/${orgId}/machines/${machineId}/keys/${keyId}`,
@@ -27113,6 +27139,12 @@ var ENDPOINTS = {
   MACHINES_ME_AGENT_WORKSPACE_STATE: (agentId) => `${API_BASE}/machines/me/agents/${agentId}/workspace-state`,
   MACHINES_ME_WS_TICKET: `${API_BASE}/machines/me/ws/ticket`,
   MACHINES_ME_BROWSE_RESPONSE: (requestId) => `${API_BASE}/machines/me/browse-response/${requestId}`,
+  // Hosted browser live-viewer control plane (api-server, NOT clip-service):
+  // the web client drives WebRTC signaling + tab nav through VIEWER_COMMAND;
+  // api-server brokers each command to the host daemon via the machine:{id}
+  // request/reply bridge (mirrors filesystem browse), and the daemon replies on
+  // VIEWER_RESPONSE. See docs/engineering-design/hosted-browser-provider-design.md.
+  MACHINES_ME_BROWSER_PROFILE_VIEWER_RESPONSE: (requestId) => `${API_BASE}/machines/me/browser-profiles/viewer-response/${requestId}`,
   // Tasks (org-scoped)
   TASKS: (orgId) => `${API_BASE}/orgs/${orgId}/tasks`,
   TASK: (orgId, taskId) => `${API_BASE}/orgs/${orgId}/tasks/${taskId}`,
@@ -27139,6 +27171,17 @@ var ENDPOINTS = {
   SCHEDULE_CANCEL: (orgId, id) => `${API_BASE}/orgs/${orgId}/schedules/${id}/cancel`,
   SCHEDULE_RUNS: (orgId, id) => `${API_BASE}/orgs/${orgId}/schedules/${id}/runs`,
   SCHEDULE_RUN: (orgId, runId) => `${API_BASE}/orgs/${orgId}/schedule_runs/${runId}`,
+  // External triggers (org-scoped incoming integration primitive)
+  EXTERNAL_CONNECTIONS: (orgId) => `${API_BASE}/orgs/${orgId}/external-connections`,
+  EXTERNAL_CONNECTION: (orgId, connectionId) => `${API_BASE}/orgs/${orgId}/external-connections/${connectionId}`,
+  EXTERNAL_CONNECTION_INGRESS_TOKEN_REGENERATE: (orgId, connectionId) => `${API_BASE}/orgs/${orgId}/external-connections/${connectionId}/ingress-token/regenerate`,
+  EXTERNAL_TRIGGER_SCHEMA: (orgId, connectionId) => `${API_BASE}/orgs/${orgId}/external-connections/${connectionId}/trigger-schema`,
+  EXTERNAL_INGRESS_EVENTS: (orgId) => `${API_BASE}/orgs/${orgId}/external-ingress-events`,
+  EXTERNAL_INGRESS_EVENT: (orgId, eventId) => `${API_BASE}/orgs/${orgId}/external-ingress-events/${eventId}`,
+  EXTERNAL_TRIGGERS: (orgId) => `${API_BASE}/orgs/${orgId}/external-triggers`,
+  EXTERNAL_TRIGGER: (orgId, triggerId) => `${API_BASE}/orgs/${orgId}/external-triggers/${triggerId}`,
+  EXTERNAL_TRIGGER_RUNS: (orgId) => `${API_BASE}/orgs/${orgId}/external-trigger-runs`,
+  EXTERNAL_TRIGGER_RUN: (orgId, runId) => `${API_BASE}/orgs/${orgId}/external-trigger-runs/${runId}`,
   // Invitations (org-scoped, admin)
   ORG_INVITATIONS: (orgId) => `${API_BASE}/orgs/${orgId}/invitations`,
   ORG_INVITATION: (orgId, invId) => `${API_BASE}/orgs/${orgId}/invitations/${invId}`,
@@ -27178,6 +27221,9 @@ var ENDPOINTS = {
   // Wiki Path Scopes (AFCS ACL)
   WIKI_PATH_SCOPES: (orgId, wikiId) => `${WIKI_BASE}/orgs/${orgId}/wikis/${wikiId}/path-scopes`,
   WIKI_PATH_SCOPE: (orgId, wikiId, scopeId) => `${WIKI_BASE}/orgs/${orgId}/wikis/${wikiId}/path-scopes/${scopeId}`,
+  // Wiki Path Restrictions (AFCS narrowing ACL — private subtrees)
+  WIKI_RESTRICTIONS: (orgId, wikiId) => `${WIKI_BASE}/orgs/${orgId}/wikis/${wikiId}/restrictions`,
+  WIKI_RESTRICTION: (orgId, wikiId, restrictionId) => `${WIKI_BASE}/orgs/${orgId}/wikis/${wikiId}/restrictions/${restrictionId}`,
   WIKI_ACCESS_STATUS: (orgId, wikiId) => `${WIKI_BASE}/orgs/${orgId}/wikis/${wikiId}/access-status`,
   WIKI_ACCESS_REQUESTS: (orgId, wikiId) => `${WIKI_BASE}/orgs/${orgId}/wikis/${wikiId}/access-requests`,
   // Wiki History (commits, file commits, blame)
@@ -27243,6 +27289,7 @@ var ENDPOINTS = {
   // Clips (org-scoped, served by clip-service)
   CLIPS: (orgId) => `${CLIP_BASE}/orgs/${orgId}/clips`,
   CLIP: (orgId, clipId) => `${CLIP_BASE}/orgs/${orgId}/clips/${clipId}`,
+  CLIPS_BULK_METADATA: (orgId) => `${CLIP_BASE}/orgs/${orgId}/clips/bulk-metadata`,
   CLIP_AGENTS: (orgId, clipId) => `${CLIP_BASE}/orgs/${orgId}/clips/${clipId}/agents`,
   AGENT_CLIPS: (orgId, agentId) => `${CLIP_BASE}/orgs/${orgId}/agents/${agentId}/clips`,
   AGENT_CLIP: (orgId, agentId, clipId) => `${CLIP_BASE}/orgs/${orgId}/agents/${agentId}/clips/${clipId}`,
@@ -27255,6 +27302,9 @@ var ENDPOINTS = {
   BROWSER_PROFILE_RESET: (orgId, profileId) => `${CLIP_BASE}/orgs/${orgId}/browser-profiles/${profileId}/reset`,
   BROWSER_PROFILE_CONSENTS: (orgId, profileId) => `${CLIP_BASE}/orgs/${orgId}/browser-profiles/${profileId}/consents`,
   BROWSER_PROFILE_CONSENT: (orgId, profileId, clipId) => `${CLIP_BASE}/orgs/${orgId}/browser-profiles/${profileId}/consents/${clipId}`,
+  // Live viewer command — on api-server (API_BASE), not clip-service: it rides
+  // the machine control-plane request/reply bridge that lives in api-server.
+  BROWSER_PROFILE_VIEWER_COMMAND: (orgId, profileId) => `${API_BASE}/orgs/${orgId}/browser-profiles/${profileId}/viewer/command`,
   // Clip registry (global, served by clip-service → Pinix Hub proxy)
   CLIP_REGISTRY: () => `${CLIP_BASE}/registry/clips`
 };
@@ -27331,6 +27381,7 @@ var WS_EVENTS = {
   MACHINE_CONFIG_UPDATED: "machine.config.updated",
   MACHINE_CLIP_SYNC: "machine.clip.sync",
   MACHINE_BROWSER_PROFILE_LIFECYCLE: "machine.browser_profile.lifecycle",
+  MACHINE_BROWSER_PROFILE_VIEWER: "machine.browser_profile.viewer",
   AGENT_NEW_SESSION: "agent.new_session",
   CLIP_CREATED: "clip.created",
   CLIP_REMOVED: "clip.removed",
@@ -27340,6 +27391,7 @@ var WS_EVENTS = {
 // ../sdk/dist/client.js
 var ParallClient = class _ParallClient {
   baseUrl;
+  wikiBaseUrl;
   token;
   onTokenExpired;
   getRefreshToken;
@@ -27391,12 +27443,22 @@ var ParallClient = class _ParallClient {
   }
   constructor(options = {}) {
     this.baseUrl = options.baseUrl ?? "";
+    this.wikiBaseUrl = options.wikiBaseUrl ?? this.baseUrl;
     this.token = options.token ?? null;
     this.onTokenExpired = options.onTokenExpired;
     this.getRefreshToken = options.getRefreshToken;
     this.setTokens = options.setTokens;
     this.swimlaneName = options.swimlaneName;
   }
+  /**
+   * Pick the origin for a request path: wiki-service base for `/wiki/v1`
+   * endpoints, api base for everything else. The path itself (from ENDPOINTS)
+   * is authoritative, so wiki vs api routing can't drift from how a caller
+   * happens to invoke the client.
+   */
+  baseUrlFor(path7) {
+    return path7.startsWith(WIKI_BASE) ? this.wikiBaseUrl : this.baseUrl;
+  }
   setToken(token) {
     this.token = token;
   }
@@ -27461,7 +27523,7 @@ var ParallClient = class _ParallClient {
     if (!retried) {
       await this.ensureFreshToken(path7);
     }
-    let url = `${this.baseUrl}${path7}`;
+    let url = `${this.baseUrlFor(path7)}${path7}`;
     if (query) {
       const params = new URLSearchParams();
       for (const [key, value] of Object.entries(query)) {
@@ -27482,7 +27544,10 @@ var ParallClient = class _ParallClient {
         method,
         headers,
         body: body ? JSON.stringify(body) : void 0,
-        signal
+        signal,
+        // keepalive lets a request fired during page unload (e.g. the browser
+        // viewer's stream.close on pagehide) outlive the document.
+        keepalive: opts?.keepalive
       });
     } catch (err) {
       throw _ParallClient.normalizeFetchError(err);
@@ -27530,7 +27595,7 @@ var ParallClient = class _ParallClient {
     void _drop;
     let res;
     try {
-      res = await fetch(`${this.baseUrl}${path7}`, {
+      res = await fetch(`${this.baseUrlFor(path7)}${path7}`, {
         method,
         headers,
         body,
@@ -27653,6 +27718,10 @@ var ParallClient = class _ParallClient {
     const res = await this.request("GET", ENDPOINTS.ORG_MEMBERS(orgId));
     return res.data;
   }
+  async getTeams(orgId) {
+    const res = await this.request("GET", ENDPOINTS.TEAMS(orgId));
+    return res.data;
+  }
   async getOnlineMembers(orgId) {
     const res = await this.request("GET", ENDPOINTS.ORG_MEMBERS_ONLINE(orgId));
     return res.user_ids ?? [];
@@ -27686,6 +27755,21 @@ var ParallClient = class _ParallClient {
       q.limit = String(params.limit);
     return this.request("GET", ENDPOINTS.ORG_MEMBER_TASKS(orgId, memberId), void 0, q);
   }
+  // Auto-paginated variant of getMemberTasks: fetches ALL pending tasks
+  // (todo + in_progress) assigned to a member, including subtasks (the
+  // endpoint does not filter parent_id). Powers the CLI `tasks assigned`
+  // command so an agent answering "what's on X's plate" sees the full
+  // backlog, not just the first page.
+  async getMemberTasksAll(orgId, memberId) {
+    const all = [];
+    let cursor;
+    do {
+      const res = await this.getMemberTasks(orgId, memberId, { cursor, limit: 100 });
+      all.push(...res.data);
+      cursor = res.has_more ? res.next_cursor : void 0;
+    } while (cursor);
+    return all;
+  }
   // ---- Invitations ----
   async createInvitation(orgId, email, role) {
     return this.request("POST", ENDPOINTS.ORG_INVITATIONS(orgId), { email, role });
@@ -27891,6 +27975,10 @@ var ParallClient = class _ParallClient {
   async createAgentApiKey(orgId, agentId) {
     return this.request("POST", ENDPOINTS.AGENT_API_KEYS(orgId, agentId));
   }
+  /** Revokes all of the agent's active API keys and mints a replacement. */
+  async regenerateAgentApiKey(orgId, agentId) {
+    return this.request("POST", ENDPOINTS.AGENT_API_KEY_REGENERATE(orgId, agentId));
+  }
   async revokeAgentApiKey(orgId, agentId, key) {
     return this.request("DELETE", ENDPOINTS.AGENT_API_KEY(orgId, agentId, key));
   }
@@ -28062,6 +28150,17 @@ var ParallClient = class _ParallClient {
       provider_enabled: providerEnabled
     });
   }
+  /**
+   * Replace the machine's capability set (admin). Primary use: healing a
+   * machine that registered without `browser_provider` during the capability
+   * migration's rolling-deploy window. Removing `agent_host` is rejected by the
+   * server while agents are attached (409 AGENTS_STILL_ATTACHED).
+   */
+  async patchMachineCapabilities(orgId, machineId, capabilities) {
+    return this.request("PATCH", ENDPOINTS.MACHINE_CAPABILITIES(orgId, machineId), {
+      capabilities
+    });
+  }
   /** Get machine-level runtime auth state. */
   async getMachineRuntimeAuth(orgId, machineId) {
     return this.request("GET", ENDPOINTS.MACHINE_RUNTIME_AUTH(orgId, machineId));
@@ -28152,6 +28251,22 @@ var ParallClient = class _ParallClient {
   async postBrowseResponse(requestId, response) {
     return this.request("POST", ENDPOINTS.MACHINES_ME_BROWSE_RESPONSE(requestId), response);
   }
+  /**
+   * `POST /machines/me/browser-profiles/viewer-response/{requestId}` — daemon
+   * reply to a `machine.browser_profile.viewer` control command. Wakes the
+   * api-server request/reply bridge (mirrors {@link postBrowseResponse}).
+   */
+  async postBrowserProfileViewerResponse(requestId, response) {
+    return this.request("POST", ENDPOINTS.MACHINES_ME_BROWSER_PROFILE_VIEWER_RESPONSE(requestId), response);
+  }
+  /**
+   * `POST /orgs/{orgId}/browser-profiles/{profileId}/viewer/command` — drive the
+   * hosted browser live viewer (WebRTC signaling + tab nav). Authz: profile
+   * owner or org admin. api-server brokers the command to the host daemon.
+   */
+  async browserViewerCommand(orgId, profileId, req, opts) {
+    return this.request("POST", ENDPOINTS.BROWSER_PROFILE_VIEWER_COMMAND(orgId, profileId), req, void 0, false, opts);
+  }
   async resizeMachine(orgId, machineId, spec) {
     return this.request("PATCH", ENDPOINTS.MACHINE_SPEC(orgId, machineId), spec);
   }
@@ -28244,7 +28359,7 @@ var ParallClient = class _ParallClient {
    * Returns null when the server responds with 304 (config unchanged).
    */
   async getPlatformConfig(currentVersion) {
-    const url = `${this.baseUrl}${ENDPOINTS.PLATFORM_CONFIG}`;
+    const url = `${this.baseUrlFor(ENDPOINTS.PLATFORM_CONFIG)}${ENDPOINTS.PLATFORM_CONFIG}`;
     const extra = {};
     if (currentVersion !== void 0) {
       extra["If-None-Match"] = currentVersion;
@@ -28410,6 +28525,55 @@ var ParallClient = class _ParallClient {
   async getScheduleRun(orgId, runId) {
     return this.request("GET", ENDPOINTS.SCHEDULE_RUN(orgId, runId));
   }
+  // ---- External triggers (org-scoped) ----
+  async createExternalConnection(orgId, input) {
+    return this.request("POST", ENDPOINTS.EXTERNAL_CONNECTIONS(orgId), input);
+  }
+  async listExternalConnections(orgId, filters) {
+    return this.request("GET", ENDPOINTS.EXTERNAL_CONNECTIONS(orgId), void 0, filters);
+  }
+  async getExternalConnection(orgId, connectionId) {
+    return this.request("GET", ENDPOINTS.EXTERNAL_CONNECTION(orgId, connectionId));
+  }
+  async updateExternalConnection(orgId, connectionId, patch) {
+    return this.request("PATCH", ENDPOINTS.EXTERNAL_CONNECTION(orgId, connectionId), patch);
+  }
+  async regenerateExternalConnectionIngressToken(orgId, connectionId) {
+    return this.request("POST", ENDPOINTS.EXTERNAL_CONNECTION_INGRESS_TOKEN_REGENERATE(orgId, connectionId));
+  }
+  async deleteExternalConnection(orgId, connectionId) {
+    return this.request("DELETE", ENDPOINTS.EXTERNAL_CONNECTION(orgId, connectionId));
+  }
+  async getExternalTriggerSchema(orgId, connectionId) {
+    return this.request("GET", ENDPOINTS.EXTERNAL_TRIGGER_SCHEMA(orgId, connectionId));
+  }
+  async listExternalIngressEvents(orgId, filters) {
+    return this.request("GET", ENDPOINTS.EXTERNAL_INGRESS_EVENTS(orgId), void 0, filters);
+  }
+  async getExternalIngressEvent(orgId, eventId) {
+    return this.request("GET", ENDPOINTS.EXTERNAL_INGRESS_EVENT(orgId, eventId));
+  }
+  async createExternalTrigger(orgId, input) {
+    return this.request("POST", ENDPOINTS.EXTERNAL_TRIGGERS(orgId), input);
+  }
+  async listExternalTriggers(orgId, filters) {
+    return this.request("GET", ENDPOINTS.EXTERNAL_TRIGGERS(orgId), void 0, filters);
+  }
+  async getExternalTrigger(orgId, triggerId) {
+    return this.request("GET", ENDPOINTS.EXTERNAL_TRIGGER(orgId, triggerId));
+  }
+  async updateExternalTrigger(orgId, triggerId, patch) {
+    return this.request("PATCH", ENDPOINTS.EXTERNAL_TRIGGER(orgId, triggerId), patch);
+  }
+  async deleteExternalTrigger(orgId, triggerId) {
+    return this.request("DELETE", ENDPOINTS.EXTERNAL_TRIGGER(orgId, triggerId));
+  }
+  async listExternalTriggerRuns(orgId, filters) {
+    return this.request("GET", ENDPOINTS.EXTERNAL_TRIGGER_RUNS(orgId), void 0, filters);
+  }
+  async getExternalTriggerRun(orgId, runId) {
+    return this.request("GET", ENDPOINTS.EXTERNAL_TRIGGER_RUN(orgId, runId));
+  }
   // ---- Wikis (org-scoped) ----
   async createWiki(orgId, data) {
     return this.request("POST", ENDPOINTS.WIKIS(orgId), data);
@@ -28424,8 +28588,35 @@ var ParallClient = class _ParallClient {
   async getWikiTree(orgId, wikiId, params) {
     return this.request("GET", ENDPOINTS.WIKI_TREE(orgId, wikiId), void 0, params);
   }
+  /**
+   * Resolve a server-returned, host-relative media URL (a wiki `signed_url`
+   * like `/wiki/v1/signed/files?token=...`) against this client's base origin,
+   * so it can be dropped straight into a browser `<img>`/`<video>`/`<iframe>`
+   * `src`.
+   *
+   * wiki-service returns these relative on purpose — it doesn't know its own
+   * public origin. A relative `src` resolves against the *page* origin, which
+   * only works when the page and wiki-service share an origin (local dev:
+   * same-origin + Next.js `/wiki/*` proxy). In deployed envs the app
+   * (app.parall.com) and wiki-service (api.parall.com) are different origins,
+   * so `app.parall.com/wiki/v1/signed/files` hits the SPA's own `/wiki/[...]`
+   * catch-all route — an `<iframe>` then recursively renders the whole app
+   * instead of the file. Prefixing with the wiki base (the exact origin every
+   * wiki API request already uses — `baseUrlFor` resolves `/wiki/v1` paths to
+   * `wikiBaseUrl`) makes the URL absolute against the origin that actually
+   * serves the bytes. An empty base (local dev, same-origin proxy) leaves it
+   * relative, preserving the proxy path.
+   */
+  absoluteMediaUrl(url) {
+    if (/^https?:\/\//i.test(url))
+      return url;
+    return `${this.baseUrlFor(url)}${url}`;
+  }
   async getWikiBlob(orgId, wikiId, params) {
-    return this.request("GET", ENDPOINTS.WIKI_BLOB(orgId, wikiId), void 0, params);
+    const blob = await this.request("GET", ENDPOINTS.WIKI_BLOB(orgId, wikiId), void 0, params);
+    if (blob.signed_url)
+      blob.signed_url = this.absoluteMediaUrl(blob.signed_url);
+    return blob;
   }
   async getWikiNodeSections(orgId, wikiId, params) {
     return this.request("GET", ENDPOINTS.WIKI_NODE_SECTIONS(orgId, wikiId), void 0, params);
@@ -28515,7 +28706,10 @@ var ParallClient = class _ParallClient {
    * token — don't leak it.
    */
   async getWikiFilePreviewUrl(orgId, wikiId, params) {
-    return this.request("POST", ENDPOINTS.WIKI_FILE_PREVIEW_URL(orgId, wikiId), params);
+    const res = await this.request("POST", ENDPOINTS.WIKI_FILE_PREVIEW_URL(orgId, wikiId), params);
+    if (res.url)
+      res.url = this.absoluteMediaUrl(res.url);
+    return res;
   }
   // ---- Wiki Path Scopes (AFCS ACL) ----
   async getWikiPathScopes(orgId, wikiId) {
@@ -28528,6 +28722,17 @@ var ParallClient = class _ParallClient {
   async deleteWikiPathScope(orgId, wikiId, scopeId) {
     await this.request("DELETE", ENDPOINTS.WIKI_PATH_SCOPE(orgId, wikiId, scopeId));
   }
+  // ---- Wiki Path Restrictions (narrowing ACL — private subtrees) ----
+  async getWikiRestrictions(orgId, wikiId) {
+    const res = await this.request("GET", ENDPOINTS.WIKI_RESTRICTIONS(orgId, wikiId));
+    return res.data;
+  }
+  async createWikiRestriction(orgId, wikiId, data) {
+    return this.request("POST", ENDPOINTS.WIKI_RESTRICTIONS(orgId, wikiId), data);
+  }
+  async deleteWikiRestriction(orgId, wikiId, restrictionId) {
+    await this.request("DELETE", ENDPOINTS.WIKI_RESTRICTION(orgId, wikiId, restrictionId));
+  }
   async getWikiAccessStatus(orgId, wikiId, path7) {
     return this.request("GET", ENDPOINTS.WIKI_ACCESS_STATUS(orgId, wikiId), void 0, path7 ? { path: path7 } : void 0);
   }
@@ -28690,6 +28895,10 @@ var ParallClient = class _ParallClient {
   async updateClip(orgId, clipId, req) {
     return this.request("PATCH", ENDPOINTS.CLIP(orgId, clipId), req);
   }
+  /** Atomically set display_name and/or description on multiple clip instances (application metadata). */
+  async bulkUpdateClipMetadata(orgId, req) {
+    return this.request("POST", ENDPOINTS.CLIPS_BULK_METADATA(orgId), req);
+  }
   async deleteClip(orgId, clipId) {
     await this.request("DELETE", ENDPOINTS.CLIP(orgId, clipId));
   }
@@ -28716,6 +28925,9 @@ var ParallClient = class _ParallClient {
     const resp = await this.request("GET", ENDPOINTS.CLIP_ONLINE(orgId));
     return resp.data;
   }
+  /** Org-wide browser-profile discovery list. Returns the sanitized
+   *  {@link BrowserProfileListItem} shape (not the full domain model), each row
+   *  carrying a per-viewer `can_open` control hint. */
   async listBrowserProfiles(orgId) {
     const resp = await this.request("GET", ENDPOINTS.BROWSER_PROFILES(orgId));
     return resp.data;
@@ -29369,6 +29581,9 @@ function resolveStepTarget(event) {
   if (event.type === "schedule" || event.targetId.startsWith("sch_")) {
     return { target_type: "schedule", target_id: event.targetId };
   }
+  if (event.type === "external_trigger" || event.targetId.startsWith("xtr_")) {
+    return { target_type: "external_trigger", target_id: event.targetId };
+  }
   if (event.type === "wiki_comment") {
     return { target_type: "wiki", target_id: event.targetId || void 0 };
   }
@@ -29573,6 +29788,18 @@ var ParallAgentGateway = class {
         } catch (err) {
           this.opts.log?.error(`schedule fire dispatch failed for ${data.source_id}: ${String(err)}`);
         }
+      } else if (data.event_type === "external_trigger") {
+        if (!data.source_id)
+          return;
+        try {
+          const dispatched = await this.fetchAndHandleExternalTriggerRun(data.source_id);
+          if (dispatched) {
+            this.opts.client.ackDispatchByID(this.opts.config.org_id, data.id).catch(() => {
+            });
+          }
+        } catch (err) {
+          this.opts.log?.error(`external trigger dispatch failed for ${data.source_id}: ${String(err)}`);
+        }
       } else if (data.event_type === "approval_decided") {
         if (!data.source_id)
           return;
@@ -29651,8 +29878,13 @@ var ParallAgentGateway = class {
         target_type: target.target_type,
         target_id: target.target_id,
         content: {
-          trigger_type: event.type === "task" ? "task_assign" : event.type === "task_comment" ? "task_comment" : event.type === "wiki_comment" ? "wiki_comment" : event.type === "schedule" ? "schedule_fire" : event.type === "approval" ? "approval_decided" : "mention",
-          trigger_ref: event.type === "task" ? { task_id: event.targetId } : event.type === "task_comment" ? { comment_id: event.messageId, task_id: event.targetId } : event.type === "wiki_comment" ? { comment_id: event.messageId, target_uri: event.replyTargetUri } : event.type === "schedule" ? { schedule_id: event.targetId, run_id: event.messageId } : event.type === "approval" ? { approval_id: event.messageId } : { message_id: event.messageId },
+          trigger_type: event.type === "task" ? "task_assign" : event.type === "task_comment" ? "task_comment" : event.type === "wiki_comment" ? "wiki_comment" : event.type === "schedule" ? "schedule_fire" : event.type === "external_trigger" ? "external_trigger" : event.type === "approval" ? "approval_decided" : "mention",
+          trigger_ref: event.type === "task" ? { task_id: event.targetId } : event.type === "task_comment" ? { comment_id: event.messageId, task_id: event.targetId } : event.type === "wiki_comment" ? { comment_id: event.messageId, target_uri: event.replyTargetUri } : event.type === "schedule" ? { schedule_id: event.targetId, run_id: event.messageId } : event.type === "external_trigger" ? {
+            trigger_id: event.targetId,
+            run_id: event.messageId,
+            connection_id: event.externalConnectionId,
+            ingress_event_id: event.externalIngressEventId
+          } : event.type === "approval" ? { approval_id: event.messageId } : { message_id: event.messageId },
           sender_id: event.senderId,
           sender_name: event.senderName,
           summary: event.body.substring(0, 200),
@@ -30221,7 +30453,7 @@ var ParallAgentGateway = class {
             this.dispatchState.mainDispatching = true;
             void this.drainMainBuffer();
           }
-        }, 5e3);
+        }, 5e3).unref();
       }
     }
   }
@@ -30688,6 +30920,62 @@ var ParallAgentGateway = class {
     }
     return dispatched;
   }
+  async fetchAndHandleExternalTriggerRun(runId) {
+    let run = null;
+    try {
+      run = await this.opts.client.getExternalTriggerRun(this.opts.config.org_id, runId);
+    } catch (err) {
+      const status = err?.status;
+      if (status === 404) {
+        this.opts.log?.warn(`external trigger run ${runId} not accessible (404), acking stale dispatch`);
+        return true;
+      }
+      this.opts.log?.warn(`external trigger run fetch failed for ${runId}, leaving pending: ${String(err)}`);
+      return false;
+    }
+    if (!run)
+      return true;
+    return this.handleExternalTriggerRun(run);
+  }
+  async handleExternalTriggerRun(run) {
+    if (this.shuttingDown)
+      return false;
+    const dedupeKey = `external_trigger_run:${run.id}`;
+    if (this.dispatchedTasks.has(dedupeKey))
+      return false;
+    this.dispatchedTasks.add(dedupeKey);
+    this.opts.log?.info(`external trigger fired: ${run.id} (trigger ${run.trigger_id})`);
+    const attachedUri = typeof run.trigger_snapshot?.attached_to_uri === "string" ? run.trigger_snapshot.attached_to_uri : void 0;
+    const event = {
+      type: "external_trigger",
+      targetId: run.trigger_id,
+      targetName: run.trigger_name || void 0,
+      targetType: "external_trigger",
+      senderId: "system",
+      senderName: "external",
+      messageId: run.id,
+      body: run.agent_input_body ?? "",
+      externalConnectionId: run.connection_id,
+      externalConnectionSourceType: run.connection_source_type || void 0,
+      externalConnectionDisplayName: run.connection_display_name || void 0,
+      externalIngressEventId: run.ingress_event_id,
+      externalIngressEventType: run.ingress_event_type || void 0,
+      attachedUri,
+      ackSourceType: "external_trigger_run",
+      ackSourceId: run.id
+    };
+    let dispatched;
+    try {
+      dispatched = await this.handleInboundEvent(event);
+    } catch (err) {
+      this.dispatchedTasks.delete(dedupeKey);
+      throw err;
+    }
+    if (!dispatched) {
+      this.dispatchedTasks.delete(dedupeKey);
+    }
+    return dispatched;
+  }
   async fetchAndHandleApprovalDecided(approvalId, actorId, chatId) {
     let approval = null;
     try {
@@ -30798,6 +31086,8 @@ var ParallAgentGateway = class {
             dispatched = await this.handleWikiComment(item.source_id, item.actor_id, item.delivery_reason);
           } else if (item.event_type === "schedule.fire" && item.source_id) {
             dispatched = await this.fetchAndHandleScheduleFire(item.source_id, item.actor_id);
+          } else if (item.event_type === "external_trigger" && item.source_id) {
+            dispatched = await this.fetchAndHandleExternalTriggerRun(item.source_id);
           } else if (item.event_type === "approval_decided" && item.source_id) {
             dispatched = await this.fetchAndHandleApprovalDecided(item.source_id, item.actor_id, item.chat_id ?? null);
           } else if (item.event_type === "message" && item.source_id && item.chat_id) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@parall/parall",
-  "version": "1.34.0",
+  "version": "1.36.0",
   "description": "OpenClaw channel plugin for Parall IM",
   "license": "MIT",
   "repository": {
@@ -16,8 +16,8 @@
     "openclaw.plugin.json"
   ],
   "dependencies": {
-    "@parall/agent-core": "1.34.0",
-    "@parall/sdk": "1.34.0"
+    "@parall/sdk": "1.36.0",
+    "@parall/agent-core": "1.36.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/skills/parall-external-triggers/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: parall-external-triggers
+description: "Parall External Trigger operations: create incoming connections, configure CEL/Liquid triggers, inspect incoming events and runs, and respond to `[Event: external.trigger]` dispatches. Use when: user asks to connect an external system to an agent, set up incoming callbacks/notifications, or when the agent receives an external trigger event."
+---
+
+# Parall External Triggers
+
+An **External Trigger** is an incoming platform trigger. External systems send events to an External Trigger Connection, Parall matches active triggers with CEL, renders a Liquid template into an agent input body, and dispatches that input to the configured target agents.
+
+Use External Triggers for incoming events such as GitHub callbacks, Slack/Feishu notifications, generic webhooks, or emails once the platform has a connection for them. The runtime behavior is incoming-only: receiving a trigger does not imply that you can call the external system back unless another explicit Parall capability is available.
+
+## Prerequisite
+
+External Trigger CLI commands are gated by the org-level `external-triggers` feature flag. If a command reports that the feature is unavailable, ask a human org admin to enable the flag before trying again. Public ingress delivery may still be live even when the management CLI is hidden behind the rollout flag.
+
+## Creating a trigger
+
+```bash
+# 1. Create a connection. The ingress token is shown once; prefer writing it
+# to a local file so it does not land in shell history or logs.
+parall external-triggers create-connection --name "GitHub CI" --token-file ./github-ci-webhook-token.txt
+
+# 2. Create a trigger that targets one or more agents.
+parall external-triggers create \
+  --connection prll://xcn_xxx \
+  --name "Failed checks" \
+  --target-ids prll://usr_agent_xxx \
+  --filter "body.json.check_run.conclusion == 'failure'" \
+  --template-file ./github-check-failed.md \
+  --attached-to-uri prll://tsk_xxx
+```
+
+`--filter` is CEL. Omit it to match all incoming events (`true`). Keep filters small and deterministic; do not model provider-specific branching in agent code when the CEL expression can select the relevant events first.
+
+`--template` / `--template-file` is Liquid with the safe Parall profile. It can read event data, body data, safe request metadata, trigger fields, run fields, and connection fields. It cannot call HTTP, read databases, evaluate arbitrary code, access platform secrets, or read arbitrary request headers/query parameters.
+
+Example template:
+
+```liquid
+GitHub check failed.
+
+Event: {{ request.headers.x_github_event | default: "unknown" }}
+Repo: {{ body.json.repository.full_name }}
+PR: {{ body.json.pull_request.number }} {{ body.json.pull_request.title }}
+Check: {{ body.json.check_run.name }}
+Conclusion: {{ body.json.check_run.conclusion }}
+
+Run: {{ body.json.check_run.html_url }}
+```
+
+Do not render access tokens, signing secrets, cookies, or private credentials into agent input. Request snapshots and bodies may contain third-party data; treat them as user-provided input.
+
+## Inspecting and lifecycle
+
+```bash
+parall external-triggers connections
+parall external-triggers connection prll://xcn_xxx
+parall external-triggers schema prll://xcn_xxx
+
+parall external-triggers list
+parall external-triggers list --connection prll://xcn_xxx
+parall external-triggers get prll://xtr_xxx
+parall external-triggers update prll://xtr_xxx --filter "event.type == 'check_run'"
+parall external-triggers pause prll://xtr_xxx
+parall external-triggers resume prll://xtr_xxx
+parall external-triggers delete prll://xtr_xxx
+
+parall external-triggers runs prll://xtr_xxx
+parall external-triggers run prll://xrn_xxx
+parall external-triggers events --connection prll://xcn_xxx
+parall external-triggers event prll://xin_xxx
+```
+
+## Responding to external trigger dispatches
+
+When you receive `[Event: external.trigger]`, Parall has already matched a trigger and rendered its template. The prompt includes headers such as:
+
+- `[Trigger: prll://xtr_xxx]`
+- `[Run: prll://xrn_xxx]`
+- `[Connection: ... (prll://xcn_xxx)]`
+- `[Ingress: prll://xin_xxx]`
+- Optional `[Attached: prll://...]`
+
+The rendered agent input body follows those headers. You usually do not need to fetch the run before acting. Fetch the run only for audit/debugging:
+
+```bash
+parall external-triggers run prll://xrn_xxx
+```
+
+Act on the rendered input the same way you would act on a user message: send a message, create or update tasks, edit wiki pages, or use available clips. If no visible response is needed, use `parall no-reply --reason "handled external trigger"` before sending any message.
+
+CLI command results are JSON on stdout; mutation commands may emit auxiliary hints on stderr, for example `Created: prll://xtr_xxx`.

package/skills/parall-platform/SKILL.md

@@ -161,9 +161,15 @@ Every entity is addressable with a `prll://` URI. Common prefixes you'll see in
 | `prll://prj_` | Project | parall-tasks |
 | `prll://sch_` | Schedule (time trigger) | parall-schedules |
 | `prll://srn_` | Schedule run (single fire audit record; carries fire-time snapshot) | parall-schedules |
+| `prll://xcn_` | External Trigger Connection (incoming endpoint) | parall-external-triggers |
+| `prll://xin_` | External Trigger Event (single incoming event audit record) | parall-external-triggers |
+| `prll://xtr_` | External Trigger (incoming trigger configuration) | parall-external-triggers |
+| `prll://xrn_` | External Trigger run (single matched dispatch audit record) | parall-external-triggers |
 | `prll://wik_` | Wiki | parall-wiki |
 | `prll://att_` | Attachment | parall-platform (files) |
 
 When a message or event references `prll://sch_xxx` or `prll://srn_xxx`, or when you receive `[Event: schedule.fired]`, switch to the **parall-schedules** skill for the CLI commands (create / list / pause / resume / cancel / runs).
 
+When a message or event references `prll://xcn_xxx`, `prll://xin_xxx`, `prll://xtr_xxx`, or `prll://xrn_xxx`, or when you receive `[Event: external.trigger]`, switch to the **parall-external-triggers** skill for the CLI commands (connections / triggers / events / runs).
+
 CLI success output is JSON. Errors print a JSON line (`{"error","status","code",...}`) and, on a `PERMISSION_DENIED`, may add a plain-text `Request approval:` line — read both.

package/skills/parall-tasks/SKILL.md

@@ -7,16 +7,39 @@ description: "Parall task operations: create, update, comment on, and query task
 
 Manage tasks and projects via the Parall CLI. Auth and runtime context are pre-configured.
 
+## Finding What's on Someone's Plate (incl. subtasks)
+
+To answer "what do I still have to do", "what's <person> working on", or any
+"open work assigned to X" question, use `tasks assigned`:
+
+```bash
+# Pending tasks (todo + in_progress) assigned to a member — INCLUDES subtasks.
+parall tasks assigned prll://usr_xxx   # a specific person (e.g. the human who asked)
+parall tasks assigned                  # yourself (defaults to the authenticated user)
+```
+
+This is the authoritative "open work for a person" query. It returns every
+pending task assigned to that member **including subtasks** — even when the
+subtask's parent task belongs to someone else. Decomposed work usually lives in
+subtasks, so do NOT answer this kind of question from `tasks list` alone:
+that is org-wide, page-capped, and not scoped to a person, so a person's
+subtasks are easily missed.
+
+Resolve a person's `prll://usr_` id from the message context, the members
+list, or ref search; your own id comes from `parall whoami`.
+
 ## Task Commands
 
 ```bash
-# List tasks (filterable by status)
+# List tasks (org-wide; filter by status, assignee, or parent)
 parall tasks list
 parall tasks list --status todo
 parall tasks list --status in_progress
+parall tasks list --assignee-id prll://usr_xxx   # first page only (default 20) — for a person's FULL backlog use 'tasks assigned' above
+parall tasks subtasks prll://tsk_xxx             # children of a single parent task
 
-# Create a task
-parall tasks create --title "Task title" [--assignee-id prll://usr_xxx] [--project-id prll://prj_xxx]
+# Create a task (add --parent-id to make it a SUBTASK of another task)
+parall tasks create --title "Task title" [--assignee-id prll://usr_xxx] [--parent-id prll://tsk_xxx] [--project-id prll://prj_xxx]
 
 # Update task status
 parall tasks update prll://tsk_xxx --status in_progress
@@ -26,6 +49,12 @@ parall tasks update prll://tsk_xxx --status done
 parall tasks comments add prll://tsk_xxx --body "Progress update..."
 ```
 
+Subtasks are just tasks with a parent: create one with `tasks create --parent-id`,
+re-parent with `tasks update --parent-id`, list a parent's children with
+`tasks subtasks`. `tasks list` without `--parent-id` already returns both
+top-level tasks and subtasks; per-person open work is best fetched with
+`tasks assigned` (above).
+
 ## Project Commands
 
 ```bash

package/skills/parall-wiki/SKILL.md

@@ -7,129 +7,175 @@ description: "Parall wiki operations: read, search, edit, and propose changes to
 
 Manage organization wikis via the Parall CLI. Auth is pre-configured.
 
-## Browsing (no local state needed)
+## Mental model
+
+Wiki editing works on a **local workspace**: `parall wiki sync` downloads the
+wiki into a directory on disk, you edit those files with your normal file
+tools, then `parall wiki changeset create` uploads the result as a proposal.
+There is no git in the workspace — your edits are detected by diffing against
+the synced baseline.
+
+Key facts the commands won't tell you:
+
+- **Workspace location is fixed.** Sync output and `parall wiki status` print
+  the absolute workspace path (`synced → /path/to/<slug>` / `Mount: ...`).
+  Always address wiki files by that absolute path — your shell cwd is usually
+  NOT inside the workspace.
+- **Text and binary are two paths.** The workspace + changeset flow is for
+  text (markdown, code, config). Binary assets (images, PDFs, archives) are
+  diff-less — they don't go in the workspace; use `parall wiki file` (see
+  **Binary files** below). Dropping a binary into the workspace just gets it
+  rejected on propose.
+- **`cat`, `search`, `query`, `outline`, and `section` read your local
+  workspace copy when it exists** — including your own unproposed edits. Add
+  `--remote` to `cat` to read the server version instead.
+- **`search`/`query` are keyword (lexical) matching**, not semantic search.
+  `query` additionally ranks whole documents — better for multi-word
+  questions; `search` for a single identifier.
+- The `<wiki>` argument is the slug or ID from `parall wiki list`; with a
+  single wiki in the org it can be omitted.
+
+## Core workflow
 
 ```bash
-parall wiki list                       # List all wikis
-parall wiki tree <slug>                 # List files and directories
-parall wiki tree <slug> --path docs/    # List a subdirectory
+parall wiki sync                                  # 1. get/update files (prints workspace path)
+# 2. read + edit files under the workspace path with standard file tools
+parall wiki diff <wiki>                            # 3. review exactly what you'll propose
+parall wiki changeset create <wiki> --title "..."  # 4. submit
 ```
 
-## Editing
+Always sync before starting and always check `diff` before proposing — the
+changeset uploads the full content of every changed file.
 
-Wiki editing works on a **local workspace** — a directory on disk where wiki
-files are synced. You sync from the server, edit files locally, then propose
-a changeset.
+Unprotected paths auto-merge immediately (`auto_merged: true`); protected
+paths stay open for human review. Follow the returned `next_action` either way.
 
-### Step 1: Sync
+## Stale base (server moved since your sync)
 
-```bash
-parall wiki sync <slug>
-```
-
-This downloads wiki files to a local directory. The output includes the
-**absolute mount path** for each wiki (e.g. `synced → /path/to/workspace/kb`).
-
-### Step 2: Find the mount path
-
-The sync output JSON contains `synced[].path` — the absolute path where files
-live. You can also check it anytime with:
+If files changed on the server after your last sync, `changeset create` is
+rejected — both by a CLI precheck and by the server (409 `STALE_BASE`) — so
+you can't silently overwrite someone's concurrent edit. Recovery:
 
 ```bash
-parall wiki status <slug>
+parall wiki sync          # pull latest; your local edits are preserved
+# if a file conflicts, resolve it (see next section)
+parall wiki changeset create <wiki> --title "..."
 ```
 
-The output includes `Mount: /absolute/path/to/<slug>`.
-
-Use this path with `read`, `write`, and `edit` tools. For example, if the mount
-is `/data/.openclaw/workspace/kb`, then `README.md` is at
-`/data/.openclaw/workspace/kb/README.md`.
+## Sync conflicts
 
-### Step 3: Edit files
+`sync` three-way merges. When both you and the server changed the same file,
+your file is left intact and the upstream copy lands under
+`<workspace>/.parall-wiki/conflicts/`:
 
-Use standard file tools (`read`, `write`, `edit`) on files under the mount path.
+| Marker | Meaning |
+|--------|---------|
+| `conflicts/<path>.remote` | Server has different content for `<path>` |
+| `conflicts/<path>.remote-deleted` | Server deleted `<path>`; you still have edits |
 
-### Step 4: Review changes
+All paths below are relative to the workspace root. Pick one:
 
 ```bash
-parall wiki diff <slug>       # Shows unified diff of all local changes
-parall wiki status <slug>     # Shows which files changed with +/- line counts
+# Accept upstream (drop your edit):
+cp <workspace>/.parall-wiki/conflicts/<path>.remote <workspace>/<path>
+
+# Keep yours / hand-merge: edit <workspace>/<path> to final content, then
+parall wiki changeset create <wiki> --title "Reconcile <path>"
+
+# Accept server delete (.remote-deleted only):
+rm <workspace>/<path>
 ```
 
-Always review before proposing.
+Then re-run `parall wiki sync` and delete the used marker file. Conflicts
+exit 0 (they need your decision); `failed[]` entries (download error,
+shape-conflict) exit 1 and retry on the next sync.
 
-### Step 5: Propose changeset
+## Changesets
 
 ```bash
-parall wiki changeset create <slug> --title "Description of changes"
+parall wiki changeset list <wiki>
+parall wiki changeset show <changesetId> <wiki>     # status + feedback
+parall wiki changeset diff <changesetId> <wiki>
+parall wiki changeset create <wiki> --update <id>   # re-propose after rejection (title inherited)
 ```
 
-This uploads your local changes. Unprotected paths auto-merge immediately; the
-CLI prints `auto_merged: true` and refreshes the local manifest. Protected
-paths remain as a changeset for review; follow the returned `next_action`.
+Rejected: read the feedback (`show` / `status`), fix the files, re-propose
+with `--update <id>`. Conflict status: `sync`, resolve, then `--update <id>`.
 
-## Changeset Management
+Re-propose REPLACES the changeset's previous contents with your current
+workspace diff — to withdraw a file from the proposal, revert it locally
+(restore the synced content) and re-propose; it drops out of the changeset.
 
-```bash
-parall wiki changeset list <slug>               # List all changesets
-parall wiki changeset show <changesetId> <slug> # Show detail + feedback
-parall wiki changeset diff <changesetId> <slug> # Show changeset diff
-```
+## Binary files
 
-If a changeset is rejected, fix the files locally and re-propose:
+Images, PDFs, archives — anything that can't be diffed — bypass the workspace
+and changeset-text flow entirely. They never belong in the synced workspace
+(propose rejects them); use `parall wiki file` instead. `cat` is text-only —
+to read a binary's real bytes use `file get` (a plain `sync` only leaves a
+few-line Git-LFS pointer on disk, since the runtime has no git-lfs).
 
 ```bash
-parall wiki changeset create <slug> --update <changesetId>
-```
+# Maintainer: direct-commit a binary to the default branch (no review)
+parall wiki file upload ./diagram.png docs/assets/diagram.png
 
-The title is inherited from the original changeset — no need to repeat it.
+# Read a binary's real bytes (LFS pointers resolved server-side) to a file.
+# Always use --output for binaries — without it the bytes stream to stdout and
+# would flood your context.
+parall wiki file get docs/assets/diagram.png --output ./diagram.png
+parall wiki file get docs/assets/diagram.png --ref <commit-or-branch> --output ./diagram.png   # a specific revision
 
-## Handling sync conflicts
+# Remove a binary from the default branch (git history still has it)
+parall wiki file delete docs/assets/diagram.png
+```
 
-`wiki sync` runs a three-way merge. When both you and the server changed the
-same file, sync **does not overwrite your work**. It leaves your file intact
-and drops the upstream version under `.parall-wiki/conflicts/`:
+`upload` needs **maintain**; it routes by size automatically (≤1 MiB inline,
+larger → LFS). A text file sent to `upload` is rejected — that's the changeset
+flow's job.
 
-| Marker | Meaning |
-|--------|---------|
-| `.parall-wiki/conflicts/<path>.remote` | Server has different content (concurrent edit, new file collision, or server changed a file you deleted) |
-| `.parall-wiki/conflicts/<path>.remote-deleted` | Server deleted the file; you still have edits |
+### Reader: propose markdown that embeds an image
 
-stderr prints one line per conflict. Recovery:
+Without maintain you can still propose a doc with images — upload the binary
+into your **changeset's** branch (read + author), not the default branch:
 
-**Accept upstream** (drop your edit):
 ```bash
-cp .parall-wiki/conflicts/<path>.remote <path>
 parall wiki sync
+# edit a .md in the workspace to add  ![alt](assets/foo.png)
+parall wiki changeset create <wiki> --title "Add foo diagram"          # creates the changeset (note its id)
+parall wiki file upload ./foo.png assets/foo.png <wiki> --changeset <changesetId>
+# leave it for a maintainer to merge — both the markdown and the image squash in together
 ```
 
-**Keep yours** (or hand-merge, then propose):
-```bash
-# edit <path> to final content
-parall wiki diff <slug>
-parall wiki changeset create <slug> --title "Reconcile <path>"
-parall wiki sync   # fast-forwards after server merges
-```
+Do the markdown `changeset create` first so the changeset exists, then attach
+the image to it. Don't re-propose (`--update`) after attaching a binary —
+re-propose replays only the text workspace and the server rejects dropping the
+attached binary (422 `REPLACE_HAS_BINARY`).
+
+## Discovery & history
 
-**Accept server delete** (`.remote-deleted` only):
 ```bash
-rm <path>
-parall wiki sync
+parall wiki query "how is auth configured" <wiki>   # multi-word lookup (query FIRST, wiki second)
+parall wiki search "JWT" <wiki>                     # single keyword (query FIRST, wiki second)
+parall wiki outline <wiki> --path docs/             # heading structure
+parall wiki cat docs/auth.md <wiki>                 # print a file (--remote for server version)
+parall wiki tree <wiki>                             # list files
+parall wiki log <wiki>                              # recent operations
+parall wiki log <wiki> docs/auth.md                 # per-file commit history
 ```
 
-Sync failures (`download`, `shape-conflict`) set exit code 1 and retry on
-next sync. Conflicts exit 0 — they need your decision, not a retry.
-
-## Discarding local changes
+## Permissions
 
-```bash
-parall wiki reset <slug>      # Restore all files to last synced state
-```
+Reads and writes are ACL-checked server-side per path. `parall wiki access
+<path>` shows your level for a path. On a `PERMISSION_DENIED`, errors include
+a `Request approval:` hint — use `parall wiki request-access <path> --reason
+"..."` to file an approval card for a maintainer, then re-sync after approval.
 
-## History
+## Recovery
 
 ```bash
-parall wiki log <slug>        # Recent wiki operations
+parall wiki reset <wiki>    # discard ALL local edits, restore last-synced state
+parall wiki status <wiki>   # local changes + your changesets, anytime
 ```
 
-CLI success output is JSON; errors may add a plain-text `Request approval:` line on a `PERMISSION_DENIED` — read both. Run `parall wiki --help` for full options.
+CLI success output is JSON on stdout (human summary on stderr); errors state
+the reason and the next step — follow them. `parall wiki --help` for the
+full command list.