orizu 0.3.5 → 0.3.6

package/src/index.ts

@@ -23,7 +23,9 @@ import { clearServerCredentials, getServerCredentials, saveServerCredentials } f
 import { parseDatasetFile } from './file-parser.js'
 import { streamJsonlRowChunks } from './jsonl-stream.js'
 import { parseDatasetReference } from './dataset-download.js'
+import { extractErrorMessage } from './error-response.js'
 import { parseGlobalFlags } from './global-flags.js'
+import { getCapabilities, renderHelpForArgs, renderRootHelp } from './help.js'
 import { runLocalAppPreview } from './preview-runtime.js'
 import {
   assertSecureTokenTransport,
@@ -32,6 +34,14 @@ import {
   resolveLoginBaseUrl,
   setGlobalFlags,
 } from './http.js'
+import {
+  getSkillInstallPath,
+  installSkillTarget,
+  isSkillInstallTarget,
+  SKILL_INSTALL_TARGETS,
+  SkillInstallTarget,
+  targetNeedsOverwrite,
+} from './skill-installer.js'
 import { formatTaskCreateError } from './task-create-error.js'
 import { LoginResponse } from './types.js'
 
@@ -270,8 +280,7 @@ 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 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 scorers exec --scorer-version <id> (--subject-version <prompt-version-id> | --optimization-run <id> --candidate <id>) --dataset-version <id> --split-set <id> --split <name> [--subject-results <jsonl>] [--dependency-score-run <alias=id>] [--dependency-results <alias=path>] [--no-submit] [--out <score.json>] [--project <team/project>] [--json]\n  orizu scores submit <results.jsonl|results.json> --scorer-version <id> (--subject-version <prompt-version-id> | --optimization-run <id> --candidate <id>) [--aggregate] [--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>]`)
-  printPreviewUsage()
+  printLine(renderRootHelp())
 }
 
 function printPreviewUsage() {
@@ -279,10 +288,11 @@ function printPreviewUsage() {
 }
 
 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] [--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]`)
