@molecule/api-agent-transcript-autodetect 1.0.0 → 1.1.0

package/README.md

@@ -3,7 +3,7 @@ AUTO-GENERATED — DO NOT EDIT THIS FILE.
 Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
 Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
 To change this document, edit the module-level JSDoc in src/index.ts.
-Generated: 2026-09-24T06:06:46.371Z
+Generated: 2026-09-29T16:49:56.713Z
 -->
 
 # @molecule/api-agent-transcript-autodetect
@@ -15,25 +15,119 @@ Generated: 2026-09-24T06:06:46.371Z
 The transcript reader to bond when files can come from more than one harness.
 
 Implements `@molecule/api-agent-transcript` by trying each bundled reader's
-`detect()` and delegating to the first that recognizes the file: Claude Code
-(`/export` text, session `.jsonl`), Codex CLI (Markdown export, rollout
-`.jsonl`) and the Molecule IDE (stored conversation JSON). `createReader()`
-composes any other list, including readers of your own.
+`detect()` and delegating to the first that recognizes the file:
+
+| Harness             | Files                                                                              |
+| ------------------- | ---------------------------------------------------------------------------------- |
+| Claude Code         | `/export` text, session `.jsonl`                                                   |
+| Codex CLI           | Markdown export, rollout `.jsonl`                                                  |
+| Molecule IDE        | stored conversation JSON                                                           |
+| Gemini CLI          | session `.jsonl` / `.json`, `/chat save` checkpoint                                |
+| Cline / Roo Code    | a task's `ui_messages.json`                                                        |
+| OpenCode            | `opencode export` JSON                                                             |
+| GitHub Copilot Chat | VS Code's "Export Chat…" `chat.json`                                               |
+| Cursor              | "Export Chat" Markdown                                                             |
+| Aider               | `.aider.chat.history.md`                                                           |
+| anything else       | a Markdown / text chat with `## User`, `**User:**` or `User:` markers (tried last) |
+
+`createReader()` composes any other list, including readers of your own;
+`harnessReaders` is the list without the generic Markdown chat reader. The example is the
+usual job: read a post's folder of transcript exports at build time and
+attribute its paragraphs with `@molecule/api-text-provenance`, writing
+`provenance.json`.
 
 ## Quick Start
 
 ```typescript
-import { readdirSync, readFileSync } from 'node:fs'
-import { join } from 'node:path'
-import { readTranscript, setProvider } from '@molecule/api-agent-transcript'
-import { provider } from '@molecule/api-agent-transcript-autodetect'
+// provenance.ts — runs in Node at build time (a build script or a Vite plugin), never in the page.
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+
+import {
+  canReadTranscript,
+  readTranscript,
+  setProvider as setTranscriptReader,
+} from '@molecule/api-agent-transcript'
+import { provider as anyTranscript } from '@molecule/api-agent-transcript-autodetect'
+import { attributeText, setProvider as setAttribution } from '@molecule/api-text-provenance'
+import { provider as wordOverlap } from '@molecule/api-text-provenance-overlap'
+
+setTranscriptReader(anyTranscript) // reads every supported harness, plus plain Markdown chats
+setAttribution(wordOverlap)
+
+// One block of the post, in page order. `prompt` and `model` are on every ai span.
+export interface ProvenanceSpan {
+  text: string // the block's markdown: a paragraph, heading, list or code block
+  origin: 'human' | 'ai'
+  prompt?: string // the person's message the AI was answering, as typed
+  model?: string // the model that wrote it, as the transcript names it
+}
+
+// What /<slug>/provenance.json holds.
+export interface Provenance {
+  aiShare: number // 0..1, the share of the post's words the AI wrote
+  words: number
+  aiWords: number
+  prompts: string[] // the distinct prompts behind the ai spans, in page order
+  spans: ProvenanceSpan[]
+}
 
-setProvider(provider)
+// The post's top-level blocks: front matter dropped, split on blank lines, never inside a code fence.
+export function markdownBlocks(markdown: string): string[] {
+  const body = markdown.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n/, '')
+  const blocks: string[] = []
+  let lines: string[] = []
+  let inFence = false
+  for (const line of body.split(/\r?\n/)) {
+    if (/^\s*(`{3}|~{3})/.test(line)) inFence = !inFence
+    if (!inFence && line.trim() === '') {
+      if (lines.length > 0) blocks.push(lines.join('\n'))
+      lines = []
+    } else {
+      lines.push(line)
+    }
+  }
+  if (lines.length > 0) blocks.push(lines.join('\n'))
+  return blocks
+}
+
+// Attribute one post from its markdown file and the folder holding its transcript exports.
+// A missing or empty folder is a 100% human post; files that are not transcripts are skipped.
+export function postProvenance(markdownFile: string, transcriptDir: string): Provenance {
+  const blocks = markdownBlocks(readFileSync(markdownFile, 'utf8'))
+  const files = existsSync(transcriptDir)
+    ? readdirSync(transcriptDir, { withFileTypes: true })
+        .filter((entry) => entry.isFile())
+        .map((entry) => entry.name)
+        .sort()
+    : []
+  const sessions = files
+    .map((name) => ({ text: readFileSync(join(transcriptDir, name), 'utf8'), fileName: name }))
+    .filter((input) => canReadTranscript(input))
+    .map((input) => readTranscript(input))
+  const result = attributeText({ paragraphs: blocks, sessions })
+  return {
+    aiShare: result.aiShare,
+    words: result.words,
+    aiWords: result.aiWords,
+    prompts: result.prompts,
+    spans: result.paragraphs.map((p): ProvenanceSpan => {
+      const text = blocks[p.index]
+      return p.origin === 'ai'
+        ? { text, origin: 'ai', prompt: p.prompt, model: p.model }
+        : { text, origin: 'human' }
+    }),
+  }
+}
 
