@readwise/cli 0.3.1 → 0.5.1

package/src/tui/app.ts

@@ -1,9 +1,10 @@
+import { exec } from "node:child_process";
 import type { ToolDef, SchemaProperty } from "../config.js";
-import { resolveProperty, resolveRef } from "../commands.js";
+import { resolveProperty } from "../commands.js";
 import { callTool } from "../mcp.js";
 import { ensureValidToken } from "../auth.js";
 import { LOGO } from "./logo.js";
-import { style, paint, screenSize, fitWidth, ansiSlice, stripAnsi, parseKey, type KeyEvent } from "./term.js";
+import { style, paint, screenSize, fitWidth, ansiSlice, parseKey, type KeyEvent } from "./term.js";
 import { VERSION } from "../version.js";
 
 // --- Types ---
@@ -29,6 +30,18 @@ function isArrayOfObjects(prop: SchemaProperty): boolean {
   return prop.type === "array" && !!prop.items?.properties;
 }
 
+type CardKind = "document" | "highlight";
+
+interface CardItem {
+  kind: CardKind;
+  title: string;
+  summary: string;
+  note: string;       // highlight note (only for highlights)
+  meta: string;       // "Source · Author · 12 min"
+  url: string;        // for opening on enter
+  raw: Record<string, unknown>;  // full object for fallback
+}
+
 interface AppState {
   view: View;
   tools: ToolDef[];
@@ -51,10 +64,12 @@ interface AppState {
   formEditFieldIdx: number;
   formEditing: boolean;
   formInputBuf: string;
+  formInputCursorPos: number;
   formEnumCursor: number;
   formEnumSelected: Set<number>;
   formValues: Record<string, string>;
   formShowRequired: boolean;
+  formShowOptional: boolean;
   formStack: FormStackEntry[];
   // Date picker
   dateParts: number[];       // [year, month, day] or [year, month, day, hour, minute]
@@ -64,6 +79,9 @@ interface AppState {
   error: string;
   resultScroll: number;
   resultScrollX: number;
+  resultCards: CardItem[];    // parsed card items for card view
+  resultCursor: number;       // selected card index
+  resultCardScroll: number;   // scroll offset for cards
   // Spinner
   spinnerFrame: number;
 }
@@ -184,6 +202,42 @@ function defaultFormCursor(fields: FormField[], filtered: number[], values: Reco
   return firstBlank >= 0 ? firstBlank : executeIndex(filtered);
 }
 
+type FieldKind = "arrayObj" | "date" | "arrayEnum" | "enum" | "bool" | "arrayText" | "text";
+
+function classifyField(prop: SchemaProperty): FieldKind {
+  if (isArrayOfObjects(prop)) return "arrayObj";
+  if (dateFieldFormat(prop)) return "date";
+  const eVals = prop.enum || prop.items?.enum;
+  if (prop.type === "boolean") return "bool";
+  if (eVals && prop.type === "array") return "arrayEnum";
+  if (eVals) return "enum";
+  if (prop.type === "array") return "arrayText";
+  return "text";
+}
+
+function fieldTypeBadge(prop: SchemaProperty): string {
+  const badges: Record<FieldKind, string> = {
+    arrayObj: "form", date: "date", bool: "yes/no", arrayEnum: "multi",
+    enum: "select", arrayText: "list", text: "text",
+  };
+  const badge = badges[classifyField(prop)];
+  if (badge !== "text") return badge;
+  if (prop.type === "integer" || prop.type === "number") return "number";
+  return "text";
+}
+
+function footerForFieldKind(kind: FieldKind): string {
+  switch (kind) {
+    case "arrayObj": return "\u2191\u2193 navigate \u00B7 enter add/edit \u00B7 backspace delete \u00B7 esc back";
+    case "date": return "\u2190\u2192 part \u00B7 \u2191\u2193 adjust \u00B7 t today \u00B7 enter confirm \u00B7 esc cancel";
+    case "arrayEnum": return "space toggle \u00B7 enter confirm \u00B7 esc cancel";
+    case "arrayText": return "\u2191\u2193 navigate \u00B7 enter add/edit \u00B7 backspace delete \u00B7 esc confirm";
+    case "enum":
+    case "bool": return "\u2191\u2193 navigate \u00B7 enter confirm \u00B7 esc cancel";
+    case "text": return "enter confirm \u00B7 esc cancel";
+  }
+}
+
 function formFieldValueDisplay(value: string, maxWidth: number): string {
   if (!value) return style.dim("–");
   // JSON array display (for array-of-objects)
@@ -253,8 +307,9 @@ function popFormStack(state: AppState): AppState {
     formFilteredIndices: parentFiltered,
     formListCursor: defaultFormCursor(entry.parentFields, parentFiltered, newParentValues),
     formScrollTop: 0,
-    formShowRequired: false,
+    formShowRequired: false, formShowOptional: false,
     formInputBuf: "",
+    formInputCursorPos: 0,
   };
 }
 
@@ -296,6 +351,219 @@ function wrapText(text: string, width: number): string[] {
   return lines.length > 0 ? lines : [""];
 }
 
+// --- Card parsing helpers ---
+
+function extractCards(data: unknown): CardItem[] | null {
+  let items: unknown[];
+  if (Array.isArray(data)) {
+    items = data;
+  } else if (typeof data === "object" && data !== null) {
+    // Look for a "results" array or similar
+    const obj = data as Record<string, unknown>;
+    const arrayKey = Object.keys(obj).find((k) => Array.isArray(obj[k]) && (obj[k] as unknown[]).length > 0);
+    if (arrayKey) {
+      items = obj[arrayKey] as unknown[];
+    } else {
+      return null;
+    }
+  } else {
+    return null;
+  }
+
+  if (items.length === 0) return null;
+  // Only works for arrays of objects
+  if (typeof items[0] !== "object" || items[0] === null || Array.isArray(items[0])) return null;
+
+  const cards = items.map((item) => {
+    const obj = item as Record<string, unknown>;
+    const kind = isHighlightObj(obj) ? "highlight" : "document";
+    if (kind === "highlight") {
+      const attrs = (typeof obj.attributes === "object" && obj.attributes !== null)
+        ? obj.attributes as Record<string, unknown> : null;
+      return {
+        kind,
+        title: str(attrs?.document_title || obj.title || obj.readable_title || ""),
+        summary: str(attrs?.highlight_plaintext || obj.text || obj.summary || obj.content || ""),
+        note: str(attrs?.highlight_note || obj.note || obj.notes || ""),
+        meta: extractHighlightMeta(obj),
+        url: obj.id ? `https://readwise.io/open/${obj.id}` : extractCardUrl(obj),
+        raw: obj,
+      };
+    }
+    return {
+      kind,
+      title: extractDocTitle(obj),
+      summary: extractDocSummary(obj),
+      note: "",
+      meta: extractDocMeta(obj),
+      url: extractCardUrl(obj),
+      raw: obj,
+    };
+  }) as CardItem[];
+
+  // Skip card view if most items have no meaningful content (e.g. just URLs)
+  const hasContent = cards.filter((c) => c.summary || c.note || (c.kind === "document" && c.title !== "Untitled" && !c.raw.url?.toString().includes(c.title)));
+  if (hasContent.length < cards.length / 2) return null;
+
+  return cards;
+}
+
+function str(val: unknown): string {
+  if (val === null || val === undefined) return "";
+  return String(val);
+}
+
+function isHighlightObj(obj: Record<string, unknown>): boolean {
+  // Reader docs with category "highlight"
+  if (obj.category === "highlight") return true;
+  // Readwise search highlights: nested attributes with highlight_plaintext
+  const attrs = obj.attributes;
+  if (typeof attrs === "object" && attrs !== null && "highlight_plaintext" in (attrs as Record<string, unknown>)) return true;
+  // Readwise highlights: have text + highlight-specific fields
+  if (typeof obj.text === "string" &&
+    ("highlighted_at" in obj || "color" in obj || "book_id" in obj || "location_type" in obj)) {
+    return true;
+  }
+  // Has text + note fields (common highlight shape even without highlighted_at)
+  if (typeof obj.text === "string" && "note" in obj) return true;
+  return false;
+}
+
+// --- Document card helpers ---
+
+function extractDocTitle(obj: Record<string, unknown>): string {
+  for (const key of ["title", "readable_title", "name"]) {
+    const val = obj[key];
+    if (val && typeof val === "string" && !String(val).startsWith("http")) return val as string;
+  }
+  // Last resort: show domain from URL
+  const url = str(obj.url || obj.source_url);
+  if (url) {
+    try { return new URL(url).hostname.replace(/^www\./, ""); } catch { /* */ }
+  }
+  return "Untitled";
+}
+
+function extractDocSummary(obj: Record<string, unknown>): string {
+  for (const key of ["summary", "description", "note", "notes", "content"]) {
+    const val = obj[key];
+    if (val && typeof val === "string") return val;
+  }
+  return "";
+}
+
+function extractDocMeta(obj: Record<string, unknown>): string {
+  const parts: string[] = [];
+
+  const siteName = str(obj.site_name);
+  if (siteName) parts.push(siteName);
+
+  const author = str(obj.author);
+  if (author && author !== siteName) parts.push(author);
+
+  const category = str(obj.category);
+  if (category) parts.push(category);
+
+  const wordCount = Number(obj.word_count);
+  if (wordCount > 0) {
+    const mins = Math.ceil(wordCount / 250);
+    parts.push(`${mins} min`);
+  }
+
+  const progress = Number(obj.reading_progress);
+  if (progress > 0 && progress < 1) {
+    parts.push(`${Math.round(progress * 100)}% read`);
+  } else if (progress >= 1) {
+    parts.push("finished");
+  }
+
+  const date = str(obj.created_at || obj.saved_at || obj.published_date);
+  if (date) {
+    const d = new Date(date);
+    if (!isNaN(d.getTime())) {
+      parts.push(d.toLocaleDateString("en-US", { month: "short", day: "numeric", year: "numeric" }));
+    }
+  }
+
+  return parts.join(" · ");
+}
+
+// --- Highlight card helpers ---
+
+function extractHighlightMeta(obj: Record<string, unknown>): string {
+  const attrs = (typeof obj.attributes === "object" && obj.attributes !== null)
+    ? obj.attributes as Record<string, unknown> : null;
+  const parts: string[] = [];
+
+  // Source book/article author
+  const author = str(attrs?.document_author || obj.author || obj.book_author);
+  if (author && !author.startsWith("http")) parts.push(author);
+
+  // Category
+  const category = str(attrs?.document_category || obj.category);
+  if (category) parts.push(category);
+
+  const color = str(obj.color);
+  if (color) parts.push(color);
+
+  // Tags (from attributes or top-level)
+  const tags = attrs?.highlight_tags || obj.tags;
+  if (Array.isArray(tags) && tags.length > 0) {
+    const tagNames = tags.map((t: unknown) =>
+      typeof t === "object" && t !== null ? str((t as Record<string, unknown>).name) : str(t)
+    ).filter(Boolean);
+    if (tagNames.length > 0) parts.push(tagNames.join(", "));
+  }
+
+  const date = str(obj.highlighted_at || obj.created_at);
+  if (date) {
+    const d = new Date(date);
+    if (!isNaN(d.getTime())) {
+      parts.push(d.toLocaleDateString("en-US", { month: "short", day: "numeric", year: "numeric" }));
+    }
+  }
+
+  return parts.join(" · ");
+}
+
+function extractCardUrl(obj: Record<string, unknown>): string {
+  for (const key of ["url", "source_url", "reader_url", "readwise_url"]) {
+    if (obj[key] && typeof obj[key] === "string") return obj[key] as string;
+  }
+  return "";
+}
+
+// --- Word boundary helpers ---
+
+function prevWordBoundary(buf: string, pos: number): number {
+  if (pos <= 0) return 0;
+  let i = pos - 1;
+  // Skip whitespace
+  while (i > 0 && /\s/.test(buf[i]!)) i--;
+  // Skip word chars or non-word non-space chars
+  if (i >= 0 && /\w/.test(buf[i]!)) {
+    while (i > 0 && /\w/.test(buf[i - 1]!)) i--;
+  } else {
+    while (i > 0 && !/\w/.test(buf[i - 1]!) && !/\s/.test(buf[i - 1]!)) i--;
+  }
+  return i;
+}
+
+function nextWordBoundary(buf: string, pos: number): number {
+  const len = buf.length;
+  if (pos >= len) return len;
+  let i = pos;
+  // Skip current word chars or non-word non-space chars
+  if (/\w/.test(buf[i]!)) {
+    while (i < len && /\w/.test(buf[i]!)) i++;
+  } else if (!/\s/.test(buf[i]!)) {
+    while (i < len && !/\w/.test(buf[i]!) && !/\s/.test(buf[i]!)) i++;
+  }
+  // Skip whitespace
+  while (i < len && /\s/.test(buf[i]!)) i++;
+  return i;
+}
+
 // --- Date helpers ---
 
 type DateFormat = "date" | "date-time";
@@ -449,7 +717,7 @@ function renderCommandList(state: AppState): string[] {
     if (i === Math.floor(LOGO.length / 2) - 1) {
       content.push(` ${logoLine}  ${style.boldYellow("Readwise")} ${style.dim("v" + VERSION)}`);
     } else if (i === Math.floor(LOGO.length / 2)) {
-      content.push(` ${logoLine}  ${style.dim("Command-line interface")}`);
+      content.push(` ${logoLine}  ${style.dim("Built for AI agents · This TUI is just for fun/learning")}`);
     } else {
       content.push(` ${logoLine}`);
     }
@@ -510,8 +778,8 @@ function renderCommandList(state: AppState): string[] {
   }
 
   const footer = state.quitConfirm
-    ? style.yellow("Press q or esc again to quit")
-    : style.dim("type to search  ↑↓ navigate  enter select  esc clear/quit");
+    ? style.yellow("Press again to quit")
+    : style.dim("type to search · ↑↓ navigate · enter select · esc/ctrl+c quit");
 
   return renderLayout({
     breadcrumb: style.boldYellow("Readwise"),
@@ -525,16 +793,223 @@ function renderForm(state: AppState): string[] {
   const tool = state.selectedTool!;
   const fields = state.fields;
   const toolTitle = humanLabel(tool.name, toolPrefix(tool));
-  // Build title: tool name + any stack breadcrumb
-  const stackParts = state.formStack.map((e) => e.parentFieldName);
-  const title = stackParts.length > 0
-    ? toolTitle + " › " + stackParts.join(" › ")
-    : toolTitle;
 
-  if (state.formEditing && state.formEditFieldIdx >= 0) {
-    return renderFormEditMode(state, title, fields, contentHeight, innerWidth);
+  // Sub-forms (nested array-of-objects) keep existing form UI
+  if (state.formStack.length > 0) {
+    const stackParts = state.formStack.map((e) => e.parentFieldName);
+    const title = toolTitle + " › " + stackParts.join(" › ");
+    if (state.formEditing && state.formEditFieldIdx >= 0) {
+      return renderFormEditMode(state, title, fields, contentHeight, innerWidth);
+    }
+    return renderFormPaletteMode(state, title, fields, contentHeight, innerWidth);
   }
-  return renderFormPaletteMode(state, title, fields, contentHeight, innerWidth);
+
+  // Top-level: command builder
+  return renderCommandBuilder(state, toolTitle, fields, contentHeight, innerWidth);
+}
+
+function renderCommandBuilder(
+  state: AppState, title: string, fields: FormField[],
+  contentHeight: number, innerWidth: number,
+): string[] {
+  const tool = state.selectedTool!;
+  const cmdName = tool.name.replace(/_/g, "-");
+  const content: string[] = [];
+  const editField = state.formEditing && state.formEditFieldIdx >= 0
+    ? fields[state.formEditFieldIdx]!
+    : null;
+
+  // Header
+  content.push("");
+  content.push("  " + style.bold(title));
+  if (tool.description) {
+    const wrapped = wrapText(tool.description, innerWidth - 4);
+    for (const line of wrapped) {
+      content.push("  " + style.dim(line));
+    }
+  }
+  content.push("");
+
+  // Classify editing field type once for both content and footer
+  const editKind = editField ? classifyField(editField.prop) : null;
+  const isTextLikeEdit = editKind === "text";
+
+  // Build command lines
+  const argLines: string[] = [];
+  for (const field of fields) {
+    const flagName = field.name.replace(/_/g, "-");
+    if (field === editField) {
+      if (isTextLikeEdit) {
+        // Inline cursor for text fields
+        const buf = state.formInputBuf;
+        const before = buf.slice(0, state.formInputCursorPos);
+        const cursorChar = state.formInputCursorPos < buf.length ? buf[state.formInputCursorPos]! : " ";
+        const after = state.formInputCursorPos < buf.length ? buf.slice(state.formInputCursorPos + 1) : "";
+        argLines.push("    --" + flagName + "=" + style.cyan(before) + style.inverse(cursorChar) + style.cyan(after));
+      } else if (isArrayOfObjects(field.prop)) {
+        // Array-of-objects: show item count
+        const existing = state.formValues[field.name] || "[]";
+        let items: unknown[] = [];
+        try { items = JSON.parse(existing); } catch { /* */ }
+        const label = items.length > 0 ? `[${items.length} item${items.length > 1 ? "s" : ""}]` : "[...]";
+        argLines.push("    --" + flagName + "=" + style.yellow(label));
+      } else {
+        // Non-text editors (enum, bool, date): show pending
+        argLines.push("    --" + flagName + "=" + style.inverse(" "));
+      }
+    } else {
+      const val = state.formValues[field.name];
+      if (val) {
+        const needsQuotes = val.includes(" ") || val.includes(",");
+        const displayVal = needsQuotes ? '"' + val + '"' : val;
+        argLines.push("    --" + flagName + "=" + style.cyan(displayVal));
+      }
+    }
+  }
+
+  // Render command with line continuations
+  const cmdPrefix = "  " + style.dim("$") + " " + style.dim("readwise") + " " + cmdName;
+  if (argLines.length === 0) {
+    content.push(cmdPrefix);
+  } else {
+    content.push(cmdPrefix + " \\");
+    for (let i = 0; i < argLines.length; i++) {
+      const isLast = i === argLines.length - 1;
+      content.push(argLines[i]! + (isLast ? "" : " \\"));
+    }
+  }
+
+  content.push("");
+
+  // Context area: field description, editor, or ready state
+  if (editField) {
+    // Field description
+    if (editField.prop.description) {
+      content.push("  " + style.dim(editField.prop.description));
+    }
+    if (editField.prop.examples?.length) {
+      const exStr = editField.prop.examples.map((e: unknown) => typeof e === "string" ? e : JSON.stringify(e)).join(", ");
+      content.push("  " + style.dim("e.g. ") + style.cyan(truncateVisible(exStr, innerWidth - 10)));
+    }
+    if (editField.prop.default != null) {
+      content.push("  " + style.dim("default: " + editField.prop.default));
+    }
+
+    const eVals = editField.prop.enum || editField.prop.items?.enum;
+
+    if (editKind === "bool") {
+      content.push("");
+      const choices = ["true", "false"];
+      for (let ci = 0; ci < choices.length; ci++) {
+        const sel = ci === state.formEnumCursor;
+        content.push(sel ? "  " + style.cyan(style.bold("\u203A " + choices[ci]!)) : "    " + choices[ci]!);
+      }
+    } else if (editKind === "enum" && eVals) {
+      content.push("");
+      for (let ci = 0; ci < eVals.length; ci++) {
+        const sel = ci === state.formEnumCursor;
+        content.push(sel ? "  " + style.cyan(style.bold("\u203A " + eVals[ci]!)) : "    " + eVals[ci]!);
+      }
+    } else if (editKind === "arrayEnum" && eVals) {
+      content.push("");
+      for (let ci = 0; ci < eVals.length; ci++) {
+        const sel = ci === state.formEnumCursor;
+        const checked = state.formEnumSelected.has(ci);
+        const check = checked ? style.cyan("[x]") : style.dim("[ ]");
+        content.push((sel ? "  \u203A " : "    ") + check + " " + eVals[ci]!);
+      }
+    } else if (editKind === "date") {
+      const dateFmt = dateFieldFormat(editField.prop)!;
+      content.push("");
+      content.push("  " + renderDateParts(state.dateParts, state.datePartCursor, dateFmt));
+    } else if (editKind === "arrayText") {
+      const existing = state.formValues[editField.name] || "";
+      const items = existing ? existing.split(",").map((s: string) => s.trim()).filter(Boolean) : [];
+      content.push("");
+      for (let i = 0; i < items.length; i++) {
+        const isCursor = i === state.formEnumCursor;
+        content.push((isCursor ? "  \u276F " : "    ") + style.cyan(items[i]!));
+      }
+      const onInput = state.formEnumCursor === items.length;
+      content.push((onInput ? "  \u276F " : "    ") + style.cyan(state.formInputBuf) + (onInput ? style.inverse(" ") : ""));
+    } else if (editKind === "arrayObj") {
+      const existing = state.formValues[editField.name] || "[]";
+      let items: unknown[] = [];
+      try { items = JSON.parse(existing); } catch { /* */ }
+      content.push("");
+      for (let i = 0; i < items.length; i++) {
+        const item = items[i] as Record<string, unknown>;
+        const summary = Object.entries(item)
+          .filter(([, v]) => v != null && v !== "")
+          .map(([k, v]) => `${k}: ${typeof v === "string" ? v : JSON.stringify(v)}`)
+          .join(", ");
+        const isCursor = i === state.formEnumCursor;
+        content.push((isCursor ? "  \u276F " : "    ") + truncateVisible(summary || "(empty)", innerWidth - 6));
+      }
+      if (items.length > 0) content.push("");
+      const addCursor = state.formEnumCursor === items.length;
+      content.push(addCursor
+        ? "  " + style.inverse(style.green(" + Add new item "))
+        : "  " + style.dim("+") + " Add new item");
+    } else if (isTextLikeEdit) {
+      // Text field: cursor is already inline in the command string
+      // Just show a hint if empty
+      if (!state.formInputBuf) {
+        content.push("");
+        content.push("  " + style.dim("Type a value and press enter"));
+      }
+    }
+  } else {
+    // Ready state / optional picker
+    const missing = missingRequiredFields(fields, state.formValues);
+    if (missing.length > 0) {
+      content.push("  " + style.red("Missing: " + missing.map((f) => f.name).join(", ")));
+    } else {
+      content.push("  " + style.dim("Press enter to run"));
+    }
+
+    // Always show optional params
+    const optionalFields = fields
+      .map((f, i) => ({ field: f, idx: i }))
+      .filter(({ field }) => !field.required);
+    if (optionalFields.length > 0) {
+      content.push("");
+      content.push("  " + style.dim("Optional parameters (tab to add)"));
+      content.push("");
+      const maxFlagWidth = Math.max(...optionalFields.map(({ field }) => field.name.length), 0) + 2;
+      for (let i = 0; i < optionalFields.length; i++) {
+        const { field } = optionalFields[i]!;
+        const flagName = field.name.replace(/_/g, "-");
+        const hasValue = !!state.formValues[field.name]?.trim();
+        const sel = state.formShowOptional && i === state.formListCursor;
+        const prefix = sel ? " \u276F " : "   ";
+        const paddedName = flagName.padEnd(maxFlagWidth);
+        const desc = field.prop.description
+          ? style.dim(truncateVisible(field.prop.description, innerWidth - maxFlagWidth - 8))
+          : "";
+        if (sel) {
+          content.push(style.boldYellow(prefix + paddedName) + "  " + desc);
+        } else if (hasValue) {
+          content.push(prefix + style.green(paddedName) + "  " + desc);
+        } else {
+          content.push(prefix + style.dim(paddedName) + "  " + desc);
+        }
+      }
+    }
+  }
+
+  // Footer
+  const footer = editKind
+    ? style.dim(footerForFieldKind(editKind))
+    : state.formShowOptional
+    ? style.dim("\u2191\u2193 select \u00B7 enter add \u00B7 esc done")
+    : style.dim("enter run \u00B7 tab add option \u00B7 esc back");
+
+  return renderLayout({
+    breadcrumb: style.boldYellow("Readwise") + style.dim(" \u203A ") + style.bold(title),
+    content,
+    footer,
+  });
 }
 
 function renderFormPaletteMode(
@@ -558,28 +1033,51 @@ function renderFormPaletteMode(
       content.push("  " + style.dim(line));
     }
   }
+
+  // Progress indicator for required fields
+  const requiredFields = fields.filter((f) => f.required);
+  if (requiredFields.length > 0) {
+    const filledRequired = requiredFields.filter((f) => {
+      const val = state.formValues[f.name]?.trim();
+      if (!val) return false;
+      if (isArrayOfObjects(f.prop)) {
+        try { return JSON.parse(val).length > 0; } catch { return false; }
+      }
+      return true;
+    });
+    const allFilled = filledRequired.length === requiredFields.length;
+    const progressText = `${filledRequired.length} of ${requiredFields.length} required`;
+    content.push("  " + (allFilled ? style.green("✓ " + progressText) : style.dim(progressText)));
+  }
+
   content.push("");
 
-  // Search input
+  // Search input (only show when there's a search query or many fields)
   const queryText = state.formSearchQuery;
-  const before = queryText.slice(0, state.formSearchCursorPos);
-  const cursorChar = state.formSearchCursorPos < queryText.length
-    ? queryText[state.formSearchCursorPos]!
-    : " ";
-  const after = state.formSearchCursorPos < queryText.length
-    ? queryText.slice(state.formSearchCursorPos + 1)
-    : "";
-  content.push(" " + style.yellow("❯") + " " + before + style.inverse(cursorChar) + after);
-  content.push("");
+  if (queryText || fields.length > 6) {
+    const before = queryText.slice(0, state.formSearchCursorPos);
+    const cursorChar = state.formSearchCursorPos < queryText.length
+      ? queryText[state.formSearchCursorPos]!
+      : " ";
+    const after = state.formSearchCursorPos < queryText.length
+      ? queryText.slice(state.formSearchCursorPos + 1)
+      : "";
+    content.push("  " + style.dim("/") + " " + before + style.inverse(cursorChar) + after);
+    content.push("");
+  } else {
+    content.push("");
+  }
 
-  // Compute maxLabelWidth
+  // Compute maxLabelWidth (include " *" for required fields)
   const maxLabelWidth = Math.max(
     ...fields.map((f) => f.name.length + (f.required ? 2 : 0)),
     6,
   ) + 1;
 
-  // Value display width budget: innerWidth - prefix(3) - label - gap(2)
-  const valueAvail = Math.max(0, innerWidth - 3 - maxLabelWidth - 2);
+  // Badge width: " text" = ~7 chars max
+  const badgeWidth = 8;
+  // Value display width budget: innerWidth - cursor(3) - label - gap(2) - badge
+  const valueAvail = Math.max(0, innerWidth - 3 - maxLabelWidth - 2 - badgeWidth);
 
   const headerUsed = content.length;
   // Reserve space for: blank + Execute + blank + description (up to 4 lines)
@@ -588,29 +1086,69 @@ function renderFormPaletteMode(
   const filtered = state.formFilteredIndices;
   const hasOnlyExecute = filtered.length === 1 && filtered[0] === -1;
 
+  // Split fields into required and optional
+  const requiredIdxs = filtered.filter((idx) => idx >= 0 && idx < fields.length && fields[idx]!.required);
+  const optionalIdxs = filtered.filter((idx) => idx >= 0 && idx < fields.length && !fields[idx]!.required);
+  const hasOptional = optionalIdxs.length > 0;
+  const showingOptional = state.formShowOptional || state.formSearchQuery;
+  // Count optional fields that have been filled
+  const filledOptionalCount = optionalIdxs.filter((idx) => !!state.formValues[fields[idx]!.name]?.trim()).length;
+
+  const renderField = (fieldIdx: number) => {
+    const field = fields[fieldIdx]!;
+    const val = state.formValues[field.name] || "";
+    const isFilled = !!val.trim();
+    const listPos = filtered.indexOf(fieldIdx);
+    const selected = listPos === state.formListCursor;
+
+    // Value display
+    const valStr = formFieldValueDisplay(val, valueAvail);
+
+    // Type badge
+    const badge = style.dim(fieldTypeBadge(field.prop));
+
+    const cursor = selected ? " ❯ " : "   ";
+    if (selected) {
+      const label = field.name + (field.required ? " *" : "");
+      content.push(style.boldYellow(cursor) + style.boldYellow(label.padEnd(maxLabelWidth)) + "  " + valStr + "  " + badge);
+    } else if (isFilled) {
+      const label = field.name + (field.required ? " *" : "");
+      content.push(cursor + style.green(label.padEnd(maxLabelWidth)) + "  " + valStr + "  " + badge);
+    } else {
+      // Unfilled: show required * in red
+      const namePart = field.name;
+      const starPart = field.required ? " *" : "";
+      const plainLabel = namePart + starPart;
+      const padAmount = Math.max(0, maxLabelWidth - plainLabel.length);
+      const displayLabel = field.required ? namePart + style.red(" *") + " ".repeat(padAmount) : plainLabel.padEnd(maxLabelWidth);
+      content.push(cursor + displayLabel + "  " + style.dim("–") + "  " + badge);
+    }
+  };
+
   if (hasOnlyExecute && state.formSearchQuery) {
     content.push("   " + style.dim("No matching parameters"));
     content.push("");
   } else {
-    // Scrolling: items before the Execute sentinel
-    const paramItems = filtered.filter((idx) => idx !== -1);
-    const visStart = state.formScrollTop;
-    const visEnd = Math.min(paramItems.length, visStart + listHeight);
-    const visible = paramItems.slice(visStart, visEnd);
-
-    for (const fieldIdx of visible) {
-      const field = fields[fieldIdx]!;
-      const nameLabel = field.name + (field.required ? " *" : "");
-      const paddedName = nameLabel.padEnd(maxLabelWidth);
-      const val = state.formValues[field.name] || "";
-      const valStr = formFieldValueDisplay(val, valueAvail);
-      const listPos = filtered.indexOf(fieldIdx);
-      const selected = listPos === state.formListCursor;
-      const prefix = selected ? " ❯ " : "   ";
-      if (selected) {
-        content.push(style.boldYellow(prefix + paddedName) + "  " + valStr);
+    // Required fields (always visible)
+    for (const fieldIdx of requiredIdxs) {
+      renderField(fieldIdx);
+    }
+
+    // Optional fields separator
+    if (hasOptional) {
+      if (showingOptional) {
+        if (requiredIdxs.length > 0) content.push("");
+        content.push("   " + style.dim("── optional ──"));
+        const visibleOptional = optionalIdxs.slice(0, listHeight - requiredIdxs.length - 2);
+        for (const fieldIdx of visibleOptional) {
+          renderField(fieldIdx);
+        }
       } else {
-        content.push(prefix + paddedName + "  " + valStr);
+        content.push("");
+        const optLabel = filledOptionalCount > 0
+          ? `── ${optionalIdxs.length} optional (${filledOptionalCount} set) · 'o' to show ──`
+          : `── ${optionalIdxs.length} optional · 'o' to show ──`;
+        content.push("   " + style.dim(optLabel));
       }
     }
   }
@@ -639,23 +1177,34 @@ function renderFormPaletteMode(
     }
   }
 
-  // Description of highlighted field
+  // Description of highlighted field or Execute hint
   const highlightedIdx = filtered[state.formListCursor];
   if (highlightedIdx !== undefined && highlightedIdx >= 0 && highlightedIdx < fields.length) {
-    const desc = fields[highlightedIdx]!.prop.description;
-    if (desc) {
+    const prop = fields[highlightedIdx]!.prop;
+    if (prop.description) {
       content.push("");
-      const wrapped = wrapText(desc, innerWidth - 4);
+      const wrapped = wrapText(prop.description, innerWidth - 4);
       for (const line of wrapped) {
         content.push("   " + style.dim(line));
       }
     }
+    if (prop.examples?.length) {
+      const exStr = prop.examples.map((e) => typeof e === "string" ? e : JSON.stringify(e)).join(", ");
+      content.push("   " + style.dim("e.g. ") + style.dim(style.cyan(truncateVisible(exStr, innerWidth - 10))));
+    }
+  } else if (highlightedIdx === -1) {
+    content.push("");
+    content.push("   " + style.dim("Press enter to run"));
   }
 
+  // Footer hints
+  const hasUnfilledRequired = requiredFields.some((f) => !state.formValues[f.name]?.trim());
+  const tabHint = hasUnfilledRequired ? " · tab next required" : "";
+  const optionalHint = hasOptional ? " · o optional" : "";
   return renderLayout({
     breadcrumb: style.boldYellow("Readwise") + style.dim(" › ") + style.bold(title),
     content,
-    footer: style.dim("type to filter  ↑↓ navigate  enter edit/run  esc back"),
+    footer: style.dim("↑↓ navigate · enter edit" + tabHint + optionalHint + " · esc back"),
   });
 }
 
@@ -668,11 +1217,24 @@ function renderFormEditMode(
 
   content.push("");
   content.push("  " + style.bold(title));
+
+  // Show tool description for context
+  const toolDesc = state.formStack.length > 0
+    ? state.formStack[state.formStack.length - 1]!.parentFields
+        .find((f) => f.name === state.formStack[state.formStack.length - 1]!.parentFieldName)
+        ?.prop.items?.description
+    : state.selectedTool!.description;
+  if (toolDesc) {
+    const wrapped = wrapText(toolDesc, innerWidth - 4);
+    for (const line of wrapped) {
+      content.push("  " + style.dim(line));
+    }
+  }
   content.push("");
 
-  // Field name
+  // Field label
   const nameLabel = field.name + (field.required ? " *" : "");
-  content.push(" " + style.boldYellow("❯ " + nameLabel));
+  content.push("  " + style.bold(nameLabel));
 
   // Field description
   if (field.prop.description) {
@@ -681,17 +1243,17 @@ function renderFormEditMode(
       content.push("  " + style.dim(line));
     }
   }
+  if (field.prop.examples?.length) {
+    const exStr = field.prop.examples.map((e) => typeof e === "string" ? e : JSON.stringify(e)).join(", ");
+    content.push("  " + style.dim("e.g. ") + style.dim(style.cyan(truncateVisible(exStr, innerWidth - 10))));
+  }
   content.push("");
 
   // Editor area
+  const kind = classifyField(field.prop);
   const eVals = field.prop.enum || field.prop.items?.enum;
-  const isArrayObj = isArrayOfObjects(field.prop);
-  const isArrayEnum = !isArrayObj && field.prop.type === "array" && !!field.prop.items?.enum;
-  const isArrayText = !isArrayObj && field.prop.type === "array" && !field.prop.items?.enum;
-  const isBool = field.prop.type === "boolean";
-  const dateFmt = dateFieldFormat(field.prop);
 
-  if (isArrayObj) {
+  if (kind === "arrayObj") {
     // Array-of-objects editor: show existing items + "Add new item"
     const existing = state.formValues[field.name] || "[]";
     let items: unknown[] = [];
@@ -715,9 +1277,10 @@ function renderFormEditMode(
     } else {
       content.push(" " + style.dim("+") + " Add new item");
     }
-  } else if (dateFmt) {
+  } else if (kind === "date") {
+    const dateFmt = dateFieldFormat(field.prop)!;
     content.push("  " + renderDateParts(state.dateParts, state.datePartCursor, dateFmt));
-  } else if (isArrayEnum && eVals) {
+  } else if (kind === "arrayEnum" && eVals) {
     // Multi-select picker
     for (let ci = 0; ci < eVals.length; ci++) {
       const isCursor = ci === state.formEnumCursor;
@@ -727,7 +1290,7 @@ function renderFormEditMode(
       const label = marker + check + " " + eVals[ci]!;
       content.push(isCursor ? style.bold(label) : label);
     }
-  } else if (isArrayText) {
+  } else if (kind === "arrayText") {
     // Tag-style list editor: navigable items + text input at bottom
     const existing = state.formValues[field.name] || "";
     const items = existing ? existing.split(",").map((s) => s.trim()).filter(Boolean) : [];
@@ -750,45 +1313,76 @@ function renderFormEditMode(
       content.push("   " + style.dim("enter  ") + style.dim("edit item"));
       content.push("   " + style.dim("bksp   ") + style.dim("remove item"));
     }
-  } else if (eVals || isBool) {
-    const choices = isBool ? ["true", "false"] : eVals!;
+  } else if (kind === "enum" || kind === "bool") {
+    const choices = kind === "bool" ? ["true", "false"] : eVals!;
     for (let ci = 0; ci < choices.length; ci++) {
       const sel = ci === state.formEnumCursor;
       const choiceLine = (sel ? "   › " : "     ") + choices[ci]!;
       content.push(sel ? style.cyan(style.bold(choiceLine)) : choiceLine);
     }
   } else {
-    // Text editor
-    const lines = state.formInputBuf.split("\n");
-    for (let li = 0; li < lines.length; li++) {
-      const prefix = li === 0 ? " " + style.yellow("❯") + " " : "   ";
-      if (li === lines.length - 1) {
-        content.push(prefix + style.cyan(lines[li]!) + style.inverse(" "));
-      } else {
-        content.push(prefix + style.cyan(lines[li]!));
+    // Text editor with cursor position
+    const prefix0 = "  ";
+    if (!state.formInputBuf) {
+      // Show placeholder text when input is empty
+      let placeholder = "type a value";
+      if (field.prop.examples?.length) {
+        placeholder = String(field.prop.examples[0]);
+      } else if (field.prop.description) {
+        placeholder = field.prop.description.toLowerCase().replace(/[.!]$/, "");
+      } else if (field.prop.type === "integer" || field.prop.type === "number") {
+        placeholder = "enter a number";
+      }
+      content.push(prefix0 + style.inverse(" ") + style.dim(" " + placeholder + "…"));
+    } else {
+      const lines = state.formInputBuf.split("\n");
+      // Find cursor line and column from flat position
+      let cursorLine = 0;
+      let cursorCol = state.formInputCursorPos;
+      for (let li = 0; li < lines.length; li++) {
+        if (cursorCol <= lines[li]!.length) {
+          cursorLine = li;
+          break;
+        }
+        cursorCol -= lines[li]!.length + 1;
+      }
+      for (let li = 0; li < lines.length; li++) {
+        const prefix = li === 0 ? prefix0 : "   ";
+        const lineText = lines[li]!;
+        if (li === cursorLine) {
+          const before = lineText.slice(0, cursorCol);
+          const cursorChar = cursorCol < lineText.length ? lineText[cursorCol]! : " ";
+          const after = cursorCol < lineText.length ? lineText.slice(cursorCol + 1) : "";
+          content.push(prefix + style.cyan(before) + style.inverse(cursorChar) + style.cyan(after));
+        } else {
+          content.push(prefix + style.cyan(lineText));
+        }
       }
     }
   }
 
-  let footer: string;
-  if (isArrayObj) {
-    footer = style.dim("↑↓ navigate  enter add/select  backspace delete  esc back");
-  } else if (dateFmt) {
-    footer = style.dim("←→ part  ↑↓ adjust  t today  enter confirm  esc cancel");
-  } else if (isArrayEnum) {
-    footer = style.dim("space toggle  enter select  esc confirm");
-  } else if (isArrayText) {
-    footer = style.dim("↑↓ navigate  enter add/edit  backspace delete  esc confirm");
-  } else if (eVals || isBool) {
-    footer = style.dim("↑↓ navigate  enter confirm  esc cancel");
-  } else {
-    footer = style.dim("enter confirm  shift+enter newline  esc cancel");
+  // Show remaining required fields hint (for text editors)
+  if (kind === "text") {
+    const requiredFields = fields.filter((f) => f.required);
+    const filledCount = requiredFields.filter((f) => {
+      if (f.name === field.name) return !!state.formInputBuf.trim(); // current field
+      return !!state.formValues[f.name]?.trim();
+    }).length;
+    const remaining = requiredFields.length - filledCount;
+    content.push("");
+    if (remaining <= 0) {
+      content.push("  " + style.dim("Then press enter to confirm → Execute"));
+    } else if (remaining === 1 && !state.formInputBuf.trim()) {
+      content.push("  " + style.dim("Type a value, then press enter"));
+    } else {
+      content.push("  " + style.dim(`${remaining} required field${remaining > 1 ? "s" : ""} remaining`));
+    }
   }
 
   return renderLayout({
     breadcrumb: style.boldYellow("Readwise") + style.dim(" › ") + style.bold(title),
     content,
-    footer,
+    footer: style.dim(footerForFieldKind(kind)),
   });
 }
 
@@ -822,6 +1416,122 @@ const SUCCESS_ICON = [
   " ╚═════╝ ╚═╝  ╚═╝",
 ];
 
+function cardLine(text: string, innerW: number, borderFn: (s: string) => string): string {
+  return "  " + borderFn("│") + " " + fitWidth(text, innerW) + " " + borderFn("│");
+}
+
+function buildCardLines(card: CardItem, ci: number, selected: boolean, cardWidth: number): string[] {
+  const borderColor = selected ? style.cyan : style.dim;
+  const innerW = Math.max(1, cardWidth - 4);
+  const lines: string[] = [];
+
+  lines.push("  " + borderColor("╭" + "─".repeat(cardWidth - 2) + "╮"));
+
+  if (card.kind === "highlight") {
+    // Highlight card: quote-style passage, optional note, meta
+    const quotePrefix = "\u201c ";
+    const quoteSuffix = "\u201d";
+    const passage = card.summary || "\u2026";
+    const maxQuoteW = innerW - quotePrefix.length;
+    const wrapped = wrapText(passage, maxQuoteW);
+    // Cap at 6 lines
+    const showLines = wrapped.slice(0, 6);
+    if (wrapped.length > 6) {
+      const last = showLines[5]!;
+      showLines[5] = truncateVisible(last, maxQuoteW - 1) + "…";
+    }
+    for (let i = 0; i < showLines.length; i++) {
+      let lineText: string;
+      if (i === 0) {
+        lineText = quotePrefix + showLines[i]!;
+        if (showLines.length === 1) lineText += quoteSuffix;
+      } else if (i === showLines.length - 1) {
+        lineText = "  " + showLines[i]! + quoteSuffix;
+      } else {
+        lineText = "  " + showLines[i]!;
+      }
+      const styled = selected ? style.cyan(lineText) : lineText;
+      lines.push(cardLine(styled, innerW, borderColor));
+    }
+
+    // Note (if present)
+    if (card.note) {
+      const noteText = "✏ " + truncateVisible(card.note, innerW - 2);
+      lines.push(cardLine(style.yellow(noteText), innerW, borderColor));
+    }
+
+    // Meta line
+    if (card.meta) {
+      lines.push(cardLine(style.dim(truncateVisible(card.meta, innerW)), innerW, borderColor));
+    }
+  } else {
+    // Document card: title, summary, meta
+    const titleText = truncateVisible(card.title || "Untitled", innerW);
+    const titleStyled = selected ? style.bold(style.cyan(titleText)) : style.bold(titleText);
+    lines.push(cardLine(titleStyled, innerW, borderColor));
+
+    if (card.summary) {
+      const summaryText = truncateVisible(card.summary, innerW);
+      lines.push(cardLine(style.dim(summaryText), innerW, borderColor));
+    }
+
+    if (card.meta) {
+      lines.push(cardLine(style.dim(truncateVisible(card.meta, innerW)), innerW, borderColor));
+    }
+  }
+
+  lines.push("  " + borderColor("╰" + "─".repeat(cardWidth - 2) + "╯"));
+  return lines;
+}
+
+function renderCardView(state: AppState): string[] {
+  const { contentHeight, innerWidth } = getBoxDimensions();
+  const tool = state.selectedTool;
+  const title = tool ? humanLabel(tool.name, toolPrefix(tool)) : "";
+  const cards = state.resultCards;
+  const cardWidth = Math.min(innerWidth - 4, 72);
+
+  const content: string[] = [];
+
+  // Header with count
+  const countInfo = style.dim(` (${state.resultCursor + 1} of ${cards.length})`);
+  content.push("  " + style.bold("Results") + countInfo);
+  content.push("");
+
+  // Build all card lines
+  const allLines: { line: string; cardIdx: number }[] = [];
+  for (let ci = 0; ci < cards.length; ci++) {
+    const cardContentLines = buildCardLines(cards[ci]!, ci, ci === state.resultCursor, cardWidth);
+    for (const line of cardContentLines) {
+      allLines.push({ line, cardIdx: ci });
+    }
+    if (ci < cards.length - 1) {
+      allLines.push({ line: "", cardIdx: ci });
+    }
+  }
+
+  // Scroll so selected card is visible
+  const availableHeight = Math.max(1, contentHeight - content.length);
+  const scroll = state.resultCardScroll;
+  const visible = allLines.slice(scroll, scroll + availableHeight);
+  for (const entry of visible) {
+    content.push(entry.line);
+  }
+
+  const hasUrl = cards[state.resultCursor]?.url;
+  const footerParts = ["↑↓ navigate"];
+  if (hasUrl) footerParts.push("enter open");
+  footerParts.push("esc back", "q quit");
+
+  return renderLayout({
+    breadcrumb: style.boldYellow("Readwise") + style.dim(" › ") + style.bold(title) + style.dim(" › results"),
+    content,
+    footer: state.quitConfirm
+      ? style.yellow("Press q again to quit")
+      : style.dim(footerParts.join(" · ")),
+  });
+}
+
 function renderResults(state: AppState): string[] {
   const { contentHeight, innerWidth } = getBoxDimensions();
   const tool = state.selectedTool;
@@ -830,6 +1540,11 @@ function renderResults(state: AppState): string[] {
   const isEmptyList = !isError && state.result === EMPTY_LIST_SENTINEL;
   const isEmpty = !isError && !isEmptyList && !state.result.trim();
 
+  // Card view for list results
+  if (!isError && !isEmptyList && !isEmpty && state.resultCards.length > 0) {
+    return renderCardView(state);
+  }
+
   // No results screen for empty lists
   if (isEmptyList) {
     const ghost = [
@@ -860,7 +1575,7 @@ function renderResults(state: AppState): string[] {
       content,
       footer: state.quitConfirm
         ? style.yellow("Press q again to quit")
-        : style.dim("enter/esc back  q quit"),
+        : style.dim("enter/esc back · q quit"),
     });
   }
 
@@ -881,7 +1596,7 @@ function renderResults(state: AppState): string[] {
       content,
       footer: state.quitConfirm
         ? style.yellow("Press q again to quit")
-        : style.dim("enter/esc back  q quit"),
+        : style.dim("enter/esc back · q quit"),
     });
   }
 
@@ -913,7 +1628,7 @@ function renderResults(state: AppState): string[] {
     content,
     footer: state.quitConfirm
       ? style.yellow("Press q again to quit")
-      : style.dim(scrollHint + "↑↓←→ scroll  esc back  q quit"),
+      : style.dim(scrollHint + "↑↓←→ scroll · esc back · q quit"),
   });
 }
 
@@ -928,7 +1643,7 @@ function renderState(state: AppState): string[] {
 
 // --- Input handling ---
 
-function handleInput(state: AppState, key: KeyEvent): AppState | "exit" | "submit" {
+function handleInput(state: AppState, key: KeyEvent): AppState | "exit" | "submit" | "openUrl" {
   switch (state.view) {
     case "commands": return handleCommandListInput(state, key);
     case "form": return handleFormInput(state, key);
@@ -945,10 +1660,8 @@ function handleCommandListInput(state: AppState, key: KeyEvent): AppState | "exi
   const logoUsed = LOGO.length + 3;
   const listHeight = Math.max(1, contentHeight - logoUsed);
 
-  if (key.ctrl && key.name === "c") return "exit";
-
-  // Escape: clear query if non-empty, otherwise quit confirm
-  if (key.name === "escape") {
+  // Escape / ctrl+c / q: clear query if non-empty, otherwise quit confirm
+  if (key.name === "escape" || (key.ctrl && key.name === "c")) {
     if (state.searchQuery) {
       const filtered = filterCommands(state.tools, "");
       const sel = selectableIndices(filtered);
@@ -1034,11 +1747,7 @@ function handleCommandListInput(state: AppState, key: KeyEvent): AppState | "exi
 
         const formValues: Record<string, string> = {};
         for (const f of fields) {
-          if (f.prop.default != null) {
-            formValues[f.name] = String(f.prop.default);
-          } else {
-            formValues[f.name] = "";
-          }
+          formValues[f.name] = "";
         }
 
         if (fields.length === 0) {
@@ -1057,33 +1766,44 @@ function handleCommandListInput(state: AppState, key: KeyEvent): AppState | "exi
             formEditFieldIdx: -1,
             formEditing: false,
             formInputBuf: "",
+            formInputCursorPos: 0,
             formEnumCursor: 0,
             formEnumSelected: new Set(),
-            formShowRequired: false,
+            formShowRequired: false, formShowOptional: false,
             formStack: [],
           };
         }
 
-        return {
+        const filteredIndices = filterFormFields(fields, "");
+        const firstBlankRequired = fields.findIndex((f) => f.required && !formValues[f.name]?.trim());
+
+        const baseState: AppState = {
           ...s,
-          view: "form",
+          view: "form" as View,
           selectedTool: tool,
           fields,
           nameColWidth,
           formValues,
           formSearchQuery: "",
           formSearchCursorPos: 0,
-          formFilteredIndices: filterFormFields(fields, ""),
-          formListCursor: defaultFormCursor(fields, filterFormFields(fields, ""), formValues),
+          formFilteredIndices: filteredIndices,
+          formListCursor: defaultFormCursor(fields, filteredIndices, formValues),
           formScrollTop: 0,
           formEditFieldIdx: -1,
           formEditing: false,
           formInputBuf: "",
+          formInputCursorPos: 0,
           formEnumCursor: 0,
           formEnumSelected: new Set(),
-          formShowRequired: false,
+          formShowRequired: false, formShowOptional: false,
           formStack: [],
         };
+
+        // Auto-open first required field
+        if (firstBlankRequired >= 0) {
+          return startEditingField(baseState, firstBlankRequired);
+        }
+        return baseState;
       }
     }
     return s;
@@ -1100,20 +1820,169 @@ function handleCommandListInput(state: AppState, key: KeyEvent): AppState | "exi
     return s;
   }
 
-  // Printable characters: insert into search query
-  if (!key.ctrl && key.raw && key.raw.length === 1 && key.raw >= " ") {
-    const newQuery = s.searchQuery.slice(0, s.searchCursorPos) + key.raw + s.searchQuery.slice(s.searchCursorPos);
-    const filtered = filterCommands(s.tools, newQuery);
-    const sel = selectableIndices(filtered);
-    return { ...s, searchQuery: newQuery, searchCursorPos: s.searchCursorPos + 1, filteredItems: filtered, listCursor: sel[0] ?? 0, listScrollTop: 0 };
+  // Printable characters or paste: insert into search query
+  if (key.name === "paste" || (!key.ctrl && key.raw && key.raw.length === 1 && key.raw >= " ")) {
+    const text = (key.name === "paste" ? key.raw.replace(/[\x00-\x1f\x7f]/g, "") : key.raw) || "";
+    if (text) {
+      const newQuery = s.searchQuery.slice(0, s.searchCursorPos) + text + s.searchQuery.slice(s.searchCursorPos);
+      const filtered = filterCommands(s.tools, newQuery);
+      const sel = selectableIndices(filtered);
+      return { ...s, searchQuery: newQuery, searchCursorPos: s.searchCursorPos + text.length, filteredItems: filtered, listCursor: sel[0] ?? 0, listScrollTop: 0 };
+    }
   }
 
   return s;
 }
 
+function startEditingField(state: AppState, fieldIdx: number): AppState {
+  const field = state.fields[fieldIdx]!;
+  if (isArrayOfObjects(field.prop)) {
+    const existing = state.formValues[field.name] || "[]";
+    let items: unknown[] = [];
+    try { items = JSON.parse(existing); } catch { /* */ }
+    return { ...state, formEditing: true, formEditFieldIdx: fieldIdx, formEnumCursor: items.length };
+  }
+  const dateFmt = dateFieldFormat(field.prop);
+  if (dateFmt) {
+    const existing = state.formValues[field.name] || "";
+    const parts = parseDateParts(existing, dateFmt) || todayParts(dateFmt);
+    return { ...state, formEditing: true, formEditFieldIdx: fieldIdx, dateParts: parts, datePartCursor: 0 };
+  }
+  const enumValues = field.prop.enum || field.prop.items?.enum;
+  const isBool = field.prop.type === "boolean";
+  const isArrayEnum = !isArrayOfObjects(field.prop) && field.prop.type === "array" && !!field.prop.items?.enum;
+  if (isArrayEnum && enumValues) {
+    const curVal = state.formValues[field.name] || "";
+    const selected = new Set<number>();
+    if (curVal) {
+      const parts = curVal.split(",").map((s) => s.trim());
+      for (const p of parts) {
+        const idx = enumValues.indexOf(p);
+        if (idx >= 0) selected.add(idx);
+      }
+    }
+    return { ...state, formEditing: true, formEditFieldIdx: fieldIdx, formEnumCursor: 0, formEnumSelected: selected };
+  }
+  if (enumValues || isBool) {
+    const choices = isBool ? ["true", "false"] : enumValues!;
+    const curVal = state.formValues[field.name] || "";
+    const idx = choices.indexOf(curVal);
+    return { ...state, formEditing: true, formEditFieldIdx: fieldIdx, formEnumCursor: idx >= 0 ? idx : 0 };
+  }
+  if (field.prop.type === "array" && !field.prop.items?.enum) {
+    const existing = state.formValues[field.name] || "";
+    const itemCount = existing ? existing.split(",").map((s) => s.trim()).filter(Boolean).length : 0;
+    return { ...state, formEditing: true, formEditFieldIdx: fieldIdx, formInputBuf: "", formInputCursorPos: 0, formEnumCursor: itemCount };
+  }
+  const editBuf = state.formValues[field.name] || "";
+  return { ...state, formEditing: true, formEditFieldIdx: fieldIdx, formInputBuf: editBuf, formInputCursorPos: editBuf.length };
+}
+
 function handleFormInput(state: AppState, key: KeyEvent): AppState | "submit" {
-  if (state.formEditing) return handleFormEditInput(state, key);
-  return handleFormPaletteInput(state, key);
+  // Sub-forms use existing palette/edit handlers
+  if (state.formStack.length > 0) {
+    if (state.formEditing) return handleFormEditInput(state, key);
+    return handleFormPaletteInput(state, key);
+  }
+
+  // Command builder: editing a field
+  if (state.formEditing) {
+    const result = handleFormEditInput(state, key);
+    if (result === "submit") return result;
+    // Auto-advance: if editing just ended via confirm (not cancel), jump to next blank required field
+    if (!result.formEditing && state.formEditing) {
+      const wasCancel = key.name === "escape";
+      if (!wasCancel) {
+        const nextBlank = result.fields.findIndex((f) => f.required && !result.formValues[f.name]?.trim());
+        if (nextBlank >= 0) {
+          return startEditingField(result, nextBlank);
+        }
+      }
+    }
+    return result;
+  }
+
+  // Command builder: optional picker
+  if (state.formShowOptional) {
+    return handleOptionalPickerInput(state, key);
+  }
+
+  // Command builder: ready state
+  return handleCommandBuilderReadyInput(state, key);
+}
+
+function commandListReset(tools: ToolDef[]): Partial<AppState> {
+  const filteredItems = buildCommandList(tools);
+  const sel = selectableIndices(filteredItems);
+  return {
+    view: "commands" as View, selectedTool: null,
+    searchQuery: "", searchCursorPos: 0,
+    filteredItems, listCursor: sel[0] ?? 0, listScrollTop: 0,
+  };
+}
+
+function handleCommandBuilderReadyInput(state: AppState, key: KeyEvent): AppState | "submit" {
+  if (key.name === "escape" || (key.ctrl && key.name === "c")) {
+    return { ...state, ...commandListReset(state.tools) };
+  }
+
+  if (key.name === "return") {
+    if (missingRequiredFields(state.fields, state.formValues).length === 0) {
+      return "submit";
+    }
+    // Jump to first missing required field
+    const nextBlank = state.fields.findIndex((f) => f.required && !state.formValues[f.name]?.trim());
+    if (nextBlank >= 0) {
+      return startEditingField(state, nextBlank);
+    }
+    return state;
+  }
+
+  if (key.name === "tab") {
+    const hasOptional = state.fields.some((f) => !f.required);
+    if (hasOptional) {
+      return { ...state, formShowOptional: true, formListCursor: 0 };
+    }
+    return state;
+  }
+
+  // Backspace: re-edit last set field
+  if (key.name === "backspace") {
+    for (let i = state.fields.length - 1; i >= 0; i--) {
+      if (state.formValues[state.fields[i]!.name]?.trim()) {
+        return startEditingField(state, i);
+      }
+    }
+    return state;
+  }
+
+  return state;
+}
+
+function handleOptionalPickerInput(state: AppState, key: KeyEvent): AppState | "submit" {
+  const optionalFields = state.fields
+    .map((f, i) => ({ field: f, idx: i }))
+    .filter(({ field }) => !field.required);
+
+  if (key.name === "escape" || (key.ctrl && key.name === "c")) {
+    return { ...state, formShowOptional: false };
+  }
+
+  if (key.name === "up") {
+    return { ...state, formListCursor: state.formListCursor > 0 ? state.formListCursor - 1 : optionalFields.length - 1 };
+  }
+  if (key.name === "down") {
+    return { ...state, formListCursor: state.formListCursor < optionalFields.length - 1 ? state.formListCursor + 1 : 0 };
+  }
+
+  if (key.name === "return") {
+    const selected = optionalFields[state.formListCursor];
+    if (selected) {
+      return startEditingField({ ...state, formShowOptional: false }, selected.idx);
+    }
+  }
+
+  return state;
 }
 
 function handleFormPaletteInput(state: AppState, key: KeyEvent): AppState | "submit" {
@@ -1155,13 +2024,62 @@ function handleFormPaletteInput(state: AppState, key: KeyEvent): AppState | "sub
         formFilteredIndices: parentFiltered,
         formListCursor: defaultFormCursor(entry.parentFields, parentFiltered, entry.parentValues),
         formScrollTop: 0,
-        formShowRequired: false,
+        formShowRequired: false, formShowOptional: false,
         formInputBuf: "",
+        formInputCursorPos: 0,
       };
     }
-    const resetFiltered = buildCommandList(state.tools);
-    const resetSel = selectableIndices(resetFiltered);
-    return { ...state, view: "commands", selectedTool: null, searchQuery: "", searchCursorPos: 0, filteredItems: resetFiltered, listCursor: resetSel[0] ?? 0, listScrollTop: 0 };
+    return { ...state, ...commandListReset(state.tools) };
+  }
+
+  // Tab: jump to next unfilled required field
+  if (key.name === "tab") {
+    const unfilledRequired = filtered
+      .map((idx, listPos) => ({ idx, listPos }))
+      .filter(({ idx }) => {
+        if (idx < 0 || idx >= fields.length) return false;
+        const f = fields[idx]!;
+        if (!f.required) return false;
+        const val = state.formValues[f.name]?.trim();
+        if (!val) return true;
+        if (isArrayOfObjects(f.prop)) {
+          try { return JSON.parse(val).length === 0; } catch { return true; }
+        }
+        return false;
+      });
+    if (unfilledRequired.length > 0) {
+      // Find the next one after current cursor, wrapping around
+      const after = unfilledRequired.find((u) => u.listPos > formListCursor);
+      const target = after || unfilledRequired[0]!;
+      let scroll = state.formScrollTop;
+      const paramItems = filtered.filter((idx) => idx !== -1);
+      if (target.idx >= 0) {
+        const posInParams = paramItems.indexOf(target.idx);
+        if (posInParams < scroll) scroll = posInParams;
+        if (posInParams >= scroll + listHeight) scroll = posInParams - listHeight + 1;
+      }
+      return { ...state, formListCursor: target.listPos, formScrollTop: scroll };
+    }
+    // No unfilled required fields — jump to Execute
+    const execPos = filtered.indexOf(-1);
+    if (execPos >= 0) return { ...state, formListCursor: execPos };
+    return state;
+  }
+
+  // 'o' key: toggle optional fields visibility (when not searching)
+  if (key.raw === "o" && !key.ctrl && !formSearchQuery) {
+    const optionalExists = filtered.some((idx) => idx >= 0 && idx < fields.length && !fields[idx]!.required);
+    if (optionalExists) {
+      const newShow = !state.formShowOptional;
+      if (!newShow) {
+        const curIdx = filtered[formListCursor];
+        if (curIdx !== undefined && curIdx >= 0 && curIdx < fields.length && !fields[curIdx]!.required) {
+          const execPos = filtered.indexOf(-1);
+          return { ...state, formShowOptional: false, formListCursor: execPos >= 0 ? execPos : 0 };
+        }
+      }
+      return { ...state, formShowOptional: newShow };
+    }
   }
 
   // Arrow left/right: move text cursor within search input
@@ -1172,29 +2090,44 @@ function handleFormPaletteInput(state: AppState, key: KeyEvent): AppState | "sub
     return { ...state, formSearchCursorPos: Math.min(formSearchQuery.length, state.formSearchCursorPos + 1) };
   }
 
-  // Arrow up/down: navigate filtered list (cycling)
+  // Helper: check if a position in filtered is navigable (skip collapsed optional fields)
+  const isNavigable = (listPos: number) => {
+    const idx = filtered[listPos];
+    if (idx === undefined) return false;
+    if (idx === -1) return true; // Execute always navigable
+    if (!state.formShowOptional && !state.formSearchQuery && idx >= 0 && idx < fields.length && !fields[idx]!.required) return false;
+    return true;
+  };
+
+  // Arrow up/down: navigate filtered list (cycling, skipping hidden items)
   if (key.name === "up") {
-    const next = formListCursor > 0 ? formListCursor - 1 : filtered.length - 1;
+    let next = formListCursor;
+    for (let i = 0; i < filtered.length; i++) {
+      next = next > 0 ? next - 1 : filtered.length - 1;
+      if (isNavigable(next)) break;
+    }
     let scroll = state.formScrollTop;
     const itemIdx = filtered[next]!;
     if (itemIdx !== -1) {
       const paramItems = filtered.filter((idx) => idx !== -1);
       const posInParams = paramItems.indexOf(itemIdx);
       if (posInParams < scroll) scroll = posInParams;
-      // Wrap to bottom: reset scroll to show end of list
       if (next > formListCursor) scroll = Math.max(0, paramItems.length - listHeight);
     }
     return { ...state, formListCursor: next, formScrollTop: scroll };
   }
   if (key.name === "down") {
-    const next = formListCursor < filtered.length - 1 ? formListCursor + 1 : 0;
+    let next = formListCursor;
+    for (let i = 0; i < filtered.length; i++) {
+      next = next < filtered.length - 1 ? next + 1 : 0;
+      if (isNavigable(next)) break;
+    }
     let scroll = state.formScrollTop;
     const itemIdx = filtered[next]!;
     if (itemIdx !== -1) {
       const paramItems = filtered.filter((idx) => idx !== -1);
       const posInParams = paramItems.indexOf(itemIdx);
       if (posInParams >= scroll + listHeight) scroll = posInParams - listHeight + 1;
-      // Wrap to top: reset scroll
       if (next < formListCursor) scroll = 0;
     } else if (next < formListCursor) {
       scroll = 0;
@@ -1217,47 +2150,7 @@ function handleFormPaletteInput(state: AppState, key: KeyEvent): AppState | "sub
       return { ...state, formShowRequired: true };
     }
     if (highlightedIdx !== undefined && highlightedIdx >= 0 && highlightedIdx < fields.length) {
-      const field = fields[highlightedIdx]!;
-      // Array-of-objects: enter edit mode with cursor on "Add new item"
-      if (isArrayOfObjects(field.prop)) {
-        const existing = state.formValues[field.name] || "[]";
-        let items: unknown[] = [];
-        try { items = JSON.parse(existing); } catch { /* */ }
-        return { ...state, formEditing: true, formEditFieldIdx: highlightedIdx, formEnumCursor: items.length };
-      }
-      const dateFmt = dateFieldFormat(field.prop);
-      const enumValues = field.prop.enum || field.prop.items?.enum;
-      const isBool = field.prop.type === "boolean";
-      if (dateFmt) {
-        const existing = state.formValues[field.name] || "";
-        const parts = parseDateParts(existing, dateFmt) || todayParts(dateFmt);
-        return { ...state, formEditing: true, formEditFieldIdx: highlightedIdx, dateParts: parts, datePartCursor: 0 };
-      }
-      const isArrayEnum = !isArrayOfObjects(field.prop) && field.prop.type === "array" && !!field.prop.items?.enum;
-      if (isArrayEnum && enumValues) {
-        const curVal = state.formValues[field.name] || "";
-        const selected = new Set<number>();
-        if (curVal) {
-          const parts = curVal.split(",").map((s) => s.trim());
-          for (const p of parts) {
-            const idx = enumValues.indexOf(p);
-            if (idx >= 0) selected.add(idx);
-          }
-        }
-        return { ...state, formEditing: true, formEditFieldIdx: highlightedIdx, formEnumCursor: 0, formEnumSelected: selected };
-      }
-      if (enumValues || isBool) {
-        const choices = isBool ? ["true", "false"] : enumValues!;
-        const curVal = state.formValues[field.name] || "";
-        const idx = choices.indexOf(curVal);
-        return { ...state, formEditing: true, formEditFieldIdx: highlightedIdx, formEnumCursor: idx >= 0 ? idx : 0 };
-      }
-      if (field.prop.type === "array" && !field.prop.items?.enum) {
-        const existing = state.formValues[field.name] || "";
-        const itemCount = existing ? existing.split(",").map((s) => s.trim()).filter(Boolean).length : 0;
-        return { ...state, formEditing: true, formEditFieldIdx: highlightedIdx, formInputBuf: "", formEnumCursor: itemCount };
-      }
-      return { ...state, formEditing: true, formEditFieldIdx: highlightedIdx, formInputBuf: state.formValues[field.name] || "" };
+      return startEditingField(state, highlightedIdx);
     }
     return state;
   }
@@ -1272,11 +2165,14 @@ function handleFormPaletteInput(state: AppState, key: KeyEvent): AppState | "sub
     return state;
   }
 
-  // Printable characters: insert into search query
-  if (!key.ctrl && key.raw && key.raw.length === 1 && key.raw >= " ") {
-    const newQuery = formSearchQuery.slice(0, state.formSearchCursorPos) + key.raw + formSearchQuery.slice(state.formSearchCursorPos);
-    const newFiltered = filterFormFields(fields, newQuery);
-    return { ...state, formSearchQuery: newQuery, formSearchCursorPos: state.formSearchCursorPos + 1, formFilteredIndices: newFiltered, formListCursor: 0, formScrollTop: 0 };
+  // Printable characters or paste: insert into search query
+  if (key.name === "paste" || (!key.ctrl && key.raw && key.raw.length === 1 && key.raw >= " ")) {
+    const text = (key.name === "paste" ? key.raw.replace(/[\x00-\x1f\x7f]/g, "") : key.raw) || "";
+    if (text) {
+      const newQuery = formSearchQuery.slice(0, state.formSearchCursorPos) + text + formSearchQuery.slice(state.formSearchCursorPos);
+      const newFiltered = filterFormFields(fields, newQuery);
+      return { ...state, formSearchQuery: newQuery, formSearchCursorPos: state.formSearchCursorPos + text.length, formFilteredIndices: newFiltered, formListCursor: 0, formScrollTop: 0 };
+    }
   }
 
   return state;
@@ -1291,7 +2187,7 @@ function handleFormEditInput(state: AppState, key: KeyEvent): AppState | "submit
 
   const resetPalette = (updatedValues?: Record<string, string>) => {
     const f = filterFormFields(fields, "");
-    return { formSearchQuery: "", formSearchCursorPos: 0, formFilteredIndices: f, formListCursor: defaultFormCursor(fields, f, updatedValues ?? formValues), formScrollTop: 0, formShowRequired: false };
+    return { formSearchQuery: "", formSearchCursorPos: 0, formFilteredIndices: f, formListCursor: defaultFormCursor(fields, f, updatedValues ?? formValues), formScrollTop: 0, formShowRequired: false, formShowOptional: false };
   };
 
   // Escape: cancel edit (for multi-select and tag editor, escape confirms since items are saved live)
@@ -1304,7 +2200,7 @@ function handleFormEditInput(state: AppState, key: KeyEvent): AppState | "submit
       const newValues = { ...formValues, [field.name]: val };
       return { ...state, formEditing: false, formEditFieldIdx: -1, formValues: newValues, formEnumSelected: new Set(), ...resetPalette(newValues) };
     }
-    return { ...state, formEditing: false, formEditFieldIdx: -1, formInputBuf: "", ...resetPalette() };
+    return { ...state, formEditing: false, formEditFieldIdx: -1, formInputBuf: "", formInputCursorPos: 0, ...resetPalette() };
   }
 
   if (key.ctrl && key.name === "c") return "submit";
@@ -1376,10 +2272,11 @@ function handleFormEditInput(state: AppState, key: KeyEvent): AppState | "submit
         formFilteredIndices: subFiltered,
         formListCursor: defaultFormCursor(subFields, subFiltered, subValues),
         formScrollTop: 0,
-        formShowRequired: false,
+        formShowRequired: false, formShowOptional: false,
         formEnumCursor: 0,
         formEnumSelected: new Set(),
         formInputBuf: "",
+        formInputCursorPos: 0,
       };
     }
     if (key.name === "backspace" && formEnumCursor < items.length) {
@@ -1491,7 +2388,7 @@ function handleFormEditInput(state: AppState, key: KeyEvent): AppState | "submit
         const newItems = [...items];
         newItems.splice(formEnumCursor, 1);
         const newValues = { ...formValues, [field.name]: newItems.join(", ") };
-        return { ...state, formValues: newValues, formInputBuf: editVal, formEnumCursor: newItems.length };
+        return { ...state, formValues: newValues, formInputBuf: editVal, formInputCursorPos: editVal.length, formEnumCursor: newItems.length };
       }
       if (key.name === "backspace") {
         // Delete item
@@ -1505,11 +2402,16 @@ function handleFormEditInput(state: AppState, key: KeyEvent): AppState | "submit
     }
 
     // Cursor on text input
+    if (key.name === "paste") {
+      // Paste: strip newlines for tag input
+      const text = key.raw.replace(/\n/g, "");
+      return { ...state, formInputBuf: formInputBuf + text, formInputCursorPos: formInputBuf.length + text.length };
+    }
     if (key.name === "return") {
       if (formInputBuf.trim()) {
         items.push(formInputBuf.trim());
         const newValues = { ...formValues, [field.name]: items.join(", ") };
-        return { ...state, formValues: newValues, formInputBuf: "", formEnumCursor: items.length };
+        return { ...state, formValues: newValues, formInputBuf: "", formInputCursorPos: 0, formEnumCursor: items.length };
       }
       // Empty input: confirm and close
       const newValues = { ...formValues, [field.name]: items.join(", ") };
@@ -1517,41 +2419,143 @@ function handleFormEditInput(state: AppState, key: KeyEvent): AppState | "submit
     }
     if (key.name === "backspace") {
       if (formInputBuf) {
-        return { ...state, formInputBuf: formInputBuf.slice(0, -1) };
+        return { ...state, formInputBuf: formInputBuf.slice(0, -1), formInputCursorPos: formInputBuf.length - 1 };
       }
       return state;
     }
     if (!key.ctrl && key.name !== "escape" && !key.raw.startsWith("\x1b")) {
-      return { ...state, formInputBuf: formInputBuf + key.raw };
+      const clean = key.raw.replace(/[\x00-\x1f\x7f]/g, ""); // strip control chars for tags
+      if (clean) return { ...state, formInputBuf: formInputBuf + clean, formInputCursorPos: formInputBuf.length + clean.length };
     }
     return state;
   }
 
   // Text editing mode
-  if (key.name === "return" && key.shift) {
-    // Shift+Enter: insert newline
-    return { ...state, formInputBuf: formInputBuf + "\n" };
+  const pos = state.formInputCursorPos;
+  if (key.name === "paste") {
+    const newBuf = formInputBuf.slice(0, pos) + key.raw + formInputBuf.slice(pos);
+    return { ...state, formInputBuf: newBuf, formInputCursorPos: pos + key.raw.length };
+  }
+  // Insert newline: Ctrl+J (\n), Shift+Enter, or Alt+Enter
+  if (key.raw === "\n" || (key.name === "return" && key.shift)) {
+    const newBuf = formInputBuf.slice(0, pos) + "\n" + formInputBuf.slice(pos);
+    return { ...state, formInputBuf: newBuf, formInputCursorPos: pos + 1 };
   }
   if (key.name === "return") {
-    // Enter: confirm
+    // Enter (\r): confirm value
     const newValues = { ...formValues, [field.name]: formInputBuf };
-    return { ...state, formEditing: false, formEditFieldIdx: -1, formValues: newValues, ...resetPalette(newValues) };
+    return { ...state, formEditing: false, formEditFieldIdx: -1, formInputCursorPos: 0, formValues: newValues, ...resetPalette(newValues) };
+  }
+  if (key.name === "left") {
+    return { ...state, formInputCursorPos: Math.max(0, pos - 1) };
+  }
+  if (key.name === "right") {
+    return { ...state, formInputCursorPos: Math.min(formInputBuf.length, pos + 1) };
+  }
+  if (key.name === "wordLeft") {
+    return { ...state, formInputCursorPos: prevWordBoundary(formInputBuf, pos) };
+  }
+  if (key.name === "wordRight") {
+    return { ...state, formInputCursorPos: nextWordBoundary(formInputBuf, pos) };
+  }
+  if (key.name === "wordBackspace") {
+    const boundary = prevWordBoundary(formInputBuf, pos);
+    const newBuf = formInputBuf.slice(0, boundary) + formInputBuf.slice(pos);
+    return { ...state, formInputBuf: newBuf, formInputCursorPos: boundary };
+  }
+  if (key.name === "up") {
+    // Move cursor up one line
+    const lines = formInputBuf.split("\n");
+    let rem = pos;
+    let line = 0;
+    for (; line < lines.length; line++) {
+      if (rem <= lines[line]!.length) break;
+      rem -= lines[line]!.length + 1;
+    }
+    if (line > 0) {
+      const col = Math.min(rem, lines[line - 1]!.length);
+      let newPos = 0;
+      for (let i = 0; i < line - 1; i++) newPos += lines[i]!.length + 1;
+      newPos += col;
+      return { ...state, formInputCursorPos: newPos };
+    }
+    return state;
+  }
+  if (key.name === "down") {
+    // Move cursor down one line
+    const lines = formInputBuf.split("\n");
+    let rem = pos;
+    let line = 0;
+    for (; line < lines.length; line++) {
+      if (rem <= lines[line]!.length) break;
+      rem -= lines[line]!.length + 1;
+    }
+    if (line < lines.length - 1) {
+      const col = Math.min(rem, lines[line + 1]!.length);
+      let newPos = 0;
+      for (let i = 0; i <= line; i++) newPos += lines[i]!.length + 1;
+      newPos += col;
+      return { ...state, formInputCursorPos: newPos };
+    }
+    return state;
   }
   if (key.name === "backspace") {
-    return { ...state, formInputBuf: formInputBuf.slice(0, -1) };
+    if (pos > 0) {
+      const newBuf = formInputBuf.slice(0, pos - 1) + formInputBuf.slice(pos);
+      return { ...state, formInputBuf: newBuf, formInputCursorPos: pos - 1 };
+    }
+    return state;
   }
   if (!key.ctrl && key.name !== "escape" && !key.raw.startsWith("\x1b")) {
-    return { ...state, formInputBuf: formInputBuf + key.raw };
+    // Preserve newlines in pasted text (multi-line supported), strip other control chars
+    const clean = key.raw.replace(/[\x00-\x09\x0b\x0c\x0e-\x1f\x7f]/g, "");
+    if (clean) {
+      const newBuf = formInputBuf.slice(0, pos) + clean + formInputBuf.slice(pos);
+      return { ...state, formInputBuf: newBuf, formInputCursorPos: pos + clean.length };
+    }
   }
   return state;
 }
 
-function handleResultsInput(state: AppState, key: KeyEvent): AppState | "exit" {
+function cardLineCount(card: CardItem, cardWidth: number): number {
+  const innerW = Math.max(1, cardWidth - 4);
+  if (card.kind === "highlight") {
+    const quoteW = innerW - 2; // account for quote prefix
+    const passage = card.summary || "\u2026";
+    const wrapped = wrapText(passage, quoteW);
+    const textLines = Math.min(wrapped.length, 6);
+    return 2 + textLines + (card.note ? 1 : 0) + (card.meta ? 1 : 0); // top + text + note? + meta? + bottom
+  }
+  return 2 + 1 + (card.summary ? 1 : 0) + (card.meta ? 1 : 0); // top + title + summary? + meta? + bottom
+}
+
+function computeCardScroll(cards: CardItem[], cursor: number, currentScroll: number, availableHeight: number): number {
+  const { innerWidth } = getBoxDimensions();
+  const cardWidth = Math.min(innerWidth - 4, 72);
+  let lineStart = 0;
+  for (let ci = 0; ci < cards.length; ci++) {
+    const card = cards[ci]!;
+    const height = cardLineCount(card, cardWidth);
+    const spacing = ci < cards.length - 1 ? 1 : 0;
+    if (ci === cursor) {
+      const lineEnd = lineStart + height + spacing;
+      if (lineStart < currentScroll) return lineStart;
+      if (lineEnd > currentScroll + availableHeight) return Math.max(0, lineEnd - availableHeight);
+      return currentScroll;
+    }
+    lineStart += height + spacing;
+  }
+  return currentScroll;
+}
+
+function handleResultsInput(state: AppState, key: KeyEvent): AppState | "exit" | "openUrl" {
   const { contentHeight } = getBoxDimensions();
-  const contentLines = (state.error || state.result).split("\n");
-  const visibleCount = Math.max(1, contentHeight - 3);
+  const inCardMode = state.resultCards.length > 0 && !state.error;
 
-  if (key.ctrl && key.name === "c") return "exit";
+  if (key.ctrl && key.name === "c") {
+    if (state.quitConfirm) return "exit";
+    return { ...state, quitConfirm: true };
+  }
 
   if (key.name === "q" && !key.ctrl) {
     if (state.quitConfirm) return "exit";
@@ -1561,59 +2565,76 @@ function handleResultsInput(state: AppState, key: KeyEvent): AppState | "exit" {
   // Any other key cancels quit confirm
   const s = state.quitConfirm ? { ...state, quitConfirm: false } : state;
 
+  const resultsClear = { result: "", error: "", resultScroll: 0, resultScrollX: 0, resultCards: [] as CardItem[], resultCursor: 0, resultCardScroll: 0 };
+
   const goBack = (): AppState => {
-    const resetFiltered = buildCommandList(s.tools);
-    const resetSel = selectableIndices(resetFiltered);
-    const searchReset = { searchQuery: "", searchCursorPos: 0, filteredItems: resetFiltered, listCursor: resetSel[0] ?? 0, listScrollTop: 0 };
-    const hasParams = s.selectedTool && Object.keys(s.selectedTool.inputSchema.properties || {}).length > 0;
+    const isEmpty = !s.error && s.result !== EMPTY_LIST_SENTINEL && !s.result.trim();
+    const hasParams = !isEmpty && s.selectedTool && Object.keys(s.selectedTool.inputSchema.properties || {}).length > 0;
     if (hasParams) {
+      const f = filterFormFields(s.fields, "");
       return {
-        ...s, view: "form" as View, result: "", error: "", resultScroll: 0, resultScrollX: 0,
+        ...s, view: "form" as View, ...resultsClear,
         formSearchQuery: "", formSearchCursorPos: 0,
-        formFilteredIndices: filterFormFields(s.fields, ""),
-        formListCursor: defaultFormCursor(s.fields, filterFormFields(s.fields, ""), s.formValues), formScrollTop: 0,
-        formEditing: false, formEditFieldIdx: -1, formShowRequired: false,
+        formFilteredIndices: f,
+        formListCursor: defaultFormCursor(s.fields, f, s.formValues), formScrollTop: 0,
+        formEditing: false, formEditFieldIdx: -1, formShowRequired: false, formShowOptional: false,
       };
     }
-    return { ...s, view: "commands" as View, selectedTool: null, result: "", error: "", resultScroll: 0, resultScrollX: 0, ...searchReset };
+    return { ...s, ...commandListReset(s.tools), ...resultsClear };
   };
 
-  // Enter on success/empty-list/error screens → go back
-  if (key.name === "return") {
-    const isEmpty = !s.error && s.result !== EMPTY_LIST_SENTINEL && !s.result.trim();
-    if (isEmpty) {
-      // Success screen → back to main menu
-      const resetFiltered = buildCommandList(s.tools);
-      const resetSel = selectableIndices(resetFiltered);
-      const searchReset = { searchQuery: "", searchCursorPos: 0, filteredItems: resetFiltered, listCursor: resetSel[0] ?? 0, listScrollTop: 0 };
-      return { ...s, view: "commands", selectedTool: null, result: "", error: "", resultScroll: 0, resultScrollX: 0, ...searchReset };
-    }
+  if (key.name === "escape") {
     return goBack();
   }
 
-  if (key.name === "escape") {
-    const isEmpty = !s.error && s.result !== EMPTY_LIST_SENTINEL && !s.result.trim();
-    const resetFiltered = buildCommandList(s.tools);
-    const resetSel = selectableIndices(resetFiltered);
-    const searchReset = { searchQuery: "", searchCursorPos: 0, filteredItems: resetFiltered, listCursor: resetSel[0] ?? 0, listScrollTop: 0 };
-    if (isEmpty) {
-      // Success screen → back to main menu
-      return { ...s, view: "commands", selectedTool: null, result: "", error: "", resultScroll: 0, resultScrollX: 0, ...searchReset };
-    }
-    // Data or error → back to form if it has params, otherwise main menu
-    const hasParams = s.selectedTool && Object.keys(s.selectedTool.inputSchema.properties || {}).length > 0;
-    if (hasParams) {
-      return {
-        ...s, view: "form", result: "", error: "", resultScroll: 0, resultScrollX: 0,
-        formSearchQuery: "", formSearchCursorPos: 0,
-        formFilteredIndices: filterFormFields(s.fields, ""),
-        formListCursor: defaultFormCursor(s.fields, filterFormFields(s.fields, ""), s.formValues), formScrollTop: 0,
-        formEditing: false, formEditFieldIdx: -1, formShowRequired: false,
-      };
+  if (inCardMode) {
+    const cards = s.resultCards;
+    // 2 lines used by header + blank
+    const availableHeight = Math.max(1, contentHeight - 2);
+
+    if (key.name === "return") {
+      const card = cards[s.resultCursor];
+      if (card?.url) return "openUrl";
+      return goBack();
+    }
+
+    if (key.name === "up") {
+      if (s.resultCursor > 0) {
+        const newCursor = s.resultCursor - 1;
+        const newScroll = computeCardScroll(cards, newCursor, s.resultCardScroll, availableHeight);
+        return { ...s, resultCursor: newCursor, resultCardScroll: newScroll };
+      }
+      return s;
+    }
+    if (key.name === "down") {
+      if (s.resultCursor < cards.length - 1) {
+        const newCursor = s.resultCursor + 1;
+        const newScroll = computeCardScroll(cards, newCursor, s.resultCardScroll, availableHeight);
+        return { ...s, resultCursor: newCursor, resultCardScroll: newScroll };
+      }
+      return s;
+    }
+    if (key.name === "pageup") {
+      const newCursor = Math.max(0, s.resultCursor - 5);
+      const newScroll = computeCardScroll(cards, newCursor, s.resultCardScroll, availableHeight);
+      return { ...s, resultCursor: newCursor, resultCardScroll: newScroll };
+    }
+    if (key.name === "pagedown") {
+      const newCursor = Math.min(cards.length - 1, s.resultCursor + 5);
+      const newScroll = computeCardScroll(cards, newCursor, s.resultCardScroll, availableHeight);
+      return { ...s, resultCursor: newCursor, resultCardScroll: newScroll };
     }
-    return { ...s, view: "commands", selectedTool: null, result: "", error: "", resultScroll: 0, resultScrollX: 0, ...searchReset };
+
+    return s;
   }
 
+  // Text mode fallback
+  const contentLines = (state.error || state.result).split("\n");
+  const visibleCount = Math.max(1, contentHeight - 3);
+
+  if (key.name === "return") {
+    return goBack();
+  }
   if (key.name === "up") {
     return { ...s, resultScroll: Math.max(0, s.resultScroll - 1) };
   }
@@ -1767,7 +2788,7 @@ async function executeTool(state: AppState): Promise<AppState> {
 
     if (res.isError) {
       const errMsg = res.content.map((c) => c.text || "").filter(Boolean).join("\n");
-      return { ...state, view: "results", error: errMsg || "Unknown error", result: "", resultScroll: 0, resultScrollX: 0 };
+      return { ...state, view: "results", error: errMsg || "Unknown error", result: "", resultScroll: 0, resultScrollX: 0, resultCards: [], resultCursor: 0, resultCardScroll: 0 };
     }
 
     const text = res.content.filter((c) => c.type === "text" && c.text).map((c) => c.text!).join("\n");
@@ -1775,21 +2796,24 @@ async function executeTool(state: AppState): Promise<AppState> {
     const structured = (res as Record<string, unknown>).structuredContent;
     let formatted: string;
     let emptyList = false;
+    let parsedData: unknown = undefined;
     if (!text && structured !== undefined) {
+      parsedData = structured;
       emptyList = isEmptyListResult(structured);
       formatted = formatJsonPretty(structured);
     } else {
       try {
-        const parsed = JSON.parse(text);
-        emptyList = isEmptyListResult(parsed);
-        formatted = formatJsonPretty(parsed);
+        parsedData = JSON.parse(text);
+        emptyList = isEmptyListResult(parsedData);
+        formatted = formatJsonPretty(parsedData);
       } catch {
         formatted = text;
       }
     }
-    return { ...state, view: "results", result: emptyList ? EMPTY_LIST_SENTINEL : formatted, error: "", resultScroll: 0, resultScrollX: 0 };
+    const cards = parsedData !== undefined ? extractCards(parsedData) || [] : [];
+    return { ...state, view: "results", result: emptyList ? EMPTY_LIST_SENTINEL : formatted, error: "", resultScroll: 0, resultScrollX: 0, resultCards: cards, resultCursor: 0, resultCardScroll: 0 };
   } catch (err) {
-    return { ...state, view: "results", error: (err as Error).message, result: "", resultScroll: 0, resultScrollX: 0 };
+    return { ...state, view: "results", error: (err as Error).message, result: "", resultScroll: 0, resultScrollX: 0, resultCards: [], resultCursor: 0, resultCardScroll: 0 };
   }
 }
 
@@ -1819,10 +2843,11 @@ export async function runApp(tools: ToolDef[]): Promise<void> {
     formEditFieldIdx: -1,
     formEditing: false,
     formInputBuf: "",
+    formInputCursorPos: 0,
     formEnumCursor: 0,
     formEnumSelected: new Set(),
     formValues: {},
-    formShowRequired: false,
+    formShowRequired: false, formShowOptional: false,
     formStack: [],
     dateParts: [],
     datePartCursor: 0,
@@ -1830,6 +2855,9 @@ export async function runApp(tools: ToolDef[]): Promise<void> {
     error: "",
     resultScroll: 0,
     resultScrollX: 0,
+    resultCards: [],
+    resultCursor: 0,
+    resultCardScroll: 0,
     spinnerFrame: 0,
   };
 
@@ -1889,6 +2917,15 @@ export async function runApp(tools: ToolDef[]): Promise<void> {
         return;
       }
 
+      if (result === "openUrl") {
+        const card = state.resultCards[state.resultCursor];
+        if (card?.url) {
+          const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+          exec(`${cmd} ${JSON.stringify(card.url)}`);
+        }
+        return;
+      }
+
       if (result === "submit") {
         state = { ...state, view: "loading", spinnerFrame: 0 };
         paint(renderState(state));