@plotday/twister 0.35.0 → 0.37.0

package/cli/templates/AGENTS.template.md

@@ -19,79 +19,78 @@ Plot Twists are TypeScript classes that extend the `Twist` base class. Twists in
 - **Store intermediate state**: Use the Store tool to persist state between batches
 - **Examples**: Syncing large datasets, processing many API calls, or performing batch operations
 
-## Understanding Activities and Notes
+## Understanding Threads and Notes
 
-**CRITICAL CONCEPT**: An **Activity** represents something done or to be done (a task, event, or conversation), while **Notes** represent the updates and details on that activity.
+**CRITICAL CONCEPT**: A **Thread** represents something done or to be done (a task, event, or conversation), while **Notes** represent the updates and details on that thread.
 
-**Think of an Activity as a thread** on a messaging platform, and **Notes as the messages in that thread**.
+**Think of a Thread as a thread** on a messaging platform, and **Notes as the messages in that thread**.
 
 ### Key Guidelines
 
-1. **Always create Activities with an initial Note** - The title is just a summary; detailed content goes in Notes
-2. **Add Notes to existing Activities for updates** - Don't create a new Activity for each related message
-3. **Use Activity.source and Note.key for automatic upserts (Recommended)** - Set Activity.source to the external item's URL for deduplication, and use Note.key for upsertable note content. No manual ID tracking needed.
-4. **For advanced cases, use generated UUIDs** - Only when you need multiple Plot activities per external item (see SYNC_STRATEGIES.md)
-5. **Most Activities should be `ActivityType.Note`** - Use `Action` only for tasks with `done`, use `Event` only for items with `start`/`end`
+1. **Always create Threads with an initial Note** - The title is just a summary; detailed content goes in Notes
+2. **Add Notes to existing Threads for updates** - Don't create a new Thread for each related message
+3. **Use Thread.source and Note.key for automatic upserts (Recommended)** - Set Thread.source to the external item's URL for deduplication, and use Note.key for upsertable note content. No manual ID tracking needed.
+4. **For advanced cases, use generated UUIDs** - Only when you need multiple Plot threads per external item (see SYNC_STRATEGIES.md)
+5. **Most Threads should be `ThreadType.Note`** - Use `Action` only for tasks with `done`, use `Event` only for items with `start`/`end`
 
 ### Recommended Decision Tree (Strategy 2: Upsert via Source/Key)
 
 ```
 New event/task/conversation from external system?
   ├─ Has stable URL or ID?
-  │   └─ Yes → Set Activity.source to the canonical URL/ID
-  │             Create Activity (Plot handles deduplication automatically)
+  │   └─ Yes → Set Thread.source to the canonical URL/ID
+  │             Create Thread (Plot handles deduplication automatically)
   │             Use Note.key for different note types:
   │               - "description" for main content
   │               - "metadata" for status/priority/assignee
   │               - "comment-{id}" for individual comments
   │
-  └─ No stable identifier OR need multiple Plot activities per external item?
+  └─ No stable identifier OR need multiple Plot threads per external item?
       └─ Use Advanced Pattern (Strategy 3: Generate and Store IDs)
           See SYNC_STRATEGIES.md for details
 ```
 
 ### Advanced Decision Tree (Strategy 3: Generate and Store IDs)
 
