@plotday/twister 0.34.0 → 0.36.0

package/dist/llm-docs/common/messaging.js

@@ -4,5 +4,5 @@
  * This file is auto-generated during build. Do not edit manually.
  * Generated from: prebuild.ts
  */
-export default "import type { ActivityLink, NewActivityWithNotes, Serializable } from \"../index\";\n\n/**\n * Represents a successful messaging service authorization.\n *\n * Returned by messaging tools when authorization completes successfully.\n * The auth token is an opaque identifier that can be used for subsequent\n * messaging operations.\n */\nexport type MessagingAuth = {\n  /** Opaque token for messaging operations */\n  authToken: string;\n};\n\n/**\n * Represents a channel from an external messaging service.\n *\n * Contains metadata about a specific channel that can be synced\n * with Plot.\n */\nexport type MessageChannel = {\n  /** Unique identifier for the channel within the provider */\n  id: string;\n  /** Human-readable name of the channel (e.g., \"Inbox\", \"#general\", \"My Team Thread\") */\n  name: string;\n  /** Optional description or additional details about the channel */\n  description: string | null;\n  /** Whether this is the user's primary/default channel (e.g. email inbox) */\n  primary: boolean;\n};\n\n/**\n * Configuration options for messaging synchronization.\n *\n * Controls the time range and other parameters for messaging sync operations.\n * Used to limit sync scope and optimize performance.\n */\nexport type MessageSyncOptions = {\n  /** Earliest date to sync events from (inclusive) */\n  timeMin?: Date;\n};\n\n/**\n * Base interface for email and chat integration tools.\n *\n * All synced messages/emails are converted to ActivityWithNotes objects.\n * Each email thread or chat conversation becomes an Activity with Notes for each message.\n *\n * **Recommended Data Sync Strategy:**\n * Use Activity.source (thread URL or ID) and Note.key (message ID) for automatic upserts.\n * See SYNC_STRATEGIES.md for detailed patterns.\n */\nexport type MessagingTool = {\n  /**\n   * Initiates the authorization flow for the service.\n   *\n   * @param callback - Function receiving (auth, ...extraArgs) when auth completes\n   * @param extraArgs - Additional arguments to pass to the callback (type-checked)\n   * @returns Promise resolving to an ActivityLink to initiate the auth flow\n   */\n  requestAuth<\n    TArgs extends Serializable[],\n    TCallback extends (auth: MessagingAuth, ...args: TArgs) => any\n  >(\n    callback: TCallback,\n    ...extraArgs: TArgs\n  ): Promise<ActivityLink>;\n\n  /**\n   * Retrieves the list of conversation channels (inboxes, channels) accessible to the user.\n   *\n   * @param authToken - Authorization token from successful auth flow\n   * @returns Promise resolving to array of available conversation channels\n   */\n  getChannels(authToken: string): Promise<MessageChannel[]>;\n\n  /**\n   * Begins synchronizing messages from a specific channel.\n   *\n   * Email threads and chat conversations are converted to NewActivityWithNotes objects.\n   *\n   * **Recommended Implementation** (Strategy 2 - Upsert via Source/Key):\n   * - Set Activity.source to the thread/conversation URL or stable ID (e.g., \"slack:{channelId}:{threadTs}\")\n   * - Use Note.key for individual messages (e.g., \"message-{messageId}\")\n   * - Each message becomes a separate note with unique key for upserts\n   * - No manual ID tracking needed - Plot handles deduplication automatically\n   * - Send NewActivityWithNotes for all threads (creates new or updates existing)\n   * - Set activity.unread = false for initial sync, omit for incremental updates\n   *\n   * **Alternative** (Strategy 3 - Advanced cases):\n   * - Use Uuid.Generate() and store ID mappings when creating multiple activities per thread\n   * - See SYNC_STRATEGIES.md for when this is appropriate\n   *\n   * @param options - Sync configuration options\n   * @param options.authToken - Authorization token for access\n   * @param options.channelId - ID of the channel (e.g., channel, inbox) to sync\n   * @param options.timeMin - Earliest date to sync events from (inclusive)\n   * @param callback - Function receiving (thread, ...extraArgs) for each synced conversation\n   * @param extraArgs - Additional arguments to pass to the callback (type-checked, no functions allowed)\n   * @returns Promise that resolves when sync setup is complete\n   */\n  startSync<\n    TArgs extends Serializable[],\n    TCallback extends (thread: NewActivityWithNotes, ...args: TArgs) => any\n  >(\n    options: {\n      authToken: string;\n      channelId: string;\n    } & MessageSyncOptions,\n    callback: TCallback,\n    ...extraArgs: TArgs\n  ): Promise<void>;\n\n  /**\n   * Stops synchronizing messages from a specific channel.\n   *\n   * @param authToken - Authorization token for access\n   * @param channelId - ID of the channel to stop syncing\n   * @returns Promise that resolves when sync is stopped\n   */\n  stopSync(authToken: string, channelId: string): Promise<void>;\n};\n";
+export default "import type { NewActivityWithNotes, Serializable } from \"../index\";\n\n/**\n * Represents a channel from an external messaging service.\n *\n * Contains metadata about a specific channel that can be synced\n * with Plot. Different messaging providers may have additional\n * provider-specific properties.\n */\nexport type MessageChannel = {\n  /** Unique identifier for the channel within the provider */\n  id: string;\n  /** Human-readable name of the channel (e.g., \"Inbox\", \"#general\", \"My Team Thread\") */\n  name: string;\n  /** Optional description or additional details about the channel */\n  description: string | null;\n  /** Whether this is the user's primary/default channel (e.g. email inbox) */\n  primary: boolean;\n};\n\n/**\n * Configuration options for messaging synchronization.\n *\n * Controls the time range and other parameters for messaging sync operations.\n * Used to limit sync scope and optimize performance.\n */\nexport type MessageSyncOptions = {\n  /** Earliest date to sync events from (inclusive) */\n  timeMin?: Date;\n};\n\n/**\n * Base interface for email and chat integration tools.\n *\n * All synced messages/emails are converted to ActivityWithNotes objects.\n * Each email thread or chat conversation becomes an Activity with Notes for each message.\n *\n * **Architecture: Tools Build, Twists Save**\n *\n * Messaging tools follow Plot's core architectural principle:\n * - **Tools**: Fetch external data and transform it into Plot format (NewActivity objects)\n * - **Twists**: Receive the data and decide what to do with it (create, update, filter, etc.)\n *\n * **Implementation Pattern:**\n * 1. Authorization is handled via the twist edit modal (Integrations provider config)\n * 2. Tool declares providers and lifecycle callbacks in build()\n * 3. onAuthorized lists available channels and calls setSyncables()\n * 4. User enables channels in the modal → onSyncEnabled fires\n * 5. **Tool builds NewActivity objects** and passes them to the twist via callback\n * 6. **Twist decides** whether to save using createActivity/updateActivity\n *\n * **Recommended Data Sync Strategy:**\n * Use Activity.source (thread URL or ID) and Note.key (message ID) for automatic upserts.\n * See SYNC_STRATEGIES.md for detailed patterns.\n */\nexport type MessagingTool = {\n  /**\n   * Retrieves the list of conversation channels (inboxes, channels) accessible to the user.\n   *\n   * @param channelId - A channel ID to use for auth lookup\n   * @returns Promise resolving to array of available conversation channels\n   */\n  getChannels(channelId: string): Promise<MessageChannel[]>;\n\n  /**\n   * Begins synchronizing messages from a specific channel.\n   *\n   * Auth is obtained automatically via integrations.get(provider, channelId).\n   *\n   * @param options - Sync configuration options\n   * @param options.channelId - ID of the channel (e.g., channel, inbox) to sync\n   * @param options.timeMin - Earliest date to sync events from (inclusive)\n   * @param callback - Function receiving (thread, ...extraArgs) for each synced conversation\n   * @param extraArgs - Additional arguments to pass to the callback (type-checked, no functions allowed)\n   * @returns Promise that resolves when sync setup is complete\n   */\n  startSync<\n    TArgs extends Serializable[],\n    TCallback extends (thread: NewActivityWithNotes, ...args: TArgs) => any\n  >(\n    options: {\n      channelId: string;\n    } & MessageSyncOptions,\n    callback: TCallback,\n    ...extraArgs: TArgs\n  ): Promise<void>;\n\n  /**\n   * Stops synchronizing messages from a specific channel.\n   *\n   * @param channelId - ID of the channel to stop syncing\n   * @returns Promise that resolves when sync is stopped\n   */\n  stopSync(channelId: string): Promise<void>;\n};\n";
 //# sourceMappingURL=messaging.js.map

package/dist/llm-docs/common/messaging.js.map

