feat(twister): twist-scoped LLM docs and compiled example twists

.changeset/twist-prompt-docs.md

@@ -0,0 +1,5 @@
+---
+"@plotday/twister": minor
+---
+
+Added: getTwistDocumentation() (twist-scoped LLM documentation that omits connector-only modules) and TWIST_EXEMPLARS (complete example twists, compiled and type-checked on every build) for generation prompts.

twister/prebuild.ts

@@ -1,5 +1,12 @@
 #!/usr/bin/env node
-import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "fs";
+import {
+ existsSync,
+ mkdirSync,
+ readdirSync,
+ readFileSync,
+ rmSync,
+ writeFileSync,
+} from "fs";
 import { dirname, join } from "path";
 import { fileURLToPath } from "url";
 
@@ -189,6 +196,50 @@ export default ${JSON.stringify(twistsTemplateContent)};
  );
 }
 
+// Generate twist-exemplars.ts from src/exemplars/*.ts — complete example
+// twists embedded for LLM generation prompts. Each file must start with a
+// /* SPEC: ... */ block comment (the user-style specification it implements).
+const exemplarsDir = join(srcDir, "exemplars");
+if (!existsSync(exemplarsDir)) {
+ throw new Error("prebuild: src/exemplars/ is missing");
+}
+const exemplarFiles = readdirSync(exemplarsDir)
+ .filter((f) => f.endsWith(".ts"))
+ .sort();
+if (exemplarFiles.length === 0) {
+ throw new Error("prebuild: src/exemplars/ contains no exemplars");
+}
+const exemplarSections = exemplarFiles.map((file) => {
+ const raw = readFileSync(join(exemplarsDir, file), "utf-8");
+ const specMatch = raw.match(/^\/\*\s*SPEC:\s*\n([\s\S]*?)\*\/\s*\n/);
+ if (!specMatch) {
+ throw new Error(`prebuild: ${file} is missing its leading /* SPEC: */ comment`);
+ }
+ const spec = specMatch[1].trim();
+ const implementation = raw.slice(specMatch[0].length).trim();
+ const title = file
+ .replace(/\.ts$/, "")
+ .split("-")
+ // Word-capitalize each hyphen segment, except known acronyms (e.g. "ai"
+ // -> "AI" for ai-responder.ts) which are upper-cased outright.
+ .map((w) =>
+ w.toLowerCase() === "ai" ? "AI" : w[0].toUpperCase() + w.slice(1)
+ )
+ .join(" ");
+ return `## Example: ${title}\n\n### Specification\n\n${spec}\n\n### Implementation\n\n\`\`\`typescript\n${implementation}\n\`\`\``;
+});
+const exemplarsContent = `/**
+ * Generated example twists for LLM generation prompts.
+ *
+ * This file is auto-generated during build. Do not edit manually.
+ * Generated from: src/exemplars/*.ts
+ */
+
+export default ${JSON.stringify(exemplarSections.join("\n\n"))};
+`;
+writeFileSync(join(llmDocsDir, "twist-exemplars.ts"), exemplarsContent, "utf-8");
+console.log(`✓ Generated twist-exemplars.ts from ${exemplarFiles.length} exemplars`);
+
 console.log(
  `✓ Generated ${typeFiles.length} LLM documentation files in src/llm-docs/`
 );

twister/src/creator-docs.ts

@@ -1,4 +1,5 @@
 import llmDocs from "./llm-docs/index.js";
+import twistExemplars from "./llm-docs/twist-exemplars.js";
 
 /**
  * Gets complete Twist Creator type definitions with import paths for LLM context.
@@ -27,3 +28,41 @@ export function getBuilderDocumentation(): string {
 
  return documentation;
 }
+
+// Modules excluded from TWIST generation docs: twists must never extend
+// Connector, and the mail-protocol tools are niche enough to dilute the
+// prompt more than they help.
+const TWIST_DOC_EXCLUSIONS = new Set([
+ "@plotday/twister/connector",
+ "@plotday/twister/tools/imap",
+ "@plotday/twister/tools/smtp",
+]);
+
+/**
+ * Twist-scoped variant of getBuilderDocumentation(): the same formatted
+ * type definitions, minus modules that are irrelevant (or misleading) when
+ * generating a twist.
+ */
+export function getTwistDocumentation(): string {
+ let documentation = "# Plot Twist Creator Type Definitions\n\n";
+ documentation +=
+ "Complete type definitions with JSDoc documentation for all Plot Twist Creator types.\n";
+ documentation +=
+ "These are the source files - use the import paths shown to import types in your twist code.\n\n";
+ for (const [importPath, content] of Object.entries(llmDocs)) {
+ if (TWIST_DOC_EXCLUSIONS.has(importPath)) continue;
+ documentation += `## ${importPath}\n\n`;
+ documentation += "```typescript\n";
+ documentation += `// Import from: ${importPath}\n\n`;
+ documentation += content;
+ documentation += "\n```\n\n";
+ }
+ return documentation;
+}
+
+/**
+ * Complete example twists (specification + implementation pairs) for LLM
+ * generation prompts. The examples are real compiled sources in
+ * src/exemplars/, so they are type-checked on every build.
+ */
+export const TWIST_EXEMPLARS: string = twistExemplars;

twister/src/exemplars/ai-responder.ts

@@ -0,0 +1,60 @@
+/* SPEC:
+When someone writes a journal note in another language, reply in the same
+thread with a short plain-English summary of what they wrote, so they can
+check their own understanding. Don't react to notes written by automations.
+*/
+import { ActorType, Twist, type Note, type ToolBuilder } from "@plotday/twister";
+import { AI } from "@plotday/twister/tools/ai";
+import { Plot, ThreadAccess } from "@plotday/twister/tools/plot";
+
+export default class LanguageJournal extends Twist<LanguageJournal> {
+ build(build: ToolBuilder) {
+ return {
+ plot: build(Plot, {
+ // onNoteCreated only fires for notes on threads this twist created,
+ // so Create access is required even though nothing else reads or
+ // updates other threads.
+ thread: { access: ThreadAccess.Create },
+ }),
+ ai: build(AI),
+ };
+ }
+
+ async activate() {
+ // Seed the standing thread the user writes journal entries into.
+ await this.tools.plot.createThread({
+ title: "Language journal",
+ notes: [
+ {
+ content:
+ "Write your journal entries here in any language — I'll reply with a plain-English summary.",
+ },
+ ],
+ });
+ }
+
+ // Fires for every new note on a thread this twist created. Guard against
+ // notes from twists/automations so we never loop on our own replies.
+ async onNoteCreated(note: Note): Promise<void> {
+ if (note.author.type === ActorType.Twist) {
+ return;
+ }
+ if (!note.content || note.content.trim().length === 0) {
+ return;
+ }
+
+ const response = await this.tools.ai.prompt({
+ model: { speed: "fast", cost: "low" },
+ prompt: `Summarize this journal entry in one or two plain-English sentences:\n\n${note.content}`,
+ });
+ if (!response.text) {
+ return;
+ }
+
+ // Reply in the same thread the note belongs to.
+ await this.tools.plot.createNote({
+ thread: { id: note.thread.id },
+ content: `English summary: ${response.text}`,
+ });
+ }
+}

twister/src/exemplars/authenticated-sync.ts

@@ -0,0 +1,84 @@
+/* SPEC:
+Connect to my bookmarking service account. Once connected, import my starred
+bookmarks as threads (title + link note), and check for new ones every hour.
+Imported bookmarks must not duplicate on re-sync.
+*/
+import { ActionType, Twist, type ToolBuilder, type Uuid } from "@plotday/twister";
+import { Options } from "@plotday/twister/options";
+import { Network } from "@plotday/twister/tools/network";
+import { Plot, ThreadAccess } from "@plotday/twister/tools/plot";
+
+export default class BookmarkSync extends Twist<BookmarkSync> {
+ build(build: ToolBuilder) {
+ return {
+ plot: build(Plot, {
+ thread: { access: ThreadAccess.Create },
+ }),
+ // Plain twists can't hold OAuth tokens — that machinery
+ // (provider/scopes/channels) belongs to Connectors. A secure Options
+ // field is the twist-safe way to let the user "connect" an account
+ // for a twist to call directly.
+ options: build(Options, {
+ apiKey: {
+ type: "text",
+ label: "Bookmarking service API key",
+ default: "",
+ secure: true,
+ },
+ }),
+ network: build(Network, {
+ urls: ["https://api.bookmarks.example/*"],
+ }),
+ };
+ }
+
+ async activate() {
+ // Re-runs hourly under a stable key; survives restarts and upgrades.
+ await this.scheduleRecurring(
+ "hourly-sync",
+ await this.callback(this.sync),
+ { intervalMs: 60 * 60 * 1000 }
+ );
+ await this.sync();
+ }
+
+ async sync(): Promise<void> {
+ const { apiKey } = this.tools.options;
+ if (!apiKey) {
+ return; // Not connected yet; nothing to sync.
+ }
+
+ const response = await fetch("https://api.bookmarks.example/v1/starred", {
+ headers: { Authorization: `Bearer ${apiKey}` },
+ });
+ if (!response.ok) {
+ return;
+ }
+ const { bookmarks } = (await response.json()) as {
+ bookmarks: Array<{ id: string; title: string; url: string }>;
+ };
+
+ // Threads a twist creates have no external Link (that's a Connector
+ // concept), so dedup is tracked manually: store the bookmark id -> thread
+ // id mapping and skip any bookmark that's already been imported.
+ for (const bookmark of bookmarks) {
+ const mappingKey = `bookmark:${bookmark.id}`;
+ if (await this.get<Uuid>(mappingKey)) {
+ continue;
+ }
+
+ const threadId = await this.tools.plot.createThread({
+ title: bookmark.title,
+ notes: [
+ {
+ content: bookmark.url,
+ actions: [
+ { type: ActionType.external, title: "Open bookmark", url: bookmark.url },
+ ],
+ },
+ ],
+ });
+ await this.set(mappingKey, threadId);
+ }
+ }
+}

twister/src/exemplars/scheduled-digest.ts

@@ -0,0 +1,61 @@
+/* SPEC:
+Every morning, post a thread with today's weather forecast for my city so I
+can plan the day. One thread per day, titled with the date.
+*/
+import { Twist, type ToolBuilder } from "@plotday/twister";
+import { Network } from "@plotday/twister/tools/network";
+import { Plot, ThreadAccess } from "@plotday/twister/tools/plot";
+
+export default class WeatherDigest extends Twist<WeatherDigest> {
+ build(build: ToolBuilder) {
+ return {
+ plot: build(Plot, {
+ thread: { access: ThreadAccess.Create },
+ }),
+ network: build(Network, {
+ urls: ["https://api.open-meteo.com/*"],
+ }),
+ };
+ }
+
+ async activate() {
+ await this.scheduleRecurring(
+ "morning-digest",
+ await this.callback(this.postDigest),
+ { intervalMs: 24 * 60 * 60 * 1000 }
+ );
+ }
+
+ async postDigest(): Promise<void> {
+ // Scheduled callbacks can fire more than once (at-least-once delivery),
+ // so guard "one thread per day" with a stored marker keyed on the date.
+ const today = new Date().toISOString().slice(0, 10);
+ const postedKey = `posted:${today}`;
+ if (await this.get<boolean>(postedKey)) {
+ return;
+ }
+
+ const response = await fetch(
+ "https://api.open-meteo.com/v1/forecast?latitude=43.65&longitude=-79.38&daily=temperature_2m_max,precipitation_probability_mean&timezone=auto&forecast_days=1"
+ );
+ if (!response.ok) {
+ return;
+ }
+ const data = (await response.json()) as {
+ daily: {
+ temperature_2m_max: number[];
+ precipitation_probability_mean: number[];
+ };
+ };
+
+ await this.tools.plot.createThread({
+ title: `Weather for ${today}`,
+ notes: [
+ {
+ content: `High of ${data.daily.temperature_2m_max[0]}°C, ${data.daily.precipitation_probability_mean[0]}% chance of rain.`,
+ },
+ ],
+ });
+ await this.set(postedKey, true);
+ }
+}

twister/tsconfig.build.json

@@ -8,7 +8,18 @@
  "declarationMap": true,
  "sourceMap": true,
  "noEmit": false,
- "composite": false
+ "composite": false,
+ // src/exemplars/*.ts import "@plotday/twister" by package name (so the
+ // embedded LLM-facing examples show real import paths, not relative
+ // ones). Resolving that self-reference requires the same
+ // moduleResolution + custom condition tsconfig.base.json already grants
+ // downstream twist/connector projects for the reverse case (resolving
+ // @plotday/twister straight to this package's src/*). Scoped to this
+ // build-only config (not tsconfig.json / tsconfig.cli.json) since
+ // "bundler" resolution is incompatible with tsconfig.cli.json's
+ // CommonJS output (TS5095).
+ "moduleResolution": "bundler",
+ "customConditions": ["@plotday/connector"]
  },
  "include": ["src/**/*.ts"],
  "exclude": [

twister/typedoc.json

@@ -18,11 +18,12 @@
  "src/utils/hash.ts"
  ],
  "out": "dist/docs",