-Only use when source/key upserts aren't sufficient (e.g., creating multiple activities from one external item):
+Only use when source/key upserts aren't sufficient (e.g., creating multiple threads from one external item):
 
 ```
 New event/task/conversation?
   ├─ Yes → Generate UUID with Uuid.Generate()
-  │         Create new Activity with that UUID
-  │         Store mapping: external_id → activity_uuid
+  │         Create new Thread with that UUID
+  │         Store mapping: external_id → thread_uuid
   │
   └─ No (update/reply/comment) → Look up mapping by external_id
-      ├─ Found → Add Note to existing Activity using stored UUID
-      └─ Not found → Create new Activity with UUID + store mapping
+      ├─ Found → Add Note to existing Thread using stored UUID
+      └─ Not found → Create new Thread with UUID + store mapping
 ```
 
 ## Twist Structure Pattern
 
 ```typescript
 import {
-  type Activity,
+  type Thread,
+  type NewThreadWithNotes,
+  type ThreadFilter,
   type Priority,
   type ToolBuilder,
-  twist,
+  Twist,
+  ThreadType,
 } from "@plotday/twister";
-import { Plot } from "@plotday/twister/tools/plot";
-import { Uuid } from "@plotday/twister/utils/uuid";
+import { ThreadAccess, Plot } from "@plotday/twister/tools/plot";
+// Import your sources or tools as needed
 
 export default class MyTwist extends Twist<MyTwist> {
   build(build: ToolBuilder) {
     return {
-      plot: build(Plot),
+      plot: build(Plot, {
+        thread: { access: ThreadAccess.Create },
+      }),
     };
   }
 
-  async activate(priority: Pick<Priority, "id">) {
-    // Called when twist is enabled for a priority
-    // Common actions: request auth, create setup activities
-  }
-
-  async activity(activity: Activity) {
-    // Called when an activity is routed to this twist
-    // Common actions: process external events, update activities
+  async activate(_priority: Pick<Priority, "id">) {
+    // Auth and resource selection handled in the twist edit modal.
   }
 }
 ```
@@ -132,238 +131,197 @@ For complete API documentation of built-in tools including all methods, types, a
 
 **Critical**: Never use instance variables for state. They are lost after function execution. Always use Store methods.
 
-### External Tools (Add to package.json)
-
-Add tool dependencies to `package.json`:
-
-```json
-{
-  "dependencies": {
-    "@plotday/twister": "workspace:^",
-    "@plotday/tool-google-calendar": "workspace:^"
-  }
-}
-```
-
-#### Common External Tools
-
-- `@plotday/tool-google-calendar`: Google Calendar integration
-- `@plotday/tool-outlook-calendar`: Outlook Calendar integration
-- `@plotday/tool-google-contacts`: Google Contacts integration
-
 ## Lifecycle Methods
 
 ### activate(priority: Pick<Priority, "id">)
 
-Called when the twist is enabled for a priority. Common patterns:
+Called when the twist is enabled for a priority. Auth and resource selection are handled automatically via the twist edit modal when using external tools with Integrations.
 
-**Request Authentication:**
+Most twists have an empty or minimal `activate()`:
 
 ```typescript
 async activate(_priority: Pick<Priority, "id">) {
-  const authLink = await this.tools.externalTool.requestAuth(
-    this.onAuthComplete,
-    "google"
-  );
-
-  await this.tools.plot.createActivity({
-    type: ActivityType.Note,
-    title: "Connect your account",
-    notes: [
-      {
-        content: "Click the link below to connect your account and start syncing.",
-        links: [authLink],
-      },
-    ],
-  });
+  // Auth and resource selection are handled in the twist edit modal.
+  // Only add custom initialization here if needed.
 }
 ```
 
-**Store Parent Activity for Later:**
+**Store Parent Thread for Later (optional):**
 
 ```typescript
-const activity = await this.tools.plot.createActivity({
-  type: ActivityType.Note,
-  title: "Setup",
-  notes: [
-    {
-      content: "Your twist is being set up. Configuration steps will appear here.",
-    },
-  ],
-});
-
-await this.set("setup_activity_id", activity.id);
+async activate(_priority: Pick<Priority, "id">) {
+  const threadId = await this.tools.plot.createThread({
+    type: ThreadType.Note,
+    title: "Setup complete",
+    notes: [{
+      content: "Your twist is ready. Threads will appear as they sync.",
+    }],
+  });
+  await this.set("setup_thread_id", threadId);
+}
 ```
 
-### activity(activity: Activity)
+### Event Callbacks (via build options)
 
