@plotday/twister 0.21.0 → 0.26.0

package/dist/docs/documents/Core_Concepts.html

@@ -16,7 +16,7 @@
 <li>Responds to lifecycle events (<code>activate</code>, <code>deactivate</code>, <code>upgrade</code>)</li>
 <li>Can process activities and create new ones</li>
 </ul>
-<h3 id="twist-anatomy" class="tsd-anchor-link">Twist Anatomy<a href="#twist-anatomy" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3><pre><code class="typescript"><span class="hl-0">import</span><span class="hl-1"> { </span><span class="hl-2">Twist</span><span class="hl-1">, </span><span class="hl-0">type</span><span class="hl-1"> </span><span class="hl-2">Priority</span><span class="hl-1">, </span><span class="hl-0">type</span><span class="hl-1"> </span><span class="hl-2">ToolBuilder</span><span class="hl-1"> } </span><span class="hl-0">from</span><span class="hl-1"> </span><span class="hl-3">&quot;@plotday/twister&quot;</span><span class="hl-1">;</span><br/><span class="hl-0">import</span><span class="hl-1"> { </span><span class="hl-2">Plot</span><span class="hl-1"> } </span><span class="hl-0">from</span><span class="hl-1"> </span><span class="hl-3">&quot;@plotday/twister/tools/plot&quot;</span><span class="hl-1">;</span><br/><br/><span class="hl-0">export</span><span class="hl-1"> </span><span class="hl-0">default</span><span class="hl-1"> </span><span class="hl-4">class</span><span class="hl-1"> </span><span class="hl-5">MyTwist</span><span class="hl-1"> </span><span class="hl-4">extends</span><span class="hl-1"> </span><span class="hl-5">Twist</span><span class="hl-1">&lt;</span><span class="hl-5">MyTwist</span><span class="hl-1">&gt; {</span><br/><span class="hl-1">  </span><span class="hl-7">// 1. Declare dependencies</span><br/><span class="hl-1">  </span><span class="hl-6">build</span><span class="hl-1">(</span><span class="hl-2">build</span><span class="hl-1">: </span><span class="hl-5">ToolBuilder</span><span class="hl-1">) {</span><br/><span class="hl-1">    </span><span class="hl-0">return</span><span class="hl-1"> {</span><br/><span class="hl-1">      </span><span class="hl-2">plot:</span><span class="hl-1"> </span><span class="hl-6">build</span><span class="hl-1">(</span><span class="hl-2">Plot</span><span class="hl-1">),</span><br/><span class="hl-1">    };</span><br/><span class="hl-1">  }</span><br/><br/><span class="hl-1">  </span><span class="hl-7">// 2. Initialize on activation</span><br/><span class="hl-1">  </span><span class="hl-4">async</span><span class="hl-1"> </span><span class="hl-6">activate</span><span class="hl-1">(</span><span class="hl-2">priority</span><span class="hl-1">: </span><span class="hl-5">Pick</span><span class="hl-1">&lt;</span><span class="hl-5">Priority</span><span class="hl-1">, </span><span class="hl-3">&quot;id&quot;</span><span class="hl-1">&gt;) {</span><br/><span class="hl-1">    </span><span class="hl-7">// Setup code - runs once when twist is added to a priority</span><br/><span class="hl-1">  }</span><br/><br/><span class="hl-1">  </span><span class="hl-7">// 3. Handle lifecycle events</span><br/><span class="hl-1">  </span><span class="hl-4">async</span><span class="hl-1"> </span><span class="hl-6">upgrade</span><span class="hl-1">() {</span><br/><span class="hl-1">    </span><span class="hl-7">// Runs when a new version is deployed</span><br/><span class="hl-1">  }</span><br/><br/><span class="hl-1">  </span><span class="hl-4">async</span><span class="hl-1"> </span><span class="hl-6">deactivate</span><span class="hl-1">() {</span><br/><span class="hl-1">    </span><span class="hl-7">// Cleanup - runs when twist is removed</span><br/><span class="hl-1">  }</span><br/><span class="hl-1">}</span>
+<h3 id="twist-anatomy" class="tsd-anchor-link">Twist Anatomy<a href="#twist-anatomy" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3><pre><code class="typescript"><span class="hl-0">import</span><span class="hl-1"> { </span><span class="hl-0">type</span><span class="hl-1"> </span><span class="hl-2">Priority</span><span class="hl-1">, </span><span class="hl-0">type</span><span class="hl-1"> </span><span class="hl-2">ToolBuilder</span><span class="hl-1">, </span><span class="hl-2">Twist</span><span class="hl-1"> } </span><span class="hl-0">from</span><span class="hl-1"> </span><span class="hl-3">&quot;@plotday/twister&quot;</span><span class="hl-1">;</span><br/><span class="hl-0">import</span><span class="hl-1"> { </span><span class="hl-2">Plot</span><span class="hl-1"> } </span><span class="hl-0">from</span><span class="hl-1"> </span><span class="hl-3">&quot;@plotday/twister/tools/plot&quot;</span><span class="hl-1">;</span><br/><br/><span class="hl-0">export</span><span class="hl-1"> </span><span class="hl-0">default</span><span class="hl-1"> </span><span class="hl-4">class</span><span class="hl-1"> </span><span class="hl-5">MyTwist</span><span class="hl-1"> </span><span class="hl-4">extends</span><span class="hl-1"> </span><span class="hl-5">Twist</span><span class="hl-1">&lt;</span><span class="hl-5">MyTwist</span><span class="hl-1">&gt; {</span><br/><span class="hl-1">  </span><span class="hl-7">// 1. Declare dependencies</span><br/><span class="hl-1">  </span><span class="hl-6">build</span><span class="hl-1">(</span><span class="hl-2">build</span><span class="hl-1">: </span><span class="hl-5">ToolBuilder</span><span class="hl-1">) {</span><br/><span class="hl-1">    </span><span class="hl-0">return</span><span class="hl-1"> {</span><br/><span class="hl-1">      </span><span class="hl-2">plot:</span><span class="hl-1"> </span><span class="hl-6">build</span><span class="hl-1">(</span><span class="hl-2">Plot</span><span class="hl-1">),</span><br/><span class="hl-1">    };</span><br/><span class="hl-1">  }</span><br/><br/><span class="hl-1">  </span><span class="hl-7">// 2. Initialize on activation</span><br/><span class="hl-1">  </span><span class="hl-4">async</span><span class="hl-1"> </span><span class="hl-6">activate</span><span class="hl-1">(</span><span class="hl-2">priority</span><span class="hl-1">: </span><span class="hl-5">Pick</span><span class="hl-1">&lt;</span><span class="hl-5">Priority</span><span class="hl-1">, </span><span class="hl-3">&quot;id&quot;</span><span class="hl-1">&gt;) {</span><br/><span class="hl-1">    </span><span class="hl-7">// Setup code - runs once when twist is added to a priority</span><br/><span class="hl-1">  }</span><br/><br/><span class="hl-1">  </span><span class="hl-7">// 3. Handle lifecycle events</span><br/><span class="hl-1">  </span><span class="hl-4">async</span><span class="hl-1"> </span><span class="hl-6">upgrade</span><span class="hl-1">() {</span><br/><span class="hl-1">    </span><span class="hl-7">// Runs when a new version is deployed</span><br/><span class="hl-1">  }</span><br/><br/><span class="hl-1">  </span><span class="hl-4">async</span><span class="hl-1"> </span><span class="hl-6">deactivate</span><span class="hl-1">() {</span><br/><span class="hl-1">    </span><span class="hl-7">// Cleanup - runs when twist is removed</span><br/><span class="hl-1">  }</span><br/><span class="hl-1">}</span>
 </code><button type="button">Copy</button></pre>
 
 <h3 id="when-to-use-twists" class="tsd-anchor-link">When to Use Twists<a href="#when-to-use-twists" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3><p>Use twists for:</p>
@@ -73,19 +73,50 @@
 
 <hr>
 <h2 id="activities" class="tsd-anchor-link">Activities<a href="#activities" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2><p>Activities are the core data type in Plot, representing tasks, events, and notes.</p>
+<p><strong>Think of an Activity as a thread</strong> on a messaging platform, and <strong>Notes as the messages in that thread</strong>. An Activity represents something done or to be done, while Notes represent the updates and details on that activity. Always create activities with an initial note, and add notes for updates rather than creating new activities.</p>
 <h3 id="activity-types" class="tsd-anchor-link">Activity Types<a href="#activity-types" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3><ul>
 <li><strong>Note</strong> - Information without actionable requirements</li>
 <li><strong>Task</strong> - Actionable items that can be completed</li>
 <li><strong>Event</strong> - Scheduled occurrences with start/end times</li>
 </ul>
-<pre><code class="typescript"><span class="hl-0">import</span><span class="hl-1"> { </span><span class="hl-2">ActivityType</span><span class="hl-1"> } </span><span class="hl-0">from</span><span class="hl-1"> </span><span class="hl-3">&quot;@plotday/twister&quot;</span><span class="hl-1">;</span><br/><br/><span class="hl-7">// Note</span><br/><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-2">tools</span><span class="hl-1">.</span><span class="hl-2">plot</span><span class="hl-1">.</span><span class="hl-6">createActivity</span><span class="hl-1">({</span><br/><span class="hl-1">  </span><span class="hl-2">type:</span><span class="hl-1"> </span><span class="hl-2">ActivityType</span><span class="hl-1">.</span><span class="hl-2">Note</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-2">title:</span><span class="hl-1"> </span><span class="hl-3">&quot;Meeting notes from sync&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-7">// Task</span><br/><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-2">tools</span><span class="hl-1">.</span><span class="hl-2">plot</span><span class="hl-1">.</span><span class="hl-6">createActivity</span><span class="hl-1">({</span><br/><span class="hl-1">  </span><span class="hl-2">type:</span><span class="hl-1"> </span><span class="hl-2">ActivityType</span><span class="hl-1">.</span><span class="hl-2">Action</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-2">title:</span><span class="hl-1"> </span><span class="hl-3">&quot;Review pull request&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-2">doneAt:</span><span class="hl-1"> </span><span class="hl-4">null</span><span class="hl-1">, </span><span class="hl-7">// null = not done</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-7">// Event</span><br/><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-2">tools</span><span class="hl-1">.</span><span class="hl-2">plot</span><span class="hl-1">.</span><span class="hl-6">createActivity</span><span class="hl-1">({</span><br/><span class="hl-1">  </span><span class="hl-2">type:</span><span class="hl-1"> </span><span class="hl-2">ActivityType</span><span class="hl-1">.</span><span class="hl-2">Event</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-2">title:</span><span class="hl-1"> </span><span class="hl-3">&quot;Team standup&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-2">start:</span><span class="hl-1"> </span><span class="hl-4">new</span><span class="hl-1"> </span><span class="hl-6">Date</span><span class="hl-1">(</span><span class="hl-3">&quot;2025-02-01T10:00:00Z&quot;</span><span class="hl-1">),</span><br/><span class="hl-1">  </span><span class="hl-2">end:</span><span class="hl-1"> </span><span class="hl-4">new</span><span class="hl-1"> </span><span class="hl-6">Date</span><span class="hl-1">(</span><span class="hl-3">&quot;2025-02-01T10:30:00Z&quot;</span><span class="hl-1">),</span><br/><span class="hl-1">});</span>
+<pre><code class="typescript"><span class="hl-0">import</span><span class="hl-1"> { </span><span class="hl-2">ActivityType</span><span class="hl-1"> } </span><span class="hl-0">from</span><span class="hl-1"> </span><span class="hl-3">&quot;@plotday/twister&quot;</span><span class="hl-1">;</span><br/><br/><span class="hl-7">// Note - Information without actionable requirements</span><br/><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-2">tools</span><span class="hl-1">.</span><span class="hl-2">plot</span><span class="hl-1">.</span><span class="hl-6">createActivity</span><span class="hl-1">({</span><br/><span class="hl-1">  </span><span class="hl-2">type:</span><span class="hl-1"> </span><span class="hl-2">ActivityType</span><span class="hl-1">.</span><span class="hl-2">Note</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-2">title:</span><span class="hl-1"> </span><span class="hl-3">&quot;Meeting notes from sync&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-2">notes:</span><span class="hl-1"> [</span><br/><span class="hl-1">    {</span><br/><span class="hl-1">      </span><span class="hl-2">content:</span><span class="hl-1"> </span><span class="hl-3">&quot;Discussed Q1 roadmap and team priorities...&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">    },</span><br/><span class="hl-1">  ],</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-7">// Task - Actionable item</span><br/><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-2">tools</span><span class="hl-1">.</span><span class="hl-2">plot</span><span class="hl-1">.</span><span class="hl-6">createActivity</span><span class="hl-1">({</span><br/><span class="hl-1">  </span><span class="hl-2">type:</span><span class="hl-1"> </span><span class="hl-2">ActivityType</span><span class="hl-1">.</span><span class="hl-2">Action</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-2">title:</span><span class="hl-1"> </span><span class="hl-3">&quot;Review pull request&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-2">doneAt:</span><span class="hl-1"> </span><span class="hl-4">null</span><span class="hl-1">, </span><span class="hl-7">// null = not done</span><br/><span class="hl-1">  </span><span class="hl-2">notes:</span><span class="hl-1"> [</span><br/><span class="hl-1">    {</span><br/><span class="hl-1">      </span><span class="hl-2">content:</span><span class="hl-1"> </span><span class="hl-3">&quot;PR adds new authentication flow. Please review for security concerns.&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">    },</span><br/><span class="hl-1">  ],</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-7">// Event - Scheduled occurrence</span><br/><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-2">tools</span><span class="hl-1">.</span><span class="hl-2">plot</span><span class="hl-1">.</span><span class="hl-6">createActivity</span><span class="hl-1">({</span><br/><span class="hl-1">  </span><span class="hl-2">type:</span><span class="hl-1"> </span><span class="hl-2">ActivityType</span><span class="hl-1">.</span><span class="hl-2">Event</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-2">title:</span><span class="hl-1"> </span><span class="hl-3">&quot;Team standup&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-2">start:</span><span class="hl-1"> </span><span class="hl-4">new</span><span class="hl-1"> </span><span class="hl-6">Date</span><span class="hl-1">(</span><span class="hl-3">&quot;2025-02-01T10:00:00Z&quot;</span><span class="hl-1">),</span><br/><span class="hl-1">  </span><span class="hl-2">end:</span><span class="hl-1"> </span><span class="hl-4">new</span><span class="hl-1"> </span><span class="hl-6">Date</span><span class="hl-1">(</span><span class="hl-3">&quot;2025-02-01T10:30:00Z&quot;</span><span class="hl-1">),</span><br/><span class="hl-1">  </span><span class="hl-2">notes:</span><span class="hl-1"> [</span><br/><span class="hl-1">    {</span><br/><span class="hl-1">      </span><span class="hl-2">content:</span><span class="hl-1"> </span><span class="hl-3">&quot;Daily sync meeting&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">    },</span><br/><span class="hl-1">  ],</span><br/><span class="hl-1">});</span>
 </code><button type="button">Copy</button></pre>
 
-<h3 id="activity-properties" class="tsd-anchor-link">Activity Properties<a href="#activity-properties" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3><pre><code class="typescript"><span class="hl-4">type</span><span class="hl-1"> </span><span class="hl-5">Activity</span><span class="hl-1"> = {</span><br/><span class="hl-1">  </span><span class="hl-2">id</span><span class="hl-1">: </span><span class="hl-5">string</span><span class="hl-1">; </span><span class="hl-7">// Unique identifier</span><br/><span class="hl-1">  </span><span class="hl-2">type</span><span class="hl-1">: </span><span class="hl-5">ActivityType</span><span class="hl-1">; </span><span class="hl-7">// Note, Task, or Event</span><br/><span class="hl-1">  </span><span class="hl-2">title</span><span class="hl-1">: </span><span class="hl-5">string</span><span class="hl-1"> | </span><span class="hl-5">null</span><span class="hl-1">; </span><span class="hl-7">// Display title</span><br/><span class="hl-1">  </span><span class="hl-2">note</span><span class="hl-1">: </span><span class="hl-5">string</span><span class="hl-1"> | </span><span class="hl-5">null</span><span class="hl-1">; </span><span class="hl-7">// Additional details</span><br/><span class="hl-1">  </span><span class="hl-2">start</span><span class="hl-1">: </span><span class="hl-5">Date</span><span class="hl-1"> | </span><span class="hl-5">null</span><span class="hl-1">; </span><span class="hl-7">// Event start time</span><br/><span class="hl-1">  </span><span class="hl-2">end</span><span class="hl-1">: </span><span class="hl-5">Date</span><span class="hl-1"> | </span><span class="hl-5">null</span><span class="hl-1">; </span><span class="hl-7">// Event end time</span><br/><span class="hl-1">  </span><span class="hl-2">doneAt</span><span class="hl-1">: </span><span class="hl-5">Date</span><span class="hl-1"> | </span><span class="hl-5">null</span><span class="hl-1">; </span><span class="hl-7">// Task completion time</span><br/><span class="hl-1">  </span><span class="hl-2">links</span><span class="hl-1">: </span><span class="hl-5">ActivityLink</span><span class="hl-1">[]; </span><span class="hl-7">// Action links</span><br/><span class="hl-1">  </span><span class="hl-2">tags</span><span class="hl-1">: </span><span class="hl-5">Record</span><span class="hl-1">&lt;</span><span class="hl-5">Tag</span><span class="hl-1">, </span><span class="hl-5">ActorId</span><span class="hl-1">[]&gt;; </span><span class="hl-7">// Tag assignments</span><br/><span class="hl-1">  </span><span class="hl-7">// ... and more</span><br/><span class="hl-1">};</span>
+<h3 id="activity-scheduling-states" class="tsd-anchor-link">Activity Scheduling States<a href="#activity-scheduling-states" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3><p>When creating Activities of type <code>Action</code> (tasks), the <code>start</code> field determines how they appear in Plot:</p>
+<ul>
+<li><strong>&quot;Do Now&quot;</strong> (Current/Actionable) - Tasks that should be done today</li>
+<li><strong>&quot;Do Later&quot;</strong> (Future Scheduled) - Tasks scheduled for a specific future date</li>
+<li><strong>&quot;Do Someday&quot;</strong> (Unscheduled Backlog) - Tasks without a specific timeline</li>
+</ul>
+<h4 id="default-behavior" class="tsd-anchor-link">Default Behavior<a href="#default-behavior" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h4><p><strong>Important:</strong> When creating an Action, omitting the <code>start</code> field defaults to the current time, making it a &quot;Do Now&quot; task.</p>
+<p>For most integrations (project management tools, issue trackers), you should explicitly set <code>start: null</code> to create backlog items, only using &quot;Do Now&quot; for tasks that are actively in progress or urgent.</p>
+<pre><code class="typescript"><span class="hl-7">// &quot;Do Now&quot; - Appears in today&#39;s actionable list</span><br/><span class="hl-7">// WARNING: This is the default when start is omitted!</span><br/><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-2">tools</span><span class="hl-1">.</span><span class="hl-2">plot</span><span class="hl-1">.</span><span class="hl-6">createActivity</span><span class="hl-1">({</span><br/><span class="hl-1">  </span><span class="hl-2">type:</span><span class="hl-1"> </span><span class="hl-2">ActivityType</span><span class="hl-1">.</span><span class="hl-2">Action</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-2">title:</span><span class="hl-1"> </span><span class="hl-3">&quot;Urgent: Review security PR&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-7">// Omitting start defaults to new Date()</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-7">// &quot;Do Someday&quot; - Backlog item (RECOMMENDED for most synced tasks)</span><br/><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-2">tools</span><span class="hl-1">.</span><span class="hl-2">plot</span><span class="hl-1">.</span><span class="hl-6">createActivity</span><span class="hl-1">({</span><br/><span class="hl-1">  </span><span class="hl-2">type:</span><span class="hl-1"> </span><span class="hl-2">ActivityType</span><span class="hl-1">.</span><span class="hl-2">Action</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-2">title:</span><span class="hl-1"> </span><span class="hl-3">&quot;Refactor authentication service&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-2">start:</span><span class="hl-1"> </span><span class="hl-4">null</span><span class="hl-1">, </span><span class="hl-7">// Explicitly set to null for backlog</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-7">// &quot;Do Later&quot; - Scheduled for specific date</span><br/><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-2">tools</span><span class="hl-1">.</span><span class="hl-2">plot</span><span class="hl-1">.</span><span class="hl-6">createActivity</span><span class="hl-1">({</span><br/><span class="hl-1">  </span><span class="hl-2">type:</span><span class="hl-1"> </span><span class="hl-2">ActivityType</span><span class="hl-1">.</span><span class="hl-2">Action</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-2">title:</span><span class="hl-1"> </span><span class="hl-3">&quot;Prepare Q1 review&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-2">start:</span><span class="hl-1"> </span><span class="hl-4">new</span><span class="hl-1"> </span><span class="hl-6">Date</span><span class="hl-1">(</span><span class="hl-3">&quot;2025-03-15&quot;</span><span class="hl-1">), </span><span class="hl-7">// Scheduled for future date</span><br/><span class="hl-1">});</span>
+</code><button type="button">Copy</button></pre>
+
+<h4 id="when-to-use-each-state" class="tsd-anchor-link">When to Use Each State<a href="#when-to-use-each-state" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h4><p><strong>Use &quot;Do Now&quot; (omit <code>start</code>)</strong> when:</p>
+<ul>
+<li>Task is actively being worked on</li>
+<li>Task has a due date of today</li>
+<li>Task is marked as &quot;In Progress&quot; in source system</li>
+<li>Task is high priority AND explicitly assigned as current work</li>
+</ul>
+<p><strong>Use &quot;Do Someday&quot; (<code>start: null</code>)</strong> when:</p>
+<ul>
+<li>Syncing backlog items from project management tools</li>
+<li>Task is in &quot;To Do&quot; or &quot;Backlog&quot; status</li>
+<li>Task doesn't have a specific due date</li>
+<li>This should be the <strong>default for most integrations</strong></li>
+</ul>
+<p><strong>Use &quot;Do Later&quot; (future <code>start</code>)</strong> when:</p>
+<ul>
+<li>Task has a specific due date in the future</li>
+<li>Task is scheduled for a particular day</li>
+</ul>
+<h3 id="activity-properties" class="tsd-anchor-link">Activity Properties<a href="#activity-properties" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3><pre><code class="typescript"><span class="hl-4">type</span><span class="hl-1"> </span><span class="hl-5">Activity</span><span class="hl-1"> = {</span><br/><span class="hl-1">  </span><span class="hl-2">id</span><span class="hl-1">: </span><span class="hl-5">string</span><span class="hl-1">; </span><span class="hl-7">// Unique identifier</span><br/><span class="hl-1">  </span><span class="hl-2">type</span><span class="hl-1">: </span><span class="hl-5">ActivityType</span><span class="hl-1">; </span><span class="hl-7">// Note, Task, or Event</span><br/><span class="hl-1">  </span><span class="hl-2">title</span><span class="hl-1">: </span><span class="hl-5">string</span><span class="hl-1"> | </span><span class="hl-5">null</span><span class="hl-1">; </span><span class="hl-7">// Display title</span><br/><span class="hl-1">  </span><span class="hl-2">preview</span><span class="hl-1">: </span><span class="hl-5">string</span><span class="hl-1"> | </span><span class="hl-5">null</span><span class="hl-1">; </span><span class="hl-7">// Brief preview text</span><br/><span class="hl-1">  </span><span class="hl-2">start</span><span class="hl-1">: </span><span class="hl-5">Date</span><span class="hl-1"> | </span><span class="hl-5">null</span><span class="hl-1">; </span><span class="hl-7">// Event start time</span><br/><span class="hl-1">  </span><span class="hl-2">end</span><span class="hl-1">: </span><span class="hl-5">Date</span><span class="hl-1"> | </span><span class="hl-5">null</span><span class="hl-1">; </span><span class="hl-7">// Event end time</span><br/><span class="hl-1">  </span><span class="hl-2">doneAt</span><span class="hl-1">: </span><span class="hl-5">Date</span><span class="hl-1"> | </span><span class="hl-5">null</span><span class="hl-1">; </span><span class="hl-7">// Task completion time</span><br/><span class="hl-1">  </span><span class="hl-2">tags</span><span class="hl-1">: </span><span class="hl-5">Record</span><span class="hl-1">&lt;</span><span class="hl-5">Tag</span><span class="hl-1">, </span><span class="hl-5">ActorId</span><span class="hl-1">[]&gt;; </span><span class="hl-7">// Tag assignments</span><br/><span class="hl-1">  </span><span class="hl-7">// ... and more</span><br/><span class="hl-1">};</span>
 </code><button type="button">Copy</button></pre>
 
-<h3 id="activity-links" class="tsd-anchor-link">Activity Links<a href="#activity-links" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3><p>Links enable user interaction with activities:</p>
-<pre><code class="typescript"><span class="hl-0">import</span><span class="hl-1"> { </span><span class="hl-2">ActivityLinkType</span><span class="hl-1"> } </span><span class="hl-0">from</span><span class="hl-1"> </span><span class="hl-3">&quot;@plotday/twister&quot;</span><span class="hl-1">;</span><br/><br/><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-2">tools</span><span class="hl-1">.</span><span class="hl-2">plot</span><span class="hl-1">.</span><span class="hl-6">createActivity</span><span class="hl-1">({</span><br/><span class="hl-1">  </span><span class="hl-2">type:</span><span class="hl-1"> </span><span class="hl-2">ActivityType</span><span class="hl-1">.</span><span class="hl-2">Action</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-2">title:</span><span class="hl-1"> </span><span class="hl-3">&quot;Fix bug #123&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-2">links:</span><span class="hl-1"> [</span><br/><span class="hl-1">    {</span><br/><span class="hl-1">      </span><span class="hl-2">type:</span><span class="hl-1"> </span><span class="hl-2">ActivityLinkType</span><span class="hl-1">.</span><span class="hl-2">external</span><span class="hl-1">,</span><br/><span class="hl-1">      </span><span class="hl-2">title:</span><span class="hl-1"> </span><span class="hl-3">&quot;View Issue&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">      </span><span class="hl-2">url:</span><span class="hl-1"> </span><span class="hl-3">&quot;https://github.com/org/repo/issues/123&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">    },</span><br/><span class="hl-1">    {</span><br/><span class="hl-1">      </span><span class="hl-2">type:</span><span class="hl-1"> </span><span class="hl-2">ActivityLinkType</span><span class="hl-1">.</span><span class="hl-2">callback</span><span class="hl-1">,</span><br/><span class="hl-1">      </span><span class="hl-2">title:</span><span class="hl-1"> </span><span class="hl-3">&quot;Mark as Fixed&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">      </span><span class="hl-2">callback:</span><span class="hl-1"> </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">callback</span><span class="hl-1">(</span><span class="hl-3">&quot;markAsFixed&quot;</span><span class="hl-1">, </span><span class="hl-3">&quot;123&quot;</span><span class="hl-1">),</span><br/><span class="hl-1">    },</span><br/><span class="hl-1">  ],</span><br/><span class="hl-1">});</span>
+<h3 id="activity-notes" class="tsd-anchor-link">Activity Notes<a href="#activity-notes" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3><p>Activities can have multiple Notes attached to them, like messages in a thread. Notes contain detailed content and links:</p>
+<pre><code class="typescript"><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-2">tools</span><span class="hl-1">.</span><span class="hl-2">plot</span><span class="hl-1">.</span><span class="hl-6">createActivity</span><span class="hl-1">({</span><br/><span class="hl-1">  </span><span class="hl-2">type:</span><span class="hl-1"> </span><span class="hl-2">ActivityType</span><span class="hl-1">.</span><span class="hl-2">Action</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-2">title:</span><span class="hl-1"> </span><span class="hl-3">&quot;Fix bug #123&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-2">source:</span><span class="hl-1"> </span><span class="hl-3">&quot;github:issue:123&quot;</span><span class="hl-1">, </span><span class="hl-7">// For deduplication</span><br/><span class="hl-1">  </span><span class="hl-2">notes:</span><span class="hl-1"> [</span><br/><span class="hl-1">    {</span><br/><span class="hl-1">      </span><span class="hl-2">content:</span><span class="hl-1"> </span><span class="hl-3">&quot;Users are unable to log in with SSO. Error occurs in auth middleware.&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">      </span><span class="hl-2">links:</span><span class="hl-1"> [</span><br/><span class="hl-1">        {</span><br/><span class="hl-1">          </span><span class="hl-2">type:</span><span class="hl-1"> </span><span class="hl-2">ActivityLinkType</span><span class="hl-1">.</span><span class="hl-2">external</span><span class="hl-1">,</span><br/><span class="hl-1">          </span><span class="hl-2">title:</span><span class="hl-1"> </span><span class="hl-3">&quot;View Issue&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">          </span><span class="hl-2">url:</span><span class="hl-1"> </span><span class="hl-3">&quot;https://github.com/org/repo/issues/123&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">        },</span><br/><span class="hl-1">        {</span><br/><span class="hl-1">          </span><span class="hl-2">type:</span><span class="hl-1"> </span><span class="hl-2">ActivityLinkType</span><span class="hl-1">.</span><span class="hl-2">callback</span><span class="hl-1">,</span><br/><span class="hl-1">          </span><span class="hl-2">title:</span><span class="hl-1"> </span><span class="hl-3">&quot;Mark as Fixed&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">          </span><span class="hl-2">callback:</span><span class="hl-1"> </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">callback</span><span class="hl-1">(</span><span class="hl-3">&quot;markAsFixed&quot;</span><span class="hl-1">, </span><span class="hl-3">&quot;123&quot;</span><span class="hl-1">),</span><br/><span class="hl-1">        },</span><br/><span class="hl-1">      ],</span><br/><span class="hl-1">    },</span><br/><span class="hl-1">  ],</span><br/><span class="hl-1">});</span>
 </code><button type="button">Copy</button></pre>
 
 <p><strong>Link Types:</strong></p>
@@ -93,7 +124,28 @@
 <li><strong>external</strong> - Opens URL in browser</li>
 <li><strong>auth</strong> - Initiates OAuth flow</li>
 <li><strong>callback</strong> - Triggers twist method when clicked</li>
+<li><strong>conferencing</strong> - Video conferencing links (Zoom, Meet, Teams, etc.)</li>
+</ul>
+<h3 id="best-practices-for-activities-and-notes" class="tsd-anchor-link">Best Practices for Activities and Notes<a href="#best-practices-for-activities-and-notes" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3><h4 id="always-create-activities-with-an-initial-note" class="tsd-anchor-link">Always Create Activities with an Initial Note<a href="#always-create-activities-with-an-initial-note" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h4><p><strong>In most cases, an Activity should be created with at least one initial Note.</strong> The Activity's <code>title</code> is just a short summary that may be truncated in the UI. Detailed information, context, and links should always go in Notes.</p>
+<p>Think of it like starting a new thread with a first message - the thread title gives context, but the real content is in the messages.</p>
+<pre><code class="typescript"><span class="hl-7">// ✅ GOOD - Activity with detailed Note (thread with first message)</span><br/><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-2">tools</span><span class="hl-1">.</span><span class="hl-2">plot</span><span class="hl-1">.</span><span class="hl-6">createActivity</span><span class="hl-1">({</span><br/><span class="hl-1">  </span><span class="hl-2">type:</span><span class="hl-1"> </span><span class="hl-2">ActivityType</span><span class="hl-1">.</span><span class="hl-2">Action</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-2">title:</span><span class="hl-1"> </span><span class="hl-3">&quot;Review PR #456&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-2">source:</span><span class="hl-1"> </span><span class="hl-3">&quot;github:pr:456&quot;</span><span class="hl-1">, </span><span class="hl-7">// For deduplication</span><br/><span class="hl-1">  </span><span class="hl-2">notes:</span><span class="hl-1"> [</span><br/><span class="hl-1">    {</span><br/><span class="hl-1">      </span><span class="hl-2">content:</span><span class="hl-1"> </span><span class="hl-3">&quot;Please review the OAuth 2.0 implementation. Key changes include:</span><span class="hl-12">\n</span><span class="hl-3">- Token refresh logic</span><span class="hl-12">\n</span><span class="hl-3">- Session management</span><span class="hl-12">\n</span><span class="hl-3">- Error handling for expired tokens&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">      </span><span class="hl-2">links:</span><span class="hl-1"> [</span><br/><span class="hl-1">        {</span><br/><span class="hl-1">          </span><span class="hl-2">type:</span><span class="hl-1"> </span><span class="hl-2">ActivityLinkType</span><span class="hl-1">.</span><span class="hl-2">external</span><span class="hl-1">,</span><br/><span class="hl-1">          </span><span class="hl-2">title:</span><span class="hl-1"> </span><span class="hl-3">&quot;View PR&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">          </span><span class="hl-2">url:</span><span class="hl-1"> </span><span class="hl-3">&quot;https://github.com/org/repo/pull/456&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">        },</span><br/><span class="hl-1">      ],</span><br/><span class="hl-1">    },</span><br/><span class="hl-1">  ],</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-7">// ❌ BAD - Relying only on title</span><br/><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-2">tools</span><span class="hl-1">.</span><span class="hl-2">plot</span><span class="hl-1">.</span><span class="hl-6">createActivity</span><span class="hl-1">({</span><br/><span class="hl-1">  </span><span class="hl-2">type:</span><span class="hl-1"> </span><span class="hl-2">ActivityType</span><span class="hl-1">.</span><span class="hl-2">Action</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-2">title:</span><span class="hl-1"> </span><span class="hl-3">&quot;Review PR #456 - OAuth implementation with token refresh and session management&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-7">// Missing Notes with full context and links</span><br/><span class="hl-1">});</span>
+</code><button type="button">Copy</button></pre>
+
+<p><strong>Why?</strong> Just as you wouldn't create a messaging thread without a first message, Activities need Notes to provide meaningful context and detail.</p>
+<h4 id="add-notes-to-existing-activities-for-related-content" class="tsd-anchor-link">Add Notes to Existing Activities for Related Content<a href="#add-notes-to-existing-activities-for-related-content" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h4><p><strong>Wherever possible, related messages should be added to an existing Activity rather than creating a new Activity.</strong> This keeps conversations, workflows, and related information together.</p>
+<p>Think of it like replying to a message thread instead of starting a new thread for every reply.</p>
+<p><strong>Use this pattern for:</strong></p>
+<ul>
+<li><strong>Email threads</strong> - All messages in a thread as Notes on one Activity</li>
+<li><strong>Chat conversations</strong> - All messages in a channel or thread as Notes</li>
+<li><strong>Workflows</strong> - All steps in an end-to-end process as Notes</li>
+<li><strong>Document collaboration</strong> - All comments and updates as Notes</li>
+<li><strong>Issue tracking</strong> - All comments and status updates as Notes</li>
 </ul>
+<pre><code class="typescript"><span class="hl-7">// ✅ GOOD - Add reply to existing thread</span><br/><span class="hl-2">async</span><span class="hl-1"> </span><span class="hl-6">onNewMessage</span><span class="hl-1">(</span><span class="hl-2">message</span><span class="hl-1">: </span><span class="hl-2">Message</span><span class="hl-1">, </span><span class="hl-2">threadId</span><span class="hl-1">: </span><span class="hl-2">string</span><span class="hl-1">) {</span><br/><span class="hl-1">  </span><span class="hl-7">// Find existing activity for this thread (check if thread exists)</span><br/><span class="hl-1">  </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">source</span><span class="hl-1"> = </span><span class="hl-3">`chat:thread:</span><span class="hl-4">${</span><span class="hl-2">threadId</span><span class="hl-4">}</span><span class="hl-3">`</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">activity</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-2">tools</span><span class="hl-1">.</span><span class="hl-2">plot</span><span class="hl-1">.</span><span class="hl-6">getActivityBySource</span><span class="hl-1">(</span><span class="hl-2">source</span><span class="hl-1">);</span><br/><br/><span class="hl-1">  </span><span class="hl-0">if</span><span class="hl-1"> (</span><span class="hl-2">activity</span><span class="hl-1">) {</span><br/><span class="hl-1">    </span><span class="hl-7">// Add new message as a Note to the existing thread</span><br/><span class="hl-1">    </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-2">tools</span><span class="hl-1">.</span><span class="hl-2">plot</span><span class="hl-1">.</span><span class="hl-6">createNote</span><span class="hl-1">({</span><br/><span class="hl-1">      </span><span class="hl-2">activity:</span><span class="hl-1"> { </span><span class="hl-2">id:</span><span class="hl-1"> </span><span class="hl-2">activity</span><span class="hl-1">.</span><span class="hl-2">id</span><span class="hl-1"> },</span><br/><span class="hl-1">      </span><span class="hl-2">content:</span><span class="hl-1"> </span><span class="hl-2">message</span><span class="hl-1">.</span><span class="hl-2">text</span><span class="hl-1">,</span><br/><span class="hl-1">    });</span><br/><span class="hl-1">  } </span><span class="hl-0">else</span><span class="hl-1"> {</span><br/><span class="hl-1">    </span><span class="hl-7">// Create new thread with initial message</span><br/><span class="hl-1">    </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-2">tools</span><span class="hl-1">.</span><span class="hl-2">plot</span><span class="hl-1">.</span><span class="hl-6">createActivity</span><span class="hl-1">({</span><br/><span class="hl-1">      </span><span class="hl-2">type:</span><span class="hl-1"> </span><span class="hl-2">ActivityType</span><span class="hl-1">.</span><span class="hl-2">Note</span><span class="hl-1">,</span><br/><span class="hl-1">      </span><span class="hl-2">title:</span><span class="hl-1"> </span><span class="hl-2">message</span><span class="hl-1">.</span><span class="hl-2">subject</span><span class="hl-1"> || </span><span class="hl-3">&quot;New conversation&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">      </span><span class="hl-2">source</span><span class="hl-1">, </span><span class="hl-7">// For future deduplication</span><br/><span class="hl-1">      </span><span class="hl-2">notes:</span><span class="hl-1"> [</span><br/><span class="hl-1">        {</span><br/><span class="hl-1">          </span><span class="hl-2">content:</span><span class="hl-1"> </span><span class="hl-2">message</span><span class="hl-1">.</span><span class="hl-2">text</span><span class="hl-1">,</span><br/><span class="hl-1">        },</span><br/><span class="hl-1">      ],</span><br/><span class="hl-1">    });</span><br/><span class="hl-1">  }</span><br/><span class="hl-1">}</span><br/><br/><span class="hl-7">// ❌ BAD - Creating separate Activity for each message (new thread for every reply!)</span><br/><span class="hl-2">async</span><span class="hl-1"> </span><span class="hl-6">onNewMessage</span><span class="hl-1">(</span><span class="hl-2">message</span><span class="hl-1">: </span><span class="hl-2">Message</span><span class="hl-1">, </span><span class="hl-2">threadId</span><span class="hl-1">: </span><span class="hl-2">string</span><span class="hl-1">) {</span><br/><span class="hl-1">  </span><span class="hl-7">// This creates clutter - each message becomes its own Activity</span><br/><span class="hl-1">  </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-2">tools</span><span class="hl-1">.</span><span class="hl-2">plot</span><span class="hl-1">.</span><span class="hl-6">createActivity</span><span class="hl-1">({</span><br/><span class="hl-1">    </span><span class="hl-2">type:</span><span class="hl-1"> </span><span class="hl-2">ActivityType</span><span class="hl-1">.</span><span class="hl-2">Note</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-2">title:</span><span class="hl-1"> </span><span class="hl-3">`Message from </span><span class="hl-4">${</span><span class="hl-2">message</span><span class="hl-13">.</span><span class="hl-2">author</span><span class="hl-4">}</span><span class="hl-3">`</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-2">notes:</span><span class="hl-1"> [{ </span><span class="hl-2">content:</span><span class="hl-1"> </span><span class="hl-2">message</span><span class="hl-1">.</span><span class="hl-2">text</span><span class="hl-1"> }],</span><br/><span class="hl-1">  });</span><br/><span class="hl-1">}</span>
+</code><button type="button">Copy</button></pre>
+
+<p><strong>Why?</strong> Grouping related content keeps the user's workspace organized and provides better context. A chat conversation with 20 messages should be one Activity with 20 Notes, not 20 separate Activities.</p>
 <hr>
 <h2 id="lifecycle-methods" class="tsd-anchor-link">Lifecycle Methods<a href="#lifecycle-methods" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2><p>Twists have several lifecycle methods that are called at specific times.</p>
 <h3 id="activatepriority" class="tsd-anchor-link">activate(priority)<a href="#activatepriority" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3><p>Called when the twist is first activated for a priority.</p>
@@ -137,7 +189,7 @@
 </code><button type="button">Copy</button></pre>
 
 <h3 id="3-batch-long-operations" class="tsd-anchor-link">3. Batch Long Operations<a href="#3-batch-long-operations" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3><p>Break long-running operations into batches:</p>
-<pre><code class="typescript"><span class="hl-2">async</span><span class="hl-1"> </span><span class="hl-6">startSync</span><span class="hl-1">() {</span><br/><span class="hl-1">  </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">callback</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">callback</span><span class="hl-1">(</span><span class="hl-3">&quot;syncBatch&quot;</span><span class="hl-1">, { </span><span class="hl-2">page:</span><span class="hl-1"> </span><span class="hl-12">1</span><span class="hl-1"> });</span><br/><span class="hl-1">  </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">runTask</span><span class="hl-1">(</span><span class="hl-2">callback</span><span class="hl-1">);</span><br/><span class="hl-1">}</span><br/><br/><span class="hl-2">async</span><span class="hl-1"> </span><span class="hl-6">syncBatch</span><span class="hl-1">(</span><span class="hl-2">args</span><span class="hl-1">: </span><span class="hl-2">any</span><span class="hl-1">, </span><span class="hl-2">context</span><span class="hl-1">: { </span><span class="hl-2">page:</span><span class="hl-1"> </span><span class="hl-2">number</span><span class="hl-1"> }) {</span><br/><span class="hl-1">  </span><span class="hl-7">// Process one page</span><br/><span class="hl-1">  </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">hasMore</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-6">processPage</span><span class="hl-1">(</span><span class="hl-2">context</span><span class="hl-1">.</span><span class="hl-2">page</span><span class="hl-1">);</span><br/><br/><span class="hl-1">  </span><span class="hl-0">if</span><span class="hl-1"> (</span><span class="hl-2">hasMore</span><span class="hl-1">) {</span><br/><span class="hl-1">    </span><span class="hl-7">// Queue next batch</span><br/><span class="hl-1">    </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">callback</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">callback</span><span class="hl-1">(</span><span class="hl-3">&quot;syncBatch&quot;</span><span class="hl-1">, {</span><br/><span class="hl-1">      </span><span class="hl-2">page:</span><span class="hl-1"> </span><span class="hl-2">context</span><span class="hl-1">.</span><span class="hl-2">page</span><span class="hl-1"> + </span><span class="hl-12">1</span><br/><span class="hl-1">    });</span><br/><span class="hl-1">    </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">runTask</span><span class="hl-1">(</span><span class="hl-2">callback</span><span class="hl-1">);</span><br/><span class="hl-1">  }</span><br/><span class="hl-1">}</span>
+<pre><code class="typescript"><span class="hl-2">async</span><span class="hl-1"> </span><span class="hl-6">startSync</span><span class="hl-1">() {</span><br/><span class="hl-1">  </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">callback</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">callback</span><span class="hl-1">(</span><span class="hl-3">&quot;syncBatch&quot;</span><span class="hl-1">, { </span><span class="hl-2">page:</span><span class="hl-1"> </span><span class="hl-14">1</span><span class="hl-1"> });</span><br/><span class="hl-1">  </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">runTask</span><span class="hl-1">(</span><span class="hl-2">callback</span><span class="hl-1">);</span><br/><span class="hl-1">}</span><br/><br/><span class="hl-2">async</span><span class="hl-1"> </span><span class="hl-6">syncBatch</span><span class="hl-1">(</span><span class="hl-2">args</span><span class="hl-1">: </span><span class="hl-2">any</span><span class="hl-1">, </span><span class="hl-2">context</span><span class="hl-1">: { </span><span class="hl-2">page:</span><span class="hl-1"> </span><span class="hl-2">number</span><span class="hl-1"> }) {</span><br/><span class="hl-1">  </span><span class="hl-7">// Process one page</span><br/><span class="hl-1">  </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">hasMore</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-6">processPage</span><span class="hl-1">(</span><span class="hl-2">context</span><span class="hl-1">.</span><span class="hl-2">page</span><span class="hl-1">);</span><br/><br/><span class="hl-1">  </span><span class="hl-0">if</span><span class="hl-1"> (</span><span class="hl-2">hasMore</span><span class="hl-1">) {</span><br/><span class="hl-1">    </span><span class="hl-7">// Queue next batch</span><br/><span class="hl-1">    </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">callback</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">callback</span><span class="hl-1">(</span><span class="hl-3">&quot;syncBatch&quot;</span><span class="hl-1">, {</span><br/><span class="hl-1">      </span><span class="hl-2">page:</span><span class="hl-1"> </span><span class="hl-2">context</span><span class="hl-1">.</span><span class="hl-2">page</span><span class="hl-1"> + </span><span class="hl-14">1</span><br/><span class="hl-1">    });</span><br/><span class="hl-1">    </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">runTask</span><span class="hl-1">(</span><span class="hl-2">callback</span><span class="hl-1">);</span><br/><span class="hl-1">  }</span><br/><span class="hl-1">}</span>
 </code><button type="button">Copy</button></pre>
 
 <p>See <a href="Runtime_Environment.html">Runtime Environment</a> for more details.</p>
@@ -158,6 +210,5 @@
 <li><strong><a href="Built-in_Tools.html">Built-in Tools Guide</a></strong> - Learn about Plot, Store, AI, and more</li>
 <li><strong><a href="Building_Custom_Tools.html">Building Custom Tools</a></strong> - Create reusable tools</li>
 <li><strong><a href="Runtime_Environment.html">Runtime Environment</a></strong> - Understand execution constraints</li>
-<li><strong><a href="Advanced.html">Advanced Topics</a></strong> - Complex patterns and techniques</li>
 </ul>
-</div></div><div class="col-sidebar"><div class="page-menu"><div class="tsd-navigation settings"><details class="tsd-accordion"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg><h3>Settings</h3></summary><div class="tsd-accordion-details"><div class="tsd-filter-visibility"><span class="settings-label">Member Visibility</span><ul id="tsd-filter-options"><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-protected" name="protected"/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Protected</span></label></li><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-inherited" name="inherited" checked/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Inherited</span></label></li></ul></div><div class="tsd-theme-toggle"><label class="settings-label" for="tsd-theme">Theme</label><select id="tsd-theme"><option value="os">OS</option><option value="light">Light</option><option value="dark">Dark</option></select></div></div></details></div><details open class="tsd-accordion tsd-page-navigation"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg><h3>On This Page</h3></summary><div class="tsd-accordion-details"><a href="#core-concepts"><span>Core <wbr/>Concepts</span></a><ul><li><a href="#table-of-contents"><span>Table of <wbr/>Contents</span></a></li><li><a href="#twists"><span>Twists</span></a></li><li><ul><li><a href="#what-is-a-twist"><span>What is a <wbr/>Twist?</span></a></li><li><a href="#twist-anatomy"><span>Twist <wbr/>Anatomy</span></a></li><li><a href="#when-to-use-twists"><span>When to <wbr/>Use <wbr/>Twists</span></a></li></ul></li><li><a href="#twist-tools"><span>Twist <wbr/>Tools</span></a></li><li><ul><li><a href="#types-of-tools"><span>Types of <wbr/>Tools</span></a></li><li><ul><li><a href="#1-built-in-tools"><span>1. <wbr/>Built-<wbr/>in <wbr/>Tools</span></a></li><li><a href="#2-custom-tools"><span>2. <wbr/>Custom <wbr/>Tools</span></a></li></ul></li><li><a href="#declaring-tool-dependencies"><span>Declaring <wbr/>Tool <wbr/>Dependencies</span></a></li><li><a href="#accessing-tools"><span>Accessing <wbr/>Tools</span></a></li><li><a href="#direct-access-methods"><span>Direct <wbr/>Access <wbr/>Methods</span></a></li></ul></li><li><a href="#priorities"><span>Priorities</span></a></li><li><ul><li><a href="#priority-hierarchy"><span>Priority <wbr/>Hierarchy</span></a></li><li><a href="#creating-priorities"><span>Creating <wbr/>Priorities</span></a></li><li><a href="#twist-activation"><span>Twist <wbr/>Activation</span></a></li></ul></li><li><a href="#activities"><span>Activities</span></a></li><li><ul><li><a href="#activity-types"><span>Activity <wbr/>Types</span></a></li><li><a href="#activity-properties"><span>Activity <wbr/>Properties</span></a></li><li><a href="#activity-links"><span>Activity <wbr/>Links</span></a></li></ul></li><li><a href="#lifecycle-methods"><span>Lifecycle <wbr/>Methods</span></a></li><li><ul><li><a href="#activatepriority"><span>activate(priority)</span></a></li><li><a href="#upgrade"><span>upgrade()</span></a></li><li><a href="#deactivate"><span>deactivate()</span></a></li></ul></li><li><a href="#best-practices"><span>Best <wbr/>Practices</span></a></li><li><ul><li><a href="#1-state-management"><span>1. <wbr/>State <wbr/>Management</span></a></li><li><a href="#2-error-handling"><span>2. <wbr/>Error <wbr/>Handling</span></a></li><li><a href="#3-batch-long-operations"><span>3. <wbr/>Batch <wbr/>Long <wbr/>Operations</span></a></li><li><a href="#4-type-safety"><span>4. <wbr/>Type <wbr/>Safety</span></a></li><li><a href="#5-tool-composition"><span>5. <wbr/>Tool <wbr/>Composition</span></a></li><li><a href="#6-clear-activity-titles"><span>6. <wbr/>Clear <wbr/>Activity <wbr/>Titles</span></a></li></ul></li><li><a href="#next-steps"><span>Next <wbr/>Steps</span></a></li></ul></div></details></div><div class="site-menu"><nav id="tsd-sidebar-links" class="tsd-navigation"><a href="https://plot.day" class="tsd-nav-link">Plot</a><a href="https://github.com/plotday/plot" class="tsd-nav-link">GitHub</a><a href="https://www.npmjs.com/package/@plotday/twister" class="tsd-nav-link">NPM</a></nav><nav class="tsd-navigation"><a href="../modules.html">Creating Plot Twists</a><ul class="tsd-small-nested-navigation" id="tsd-nav-container"><li>Loading...</li></ul></nav></div></div></div><footer><p class="tsd-generator">Generated using <a href="https://typedoc.org/" target="_blank">TypeDoc</a></p></footer><div class="overlay"></div></body></html>
+</div></div><div class="col-sidebar"><div class="page-menu"><div class="tsd-navigation settings"><details class="tsd-accordion"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg><h3>Settings</h3></summary><div class="tsd-accordion-details"><div class="tsd-filter-visibility"><span class="settings-label">Member Visibility</span><ul id="tsd-filter-options"><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-protected" name="protected"/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Protected</span></label></li><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-inherited" name="inherited" checked/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Inherited</span></label></li></ul></div><div class="tsd-theme-toggle"><label class="settings-label" for="tsd-theme">Theme</label><select id="tsd-theme"><option value="os">OS</option><option value="light">Light</option><option value="dark">Dark</option></select></div></div></details></div><details open class="tsd-accordion tsd-page-navigation"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg><h3>On This Page</h3></summary><div class="tsd-accordion-details"><a href="#core-concepts"><span>Core <wbr/>Concepts</span></a><ul><li><a href="#table-of-contents"><span>Table of <wbr/>Contents</span></a></li><li><a href="#twists"><span>Twists</span></a></li><li><ul><li><a href="#what-is-a-twist"><span>What is a <wbr/>Twist?</span></a></li><li><a href="#twist-anatomy"><span>Twist <wbr/>Anatomy</span></a></li><li><a href="#when-to-use-twists"><span>When to <wbr/>Use <wbr/>Twists</span></a></li></ul></li><li><a href="#twist-tools"><span>Twist <wbr/>Tools</span></a></li><li><ul><li><a href="#types-of-tools"><span>Types of <wbr/>Tools</span></a></li><li><ul><li><a href="#1-built-in-tools"><span>1. <wbr/>Built-<wbr/>in <wbr/>Tools</span></a></li><li><a href="#2-custom-tools"><span>2. <wbr/>Custom <wbr/>Tools</span></a></li></ul></li><li><a href="#declaring-tool-dependencies"><span>Declaring <wbr/>Tool <wbr/>Dependencies</span></a></li><li><a href="#accessing-tools"><span>Accessing <wbr/>Tools</span></a></li><li><a href="#direct-access-methods"><span>Direct <wbr/>Access <wbr/>Methods</span></a></li></ul></li><li><a href="#priorities"><span>Priorities</span></a></li><li><ul><li><a href="#priority-hierarchy"><span>Priority <wbr/>Hierarchy</span></a></li><li><a href="#creating-priorities"><span>Creating <wbr/>Priorities</span></a></li><li><a href="#twist-activation"><span>Twist <wbr/>Activation</span></a></li></ul></li><li><a href="#activities"><span>Activities</span></a></li><li><ul><li><a href="#activity-types"><span>Activity <wbr/>Types</span></a></li><li><a href="#activity-scheduling-states"><span>Activity <wbr/>Scheduling <wbr/>States</span></a></li><li><ul><li><a href="#default-behavior"><span>Default <wbr/>Behavior</span></a></li><li><a href="#when-to-use-each-state"><span>When to <wbr/>Use <wbr/>Each <wbr/>State</span></a></li></ul></li><li><a href="#activity-properties"><span>Activity <wbr/>Properties</span></a></li><li><a href="#activity-notes"><span>Activity <wbr/>Notes</span></a></li><li><a href="#best-practices-for-activities-and-notes"><span>Best <wbr/>Practices for <wbr/>Activities and <wbr/>Notes</span></a></li><li><ul><li><a href="#always-create-activities-with-an-initial-note"><span>Always <wbr/>Create <wbr/>Activities with an <wbr/>Initial <wbr/>Note</span></a></li><li><a href="#add-notes-to-existing-activities-for-related-content"><span>Add <wbr/>Notes to <wbr/>Existing <wbr/>Activities for <wbr/>Related <wbr/>Content</span></a></li></ul></li></ul></li><li><a href="#lifecycle-methods"><span>Lifecycle <wbr/>Methods</span></a></li><li><ul><li><a href="#activatepriority"><span>activate(priority)</span></a></li><li><a href="#upgrade"><span>upgrade()</span></a></li><li><a href="#deactivate"><span>deactivate()</span></a></li></ul></li><li><a href="#best-practices"><span>Best <wbr/>Practices</span></a></li><li><ul><li><a href="#1-state-management"><span>1. <wbr/>State <wbr/>Management</span></a></li><li><a href="#2-error-handling"><span>2. <wbr/>Error <wbr/>Handling</span></a></li><li><a href="#3-batch-long-operations"><span>3. <wbr/>Batch <wbr/>Long <wbr/>Operations</span></a></li><li><a href="#4-type-safety"><span>4. <wbr/>Type <wbr/>Safety</span></a></li><li><a href="#5-tool-composition"><span>5. <wbr/>Tool <wbr/>Composition</span></a></li><li><a href="#6-clear-activity-titles"><span>6. <wbr/>Clear <wbr/>Activity <wbr/>Titles</span></a></li></ul></li><li><a href="#next-steps"><span>Next <wbr/>Steps</span></a></li></ul></div></details></div><div class="site-menu"><nav id="tsd-sidebar-links" class="tsd-navigation"><a href="https://plot.day" class="tsd-nav-link">Plot</a><a href="https://github.com/plotday/plot" class="tsd-nav-link">GitHub</a><a href="https://www.npmjs.com/package/@plotday/twister" class="tsd-nav-link">NPM</a></nav><nav class="tsd-navigation"><a href="../modules.html">Creating Plot Twists</a><ul class="tsd-small-nested-navigation" id="tsd-nav-container"><li>Loading...</li></ul></nav></div></div></div><footer><p class="tsd-generator">Generated using <a href="https://typedoc.org/" target="_blank">TypeDoc</a></p></footer><div class="overlay"></div></body></html>

package/dist/docs/documents/Getting_Started.html

@@ -41,7 +41,7 @@
 </code><button>Copy</button></pre>
 
 <h3 id="step-2-implement-your-twist" class="tsd-anchor-link">Step 2: Implement Your Twist<a href="#step-2-implement-your-twist" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3><p>Edit <code>src/index.ts</code> to add your twist logic:</p>
-<pre><code class="typescript"><span class="hl-0">import</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-0">type</span><span class="hl-1"> </span><span class="hl-2">Activity</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-2">ActivityType</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-2">Twist</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-0">type</span><span class="hl-1"> </span><span class="hl-2">Priority</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-0">type</span><span class="hl-1"> </span><span class="hl-2">ToolBuilder</span><span class="hl-1">,</span><br/><span class="hl-1">} </span><span class="hl-0">from</span><span class="hl-1"> </span><span class="hl-3">&quot;@plotday/twister&quot;</span><span class="hl-1">;</span><br/><span class="hl-0">import</span><span class="hl-1"> { </span><span class="hl-2">Plot</span><span class="hl-1"> } </span><span class="hl-0">from</span><span class="hl-1"> </span><span class="hl-3">&quot;@plotday/twister/tools/plot&quot;</span><span class="hl-1">;</span><br/><br/><span class="hl-0">export</span><span class="hl-1"> </span><span class="hl-0">default</span><span class="hl-1"> </span><span class="hl-4">class</span><span class="hl-1"> </span><span class="hl-5">MyTwist</span><span class="hl-1"> </span><span class="hl-4">extends</span><span class="hl-1"> </span><span class="hl-5">Twist</span><span class="hl-1">&lt;</span><span class="hl-5">MyTwist</span><span class="hl-1">&gt; {</span><br/><span class="hl-1">  </span><span class="hl-7">// Declare tool dependencies</span><br/><span class="hl-1">  </span><span class="hl-6">build</span><span class="hl-1">(</span><span class="hl-2">build</span><span class="hl-1">: </span><span class="hl-5">ToolBuilder</span><span class="hl-1">) {</span><br/><span class="hl-1">    </span><span class="hl-0">return</span><span class="hl-1"> {</span><br/><span class="hl-1">      </span><span class="hl-2">plot:</span><span class="hl-1"> </span><span class="hl-6">build</span><span class="hl-1">(</span><span class="hl-2">Plot</span><span class="hl-1">),</span><br/><span class="hl-1">    };</span><br/><span class="hl-1">  }</span><br/><br/><span class="hl-1">  </span><span class="hl-7">// Called when the twist is activated for a priority</span><br/><span class="hl-1">  </span><span class="hl-4">async</span><span class="hl-1"> </span><span class="hl-6">activate</span><span class="hl-1">(</span><span class="hl-2">priority</span><span class="hl-1">: </span><span class="hl-5">Pick</span><span class="hl-1">&lt;</span><span class="hl-5">Priority</span><span class="hl-1">, </span><span class="hl-3">&quot;id&quot;</span><span class="hl-1">&gt;) {</span><br/><span class="hl-1">    </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-2">tools</span><span class="hl-1">.</span><span class="hl-2">plot</span><span class="hl-1">.</span><span class="hl-6">createActivity</span><span class="hl-1">({</span><br/><span class="hl-1">      </span><span class="hl-2">type:</span><span class="hl-1"> </span><span class="hl-2">ActivityType</span><span class="hl-1">.</span><span class="hl-2">Note</span><span class="hl-1">,</span><br/><span class="hl-1">      </span><span class="hl-2">title:</span><span class="hl-1"> </span><span class="hl-3">&quot;Welcome! Your twist is now active.&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">    });</span><br/><span class="hl-1">  }</span><br/><br/><span class="hl-1">  </span><span class="hl-7">// Called when an activity is routed to this twist</span><br/><span class="hl-1">  </span><span class="hl-4">async</span><span class="hl-1"> </span><span class="hl-6">activity</span><span class="hl-1">(</span><span class="hl-2">activity</span><span class="hl-1">: </span><span class="hl-5">Activity</span><span class="hl-1">) {</span><br/><span class="hl-1">    </span><span class="hl-2">console</span><span class="hl-1">.</span><span class="hl-6">log</span><span class="hl-1">(</span><span class="hl-3">&quot;Processing activity:&quot;</span><span class="hl-1">, </span><span class="hl-2">activity</span><span class="hl-1">.</span><span class="hl-2">title</span><span class="hl-1">);</span><br/><span class="hl-1">  }</span><br/><span class="hl-1">}</span>
+<pre><code class="typescript"><span class="hl-0">import</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-0">type</span><span class="hl-1"> </span><span class="hl-2">Activity</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-2">ActivityType</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-0">type</span><span class="hl-1"> </span><span class="hl-2">Priority</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-0">type</span><span class="hl-1"> </span><span class="hl-2">ToolBuilder</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-2">Twist</span><span class="hl-1">,</span><br/><span class="hl-1">} </span><span class="hl-0">from</span><span class="hl-1"> </span><span class="hl-3">&quot;@plotday/twister&quot;</span><span class="hl-1">;</span><br/><span class="hl-0">import</span><span class="hl-1"> { </span><span class="hl-2">Plot</span><span class="hl-1"> } </span><span class="hl-0">from</span><span class="hl-1"> </span><span class="hl-3">&quot;@plotday/twister/tools/plot&quot;</span><span class="hl-1">;</span><br/><br/><span class="hl-0">export</span><span class="hl-1"> </span><span class="hl-0">default</span><span class="hl-1"> </span><span class="hl-4">class</span><span class="hl-1"> </span><span class="hl-5">MyTwist</span><span class="hl-1"> </span><span class="hl-4">extends</span><span class="hl-1"> </span><span class="hl-5">Twist</span><span class="hl-1">&lt;</span><span class="hl-5">MyTwist</span><span class="hl-1">&gt; {</span><br/><span class="hl-1">  </span><span class="hl-7">// Declare tool dependencies</span><br/><span class="hl-1">  </span><span class="hl-6">build</span><span class="hl-1">(</span><span class="hl-2">build</span><span class="hl-1">: </span><span class="hl-5">ToolBuilder</span><span class="hl-1">) {</span><br/><span class="hl-1">    </span><span class="hl-0">return</span><span class="hl-1"> {</span><br/><span class="hl-1">      </span><span class="hl-2">plot:</span><span class="hl-1"> </span><span class="hl-6">build</span><span class="hl-1">(</span><span class="hl-2">Plot</span><span class="hl-1">),</span><br/><span class="hl-1">    };</span><br/><span class="hl-1">  }</span><br/><br/><span class="hl-1">  </span><span class="hl-7">// Called when the twist is activated for a priority</span><br/><span class="hl-1">  </span><span class="hl-4">async</span><span class="hl-1"> </span><span class="hl-6">activate</span><span class="hl-1">(</span><span class="hl-2">priority</span><span class="hl-1">: </span><span class="hl-5">Pick</span><span class="hl-1">&lt;</span><span class="hl-5">Priority</span><span class="hl-1">, </span><span class="hl-3">&quot;id&quot;</span><span class="hl-1">&gt;) {</span><br/><span class="hl-1">    </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-2">tools</span><span class="hl-1">.</span><span class="hl-2">plot</span><span class="hl-1">.</span><span class="hl-6">createActivity</span><span class="hl-1">({</span><br/><span class="hl-1">      </span><span class="hl-2">type:</span><span class="hl-1"> </span><span class="hl-2">ActivityType</span><span class="hl-1">.</span><span class="hl-2">Note</span><span class="hl-1">,</span><br/><span class="hl-1">      </span><span class="hl-2">title:</span><span class="hl-1"> </span><span class="hl-3">&quot;Welcome! Your twist is now active.&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">      </span><span class="hl-2">notes:</span><span class="hl-1"> [</span><br/><span class="hl-1">        {</span><br/><span class="hl-1">          </span><span class="hl-2">content:</span><span class="hl-1"> </span><span class="hl-3">&quot;Your twist is ready to use. You can now start creating activities and automating your workflow.&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">        },</span><br/><span class="hl-1">      ],</span><br/><span class="hl-1">    });</span><br/><span class="hl-1">  }</span><br/><br/><span class="hl-1">  </span><span class="hl-7">// Called when an activity is routed to this twist</span><br/><span class="hl-1">  </span><span class="hl-4">async</span><span class="hl-1"> </span><span class="hl-6">activity</span><span class="hl-1">(</span><span class="hl-2">activity</span><span class="hl-1">: </span><span class="hl-5">Activity</span><span class="hl-1">) {</span><br/><span class="hl-1">    </span><span class="hl-2">console</span><span class="hl-1">.</span><span class="hl-6">log</span><span class="hl-1">(</span><span class="hl-3">&quot;Processing activity:&quot;</span><span class="hl-1">, </span><span class="hl-2">activity</span><span class="hl-1">.</span><span class="hl-2">title</span><span class="hl-1">);</span><br/><span class="hl-1">  }</span><br/><span class="hl-1">}</span>
 </code><button type="button">Copy</button></pre>
 
 <h3 id="step-3-test-locally" class="tsd-anchor-link">Step 3: Test Locally<a href="#step-3-test-locally" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3><p>Build and check for errors:</p>
@@ -77,7 +77,14 @@
 <li><strong><a href="Building_Custom_Tools.html">Building Custom Tools</a></strong> - Create your own reusable twist tools</li>
 <li><strong><a href="Runtime_Environment.html">Runtime Environment</a></strong> - Understand execution constraints and optimization</li>
 </ul>
-<h2 id="common-first-tasks" class="tsd-anchor-link">Common First Tasks<a href="#common-first-tasks" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2><h3 id="creating-activities" class="tsd-anchor-link">Creating Activities<a href="#creating-activities" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3><pre><code class="typescript"><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-2">tools</span><span class="hl-1">.</span><span class="hl-2">plot</span><span class="hl-1">.</span><span class="hl-6">createActivity</span><span class="hl-1">({</span><br/><span class="hl-1">  </span><span class="hl-2">type:</span><span class="hl-1"> </span><span class="hl-2">ActivityType</span><span class="hl-1">.</span><span class="hl-2">Action</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-2">title:</span><span class="hl-1"> </span><span class="hl-3">&quot;Review pull request&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-2">note:</span><span class="hl-1"> </span><span class="hl-3">&quot;Check the new authentication flow&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-2">links:</span><span class="hl-1"> [</span><br/><span class="hl-1">    {</span><br/><span class="hl-1">      </span><span class="hl-2">type:</span><span class="hl-1"> </span><span class="hl-2">ActivityLinkType</span><span class="hl-1">.</span><span class="hl-2">external</span><span class="hl-1">,</span><br/><span class="hl-1">      </span><span class="hl-2">title:</span><span class="hl-1"> </span><span class="hl-3">&quot;View PR&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">      </span><span class="hl-2">url:</span><span class="hl-1"> </span><span class="hl-3">&quot;https://github.com/org/repo/pull/123&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">    },</span><br/><span class="hl-1">  ],</span><br/><span class="hl-1">});</span>
+<h2 id="common-first-tasks" class="tsd-anchor-link">Common First Tasks<a href="#common-first-tasks" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2><h3 id="understanding-activities-and-notes" class="tsd-anchor-link">Understanding Activities and Notes<a href="#understanding-activities-and-notes" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3><p><strong>Activity</strong> represents something done or to be done (a task, event, or conversation), while <strong>Notes</strong> represent the updates and details on that activity.</p>
+<p>Think of an <strong>Activity as a thread</strong> on a messaging platform, and <strong>Notes as the messages in that thread</strong>. Always create activities with an initial note, and add notes for updates rather than creating new activities.</p>
+<h3 id="creating-activities" class="tsd-anchor-link">Creating Activities<a href="#creating-activities" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3><p>Always create activities with an initial note. The <code>notes</code> array can contain multiple notes (messages in the thread):</p>
+<pre><code class="typescript"><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-2">tools</span><span class="hl-1">.</span><span class="hl-2">plot</span><span class="hl-1">.</span><span class="hl-6">createActivity</span><span class="hl-1">({</span><br/><span class="hl-1">  </span><span class="hl-2">type:</span><span class="hl-1"> </span><span class="hl-2">ActivityType</span><span class="hl-1">.</span><span class="hl-2">Action</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-2">title:</span><span class="hl-1"> </span><span class="hl-3">&quot;Review pull request&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-2">source:</span><span class="hl-1"> </span><span class="hl-3">&quot;github:pr:123&quot;</span><span class="hl-1">, </span><span class="hl-7">// For deduplication</span><br/><span class="hl-1">  </span><span class="hl-2">notes:</span><span class="hl-1"> [</span><br/><span class="hl-1">    {</span><br/><span class="hl-1">      </span><span class="hl-2">content:</span><span class="hl-1"> </span><span class="hl-3">&quot;Please review the authentication changes and ensure they follow security best practices.&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">      </span><span class="hl-2">links:</span><span class="hl-1"> [</span><br/><span class="hl-1">        {</span><br/><span class="hl-1">          </span><span class="hl-2">type:</span><span class="hl-1"> </span><span class="hl-2">ActivityLinkType</span><span class="hl-1">.</span><span class="hl-2">external</span><span class="hl-1">,</span><br/><span class="hl-1">          </span><span class="hl-2">title:</span><span class="hl-1"> </span><span class="hl-3">&quot;View PR&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">          </span><span class="hl-2">url:</span><span class="hl-1"> </span><span class="hl-3">&quot;https://github.com/org/repo/pull/123&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">        },</span><br/><span class="hl-1">      ],</span><br/><span class="hl-1">    },</span><br/><span class="hl-1">  ],</span><br/><span class="hl-1">});</span>
+</code><button type="button">Copy</button></pre>
+
+<h4 id="scheduling-states-for-actions" class="tsd-anchor-link">Scheduling States for Actions<a href="#scheduling-states-for-actions" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h4><p><strong>Important:</strong> When creating Actions (tasks), the <code>start</code> field determines how they appear in Plot. By default, omitting <code>start</code> creates a &quot;Do Now&quot; task. For most integrations, you should explicitly set <code>start: null</code> to create backlog items.</p>
+<pre><code class="typescript"><span class="hl-7">// &quot;Do Now&quot; - Actionable today (DEFAULT when start is omitted)</span><br/><span class="hl-7">// Use for urgent tasks or items actively in progress</span><br/><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-2">tools</span><span class="hl-1">.</span><span class="hl-2">plot</span><span class="hl-1">.</span><span class="hl-6">createActivity</span><span class="hl-1">({</span><br/><span class="hl-1">  </span><span class="hl-2">type:</span><span class="hl-1"> </span><span class="hl-2">ActivityType</span><span class="hl-1">.</span><span class="hl-2">Action</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-2">title:</span><span class="hl-1"> </span><span class="hl-3">&quot;Fix critical bug in production&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-2">notes:</span><span class="hl-1"> [{ </span><span class="hl-2">content:</span><span class="hl-1"> </span><span class="hl-3">&quot;Users reporting login failures&quot;</span><span class="hl-1"> }],</span><br/><span class="hl-1">  </span><span class="hl-7">// Omitting start defaults to current time</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-7">// &quot;Do Someday&quot; - Backlog item (RECOMMENDED for most synced tasks)</span><br/><span class="hl-7">// Use for task backlog, future ideas, non-urgent items</span><br/><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-2">tools</span><span class="hl-1">.</span><span class="hl-2">plot</span><span class="hl-1">.</span><span class="hl-6">createActivity</span><span class="hl-1">({</span><br/><span class="hl-1">  </span><span class="hl-2">type:</span><span class="hl-1"> </span><span class="hl-2">ActivityType</span><span class="hl-1">.</span><span class="hl-2">Action</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-2">title:</span><span class="hl-1"> </span><span class="hl-3">&quot;Refactor authentication module&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-2">start:</span><span class="hl-1"> </span><span class="hl-4">null</span><span class="hl-1">, </span><span class="hl-7">// Explicitly set to null for backlog</span><br/><span class="hl-1">  </span><span class="hl-2">notes:</span><span class="hl-1"> [{ </span><span class="hl-2">content:</span><span class="hl-1"> </span><span class="hl-3">&quot;Technical debt item to address later&quot;</span><span class="hl-1"> }],</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-7">// &quot;Do Later&quot; - Scheduled for specific date</span><br/><span class="hl-7">// Use when task has a specific due date</span><br/><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-2">tools</span><span class="hl-1">.</span><span class="hl-2">plot</span><span class="hl-1">.</span><span class="hl-6">createActivity</span><span class="hl-1">({</span><br/><span class="hl-1">  </span><span class="hl-2">type:</span><span class="hl-1"> </span><span class="hl-2">ActivityType</span><span class="hl-1">.</span><span class="hl-2">Action</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-2">title:</span><span class="hl-1"> </span><span class="hl-3">&quot;Submit expense report&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-2">start:</span><span class="hl-1"> </span><span class="hl-4">new</span><span class="hl-1"> </span><span class="hl-6">Date</span><span class="hl-1">(</span><span class="hl-3">&quot;2025-01-31&quot;</span><span class="hl-1">), </span><span class="hl-7">// Due date</span><br/><span class="hl-1">  </span><span class="hl-2">notes:</span><span class="hl-1"> [{ </span><span class="hl-2">content:</span><span class="hl-1"> </span><span class="hl-3">&quot;December expenses need to be submitted by end of month&quot;</span><span class="hl-1"> }],</span><br/><span class="hl-1">});</span>
 </code><button type="button">Copy</button></pre>
 
 <h3 id="storing-data" class="tsd-anchor-link">Storing Data<a href="#storing-data" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3><pre><code class="typescript"><span class="hl-7">// Save</span><br/><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">set</span><span class="hl-1">(</span><span class="hl-3">&quot;last_sync&quot;</span><span class="hl-1">, </span><span class="hl-4">new</span><span class="hl-1"> </span><span class="hl-6">Date</span><span class="hl-1">().</span><span class="hl-6">toISOString</span><span class="hl-1">());</span><br/><br/><span class="hl-7">// Retrieve</span><br/><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">lastSync</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">get</span><span class="hl-1">&lt;</span><span class="hl-5">string</span><span class="hl-1">&gt;(</span><span class="hl-3">&quot;last_sync&quot;</span><span class="hl-1">);</span>