- "tsconfig": "./tsconfig.json",
+ "tsconfig": "./tsconfig.build.json",
  "exclude": [
  "**/*+(.spec|.test).ts",
  "**/llm-docs/**",
  "**/cli/**",
+ "**/exemplars/**",
  "src/twist-guide.ts",
  "src/creator-docs.ts",
  "prebuild.ts",

.changeset/twist-prompt-docs.md

@@ -0,0 +1,5 @@
+---
+"@plotday/twister": minor
+---
+
+Added: getTwistDocumentation() (twist-scoped LLM documentation that omits connector-only modules) and TWIST_EXEMPLARS (complete example twists, compiled and type-checked on every build) for generation prompts.

twister/prebuild.ts

@@ -1,5 +1,12 @@
 #!/usr/bin/env node
-import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "fs";
+import {
+ existsSync,
+ mkdirSync,
+ readdirSync,
+ readFileSync,
+ rmSync,
+ writeFileSync,
+} from "fs";
 import { dirname, join } from "path";
 import { fileURLToPath } from "url";
 
@@ -189,6 +196,50 @@ export default ${JSON.stringify(twistsTemplateContent)};
  );
 }
 
+// Generate twist-exemplars.ts from src/exemplars/*.ts — complete example
+// twists embedded for LLM generation prompts. Each file must start with a
+// /* SPEC: ... */ block comment (the user-style specification it implements).
+const exemplarsDir = join(srcDir, "exemplars");
+if (!existsSync(exemplarsDir)) {
+ throw new Error("prebuild: src/exemplars/ is missing");
+}
+const exemplarFiles = readdirSync(exemplarsDir)
+ .filter((f) => f.endsWith(".ts"))
+ .sort();
+if (exemplarFiles.length === 0) {
+ throw new Error("prebuild: src/exemplars/ contains no exemplars");
+}
+const exemplarSections = exemplarFiles.map((file) => {
+ const raw = readFileSync(join(exemplarsDir, file), "utf-8");
+ const specMatch = raw.match(/^\/\*\s*SPEC:\s*\n([\s\S]*?)\*\/\s*\n/);
+ if (!specMatch) {
+ throw new Error(`prebuild: ${file} is missing its leading /* SPEC: */ comment`);
+ }
+ const spec = specMatch[1].trim();
+ const implementation = raw.slice(specMatch[0].length).trim();
+ const title = file
+ .replace(/\.ts$/, "")
+ .split("-")
+ // Word-capitalize each hyphen segment, except known acronyms (e.g. "ai"
+ // -> "AI" for ai-responder.ts) which are upper-cased outright.
+ .map((w) =>
+ w.toLowerCase() === "ai" ? "AI" : w[0].toUpperCase() + w.slice(1)
+ )
+ .join(" ");
+ return `## Example: ${title}\n\n### Specification\n\n${spec}\n\n### Implementation\n\n\`\`\`typescript\n${implementation}\n\`\`\``;
+});
+const exemplarsContent = `/**
+ * Generated example twists for LLM generation prompts.
+ *
+ * This file is auto-generated during build. Do not edit manually.
+ * Generated from: src/exemplars/*.ts
+ */
+
+export default ${JSON.stringify(exemplarSections.join("\n\n"))};
+`;
+writeFileSync(join(llmDocsDir, "twist-exemplars.ts"), exemplarsContent, "utf-8");
+console.log(`✓ Generated twist-exemplars.ts from ${exemplarFiles.length} exemplars`);
+
 console.log(
  `✓ Generated ${typeFiles.length} LLM documentation files in src/llm-docs/`
 );

twister/src/creator-docs.ts

@@ -1,4 +1,5 @@
 import llmDocs from "./llm-docs/index.js";
+import twistExemplars from "./llm-docs/twist-exemplars.js";
 
 /**
  * Gets complete Twist Creator type definitions with import paths for LLM context.
@@ -27,3 +28,41 @@ export function getBuilderDocumentation(): string {
 
  return documentation;
 }
+
+// Modules excluded from TWIST generation docs: twists must never extend
+// Connector, and the mail-protocol tools are niche enough to dilute the
+// prompt more than they help.
+const TWIST_DOC_EXCLUSIONS = new Set([
+ "@plotday/twister/connector",
+ "@plotday/twister/tools/imap",
+ "@plotday/twister/tools/smtp",
+]);
+
+/**
+ * Twist-scoped variant of getBuilderDocumentation(): the same formatted
+ * type definitions, minus modules that are irrelevant (or misleading) when
+ * generating a twist.
+ */
+export function getTwistDocumentation(): string {
+ let documentation = "# Plot Twist Creator Type Definitions\n\n";
+ documentation +=
+ "Complete type definitions with JSDoc documentation for all Plot Twist Creator types.\n";
+ documentation +=
+ "These are the source files - use the import paths shown to import types in your twist code.\n\n";
+ for (const [importPath, content] of Object.entries(llmDocs)) {
+ if (TWIST_DOC_EXCLUSIONS.has(importPath)) continue;
+ documentation += `## ${importPath}\n\n`;
+ documentation += "```typescript\n";
+ documentation += `// Import from: ${importPath}\n\n`;
+ documentation += content;
+ documentation += "\n```\n\n";
+ }
+ return documentation;
+}
+
+/**
+ * Complete example twists (specification + implementation pairs) for LLM
+ * generation prompts. The examples are real compiled sources in
+ * src/exemplars/, so they are type-checked on every build.
+ */
+export const TWIST_EXEMPLARS: string = twistExemplars;

twister/src/exemplars/ai-responder.ts

@@ -0,0 +1,60 @@
+/* SPEC:
+When someone writes a journal note in another language, reply in the same
+thread with a short plain-English summary of what they wrote, so they can
+check their own understanding. Don't react to notes written by automations.
+*/
+import { ActorType, Twist, type Note, type ToolBuilder } from "@plotday/twister";
+import { AI } from "@plotday/twister/tools/ai";
+import { Plot, ThreadAccess } from "@plotday/twister/tools/plot";
+
+export default class LanguageJournal extends Twist<LanguageJournal> {
+ build(build: ToolBuilder) {
+ return {
+ plot: build(Plot, {
+ // onNoteCreated only fires for notes on threads this twist created,
+ // so Create access is required even though nothing else reads or
+ // updates other threads.
+ thread: { access: ThreadAccess.Create },
+ }),
+ ai: build(AI),
+ };
+ }
+
+ async activate() {
+ // Seed the standing thread the user writes journal entries into.
+ await this.tools.plot.createThread({
+ title: "Language journal",
+ notes: [
+ {
+ content:
+ "Write your journal entries here in any language — I'll reply with a plain-English summary.",
+ },
+ ],
+ });
+ }
+
+ // Fires for every new note on a thread this twist created. Guard against
+ // notes from twists/automations so we never loop on our own replies.
+ async onNoteCreated(note: Note): Promise<void> {
+ if (note.author.type === ActorType.Twist) {
+ return;
+ }
+ if (!note.content || note.content.trim().length === 0) {
+ return;
+ }
+
+ const response = await this.tools.ai.prompt({
+ model: { speed: "fast", cost: "low" },
+ prompt: `Summarize this journal entry in one or two plain-English sentences:\n\n${note.content}`,
+ });
+ if (!response.text) {
+ return;
+ }
+
+ // Reply in the same thread the note belongs to.
+ await this.tools.plot.createNote({
+ thread: { id: note.thread.id },
+ content: `English summary: ${response.text}`,
+ });
+ }
+}

twister/src/exemplars/authenticated-sync.ts

@@ -0,0 +1,84 @@
+/* SPEC:
+Connect to my bookmarking service account. Once connected, import my starred
+bookmarks as threads (title + link note), and check for new ones every hour.
+Imported bookmarks must not duplicate on re-sync.
+*/
+import { ActionType, Twist, type ToolBuilder, type Uuid } from "@plotday/twister";
+import { Options } from "@plotday/twister/options";
+import { Network } from "@plotday/twister/tools/network";
+import { Plot, ThreadAccess } from "@plotday/twister/tools/plot";
+
+export default class BookmarkSync extends Twist<BookmarkSync> {
+ build(build: ToolBuilder) {
+ return {
+ plot: build(Plot, {
+ thread: { access: ThreadAccess.Create },
+ }),
+ // Plain twists can't hold OAuth tokens — that machinery
+ // (provider/scopes/channels) belongs to Connectors. A secure Options
+ // field is the twist-safe way to let the user "connect" an account
+ // for a twist to call directly.
+ options: build(Options, {
+ apiKey: {
+ type: "text",
+ label: "Bookmarking service API key",
+ default: "",
+ secure: true,
+ },
+ }),
+ network: build(Network, {
+ urls: ["https://api.bookmarks.example/*"],
+ }),
+ };
+ }
+
+ async activate() {
+ // Re-runs hourly under a stable key; survives restarts and upgrades.
+ await this.scheduleRecurring(
+ "hourly-sync",
+ await this.callback(this.sync),
+ { intervalMs: 60 * 60 * 1000 }
+ );
+ await this.sync();
+ }
+
+ async sync(): Promise<void> {
+ const { apiKey } = this.tools.options;
+ if (!apiKey) {
+ return; // Not connected yet; nothing to sync.
+ }
+
+ const response = await fetch("https://api.bookmarks.example/v1/starred", {
+ headers: { Authorization: `Bearer ${apiKey}` },
+ });
+ if (!response.ok) {
+ return;
+ }
+ const { bookmarks } = (await response.json()) as {
+ bookmarks: Array<{ id: string; title: string; url: string }>;
+ };
+
+ // Threads a twist creates have no external Link (that's a Connector
+ // concept), so dedup is tracked manually: store the bookmark id -> thread
+ // id mapping and skip any bookmark that's already been imported.
+ for (const bookmark of bookmarks) {
+ const mappingKey = `bookmark:${bookmark.id}`;
+ if (await this.get<Uuid>(mappingKey)) {
+ continue;
+ }
+
+ const threadId = await this.tools.plot.createThread({
+ title: bookmark.title,
+ notes: [
+ {
+ content: bookmark.url,
+ actions: [
+ { type: ActionType.external, title: "Open bookmark", url: bookmark.url },
+ ],
+ },
+ ],
+ });
+ await this.set(mappingKey, threadId);
+ }
+ }
+}

twister/src/exemplars/scheduled-digest.ts

@@ -0,0 +1,61 @@
+/* SPEC:
+Every morning, post a thread with today's weather forecast for my city so I
+can plan the day. One thread per day, titled with the date.
+*/
+import { Twist, type ToolBuilder } from "@plotday/twister";
+import { Network } from "@plotday/twister/tools/network";
+import { Plot, ThreadAccess } from "@plotday/twister/tools/plot";
+
+export default class WeatherDigest extends Twist<WeatherDigest> {
+ build(build: ToolBuilder) {
+ return {
+ plot: build(Plot, {
+ thread: { access: ThreadAccess.Create },
+ }),
+ network: build(Network, {
+ urls: ["https://api.open-meteo.com/*"],
+ }),
+ };
+ }
+
+ async activate() {
+ await this.scheduleRecurring(
+ "morning-digest",
+ await this.callback(this.postDigest),
+ { intervalMs: 24 * 60 * 60 * 1000 }
+ );
+ }
+
+ async postDigest(): Promise<void> {
+ // Scheduled callbacks can fire more than once (at-least-once delivery),
+ // so guard "one thread per day" with a stored marker keyed on the date.
+ const today = new Date().toISOString().slice(0, 10);
+ const postedKey = `posted:${today}`;
+ if (await this.get<boolean>(postedKey)) {
+ return;
+ }
+
+ const response = await fetch(
+ "https://api.open-meteo.com/v1/forecast?latitude=43.65&longitude=-79.38&daily=temperature_2m_max,precipitation_probability_mean&timezone=auto&forecast_days=1"
+ );
+ if (!response.ok) {
+ return;
+ }
+ const data = (await response.json()) as {
+ daily: {
+ temperature_2m_max: number[];
+ precipitation_probability_mean: number[];
+ };
+ };
+
+ await this.tools.plot.createThread({
+ title: `Weather for ${today}`,
+ notes: [
+ {
+ content: `High of ${data.daily.temperature_2m_max[0]}°C, ${data.daily.precipitation_probability_mean[0]}% chance of rain.`,
+ },
+ ],
+ });
+ await this.set(postedKey, true);
+ }
+}

twister/tsconfig.build.json

@@ -8,7 +8,18 @@
  "declarationMap": true,
  "sourceMap": true,
  "noEmit": false,
- "composite": false
+ "composite": false,
+ // src/exemplars/*.ts import "@plotday/twister" by package name (so the
+ // embedded LLM-facing examples show real import paths, not relative
+ // ones). Resolving that self-reference requires the same
+ // moduleResolution + custom condition tsconfig.base.json already grants
+ // downstream twist/connector projects for the reverse case (resolving
+ // @plotday/twister straight to this package's src/*). Scoped to this
+ // build-only config (not tsconfig.json / tsconfig.cli.json) since
+ // "bundler" resolution is incompatible with tsconfig.cli.json's
+ // CommonJS output (TS5095).
+ "moduleResolution": "bundler",
+ "customConditions": ["@plotday/connector"]
  },
  "include": ["src/**/*.ts"],
  "exclude": [

twister/typedoc.json

@@ -18,11 +18,12 @@
  "src/utils/hash.ts"
  ],
  "out": "dist/docs",