-Called when an activity is routed to the twist. Common patterns:
+Twists respond to events through callbacks declared in `build()`:
 
-**Create Activities from External Events:**
+**React to thread changes (for two-way sync):**
 
 ```typescript
-async activity(activity: Activity) {
-  await this.tools.plot.createActivity(activity);
+plot: build(Plot, {
+  thread: {
+    access: ThreadAccess.Create,
+    updated: this.onThreadUpdated,
+  },
+  note: {
+    created: this.onNoteCreated,
+  },
+}),
+
+async onThreadUpdated(thread: Thread, changes: { tagsAdded, tagsRemoved }): Promise<void> {
+  const tool = this.getToolForThread(thread);
+  if (tool?.updateIssue) await tool.updateIssue(thread);
+}
+
+async onNoteCreated(note: Note): Promise<void> {
+  if (note.author.type === ActorType.Twist) return; // Prevent loops
+  // Sync note to external service as a comment
 }
 ```
 
-**Update Based on User Action:**
+**Respond to mentions (AI twist pattern):**
 
 ```typescript
-async activity(activity: Activity) {
-  if (activity.completed) {
-    await this.handleCompletion(activity);
-  }
-}
+plot: build(Plot, {
+  thread: { access: ThreadAccess.Respond },
+  note: {
+    intents: [{
+      description: "Respond to general questions",
+      examples: ["What's the weather?", "Help me plan my week"],
+      handler: this.respond,
+    }],
+  },
+}),
 ```
 
-## Activity Links
+## Actions
 
-Activity links enable user interaction:
+Actions enable user interaction:
 
 ```typescript
-import { type ActivityLink, ActivityLinkType } from "@plotday/twister";
+import { type Action, ActionType } from "@plotday/twister";
 
-// URL link
-const urlLink: ActivityLink = {
+// External URL action
+const urlAction: Action = {
   title: "Open website",
-  type: ActivityLinkType.url,
+  type: ActionType.external,
   url: "https://example.com",
 };
 
-// Callback link (uses Callbacks tool)
-const token = await this.callback(this.onLinkClicked, "context");
-const callbackLink: ActivityLink = {
+// Callback action (uses Callbacks tool — use linkCallback, not callback)
+const token = await this.linkCallback(this.onActionClicked, "context");
+const callbackAction: Action = {
   title: "Click me",
-  type: ActivityLinkType.callback,
-  token: token,
+  type: ActionType.callback,
+  callback: token,
 };
 
-// Add to activity note
-await this.tools.plot.createActivity({
-  type: ActivityType.Note,
-  title: "Task with links",
+// Add to thread note
+await this.tools.plot.createThread({
+  type: ThreadType.Note,
+  title: "Task with actions",
   notes: [
     {
-      content: "Click the links below to take action.",
-      links: [urlLink, callbackLink],
+      content: "Click the actions below to take action.",
+      actions: [urlAction, callbackAction],
     },
   ],
 });
+
+// Callback handler receives the Action as first argument
+async onActionClicked(action: Action, context: string): Promise<void> {
+  // Handle action click
+}
 ```
 
 ## Authentication Pattern
 
