@lifestreamdynamics/vault-cli 1.3.7 → 1.3.9

package/dist/commands/admin.js

@@ -4,7 +4,9 @@ import { addGlobalFlags, resolveFlags } from '../utils/flags.js';
 import { createOutput, handleError } from '../utils/output.js';
 import { formatBytes, formatUptime } from '../utils/format.js';
 export function registerAdminCommands(program) {
-    const admin = program.command('admin').description('System administration (requires admin role)');
+    const admin = program.command('admin')
+        .description('System administration (requires admin role)')
+        .addHelpText('after', '\nNOTE: Admin commands require JWT authentication with admin role.\nRun "lsvault auth login" to authenticate first.');
     // ── System Stats ────────────────────────────────────────────────────
     const stats = admin.command('stats').description('View system-wide statistics and metrics');
     const statsAction = async (_opts) => {

package/dist/commands/ai.js

@@ -80,7 +80,11 @@ export function registerAiCommands(program) {
     addGlobalFlags(ai.command('chat')
         .description('Send a message in an AI chat session')
         .argument('<sessionId>', 'Session ID')
-        .argument('<message>', 'Message to send'))
+        .argument('<message>', 'Message to send')
+        .addHelpText('after', `
+EXAMPLES
+  lsvault ai chat <session-id> "What are the key points in my notes?"
+  lsvault ai chat <session-id> "Summarize recent changes" -o json`))
         .action(async (sessionId, message, _opts) => {
         const flags = resolveFlags(_opts);
         const out = createOutput(flags);

package/dist/commands/analytics.js

@@ -67,7 +67,7 @@ export function registerAnalyticsCommands(program) {
         .addHelpText('after', `
 NOTE
   The publishedDocId is a UUID, NOT a document path. Get it from:
-    lsvault publish list <vaultId>`))
+    lsvault analytics published`))
         .action(async (vaultId, publishedDocId, _opts) => {
         const flags = resolveFlags(_opts);
         const out = createOutput(flags);

package/dist/commands/audit.js

@@ -43,6 +43,7 @@ EXAMPLES
             const logPath = String(_opts.logPath || DEFAULT_LOG_PATH);
             if (!fs.existsSync(logPath)) {
                 out.warn(`Audit log file not found at ${logPath}`);
+                process.exitCode = 1;
                 if (flags.output === 'json') {
                     process.stdout.write('[]\n');
                 }

package/dist/commands/auth.js

@@ -5,6 +5,8 @@ import { loadConfigAsync, getCredentialManager } from '../config.js';
 import { getClientAsync } from '../client.js';
 import { migrateCredentials, hasPlaintextCredentials, checkAndPromptMigration } from '../lib/migration.js';
 import { promptPassword, promptMfaCode } from '../utils/prompt.js';
+import { addGlobalFlags, resolveFlags } from '../utils/flags.js';
+import { createOutput, handleError } from '../utils/output.js';
 export function registerAuthCommands(program) {
     const auth = program.command('auth').description('Authentication and credential management');
     auth.command('login')
@@ -186,41 +188,47 @@ EXAMPLES
             spinner.info('Migration skipped.');
         }
     });
-    auth.command('whoami')
-        .description('Show the currently authenticated user, plan, and API URL')
-        .action(async () => {
+    addGlobalFlags(auth.command('whoami')
+        .description('Show the currently authenticated user, plan, and API URL'))
+        .action(async (_opts) => {
+        const flags = resolveFlags(_opts);
+        const out = createOutput(flags);
         const config = await loadConfigAsync();
-        console.log(`API URL: ${config.apiUrl}`);
-        console.log(`API Key: ${config.apiKey ? config.apiKey.slice(0, 12) + '...' : chalk.yellow('not set')}`);
-        if (config.accessToken) {
-            console.log(`Auth:    ${chalk.green('JWT (email/password)')}`);
-        }
         // Warn about plaintext credentials
         await checkAndPromptMigration(getCredentialManager());
-        if (config.apiKey || config.accessToken) {
-            const spinner = ora('Fetching user info...').start();
-            try {
-                const client = await getClientAsync();
-                const user = await client.user.me();
-                spinner.stop();
-                console.log(`User:    ${chalk.cyan(user.email)}`);
-                console.log(`Name:    ${user.displayName || chalk.dim('not set')}`);
-                console.log(`Role:    ${user.role}`);
-                let plan = user.subscriptionTier;
-                if (!plan) {
-                    try {
-                        const sub = await client.subscription.get();
-                        plan = sub.subscription.tier;
-                    }
-                    catch { /* API key may not have scope */ }
+        if (!config.apiKey && !config.accessToken) {
+            out.record({
+                apiUrl: config.apiUrl,
+                apiKey: null,
+                auth: 'none',
+            });
+            return;
+        }
+        out.startSpinner('Fetching user info...');
+        try {
+            const client = await getClientAsync();
+            const user = await client.user.me();
+            out.stopSpinner();
+            let plan = user.subscriptionTier;
+            if (!plan) {
+                try {
+                    const sub = await client.subscription.get();
+                    plan = sub.subscription.tier;
                 }
-                console.log(`Plan:    ${plan ? chalk.green(plan) : chalk.dim('unknown')}`);
-            }
-            catch (err) {
-                spinner.fail('Could not fetch user info');
-                console.error(err instanceof Error ? err.message : String(err));
-                process.exitCode = 1;
+                catch { /* API key may not have scope */ }
             }
+            out.record({
+                apiUrl: config.apiUrl,
+                apiKey: config.apiKey ? config.apiKey.slice(0, 12) + '...' : null,
+                auth: config.accessToken ? 'JWT (email/password)' : 'API key',
+                email: user.email,
+                displayName: user.displayName || null,
+                role: user.role,
+                plan: plan || 'unknown',
+            });
+        }
+        catch (err) {
+            handleError(out, err, 'Could not fetch user info');
         }
     });
 }

package/dist/commands/booking.js

@@ -170,7 +170,7 @@ export function registerBookingCommands(program) {
             const client = await getClientAsync();
             await client.booking.deleteSlot(vaultId, slotId);
             out.stopSpinner();
-            out.status(chalk.green(`Slot ${slotId} deleted.`));
+            out.success(`Slot ${slotId} deleted.`, { id: slotId, deleted: true });
         }
         catch (err) {
             handleError(out, err, 'Delete slot failed');
@@ -405,7 +405,8 @@ export function registerBookingCommands(program) {
     addGlobalFlags(booking.command('reschedule')
         .description('Reschedule a booking by guest reschedule token')
         .argument('<token>', 'Reschedule token (from guest email link)')
-        .argument('<newStartAt>', 'New start time in ISO 8601 format (e.g. 2026-03-15T10:00:00Z)'))
+        .argument('<newStartAt>', 'New start time in ISO 8601 format (e.g. 2026-03-15T10:00:00Z)')
+        .addHelpText('after', '\n  The <token> is the guest reschedule token from the booking confirmation email,\n  not the booking ID.'))
         .action(async (token, newStartAt, _opts) => {
         const flags = resolveFlags(_opts);
         const out = createOutput(flags);

package/dist/commands/calendar.js

@@ -31,6 +31,7 @@ export function registerCalendarCommands(program) {
         out.startSpinner('Loading calendar...');
         try {
             vaultId = await resolveVaultId(vaultId);
+            out.debug(`API: GET calendar events for vault ${vaultId}`);
             const client = await getClientAsync();
             const response = await client.calendar.getActivity(vaultId, {
                 start: _opts.start ?? getDefaultStart(),
@@ -134,9 +135,7 @@ export function registerCalendarCommands(program) {
                 recurrence: _opts.recurrence || null,
             });
             out.stopSpinner();
-            out.status(dateStr === 'clear'
-                ? chalk.green(`Due date cleared for ${path}`)
-                : chalk.green(`Due date set to ${dateStr} for ${path}`));
+            out.success(dateStr === 'clear' ? `Due date cleared for ${path}` : `Due date set to ${dateStr} for ${path}`, { path, dueDate: dateStr === 'clear' ? null : dateStr });
         }
         catch (err) {
             handleError(out, err, 'Set due date failed');
@@ -290,7 +289,7 @@ export function registerCalendarCommands(program) {
             const client = await getClientAsync();
             await client.calendar.deleteEvent(vaultId, eventId);
             out.stopSpinner();
-            out.status(chalk.green(`Event ${eventId} deleted.`));
+            out.success(`Event ${eventId} deleted.`, { id: eventId, deleted: true });
         }
         catch (err) {
             handleError(out, err, 'Delete event failed');
@@ -809,7 +808,7 @@ NOTE
             const client = await getClientAsync();
             await client.calendar.removeParticipant(vaultId, eventId, participantId);
             out.stopSpinner();
-            out.status(chalk.green(`Participant ${participantId} removed.`));
+            out.success(`Participant ${participantId} removed.`, { id: participantId, eventId, removed: true });
         }
         catch (err) {
             handleError(out, err, 'Remove participant failed');

package/dist/commands/completion.js

@@ -1,45 +1,217 @@
 const SAFE_COMMAND_NAME = /^[a-z][a-z0-9-]*$/;
-function collectCommandNames(cmd, prefix = '') {
-    const names = [];
+/**
+ * Recursively walk the Commander tree and produce a structured CommandNode tree.
+ * Only names matching SAFE_COMMAND_NAME are included (shell injection guard).
+ */
+function collectCommandTree(cmd) {
+    const nodes = [];
     for (const sub of cmd.commands) {
         const name = sub.name();
-        // Skip any name that doesn't match the safe pattern to prevent shell injection
         if (!SAFE_COMMAND_NAME.test(name))
             continue;
-        const full = prefix ? `${prefix} ${name}` : name;
-        names.push(name);
-        names.push(...collectCommandNames(sub, full));
+        // Collect long-form option flags from this command's declared options.
+        const options = sub.options
+            .map((o) => o.long)
+            .filter((flag) => typeof flag === 'string');
+        nodes.push({
+            name,
+            description: sub.description() ?? '',
+            subcommands: collectCommandTree(sub),
+            options,
+        });
     }
-    return names;
+    return nodes;
+}
+// ---------------------------------------------------------------------------
+// Bash
+// ---------------------------------------------------------------------------
+/**
+ * Emit the bash case arm for a top-level command.
+ * Handles COMP_CWORD == 2 (show subcommand names) and COMP_CWORD >= 3 (show
+ * a flat list of options for the matched sub/sub-subcommand).
+ */
+function bashCaseArm(node, indent) {
+    const lines = [];
+    lines.push(`${indent}${node.name})`);
+    if (node.subcommands.length > 0) {
+        const subNames = node.subcommands.map(s => s.name).join(' ');
+        lines.push(`${indent}  if [[ $COMP_CWORD -eq 2 ]]; then`);
+        lines.push(`${indent}    COMPREPLY=($(compgen -W "${subNames}" -- "$cur"))`);
+        lines.push(`${indent}  else`);
+        // Third-level: match sub-subcommand name in COMP_WORDS[2] and show its options
+        lines.push(`${indent}    case "$cmd2" in`);
+        for (const sub of node.subcommands) {
+            const allOpts = sub.options.join(' ');
+            // Also include sub-subcommand names if this node has nested commands
+            const deepNames = sub.subcommands.map(s => s.name).join(' ');
+            const completions = [deepNames, allOpts].filter(Boolean).join(' ');
+            lines.push(`${indent}      ${sub.name})`);
+            if (completions) {
+                lines.push(`${indent}        COMPREPLY=($(compgen -W "${completions}" -- "$cur"))`);
+            }
+            lines.push(`${indent}        ;;`);
+        }
+        lines.push(`${indent}    esac`);
+        lines.push(`${indent}  fi`);
+    }
+    else if (node.options.length > 0) {
+        // Leaf command with flags only
+        const opts = node.options.join(' ');
+        lines.push(`${indent}  COMPREPLY=($(compgen -W "${opts}" -- "$cur"))`);
+    }
+    lines.push(`${indent}  ;;`);
+    return lines.join('\n');
 }
 export function generateBashCompletion(program) {
-    const commands = collectCommandNames(program);
+    const tree = collectCommandTree(program);
+    const topLevelNames = tree.map(n => n.name).join(' ');
+    const caseArms = tree.map(node => bashCaseArm(node, '    ')).join('\n');
     return `# Bash completion for lsvault
 # Add to ~/.bashrc: eval "$(lsvault completion bash)"
 _lsvault_completions() {
   local cur="\${COMP_WORDS[COMP_CWORD]}"
-  local commands="${commands.join(' ')}"
-  COMPREPLY=($(compgen -W "\${commands}" -- "\${cur}"))
+  local cmd1="\${COMP_WORDS[1]:-}"
+  local cmd2="\${COMP_WORDS[2]:-}"
+
+  # Top-level completions
+  if [[ $COMP_CWORD -eq 1 ]]; then
+    COMPREPLY=($(compgen -W "${topLevelNames}" -- "$cur"))
+    return
+  fi
+
+  # Second-level and deeper
+  case "$cmd1" in
+${caseArms}
+  esac
 }
 complete -F _lsvault_completions lsvault
 `;
 }
+// ---------------------------------------------------------------------------
+// Zsh
+// ---------------------------------------------------------------------------
+function zshDescribeArray(nodes, varName, indent) {
+    const lines = [];
+    lines.push(`${indent}local -a ${varName}`);
+    lines.push(`${indent}${varName}=(`);
+    for (const n of nodes) {
+        // Escape single quotes in description
+        const desc = n.description.replace(/'/g, "'\\''");
+        lines.push(`${indent}  '${n.name}:${desc}'`);
+    }
+    lines.push(`${indent})`);
+    return lines.join('\n');
+}
+function zshCaseArm(node, indent) {
+    const lines = [];
+    lines.push(`${indent}${node.name})`);
+    if (node.subcommands.length > 0) {
+        lines.push(zshDescribeArray(node.subcommands, 'subcmds', indent + '  '));
+        lines.push(`${indent}  if (( CURRENT == 3 )); then`);
+        lines.push(`${indent}    _describe 'subcommand' subcmds`);
+        lines.push(`${indent}  else`);
+        // Third-level: show options for matched subcommand
+        lines.push(`${indent}    case "$words[3]" in`);
+        for (const sub of node.subcommands) {
+            if (sub.options.length > 0 || sub.subcommands.length > 0) {
+                lines.push(`${indent}      ${sub.name})`);
+                if (sub.subcommands.length > 0) {
+                    lines.push(zshDescribeArray(sub.subcommands, 'deepcmds', indent + '        '));
+                    lines.push(`${indent}        if (( CURRENT == 4 )); then`);
+                    lines.push(`${indent}          _describe 'subcommand' deepcmds`);
+                    if (sub.options.length > 0) {
+                        const optSpecs = sub.options.map(o => `'${o}'`).join(' ');
+                        lines.push(`${indent}        else`);
+                        lines.push(`${indent}          _arguments ${optSpecs}`);
+                    }
+                    lines.push(`${indent}        fi`);
+                }
+                else if (sub.options.length > 0) {
+                    const optSpecs = sub.options.map(o => `'${o}'`).join(' ');
+                    lines.push(`${indent}        _arguments ${optSpecs}`);
+                }
+                lines.push(`${indent}        ;;`);
+            }
+        }
+        lines.push(`${indent}    esac`);
+        lines.push(`${indent}  fi`);
+    }
+    else if (node.options.length > 0) {
+        const optSpecs = node.options.map(o => `'${o}'`).join(' ');
+        lines.push(`${indent}  _arguments ${optSpecs}`);
+    }
+    lines.push(`${indent}  ;;`);
+    return lines.join('\n');
+}
 export function generateZshCompletion(program) {
-    const commands = collectCommandNames(program);
+    const tree = collectCommandTree(program);
+    const topLevelArray = zshDescribeArray(tree, 'toplevel', '  ');
+    const caseArms = tree.map(node => zshCaseArm(node, '    ')).join('\n');
     return `# Zsh completion for lsvault
 # Add to ~/.zshrc: eval "$(lsvault completion zsh)"
 _lsvault() {
-  local -a commands
-  commands=(${commands.map(c => `'${c}'`).join(' ')})
-  _describe 'lsvault commands' commands
+${topLevelArray}
+
+  if (( CURRENT == 2 )); then
+    _describe 'command' toplevel
+    return
+  fi
+
+  case "$words[2]" in
+${caseArms}
+  esac
 }
 compdef _lsvault lsvault
 `;
 }
+// ---------------------------------------------------------------------------
+// Fish
+// ---------------------------------------------------------------------------
+/**
+ * Escape a string for use inside a fish completion -d '...' description.
+ * Fish uses single quotes and doesn't support backslash escapes within them,
+ * so we just strip single quotes entirely.
+ */
+function fishDesc(s) {
+    return s.replace(/'/g, '');
+}
 export function generateFishCompletion(program) {
-    const commands = collectCommandNames(program);
-    return commands.map(c => `complete -c lsvault -n '__fish_use_subcommand' -a '${c}' -d '${c} command'`).join('\n') + '\n';
+    const tree = collectCommandTree(program);
+    const lines = [];
+    // Helper: the names of all top-level commands (used in __fish_seen_subcommand_from guards)
+    const topLevelNames = tree.map(n => n.name).join(' ');
+    for (const node of tree) {
+        // Top-level command — only show when no subcommand has been entered yet
+        lines.push(`complete -c lsvault -n '__fish_use_subcommand' -a '${node.name}' -d '${fishDesc(node.description)}'`);
+        if (node.subcommands.length > 0) {
+            // Subcommand names — show when this top-level command is active and no sub-subcommand yet
+            for (const sub of node.subcommands) {
+                lines.push(`complete -c lsvault -n '__fish_seen_subcommand_from ${node.name}; and not __fish_seen_subcommand_from ${sub.subcommands.map(s => s.name).concat(node.subcommands.map(s => s.name)).join(' ')}' -a '${sub.name}' -d '${fishDesc(sub.description)}'`);
+                // Options for this subcommand — show when top-level AND subcommand are both seen
+                for (const opt of sub.options) {
+                    lines.push(`complete -c lsvault -n '__fish_seen_subcommand_from ${node.name}; and __fish_seen_subcommand_from ${sub.name}' -a '${opt}'`);
+                }
+                // Third-level sub-subcommands
+                for (const deep of sub.subcommands) {
+                    lines.push(`complete -c lsvault -n '__fish_seen_subcommand_from ${node.name}; and __fish_seen_subcommand_from ${sub.name}' -a '${deep.name}' -d '${fishDesc(deep.description)}'`);
+                    for (const opt of deep.options) {
+                        lines.push(`complete -c lsvault -n '__fish_seen_subcommand_from ${node.name}; and __fish_seen_subcommand_from ${deep.name}' -a '${opt}'`);
+                    }
+                }
+            }
+        }
+        else {
+            // Leaf top-level command — offer its own options when active
+            for (const opt of node.options) {
+                lines.push(`complete -c lsvault -n '__fish_seen_subcommand_from ${topLevelNames}' -f -a '${opt}'`);
+            }
+        }
+    }
+    return lines.join('\n') + '\n';
 }
+// ---------------------------------------------------------------------------
+// Registration
+// ---------------------------------------------------------------------------
 export function registerCompletionCommands(program) {
     const completion = program.command('completion').description('Generate shell completion scripts');
     completion.command('bash')

package/dist/commands/config.js

@@ -46,6 +46,7 @@ EXAMPLES
         }
         else {
             process.stdout.write(chalk.yellow(`Key "${key}" not set in profile "${profile}"`) + '\n');
+            process.exitCode = 1;
         }
     });
     config
@@ -83,6 +84,13 @@ EXAMPLES
   lsvault config use prod
   lsvault config use dev`)
         .action((name) => {
+        const profiles = listProfiles();
+        if (!profiles.includes(name)) {
+            process.stderr.write(chalk.red(`Profile '${name}' does not exist.`) + '\n');
+            process.stderr.write(chalk.dim('Available profiles: ' + (profiles.length ? profiles.join(', ') : 'none')) + '\n');
+            process.exitCode = 1;
+            return;
+        }
         setActiveProfile(name);
         process.stdout.write(chalk.green(`Active profile set to ${chalk.bold(name)}`) + '\n');
     });