- "tsconfig": "./tsconfig.json",
+ "tsconfig": "./tsconfig.build.json",
  "exclude": [
  "**/*+(.spec|.test).ts",
  "**/llm-docs/**",
  "**/cli/**",
+ "**/exemplars/**",
  "src/twist-guide.ts",
  "src/creator-docs.ts",
  "prebuild.ts",

.changeset/twist-prompt-docs.md

@@ -0,0 +1,5 @@
+---
+"@plotday/twister": minor
+---
+
+Added: getTwistDocumentation() (twist-scoped LLM documentation that omits connector-only modules) and TWIST_EXEMPLARS (complete example twists, compiled and type-checked on every build) for generation prompts.

twister/prebuild.ts

@@ -1,5 +1,12 @@
 #!/usr/bin/env node
-import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "fs";
+import {
+ existsSync,
+ mkdirSync,
+ readdirSync,
+ readFileSync,
+ rmSync,
+ writeFileSync,
+} from "fs";
 import { dirname, join } from "path";
 import { fileURLToPath } from "url";
 
@@ -189,6 +196,50 @@ export default ${JSON.stringify(twistsTemplateContent)};
  );
 }
 
+// Generate twist-exemplars.ts from src/exemplars/*.ts — complete example
+// twists embedded for LLM generation prompts. Each file must start with a
+// /* SPEC: ... */ block comment (the user-style specification it implements).
+const exemplarsDir = join(srcDir, "exemplars");
+if (!existsSync(exemplarsDir)) {
+ throw new Error("prebuild: src/exemplars/ is missing");
+}
+const exemplarFiles = readdirSync(exemplarsDir)
+ .filter((f) => f.endsWith(".ts"))
+ .sort();
+if (exemplarFiles.length === 0) {
+ throw new Error("prebuild: src/exemplars/ contains no exemplars");
+}
+const exemplarSections = exemplarFiles.map((file) => {
+ const raw = readFileSync(join(exemplarsDir, file), "utf-8");
+ const specMatch = raw.match(/^\/\*\s*SPEC:\s*\n([\s\S]*?)\*\/\s*\n/);
+ if (!specMatch) {
+ throw new Error(`prebuild: ${file} is missing its leading /* SPEC: */ comment`);
+ }
+ const spec = specMatch[1].trim();
+ const implementation = raw.slice(specMatch[0].length).trim();
+ const title = file
+ .replace(/\.ts$/, "")
+ .split("-")
+ // Word-capitalize each hyphen segment, except known acronyms (e.g. "ai"
+ // -> "AI" for ai-responder.ts) which are upper-cased outright.
+ .map((w) =>
+ w.toLowerCase() === "ai" ? "AI" : w[0].toUpperCase() + w.slice(1)
+ )
+ .join(" ");
+ return `## Example: ${title}\n\n### Specification\n\n${spec}\n\n### Implementation\n\n\`\`\`typescript\n${implementation}\n\`\`\``;
+});
+const exemplarsContent = `/**
+ * Generated example twists for LLM generation prompts.
+ *
+ * This file is auto-generated during build. Do not edit manually.
+ * Generated from: src/exemplars/*.ts
+ */
+
+export default ${JSON.stringify(exemplarSections.join("\n\n"))};
+`;
+writeFileSync(join(llmDocsDir, "twist-exemplars.ts"), exemplarsContent, "utf-8");
+console.log(`✓ Generated twist-exemplars.ts from ${exemplarFiles.length} exemplars`);
+
 console.log(
  `✓ Generated ${typeFiles.length} LLM documentation files in src/llm-docs/`
 );

twister/src/creator-docs.ts

@@ -1,4 +1,5 @@
 import llmDocs from "./llm-docs/index.js";
+import twistExemplars from "./llm-docs/twist-exemplars.js";
 
 /**
  * Gets complete Twist Creator type definitions with import paths for LLM context.
@@ -27,3 +28,41 @@ export function getBuilderDocumentation(): string {
 
  return documentation;
 }
+
+// Modules excluded from TWIST generation docs: twists must never extend
+// Connector, and the mail-protocol tools are niche enough to dilute the
+// prompt more than they help.
+const TWIST_DOC_EXCLUSIONS = new Set([
+ "@plotday/twister/connector",
+ "@plotday/twister/tools/imap",
+ "@plotday/twister/tools/smtp",
+]);
+
+/**
+ * Twist-scoped variant of getBuilderDocumentation(): the same formatted
+ * type definitions, minus modules that are irrelevant (or misleading) when
+ * generating a twist.
+ */
+export function getTwistDocumentation(): string {
+ let documentation = "# Plot Twist Creator Type Definitions\n\n";
+ documentation +=
+ "Complete type definitions with JSDoc documentation for all Plot Twist Creator types.\n";
+ documentation +=
+ "These are the source files - use the import paths shown to import types in your twist code.\n\n";
+ for (const [importPath, content] of Object.entries(llmDocs)) {
+ if (TWIST_DOC_EXCLUSIONS.has(importPath)) continue;
+ documentation += `## ${importPath}\n\n`;
+ documentation += "```typescript\n";
+ documentation += `// Import from: ${importPath}\n\n`;
+ documentation += content;
+ documentation += "\n```\n\n";
+ }
+ return documentation;
+}
+
+/**
+ * Complete example twists (specification + implementation pairs) for LLM
+ * generation prompts. The examples are real compiled sources in
+ * src/exemplars/, so they are type-checked on every build.
+ */
+export const TWIST_EXEMPLARS: string = twistExemplars;

twister/src/exemplars/ai-responder.ts

@@ -0,0 +1,60 @@
+/* SPEC:
+When someone writes a journal note in another language, reply in the same
+thread with a short plain-English summary of what they wrote, so they can
+check their own understanding. Don't react to notes written by automations.
+*/
+import { ActorType, Twist, type Note, type ToolBuilder } from "@plotday/twister";
+import { AI } from "@plotday/twister/tools/ai";
+import { Plot, ThreadAccess } from "@plotday/twister/tools/plot";
+
+export default class LanguageJournal extends Twist<LanguageJournal> {
+ build(build: ToolBuilder) {
+ return {
+ plot: build(Plot, {
+ // onNoteCreated only fires for notes on threads this twist created,
+ // so Create access is required even though nothing else reads or
+ // updates other threads.
+ thread: { access: ThreadAccess.Create },
+ }),
+ ai: build(AI),
+ };
+ }
+
+ async activate() {
+ // Seed the standing thread the user writes journal entries into.
+ await this.tools.plot.createThread({
+ title: "Language journal",
+ notes: [
+ {
+ content:
+ "Write your journal entries here in any language — I'll reply with a plain-English summary.",
+ },
+ ],
+ });
+ }
+
+ // Fires for every new note on a thread this twist created. Guard against
+ // notes from twists/automations so we never loop on our own replies.
+ async onNoteCreated(note: Note): Promise<void> {
+ if (note.author.type === ActorType.Twist) {
+ return;
+ }
+ if (!note.content || note.content.trim().length === 0) {
+ return;
+ }
+
+ const response = await this.tools.ai.prompt({
+ model: { speed: "fast", cost: "low" },
+ prompt: `Summarize this journal entry in one or two plain-English sentences:\n\n${note.content}`,
+ });
+ if (!response.text) {
+ return;
+ }
+
+ // Reply in the same thread the note belongs to.
+ await this.tools.plot.createNote({
+ thread: { id: note.thread.id },
+ content: `English summary: ${response.text}`,
+ });
+ }
+}

twister/src/exemplars/authenticated-sync.ts

@@ -0,0 +1,84 @@
+/* SPEC:
+Connect to my bookmarking service account. Once connected, import my starred
+bookmarks as threads (title + link note), and check for new ones every hour.
+Imported bookmarks must not duplicate on re-sync.
+*/
+import { ActionType, Twist, type ToolBuilder, type Uuid } from "@plotday/twister";
+import { Options } from "@plotday/twister/options";
+import { Network } from "@plotday/twister/tools/network";
+import { Plot, ThreadAccess } from "@plotday/twister/tools/plot";
+
+export default class BookmarkSync extends Twist<BookmarkSync> {
+ build(build: ToolBuilder) {
+ return {
+ plot: build(Plot, {
+ thread: { access: ThreadAccess.Create },
+ }),
+ // Plain twists can't hold OAuth tokens — that machinery
+ // (provider/scopes/channels) belongs to Connectors. A secure Options
+ // field is the twist-safe way to let the user "connect" an account
+ // for a twist to call directly.
+ options: build(Options, {
+ apiKey: {
+ type: "text",
+ label: "Bookmarking service API key",
+ default: "",
+ secure: true,
+ },
+ }),
+ network: build(Network, {
+ urls: ["https://api.bookmarks.example/*"],
+ }),
+ };
+ }
+
+ async activate() {
+ // Re-runs hourly under a stable key; survives restarts and upgrades.
+ await this.scheduleRecurring(
+ "hourly-sync",
+ await this.callback(this.sync),
+ { intervalMs: 60 * 60 * 1000 }
+ );
+ await this.sync();
+ }
+
+ async sync(): Promise<void> {
+ const { apiKey } = this.tools.options;
+ if (!apiKey) {
+ return; // Not connected yet; nothing to sync.
+ }
+
+ const response = await fetch("https://api.bookmarks.example/v1/starred", {
+ headers: { Authorization: `Bearer ${apiKey}` },
+ });
+ if (!response.ok) {
+ return;
+ }
+ const { bookmarks } = (await response.json()) as {
+ bookmarks: Array<{ id: string; title: string; url: string }>;
+ };
+
+ // Threads a twist creates have no external Link (that's a Connector
+ // concept), so dedup is tracked manually: store the bookmark id -> thread
+ // id mapping and skip any bookmark that's already been imported.
+ for (const bookmark of bookmarks) {
+ const mappingKey = `bookmark:${bookmark.id}`;
+ if (await this.get<Uuid>(mappingKey)) {
+ continue;
+ }
+
+ const threadId = await this.tools.plot.createThread({
+ title: bookmark.title,
+ notes: [
+ {
+ content: bookmark.url,
+ actions: [
+ { type: ActionType.external, title: "Open bookmark", url: bookmark.url },
+ ],
+ },
+ ],
+ });
+ await this.set(mappingKey, threadId);
+ }
+ }
+}

twister/src/exemplars/scheduled-digest.ts

@@ -0,0 +1,61 @@
+/* SPEC:
+Every morning, post a thread with today's weather forecast for my city so I
+can plan the day. One thread per day, titled with the date.
+*/
+import { Twist, type ToolBuilder } from "@plotday/twister";
+import { Network } from "@plotday/twister/tools/network";
+import { Plot, ThreadAccess } from "@plotday/twister/tools/plot";
+
+export default class WeatherDigest extends Twist<WeatherDigest> {
+ build(build: ToolBuilder) {
+ return {
+ plot: build(Plot, {
+ thread: { access: ThreadAccess.Create },
+ }),
+ network: build(Network, {
+ urls: ["https://api.open-meteo.com/*"],
+ }),
+ };
+ }
+
+ async activate() {
+ await this.scheduleRecurring(
+ "morning-digest",
+ await this.callback(this.postDigest),
+ { intervalMs: 24 * 60 * 60 * 1000 }
+ );
+ }
+
+ async postDigest(): Promise<void> {
+ // Scheduled callbacks can fire more than once (at-least-once delivery),
+ // so guard "one thread per day" with a stored marker keyed on the date.
+ const today = new Date().toISOString().slice(0, 10);
+ const postedKey = `posted:${today}`;
+ if (await this.get<boolean>(postedKey)) {
+ return;
+ }
+
+ const response = await fetch(
+ "https://api.open-meteo.com/v1/forecast?latitude=43.65&longitude=-79.38&daily=temperature_2m_max,precipitation_probability_mean&timezone=auto&forecast_days=1"
+ );
+ if (!response.ok) {
+ return;
+ }
+ const data = (await response.json()) as {
+ daily: {
+ temperature_2m_max: number[];
+ precipitation_probability_mean: number[];
+ };
+ };
+
+ await this.tools.plot.createThread({
+ title: `Weather for ${today}`,
+ notes: [
+ {
+ content: `High of ${data.daily.temperature_2m_max[0]}°C, ${data.daily.precipitation_probability_mean[0]}% chance of rain.`,
+ },
+ ],
+ });
+ await this.set(postedKey, true);
+ }
+}

twister/tsconfig.build.json

@@ -8,7 +8,18 @@
  "declarationMap": true,
  "sourceMap": true,
  "noEmit": false,
- "composite": false
+ "composite": false,
+ // src/exemplars/*.ts import "@plotday/twister" by package name (so the
+ // embedded LLM-facing examples show real import paths, not relative
+ // ones). Resolving that self-reference requires the same
+ // moduleResolution + custom condition tsconfig.base.json already grants
+ // downstream twist/connector projects for the reverse case (resolving
+ // @plotday/twister straight to this package's src/*). Scoped to this
+ // build-only config (not tsconfig.json / tsconfig.cli.json) since
+ // "bundler" resolution is incompatible with tsconfig.cli.json's
+ // CommonJS output (TS5095).
+ "moduleResolution": "bundler",
+ "customConditions": ["@plotday/connector"]
  },
  "include": ["src/**/*.ts"],
  "exclude": [

twister/typedoc.json

@@ -18,11 +18,12 @@
  "src/utils/hash.ts"
  ],
  "out": "dist/docs",