-Common pattern for OAuth authentication:
+Auth is handled automatically via the Integrations tool. Tools declare their OAuth provider in `build()`, and users connect in the twist edit modal. **You do not need to create auth activities manually.**
 
 ```typescript
-async activate(_priority: Pick<Priority, "id">) {
-  // Request auth link from tool with callback
-  const authLink = await this.tools.googleTool.requestAuth(
-    this.onAuthComplete,
-    "google"
-  );
-
-  // Create activity with auth link
-  const activity = await this.tools.plot.createActivity({
-    type: ActivityType.Note,
-    title: "Connect Google account",
-    notes: [
-      {
-        content: "Click below to connect your Google account and start syncing.",
-        links: [authLink],
-      },
-    ],
-  });
-
-  // Store for later use
-  await this.set("auth_activity_id", activity.id);
+// In your tool's build() method:
+build(build: ToolBuilder) {
+  return {
+    integrations: build(Integrations, {
+      providers: [{
+        provider: AuthProvider.Google,
+        scopes: ["https://www.googleapis.com/auth/calendar"],
+        getChannels: this.getChannels,          // List available resources after auth
+        onChannelEnabled: this.onChannelEnabled, // User enabled a resource
+        onChannelDisabled: this.onChannelDisabled, // User disabled a resource
+      }],
+    }),
+    // ...
+  };
 }
 
-async onAuthComplete(authResult: { authToken: string }, provider: string) {
-  // Store auth token
-  await this.set(`${provider}_auth`, authResult.authToken);
+// Get a token for API calls:
+const token = await this.tools.integrations.get(AuthProvider.Google, channelId);
+if (!token) throw new Error("No auth token available");
+const client = new ApiClient({ accessToken: token.token });
+```
 
-  // Continue setup flow
-  await this.setupSyncOptions(authResult.authToken);
-}
+For per-user write-backs (e.g., RSVP, comments attributed to the acting user):
+
+```typescript
+await this.tools.integrations.actAs(
+  AuthProvider.Google,
+  actorId,       // The user who performed the action
+  threadId,      // Thread to prompt for auth if needed
+  this.performWriteBack,
+  ...extraArgs
+);
 ```
 
 ## Sync Pattern
 
-### Recommended: Upsert via Source/Key (Strategy 2)
+### Upsert via Source/Key (Strategy 2)
 