package/dist/commands/connectors.js

@@ -14,6 +14,7 @@ export function registerConnectorCommands(program) {
         const out = createOutput(flags);
         out.startSpinner('Fetching connectors...');
         try {
+            out.debug('API: GET connectors');
             if (_opts.vault)
                 _opts.vault = await resolveVaultId(String(_opts.vault));
             const client = await getClientAsync();
@@ -205,12 +206,17 @@ VALID PROVIDERS
         const out = createOutput(flags);
         out.startSpinner('Triggering sync...');
         try {
+            out.debug(`API: POST connectors/${connectorId}/sync`);
             const client = await getClientAsync();
             const result = await client.connectors.sync(connectorId);
             out.success(result.message, { message: result.message });
         }
         catch (err) {
             handleError(out, err, 'Failed to trigger sync');
+            const msg = err instanceof Error ? err.message : String(err);
+            if (/oauth|token|not authorized|unauthorized/i.test(msg)) {
+                out.status(chalk.dim('Hint: Ensure the connector has valid OAuth credentials. Run "lsvault connectors create" to set up.'));
+            }
         }
     });
     addGlobalFlags(connectors.command('logs')

package/dist/commands/custom-domains.js

@@ -106,8 +106,9 @@ export function registerCustomDomainCommands(program) {
         }
     });
     addGlobalFlags(domains.command('verify')
-        .description('Verify a custom domain via DNS')
-        .argument('<domainId>', 'Domain ID'))
+        .description('Trigger DNS verification check for a custom domain')
+        .argument('<domainId>', 'Domain ID')
+        .addHelpText('after', '\n  Submits a verification request to the server, which checks your DNS TXT record.\n  Use "check" to read the current verification status without triggering a new check.'))
         .action(async (domainId, _opts) => {
         const flags = resolveFlags(_opts);
         const out = createOutput(flags);
@@ -122,8 +123,9 @@ export function registerCustomDomainCommands(program) {
         }
     });
     addGlobalFlags(domains.command('check')
-        .description('Check DNS configuration for a custom domain')
-        .argument('<domainId>', 'Domain ID'))
+        .description('Show current DNS verification status for a custom domain')
+        .argument('<domainId>', 'Domain ID')
+        .addHelpText('after', '\n  Returns the current verification status without triggering a new check.\n  Use "verify" to submit a fresh DNS verification request to the server.'))
         .action(async (domainId, _opts) => {
         const flags = resolveFlags(_opts);
         const out = createOutput(flags);

package/dist/commands/docs.js

@@ -165,9 +165,11 @@ EXAMPLES
             else {
                 doc = await client.documents.put(vaultId, docPath, content);
             }
-            out.success(`Document saved: ${chalk.cyan(doc.path)} (${doc.sizeBytes ?? 0} bytes)`, {
-                path: doc.path,
-                sizeBytes: doc.sizeBytes ?? 0,
+            const docPath2 = doc.path ?? docPath;
+            const size = doc.sizeBytes ?? Buffer.byteLength(content, 'utf8');
+            out.success(`Document saved: ${chalk.cyan(docPath2)} (${size} bytes)`, {
+                path: docPath2,
+                sizeBytes: size,
                 encrypted: doc.encrypted ?? false,
             });
         }

package/dist/commands/links.js

@@ -22,16 +22,16 @@ export function registerLinkCommands(program) {
             out.list(linkList.map(link => ({
                 targetPath: link.targetPath,
                 linkText: link.linkText,
-                resolved: link.isResolved ? 'Yes' : 'No',
+                isResolved: link.isResolved,
             })), {
                 emptyMessage: 'No forward links found.',
                 columns: [
                     { key: 'targetPath', header: 'Target' },
                     { key: 'linkText', header: 'Link Text' },
-                    { key: 'resolved', header: 'Resolved' },
+                    { key: 'isResolved', header: 'Resolved' },
                 ],
                 textFn: (link) => {
-                    const resolved = link.resolved === 'Yes' ? chalk.green('✓') : chalk.red('✗');
+                    const resolved = link.isResolved ? chalk.green('✓') : chalk.red('✗');
                     return `  ${resolved} [[${String(link.linkText)}]] → ${String(link.targetPath)}`;
                 },
             });
@@ -55,18 +55,23 @@ export function registerLinkCommands(program) {
             const backlinks = await client.documents.getBacklinks(vaultId, docPath);
             out.stopSpinner();
             out.list(backlinks.map(bl => ({
-                source: bl.sourceDocument.title || bl.sourceDocument.path,
+                sourcePath: bl.sourceDocument.path,
+                sourceTitle: bl.sourceDocument.title || null,
                 linkText: bl.linkText,
                 context: bl.contextSnippet || '',
             })), {
                 emptyMessage: 'No backlinks found.',
                 columns: [
-                    { key: 'source', header: 'Source' },
+                    { key: 'sourcePath', header: 'Source Path' },
+                    { key: 'sourceTitle', header: 'Source Title' },
                     { key: 'linkText', header: 'Link Text' },
                     { key: 'context', header: 'Context' },
                 ],
                 textFn: (bl) => {
-                    const lines = [chalk.cyan(`  ${String(bl.source)}`)];
+                    const displayName = bl.sourceTitle ? String(bl.sourceTitle) : String(bl.sourcePath);
+                    const lines = [chalk.cyan(`  ${displayName}`)];
+                    if (bl.sourceTitle)
+                        lines.push(`  Path: ${String(bl.sourcePath)}`);
                     lines.push(`  Link: [[${String(bl.linkText)}]]`);
                     if (bl.context)
                         lines.push(`  Context: ...${String(bl.context)}...`);