@agent-native/core 0.101.6 → 0.101.7

package/corpus/core/src/integrations/adapters/google-docs.ts

@@ -6,6 +6,7 @@ import type {
   IncomingMessage,
   OutgoingMessage,
   IntegrationStatus,
+  PlatformDeliveryReceipt,
 } from "../types.js";
 
 /** Google Docs comment replies have no formal length limit but keep it reasonable */
@@ -303,7 +304,7 @@ export function googleDocsAdapter(): PlatformAdapter {
     async sendResponse(
       message: OutgoingMessage,
       context: IncomingMessage,
-    ): Promise<void> {
+    ): Promise<void | PlatformDeliveryReceipt> {
       const fileId = context.platformContext.fileId as string;
       const commentId = context.platformContext.commentId as string;
 
@@ -319,8 +320,10 @@ export function googleDocsAdapter(): PlatformAdapter {
           await replyToComment(fileId, commentId, chunk, accessToken);
         } catch (err) {
           console.error("[google-docs] Failed to send reply:", err);
+          throw err;
         }
       }
+      return { status: "delivered" };
     },
 
     formatAgentResponse(text: string): OutgoingMessage {

package/corpus/core/src/integrations/adapters/microsoft-teams.ts

@@ -8,6 +8,7 @@ import type {
   IntegrationStatus,
   OutgoingMessage,
   PlatformAdapter,
+  PlatformDeliveryReceipt,
 } from "../types.js";
 
 const BOT_FRAMEWORK_SCOPE = "https://api.botframework.com/.default";
@@ -201,7 +202,7 @@ export function microsoftTeamsAdapter(): PlatformAdapter {
     async sendResponse(
       message: OutgoingMessage,
       context: IncomingMessage,
-    ): Promise<void> {
+    ): Promise<void | PlatformDeliveryReceipt> {
       const serviceUrl = normalizeServiceUrl(
         context.platformContext.serviceUrl,
       );
@@ -242,6 +243,7 @@ export function microsoftTeamsAdapter(): PlatformAdapter {
           `Microsoft Teams reply failed (HTTP ${response.status})`,
         );
       }
+      return { status: "delivered" };
     },
 
     formatAgentResponse(text: string): OutgoingMessage {

package/corpus/core/src/integrations/adapters/slack.ts

@@ -23,6 +23,7 @@ import type {
   OutboundTarget,
   PlatformRunProgress,
   PlatformRunProgressRef,
+  PlatformDeliveryReceipt,
   IntegrationContextMessage,
   IntegrationFileReference,
 } from "../types.js";
@@ -431,11 +432,12 @@ export function slackAdapter(
       message: OutgoingMessage,
       context: IncomingMessage,
       opts?: { placeholderRef?: string },
-    ): Promise<void> {
+    ): Promise<void | PlatformDeliveryReceipt> {
       const token = await resolveBotToken(context);
       if (!token) {
-        console.error("[slack] SLACK_BOT_TOKEN not configured");
-        return;
+        throw new Error(
+          "[slack] Cannot deliver response: no Slack bot token is configured",
+        );
       }
 
       const channelId = context.platformContext.channelId as string;
@@ -458,6 +460,7 @@ export function slackAdapter(
         return;
       }
       const restChunks = chunks.slice(1);
+      const messageRefs: string[] = [];
 
       const finalBlocks =
         blocks ??
@@ -489,14 +492,29 @@ export function slackAdapter(
           const data = (await res.json()) as {
             ok: boolean;
             error?: string;
+            ts?: string;
           };
           if (!data.ok) {
             console.error("[slack] chat.update error:", data.error);
             // Fall back to a fresh post so the user still sees a reply
-            await postFresh(token, channelId, threadTs, baseBody);
+            const postedTs = await postFresh(
+              token,
+              channelId,
+              threadTs,
+              baseBody,
+            );
+            if (postedTs) messageRefs.push(postedTs);
+          } else {
+            messageRefs.push(data.ts || placeholderRef);
           }
         } else {
-          await postFresh(token, channelId, threadTs, baseBody);
+          const postedTs = await postFresh(
+            token,
+            channelId,
+            threadTs,
+            baseBody,
+          );
+          if (postedTs) messageRefs.push(postedTs);
         }
 
         // Clear the AI-assistant "is thinking…" status now that we've
@@ -507,14 +525,19 @@ export function slackAdapter(
 
         // Overflow chunks (rare) — post as plain follow-ups in the same thread
         for (const chunk of restChunks) {
-          await postFresh(token, channelId, threadTs, {
+          const postedTs = await postFresh(token, channelId, threadTs, {
             channel: channelId,
             text: chunk,
             unfurl_links: false,
             unfurl_media: false,
             mrkdwn: true,
           });
+          if (postedTs) messageRefs.push(postedTs);
         }
+        return {
+          status: "delivered",
+          ...(messageRefs.length > 0 ? { messageRefs } : {}),
+        };
       } catch (err) {
         console.error("[slack] Failed to send message:", err);
         throw err;
@@ -992,7 +1015,7 @@ async function postFresh(
   channelId: string,
   threadTs: string | undefined,
   body: Record<string, unknown>,
-): Promise<void> {
+): Promise<string | undefined> {
   const hasBlocks =
     Array.isArray(body.blocks) && (body.blocks as unknown[]).length > 0;
   if (
@@ -1000,7 +1023,7 @@ async function postFresh(
     body.text.trim().length === 0 &&
     !hasBlocks
   ) {
-    return;
+    return undefined;
   }
 
   const payload: Record<string, unknown> = {
@@ -1016,11 +1039,16 @@ async function postFresh(
     },
     body: JSON.stringify(payload),
   });
-  const data = (await res.json()) as { ok: boolean; error?: string };
+  const data = (await res.json()) as {
+    ok: boolean;
+    error?: string;
+    ts?: string;
+  };
   if (!data.ok) {
     console.error("[slack] chat.postMessage error:", data.error);
     throw new Error(data.error || "chat.postMessage failed");
   }
+  return data.ts;
 }
 
 async function slackApiFetch(
@@ -1871,6 +1899,7 @@ function createSlackRunProgress(
           : {}),
       });
       setSlackAssistantStatus(token, channel, threadTs, "");
+      return { status: "delivered", messageRefs: [streamTs] };
     },
     async fail(message) {
       if (pendingTimer) clearTimeout(pendingTimer);

package/corpus/core/src/integrations/adapters/telegram.ts

@@ -10,6 +10,7 @@ import type {
   OutgoingMessage,
   IntegrationStatus,
   OutboundTarget,
+  PlatformDeliveryReceipt,
 } from "../types.js";
 
 /** Telegram's max message length */
@@ -194,7 +195,7 @@ export function telegramAdapter(): PlatformAdapter {
     async sendResponse(
       message: OutgoingMessage,
       context: IncomingMessage,
-    ): Promise<void> {
+    ): Promise<void | PlatformDeliveryReceipt> {
       const token = await resolveSecret("TELEGRAM_BOT_TOKEN");
       if (!token) {
         console.error("[telegram] TELEGRAM_BOT_TOKEN not configured");
@@ -235,22 +236,43 @@ export function telegramAdapter(): PlatformAdapter {
           if (!data.ok) {
             // Retry without Markdown if parsing fails
             if (data.description?.includes("parse")) {
-              await fetch(`https://api.telegram.org/bot${token}/sendMessage`, {
-                method: "POST",
-                headers: { "Content-Type": "application/json" },
-                body: JSON.stringify({
-                  ...body,
-                  parse_mode: undefined,
-                }),
-              });
+              const retry = await fetch(
+                `https://api.telegram.org/bot${token}/sendMessage`,
+                {
+                  method: "POST",
+                  headers: { "Content-Type": "application/json" },
+                  body: JSON.stringify({
+                    ...body,
+                    parse_mode: undefined,
+                  }),
+                },
+              );
+              if (!retry.ok) {
+                throw new Error(
+                  `Telegram sendMessage retry failed (HTTP ${retry.status})`,
+                );
+              }
+              const retryData = (await retry.json()) as {
+                ok: boolean;
+                description?: string;
+              };
+              if (!retryData.ok) {
+                throw new Error(
+                  `Telegram sendMessage retry failed: ${retryData.description ?? "unknown error"}`,
+                );
+              }
             } else {
-              console.error("[telegram] sendMessage error:", data.description);
+              throw new Error(
+                `Telegram sendMessage failed: ${data.description ?? "unknown error"}`,
+              );
             }
           }
         } catch (err) {
           console.error("[telegram] Failed to send message:", err);
+          throw err;
         }
       }
+      return { status: "delivered" };
     },
 
     async sendMessageToTarget(

package/corpus/core/src/integrations/adapters/whatsapp.ts

@@ -8,6 +8,7 @@ import type {
   IncomingMessage,
   OutgoingMessage,
   IntegrationStatus,
+  PlatformDeliveryReceipt,
 } from "../types.js";
 
 /** WhatsApp's max message length */
@@ -240,7 +241,7 @@ export function whatsappAdapter(): PlatformAdapter {
     async sendResponse(
       message: OutgoingMessage,
       context: IncomingMessage,
-    ): Promise<void> {
+    ): Promise<void | PlatformDeliveryReceipt> {
       const accessToken = await resolveSecret("WHATSAPP_ACCESS_TOKEN");
       const phoneNumberId = await resolveSecret("WHATSAPP_PHONE_NUMBER_ID");
       if (!accessToken || !phoneNumberId) {
@@ -279,11 +280,14 @@ export function whatsappAdapter(): PlatformAdapter {
           if (!res.ok) {
             const data = await res.json().catch(() => ({}));
             console.error("[whatsapp] sendMessage error:", data);
+            throw new Error(`WhatsApp sendMessage failed (HTTP ${res.status})`);
           }
         } catch (err) {
           console.error("[whatsapp] Failed to send message:", err);
+          throw err;
         }
       }
+      return { status: "delivered" };
     },
 
     formatAgentResponse(text: string): OutgoingMessage {

package/corpus/core/src/integrations/index.ts

@@ -15,6 +15,7 @@ export type {
   IntegrationConversationType,
   IntegrationTriggerKind,
   PlatformRunProgress,
+  PlatformDeliveryReceipt,
 } from "./types.js";
 export { assertPlatformCapability } from "./types.js";
 

package/corpus/core/src/integrations/types.ts

@@ -127,6 +127,13 @@ export interface OutgoingMessage {
   platformContext: Record<string, unknown>;
 }
 
+/** Provider-confirmed references for a successfully delivered response. */
+export interface PlatformDeliveryReceipt {
+  status: "delivered";
+  /** Opaque provider message ids/timestamps; never message content. */
+  messageRefs?: string[];
+}
+
 /**
  * Proactive outbound message target for a platform.
  * Used when the agent needs to send to a saved destination instead of replying
@@ -197,7 +204,7 @@ export interface PlatformRunProgress {
   /** Receive normalized agent events. Implementations should throttle writes. */
   onEvent(event: AgentChatEvent): Promise<void> | void;
   /** Finalize the provider-native progress surface with the answer. */
-  complete(message: OutgoingMessage): Promise<void>;
+  complete(message: OutgoingMessage): Promise<void | PlatformDeliveryReceipt>;
   /** Mark the provider-native surface failed and leave a retryable explanation. */
   fail?(message: string): Promise<void>;
 }
@@ -316,7 +323,7 @@ export interface PlatformAdapter {
     message: OutgoingMessage,
     context: IncomingMessage,
     opts?: { placeholderRef?: string },
-  ): Promise<void>;
+  ): Promise<void | PlatformDeliveryReceipt>;
 
   /**
    * Send a short best-effort system notice to the conversation the incoming

package/corpus/core/src/integrations/webhook-handler.ts

@@ -2,6 +2,7 @@ import type { H3Event } from "h3";
 
 import {
   appendA2AArtifactLinks,
+  extractA2AArtifactIdentities,
   type A2AToolResultSummary,
 } from "../a2a/artifact-response.js";
 import { collectFinalResponseTextFromAgentEvents } from "../a2a/response-text.js";
@@ -35,6 +36,7 @@ import {
 import {
   buildAssistantMessage,
   extractThreadMeta,
+  threadDataToEngineMessages,
 } from "../agent/thread-data-builder.js";
 import { attachToolSearch } from "../agent/tool-search.js";
 import { createThread, getThread } from "../chat-threads/store.js";
@@ -63,7 +65,11 @@ import {
 } from "./pending-tasks-store.js";
 import { integrationScopeSubjectKey } from "./scope-store.js";
 import { getThreadMapping, saveThreadMapping } from "./thread-mapping-store.js";
-import type { PlatformAdapter, IncomingMessage } from "./types.js";
+import type {
+  PlatformAdapter,
+  IncomingMessage,
+  PlatformDeliveryReceipt,
+} from "./types.js";
 import {
   listIntegrationUsageBudgets,
   releaseIntegrationUsageBudget,
@@ -710,34 +716,7 @@ async function processIncomingMessage(
   }
   const existingMessages: EngineMessage[] = [];
   if (thread?.threadData) {
-    try {
-      const data = JSON.parse(thread.threadData);
-      if (Array.isArray(data.messages)) {
-        for (const msg of data.messages) {
-          const m = msg.message ?? msg;
-          const textContent =
-            typeof m.content === "string"
-              ? m.content
-              : Array.isArray(m.content)
-                ? m.content
-                    .filter((c: any) => c.type === "text")
-                    .map((c: any) => c.text)
-                    .join("\n")
-                : "";
-          if (m.role === "user") {
-            existingMessages.push({
-              role: "user",
-              content: [{ type: "text", text: textContent }],
-            });
-          } else if (m.role === "assistant") {
-            existingMessages.push({
-              role: "assistant",
-              content: [{ type: "text", text: textContent }],
-            });
-          }
-        }
-      }
-    } catch {}
+    existingMessages.push(...threadDataToEngineMessages(thread.threadData));
   }
 
   // Add the new user message. Include verified platform identity as lightweight
@@ -988,12 +967,11 @@ async function processIncomingMessage(
           // preview card.
           const baseUrl = process.env.APP_URL || process.env.URL || "";
           const appBaseUrl = baseUrl ? withConfiguredAppBasePath(baseUrl) : "";
+          const toolResults = collectToolResultSummaries(completedRun);
           if (!suppressPlatformReply) {
-            responseText = appendA2AArtifactLinks(
-              responseText,
-              collectToolResultSummaries(completedRun),
-              { baseUrl: appBaseUrl || undefined },
-            );
+            responseText = appendA2AArtifactLinks(responseText, toolResults, {
+              baseUrl: appBaseUrl || undefined,
+            });
           }
           const threadDeepLinkUrl =
             appBaseUrl && threadId
@@ -1002,34 +980,60 @@ async function processIncomingMessage(
 
           // Format and send back to platform — update the "thinking…"
           // placeholder in place if the adapter supplied one.
+          let deliveredResponse:
+            | {
+                platform: string;
+                status: "delivered";
+                text: string;
+                deliveredAt: string;
+                messageRefs?: string[];
+              }
+            | undefined;
           if (!suppressPlatformReply) {
             const outgoing = adapter.formatAgentResponse(responseText, {
               threadDeepLinkUrl,
             });
-            let delivered = false;
+            let deliveryReceipt: void | PlatformDeliveryReceipt;
             if (queuedA2AContinuation && progress?.ref) {
               // Post substantive parent results as a normal thread reply while
               // the one continuation that claimed this resumable stream keeps
               // it open for its eventual terminal result.
-              await adapter.sendResponse(outgoing, incoming, {
+              deliveryReceipt = await adapter.sendResponse(outgoing, incoming, {
                 placeholderRef: opts.placeholderRef,
               });
-              delivered = true;
             } else if (progress) {
               try {
-                await progress.complete(outgoing);
-                delivered = true;
+                deliveryReceipt = await progress.complete(outgoing);
               } catch {
-                await adapter.sendResponse(outgoing, incoming, {
-                  placeholderRef: opts.placeholderRef,
-                });
-                delivered = true;
+                deliveryReceipt = await adapter.sendResponse(
+                  outgoing,
+                  incoming,
+                  {
+                    placeholderRef: opts.placeholderRef,
+                  },
+                );
               }
             } else {
-              await adapter.sendResponse(outgoing, incoming, {
+              deliveryReceipt = await adapter.sendResponse(outgoing, incoming, {
                 placeholderRef: opts.placeholderRef,
               });
-              delivered = true;
+            }
+            const delivered = deliveryReceipt?.status === "delivered";
+            if (!delivered) {
+              throw new Error(
+                `${incoming.platform} response completed without delivery proof`,
+              );
+            }
+            if (delivered) {
+              deliveredResponse = {
+                platform: incoming.platform,
+                status: "delivered",
+                text: outgoing.text,
+                deliveredAt: new Date().toISOString(),
+                ...(deliveryReceipt?.messageRefs?.length
+                  ? { messageRefs: deliveryReceipt.messageRefs }
+                  : {}),
+              };
             }
             if (slackInputRequest && delivered && incoming.senderId) {
               await setIntegrationAwaitingInput({
@@ -1078,6 +1082,8 @@ async function processIncomingMessage(
             incoming.text,
             completedRun,
             thread,
+            deliveredResponse,
+            toolResults,
           );
           await recordIntegrationUsage({
             usage,
@@ -1533,6 +1539,14 @@ async function persistThreadData(
   userText: string,
   completedRun: ActiveRun,
   thread: any,
+  deliveredResponse?: {
+    platform: string;
+    status: "delivered";
+    text: string;
+    deliveredAt: string;
+    messageRefs?: string[];
+  },
+  toolResults: A2AToolResultSummary[] = [],
 ): Promise<void> {
   try {
     let repo: any;
@@ -1556,6 +1570,16 @@ async function persistThreadData(
       completedRun.events ?? [],
       completedRun.runId,
     );
+    if (assistantMsg) {
+      assistantMsg.metadata.integrationDeliveryAttempted = true;
+      if (deliveredResponse) {
+        assistantMsg.metadata.integrationDelivery = deliveredResponse;
+        const artifactIdentities = extractA2AArtifactIdentities(toolResults);
+        if (artifactIdentities.length > 0) {
+          assistantMsg.metadata.integrationArtifacts = artifactIdentities;
+        }
+      }
+    }
 
     repo.messages.push(userMsg);
     if (assistantMsg) {

package/corpus/core/src/server/agent-chat/action-filters-a2a.ts

@@ -110,6 +110,7 @@ export function assembleA2AFinalResponse(
   const finalText = appendA2AArtifactLinks(responseText, [...toolResults], {
     baseUrl: options.baseUrl ?? resolveArtifactBaseUrl(options.event),
     includeReferencedArtifacts: true,
+    includePersistedArtifactMarker: true,
   });
   if (terminalError && !finalText.trim()) {
     throw new Error(formatA2ATerminalError(terminalError));

package/corpus/templates/content/.agents/skills/content/SKILL.md

@@ -101,6 +101,37 @@ inferences for confirmation, then submit once. When required information is
 missing, keep the clarification in the originating thread and retain earlier
 answers as context.
 
+### Slack Follow-ups And Corrections
+
+A follow-up in an existing Slack thread is not automatically a new intake. Read
+the thread context and inspect the prior Content artifact identity first,
+including any returned document ID or `/page/<id>` path and the canonical
+database row when available. Then choose the operation that matches the user's
+intent:
+
+- **Update** the same document for corrections, refinements, status changes, or
+  renames that still describe the same request. A rename changes the title, not
+  the artifact identity: preserve the stable Content document ID and page path.
+- **Add** new details to the same document when the follow-up extends the
+  original request without replacing it.
+- **Supersede** only when the user intends a replacement artifact or distinct
+  successor and the workspace's schema or instructions define how that
+  relationship is recorded. Preserve a concrete link to the prior artifact.
+- **Create** only when the follow-up is genuinely a separate request or the user
+  explicitly asks for a new artifact. Do not blindly submit another row merely
+  because a new Slack message arrived.
+
+Apply people fields from verified identity and intent, not from convenient
+guesswork:
+
+- When the database has a `Requester` field, default it to the verified Slack
+  sender unless the user explicitly identifies a different requester.
+- A named doer such as "for Apoorva" maps to `Assignee` when that field exists.
+  Naming an assignee never changes or replaces `Requester`.
+- Resolve named people to the database's accepted person identity before
+  writing. If a named person cannot be resolved unambiguously, clarify in the
+  originating Slack thread; never omit, downgrade, or silently drop the person.
+
 ## Local File Mode
 
 Install into an existing repo with:

package/corpus/templates/content/.agents/skills/document-editing/SKILL.md

@@ -7,7 +7,10 @@ description: >-
 
 # Document Editing
 
-Documents are stored in the SQL database via Drizzle ORM. Each document has a title, markdown content, optional parent (for nesting), and a position for ordering.
+Documents are stored in the SQL database via Drizzle ORM. Each document has a
+title, stable description, markdown content, optional parent (for nesting), and
+a position for ordering. The description explains why the page exists and what
+belongs there; it is not a changing synopsis of the current body.
 
 ## Scripts
 
@@ -48,6 +51,7 @@ Create a new document.
 pnpm action create-document --title "Meeting Notes" --content "# Meeting Notes\n\nAttendees: ..."
 pnpm action create-document --title "Sub Page" --parentId parent123
 pnpm action create-document --title "My Page" --icon "📝"
+pnpm action create-document --title "Research" --description "Evidence and source notes that support the current project"
 ```
 
 ### edit-document
@@ -73,6 +77,7 @@ Update an existing document. Use for **full rewrites or new content**, not for s
 pnpm action update-document --id abc123 --title "New Title"
 pnpm action update-document --id abc123 --content "# Updated Content\n\nNew text here"
 pnpm action update-document --id abc123 --title "New Title" --content "New content"
+pnpm action update-document --id abc123 --description "Stable guidance for what belongs on this page"
 ```
 
 ### delete-document
@@ -123,17 +128,18 @@ Always run this after any document modification to update the sidebar.
 
 ## Document Schema
 
-| Column       | Type    | Description                             |
-| ------------ | ------- | --------------------------------------- |
-| `id`         | text    | Primary key (12-char hex string)        |
-| `parent_id`  | text    | Parent document ID (null for root)      |
-| `title`      | text    | Document title (default: "Untitled")    |
-| `content`    | text    | Markdown content                        |
-| `icon`       | text    | Emoji icon (optional)                   |
-| `position`   | integer | Sort order within parent (0-based)      |
-| `is_favorite`| integer | Whether document is favorited (0 or 1)  |
-| `created_at` | text    | ISO timestamp                           |
-| `updated_at` | text    | ISO timestamp                           |
+| Column        | Type    | Description                            |
+| ------------- | ------- | -------------------------------------- |
+| `id`          | text    | Primary key (12-char hex string)       |
+| `parent_id`   | text    | Parent document ID (null for root)     |
+| `title`       | text    | Document title (default: "Untitled")   |
+| `description` | text    | Stable semantic guidance for the page  |
+| `content`     | text    | Markdown content                       |
+| `icon`        | text    | Emoji icon (optional)                  |
+| `position`    | integer | Sort order within parent (0-based)     |
+| `is_favorite` | integer | Whether document is favorited (0 or 1) |
+| `created_at`  | text    | ISO timestamp                          |
+| `updated_at`  | text    | ISO timestamp                          |
 
 ## Content Format
 
@@ -142,21 +148,29 @@ Documents use **markdown** for content. The editor renders markdown in real time
 ## Parent-Child Hierarchy
 
 Documents form a tree via `parent_id`:
+
 - Root documents have `parent_id = null`
 - Child documents reference their parent's `id`
 - Deleting a parent recursively deletes all children
 - Position determines ordering within the same parent
 
+Descriptions are owned; context is inherited. `get-document` and `view-screen`
+return the focused page's own description plus a computed root-to-parent
+`contextPath`. Use that path to understand where the page lives, but never copy
+ancestor descriptions into the child. Database, property, and option
+descriptions narrow the guidance further when working with structured values.
+
 ## Common Tasks
 
-| User says                     | What to do                                                       |
-| ----------------------------- | ---------------------------------------------------------------- |
-| "Create a page about X"       | `create-document --title "X" --content "# X\n\n..."`           |
-| "Find my meeting notes"       | `search-documents --query "meeting notes"`                      |
-| "Fix a typo / edit a line"    | `view-screen` to get ID, then `edit-document --id ... --find "old" --replace "new"` |
-| "Rewrite this document"       | `view-screen` to get ID, then `update-document --id ... --content ...` |
-| "Delete this page"            | `view-screen` to get ID, then `delete-document --id ...`       |
-| "Add a sub-page"              | `create-document --title "Sub" --parentId <parentId>`           |
-| "Show me the document tree"   | `list-documents`                                                |
+| User says                    | What to do                                                                          |
+| ---------------------------- | ----------------------------------------------------------------------------------- |
+| "Create a page about X"      | `create-document --title "X" --content "# X\n\n..."`                                |
+| "Describe what belongs here" | `update-document --id ... --description "..."`                                      |
+| "Find my meeting notes"      | `search-documents --query "meeting notes"`                                          |
+| "Fix a typo / edit a line"   | `view-screen` to get ID, then `edit-document --id ... --find "old" --replace "new"` |
+| "Rewrite this document"      | `view-screen` to get ID, then `update-document --id ... --content ...`              |
+| "Delete this page"           | `view-screen` to get ID, then `delete-document --id ...`                            |
+| "Add a sub-page"             | `create-document --title "Sub" --parentId <parentId>`                               |
+| "Show me the document tree"  | `list-documents`                                                                    |
 
 Always run `refresh-list` after any create, update, or delete operation.