@readwise/cli 0.3.1 → 0.5.1

package/dist/tui/app.js

@@ -1,3 +1,4 @@
+import { exec } from "node:child_process";
 import { resolveProperty } from "../commands.js";
 import { callTool } from "../mcp.js";
 import { ensureValidToken } from "../auth.js";
@@ -125,6 +126,45 @@ function defaultFormCursor(fields, filtered, values) {
     const firstBlank = filtered.findIndex((idx) => idx >= 0 && missing.has(fields[idx].name));
     return firstBlank >= 0 ? firstBlank : executeIndex(filtered);
 }
+function classifyField(prop) {
+    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) {
+    const badges = {
+        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) {
+    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, maxWidth) {
     if (!value)
         return style.dim("–");
@@ -205,8 +245,9 @@ function popFormStack(state) {
         formFilteredIndices: parentFiltered,
         formListCursor: defaultFormCursor(entry.parentFields, parentFiltered, newParentValues),
         formScrollTop: 0,
-        formShowRequired: false,
+        formShowRequired: false, formShowOptional: false,
         formInputBuf: "",
+        formInputCursorPos: 0,
     };
 }
 const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
@@ -248,6 +289,220 @@ function wrapText(text, width) {
         lines.push(current);
     return lines.length > 0 ? lines : [""];
 }
+// --- Card parsing helpers ---
+function extractCards(data) {
+    let items;
+    if (Array.isArray(data)) {
+        items = data;
+    }
+    else if (typeof data === "object" && data !== null) {
+        // Look for a "results" array or similar
+        const obj = data;
+        const arrayKey = Object.keys(obj).find((k) => Array.isArray(obj[k]) && obj[k].length > 0);
+        if (arrayKey) {
+            items = obj[arrayKey];
+        }
+        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;
+        const kind = isHighlightObj(obj) ? "highlight" : "document";
+        if (kind === "highlight") {
+            const attrs = (typeof obj.attributes === "object" && obj.attributes !== null)
+                ? obj.attributes : 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,
+        };
+    });
+    // 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) {
+    if (val === null || val === undefined)
+        return "";
+    return String(val);
+}
+function isHighlightObj(obj) {
+    // 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)
+        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) {
+    for (const key of ["title", "readable_title", "name"]) {
+        const val = obj[key];
+        if (val && typeof val === "string" && !String(val).startsWith("http"))
+            return val;
+    }
+    // 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) {
+    for (const key of ["summary", "description", "note", "notes", "content"]) {
+        const val = obj[key];
+        if (val && typeof val === "string")
+            return val;
+    }
+    return "";
+}
+function extractDocMeta(obj) {
+    const parts = [];
+    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) {
+    const attrs = (typeof obj.attributes === "object" && obj.attributes !== null)
+        ? obj.attributes : null;
+    const parts = [];
+    // 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) => typeof t === "object" && t !== null ? str(t.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) {
+    for (const key of ["url", "source_url", "reader_url", "readwise_url"]) {
+        if (obj[key] && typeof obj[key] === "string")
+            return obj[key];
+    }
+    return "";
+}
+// --- Word boundary helpers ---
+function prevWordBoundary(buf, pos) {
+    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, pos) {
+    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;
+}
 function dateFieldFormat(prop) {
     if (prop.format === "date")
         return "date";
@@ -385,7 +640,7 @@ function renderCommandList(state) {
             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}`);
@@ -445,8 +700,8 @@ function renderCommandList(state) {
         }
     }
     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"),
         content,
@@ -458,15 +713,227 @@ function renderForm(state) {
     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, title, fields, contentHeight, innerWidth) {
+    const tool = state.selectedTool;
+    const cmdName = tool.name.replace(/_/g, "-");
+    const content = [];
+    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 = [];
+    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 = [];
+                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) => 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) => 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 = [];
+            try {
+                items = JSON.parse(existing);
+            }
+            catch { /* */ }
+            content.push("");
+            for (let i = 0; i < items.length; i++) {
+                const item = items[i];
+                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(state, title, fields, contentHeight, innerWidth) {
     const content = [];
@@ -485,51 +952,117 @@ function renderFormPaletteMode(state, title, fields, contentHeight, innerWidth)
             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("");
-    // Compute maxLabelWidth
+    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 (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)
     const listHeight = Math.max(1, contentHeight - headerUsed - 8);
     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) => {
+        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));
             }
         }
     }
@@ -556,22 +1089,34 @@ function renderFormPaletteMode(state, title, fields, contentHeight, innerWidth)
             content.push("   " + style.red("Required: " + names));
         }
     }
-    // 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"),
     });
 }
 function renderFormEditMode(state, title, fields, _contentHeight, innerWidth) {
@@ -579,10 +1124,22 @@ function renderFormEditMode(state, title, fields, _contentHeight, innerWidth) {
     const content = [];
     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) {
         const wrapped = wrapText(field.prop.description, innerWidth - 4);
@@ -590,15 +1147,15 @@ function renderFormEditMode(state, title, fields, _contentHeight, innerWidth) {
             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 = [];
@@ -628,10 +1185,11 @@ function renderFormEditMode(state, title, fields, _contentHeight, innerWidth) {
             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;
@@ -642,7 +1200,7 @@ function renderFormEditMode(state, title, fields, _contentHeight, innerWidth) {
             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) : [];
@@ -668,8 +1226,8 @@ function renderFormEditMode(state, title, fields, _contentHeight, innerWidth) {
             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];
@@ -677,41 +1235,73 @@ function renderFormEditMode(state, title, fields, _contentHeight, innerWidth) {
         }
     }
     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(" "));
+        // 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 {
-                content.push(prefix + style.cyan(lines[li]));
+            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;
-    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)),
     });
 }
 function renderLoading(state) {
@@ -740,6 +1330,111 @@ const SUCCESS_ICON = [
     "╚██████╔╝██║  ██╗",
     " ╚═════╝ ╚═╝  ╚═╝",
 ];
+function cardLine(text, innerW, borderFn) {
+    return "  " + borderFn("│") + " " + fitWidth(text, innerW) + " " + borderFn("│");
+}
+function buildCardLines(card, ci, selected, cardWidth) {
+    const borderColor = selected ? style.cyan : style.dim;
+    const innerW = Math.max(1, cardWidth - 4);
+    const lines = [];
+    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;
+            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) {
+    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 = [];
+    // 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 = [];
+    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) {
     const { contentHeight, innerWidth } = getBoxDimensions();
     const tool = state.selectedTool;
@@ -747,6 +1442,10 @@ function renderResults(state) {
     const isError = !!state.error;
     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 = [
@@ -777,7 +1476,7 @@ function renderResults(state) {
             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"),
         });
     }
     // Success screen for empty results
@@ -797,7 +1496,7 @@ function renderResults(state) {
             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"),
         });
     }
     const rawContent = state.error || state.result;
@@ -825,7 +1524,7 @@ function renderResults(state) {
         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"),
     });
 }
 function renderState(state) {
@@ -852,10 +1551,8 @@ function handleCommandListInput(state, key) {
     // search input uses: LOGO.length + 1 (blank) + 1 (search line) + 1 (blank)
     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);
@@ -937,12 +1634,7 @@ function handleCommandListInput(state, key) {
                 const nameColWidth = Math.max(...fields.map((f) => f.name.length + (f.required ? 2 : 0)), 6) + 1;
                 const formValues = {};
                 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) {
                     return {
@@ -960,13 +1652,16 @@ function handleCommandListInput(state, key) {
                         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 = {
                     ...s,
                     view: "form",
                     selectedTool: tool,
@@ -975,17 +1670,23 @@ function handleCommandListInput(state, key) {
                     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;
@@ -1000,19 +1701,158 @@ function handleCommandListInput(state, key) {
         }
         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, fieldIdx) {
+    const field = state.fields[fieldIdx];
+    if (isArrayOfObjects(field.prop)) {
+        const existing = state.formValues[field.name] || "[]";
+        let items = [];
+        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();
+        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, key) {
-    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) {
+    const filteredItems = buildCommandList(tools);
+    const sel = selectableIndices(filteredItems);
+    return {
+        view: "commands", selectedTool: null,
+        searchQuery: "", searchCursorPos: 0,
+        filteredItems, listCursor: sel[0] ?? 0, listScrollTop: 0,
+    };
+}
+function handleCommandBuilderReadyInput(state, key) {
+    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, key) {
+    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, key) {
     const { fields, formFilteredIndices: filtered, formListCursor, formSearchQuery } = state;
@@ -1055,13 +1895,71 @@ function handleFormPaletteInput(state, key) {
                 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
     if (key.name === "left") {
@@ -1070,9 +1968,25 @@ function handleFormPaletteInput(state, key) {
     if (key.name === "right") {
         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) => {
+        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) {
@@ -1080,14 +1994,18 @@ function handleFormPaletteInput(state, key) {
             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) {
@@ -1095,7 +2013,6 @@ function handleFormPaletteInput(state, key) {
             const posInParams = paramItems.indexOf(itemIdx);
             if (posInParams >= scroll + listHeight)
                 scroll = posInParams - listHeight + 1;
-            // Wrap to top: reset scroll
             if (next < formListCursor)
                 scroll = 0;
         }
@@ -1119,51 +2036,7 @@ function handleFormPaletteInput(state, key) {
             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 = [];
-                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();
-                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;
     }
@@ -1176,11 +2049,14 @@ function handleFormPaletteInput(state, key) {
         }
         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;
 }
@@ -1192,7 +2068,7 @@ function handleFormEditInput(state, key) {
     const isBool = field.prop.type === "boolean";
     const resetPalette = (updatedValues) => {
         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)
     if (key.name === "escape") {
@@ -1204,7 +2080,7 @@ function handleFormEditInput(state, key) {
             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";
@@ -1280,10 +2156,11 @@ function handleFormEditInput(state, key) {
                 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) {
@@ -1391,7 +2268,7 @@ function handleFormEditInput(state, key) {
                 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
@@ -1404,11 +2281,16 @@ function handleFormEditInput(state, key) {
             return state;
         }
         // 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(", ") };
@@ -1416,39 +2298,146 @@ function handleFormEditInput(state, key) {
         }
         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 cardLineCount(card, cardWidth) {
+    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, cursor, currentScroll, availableHeight) {
+    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, key) {
     const { contentHeight } = getBoxDimensions();
-    const contentLines = (state.error || state.result).split("\n");
-    const visibleCount = Math.max(1, contentHeight - 3);
-    if (key.ctrl && key.name === "c")
-        return "exit";
+    const inCardMode = state.resultCards.length > 0 && !state.error;
+    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";
@@ -1456,55 +2445,68 @@ function handleResultsInput(state, key) {
     }
     // Any other key cancels quit confirm
     const s = state.quitConfirm ? { ...state, quitConfirm: false } : state;
+    const resultsClear = { result: "", error: "", resultScroll: 0, resultScrollX: 0, resultCards: [], resultCursor: 0, resultCardScroll: 0 };
     const goBack = () => {
-        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", result: "", error: "", resultScroll: 0, resultScrollX: 0,
+                ...s, view: "form", ...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", 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;
         }
-        return { ...s, view: "commands", selectedTool: null, result: "", error: "", resultScroll: 0, resultScrollX: 0, ...searchReset };
+        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;
+    }
+    // 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) };
@@ -1668,31 +2670,34 @@ async function executeTool(state) {
         const res = await callTool(token, authType, tool.name, args);
         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");
         // Check structuredContent if text content is empty
         const structured = res.structuredContent;
         let formatted;
         let emptyList = false;
+        let parsedData = 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.message, result: "", resultScroll: 0, resultScrollX: 0 };
+        return { ...state, view: "results", error: err.message, result: "", resultScroll: 0, resultScrollX: 0, resultCards: [], resultCursor: 0, resultCardScroll: 0 };
     }
 }
 // --- Main loop ---
@@ -1719,10 +2724,11 @@ export async function runApp(tools) {
         formEditFieldIdx: -1,
         formEditing: false,
         formInputBuf: "",
+        formInputCursorPos: 0,
         formEnumCursor: 0,
         formEnumSelected: new Set(),
         formValues: {},
-        formShowRequired: false,
+        formShowRequired: false, formShowOptional: false,
         formStack: [],
         dateParts: [],
         datePartCursor: 0,
@@ -1730,6 +2736,9 @@ export async function runApp(tools) {
         error: "",
         resultScroll: 0,
         resultScrollX: 0,
+        resultCards: [],
+        resultCursor: 0,
+        resultCardScroll: 0,
         spinnerFrame: 0,
     };
     paint(renderState(state));
@@ -1781,6 +2790,14 @@ export async function runApp(tools) {
                 cleanup();
                 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));