@@ -86,9 +93,18 @@
 <h3 id="scheduling-tasks" class="tsd-anchor-link">Scheduling Tasks<a href="#scheduling-tasks" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3><pre><code class="typescript"><span class="hl-7">// Run immediately</span><br/><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">callback</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">callback</span><span class="hl-1">(</span><span class="hl-3">&quot;processData&quot;</span><span class="hl-1">);</span><br/><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">runTask</span><span class="hl-1">(</span><span class="hl-2">callback</span><span class="hl-1">);</span><br/><br/><span class="hl-7">// Schedule for later</span><br/><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">runTask</span><span class="hl-1">(</span><span class="hl-2">callback</span><span class="hl-1">, {</span><br/><span class="hl-1">  </span><span class="hl-2">runAt:</span><span class="hl-1"> </span><span class="hl-4">new</span><span class="hl-1"> </span><span class="hl-6">Date</span><span class="hl-1">(</span><span class="hl-3">&quot;2025-02-01T10:00:00Z&quot;</span><span class="hl-1">),</span><br/><span class="hl-1">});</span>
 </code><button type="button">Copy</button></pre>
 
+<h3 id="best-practices" class="tsd-anchor-link">Best Practices<a href="#best-practices" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3><h4 id="always-include-notes-with-activities" class="tsd-anchor-link">Always Include Notes with Activities<a href="#always-include-notes-with-activities" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h4><p><strong>Important:</strong> Always create Activities with at least one initial Note. The <code>title</code> and <code>preview</code> are brief summaries that may be truncated in the UI. Detailed information should go in Notes.</p>
+<pre><code class="typescript"><span class="hl-7">// ✅ Good - Activity with detailed Note</span><br/><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-2">tools</span><span class="hl-1">.</span><span class="hl-2">plot</span><span class="hl-1">.</span><span class="hl-6">createActivity</span><span class="hl-1">({</span><br/><span class="hl-1">  </span><span class="hl-2">type:</span><span class="hl-1"> </span><span class="hl-2">ActivityType</span><span class="hl-1">.</span><span class="hl-2">Action</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-2">title:</span><span class="hl-1"> </span><span class="hl-3">&quot;Deploy v2.0&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-2">notes:</span><span class="hl-1"> [</span><br/><span class="hl-1">    {</span><br/><span class="hl-1">      </span><span class="hl-2">note:</span><span class="hl-1"> </span><span class="hl-3">&quot;Deployment checklist:</span><span class="hl-12">\n</span><span class="hl-3">- Run database migrations</span><span class="hl-12">\n</span><span class="hl-3">- Update environment variables</span><span class="hl-12">\n</span><span class="hl-3">- Deploy backend services</span><span class="hl-12">\n</span><span class="hl-3">- Deploy frontend</span><span class="hl-12">\n</span><span class="hl-3">- Run smoke tests&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">      </span><span class="hl-2">links:</span><span class="hl-1"> [</span><br/><span class="hl-1">        {</span><br/><span class="hl-1">          </span><span class="hl-2">type:</span><span class="hl-1"> </span><span class="hl-2">ActivityLinkType</span><span class="hl-1">.</span><span class="hl-2">external</span><span class="hl-1">,</span><br/><span class="hl-1">          </span><span class="hl-2">title:</span><span class="hl-1"> </span><span class="hl-3">&quot;Deployment Guide&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">          </span><span class="hl-2">url:</span><span class="hl-1"> </span><span class="hl-3">&quot;https://docs.example.com/deploy&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">        },</span><br/><span class="hl-1">      ],</span><br/><span class="hl-1">    },</span><br/><span class="hl-1">  ],</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-7">// ❌ Bad - No detailed information</span><br/><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-2">tools</span><span class="hl-1">.</span><span class="hl-2">plot</span><span class="hl-1">.</span><span class="hl-6">createActivity</span><span class="hl-1">({</span><br/><span class="hl-1">  </span><span class="hl-2">type:</span><span class="hl-1"> </span><span class="hl-2">ActivityType</span><span class="hl-1">.</span><span class="hl-2">Action</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-2">title:</span><span class="hl-1"> </span><span class="hl-3">&quot;Deploy v2.0&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-7">// Missing Notes with context and steps</span><br/><span class="hl-1">});</span>
+</code><button type="button">Copy</button></pre>
+
+<h4 id="add-notes-to-existing-activities-for-related-content" class="tsd-anchor-link">Add Notes to Existing Activities for Related Content<a href="#add-notes-to-existing-activities-for-related-content" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h4><p>For conversations, email threads, or workflows, add Notes to the existing Activity instead of creating new Activities:</p>
+<pre><code class="typescript"><span class="hl-7">// Check if Activity exists</span><br/><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">existing</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-2">tools</span><span class="hl-1">.</span><span class="hl-2">plot</span><span class="hl-1">.</span><span class="hl-6">getActivityBySource</span><span class="hl-1">({</span><br/><span class="hl-1">  </span><span class="hl-2">conversation_id:</span><span class="hl-1"> </span><span class="hl-2">conversationId</span><span class="hl-1">,</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-0">if</span><span class="hl-1"> (</span><span class="hl-2">existing</span><span class="hl-1">) {</span><br/><span class="hl-1">  </span><span class="hl-7">// Add to existing Activity</span><br/><span class="hl-1">  </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-2">tools</span><span class="hl-1">.</span><span class="hl-2">plot</span><span class="hl-1">.</span><span class="hl-6">createNote</span><span class="hl-1">({</span><br/><span class="hl-1">    </span><span class="hl-2">activity:</span><span class="hl-1"> { </span><span class="hl-2">id:</span><span class="hl-1"> </span><span class="hl-2">existing</span><span class="hl-1">.</span><span class="hl-2">id</span><span class="hl-1"> },</span><br/><span class="hl-1">    </span><span class="hl-2">note:</span><span class="hl-1"> </span><span class="hl-2">newMessage</span><span class="hl-1">.</span><span class="hl-2">text</span><span class="hl-1">,</span><br/><span class="hl-1">  });</span><br/><span class="hl-1">} </span><span class="hl-0">else</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-7">// Create new Activity with initial Note</span><br/><span class="hl-1">  </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-2">tools</span><span class="hl-1">.</span><span class="hl-2">plot</span><span class="hl-1">.</span><span class="hl-6">createActivity</span><span class="hl-1">({</span><br/><span class="hl-1">    </span><span class="hl-2">type:</span><span class="hl-1"> </span><span class="hl-2">ActivityType</span><span class="hl-1">.</span><span class="hl-2">Note</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-2">title:</span><span class="hl-1"> </span><span class="hl-3">&quot;New conversation&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-2">meta:</span><span class="hl-1"> { </span><span class="hl-2">conversation_id:</span><span class="hl-1"> </span><span class="hl-2">conversationId</span><span class="hl-1"> },</span><br/><span class="hl-1">    </span><span class="hl-2">notes:</span><span class="hl-1"> [{ </span><span class="hl-2">note:</span><span class="hl-1"> </span><span class="hl-2">newMessage</span><span class="hl-1">.</span><span class="hl-2">text</span><span class="hl-1"> }],</span><br/><span class="hl-1">  });</span><br/><span class="hl-1">}</span>
+</code><button type="button">Copy</button></pre>
+
+<p>See <a href="Core_Concepts.html#best-practices-for-activities-and-notes">Core Concepts - Best Practices</a> for more details.</p>
 <h2 id="need-help" class="tsd-anchor-link">Need Help?<a href="#need-help" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2><ul>
 <li><strong>Documentation</strong>: Continue reading the guides</li>
 <li><strong>Examples</strong>: Check the <a href="https://github.com/plotday/plot/tree/main/twists">examples directory</a></li>
 <li><strong>Issues</strong>: <a href="https://github.com/plotday/plot/issues">Report bugs or request features</a></li>
 </ul>