-const dir = 'transcripts/my-post'
-const sessions = readdirSync(dir).map((f) =>
-  readTranscript({ text: readFileSync(join(dir, f), 'utf8'), fileName: f }),
-)
+// Write provenance.json, creating its folder.
+export function writeProvenance(outFile: string, provenance: Provenance): void {
+  mkdirSync(dirname(outFile), { recursive: true })
+  writeFileSync(outFile, `${JSON.stringify(provenance, null, 2)}\n`)
+}
+
+// In the build, for each PUBLISHED post (skip drafts), after the site's own build has written dist/:
+// writeProvenance('dist/my-post/provenance.json', postProvenance('posts/my-post.md', 'transcripts/my-post'))
 ```
 
 ## Type
@@ -43,7 +137,7 @@ const sessions = readdirSync(dir).map((f) =>
 ## Installation
 
 ```bash
-npm install @molecule/api-agent-transcript-autodetect @molecule/api-agent-transcript @molecule/api-agent-transcript-claude-code @molecule/api-agent-transcript-codex @molecule/api-agent-transcript-molecule-ide
+npm install @molecule/api-agent-transcript-autodetect @molecule/api-agent-transcript @molecule/api-agent-transcript-aider @molecule/api-agent-transcript-claude-code @molecule/api-agent-transcript-cline @molecule/api-agent-transcript-codex @molecule/api-agent-transcript-copilot-chat @molecule/api-agent-transcript-cursor @molecule/api-agent-transcript-gemini-cli @molecule/api-agent-transcript-markdown-chat @molecule/api-agent-transcript-molecule-ide @molecule/api-agent-transcript-opencode
 ```
 
 ## API
@@ -64,9 +158,24 @@ function createReader(readers: readonly AgentTranscriptReader[]): AgentTranscrip
 
 ### Constants
 
+#### `harnessReaders`
+
+Every harness-specific reader, in the order they are tried. Each accepts
+only its own harness's files, so the order only matters for the generic
+Markdown chat reader, which is not in this list. Compose
+`createReader(harnessReaders)` when only a real harness's own file should
+be read.
+
+```typescript
+const harnessReaders: readonly AgentTranscriptReader[]
+```
+
 #### `provider`
 
-Reads any Claude Code, Codex CLI or Molecule IDE transcript.
+Reads a transcript from any supported harness — Claude Code, Codex CLI,
+the Molecule IDE, Gemini CLI, Cline / Roo Code, OpenCode, GitHub Copilot
+Chat, Cursor and Aider — and, last, any plain Markdown / text chat with
+User / Assistant speaker markers.
 
 ```typescript
 const provider: AgentTranscriptReader