- "tsconfig": "./tsconfig.json",
+ "tsconfig": "./tsconfig.build.json",
  "exclude": [
  "**/*+(.spec|.test).ts",
  "**/llm-docs/**",
  "**/cli/**",
+ "**/exemplars/**",
  "src/twist-guide.ts",
  "src/creator-docs.ts",
  "prebuild.ts",

.changeset/twist-prompt-docs.md

@@ -0,0 +1,5 @@
+---
+"@plotday/twister": minor
+---
+
+Added: getTwistDocumentation() (twist-scoped LLM documentation that omits connector-only modules) and TWIST_EXEMPLARS (complete example twists, compiled and type-checked on every build) for generation prompts.

twister/prebuild.ts

@@ -1,5 +1,12 @@
 #!/usr/bin/env node
-import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "fs";
+import {
+ existsSync,
+ mkdirSync,
+ readdirSync,
+ readFileSync,
+ rmSync,
+ writeFileSync,
+} from "fs";
 import { dirname, join } from "path";
 import { fileURLToPath } from "url";
 
@@ -189,6 +196,50 @@ export default ${JSON.stringify(twistsTemplateContent)};
  );
 }
 
+// Generate twist-exemplars.ts from src/exemplars/*.ts — complete example
+// twists embedded for LLM generation prompts. Each file must start with a
+// /* SPEC: ... */ block comment (the user-style specification it implements).
+const exemplarsDir = join(srcDir, "exemplars");
+if (!existsSync(exemplarsDir)) {
+ throw new Error("prebuild: src/exemplars/ is missing");
+}
+const exemplarFiles = readdirSync(exemplarsDir)
+ .filter((f) => f.endsWith(".ts"))
+ .sort();
+if (exemplarFiles.length === 0) {
+ throw new Error("prebuild: src/exemplars/ contains no exemplars");
+}
+const exemplarSections = exemplarFiles.map((file) => {
+ const raw = readFileSync(join(exemplarsDir, file), "utf-8");
+ const specMatch = raw.match(/^\/\*\s*SPEC:\s*\n([\s\S]*?)\*\/\s*\n/);
+ if (!specMatch) {
+ throw new Error(`prebuild: ${file} is missing its leading /* SPEC: */ comment`);
+ }
+ const spec = specMatch[1].trim();
+ const implementation = raw.slice(specMatch[0].length).trim();
+ const title = file
+ .replace(/\.ts$/, "")
+ .split("-")
+ // Word-capitalize each hyphen segment, except known acronyms (e.g. "ai"
+ // -> "AI" for ai-responder.ts) which are upper-cased outright.
+ .map((w) =>
+ w.toLowerCase() === "ai" ? "AI" : w[0].toUpperCase() + w.slice(1)
+ )
+ .join(" ");
+ return `## Example: ${title}\n\n### Specification\n\n${spec}\n\n### Implementation\n\n\`\`\`typescript\n${implementation}\n\`\`\``;
+});
+const exemplarsContent = `/**
+ * Generated example twists for LLM generation prompts.
+ *
+ * This file is auto-generated during build. Do not edit manually.
+ * Generated from: src/exemplars/*.ts
+ */
+
+export default ${JSON.stringify(exemplarSections.join("\n\n"))};
+`;
+writeFileSync(join(llmDocsDir, "twist-exemplars.ts"), exemplarsContent, "utf-8");
+console.log(`✓ Generated twist-exemplars.ts from ${exemplarFiles.length} exemplars`);
+
 console.log(
  `✓ Generated ${typeFiles.length} LLM documentation files in src/llm-docs/`
 );

twister/src/creator-docs.ts

@@ -1,4 +1,5 @@
 import llmDocs from "./llm-docs/index.js";
+import twistExemplars from "./llm-docs/twist-exemplars.js";
 
 /**
  * Gets complete Twist Creator type definitions with import paths for LLM context.
@@ -27,3 +28,41 @@ export function getBuilderDocumentation(): string {
 
  return documentation;
 }
+
+// Modules excluded from TWIST generation docs: twists must never extend
+// Connector, and the mail-protocol tools are niche enough to dilute the
+// prompt more than they help.
+const TWIST_DOC_EXCLUSIONS = new Set([
+ "@plotday/twister/connector",
+ "@plotday/twister/tools/imap",
+ "@plotday/twister/tools/smtp",
+]);
+
+/**
+ * Twist-scoped variant of getBuilderDocumentation(): the same formatted
+ * type definitions, minus modules that are irrelevant (or misleading) when
+ * generating a twist.
+ */
+export function getTwistDocumentation(): string {
+ let documentation = "# Plot Twist Creator Type Definitions\n\n";
+ documentation +=
+ "Complete type definitions with JSDoc documentation for all Plot Twist Creator types.\n";
+ documentation +=
+ "These are the source files - use the import paths shown to import types in your twist code.\n\n";
+ for (const [importPath, content] of Object.entries(llmDocs)) {
+ if (TWIST_DOC_EXCLUSIONS.has(importPath)) continue;
+ documentation += `## ${importPath}\n\n`;
+ documentation += "```typescript\n";
+ documentation += `// Import from: ${importPath}\n\n`;
+ documentation += content;
+ documentation += "\n```\n\n";
+ }
+ return documentation;
+}
+
+/**
+ * Complete example twists (specification + implementation pairs) for LLM
+ * generation prompts. The examples are real compiled sources in
+ * src/exemplars/, so they are type-checked on every build.
+ */
+export const TWIST_EXEMPLARS: string = twistExemplars;

twister/src/exemplars/ai-responder.ts

@@ -0,0 +1,60 @@
+/* SPEC:
+When someone writes a journal note in another language, reply in the same
+thread with a short plain-English summary of what they wrote, so they can
+check their own understanding. Don't react to notes written by automations.
+*/
+import { ActorType, Twist, type Note, type ToolBuilder } from "@plotday/twister";
+import { AI } from "@plotday/twister/tools/ai";
+import { Plot, ThreadAccess } from "@plotday/twister/tools/plot";
+
+export default class LanguageJournal extends Twist<LanguageJournal> {
+ build(build: ToolBuilder) {
+ return {
+ plot: build(Plot, {
+ // onNoteCreated only fires for notes on threads this twist created,
+ // so Create access is required even though nothing else reads or
+ // updates other threads.
+ thread: { access: ThreadAccess.Create },
+ }),
+ ai: build(AI),
+ };
+ }
+
+ async activate() {
+ // Seed the standing thread the user writes journal entries into.
+ await this.tools.plot.createThread({
+ title: "Language journal",
+ notes: [
+ {
+ content:
+ "Write your journal entries here in any language — I'll reply with a plain-English summary.",
+ },
+ ],
+ });
+ }
+
+ // Fires for every new note on a thread this twist created. Guard against
+ // notes from twists/automations so we never loop on our own replies.
+ async onNoteCreated(note: Note): Promise<void> {
+ if (note.author.type === ActorType.Twist) {
+ return;
+ }
+ if (!note.content || note.content.trim().length === 0) {
+ return;
+ }
+
+ const response = await this.tools.ai.prompt({
+ model: { speed: "fast", cost: "low" },
+ prompt: `Summarize this journal entry in one or two plain-English sentences:\n\n${note.content}`,
+ });
+ if (!response.text) {
+ return;
+ }
+
+ // Reply in the same thread the note belongs to.
+ await this.tools.plot.createNote({
+ thread: { id: note.thread.id },
+ content: `English summary: ${response.text}`,
+ });
+ }
+}

twister/src/exemplars/authenticated-sync.ts

@@ -0,0 +1,84 @@
+/* SPEC:
+Connect to my bookmarking service account. Once connected, import my starred
+bookmarks as threads (title + link note), and check for new ones every hour.
+Imported bookmarks must not duplicate on re-sync.
+*/
+import { ActionType, Twist, type ToolBuilder, type Uuid } from "@plotday/twister";
+import { Options } from "@plotday/twister/options";
+import { Network } from "@plotday/twister/tools/network";
+import { Plot, ThreadAccess } from "@plotday/twister/tools/plot";
+
+export default class BookmarkSync extends Twist<BookmarkSync> {
+ build(build: ToolBuilder) {
+ return {
+ plot: build(Plot, {
+ thread: { access: ThreadAccess.Create },
+ }),
+ // Plain twists can't hold OAuth tokens — that machinery
+ // (provider/scopes/channels) belongs to Connectors. A secure Options
+ // field is the twist-safe way to let the user "connect" an account
+ // for a twist to call directly.
+ options: build(Options, {
+ apiKey: {
+ type: "text",
+ label: "Bookmarking service API key",
+ default: "",
+ secure: true,
+ },
+ }),
+ network: build(Network, {
+ urls: ["https://api.bookmarks.example/*"],
+ }),
+ };
+ }
+
+ async activate() {
+ // Re-runs hourly under a stable key; survives restarts and upgrades.
+ await this.scheduleRecurring(
+ "hourly-sync",
+ await this.callback(this.sync),
+ { intervalMs: 60 * 60 * 1000 }
+ );
+ await this.sync();
+ }
+
+ async sync(): Promise<void> {
+ const { apiKey } = this.tools.options;
+ if (!apiKey) {
+ return; // Not connected yet; nothing to sync.
+ }
+
+ const response = await fetch("https://api.bookmarks.example/v1/starred", {
+ headers: { Authorization: `Bearer ${apiKey}` },
+ });
+ if (!response.ok) {
+ return;
+ }
+ const { bookmarks } = (await response.json()) as {
+ bookmarks: Array<{ id: string; title: string; url: string }>;
+ };
+
+ // Threads a twist creates have no external Link (that's a Connector
+ // concept), so dedup is tracked manually: store the bookmark id -> thread
+ // id mapping and skip any bookmark that's already been imported.
+ for (const bookmark of bookmarks) {
+ const mappingKey = `bookmark:${bookmark.id}`;
+ if (await this.get<Uuid>(mappingKey)) {
+ continue;
+ }
+
+ const threadId = await this.tools.plot.createThread({
+ title: bookmark.title,
+ notes: [
+ {
+ content: bookmark.url,
+ actions: [
+ { type: ActionType.external, title: "Open bookmark", url: bookmark.url },
+ ],
+ },
+ ],
+ });
+ await this.set(mappingKey, threadId);
+ }
+ }
+}

twister/src/exemplars/scheduled-digest.ts

@@ -0,0 +1,61 @@
+/* SPEC:
+Every morning, post a thread with today's weather forecast for my city so I
+can plan the day. One thread per day, titled with the date.
+*/
+import { Twist, type ToolBuilder } from "@plotday/twister";
+import { Network } from "@plotday/twister/tools/network";
+import { Plot, ThreadAccess } from "@plotday/twister/tools/plot";
+
+export default class WeatherDigest extends Twist<WeatherDigest> {
+ build(build: ToolBuilder) {
+ return {
+ plot: build(Plot, {
+ thread: { access: ThreadAccess.Create },
+ }),
+ network: build(Network, {
+ urls: ["https://api.open-meteo.com/*"],
+ }),
+ };
+ }
+
+ async activate() {
+ await this.scheduleRecurring(
+ "morning-digest",
+ await this.callback(this.postDigest),
+ { intervalMs: 24 * 60 * 60 * 1000 }
+ );
+ }
+
+ async postDigest(): Promise<void> {
+ // Scheduled callbacks can fire more than once (at-least-once delivery),
+ // so guard "one thread per day" with a stored marker keyed on the date.
+ const today = new Date().toISOString().slice(0, 10);
+ const postedKey = `posted:${today}`;
+ if (await this.get<boolean>(postedKey)) {
+ return;
+ }
+
+ const response = await fetch(
+ "https://api.open-meteo.com/v1/forecast?latitude=43.65&longitude=-79.38&daily=temperature_2m_max,precipitation_probability_mean&timezone=auto&forecast_days=1"
+ );
+ if (!response.ok) {
+ return;
+ }
+ const data = (await response.json()) as {
+ daily: {
+ temperature_2m_max: number[];
+ precipitation_probability_mean: number[];
+ };
+ };
+
+ await this.tools.plot.createThread({
+ title: `Weather for ${today}`,
+ notes: [
+ {
+ content: `High of ${data.daily.temperature_2m_max[0]}°C, ${data.daily.precipitation_probability_mean[0]}% chance of rain.`,
+ },
+ ],
+ });
+ await this.set(postedKey, true);
+ }
+}

twister/tsconfig.build.json

@@ -8,7 +8,18 @@
  "declarationMap": true,
  "sourceMap": true,
  "noEmit": false,
- "composite": false
+ "composite": false,
+ // src/exemplars/*.ts import "@plotday/twister" by package name (so the
+ // embedded LLM-facing examples show real import paths, not relative
+ // ones). Resolving that self-reference requires the same
+ // moduleResolution + custom condition tsconfig.base.json already grants
+ // downstream twist/connector projects for the reverse case (resolving
+ // @plotday/twister straight to this package's src/*). Scoped to this
+ // build-only config (not tsconfig.json / tsconfig.cli.json) since
+ // "bundler" resolution is incompatible with tsconfig.cli.json's
+ // CommonJS output (TS5095).
+ "moduleResolution": "bundler",
+ "customConditions": ["@plotday/connector"]
  },
  "include": ["src/**/*.ts"],
  "exclude": [

twister/typedoc.json

@@ -18,11 +18,12 @@
  "src/utils/hash.ts"
  ],
  "out": "dist/docs",
