@plotday/twister 0.57.0 → 0.58.0

package/dist/docs/documents/Core_Concepts.html

@@ -2,8 +2,8 @@
 <h2 id="table-of-contents" class="tsd-anchor-link">Table of Contents<a href="#table-of-contents" 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><a href="#twists">Twists</a></li>
 <li><a href="#twist-tools">Twist Tools</a></li>
-<li><a href="#priorities">Priorities</a></li>
-<li><a href="#activities">Activities</a></li>
+<li><a href="#focuses">Focuses</a></li>
+<li><a href="#threads">Threads</a></li>
 <li><a href="#lifecycle-methods">Lifecycle Methods</a></li>
 <li><a href="#best-practices">Best Practices</a></li>
 </ul>
@@ -14,15 +14,16 @@
 <li>Extends the <code>Twist&lt;T&gt;</code> base class</li>
 <li>Declares tool dependencies in the <code>build()</code> method</li>
 <li>Responds to lifecycle events (<code>activate</code>, <code>deactivate</code>, <code>upgrade</code>)</li>
-<li>Can process activities and create new ones</li>
+<li>Can create threads and respond to new notes, links, and thread changes</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-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>
+<p>A twist is installed at the workspace level and owned by a single user. Threads it creates are filed against the owner's focuses, with automatic focus matching when no explicit focus is provided.</p>
+<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">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-2">ThreadAccess</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><span class="hl-2">thread:</span><span class="hl-1"> { </span><span class="hl-2">access:</span><span class="hl-1"> </span><span class="hl-2">ThreadAccess</span><span class="hl-1">.</span><span class="hl-2">Create</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-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><br/><span class="hl-1">    </span><span class="hl-7">// Setup code - runs once when the twist is installed</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 the twist is uninstalled</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>
 <ul>
 <li><strong>Automations</strong> - Automatic task creation, reminders, status updates</li>
-<li><strong>Data Processing</strong> - Analyzing and organizing activities</li>
+<li><strong>Data Processing</strong> - Analyzing and organizing threads</li>
 <li><strong>Notifications</strong> - Sending alerts based on conditions</li>
 </ul>
 <p>For external service integrations (Google Calendar, GitHub, Slack, etc.), build a <strong>Connector</strong> instead. Connectors extend <code>Connector&lt;T&gt;</code> (which itself extends <code>Twist&lt;T&gt;</code>) and provide the OAuth and channel lifecycle needed for syncing external data. See <a href="Building_Connectors.html">Building Connectors</a>.</p>
@@ -30,7 +31,7 @@
 <h2 id="twist-tools" class="tsd-anchor-link">Twist Tools<a href="#twist-tools" 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>Twist tools provide capabilities to twists. They are usually unopinionated and do nothing on their own. Tools encapsulate reusable capabilities and can be composed together.</p>
 <h3 id="types-of-tools" class="tsd-anchor-link">Types of Tools<a href="#types-of-tools" 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="1-built-in-tools" class="tsd-anchor-link">1. Built-in Tools<a href="#1-built-in-tools" 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>Core Plot functionality provided by the Twist Creator:</p>
 <ul>
-<li><strong>Plot</strong> - Create and manage activities and priorities</li>
+<li><strong>Plot</strong> - Create and manage threads, notes, and focuses</li>
 <li><strong>Store</strong> - Persistent key-value storage</li>
 <li><strong>Integrations</strong> - OAuth authentication</li>
 <li><strong>Tasks</strong> - Background task execution</li>
@@ -42,127 +43,97 @@
 <h4 id="2-connectors" class="tsd-anchor-link">2. Connectors<a href="#2-connectors" 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>External service integrations are built as Connectors, which extend <code>Connector&lt;T&gt;</code>. Connectors declare OAuth providers, expose channels for users to enable/disable, and sync data from services like Google Calendar, Slack, GitHub, and more.</p>
 <p>See <a href="Building_Connectors.html">Building Connectors</a> to create your own.</p>
 <h3 id="declaring-tool-dependencies" class="tsd-anchor-link">Declaring Tool Dependencies<a href="#declaring-tool-dependencies" 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 the <code>build()</code> method to declare which tools your twist needs:</p>
-<pre><code class="typescript"><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-2">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><span class="hl-2">store:</span><span class="hl-1"> </span><span class="hl-6">build</span><span class="hl-1">(</span><span class="hl-2">Store</span><span class="hl-1">),</span><br/><span class="hl-1">    </span><span class="hl-2">calendar:</span><span class="hl-1"> </span><span class="hl-6">build</span><span class="hl-1">(</span><span class="hl-2">GoogleCalendar</span><span class="hl-1">, {</span><br/><span class="hl-1">      </span><span class="hl-7">// Tool-specific options</span><br/><span class="hl-1">      </span><span class="hl-2">defaultCalendar:</span><span class="hl-1"> </span><span class="hl-3">&quot;primary&quot;</span><br/><span class="hl-1">    }),</span><br/><span class="hl-1">  };</span><br/><span class="hl-1">}</span>
+<pre><code class="typescript"><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-2">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><span class="hl-2">thread:</span><span class="hl-1"> { </span><span class="hl-2">access:</span><span class="hl-1"> </span><span class="hl-2">ThreadAccess</span><span class="hl-1">.</span><span class="hl-2">Create</span><span class="hl-1"> },</span><br/><span class="hl-1">    }),</span><br/><span class="hl-1">    </span><span class="hl-2">network:</span><span class="hl-1"> </span><span class="hl-6">build</span><span class="hl-1">(</span><span class="hl-2">Network</span><span class="hl-1">, {</span><br/><span class="hl-1">      </span><span class="hl-7">// Tool-specific options</span><br/><span class="hl-1">      </span><span class="hl-2">urls:</span><span class="hl-1"> [</span><span class="hl-3">&quot;https://api.service.com/*&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="accessing-tools" class="tsd-anchor-link">Accessing Tools<a href="#accessing-tools" 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>Access your tools via <code>this.tools</code>:</p>
-<pre><code class="typescript"><span class="hl-2">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-2">Pick</span><span class="hl-1">&lt;</span><span class="hl-2">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">// Tools are fully typed</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;Hello from my twist&quot;</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">activate</span><span class="hl-1">() {</span><br/><span class="hl-1">  </span><span class="hl-7">// Tools are fully typed</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">createThread</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;Hello from my twist&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;The twist is now set up.&quot;</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="direct-access-methods" class="tsd-anchor-link">Direct Access Methods<a href="#direct-access-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></h3><p>Some tool methods are available directly on the Twist class for convenience:</p>
-<pre><code class="typescript"><span class="hl-7">// Store</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">get</span><span class="hl-1">(</span><span class="hl-3">&quot;key&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">set</span><span class="hl-1">(</span><span class="hl-3">&quot;key&quot;</span><span class="hl-1">, </span><span class="hl-2">value</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">clear</span><span class="hl-1">(</span><span class="hl-3">&quot;key&quot;</span><span class="hl-1">);</span><br/><br/><span class="hl-7">// 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-6">runTask</span><span class="hl-1">(</span><span class="hl-2">callback</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">cancelTask</span><span class="hl-1">(</span><span class="hl-2">token</span><span class="hl-1">);</span><br/><br/><span class="hl-7">// Callbacks</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">callback</span><span class="hl-1">(</span><span class="hl-3">&quot;methodName&quot;</span><span class="hl-1">, ...</span><span class="hl-2">args</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">run</span><span class="hl-1">(</span><span class="hl-2">callbackToken</span><span class="hl-1">);</span>
+<pre><code class="typescript"><span class="hl-7">// Store</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">get</span><span class="hl-1">(</span><span class="hl-3">&quot;key&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">set</span><span class="hl-1">(</span><span class="hl-3">&quot;key&quot;</span><span class="hl-1">, </span><span class="hl-2">value</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">clear</span><span class="hl-1">(</span><span class="hl-3">&quot;key&quot;</span><span class="hl-1">);</span><br/><br/><span class="hl-7">// 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-6">runTask</span><span class="hl-1">(</span><span class="hl-2">callback</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">cancelTask</span><span class="hl-1">(</span><span class="hl-2">token</span><span class="hl-1">);</span><br/><br/><span class="hl-7">// Callbacks (pass a method reference, not a string)</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">callback</span><span class="hl-1">(</span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-2">methodName</span><span class="hl-1">, ...</span><span class="hl-2">args</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">run</span><span class="hl-1">(</span><span class="hl-2">callbackToken</span><span class="hl-1">);</span>
 </code><button type="button">Copy</button></pre>
 
 <hr>
-<h2 id="priorities" class="tsd-anchor-link">Priorities<a href="#priorities" 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>Priorities are contexts that organize activities. Think of them like projects or focus areas.</p>
-<h3 id="priority-hierarchy" class="tsd-anchor-link">Priority Hierarchy<a href="#priority-hierarchy" 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>Priorities can be nested to create hierarchies:</p>
-<pre><code><span class="hl-2">Work</span><br/><span class="hl-1">├── </span><span class="hl-2">Project</span><span class="hl-1"> </span><span class="hl-8">A</span><br/><span class="hl-1">│   ├── </span><span class="hl-2">Backend</span><br/><span class="hl-1">│   └── </span><span class="hl-2">Frontend</span><br/><span class="hl-1">└── </span><span class="hl-2">Project</span><span class="hl-1"> </span><span class="hl-8">B</span>
-</code><button>Copy</button></pre>
-
-<h3 id="creating-priorities" class="tsd-anchor-link">Creating Priorities<a href="#creating-priorities" 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">// Top-level priority</span><br/><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">work</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">createPriority</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;Work&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-7">// Nested priority</span><br/><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">projectA</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">createPriority</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;Project A&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-2">parentId:</span><span class="hl-1"> </span><span class="hl-2">work</span><span class="hl-1">.</span><span class="hl-2">id</span><span class="hl-1">,</span><br/><span class="hl-1">});</span>
+<h2 id="focuses" class="tsd-anchor-link">Focuses<a href="#focuses" 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>Focuses are contexts that organize threads. Think of them like projects or areas of life. Focuses are flat — they have no parent and no children. Threads not matched to any focus live in the Inbox.</p>
+<h3 id="creating-focuses" class="tsd-anchor-link">Creating Focuses<a href="#creating-focuses" 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>Creating focuses requires <code>FocusAccess</code> in the Plot tool options. A focus can carry a <code>key</code> (unique per user) so it can be upserted without tracking its UUID:</p>
+<pre><code class="typescript"><span class="hl-0">import</span><span class="hl-1"> { </span><span class="hl-2">FocusAccess</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-6">build</span><span class="hl-1">(</span><span class="hl-2">build</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">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><span class="hl-2">thread:</span><span class="hl-1"> { </span><span class="hl-2">access:</span><span class="hl-1"> </span><span class="hl-2">ThreadAccess</span><span class="hl-1">.</span><span class="hl-2">Create</span><span class="hl-1"> },</span><br/><span class="hl-1">      </span><span class="hl-2">focus:</span><span class="hl-1"> { </span><span class="hl-2">access:</span><span class="hl-1"> </span><span class="hl-2">FocusAccess</span><span class="hl-1">.</span><span class="hl-2">Create</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">// Create (or upsert by key) a focus</span><br/><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">work</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">createFocus</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;Work&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-2">key:</span><span class="hl-1"> </span><span class="hl-3">&quot;work&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">});</span>
 </code><button type="button">Copy</button></pre>
 
-<h3 id="twist-activation" class="tsd-anchor-link">Twist Activation<a href="#twist-activation" 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>Twists are activated within a specific priority. When activated, the twist has access to that priority and all its children.</p>
-<pre><code class="typescript"><span class="hl-2">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-2">Pick</span><span class="hl-1">&lt;</span><span class="hl-2">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">// This twist is now active for this priority</span><br/><span class="hl-1">  </span><span class="hl-7">// It can create activities, set up webhooks, etc.</span><br/><span class="hl-1">}</span>
+<h3 id="automatic-focus-matching" class="tsd-anchor-link">Automatic Focus Matching<a href="#automatic-focus-matching" 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 a twist creates a thread without specifying a <code>focus</code>, the server classifies the thread into one of the owner's focuses automatically. Provide an explicit <code>focus: { id }</code> only when you want to override that routing:</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">createThread</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;Quarterly planning&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-2">focus:</span><span class="hl-1"> { </span><span class="hl-2">id:</span><span class="hl-1"> </span><span class="hl-2">work</span><span class="hl-1">.</span><span class="hl-2">id</span><span class="hl-1"> }, </span><span class="hl-7">// Optional - omit to let Plot classify it</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;Kick off Q3 planning.&quot;</span><span class="hl-1"> }],</span><br/><span class="hl-1">});</span>
 </code><button type="button">Copy</button></pre>
 
 <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 - 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">done:</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-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>
+<h2 id="threads" class="tsd-anchor-link">Threads<a href="#threads" 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>Threads are the core data type in Plot, representing tasks, events, and conversations.</p>
+<p><strong>Think of a Thread as a thread</strong> on a messaging platform, and <strong>Notes as the messages in that thread</strong>. A Thread represents something done or to be done, while Notes represent the updates and details on that thread. Always create threads with an initial note, and add notes for updates rather than creating new threads.</p>
+<h3 id="thread-types" class="tsd-anchor-link">Thread Types<a href="#thread-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><p>A thread's <code>type</code> is a sub-type/category that determines its icon. Available types depend on whether the focus is shared:</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>
+<li><strong>Private focuses</strong>: <code>&quot;action&quot;</code> (tasks), <code>&quot;notes&quot;</code> (default), <code>&quot;idea&quot;</code>, <code>&quot;goal&quot;</code>, <code>&quot;decision&quot;</code></li>
+<li><strong>Shared focuses</strong>: all of the above plus <code>&quot;discussion&quot;</code> (default), <code>&quot;announcement&quot;</code>, <code>&quot;ask&quot;</code></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>
+<pre><code class="typescript"><span class="hl-7">// Notes - Information without actionable requirements (default)</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">createThread</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">// Action - 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">createThread</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-3">&quot;action&quot;</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">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">// Scheduled event - a thread with a schedule</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">createThread</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">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><span class="hl-2">schedules:</span><span class="hl-1"> [</span><br/><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><br/><span class="hl-1">  ],</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, Action, 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">source</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">// Canonical URL for external item (enables automatic upserts)</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">done</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">// Action 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>
+<h3 id="thread-properties" class="tsd-anchor-link">Thread Properties<a href="#thread-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">Thread</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">Uuid</span><span class="hl-1">; </span><span class="hl-7">// Unique identifier</span><br/><span class="hl-1">  </span><span class="hl-2">created</span><span class="hl-1">: </span><span class="hl-5">Date</span><span class="hl-1">; </span><span class="hl-7">// When the thread was created</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-7">// Display title</span><br/><span class="hl-1">  </span><span class="hl-2">focus</span><span class="hl-1">: </span><span class="hl-5">Focus</span><span class="hl-1">; </span><span class="hl-7">// The focus this thread belongs to</span><br/><span class="hl-1">  </span><span class="hl-2">type</span><span class="hl-1">: </span><span class="hl-5">ThreadType</span><span class="hl-1"> | </span><span class="hl-5">null</span><span class="hl-1">; </span><span class="hl-7">// Sub-type/category, determines the icon</span><br/><span class="hl-1">  </span><span class="hl-2">archived</span><span class="hl-1">: </span><span class="hl-5">boolean</span><span class="hl-1">; </span><span class="hl-7">// Whether the thread has been archived</span><br/><span class="hl-1">  </span><span class="hl-2">access</span><span class="hl-1">: </span><span class="hl-5">ThreadAccessLevel</span><span class="hl-1">; </span><span class="hl-7">// &quot;public&quot;, &quot;members&quot;, or &quot;private&quot;</span><br/><span class="hl-1">  </span><span class="hl-2">tags</span><span class="hl-1">: </span><span class="hl-5">Tags</span><span class="hl-1">; </span><span class="hl-7">// Tag assignments (tag -&gt; actors who added it)</span><br/><span class="hl-1">  </span><span class="hl-2">reactions</span><span class="hl-1">: </span><span class="hl-5">Reactions</span><span class="hl-1">; </span><span class="hl-7">// Emoji reactions (emoji -&gt; actors who reacted)</span><br/><span class="hl-1">  </span><span class="hl-2">schedule</span><span class="hl-1">?: </span><span class="hl-5">Schedule</span><span class="hl-1">; </span><span class="hl-7">// The schedule associated with this thread, if any</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>
 
 <p><strong>Key Properties:</strong></p>
 <ul>
-<li><strong><code>source</code></strong>: Canonical URL or stable identifier for items from external systems. When set, it uniquely identifies the activity within a priority tree and enables automatic deduplication. See <a href="../media/SYNC_STRATEGIES.md">Sync Strategies</a>.</li>
-<li><strong><code>type</code></strong>: Determines how the activity is displayed and interacted with (Note, Action with <code>done</code>, Event with <code>start</code>/<code>end</code>)</li>
 <li><strong><code>title</code></strong>: Short summary that may be truncated in the UI - detailed content should go in Notes</li>
+<li><strong><code>type</code></strong>: Determines how the thread is displayed (icon and category)</li>
+<li><strong><code>focus</code></strong>: The focus the thread is filed in - assigned automatically unless you provide one</li>
 </ul>
-<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>
-<p><strong>Data Sync:</strong> When syncing from external systems, use <code>Activity.source</code> and <code>Note.key</code> for automatic upserts. See <a href="../media/SYNC_STRATEGIES.md">Sync Strategies</a>.</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">source:</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><span class="hl-7">// Enables automatic deduplication</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">notes:</span><span class="hl-1"> [</span><br/><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">source:</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><span class="hl-2">key:</span><span class="hl-1"> </span><span class="hl-3">&quot;description&quot;</span><span class="hl-1">, </span><span class="hl-7">// Using key enables upserts</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>
+<h3 id="thread-notes" class="tsd-anchor-link">Thread Notes<a href="#thread-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>Threads can have multiple Notes attached to them, like messages in a thread. Notes contain detailed content and interactive actions.</p>
+<p><strong>Data Sync:</strong> When syncing from external systems, connectors use <code>Link.sources</code> and <code>Note.key</code> for automatic upserts. See <a href="SYNC_STRATEGIES.html">Sync Strategies</a>.</p>
+<pre><code class="typescript"><span class="hl-0">import</span><span class="hl-1"> { </span><span class="hl-2">ActionType</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">createThread</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-3">&quot;action&quot;</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">notes:</span><span class="hl-1"> [</span><br/><span class="hl-1">    {</span><br/><span class="hl-1">      </span><span class="hl-2">key:</span><span class="hl-1"> </span><span class="hl-3">&quot;description&quot;</span><span class="hl-1">, </span><span class="hl-7">// Using key enables upserts</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">actions:</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">ActionType</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">ActionType</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">actionCallback</span><span class="hl-1">(</span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-2">markAsFixed</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>
+<p><strong>Action Types:</strong></p>
 <ul>
 <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>
+<li><strong>file</strong> / <strong>fileRef</strong> - File attachments (stored in Plot or referenced from a connector's source system)</li>
+<li><strong>thread</strong> - Navigates to a related thread</li>
+<li><strong>plan</strong> - Structured plan of operations for user approval</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>
+<h3 id="best-practices-for-threads-and-notes" class="tsd-anchor-link">Best Practices for Threads and Notes<a href="#best-practices-for-threads-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-threads-with-an-initial-note" class="tsd-anchor-link">Always Create Threads with an Initial Note<a href="#always-create-threads-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, a Thread should be created with at least one initial Note.</strong> The Thread's <code>title</code> is just a short summary that may be truncated in the UI. Detailed information, context, and actions 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">source:</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><span class="hl-7">// Enables automatic deduplication</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">notes:</span><span class="hl-1"> [</span><br/><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">source:</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><span class="hl-2">key:</span><span class="hl-1"> </span><span class="hl-3">&quot;description&quot;</span><span class="hl-1">, </span><span class="hl-7">// Using key enables upserts</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>
+<pre><code class="typescript"><span class="hl-7">// ✅ GOOD - Thread 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">createThread</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-3">&quot;action&quot;</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">notes:</span><span class="hl-1"> [</span><br/><span class="hl-1">    {</span><br/><span class="hl-1">      </span><span class="hl-2">key:</span><span class="hl-1"> </span><span class="hl-3">&quot;description&quot;</span><span class="hl-1">, </span><span class="hl-7">// Using key enables upserts</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">actions:</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">ActionType</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">createThread</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-3">&quot;action&quot;</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 actions</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><strong>Why?</strong> Just as you wouldn't create a messaging thread without a first message, Threads need Notes to provide meaningful context and detail.</p>
+<h4 id="add-notes-to-existing-threads-for-related-content" class="tsd-anchor-link">Add Notes to Existing Threads for Related Content<a href="#add-notes-to-existing-threads-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 Thread rather than creating a new Thread.</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>Email threads</strong> - All messages in a thread as Notes on one Thread</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 using source/key pattern (no lookup needed)</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">// Simply create - Plot handles deduplication automatically</span><br/><span class="hl-1">  </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">threadSource</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/><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">source:</span><span class="hl-1"> </span><span class="hl-2">threadSource</span><span class="hl-1"> }, </span><span class="hl-7">// References activity by source</span><br/><span class="hl-1">    </span><span class="hl-2">key:</span><span class="hl-1"> </span><span class="hl-3">`message-</span><span class="hl-4">${</span><span class="hl-2">message</span><span class="hl-13">.</span><span class="hl-2">id</span><span class="hl-4">}</span><span class="hl-3">`</span><span class="hl-1">, </span><span class="hl-7">// Unique key per message for upserts</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/><br/><span class="hl-1">  </span><span class="hl-7">// If thread doesn&#39;t exist yet, create it first</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">source:</span><span class="hl-1"> </span><span class="hl-2">threadSource</span><span class="hl-1">, </span><span class="hl-7">// Same source for deduplication</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">notes:</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">source:</span><span class="hl-1"> </span><span class="hl-2">threadSource</span><span class="hl-1"> },</span><br/><span class="hl-1">      </span><span class="hl-2">key:</span><span class="hl-1"> </span><span class="hl-3">`message-</span><span class="hl-4">${</span><span class="hl-2">message</span><span class="hl-13">.</span><span class="hl-2">id</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">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/><br/><span class="hl-7">// Alternative: Check existence first (for advanced cases)</span><br/><span class="hl-2">async</span><span class="hl-1"> </span><span class="hl-6">onNewMessageAdvanced</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-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">threadId</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-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-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">meta:</span><span class="hl-1"> { </span><span class="hl-2">threadId</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><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>
+<pre><code class="typescript"><span class="hl-7">// ✅ GOOD - Track the thread ID and add replies as Notes</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">conversationId</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-4">let</span><span class="hl-1"> </span><span class="hl-2">threadId</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">Uuid</span><span class="hl-1">&gt;(</span><span class="hl-3">`thread_</span><span class="hl-4">${</span><span class="hl-2">conversationId</span><span class="hl-4">}</span><span class="hl-3">`</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">threadId</span><span class="hl-1">) {</span><br/><span class="hl-1">    </span><span class="hl-7">// First message - create the thread with the message as its initial note</span><br/><span class="hl-1">    </span><span class="hl-2">threadId</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">createThread</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">notes:</span><span class="hl-1"> [</span><br/><span class="hl-1">        {</span><br/><span class="hl-1">          </span><span class="hl-2">key:</span><span class="hl-1"> </span><span class="hl-3">`message-</span><span class="hl-4">${</span><span class="hl-2">message</span><span class="hl-13">.</span><span class="hl-2">id</span><span class="hl-4">}</span><span class="hl-3">`</span><span class="hl-1">, </span><span class="hl-7">// Unique key per message for upserts</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><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">`thread_</span><span class="hl-4">${</span><span class="hl-2">conversationId</span><span class="hl-4">}</span><span class="hl-3">`</span><span class="hl-1">, </span><span class="hl-2">threadId</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><br/><br/><span class="hl-1">  </span><span class="hl-7">// Follow-up message - add 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">thread:</span><span class="hl-1"> { </span><span class="hl-2">id:</span><span class="hl-1"> </span><span class="hl-2">threadId</span><span class="hl-1"> },</span><br/><span class="hl-1">    </span><span class="hl-2">key:</span><span class="hl-1"> </span><span class="hl-3">`message-</span><span class="hl-4">${</span><span class="hl-2">message</span><span class="hl-13">.</span><span class="hl-2">id</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">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/><br/><span class="hl-7">// ❌ BAD - Creating separate Thread 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">conversationId</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 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">createThread</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>See <a href="../media/SYNC_STRATEGIES.md">Sync Strategies</a> for more details on choosing the right pattern.</p>
-<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>
+<p><strong>For connectors:</strong> When syncing from an external service, there's no need to store thread IDs — save links with <code>integrations.saveLink()</code> using <code>Link.sources</code> for deduplication, and reference the thread by source (<code>thread: { source: ... }</code>) when creating notes.</p>
+<p>See <a href="SYNC_STRATEGIES.html">Sync Strategies</a> for more details on choosing the right pattern.</p>
+<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 Thread with 20 Notes, not 20 separate Threads.</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>
+<h3 id="activate" class="tsd-anchor-link">activate()<a href="#activate" 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 installed by a user. When it runs, <code>this.userId</code> is already populated with the installing user's ID.</p>
 <p><strong>Use for:</strong></p>
 <ul>
-<li>Creating initial activities</li>
+<li>Creating initial threads</li>
 <li>Setting up webhooks</li>
 <li>Initializing state</li>
-<li>Requesting authentication</li>
 </ul>
-<pre><code class="typescript"><span class="hl-2">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-2">Pick</span><span class="hl-1">&lt;</span><span class="hl-2">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">// Create welcome 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-3">&quot;Calendar sync is now active&quot;</span><br/><span class="hl-1">  });</span><br/><br/><span class="hl-1">  </span><span class="hl-7">// Set up webhook</span><br/><span class="hl-1">  </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">webhookUrl</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">network</span><span class="hl-1">.</span><span class="hl-6">createWebhook</span><span class="hl-1">(</span><span class="hl-3">&quot;onUpdate&quot;</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">set</span><span class="hl-1">(</span><span class="hl-3">&quot;webhook_url&quot;</span><span class="hl-1">, </span><span class="hl-2">webhookUrl</span><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">activate</span><span class="hl-1">() {</span><br/><span class="hl-1">  </span><span class="hl-7">// Create welcome 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">createThread</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;Calendar sync 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><span class="hl-2">content:</span><span class="hl-1"> </span><span class="hl-3">&quot;Events will appear as they sync.&quot;</span><span class="hl-1"> }],</span><br/><span class="hl-1">  });</span><br/><br/><span class="hl-1">  </span><span class="hl-7">// Set up webhook</span><br/><span class="hl-1">  </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">webhookUrl</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">network</span><span class="hl-1">.</span><span class="hl-6">createWebhook</span><span class="hl-1">({}, </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-2">onUpdate</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">set</span><span class="hl-1">(</span><span class="hl-3">&quot;webhook_url&quot;</span><span class="hl-1">, </span><span class="hl-2">webhookUrl</span><span class="hl-1">);</span><br/><span class="hl-1">}</span>
 </code><button type="button">Copy</button></pre>
 
-<h3 id="upgrade" class="tsd-anchor-link">upgrade()<a href="#upgrade" 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 a new version of your twist is deployed to an existing priority.</p>
+<h3 id="upgrade" class="tsd-anchor-link">upgrade()<a href="#upgrade" 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 a new version of your twist is deployed to existing installations.</p>
 <p><strong>Use for:</strong></p>
 <ul>
 <li>Migrating data structures</li>
@@ -186,14 +157,14 @@
 </code><button type="button">Copy</button></pre>
 
 <p><strong>For Breaking Changes:</strong> Recreate callbacks in <code>upgrade()</code>:</p>
-<pre><code class="typescript"><span class="hl-2">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-4">const</span><span class="hl-1"> </span><span class="hl-8">version</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;version&quot;</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">version</span><span class="hl-1"> === </span><span class="hl-3">&quot;1.0.0&quot;</span><span class="hl-1">) {</span><br/><span class="hl-1">    </span><span class="hl-7">// Recreate callbacks with new signature</span><br/><span class="hl-1">    </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">syncs</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">SyncState</span><span class="hl-1">[]&gt;(</span><span class="hl-3">&quot;active_syncs&quot;</span><span class="hl-1">);</span><br/><span class="hl-1">    </span><span class="hl-0">for</span><span class="hl-1"> (</span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">sync</span><span class="hl-1"> </span><span class="hl-4">of</span><span class="hl-1"> </span><span class="hl-2">syncs</span><span class="hl-1">) {</span><br/><span class="hl-1">      </span><span class="hl-7">// Delete old callback</span><br/><span class="hl-1">      </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">oldCallback</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">`sync_</span><span class="hl-4">${</span><span class="hl-2">sync</span><span class="hl-13">.</span><span class="hl-2">id</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-0">if</span><span class="hl-1"> (</span><span class="hl-2">oldCallback</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">deleteCallback</span><span class="hl-1">(</span><span class="hl-2">oldCallback</span><span class="hl-1">);</span><br/><br/><span class="hl-1">      </span><span class="hl-7">// Create new callback with updated signature</span><br/><span class="hl-1">      </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">newCallback</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;syncBatchV2&quot;</span><span class="hl-1">, </span><span class="hl-2">sync</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-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">`sync_</span><span class="hl-4">${</span><span class="hl-2">sync</span><span class="hl-13">.</span><span class="hl-2">id</span><span class="hl-4">}</span><span class="hl-3">`</span><span class="hl-1">, </span><span class="hl-2">newCallback</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-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;version&quot;</span><span class="hl-1">, </span><span class="hl-3">&quot;2.0.0&quot;</span><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">upgrade</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">version</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;version&quot;</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">version</span><span class="hl-1"> === </span><span class="hl-3">&quot;1.0.0&quot;</span><span class="hl-1">) {</span><br/><span class="hl-1">    </span><span class="hl-7">// Recreate callbacks with new signature</span><br/><span class="hl-1">    </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">syncs</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">SyncState</span><span class="hl-1">[]&gt;(</span><span class="hl-3">&quot;active_syncs&quot;</span><span class="hl-1">);</span><br/><span class="hl-1">    </span><span class="hl-0">for</span><span class="hl-1"> (</span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">sync</span><span class="hl-1"> </span><span class="hl-4">of</span><span class="hl-1"> </span><span class="hl-2">syncs</span><span class="hl-1">) {</span><br/><span class="hl-1">      </span><span class="hl-7">// Delete old callback</span><br/><span class="hl-1">      </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">oldCallback</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">Callback</span><span class="hl-1">&gt;(</span><span class="hl-3">`sync_</span><span class="hl-4">${</span><span class="hl-2">sync</span><span class="hl-13">.</span><span class="hl-2">id</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-0">if</span><span class="hl-1"> (</span><span class="hl-2">oldCallback</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">deleteCallback</span><span class="hl-1">(</span><span class="hl-2">oldCallback</span><span class="hl-1">);</span><br/><br/><span class="hl-1">      </span><span class="hl-7">// Create new callback with updated signature</span><br/><span class="hl-1">      </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">newCallback</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-4">this</span><span class="hl-1">.</span><span class="hl-2">syncBatchV2</span><span class="hl-1">, </span><span class="hl-2">sync</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-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">`sync_</span><span class="hl-4">${</span><span class="hl-2">sync</span><span class="hl-13">.</span><span class="hl-2">id</span><span class="hl-4">}</span><span class="hl-3">`</span><span class="hl-1">, </span><span class="hl-2">newCallback</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-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;version&quot;</span><span class="hl-1">, </span><span class="hl-3">&quot;2.0.0&quot;</span><span class="hl-1">);</span><br/><span class="hl-1">}</span>
 </code><button type="button">Copy</button></pre>
 
 <p>Alternatively, keep the old function temporarily while callbacks complete:</p>
 <pre><code class="typescript"><span class="hl-7">// Keep old signature for in-flight callbacks</span><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">batchNumber</span><span class="hl-1">: </span><span class="hl-2">number</span><span class="hl-1">, </span><span class="hl-2">authToken</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">// Delegate to new implementation</span><br/><span class="hl-1">  </span><span class="hl-0">return</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">syncBatchV2</span><span class="hl-1">({ </span><span class="hl-2">batchNumber</span><span class="hl-1">, </span><span class="hl-2">authToken</span><span class="hl-1"> });</span><br/><span class="hl-1">}</span><br/><br/><span class="hl-7">// New signature for new callbacks</span><br/><span class="hl-2">async</span><span class="hl-1"> </span><span class="hl-6">syncBatchV2</span><span class="hl-1">(</span><span class="hl-2">options</span><span class="hl-1">: </span><span class="hl-2">SyncOptions</span><span class="hl-1">) {</span><br/><span class="hl-1">  </span><span class="hl-7">// New implementation</span><br/><span class="hl-1">}</span>
 </code><button type="button">Copy</button></pre>
 
-<h3 id="deactivate" class="tsd-anchor-link">deactivate()<a href="#deactivate" 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 removed from a priority.</p>
+<h3 id="deactivate" class="tsd-anchor-link">deactivate()<a href="#deactivate" 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 uninstalled.</p>
 <p><strong>Use for:</strong></p>
 <ul>
 <li>Removing webhooks</li>
@@ -209,11 +180,11 @@
 </code><button type="button">Copy</button></pre>
 
 <h3 id="2-error-handling" class="tsd-anchor-link">2. Error Handling<a href="#2-error-handling" 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 handle errors gracefully:</p>
-<pre><code class="typescript"><span class="hl-2">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-2">Pick</span><span class="hl-1">&lt;</span><span class="hl-2">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">try</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-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;Twist activated&quot;</span><br/><span class="hl-1">    });</span><br/><span class="hl-1">  } </span><span class="hl-0">catch</span><span class="hl-1"> (</span><span class="hl-2">error</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">error</span><span class="hl-1">(</span><span class="hl-3">&quot;Failed to create activity:&quot;</span><span class="hl-1">, </span><span class="hl-2">error</span><span class="hl-1">);</span><br/><span class="hl-1">    </span><span class="hl-7">// Twist activation continues even if this fails</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">activate</span><span class="hl-1">() {</span><br/><span class="hl-1">  </span><span class="hl-0">try</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-2">tools</span><span class="hl-1">.</span><span class="hl-2">plot</span><span class="hl-1">.</span><span class="hl-6">createThread</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;Twist activated&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;Setup is complete.&quot;</span><span class="hl-1"> }],</span><br/><span class="hl-1">    });</span><br/><span class="hl-1">  } </span><span class="hl-0">catch</span><span class="hl-1"> (</span><span class="hl-2">error</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">error</span><span class="hl-1">(</span><span class="hl-3">&quot;Failed to create thread:&quot;</span><span class="hl-1">, </span><span class="hl-2">error</span><span class="hl-1">);</span><br/><span class="hl-1">    </span><span class="hl-7">// Twist activation continues even if this fails</span><br/><span class="hl-1">  }</span><br/><span class="hl-1">}</span>
 </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-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>
+<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-4">this</span><span class="hl-1">.</span><span class="hl-2">syncBatch</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">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-4">this</span><span class="hl-1">.</span><span class="hl-6">processPage</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-4">this</span><span class="hl-1">.</span><span class="hl-2">syncBatch</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/><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>
@@ -222,11 +193,11 @@
 </code><button type="button">Copy</button></pre>
 
 <h3 id="5-tool-composition" class="tsd-anchor-link">5. Tool Composition<a href="#5-tool-composition" 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 complex functionality by composing tools:</p>
-<pre><code class="typescript"><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-2">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><span class="hl-2">network:</span><span class="hl-1"> </span><span class="hl-6">build</span><span class="hl-1">(</span><span class="hl-2">Network</span><span class="hl-1">, {</span><br/><span class="hl-1">      </span><span class="hl-2">urls:</span><span class="hl-1"> [</span><span class="hl-3">&quot;https://api.service.com/*&quot;</span><span class="hl-1">]</span><br/><span class="hl-1">    }),</span><br/><span class="hl-1">    </span><span class="hl-2">auth:</span><span class="hl-1"> </span><span class="hl-6">build</span><span class="hl-1">(</span><span class="hl-2">Integrations</span><span class="hl-1">),</span><br/><span class="hl-1">    </span><span class="hl-2">ai:</span><span class="hl-1"> </span><span class="hl-6">build</span><span class="hl-1">(</span><span class="hl-8">AI</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-6">build</span><span class="hl-1">(</span><span class="hl-2">build</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">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><span class="hl-2">thread:</span><span class="hl-1"> { </span><span class="hl-2">access:</span><span class="hl-1"> </span><span class="hl-2">ThreadAccess</span><span class="hl-1">.</span><span class="hl-2">Create</span><span class="hl-1"> },</span><br/><span class="hl-1">    }),</span><br/><span class="hl-1">    </span><span class="hl-2">network:</span><span class="hl-1"> </span><span class="hl-6">build</span><span class="hl-1">(</span><span class="hl-2">Network</span><span class="hl-1">, {</span><br/><span class="hl-1">      </span><span class="hl-2">urls:</span><span class="hl-1"> [</span><span class="hl-3">&quot;https://api.service.com/*&quot;</span><span class="hl-1">]</span><br/><span class="hl-1">    }),</span><br/><span class="hl-1">    </span><span class="hl-2">integrations:</span><span class="hl-1"> </span><span class="hl-6">build</span><span class="hl-1">(</span><span class="hl-2">Integrations</span><span class="hl-1">),</span><br/><span class="hl-1">    </span><span class="hl-2">ai:</span><span class="hl-1"> </span><span class="hl-6">build</span><span class="hl-1">(</span><span class="hl-8">AI</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="6-clear-activity-titles" class="tsd-anchor-link">6. Clear Activity Titles<a href="#6-clear-activity-titles" 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>Make activity titles clear and actionable:</p>
-<pre><code class="typescript"><span class="hl-7">// ❌ Vague</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;Thing&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-7">// ✅ Clear</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 #123 for authentication fix&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">});</span>
+<h3 id="6-clear-thread-titles" class="tsd-anchor-link">6. Clear Thread Titles<a href="#6-clear-thread-titles" 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>Make thread titles clear and actionable:</p>
+<pre><code class="typescript"><span class="hl-7">// ❌ Vague</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">createThread</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-3">&quot;action&quot;</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;Thing&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-7">// ✅ Clear</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">createThread</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-3">&quot;action&quot;</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 #123 for authentication fix&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">});</span>
 </code><button type="button">Copy</button></pre>
 
 <hr>
@@ -235,4 +206,4 @@
 <li><strong><a href="Building_Connectors.html">Building Connectors</a></strong> - Build external service integrations</li>
 <li><strong><a href="Runtime_Environment.html">Runtime Environment</a></strong> - Understand execution constraints</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-connectors"><span>2. <wbr/>Connectors</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><ul><li><a href="#callback-versioning-during-upgrades"><span>Callback <wbr/>Versioning <wbr/>During <wbr/>Upgrades</span></a></li></ul></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-connectors"><span>2. <wbr/>Connectors</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="#focuses"><span>Focuses</span></a></li><li><ul><li><a href="#creating-focuses"><span>Creating <wbr/>Focuses</span></a></li><li><a href="#automatic-focus-matching"><span>Automatic <wbr/>Focus <wbr/>Matching</span></a></li></ul></li><li><a href="#threads"><span>Threads</span></a></li><li><ul><li><a href="#thread-types"><span>Thread <wbr/>Types</span></a></li><li><a href="#thread-properties"><span>Thread <wbr/>Properties</span></a></li><li><a href="#thread-notes"><span>Thread <wbr/>Notes</span></a></li><li><a href="#best-practices-for-threads-and-notes"><span>Best <wbr/>Practices for <wbr/>Threads and <wbr/>Notes</span></a></li><li><ul><li><a href="#always-create-threads-with-an-initial-note"><span>Always <wbr/>Create <wbr/>Threads with an <wbr/>Initial <wbr/>Note</span></a></li><li><a href="#add-notes-to-existing-threads-for-related-content"><span>Add <wbr/>Notes to <wbr/>Existing <wbr/>Threads 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="#activate"><span>activate()</span></a></li><li><a href="#upgrade"><span>upgrade()</span></a></li><li><ul><li><a href="#callback-versioning-during-upgrades"><span>Callback <wbr/>Versioning <wbr/>During <wbr/>Upgrades</span></a></li></ul></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-thread-titles"><span>6. <wbr/>Clear <wbr/>Thread <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>