@@ -100,12 +209,32 @@ Peer dependencies:
 ### Runtime Dependencies
 
 - `@molecule/api-agent-transcript`
+- `@molecule/api-agent-transcript-aider`
 - `@molecule/api-agent-transcript-claude-code`
+- `@molecule/api-agent-transcript-cline`
 - `@molecule/api-agent-transcript-codex`
+- `@molecule/api-agent-transcript-copilot-chat`
+- `@molecule/api-agent-transcript-cursor`
+- `@molecule/api-agent-transcript-gemini-cli`
+- `@molecule/api-agent-transcript-markdown-chat`
 - `@molecule/api-agent-transcript-molecule-ide`
-
-- A file no reader recognizes throws, naming the file and the readers
-  tried — it is never read as an empty session. Check `canReadTranscript()`
-  first to skip non-transcript files (a README beside the exports).
-- Order matters only for a file two readers would both accept; the bundled
-  readers accept disjoint formats.
+- `@molecule/api-agent-transcript-opencode`
+
+- **Do NOT call `readTranscript` on every file in a folder.** A file no
+  reader recognizes throws, naming the file and the readers tried — it is
+  never read as an empty session. Filter with `canReadTranscript()` first,
+  as the example does.
+- **Do NOT parse an export yourself or bond a single-format reader "to be
+  safe".** This bond reads every format above; a user turn is already only
+  what the person typed.
+- **A plain chat with speaker markers is read too — as `markdown-chat`,
+  never as a harness.** When only a real harness's own file may count
+  (attributing text to a model, say), check `session.format !==
+'markdown-chat'`, or bond `createReader(harnessReaders)` instead.
+- **Do NOT import this from page or client code** — it is server-only and
+  throws in a browser bundle.
+- Install all four packages the example uses:
+  `npm install @molecule/api-agent-transcript @molecule/api-agent-transcript-autodetect @molecule/api-text-provenance @molecule/api-text-provenance-overlap`.
+- Order matters only for a file two readers would both accept. The harness
+  readers accept disjoint formats; the generic Markdown chat reader is
+  tried last, so it never claims a harness's own file.

package/dist/index.d.ts

@@ -2,32 +2,139 @@
  * The transcript reader to bond when files can come from more than one harness.
  *
  * Implements `@molecule/api-agent-transcript` by trying each bundled reader's