- "tsconfig": "./tsconfig.json",
+ "tsconfig": "./tsconfig.build.json",
  "exclude": [
  "**/*+(.spec|.test).ts",
  "**/llm-docs/**",
  "**/cli/**",
+ "**/exemplars/**",
  "src/twist-guide.ts",
  "src/creator-docs.ts",
  "prebuild.ts",

.changeset/twist-prompt-docs.md

@@ -0,0 +1,5 @@
+---
+"@plotday/twister": minor
+---
+
+Added: getTwistDocumentation() (twist-scoped LLM documentation that omits connector-only modules) and TWIST_EXEMPLARS (complete example twists, compiled and type-checked on every build) for generation prompts.

twister/prebuild.ts

@@ -1,5 +1,12 @@
 #!/usr/bin/env node
-import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "fs";
+import {
+ existsSync,
+ mkdirSync,
+ readdirSync,
+ readFileSync,
+ rmSync,
+ writeFileSync,
+} from "fs";
 import { dirname, join } from "path";
 import { fileURLToPath } from "url";
 
@@ -189,6 +196,50 @@ export default ${JSON.stringify(twistsTemplateContent)};
  );
 }
 
+// Generate twist-exemplars.ts from src/exemplars/*.ts — complete example
+// twists embedded for LLM generation prompts. Each file must start with a
+// /* SPEC: ... */ block comment (the user-style specification it implements).
+const exemplarsDir = join(srcDir, "exemplars");
+if (!existsSync(exemplarsDir)) {
+ throw new Error("prebuild: src/exemplars/ is missing");
+}
+const exemplarFiles = readdirSync(exemplarsDir)
+ .filter((f) => f.endsWith(".ts"))
+ .sort();
+if (exemplarFiles.length === 0) {
+ throw new Error("prebuild: src/exemplars/ contains no exemplars");
+}
+const exemplarSections = exemplarFiles.map((file) => {
+ const raw = readFileSync(join(exemplarsDir, file), "utf-8");
+ const specMatch = raw.match(/^\/\*\s*SPEC:\s*\n([\s\S]*?)\*\/\s*\n/);
+ if (!specMatch) {
+ throw new Error(`prebuild: ${file} is missing its leading /* SPEC: */ comment`);
+ }
+ const spec = specMatch[1].trim();
+ const implementation = raw.slice(specMatch[0].length).trim();
+ const title = file
+ .replace(/\.ts$/, "")
+ .split("-")
+ // Word-capitalize each hyphen segment, except known acronyms (e.g. "ai"
+ // -> "AI" for ai-responder.ts) which are upper-cased outright.
+ .map((w) =>
+ w.toLowerCase() === "ai" ? "AI" : w[0].toUpperCase() + w.slice(1)
+ )
+ .join(" ");
+ return `## Example: ${title}\n\n### Specification\n\n${spec}\n\n### Implementation\n\n\`\`\`typescript\n${implementation}\n\`\`\``;
+});
+const exemplarsContent = `/**
+ * Generated example twists for LLM generation prompts.
+ *
+ * This file is auto-generated during build. Do not edit manually.
+ * Generated from: src/exemplars/*.ts
+ */
+
+export default ${JSON.stringify(exemplarSections.join("\n\n"))};
+`;
+writeFileSync(join(llmDocsDir, "twist-exemplars.ts"), exemplarsContent, "utf-8");
+console.log(`✓ Generated twist-exemplars.ts from ${exemplarFiles.length} exemplars`);
+
 console.log(
  `✓ Generated ${typeFiles.length} LLM documentation files in src/llm-docs/`
 );

twister/src/creator-docs.ts

@@ -1,4 +1,5 @@
 import llmDocs from "./llm-docs/index.js";
+import twistExemplars from "./llm-docs/twist-exemplars.js";
 
 /**
  * Gets complete Twist Creator type definitions with import paths for LLM context.
@@ -27,3 +28,41 @@ export function getBuilderDocumentation(): string {
 
  return documentation;
 }
+
+// Modules excluded from TWIST generation docs: twists must never extend
+// Connector, and the mail-protocol tools are niche enough to dilute the
+// prompt more than they help.
+const TWIST_DOC_EXCLUSIONS = new Set([
+ "@plotday/twister/connector",
+ "@plotday/twister/tools/imap",
+ "@plotday/twister/tools/smtp",
+]);
+
+/**
+ * Twist-scoped variant of getBuilderDocumentation(): the same formatted
+ * type definitions, minus modules that are irrelevant (or misleading) when
+ * generating a twist.
+ */
+export function getTwistDocumentation(): string {
+ let documentation = "# Plot Twist Creator Type Definitions\n\n";
+ documentation +=
+ "Complete type definitions with JSDoc documentation for all Plot Twist Creator types.\n";
+ documentation +=
+ "These are the source files - use the import paths shown to import types in your twist code.\n\n";
+ for (const [importPath, content] of Object.entries(llmDocs)) {
+ if (TWIST_DOC_EXCLUSIONS.has(importPath)) continue;
+ documentation += `## ${importPath}\n\n`;
+ documentation += "```typescript\n";
+ documentation += `// Import from: ${importPath}\n\n`;
+ documentation += content;
+ documentation += "\n```\n\n";
+ }
+ return documentation;
+}
+
+/**
+ * Complete example twists (specification + implementation pairs) for LLM
+ * generation prompts. The examples are real compiled sources in
+ * src/exemplars/, so they are type-checked on every build.
+ */
+export const TWIST_EXEMPLARS: string = twistExemplars;

twister/src/exemplars/ai-responder.ts

@@ -0,0 +1,60 @@
+/* SPEC:
+When someone writes a journal note in another language, reply in the same
+thread with a short plain-English summary of what they wrote, so they can
+check their own understanding. Don't react to notes written by automations.
+*/
+import { ActorType, Twist, type Note, type ToolBuilder } from "@plotday/twister";
+import { AI } from "@plotday/twister/tools/ai";
+import { Plot, ThreadAccess } from "@plotday/twister/tools/plot";
+
+export default class LanguageJournal extends Twist<LanguageJournal> {
+ build(build: ToolBuilder) {
+ return {
+ plot: build(Plot, {
+ // onNoteCreated only fires for notes on threads this twist created,
+ // so Create access is required even though nothing else reads or
+ // updates other threads.
+ thread: { access: ThreadAccess.Create },
+ }),
+ ai: build(AI),
+ };
+ }
+
+ async activate() {
+ // Seed the standing thread the user writes journal entries into.
+ await this.tools.plot.createThread({
+ title: "Language journal",
+ notes: [
+ {
+ content:
+ "Write your journal entries here in any language — I'll reply with a plain-English summary.",
+ },
+ ],
+ });
+ }
+
+ // Fires for every new note on a thread this twist created. Guard against
+ // notes from twists/automations so we never loop on our own replies.
+ async onNoteCreated(note: Note): Promise<void> {
+ if (note.author.type === ActorType.Twist) {
+ return;
+ }
+ if (!note.content || note.content.trim().length === 0) {
+ return;
+ }
+
+ const response = await this.tools.ai.prompt({
+ model: { speed: "fast", cost: "low" },
+ prompt: `Summarize this journal entry in one or two plain-English sentences:\n\n${note.content}`,
+ });
+ if (!response.text) {
+ return;
+ }
+
+ // Reply in the same thread the note belongs to.
+ await this.tools.plot.createNote({
+ thread: { id: note.thread.id },
+ content: `English summary: ${response.text}`,
+ });
+ }
+}

twister/src/exemplars/authenticated-sync.ts

@@ -0,0 +1,84 @@
+/* SPEC:
+Connect to my bookmarking service account. Once connected, import my starred
+bookmarks as threads (title + link note), and check for new ones every hour.
+Imported bookmarks must not duplicate on re-sync.
+*/
+import { ActionType, Twist, type ToolBuilder, type Uuid } from "@plotday/twister";
+import { Options } from "@plotday/twister/options";
+import { Network } from "@plotday/twister/tools/network";
+import { Plot, ThreadAccess } from "@plotday/twister/tools/plot";
+
+export default class BookmarkSync extends Twist<BookmarkSync> {
+ build(build: ToolBuilder) {
+ return {
+ plot: build(Plot, {
+ thread: { access: ThreadAccess.Create },
+ }),
+ // Plain twists can't hold OAuth tokens — that machinery
+ // (provider/scopes/channels) belongs to Connectors. A secure Options
+ // field is the twist-safe way to let the user "connect" an account
+ // for a twist to call directly.
+ options: build(Options, {
+ apiKey: {
+ type: "text",
+ label: "Bookmarking service API key",
+ default: "",
+ secure: true,
+ },
+ }),
+ network: build(Network, {
+ urls: ["https://api.bookmarks.example/*"],
+ }),
+ };
+ }
+
+ async activate() {
+ // Re-runs hourly under a stable key; survives restarts and upgrades.
+ await this.scheduleRecurring(
+ "hourly-sync",
+ await this.callback(this.sync),
+ { intervalMs: 60 * 60 * 1000 }
+ );
+ await this.sync();
+ }
+
+ async sync(): Promise<void> {
+ const { apiKey } = this.tools.options;
+ if (!apiKey) {
+ return; // Not connected yet; nothing to sync.
+ }
+
+ const response = await fetch("https://api.bookmarks.example/v1/starred", {
+ headers: { Authorization: `Bearer ${apiKey}` },
+ });
+ if (!response.ok) {
+ return;
+ }
+ const { bookmarks } = (await response.json()) as {
+ bookmarks: Array<{ id: string; title: string; url: string }>;
+ };
+
+ // Threads a twist creates have no external Link (that's a Connector
+ // concept), so dedup is tracked manually: store the bookmark id -> thread
+ // id mapping and skip any bookmark that's already been imported.
+ for (const bookmark of bookmarks) {
+ const mappingKey = `bookmark:${bookmark.id}`;
+ if (await this.get<Uuid>(mappingKey)) {
+ continue;
+ }
+
+ const threadId = await this.tools.plot.createThread({
+ title: bookmark.title,
+ notes: [
+ {
+ content: bookmark.url,
+ actions: [
+ { type: ActionType.external, title: "Open bookmark", url: bookmark.url },
+ ],
+ },
+ ],
+ });
+ await this.set(mappingKey, threadId);
+ }
+ }
+}

twister/src/exemplars/scheduled-digest.ts

@@ -0,0 +1,61 @@
+/* SPEC:
+Every morning, post a thread with today's weather forecast for my city so I
+can plan the day. One thread per day, titled with the date.
+*/
+import { Twist, type ToolBuilder } from "@plotday/twister";
+import { Network } from "@plotday/twister/tools/network";
+import { Plot, ThreadAccess } from "@plotday/twister/tools/plot";
+
+export default class WeatherDigest extends Twist<WeatherDigest> {
+ build(build: ToolBuilder) {
+ return {
+ plot: build(Plot, {
+ thread: { access: ThreadAccess.Create },
+ }),
+ network: build(Network, {
+ urls: ["https://api.open-meteo.com/*"],
+ }),
+ };
+ }
+
+ async activate() {
+ await this.scheduleRecurring(
+ "morning-digest",
+ await this.callback(this.postDigest),
+ { intervalMs: 24 * 60 * 60 * 1000 }
+ );
+ }
+
+ async postDigest(): Promise<void> {
+ // Scheduled callbacks can fire more than once (at-least-once delivery),
+ // so guard "one thread per day" with a stored marker keyed on the date.
+ const today = new Date().toISOString().slice(0, 10);
+ const postedKey = `posted:${today}`;
+ if (await this.get<boolean>(postedKey)) {
+ return;
+ }
+
+ const response = await fetch(
+ "https://api.open-meteo.com/v1/forecast?latitude=43.65&longitude=-79.38&daily=temperature_2m_max,precipitation_probability_mean&timezone=auto&forecast_days=1"
+ );
+ if (!response.ok) {
+ return;
+ }
+ const data = (await response.json()) as {
+ daily: {
+ temperature_2m_max: number[];
+ precipitation_probability_mean: number[];
+ };
+ };
+
+ await this.tools.plot.createThread({
+ title: `Weather for ${today}`,
+ notes: [
+ {
+ content: `High of ${data.daily.temperature_2m_max[0]}°C, ${data.daily.precipitation_probability_mean[0]}% chance of rain.`,
+ },
+ ],
+ });
+ await this.set(postedKey, true);
+ }
+}

twister/tsconfig.build.json

@@ -8,7 +8,18 @@
  "declarationMap": true,
  "sourceMap": true,
  "noEmit": false,
- "composite": false
+ "composite": false,
+ // src/exemplars/*.ts import "@plotday/twister" by package name (so the
+ // embedded LLM-facing examples show real import paths, not relative
+ // ones). Resolving that self-reference requires the same
+ // moduleResolution + custom condition tsconfig.base.json already grants
+ // downstream twist/connector projects for the reverse case (resolving
+ // @plotday/twister straight to this package's src/*). Scoped to this
+ // build-only config (not tsconfig.json / tsconfig.cli.json) since
+ // "bundler" resolution is incompatible with tsconfig.cli.json's
+ // CommonJS output (TS5095).
+ "moduleResolution": "bundler",
+ "customConditions": ["@plotday/connector"]
  },
  "include": ["src/**/*.ts"],
  "exclude": [

twister/typedoc.json

@@ -18,11 +18,12 @@
  "src/utils/hash.ts"
  ],
  "out": "dist/docs",