-</div></div><div class="col-sidebar"><div class="page-menu"><div class="tsd-navigation settings"><details class="tsd-accordion"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg><h3>Settings</h3></summary><div class="tsd-accordion-details"><div class="tsd-filter-visibility"><span class="settings-label">Member Visibility</span><ul id="tsd-filter-options"><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-protected" name="protected"/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Protected</span></label></li><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-inherited" name="inherited" checked/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Inherited</span></label></li></ul></div><div class="tsd-theme-toggle"><label class="settings-label" for="tsd-theme">Theme</label><select id="tsd-theme"><option value="os">OS</option><option value="light">Light</option><option value="dark">Dark</option></select></div></div></details></div><details open class="tsd-accordion tsd-page-navigation"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg><h3>On This Page</h3></summary><div class="tsd-accordion-details"><a href="#getting-started-with-plot-twists"><span>Getting <wbr/>Started with <wbr/>Plot <wbr/>Twists</span></a><ul><li><a href="#choose-your-path"><span>Choose <wbr/>Your <wbr/>Path</span></a></li><li><a href="#no-code-twists"><span>No-<wbr/>Code <wbr/>Twists</span></a></li><li><ul><li><a href="#step-1-create-a-plot-twistmd-file"><span>Step 1: <wbr/>Create a plot-<wbr/>twist.md <wbr/>File</span></a></li><li><a href="#step-2-deploy-your-twist"><span>Step 2: <wbr/>Deploy <wbr/>Your <wbr/>Twist</span></a></li><li><a href="#optional-generate-code-first"><span>Optional: <wbr/>Generate <wbr/>Code <wbr/>First</span></a></li></ul></li><li><a href="#developer-twists"><span>Developer <wbr/>Twists</span></a></li><li><ul><li><a href="#step-1-create-a-new-twist-project"><span>Step 1: <wbr/>Create a <wbr/>New <wbr/>Twist <wbr/>Project</span></a></li><li><a href="#step-2-implement-your-twist"><span>Step 2: <wbr/>Implement <wbr/>Your <wbr/>Twist</span></a></li><li><a href="#step-3-test-locally"><span>Step 3: <wbr/>Test <wbr/>Locally</span></a></li><li><a href="#step-4-deploy"><span>Step 4: <wbr/>Deploy</span></a></li></ul></li><li><a href="#understanding-the-project-structure"><span>Understanding the <wbr/>Project <wbr/>Structure</span></a></li><li><ul><li><a href="#twist-file-srcindexts"><span>Twist <wbr/>File (src/index.ts)</span></a></li><li><a href="#configuration-plot-twistjson"><span>Configuration (plot-<wbr/>twist.json)</span></a></li><li><a href="#typescript-config-tsconfigjson"><span>Type<wbr/>Script <wbr/>Config (tsconfig.json)</span></a></li></ul></li><li><a href="#next-steps"><span>Next <wbr/>Steps</span></a></li><li><a href="#common-first-tasks"><span>Common <wbr/>First <wbr/>Tasks</span></a></li><li><ul><li><a href="#creating-activities"><span>Creating <wbr/>Activities</span></a></li><li><a href="#storing-data"><span>Storing <wbr/>Data</span></a></li><li><a href="#scheduling-tasks"><span>Scheduling <wbr/>Tasks</span></a></li></ul></li><li><a href="#need-help"><span>Need <wbr/>Help?</span></a></li></ul></div></details></div><div class="site-menu"><nav id="tsd-sidebar-links" class="tsd-navigation"><a href="https://plot.day" class="tsd-nav-link">Plot</a><a href="https://github.com/plotday/plot" class="tsd-nav-link">GitHub</a><a href="https://www.npmjs.com/package/@plotday/twister" class="tsd-nav-link">NPM</a></nav><nav class="tsd-navigation"><a href="../modules.html">Creating Plot Twists</a><ul class="tsd-small-nested-navigation" id="tsd-nav-container"><li>Loading...</li></ul></nav></div></div></div><footer><p class="tsd-generator">Generated using <a href="https://typedoc.org/" target="_blank">TypeDoc</a></p></footer><div class="overlay"></div></body></html>
+</div></div><div class="col-sidebar"><div class="page-menu"><div class="tsd-navigation settings"><details class="tsd-accordion"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg><h3>Settings</h3></summary><div class="tsd-accordion-details"><div class="tsd-filter-visibility"><span class="settings-label">Member Visibility</span><ul id="tsd-filter-options"><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-protected" name="protected"/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Protected</span></label></li><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-inherited" name="inherited" checked/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Inherited</span></label></li></ul></div><div class="tsd-theme-toggle"><label class="settings-label" for="tsd-theme">Theme</label><select id="tsd-theme"><option value="os">OS</option><option value="light">Light</option><option value="dark">Dark</option></select></div></div></details></div><details open class="tsd-accordion tsd-page-navigation"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg><h3>On This Page</h3></summary><div class="tsd-accordion-details"><a href="#getting-started-with-plot-twists"><span>Getting <wbr/>Started with <wbr/>Plot <wbr/>Twists</span></a><ul><li><a href="#choose-your-path"><span>Choose <wbr/>Your <wbr/>Path</span></a></li><li><a href="#no-code-twists"><span>No-<wbr/>Code <wbr/>Twists</span></a></li><li><ul><li><a href="#step-1-create-a-plot-twistmd-file"><span>Step 1: <wbr/>Create a plot-<wbr/>twist.md <wbr/>File</span></a></li><li><a href="#step-2-deploy-your-twist"><span>Step 2: <wbr/>Deploy <wbr/>Your <wbr/>Twist</span></a></li><li><a href="#optional-generate-code-first"><span>Optional: <wbr/>Generate <wbr/>Code <wbr/>First</span></a></li></ul></li><li><a href="#developer-twists"><span>Developer <wbr/>Twists</span></a></li><li><ul><li><a href="#step-1-create-a-new-twist-project"><span>Step 1: <wbr/>Create a <wbr/>New <wbr/>Twist <wbr/>Project</span></a></li><li><a href="#step-2-implement-your-twist"><span>Step 2: <wbr/>Implement <wbr/>Your <wbr/>Twist</span></a></li><li><a href="#step-3-test-locally"><span>Step 3: <wbr/>Test <wbr/>Locally</span></a></li><li><a href="#step-4-deploy"><span>Step 4: <wbr/>Deploy</span></a></li></ul></li><li><a href="#understanding-the-project-structure"><span>Understanding the <wbr/>Project <wbr/>Structure</span></a></li><li><ul><li><a href="#twist-file-srcindexts"><span>Twist <wbr/>File (src/index.ts)</span></a></li><li><a href="#configuration-plot-twistjson"><span>Configuration (plot-<wbr/>twist.json)</span></a></li><li><a href="#typescript-config-tsconfigjson"><span>Type<wbr/>Script <wbr/>Config (tsconfig.json)</span></a></li></ul></li><li><a href="#next-steps"><span>Next <wbr/>Steps</span></a></li><li><a href="#common-first-tasks"><span>Common <wbr/>First <wbr/>Tasks</span></a></li><li><ul><li><a href="#understanding-activities-and-notes"><span>Understanding <wbr/>Activities and <wbr/>Notes</span></a></li><li><a href="#creating-activities"><span>Creating <wbr/>Activities</span></a></li><li><ul><li><a href="#scheduling-states-for-actions"><span>Scheduling <wbr/>States for <wbr/>Actions</span></a></li></ul></li><li><a href="#storing-data"><span>Storing <wbr/>Data</span></a></li><li><a href="#scheduling-tasks"><span>Scheduling <wbr/>Tasks</span></a></li><li><a href="#best-practices"><span>Best <wbr/>Practices</span></a></li><li><ul><li><a href="#always-include-notes-with-activities"><span>Always <wbr/>Include <wbr/>Notes with <wbr/>Activities</span></a></li><li><a href="#add-notes-to-existing-activities-for-related-content"><span>Add <wbr/>Notes to <wbr/>Existing <wbr/>Activities for <wbr/>Related <wbr/>Content</span></a></li></ul></li></ul></li><li><a href="#need-help"><span>Need <wbr/>Help?</span></a></li></ul></div></details></div><div class="site-menu"><nav id="tsd-sidebar-links" class="tsd-navigation"><a href="https://plot.day" class="tsd-nav-link">Plot</a><a href="https://github.com/plotday/plot" class="tsd-nav-link">GitHub</a><a href="https://www.npmjs.com/package/@plotday/twister" class="tsd-nav-link">NPM</a></nav><nav class="tsd-navigation"><a href="../modules.html">Creating Plot Twists</a><ul class="tsd-small-nested-navigation" id="tsd-nav-container"><li>Loading...</li></ul></nav></div></div></div><footer><p class="tsd-generator">Generated using <a href="https://typedoc.org/" target="_blank">TypeDoc</a></p></footer><div class="overlay"></div></body></html>