-Pattern for syncing external data using automatic upserts - **no manual ID tracking needed**:
+Use source/key for automatic upserts:
 
 ```typescript
-async startSync(calendarId: string): Promise<void> {
-  const authToken = await this.get<string>("auth_token");
-
-  await this.tools.calendarTool.startSync(
-    authToken,
-    calendarId,
-    this.handleEvent,
-    calendarId
-  );
-}
-
-async handleEvent(
-  event: ExternalEvent,
-  calendarId: string
-): Promise<void> {
-  // Use the event's canonical URL as the source for automatic deduplication
-  const activity: NewActivityWithNotes = {
-    source: event.htmlLink, // or event.url, depending on your external system
-    type: ActivityType.Event,
+async handleEvent(event: ExternalEvent): Promise<void> {
+  const thread: NewThreadWithNotes = {
+    source: event.htmlLink,  // Canonical URL for automatic deduplication
+    type: ThreadType.Event,
     title: event.summary || "(No title)",
-    start: event.start?.dateTime || event.start?.date || null,
-    end: event.end?.dateTime || event.end?.date || null,
     notes: [],
   };
 
-  // Add description as an upsertable note
   if (event.description) {
-    activity.notes.push({
-      activity: { source: event.htmlLink },
-      key: "description", // This key enables upserts - same key updates the note
+    thread.notes.push({
+      thread: { source: event.htmlLink },
+      key: "description",  // This key enables note-level upserts
       content: event.description,
     });
   }
 
-  // Add attendees as an upsertable note
-  if (event.attendees?.length) {
-    const attendeeList = event.attendees
-      .map(a => `- ${a.email}${a.displayName ? ` (${a.displayName})` : ''}`)
-      .join('\n');
-
-    activity.notes.push({
-      activity: { source: event.htmlLink },
-      key: "attendees", // Different key for different note types
-      content: `## Attendees\n${attendeeList}`,
-    });
-  }
-
-  // Create or update - Plot automatically handles deduplication based on source
-  await this.tools.plot.createActivity(activity);
-}
-
-async stopSync(calendarId: string): Promise<void> {
-  const authToken = await this.get<string>("auth_token");
-  await this.tools.calendarTool.stopSync(authToken, calendarId);
+  // Create or update — Plot handles deduplication automatically
+  await this.tools.plot.createThread(thread);
 }
 ```
 
 ### Advanced: Generate and Store IDs (Strategy 3)
 
-Only use this pattern when you need to create multiple Plot activities from a single external item, or when the external system doesn't provide stable identifiers. See SYNC_STRATEGIES.md for details.
+Only use this pattern when you need to create multiple Plot threads from a single external item, or when the external system doesn't provide stable identifiers. See SYNC_STRATEGIES.md for details.
 
 ```typescript
 async handleEventAdvanced(
-  incomingActivity: NewActivityWithNotes,
+  incomingThread: NewThreadWithNotes,
   calendarId: string
 ): Promise<void> {
   // Extract external event ID from meta (adapt based on your tool's data)
-  const externalId = incomingActivity.meta?.eventId;
+  const externalId = incomingThread.meta?.eventId;
 
   if (!externalId) {
     console.error("Event missing external ID");
@@ -372,86 +330,45 @@ async handleEventAdvanced(
 
   // Check if we've already synced this event
   const mappingKey = `event_mapping:${calendarId}:${externalId}`;
-  const existingActivityId = await this.get<Uuid>(mappingKey);
+  const existingThreadId = await this.get<Uuid>(mappingKey);
 
-  if (existingActivityId) {
+  if (existingThreadId) {
     // Event already exists - add update as a Note (add message to thread)
-    if (incomingActivity.notes?.[0]?.content) {
+    if (incomingThread.notes?.[0]?.content) {
       await this.tools.plot.createNote({
-        activity: { id: existingActivityId },
-        content: incomingActivity.notes[0].content,
+        thread: { id: existingThreadId },
+        content: incomingThread.notes[0].content,
       });
     }
     return;
   }
 
   // New event - generate UUID and store mapping
-  const activityId = Uuid.Generate();
-  await this.set(mappingKey, activityId);
+  const threadId = Uuid.Generate();
+  await this.set(mappingKey, threadId);
 
-  // Create new Activity with initial Note (new thread with first message)
-  await this.tools.plot.createActivity({
-    ...incomingActivity,
-    id: activityId,
+  // Create new Thread with initial Note (new thread with first message)
+  await this.tools.plot.createThread({
+    ...incomingThread,
+    id: threadId,
   });
 }
 ```
 
-## Calendar Selection Pattern
+## Resource Selection
 
-Pattern for letting users select from multiple calendars/accounts:
+Resource selection (calendars, projects, channels) is handled automatically in the twist edit modal via the Integrations tool. Users see a list of available resources returned by your tool's `getChannels()` method and toggle them on/off. You do **not** need to build custom selection UI.
 
 ```typescript
-private async createCalendarSelectionActivity(
-  provider: string,
-  calendars: Calendar[],
-  authToken: string
-): Promise<void> {
-  const links: ActivityLink[] = [];
-
-  for (const calendar of calendars) {
-    const token = await this.callback(
-      this.onCalendarSelected,
-      provider,
-      calendar.id,
-      calendar.name,
-      authToken
-    );
-
-    links.push({
-      title: `📅 ${calendar.name}${calendar.primary ? " (Primary)" : ""}`,
-      type: ActivityLinkType.callback,
-      token: token,
-    });
-  }
-
-  await this.tools.plot.createActivity({
-    type: ActivityType.Note,
-    title: "Which calendars would you like to connect?",
-    notes: [
-      {
-        content: "Select the calendars you want to sync:",
-        links,
-      },
-    ],
-  });
-}
-
-async onCalendarSelected(
-  link: ActivityLink,
-  provider: string,
-  calendarId: string,
-  calendarName: string,
-  authToken: string
-): Promise<void> {
-  // Start sync for selected calendar
-  await this.tools.tool.startSync(
-    authToken,
-    calendarId,
-    this.handleEvent,
-    provider,
-    calendarId
-  );
+// In your tool:
+async getChannels(_auth: Authorization, token: AuthToken): Promise<Channel[]> {
+  const client = new ApiClient({ accessToken: token.token });
+  const calendars = await client.listCalendars();
+  return calendars.map(c => ({
+    id: c.id,
+    title: c.name,
+    children: c.subCalendars?.map(sc => ({ id: sc.id, title: sc.name })),
+  }));
 }
 ```
 
@@ -486,7 +403,7 @@ async startSync(resourceId: string): Promise<void> {
   await this.runTask(callback);
 }
 
-async syncBatch(args: any, resourceId: string): Promise<void> {
+async syncBatch(resourceId: string): Promise<void> {
   // Load state from Store (set by previous execution)
   const state = await this.get(`sync_state_${resourceId}`);
 
@@ -496,17 +413,17 @@ async syncBatch(args: any, resourceId: string): Promise<void> {
   // Process results using source/key pattern (automatic upserts, no manual tracking)
   // If each item makes ~10 requests, keep batch size ≤ 100 items to stay under limit
   for (const item of result.items) {
-    // Each createActivity may make ~5-10 requests depending on notes/links
-    await this.tools.plot.createActivity({
+    // Each createThread may make ~5-10 requests depending on notes/links
+    await this.tools.plot.createThread({
       source: item.url, // Use item's canonical URL for automatic deduplication
-      type: ActivityType.Note,
+      type: ThreadType.Note,
       title: item.title,
       notes: [{
         activity: { source: item.url },
         key: "description", // Use key for upsertable notes
         content: item.description,
       }],
-      unread: !state.initialSync, // false for initial sync, true for incremental
+      ...(state.initialSync ? { unread: false } : {}), // false for initial, omit for incremental
       ...(state.initialSync ? { archived: false } : {}), // unarchive on initial only
     });
   }
@@ -528,8 +445,8 @@ async syncBatch(args: any, resourceId: string): Promise<void> {
     await this.clear(`sync_state_${resourceId}`);
 
     // Optionally notify user of completion
-    await this.tools.plot.createActivity({
-      type: ActivityType.Note,
+    await this.tools.plot.createThread({
+      type: ThreadType.Note,
       title: "Sync complete",
       notes: [
         {
@@ -541,9 +458,9 @@ async syncBatch(args: any, resourceId: string): Promise<void> {
 }
 ```
 
-## Activity Sync Best Practices
+## Thread Sync Best Practices
 
-When syncing activities from external systems, follow these patterns for optimal user experience:
+When syncing threads from external systems, follow these patterns for optimal user experience:
 
 ### The `initialSync` Flag
 
@@ -551,30 +468,30 @@ All sync-based tools should distinguish between initial sync (first import) and
 
 | Field | Initial Sync | Incremental Sync | Reason |
 |-------|--------------|------------------|---------|
-| `unread` | `false` | `true` | Avoid notification overload from historical items |
+| `unread` | `false` | *omit* | Initial: mark read for all. Incremental: auto-mark read for author only |
 | `archived` | `false` | *omit* | Unarchive on install, preserve user choice on updates |
 
 **Example:**
 ```typescript
-const activity: NewActivity = {
-  type: ActivityType.Event,
+const thread: NewThread = {
+  type: ThreadType.Event,
   source: event.url,
   title: event.title,
-  unread: !initialSync,                      // false for initial, true for incremental
-  ...(initialSync ? { archived: false } : {}),  // unarchive on initial only
+  ...(initialSync ? { unread: false } : {}),     // false for initial, omit for incremental
+  ...(initialSync ? { archived: false } : {}),    // unarchive on initial only
 };
 ```
 
 **Why this matters:**
-- **Initial sync**: Activities are unarchived and marked as read, preventing spam from bulk historical imports
-- **Incremental sync**: New activities appear as unread, and archived state is preserved (respects user's archiving decisions)
+- **Initial sync**: Activities are unarchived and marked as read for all users, preventing spam from bulk historical imports
+- **Incremental sync**: Activities are auto-marked read for the author (twist owner), unread for everyone else. Archived state is preserved
 - **Reinstall**: Acts as initial sync, so previously archived activities are unarchived (fresh start)
 
 ### Two-Way Sync: Avoiding Race Conditions
 
-When implementing two-way sync where items created in Plot are pushed to an external system (e.g. Notes becoming comments), a race condition can occur: the external system may send a webhook for the newly created item before you've updated the Activity/Note with the external key. The webhook handler won't find the item by external key and may create a duplicate.
+When implementing two-way sync where items created in Plot are pushed to an external system (e.g. Notes becoming comments), a race condition can occur: the external system may send a webhook for the newly created item before you've updated the Thread/Note with the external key. The webhook handler won't find the item by external key and may create a duplicate.
 
-**Solution:** Embed the Plot `Activity.id` / `Note.id` in the external item's metadata when creating it, and update `Activity.source` / `Note.key` after creation. When processing webhooks, check for the Plot ID in metadata first.
+**Solution:** Embed the Plot `Thread.id` / `Note.id` in the external item's metadata when creating it, and update `Thread.source` / `Note.key` after creation. When processing webhooks, check for the Plot ID in metadata first.
 
 ```typescript
 async pushNoteAsComment(note: Note, externalItemId: string): Promise<void> {
@@ -617,8 +534,8 @@ try {
 } catch (error) {
   console.error("Operation failed:", error);
 
-  await this.tools.plot.createActivity({
-    type: ActivityType.Note,
+  await this.tools.plot.createThread({
+    type: ThreadType.Note,
     title: "Operation failed",
     notes: [
       {
@@ -632,11 +549,11 @@ try {
 ## Common Pitfalls
 
 - **Don't use instance variables for state** - Anything stored in memory is lost after function execution. Always use the Store tool for data that needs to persist.
-- **Processing self-created activities** - Other users may change an Activity created by the twist, resulting in an \`activity\` call. Be sure to check the \`changes === null\` and/or \`activity.author.id !== this.id\` to avoid re-processing.
-- **Always create Activities with Notes** - See "Understanding Activities and Notes" section above for the thread/message pattern and decision tree.
-- **Use correct Activity types** - Most should be `ActivityType.Note`. Only use `Action` for tasks with `done`, and `Event` for items with `start`/`end`.
-- **Use Activity.source and Note.key for automatic upserts (Recommended)** - Set Activity.source to the external item's URL for automatic deduplication. Only use UUID generation and storage for advanced cases (see SYNC_STRATEGIES.md).
-- **Add Notes to existing Activities** - For source/key pattern, reference activities by source. For UUID pattern, look up stored mappings before creating new Activities. Think thread replies, not new threads.
+- **Processing self-created threads** - Other users may change a Thread created by the twist, resulting in a callback. Be sure to check the `changes === null` and/or `thread.author.id !== this.id` to avoid re-processing.
+- **Always create Threads with Notes** - See "Understanding Threads and Notes" section above for the thread/message pattern and decision tree.
+- **Use correct Thread types** - Most should be `ThreadType.Note`. Only use `Action` for tasks with `done`, and `Event` for items with `start`/`end`.
+- **Use Thread.source and Note.key for automatic upserts (Recommended)** - Set Thread.source to the external item's URL for automatic deduplication. Only use UUID generation and storage for advanced cases (see SYNC_STRATEGIES.md).
+- **Add Notes to existing Threads** - For source/key pattern, reference threads by source. For UUID pattern, look up stored mappings before creating new Threads. Think thread replies, not new threads.
 - Tools are declared in the `build` method and accessed via `this.tools.toolName` in twist methods.
 - **Don't forget request limits** - Each execution has ~1000 requests (HTTP requests, tool calls). Break long loops into batches with `this.runTask()` to get fresh request limits. Calculate requests per item to determine safe batch size (e.g., if each item needs ~10 requests, batch size = ~100 items).
 - **Always use Callbacks tool for persistent references** - Direct function references don't survive worker restarts.