- "tsconfig": "./tsconfig.json",
+ "tsconfig": "./tsconfig.build.json",
  "exclude": [
  "**/*+(.spec|.test).ts",
  "**/llm-docs/**",
  "**/cli/**",
+ "**/exemplars/**",
  "src/twist-guide.ts",
  "src/creator-docs.ts",
  "prebuild.ts",

.changeset/twist-prompt-docs.md

@@ -0,0 +1,5 @@
+---
+"@plotday/twister": minor
+---
+
+Added: getTwistDocumentation() (twist-scoped LLM documentation that omits connector-only modules) and TWIST_EXEMPLARS (complete example twists, compiled and type-checked on every build) for generation prompts.

twister/prebuild.ts

@@ -1,5 +1,12 @@
 #!/usr/bin/env node
-import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "fs";
+import {
+ existsSync,
+ mkdirSync,
+ readdirSync,
+ readFileSync,
+ rmSync,
+ writeFileSync,
+} from "fs";
 import { dirname, join } from "path";
 import { fileURLToPath } from "url";
 
@@ -189,6 +196,50 @@ export default ${JSON.stringify(twistsTemplateContent)};
  );
 }
 
+// Generate twist-exemplars.ts from src/exemplars/*.ts — complete example
+// twists embedded for LLM generation prompts. Each file must start with a
+// /* SPEC: ... */ block comment (the user-style specification it implements).
+const exemplarsDir = join(srcDir, "exemplars");
+if (!existsSync(exemplarsDir)) {
+ throw new Error("prebuild: src/exemplars/ is missing");
+}
+const exemplarFiles = readdirSync(exemplarsDir)
+ .filter((f) => f.endsWith(".ts"))
+ .sort();
+if (exemplarFiles.length === 0) {
+ throw new Error("prebuild: src/exemplars/ contains no exemplars");
+}
+const exemplarSections = exemplarFiles.map((file) => {
+ const raw = readFileSync(join(exemplarsDir, file), "utf-8");
+ const specMatch = raw.match(/^\/\*\s*SPEC:\s*\n([\s\S]*?)\*\/\s*\n/);
+ if (!specMatch) {
+ throw new Error(`prebuild: ${file} is missing its leading /* SPEC: */ comment`);
+ }
+ const spec = specMatch[1].trim();
+ const implementation = raw.slice(specMatch[0].length).trim();
+ const title = file
+ .replace(/\.ts$/, "")
+ .split("-")
+ // Word-capitalize each hyphen segment, except known acronyms (e.g. "ai"
+ // -> "AI" for ai-responder.ts) which are upper-cased outright.
+ .map((w) =>
+ w.toLowerCase() === "ai" ? "AI" : w[0].toUpperCase() + w.slice(1)
+ )
+ .join(" ");
+ return `## Example: ${title}\n\n### Specification\n\n${spec}\n\n### Implementation\n\n\`\`\`typescript\n${implementation}\n\`\`\``;
+});
+const exemplarsContent = `/**
+ * Generated example twists for LLM generation prompts.
+ *
+ * This file is auto-generated during build. Do not edit manually.
+ * Generated from: src/exemplars/*.ts
+ */
+
+export default ${JSON.stringify(exemplarSections.join("\n\n"))};
+`;
+writeFileSync(join(llmDocsDir, "twist-exemplars.ts"), exemplarsContent, "utf-8");
+console.log(`✓ Generated twist-exemplars.ts from ${exemplarFiles.length} exemplars`);
+
 console.log(
  `✓ Generated ${typeFiles.length} LLM documentation files in src/llm-docs/`
 );

twister/src/creator-docs.ts

@@ -1,4 +1,5 @@
 import llmDocs from "./llm-docs/index.js";
+import twistExemplars from "./llm-docs/twist-exemplars.js";
 
 /**
  * Gets complete Twist Creator type definitions with import paths for LLM context.
@@ -27,3 +28,41 @@ export function getBuilderDocumentation(): string {
 
  return documentation;
 }
+
+// Modules excluded from TWIST generation docs: twists must never extend
+// Connector, and the mail-protocol tools are niche enough to dilute the
+// prompt more than they help.
+const TWIST_DOC_EXCLUSIONS = new Set([
+ "@plotday/twister/connector",
+ "@plotday/twister/tools/imap",
+ "@plotday/twister/tools/smtp",
+]);
+
+/**
+ * Twist-scoped variant of getBuilderDocumentation(): the same formatted
+ * type definitions, minus modules that are irrelevant (or misleading) when
+ * generating a twist.
+ */
+export function getTwistDocumentation(): string {
+ let documentation = "# Plot Twist Creator Type Definitions\n\n";
+ documentation +=
+ "Complete type definitions with JSDoc documentation for all Plot Twist Creator types.\n";
+ documentation +=
+ "These are the source files - use the import paths shown to import types in your twist code.\n\n";
+ for (const [importPath, content] of Object.entries(llmDocs)) {
+ if (TWIST_DOC_EXCLUSIONS.has(importPath)) continue;
+ documentation += `## ${importPath}\n\n`;
+ documentation += "```typescript\n";
+ documentation += `// Import from: ${importPath}\n\n`;
+ documentation += content;
+ documentation += "\n```\n\n";
+ }
+ return documentation;
+}
+
+/**
+ * Complete example twists (specification + implementation pairs) for LLM
+ * generation prompts. The examples are real compiled sources in
+ * src/exemplars/, so they are type-checked on every build.
+ */
+export const TWIST_EXEMPLARS: string = twistExemplars;

twister/src/exemplars/ai-responder.ts

@@ -0,0 +1,60 @@
+/* SPEC:
+When someone writes a journal note in another language, reply in the same
+thread with a short plain-English summary of what they wrote, so they can
+check their own understanding. Don't react to notes written by automations.
+*/
+import { ActorType, Twist, type Note, type ToolBuilder } from "@plotday/twister";
+import { AI } from "@plotday/twister/tools/ai";
+import { Plot, ThreadAccess } from "@plotday/twister/tools/plot";
+
+export default class LanguageJournal extends Twist<LanguageJournal> {
+ build(build: ToolBuilder) {
+ return {
+ plot: build(Plot, {
+ // onNoteCreated only fires for notes on threads this twist created,
+ // so Create access is required even though nothing else reads or
+ // updates other threads.
+ thread: { access: ThreadAccess.Create },
+ }),
+ ai: build(AI),
+ };
+ }
+
+ async activate() {
+ // Seed the standing thread the user writes journal entries into.
+ await this.tools.plot.createThread({
+ title: "Language journal",
+ notes: [
+ {
+ content:
+ "Write your journal entries here in any language — I'll reply with a plain-English summary.",
+ },
+ ],
+ });
+ }
+
+ // Fires for every new note on a thread this twist created. Guard against
+ // notes from twists/automations so we never loop on our own replies.
+ async onNoteCreated(note: Note): Promise<void> {
+ if (note.author.type === ActorType.Twist) {
+ return;
+ }
+ if (!note.content || note.content.trim().length === 0) {
+ return;
+ }
+
+ const response = await this.tools.ai.prompt({
+ model: { speed: "fast", cost: "low" },
+ prompt: `Summarize this journal entry in one or two plain-English sentences:\n\n${note.content}`,
+ });
+ if (!response.text) {
+ return;
+ }
+
+ // Reply in the same thread the note belongs to.
+ await this.tools.plot.createNote({
+ thread: { id: note.thread.id },
+ content: `English summary: ${response.text}`,
+ });
+ }
+}

twister/src/exemplars/authenticated-sync.ts

@@ -0,0 +1,84 @@
+/* SPEC:
+Connect to my bookmarking service account. Once connected, import my starred
+bookmarks as threads (title + link note), and check for new ones every hour.
+Imported bookmarks must not duplicate on re-sync.
+*/
+import { ActionType, Twist, type ToolBuilder, type Uuid } from "@plotday/twister";
+import { Options } from "@plotday/twister/options";
+import { Network } from "@plotday/twister/tools/network";
+import { Plot, ThreadAccess } from "@plotday/twister/tools/plot";
+
+export default class BookmarkSync extends Twist<BookmarkSync> {
+ build(build: ToolBuilder) {
+ return {
+ plot: build(Plot, {
+ thread: { access: ThreadAccess.Create },
+ }),
+ // Plain twists can't hold OAuth tokens — that machinery
+ // (provider/scopes/channels) belongs to Connectors. A secure Options
+ // field is the twist-safe way to let the user "connect" an account
+ // for a twist to call directly.
+ options: build(Options, {
+ apiKey: {
+ type: "text",
+ label: "Bookmarking service API key",
+ default: "",
+ secure: true,
+ },
+ }),
+ network: build(Network, {
+ urls: ["https://api.bookmarks.example/*"],
+ }),
+ };
+ }
+
+ async activate() {
+ // Re-runs hourly under a stable key; survives restarts and upgrades.
+ await this.scheduleRecurring(
+ "hourly-sync",
+ await this.callback(this.sync),
+ { intervalMs: 60 * 60 * 1000 }
+ );
+ await this.sync();
+ }
+
+ async sync(): Promise<void> {
+ const { apiKey } = this.tools.options;
+ if (!apiKey) {
+ return; // Not connected yet; nothing to sync.
+ }
+
+ const response = await fetch("https://api.bookmarks.example/v1/starred", {
+ headers: { Authorization: `Bearer ${apiKey}` },
+ });
+ if (!response.ok) {
+ return;
+ }
+ const { bookmarks } = (await response.json()) as {
+ bookmarks: Array<{ id: string; title: string; url: string }>;
+ };
+
+ // Threads a twist creates have no external Link (that's a Connector
+ // concept), so dedup is tracked manually: store the bookmark id -> thread
+ // id mapping and skip any bookmark that's already been imported.
+ for (const bookmark of bookmarks) {
+ const mappingKey = `bookmark:${bookmark.id}`;
+ if (await this.get<Uuid>(mappingKey)) {
+ continue;
+ }
+
+ const threadId = await this.tools.plot.createThread({
+ title: bookmark.title,
+ notes: [
+ {
+ content: bookmark.url,
+ actions: [
+ { type: ActionType.external, title: "Open bookmark", url: bookmark.url },
+ ],
+ },
+ ],
+ });
+ await this.set(mappingKey, threadId);
+ }
+ }
+}

twister/src/exemplars/scheduled-digest.ts

@@ -0,0 +1,61 @@
+/* SPEC:
+Every morning, post a thread with today's weather forecast for my city so I
+can plan the day. One thread per day, titled with the date.
+*/
+import { Twist, type ToolBuilder } from "@plotday/twister";
+import { Network } from "@plotday/twister/tools/network";
+import { Plot, ThreadAccess } from "@plotday/twister/tools/plot";
+
+export default class WeatherDigest extends Twist<WeatherDigest> {
+ build(build: ToolBuilder) {
+ return {
+ plot: build(Plot, {
+ thread: { access: ThreadAccess.Create },
+ }),
+ network: build(Network, {
+ urls: ["https://api.open-meteo.com/*"],
+ }),
+ };
+ }
+
+ async activate() {
+ await this.scheduleRecurring(
+ "morning-digest",
+ await this.callback(this.postDigest),
+ { intervalMs: 24 * 60 * 60 * 1000 }
+ );
+ }
+
+ async postDigest(): Promise<void> {
+ // Scheduled callbacks can fire more than once (at-least-once delivery),
+ // so guard "one thread per day" with a stored marker keyed on the date.
+ const today = new Date().toISOString().slice(0, 10);
+ const postedKey = `posted:${today}`;
+ if (await this.get<boolean>(postedKey)) {
+ return;
+ }
+
+ const response = await fetch(
+ "https://api.open-meteo.com/v1/forecast?latitude=43.65&longitude=-79.38&daily=temperature_2m_max,precipitation_probability_mean&timezone=auto&forecast_days=1"
+ );
+ if (!response.ok) {
+ return;
+ }
+ const data = (await response.json()) as {
+ daily: {
+ temperature_2m_max: number[];
+ precipitation_probability_mean: number[];
+ };
+ };
+
+ await this.tools.plot.createThread({
+ title: `Weather for ${today}`,
+ notes: [
+ {
+ content: `High of ${data.daily.temperature_2m_max[0]}°C, ${data.daily.precipitation_probability_mean[0]}% chance of rain.`,
+ },
+ ],
+ });
+ await this.set(postedKey, true);
+ }
+}

twister/tsconfig.build.json

@@ -8,7 +8,18 @@
  "declarationMap": true,
  "sourceMap": true,
  "noEmit": false,
- "composite": false
+ "composite": false,
+ // src/exemplars/*.ts import "@plotday/twister" by package name (so the
+ // embedded LLM-facing examples show real import paths, not relative
+ // ones). Resolving that self-reference requires the same
+ // moduleResolution + custom condition tsconfig.base.json already grants
+ // downstream twist/connector projects for the reverse case (resolving
+ // @plotday/twister straight to this package's src/*). Scoped to this
+ // build-only config (not tsconfig.json / tsconfig.cli.json) since
+ // "bundler" resolution is incompatible with tsconfig.cli.json's
+ // CommonJS output (TS5095).
+ "moduleResolution": "bundler",
+ "customConditions": ["@plotday/connector"]
  },
  "include": ["src/**/*.ts"],
  "exclude": [

twister/typedoc.json

@@ -18,11 +18,12 @@
  "src/utils/hash.ts"
  ],
  "out": "dist/docs",
