orizu 0.3.2 → 0.3.4

package/src/index.ts

@@ -99,6 +99,62 @@ interface PromptSummary {
   description?: string | null
 }
 
+interface PromptCommentAuthor {
+  name: string
+  initials?: string
+  color?: string
+}
+
+interface PromptCommentAnchor {
+  text: string | null
+  startLine: number | null
+  endLine: number | null
+}
+
+interface PromptCommentReply {
+  id: string
+  body: string
+  author: PromptCommentAuthor
+  createdAt: string
+  updatedAt: string
+}
+
+interface PromptCommentThread {
+  id: string
+  status: 'open' | 'resolved'
+  body: string
+  anchor: PromptCommentAnchor | null
+  author: PromptCommentAuthor
+  createdAt: string
+  updatedAt: string
+  resolvedAt: string | null
+  resolvedByUserId: string | null
+  replyCount: number
+  replies: PromptCommentReply[]
+}
+
+interface PromptCommentsPayload {
+  prompt: {
+    id: string
+    name: string
+    role: string
+    description?: string | null
+  }
+  version: {
+    id: string
+    versionNumber?: number
+    versionLabel?: string | null
+    status?: string | null
+  }
+  summary: {
+    threadCount: number
+    openThreadCount: number
+    resolvedThreadCount: number
+    replyCount: number
+  }
+  comments: PromptCommentThread[]
+}
+
 interface ScorerSummary {
   id: string
   name: string
@@ -129,6 +185,8 @@ interface RunnerExecContext {
 
 type DatasetUploadSourceType = 'csv' | 'json' | 'jsonl'
 
+const MAX_README_LENGTH = 200_000
+
 interface DatasetUploadResponse {
   dataset: {
     id: string
@@ -137,6 +195,11 @@ interface DatasetUploadResponse {
     sourceType: string
     url?: string
   }
+  readmeVersion?: {
+    id: string
+    version_num: number
+    created_at: string
+  } | null
 }
 
 interface TeamMember {
@@ -200,11 +263,11 @@ function printVersion() {
 }
 
 function printUsage() {
-  printLine(`orizu global options:\n\n  --local                 Use http://localhost:3000\n  --server <url>          Use a specific server origin (for example: https://preview.example.com)\n  --version, -v           Print the orizu CLI version\n\norizu commands:\n\n  orizu login [--no-prompt-if-logged-in]\n  orizu logout\n  orizu whoami\n  orizu env [--project <team/project>] [--project-id <projectId>]\n  orizu log <event_type> --run-id <id> --sequence <n> --payload @event.json\n  orizu teams list\n  orizu teams create [--name <name>]\n  orizu teams members list [--team <teamSlug>]\n  orizu teams members add --email <email> [--team <teamSlug>]\n  orizu teams members remove --email <email> [--team <teamSlug>]\n  orizu teams members role --team <teamSlug> --email <email> --role <admin|member>\n  orizu projects list [--team <teamSlug>]\n  orizu projects create --name <name> [--team <teamSlug>]\n  orizu prompts list --project <team/project>\n  orizu prompts pull <prompt-id-or-name> --project <team/project> --out <dir> [--label <label> | --version <id>] [--json]\n  orizu prompts push <dir> [--runner-version <id>] [--project <team/project>] [--parent <version-id>] [--json]\n  orizu prompts labels set <prompt-name> <label> --version <version-id> [--project <team/project>] [--json]\n  orizu prompts scorers set-headline <prompt-id> --scorer-version <id> [--dataset-version <id> --split-set <id> --split <name>] [--project <team/project>] [--json]\n  orizu prompts scorers add <prompt-id> --scorer-version <id> [--dataset-version <id> --split-set <id> --split <name>] [--project <team/project>] [--json]\n  orizu scorers list --project <team/project>\n  orizu scorers register --project <team/project> --name <name> --manifest <manifest.json> [--prompt-version <id>] [--runner-version <id>] [--label <label>] [--json]\n  orizu scorers detail <scorer-id-or-name> --project <team/project> [--json]\n  orizu scorers labels set <scorer-name> <label> --version <scorer-version-id> [--project <team/project>] [--json]\n  orizu scores submit <results.jsonl|results.json> --scorer-version <id> --subject-version <prompt-version-id> [--dataset-version <id> --split-set <id> --split <name>] [--project <team/project>] [--json]\n  orizu judges list --project <team/project>\n  orizu judges pull <judge-id-or-name> --project <team/project> --out <dir> [--label <label> | --version <id>] [--json]\n  orizu judges push <dir> [--runner-version <id>] [--project <team/project>] [--parent <version-id>] [--json]\n  orizu runners push <dir> [--project <team/project>] [--name <name>] [--label <label>] [--json]\n  orizu runners exec (--prompt <prompt-version-id> | --prompt-version <id> --runner-version <id> | --scorer-version <id>) --dataset-version <id> --split-set <id-or-name> --split <name> [--runner-dir <dir>] --out <results.jsonl|results.jsonl.gz>\n  orizu optimizers push <dir> [--project <team/project>] [--name <name>] [--label <label>] [--json]\n  orizu runs submit <results.jsonl|results.jsonl.gz> --prompt-version <id> --runner-version <id> --dataset-version <id> --split-set <id> --split <name> [--project <team/project>]\n  orizu apps list [--project <team/project>]\n  orizu apps create --project <team/project> --name <name> --dataset <datasetId> --file <path> --input-schema <json-path> --output-schema <json-path> [--component <name>]\n  orizu apps update [--app <appId>] [--project <team/project>] --file <path> --input-schema <json-path> --output-schema <json-path> [--component <name>]\n  orizu apps link-dataset --dataset <datasetId> [--app <appId>] [--project <team/project>] [--version <n>]\n  orizu apps detail --app <appId> [--project <team/project>] [--json]\n  orizu tasks list [--project <team/project>]\n  orizu tasks create --project <team/project> --dataset <datasetId> --app <appId> --title <title> --assignees <userIdOrEmail1,userIdOrEmail2> [--version <n>] [--instructions <text>] [--labels-per-item <n>] [--json]\n  orizu tasks assign --task <taskId> --assignees <userId1,userId2>\n  orizu tasks status --task <taskId> [--json]\n  orizu tasks pause --task <taskId>\n  orizu tasks unpause --task <taskId>\n  orizu datasets upload --file <path> [--project <team/project>] [--name <name>]\n  orizu datasets push <path> [--project <team/project>] [--name <name>] [--json]\n  orizu datasets versions create <datasetId|dataset-name> [--project <team/project>] [--label <label>] [--json]\n  orizu datasets splits create <datasetVersionId> [--from-file <split.json>] [--json]\n  orizu datasets download [--dataset <datasetId|datasetUrl>] [--project <team/project>] [--format <csv|json|jsonl>] [--out <path>]\n  orizu datasets append [--dataset <datasetId|datasetUrl>] [--project <team/project>] --file <path>\n  orizu datasets edit-rows [--dataset <datasetId|datasetUrl>] [--project <team/project>] --file <path>\n  orizu datasets delete-rows [--dataset <datasetId|datasetUrl>] [--project <team/project>] --row-ids <id1,id2>\n  orizu datasets delete [--dataset <datasetId|datasetUrl>] [--project <team/project>]\n  orizu datasets lock [--dataset <datasetId|datasetUrl>] [--project <team/project>] [--reason <text>]\n  orizu datasets clone [--dataset <datasetId|datasetUrl>] [--project <team/project>] [--name <name>]\n  orizu tasks export [--task <taskId>] [--format <csv|json|jsonl>] [--out <path>]`)
+  printLine(`orizu global options:\n\n  --local                 Use http://localhost:3000\n  --server <url>          Use a specific server origin (for example: https://preview.example.com)\n  --version, -v           Print the orizu CLI version\n\norizu commands:\n\n  orizu login [--no-prompt-if-logged-in]\n  orizu logout\n  orizu whoami\n  orizu env [--project <team/project>] [--project-id <projectId>]\n  orizu log <event_type> --run-id <id> --sequence <n> --payload @event.json\n  orizu teams list\n  orizu teams create [--name <name>]\n  orizu teams members list [--team <teamSlug>]\n  orizu teams members add --email <email> [--team <teamSlug>]\n  orizu teams members remove --email <email> [--team <teamSlug>]\n  orizu teams members role --team <teamSlug> --email <email> --role <admin|member>\n  orizu projects list [--team <teamSlug>]\n  orizu projects create --name <name> [--team <teamSlug>]\n  orizu prompts list --project <team/project>\n  orizu prompts comments <prompt-id-or-name> --project <team/project> [--label <label> | --version <id>] [--json]\n  orizu prompts pull <prompt-id-or-name> --project <team/project> --out <dir> [--label <label> | --version <id>] [--json]\n  orizu prompts push <dir> [--runner-version <id>] [--project <team/project>] [--parent <version-id>] [--json]\n  orizu prompts labels set <prompt-name> <label> --version <version-id> [--project <team/project>] [--json]\n  orizu prompts scorers set-headline <prompt-id> --scorer-version <id> [--dataset-version <id> --split-set <id> --split <name>] [--project <team/project>] [--json]\n  orizu prompts scorers add <prompt-id> --scorer-version <id> [--dataset-version <id> --split-set <id> --split <name>] [--project <team/project>] [--json]\n  orizu scorers list --project <team/project>\n  orizu scorers register --project <team/project> --name <name> --manifest <manifest.json> [--prompt-version <id>] [--runner-version <id>] [--label <label>] [--json]\n  orizu scorers detail <scorer-id-or-name> --project <team/project> [--json]\n  orizu scorers labels set <scorer-name> <label> --version <scorer-version-id> [--project <team/project>] [--json]\n  orizu scores submit <results.jsonl|results.json> --scorer-version <id> --subject-version <prompt-version-id> [--dataset-version <id> --split-set <id> --split <name>] [--project <team/project>] [--json]\n  orizu judges list --project <team/project>\n  orizu judges pull <judge-id-or-name> --project <team/project> --out <dir> [--label <label> | --version <id>] [--json]\n  orizu judges push <dir> [--runner-version <id>] [--project <team/project>] [--parent <version-id>] [--json]\n  orizu runners push <dir> [--project <team/project>] [--name <name>] [--label <label>] [--json]\n  orizu runners exec (--prompt <prompt-version-id> | --prompt-version <id> --runner-version <id> | --scorer-version <id>) --dataset-version <id> --split-set <id-or-name> --split <name> [--runner-dir <dir>] --out <results.jsonl|results.jsonl.gz>\n  orizu optimizers push <dir> [--project <team/project>] [--name <name>] [--label <label>] [--json]\n  orizu runs submit <results.jsonl|results.jsonl.gz> --prompt-version <id> --runner-version <id> --dataset-version <id> --split-set <id> --split <name> [--project <team/project>]\n  orizu apps list [--project <team/project>]\n  orizu apps create --project <team/project> --name <name> --dataset <datasetId> --file <path> --input-schema <json-path> --output-schema <json-path> [--component <name>]\n  orizu apps update [--app <appId>] [--project <team/project>] --file <path> --input-schema <json-path> --output-schema <json-path> [--component <name>]\n  orizu apps link-dataset --dataset <datasetId> [--app <appId>] [--project <team/project>] [--version <n>]\n  orizu apps detail --app <appId> [--project <team/project>] [--json]\n  orizu apps export [--app <appId>] [--project <team/project>] [--version <n>] [--out <path>]\n  orizu tasks list [--project <team/project>]\n  orizu tasks create --project <team/project> --dataset <datasetId> --app <appId> --title <title> --assignees <userIdOrEmail1,userIdOrEmail2> [--version <n>] [--instructions <text>] [--labels-per-item <n>] [--json]\n  orizu tasks assign --task <taskId> --assignees <userId1,userId2>\n  orizu tasks status --task <taskId> [--json]\n  orizu tasks pause --task <taskId>\n  orizu tasks unpause --task <taskId>\n  orizu datasets upload --file <path> [--project <team/project>] [--name <name>] [--readme-file <README.md> | --readme-text <markdown>]\n  orizu datasets push <path> [--project <team/project>] [--name <name>] [--readme-file <README.md> | --readme-text <markdown>] [--json]\n  orizu datasets readme set <datasetId|dataset-name> [--project <team/project>] (--readme-file <README.md> | --readme-text <markdown>) [--json]\n  orizu datasets versions create <datasetId|dataset-name> [--project <team/project>] [--label <label>] [--readme-file <README.md> | --readme-text <markdown>] [--json]\n  orizu datasets splits create <datasetVersionId> [--from-file <split.json>] [--json]\n  orizu datasets download [--dataset <datasetId|datasetUrl>] [--project <team/project>] [--format <csv|json|jsonl>] [--out <path>]\n  orizu datasets append [--dataset <datasetId|datasetUrl>] [--project <team/project>] --file <path>\n  orizu datasets edit-rows [--dataset <datasetId|datasetUrl>] [--project <team/project>] --file <path>\n  orizu datasets delete-rows [--dataset <datasetId|datasetUrl>] [--project <team/project>] --row-ids <id1,id2>\n  orizu datasets delete [--dataset <datasetId|datasetUrl>] [--project <team/project>]\n  orizu datasets lock [--dataset <datasetId|datasetUrl>] [--project <team/project>] [--reason <text>]\n  orizu datasets clone [--dataset <datasetId|datasetUrl>] [--project <team/project>] [--name <name>]\n  orizu tasks export [--task <taskId>] [--format <csv|json|jsonl>] [--out <path>]`)
 }
 
 function printOptimizationUsage() {
-  printLine(`\nOptimization lifecycle commands:\n\n  orizu optimizations start --project <team/project> --optimizer-version <id> --prompt-version <id[,id]> --selection-scorer <id> [--reflection-scorer <id>] [--pareto-scorer <id>] [--best-scorer <id>] --dataset-version <id> --split-set <id> [--train-split <name>] [--validation-split <name>] [--metadata <json|@file>] [--json]\n  orizu optimizations run-gepa --project <team/project> --optimizer-version-id <id> --candidate-version-id <id> --runner-version-id <id> --candidate-runner-dir <dir> --scorer-version-id <id> --scorer-runner-version-id <id> --scorer-runner-dir <dir> --dataset-version-id <id> --split-set-id <id> [--train-split train] [--val-split validation]\n  orizu optimizations pause <run-id> [--reason <text>] [--json]\n  orizu optimizations resume <run-id> [--json]\n  orizu optimizations finish <run-id> [--best-score <n>] [--best-candidate <id>] [--result-prompt-version <id>] [--metadata <json|@file>] [--json]\n  orizu optimizations fail <run-id> [--reason <text>] [--metadata <json|@file>] [--json]\n  orizu optimizations cancel <run-id> [--reason <text>] [--json]`)
+  printLine(`\nOptimization lifecycle commands:\n\n  orizu optimizations start --project <team/project> --optimizer-version <id> --prompt-version <id[,id]> --selection-scorer <id> [--reflection-scorer <id>] [--pareto-scorer <id>] [--best-scorer <id>] --dataset-version <id> --split-set <id> [--train-split <name>] [--validation-split <name>] [--metadata <json|@file>] [--json]\n  orizu optimizations run-gepa --project <team/project> --optimizer-version-id <id> --candidate-version-id <id> --runner-version-id <id> --candidate-runner-dir <dir> --scorer-version-id <id> --scorer-runner-version-id <id> --scorer-runner-dir <dir> --dataset-version-id <id> --split-set-id <id> [--train-split train] [--val-split validation] [--log-dir logs]\n  orizu optimizations export <run-id> [--out <path>] [--json]\n  orizu optimizations pause <run-id> [--reason <text>] [--json]\n  orizu optimizations resume <run-id> [--json]\n  orizu optimizations finish <run-id> [--best-score <n>] [--best-candidate <id>] [--result-prompt-version <id>] [--report <markdown|@file> | --report-file <path>] [--metadata <json|@file>] [--json]\n  orizu optimizations fail <run-id> [--reason <text>] [--report <markdown|@file> | --report-file <path>] [--metadata <json|@file>] [--json]\n  orizu optimizations cancel <run-id> [--reason <text>] [--report <markdown|@file> | --report-file <path>] [--json]`)
 }
 
 let cliArgs = process.argv.slice(2)
@@ -239,6 +302,25 @@ export function expandHomePath(path: string): string {
   return path
 }
 
+function readReadmeMarkdownFromArgs(usage: string): string | null {
+  const readmeFile = getArg('--readme-file')
+  const readmeText = getArg('--readme-text')
+
+  if (readmeFile !== null && readmeText !== null) {
+    throw new Error(`Use either --readme-file or --readme-text, not both.\n${usage}`)
+  }
+
+  const markdown = readmeFile !== null
+    ? readFileSync(expandHomePath(readmeFile), 'utf8')
+    : readmeText
+
+  if (markdown !== null && markdown.length > MAX_README_LENGTH) {
+    throw new Error(`README markdown is too large. Maximum size is ${MAX_README_LENGTH} characters.`)
+  }
+
+  return markdown
+}
+
 function createCodeVerifier(): string {
   return randomBytes(32).toString('base64url')
 }
@@ -835,6 +917,78 @@ function printTaskStatusSummary(data: TaskStatusPayload) {
   }
 }
 
+function compactTerminalText(value: string, maxLength = 160): string {
+  const compact = sanitizeTerminalText(value).replace(/\s+/g, ' ').trim()
+  if (compact.length <= maxLength) {
+    return compact
+  }
+
+  return `${compact.slice(0, Math.max(0, maxLength - 1)).trim()}…`
+}
+
+function printIndentedBody(value: string, indent: string) {
+  const lines = sanitizeTerminalText(value || '').split(/\r?\n/)
+  for (const line of lines) {
+    printLine(`${indent}${line}`)
+  }
+}
+
+function formatPromptCommentAnchor(anchor: PromptCommentAnchor | null): string | null {
+  if (!anchor) {
+    return null
+  }
+
+  const lineLabel = anchor.startLine && anchor.endLine
+    ? anchor.startLine === anchor.endLine
+      ? `line ${anchor.startLine}`
+      : `lines ${anchor.startLine}-${anchor.endLine}`
+    : null
+  const selectedText = anchor.text ? `"${compactTerminalText(anchor.text, 180)}"` : null
+
+  if (lineLabel && selectedText) {
+    return `${lineLabel}: ${selectedText}`
+  }
+  return lineLabel || selectedText
+}
+
+function printPromptComments(data: PromptCommentsPayload) {
+  const versionLabel = data.version.versionLabel || (
+    data.version.versionNumber ? `v${data.version.versionNumber}` : data.version.id
+  )
+
+  printLine(`Prompt: ${sanitizeTerminalText(data.prompt.name)} (${sanitizeTerminalText(data.prompt.id)})`)
+  printLine(`Version: ${sanitizeTerminalText(String(versionLabel))} (${sanitizeTerminalText(data.version.id)})`)
+  printLine(
+    `Comments: ${data.summary.threadCount} thread${data.summary.threadCount === 1 ? '' : 's'} ` +
+    `(${data.summary.openThreadCount} open, ${data.summary.resolvedThreadCount} resolved, ${data.summary.replyCount} replies)`
+  )
+
+  if (data.comments.length === 0) {
+    printLine('\nNo comments found for this prompt version.')
+    return
+  }
+
+  for (const [index, thread] of data.comments.entries()) {
+    const authorName = thread.author?.name || 'Unknown'
+    const anchor = formatPromptCommentAnchor(thread.anchor)
+    printLine('')
+    printLine(`${index + 1}. [${thread.status}] ${sanitizeTerminalText(authorName)} · ${sanitizeTerminalText(thread.createdAt)}`)
+    if (anchor) {
+      printLine(`   Selection: ${anchor}`)
+    }
+    printIndentedBody(thread.body, '   ')
+
+    if (thread.replies.length > 0) {
+      printLine(`   Replies (${thread.replies.length})`)
+      for (const reply of thread.replies) {
+        const replyAuthor = reply.author?.name || 'Unknown'
+        printLine(`   - ${sanitizeTerminalText(replyAuthor)} · ${sanitizeTerminalText(reply.createdAt)}`)
+        printIndentedBody(reply.body, '     ')
+      }
+    }
+  }
+}
+
 const DEFAULT_AUTH_CALLBACK_PORT = 43123
 
 function resolveAuthCallbackPort(): number {
@@ -1185,6 +1339,37 @@ async function listJudges() {
   printPromptSummaries(data.judges, 'No judges found.')
 }
 
+async function listPromptComments() {
+  const promptRef = getPositionalArg(2)
+  const project = getArg('--project') || await resolveProjectSlug(null)
+  const label = getArg('--label')
+  const version = getArg('--version')
+
+  if (!promptRef) {
+    throw new Error('Usage: orizu prompts comments <prompt-id-or-name> --project <team/project> [--label <label> | --version <version-id>] [--json]')
+  }
+  if (label && version) {
+    throw new Error('Use either --label or --version, not both')
+  }
+
+  const params = new URLSearchParams({ project })
+  if (label) params.set('label', label)
+  if (version) params.set('version', version)
+
+  const response = await authedFetch(`/api/cli/prompts/${encodeURIComponent(promptRef)}/comments?${params.toString()}`)
+  if (!response.ok) {
+    throw new Error(`Failed to fetch prompt comments: ${await response.text()}`)
+  }
+
+  const data = await parseJsonResponse<PromptCommentsPayload>(response, 'Prompt comments')
+  if (hasJsonFlag()) {
+    printJson(data as unknown as Record<string, unknown>)
+    return
+  }
+
+  printPromptComments(data)
+}
+
 async function listScorers() {
   const project = getArg('--project') || await resolveProjectSlug(null)
   const response = await authedFetch(`/api/cli/scorers?project=${encodeURIComponent(project)}`)
@@ -1648,16 +1833,21 @@ async function createDatasetVersion() {
   const datasetId = getPositionalArg(3) || getArg('--dataset')
   const versionLabel = getArg('--label') || getArg('--version-label') || null
   const project = getArg('--project')
+  const usage = 'Usage: orizu datasets versions create <datasetId|dataset-name> [--project <team/project>] [--label <label>] [--readme-file <README.md> | --readme-text <markdown>] [--json]'
 
   if (!datasetId) {
-    throw new Error('Usage: orizu datasets versions create <datasetId|dataset-name> [--project <team/project>] [--label <label>] [--json]')
+    throw new Error(usage)
   }
 
+  const readmeMarkdown = readReadmeMarkdownFromArgs(usage)
   const resolvedDatasetId = await resolveDatasetIdForProject(datasetId, project)
   const response = await authedFetch(`/api/cli/datasets/${encodeURIComponent(resolvedDatasetId)}/versions`, {
     method: 'POST',
     headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({ versionLabel }),
+    body: JSON.stringify({
+      versionLabel,
+      ...(readmeMarkdown !== null ? { readmeMarkdown } : {}),
+    }),
   })
 
   if (!response.ok) {
@@ -1874,6 +2064,7 @@ function normalizeScoreResultsInput(sourcePath: string, raw: string): string {
 }
 
 type OptimizationLifecycleAction = 'pause' | 'resume' | 'finish' | 'fail' | 'cancel'
+const OPTIMIZATION_REPORT_MAX_BYTES = 2 * 1024 * 1024
 
 function parseOptionalNumberFlag(name: string): number | undefined {
   const value = getArg(name)
@@ -1893,6 +2084,46 @@ function hasObjectKeys(value: Record<string, unknown>): boolean {
   return Object.keys(value).length > 0
 }
 
+function readOptimizationReportInput(): { markdown: string; sourceName: string | null } | null {
+  const report = getArg('--report')
+  const reportFile = getArg('--report-file')
+
+  if (report && reportFile) {
+    throw new Error('Use either --report or --report-file, not both')
+  }
+
+  if (!report && !reportFile) {
+    return null
+  }
+
+  let markdown: string
+  let sourceName: string | null
+
+  if (reportFile) {
+    const expandedPath = expandHomePath(reportFile)
+    markdown = readSourceFile(reportFile)
+    sourceName = basename(expandedPath)
+  } else if (report?.startsWith('@')) {
+    const path = report.slice(1)
+    const expandedPath = expandHomePath(path)
+    markdown = readSourceFile(path)
+    sourceName = basename(expandedPath)
+  } else {
+    markdown = report || ''
+    sourceName = 'inline'
+  }
+
+  if (!markdown.trim()) {
+    throw new Error('Optimization report markdown must not be blank')
+  }
+
+  if (Buffer.byteLength(markdown, 'utf8') > OPTIMIZATION_REPORT_MAX_BYTES) {
+    throw new Error(`Optimization report exceeds ${OPTIMIZATION_REPORT_MAX_BYTES} bytes`)
+  }
+
+  return { markdown, sourceName }
+}
+
 async function startOptimizationRun() {
   const project = getArg('--project') || await resolveProjectSlug(null)
   const optimizerVersionId = getArg('--optimizer-version')
@@ -1997,6 +2228,11 @@ async function updateOptimizationRunLifecycle(action: OptimizationLifecycleActio
   }
   const metadata = readJsonObjectArg(getArg('--metadata'), 'optimization metadata')
   const reason = getArg('--reason')
+  const report = readOptimizationReportInput()
+
+  if (report && (action === 'pause' || action === 'resume')) {
+    throw new Error(`orizu optimizations ${action} does not accept optimization reports`)
+  }
 
   if ((action === 'pause' || action === 'cancel') && reason) {
     metadata.reason = reason
@@ -2011,6 +2247,11 @@ async function updateOptimizationRunLifecycle(action: OptimizationLifecycleActio
     body.metadata = metadata
   }
 
+  if (report) {
+    body.reportMarkdown = report.markdown
+    body.reportSourceName = report.sourceName
+  }
+
   if (action === 'finish') {
     const bestScore = parseOptionalNumberFlag('--best-score')
     if (bestScore !== undefined) {
@@ -2070,6 +2311,32 @@ async function updateOptimizationRunLifecycle(action: OptimizationLifecycleActio
   }
 }
 
+async function exportOptimizationRun() {
+  const runId = getPositionalArg(2) || getArg('--run-id')
+  const outPathArg = getArg('--out')
+
+  if (!runId) {
+    throw new Error('Usage: orizu optimizations export <run-id> [--out <path>] [--json]')
+  }
+
+  const response = await authedFetch(`/api/cli/optimization-runs/${encodeURIComponent(runId)}/export`)
+  if (!response.ok) {
+    throw new Error(`Failed to export optimization run: ${await response.text()}`)
+  }
+
+  const data = await parseJsonResponse<Record<string, unknown>>(response, 'Optimization export')
+  if (hasJsonFlag() && !outPathArg) {
+    printJson(data)
+    return
+  }
+
+  const filename = outPathArg
+    ? expandHomePath(outPathArg)
+    : `${runId}.optimization.json`
+  writeTextFileEnsuringDir(filename, `${JSON.stringify(data, null, 2)}\n`)
+  printLine(`Saved optimization export to ${sanitizeTerminalText(filename)}`)
+}
+
 function removeFlagWithValue(args: string[], flag: string): string[] {
   const filtered: string[] = []
   for (let index = 0; index < args.length; index += 1) {
@@ -2838,6 +3105,28 @@ interface AppDetailPayload {
   projectName: string
 }
 
+interface AppExportPayload {
+  app: {
+    id: string
+    name: string
+  }
+  version: {
+    id: string
+    versionNum: number
+    createdAt?: string
+    code: string
+  }
+}
+
+function defaultAppExportFilename(appName: string, versionNum: number): string {
+  const safeName = appName
+    .trim()
+    .replace(/[^A-Za-z0-9._-]+/g, '_')
+    .replace(/^_+|_+$/g, '')
+    .slice(0, 100)
+  return `${safeName || 'app'}.v${versionNum}.tsx`
+}
+
 async function appDetail() {
   const appId = getArg('--app')
   const project = getArg('--project')
@@ -2883,6 +3172,50 @@ async function appDetail() {
   printLine(`  Updated: ${sanitizeTerminalText(detail.updatedAt)}`)
 }
 
+async function exportAppSource() {
+  const project = getArg('--project')
+  const versionArg = getArg('--version')
+  const outPathArg = getArg('--out')
+  let appId = getArg('--app')
+
+  const versionNum = versionArg && /^[1-9]\d*$/.test(versionArg)
+    ? Number.parseInt(versionArg, 10)
+    : undefined
+
+  if (versionArg && versionNum === undefined) {
+    throw new Error('--version must be a positive integer')
+  }
+
+  if (!appId) {
+    const selected = await selectAppIdInteractively(project)
+    appId = selected.appId
+  }
+
+  const query = new URLSearchParams()
+  if (project) {
+    query.set('project', project)
+  }
+  if (versionNum) {
+    query.set('version', String(versionNum))
+  }
+
+  const suffix = query.toString() ? `?${query.toString()}` : ''
+  const response = await authedFetch(`/api/cli/apps/${encodeURIComponent(appId)}/export${suffix}`)
+  if (!response.ok) {
+    throw new Error(`Failed to export app (${response.status}): ${await response.text()}`)
+  }
+
+  const data = await parseJsonResponse<AppExportPayload>(response, 'App export')
+  const filename = outPathArg
+    ? expandHomePath(outPathArg)
+    : defaultAppExportFilename(data.app.name, data.version.versionNum)
+
+  writeTextFileEnsuringDir(filename, data.version.code)
+  printLine(
+    `Saved app ${sanitizeTerminalText(data.app.name)} v${data.version.versionNum} source to ${sanitizeTerminalText(filename)}`
+  )
+}
+
 async function listTeamMembers() {
   const teamSlug = await resolveTeamSlug(getArg('--team'))
 
@@ -2969,7 +3302,8 @@ async function createDatasetFromRows(
   project: string,
   name: string,
   sourceType: DatasetUploadSourceType,
-  rows: Array<Record<string, unknown>>
+  rows: Array<Record<string, unknown>>,
+  readmeMarkdown: string | null = null
 ): Promise<DatasetUploadResponse> {
   const response = await authedFetch('/api/cli/datasets/upload', {
     method: 'POST',
@@ -2981,6 +3315,7 @@ async function createDatasetFromRows(
       name,
       rows,
       sourceType,
+      ...(readmeMarkdown !== null ? { readmeMarkdown } : {}),
     }),
   })
 
@@ -2995,7 +3330,8 @@ async function createDatasetFromRows(
 async function uploadJsonlDatasetInChunks(
   file: string,
   project: string,
-  datasetName: string
+  datasetName: string,
+  readmeMarkdown: string | null = null
 ) {
   let dataset: DatasetUploadResponse['dataset'] | null = null
   let totalUploaded = 0
@@ -3030,7 +3366,7 @@ async function uploadJsonlDatasetInChunks(
 
     try {
       if (!dataset) {
-        const data = await createDatasetFromRows(project, datasetName, 'jsonl', chunk)
+        const data = await createDatasetFromRows(project, datasetName, 'jsonl', chunk, readmeMarkdown)
         dataset = data.dataset
         totalUploaded = data.dataset.rowCount
         continue
@@ -3071,22 +3407,24 @@ async function uploadDataset() {
   const projectArg = getArg('--project')
   const fileArg = getArg('--file')
   const name = getArg('--name')
+  const usage = 'Usage: orizu datasets upload --file <path> [--project <team/project>] [--name <name>] [--readme-file <README.md> | --readme-text <markdown>]'
 
   if (!fileArg) {
-    throw new Error('Usage: orizu datasets upload --file <path> [--project <team/project>] [--name <name>]')
+    throw new Error(usage)
   }
 
+  const readmeMarkdown = readReadmeMarkdownFromArgs(usage)
   const file = expandHomePath(fileArg)
   const project = await resolveProjectSlug(projectArg)
   const datasetName = name || basename(file)
 
   if (extname(file).toLowerCase() === '.jsonl') {
-    await uploadJsonlDatasetInChunks(file, project, datasetName)
+    await uploadJsonlDatasetInChunks(file, project, datasetName, readmeMarkdown)
     return
   }
 
   const { rows, sourceType } = parseDatasetFile(file)
-  const data = await createDatasetFromRows(project, datasetName, sourceType, rows)
+  const data = await createDatasetFromRows(project, datasetName, sourceType, rows, readmeMarkdown)
 
   printLine(`Uploaded dataset ${sanitizeTerminalText(data.dataset.name)} (${sanitizeTerminalText(data.dataset.id)}) with ${data.dataset.rowCount} rows.`)
   if (data.dataset.url) {
@@ -3098,23 +3436,29 @@ async function pushDataset() {
   const projectArg = getArg('--project')
   const fileArg = getPositionalArg(2) || getArg('--file')
   const name = getArg('--name')
+  const usage = 'Usage: orizu datasets push <rows.csv|rows.json|rows.jsonl> [--project <team/project>] [--name <name>] [--readme-file <README.md> | --readme-text <markdown>] [--json]'
 
   if (!fileArg) {
-    throw new Error('Usage: orizu datasets push <rows.csv|rows.json|rows.jsonl> [--project <team/project>] [--name <name>] [--json]')
+    throw new Error(usage)
   }
 
+  const readmeMarkdown = readReadmeMarkdownFromArgs(usage)
   const file = expandHomePath(fileArg)
   const project = await resolveProjectSlug(projectArg)
   const datasetName = name || basename(file)
   const { rows, sourceType } = parseDatasetFile(file)
-  const data = await createDatasetFromRows(project, datasetName, sourceType, rows)
+  const data = await createDatasetFromRows(project, datasetName, sourceType, rows, readmeMarkdown)
 
   if (hasJsonFlag()) {
-    printJson({
+    const payload: Record<string, unknown> = {
       dataset_id: data.dataset.id,
       name: data.dataset.name,
       row_count: data.dataset.rowCount,
-    })
+    }
+    if (data.readmeVersion?.id) {
+      payload.readme_version_id = data.readmeVersion.id
+    }
+    printJson(payload)
     return
   }
 
@@ -3124,6 +3468,55 @@ async function pushDataset() {
   }
 }
 
+async function setDatasetReadme() {
+  const datasetId = getPositionalArg(3) || getArg('--dataset')
+  const project = getArg('--project')
+  const usage = 'Usage: orizu datasets readme set <datasetId|dataset-name> [--project <team/project>] (--readme-file <README.md> | --readme-text <markdown>) [--json]'
+
+  if (!datasetId) {
+    throw new Error(usage)
+  }
+
+  const readmeMarkdown = readReadmeMarkdownFromArgs(usage)
+  if (readmeMarkdown === null) {
+    throw new Error(usage)
+  }
+
+  const resolvedDatasetId = await resolveDatasetIdForProject(datasetId, project)
+  const response = await authedFetch(`/api/cli/datasets/${encodeURIComponent(resolvedDatasetId)}/readme`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ markdown: readmeMarkdown }),
+  })
+
+  if (!response.ok) {
+    throw new Error(`Failed to save dataset README: ${await response.text()}`)
+  }
+
+  const data = await parseJsonResponse<{
+    version: {
+      id: string
+      dataset_id: string
+      version_num: number
+      created_at: string
+    }
+  }>(response, 'Dataset README save')
+
+  if (hasJsonFlag()) {
+    printJson({
+      dataset_id: data.version.dataset_id,
+      readme_version_id: data.version.id,
+      readme_version_num: data.version.version_num,
+    })
+    return
+  }
+
+  printLine(
+    `Saved README v${data.version.version_num} for dataset ` +
+    `${sanitizeTerminalText(data.version.dataset_id)} (${sanitizeTerminalText(data.version.id)}).`
+  )
+}
+
 function getDatasetReferenceInput(): string | null {
   const fromFlag = getArg('--dataset')
   if (fromFlag) {
@@ -3930,6 +4323,11 @@ export async function main(rawArgs = process.argv.slice(2)) {
     return
   }
 
+  if (command === 'prompts' && subcommand === 'comments') {
+    await listPromptComments()
+    return
+  }
+
   if (command === 'prompts' && subcommand === 'pull') {
     await pullPromptArtifact('prompt')
     return
@@ -4025,6 +4423,11 @@ export async function main(rawArgs = process.argv.slice(2)) {
     return
   }
 
+  if (command === 'optimizations' && subcommand === 'export') {
+    await exportOptimizationRun()
+    return
+  }
+
   if (
     command === 'optimizations' &&
     (
@@ -4064,6 +4467,11 @@ export async function main(rawArgs = process.argv.slice(2)) {
     return
   }
 
+  if (command === 'apps' && subcommand === 'export') {
+    await exportAppSource()
+    return
+  }
+
   if (command === 'tasks' && subcommand === 'list') {
     await listTasks()
     return
@@ -4115,6 +4523,11 @@ export async function main(rawArgs = process.argv.slice(2)) {
   }
 
   const datasetsAction = cliArgs[2]
+  if (command === 'datasets' && subcommand === 'readme' && datasetsAction === 'set') {
+    await setDatasetReadme()
+    return
+  }
+
   if (command === 'datasets' && subcommand === 'versions' && datasetsAction === 'create') {
     await createDatasetVersion()
     return