recappi 0.1.56 → 0.1.57

package/dist/index.js

@@ -19933,6 +19933,184 @@ function runMacOpen(args, deps) {
   });
 }
 
+// src/commandMetadata.ts
+var COMMON_TASKS = [
+  { label: "Record audio + live captions", command: "recappi record --live" },
+  { label: "Transcribe a local file", command: "recappi upload <file> --transcribe --wait" },
+  { label: "Re-transcribe a recording", command: "recappi recordings retranscribe <recordingId> --wait" },
+  { label: "List / find recordings", command: "recappi recordings list" },
+  { label: "Read a transcript", command: "recappi transcript get <transcriptId>" },
+  { label: "Download / open audio", command: "recappi audio <recordingId> --open" },
+  { label: "Check a transcription job", command: "recappi jobs wait <jobId>" },
+  { label: "Account \xB7 quota \xB7 usage", command: "recappi account status" },
+  { label: "Sign in", command: "recappi auth login" },
+  { label: "Diagnose auth / audio setup", command: "recappi doctor" }
+];
+var COMMAND_METADATA = {
+  "auth import-macos": {
+    capabilities: ["Reuse the macOS app's signed-in session for the CLI"],
+    examples: [
+      { description: "Copy the macOS app session into CLI config", command: "recappi auth import-macos" }
+    ],
+    relatedCommands: ["auth login", "auth status"]
+  },
+  "auth login": {
+    capabilities: ["Authenticate the CLI via device-code OAuth"],
+    examples: [
+      { description: "Start device-code sign-in", command: "recappi auth login" },
+      { description: "Print the login URL without opening a browser", command: "recappi auth login --no-open" }
+    ],
+    relatedCommands: ["auth status", "auth import-macos"]
+  },
+  "auth logout": {
+    capabilities: ["Sign the CLI out and clear stored token"],
+    examples: [{ description: "Remove the local CLI token", command: "recappi auth logout" }],
+    relatedCommands: ["auth status", "auth login"]
+  },
+  "auth status": {
+    capabilities: ["Check whether the CLI is signed in, and as whom"],
+    examples: [{ description: "Show sign-in status", command: "recappi auth status" }],
+    relatedCommands: ["auth login", "doctor"]
+  },
+  "account status": {
+    capabilities: ["Show account plan, minutes/storage quota, and usage"],
+    examples: [{ description: "Show account, quota, and local state", command: "recappi account status" }],
+    relatedCommands: ["auth status", "dashboard stats"]
+  },
+  doctor: {
+    capabilities: ["Diagnose auth, cloud connectivity, local audio/TCC permissions"],
+    examples: [{ description: "Check setup health", command: "recappi doctor" }],
+    relatedCommands: ["auth status", "record"]
+  },
+  upload: {
+    capabilities: [
+      "Upload a local audio file or directory",
+      "Transcribe uploaded audio",
+      "Wait for transcription to finish"
+    ],
+    examples: [
+      {
+        description: "Upload a local audio file and wait for transcription",
+        command: "recappi upload talk.m4a --transcribe --wait"
+      },
+      {
+        description: "Upload and transcribe a directory of audio files",
+        command: "recappi upload ./recordings --transcribe"
+      },
+      {
+        description: "Transcribe with title and language hints",
+        command: 'recappi upload talk.m4a --transcribe --language en --title "Team sync"'
+      }
+    ],
+    relatedCommands: ["jobs wait", "recordings list", "transcript get"]
+  },
+  record: {
+    capabilities: [
+      "Record system audio and/or mic",
+      "Live captions while recording",
+      "Auto upload+transcribe+summarize on stop"
+    ],
+    examples: [
+      { description: "Record with live captions", command: "recappi record --live" },
+      { description: "Record a microphone-only voice note", command: 'recappi record --no-system-audio --title "Voice note"' },
+      { description: "Record with live caption translation", command: "recappi record --live --translation-language en" }
+    ],
+    relatedCommands: ["recordings list", "transcript get"]
+  },
+  audio: {
+    capabilities: ["Download audio", "Open in default player", "Reveal in Finder"],
+    examples: [
+      { description: "Download and open audio", command: "recappi audio <recordingId> --open" },
+      { description: "Download audio and print the local path", command: "recappi audio <recordingId> --download" },
+      { description: "Reveal downloaded audio in Finder", command: "recappi audio <recordingId> --reveal" }
+    ],
+    relatedCommands: ["recordings list", "recordings get"]
+  },
+  schema: {
+    capabilities: ["Print the full machine-readable CLI contract for agents"],
+    examples: [
+      { description: "Read the full machine-readable command contract", command: "recappi schema --json --compact" }
+    ]
+  },
+  "dashboard stats": {
+    capabilities: ["Fetch aggregate dashboard counters/stats"],
+    examples: [{ description: "Fetch dashboard counters", command: "recappi dashboard stats --json --compact" }],
+    relatedCommands: ["account status", "recordings list"]
+  },
+  "recordings get": {
+    capabilities: ["Fetch one recording's metadata and status by id"],
+    examples: [{ description: "Fetch one recording", command: "recappi recordings get <recordingId>" }],
+    relatedCommands: ["recordings list", "transcript get", "audio"]
+  },
+  "recordings list": {
+    capabilities: ["List recent recordings", "Search recordings and transcripts", "Find a recordingId"],
+    examples: [
+      { description: "List recent recordings", command: "recappi recordings list" },
+      { description: "Search recordings and transcripts", command: "recappi recordings list --search <query>" }
+    ],
+    relatedCommands: ["recordings get", "audio", "transcript get"]
+  },
+  "recordings retranscribe": {
+    capabilities: ["Re-transcribe an existing recording", "Re-transcribe with new language/prompt/scene/model"],
+    examples: [
+      {
+        description: "Start a fresh transcription for an existing cloud recording",
+        command: "recappi recordings retranscribe <recordingId> --wait"
+      },
+      {
+        description: "Re-transcribe with language and prompt hints",
+        command: 'recappi recordings retranscribe <recordingId> --language en --prompt "medical terms" --wait'
+      }
+    ],
+    relatedCommands: ["jobs wait", "transcript get"]
+  },
+  "transcript get": {
+    capabilities: ["Fetch a finished transcript by id"],
+    examples: [{ description: "Fetch an existing transcript", command: "recappi transcript get <transcriptId>" }],
+    relatedCommands: ["recordings get", "jobs wait"]
+  },
+  "jobs list": {
+    capabilities: ["List transcription jobs", "Filter by status"],
+    examples: [
+      { description: "List active transcription jobs", command: "recappi jobs list --status active" },
+      { description: "List recent jobs across statuses", command: "recappi jobs list --status all --limit 20" }
+    ],
+    relatedCommands: ["jobs wait", "recordings retranscribe"]
+  },
+  "jobs wait": {
+    capabilities: ["Block until a transcription job reaches a terminal state"],
+    examples: [
+      { description: "Wait for a transcription job", command: "recappi jobs wait <jobId>" }
+    ],
+    relatedCommands: ["jobs list", "transcript get"]
+  }
+};
+function commonTasksHelpText() {
+  return [
+    "Common tasks:",
+    ...COMMON_TASKS.map((task) => `  ${task.label.padEnd(30)} ${task.command}`)
+  ].join("\n");
+}
+function commandMetadataHelpText(commandName) {
+  const metadata = COMMAND_METADATA[commandName];
+  if (!metadata) return "";
+  const lines = [];
+  if (metadata.examples.length > 0) {
+    lines.push("Examples:");
+    for (const example of metadata.examples) {
+      lines.push(`  ${example.command}`);
+      lines.push(`    ${example.description}`);
+    }
+  }
+  if (metadata.relatedCommands && metadata.relatedCommands.length > 0) {
+    lines.push("Related:");
+    lines.push(`  ${metadata.relatedCommands.join(" \xB7 ")}`);
+  }
+  return lines.length > 0 ? `
+${lines.join("\n")}
+` : "";
+}
+
 // src/render.ts
 function createHumanProgressState(interactive) {
   return {
@@ -20289,6 +20467,19 @@ Next:
       const summary = typeof entry.summary === "string" ? ` \u2014 ${entry.summary}` : "";
       opts.stdout(`  ${entry.name}${summary}
 `);
+      if (Array.isArray(entry.capabilities) && entry.capabilities.length > 0) {
+        opts.stdout(`    capabilities: ${entry.capabilities.join(", ")}
+`);
+      }
+      if (Array.isArray(entry.examples) && entry.examples.length > 0) {
+        const first = entry.examples.find(
+          (example) => isRecord4(example) && typeof example.command === "string"
+        );
+        if (isRecord4(first) && typeof first.command === "string") {
+          opts.stdout(`    example: ${first.command}
+`);
+        }
+      }
     }
     const errorCount = Array.isArray(data.errorCodes) ? data.errorCodes.length : 0;
     opts.stdout(`
@@ -20556,6 +20747,7 @@ var COMMON_OPTION_LONGS = /* @__PURE__ */ new Set([
   "--human",
   "--fields",
   "--compact",
+  "--verbose",
   "--origin"
 ]);
 var EXIT_CODE_LEGEND = {
@@ -20594,11 +20786,18 @@ function walkCommands(command, path6, out) {
 }
 function leafCommandDoc(command, fullName) {
   const dataSchema = COMMAND_DATA_SCHEMAS[fullName];
+  const metadata = COMMAND_METADATA[fullName] ?? {
+    capabilities: [],
+    examples: []
+  };
   return {
     name: fullName,
     summary: command.description(),
+    capabilities: metadata.capabilities,
     arguments: argumentDocs(command),
     options: optionDocs(command).filter((opt) => !isCommonOption(opt)),
+    examples: metadata.examples,
+    ...metadata.relatedCommands ? { relatedCommands: metadata.relatedCommands } : {},
     ...dataSchema ? { data: toJsonSchema(dataSchema) } : {}
   };
 }
@@ -22370,15 +22569,24 @@ function buildProgram({ onHelpOutput, onSelect }) {
   }).addHelpText(
     "after",
     `
+${commonTasksHelpText()}
+
+Transcribe:
+  Local audio file          recappi upload <file> --transcribe --wait
+  Existing cloud recording  recappi recordings retranscribe <recordingId> --wait
+  (the "transcript" command only fetches an existing transcript by id.)
+
 Agent mode:
   Non-TTY stdout defaults to JSON. Progress and human diagnostics go to stderr.
   Use --json for a single envelope or --jsonl for a terminal event stream.
+  Use recappi schema --json --compact to probe commands, capabilities, examples,
+  related commands, output schemas, error codes, and JSONL events.
 `
   );
   addCommonOptions(program);
-  const auth = program.command("auth").description("Authentication commands");
+  const auth = program.command("auth").description("Sign in/out and check Recappi Cloud auth");
   addCommonOptions(auth);
-  const authLogin = auth.command("login").description("Sign in to Recappi Cloud with a device code").option("--no-open", "print the device URL without opening a browser");
+  const authLogin = auth.command("login").description("Sign in to Recappi Cloud with a device code").option("--no-open", "print the device URL without opening a browser").addHelpText("after", commandMetadataHelpText("auth login"));
   addCommonOptions(authLogin);
   authLogin.action((opts, command) => {
     onSelect({
@@ -22388,7 +22596,7 @@ Agent mode:
       ...opts.open === false ? { noOpen: true } : {}
     });
   });
-  const authLogout = auth.command("logout").description("Remove the Recappi CLI sign-in token");
+  const authLogout = auth.command("logout").description("Remove the Recappi CLI sign-in token").addHelpText("after", commandMetadataHelpText("auth logout"));
   addCommonOptions(authLogout);
   authLogout.action((_options, command) => {
     onSelect({
@@ -22397,7 +22605,7 @@ Agent mode:
       commandName: "auth logout"
     });
   });
-  const authImportMacOS = auth.command("import-macos").description("Copy the Recappi Mini macOS app session into CLI config");
+  const authImportMacOS = auth.command("import-macos").description("Copy the Recappi Mini macOS app session into CLI config").addHelpText("after", commandMetadataHelpText("auth import-macos"));
   addCommonOptions(authImportMacOS);
   authImportMacOS.action((_options, command) => {
     onSelect({
@@ -22406,7 +22614,7 @@ Agent mode:
       commandName: "auth import-macos"
     });
   });
-  const authStatus = auth.command("status").description("Show Recappi Cloud sign-in status");
+  const authStatus = auth.command("status").description("Show Recappi Cloud sign-in status").addHelpText("after", commandMetadataHelpText("auth status"));
   addCommonOptions(authStatus);
   authStatus.action((_options, command) => {
     onSelect({
@@ -22415,7 +22623,7 @@ Agent mode:
       commandName: "auth status"
     });
   });
-  const doctor = program.command("doctor").description("Check Recappi auth, cloud connectivity, and local audio support");
+  const doctor = program.command("doctor").description("Check Recappi auth, cloud connectivity, and local audio support").addHelpText("after", commandMetadataHelpText("doctor"));
   addCommonOptions(doctor);
   doctor.action((_options, command) => {
     onSelect({
@@ -22424,9 +22632,9 @@ Agent mode:
       commandName: "doctor"
     });
   });
-  const account = program.command("account").description("Account and quota commands");
+  const account = program.command("account").description("Show account status, quota, and usage");
   addCommonOptions(account);
-  const accountStatus = account.command("status").description("Show account, quota, and local state");
+  const accountStatus = account.command("status").description("Show account, quota, and local state").addHelpText("after", commandMetadataHelpText("account status"));
   addCommonOptions(accountStatus);
   accountStatus.action((_options, command) => {
     onSelect({
@@ -22435,7 +22643,7 @@ Agent mode:
       commandName: "account status"
     });
   });
-  const upload = program.command("upload <file-or-dir>").description("Upload an audio file or directory to Recappi Cloud").option("--title <title>", "recording title", parseStringOption("--title")).option("--transcribe", "start transcription after upload").option("--wait", "wait for the transcription job to reach a terminal state").option("--language <lang>", "transcription language hint", parseStringOption("--language")).option("--provider <name>", "transcription provider", parseStringOption("--provider")).option("--prompt <text>", "transcription prompt/context", parseStringOption("--prompt")).option("--force", "force upload if a conflict is retryable");
+  const upload = program.command("upload <file-or-dir>").description("Upload a local audio file or directory (optionally transcribe)").option("--title <title>", "recording title", parseStringOption("--title")).option("--transcribe", "start transcription after upload").option("--wait", "wait for the transcription job to reach a terminal state").option("--language <lang>", "transcription language hint", parseStringOption("--language")).option("--provider <name>", "transcription provider", parseStringOption("--provider")).option("--prompt <text>", "transcription prompt/context", parseStringOption("--prompt")).option("--force", "force upload if a conflict is retryable").addHelpText("after", commandMetadataHelpText("upload"));
   addCommonOptions(upload);
   upload.action((inputPath, opts, command) => {
     onSelect({
@@ -22452,7 +22660,7 @@ Agent mode:
       ...opts.force === true ? { force: true } : {}
     });
   });
-  const record2 = program.command("record").description("Start a Recappi Mini sidecar recording").option("--title <title>", "recording title", parseStringOption("--title")).option("--live", "show live captions while recording").option("--no-system-audio", "record microphone only").option("--no-microphone", "record system audio only").option(
+  const record2 = program.command("record").description("Record system/mic audio via the Recappi Mini sidecar").option("--title <title>", "recording title", parseStringOption("--title")).option("--live", "show live captions while recording").option("--no-system-audio", "record microphone only").option("--no-microphone", "record system audio only").option(
     "--translation-language <lang>",
     "live caption translation language",
     parseStringOption("--translation-language")
@@ -22464,7 +22672,7 @@ Agent mode:
     "--sidecar-command <path>",
     "Recappi Mini sidecar executable",
     parseStringOption("--sidecar-command")
-  );
+  ).addHelpText("after", commandMetadataHelpText("record"));
   addCommonOptions(record2);
   record2.action((opts, command) => {
     if (opts.systemAudio === false && opts.microphone === false) {
@@ -22485,11 +22693,11 @@ Agent mode:
       ...typeof opts.sidecarCommand === "string" ? { sidecarCommand: opts.sidecarCommand } : {}
     });
   });
-  const audio = program.command("audio").description("Download or open a recording audio file").argument("<recording-id>", "recording id").option("--download", "download audio and print the local path").option("--open", "download if needed, then open the audio file").option("--reveal", "download if needed, then reveal the audio file in Finder").option(
+  const audio = program.command("audio").description("Download, open, or reveal a recording's audio file").argument("<recording-id>", "recording id").option("--download", "download audio and print the local path").option("--open", "download if needed, then open the audio file").option("--reveal", "download if needed, then reveal the audio file in Finder").option(
     "--output-dir <dir>",
     "directory for downloaded audio",
     parseStringOption("--output-dir")
-  );
+  ).addHelpText("after", commandMetadataHelpText("audio"));
   addCommonOptions(audio);
   audio.action((recordingId, opts, command) => {
     onSelect({
@@ -22501,7 +22709,7 @@ Agent mode:
       ...opts.outputDir ? { outputDir: opts.outputDir } : {}
     });
   });
-  const schema = program.command("schema").description("Print the machine-readable CLI contract (commands, error codes, JSON Schemas)");
+  const schema = program.command("schema").description("Print the machine-readable CLI contract (commands, error codes, JSON Schemas)").addHelpText("after", commandMetadataHelpText("schema"));
   addCommonOptions(schema);
   schema.action((_options, command) => {
     onSelect({
@@ -22511,9 +22719,9 @@ Agent mode:
       document: buildSchemaDocument(program)
     });
   });
-  const dashboard = program.command("dashboard").description("Dashboard data commands");
+  const dashboard = program.command("dashboard").description("Fetch dashboard counters and stats");
   addCommonOptions(dashboard);
-  const dashboardStats = dashboard.command("stats").description("Fetch dashboard counters");
+  const dashboardStats = dashboard.command("stats").description("Fetch dashboard counters").addHelpText("after", commandMetadataHelpText("dashboard stats"));
   addCommonOptions(dashboardStats);
   dashboardStats.action((_options, command) => {
     onSelect({
@@ -22522,9 +22730,9 @@ Agent mode:
       commandName: "dashboard stats"
     });
   });
-  const recordings = program.command("recordings").description("Recording commands");
+  const recordings = program.command("recordings").description("List, fetch, and re-transcribe recordings");
   addCommonOptions(recordings);
-  const recordingsList = recordings.command("list").description("List recent recordings").option("--limit <n>", "number of recordings to show", parseLimitOption("--limit", 1, 100), 20).option("--cursor <cursor>", "pagination cursor", parseStringOption("--cursor")).option("--search <query>", "search recordings and transcripts", parseStringOption("--search"));
+  const recordingsList = recordings.command("list").description("List recent recordings").option("--limit <n>", "number of recordings to show", parseLimitOption("--limit", 1, 100), 20).option("--cursor <cursor>", "pagination cursor", parseStringOption("--cursor")).option("--search <query>", "search recordings and transcripts", parseStringOption("--search")).addHelpText("after", commandMetadataHelpText("recordings list"));
   addCommonOptions(recordingsList);
   recordingsList.action((_options, command) => {
     const opts = command.opts();
@@ -22537,7 +22745,7 @@ Agent mode:
       ...typeof opts.search === "string" ? { search: opts.search } : {}
     });
   });
-  const recordingsGet = recordings.command("get <recordingId>").description("Fetch a recording by recording id");
+  const recordingsGet = recordings.command("get <recordingId>").description("Fetch a recording by recording id").addHelpText("after", commandMetadataHelpText("recordings get"));
   addCommonOptions(recordingsGet);
   recordingsGet.action(
     (recordingId, _options, command) => {
@@ -22549,7 +22757,7 @@ Agent mode:
       });
     }
   );
-  const recordingsRetranscribe = recordings.command("retranscribe <recordingId>").description("Start a fresh transcription job for an existing recording").option("--language <lang>", "transcription language hint", parseStringOption("--language")).option("--provider <name>", "transcription provider", parseStringOption("--provider")).option("--model <name>", "transcription model", parseStringOption("--model")).option("--prompt <text>", "custom transcription prompt/context", parseStringOption("--prompt")).option("--scene <id>", "transcription scene preset", parseStringOption("--scene")).option("--wait", "wait for the transcription job to reach a terminal state");
+  const recordingsRetranscribe = recordings.command("retranscribe <recordingId>").description("Start a fresh transcription job for an existing recording").option("--language <lang>", "transcription language hint", parseStringOption("--language")).option("--provider <name>", "transcription provider", parseStringOption("--provider")).option("--model <name>", "transcription model", parseStringOption("--model")).option("--prompt <text>", "custom transcription prompt/context", parseStringOption("--prompt")).option("--scene <id>", "transcription scene preset", parseStringOption("--scene")).option("--wait", "wait for the transcription job to reach a terminal state").addHelpText("after", commandMetadataHelpText("recordings retranscribe"));
   addCommonOptions(recordingsRetranscribe);
   recordingsRetranscribe.action(
     (recordingId, _options, command) => {
@@ -22568,9 +22776,16 @@ Agent mode:
       });
     }
   );
-  const transcript = program.command("transcript").description("Transcript commands");
+  const transcript = program.command("transcript").description("Read transcripts (create via upload --transcribe or recordings retranscribe)").addHelpText(
+    "after",
+    `
+To create a transcript (not here):
+  Local audio file          recappi upload <file> --transcribe --wait
+  Existing cloud recording  recappi recordings retranscribe <recordingId> --wait
+`
+  );
   addCommonOptions(transcript);
-  const transcriptGet = transcript.command("get <transcriptId>").description("Fetch a transcript by transcript id");
+  const transcriptGet = transcript.command("get <transcriptId>").description("Fetch a transcript by transcript id").addHelpText("after", commandMetadataHelpText("transcript get"));
   addCommonOptions(transcriptGet);
   transcriptGet.action(
     (transcriptId, _options, command) => {
@@ -22582,7 +22797,7 @@ Agent mode:
       });
     }
   );
-  const jobs = program.command("jobs").description("Transcription job commands");
+  const jobs = program.command("jobs").description("List transcription jobs and wait for one to finish");
   addCommonOptions(jobs);
   const jobsList = jobs.command("list").description("List recent transcription jobs").option(
     "--status <status>",
@@ -22590,6 +22805,7 @@ Agent mode:
     parseJobStatusOption,
     "all"
   ).option("--limit <n>", "number of jobs to show", parseLimitOption("--limit", 1, 50), 10);
+  jobsList.addHelpText("after", commandMetadataHelpText("jobs list"));
   addCommonOptions(jobsList);
   jobsList.action((_options, command) => {
     const opts = command.opts();
@@ -22601,7 +22817,7 @@ Agent mode:
       limit: opts.limit ?? 10
     });
   });
-  const jobsWait = jobs.command("wait <jobId>").description("Wait for an existing transcription job to finish");
+  const jobsWait = jobs.command("wait <jobId>").description("Wait for an existing transcription job to finish").addHelpText("after", commandMetadataHelpText("jobs wait"));
   addCommonOptions(jobsWait);
   jobsWait.action((jobId, _options, command) => {
     onSelect({