- "tsconfig": "./tsconfig.json",
+ "tsconfig": "./tsconfig.build.json",
  "exclude": [
  "**/*+(.spec|.test).ts",
  "**/llm-docs/**",
  "**/cli/**",
+ "**/exemplars/**",
  "src/twist-guide.ts",
  "src/creator-docs.ts",
  "prebuild.ts",

.changeset/twist-prompt-docs.md

@@ -0,0 +1,5 @@
+---
+"@plotday/twister": minor
+---
+
+Added: getTwistDocumentation() (twist-scoped LLM documentation that omits connector-only modules) and TWIST_EXEMPLARS (complete example twists, compiled and type-checked on every build) for generation prompts.

twister/prebuild.ts

@@ -1,5 +1,12 @@
 #!/usr/bin/env node
-import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "fs";
+import {
+ existsSync,
+ mkdirSync,
+ readdirSync,
+ readFileSync,
+ rmSync,
+ writeFileSync,
+} from "fs";
 import { dirname, join } from "path";
 import { fileURLToPath } from "url";
 
@@ -189,6 +196,50 @@ export default ${JSON.stringify(twistsTemplateContent)};
  );
 }
 
+// Generate twist-exemplars.ts from src/exemplars/*.ts — complete example
+// twists embedded for LLM generation prompts. Each file must start with a
+// /* SPEC: ... */ block comment (the user-style specification it implements).
+const exemplarsDir = join(srcDir, "exemplars");
+if (!existsSync(exemplarsDir)) {
+ throw new Error("prebuild: src/exemplars/ is missing");
+}
+const exemplarFiles = readdirSync(exemplarsDir)
+ .filter((f) => f.endsWith(".ts"))
+ .sort();
+if (exemplarFiles.length === 0) {
+ throw new Error("prebuild: src/exemplars/ contains no exemplars");
+}
+const exemplarSections = exemplarFiles.map((file) => {
+ const raw = readFileSync(join(exemplarsDir, file), "utf-8");
+ const specMatch = raw.match(/^\/\*\s*SPEC:\s*\n([\s\S]*?)\*\/\s*\n/);
+ if (!specMatch) {
+ throw new Error(`prebuild: ${file} is missing its leading /* SPEC: */ comment`);
+ }
+ const spec = specMatch[1].trim();
+ const implementation = raw.slice(specMatch[0].length).trim();
+ const title = file
+ .replace(/\.ts$/, "")
+ .split("-")
+ // Word-capitalize each hyphen segment, except known acronyms (e.g. "ai"
+ // -> "AI" for ai-responder.ts) which are upper-cased outright.
+ .map((w) =>
+ w.toLowerCase() === "ai" ? "AI" : w[0].toUpperCase() + w.slice(1)
+ )
+ .join(" ");
+ return `## Example: ${title}\n\n### Specification\n\n${spec}\n\n### Implementation\n\n\`\`\`typescript\n${implementation}\n\`\`\``;
+});
+const exemplarsContent = `/**
+ * Generated example twists for LLM generation prompts.
+ *
+ * This file is auto-generated during build. Do not edit manually.
+ * Generated from: src/exemplars/*.ts
+ */
+
+export default ${JSON.stringify(exemplarSections.join("\n\n"))};
+`;
+writeFileSync(join(llmDocsDir, "twist-exemplars.ts"), exemplarsContent, "utf-8");
+console.log(`✓ Generated twist-exemplars.ts from ${exemplarFiles.length} exemplars`);
+
 console.log(
  `✓ Generated ${typeFiles.length} LLM documentation files in src/llm-docs/`
 );

twister/src/creator-docs.ts

@@ -1,4 +1,5 @@
 import llmDocs from "./llm-docs/index.js";
+import twistExemplars from "./llm-docs/twist-exemplars.js";
 
 /**
  * Gets complete Twist Creator type definitions with import paths for LLM context.
@@ -27,3 +28,41 @@ export function getBuilderDocumentation(): string {
 
  return documentation;
 }
+
+// Modules excluded from TWIST generation docs: twists must never extend
+// Connector, and the mail-protocol tools are niche enough to dilute the
+// prompt more than they help.
+const TWIST_DOC_EXCLUSIONS = new Set([
+ "@plotday/twister/connector",
+ "@plotday/twister/tools/imap",
+ "@plotday/twister/tools/smtp",
+]);
+
+/**
+ * Twist-scoped variant of getBuilderDocumentation(): the same formatted
+ * type definitions, minus modules that are irrelevant (or misleading) when
+ * generating a twist.
+ */
+export function getTwistDocumentation(): string {
+ let documentation = "# Plot Twist Creator Type Definitions\n\n";
+ documentation +=
+ "Complete type definitions with JSDoc documentation for all Plot Twist Creator types.\n";
+ documentation +=
+ "These are the source files - use the import paths shown to import types in your twist code.\n\n";
+ for (const [importPath, content] of Object.entries(llmDocs)) {
+ if (TWIST_DOC_EXCLUSIONS.has(importPath)) continue;
+ documentation += `## ${importPath}\n\n`;
+ documentation += "```typescript\n";
+ documentation += `// Import from: ${importPath}\n\n`;
+ documentation += content;
+ documentation += "\n```\n\n";
+ }
+ return documentation;
+}
+
+/**
+ * Complete example twists (specification + implementation pairs) for LLM
+ * generation prompts. The examples are real compiled sources in
+ * src/exemplars/, so they are type-checked on every build.
+ */
+export const TWIST_EXEMPLARS: string = twistExemplars;

twister/src/exemplars/ai-responder.ts

@@ -0,0 +1,60 @@
+/* SPEC:
+When someone writes a journal note in another language, reply in the same
+thread with a short plain-English summary of what they wrote, so they can
+check their own understanding. Don't react to notes written by automations.
+*/
+import { ActorType, Twist, type Note, type ToolBuilder } from "@plotday/twister";
+import { AI } from "@plotday/twister/tools/ai";
+import { Plot, ThreadAccess } from "@plotday/twister/tools/plot";
+
+export default class LanguageJournal extends Twist<LanguageJournal> {
+ build(build: ToolBuilder) {
+ return {
+ plot: build(Plot, {
+ // onNoteCreated only fires for notes on threads this twist created,
+ // so Create access is required even though nothing else reads or
+ // updates other threads.
+ thread: { access: ThreadAccess.Create },
+ }),
+ ai: build(AI),
+ };
+ }
+
+ async activate() {
+ // Seed the standing thread the user writes journal entries into.
+ await this.tools.plot.createThread({
+ title: "Language journal",
+ notes: [
+ {
+ content:
+ "Write your journal entries here in any language — I'll reply with a plain-English summary.",
+ },
+ ],
+ });
+ }
+
+ // Fires for every new note on a thread this twist created. Guard against
+ // notes from twists/automations so we never loop on our own replies.
+ async onNoteCreated(note: Note): Promise<void> {
+ if (note.author.type === ActorType.Twist) {
+ return;
+ }
+ if (!note.content || note.content.trim().length === 0) {
+ return;
+ }
+
+ const response = await this.tools.ai.prompt({
+ model: { speed: "fast", cost: "low" },
+ prompt: `Summarize this journal entry in one or two plain-English sentences:\n\n${note.content}`,
+ });
+ if (!response.text) {
+ return;
+ }
+
+ // Reply in the same thread the note belongs to.
+ await this.tools.plot.createNote({
+ thread: { id: note.thread.id },
+ content: `English summary: ${response.text}`,
+ });
+ }
+}

twister/src/exemplars/authenticated-sync.ts

@@ -0,0 +1,84 @@
+/* SPEC:
+Connect to my bookmarking service account. Once connected, import my starred
+bookmarks as threads (title + link note), and check for new ones every hour.
+Imported bookmarks must not duplicate on re-sync.
+*/
+import { ActionType, Twist, type ToolBuilder, type Uuid } from "@plotday/twister";
+import { Options } from "@plotday/twister/options";
+import { Network } from "@plotday/twister/tools/network";
+import { Plot, ThreadAccess } from "@plotday/twister/tools/plot";
+
+export default class BookmarkSync extends Twist<BookmarkSync> {
+ build(build: ToolBuilder) {
+ return {
+ plot: build(Plot, {
+ thread: { access: ThreadAccess.Create },
+ }),
+ // Plain twists can't hold OAuth tokens — that machinery
+ // (provider/scopes/channels) belongs to Connectors. A secure Options
+ // field is the twist-safe way to let the user "connect" an account
+ // for a twist to call directly.
+ options: build(Options, {
+ apiKey: {
+ type: "text",
+ label: "Bookmarking service API key",
+ default: "",
+ secure: true,
+ },
+ }),
+ network: build(Network, {
+ urls: ["https://api.bookmarks.example/*"],
+ }),
+ };
+ }
+
+ async activate() {
+ // Re-runs hourly under a stable key; survives restarts and upgrades.
+ await this.scheduleRecurring(
+ "hourly-sync",
+ await this.callback(this.sync),
+ { intervalMs: 60 * 60 * 1000 }
+ );
+ await this.sync();
+ }
+
+ async sync(): Promise<void> {
+ const { apiKey } = this.tools.options;
+ if (!apiKey) {
+ return; // Not connected yet; nothing to sync.
+ }
+
+ const response = await fetch("https://api.bookmarks.example/v1/starred", {
+ headers: { Authorization: `Bearer ${apiKey}` },
+ });
+ if (!response.ok) {
+ return;
+ }
+ const { bookmarks } = (await response.json()) as {
+ bookmarks: Array<{ id: string; title: string; url: string }>;
+ };
+
+ // Threads a twist creates have no external Link (that's a Connector
+ // concept), so dedup is tracked manually: store the bookmark id -> thread
+ // id mapping and skip any bookmark that's already been imported.
+ for (const bookmark of bookmarks) {
+ const mappingKey = `bookmark:${bookmark.id}`;
+ if (await this.get<Uuid>(mappingKey)) {
+ continue;
+ }
+
+ const threadId = await this.tools.plot.createThread({
+ title: bookmark.title,
+ notes: [
+ {
+ content: bookmark.url,
+ actions: [
+ { type: ActionType.external, title: "Open bookmark", url: bookmark.url },
+ ],
+ },
+ ],
+ });
+ await this.set(mappingKey, threadId);
+ }
+ }
+}

twister/src/exemplars/scheduled-digest.ts

@@ -0,0 +1,61 @@
+/* SPEC:
+Every morning, post a thread with today's weather forecast for my city so I
+can plan the day. One thread per day, titled with the date.
+*/
+import { Twist, type ToolBuilder } from "@plotday/twister";
+import { Network } from "@plotday/twister/tools/network";
+import { Plot, ThreadAccess } from "@plotday/twister/tools/plot";
+
+export default class WeatherDigest extends Twist<WeatherDigest> {
+ build(build: ToolBuilder) {
+ return {
+ plot: build(Plot, {
+ thread: { access: ThreadAccess.Create },
+ }),
+ network: build(Network, {
+ urls: ["https://api.open-meteo.com/*"],
+ }),
+ };
+ }
+
+ async activate() {
+ await this.scheduleRecurring(
+ "morning-digest",
+ await this.callback(this.postDigest),
+ { intervalMs: 24 * 60 * 60 * 1000 }
+ );
+ }
+
+ async postDigest(): Promise<void> {
+ // Scheduled callbacks can fire more than once (at-least-once delivery),
+ // so guard "one thread per day" with a stored marker keyed on the date.
+ const today = new Date().toISOString().slice(0, 10);
+ const postedKey = `posted:${today}`;
+ if (await this.get<boolean>(postedKey)) {
+ return;
+ }
+
+ const response = await fetch(
+ "https://api.open-meteo.com/v1/forecast?latitude=43.65&longitude=-79.38&daily=temperature_2m_max,precipitation_probability_mean&timezone=auto&forecast_days=1"
+ );
+ if (!response.ok) {
+ return;
+ }
+ const data = (await response.json()) as {
+ daily: {
+ temperature_2m_max: number[];
+ precipitation_probability_mean: number[];
+ };
+ };
+
+ await this.tools.plot.createThread({
+ title: `Weather for ${today}`,
+ notes: [
+ {
+ content: `High of ${data.daily.temperature_2m_max[0]}°C, ${data.daily.precipitation_probability_mean[0]}% chance of rain.`,
+ },
+ ],
+ });
+ await this.set(postedKey, true);
+ }
+}

twister/tsconfig.build.json

@@ -8,7 +8,18 @@
  "declarationMap": true,
  "sourceMap": true,
  "noEmit": false,
- "composite": false
+ "composite": false,
+ // src/exemplars/*.ts import "@plotday/twister" by package name (so the
+ // embedded LLM-facing examples show real import paths, not relative
+ // ones). Resolving that self-reference requires the same
+ // moduleResolution + custom condition tsconfig.base.json already grants
+ // downstream twist/connector projects for the reverse case (resolving
+ // @plotday/twister straight to this package's src/*). Scoped to this
+ // build-only config (not tsconfig.json / tsconfig.cli.json) since
+ // "bundler" resolution is incompatible with tsconfig.cli.json's
+ // CommonJS output (TS5095).
+ "moduleResolution": "bundler",
+ "customConditions": ["@plotday/connector"]
  },
  "include": ["src/**/*.ts"],
  "exclude": [

twister/typedoc.json

@@ -18,11 +18,12 @@
  "src/utils/hash.ts"
  ],
  "out": "dist/docs",
