Timeline

Timeline is Herald’s primary reading view. It shows chronological mail rows, thread grouping, search results, split or full-screen previews, quick replies, attachment saving, text selection, and actions that operate on the current message.

Overview

Press 1 to open Timeline. Use it when you want to scan mail, switch folders, search across cached content, read a message, reply or forward, save attachments, star important threads, unsubscribe, or copy message text.

Screen Anatomy

Area	What it shows
Folder sidebar	Folder tree, unread counts, total counts, expandable parents, and virtual `All Mail only` when available.
Timeline table	One row per visible thread or email. Columns are Sender, Subject, Date, Size KB, Att, and Tag.
Sender cell	Sender name plus unread indicator, star indicator, thread count, and child-row prefix for expanded threads.
Subject cell	Subject for the newest thread message or the individual email row.
Date and size	Message date and approximate message size in KB.
Att column	Attachment indicator when Herald detected attachments.
Tag column	AI classification/category when present.
Preview panel	Message header, body text, tags, unsubscribe/hide actions, attachments, inline image notes, loading/error state, and scroll position.
Full-screen preview	Same message content expanded across the terminal, with more room for body text and image descriptions.
Search input/results	Search prompt, search mode, result count, and focused result rows.
Quick reply picker	A small choice list of canned and optional AI-generated replies.

Controls

Key	Context	Preconditions	Result
`enter`	Timeline row	A row is selected.	Opens the email preview. If the row is a collapsed thread, expands the thread first.
`enter`	Search results	Search result focus is active.	Opens the selected result. If preview focus is active, returns focus to results.
`j` / `down`	Timeline list	Timeline list is focused.	Moves down and updates preview if one is open.
`k` / `up`	Timeline list	Timeline list is focused.	Moves up and updates preview if one is open.
`j` / `down`	Preview/full-screen	Preview or full-screen is focused.	Scrolls body down, or extends visual selection.
`k` / `up`	Preview/full-screen	Preview or full-screen is focused.	Scrolls body up, or shrinks visual selection.
`/`	Timeline	Not loading and search is closed.	Opens Timeline search.
`ctrl+i` / `tab`	Search input	Search query is non-empty.	Runs server IMAP search instead of local search.
`esc`	Search/preview states	Search, preview, full-screen, quick reply, visual mode, or chat filter is active.	Unwinds the active state in the safest order.
`*`	Timeline row	Not read-only.	Toggles star on the current row email.
`R`	Timeline row	Not loading and not read-only.	Opens Compose as a reply to the selected email.
`F`	Timeline row	Not read-only.	Opens Compose as a forward of the selected email.
`D`	Timeline or selected message	Not read-only.	Starts delete confirmation for the current or selected target.
`e`	Timeline or selected message	Not read-only.	Starts archive confirmation for the current or selected target.
`A`	Timeline row	AI configured.	Re-classifies the current email.
`ctrl+q`	Timeline row	A current email exists.	Opens or closes the quick reply picker.
`z`	Preview	A selected email is open.	Toggles full-screen reading.
`s`	Preview	Preview has attachments.	Opens attachment save prompt with a default Downloads path.
`[` / `]`	Preview	Message has more than one attachment.	Selects previous or next attachment.
`u`	Preview	Body has `List-Unsubscribe` data and tab is not read-only.	Opens unsubscribe confirmation.
`h` / `H`	Preview	A selected email is open and tab is not read-only.	Creates a hide-future-mail rule for the sender.
`v`	Preview/full-screen	Body wrapped lines are available.	Toggles visual text selection.
`y`	Preview/full-screen	Visual selection is active.	Copies selected lines and exits visual mode.
`y` then `y`	Preview/full-screen	Body wrapped lines are available.	Copies the current visible body line.
`Y`	Preview/full-screen	Body wrapped lines are available.	Copies the full wrapped body.
`m`	Timeline	Any Timeline state.	Toggles mouse-selection mode for terminal copy behavior.

Workflows

Read a Message

Press 1.
Use j/k to select a row.
Press enter.
Read in the split preview. Press z for full-screen.
Press esc to leave full-screen or close the preview.

Search Timeline

Press /.
Type a query. Herald debounces local search while you type.
Use prefixes when needed: /b for body search, /* for cross-folder search, or ? for semantic search.
Press enter to run or focus existing results.
Press ctrl+i or tab from the search input to run server IMAP search.
Press esc once to leave results or twice to clear search.

Reply or Forward

Select an email row.
Press R to reply or F to forward.
Herald switches to Compose and prefills To/Subject/body context.
Finish the draft and send with ctrl+s.

Use Quick Replies

Select or open an email.
Press ctrl+q.
Move with j/k or press number 1 through 8.
Press enter to open the selected reply in Compose.
Press esc to cancel.

Save an Attachment

Open an email with attachments.
Use [ and ] to choose the attachment when there are several.
Press s.
Edit the destination path if needed.
Press enter to save or esc to cancel.

States

State	What happens
Loading	Existing cached rows remain visible when possible; new IMAP work is reflected in the top sync strip and status bar.
Empty folder	Timeline shows an empty row area and key hints still expose refresh, sidebar, chat, and tabs when available.
Preview loading	Header/preview area opens while Herald fetches and MIME-parses body text and attachments.
Preview error	The preview reports a body fetch or parse failure without crashing the tab.
Read-only diagnostic	`All Mail only` disables destructive actions, server/body/cross/semantic search, and mailbox mutations.
AI unavailable	Tags may be absent; semantic search, AI replies, and re-classification show concise unavailable messages.
Attachment prompt	The save-path input captures keys until `enter` or `esc`.
Unsubscribe confirmation	Status asks for `y` confirm or `n`/`Esc` cancel before running the unsubscribe method.
Narrow terminal	Sidebar and chat may hide; preview and table widths shrink. Below the minimum size, the global size guard appears.

Data And Privacy

Timeline reads message metadata from SQLite and IMAP-backed cache. Opening a message fetches the full message body by UID, parses text/plain content, inline images, attachments, and unsubscribe headers, and can cache body text for later use. Marking read, starring, deleting, archiving, unsubscribing, hiding future mail, and attachment saving write to IMAP, SQLite, local files, or rules depending on the action.

AI actions such as semantic search, classification, image descriptions, and quick replies send selected query or message context to the configured AI backend. Ollama is local by default; external providers receive the context required for the requested action.

Troubleshooting

If search appears stuck, press esc to return from results to input, then press esc again to clear the search state.

If delete/archive/star does nothing, check whether you are in All Mail only read-only diagnostic mode.

If attachments do not save, verify the destination path is writable. The default path expands to ~/Downloads/<filename>.

If quick replies only show canned choices, the AI backend is unavailable or still generating; the canned replies remain usable.