@@ -1 +1 @@
-{"version":3,"file":"messaging.js","sourceRoot":"","sources":["../../../src/llm-docs/common/messaging.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAe,mtJAAmtJ,CAAC"}
+{"version":3,"file":"messaging.js","sourceRoot":"","sources":["../../../src/llm-docs/common/messaging.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAe,6tHAA6tH,CAAC"}

package/dist/llm-docs/common/projects.d.ts

@@ -4,6 +4,6 @@
  * This file is auto-generated during build. Do not edit manually.
  * Generated from: prebuild.ts
  */
-declare const _default: "import type {\n  Activity,\n  ActivityLink,\n  ActivityMeta,\n  NewActivityWithNotes,\n  Serializable,\n} from \"../index\";\n\n/**\n * Represents a successful project management service authorization.\n *\n * Returned by project management tools when authorization completes successfully.\n * The auth token is an opaque identifier that can be used for subsequent\n * project operations.\n */\nexport type ProjectAuth = {\n  /** Opaque token for project management operations */\n  authToken: string;\n};\n\n/**\n * Represents a project from an external project management service.\n *\n * Contains metadata about a specific project/board/workspace that can be synced\n * with Plot.\n */\nexport type Project = {\n  /** Unique identifier for the project within the provider */\n  id: string;\n  /** Human-readable name of the project (e.g., \"Q1 Roadmap\", \"Engineering\") */\n  name: string;\n  /** Optional description or additional details about the project */\n  description: string | null;\n  /** Optional project key/abbreviation (e.g., \"PROJ\" in Jira, \"ENG\" in Linear) */\n  key: string | null;\n};\n\n/**\n * Configuration options for project synchronization.\n *\n * Controls the time range and other parameters for project sync operations.\n * Used to limit sync scope and optimize performance.\n */\nexport type ProjectSyncOptions = {\n  /** Earliest date to sync issues from (inclusive) */\n  timeMin?: Date;\n};\n\n/**\n * Base interface for project management integration tools.\n *\n * All synced issues/tasks are converted to ActivityWithNotes objects.\n * Each issue becomes an Activity with Notes for the description and comments.\n *\n * **Recommended Data Sync Strategy:**\n * Use Activity.source (issue URL) and Note.key for automatic upserts.\n * See SYNC_STRATEGIES.md for detailed patterns.\n */\nexport type ProjectTool = {\n  /**\n   * Initiates the authorization flow for the service.\n   *\n   * @param callback - Function receiving (auth, ...extraArgs) when auth completes\n   * @param extraArgs - Additional arguments to pass to the callback (type-checked)\n   * @returns Promise resolving to an ActivityLink to initiate the auth flow\n   */\n  requestAuth<\n    TArgs extends Serializable[],\n    TCallback extends (auth: ProjectAuth, ...args: TArgs) => any\n  >(\n    callback: TCallback,\n    ...extraArgs: TArgs\n  ): Promise<ActivityLink>;\n\n  /**\n   * Retrieves the list of projects accessible to the user.\n   *\n   * @param authToken - Authorization token from successful auth flow\n   * @returns Promise resolving to array of available projects\n   */\n  getProjects(authToken: string): Promise<Project[]>;\n\n  /**\n   * Begins synchronizing issues from a specific project.\n   *\n   * Issues and tasks are converted to NewActivityWithNotes objects.\n   *\n   * **Recommended Implementation** (Strategy 2 - Upsert via Source/Key):\n   * - Set Activity.source to the issue's canonical URL (e.g., Linear issue URL, Jira issue URL)\n   * - Use Note.key for issue details:\n   *   - key: \"description\" for issue description (upserts on changes)\n   *   - key: \"metadata\" for status, priority, assignee, etc.\n   *   - key: \"comment-{commentId}\" for individual comments (unique per comment)\n   * - No manual ID tracking needed - Plot handles deduplication automatically\n   * - Send NewActivityWithNotes for all issues (creates new or updates existing)\n   * - Set activity.unread = false for initial sync, omit for incremental updates\n   *\n   * **Alternative** (Strategy 3 - Advanced cases):\n   * - Use Uuid.Generate() and store ID mappings when creating multiple activities per issue\n   * - See SYNC_STRATEGIES.md for when this is appropriate\n   *\n   * @param options - Sync configuration options\n   * @param options.authToken - Authorization token for access\n   * @param options.projectId - ID of the project to sync\n   * @param options.timeMin - Earliest date to sync issues from (inclusive)\n   * @param callback - Function receiving (activity, ...extraArgs) for each synced issue\n   * @param extraArgs - Additional arguments to pass to the callback (type-checked, no functions allowed)\n   * @returns Promise that resolves when sync setup is complete\n   */\n  startSync<\n    TArgs extends Serializable[],\n    TCallback extends (activity: NewActivityWithNotes, ...args: TArgs) => any\n  >(\n    options: {\n      authToken: string;\n      projectId: string;\n    } & ProjectSyncOptions,\n    callback: TCallback,\n    ...extraArgs: TArgs\n  ): Promise<void>;\n\n  /**\n   * Stops synchronizing issues from a specific project.\n   *\n   * @param authToken - Authorization token for access\n   * @param projectId - ID of the project to stop syncing\n   * @returns Promise that resolves when sync is stopped\n   */\n  stopSync(authToken: string, projectId: string): Promise<void>;\n\n  /**\n   * Updates an issue/task with new values.\n   *\n   * Optional method for bidirectional sync. When implemented, allows Plot to\n   * sync activity updates back to the external service.\n   *\n   * Uses the combination of start and done to determine workflow state:\n   * - done set \u2192 Completed/Done state\n   * - done null + start set \u2192 In Progress/Active state\n   * - done null + start null \u2192 Backlog/Todo state\n   *\n   * @param authToken - Authorization token for access\n   * @param activity - The updated activity\n   * @returns Promise that resolves when the update is synced\n   */\n  updateIssue?(authToken: string, activity: Activity): Promise<void>;\n\n  /**\n   * Adds a comment to an issue/task.\n   *\n   * Optional method for bidirectional sync. When implemented, allows Plot to\n   * sync notes added to activities back as comments on the external service.\n   *\n   * The tool should extract its own ID from meta (e.g., linearId, taskGid, issueKey).\n   *\n   * @param authToken - Authorization token for access\n   * @param meta - Activity metadata containing the tool's issue/task identifier\n   * @param body - The comment text content\n   * @param noteId - Optional Plot note ID, used by tools that support comment metadata (e.g. Jira)\n   * @returns The external comment key (e.g. \"comment-123\") for dedup, or void\n   */\n  addIssueComment?(\n    authToken: string,\n    meta: ActivityMeta,\n    body: string,\n    noteId?: string,\n  ): Promise<string | void>;\n};\n";
+declare const _default: "import type {\n  Activity,\n  ActivityMeta,\n  NewActivityWithNotes,\n  Serializable,\n} from \"../index\";\n\n/**\n * Represents a project from an external project management service.\n *\n * Contains metadata about a specific project/board/workspace that can be synced\n * with Plot. Different project providers may have additional\n * provider-specific properties.\n */\nexport type Project = {\n  /** Unique identifier for the project within the provider */\n  id: string;\n  /** Human-readable name of the project (e.g., \"Q1 Roadmap\", \"Engineering\") */\n  name: string;\n  /** Optional description or additional details about the project */\n  description: string | null;\n  /** Optional project key/abbreviation (e.g., \"PROJ\" in Jira, \"ENG\" in Linear) */\n  key: string | null;\n};\n\n/**\n * Configuration options for project synchronization.\n *\n * Controls the time range and other parameters for project sync operations.\n * Used to limit sync scope and optimize performance.\n */\nexport type ProjectSyncOptions = {\n  /** Earliest date to sync issues from (inclusive) */\n  timeMin?: Date;\n};\n\n/**\n * Base interface for project management integration tools.\n *\n * All synced issues/tasks are converted to ActivityWithNotes objects.\n * Each issue becomes an Activity with Notes for the description and comments.\n *\n * **Architecture: Tools Build, Twists Save**\n *\n * Project tools follow Plot's core architectural principle:\n * - **Tools**: Fetch external data and transform it into Plot format (NewActivity objects)\n * - **Twists**: Receive the data and decide what to do with it (create, update, filter, etc.)\n *\n * **Implementation Pattern:**\n * 1. Authorization is handled via the twist edit modal (Integrations provider config)\n * 2. Tool declares providers and lifecycle callbacks in build()\n * 3. onAuthorized lists available projects and calls setSyncables()\n * 4. User enables projects in the modal \u2192 onSyncEnabled fires\n * 5. **Tool builds NewActivity objects** and passes them to the twist via callback\n * 6. **Twist decides** whether to save using createActivity/updateActivity\n *\n * **Recommended Data Sync Strategy:**\n * Use Activity.source (issue URL) and Note.key for automatic upserts.\n * See SYNC_STRATEGIES.md for detailed patterns.\n */\nexport type ProjectTool = {\n  /**\n   * Retrieves the list of projects accessible to the user.\n   *\n   * @param projectId - A project ID to use for auth lookup\n   * @returns Promise resolving to array of available projects\n   */\n  getProjects(projectId: string): Promise<Project[]>;\n\n  /**\n   * Begins synchronizing issues from a specific project.\n   *\n   * Auth is obtained automatically via integrations.get(provider, projectId).\n   *\n   * @param options - Sync configuration options\n   * @param options.projectId - ID of the project to sync\n   * @param options.timeMin - Earliest date to sync issues from (inclusive)\n   * @param callback - Function receiving (activity, ...extraArgs) for each synced issue\n   * @param extraArgs - Additional arguments to pass to the callback (type-checked, no functions allowed)\n   * @returns Promise that resolves when sync setup is complete\n   */\n  startSync<\n    TArgs extends Serializable[],\n    TCallback extends (activity: NewActivityWithNotes, ...args: TArgs) => any\n  >(\n    options: {\n      projectId: string;\n    } & ProjectSyncOptions,\n    callback: TCallback,\n    ...extraArgs: TArgs\n  ): Promise<void>;\n\n  /**\n   * Stops synchronizing issues from a specific project.\n   *\n   * @param projectId - ID of the project to stop syncing\n   * @returns Promise that resolves when sync is stopped\n   */\n  stopSync(projectId: string): Promise<void>;\n\n  /**\n   * Updates an issue/task with new values.\n   *\n   * Optional method for bidirectional sync. When implemented, allows Plot to\n   * sync activity updates back to the external service.\n   *\n   * Auth is obtained automatically via integrations.get(provider, projectId)\n   * using the projectId from activity.meta.\n   *\n   * @param activity - The updated activity\n   * @returns Promise that resolves when the update is synced\n   */\n  updateIssue?(activity: Activity): Promise<void>;\n\n  /**\n   * Adds a comment to an issue/task.\n   *\n   * Optional method for bidirectional sync. When implemented, allows Plot to\n   * sync notes added to activities back as comments on the external service.\n   *\n   * Auth is obtained automatically. The tool should extract its own ID\n   * from meta (e.g., linearId, taskGid, issueKey).\n   *\n   * @param meta - Activity metadata containing the tool's issue/task identifier\n   * @param body - The comment text content\n   * @param noteId - Optional Plot note ID, used by tools that support comment metadata (e.g. Jira)\n   * @returns The external comment key (e.g. \"comment-123\") for dedup, or void\n   */\n  addIssueComment?(\n    meta: ActivityMeta,\n    body: string,\n    noteId?: string,\n  ): Promise<string | void>;\n};\n";
 export default _default;
 //# sourceMappingURL=projects.d.ts.map

package/dist/llm-docs/common/projects.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"projects.d.ts","sourceRoot":"","sources":["../../../src/llm-docs/common/projects.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;wBAEY,guMAAitM;AAAhuM,wBAAiuM"}
+{"version":3,"file":"projects.d.ts","sourceRoot":"","sources":["../../../src/llm-docs/common/projects.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;wBAEY,i6JAA45J;AAA36J,wBAA46J"}

package/dist/llm-docs/common/projects.js

@@ -4,5 +4,5 @@
  * This file is auto-generated during build. Do not edit manually.
  * Generated from: prebuild.ts
  */
-export default "import type {\n  Activity,\n  ActivityLink,\n  ActivityMeta,\n  NewActivityWithNotes,\n  Serializable,\n} from \"../index\";\n\n/**\n * Represents a successful project management service authorization.\n *\n * Returned by project management tools when authorization completes successfully.\n * The auth token is an opaque identifier that can be used for subsequent\n * project operations.\n */\nexport type ProjectAuth = {\n  /** Opaque token for project management operations */\n  authToken: string;\n};\n\n/**\n * Represents a project from an external project management service.\n *\n * Contains metadata about a specific project/board/workspace that can be synced\n * with Plot.\n */\nexport type Project = {\n  /** Unique identifier for the project within the provider */\n  id: string;\n  /** Human-readable name of the project (e.g., \"Q1 Roadmap\", \"Engineering\") */\n  name: string;\n  /** Optional description or additional details about the project */\n  description: string | null;\n  /** Optional project key/abbreviation (e.g., \"PROJ\" in Jira, \"ENG\" in Linear) */\n  key: string | null;\n};\n\n/**\n * Configuration options for project synchronization.\n *\n * Controls the time range and other parameters for project sync operations.\n * Used to limit sync scope and optimize performance.\n */\nexport type ProjectSyncOptions = {\n  /** Earliest date to sync issues from (inclusive) */\n  timeMin?: Date;\n};\n\n/**\n * Base interface for project management integration tools.\n *\n * All synced issues/tasks are converted to ActivityWithNotes objects.\n * Each issue becomes an Activity with Notes for the description and comments.\n *\n * **Recommended Data Sync Strategy:**\n * Use Activity.source (issue URL) and Note.key for automatic upserts.\n * See SYNC_STRATEGIES.md for detailed patterns.\n */\nexport type ProjectTool = {\n  /**\n   * Initiates the authorization flow for the service.\n   *\n   * @param callback - Function receiving (auth, ...extraArgs) when auth completes\n   * @param extraArgs - Additional arguments to pass to the callback (type-checked)\n   * @returns Promise resolving to an ActivityLink to initiate the auth flow\n   */\n  requestAuth<\n    TArgs extends Serializable[],\n    TCallback extends (auth: ProjectAuth, ...args: TArgs) => any\n  >(\n    callback: TCallback,\n    ...extraArgs: TArgs\n  ): Promise<ActivityLink>;\n\n  /**\n   * Retrieves the list of projects accessible to the user.\n   *\n   * @param authToken - Authorization token from successful auth flow\n   * @returns Promise resolving to array of available projects\n   */\n  getProjects(authToken: string): Promise<Project[]>;\n\n  /**\n   * Begins synchronizing issues from a specific project.\n   *\n   * Issues and tasks are converted to NewActivityWithNotes objects.\n   *\n   * **Recommended Implementation** (Strategy 2 - Upsert via Source/Key):\n   * - Set Activity.source to the issue's canonical URL (e.g., Linear issue URL, Jira issue URL)\n   * - Use Note.key for issue details:\n   *   - key: \"description\" for issue description (upserts on changes)\n   *   - key: \"metadata\" for status, priority, assignee, etc.\n   *   - key: \"comment-{commentId}\" for individual comments (unique per comment)\n   * - No manual ID tracking needed - Plot handles deduplication automatically\n   * - Send NewActivityWithNotes for all issues (creates new or updates existing)\n   * - Set activity.unread = false for initial sync, omit for incremental updates\n   *\n   * **Alternative** (Strategy 3 - Advanced cases):\n   * - Use Uuid.Generate() and store ID mappings when creating multiple activities per issue\n   * - See SYNC_STRATEGIES.md for when this is appropriate\n   *\n   * @param options - Sync configuration options\n   * @param options.authToken - Authorization token for access\n   * @param options.projectId - ID of the project to sync\n   * @param options.timeMin - Earliest date to sync issues from (inclusive)\n   * @param callback - Function receiving (activity, ...extraArgs) for each synced issue\n   * @param extraArgs - Additional arguments to pass to the callback (type-checked, no functions allowed)\n   * @returns Promise that resolves when sync setup is complete\n   */\n  startSync<\n    TArgs extends Serializable[],\n    TCallback extends (activity: NewActivityWithNotes, ...args: TArgs) => any\n  >(\n    options: {\n      authToken: string;\n      projectId: string;\n    } & ProjectSyncOptions,\n    callback: TCallback,\n    ...extraArgs: TArgs\n  ): Promise<void>;\n\n  /**\n   * Stops synchronizing issues from a specific project.\n   *\n   * @param authToken - Authorization token for access\n   * @param projectId - ID of the project to stop syncing\n   * @returns Promise that resolves when sync is stopped\n   */\n  stopSync(authToken: string, projectId: string): Promise<void>;\n\n  /**\n   * Updates an issue/task with new values.\n   *\n   * Optional method for bidirectional sync. When implemented, allows Plot to\n   * sync activity updates back to the external service.\n   *\n   * Uses the combination of start and done to determine workflow state:\n   * - done set → Completed/Done state\n   * - done null + start set → In Progress/Active state\n   * - done null + start null → Backlog/Todo state\n   *\n   * @param authToken - Authorization token for access\n   * @param activity - The updated activity\n   * @returns Promise that resolves when the update is synced\n   */\n  updateIssue?(authToken: string, activity: Activity): Promise<void>;\n\n  /**\n   * Adds a comment to an issue/task.\n   *\n   * Optional method for bidirectional sync. When implemented, allows Plot to\n   * sync notes added to activities back as comments on the external service.\n   *\n   * The tool should extract its own ID from meta (e.g., linearId, taskGid, issueKey).\n   *\n   * @param authToken - Authorization token for access\n   * @param meta - Activity metadata containing the tool's issue/task identifier\n   * @param body - The comment text content\n   * @param noteId - Optional Plot note ID, used by tools that support comment metadata (e.g. Jira)\n   * @returns The external comment key (e.g. \"comment-123\") for dedup, or void\n   */\n  addIssueComment?(\n    authToken: string,\n    meta: ActivityMeta,\n    body: string,\n    noteId?: string,\n  ): Promise<string | void>;\n};\n";
+export default "import type {\n  Activity,\n  ActivityMeta,\n  NewActivityWithNotes,\n  Serializable,\n} from \"../index\";\n\n/**\n * Represents a project from an external project management service.\n *\n * Contains metadata about a specific project/board/workspace that can be synced\n * with Plot. Different project providers may have additional\n * provider-specific properties.\n */\nexport type Project = {\n  /** Unique identifier for the project within the provider */\n  id: string;\n  /** Human-readable name of the project (e.g., \"Q1 Roadmap\", \"Engineering\") */\n  name: string;\n  /** Optional description or additional details about the project */\n  description: string | null;\n  /** Optional project key/abbreviation (e.g., \"PROJ\" in Jira, \"ENG\" in Linear) */\n  key: string | null;\n};\n\n/**\n * Configuration options for project synchronization.\n *\n * Controls the time range and other parameters for project sync operations.\n * Used to limit sync scope and optimize performance.\n */\nexport type ProjectSyncOptions = {\n  /** Earliest date to sync issues from (inclusive) */\n  timeMin?: Date;\n};\n\n/**\n * Base interface for project management integration tools.\n *\n * All synced issues/tasks are converted to ActivityWithNotes objects.\n * Each issue becomes an Activity with Notes for the description and comments.\n *\n * **Architecture: Tools Build, Twists Save**\n *\n * Project tools follow Plot's core architectural principle:\n * - **Tools**: Fetch external data and transform it into Plot format (NewActivity objects)\n * - **Twists**: Receive the data and decide what to do with it (create, update, filter, etc.)\n *\n * **Implementation Pattern:**\n * 1. Authorization is handled via the twist edit modal (Integrations provider config)\n * 2. Tool declares providers and lifecycle callbacks in build()\n * 3. onAuthorized lists available projects and calls setSyncables()\n * 4. User enables projects in the modal → onSyncEnabled fires\n * 5. **Tool builds NewActivity objects** and passes them to the twist via callback\n * 6. **Twist decides** whether to save using createActivity/updateActivity\n *\n * **Recommended Data Sync Strategy:**\n * Use Activity.source (issue URL) and Note.key for automatic upserts.\n * See SYNC_STRATEGIES.md for detailed patterns.\n */\nexport type ProjectTool = {\n  /**\n   * Retrieves the list of projects accessible to the user.\n   *\n   * @param projectId - A project ID to use for auth lookup\n   * @returns Promise resolving to array of available projects\n   */\n  getProjects(projectId: string): Promise<Project[]>;\n\n  /**\n   * Begins synchronizing issues from a specific project.\n   *\n   * Auth is obtained automatically via integrations.get(provider, projectId).\n   *\n   * @param options - Sync configuration options\n   * @param options.projectId - ID of the project to sync\n   * @param options.timeMin - Earliest date to sync issues from (inclusive)\n   * @param callback - Function receiving (activity, ...extraArgs) for each synced issue\n   * @param extraArgs - Additional arguments to pass to the callback (type-checked, no functions allowed)\n   * @returns Promise that resolves when sync setup is complete\n   */\n  startSync<\n    TArgs extends Serializable[],\n    TCallback extends (activity: NewActivityWithNotes, ...args: TArgs) => any\n  >(\n    options: {\n      projectId: string;\n    } & ProjectSyncOptions,\n    callback: TCallback,\n    ...extraArgs: TArgs\n  ): Promise<void>;\n\n  /**\n   * Stops synchronizing issues from a specific project.\n   *\n   * @param projectId - ID of the project to stop syncing\n   * @returns Promise that resolves when sync is stopped\n   */\n  stopSync(projectId: string): Promise<void>;\n\n  /**\n   * Updates an issue/task with new values.\n   *\n   * Optional method for bidirectional sync. When implemented, allows Plot to\n   * sync activity updates back to the external service.\n   *\n   * Auth is obtained automatically via integrations.get(provider, projectId)\n   * using the projectId from activity.meta.\n   *\n   * @param activity - The updated activity\n   * @returns Promise that resolves when the update is synced\n   */\n  updateIssue?(activity: Activity): Promise<void>;\n\n  /**\n   * Adds a comment to an issue/task.\n   *\n   * Optional method for bidirectional sync. When implemented, allows Plot to\n   * sync notes added to activities back as comments on the external service.\n   *\n   * Auth is obtained automatically. The tool should extract its own ID\n   * from meta (e.g., linearId, taskGid, issueKey).\n   *\n   * @param meta - Activity metadata containing the tool's issue/task identifier\n   * @param body - The comment text content\n   * @param noteId - Optional Plot note ID, used by tools that support comment metadata (e.g. Jira)\n   * @returns The external comment key (e.g. \"comment-123\") for dedup, or void\n   */\n  addIssueComment?(\n    meta: ActivityMeta,\n    body: string,\n    noteId?: string,\n  ): Promise<string | void>;\n};\n";
 //# sourceMappingURL=projects.js.map

package/dist/llm-docs/common/projects.js.map

@@ -1 +1 @@
-{"version":3,"file":"projects.js","sourceRoot":"","sources":["../../../src/llm-docs/common/projects.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAe,itMAAitM,CAAC"}
+{"version":3,"file":"projects.js","sourceRoot":"","sources":["../../../src/llm-docs/common/projects.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAe,45JAA45J,CAAC"}

package/dist/llm-docs/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/llm-docs/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAmBH,QAAA,MAAM,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAiBnC,CAAC;AAEF,eAAe,OAAO,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/llm-docs/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAoBH,QAAA,MAAM,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAkBnC,CAAC;AAEF,eAAe,OAAO,CAAC"}

package/dist/llm-docs/index.js

@@ -6,6 +6,7 @@
  *
  * Provides a mapping of Twister import paths to their source code documentation.
  */
+import options from "./options.js";
 import plot from "./plot.js";
 import tag from "./tag.js";
 import tool from "./tool.js";
@@ -23,6 +24,7 @@ import tools_store from "./tools/store.js";
 import tools_tasks from "./tools/tasks.js";
 import tools_twists from "./tools/twists.js";
 const llmDocs = {
+    "@plotday/twister/options": options,
     "@plotday/twister/plot": plot,
     "@plotday/twister/tag": tag,
     "@plotday/twister/tool": tool,

package/dist/llm-docs/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/llm-docs/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,GAAG,MAAM,UAAU,CAAC;AAC3B,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,KAAK,MAAM,YAAY,CAAC;AAC/B,OAAO,eAAe,MAAM,sBAAsB,CAAC;AACnD,OAAO,gBAAgB,MAAM,uBAAuB,CAAC;AACrD,OAAO,gBAAgB,MAAM,uBAAuB,CAAC;AACrD,OAAO,eAAe,MAAM,sBAAsB,CAAC;AACnD,OAAO,QAAQ,MAAM,eAAe,CAAC;AACrC,OAAO,eAAe,MAAM,sBAAsB,CAAC;AACnD,OAAO,kBAAkB,MAAM,yBAAyB,CAAC;AACzD,OAAO,aAAa,MAAM,oBAAoB,CAAC;AAC/C,OAAO,UAAU,MAAM,iBAAiB,CAAC;AACzC,OAAO,WAAW,MAAM,kBAAkB,CAAC;AAC3C,OAAO,WAAW,MAAM,kBAAkB,CAAC;AAC3C,OAAO,YAAY,MAAM,mBAAmB,CAAC;AAE7C,MAAM,OAAO,GAA2B;IACtC,uBAAuB,EAAE,IAAI;IAC7B,sBAAsB,EAAE,GAAG;IAC3B,uBAAuB,EAAE,IAAI;IAC7B,wBAAwB,EAAE,KAAK;IAC/B,kCAAkC,EAAE,eAAe;IACnD,mCAAmC,EAAE,gBAAgB;IACrD,mCAAmC,EAAE,gBAAgB;IACrD,kCAAkC,EAAE,eAAe;IACnD,2BAA2B,EAAE,QAAQ;IACrC,kCAAkC,EAAE,eAAe;IACnD,qCAAqC,EAAE,kBAAkB;IACzD,gCAAgC,EAAE,aAAa;IAC/C,6BAA6B,EAAE,UAAU;IACzC,8BAA8B,EAAE,WAAW;IAC3C,8BAA8B,EAAE,WAAW;IAC3C,+BAA+B,EAAE,YAAY;CAC9C,CAAC;AAEF,eAAe,OAAO,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/llm-docs/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,OAAO,MAAM,cAAc,CAAC;AACnC,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,GAAG,MAAM,UAAU,CAAC;AAC3B,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,KAAK,MAAM,YAAY,CAAC;AAC/B,OAAO,eAAe,MAAM,sBAAsB,CAAC;AACnD,OAAO,gBAAgB,MAAM,uBAAuB,CAAC;AACrD,OAAO,gBAAgB,MAAM,uBAAuB,CAAC;AACrD,OAAO,eAAe,MAAM,sBAAsB,CAAC;AACnD,OAAO,QAAQ,MAAM,eAAe,CAAC;AACrC,OAAO,eAAe,MAAM,sBAAsB,CAAC;AACnD,OAAO,kBAAkB,MAAM,yBAAyB,CAAC;AACzD,OAAO,aAAa,MAAM,oBAAoB,CAAC;AAC/C,OAAO,UAAU,MAAM,iBAAiB,CAAC;AACzC,OAAO,WAAW,MAAM,kBAAkB,CAAC;AAC3C,OAAO,WAAW,MAAM,kBAAkB,CAAC;AAC3C,OAAO,YAAY,MAAM,mBAAmB,CAAC;AAE7C,MAAM,OAAO,GAA2B;IACtC,0BAA0B,EAAE,OAAO;IACnC,uBAAuB,EAAE,IAAI;IAC7B,sBAAsB,EAAE,GAAG;IAC3B,uBAAuB,EAAE,IAAI;IAC7B,wBAAwB,EAAE,KAAK;IAC/B,kCAAkC,EAAE,eAAe;IACnD,mCAAmC,EAAE,gBAAgB;IACrD,mCAAmC,EAAE,gBAAgB;IACrD,kCAAkC,EAAE,eAAe;IACnD,2BAA2B,EAAE,QAAQ;IACrC,kCAAkC,EAAE,eAAe;IACnD,qCAAqC,EAAE,kBAAkB;IACzD,gCAAgC,EAAE,aAAa;IAC/C,6BAA6B,EAAE,UAAU;IACzC,8BAA8B,EAAE,WAAW;IAC3C,8BAA8B,EAAE,WAAW;IAC3C,+BAA+B,EAAE,YAAY;CAC9C,CAAC;AAEF,eAAe,OAAO,CAAC"}

package/dist/llm-docs/options.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Generated LLM documentation for @plotday/twister/options
+ *
+ * This file is auto-generated during build. Do not edit manually.
+ * Generated from: prebuild.ts
+ */
+declare const _default: "import { ITool } from \"./tool\";\n\n/**\n * A select option definition for twist configuration.\n * Renders as a dropdown in the Flutter UI.\n */\nexport type SelectDef = {\n  type: \"select\";\n  label: string;\n  description?: string;\n  choices: ReadonlyArray<{ value: string; label: string }>;\n  default: string;\n};\n\n/**\n * A text input option definition for twist configuration.\n * Renders as a text field in the Flutter UI.\n */\nexport type TextDef = {\n  type: \"text\";\n  label: string;\n  description?: string;\n  default: string;\n  placeholder?: string;\n};\n\n/**\n * A number input option definition for twist configuration.\n * Renders as a number field in the Flutter UI.\n */\nexport type NumberDef = {\n  type: \"number\";\n  label: string;\n  description?: string;\n  default: number;\n  min?: number;\n  max?: number;\n};\n\n/**\n * A boolean toggle option definition for twist configuration.\n * Renders as a switch in the Flutter UI.\n */\nexport type BooleanDef = {\n  type: \"boolean\";\n  label: string;\n  description?: string;\n  default: boolean;\n};\n\n/**\n * Union of all option definition types.\n */\nexport type OptionDef = SelectDef | TextDef | NumberDef | BooleanDef;\n\n/**\n * Schema defining all configurable options for a twist.\n * Each key maps to an option definition that describes its type, label, and default value.\n */\nexport type OptionsSchema = Record<string, OptionDef>;\n\n/**\n * Infers the resolved value types from an options schema.\n * Boolean options resolve to `boolean`, number options to `number`,\n * and select/text options to `string`.\n */\nexport type ResolvedOptions<T extends OptionsSchema> = {\n  [K in keyof T]: T[K] extends BooleanDef\n    ? boolean\n    : T[K] extends NumberDef\n      ? number\n      : string;\n};\n\n/**\n * Built-in marker class for twist configuration options.\n *\n * Declare options in your twist's `build()` method to expose configurable\n * settings to users. The schema is introspected at deploy time and stored\n * alongside permissions. At runtime, user values are merged with defaults.\n *\n * @example\n * ```typescript\n * import { Options, type OptionsSchema } from \"@plotday/twister/options\";\n *\n * export default class MyTwist extends Twist<MyTwist> {\n *   build(build: ToolBuilder) {\n *     return {\n *       options: build(Options, {\n *         model: {\n *           type: 'select',\n *           label: 'AI Model',\n *           choices: [\n *             { value: 'fast', label: 'Fast' },\n *             { value: 'smart', label: 'Smart' },\n *           ],\n *           default: 'fast',\n *         },\n *       }),\n *       // ... other tools\n *     };\n *   }\n *\n *   async respond(note: Note) {\n *     const model = this.tools.options.model; // typed as string\n *   }\n * }\n * ```\n */\nexport abstract class Options extends ITool {\n  static readonly toolId = \"Options\";\n}\n";
+export default _default;
+//# sourceMappingURL=options.d.ts.map

package/dist/llm-docs/options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"options.d.ts","sourceRoot":"","sources":["../../src/llm-docs/options.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;wBAEY,w2FAAw2F;AAAv3F,wBAAw3F"}

package/dist/llm-docs/options.js

@@ -0,0 +1,8 @@
+/**
+ * Generated LLM documentation for @plotday/twister/options
+ *
+ * This file is auto-generated during build. Do not edit manually.
+ * Generated from: prebuild.ts
+ */
+export default "import { ITool } from \"./tool\";\n\n/**\n * A select option definition for twist configuration.\n * Renders as a dropdown in the Flutter UI.\n */\nexport type SelectDef = {\n  type: \"select\";\n  label: string;\n  description?: string;\n  choices: ReadonlyArray<{ value: string; label: string }>;\n  default: string;\n};\n\n/**\n * A text input option definition for twist configuration.\n * Renders as a text field in the Flutter UI.\n */\nexport type TextDef = {\n  type: \"text\";\n  label: string;\n  description?: string;\n  default: string;\n  placeholder?: string;\n};\n\n/**\n * A number input option definition for twist configuration.\n * Renders as a number field in the Flutter UI.\n */\nexport type NumberDef = {\n  type: \"number\";\n  label: string;\n  description?: string;\n  default: number;\n  min?: number;\n  max?: number;\n};\n\n/**\n * A boolean toggle option definition for twist configuration.\n * Renders as a switch in the Flutter UI.\n */\nexport type BooleanDef = {\n  type: \"boolean\";\n  label: string;\n  description?: string;\n  default: boolean;\n};\n\n/**\n * Union of all option definition types.\n */\nexport type OptionDef = SelectDef | TextDef | NumberDef | BooleanDef;\n\n/**\n * Schema defining all configurable options for a twist.\n * Each key maps to an option definition that describes its type, label, and default value.\n */\nexport type OptionsSchema = Record<string, OptionDef>;\n\n/**\n * Infers the resolved value types from an options schema.\n * Boolean options resolve to `boolean`, number options to `number`,\n * and select/text options to `string`.\n */\nexport type ResolvedOptions<T extends OptionsSchema> = {\n  [K in keyof T]: T[K] extends BooleanDef\n    ? boolean\n    : T[K] extends NumberDef\n      ? number\n      : string;\n};\n\n/**\n * Built-in marker class for twist configuration options.\n *\n * Declare options in your twist's `build()` method to expose configurable\n * settings to users. The schema is introspected at deploy time and stored\n * alongside permissions. At runtime, user values are merged with defaults.\n *\n * @example\n * ```typescript\n * import { Options, type OptionsSchema } from \"@plotday/twister/options\";\n *\n * export default class MyTwist extends Twist<MyTwist> {\n *   build(build: ToolBuilder) {\n *     return {\n *       options: build(Options, {\n *         model: {\n *           type: 'select',\n *           label: 'AI Model',\n *           choices: [\n *             { value: 'fast', label: 'Fast' },\n *             { value: 'smart', label: 'Smart' },\n *           ],\n *           default: 'fast',\n *         },\n *       }),\n *       // ... other tools\n *     };\n *   }\n *\n *   async respond(note: Note) {\n *     const model = this.tools.options.model; // typed as string\n *   }\n * }\n * ```\n */\nexport abstract class Options extends ITool {\n  static readonly toolId = \"Options\";\n}\n";
+//# sourceMappingURL=options.js.map

package/dist/llm-docs/options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"options.js","sourceRoot":"","sources":["../../src/llm-docs/options.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAe,w2FAAw2F,CAAC"}

package/dist/llm-docs/plot.d.ts

@@ -4,6 +4,6 @@
  * This file is auto-generated during build. Do not edit manually.
  * Generated from: prebuild.ts
  */
-declare const _default: "import { type Tag } from \"./tag\";\nimport { type Callback } from \"./tools/callbacks\";\nimport { type AuthProvider } from \"./tools/integrations\";\nimport { type JSONValue } from \"./utils/types\";\nimport { Uuid } from \"./utils/uuid\";\n\nexport { Tag } from \"./tag\";\nexport { Uuid } from \"./utils/uuid\";\nexport { type JSONValue } from \"./utils/types\";\nexport { type AuthProvider } from \"./tools/integrations\";\n\n/**\n * @fileoverview\n * Core Plot entity types for working with activities, notes, priorities, and contacts.\n *\n * ## Type Pattern: Null vs Undefined Semantics\n *\n * Plot entity types use a consistent pattern to distinguish between missing, unset, and explicitly cleared values:\n *\n * ### Entity Types (Activity, Priority, Note, Actor)\n * - **Required fields**: No `?`, cannot be `undefined`\n *   - Example: `id: Uuid`, `type: ActivityType`\n * - **Nullable fields**: Use `| null` to allow explicit clearing\n *   - Example: `assignee: ActorId | null`, `done: Date | null`\n *   - `null` = field is explicitly unset/cleared\n *   - Non-null value = field has a value\n * - **Optional nullable fields**: Use `?` with `| null` for permission-based access\n *   - Example: `email?: string | null`, `name?: string | null`\n *   - `undefined` = field not included (e.g., no permission to access)\n *   - `null` = field included but not set\n *   - Value = field has a value\n *\n * ### New* Types (NewActivity, NewNote, NewPriority)\n * Used for creating or updating entities. Support partial updates by distinguishing omitted vs cleared fields:\n * - **Required fields**: Must be provided (no `?`)\n *   - Example: `type: ActivityType` in NewActivity\n * - **Optional fields**: Use `?` to make them optional\n *   - Example: `title?: string`, `author?: NewActor`\n *   - `undefined` (omitted) = don't set/update this field\n *   - Provided value = set/update this field\n * - **Optional nullable fields**: Use `?` with `| null` to support clearing\n *   - Example: `assignee?: NewActor | null`\n *   - `undefined` (omitted) = don't change assignee\n *   - `null` = clear the assignee\n *   - NewActor = set/update the assignee\n *\n * This pattern allows API consumers to:\n * 1. Omit fields they don't want to change (undefined)\n * 2. Explicitly clear fields by setting to null\n * 3. Set or update fields by providing values\n *\n * @example\n * ```typescript\n * // Creating a new activity\n * const newActivity: NewActivity = {\n *   type: ActivityType.Action,  // Required\n *   title: \"Review PR\",          // Optional, provided\n *   assignee: null,              // Optional nullable, explicitly clearing\n *   // priority is omitted (undefined), will auto-select or use default\n * };\n *\n * // Updating an activity - only change what's specified\n * const update: ActivityUpdate = {\n *   id: activityId,\n *   done: new Date(),       // Mark as done\n *   assignee: null,         // Clear assignee\n *   // title is omitted, won't be changed\n * };\n * ```\n */\n\n/**\n * Represents a unique user, contact, or twist in Plot.\n *\n * ActorIds are used throughout Plot for:\n * - Activity authors and assignees\n * - Tag creators (actor_id in activity_tag/note_tag)\n * - Mentions in activities and notes\n * - Any entity that can perform actions in Plot\n */\nexport type ActorId = string & { readonly __brand: \"ActorId\" };\n\n/**\n * Theme colors for priorities.\n */\nexport enum ThemeColor {\n  /** Catalyst - Green */\n  Catalyst = 0,\n  /** Call to Adventure - Blue */\n  CallToAdventure = 1,\n  /** Rising Action - Purple */\n  RisingAction = 2,\n  /** Momentum - Pink-Purple */\n  Momentum = 3,\n  /** Turning Point - Pink */\n  TurningPoint = 4,\n  /** Breakthrough - Orange */\n  Breakthrough = 5,\n  /** Climax - Olive */\n  Climax = 6,\n  /** Resolution - Blue-Gray */\n  Resolution = 7,\n}\n\n/**\n * Represents a priority context within Plot.\n *\n * Priorities are similar to projects in other apps. All Activity is in a Priority.\n * Priorities can be nested.\n */\nexport type Priority = {\n  /** Unique identifier for the priority */\n  id: Uuid;\n  /** Human-readable title for the priority */\n  title: string;\n  /** Whether this priority has been archived */\n  archived: boolean;\n  /**\n   * Optional key for referencing this priority.\n   * Keys are unique per priority tree (a user's personal priorities or the root of a shared priority).\n   */\n  key: string | null;\n  /** Optional theme color for the priority (0-7). If not set, inherits from parent or defaults to 7 (Resolution). */\n  color: ThemeColor | null;\n};\n\n/**\n * Type for creating new priorities.\n *\n * Supports multiple creation patterns:\n * - Provide a specific UUID for the priority\n * - Provide a key for upsert within the user's priorities\n * - Omit both to auto-generate a new UUID\n *\n * Optionally specify a parent priority by ID or key for hierarchical structures.\n */\nexport type NewPriority = Pick<Priority, \"title\"> &\n  Partial<Omit<Priority, \"id\" | \"title\">> &\n  (\n    | {\n        /**\n         * Unique identifier for the priority, generated by Uuid.Generate().\n         * Specifying an ID allows tools to track and upsert priorities.\n         */\n        id: Uuid;\n      }\n    | {\n        /**\n         * Unique key for the priority within the user's priorities.\n         * Can be used to upsert without knowing the UUID.\n         * For example, \"@plot\" identifies the Plot priority.\n         */\n        key: string;\n      }\n    | {\n        /* Neither id nor key is required. An id will be generated and returned. */\n      }\n  ) & {\n    /** Add the new priority as the child of another priority */\n    parent?: { id: Uuid } | { key: string };\n  };\n\n/**\n * Type for updating existing priorities.\n * Must provide either id or key to identify the priority to update.\n */\nexport type PriorityUpdate = ({ id: Uuid } | { key: string }) &\n  Partial<Pick<Priority, \"title\" | \"archived\">>;\n\n/**\n * Enumeration of supported activity types in Plot.\n *\n * Each activity type has different behaviors and rendering characteristics\n * within the Plot application.\n */\nexport enum ActivityType {\n  /** A note or piece of information without actionable requirements */\n  Note,\n  /** An actionable item that can be completed */\n  Action,\n  /** A scheduled occurrence with start and optional end time */\n  Event,\n}\n\n/**\n * Kinds of activities. Used only for visual categorization (icon).\n */\nexport enum ActivityKind {\n  document = \"document\", // any external document or item in an external system\n  messages = \"messages\", // emails and chat threads\n  meeting = \"meeting\", // in-person meeting\n  videoconference = \"videoconference\",\n  phone = \"phone\",\n  focus = \"focus\",\n  meal = \"meal\",\n  exercise = \"exercise\",\n  family = \"family\",\n  travel = \"travel\",\n  social = \"social\",\n  entertainment = \"entertainment\",\n}\n\n/**\n * Enumeration of supported activity link types.\n *\n * Different link types have different behaviors when clicked by users\n * and may require different rendering approaches.\n */\nexport enum ActivityLinkType {\n  /** External web links that open in browser */\n  external = \"external\",\n  /** Authentication flows for connecting services */\n  auth = \"auth\",\n  /** Callback links that trigger twist methods when clicked */\n  callback = \"callback\",\n  /** Video conferencing links with provider-specific handling */\n  conferencing = \"conferencing\",\n  /** File attachment links stored in R2 */\n  file = \"file\",\n}\n\n/**\n * Video conferencing providers for conferencing links.\n *\n * Used to identify the conferencing platform and provide\n * provider-specific UI elements (titles, icons, etc.).\n */\nexport enum ConferencingProvider {\n  /** Google Meet */\n  googleMeet = \"googleMeet\",\n  /** Zoom */\n  zoom = \"zoom\",\n  /** Microsoft Teams */\n  microsoftTeams = \"microsoftTeams\",\n  /** Cisco Webex */\n  webex = \"webex\",\n  /** Other or unknown conferencing provider */\n  other = \"other\",\n}\n\n/**\n * Represents a clickable link attached to an activity.\n *\n * Activity links are rendered as buttons that enable user interaction with activities.\n * Different link types have specific behaviors and required fields for proper functionality.\n *\n * @example\n * ```typescript\n * // External link - opens URL in browser\n * const externalLink: ActivityLink = {\n *   type: ActivityLinkType.external,\n *   title: \"Open in Google Calendar\",\n *   url: \"https://calendar.google.com/event/123\",\n * };\n *\n * // Conferencing link - opens video conference with provider info\n * const conferencingLink: ActivityLink = {\n *   type: ActivityLinkType.conferencing,\n *   url: \"https://meet.google.com/abc-defg-hij\",\n *   provider: ConferencingProvider.googleMeet,\n * };\n *\n * // Integrations link - initiates OAuth flow\n * const authLink: ActivityLink = {\n *   type: ActivityLinkType.auth,\n *   title: \"Continue with Google\",\n *   provider: AuthProvider.Google,\n *   scopes: [\"https://www.googleapis.com/auth/calendar.readonly\"],\n *   callback: \"callback-token-for-auth-completion\"\n * };\n *\n * // Callback link - triggers a twist method\n * const callbackLink: ActivityLink = {\n *   type: ActivityLinkType.callback,\n *   title: \"\uD83D\uDCC5 Primary Calendar\",\n *   token: \"callback-token-here\"\n * };\n * ```\n */\nexport type ActivityLink =\n  | {\n      /** External web link that opens in browser */\n      type: ActivityLinkType.external;\n      /** Display text for the link button */\n      title: string;\n      /** URL to open when clicked */\n      url: string;\n    }\n  | {\n      /** Video conferencing link with provider-specific handling */\n      type: ActivityLinkType.conferencing;\n      /** URL to join the conference */\n      url: string;\n      /** Conferencing provider for UI customization */\n      provider: ConferencingProvider;\n    }\n  | {\n      /** Authentication link that initiates an OAuth flow */\n      type: ActivityLinkType.auth;\n      /** Display text for the auth button */\n      title: string;\n      /** OAuth provider (e.g., \"google\", \"microsoft\") */\n      provider: string;\n      /** Array of OAuth scopes to request */\n      scopes: string[];\n      /** Callback token for auth completion notification */\n      callback: Callback;\n    }\n  | {\n      /** Callback link that triggers a twist method when clicked */\n      type: ActivityLinkType.callback;\n      /** Display text for the callback button */\n      title: string;\n      /** Token identifying the callback to execute */\n      callback: Callback;\n    }\n  | {\n      /** File attachment link stored in R2 */\n      type: ActivityLinkType.file;\n      /** Unique identifier for the stored file */\n      fileId: string;\n      /** Original filename */\n      fileName: string;\n      /** File size in bytes */\n      fileSize: number;\n      /** MIME type of the file */\n      mimeType: string;\n    };\n\n/**\n * Represents metadata about an activity, typically from an external system.\n *\n * Activity metadata enables storing additional information about activities,\n * which is useful for synchronization, linking back to external systems,\n * and storing tool-specific data.\n *\n * Must be valid JSON data (strings, numbers, booleans, null, objects, arrays).\n * Functions and other non-JSON values are not supported.\n *\n * @example\n * ```typescript\n * // Calendar event metadata\n * await plot.createActivity({\n *   type: ActivityType.Event,\n *   title: \"Team Meeting\",\n *   start: new Date(\"2024-01-15T10:00:00Z\"),\n *   meta: {\n *     calendarId: \"primary\",\n *     htmlLink: \"https://calendar.google.com/event/abc123\",\n *     conferenceData: { ... }\n *   }\n * });\n *\n * // Project issue metadata\n * await plot.createActivity({\n *   type: ActivityType.Action,\n *   title: \"Fix login bug\",\n *   meta: {\n *     projectId: \"TEAM\",\n *     issueNumber: 123,\n *     url: \"https://linear.app/team/issue/TEAM-123\"\n *   }\n * });\n * ```\n */\nexport type ActivityMeta = {\n  /** Source-specific properties and metadata */\n  [key: string]: JSONValue;\n};\n\n/**\n * Tags on an item, along with the actors who added each tag.\n */\nexport type Tags = { [K in Tag]?: ActorId[] };\n\n/**\n * A set of tags to add to an item, along with the actors adding each tag.\n */\nexport type NewTags = { [K in Tag]?: NewActor[] };\n\n/**\n * Common fields shared by both Activity and Note entities.\n */\nexport type ActivityCommon = {\n  /** Unique identifier for the activity */\n  id: Uuid;\n  /**\n   * When this activity was originally created in its source system.\n   *\n   * For activities created in Plot, this is when the user created it.\n   * For activities synced from external systems (GitHub issues, emails, calendar events),\n   * this is the original creation time in that system.\n   *\n   * Defaults to the current time when creating new activities.\n   */\n  created: Date;\n  /** Information about who created the activity */\n  author: Actor;\n  /** Whether this activity is private (only visible to author) */\n  private: boolean;\n  /** Whether this activity has been archived */\n  archived: boolean;\n  /** Tags attached to this activity. Maps tag ID to array of actor IDs who added that tag. */\n  tags: Tags;\n  /** Array of actor IDs (users, contacts, or twists) mentioned in this activity via @-mentions */\n  mentions: ActorId[];\n};\n\n/**\n * Common fields shared by all activity types (Note, Action, Event).\n * Does not include the discriminant `type` field or type-specific fields like `done`.\n */\ntype ActivityFields = ActivityCommon & {\n  /**\n   * Globally unique, stable identifier for the item in an external system.\n   * MUST use immutable system-generated IDs, not human-readable slugs or titles.\n   *\n   * Recommended format: `${domain}:${type}:${id}`\n   *\n   * Examples:\n   *   - `linear:issue:549dd8bd-2bc9-43d1-95d5-4b4af0c5af1b` (Linear issue by UUID)\n   *   - `jira:10001:issue:12345` (Jira issue by numeric ID with cloud ID)\n   *   - `gmail:thread:18d4e5f2a3b1c9d7` (Gmail thread by system ID)\n   *\n   * \u26A0\uFE0F AVOID: URLs with mutable components like team names or issue keys\n   *   - Bad: `https://linear.app/team/issue/TEAM-123/title` (team and title can change)\n   *   - Bad: `jira:issue:PROJECT-42` (issue key can change)\n   *\n   * When set, uniquely identifies the activity within a priority tree for upsert operations.\n   */\n  source: string | null;\n  /** The display title/summary of the activity */\n  title: string;\n  /** Optional kind for additional categorization within the activity */\n  kind: ActivityKind | null;\n  /**\n   * The actor assigned to this activity.\n   *\n   * **For actions (tasks):**\n   * - If not provided (undefined), defaults to the user who installed the twist (twist owner)\n   * - To create an **unassigned action**, explicitly set `assignee: null`\n   * - For synced tasks from external systems, typically set `assignee: null` for unassigned items\n   *\n   * **For notes and events:** Assignee is optional and typically null.\n   * When marking an activity as done, it becomes an Action; if no assignee is set,\n   * the twist owner is assigned automatically.\n   *\n   * @example\n   * ```typescript\n   * // Create action assigned to twist owner (default behavior)\n   * const task: NewActivity = {\n   *   type: ActivityType.Action,\n   *   title: \"Follow up on email\"\n   *   // assignee omitted \u2192 defaults to twist owner\n   * };\n   *\n   * // Create UNASSIGNED action (for backlog items)\n   * const backlogTask: NewActivity = {\n   *   type: ActivityType.Action,\n   *   title: \"Review PR #123\",\n   *   assignee: null  // Explicitly set to null\n   * };\n   *\n   * // Create action with explicit assignee\n   * const assignedTask: NewActivity = {\n   *   type: ActivityType.Action,\n   *   title: \"Deploy to production\",\n   *   assignee: {\n   *     id: userId as ActorId,\n   *     type: ActorType.User,\n   *     name: \"Alice\"\n   *   }\n   * };\n   * ```\n   */\n  assignee: Actor | null;\n  /**\n   * Start time of a scheduled activity. Notes are not typically scheduled unless they're about specific times.\n   * For recurring events, this represents the start of the first occurrence.\n   * Can be a Date object for timed events or a date string in \"YYYY-MM-DD\" format for all-day events.\n   *\n   * **Activity Scheduling States** (for Actions):\n   * - **Do Now** (current/actionable): When creating an Action, omitting `start` defaults to current time\n   * - **Do Later** (future scheduled): Set `start` to a future Date or date string\n   * - **Do Someday** (unscheduled backlog): Explicitly set `start: null`\n   *\n   * **Important for synced tasks**: When syncing unassigned backlog items from external systems,\n   * set BOTH `start: null` AND `assignee: null` to create unscheduled, unassigned actions.\n   *\n   * @example\n   * ```typescript\n   * // \"Do Now\" - assigned to twist owner, actionable immediately\n   * await this.tools.plot.createActivity({\n   *   type: ActivityType.Action,\n   *   title: \"Urgent task\"\n   *   // start omitted \u2192 defaults to now\n   *   // assignee omitted \u2192 defaults to twist owner\n   * });\n   *\n   * // \"Do Later\" - scheduled for a specific time\n   * await this.tools.plot.createActivity({\n   *   type: ActivityType.Action,\n   *   title: \"Future task\",\n   *   start: new Date(\"2025-02-01\")\n   * });\n   *\n   * // \"Do Someday\" - unassigned backlog item (common for synced tasks)\n   * await this.tools.plot.createActivity({\n   *   type: ActivityType.Action,\n   *   title: \"Backlog task\",\n   *   start: null,      // Explicitly unscheduled\n   *   assignee: null    // Explicitly unassigned\n   * });\n   * ```\n   */\n  start: Date | string | null;\n  /**\n   * End time of a scheduled activity. Notes are not typically scheduled unless they're about specific times.\n   * For recurring events, this represents the end of the first occurrence.\n   * Can be a Date object for timed events or a date string in \"YYYY-MM-DD\" format for all-day events.\n   * Null for tasks or activities without defined end times.\n   */\n  end: Date | string | null;\n  /**\n   * For recurring activities, the last occurrence date (inclusive).\n   * Can be a Date object, date string in \"YYYY-MM-DD\" format, or null if recurring indefinitely.\n   * When both recurrenceCount and recurrenceUntil are provided, recurrenceCount takes precedence.\n   */\n  recurrenceUntil: Date | string | null;\n  /**\n   * For recurring activities, the number of occurrences to generate.\n   * Takes precedence over recurrenceUntil if both are provided.\n   * Null for non-recurring activities or indefinite recurrence.\n   */\n  recurrenceCount: number | null;\n  /** The priority context this activity belongs to */\n  priority: Priority;\n  /** Recurrence rule in RFC 5545 RRULE format (e.g., \"FREQ=WEEKLY;BYDAY=MO,WE,FR\") */\n  recurrenceRule: string | null;\n  /** Array of dates to exclude from the recurrence pattern */\n  recurrenceExdates: Date[] | null;\n  /** Metadata about the activity, typically from an external system that created it */\n  meta: ActivityMeta | null;\n};\n\nexport type Activity = ActivityFields &\n  (\n    | { type: ActivityType.Note }\n    | {\n        type: ActivityType.Action;\n        /**\n         * Timestamp when the activity was marked as complete. Null if not completed.\n         */\n        done: Date | null;\n      }\n    | { type: ActivityType.Event }\n  );\n\nexport type ActivityWithNotes = Activity & {\n  notes: Note[];\n};\n\nexport type NewActivityWithNotes = NewActivity & {\n  notes: Omit<NewNote, \"activity\">[];\n};\n\n/**\n * Represents a specific instance of a recurring activity.\n * All field values are computed by merging the recurring activity's\n * defaults with any occurrence-specific overrides.\n */\nexport type ActivityOccurrence = {\n  /**\n   * Original date/datetime of this occurrence.\n   * Use start for the occurrence's current start time.\n   * Format: Date object or \"YYYY-MM-DD\" for all-day events.\n   */\n  occurrence: Date | string;\n\n  /**\n   * The recurring activity of which this is an occurrence.\n   */\n  activity: Activity;\n\n  /**\n   * Effective values for this occurrence (series defaults + overrides).\n   * These are the actual values that apply to this specific instance.\n   */\n  start: Date | string;\n  end: Date | string | null;\n  done: Date | null;\n  title: string;\n  /**\n   * Meta is merged, with the occurrence's meta taking precedence.\n   */\n  meta: ActivityMeta | null;\n\n  /**\n   * Tags for this occurrence (merged with the recurring tags).\n   */\n  tags: Tags;\n\n  /**\n   * True if the occurrence is archived.\n   */\n  archived: boolean;\n};\n\n/**\n * Type for creating or updating activity occurrences.\n *\n * Follows the same pattern as Activity/NewActivity:\n * - Required fields: `occurrence` (key) and `start` (for scheduling)\n * - Optional fields: All others from ActivityOccurrence\n * - Additional fields: `twistTags` for add/remove, `unread` for notification control\n *\n * @example\n * ```typescript\n * const activity: NewActivity = {\n *   type: ActivityType.Event,\n *   recurrenceRule: \"FREQ=WEEKLY;BYDAY=MO\",\n *   occurrences: [\n *     {\n *       occurrence: new Date(\"2025-01-27T14:00:00Z\"),\n *       start: new Date(\"2025-01-27T14:00:00Z\"),\n *       tags: { [Tag.Skip]: [user] }\n *     }\n *   ]\n * };\n * ```\n */\nexport type NewActivityOccurrence = Pick<\n  ActivityOccurrence,\n  \"occurrence\" | \"start\"\n> &\n  Partial<\n    Omit<ActivityOccurrence, \"occurrence\" | \"start\" | \"activity\" | \"tags\">\n  > & {\n    /**\n     * Tags specific to this occurrence.\n     * These replace any recurrence-level tags for this occurrence.\n     */\n    tags?: NewTags;\n\n    /**\n     * Add or remove the twist's tags on this occurrence.\n     * Maps tag ID to boolean: true = add tag, false = remove tag.\n     */\n    twistTags?: Partial<Record<Tag, boolean>>;\n\n    /**\n     * Whether this occurrence should be marked as unread for users.\n     * - undefined/omitted (default): Occurrence is unread for users, except auto-marked\n     *   as read for the author if they are the twist owner (user)\n     * - true: Occurrence is explicitly unread for ALL users (use sparingly)\n     * - false: Occurrence is marked as read for all users\n     *\n     * For the default behavior, omit this field entirely.\n     * Use false for initial sync to avoid marking historical items as unread.\n     */\n    unread?: boolean;\n  };\n\n/**\n * Inline type for creating/updating occurrences within NewActivity/ActivityUpdate.\n * Used to specify occurrence-specific overrides when creating or updating a recurring activity.\n */\nexport type ActivityOccurrenceUpdate = Pick<\n  NewActivityOccurrence,\n  \"occurrence\"\n> &\n  Partial<Omit<NewActivityOccurrence, \"occurrence\" | \"activity\">>;\n\n/**\n * Configuration for automatic priority selection based on activity similarity.\n *\n * Maps activity fields to scoring weights or required exact matches:\n * - Number value: Maximum score for similarity matching on this field\n * - `true` value: Required exact match - activities must match exactly or be excluded\n *\n * Scoring rules:\n * - content: Uses vector similarity on activity embedding (cosine similarity)\n * - type: Exact match on ActivityType\n * - mentions: Percentage of existing activity's mentions that appear in new activity\n * - meta.field: Exact match on top-level meta fields (e.g., \"meta.sourceId\")\n *\n * When content is `true`, applies a strong similarity threshold to ensure only close matches.\n * Default (when neither priority nor pickPriority specified): `{content: true}`\n *\n * @example\n * ```typescript\n * // Require exact content match with strong similarity\n * pickPriority: { content: true }\n *\n * // Score based on content (max 100 points) and require exact type match\n * pickPriority: { content: 100, type: true }\n *\n * // Match on meta and score content\n * pickPriority: { \"meta.projectId\": true, content: 50 }\n * ```\n */\nexport type PickPriorityConfig = {\n  content?: number | true;\n  type?: number | true;\n  mentions?: number | true;\n  [key: `meta.${string}`]: number | true;\n};\n\n/**\n * Type for creating new activities.\n *\n * Requires only the activity type, with all other fields optional.\n * The author will be automatically assigned by the Plot system based on\n * the current execution context. The ID can be optionally provided by\n * tools for tracking and update detection purposes.\n *\n * **Important: Defaults for Actions**\n *\n * When creating an Activity of type `Action`:\n * - **`start` omitted** \u2192 Defaults to current time (now) \u2192 \"Do Now\"\n * - **`assignee` omitted** \u2192 Defaults to twist owner \u2192 Assigned action\n *\n * To create unassigned backlog items (common for synced tasks), you MUST explicitly set BOTH:\n * - `start: null` \u2192 \"Do Someday\" (unscheduled)\n * - `assignee: null` \u2192 Unassigned\n *\n * **Scheduling States**:\n * - **\"Do Now\"** (actionable today): Omit `start` or set to current time\n * - **\"Do Later\"** (scheduled): Set `start` to a future Date\n * - **\"Do Someday\"** (backlog): Set `start: null`\n *\n * Priority can be specified in three ways:\n * 1. Explicit priority: `priority: { id: \"...\" }` - Use specific priority (disables pickPriority)\n * 2. Pick priority config: `pickPriority: { ... }` - Auto-select based on similarity\n * 3. Neither: Defaults to `pickPriority: { content: true }` for automatic matching\n *\n * @example\n * ```typescript\n * // \"Do Now\" - Assigned to twist owner, actionable immediately\n * const urgentTask: NewActivity = {\n *   type: ActivityType.Action,\n *   title: \"Review pull request\"\n *   // start omitted \u2192 defaults to now\n *   // assignee omitted \u2192 defaults to twist owner\n * };\n *\n * // \"Do Someday\" - UNASSIGNED backlog item (for synced tasks)\n * const backlogTask: NewActivity = {\n *   type: ActivityType.Action,\n *   title: \"Refactor user service\",\n *   start: null,      // Must explicitly set to null\n *   assignee: null    // Must explicitly set to null\n * };\n *\n * // \"Do Later\" - Scheduled for specific date\n * const futureTask: NewActivity = {\n *   type: ActivityType.Action,\n *   title: \"Prepare Q1 review\",\n *   start: new Date(\"2025-03-15\")\n * };\n *\n * // Note (typically unscheduled)\n * const note: NewActivity = {\n *   type: ActivityType.Note,\n *   title: \"Meeting notes\",\n *   content: \"Discussed Q4 roadmap...\",\n *   start: null  // Notes typically don't have scheduled times\n * };\n *\n * // Event (always has explicit start/end times)\n * const event: NewActivity = {\n *   type: ActivityType.Event,\n *   title: \"Team standup\",\n *   start: new Date(\"2025-01-15T10:00:00\"),\n *   end: new Date(\"2025-01-15T10:30:00\")\n * };\n * ```\n */\nexport type NewActivity = (\n  | { type: ActivityType.Note; done?: never }\n  | { type: ActivityType.Action; done?: Date | null }\n  | { type: ActivityType.Event; done?: never }\n) &\n  Partial<\n    Omit<\n      ActivityFields,\n      | \"author\"\n      | \"assignee\"\n      | \"priority\"\n      | \"tags\"\n      | \"mentions\"\n      | \"id\"\n      | \"source\"\n    >\n  > &\n  (\n    | {\n        /**\n         * Unique identifier for the activity, generated by Uuid.Generate().\n         * Specifying an ID allows tools to track and upsert activities.\n         */\n        id: Uuid;\n      }\n    | {\n        /**\n         * Canonical URL for the item in an external system.\n         * For example, https://acme.atlassian.net/browse/PROJ-42 could represent a Jira issue.\n         * When set, it uniquely identifies the activity within a priority tree. This performs\n         * an upsert.\n         */\n        source: string;\n      }\n    | {\n        /* Neither id nor source is required. An id will be generated and returned. */\n      }\n  ) &\n  (\n    | {\n        /** Explicit priority (required when specified) - disables automatic priority matching */\n        priority: Pick<Priority, \"id\">;\n      }\n    | {\n        /** Configuration for automatic priority selection based on similarity */\n        pickPriority?: PickPriorityConfig;\n      }\n  ) & {\n    /**\n     * The person that created the item. By default, it will be the twist itself.\n     */\n    author?: NewActor;\n\n    /**\n     * The person that assigned to the item.\n     */\n    assignee?: NewActor | null;\n\n    /**\n     * All tags to set on the new activity.\n     */\n    tags?: NewTags;\n\n    /**\n     * Whether the activity should be marked as unread for users.\n     * - undefined/omitted (default): Activity is unread for users, except auto-marked\n     *   as read for the author if they are the twist owner (user)\n     * - true: Activity is explicitly unread for ALL users (use sparingly)\n     * - false: Activity is marked as read for all users in the priority at creation time\n     *\n     * For the default behavior, omit this field entirely.\n     * Use false for initial sync to avoid marking historical items as unread.\n     */\n    unread?: boolean;\n\n    /**\n     * Whether the activity is archived.\n     * - true: Archive the activity\n     * - false: Unarchive the activity\n     * - undefined (default): Preserve current archive state\n     *\n     * Best practice: Set to false during initial syncs to ensure activities\n     * are unarchived. Omit during incremental syncs to preserve user's choice.\n     */\n    archived?: boolean;\n\n    /**\n     * Optional preview content for the activity. Can be Markdown formatted.\n     * The preview will be automatically generated from this content (truncated to 100 chars).\n     *\n     * - string: Use this content for preview generation\n     * - null: Explicitly disable preview (no preview will be shown)\n     * - undefined (default): Fall back to legacy behavior (generate from first note with content)\n     *\n     * This field is write-only and won't be returned when reading activities.\n     */\n    preview?: string | null;\n\n    /**\n     * Create or update specific occurrences of a recurring activity.\n     * Each entry specifies overrides for a specific occurrence.\n     *\n     * When occurrence matches the recurrence rule but only tags are specified,\n     * the occurrence is created with just tags in activity_tag.occurrence (no activity_exception).\n     *\n     * When any other field is specified, creates/updates an activity_exception row.\n     *\n     * @example\n     * ```typescript\n     * // Create recurring event with per-occurrence RSVPs\n     * const meeting: NewActivity = {\n     *   type: ActivityType.Event,\n     *   recurrenceRule: \"FREQ=WEEKLY;BYDAY=MO\",\n     *   start: new Date(\"2025-01-20T14:00:00Z\"),\n     *   duration: 1800000, // 30 minutes\n     *   occurrences: [\n     *     {\n     *       occurrence: new Date(\"2025-01-27T14:00:00Z\"),\n     *       tags: { [Tag.Skip]: [{ email: \"user@example.com\" }] }\n     *     },\n     *     {\n     *       occurrence: new Date(\"2025-02-03T14:00:00Z\"),\n     *       start: new Date(\"2025-02-03T15:00:00Z\"), // Reschedule this one\n     *       tags: { [Tag.Attend]: [{ email: \"user@example.com\" }] }\n     *     }\n     *   ]\n     * };\n     * ```\n     */\n    occurrences?: NewActivityOccurrence[];\n\n    /**\n     * Dates to add to the recurrence exclusion list.\n     * These are merged with existing exdates. Use this for incremental updates\n     * (e.g., cancelling a single occurrence) instead of replacing the full list.\n     */\n    addRecurrenceExdates?: Date[];\n\n    /**\n     * Dates to remove from the recurrence exclusion list.\n     * Use this to \"uncancel\" a previously excluded occurrence.\n     */\n    removeRecurrenceExdates?: Date[];\n  };\n\nexport type ActivityUpdate = (\n  | {\n      /**\n       * Unique identifier for the activity.\n       */\n      id: Uuid;\n    }\n  | {\n      /**\n       * Canonical URL for the item in an external system.\n       */\n      source: string;\n    }\n) &\n  Partial<\n    Pick<\n      ActivityFields,\n      | \"kind\"\n      | \"start\"\n      | \"end\"\n      | \"title\"\n      | \"assignee\"\n      | \"private\"\n      | \"archived\"\n      | \"meta\"\n      | \"recurrenceRule\"\n      | \"recurrenceExdates\"\n      | \"recurrenceUntil\"\n      | \"recurrenceCount\"\n    >\n  > & {\n    /** Update the type of the activity. */\n    type?: ActivityType;\n    /**\n     * Timestamp when the activity was marked as complete. Null if not completed.\n     * Setting done will automatically set the type to Action if not already.\n     */\n    done?: Date | null;\n    /**\n     * Tags to change on the activity. Use an empty array of NewActor to remove a tag.\n     * Use twistTags to add/remove the twist from tags to avoid clearing other actors' tags.\n     */\n    tags?: NewTags;\n\n    /**\n     * Add or remove the twist's tags.\n     * Maps tag ID to boolean: true = add tag, false = remove tag.\n     * This is allowed on all activities the twist has access to.\n     */\n    twistTags?: Partial<Record<Tag, boolean>>;\n\n    /**\n     * Optional preview content for the activity. Can be Markdown formatted.\n     * The preview will be automatically generated from this content (truncated to 100 chars).\n     *\n     * - string: Use this content for preview generation\n     * - null: Explicitly disable preview (no preview will be shown)\n     * - undefined (omitted): Preserve current preview value\n     *\n     * This field is write-only and won't be returned when reading activities.\n     */\n    preview?: string | null;\n\n    /**\n     * Create or update specific occurrences of this recurring activity.\n     * Each entry specifies overrides for a specific occurrence.\n     *\n     * Setting a field to null reverts it to the series default.\n     * Omitting a field leaves it unchanged.\n     *\n     * @example\n     * ```typescript\n     * // Update RSVPs for specific occurrences\n     * await plot.updateActivity({\n     *   id: meetingId,\n     *   occurrences: [\n     *     {\n     *       occurrence: new Date(\"2025-01-27T14:00:00Z\"),\n     *       tags: { [Tag.Skip]: [user] }\n     *     },\n     *     {\n     *       occurrence: new Date(\"2025-02-03T14:00:00Z\"),\n     *       tags: { [Tag.Attend]: [user] }\n     *     },\n     *     {\n     *       occurrence: new Date(\"2025-02-10T14:00:00Z\"),\n     *       archived: true  // Cancel this occurrence\n     *     }\n     *   ]\n     * });\n     * ```\n     */\n    occurrences?: (NewActivityOccurrence | ActivityOccurrenceUpdate)[];\n\n    /**\n     * Dates to add to the recurrence exclusion list.\n     * These are merged with existing exdates. Use this for incremental updates\n     * (e.g., cancelling a single occurrence) instead of replacing the full list.\n     */\n    addRecurrenceExdates?: Date[];\n\n    /**\n     * Dates to remove from the recurrence exclusion list.\n     * Use this to \"uncancel\" a previously excluded occurrence.\n     */\n    removeRecurrenceExdates?: Date[];\n  };\n\n/**\n * Represents a note within an activity.\n *\n * Notes contain the detailed content (note text, links) associated with an activity.\n * They are always ordered by creation time within their parent activity.\n */\nexport type Note = ActivityCommon & {\n  /**\n   * Globally unique, stable identifier for the note within its activity.\n   * Can be used to upsert without knowing the id.\n   *\n   * Use one of these patterns:\n   *   - Hardcoded semantic keys for fixed note types: \"description\", \"cancellation\"\n   *   - External service IDs for dynamic collections: `comment:${immutableId}`\n   *\n   * Examples:\n   *   - `\"description\"` (for a Jira issue's description note)\n   *   - `\"comment:12345\"` (for a specific comment by ID)\n   *   - `\"gmail:msg:18d4e5f2a3b1c9d7\"` (for a Gmail message within a thread)\n   *\n   * \u26A0\uFE0F Ensure IDs are immutable - avoid human-readable slugs or titles.\n   */\n  key: string | null;\n  /** The parent activity this note belongs to */\n  activity: Activity;\n  /** Primary content for the note (markdown) */\n  content: string | null;\n  /** Array of interactive links attached to the note */\n  links: Array<ActivityLink> | null;\n  /** The note this is a reply to, or null if not a reply */\n  reNote: { id: Uuid } | null;\n};\n\n/**\n * Type for creating new notes.\n *\n * Requires the activity reference, with all other fields optional.\n * Can provide id, key, or neither for note identification:\n * - id: Provide a specific UUID for the note\n * - key: Provide an external identifier for upsert within the activity\n * - neither: A new note with auto-generated UUID will be created\n */\nexport type NewNote = Partial<\n  Omit<Note, \"author\" | \"activity\" | \"tags\" | \"mentions\" | \"id\" | \"key\" | \"reNote\">\n> &\n  ({ id: Uuid } | { key: string } | {}) & {\n    /** Reference to the parent activity (required) */\n    activity:\n      | Pick<Activity, \"id\">\n      | {\n          source: string;\n        };\n\n    /**\n     * The person that created the item, or leave undefined to use the twist as author.\n     */\n    author?: NewActor;\n\n    /**\n     * Format of the note content. Determines how the note is processed:\n     * - 'text': Plain text that will be converted to markdown (auto-links URLs, preserves line breaks)\n     * - 'markdown': Already in markdown format (default, no conversion)\n     * - 'html': HTML content that will be converted to markdown\n     */\n    contentType?: ContentType;\n\n    /**\n     * Tags to change on the activity. Use an empty array of NewActor to remove a tag.\n     * Use twistTags to add/remove the twist from tags to avoid clearing other actors' tags.\n     */\n    tags?: NewTags;\n\n    /**\n     * Change the mentions on the note.\n     */\n    mentions?: NewActor[];\n\n    /**\n     * Whether the note should mark the parent activity as unread for users.\n     * - undefined/omitted (default): Activity is unread for users, except auto-marked\n     *   as read for the author if they are the twist owner (user)\n     * - true: Activity is explicitly unread for ALL users (use sparingly)\n     * - false: Activity is marked as read for all users in the priority at note creation time\n     *\n     * For the default behavior, omit this field entirely.\n     * Use false for initial sync to avoid marking historical items as unread.\n     */\n    unread?: boolean;\n\n    /**\n     * Reference to a parent note this note is a reply to.\n     * - `{ id }`: reply by UUID\n     * - `{ key }`: reply by key, resolved after creation (for batch ops)\n     * - `null`: explicitly not a reply\n     * - `undefined` (omitted): not a reply\n     */\n    reNote?: { id: Uuid } | { key: string } | null;\n  };\n\n/**\n * Type for updating existing notes.\n * Must provide either id or key to identify the note to update.\n */\nexport type NoteUpdate = ({ id: Uuid; key?: string } | { key: string }) &\n  Partial<Pick<Note, \"private\" | \"archived\" | \"content\" | \"links\" | \"reNote\">> & {\n    /**\n     * Format of the note content. Determines how the note is processed:\n     * - 'text': Plain text that will be converted to markdown (auto-links URLs, preserves line breaks)\n     * - 'markdown': Already in markdown format (default, no conversion)\n     * - 'html': HTML content that will be converted to markdown\n     */\n    contentType?: ContentType;\n\n    /**\n     * Tags to change on the note. Use an empty array of NewActor to remove a tag.\n     * Use twistTags to add/remove the twist from tags to avoid clearing other actors' tags.\n     */\n    tags?: NewTags;\n\n    /**\n     * Add or remove the twist's tags.\n     * Maps tag ID to boolean: true = add tag, false = remove tag.\n     * This is allowed on all notes the twist has access to.\n     */\n    twistTags?: Partial<Record<Tag, boolean>>;\n\n    /**\n     * Change the mentions on the note.\n     */\n    mentions?: NewActor[];\n  };\n\n/**\n * Represents an actor in Plot - a user, contact, or twist.\n *\n * Actors can be associated with activities as authors, assignees, or mentions.\n * The email field is only included when ContactAccess.Read permission is granted.\n *\n * @example\n * ```typescript\n * const actor: Actor = {\n *   id: \"f0ffd5f8-1635-4b13-9532-35f97446db90\" as ActorId,\n *   type: ActorType.Contact,\n *   email: \"john.doe@example.com\",  // Only if ContactAccess.Read\n *   name: \"John Doe\"\n * };\n * ```\n */\nexport type Actor = {\n  /** Unique identifier for the actor */\n  id: ActorId;\n  /** Type of actor (User, Contact, or Twist) */\n  type: ActorType;\n  /**\n   * Email address (only included with ContactAccess.Read permission).\n   * - `undefined`: No permission to read email\n   * - `null`: Permission granted but email not set\n   * - `string`: Email address\n   */\n  email?: string | null;\n  /**\n   * Display name.\n   * - `undefined`: Not included due to permissions\n   * - `null`: Not set\n   * - `string`: Display name\n   */\n  name?: string | null;\n};\n\n/**\n * An existing or new contact.\n */\nexport type NewActor =\n  | {\n      /** Unique identifier for the actor */\n      id: ActorId;\n    }\n  | NewContact;\n\n/**\n * Enumeration of author types that can create activities.\n *\n * The author type affects how activities are displayed and processed\n * within the Plot system.\n */\nexport enum ActorType {\n  /** Activities created by human users */\n  User,\n  /** Activities created by external contacts */\n  Contact,\n  /** Activities created by automated twists */\n  Twist,\n}\n\n/**\n * Represents contact information for creating a new contact.\n *\n * Contacts are used throughout Plot for representing people associated\n * with activities, such as event attendees or task assignees.\n *\n * @example\n * ```typescript\n * const newContact: NewContact = {\n *   email: \"john.doe@example.com\",\n *   name: \"John Doe\",\n *   avatar: \"https://avatar.example.com/john.jpg\"\n * };\n * ```\n */\nexport type NewContact = {\n  /** Email address of the contact (required) */\n  email: string;\n  /** Optional display name for the contact */\n  name?: string;\n  /** Optional avatar image URL for the contact */\n  avatar?: string;\n  /**\n   * External provider account source. Used for privacy compliance\n   * (e.g. Atlassian personal data reporting for GDPR account closure).\n   * Required for contacts sourced from providers that mandate personal data reporting.\n   */\n  source?: { provider: AuthProvider; accountId: string };\n};\n\nexport type ContentType = \"text\" | \"markdown\" | \"html\";\n";
+declare const _default: "import { type Tag } from \"./tag\";\nimport { type Callback } from \"./tools/callbacks\";\nimport { type AuthProvider } from \"./tools/integrations\";\nimport { type JSONValue } from \"./utils/types\";\nimport { Uuid } from \"./utils/uuid\";\n\nexport { Tag } from \"./tag\";\nexport { Uuid } from \"./utils/uuid\";\nexport { type JSONValue } from \"./utils/types\";\nexport { type AuthProvider } from \"./tools/integrations\";\n\n/**\n * @fileoverview\n * Core Plot entity types for working with activities, notes, priorities, and contacts.\n *\n * ## Type Pattern: Null vs Undefined Semantics\n *\n * Plot entity types use a consistent pattern to distinguish between missing, unset, and explicitly cleared values:\n *\n * ### Entity Types (Activity, Priority, Note, Actor)\n * - **Required fields**: No `?`, cannot be `undefined`\n *   - Example: `id: Uuid`, `type: ActivityType`\n * - **Nullable fields**: Use `| null` to allow explicit clearing\n *   - Example: `assignee: ActorId | null`, `done: Date | null`\n *   - `null` = field is explicitly unset/cleared\n *   - Non-null value = field has a value\n * - **Optional nullable fields**: Use `?` with `| null` for permission-based access\n *   - Example: `email?: string | null`, `name?: string | null`\n *   - `undefined` = field not included (e.g., no permission to access)\n *   - `null` = field included but not set\n *   - Value = field has a value\n *\n * ### New* Types (NewActivity, NewNote, NewPriority)\n * Used for creating or updating entities. Support partial updates by distinguishing omitted vs cleared fields:\n * - **Required fields**: Must be provided (no `?`)\n *   - Example: `type: ActivityType` in NewActivity\n * - **Optional fields**: Use `?` to make them optional\n *   - Example: `title?: string`, `author?: NewActor`\n *   - `undefined` (omitted) = don't set/update this field\n *   - Provided value = set/update this field\n * - **Optional nullable fields**: Use `?` with `| null` to support clearing\n *   - Example: `assignee?: NewActor | null`\n *   - `undefined` (omitted) = don't change assignee\n *   - `null` = clear the assignee\n *   - NewActor = set/update the assignee\n *\n * This pattern allows API consumers to:\n * 1. Omit fields they don't want to change (undefined)\n * 2. Explicitly clear fields by setting to null\n * 3. Set or update fields by providing values\n *\n * @example\n * ```typescript\n * // Creating a new activity\n * const newActivity: NewActivity = {\n *   type: ActivityType.Action,  // Required\n *   title: \"Review PR\",          // Optional, provided\n *   assignee: null,              // Optional nullable, explicitly clearing\n *   // priority is omitted (undefined), will auto-select or use default\n * };\n *\n * // Updating an activity - only change what's specified\n * const update: ActivityUpdate = {\n *   id: activityId,\n *   done: new Date(),       // Mark as done\n *   assignee: null,         // Clear assignee\n *   // title is omitted, won't be changed\n * };\n * ```\n */\n\n/**\n * Represents a unique user, contact, or twist in Plot.\n *\n * ActorIds are used throughout Plot for:\n * - Activity authors and assignees\n * - Tag creators (actor_id in activity_tag/note_tag)\n * - Mentions in activities and notes\n * - Any entity that can perform actions in Plot\n */\nexport type ActorId = string & { readonly __brand: \"ActorId\" };\n\n/**\n * Theme colors for priorities.\n */\nexport enum ThemeColor {\n  /** Catalyst - Green */\n  Catalyst = 0,\n  /** Call to Adventure - Blue */\n  CallToAdventure = 1,\n  /** Rising Action - Purple */\n  RisingAction = 2,\n  /** Momentum - Pink-Purple */\n  Momentum = 3,\n  /** Turning Point - Pink */\n  TurningPoint = 4,\n  /** Breakthrough - Orange */\n  Breakthrough = 5,\n  /** Climax - Olive */\n  Climax = 6,\n  /** Resolution - Blue-Gray */\n  Resolution = 7,\n}\n\n/**\n * Represents a priority context within Plot.\n *\n * Priorities are similar to projects in other apps. All Activity is in a Priority.\n * Priorities can be nested.\n */\nexport type Priority = {\n  /** Unique identifier for the priority */\n  id: Uuid;\n  /** Human-readable title for the priority */\n  title: string;\n  /** Whether this priority has been archived */\n  archived: boolean;\n  /**\n   * Optional key for referencing this priority.\n   * Keys are unique per priority tree (a user's personal priorities or the root of a shared priority).\n   */\n  key: string | null;\n  /** Optional theme color for the priority (0-7). If not set, inherits from parent or defaults to 7 (Resolution). */\n  color: ThemeColor | null;\n};\n\n/**\n * Type for creating new priorities.\n *\n * Supports multiple creation patterns:\n * - Provide a specific UUID for the priority\n * - Provide a key for upsert within the user's priorities\n * - Omit both to auto-generate a new UUID\n *\n * Optionally specify a parent priority by ID or key for hierarchical structures.\n */\nexport type NewPriority = Pick<Priority, \"title\"> &\n  Partial<Omit<Priority, \"id\" | \"title\">> &\n  (\n    | {\n        /**\n         * Unique identifier for the priority, generated by Uuid.Generate().\n         * Specifying an ID allows tools to track and upsert priorities.\n         */\n        id: Uuid;\n      }\n    | {\n        /**\n         * Unique key for the priority within the user's priorities.\n         * Can be used to upsert without knowing the UUID.\n         * For example, \"@plot\" identifies the Plot priority.\n         */\n        key: string;\n      }\n    | {\n        /* Neither id nor key is required. An id will be generated and returned. */\n      }\n  ) & {\n    /** Add the new priority as the child of another priority */\n    parent?: { id: Uuid } | { key: string };\n  };\n\n/**\n * Type for updating existing priorities.\n * Must provide either id or key to identify the priority to update.\n */\nexport type PriorityUpdate = ({ id: Uuid } | { key: string }) &\n  Partial<Pick<Priority, \"title\" | \"archived\">>;\n\n/**\n * Enumeration of supported activity types in Plot.\n *\n * Each activity type has different behaviors and rendering characteristics\n * within the Plot application.\n */\nexport enum ActivityType {\n  /** A note or piece of information without actionable requirements */\n  Note,\n  /** An actionable item that can be completed */\n  Action,\n  /** A scheduled occurrence with start and optional end time */\n  Event,\n}\n\n/**\n * Kinds of activities. Used only for visual categorization (icon).\n */\nexport enum ActivityKind {\n  document = \"document\", // any external document or item in an external system\n  messages = \"messages\", // emails and chat threads\n  meeting = \"meeting\", // in-person meeting\n  videoconference = \"videoconference\",\n  phone = \"phone\",\n  focus = \"focus\",\n  meal = \"meal\",\n  exercise = \"exercise\",\n  family = \"family\",\n  travel = \"travel\",\n  social = \"social\",\n  entertainment = \"entertainment\",\n}\n\n/**\n * Enumeration of supported activity link types.\n *\n * Different link types have different behaviors when clicked by users\n * and may require different rendering approaches.\n */\nexport enum ActivityLinkType {\n  /** External web links that open in browser */\n  external = \"external\",\n  /** Authentication flows for connecting services */\n  auth = \"auth\",\n  /** Callback links that trigger twist methods when clicked */\n  callback = \"callback\",\n  /** Video conferencing links with provider-specific handling */\n  conferencing = \"conferencing\",\n  /** File attachment links stored in R2 */\n  file = \"file\",\n}\n\n/**\n * Video conferencing providers for conferencing links.\n *\n * Used to identify the conferencing platform and provide\n * provider-specific UI elements (titles, icons, etc.).\n */\nexport enum ConferencingProvider {\n  /** Google Meet */\n  googleMeet = \"googleMeet\",\n  /** Zoom */\n  zoom = \"zoom\",\n  /** Microsoft Teams */\n  microsoftTeams = \"microsoftTeams\",\n  /** Cisco Webex */\n  webex = \"webex\",\n  /** Other or unknown conferencing provider */\n  other = \"other\",\n}\n\n/**\n * Represents a clickable link attached to an activity.\n *\n * Activity links are rendered as buttons that enable user interaction with activities.\n * Different link types have specific behaviors and required fields for proper functionality.\n *\n * @example\n * ```typescript\n * // External link - opens URL in browser\n * const externalLink: ActivityLink = {\n *   type: ActivityLinkType.external,\n *   title: \"Open in Google Calendar\",\n *   url: \"https://calendar.google.com/event/123\",\n * };\n *\n * // Conferencing link - opens video conference with provider info\n * const conferencingLink: ActivityLink = {\n *   type: ActivityLinkType.conferencing,\n *   url: \"https://meet.google.com/abc-defg-hij\",\n *   provider: ConferencingProvider.googleMeet,\n * };\n *\n * // Integrations link - initiates OAuth flow\n * const authLink: ActivityLink = {\n *   type: ActivityLinkType.auth,\n *   title: \"Continue with Google\",\n *   provider: AuthProvider.Google,\n *   scopes: [\"https://www.googleapis.com/auth/calendar.readonly\"],\n *   callback: \"callback-token-for-auth-completion\"\n * };\n *\n * // Callback link - triggers a twist method\n * const callbackLink: ActivityLink = {\n *   type: ActivityLinkType.callback,\n *   title: \"\uD83D\uDCC5 Primary Calendar\",\n *   token: \"callback-token-here\"\n * };\n * ```\n */\nexport type ActivityLink =\n  | {\n      /** External web link that opens in browser */\n      type: ActivityLinkType.external;\n      /** Display text for the link button */\n      title: string;\n      /** URL to open when clicked */\n      url: string;\n    }\n  | {\n      /** Video conferencing link with provider-specific handling */\n      type: ActivityLinkType.conferencing;\n      /** URL to join the conference */\n      url: string;\n      /** Conferencing provider for UI customization */\n      provider: ConferencingProvider;\n    }\n  | {\n      /** Authentication link that initiates an OAuth flow */\n      type: ActivityLinkType.auth;\n      /** Display text for the auth button */\n      title: string;\n      /** OAuth provider (e.g., \"google\", \"microsoft\") */\n      provider: string;\n      /** Array of OAuth scopes to request */\n      scopes: string[];\n      /** Callback token for auth completion notification */\n      callback: Callback;\n    }\n  | {\n      /** Callback link that triggers a twist method when clicked */\n      type: ActivityLinkType.callback;\n      /** Display text for the callback button */\n      title: string;\n      /** Token identifying the callback to execute */\n      callback: Callback;\n    }\n  | {\n      /** File attachment link stored in R2 */\n      type: ActivityLinkType.file;\n      /** Unique identifier for the stored file */\n      fileId: string;\n      /** Original filename */\n      fileName: string;\n      /** File size in bytes */\n      fileSize: number;\n      /** MIME type of the file */\n      mimeType: string;\n    };\n\n/**\n * Represents metadata about an activity, typically from an external system.\n *\n * Activity metadata enables storing additional information about activities,\n * which is useful for synchronization, linking back to external systems,\n * and storing tool-specific data.\n *\n * Must be valid JSON data (strings, numbers, booleans, null, objects, arrays).\n * Functions and other non-JSON values are not supported.\n *\n * @example\n * ```typescript\n * // Calendar event metadata\n * await plot.createActivity({\n *   type: ActivityType.Event,\n *   title: \"Team Meeting\",\n *   start: new Date(\"2024-01-15T10:00:00Z\"),\n *   meta: {\n *     calendarId: \"primary\",\n *     htmlLink: \"https://calendar.google.com/event/abc123\",\n *     conferenceData: { ... }\n *   }\n * });\n *\n * // Project issue metadata\n * await plot.createActivity({\n *   type: ActivityType.Action,\n *   title: \"Fix login bug\",\n *   meta: {\n *     projectId: \"TEAM\",\n *     issueNumber: 123,\n *     url: \"https://linear.app/team/issue/TEAM-123\"\n *   }\n * });\n * ```\n */\nexport type ActivityMeta = {\n  /** Source-specific properties and metadata */\n  [key: string]: JSONValue;\n};\n\n/**\n * Tags on an item, along with the actors who added each tag.\n */\nexport type Tags = { [K in Tag]?: ActorId[] };\n\n/**\n * A set of tags to add to an item, along with the actors adding each tag.\n */\nexport type NewTags = { [K in Tag]?: NewActor[] };\n\n/**\n * Common fields shared by both Activity and Note entities.\n */\nexport type ActivityCommon = {\n  /** Unique identifier for the activity */\n  id: Uuid;\n  /**\n   * When this activity was originally created in its source system.\n   *\n   * For activities created in Plot, this is when the user created it.\n   * For activities synced from external systems (GitHub issues, emails, calendar events),\n   * this is the original creation time in that system.\n   *\n   * Defaults to the current time when creating new activities.\n   */\n  created: Date;\n  /** Information about who created the activity */\n  author: Actor;\n  /** Whether this activity is private (only visible to author) */\n  private: boolean;\n  /** Whether this activity has been archived */\n  archived: boolean;\n  /** Tags attached to this activity. Maps tag ID to array of actor IDs who added that tag. */\n  tags: Tags;\n  /** Array of actor IDs (users, contacts, or twists) mentioned in this activity via @-mentions */\n  mentions: ActorId[];\n};\n\n/**\n * Common fields shared by all activity types (Note, Action, Event).\n * Does not include the discriminant `type` field or type-specific fields like `done`.\n */\ntype ActivityFields = ActivityCommon & {\n  /**\n   * Globally unique, stable identifier for the item in an external system.\n   * MUST use immutable system-generated IDs, not human-readable slugs or titles.\n   *\n   * Recommended format: `${domain}:${type}:${id}`\n   *\n   * Examples:\n   *   - `linear:issue:549dd8bd-2bc9-43d1-95d5-4b4af0c5af1b` (Linear issue by UUID)\n   *   - `jira:10001:issue:12345` (Jira issue by numeric ID with cloud ID)\n   *   - `gmail:thread:18d4e5f2a3b1c9d7` (Gmail thread by system ID)\n   *\n   * \u26A0\uFE0F AVOID: URLs with mutable components like team names or issue keys\n   *   - Bad: `https://linear.app/team/issue/TEAM-123/title` (team and title can change)\n   *   - Bad: `jira:issue:PROJECT-42` (issue key can change)\n   *\n   * When set, uniquely identifies the activity within a priority tree for upsert operations.\n   */\n  source: string | null;\n  /** The display title/summary of the activity */\n  title: string;\n  /** Optional kind for additional categorization within the activity */\n  kind: ActivityKind | null;\n  /**\n   * The actor assigned to this activity.\n   *\n   * **For actions (tasks):**\n   * - If not provided (undefined), defaults to the user who installed the twist (twist owner)\n   * - To create an **unassigned action**, explicitly set `assignee: null`\n   * - For synced tasks from external systems, typically set `assignee: null` for unassigned items\n   *\n   * **For notes and events:** Assignee is optional and typically null.\n   * When marking an activity as done, it becomes an Action; if no assignee is set,\n   * the twist owner is assigned automatically.\n   *\n   * @example\n   * ```typescript\n   * // Create action assigned to twist owner (default behavior)\n   * const task: NewActivity = {\n   *   type: ActivityType.Action,\n   *   title: \"Follow up on email\"\n   *   // assignee omitted \u2192 defaults to twist owner\n   * };\n   *\n   * // Create UNASSIGNED action (for backlog items)\n   * const backlogTask: NewActivity = {\n   *   type: ActivityType.Action,\n   *   title: \"Review PR #123\",\n   *   assignee: null  // Explicitly set to null\n   * };\n   *\n   * // Create action with explicit assignee\n   * const assignedTask: NewActivity = {\n   *   type: ActivityType.Action,\n   *   title: \"Deploy to production\",\n   *   assignee: {\n   *     id: userId as ActorId,\n   *     type: ActorType.User,\n   *     name: \"Alice\"\n   *   }\n   * };\n   * ```\n   */\n  assignee: Actor | null;\n  /**\n   * Start time of a scheduled activity. Notes are not typically scheduled unless they're about specific times.\n   * For recurring events, this represents the start of the first occurrence.\n   * Can be a Date object for timed events or a date string in \"YYYY-MM-DD\" format for all-day events.\n   *\n   * **Activity Scheduling States** (for Actions):\n   * - **Do Now** (current/actionable): When creating an Action, omitting `start` defaults to current time\n   * - **Do Later** (future scheduled): Set `start` to a future Date or date string\n   * - **Do Someday** (unscheduled backlog): Explicitly set `start: null`\n   *\n   * **Important for synced tasks**: When syncing unassigned backlog items from external systems,\n   * set BOTH `start: null` AND `assignee: null` to create unscheduled, unassigned actions.\n   *\n   * @example\n   * ```typescript\n   * // \"Do Now\" - assigned to twist owner, actionable immediately\n   * await this.tools.plot.createActivity({\n   *   type: ActivityType.Action,\n   *   title: \"Urgent task\"\n   *   // start omitted \u2192 defaults to now\n   *   // assignee omitted \u2192 defaults to twist owner\n   * });\n   *\n   * // \"Do Later\" - scheduled for a specific time\n   * await this.tools.plot.createActivity({\n   *   type: ActivityType.Action,\n   *   title: \"Future task\",\n   *   start: new Date(\"2025-02-01\")\n   * });\n   *\n   * // \"Do Someday\" - unassigned backlog item (common for synced tasks)\n   * await this.tools.plot.createActivity({\n   *   type: ActivityType.Action,\n   *   title: \"Backlog task\",\n   *   start: null,      // Explicitly unscheduled\n   *   assignee: null    // Explicitly unassigned\n   * });\n   * ```\n   */\n  start: Date | string | null;\n  /**\n   * End time of a scheduled activity. Notes are not typically scheduled unless they're about specific times.\n   * For recurring events, this represents the end of the first occurrence.\n   * Can be a Date object for timed events or a date string in \"YYYY-MM-DD\" format for all-day events.\n   * Null for tasks or activities without defined end times.\n   */\n  end: Date | string | null;\n  /**\n   * For recurring activities, the last occurrence date (inclusive).\n   * Can be a Date object, date string in \"YYYY-MM-DD\" format, or null if recurring indefinitely.\n   * When both recurrenceCount and recurrenceUntil are provided, recurrenceCount takes precedence.\n   */\n  recurrenceUntil: Date | string | null;\n  /**\n   * For recurring activities, the number of occurrences to generate.\n   * Takes precedence over recurrenceUntil if both are provided.\n   * Null for non-recurring activities or indefinite recurrence.\n   */\n  recurrenceCount: number | null;\n  /** The priority context this activity belongs to */\n  priority: Priority;\n  /** Recurrence rule in RFC 5545 RRULE format (e.g., \"FREQ=WEEKLY;BYDAY=MO,WE,FR\") */\n  recurrenceRule: string | null;\n  /** Array of dates to exclude from the recurrence pattern */\n  recurrenceExdates: Date[] | null;\n  /** Metadata about the activity, typically from an external system that created it */\n  meta: ActivityMeta | null;\n  /** Sort order for the activity (fractional positioning) */\n  order: number;\n};\n\nexport type Activity = ActivityFields &\n  (\n    | { type: ActivityType.Note }\n    | {\n        type: ActivityType.Action;\n        /**\n         * Timestamp when the activity was marked as complete. Null if not completed.\n         */\n        done: Date | null;\n      }\n    | { type: ActivityType.Event }\n  );\n\nexport type ActivityWithNotes = Activity & {\n  notes: Note[];\n};\n\nexport type NewActivityWithNotes = NewActivity & {\n  notes: Omit<NewNote, \"activity\">[];\n};\n\n/**\n * Represents a specific instance of a recurring activity.\n * All field values are computed by merging the recurring activity's\n * defaults with any occurrence-specific overrides.\n */\nexport type ActivityOccurrence = {\n  /**\n   * Original date/datetime of this occurrence.\n   * Use start for the occurrence's current start time.\n   * Format: Date object or \"YYYY-MM-DD\" for all-day events.\n   */\n  occurrence: Date | string;\n\n  /**\n   * The recurring activity of which this is an occurrence.\n   */\n  activity: Activity;\n\n  /**\n   * Effective values for this occurrence (series defaults + overrides).\n   * These are the actual values that apply to this specific instance.\n   */\n  start: Date | string;\n  end: Date | string | null;\n  done: Date | null;\n  title: string;\n  /**\n   * Meta is merged, with the occurrence's meta taking precedence.\n   */\n  meta: ActivityMeta | null;\n\n  /**\n   * Tags for this occurrence (merged with the recurring tags).\n   */\n  tags: Tags;\n\n  /**\n   * True if the occurrence is archived.\n   */\n  archived: boolean;\n};\n\n/**\n * Type for creating or updating activity occurrences.\n *\n * Follows the same pattern as Activity/NewActivity:\n * - Required fields: `occurrence` (key) and `start` (for scheduling)\n * - Optional fields: All others from ActivityOccurrence\n * - Additional fields: `twistTags` for add/remove, `unread` for notification control\n *\n * @example\n * ```typescript\n * const activity: NewActivity = {\n *   type: ActivityType.Event,\n *   recurrenceRule: \"FREQ=WEEKLY;BYDAY=MO\",\n *   occurrences: [\n *     {\n *       occurrence: new Date(\"2025-01-27T14:00:00Z\"),\n *       start: new Date(\"2025-01-27T14:00:00Z\"),\n *       tags: { [Tag.Skip]: [user] }\n *     }\n *   ]\n * };\n * ```\n */\nexport type NewActivityOccurrence = Pick<\n  ActivityOccurrence,\n  \"occurrence\" | \"start\"\n> &\n  Partial<\n    Omit<ActivityOccurrence, \"occurrence\" | \"start\" | \"activity\" | \"tags\">\n  > & {\n    /**\n     * Tags specific to this occurrence.\n     * These replace any recurrence-level tags for this occurrence.\n     */\n    tags?: NewTags;\n\n    /**\n     * Add or remove the twist's tags on this occurrence.\n     * Maps tag ID to boolean: true = add tag, false = remove tag.\n     */\n    twistTags?: Partial<Record<Tag, boolean>>;\n\n    /**\n     * Whether this occurrence should be marked as unread for users.\n     * - undefined/omitted (default): Occurrence is unread for users, except auto-marked\n     *   as read for the author if they are the twist owner (user)\n     * - true: Occurrence is explicitly unread for ALL users (use sparingly)\n     * - false: Occurrence is marked as read for all users\n     *\n     * For the default behavior, omit this field entirely.\n     * Use false for initial sync to avoid marking historical items as unread.\n     */\n    unread?: boolean;\n  };\n\n/**\n * Inline type for creating/updating occurrences within NewActivity/ActivityUpdate.\n * Used to specify occurrence-specific overrides when creating or updating a recurring activity.\n */\nexport type ActivityOccurrenceUpdate = Pick<\n  NewActivityOccurrence,\n  \"occurrence\"\n> &\n  Partial<Omit<NewActivityOccurrence, \"occurrence\" | \"activity\">>;\n\n/**\n * Configuration for automatic priority selection based on activity similarity.\n *\n * Maps activity fields to scoring weights or required exact matches:\n * - Number value: Maximum score for similarity matching on this field\n * - `true` value: Required exact match - activities must match exactly or be excluded\n *\n * Scoring rules:\n * - content: Uses vector similarity on activity embedding (cosine similarity)\n * - type: Exact match on ActivityType\n * - mentions: Percentage of existing activity's mentions that appear in new activity\n * - meta.field: Exact match on top-level meta fields (e.g., \"meta.sourceId\")\n *\n * When content is `true`, applies a strong similarity threshold to ensure only close matches.\n * Default (when neither priority nor pickPriority specified): `{content: true}`\n *\n * @example\n * ```typescript\n * // Require exact content match with strong similarity\n * pickPriority: { content: true }\n *\n * // Score based on content (max 100 points) and require exact type match\n * pickPriority: { content: 100, type: true }\n *\n * // Match on meta and score content\n * pickPriority: { \"meta.projectId\": true, content: 50 }\n * ```\n */\nexport type PickPriorityConfig = {\n  content?: number | true;\n  type?: number | true;\n  mentions?: number | true;\n  [key: `meta.${string}`]: number | true;\n};\n\n/**\n * Type for creating new activities.\n *\n * Requires only the activity type, with all other fields optional.\n * The author will be automatically assigned by the Plot system based on\n * the current execution context. The ID can be optionally provided by\n * tools for tracking and update detection purposes.\n *\n * **Important: Defaults for Actions**\n *\n * When creating an Activity of type `Action`:\n * - **`start` omitted** \u2192 Defaults to current time (now) \u2192 \"Do Now\"\n * - **`assignee` omitted** \u2192 Defaults to twist owner \u2192 Assigned action\n *\n * To create unassigned backlog items (common for synced tasks), you MUST explicitly set BOTH:\n * - `start: null` \u2192 \"Do Someday\" (unscheduled)\n * - `assignee: null` \u2192 Unassigned\n *\n * **Scheduling States**:\n * - **\"Do Now\"** (actionable today): Omit `start` or set to current time\n * - **\"Do Later\"** (scheduled): Set `start` to a future Date\n * - **\"Do Someday\"** (backlog): Set `start: null`\n *\n * Priority can be specified in three ways:\n * 1. Explicit priority: `priority: { id: \"...\" }` - Use specific priority (disables pickPriority)\n * 2. Pick priority config: `pickPriority: { ... }` - Auto-select based on similarity\n * 3. Neither: Defaults to `pickPriority: { content: true }` for automatic matching\n *\n * @example\n * ```typescript\n * // \"Do Now\" - Assigned to twist owner, actionable immediately\n * const urgentTask: NewActivity = {\n *   type: ActivityType.Action,\n *   title: \"Review pull request\"\n *   // start omitted \u2192 defaults to now\n *   // assignee omitted \u2192 defaults to twist owner\n * };\n *\n * // \"Do Someday\" - UNASSIGNED backlog item (for synced tasks)\n * const backlogTask: NewActivity = {\n *   type: ActivityType.Action,\n *   title: \"Refactor user service\",\n *   start: null,      // Must explicitly set to null\n *   assignee: null    // Must explicitly set to null\n * };\n *\n * // \"Do Later\" - Scheduled for specific date\n * const futureTask: NewActivity = {\n *   type: ActivityType.Action,\n *   title: \"Prepare Q1 review\",\n *   start: new Date(\"2025-03-15\")\n * };\n *\n * // Note (typically unscheduled)\n * const note: NewActivity = {\n *   type: ActivityType.Note,\n *   title: \"Meeting notes\",\n *   content: \"Discussed Q4 roadmap...\",\n *   start: null  // Notes typically don't have scheduled times\n * };\n *\n * // Event (always has explicit start/end times)\n * const event: NewActivity = {\n *   type: ActivityType.Event,\n *   title: \"Team standup\",\n *   start: new Date(\"2025-01-15T10:00:00\"),\n *   end: new Date(\"2025-01-15T10:30:00\")\n * };\n * ```\n */\nexport type NewActivity = (\n  | { type: ActivityType.Note; done?: never }\n  | { type: ActivityType.Action; done?: Date | null }\n  | { type: ActivityType.Event; done?: never }\n) &\n  Partial<\n    Omit<\n      ActivityFields,\n      \"author\" | \"assignee\" | \"priority\" | \"tags\" | \"mentions\" | \"id\" | \"source\"\n    >\n  > &\n  (\n    | {\n        /**\n         * Unique identifier for the activity, generated by Uuid.Generate().\n         * Specifying an ID allows tools to track and upsert activities.\n         */\n        id: Uuid;\n      }\n    | {\n        /**\n         * Canonical URL for the item in an external system.\n         * For example, https://acme.atlassian.net/browse/PROJ-42 could represent a Jira issue.\n         * When set, it uniquely identifies the activity within a priority tree. This performs\n         * an upsert.\n         */\n        source: string;\n      }\n    | {\n        /* Neither id nor source is required. An id will be generated and returned. */\n      }\n  ) &\n  (\n    | {\n        /** Explicit priority (required when specified) - disables automatic priority matching */\n        priority: Pick<Priority, \"id\">;\n      }\n    | {\n        /** Configuration for automatic priority selection based on similarity */\n        pickPriority?: PickPriorityConfig;\n      }\n  ) & {\n    /**\n     * The person that created the item. By default, it will be the twist itself.\n     */\n    author?: NewActor;\n\n    /**\n     * The person that assigned to the item.\n     */\n    assignee?: NewActor | null;\n\n    /**\n     * All tags to set on the new activity.\n     */\n    tags?: NewTags;\n\n    /**\n     * Whether the activity should be marked as unread for users.\n     * - undefined/omitted (default): Activity is unread for users, except auto-marked\n     *   as read for the author if they are the twist owner (user)\n     * - true: Activity is explicitly unread for ALL users (use sparingly)\n     * - false: Activity is marked as read for all users in the priority at creation time\n     *\n     * For the default behavior, omit this field entirely.\n     * Use false for initial sync to avoid marking historical items as unread.\n     */\n    unread?: boolean;\n\n    /**\n     * Whether the activity is archived.\n     * - true: Archive the activity\n     * - false: Unarchive the activity\n     * - undefined (default): Preserve current archive state\n     *\n     * Best practice: Set to false during initial syncs to ensure activities\n     * are unarchived. Omit during incremental syncs to preserve user's choice.\n     */\n    archived?: boolean;\n\n    /**\n     * Optional preview content for the activity. Can be Markdown formatted.\n     * The preview will be automatically generated from this content (truncated to 100 chars).\n     *\n     * - string: Use this content for preview generation\n     * - null: Explicitly disable preview (no preview will be shown)\n     * - undefined (default): Fall back to legacy behavior (generate from first note with content)\n     *\n     * This field is write-only and won't be returned when reading activities.\n     */\n    preview?: string | null;\n\n    /**\n     * Create or update specific occurrences of a recurring activity.\n     * Each entry specifies overrides for a specific occurrence.\n     *\n     * When occurrence matches the recurrence rule but only tags are specified,\n     * the occurrence is created with just tags in activity_tag.occurrence (no activity_exception).\n     *\n     * When any other field is specified, creates/updates an activity_exception row.\n     *\n     * @example\n     * ```typescript\n     * // Create recurring event with per-occurrence RSVPs\n     * const meeting: NewActivity = {\n     *   type: ActivityType.Event,\n     *   recurrenceRule: \"FREQ=WEEKLY;BYDAY=MO\",\n     *   start: new Date(\"2025-01-20T14:00:00Z\"),\n     *   duration: 1800000, // 30 minutes\n     *   occurrences: [\n     *     {\n     *       occurrence: new Date(\"2025-01-27T14:00:00Z\"),\n     *       tags: { [Tag.Skip]: [{ email: \"user@example.com\" }] }\n     *     },\n     *     {\n     *       occurrence: new Date(\"2025-02-03T14:00:00Z\"),\n     *       start: new Date(\"2025-02-03T15:00:00Z\"), // Reschedule this one\n     *       tags: { [Tag.Attend]: [{ email: \"user@example.com\" }] }\n     *     }\n     *   ]\n     * };\n     * ```\n     */\n    occurrences?: NewActivityOccurrence[];\n\n    /**\n     * Dates to add to the recurrence exclusion list.\n     * These are merged with existing exdates. Use this for incremental updates\n     * (e.g., cancelling a single occurrence) instead of replacing the full list.\n     */\n    addRecurrenceExdates?: Date[];\n\n    /**\n     * Dates to remove from the recurrence exclusion list.\n     * Use this to \"uncancel\" a previously excluded occurrence.\n     */\n    removeRecurrenceExdates?: Date[];\n  };\n\nexport type ActivityFilter = {\n  type?: ActorType;\n  meta?: {\n    [key: string]: JSONValue;\n  };\n};\n\n/**\n * Fields supported by bulk updates via `match`. Only simple scalar fields\n * that can be applied uniformly across many activities are included.\n */\ntype ActivityBulkUpdateFields = Partial<\n  Pick<ActivityFields, \"kind\" | \"title\" | \"private\" | \"archived\" | \"meta\" | \"order\">\n> & {\n  /** Update the type of all matching activities. */\n  type?: ActivityType;\n  /**\n   * Timestamp when the activities were marked as complete. Null to clear.\n   * Setting done will automatically set the type to Action if not already.\n   */\n  done?: Date | null;\n};\n\n/**\n * Fields supported by single-activity updates via `id` or `source`.\n * Includes all bulk fields plus scheduling, recurrence, tags, and occurrences.\n */\ntype ActivitySingleUpdateFields = ActivityBulkUpdateFields &\n  Partial<\n    Pick<\n      ActivityFields,\n      | \"start\"\n      | \"end\"\n      | \"assignee\"\n      | \"recurrenceRule\"\n      | \"recurrenceExdates\"\n      | \"recurrenceUntil\"\n      | \"recurrenceCount\"\n    >\n  > & {\n    /**\n     * Tags to change on the activity. Use an empty array of NewActor to remove a tag.\n     * Use twistTags to add/remove the twist from tags to avoid clearing other actors' tags.\n     */\n    tags?: NewTags;\n\n    /**\n     * Add or remove the twist's tags.\n     * Maps tag ID to boolean: true = add tag, false = remove tag.\n     * This is allowed on all activities the twist has access to.\n     */\n    twistTags?: Partial<Record<Tag, boolean>>;\n\n    /**\n     * Optional preview content for the activity. Can be Markdown formatted.\n     * The preview will be automatically generated from this content (truncated to 100 chars).\n     *\n     * - string: Use this content for preview generation\n     * - null: Explicitly disable preview (no preview will be shown)\n     * - undefined (omitted): Preserve current preview value\n     *\n     * This field is write-only and won't be returned when reading activities.\n     */\n    preview?: string | null;\n\n    /**\n     * Create or update specific occurrences of this recurring activity.\n     * Each entry specifies overrides for a specific occurrence.\n     *\n     * Setting a field to null reverts it to the series default.\n     * Omitting a field leaves it unchanged.\n     *\n     * @example\n     * ```typescript\n     * // Update RSVPs for specific occurrences\n     * await plot.updateActivity({\n     *   id: meetingId,\n     *   occurrences: [\n     *     {\n     *       occurrence: new Date(\"2025-01-27T14:00:00Z\"),\n     *       tags: { [Tag.Skip]: [user] }\n     *     },\n     *     {\n     *       occurrence: new Date(\"2025-02-03T14:00:00Z\"),\n     *       tags: { [Tag.Attend]: [user] }\n     *     },\n     *     {\n     *       occurrence: new Date(\"2025-02-10T14:00:00Z\"),\n     *       archived: true  // Cancel this occurrence\n     *     }\n     *   ]\n     * });\n     * ```\n     */\n    occurrences?: (NewActivityOccurrence | ActivityOccurrenceUpdate)[];\n\n    /**\n     * Dates to add to the recurrence exclusion list.\n     * These are merged with existing exdates. Use this for incremental updates\n     * (e.g., cancelling a single occurrence) instead of replacing the full list.\n     */\n    addRecurrenceExdates?: Date[];\n\n    /**\n     * Dates to remove from the recurrence exclusion list.\n     * Use this to \"uncancel\" a previously excluded occurrence.\n     */\n    removeRecurrenceExdates?: Date[];\n  };\n\nexport type ActivityUpdate =\n  | (({ id: Uuid } | { source: string }) & ActivitySingleUpdateFields)\n  | ({\n      /**\n       * Update all activities matching the specified criteria. Only activities\n       * that match all provided fields and were created by the twist will be updated.\n       */\n      match: ActivityFilter;\n    } & ActivityBulkUpdateFields);\n\n/**\n * Represents a note within an activity.\n *\n * Notes contain the detailed content (note text, links) associated with an activity.\n * They are always ordered by creation time within their parent activity.\n */\nexport type Note = ActivityCommon & {\n  /**\n   * Globally unique, stable identifier for the note within its activity.\n   * Can be used to upsert without knowing the id.\n   *\n   * Use one of these patterns:\n   *   - Hardcoded semantic keys for fixed note types: \"description\", \"cancellation\"\n   *   - External service IDs for dynamic collections: `comment:${immutableId}`\n   *\n   * Examples:\n   *   - `\"description\"` (for a Jira issue's description note)\n   *   - `\"comment:12345\"` (for a specific comment by ID)\n   *   - `\"gmail:msg:18d4e5f2a3b1c9d7\"` (for a Gmail message within a thread)\n   *\n   * \u26A0\uFE0F Ensure IDs are immutable - avoid human-readable slugs or titles.\n   */\n  key: string | null;\n  /** The parent activity this note belongs to */\n  activity: Activity;\n  /** Primary content for the note (markdown) */\n  content: string | null;\n  /** Array of interactive links attached to the note */\n  links: Array<ActivityLink> | null;\n  /** The note this is a reply to, or null if not a reply */\n  reNote: { id: Uuid } | null;\n};\n\n/**\n * Type for creating new notes.\n *\n * Requires the activity reference, with all other fields optional.\n * Can provide id, key, or neither for note identification:\n * - id: Provide a specific UUID for the note\n * - key: Provide an external identifier for upsert within the activity\n * - neither: A new note with auto-generated UUID will be created\n */\nexport type NewNote = Partial<\n  Omit<\n    Note,\n    \"author\" | \"activity\" | \"tags\" | \"mentions\" | \"id\" | \"key\" | \"reNote\"\n  >\n> &\n  ({ id: Uuid } | { key: string } | {}) & {\n    /** Reference to the parent activity (required) */\n    activity:\n      | Pick<Activity, \"id\">\n      | {\n          source: string;\n        };\n\n    /**\n     * The person that created the item, or leave undefined to use the twist as author.\n     */\n    author?: NewActor;\n\n    /**\n     * Format of the note content. Determines how the note is processed:\n     * - 'text': Plain text that will be converted to markdown (auto-links URLs, preserves line breaks)\n     * - 'markdown': Already in markdown format (default, no conversion)\n     * - 'html': HTML content that will be converted to markdown\n     */\n    contentType?: ContentType;\n\n    /**\n     * Tags to change on the activity. Use an empty array of NewActor to remove a tag.\n     * Use twistTags to add/remove the twist from tags to avoid clearing other actors' tags.\n     */\n    tags?: NewTags;\n\n    /**\n     * Change the mentions on the note.\n     */\n    mentions?: NewActor[];\n\n    /**\n     * Whether the note should mark the parent activity as unread for users.\n     * - undefined/omitted (default): Activity is unread for users, except auto-marked\n     *   as read for the author if they are the twist owner (user)\n     * - true: Activity is explicitly unread for ALL users (use sparingly)\n     * - false: Activity is marked as read for all users in the priority at note creation time\n     *\n     * For the default behavior, omit this field entirely.\n     * Use false for initial sync to avoid marking historical items as unread.\n     */\n    unread?: boolean;\n\n    /**\n     * Reference to a parent note this note is a reply to.\n     * - `{ id }`: reply by UUID\n     * - `{ key }`: reply by key, resolved after creation (for batch ops)\n     * - `null`: explicitly not a reply\n     * - `undefined` (omitted): not a reply\n     */\n    reNote?: { id: Uuid } | { key: string } | null;\n  };\n\n/**\n * Type for updating existing notes.\n * Must provide either id or key to identify the note to update.\n */\nexport type NoteUpdate = ({ id: Uuid; key?: string } | { key: string }) &\n  Partial<\n    Pick<Note, \"private\" | \"archived\" | \"content\" | \"links\" | \"reNote\">\n  > & {\n    /**\n     * Format of the note content. Determines how the note is processed:\n     * - 'text': Plain text that will be converted to markdown (auto-links URLs, preserves line breaks)\n     * - 'markdown': Already in markdown format (default, no conversion)\n     * - 'html': HTML content that will be converted to markdown\n     */\n    contentType?: ContentType;\n\n    /**\n     * Tags to change on the note. Use an empty array of NewActor to remove a tag.\n     * Use twistTags to add/remove the twist from tags to avoid clearing other actors' tags.\n     */\n    tags?: NewTags;\n\n    /**\n     * Add or remove the twist's tags.\n     * Maps tag ID to boolean: true = add tag, false = remove tag.\n     * This is allowed on all notes the twist has access to.\n     */\n    twistTags?: Partial<Record<Tag, boolean>>;\n\n    /**\n     * Change the mentions on the note.\n     */\n    mentions?: NewActor[];\n  };\n\n/**\n * Represents an actor in Plot - a user, contact, or twist.\n *\n * Actors can be associated with activities as authors, assignees, or mentions.\n * The email field is only included when ContactAccess.Read permission is granted.\n *\n * @example\n * ```typescript\n * const actor: Actor = {\n *   id: \"f0ffd5f8-1635-4b13-9532-35f97446db90\" as ActorId,\n *   type: ActorType.Contact,\n *   email: \"john.doe@example.com\",  // Only if ContactAccess.Read\n *   name: \"John Doe\"\n * };\n * ```\n */\nexport type Actor = {\n  /** Unique identifier for the actor */\n  id: ActorId;\n  /** Type of actor (User, Contact, or Twist) */\n  type: ActorType;\n  /**\n   * Email address (only included with ContactAccess.Read permission).\n   * - `undefined`: No permission to read email\n   * - `null`: Permission granted but email not set\n   * - `string`: Email address\n   */\n  email?: string | null;\n  /**\n   * Display name.\n   * - `undefined`: Not included due to permissions\n   * - `null`: Not set\n   * - `string`: Display name\n   */\n  name?: string | null;\n};\n\n/**\n * An existing or new contact.\n */\nexport type NewActor =\n  | {\n      /** Unique identifier for the actor */\n      id: ActorId;\n    }\n  | NewContact;\n\n/**\n * Enumeration of author types that can create activities.\n *\n * The author type affects how activities are displayed and processed\n * within the Plot system.\n */\nexport enum ActorType {\n  /** Activities created by human users */\n  User,\n  /** Activities created by external contacts */\n  Contact,\n  /** Activities created by automated twists */\n  Twist,\n}\n\n/**\n * Represents contact information for creating a new contact.\n *\n * Contacts are used throughout Plot for representing people associated\n * with activities, such as event attendees or task assignees.\n *\n * @example\n * ```typescript\n * const newContact: NewContact = {\n *   email: \"john.doe@example.com\",\n *   name: \"John Doe\",\n *   avatar: \"https://avatar.example.com/john.jpg\"\n * };\n * ```\n */\nexport type NewContact = {\n  /** Email address of the contact (required) */\n  email: string;\n  /** Optional display name for the contact */\n  name?: string;\n  /** Optional avatar image URL for the contact */\n  avatar?: string;\n  /**\n   * External provider account source. Used for privacy compliance\n   * (e.g. Atlassian personal data reporting for GDPR account closure).\n   * Required for contacts sourced from providers that mandate personal data reporting.\n   */\n  source?: { provider: AuthProvider; accountId: string };\n};\n\nexport type ContentType = \"text\" | \"markdown\" | \"html\";\n";
 export default _default;
 //# sourceMappingURL=plot.d.ts.map

package/dist/llm-docs/plot.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plot.d.ts","sourceRoot":"","sources":["../../src/llm-docs/plot.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;wBAEY,sg0CAAi7zC;AAAh8zC,wBAAi8zC"}
+{"version":3,"file":"plot.d.ts","sourceRoot":"","sources":["../../src/llm-docs/plot.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;wBAEY,6s1CAAwn1C;AAAvo1C,wBAAwo1C"}