@plotday/twister 0.48.0 → 0.49.0

package/dist/docs/media/AGENTS.md

@@ -1,28 +1,22 @@
 # Connector Development Guide
 
-This guide covers everything needed to build a Plot connector correctly.
+Covers everything needed to build a Plot connector correctly. For twists, see `../twister/cli/templates/AGENTS.template.md`. For navigation, `../AGENTS.md`. Type definitions with full JSDoc live in `../twister/src/tools/*.ts`.
 
-**For twist development**: See `../twister/cli/templates/AGENTS.template.md`
-**For general navigation**: See `../AGENTS.md`
-**For type definitions**: See `../twister/src/tools/*.ts` (comprehensive JSDoc)
-
-## Quick Start: Complete Connector Scaffold
-
-Every connector follows this structure:
+## Scaffold
 
 ```
 connectors/<name>/
   src/
-    index.ts              # Re-exports: export { default, ClassName } from "./class-file"
-    <class-name>.ts       # Main Connector class
-    <api-name>.ts         # (optional) Separate API client + transform functions
+    index.ts          # export { default, ConnectorName } from "./connector-name";
+    <connector-name>.ts
+    <api-name>.ts     # (optional)
   package.json
   tsconfig.json
   README.md
   LICENSE
 ```
 
-### package.json
+### package.json essentials
 
 ```json
 {
@@ -44,30 +38,18 @@ connectors/<name>/
     }
   },
   "files": ["dist", "README.md", "LICENSE"],
-  "scripts": {
-    "build": "tsc",
-    "clean": "rm -rf dist"
-  },
-  "dependencies": {
-    "@plotday/twister": "workspace:^"
-  },
-  "devDependencies": {
-    "typescript": "^5.9.3"
-  },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/plotday/plot.git",
-    "directory": "connectors/<name>"
-  },
+  "scripts": { "build": "tsc", "clean": "rm -rf dist" },
+  "dependencies": { "@plotday/twister": "workspace:^" },
+  "devDependencies": { "typescript": "^5.9.3" },
+  "repository": { "type": "git", "url": "https://github.com/plotday/plot.git", "directory": "connectors/<name>" },
   "homepage": "https://plot.day",
-  "keywords": ["plot", "connector", "<name>"],
+  "keywords": ["plot", "connector", "<name>"]
 }
 ```
 
-**Notes:**
-- `"@plotday/connector"` export condition resolves to TypeScript source during workspace development
-- Add third-party SDKs to `dependencies` (e.g., `"@linear/sdk": "^72.0.0"`)
-- Add `@plotday/connector-google-contacts` as `"workspace:^"` if your connector syncs contacts (Google connectors only)
+- `"@plotday/connector"` export condition resolves to TS source during workspace dev.
+- Add third-party SDKs to `dependencies` (e.g. `"@linear/sdk": "^72.0.0"`).
+- Add `@plotday/connector-google-contacts` as `"workspace:^"` if you sync contacts (Google connectors only).
 
 ### tsconfig.json
 
@@ -75,60 +57,35 @@ connectors/<name>/
 {
   "$schema": "https://json.schemastore.org/tsconfig",
   "extends": "@plotday/twister/tsconfig.base.json",
-  "compilerOptions": {
-    "outDir": "./dist"
-  },
+  "compilerOptions": { "outDir": "./dist" },
   "include": ["src/**/*.ts"]
 }
 ```
 
-### src/index.ts
-
-```typescript
-export { default, ConnectorName } from "./connector-name";
-```
+## Class skeleton
 
-## Connector Class Template
+Use `connectors/linear/` as the canonical reference. Minimum shape:
 
 ```typescript
 import {
-  ActivityType,
-  LinkType,
-  type NewActivity,
-  type NewActivityWithNotes,
-  type NewNote,
-  type SyncToolOptions,
-  Connector,
-  type ConnectorBuilder,
+  ActivityType, LinkType, Connector,
+  type NewActivityWithNotes, type SyncToolOptions, type ConnectorBuilder,
 } from "@plotday/twister";
-import type { NewContact } from "@plotday/twister/plot";
 import { type Callback, Callbacks } from "@plotday/twister/tools/callbacks";
 import {
-  AuthProvider,
-  type AuthToken,
-  type Authorization,
-  Integrations,
-  type Channel,
+  AuthProvider, Integrations,
+  type AuthToken, type Authorization, type Channel,
 } from "@plotday/twister/tools/integrations";
 import { Network, type WebhookRequest } from "@plotday/twister/tools/network";
 import { Tasks } from "@plotday/twister/tools/tasks";
 