+  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] [--no-skip-perfect-parent-reflection]\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)
+let cliJsonOutput = false
 
 function getArg(name: string): string | null {
   const index = cliArgs.indexOf(name)
@@ -293,6 +303,31 @@ function getArg(name: string): string | null {
   return cliArgs[index + 1]
 }
 
+function getArgs(name: string): string[] {
+  const values: string[] = []
+  for (let index = 0; index < cliArgs.length; index += 1) {
+    if (cliArgs[index] !== name) {
+      continue
+    }
+
+    const value = cliArgs[index + 1]
+    if (!value || value.startsWith('-')) {
+      throw new Error(`Usage: ${name} <value>`)
+    }
+
+    values.push(value)
+    index += 1
+  }
+
+  return values
+}
+
+function rejectDashPrefixedOptionValue(name: string, value: string | null) {
+  if (value && value.startsWith('-')) {
+    throw new Error(`Invalid value for ${name}: option values cannot start with a dash`)
+  }
+}
+
 export function normalizeSlugInput(slug: string): string {
   return slug.trim().toLowerCase()
 }
@@ -2217,7 +2252,7 @@ async function execScorer() {
 }
 
 type OptimizationLifecycleAction = 'pause' | 'resume' | 'finish' | 'fail' | 'cancel'
-const OPTIMIZATION_REPORT_MAX_BYTES = 2 * 1024 * 1024
+const MARKDOWN_REPORT_MAX_BYTES = 2 * 1024 * 1024
 
 function parseOptionalNumberFlag(name: string): number | undefined {
   const value = getArg(name)
@@ -2237,10 +2272,15 @@ function hasObjectKeys(value: Record<string, unknown>): boolean {
   return Object.keys(value).length > 0
 }
 
-function readOptimizationReportInput(): { markdown: string; sourceName: string | null } | null {
+function readMarkdownReportInput(
+  reportLabel: 'Optimization' | 'Task'
+): { markdown: string; sourceName: string | null } | null {
   const report = getArg('--report')
   const reportFile = getArg('--report-file')
 
+  rejectDashPrefixedOptionValue('--report', report)
+  rejectDashPrefixedOptionValue('--report-file', reportFile)
+
   if (report && reportFile) {
     throw new Error('Use either --report or --report-file, not both')
   }
@@ -2267,16 +2307,24 @@ function readOptimizationReportInput(): { markdown: string; sourceName: string |
   }
 
   if (!markdown.trim()) {
-    throw new Error('Optimization report markdown must not be blank')
+    throw new Error(`${reportLabel} 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`)
+  if (Buffer.byteLength(markdown, 'utf8') > MARKDOWN_REPORT_MAX_BYTES) {
+    throw new Error(`${reportLabel} report exceeds ${MARKDOWN_REPORT_MAX_BYTES} bytes`)
   }
 
   return { markdown, sourceName }
 }
 
+function readOptimizationReportInput(): { markdown: string; sourceName: string | null } | null {
+  return readMarkdownReportInput('Optimization')
+}
+
+function readTaskReportInput(): { markdown: string; sourceName: string | null } | null {
+  return readMarkdownReportInput('Task')
+}
+
 async function startOptimizationRun() {
   const project = getArg('--project') || await resolveProjectSlug(null)
   const optimizerVersionId = getArg('--optimizer-version')
@@ -2674,13 +2722,120 @@ function readSourceBytes(pathArg: string): Buffer {
 }
 
 function hasJsonFlag(): boolean {
-  return hasArg('--json')
+  return cliJsonOutput || hasArg('--json')
 }
 
 function printJson(value: Record<string, unknown>) {
   printLine(JSON.stringify(value))
 }
 
+function printCapabilities() {
+  const capabilities = getCapabilities(getCliVersion())
+  if (hasJsonFlag()) {
+    printLine(JSON.stringify(capabilities))
+    return
+  }
+
+  printLine('orizu capabilities')
+  printLine('')
+  printLine('Run `orizu capabilities --json` for a machine-readable command manifest.')
+  printLine('')
+  for (const command of capabilities.commands) {
+    printLine(`  ${command.name.padEnd(34)} ${command.help}`)
+  }
+}
+
+async function askYesNo(question: string, defaultYes: boolean): Promise<boolean> {
+  const rl = createInterface({ input, output })
+  try {
+    const suffix = defaultYes ? 'Y/n' : 'y/N'
+    const answer = (await rl.question(`${question} (${suffix}) `)).trim().toLowerCase()
+    if (!answer) {
+      return defaultYes
+    }
+    return answer === 'y' || answer === 'yes'
+  } finally {
+    rl.close()
+  }
+}
+
+async function promptSkillInstallTargets(): Promise<SkillInstallTarget[]> {
+  if (!isInteractiveTerminal()) {
+    throw new Error(
+      `Usage: orizu install-skill --target <${SKILL_INSTALL_TARGETS.join('|')}> [--yes] [--dry-run]`
+    )
+  }
+
+  printLine('Where should the Orizu CLI skill be installed?')
+  const targets: SkillInstallTarget[] = []
+  for (const target of SKILL_INSTALL_TARGETS) {
+    const defaultYes = target === 'agent-user'
+    if (await askYesNo(`  Install to ${target}?`, defaultYes)) {
+      targets.push(target)
+    }
+  }
+
+  return targets
+}
+
+function parseSkillInstallTargets(): SkillInstallTarget[] {
+  const rawTargets = getArgs('--target')
+  const targets: SkillInstallTarget[] = []
+  for (const target of rawTargets) {
+    if (!isSkillInstallTarget(target)) {
+      throw new Error(
+        `Unknown skill install target '${target}'. Available targets: ${SKILL_INSTALL_TARGETS.join(', ')}`
+      )
+    }
+    if (!targets.includes(target)) {
+      targets.push(target)
+    }
+  }
+  return targets
+}
+
+function formatSkillInstallAction(action: string): string {
+  if (action === 'created') return 'Wrote'
+  if (action === 'updated') return 'Updated'
+  if (action === 'would-create') return 'Would write'
+  return 'Would update'
+}
+
+async function installSkillCommand() {
+  const skipConfirm = hasArg('--yes')
+  const dryRun = hasArg('--dry-run')
+  let targets = parseSkillInstallTargets()
+  if (targets.length === 0) {
+    targets = await promptSkillInstallTargets()
+  }
+
+  if (targets.length === 0) {
+    printLine('No targets selected; nothing to do.')
+    return
+  }
+
+  for (const target of targets) {
+    let overwrite = skipConfirm
+    const installPath = getSkillInstallPath(target)
+    if (!dryRun && !overwrite && targetNeedsOverwrite(target)) {
+      if (!isInteractiveTerminal()) {
+        throw new Error(`${installPath} already exists. Pass --yes to replace it.`)
+      }
+      overwrite = await askYesNo(`Replace ${installPath}?`, true)
+      if (!overwrite) {
+        printLine(`Skipped ${installPath}`)
+        continue
+      }
+    }
+
+    const result = installSkillTarget(target, {
+      overwrite,
+      dryRun,
+    })
+    printLine(`${formatSkillInstallAction(result.action)} ${result.path}`)
+  }
+}
+
 function readJsonFile(pathArg: string): Record<string, unknown> {
   const raw = readSourceFile(pathArg)
   try {
@@ -3104,6 +3259,7 @@ async function createTask() {
   const appId = getArg('--app')
   const title = getArg('--title')
   const assignees = parseCommaSeparated(getArg('--assignees'))
+  const publish = hasArg('--publish')
   const versionArg = getArg('--version')
   const instructions = getArg('--instructions')
   const labelsPerItemArg = getArg('--labels-per-item')
@@ -3112,8 +3268,8 @@ async function createTask() {
   const versionNum =
     Number.isInteger(parsedVersionNum) && parsedVersionNum > 0 ? parsedVersionNum : null
 
-  if (!projectSlug || !datasetId || !appId || !title || assignees.length === 0) {
-    throw new Error('Usage: orizu tasks create --project <team/project> --dataset <datasetId> --app <appId> --title <title> --assignees <userIdOrEmail1,userIdOrEmail2> [--version <n>] [--instructions <text>] [--labels-per-item <n>] [--json]')
+  if (!projectSlug || !datasetId || !appId || !title || (publish && assignees.length === 0)) {
+    throw new Error('Usage: orizu tasks create --project <team/project> --dataset <datasetId> --app <appId> --title <title> [--assignees <userIdOrEmail1,userIdOrEmail2>] [--publish] [--version <n>] [--instructions <text>] [--labels-per-item <n>] [--json]')
   }
 
   if (versionArg && versionNum === null) {
@@ -3130,6 +3286,7 @@ async function createTask() {
       versionNum,
       title,
       memberIds: assignees,
+      publish,
       instructions,
       requiredAssignmentsPerRow: labelsPerItem,
     }),
@@ -3172,6 +3329,13 @@ async function createTask() {
       status: data.task.status,
       requiredAssignmentsPerRow: data.task.requiredAssignmentsPerRow,
       assignmentsCreated: data.assignmentsCreated,
+      draft: data.task.status === 'draft',
+      ...(data.task.status === 'draft'
+        ? {
+            message: 'Draft created. Test it manually before assigning.',
+            publishCommand: `orizu tasks publish --task ${data.task.id} --assignees <userId1,userId2>`,
+          }
+        : {}),
       ...(data.assignmentShortfall !== undefined ? { assignmentShortfall: data.assignmentShortfall } : {}),
       ...(data.warning ? { warning: data.warning } : {}),
     }, null, 2))
@@ -3180,15 +3344,76 @@ async function createTask() {
 
   const baseUrl = getBaseUrl()
   const taskUrl = `${baseUrl}/d/${projectSlug}/tasks/${data.task.id}`
+  const isDraft = data.task.status === 'draft'
   printLine(
-    `Created task ${sanitizeTerminalText(data.task.title)} (${sanitizeTerminalText(data.task.id)}) [${sanitizeTerminalText(data.task.status)}]` +
+    `Created ${isDraft ? 'draft ' : ''}task ${sanitizeTerminalText(data.task.title)} (${sanitizeTerminalText(data.task.id)}) [${sanitizeTerminalText(data.task.status)}]` +
     `\n  Task ID:    ${sanitizeTerminalText(data.task.id)}` +
     `\n  Dataset ID: ${sanitizeTerminalText(datasetId)}` +
     `\n  Version:    v${data.task.versionNum} (${sanitizeTerminalText(data.task.versionId)})` +
     `\n  Labels/row: ${data.task.requiredAssignmentsPerRow}` +
     `\n  Assignments: ${data.assignmentsCreated}` +
     (data.warning ? `\n  Warning:    ${sanitizeTerminalText(data.warning)}` : '') +
-    `\n  URL:        ${sanitizeTerminalText(taskUrl)}`
+    `\n  URL:        ${sanitizeTerminalText(taskUrl)}` +
+    (isDraft
+      ? `\n\nThis task is a draft. Test it manually before assigning.\nPublish after approval: orizu tasks publish --task ${sanitizeTerminalText(data.task.id)} --assignees <userId1,userId2>`
+      : '')
+  )
+}
+
+async function publishTask() {
+  const taskId = getArg('--task')
+  const assignees = parseCommaSeparated(getArg('--assignees'))
+
+  if (!taskId || assignees.length === 0) {
+    throw new Error('Usage: orizu tasks publish --task <taskId> --assignees <userId1,userId2> [--json]')
+  }
+
+  const response = await authedFetch(`/api/cli/tasks/${encodeURIComponent(taskId)}/publish`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ memberIds: assignees }),
+  })
+
+  if (!response.ok) {
+    throw new Error(`Failed to publish task: ${await extractErrorMessage(response)}`)
+  }
+
+  const data = await parseJsonResponse<{
+    task: { id: string; status: string }
+    assignmentsProcessed: number
+    assignmentsCreated: number
+    assignmentsRemoved?: number
+    assignmentShortfall?: number
+    warning?: string
+  }>(
+    response,
+    'Task publish'
+  )
+
+  if (hasArg('--json')) {
+    printLine(JSON.stringify({
+      taskId: data.task.id,
+      status: data.task.status,
+      assignmentsCreated: data.assignmentsCreated,
+      assignmentsProcessed: data.assignmentsProcessed,
+      ...(data.assignmentsRemoved !== undefined
+        ? { assignmentsRemoved: data.assignmentsRemoved }
+        : {}),
+      ...(data.assignmentShortfall !== undefined
+        ? { assignmentShortfall: data.assignmentShortfall }
+        : {}),
+      ...(data.warning ? { warning: data.warning } : {}),
+    }, null, 2))
+    return
+  }
+
+  printLine(
+    `Published task ${sanitizeTerminalText(data.task.id)} [${sanitizeTerminalText(data.task.status)}]` +
+    `\n  Assignments: ${data.assignmentsCreated}` +
+    (data.assignmentsRemoved !== undefined
+      ? `\n  Replaced:    ${data.assignmentsRemoved} old assignments removed`
+      : '') +
+    (data.warning ? `\n  Warning:     ${sanitizeTerminalText(data.warning)}` : '')
   )
 }
 
@@ -3281,6 +3506,58 @@ async function updateTaskStatus(targetStatus: 'paused' | 'active') {
   printLine(`${action} task ${sanitizeTerminalText(data.task.id)} [${sanitizeTerminalText(data.task.status)}]`)
 }
 
+async function setTaskReport() {
+  const taskId = getArg('--task')
+  rejectDashPrefixedOptionValue('--task', taskId)
+  if (!taskId) {
+    throw new Error(
+      'Usage: orizu tasks report set --task <taskId> (--report <markdown|@file> | --report-file <path>) [--json]'
+    )
+  }
+
+  const report = readTaskReportInput()
+  if (!report) {
+    throw new Error(
+      'Usage: orizu tasks report set --task <taskId> (--report <markdown|@file> | --report-file <path>) [--json]'
+    )
+  }
+
+  const response = await authedFetch(`/api/cli/tasks/${encodeURIComponent(taskId)}/report`, {
+    method: 'PATCH',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      reportMarkdown: report.markdown,
+      reportSourceName: report.sourceName,
+    }),
+  })
+
+  if (!response.ok) {
+    throw new Error(`Failed to update task report: ${await response.text()}`)
+  }
+
+  const data = await parseJsonResponse<{
+    task: {
+      id: string
+      status: string
+      report: {
+        markdown: string
+        sourceName: string | null
+        createdAt: string | null
+      }
+    }
+  }>(response, 'Task report update')
+
+  if (hasJsonFlag()) {
+    printJson(data)
+    return
+  }
+
+  printLine(
+    `Uploaded task report for ${sanitizeTerminalText(data.task.id)} ` +
+    `[${sanitizeTerminalText(data.task.status)}]`
+  )
+}
+
 interface AppDetailPayload {
   id: string
   name: string
@@ -4435,11 +4712,45 @@ async function runnersExec() {
   }
 }
 
+function isHelpToken(value: string): boolean {
+  return value === '--help' || value === '-h'
+}
+
+function extractHelpTarget(args: string[]): string[] | null {
+  if (args[0] === 'help') {
+    return helpTargetFromArgs(args.slice(1))
+  }
+
+  if (!args.some(isHelpToken)) {
+    return null
+  }
+
+  return helpTargetFromArgs(args)
+}
+
+function helpTargetFromArgs(args: string[]): string[] {
+  const targetArgs = args.filter(arg => !isHelpToken(arg) && arg !== '--json')
+  const optionIndex = targetArgs.findIndex(arg => arg.startsWith('-'))
+  return optionIndex === -1 ? targetArgs : targetArgs.slice(0, optionIndex)
+}
+
 export async function main(rawArgs = process.argv.slice(2)) {
   const parsed = parseGlobalFlags(rawArgs)
   setGlobalFlags(parsed.flags)
   cliArgs = parsed.args
 
+  cliJsonOutput = false
+  if (cliArgs[0] === '--json') {
+    cliJsonOutput = true
+    cliArgs = cliArgs.slice(1)
+  }
+
+  const helpTarget = extractHelpTarget(cliArgs)
+  if (helpTarget !== null) {
+    printLine(renderHelpForArgs(helpTarget))
+    return
+  }
+
   const command = cliArgs[0]
   const subcommand = cliArgs[1]
 
@@ -4450,10 +4761,24 @@ export async function main(rawArgs = process.argv.slice(2)) {
 
   if (!command) {
     printUsage()
-    printOptimizationUsage()
     process.exit(1)
   }
 
+  if (command === 'capabilities') {
+    printCapabilities()
+    return
+  }
+
+  if (command === 'install-skill') {
+    await installSkillCommand()
+    return
+  }
+
+  if (command === 'skills' && subcommand === 'install') {
+    await installSkillCommand()
+    return
+  }
+
   if (command === 'login') {
     await login()
     return
@@ -4691,6 +5016,11 @@ export async function main(rawArgs = process.argv.slice(2)) {
     return
   }
 
+  if (command === 'tasks' && subcommand === 'publish') {
+    await publishTask()
+    return
+  }
+
   if (command === 'tasks' && subcommand === 'assign') {
     await assignTask()
     return
@@ -4701,6 +5031,15 @@ export async function main(rawArgs = process.argv.slice(2)) {
     return
   }
 
+  if (
+    command === 'tasks' &&
+    subcommand === 'report' &&
+    (cliArgs[2] === 'set' || cliArgs[2] === 'upload')
+  ) {
+    await setTaskReport()
+    return
+  }
+
   if (command === 'tasks' && subcommand === 'pause') {
     await updateTaskStatus('paused')
     return
@@ -4778,7 +5117,6 @@ export async function main(rawArgs = process.argv.slice(2)) {
   }
 
   printUsage()
-  printOptimizationUsage()
   process.exit(1)
 }