@theplato/tiro-cli 0.1.0 → 0.2.1

package/dist/bin/tiro.js

@@ -175,8 +175,8 @@ async function startLoopbackServer() {
     );
     if (pendingResolve) settle(pendingResolve, { code, state });
   });
-  await new Promise((resolve2) => {
-    server.listen(0, "127.0.0.1", () => resolve2());
+  await new Promise((resolve3) => {
+    server.listen(0, "127.0.0.1", () => resolve3());
   });
   const address = server.address();
   const port = address.port;
@@ -185,7 +185,7 @@ async function startLoopbackServer() {
     redirectUri,
     port,
     waitForCallback(timeoutMs) {
-      return new Promise((resolve2, reject) => {
+      return new Promise((resolve3, reject) => {
         const timer = setTimeout(() => {
           pendingResolve = null;
           pendingReject = null;
@@ -193,7 +193,7 @@ async function startLoopbackServer() {
         }, timeoutMs);
         pendingResolve = (r) => {
           clearTimeout(timer);
-          resolve2(r);
+          resolve3(r);
         };
         pendingReject = (e) => {
           clearTimeout(timer);
@@ -722,15 +722,47 @@ var NoteSchema = z2.object({
   recordingStartAt: z2.string().nullable().optional(),
   recordingEndAt: z2.string().nullable().optional()
 }).passthrough();
+var TextObjectSchema = z2.object({
+  type: z2.string(),
+  content: z2.string()
+});
+var SpeakerInfoSchema = z2.object({
+  label: z2.string(),
+  personName: z2.string().nullable().optional()
+});
+var DiarizedSegmentSchema = z2.object({
+  content: z2.string(),
+  speaker: SpeakerInfoSchema
+});
 var ParagraphSchema = z2.object({
-  text: z2.string(),
-  startMs: z2.number().nullable().optional(),
-  endMs: z2.number().nullable().optional(),
-  speaker: z2.object({
-    name: z2.string().nullable().optional(),
-    email: z2.string().nullable().optional()
-  }).nullable().optional()
+  uuid: z2.string(),
+  transcribeLocale: z2.string().nullable().optional(),
+  transcript: TextObjectSchema.nullable().optional(),
+  diarizedSegments: z2.array(DiarizedSegmentSchema).nullable().optional(),
+  timeFrom: z2.string().nullable().optional(),
+  timeTo: z2.string().nullable().optional(),
+  locked: z2.boolean().optional()
 }).passthrough();
+var McpSegmentSchema = z2.object({
+  content: z2.string(),
+  speaker: z2.object({
+    label: z2.string(),
+    name: z2.string().nullable()
+  }).nullable()
+});
+var McpParagraphSchema = z2.object({
+  timeFrom: z2.string().nullable(),
+  timeTo: z2.string().nullable(),
+  segments: z2.array(McpSegmentSchema)
+});
+var McpTranscriptSchema = z2.object({
+  noteGuid: z2.string(),
+  title: z2.string(),
+  participants: z2.array(z2.string()),
+  createdAt: z2.string(),
+  recordingDurationSeconds: z2.number(),
+  paragraphs: z2.array(McpParagraphSchema)
+});
 var PageCursorResponseSchema = (item) => z2.object({
   content: z2.array(item),
   nextCursor: z2.string().nullable()
@@ -903,34 +935,113 @@ function createApiClient(opts = {}) {
   return new TiroApiClient(hostname, t.accessToken);
 }
 
+// src/lib/util/parseDate.ts
+var RELATIVE_RE = /^(\d+)([smhdw])$/i;
+var UNIT_MS = {
+  s: 1e3,
+  m: 6e4,
+  h: 36e5,
+  d: 864e5,
+  w: 6048e5
+};
+function parseDate(input) {
+  const trimmed = input.trim();
+  const rel = trimmed.match(RELATIVE_RE);
+  if (rel) {
+    const num = parseInt(rel[1] ?? "", 10);
+    const unit = (rel[2] ?? "").toLowerCase();
+    const factor = UNIT_MS[unit];
+    if (!factor || !Number.isFinite(num)) {
+      throw invalidDate(input);
+    }
+    return new Date(Date.now() - num * factor).toISOString();
+  }
+  const d = new Date(trimmed);
+  if (Number.isNaN(d.getTime())) throw invalidDate(input);
+  return d.toISOString();
+}
+function invalidDate(input) {
+  return new TiroError(
+    {
+      code: "invalid_date",
+      message: `Invalid date: "${input}". Use ISO-8601 (e.g. 2026-04-01T10:00:00Z) or relative (e.g. 7d, 24h, 30m).`,
+      errorType: "bad_request"
+    },
+    ExitCode.Usage
+  );
+}
+
+// src/lib/util/noteFilter.ts
+var PLACEHOLDER_TITLE = "Untitled";
+var PLACEHOLDER_SOURCE_TYPES = /* @__PURE__ */ new Set(["onboarding"]);
+function isVisibleNote(note) {
+  if (note.title === PLACEHOLDER_TITLE) return false;
+  if (note.sourceType !== null && note.sourceType !== void 0 && PLACEHOLDER_SOURCE_TYPES.has(note.sourceType)) {
+    return false;
+  }
+  return true;
+}
+
 // src/commands/notes/list.ts
 var ListResponseSchema = PageCursorResponseSchema(NoteSchema);
+var DEFAULT_PAGE_SIZE = 100;
+var MAX_PAGE_SIZE = 1e3;
+var HELP_AFTER = `
+Examples:
+  tiro notes list --since 7d
+  tiro notes list --keyword "OKR" --since 30d --json
+  tiro notes list --folder <id> --limit 50
+
+Keyword matching:
+  --keyword reorders results by OpenSearch relevance (case-insensitive,
+  full-text against note title and paragraph content). When --keyword is
+  set, nextCursor is always null. Without --keyword, results are ordered
+  by createdAt desc.
+
+Note: placeholder notes (title='Untitled' or sourceType='onboarding') are
+filtered out by default. A page of N may return fewer than N visible notes \u2014
+keep paginating to fetch more, or pass --include-untitled to surface them.
+`;
 function registerNotesList(parent) {
-  parent.command("list").description("List recent notes").option("--folder <id>", "Filter by folder ID").option("--limit <n>", "Max results per page (default 50, max 500)").option("--cursor <token>", "Cursor for the next page").action(async (opts, cmd) => {
+  parent.command("list").description("List notes (lightweight metadata).").option("--keyword <text>", 'Reorder by OpenSearch relevance for this keyword (e.g. "OKR")').option("--folder <id>", "Restrict to a folder and its descendants").option(
+    "--since <date>",
+    "Inclusive lower bound on createdAt (ISO-8601 or relative: 7d, 24h, 30m)"
+  ).option("--until <date>", "Exclusive upper bound on createdAt").option(
+    "--limit <n>",
+    `Max results per page (default ${DEFAULT_PAGE_SIZE}, max ${MAX_PAGE_SIZE})`
+  ).option("--cursor <token>", "Continue a previous page").option(
+    "--include-untitled",
+    "Include placeholder notes (title='Untitled' or sourceType='onboarding'). Default: hidden",
+    false
+  ).addHelpText("after", HELP_AFTER).action(async (opts, cmd) => {
     const globalOpts = cmd.optsWithGlobals();
-    const limit = clampLimit(opts.limit);
     const client = createApiClient({
       ...globalOpts.hostname !== void 0 && { hostnameOverride: globalOpts.hostname }
     });
     const params = {};
+    if (opts.keyword) params["keyword"] = opts.keyword;
     if (opts.folder) params["folderId"] = opts.folder;
-    if (limit !== void 0) params["size"] = limit;
+    if (opts.since) params["createdAtFrom"] = parseDate(opts.since);
+    if (opts.until) params["createdAtTo"] = parseDate(opts.until);
+    const size = clampLimit(opts.limit);
+    if (size !== void 0) params["size"] = size;
     if (opts.cursor) params["cursor"] = opts.cursor;
     const res = await client.getJson("/v1/external/notes", ListResponseSchema, params);
+    const visible = opts.includeUntitled === true ? res.content : res.content.filter(isVisibleNote);
     const mode = resolveOutputMode(globalOpts);
     if (mode === "json") {
-      for (const note of res.content) printNdjson(note);
+      for (const note of visible) printNdjson(note);
       if (res.nextCursor) printNdjson({ _cursor: res.nextCursor });
     } else {
-      printPretty(res.content, res.nextCursor, globalOpts);
+      printPretty(visible, res.nextCursor, globalOpts);
     }
   });
 }
 function clampLimit(raw) {
   if (!raw) return void 0;
   const n = parseInt(raw, 10);
-  if (!Number.isFinite(n) || n <= 0) return 50;
-  return Math.min(n, 500);
+  if (!Number.isFinite(n) || n <= 0) return DEFAULT_PAGE_SIZE;
+  return Math.min(n, MAX_PAGE_SIZE);
 }
 function printPretty(notes, nextCursor, opts) {
   if (notes.length === 0) {
@@ -938,11 +1049,13 @@ function printPretty(notes, nextCursor, opts) {
 `);
     return;
   }
+  const titleWidth = computeTitleWidth();
   for (const n of notes) {
     const date = n.createdAt.slice(0, 10);
     const dur = formatDuration(n.recordingDurationSeconds);
+    const title = truncate(n.title, titleWidth);
     process.stdout.write(
-      `${color(date, "gray", opts)}  ${color(n.guid, "dim", opts)}  ${color(dur, "cyan", opts)}  ${n.title}
+      `${color(date, "gray", opts)}  ${color(n.guid, "dim", opts)}  ${color(dur, "cyan", opts)}  ${title}
 `
     );
   }
@@ -954,6 +1067,15 @@ function printPretty(notes, nextCursor, opts) {
     );
   }
 }
+function computeTitleWidth() {
+  const cols = process.stdout.columns;
+  if (!cols || cols < 60) return 40;
+  return Math.max(20, cols - 60);
+}
+function truncate(s, max) {
+  if (s.length <= max) return s;
+  return s.slice(0, Math.max(0, max - 1)) + "\u2026";
+}
 function formatDuration(sec) {
   if (!sec || sec <= 0) return "\u2014";
   const m = Math.floor(sec / 60);
@@ -964,79 +1086,91 @@ function formatDuration(sec) {
 
 // src/commands/notes/search.ts
 import "commander";
+var SearchResponseSchema = PageCursorResponseSchema(NoteSchema).passthrough();
+var DEFAULT_PAGE_SIZE2 = 100;
+var MAX_PAGE_SIZE2 = 1e3;
+var HELP_AFTER2 = `
+Examples:
+  tiro notes search "Q3 Planning"
+  tiro notes search "Acme Corp" --since 7d --json
+  tiro notes search "release" --since 2026-04-01 --until 2026-05-01
 
-// src/lib/util/parseDate.ts
-var RELATIVE_RE = /^(\d+)([smhdw])$/i;
-var UNIT_MS = {
-  s: 1e3,
-  m: 6e4,
-  h: 36e5,
-  d: 864e5,
-  w: 6048e5
-};
-function parseDate(input) {
-  const trimmed = input.trim();
-  const rel = trimmed.match(RELATIVE_RE);
-  if (rel) {
-    const num = parseInt(rel[1] ?? "", 10);
-    const unit = (rel[2] ?? "").toLowerCase();
-    const factor = UNIT_MS[unit];
-    if (!factor || !Number.isFinite(num)) {
-      throw invalidDate(input);
-    }
-    return new Date(Date.now() - num * factor).toISOString();
-  }
-  const d = new Date(trimmed);
-  if (Number.isNaN(d.getTime())) throw invalidDate(input);
-  return d.toISOString();
-}
-function invalidDate(input) {
-  return new TiroError(
-    {
-      code: "invalid_date",
-      message: `Invalid date: "${input}". Use ISO-8601 (e.g. 2026-04-01T10:00:00Z) or relative (e.g. 7d, 24h, 30m).`,
-      errorType: "bad_request"
-    },
-    ExitCode.Usage
-  );
-}
+Keyword matching:
+  Full-text against note title + paragraph content via OpenSearch.
+  Case-insensitive. Multi-word keywords are tokenized \u2014 "OKR planning"
+  matches notes containing both terms. The deep search variant (this
+  command) hydrates each result with its primary documents (one-pager,
+  custom) so an MCP/LLM client can read content alongside metadata in
+  one call.
 
-// src/commands/notes/search.ts
-var SearchResponseSchema = PageCursorResponseSchema(NoteSchema);
+Note: placeholder notes (title='Untitled' or sourceType='onboarding') are
+filtered out by default. Pass --include-untitled to surface them.
+`;
 function registerNotesSearch(parent) {
-  parent.command("search [query]").description("Search notes by speaker / date / folder / keyword").option("--speaker <name>", "Filter by speaker name").option("--since <date>", "Notes created after this date (ISO-8601 or 7d, 24h, 30m)").option("--until <date>", "Notes created before this date").option("--folder <id>", "Filter by folder ID").option("--limit <n>", "Max results per page (default 50, max 500)").option("--cursor <token>", "Cursor for the next page").action(async (query, opts, cmd) => {
+  parent.command("search [keyword]").description("Deep keyword search \u2014 returns notes hydrated with their primary documents.").option(
+    "--keyword <text>",
+    'Alternative to positional keyword (e.g. --keyword "Q3 Planning")'
+  ).option("--folder <id>", "Restrict hits to a folder and its descendants").option(
+    "--since <date>",
+    "Inclusive lower bound on createdAt (ISO-8601 or relative: 7d, 24h, 30m)"
+  ).option("--until <date>", "Exclusive upper bound on createdAt").option(
+    "--limit <n>",
+    `Max results per page (default ${DEFAULT_PAGE_SIZE2}, max ${MAX_PAGE_SIZE2})`
+  ).option(
+    "--cursor <token>",
+    "Continue a previous page (reserved \u2014 backend currently always null)"
+  ).option(
+    "--include-untitled",
+    "Include placeholder notes. Default: hidden",
+    false
+  ).addHelpText("after", HELP_AFTER2).action(async (positional, opts, cmd) => {
     const globalOpts = cmd.optsWithGlobals();
+    const keyword = (positional ?? opts.keyword ?? "").trim();
+    if (!keyword) {
+      throw new TiroError(
+        {
+          code: "missing_keyword",
+          message: "search requires a keyword (positional or --keyword).",
+          errorType: "bad_request",
+          suggestion: 'tiro notes search "OKR"'
+        },
+        ExitCode.Usage
+      );
+    }
+    const filter = {};
+    if (opts.folder) filter["folderId"] = opts.folder;
+    if (opts.since) filter["createdAtFrom"] = parseDate(opts.since);
+    if (opts.until) filter["createdAtTo"] = parseDate(opts.until);
+    const pagination = {};
+    const size = clampLimit2(opts.limit);
+    if (size !== void 0) pagination["size"] = size;
+    if (opts.cursor) pagination["cursor"] = opts.cursor;
+    const body = { keyword };
+    if (Object.keys(filter).length > 0) body["filter"] = filter;
+    if (Object.keys(pagination).length > 0) body["pagination"] = pagination;
     const client = createApiClient({
       ...globalOpts.hostname !== void 0 && { hostnameOverride: globalOpts.hostname }
     });
-    const body = {};
-    if (query) body["query"] = query;
-    if (opts.speaker) body["speaker"] = opts.speaker;
-    if (opts.since) body["since"] = parseDate(opts.since);
-    if (opts.until) body["until"] = parseDate(opts.until);
-    if (opts.folder) body["folderId"] = opts.folder;
-    const limit = clampLimit2(opts.limit);
-    if (limit !== void 0) body["size"] = limit;
-    if (opts.cursor) body["cursor"] = opts.cursor;
     const res = await client.postJson(
       "/v1/external/notes/search",
       SearchResponseSchema,
       body
     );
+    const visible = opts.includeUntitled === true ? res.content : res.content.filter(isVisibleNote);
     const mode = resolveOutputMode(globalOpts);
     if (mode === "json") {
-      for (const note of res.content) printNdjson(note);
+      for (const note of visible) printNdjson(note);
       if (res.nextCursor) printNdjson({ _cursor: res.nextCursor });
     } else {
-      printPretty2(res.content, res.nextCursor, globalOpts);
+      printPretty2(visible, res.nextCursor, globalOpts);
     }
   });
 }
 function clampLimit2(raw) {
   if (!raw) return void 0;
   const n = parseInt(raw, 10);
-  if (!Number.isFinite(n) || n <= 0) return 50;
-  return Math.min(n, 500);
+  if (!Number.isFinite(n) || n <= 0) return DEFAULT_PAGE_SIZE2;
+  return Math.min(n, MAX_PAGE_SIZE2);
 }
 function printPretty2(notes, nextCursor, opts) {
   if (notes.length === 0) {
@@ -1098,6 +1232,98 @@ async function fileExists(p) {
   }
 }
 
+// src/lib/output/transcript.ts
+function buildMcpTranscript(note, paragraphs) {
+  return {
+    noteGuid: note.guid,
+    title: note.title,
+    participants: note.participants?.map((p) => p.name || p.email || "").filter((s) => typeof s === "string" && s.length > 0) ?? [],
+    createdAt: note.createdAt,
+    recordingDurationSeconds: note.recordingDurationSeconds,
+    paragraphs: paragraphsToMcp(paragraphs)
+  };
+}
+function paragraphsToMcp(paragraphs) {
+  return paragraphs.map((p) => ({
+    timeFrom: p.timeFrom ?? null,
+    timeTo: p.timeTo ?? null,
+    segments: paragraphToSegments(p)
+  })).filter((p) => p.segments.length > 0);
+}
+function paragraphToSegments(p) {
+  const ds = p.diarizedSegments;
+  if (ds && ds.length > 0) {
+    return ds.map((s) => ({
+      content: stripHtml(s.content),
+      speaker: {
+        label: s.speaker.label,
+        name: s.speaker.personName ? stripHtml(s.speaker.personName) : null
+      }
+    })).filter((s) => s.content.length > 0);
+  }
+  const plain = stripHtml(p.transcript?.content ?? "");
+  return plain ? [{ content: plain, speaker: null }] : [];
+}
+function renderTranscriptJson(t) {
+  return `${JSON.stringify(t, null, 2)}
+`;
+}
+function renderTranscriptMarkdown(t) {
+  const anchor = anchorTime(t);
+  const lines = [];
+  lines.push(`# ${t.title}`, "");
+  if (t.participants.length > 0) {
+    lines.push(`**Participants**: ${t.participants.join(", ")}`, "");
+  }
+  lines.push("## Transcript", "");
+  for (const p of t.paragraphs) {
+    const ts = elapsed(p.timeFrom, anchor);
+    for (const s of p.segments) {
+      const who = s.speaker?.name ?? s.speaker?.label ?? "Unknown";
+      const tag = ts ? `${who}, ${ts}` : who;
+      lines.push(`**[${tag}]** ${s.content}`);
+    }
+    lines.push("");
+  }
+  return `${lines.join("\n").trimEnd()}
+`;
+}
+function renderTranscriptText(t) {
+  const lines = [];
+  for (const p of t.paragraphs) {
+    for (const s of p.segments) {
+      const who = s.speaker?.name ?? s.speaker?.label ?? "Unknown";
+      lines.push(`[${who}] ${s.content}`);
+    }
+  }
+  return `${lines.join("\n")}
+`;
+}
+function anchorTime(t) {
+  for (const p of t.paragraphs) {
+    if (p.timeFrom) return p.timeFrom;
+  }
+  return null;
+}
+function elapsed(currentIso, anchorIso) {
+  if (!currentIso || !anchorIso) return "";
+  const cur = Date.parse(currentIso);
+  const anc = Date.parse(anchorIso);
+  if (!Number.isFinite(cur) || !Number.isFinite(anc)) return "";
+  const seconds = Math.max(0, Math.floor((cur - anc) / 1e3));
+  const h = Math.floor(seconds / 3600);
+  const m = Math.floor(seconds % 3600 / 60);
+  const s = seconds % 60;
+  if (h > 0) return `${pad(h)}:${pad(m)}:${pad(s)}`;
+  return `${pad(m)}:${pad(s)}`;
+}
+function pad(n) {
+  return n.toString().padStart(2, "0");
+}
+function stripHtml(s) {
+  return s.replace(/<[^>]*>/g, "").replace(/&nbsp;/g, " ").replace(/&amp;/g, "&").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&#39;/g, "'").trim();
+}
+
 // src/lib/output/format.ts
 function formatNote(note, format, opts = {}) {
   switch (format) {
@@ -1134,20 +1360,19 @@ function formatMarkdown(note, opts) {
     parts.push("");
   }
   if (opts.includeTranscript && opts.paragraphs && opts.paragraphs.length > 0) {
-    parts.push("## Transcript", "");
-    for (const p of opts.paragraphs) {
-      const speaker = p.speaker?.name ?? "Unknown";
-      const ts = formatTimestamp(p.startMs ?? null);
-      parts.push(`**[${speaker}${ts ? `, ${ts}` : ""}]** ${p.text}`);
-      parts.push("");
-    }
+    const mcp = buildMcpTranscript(note, opts.paragraphs);
+    const transcriptBody = renderTranscriptMarkdown(mcp);
+    const startsWithHeader = transcriptBody.startsWith(`# ${note.title}`);
+    const trimmed = startsWithHeader ? transcriptBody.slice(transcriptBody.indexOf("\n") + 1) : transcriptBody;
+    parts.push(trimmed.replace(/^\s*\n+/, ""));
   }
-  return parts.join("\n");
+  return `${parts.join("\n").trimEnd()}
+`;
 }
 function formatJson(note, opts) {
   const out = { ...note };
   if (opts.includeTranscript && opts.paragraphs) {
-    out["transcript"] = { paragraphs: opts.paragraphs };
+    out["transcript"] = { paragraphs: paragraphsToMcp(opts.paragraphs) };
   }
   return `${JSON.stringify(out, null, 2)}
 `;
@@ -1158,21 +1383,8 @@ function formatText(note, opts) {
 ${note.webUrl}
 `;
   }
-  return opts.paragraphs.map((p) => `[${p.speaker?.name ?? "Unknown"}] ${p.text}`).join("\n");
-}
-function formatTimestamp(ms) {
-  if (ms === null || ms === void 0 || !Number.isFinite(ms)) return "";
-  const totalSec = Math.floor(ms / 1e3);
-  const h = Math.floor(totalSec / 3600);
-  const m = Math.floor(totalSec % 3600 / 60);
-  const s = totalSec % 60;
-  if (h > 0) {
-    return `${pad(h)}:${pad(m)}:${pad(s)}`;
-  }
-  return `${pad(m)}:${pad(s)}`;
-}
-function pad(n) {
-  return n.toString().padStart(2, "0");
+  const mcp = buildMcpTranscript(note, opts.paragraphs);
+  return renderTranscriptText(mcp);
 }
 function escapeYaml(s) {
   if (/[:#\n"']/.test(s)) {
@@ -1182,20 +1394,35 @@ function escapeYaml(s) {
 }
 
 // src/commands/notes/get.ts
+var ALLOWED_INCLUDES = /* @__PURE__ */ new Set(["transcript"]);
 var ParagraphsListSchema = SimpleListResponseSchema(ParagraphSchema);
 var ParagraphsCursorSchema = PageCursorResponseSchema(ParagraphSchema);
 function registerNotesGet(parent) {
-  parent.command("get <guid>").description("Get a single note (stdout or file)").option("--output <path>", "Write to file (stdout becomes metadata only)").option("--format <md|json|txt>", "Output format (default: md for TTY, json for pipe)").option(
+  parent.command("get <guid>").description("Get a single note. Outputs to stdout, or saves to a file with --output.").option("--output <path>", "Write to file (stdout becomes a single metadata line)").option(
+    "--format <md|json|txt>",
+    "Output format (default: md for TTY, json when piped)"
+  ).option(
     "--include <items>",
-    "Comma-separated extras: transcript",
+    "Comma-separated extras (v0.2 supports: transcript)",
     ""
-  ).option("--force", "Overwrite existing file").action(async (guid, opts, cmd) => {
+  ).option("--force", "Overwrite existing file at --output path").addHelpText("after", `
+Examples:
+  tiro notes get <guid>                                    # markdown to stdout
+  tiro notes get <guid> --include transcript               # add speaker-attributed paragraphs
+  tiro notes get <guid> --output ./meeting.md --include transcript
+  tiro notes get <guid> --format json                      # JSON to stdout
+
+Tip for agents: prefer --output <path>. The actual content goes to disk
+and stdout collapses to a single metadata line, keeping your context
+window light.
+`).action(async (guid, opts, cmd) => {
     const globalOpts = cmd.optsWithGlobals();
+    const includes = parseIncludes(opts.include);
+    validateIncludes(includes);
+    const format = pickFormat(opts.format, opts.output);
     const client = createApiClient({
       ...globalOpts.hostname !== void 0 && { hostnameOverride: globalOpts.hostname }
     });
-    const includes = parseIncludes(opts.include);
-    const format = pickFormat(opts.format, opts.output);
     const note = await client.getJson(`/v1/external/notes/${guid}`, NoteSchema);
     let paragraphs;
     if (includes.has("transcript") || format === "txt") {
@@ -1231,7 +1458,7 @@ function registerNotesGet(parent) {
           ok: true,
           data: {
             ...note,
-            ...paragraphs && { transcript: { paragraphs } }
+            ...paragraphs && { transcript: { paragraphs: paragraphsToMcp(paragraphs) } }
           }
         },
         globalOpts
@@ -1239,8 +1466,9 @@ function registerNotesGet(parent) {
     } else if (format === "json") {
       process.stdout.write(content);
     } else {
-      if (process.stdout.isTTY) {
+      if (process.stdout.isTTY && format === "txt") {
         process.stdout.write(`${color(`# ${note.title}`, "bold", globalOpts)}
+
 `);
       }
       process.stdout.write(content);
@@ -1248,13 +1476,13 @@ function registerNotesGet(parent) {
   });
 }
 async function fetchAllParagraphs(client, guid) {
-  const tryCursor = await client.getJson(
+  const first = await client.getJson(
     `/v1/external/notes/${guid}/paragraphs`,
     ParagraphsCursorSchema.or(ParagraphsListSchema)
   );
-  const all = [...tryCursor.content];
-  if ("nextCursor" in tryCursor) {
-    let cursor = tryCursor.nextCursor;
+  const all = [...first.content];
+  if ("nextCursor" in first) {
+    let cursor = first.nextCursor;
     while (cursor) {
       const next = await client.getJson(
         `/v1/external/notes/${guid}/paragraphs`,
@@ -1273,6 +1501,21 @@ function parseIncludes(raw) {
     raw.split(",").map((s) => s.trim().toLowerCase()).filter((s) => s.length > 0)
   );
 }
+function validateIncludes(includes) {
+  for (const inc of includes) {
+    if (!ALLOWED_INCLUDES.has(inc)) {
+      throw new TiroError(
+        {
+          code: "invalid_include",
+          message: `Invalid --include "${inc}". v0.2.0 supports: transcript.`,
+          errorType: "bad_request",
+          suggestion: "Use --include transcript"
+        },
+        ExitCode.Usage
+      );
+    }
+  }
+}
 function pickFormat(format, output) {
   const allowed = ["md", "json", "txt"];
   if (format) {
@@ -1302,18 +1545,30 @@ import "commander";
 var ParagraphsListSchema2 = SimpleListResponseSchema(ParagraphSchema);
 var ParagraphsCursorSchema2 = PageCursorResponseSchema(ParagraphSchema);
 function registerNotesTranscript(parent) {
-  parent.command("transcript <guid>").description("Get raw transcript paragraphs of a note").option("--output <path>", "Write to file (stdout = metadata only)").option("--format <md|json|txt>", "Output format (default: txt for transcript)").option("--force", "Overwrite existing file").action(async (guid, opts, cmd) => {
+  parent.command("transcript <guid>").description(
+    "Get the full transcript of a note as speaker-attributed paragraphs.\nJSON output matches MCP get_note_transcript shape exactly."
+  ).option("--output <path>", "Write to file (stdout = single metadata line)").option(
+    "--format <md|json|txt>",
+    "Output format (default: md if TTY, txt when piped; json mirrors MCP)"
+  ).option("--force", "Overwrite existing file at --output path").addHelpText("after", `
+Examples:
+  tiro notes transcript <guid>                                  # md in TTY, txt in pipe
+  tiro notes transcript <guid> --format md --output ./t.md
+  tiro notes transcript <guid> --format json                    # MCP-shape JSON
+  tiro notes transcript <guid> --format txt --output ./embed.txt
+
+The --format json output is byte-for-byte identical to MCP's
+get_note_transcript so agents can swap surfaces without changing parsers.
+`).action(async (guid, opts, cmd) => {
     const globalOpts = cmd.optsWithGlobals();
+    const format = pickFormat2(opts.format, opts.output, globalOpts);
     const client = createApiClient({
       ...globalOpts.hostname !== void 0 && { hostnameOverride: globalOpts.hostname }
     });
-    const format = pickFormat2(opts.format, opts.output);
     const note = await client.getJson(`/v1/external/notes/${guid}`, NoteSchema);
     const paragraphs = await fetchAllParagraphs2(client, guid);
-    const content = formatNote(note, format, {
-      includeTranscript: true,
-      paragraphs
-    });
+    const mcp = buildMcpTranscript(note, paragraphs);
+    const content = format === "json" ? renderTranscriptJson(mcp) : format === "md" ? renderTranscriptMarkdown(mcp) : renderTranscriptText(mcp);
     if (opts.output) {
       const result = await writeFileAtomic(opts.output, content, {
         ...opts.force === true && { force: true }
@@ -1326,7 +1581,8 @@ function registerNotesTranscript(parent) {
             size: result.size,
             format,
             guid: note.guid,
-            paragraphCount: paragraphs.length
+            paragraphCount: mcp.paragraphs.length,
+            segmentCount: mcp.paragraphs.reduce((sum, p) => sum + p.segments.length, 0)
           }
         },
         globalOpts
@@ -1335,10 +1591,7 @@ function registerNotesTranscript(parent) {
     }
     const mode = resolveOutputMode(globalOpts);
     if (mode === "json" && format !== "json") {
-      printOutput(
-        { ok: true, data: { guid: note.guid, paragraphs } },
-        globalOpts
-      );
+      printOutput({ ok: true, data: mcp }, globalOpts);
     } else {
       process.stdout.write(content);
     }
@@ -1364,7 +1617,7 @@ async function fetchAllParagraphs2(client, guid) {
   }
   return all;
 }
-function pickFormat2(format, output) {
+function pickFormat2(format, output, globalOpts) {
   const allowed = ["md", "json", "txt"];
   if (format) {
     const f = format.toLowerCase();
@@ -1383,9 +1636,12 @@ function pickFormat2(format, output) {
   if (output) {
     if (output.endsWith(".json")) return "json";
     if (output.endsWith(".md")) return "md";
-    return "txt";
+    if (output.endsWith(".txt")) return "txt";
+    return "md";
   }
-  return "txt";
+  if (globalOpts.json) return "json";
+  if (globalOpts.pretty) return "md";
+  return process.stdout.isTTY ? "md" : "txt";
 }
 
 // src/commands/notes/index.ts
@@ -1397,21 +1653,74 @@ function registerNotes(program) {
   registerNotesTranscript(notes);
 }
 
+// src/lib/updateCheck.ts
+import updateNotifier from "update-notifier";
+import { readFile } from "fs/promises";
+import { fileURLToPath } from "url";
+import { dirname as dirname2, resolve as resolve2 } from "path";
+var HERE = dirname2(fileURLToPath(import.meta.url));
+var CANDIDATE_PATHS = [
+  resolve2(HERE, "../../package.json"),
+  resolve2(HERE, "../../../package.json")
+];
+var ONE_DAY_MS = 24 * 60 * 60 * 1e3;
+async function startUpdateCheck() {
+  if (process.env["NO_UPDATE_NOTIFIER"] === "1") return null;
+  if (process.env["CI"]) return null;
+  if (process.stdout.isTTY !== true) return null;
+  const pkg = await loadPkg();
+  if (!pkg) return null;
+  try {
+    const factory = updateNotifier;
+    return factory({
+      pkg,
+      updateCheckInterval: ONE_DAY_MS,
+      shouldNotifyInNpmScript: false
+    });
+  } catch {
+    return null;
+  }
+}
+function emitUpdateBanner(notifier) {
+  if (!notifier) return;
+  if (!notifier.update) return;
+  notifier.notify({
+    isGlobal: true,
+    defer: false,
+    message: "Update available {currentVersion} \u2192 {latestVersion}\nRun npm install -g {packageName} to update\n\nChangelog: https://www.npmjs.com/package/{packageName}?activeTab=versions"
+  });
+}
+async function loadPkg() {
+  for (const path of CANDIDATE_PATHS) {
+    try {
+      const raw = await readFile(path, "utf8");
+      const parsed = JSON.parse(raw);
+      if (typeof parsed.name === "string" && typeof parsed.version === "string" && parsed.name.length > 0 && parsed.version.length > 0) {
+        return { name: parsed.name, version: parsed.version };
+      }
+    } catch {
+    }
+  }
+  return null;
+}
+
 // src/bin/tiro.ts
 var EXAMPLES = `
 EXAMPLES
   $ tiro auth login
-  $ tiro notes search --speaker "\uAE40\uCCA0\uC218" --since 7d --json
+  $ tiro notes list --since 7d
+  $ tiro notes search "Q3 Planning" --since 30d --json
   $ tiro notes get <guid> --output ./meeting.md --include transcript
-  $ tiro notes transcript <guid> --format txt
+  $ tiro notes transcript <guid> --format md --output ./transcript.md
 
 ENVIRONMENT
-  TIRO_TOKEN       Bearer token (overrides keychain)
-  TIRO_HOSTNAME    API base URL (default: https://api.tiro.ooo)
-  NO_COLOR         Disable colors
+  TIRO_TOKEN             Bearer token (overrides keychain \u2014 for CI / agents)
+  TIRO_HOSTNAME          API base URL (default: https://api.tiro.ooo)
+  NO_COLOR               Disable colors (https://no-color.org)
+  NO_UPDATE_NOTIFIER     Set to "1" to disable the update banner
 
 DOCS
-  https://api.tiro.ooo/cli
+  https://api-docs.tiro.ooo/cli/overview
 `;
 function buildProgram() {
   const program = new Command10();
@@ -1423,8 +1732,10 @@ function buildProgram() {
 }
 async function main() {
   const program = buildProgram();
+  const notifier = await startUpdateCheck();
   try {
     await program.parseAsync(process.argv);
+    emitUpdateBanner(notifier);
   } catch (err) {
     handleError(err, program);
   }