- "tsconfig": "./tsconfig.json",
+ "tsconfig": "./tsconfig.build.json",
  "exclude": [
  "**/*+(.spec|.test).ts",
  "**/llm-docs/**",
  "**/cli/**",
+ "**/exemplars/**",
  "src/twist-guide.ts",
  "src/creator-docs.ts",
  "prebuild.ts",

.changeset/twist-prompt-docs.md

@@ -0,0 +1,5 @@
+---
+"@plotday/twister": minor
+---
+
+Added: getTwistDocumentation() (twist-scoped LLM documentation that omits connector-only modules) and TWIST_EXEMPLARS (complete example twists, compiled and type-checked on every build) for generation prompts.

twister/prebuild.ts

@@ -1,5 +1,12 @@
 #!/usr/bin/env node
-import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "fs";
+import {
+ existsSync,
+ mkdirSync,
+ readdirSync,
+ readFileSync,
+ rmSync,
+ writeFileSync,
+} from "fs";
 import { dirname, join } from "path";
 import { fileURLToPath } from "url";
 
@@ -189,6 +196,50 @@ export default ${JSON.stringify(twistsTemplateContent)};
  );
 }
 
+// Generate twist-exemplars.ts from src/exemplars/*.ts — complete example
+// twists embedded for LLM generation prompts. Each file must start with a
+// /* SPEC: ... */ block comment (the user-style specification it implements).
+const exemplarsDir = join(srcDir, "exemplars");
+if (!existsSync(exemplarsDir)) {
+ throw new Error("prebuild: src/exemplars/ is missing");
+}
+const exemplarFiles = readdirSync(exemplarsDir)
+ .filter((f) => f.endsWith(".ts"))
+ .sort();
+if (exemplarFiles.length === 0) {
+ throw new Error("prebuild: src/exemplars/ contains no exemplars");
+}
+const exemplarSections = exemplarFiles.map((file) => {
+ const raw = readFileSync(join(exemplarsDir, file), "utf-8");
+ const specMatch = raw.match(/^\/\*\s*SPEC:\s*\n([\s\S]*?)\*\/\s*\n/);
+ if (!specMatch) {
+ throw new Error(`prebuild: ${file} is missing its leading /* SPEC: */ comment`);
+ }
+ const spec = specMatch[1].trim();
+ const implementation = raw.slice(specMatch[0].length).trim();
+ const title = file
+ .replace(/\.ts$/, "")
+ .split("-")
+ // Word-capitalize each hyphen segment, except known acronyms (e.g. "ai"
+ // -> "AI" for ai-responder.ts) which are upper-cased outright.
+ .map((w) =>
+ w.toLowerCase() === "ai" ? "AI" : w[0].toUpperCase() + w.slice(1)
+ )
+ .join(" ");
+ return `## Example: ${title}\n\n### Specification\n\n${spec}\n\n### Implementation\n\n\`\`\`typescript\n${implementation}\n\`\`\``;
+});
+const exemplarsContent = `/**
+ * Generated example twists for LLM generation prompts.
+ *
+ * This file is auto-generated during build. Do not edit manually.
+ * Generated from: src/exemplars/*.ts
+ */
+
+export default ${JSON.stringify(exemplarSections.join("\n\n"))};
+`;
+writeFileSync(join(llmDocsDir, "twist-exemplars.ts"), exemplarsContent, "utf-8");
+console.log(`✓ Generated twist-exemplars.ts from ${exemplarFiles.length} exemplars`);
+
 console.log(
  `✓ Generated ${typeFiles.length} LLM documentation files in src/llm-docs/`
 );

twister/src/creator-docs.ts

@@ -1,4 +1,5 @@
 import llmDocs from "./llm-docs/index.js";
+import twistExemplars from "./llm-docs/twist-exemplars.js";
 
 /**
  * Gets complete Twist Creator type definitions with import paths for LLM context.
@@ -27,3 +28,41 @@ export function getBuilderDocumentation(): string {
 
  return documentation;
 }
+
+// Modules excluded from TWIST generation docs: twists must never extend
+// Connector, and the mail-protocol tools are niche enough to dilute the
+// prompt more than they help.
+const TWIST_DOC_EXCLUSIONS = new Set([
+ "@plotday/twister/connector",
+ "@plotday/twister/tools/imap",
+ "@plotday/twister/tools/smtp",
+]);
+
+/**
+ * Twist-scoped variant of getBuilderDocumentation(): the same formatted
+ * type definitions, minus modules that are irrelevant (or misleading) when
+ * generating a twist.
+ */
+export function getTwistDocumentation(): string {
+ let documentation = "# Plot Twist Creator Type Definitions\n\n";
+ documentation +=
+ "Complete type definitions with JSDoc documentation for all Plot Twist Creator types.\n";
+ documentation +=
+ "These are the source files - use the import paths shown to import types in your twist code.\n\n";
+ for (const [importPath, content] of Object.entries(llmDocs)) {
+ if (TWIST_DOC_EXCLUSIONS.has(importPath)) continue;
+ documentation += `## ${importPath}\n\n`;
+ documentation += "```typescript\n";
+ documentation += `// Import from: ${importPath}\n\n`;
+ documentation += content;
+ documentation += "\n```\n\n";
+ }
+ return documentation;
+}
+
+/**
+ * Complete example twists (specification + implementation pairs) for LLM
+ * generation prompts. The examples are real compiled sources in
+ * src/exemplars/, so they are type-checked on every build.
+ */
+export const TWIST_EXEMPLARS: string = twistExemplars;

twister/src/exemplars/ai-responder.ts

@@ -0,0 +1,60 @@
+/* SPEC:
+When someone writes a journal note in another language, reply in the same
+thread with a short plain-English summary of what they wrote, so they can
+check their own understanding. Don't react to notes written by automations.
+*/
+import { ActorType, Twist, type Note, type ToolBuilder } from "@plotday/twister";
+import { AI } from "@plotday/twister/tools/ai";
+import { Plot, ThreadAccess } from "@plotday/twister/tools/plot";
+
+export default class LanguageJournal extends Twist<LanguageJournal> {
+ build(build: ToolBuilder) {
+ return {
+ plot: build(Plot, {
+ // onNoteCreated only fires for notes on threads this twist created,
+ // so Create access is required even though nothing else reads or
+ // updates other threads.
+ thread: { access: ThreadAccess.Create },
+ }),
+ ai: build(AI),
+ };
+ }
+
+ async activate() {
+ // Seed the standing thread the user writes journal entries into.
+ await this.tools.plot.createThread({
+ title: "Language journal",
+ notes: [
+ {
+ content:
+ "Write your journal entries here in any language — I'll reply with a plain-English summary.",
+ },
+ ],
+ });
+ }
+
+ // Fires for every new note on a thread this twist created. Guard against
+ // notes from twists/automations so we never loop on our own replies.
+ async onNoteCreated(note: Note): Promise<void> {
+ if (note.author.type === ActorType.Twist) {
+ return;
+ }
+ if (!note.content || note.content.trim().length === 0) {
+ return;
+ }
+
+ const response = await this.tools.ai.prompt({
+ model: { speed: "fast", cost: "low" },
+ prompt: `Summarize this journal entry in one or two plain-English sentences:\n\n${note.content}`,
+ });
+ if (!response.text) {
+ return;
+ }
+
+ // Reply in the same thread the note belongs to.
+ await this.tools.plot.createNote({
+ thread: { id: note.thread.id },
+ content: `English summary: ${response.text}`,
+ });
+ }
+}

twister/src/exemplars/authenticated-sync.ts

@@ -0,0 +1,84 @@
+/* SPEC:
+Connect to my bookmarking service account. Once connected, import my starred
+bookmarks as threads (title + link note), and check for new ones every hour.
+Imported bookmarks must not duplicate on re-sync.
+*/
+import { ActionType, Twist, type ToolBuilder, type Uuid } from "@plotday/twister";
+import { Options } from "@plotday/twister/options";
+import { Network } from "@plotday/twister/tools/network";
+import { Plot, ThreadAccess } from "@plotday/twister/tools/plot";
+
+export default class BookmarkSync extends Twist<BookmarkSync> {
+ build(build: ToolBuilder) {
+ return {
+ plot: build(Plot, {
+ thread: { access: ThreadAccess.Create },
+ }),
+ // Plain twists can't hold OAuth tokens — that machinery
+ // (provider/scopes/channels) belongs to Connectors. A secure Options
+ // field is the twist-safe way to let the user "connect" an account
+ // for a twist to call directly.
+ options: build(Options, {
+ apiKey: {
+ type: "text",
+ label: "Bookmarking service API key",
+ default: "",
+ secure: true,
+ },
+ }),
+ network: build(Network, {
+ urls: ["https://api.bookmarks.example/*"],
+ }),
+ };
+ }
+
+ async activate() {
+ // Re-runs hourly under a stable key; survives restarts and upgrades.
+ await this.scheduleRecurring(
+ "hourly-sync",
+ await this.callback(this.sync),
+ { intervalMs: 60 * 60 * 1000 }
+ );
+ await this.sync();
+ }
+
+ async sync(): Promise<void> {
+ const { apiKey } = this.tools.options;
+ if (!apiKey) {
+ return; // Not connected yet; nothing to sync.
+ }
+
+ const response = await fetch("https://api.bookmarks.example/v1/starred", {
+ headers: { Authorization: `Bearer ${apiKey}` },
+ });
+ if (!response.ok) {
+ return;
+ }
+ const { bookmarks } = (await response.json()) as {
+ bookmarks: Array<{ id: string; title: string; url: string }>;
+ };
+
+ // Threads a twist creates have no external Link (that's a Connector
+ // concept), so dedup is tracked manually: store the bookmark id -> thread
+ // id mapping and skip any bookmark that's already been imported.
+ for (const bookmark of bookmarks) {
+ const mappingKey = `bookmark:${bookmark.id}`;
+ if (await this.get<Uuid>(mappingKey)) {
+ continue;
+ }
+
+ const threadId = await this.tools.plot.createThread({
+ title: bookmark.title,
+ notes: [
+ {
+ content: bookmark.url,
+ actions: [
+ { type: ActionType.external, title: "Open bookmark", url: bookmark.url },
+ ],
+ },
+ ],
+ });
+ await this.set(mappingKey, threadId);
+ }
+ }
+}

twister/src/exemplars/scheduled-digest.ts

@@ -0,0 +1,61 @@
+/* SPEC:
+Every morning, post a thread with today's weather forecast for my city so I
+can plan the day. One thread per day, titled with the date.
+*/
+import { Twist, type ToolBuilder } from "@plotday/twister";
+import { Network } from "@plotday/twister/tools/network";
+import { Plot, ThreadAccess } from "@plotday/twister/tools/plot";
+
+export default class WeatherDigest extends Twist<WeatherDigest> {
+ build(build: ToolBuilder) {
+ return {
+ plot: build(Plot, {
+ thread: { access: ThreadAccess.Create },
+ }),
+ network: build(Network, {
+ urls: ["https://api.open-meteo.com/*"],
+ }),
+ };
+ }
+
+ async activate() {
+ await this.scheduleRecurring(
+ "morning-digest",
+ await this.callback(this.postDigest),
+ { intervalMs: 24 * 60 * 60 * 1000 }
+ );
+ }
+
+ async postDigest(): Promise<void> {
+ // Scheduled callbacks can fire more than once (at-least-once delivery),
+ // so guard "one thread per day" with a stored marker keyed on the date.
+ const today = new Date().toISOString().slice(0, 10);
+ const postedKey = `posted:${today}`;
+ if (await this.get<boolean>(postedKey)) {
+ return;
+ }
+
+ const response = await fetch(
+ "https://api.open-meteo.com/v1/forecast?latitude=43.65&longitude=-79.38&daily=temperature_2m_max,precipitation_probability_mean&timezone=auto&forecast_days=1"
+ );
+ if (!response.ok) {
+ return;
+ }
+ const data = (await response.json()) as {
+ daily: {
+ temperature_2m_max: number[];
+ precipitation_probability_mean: number[];
+ };
+ };
+
+ await this.tools.plot.createThread({
+ title: `Weather for ${today}`,
+ notes: [
+ {
+ content: `High of ${data.daily.temperature_2m_max[0]}°C, ${data.daily.precipitation_probability_mean[0]}% chance of rain.`,
+ },
+ ],
+ });
+ await this.set(postedKey, true);
+ }
+}

twister/tsconfig.build.json

@@ -8,7 +8,18 @@
  "declarationMap": true,
  "sourceMap": true,
  "noEmit": false,
- "composite": false
+ "composite": false,
+ // src/exemplars/*.ts import "@plotday/twister" by package name (so the
+ // embedded LLM-facing examples show real import paths, not relative
+ // ones). Resolving that self-reference requires the same
+ // moduleResolution + custom condition tsconfig.base.json already grants
+ // downstream twist/connector projects for the reverse case (resolving
+ // @plotday/twister straight to this package's src/*). Scoped to this
+ // build-only config (not tsconfig.json / tsconfig.cli.json) since
+ // "bundler" resolution is incompatible with tsconfig.cli.json's
+ // CommonJS output (TS5095).
+ "moduleResolution": "bundler",
+ "customConditions": ["@plotday/connector"]
  },
  "include": ["src/**/*.ts"],
  "exclude": [

twister/typedoc.json

@@ -18,11 +18,12 @@
  "src/utils/hash.ts"
  ],
  "out": "dist/docs",
- "tsconfig": "./tsconfig.json",
+ "tsconfig": "./tsconfig.build.json",
  "exclude": [
  "**/*+(.spec|.test).ts",
  "**/llm-docs/**",
  "**/cli/**",
+ "**/exemplars/**",
  "src/twist-guide.ts",
  "src/creator-docs.ts",
  "prebuild.ts",