- * `detect()` and delegating to the first that recognizes the file: Claude Code
- * (`/export` text, session `.jsonl`), Codex CLI (Markdown export, rollout
- * `.jsonl`) and the Molecule IDE (stored conversation JSON). `createReader()`
- * composes any other list, including readers of your own.
+ * `detect()` and delegating to the first that recognizes the file:
+ *
+ * | Harness | Files |
+ * |---|---|
+ * | Claude Code | `/export` text, session `.jsonl` |
+ * | Codex CLI | Markdown export, rollout `.jsonl` |
+ * | Molecule IDE | stored conversation JSON |
+ * | Gemini CLI | session `.jsonl` / `.json`, `/chat save` checkpoint |
+ * | Cline / Roo Code | a task's `ui_messages.json` |
+ * | OpenCode | `opencode export` JSON |
+ * | GitHub Copilot Chat | VS Code's "Export Chat…" `chat.json` |
+ * | Cursor | "Export Chat" Markdown |
+ * | Aider | `.aider.chat.history.md` |
+ * | anything else | a Markdown / text chat with `## User`, `**User:**` or `User:` markers (tried last) |
+ *
+ * `createReader()` composes any other list, including readers of your own;
+ * `harnessReaders` is the list without the generic Markdown chat reader. The example is the
+ * usual job: read a post's folder of transcript exports at build time and
+ * attribute its paragraphs with `@molecule/api-text-provenance`, writing
+ * `provenance.json`.
  *
  * @example
  * ```typescript
- * import { readdirSync, readFileSync } from 'node:fs'
- * import { join } from 'node:path'
- * import { readTranscript, setProvider } from '@molecule/api-agent-transcript'
- * import { provider } from '@molecule/api-agent-transcript-autodetect'
+ * // provenance.ts — runs in Node at build time (a build script or a Vite plugin), never in the page.
+ * import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs'
+ * import { dirname, join } from 'node:path'
+ *
+ * import {
+ *   canReadTranscript,
+ *   readTranscript,
+ *   setProvider as setTranscriptReader,
+ * } from '@molecule/api-agent-transcript'
+ * import { provider as anyTranscript } from '@molecule/api-agent-transcript-autodetect'
+ * import { attributeText, setProvider as setAttribution } from '@molecule/api-text-provenance'
+ * import { provider as wordOverlap } from '@molecule/api-text-provenance-overlap'
+ *
+ * setTranscriptReader(anyTranscript) // reads every supported harness, plus plain Markdown chats
+ * setAttribution(wordOverlap)
+ *
+ * // One block of the post, in page order. `prompt` and `model` are on every ai span.
+ * export interface ProvenanceSpan {
+ *   text: string // the block's markdown: a paragraph, heading, list or code block
+ *   origin: 'human' | 'ai'
+ *   prompt?: string // the person's message the AI was answering, as typed
+ *   model?: string // the model that wrote it, as the transcript names it
+ * }
+ *
+ * // What /<slug>/provenance.json holds.
+ * export interface Provenance {
+ *   aiShare: number // 0..1, the share of the post's words the AI wrote
+ *   words: number
+ *   aiWords: number
+ *   prompts: string[] // the distinct prompts behind the ai spans, in page order
+ *   spans: ProvenanceSpan[]
+ * }
+ *
+ * // The post's top-level blocks: front matter dropped, split on blank lines, never inside a code fence.
+ * export function markdownBlocks(markdown: string): string[] {
+ *   const body = markdown.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n/, '')
+ *   const blocks: string[] = []
+ *   let lines: string[] = []
+ *   let inFence = false
+ *   for (const line of body.split(/\r?\n/)) {
+ *     if (/^\s*(`{3}|~{3})/.test(line)) inFence = !inFence
+ *     if (!inFence && line.trim() === '') {
+ *       if (lines.length > 0) blocks.push(lines.join('\n'))
+ *       lines = []
+ *     } else {
+ *       lines.push(line)
+ *     }
+ *   }
+ *   if (lines.length > 0) blocks.push(lines.join('\n'))
+ *   return blocks
+ * }
+ *
+ * // Attribute one post from its markdown file and the folder holding its transcript exports.
+ * // A missing or empty folder is a 100% human post; files that are not transcripts are skipped.
+ * export function postProvenance(markdownFile: string, transcriptDir: string): Provenance {
+ *   const blocks = markdownBlocks(readFileSync(markdownFile, 'utf8'))
+ *   const files = existsSync(transcriptDir)
+ *     ? readdirSync(transcriptDir, { withFileTypes: true })
+ *         .filter((entry) => entry.isFile())
+ *         .map((entry) => entry.name)
+ *         .sort()
+ *     : []
+ *   const sessions = files
+ *     .map((name) => ({ text: readFileSync(join(transcriptDir, name), 'utf8'), fileName: name }))
+ *     .filter((input) => canReadTranscript(input))
+ *     .map((input) => readTranscript(input))
+ *   const result = attributeText({ paragraphs: blocks, sessions })
+ *   return {
+ *     aiShare: result.aiShare,
+ *     words: result.words,
+ *     aiWords: result.aiWords,
+ *     prompts: result.prompts,
+ *     spans: result.paragraphs.map((p): ProvenanceSpan => {
+ *       const text = blocks[p.index]
+ *       return p.origin === 'ai'
+ *         ? { text, origin: 'ai', prompt: p.prompt, model: p.model }
+ *         : { text, origin: 'human' }
+ *     }),
+ *   }
+ * }
  *