-type SyncState = {
-  cursor: string | null;
-  batchNumber: number;
-  itemsProcessed: number;
-  initialSync: boolean;
-};
-
 export class MyConnector extends Connector<MyConnector> {
-  // 1. Static constants
-  static readonly PROVIDER = AuthProvider.Linear; // Use appropriate provider
+  static readonly PROVIDER = AuthProvider.Linear;
   static readonly SCOPES = ["read", "write"];
   static readonly Options: SyncToolOptions;
-  static readonly handleReplies = true; // Enable @-mentions on replies to synced threads
+  static readonly handleReplies = true; // only for bidirectional connectors
   declare readonly Options: SyncToolOptions;
 
-  // 2. Declare dependencies
   build(build: ConnectorBuilder) {
     return {
       integrations: build(Integrations, {
@@ -146,860 +103,426 @@ export class MyConnector extends Connector<MyConnector> {
     };
   }
 
-  // 3. Create API client using channel-based auth
-  private async getClient(channelId: string): Promise<any> {
-    const token = await this.tools.integrations.get(MyConnector.PROVIDER, channelId);
-    if (!token) throw new Error("No authentication token available");
-    return new SomeApiClient({ accessToken: token.token });
-  }
-
-  // 4. Return available resources for the user to select
-  async getChannels(_auth: Authorization, token: AuthToken): Promise<Channel[]> {
-    const client = new SomeApiClient({ accessToken: token.token });
-    const resources = await client.listResources();
-    return resources.map(r => ({ id: r.id, title: r.name }));
-  }
+  async getChannels(_auth: Authorization, token: AuthToken): Promise<Channel[]> { /* list resources */ }
 
-  // 5. Called when user enables a resource
   async onChannelEnabled(channel: Channel): Promise<void> {
-    await this.set(`sync_enabled_${channel.id}`, true);
-
-    // Store parent callback tokens
-    const itemCallbackToken = await this.tools.callbacks.createFromParent(
-      this.options.onItem
-    );
-    await this.set(`item_callback_${channel.id}`, itemCallbackToken);
-
-    if (this.options.onChannelDisabled) {
-      const disableCallbackToken = await this.tools.callbacks.createFromParent(
-        this.options.onChannelDisabled,
-        { meta: { syncProvider: "myprovider", channelId: channel.id } }
-      );
-      await this.set(`disable_callback_${channel.id}`, disableCallbackToken);
-    }
-
-    // Queue webhook and sync as separate tasks — do NOT run inline,
-    // onChannelEnabled blocks the HTTP response until it returns
-    const webhookCallback = await this.callback(this.setupWebhook, channel.id);
-    await this.runTask(webhookCallback);
-    await this.startBatchSync(channel.id);
+    // 1. Store parent callback tokens via tools.callbacks.createFromParent(this.options.onItem)
+    // 2. Queue webhook + initial sync as SEPARATE tasks via runTask() — never inline;
+    //    onChannelEnabled blocks the HTTP response until it returns.
   }
 
-  // 6. Called when user disables a resource
   async onChannelDisabled(channel: Channel): Promise<void> {
-    await this.stopSync(channel.id);
-
-    const disableCallbackToken = await this.get<Callback>(`disable_callback_${channel.id}`);
-    if (disableCallbackToken) {
-      await this.tools.callbacks.run(disableCallbackToken);
-      await this.tools.callbacks.delete(disableCallbackToken);
-      await this.clear(`disable_callback_${channel.id}`);
-    }
-
-    const itemCallbackToken = await this.get<Callback>(`item_callback_${channel.id}`);
-    if (itemCallbackToken) {
-      await this.tools.callbacks.delete(itemCallbackToken);
-      await this.clear(`item_callback_${channel.id}`);
-    }
-
-    await this.clear(`sync_enabled_${channel.id}`);
-  }
-
-  // 7. Public interface methods (from common interface)
-  async getProjects(projectId: string): Promise<any[]> {
-    const client = await this.getClient(projectId);
-    const projects = await client.listProjects();
-    return projects.map(p => ({
-      id: p.id,
-      name: p.name,
-      description: p.description || null,
-      key: p.key || null,
-    }));
-  }
-
-  async startSync<TArgs extends any[], TCallback extends Function>(
-    options: { projectId: string },
-    callback: TCallback,
-    ...extraArgs: TArgs
-  ): Promise<void> {
-    const callbackToken = await this.tools.callbacks.createFromParent(callback, ...extraArgs);
-    await this.set(`item_callback_${options.projectId}`, callbackToken);
-    const webhookCallback = await this.callback(this.setupWebhook, options.projectId);
-    await this.runTask(webhookCallback);
-    await this.startBatchSync(options.projectId);
-  }
-
-  async stopSync(projectId: string): Promise<void> {
-    // Remove webhook
-    const webhookId = await this.get<string>(`webhook_id_${projectId}`);
-    if (webhookId) {
-      try {
-        const client = await this.getClient(projectId);
-        await client.deleteWebhook(webhookId);
-      } catch (error) {
-        console.warn("Failed to delete webhook:", error);
-      }
-      await this.clear(`webhook_id_${projectId}`);
-    }
-
-    // Cleanup callbacks
-    const itemCallbackToken = await this.get<Callback>(`item_callback_${projectId}`);
-    if (itemCallbackToken) {
-      await this.deleteCallback(itemCallbackToken);
-      await this.clear(`item_callback_${projectId}`);
-    }
-
-    await this.clear(`sync_state_${projectId}`);
-  }
-
-  // 8. Webhook setup (non-private so it can be used with this.callback())
-  async setupWebhook(resourceId: string): Promise<void> {
-    try {
-      const webhookUrl = await this.tools.network.createWebhook(
-        {},
-        this.onWebhook,
-        resourceId
-      );
-
-      // REQUIRED: Skip webhook registration in development
-      if (webhookUrl.includes("localhost") || webhookUrl.includes("127.0.0.1")) {
-        return;
-      }
-
-      const client = await this.getClient(resourceId);
-      const webhook = await client.createWebhook({ url: webhookUrl });
-      if (webhook?.id) {
-        await this.set(`webhook_id_${resourceId}`, webhook.id);
-      }
-    } catch (error) {
-      console.error("Failed to set up webhook:", error);
-    }
-  }
-
-  // 9. Batch sync
-  private async startBatchSync(resourceId: string): Promise<void> {
-    await this.set(`sync_state_${resourceId}`, {
-      cursor: null,
-      batchNumber: 1,
-      itemsProcessed: 0,
-      initialSync: true,
-    });
-
-    const batchCallback = await this.callback(this.syncBatch, resourceId);
-    await this.tools.tasks.runTask(batchCallback);
-  }
-
-  private async syncBatch(resourceId: string): Promise<void> {
-    const state = await this.get<SyncState>(`sync_state_${resourceId}`);
-    if (!state) throw new Error(`Sync state not found for ${resourceId}`);
-
-    const callbackToken = await this.get<Callback>(`item_callback_${resourceId}`);
-    if (!callbackToken) throw new Error(`Callback not found for ${resourceId}`);
-
-    const client = await this.getClient(resourceId);
-    const result = await client.listItems({ cursor: state.cursor, limit: 50 });
-
-    for (const item of result.items) {
-      const activity = this.transformItem(item, resourceId, state.initialSync);
-      // Inject sync metadata for bulk operations
-      activity.meta = {
-        ...activity.meta,
-        syncProvider: "myprovider",
-        channelId: resourceId,
-      };
-      await this.tools.callbacks.run(callbackToken, activity);
-    }
-
-    if (result.nextCursor) {
-      await this.set(`sync_state_${resourceId}`, {
-        cursor: result.nextCursor,
-        batchNumber: state.batchNumber + 1,
-        itemsProcessed: state.itemsProcessed + result.items.length,
-        initialSync: state.initialSync,
-      });
-      const nextBatch = await this.callback(this.syncBatch, resourceId);
-      await this.tools.tasks.runTask(nextBatch);
-    } else {
-      await this.clear(`sync_state_${resourceId}`);
-    }
-  }
-
-  // 10. Data transformation
-  private transformItem(item: any, resourceId: string, initialSync: boolean): NewActivityWithNotes {
-    return {
-      source: `myprovider:item:${item.id}`,  // Canonical source for upsert
-      type: ActivityType.Action,
-      title: item.title,
-      created: item.createdAt,
-      author: item.creator?.email ? {
-        email: item.creator.email,
-        name: item.creator.name,
-      } : undefined,
-      meta: {
-        externalId: item.id,
-        resourceId,
-      },
-      notes: [{
-        key: "description",  // Enables note upsert
-        content: item.description || null,
-        contentType: item.descriptionHtml ? "html" as const : "text" as const,
-        links: item.url ? [{
-          type: LinkType.external,
-          title: "Open in Service",
-          url: item.url,
-        }] : null,
-      }],
-      ...(initialSync ? { unread: false } : {}),
-      ...(initialSync ? { archived: false } : {}),
-    };
-  }
-
-  // 11. Webhook handler
-  private async onWebhook(request: WebhookRequest, resourceId: string): Promise<void> {
-    // Verify webhook signature (provider-specific)
-    // ...
-
-    const callbackToken = await this.get<Callback>(`item_callback_${resourceId}`);
-    if (!callbackToken) return;
-
-    const payload = JSON.parse(request.rawBody || "{}");
-    const activity = this.transformItem(payload.item, resourceId, false);
-    activity.meta = {
-      ...activity.meta,
-      syncProvider: "myprovider",
-      channelId: resourceId,
-    };
-    await this.tools.callbacks.run(callbackToken, activity);
+    // Delete webhook, delete callback tokens, clear() all per-channel state.
   }
 }
 
 export default MyConnector;
 ```
 
-## The Integrations Pattern (Auth + Channels)
-
-**This is how ALL authentication works.** Auth is handled in the Flutter edit modal, not in code. Connectors declare their provider config in `build()`.
-
-### How It Works
-
-1. Connector declares providers in `build()` with `getChannels`, `onChannelEnabled`, `onChannelDisabled` callbacks
-2. User clicks "Connect" in the twist edit modal → OAuth flow happens automatically
-3. After auth, the runtime calls your `getChannels()` to list available resources
-4. User enables resources in the modal → `onChannelEnabled()` fires
-5. User disables resources → `onChannelDisabled()` fires
-6. Get tokens via `this.tools.integrations.get(PROVIDER, channelId)`
-
-### Available Providers
+Required private helpers: `getClient(channelId)`, `setupWebhook(id)`, `startBatchSync(id)`, `syncBatch(id)`, `transformItem(item, id, initialSync)`, `onWebhook(req, id)`. See `linear/` for the full pattern.
 
-`AuthProvider` enum: `Google`, `Microsoft`, `Notion`, `Slack`, `Atlassian`, `Linear`, `Monday`, `GitHub`, `Asana`, `HubSpot`.
+## Integrations (auth + channels)
 
-### Per-User Auth for Write-Backs
+Auth is handled in the Flutter edit modal — you declare providers in `build()`, the runtime drives OAuth.
 
-For bidirectional sync where actions should be attributed to the acting user:
-
-```typescript
-await this.tools.integrations.actAs(
-  MyConnector.PROVIDER,
-  actorId,      // The user who performed the action
-  activityId,   // Activity to create auth prompt in (if user hasn't connected)
-  this.performWriteBack,
-  ...extraArgs
-);
-
-async performWriteBack(token: AuthToken, ...extraArgs: any[]): Promise<void> {
-  // token is the acting user's token
-  const client = new ApiClient({ accessToken: token.token });
-  await client.doSomething();
-}
-```
+1. User clicks "Connect" → OAuth runs automatically.
+2. Runtime calls your `getChannels()` to list resources.
+3. User enables → `onChannelEnabled()`. User disables → `onChannelDisabled()`.
+4. Read tokens via `this.tools.integrations.get(PROVIDER, channelId)`.
 
-### Cross-Connector Auth Sharing (Google Connectors)
+`AuthProvider` values: `Google`, `Microsoft`, `Notion`, `Slack`, `Atlassian`, `Linear`, `Monday`, `GitHub`, `Asana`, `HubSpot`.
 
-When building a Google connector that should also sync contacts, merge scopes:
+### Per-user auth for write-backs
 
 ```typescript
-import GoogleContacts from "@plotday/connector-google-contacts";
+await this.tools.integrations.actAs(MyConnector.PROVIDER, actorId, activityId, this.performWriteBack, ...args);
 
-build(build: ConnectorBuilder) {
-  return {
-    integrations: build(Integrations, {
-      providers: [{
-        provider: AuthProvider.Google,
-        scopes: Integrations.MergeScopes(
-          MyGoogleConnector.SCOPES,
-          GoogleContacts.SCOPES
-        ),
-        getChannels: this.getChannels,
-        onChannelEnabled: this.onChannelEnabled,
-        onChannelDisabled: this.onChannelDisabled,
-      }],
-    }),
-    googleContacts: build(GoogleContacts),
-    // ...
-  };
+async performWriteBack(token: AuthToken, ...args: any[]): Promise<void> {
+  // token is the acting user's token
 }
 ```
 
-## Architecture: Connectors Save Directly
-
-**Connectors save data directly** via `integrations.saveLink()`. Connectors build `NewLinkWithNotes` objects and save them, rather than passing them through a parent twist.
-
-This means:
-- Connectors request `Plot` with `ContactAccess.Write` (for contacts on threads)
-- Connectors declare providers via `Integrations` with lifecycle callbacks
-- Connectors call save methods directly to persist synced data
+### Cross-connector auth sharing (Google)
 
-## Critical: Callback Serialization Pattern
+Merge scopes with `Integrations.MergeScopes(MyGoogleConnector.SCOPES, GoogleContacts.SCOPES)` and add `googleContacts: build(GoogleContacts)` to your `build()` return.
 
-**The #1 mistake when building connectors is passing function references as callback arguments.** Functions cannot be serialized across worker boundaries.
+## Architecture
 
-### ❌ WRONG - Passing Function as Callback Argument
+Connectors persist data directly via `integrations.saveLink()` (building `NewLinkWithNotes`). They do not push through a parent twist, and should not call `plot.createThread()`.
 
-```typescript
-async startSync(callback: Function, ...extraArgs: any[]): Promise<void> {
-  // ❌ WRONG: callback is a function — NOT SERIALIZABLE!
-  await this.callback(this.syncBatch, callback, ...extraArgs);
-}
-```
+## Callback serialization (the #1 mistake)
 
-**Error:** `Cannot create callback args: Found function at path "value[0]"`
-
-### ✅ CORRECT - Store Token, Pass Primitives
+Functions are not serializable across worker boundaries. Convert to tokens, store primitives.
 
 ```typescript
-async startSync(resourceId: string, callback: Function, ...extraArgs: any[]): Promise<void> {
-  // Step 1: Convert function to token and STORE it
-  const callbackToken = await this.tools.callbacks.createFromParent(callback, ...extraArgs);
-  await this.set(`callback_${resourceId}`, callbackToken);
-
-  // Step 2: Pass ONLY serializable values to this.callback()
-  const batchCallback = await this.callback(this.syncBatch, resourceId);
-  await this.tools.tasks.runTask(batchCallback);
-}
+// ❌ WRONG — passing a function as a callback arg
+await this.callback(this.syncBatch, callback, ...extraArgs);
+// Error: Cannot create callback args: Found function at path "value[0]"
 
-async syncBatch(resourceId: string): Promise<void> {
-  // Step 3: Retrieve token from storage
-  const callbackToken = await this.get<Callback>(`callback_${resourceId}`);
-  if (!callbackToken) throw new Error(`Callback not found for ${resourceId}`);
+// ✅ CORRECT
+const token = await this.tools.callbacks.createFromParent(callback, ...extraArgs);
+await this.set(`callback_${resourceId}`, token);
+const batch = await this.callback(this.syncBatch, resourceId); // primitives only
+await this.tools.tasks.runTask(batch);
 
-  // Step 4: Fetch data and execute callback with result
-  const result = await this.fetchItems(resourceId);
-  for (const item of result.items) {
-    await this.tools.callbacks.run(callbackToken, item);
-  }
-}
+// In syncBatch:
+const token = await this.get<Callback>(`callback_${resourceId}`);
+if (!token) throw new Error(`Callback not found for ${resourceId}`);
+await this.tools.callbacks.run(token, item);
 ```
 
-### What's Serializable
-
-| ✅ Safe | ❌ NOT Serializable |
-|---------|---------------------|
-| Strings, numbers, booleans, null | Functions, `() => {}`, method refs |
-| Plain objects `{ key: "value" }` | `undefined` (use `null` instead) |
-| Arrays `[1, 2, 3]` | Symbols |
-| Dates (serialized via SuperJSON) | RPC stubs |
-| Callback tokens (branded strings) | Circular references |
+Serializable: strings, numbers, booleans, `null`, plain objects, arrays, Dates (SuperJSON), callback tokens.  
+Not serializable: functions, `undefined` (use `null`), symbols, RPC stubs, circular refs.
 
-## Callback Backward Compatibility
+## Callback backward compatibility
 
-**All callbacks automatically upgrade to new connector versions on deployment.** You MUST maintain backward compatibility.
+Deployed callbacks auto-upgrade to new connector versions. Signatures must stay compatible:
 
-- ❌ Don't change function signatures (remove/reorder params, change types)
-- ✅ Do add optional parameters at the end
-- ✅ Do handle both old and new data formats with version guards
+- ✅ Add optional params at the end with safe defaults.
+- ❌ Don't remove/reorder params or change existing types.
 
 ```typescript
-// v1.0 - Original
+// v1.0
 async syncBatch(batchNumber: number, resourceId: string) { ... }
-
-// v1.1 - ✅ GOOD: Optional parameter at end
+// v1.1 — safe
 async syncBatch(batchNumber: number, resourceId: string, initialSync?: boolean) {
-  const isInitial = initialSync ?? true; // Safe default for old callbacks
-}
-
-// v2.0 - ❌ BAD: Completely changed signature
-async syncBatch(options: SyncOptions) { ... }
-```
-
-For breaking changes, implement migration logic in `preUpgrade()`:
-
-```typescript
-async preUpgrade(): Promise<void> {
-  // Clean up stale locks from previous version
-  const keys = await this.list("sync_lock_");
-  for (const key of keys) {
-    await this.clear(key);
-  }
+  const isInitial = initialSync ?? true;
 }
 ```
 
-## Storage Key Conventions
+For breaking changes, do migration in `preUpgrade()` (e.g. clear stale locks).
 
-All connectors use consistent key prefixes:
+## Storage key conventions
 
-| Key Pattern | Purpose |
-|------------|---------|
-| `item_callback_<id>` | Serialized callback to parent's `onItem` |
-| `disable_callback_<id>` | Serialized callback to parent's `onChannelDisabled` |
+| Key | Purpose |
+|---|---|
+| `item_callback_<id>` | Token for parent's `onItem` |
+| `disable_callback_<id>` | Token for parent's `onChannelDisabled` |
 | `sync_state_<id>` | Current batch pagination state |
 | `sync_enabled_<id>` | Boolean tracking enabled state |
-| `webhook_id_<id>` | External webhook registration ID |
+| `webhook_id_<id>` | External webhook registration id |
 | `webhook_secret_<id>` | Webhook signing secret |
-| `watch_renewal_task_<id>` | Scheduled task token for webhook renewal |
-
-## Activity Source URL Conventions
-
-The `activity.source` field is the idempotency key for automatic upserts. Use a canonical format:
-
-```
-<provider>:<entity>:<id>        — Standard pattern
-<provider>:<namespace>:<id>     — When provider has multiple entity types
-```
+| `watch_renewal_task_<id>` | Scheduled task for webhook renewal |
 
-### Source identifier uniqueness (CRITICAL)
+## `source` — idempotency + cross-user dedup (CRITICAL)
 
-`source` is the **cross-user deduplication key** for the Plot runtime. Two instances of the same connector that emit the same `source` string will **converge on a single shared thread** across users — that's how two users on the same Gmail message see one shared thread rather than two parallel ones.
+`activity.source` / `link.source` is the upsert key AND the cross-user dedup key: two instances emitting the same `source` converge on a single shared thread across users (that's how two users on the same Gmail message share one thread).
 
-This means your `source` must be globally unique for the logical external item — not merely unique within a single user's account. Before committing a source pattern, ask yourself: *"Could two different users' connector instances emit this exact string for different external items?"* If yes, you must include a qualifier (workspace, tenant, mailbox, project, …).
+**Your `source` must be globally unique for the external item, not merely unique within a user's account.** If two different users' connectors could emit the same string for different items, include a qualifier (workspace, tenant, mailbox, project).
 
-Safe patterns (globally unique external ids):
+Safe (globally unique ids):
 ```
-linear:issue:<uuid>                           — Linear issue UUIDs are globally unique
-github:<owner>/<repo>/issue:<number>          — Scoped by owner+repo
-google-chat:<spaceId>:thread:<threadKey>      — Space id globally unique
-ms-teams:channel:<channelId>:message:<id>     — Teams channel id globally unique
-ms-teams:dm:<chatId>                          — Chat ids globally unique
-https://mail.google.com/mail/u/0/#inbox/<threadId>   — Gmail thread id globally unique
+linear:issue:<uuid>
+github:<owner>/<repo>/issue:<number>
+google-chat:<spaceId>:thread:<threadKey>
+ms-teams:channel:<channelId>:message:<id>
+ms-teams:dm:<chatId>
+https://mail.google.com/mail/u/0/#inbox/<threadId>
 ```
 
-Patterns that need disambiguation:
+Need disambiguation (scoped ids):
 ```
-attio:<workspaceId>:<type>:<recordId>         — Attio record ids are workspace-scoped
-posthog:<projectId>:person:<distinctId>       — distinct_id is project-scoped (often just an email)
-outlook-calendar:<mailboxId>:<eventId>        — Graph event ids are mailbox-local
-fellow:<tenantId>:note:<id>                   — Fellow ids are tenant-scoped
+attio:<workspaceId>:<type>:<recordId>
+posthog:<projectId>:person:<distinctId>
+outlook-calendar:<mailboxId>:<eventId>
+fellow:<tenantId>:note:<id>
 ```
 
-**If you're adding a new connector, pick a source format that encodes the tenant/workspace/mailbox upfront.** Retrofits are possible but require a backfill migration.
-
-**Mutable IDs:** For services where identifiers can change (like Jira issue keys that change on project move), use the immutable ID in `source` and store the mutable key in `meta` only.
+Pick the format up front — retrofits require a backfill migration.
 
-### Attestation-based visibility for shared threads
+**Mutable ids:** use the immutable id in `source`, store the mutable key in `meta` only (e.g. Jira issue id in `source`, issue key in `meta`).
 
-When your connector populates `thread.contacts` from an external item's recipients, listing someone there does NOT automatically admit them to the thread. The runtime requires that each user's own connector instance independently sync the item (proof that it's in their authenticated account) before they gain a `thread_priority` row. Users whose own sync arrives before any other user has attested them land in `thread.pending_contacts` and are promoted to `thread.contacts` on the next attester's sync.
+### Attestation-based visibility
 
-You don't need to do anything special for this — just continue to populate `contacts` with every recipient you see. The runtime's `upsert_thread` enforces attestation; connectors can treat visibility as a server-side concern.
+Populating `thread.contacts` with recipients does NOT automatically admit them. The runtime requires each user's own connector to sync the item before they get a `thread_priority` row. Users whose sync lands first go to `thread.pending_contacts` and are promoted on the next attester's sync. You just populate `contacts` with every recipient you see — the runtime's `upsert_thread` handles the rest.
 
-## Note Key Conventions
+## Note key conventions
 
-`note.key` enables note-level upserts within an activity:
+`note.key` enables note-level upserts AND is the only way the runtime can correlate a Plot-authored note with its external counterpart for baseline preservation (see "Sync baseline preservation" above). Bidirectional connectors must assign keys on write-back.
 
 ```
-"description"                    — Main content / description note
-"summary"                        — Document summary
-"metadata"                       — Status/priority/assignee metadata
-"cancellation"                   — Cancelled event note
-"comment-<externalCommentId>"    — Individual comment
-"reply-<commentId>-<replyId>"    — Reply to a comment
-```
-
-## HTML Content Handling
-
-**Never strip HTML tags locally.** When external APIs return HTML content, pass it through with `contentType: "html"` and let the server convert it to clean markdown. Local regex-based tag stripping produces broken encoding, loses link structure, and collapses whitespace.
-
-### Pattern
-
-```typescript
-// ✅ CORRECT: Pass raw HTML with contentType
-const note = {
-  key: "description",
-  content: item.bodyHtml,             // Raw HTML from API
-  contentType: "html" as const,       // Server converts to markdown
-};
-
-// ✅ CORRECT: Use plain text when that's what you have
-const note = {
-  key: "description",
-  content: item.bodyText,
-  contentType: "text" as const,
-};
-
-// ❌ WRONG: Stripping HTML locally
-const stripped = html.replace(/<[^>]+>/g, " ").trim();
-const note = { content: stripped };    // Broken encoding, lost links
+"description"                 — main body
+"summary"                     — document summary
+"metadata"                    — status/priority/assignee
+"cancellation"                — cancelled event note
+"comment-<externalCommentId>"
+"reply-<commentId>-<replyId>"
 ```
 
-### When APIs provide both HTML and plain text
+## HTML content
 
-Prefer HTML — the server-side `toMarkdown()` conversion (via Cloudflare AI) produces cleaner output with proper links, formatting, and character encoding. Only use plain text if no HTML is available.
+**Never strip HTML locally.** Pass raw HTML with `contentType: "html"` and let the server convert to markdown (cleaner output, preserved links/encoding).
 
 ```typescript
-function extractBody(part: MessagePart): { content: string; contentType: "text" | "html" } {
-  // Prefer HTML for server-side conversion
-  const htmlPart = findPart(part, "text/html");
-  if (htmlPart) return { content: decode(htmlPart), contentType: "html" };
-
-  const textPart = findPart(part, "text/plain");
-  if (textPart) return { content: decode(textPart), contentType: "text" };
-
-  return { content: "", contentType: "text" };
-}
+const note = { key: "description", content: item.bodyHtml, contentType: "html" as const };
 ```
 
-### Previews
+When both are available, prefer HTML. Use `"text"` only if no HTML is available.
 
-For `preview` fields on threads/links, use a plain-text source (like Gmail's `snippet` or a truncated title) — never raw HTML. Previews are displayed directly and are not processed by the server.
+Previews (`preview` fields) always use plain text — `snippet` or truncated title, never HTML.
 
-### ContentType values
+`contentType`: `"text"` (auto-links URLs), `"markdown"` (default), `"html"` (server-converted).
 
-| Value | Meaning |
-|-------|---------|
-| `"text"` | Plain text — auto-links URLs, preserves line breaks |
-| `"markdown"` | Already markdown (default if omitted) |
-| `"html"` | HTML — converted to markdown server-side |
+## Sync metadata injection
 
-## Sync Metadata Injection
-
-**Every synced activity MUST include sync metadata** in `activity.meta` for bulk operations (e.g., archiving all activities when a sync is disabled):
-
-```typescript
-activity.meta = {
-  ...activity.meta,
-  syncProvider: "myprovider",    // Provider identifier
-  channelId: resourceId,         // Resource being synced
-};
-```
-
-This metadata is used by the twist's `onChannelDisabled` callback to match and archive activities:
+Every synced activity must include provider and channel metadata — the twist's bulk operations (e.g. archiving on disable) rely on it:
 
 ```typescript
-// In the twist:
-async onChannelDisabled(filter: ActivityFilter): Promise<void> {
-  await this.tools.plot.updateActivity({ match: filter, archived: true });
-}
+activity.meta = { ...activity.meta, syncProvider: "myprovider", channelId: resourceId };
 ```
 
-## Initial vs. Incremental Sync (REQUIRED)
+## Initial vs incremental sync (REQUIRED)
 
-**Every connector MUST track whether it is performing an initial sync (first import) or an incremental sync (ongoing updates).** Omitting this causes notification spam from bulk historical imports.
+Missing this causes notification spam from bulk historical imports.
 
-| Field | Initial Sync | Incremental Sync | Reason |
-|-------|-------------|------------------|--------|
-| `unread` | `false` | *omit* | Initial: mark all read. Incremental: auto-mark read for author only |
-| `archived` | `false` | *omit* | Unarchive on install, preserve user choice on updates |
+| Field | Initial | Incremental |
+|---|---|---|
+| `unread` | `false` | *omit* |
+| `archived` | `false` | *omit* |
 
 ```typescript
 const activity = {
-  // ...
-  ...(initialSync ? { unread: false } : {}),
-  ...(initialSync ? { archived: false } : {}),
+  ...(initialSync ? { unread: false, archived: false } : {}),
 };
 ```
 
-### How to propagate the flag
-
-The `initialSync` flag must flow from the entry point (`onChannelEnabled` / `startSync`) through every batch to the point where activities are created. There are two patterns:
-
-**Pattern A: Store in SyncState** (used in the scaffold above)
-
-The scaffold's `SyncState` type includes `initialSync: boolean`. Set it to `true` in `startBatchSync`, read it in `syncBatch`, and preserve it across batches. Webhook/incremental handlers pass `false`.
+The flag must flow from entry point through every batch to the activity-creation site.
 
-**Pattern B: Pass as callback argument** (used by connectors like Gmail that don't store `initialSync` in state)
+- **Pattern A — store in SyncState**: include `initialSync: boolean` in your state type; set `true` in `startBatchSync`, preserve across batches, webhooks pass `false`.
+- **Pattern B — pass as callback arg**: make it the last, optional param (for backward compat) and propagate: `async syncBatch(batch: number, mode: "full"|"incremental", channelId: string, initialSync?: boolean)`. Used by connectors like Gmail.
 
-Pass `initialSync` as an explicit argument through `this.callback()`:
+Entry points: `onChannelEnabled`/`startSync` → `true`; webhook/incremental → `false`; next batch → propagate current value.
 
-```typescript
-// onChannelEnabled — initial sync
-const syncCallback = await this.callback(this.syncBatch, 1, "full", channel.id, true);
-
-// startIncrementalSync — not initial
-const syncCallback = await this.callback(this.syncBatch, 1, "incremental", channelId, false);
-
-// syncBatch — accept and propagate the flag
-async syncBatch(
-  batchNumber: number,
-  mode: "full" | "incremental",
-  channelId: string,
-  initialSync?: boolean  // optional for backward compat with old serialized callbacks
-): Promise<void> {
-  const isInitial = initialSync ?? (mode === "full");  // safe default for old callbacks
-  // ... pass isInitial to processItems and to next batch callback
-}
-```
-
-**Whichever pattern you use, verify that ALL entry points set the flag correctly:**
-- `onChannelEnabled` → `true` (first import)
-- `startSync` → `true` (manual full sync)
-- Webhook / incremental handler → `false`
-- Next batch callback → propagate current value
-
-## Webhook Patterns
+## Webhooks
 
-### Localhost Guard (REQUIRED)
-
-All connectors MUST skip webhook registration in local development:
+### Localhost guard (REQUIRED)
 
 ```typescript
 const webhookUrl = await this.tools.network.createWebhook({}, this.onWebhook, resourceId);
-
-if (webhookUrl.includes("localhost") || webhookUrl.includes("127.0.0.1")) {
-  return; // Skip — webhooks can't reach localhost
-}
+if (webhookUrl.includes("localhost") || webhookUrl.includes("127.0.0.1")) return;
 ```
 
-### Webhook Verification
-
-Verify webhook signatures to prevent unauthorized calls. Each provider has its own method:
+### Signature verification
 
 | Provider | Method |
-|----------|--------|
+|---|---|
 | Linear | `LinearWebhookClient` from `@linear/sdk/webhooks` |
-| Slack | Challenge response + event type filtering |
+| Slack | Challenge response + event type filter |
 | Google | UUID secret in channel token query |
 | Microsoft | Subscription `clientState` |
 | Asana | HMAC-SHA256 via `crypto.subtle` |
 
-### Watch Renewal (Calendar/Drive)
-
-For providers that expire watches, schedule proactive renewal:
+### Watch renewal (Calendar/Drive)
 
 ```typescript
-private async scheduleWatchRenewal(resourceId: string): Promise<void> {
-  const expiresAt = /* watch expiry from provider */;
-  const renewalTime = new Date(expiresAt.getTime() - 24 * 60 * 60 * 1000); // 24h before
-
-  const renewalCallback = await this.callback(this.renewWatch, resourceId);
-  const taskToken = await this.runTask(renewalCallback, { runAt: renewalTime });
-  if (taskToken) await this.set(`watch_renewal_task_${resourceId}`, taskToken);
-}
+const renewalTime = new Date(expiresAt.getTime() - 24 * 60 * 60 * 1000);
+const renewal = await this.callback(this.renewWatch, resourceId);
+const taskToken = await this.runTask(renewal, { runAt: renewalTime });
+if (taskToken) await this.set(`watch_renewal_task_${resourceId}`, taskToken);
 ```
 
-## Bidirectional Sync
-
-For connectors that support write-backs (updating external items from Plot):
-
-### Issue/Task Updates (`updateIssue`)
+## Bidirectional sync
 
 ```typescript
+// Update issue/task from Plot
 async updateIssue(activity: Activity): Promise<void> {
   const externalId = activity.meta?.externalId as string;
-  if (!externalId) throw new Error("External ID not found in meta");
-
   const client = await this.getClient(activity.meta?.resourceId as string);
-  await client.updateItem(externalId, {
-    title: activity.title,
-    done: activity.type === ActivityType.Action ? activity.done : undefined,
-  });
+  await client.updateItem(externalId, { title: activity.title, done: /* ... */ });
 }
-```
-
-### Comment Sync (`addIssueComment`)
 
-```typescript
-async addIssueComment(meta: ActivityMeta, body: string, noteId?: string): Promise<string | void> {
-  const externalId = meta.externalId as string;
-  if (!externalId) throw new Error("External ID not found");
+// Post a comment. Return a NoteWriteBackResult with externalContent so the
+// runtime can establish a sync baseline (see "Sync baseline preservation"
+// below). Returning just a string still works, but without a baseline the
+// next sync-in will overwrite Plot's (possibly richer-markdown) content
+// with the round-tripped plain text the external system stored.
+async onNoteCreated(note: Note, thread: Thread): Promise<NoteWriteBackResult | void> {
+  const client = await this.getClient(thread.meta?.resourceId as string);
+  const comment = await client.createComment(thread.meta?.externalId as string, { body: note.content ?? "" });
+  if (!comment?.id) return;
+  return {
+    key: `comment-${comment.id}`,
+    externalContent: comment.body, // what the external system NOW STORES
+  };
+}
 
-  const client = await this.getClient(meta.resourceId as string);
-  const comment = await client.createComment(externalId, { body });
-  if (comment?.id) return `comment-${comment.id}`;
+// Push a local edit back to the external system. `note.key` identifies the
+// target; refresh the baseline from the response so the next sync-in
+// recognises the round-trip and preserves Plot's edited content.
+async onNoteUpdated(note: Note, thread: Thread): Promise<NoteWriteBackResult | void> {
+  if (!note.key?.startsWith("comment-")) return;
+  const commentId = note.key.slice("comment-".length);
+  const client = await this.getClient(thread.meta?.resourceId as string);
+  const updated = await client.updateComment(commentId, { body: note.content ?? "" });
+  return { externalContent: updated.body };
 }
 ```
 
-### Loop Prevention
+**Loop prevention** (in the twist, not the connector): `if (note.author.type === ActorType.Twist) return;`
+
+**`handleReplies`**: bidirectional connectors must set `static readonly handleReplies = true` to enable @-mentions on replies. Read-only connectors should NOT.
+
+### Sync baseline preservation (required for any note round-trip)
+
+When Plot pushes a note to an external system that stores content in a lossier format than Plot does (e.g. plain-text comments APIs, ADF, HTML that gets sanitised), the external's version re-ingested on the next sync would overwrite Plot's original content with the round-tripped form — `1.` → `1\.`, `[name]` → `\[name\]`, etc. To prevent this, the runtime tracks a per-note "external baseline" hash in `note.external_content_hash`:
+
+- **Write-back (`onNoteCreated` / `onNoteUpdated`) returns `NoteWriteBackResult`** with `externalContent` set to what the external system now stores. The runtime hashes this and stores it as the note's baseline. (The hash is over the content string only — no contentType prefix — so write-back and sync-in don't need to agree on a contentType label to match.)
+- **Sync-in** computes the same hash on each incoming `NewNote.content`. Match → preserve Plot's stored content (skip overwrite). Mismatch → external was edited, overwrite.
+
+The hard contract:
+
+> **`externalContent` must exactly equal the `NewNote.content` string your sync-in path will emit for this note on re-ingest.**
+
+If your sync-in runs incoming comment bodies through a transform (e.g. Airtable's `translateMentionsInbound`, Jira's `extractTextFromADF`), apply the same transform to the write-back response before returning it. Pick the value by looking at the sync-in `build*Note` function and returning exactly what ends up in `content`.
+
+For systems that return the stored representation on write (Drive, GitHub, Linear, Slack `chat.postMessage`), use the response directly. For systems that don't (Gmail `messages.send`), either fetch the stored form with an extra API call or skip `externalContent` — the first sync-in after the write will organically establish the baseline. Document the tradeoff.
 
-The parent twist prevents infinite loops by checking note authorship:
+**Failure modes you must avoid:**
+
+- Returning `externalContent` that differs from what sync-in will produce → every sync-in clobbers Plot's content.
+- Not setting `handleReplies = true` → dispatch never reaches `onNoteCreated`.
+- Calling `integrations.saveLink()` inside `onNoteCreated` to propagate the key → no longer needed (runtime now does it). Remove any such workaround.
+
+**Legacy:** `onNoteCreated` may still return a plain `string` — treated as `{ key }` with no baseline. Don't use this shape in new connectors.
+
+### Creating new items from Plot (`onCreateLink`)
+
+Opt a link type in by marking one status with `createDefault: true`:
 
 ```typescript
-// In the twist (not the connector):
-async onNoteCreated(note: Note): Promise<void> {
-  if (note.author.type === ActorType.Twist) return; // Prevent loops
-  // ... sync note to external service
-}
+statuses: [
+  { status: "backlog", label: "Backlog" },
+  { status: "unstarted", label: "To Do", todo: true, createDefault: true },
+  { status: "completed", label: "Done", tag: Tag.Done, done: true },
+]
 ```
 
-### Default Mention on Replies
-
-Connectors with bidirectional sync should set `static readonly handleReplies = true` so replies to synced threads automatically mention the connector:
+Then implement `onCreateLink` — return the link, do NOT call `integrations.saveLink()` (platform wires it to the originating thread):
 
 ```typescript
-export class MyConnector extends Connector<MyConnector> {
-  static readonly handleReplies = true;  // Replies to synced threads mention this connector by default
-  // ...
+async onCreateLink(draft: CreateLinkDraft): Promise<NewLinkWithNotes | null> {
+  if (draft.type !== "issue") return null;
+  const client = await this.getClient(draft.channelId);
+  const payload = await client.createIssue({
+    teamId: draft.channelId,
+    title: draft.title,
+    description: draft.noteContent ?? undefined,
+    stateId: await this.resolveStateId(client, draft.channelId, draft.status),
+  });
+  const issue = await payload.issue;
+  if (!issue) return null;
+  return {
+    source: `linear:issue:${issue.id}`,
+    type: "issue",
+    title: issue.title,
+    status: draft.status,
+    created: issue.createdAt,
+    sourceUrl: issue.url ?? null,
+    meta: { linearId: issue.id, projectId: draft.channelId },
+    // channelId/type default to draft values if omitted
+  };
 }
 ```
 
-Without this, the connector cannot be @-mentioned at all. Connectors that don't process replies (e.g., read-only calendar sync) should NOT set this flag.
-
-### Creating New Items from Plot (`onCreateLink`)
-
-Plot users can start a new thread tied to a brand-new external item (e.g. create a Linear issue, a Google Calendar event, a Slack DM) via "Create new …" in the Add link modal. Connectors opt in per link type:
-
-1. **Mark a status as the creation default** on the `LinkTypeConfig` you expose for that type — either on the static `readonly linkTypes` on the class, or on the dynamic per-channel linkTypes returned by `getChannels`:
-
-   ```typescript
-   statuses: [
-     { status: "backlog", label: "Backlog" },
-     { status: "unstarted", label: "To Do", todo: true, createDefault: true },
-     { status: "completed", label: "Done", tag: Tag.Done, done: true },
-   ],
-   ```
-
-   A link type opts in to Plot-initiated creation by declaring at least one status with `createDefault: true`. The marked status is used as the default when the user selects "Create new X".
-
-2. **Implement `onCreateLink(draft)`** — called after the Plot thread is saved and titled. Create the external item and return a `NewLinkWithNotes` describing it. The platform attaches the link to the originating thread; do NOT call `integrations.saveLink()` yourself.
-
-   ```typescript
-   async onCreateLink(draft: CreateLinkDraft): Promise<NewLinkWithNotes | null> {
-     if (draft.type !== "issue") return null;
-     const client = await this.getClient(draft.channelId);
-     const payload = await client.createIssue({
-       teamId: draft.channelId,
-       title: draft.title,
-       description: draft.noteContent ?? undefined,
-       stateId: await this.resolveStateId(client, draft.channelId, draft.status),
-     });
-     const issue = await payload.issue;
-     if (!issue) return null;
-     return {
-       source: `linear:issue:${issue.id}`,
-       type: "issue",
-       title: issue.title,
-       status: draft.status,
-       created: issue.createdAt,
-       sourceUrl: issue.url ?? null,
-       meta: { linearId: issue.id, projectId: draft.channelId },
-       // channelId/type default to draft.channelId/draft.type if you omit them.
-     };
-   }
-   ```
-
-**`CreateLinkDraft` shape** (see `twister/src/connector.ts`):
-- `channelId`, `type`, `status` — identify the target channel + link type + status.
-- `title` — Plot thread title (post AI title generation).
-- `noteContent` — markdown of the thread's first note, or `null`.
-- `contacts: Actor[]` — thread's contacts (excluding the creating user), for email recipients / DM members / invitees.
-
-**Platform defaults**: the runtime fills in `channelId` and `type` on the returned link from the draft if the connector omits them. Status label resolution depends on `channel_id`, so this default keeps the UI rendering correct even if you forget to echo them.
-
-**Do not**:
-- Call `integrations.saveLink()` — the platform wires the returned link to the user's thread.
-- Assume the draft's status matches an external state id verbatim. For dynamic-per-team statuses (Linear teams, Jira projects), the draft's status is whatever was shown in the picker — your connector is responsible for resolving categories like `"unstarted"` if your static `linkTypes` fallback was used.
-
-**Loop prevention**: the link your `onCreateLink` returns is written with `updated_by` set to the twist, so subsequent syncs of the same external id won't retrigger `onCreateLink` or `onLinkUpdated` for the initial state.
-
-## Contacts Pattern
-
-Connectors that sync user data should create contacts for authors and assignees:
+`CreateLinkDraft`: `channelId`, `type`, `status`, `title`, `noteContent`, `contacts: Actor[]`. See `twister/src/connector.ts`.
 
-```typescript
-import type { NewContact } from "@plotday/twister/plot";
+Resolve category statuses (`"unstarted"`, etc.) to the provider's state id yourself — the draft's status is whatever the picker showed.
+
+The returned link is written with `updated_by` set to the twist, so subsequent syncs of the same id won't re-fire `onCreateLink`/`onLinkUpdated` for the initial state.
+
+## Contacts
 
-const authorContact: NewContact | undefined = creator?.email ? {
-  email: creator.email,
-  name: creator.name,
-  avatar: creator.avatarUrl ?? undefined,
-} : undefined;
+Contacts are created implicitly when you save threads/links — no `addContacts()` call, no `ContactAccess.Write`.
+
+```typescript
+const author: NewContact | undefined = creator?.email
+  ? { email: creator.email, name: creator.name, avatar: creator.avatarUrl ?? undefined }
+  : undefined;
 
 const activity: NewActivityWithNotes = {
-  // ...
-  author: authorContact,
+  author,
   assignee: assigneeContact ?? null,
-  notes: [{
-    author: authorContact,  // Note-level author too
-    // ...
-  }],
+  notes: [{ author /* note-level author too */ }],
 };
 ```
 
-Contacts are created implicitly when saving threads/links via `integrations.saveLink()` — no explicit `addContacts()` call or `ContactAccess.Write` permission is needed.
+## Buffer declaration
 
-## Buffer Declaration
-
-Cloudflare Workers provides `Buffer` globally, but TypeScript doesn't know about it. Declare it at the top of files that need it:
+Cloudflare Workers provide `Buffer` globally but TS doesn't know. Add at file top:
 
 ```typescript
 declare const Buffer: {
-  from(
-    data: string | ArrayBuffer | Uint8Array,
-    encoding?: string
-  ): Uint8Array & { toString(encoding?: string): string };
+  from(data: string | ArrayBuffer | Uint8Array, encoding?: string):
+    Uint8Array & { toString(encoding?: string): string };
 };
 ```
 
-## Building and Testing
+## Build & test
 
 ```bash
-# Build the connector
 cd public/connectors/<name> && pnpm build
-
-# Type-check without building
 cd public/connectors/<name> && pnpm exec tsc --noEmit
-
-# Install dependencies (from repo root)
-pnpm install
-```
-
-After creating a new connector, add it to `pnpm-workspace.yaml` if not already covered by the glob pattern.
-
-## Connector Development Checklist
-
-- [ ] Extend `Connector<YourConnector>`
-- [ ] Declare `static readonly PROVIDER`, `static readonly SCOPES`
-- [ ] Declare `static readonly Options: SyncToolOptions` and `declare readonly Options: SyncToolOptions`
-- [ ] Declare all dependencies in `build()`: Integrations, Network, Callbacks, Tasks
-- [ ] Set `static readonly handleReplies = true` if the connector supports bidirectional sync
-- [ ] Implement `getChannels()`, `onChannelEnabled()`, `onChannelDisabled()` — **use `runTask()` (not `run()`) in `onChannelEnabled` to avoid blocking the API response**
-- [ ] Convert parent callbacks to tokens with `createFromParent()` — **never pass functions to `this.callback()`**
-- [ ] Store callback tokens with `this.set()`, retrieve with `this.get<Callback>()`
-- [ ] Pass only serializable values (no functions, no undefined) to `this.callback()`
-- [ ] Implement batch sync with `this.tools.tasks.runTask()` for fresh request limits
-- [ ] Add localhost guard in webhook setup
-- [ ] Verify webhook signatures
-- [ ] Use canonical `source` URLs for activity upserts (immutable IDs)
-- [ ] Use `note.key` for note-level upserts
-- [ ] Set `contentType: "html"` on notes with HTML content — **never strip HTML locally**
-- [ ] Inject `syncProvider` and `channelId` into `activity.meta`
-- [ ] Set `created` on notes using the external system's timestamp (not sync time)
-- [ ] Handle `initialSync` flag in **every sync entry point**: `onChannelEnabled`/`startSync` set `true`, webhooks/incremental set `false`, and the flag is propagated through all batch callbacks to where activities are created. Set `unread: false` and `archived: false` for initial, omit both for incremental
-- [ ] Create contacts for authors/assignees with `NewContact`
-- [ ] Clean up all stored state and callbacks in `stopSync()` and `onChannelDisabled()`
-- [ ] **If the connector should let users create new items from Plot**: mark one status per opted-in `LinkTypeConfig` with `createDefault: true` and implement `onCreateLink(draft)`. Return a `NewLinkWithNotes` — never call `integrations.saveLink()` from `onCreateLink`
-- [ ] Add `package.json` with correct structure, `tsconfig.json`, and `src/index.ts` re-export
-- [ ] Verify the connector builds: `pnpm build`
-
-## Common Pitfalls
-
-1. **❌ Passing functions to `this.callback()`** — Convert to tokens first with `createFromParent()`
-2. **❌ Storing functions with `this.set()`** — Convert to tokens first
-3. **❌ Not validating callback token exists** — Always check before `callbacks.run()`
-4. **❌ Forgetting sync metadata** — Always inject `syncProvider` and `channelId` into `activity.meta`
-5. **❌ Not propagating `initialSync` through the full sync pipeline** — The flag must flow from the entry point (`onChannelEnabled`/`startSync` → `true`, webhook → `false`) through every batch callback to where activities are created. Missing this causes notification spam from bulk historical imports
-6. **❌ Using mutable IDs in `source`** — Use immutable IDs (Jira issue ID, not issue key)
-7. **❌ Not breaking loops into batches** — Each execution has ~1000 request limit
-8. **❌ Missing localhost guard** — Webhook registration fails silently on localhost
-9. **❌ Calling `plot.createThread()` from a connector** — Connectors save data directly via `integrations.saveLink()`
-10. **❌ Breaking callback signatures** — Old callbacks auto-upgrade; add optional params at end only
-11. **❌ Passing `undefined` in serializable values** — Use `null` instead
-12. **❌ Forgetting to clean up on disable** — Delete callbacks, webhooks, and stored state
-13. **❌ Two-way sync without metadata correlation** — Embed Plot ID in external item metadata to prevent duplicates from race conditions (see SYNC_STRATEGIES.md §6)
-14. **❌ Stripping HTML tags locally** — Pass raw HTML with `contentType: "html"` for server-side conversion. Local regex stripping breaks encoding and loses links
-15. **❌ Using placeholder titles in comment/update webhooks** — `title` always overwrites on upsert. Always use the real entity title (fetch from API if not in the webhook payload). Never use IDs or keys as placeholder titles
-16. **❌ Not setting `created` on notes from external data** — Always pass the external system's timestamp (e.g., `internalDate` from Gmail, `created_at` from an API) as the note's `created` field. Omitting it defaults to sync time, making all notes appear to have been created "just now"
-17. **❌ Using `this.run()` in `onChannelEnabled` to start sync** — `onChannelEnabled` runs synchronously inside the API request handler. Using `this.run()` (which executes inline) blocks the HTTP response until the entire sync completes, causing client timeouts. Always use `this.runTask()` to queue the initial sync as a separate execution so `onChannelEnabled` returns quickly
-18. **❌ Calling `integrations.saveLink()` from `onCreateLink`** — The platform wires the returned link to the user's originating thread. Calling `saveLink` yourself creates a duplicate thread. Just return the `NewLinkWithNotes`
-19. **❌ Forgetting to mark a status with `createDefault: true`** — Without it, Plot has no idea the link type opts in to Plot-initiated creation, so the "Create new X" entry never appears in the Add link modal. Declaring the marker is what opts a link type in, not implementing `onCreateLink` alone
-
-## Study These Examples
-
-| Connector | Category | Key Patterns |
-|-----------|----------|-------------|
-| `linear/` | ProjectConnector | Clean reference implementation, webhook handling, bidirectional sync |
-| `google-calendar/` | CalendarConnector | Recurring events, RSVP write-back, watch renewal, cross-connector auth sharing |
-| `slack/` | MessagingConnector | Team-sharded webhooks, thread model, Slack-specific auth |
-| `gmail/` | MessagingConnector | PubSub webhooks, email thread transformation, HTML contentType, callback-arg initialSync pattern |
-| `google-drive/` | DocumentConnector | Document comments, reply threading, file watching |
-| `jira/` | ProjectConnector | Immutable vs mutable IDs, comment metadata for dedup |
-| `asana/` | ProjectConnector | HMAC webhook verification, section-based projects |
-| `outlook-calendar/` | CalendarConnector | Microsoft Graph API, subscription management |
-| `google-contacts/` | (Supporting) | Contact sync, cross-connector `syncWithAuth()` pattern |
+pnpm install  # from repo root
+```
+
+Add to `pnpm-workspace.yaml` if not already covered by a glob.
+
+## Checklist
+
+- [ ] Extend `Connector<YourConnector>`; declare `PROVIDER`, `SCOPES`, `Options` (static + `declare readonly`)
+- [ ] `build()` declares Integrations, Network, Callbacks, Tasks (plus GoogleContacts if applicable)
+- [ ] Set `handleReplies = true` only if bidirectional
+- [ ] For bidirectional note sync: `onNoteCreated` / `onNoteUpdated` return `NoteWriteBackResult` with `externalContent` matching what sync-in will emit for this note — no `Promise<string | void>` in new connectors
+- [ ] For bidirectional note sync: implement `onNoteUpdated` if the external supports editing (document the gap if it doesn't)
+- [ ] `onChannelEnabled` uses `runTask()` (NOT `run()`) for webhook setup and initial sync — blocks HTTP response otherwise
+- [ ] Convert parent callbacks to tokens with `createFromParent()`; store via `this.set()`; retrieve with `this.get<Callback>()`
+- [ ] Never pass functions, RPC stubs, or `undefined` to `this.callback()` — use `null`
+- [ ] Validate token exists before `callbacks.run()`
+- [ ] Localhost guard in webhook setup; verify webhook signatures
+- [ ] Canonical, globally-unique `source` using immutable ids; mutable keys in `meta` only
+- [ ] `note.key` for note-level upserts
+- [ ] Inject `syncProvider` + `channelId` into `activity.meta`
+- [ ] `contentType: "html"` for HTML — never strip tags locally
+- [ ] `created` on notes = external timestamp, not sync time
+- [ ] `initialSync` propagated through every entry point and batch; set `unread: false, archived: false` on initial, omit on incremental
+- [ ] Create `NewContact` for authors/assignees
+- [ ] Clean up callbacks, webhooks, stored state in `stopSync()` and `onChannelDisabled()`
+- [ ] For Plot-initiated creation: mark status with `createDefault: true` AND implement `onCreateLink` — don't call `saveLink` from inside it
+- [ ] `pnpm build` succeeds
+
+## Common pitfalls
+
+1. Passing functions/`undefined`/RPC stubs to `this.callback()` → use tokens + `null`.
+2. Forgetting sync metadata (`syncProvider`, `channelId`) → breaks bulk archive on disable.
+3. Not propagating `initialSync` through the whole pipeline → notification spam.
+4. Mutable ids in `source` (e.g. Jira issue key) → use immutable id, store key in `meta`.
+5. `source` that's only unique within one user's account → breaks cross-user dedup; add workspace/tenant/mailbox qualifier.
+6. Not breaking long loops into batches → each execution has ~1000 request limit.
+7. Missing localhost guard → webhook registration fails silently.
+8. Calling `plot.createThread()` from a connector → use `integrations.saveLink()`.
+9. Breaking callback signatures → add optional params at end only; use `preUpgrade()` for breaking migrations.
+10. Not cleaning up on disable → orphan callbacks, webhooks, state.
+11. Two-way sync without metadata correlation → embed Plot id in external metadata to prevent race-condition duplicates (see SYNC_STRATEGIES.md §6).
+12. Stripping HTML locally → breaks encoding + loses links; use `contentType: "html"`.
+13. Placeholder titles in comment/update webhooks → `title` overwrites on upsert; fetch the real title if webhook doesn't carry it.
+14. Omitting `created` on notes → everything appears "just now"; pass external timestamp.
+15. `this.run()` in `onChannelEnabled` → blocks HTTP response until full sync completes; always `runTask()`.
+16. Calling `integrations.saveLink()` inside `onCreateLink` → duplicate thread; just return the link.
+17. Implementing `onCreateLink` without `createDefault: true` on a status → "Create new X" entry never appears.
+18. Returning a bare `string` (key only) from `onNoteCreated` when the external stores content lossily (plain-text comments APIs, ADF, sanitised HTML) → next sync-in clobbers Plot's content with the round-tripped form (e.g. `1.` → `1\.`). Return a `NoteWriteBackResult` with `externalContent` matching sync-in's shape instead.
+19. Returning `externalContent` that doesn't match what sync-in emits for the same note (e.g. post-write raw HTML when sync-in extracts plain text; pre-translation mentions when sync-in translates them) → baseline hash always mismatches and every sync clobbers. Inspect the sync-in `build*Note` path and return exactly what it produces.
+20. Calling `integrations.saveLink()` inside `onNoteCreated` to set the note's `key` → legacy workaround, no longer needed. The runtime sets `key` automatically from the `NoteWriteBackResult` return.
+
+## Examples
+
+| Connector | Category | Key patterns |
+|---|---|---|
+| `linear/` | ProjectConnector | Canonical reference; webhooks; bidirectional |
+| `google-calendar/` | CalendarConnector | Recurring events; RSVP write-back; watch renewal; shared Google auth |
+| `slack/` | MessagingConnector | Team-sharded webhooks; thread model |
+| `gmail/` | MessagingConnector | PubSub webhooks; HTML contentType; callback-arg `initialSync` |
+| `google-drive/` | DocumentConnector | Document comments; reply threading; file watching; canonical `NoteWriteBackResult` + `onNoteUpdated` example |
+| `jira/` | ProjectConnector | Immutable vs mutable ids; comment metadata dedup |
+| `asana/` | ProjectConnector | HMAC webhook verification; section-based projects |
+| `outlook-calendar/` | CalendarConnector | Microsoft Graph; subscription management |
+| `google-contacts/` | Supporting | Contact sync; cross-connector `syncWithAuth()` |