- * setProvider(provider)
+ * // Write provenance.json, creating its folder.
+ * export function writeProvenance(outFile: string, provenance: Provenance): void {
+ *   mkdirSync(dirname(outFile), { recursive: true })
+ *   writeFileSync(outFile, `${JSON.stringify(provenance, null, 2)}\n`)
+ * }
  *
- * const dir = 'transcripts/my-post'
- * const sessions = readdirSync(dir).map((f) =>
- *   readTranscript({ text: readFileSync(join(dir, f), 'utf8'), fileName: f }),
- * )
+ * // In the build, for each PUBLISHED post (skip drafts), after the site's own build has written dist/:
+ * // writeProvenance('dist/my-post/provenance.json', postProvenance('posts/my-post.md', 'transcripts/my-post'))
  * ```
  *
  * @remarks
- * - A file no reader recognizes throws, naming the file and the readers
- *   tried — it is never read as an empty session. Check `canReadTranscript()`
- *   first to skip non-transcript files (a README beside the exports).
- * - Order matters only for a file two readers would both accept; the bundled
- *   readers accept disjoint formats.
+ * - **Do NOT call `readTranscript` on every file in a folder.** A file no
+ *   reader recognizes throws, naming the file and the readers tried — it is
+ *   never read as an empty session. Filter with `canReadTranscript()` first,
+ *   as the example does.
+ * - **Do NOT parse an export yourself or bond a single-format reader "to be
+ *   safe".** This bond reads every format above; a user turn is already only
+ *   what the person typed.
+ * - **A plain chat with speaker markers is read too — as `markdown-chat`,
+ *   never as a harness.** When only a real harness's own file may count
+ *   (attributing text to a model, say), check `session.format !==
+ *   'markdown-chat'`, or bond `createReader(harnessReaders)` instead.
+ * - **Do NOT import this from page or client code** — it is server-only and
+ *   throws in a browser bundle.
+ * - Install all four packages the example uses:
+ *   `npm install @molecule/api-agent-transcript @molecule/api-agent-transcript-autodetect @molecule/api-text-provenance @molecule/api-text-provenance-overlap`.
+ * - Order matters only for a file two readers would both accept. The harness
+ *   readers accept disjoint formats; the generic Markdown chat reader is
+ *   tried last, so it never claims a harness's own file.
  *
  * @module
  */

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,cAAc,oBAAoB,CAAA;AAClC,cAAc,eAAe,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2IG;AAEH,cAAc,oBAAoB,CAAA;AAClC,cAAc,eAAe,CAAA"}

package/dist/index.js

@@ -2,32 +2,139 @@
  * The transcript reader to bond when files can come from more than one harness.
  *
  * Implements `@molecule/api-agent-transcript` by trying each bundled reader's
- * `detect()` and delegating to the first that recognizes the file: Claude Code
- * (`/export` text, session `.jsonl`), Codex CLI (Markdown export, rollout
- * `.jsonl`) and the Molecule IDE (stored conversation JSON). `createReader()`
- * composes any other list, including readers of your own.
+ * `detect()` and delegating to the first that recognizes the file:
+ *
+ * | Harness | Files |
+ * |---|---|
+ * | Claude Code | `/export` text, session `.jsonl` |
+ * | Codex CLI | Markdown export, rollout `.jsonl` |
+ * | Molecule IDE | stored conversation JSON |
+ * | Gemini CLI | session `.jsonl` / `.json`, `/chat save` checkpoint |
+ * | Cline / Roo Code | a task's `ui_messages.json` |
+ * | OpenCode | `opencode export` JSON |
+ * | GitHub Copilot Chat | VS Code's "Export Chat…" `chat.json` |
+ * | Cursor | "Export Chat" Markdown |
+ * | Aider | `.aider.chat.history.md` |
+ * | anything else | a Markdown / text chat with `## User`, `**User:**` or `User:` markers (tried last) |
+ *
+ * `createReader()` composes any other list, including readers of your own;
+ * `harnessReaders` is the list without the generic Markdown chat reader. The example is the
+ * usual job: read a post's folder of transcript exports at build time and
+ * attribute its paragraphs with `@molecule/api-text-provenance`, writing
+ * `provenance.json`.
  *
  * @example
  * ```typescript
- * import { readdirSync, readFileSync } from 'node:fs'
- * import { join } from 'node:path'
- * import { readTranscript, setProvider } from '@molecule/api-agent-transcript'
- * import { provider } from '@molecule/api-agent-transcript-autodetect'
+ * // provenance.ts — runs in Node at build time (a build script or a Vite plugin), never in the page.
+ * import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs'
+ * import { dirname, join } from 'node:path'
+ *
+ * import {
+ *   canReadTranscript,
+ *   readTranscript,
+ *   setProvider as setTranscriptReader,
+ * } from '@molecule/api-agent-transcript'
+ * import { provider as anyTranscript } from '@molecule/api-agent-transcript-autodetect'
+ * import { attributeText, setProvider as setAttribution } from '@molecule/api-text-provenance'
+ * import { provider as wordOverlap } from '@molecule/api-text-provenance-overlap'
+ *
+ * setTranscriptReader(anyTranscript) // reads every supported harness, plus plain Markdown chats
+ * setAttribution(wordOverlap)
+ *
+ * // One block of the post, in page order. `prompt` and `model` are on every ai span.
+ * export interface ProvenanceSpan {
+ *   text: string // the block's markdown: a paragraph, heading, list or code block
+ *   origin: 'human' | 'ai'
+ *   prompt?: string // the person's message the AI was answering, as typed
+ *   model?: string // the model that wrote it, as the transcript names it
+ * }
+ *
+ * // What /<slug>/provenance.json holds.
+ * export interface Provenance {
+ *   aiShare: number // 0..1, the share of the post's words the AI wrote
+ *   words: number
+ *   aiWords: number
+ *   prompts: string[] // the distinct prompts behind the ai spans, in page order
+ *   spans: ProvenanceSpan[]
+ * }
+ *
+ * // The post's top-level blocks: front matter dropped, split on blank lines, never inside a code fence.
+ * export function markdownBlocks(markdown: string): string[] {
+ *   const body = markdown.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n/, '')
+ *   const blocks: string[] = []
+ *   let lines: string[] = []
+ *   let inFence = false
+ *   for (const line of body.split(/\r?\n/)) {
+ *     if (/^\s*(`{3}|~{3})/.test(line)) inFence = !inFence
+ *     if (!inFence && line.trim() === '') {
+ *       if (lines.length > 0) blocks.push(lines.join('\n'))
+ *       lines = []
+ *     } else {
+ *       lines.push(line)
+ *     }
+ *   }
+ *   if (lines.length > 0) blocks.push(lines.join('\n'))
+ *   return blocks
+ * }
+ *
+ * // Attribute one post from its markdown file and the folder holding its transcript exports.
+ * // A missing or empty folder is a 100% human post; files that are not transcripts are skipped.
+ * export function postProvenance(markdownFile: string, transcriptDir: string): Provenance {
+ *   const blocks = markdownBlocks(readFileSync(markdownFile, 'utf8'))
+ *   const files = existsSync(transcriptDir)
+ *     ? readdirSync(transcriptDir, { withFileTypes: true })
+ *         .filter((entry) => entry.isFile())
+ *         .map((entry) => entry.name)
+ *         .sort()
+ *     : []
+ *   const sessions = files
+ *     .map((name) => ({ text: readFileSync(join(transcriptDir, name), 'utf8'), fileName: name }))
+ *     .filter((input) => canReadTranscript(input))
+ *     .map((input) => readTranscript(input))
+ *   const result = attributeText({ paragraphs: blocks, sessions })
+ *   return {
+ *     aiShare: result.aiShare,
+ *     words: result.words,
+ *     aiWords: result.aiWords,
+ *     prompts: result.prompts,
+ *     spans: result.paragraphs.map((p): ProvenanceSpan => {
+ *       const text = blocks[p.index]
+ *       return p.origin === 'ai'
+ *         ? { text, origin: 'ai', prompt: p.prompt, model: p.model }
+ *         : { text, origin: 'human' }
+ *     }),
+ *   }
+ * }
  *
- * setProvider(provider)
+ * // Write provenance.json, creating its folder.
+ * export function writeProvenance(outFile: string, provenance: Provenance): void {
+ *   mkdirSync(dirname(outFile), { recursive: true })
+ *   writeFileSync(outFile, `${JSON.stringify(provenance, null, 2)}\n`)
+ * }
  *
- * const dir = 'transcripts/my-post'
- * const sessions = readdirSync(dir).map((f) =>
- *   readTranscript({ text: readFileSync(join(dir, f), 'utf8'), fileName: f }),
- * )
+ * // In the build, for each PUBLISHED post (skip drafts), after the site's own build has written dist/:
+ * // writeProvenance('dist/my-post/provenance.json', postProvenance('posts/my-post.md', 'transcripts/my-post'))
  * ```
  *
  * @remarks
- * - A file no reader recognizes throws, naming the file and the readers
- *   tried — it is never read as an empty session. Check `canReadTranscript()`
- *   first to skip non-transcript files (a README beside the exports).
- * - Order matters only for a file two readers would both accept; the bundled
- *   readers accept disjoint formats.
+ * - **Do NOT call `readTranscript` on every file in a folder.** A file no
+ *   reader recognizes throws, naming the file and the readers tried — it is
+ *   never read as an empty session. Filter with `canReadTranscript()` first,
+ *   as the example does.
+ * - **Do NOT parse an export yourself or bond a single-format reader "to be
+ *   safe".** This bond reads every format above; a user turn is already only
+ *   what the person typed.
+ * - **A plain chat with speaker markers is read too — as `markdown-chat`,
+ *   never as a harness.** When only a real harness's own file may count
+ *   (attributing text to a model, say), check `session.format !==
+ *   'markdown-chat'`, or bond `createReader(harnessReaders)` instead.
+ * - **Do NOT import this from page or client code** — it is server-only and
+ *   throws in a browser bundle.
+ * - Install all four packages the example uses:
+ *   `npm install @molecule/api-agent-transcript @molecule/api-agent-transcript-autodetect @molecule/api-text-provenance @molecule/api-text-provenance-overlap`.
+ * - Order matters only for a file two readers would both accept. The harness
+ *   readers accept disjoint formats; the generic Markdown chat reader is
+ *   tried last, so it never claims a harness's own file.
  *
  * @module
  */

package/dist/provider.d.ts

@@ -12,7 +12,18 @@ import type { AgentTranscriptReader } from '@molecule/api-agent-transcript';
  */
 export declare function createReader(readers: readonly AgentTranscriptReader[]): AgentTranscriptReader;
 /**
- * Reads any Claude Code, Codex CLI or Molecule IDE transcript.
+ * Every harness-specific reader, in the order they are tried. Each accepts
+ * only its own harness's files, so the order only matters for the generic
+ * Markdown chat reader, which is not in this list. Compose
+ * `createReader(harnessReaders)` when only a real harness's own file should
+ * be read.
+ */
+export declare const harnessReaders: readonly AgentTranscriptReader[];
+/**
+ * Reads a transcript from any supported harness — Claude Code, Codex CLI,
+ * the Molecule IDE, Gemini CLI, Cline / Roo Code, OpenCode, GitHub Copilot
+ * Chat, Cursor and Aider — and, last, any plain Markdown / text chat with
+ * User / Assistant speaker markers.
  */
 export declare const provider: AgentTranscriptReader;
 //# sourceMappingURL=provider.d.ts.map

package/dist/provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAEV,qBAAqB,EAEtB,MAAM,gCAAgC,CAAA;AAKvC;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,SAAS,qBAAqB,EAAE,GAAG,qBAAqB,CAmB7F;AAED;;GAEG;AACH,eAAO,MAAM,QAAQ,EAAE,qBAAsE,CAAA"}
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAEV,qBAAqB,EAEtB,MAAM,gCAAgC,CAAA;AAYvC;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,SAAS,qBAAqB,EAAE,GAAG,qBAAqB,CAmB7F;AAED;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,EAAE,SAAS,qBAAqB,EAU1D,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,EAAE,qBAAuE,CAAA"}

package/dist/provider.js

@@ -3,9 +3,16 @@
  *
  * @module
  */
+import { provider as aider } from '@molecule/api-agent-transcript-aider';
 import { provider as claudeCode } from '@molecule/api-agent-transcript-claude-code';
+import { provider as cline } from '@molecule/api-agent-transcript-cline';
 import { provider as codex } from '@molecule/api-agent-transcript-codex';
+import { provider as copilotChat } from '@molecule/api-agent-transcript-copilot-chat';
+import { provider as cursor } from '@molecule/api-agent-transcript-cursor';
+import { provider as geminiCli } from '@molecule/api-agent-transcript-gemini-cli';
+import { provider as markdownChat } from '@molecule/api-agent-transcript-markdown-chat';
 import { provider as moleculeIde } from '@molecule/api-agent-transcript-molecule-ide';
+import { provider as opencode } from '@molecule/api-agent-transcript-opencode';
 /**
  * Compose readers: the first whose `detect()` accepts the input reads it.
  *
@@ -30,6 +37,27 @@ export function createReader(readers) {
     };
 }
 /**
- * Reads any Claude Code, Codex CLI or Molecule IDE transcript.
+ * Every harness-specific reader, in the order they are tried. Each accepts
+ * only its own harness's files, so the order only matters for the generic
+ * Markdown chat reader, which is not in this list. Compose
+ * `createReader(harnessReaders)` when only a real harness's own file should
+ * be read.
  */
-export const provider = createReader([claudeCode, codex, moleculeIde]);
+export const harnessReaders = [
+    claudeCode,
+    codex,
+    moleculeIde,
+    geminiCli,
+    cline,
+    opencode,
+    copilotChat,
+    cursor,
+    aider,
+];
+/**
+ * Reads a transcript from any supported harness — Claude Code, Codex CLI,
+ * the Molecule IDE, Gemini CLI, Cline / Roo Code, OpenCode, GitHub Copilot
+ * Chat, Cursor and Aider — and, last, any plain Markdown / text chat with
+ * User / Assistant speaker markers.
+ */
+export const provider = createReader([...harnessReaders, markdownChat]);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@molecule/api-agent-transcript-autodetect",
-  "version": "1.0.0",
-  "description": "Picks the reader that recognizes a transcript and delegates to it; bundles the Claude Code, Codex and Molecule IDE readers",
+  "version": "1.1.0",
+  "description": "Picks the reader that recognizes a transcript and delegates to it; bundles readers for Claude Code, Codex CLI, the Molecule IDE, Gemini CLI, Cline / Roo Code, OpenCode, GitHub Copilot Chat, Cursor and Aider, plus a generic Markdown chat reader",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -26,20 +26,33 @@
     "transcript",
     "detect",
     "claude-code",
-    "codex"
+    "codex",
+    "gemini-cli",
+    "aider",
+    "cursor",
+    "cline",
+    "opencode",
+    "copilot"
   ],
   "license": "Apache-2.0",
   "author": "Molecule Dev, Inc. (https://molecule.dev)",
   "dependencies": {
+    "@molecule/api-agent-transcript-aider": "1.0.0",
     "@molecule/api-agent-transcript-claude-code": "1.0.0",
+    "@molecule/api-agent-transcript-cline": "1.0.0",
     "@molecule/api-agent-transcript-codex": "1.0.0",
-    "@molecule/api-agent-transcript-molecule-ide": "1.0.0"
+    "@molecule/api-agent-transcript-copilot-chat": "1.0.0",
+    "@molecule/api-agent-transcript-cursor": "1.0.0",
+    "@molecule/api-agent-transcript-gemini-cli": "1.0.0",
+    "@molecule/api-agent-transcript-markdown-chat": "1.0.0",
+    "@molecule/api-agent-transcript-molecule-ide": "1.0.0",
+    "@molecule/api-agent-transcript-opencode": "1.0.0"
   },
   "peerDependencies": {
     "@molecule/api-agent-transcript": "^1.0.0"
   },
   "devDependencies": {
-    "@molecule/api-agent-transcript": "1.0.0",
+    "@molecule/api-agent-transcript": "1.0.1",
     "@types/node": "26.1.2",
     "typescript": "6.0.3",
     "vitest": "4.1.11"